From 04a415960170d28a1a18decc6971a7d153a51e0a Mon Sep 17 00:00:00 2001 From: Samrat Banerjee <106741933+SamratB8@users.noreply.github.com> Date: Sun, 12 Jul 2026 14:08:59 +0530 Subject: [PATCH 01/10] feat: scaffold initial WinDroid Runtime solution --- .gitignore | 11 +++++ Directory.Build.props | 14 ++++++ README.md | 55 +++++++++++++++++++++- WinDroid.Runtime.slnx | 8 ++++ src/WinDroid.Adb/WinDroid.Adb.csproj | 13 +++++ src/WinDroid.Core/WinDroid.Core.csproj | 9 ++++ src/WinDroid.Engine/WinDroid.Engine.csproj | 9 ++++ src/WinDroid.Studio/App.xaml | 13 +++++ src/WinDroid.Studio/App.xaml.cs | 22 +++++++++ src/WinDroid.Studio/MainWindow.xaml | 23 +++++++++ src/WinDroid.Studio/MainWindow.xaml.cs | 14 ++++++ src/WinDroid.Studio/WinDroid.Studio.csproj | 32 +++++++++++++ src/WinDroid.Studio/app.manifest | 17 +++++++ tests/README.md | 7 +++ 14 files changed, 246 insertions(+), 1 deletion(-) create mode 100644 Directory.Build.props create mode 100644 WinDroid.Runtime.slnx create mode 100644 src/WinDroid.Adb/WinDroid.Adb.csproj create mode 100644 src/WinDroid.Core/WinDroid.Core.csproj create mode 100644 src/WinDroid.Engine/WinDroid.Engine.csproj create mode 100644 src/WinDroid.Studio/App.xaml create mode 100644 src/WinDroid.Studio/App.xaml.cs create mode 100644 src/WinDroid.Studio/MainWindow.xaml create mode 100644 src/WinDroid.Studio/MainWindow.xaml.cs create mode 100644 src/WinDroid.Studio/WinDroid.Studio.csproj create mode 100644 src/WinDroid.Studio/app.manifest create mode 100644 tests/README.md diff --git a/.gitignore b/.gitignore index d5a18de..572ea28 100644 --- a/.gitignore +++ b/.gitignore @@ -427,3 +427,14 @@ FodyWeavers.xsd *.msix *.msm *.msp + +# MSIX packaging output (extensions not covered by the base template) +*.msixupload +*.msixbundle + +# Local environment and secret files (never commit) +.env.* +secrets.json + +# JetBrains Rider / IntelliJ IDE files +.idea/ diff --git a/Directory.Build.props b/Directory.Build.props new file mode 100644 index 0000000..c5ab8e0 --- /dev/null +++ b/Directory.Build.props @@ -0,0 +1,14 @@ + + + + + enable + enable + latestMajor + true + + + diff --git a/README.md b/README.md index 001b722..51e838d 100644 --- a/README.md +++ b/README.md @@ -113,7 +113,7 @@ Research areas: ### Phase 1 — Native Windows Control App -- [ ] Create WinUI 3 / .NET project structure +- [x] Create WinUI 3 / .NET project structure - [ ] Build initial dashboard UI - [ ] Add project settings page - [ ] Add logging system @@ -202,6 +202,59 @@ WinDroid-Runtime/ └── .gitignore ``` +## Current Solution Structure + +The initial multi-project solution has been scaffolded. This is foundational +structure only — it establishes the planned architecture and builds cleanly, but +no ADB functionality, Android runtime, or virtualization backend exists yet. + +```text +WinDroid-Runtime/ +├── src/ +│ ├── WinDroid.Studio/ # WinUI 3 desktop app (unpackaged), minimal window +│ ├── WinDroid.Core/ # Class library (empty foundation) +│ ├── WinDroid.Adb/ # Class library (empty foundation, references Core) +│ └── WinDroid.Engine/ # Class library (empty architectural boundary) +│ +├── tests/ # Reserved for future test projects +├── Directory.Build.props # Shared build settings +├── WinDroid.Runtime.slnx # Solution (XML format) +├── README.md +├── LICENSE +└── .gitignore +``` + +Project dependencies: + +```text +WinDroid.Studio -> WinDroid.Core, WinDroid.Adb +WinDroid.Adb -> WinDroid.Core +WinDroid.Core -> (no project references) +WinDroid.Engine -> (isolated) +``` + +### Building + +Prerequisites (verified with the toolchain used to scaffold this solution): + +- Windows 11 +- .NET SDK 10.0.x (the class libraries target `net8.0`; the app targets + `net8.0-windows10.0.19041.0`) +- Windows App SDK 2.2.0 (restored automatically via NuGet) +- Visual Studio 2026 (or 2022) with the **Windows App SDK C#** / + **.NET Desktop Development** workload and a Windows 10/11 SDK. This workload + may be required to open, build, and run `WinDroid.Studio` (WinUI 3). + +Build from the repository root: + +```powershell +dotnet restore .\WinDroid.Runtime.slnx +dotnet build .\WinDroid.Runtime.slnx --configuration Debug --no-restore +dotnet build .\WinDroid.Runtime.slnx --configuration Release --no-restore +``` + +The solution can also be opened and built directly in Visual Studio. + ## Technology Stack The planned first-stage stack: diff --git a/WinDroid.Runtime.slnx b/WinDroid.Runtime.slnx new file mode 100644 index 0000000..8c93341 --- /dev/null +++ b/WinDroid.Runtime.slnx @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/src/WinDroid.Adb/WinDroid.Adb.csproj b/src/WinDroid.Adb/WinDroid.Adb.csproj new file mode 100644 index 0000000..6713294 --- /dev/null +++ b/src/WinDroid.Adb/WinDroid.Adb.csproj @@ -0,0 +1,13 @@ + + + + net8.0 + WinDroid.Adb + WinDroid.Adb + + + + + + + diff --git a/src/WinDroid.Core/WinDroid.Core.csproj b/src/WinDroid.Core/WinDroid.Core.csproj new file mode 100644 index 0000000..214aabb --- /dev/null +++ b/src/WinDroid.Core/WinDroid.Core.csproj @@ -0,0 +1,9 @@ + + + + net8.0 + WinDroid.Core + WinDroid.Core + + + diff --git a/src/WinDroid.Engine/WinDroid.Engine.csproj b/src/WinDroid.Engine/WinDroid.Engine.csproj new file mode 100644 index 0000000..b95dd23 --- /dev/null +++ b/src/WinDroid.Engine/WinDroid.Engine.csproj @@ -0,0 +1,9 @@ + + + + net8.0 + WinDroid.Engine + WinDroid.Engine + + + diff --git a/src/WinDroid.Studio/App.xaml b/src/WinDroid.Studio/App.xaml new file mode 100644 index 0000000..e81f2aa --- /dev/null +++ b/src/WinDroid.Studio/App.xaml @@ -0,0 +1,13 @@ + + + + + + + + + + diff --git a/src/WinDroid.Studio/App.xaml.cs b/src/WinDroid.Studio/App.xaml.cs new file mode 100644 index 0000000..504f2ec --- /dev/null +++ b/src/WinDroid.Studio/App.xaml.cs @@ -0,0 +1,22 @@ +using Microsoft.UI.Xaml; + +namespace WinDroid.Studio; + +/// +/// Application entry point for WinDroid Studio. +/// +public partial class App : Application +{ + private Window? _window; + + public App() + { + InitializeComponent(); + } + + protected override void OnLaunched(LaunchActivatedEventArgs args) + { + _window = new MainWindow(); + _window.Activate(); + } +} diff --git a/src/WinDroid.Studio/MainWindow.xaml b/src/WinDroid.Studio/MainWindow.xaml new file mode 100644 index 0000000..cd43e94 --- /dev/null +++ b/src/WinDroid.Studio/MainWindow.xaml @@ -0,0 +1,23 @@ + + + + + + + + + diff --git a/src/WinDroid.Studio/MainWindow.xaml.cs b/src/WinDroid.Studio/MainWindow.xaml.cs new file mode 100644 index 0000000..1f2911a --- /dev/null +++ b/src/WinDroid.Studio/MainWindow.xaml.cs @@ -0,0 +1,14 @@ +using Microsoft.UI.Xaml; + +namespace WinDroid.Studio; + +/// +/// Minimal initial window shown while the project is in its scaffolding stage. +/// +public sealed partial class MainWindow : Window +{ + public MainWindow() + { + InitializeComponent(); + } +} diff --git a/src/WinDroid.Studio/WinDroid.Studio.csproj b/src/WinDroid.Studio/WinDroid.Studio.csproj new file mode 100644 index 0000000..206cacb --- /dev/null +++ b/src/WinDroid.Studio/WinDroid.Studio.csproj @@ -0,0 +1,32 @@ + + + + WinExe + net8.0-windows10.0.19041.0 + 10.0.17763.0 + WinDroid.Studio + WinDroid.Studio + app.manifest + x86;x64;ARM64 + win-x86;win-x64;win-arm64 + true + + None + + + + + + + + + + + + + diff --git a/src/WinDroid.Studio/app.manifest b/src/WinDroid.Studio/app.manifest new file mode 100644 index 0000000..56d81a4 --- /dev/null +++ b/src/WinDroid.Studio/app.manifest @@ -0,0 +1,17 @@ + + + + + + + PerMonitorV2 + + + + + + + + + + diff --git a/tests/README.md b/tests/README.md new file mode 100644 index 0000000..85c01aa --- /dev/null +++ b/tests/README.md @@ -0,0 +1,7 @@ +# Tests + +This directory is reserved for future test projects. + +No test projects exist yet. This foundational scaffolding issue contains +almost no business logic, so meaningful automated tests are deferred until +real functionality (for example, the ADB service layer) is implemented. From 04f679dbbf4bec73c04334fb071a43809c8bb793 Mon Sep 17 00:00:00 2001 From: Samrat Banerjee <106741933+SamratB8@users.noreply.github.com> Date: Sun, 12 Jul 2026 17:07:09 +0530 Subject: [PATCH 02/10] feat(core): add basic ADB settings model --- .../Configuration/AdbSettings.cs | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 src/WinDroid.Core/Configuration/AdbSettings.cs diff --git a/src/WinDroid.Core/Configuration/AdbSettings.cs b/src/WinDroid.Core/Configuration/AdbSettings.cs new file mode 100644 index 0000000..5f7246e --- /dev/null +++ b/src/WinDroid.Core/Configuration/AdbSettings.cs @@ -0,0 +1,20 @@ +namespace WinDroid.Core.Configuration; + +/// +/// Represents user-configurable settings used by future ADB services. +/// +public sealed class AdbSettings +{ + /// + /// Optional user-specified path to the ADB executable. When not set, a + /// future service is expected to fall back to its own default resolution. + /// The value is stored as provided and is not validated or normalized here. + /// + public string? CustomAdbPath { get; set; } + + /// + /// Indicates whether a future service should prefer an ADB executable + /// distributed with WinDroid. Defaults to . + /// + public bool UseBundledAdb { get; set; } +} From 2dc4c2bd945a43b47c96f7cbee6a316bbc6aaebb Mon Sep 17 00:00:00 2001 From: Samrat Banerjee <106741933+SamratB8@users.noreply.github.com> Date: Sun, 12 Jul 2026 19:55:33 +0530 Subject: [PATCH 03/10] Add security and legal policy documentation Add comprehensive SECURITY.md and legal-notes.md documents to establish clear policies for vulnerability reporting, security scope, licensing boundaries, trademark usage, and contribution requirements. Update README.md to reference the new legal-notes.md document and mark the corresponding tasks as complete. --- README.md | 8 +- SECURITY.md | 631 ++++++++++++++++++++++++ docs/legal-notes.md | 1109 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 1745 insertions(+), 3 deletions(-) create mode 100644 SECURITY.md create mode 100644 docs/legal-notes.md diff --git a/README.md b/README.md index cbeaa2a..65effa3 100644 --- a/README.md +++ b/README.md @@ -108,8 +108,8 @@ Research areas: - [x] Add license - [x] Create initial README - [ ] Write architecture notes -- [ ] Create contribution guidelines -- [ ] Document legal/trademark boundaries +- [x] Create contribution guidelines +- [x] Document legal/trademark boundaries ### Phase 1 — Native Windows Control App @@ -305,7 +305,9 @@ WinDroid Runtime is not affiliated with, endorsed by, sponsored by, or connected Windows, Android, Google Play, Amazon Appstore, Microsoft, Google, Amazon, and related names, logos, and trademarks are the property of their respective owners. -This project does not use Microsoft WSA binaries, Microsoft branding, Google Play binaries, or proprietary app store components. +This project does not use Microsoft WSA binaries, Microsoft branding, Google Play binaries, or proprietary application-store components. + +For the complete project policy, see [Legal, Licensing, and Trademark Boundaries](docs/legal-notes.md). ## App Store and Google Play Notice diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..407324d --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,631 @@ +# Security Policy + +WinDroid Runtime is an early-stage open-source project involving Windows desktop software, Android Debug Bridge integration, APK management, process execution, and future runtime and virtualization research. + +Security reports are taken seriously. + +This document explains how to report suspected vulnerabilities, which project areas are currently in scope, and how security-related disclosures will be handled. + +> [!IMPORTANT] +> WinDroid Runtime is currently under active development and is not production-ready. +> +> Do not use current development builds in sensitive, privileged, or production environments unless you fully understand the risks. + +--- + +## Supported Versions + +WinDroid Runtime has not yet published a stable production release. + +Security support currently applies to: + +| Version or branch | Security support | +|---|---| +| Latest `main` branch | Supported | +| Latest `dev` branch | Best effort | +| Active development branches | Best effort | +| Older commits | Not normally supported | +| Unofficial builds or forks | Not supported by this project | +| Third-party repackaged releases | Not supported | + +Once public releases begin, this table will be updated to identify which release versions continue to receive security fixes. + +--- + +## Reporting a Vulnerability + +Do not report security vulnerabilities through: + +- public GitHub issues +- public GitHub Discussions +- pull-request comments +- social media +- public chat servers +- screenshots containing secrets +- public proof-of-concept repositories + +Use a private maintainer communication channel. + +Preferred reporting method: + +```text +Security contact: novasystemslab@gmail.com +Subject: [SECURITY] WinDroid Runtime vulnerability report +``` + +When GitHub private vulnerability reporting is available and enabled for this repository, it may also be used. + +If the report contains credentials, private keys, personal information, sensitive logs, or exploit material, do not include more information than is necessary to identify the issue. + +--- + +## Information to Include + +A useful security report should contain: + +- a clear title +- the affected component +- the affected branch, commit, or version +- the operating-system version +- reproduction steps +- expected behaviour +- observed behaviour +- potential security impact +- required privileges +- whether user interaction is required +- whether the issue is remotely exploitable +- relevant logs with sensitive data removed +- proof-of-concept details where safe +- suggested mitigations, if known + +Where relevant, identify the affected project area: + +- WinDroid Studio +- WinDroid Core +- WinDroid ADB +- WinDroid Engine +- installer or packaging +- update mechanism +- configuration storage +- logging +- dependency +- documentation +- build or release infrastructure + +Do not include: + +- real user credentials +- live access tokens +- private signing keys +- personal documents +- third-party confidential data +- destructive payloads +- malware +- unnecessary personal information + +--- + +## Security Scope + +The following areas are considered security-sensitive. + +### ADB Command Execution + +Reports are in scope when they involve: + +- command injection +- unsafe argument construction +- shell interpolation +- execution of unintended commands +- unsafe custom ADB paths +- execution of an untrusted ADB binary +- privilege-boundary confusion +- insecure process creation +- uncontrolled environment-variable use +- sensitive command output exposure +- improper handling of connected devices + +ADB commands must be executed through controlled process boundaries and structured arguments rather than unsafe shell-concatenated command strings. + +--- + +### APK Handling + +Reports are in scope when they involve: + +- arbitrary code execution caused by APK parsing +- unsafe file-path handling +- directory traversal +- unsafe temporary-file creation +- automatic execution of untrusted files +- insecure APK metadata extraction +- signature or identity misrepresentation +- installing an APK on the wrong target +- bypassing required user confirmation +- leakage of APK contents or metadata +- malicious filename handling +- unsafe archive extraction + +WinDroid Runtime must treat APK files as untrusted input. + +Selecting an APK must not imply that it is safe, authentic, licensed, or malware-free. + +--- + +### File-System Access + +Reports are in scope when they involve: + +- arbitrary file overwrite +- arbitrary file deletion +- path traversal +- insecure temporary directories +- unsafe symbolic-link handling +- writing outside approved directories +- exposing sensitive user files +- insecure permission handling +- unsafe import or export behaviour + +Future file push, pull, backup, import, export, and shared-folder features must use explicit destination validation and user confirmation. + +--- + +### Configuration and Secrets + +Reports are in scope when they involve: + +- credentials stored in plaintext +- access tokens committed to the repository +- secrets included in logs +- insecure configuration permissions +- unsafe custom binary paths +- sensitive environment-variable exposure +- insecure recovery information +- accidental upload of local configuration +- secret leakage through diagnostics or crash reports + +The project should not require or store unnecessary credentials. + +No secrets should be committed to source control. + +--- + +### Logging and Diagnostics + +Reports are in scope when logs or diagnostic reports expose: + +- usernames +- home-directory paths +- device identifiers +- serial numbers +- IP addresses +- application lists +- package names where sensitive +- command history +- access tokens +- credentials +- private file paths +- personal information +- ADB output containing sensitive device data + +Logs must be treated as potentially sensitive. + +Diagnostic exports should minimize data and clearly tell users what will be included. + +--- + +### Device and Runtime Isolation + +Future runtime and virtualization issues are in scope when they involve: + +- guest-to-host escape +- host-to-guest boundary failure +- unauthorized host-file access +- unsafe shared folders +- clipboard leakage +- cross-application data exposure +- network isolation failure +- privilege escalation +- insecure inter-process communication +- unauthorized device access +- sandbox bypass +- runtime image tampering +- unverified boot components + +Claims of isolation or sandboxing must not be made until they are implemented and tested. + +--- + +### Windows Integration + +Reports are in scope when they involve: + +- privilege escalation +- unsafe elevation prompts +- insecure service installation +- insecure registry modification +- unsafe scheduled tasks +- startup persistence without consent +- insecure URI handlers +- unsafe file associations +- unquoted executable paths +- DLL search-order issues +- insecure update mechanisms +- misuse of Windows application capabilities + +WinDroid Runtime should use the least privilege necessary. + +Administrative privileges must not be requested unless a feature genuinely requires them. + +--- + +### Dependencies and Supply Chain + +Reports are in scope when they involve: + +- vulnerable dependencies +- dependency confusion +- malicious packages +- compromised build tools +- unpinned or unverified release dependencies +- unsafe download behaviour +- missing integrity verification +- compromised GitHub Actions +- exposed workflow secrets +- insecure release artifacts +- tampered third-party binaries +- untrusted ADB distributions +- unexpected telemetry in dependencies + +Dependencies should be obtained from trusted sources and reviewed for licence, maintenance, and security status. + +--- + +### Update and Release Security + +Future update mechanisms must protect against: + +- unsigned updates +- update-channel hijacking +- downgrade attacks +- insecure transport +- tampered packages +- execution before integrity verification +- release-signing key exposure +- misleading publisher information + +Until a secure update system exists, the project must not claim to provide automatic secure updates. + +--- + +## Out-of-Scope Reports + +The following are normally outside the project’s security scope: + +- vulnerabilities in Microsoft Windows itself +- vulnerabilities in Android itself +- vulnerabilities in AOSP not introduced by WinDroid Runtime +- vulnerabilities in Google Play Services +- vulnerabilities in Amazon Appstore +- vulnerabilities in third-party APKs +- vulnerabilities in user-supplied Android images +- vulnerabilities in unofficial forks +- vulnerabilities in modified or repackaged builds +- unsupported operating systems +- unsupported hardware configurations +- social-engineering attacks unrelated to the project +- denial-of-service reports requiring unrealistic local resource exhaustion +- theoretical issues without a credible impact or reproduction path +- missing security headers on sites that do not process sensitive data +- reports based only on automated scanner output without validation + +A third-party vulnerability may still be relevant if WinDroid Runtime introduces, worsens, or fails to mitigate the risk in a way users would not reasonably expect. + +--- + +## Unsafe or Prohibited Testing + +Do not perform security testing that: + +- accesses another person’s system without permission +- damages data +- disrupts services +- distributes malware +- steals credentials +- bypasses payment or licence systems +- attacks unrelated third parties +- uploads confidential information +- creates persistence without consent +- targets production systems not owned by you +- violates applicable law +- violates a third party’s terms or authorization boundaries + +Testing should be performed only on systems, devices, images, applications, and accounts that you own or are explicitly authorized to test. + +--- + +## Responsible Disclosure + +Reporters are asked to allow maintainers a reasonable opportunity to: + +- confirm the issue +- understand the impact +- develop a fix +- test the fix +- review affected releases +- notify users where appropriate +- coordinate disclosure + +Do not publish technical details that would place users at immediate risk before a fix or mitigation is available. + +The project will attempt to coordinate disclosure timing with the reporter. + +No guarantee of a particular disclosure date can be made for complex, disputed, third-party, or architectural issues. + +--- + +## Expected Response Process + +After receiving a report, maintainers will aim to: + +1. acknowledge receipt +2. review the report for completeness +3. reproduce or validate the issue +4. determine severity and affected components +5. identify temporary mitigations +6. prepare and review a fix +7. test for regressions +8. publish an advisory or release where appropriate +9. credit the reporter when requested and appropriate + +Target response times are goals rather than guarantees: + +| Stage | Target | +|---|---| +| Initial acknowledgement | Within 5 business days | +| Initial assessment | Within 10 business days | +| Status update for confirmed issues | At least every 14 days | +| Fix timeline | Depends on severity and complexity | + +Response time may be longer during the project’s early development phase. + +--- + +## Severity Considerations + +Severity will be evaluated based on factors such as: + +- confidentiality impact +- integrity impact +- availability impact +- required privileges +- required user interaction +- attack complexity +- exploit reliability +- affected users +- default configuration +- whether the issue crosses a security boundary +- whether the issue exposes the Windows host +- whether the issue exposes Android guest data +- whether the issue can affect connected physical devices + +Examples of potentially high-severity issues include: + +- arbitrary code execution on the Windows host +- guest-to-host escape +- unauthorized administrative execution +- silent installation of an unintended APK +- execution of an attacker-controlled binary +- arbitrary host-file overwrite +- exposure of credentials or signing keys +- insecure automatic updates +- command injection through user-controlled input + +--- + +## Security Fixes + +Security fixes should normally: + +- be developed privately when early disclosure creates meaningful risk +- include regression tests where practical +- avoid introducing unrelated changes +- document affected versions +- include mitigation guidance +- be reviewed before release +- avoid publishing exploit details before users can update + +Once a fix is available, maintainers may: + +- publish a security advisory +- release a patched version +- update affected branches +- revoke compromised credentials +- rotate signing or access keys +- remove unsafe releases +- update documentation +- notify downstream users or maintainers + +--- + +## Security in Pull Requests + +Contributors must not knowingly introduce: + +- unsafe shell command construction +- hard-coded secrets +- insecure temporary files +- silent telemetry +- unnecessary elevation +- unvalidated external paths +- automatic execution of downloaded files +- unverified binary downloads +- insecure deserialization +- broad file-system permissions +- security-sensitive behaviour without user confirmation + +Security-sensitive pull requests should explain: + +- the trust boundary +- attacker-controlled inputs +- required privileges +- validation performed +- failure behaviour +- logging behaviour +- tests added +- security trade-offs + +Large security-sensitive changes may require an architecture decision record before implementation. + +--- + +## Secret Handling + +Never commit: + +- passwords +- access tokens +- API keys +- private keys +- signing certificates +- recovery codes +- personal credentials +- production connection strings +- webhook secrets +- cloud credentials +- private package tokens + +If a secret is accidentally committed: + +1. treat it as compromised +2. revoke or rotate it immediately +3. notify the maintainers privately +4. remove it from current source +5. review repository history and logs +6. assess whether additional cleanup is required + +Deleting the visible line from a later commit does not make an exposed secret safe. + +--- + +## Security of AI-Assisted Contributions + +AI-assisted code must receive the same security review as manually written code. + +Contributors remain responsible for: + +- validating generated code +- testing failure cases +- checking for command injection +- checking for insecure file handling +- checking for invented APIs +- checking for hard-coded secrets +- checking dependency suggestions +- verifying licensing and provenance +- removing confidential prompt content +- ensuring meaningful human review + +AI-generated code must not be merged solely because it compiles. + +--- + +## Privacy + +Security reports may contain sensitive information. + +Maintainers should: + +- limit access to reports +- avoid forwarding sensitive data unnecessarily +- redact secrets from public advisories +- avoid storing personal information longer than necessary +- not disclose reporter identity without permission +- use secure communication where practical + +Reporters should remove unnecessary personal data before submitting logs or screenshots. + +--- + +## Researcher Credit + +The project may publicly credit reporters who: + +- submit a valid security issue +- follow responsible-disclosure practices +- do not place users at unnecessary risk +- provide permission to be credited + +Credit may include: + +- name +- handle +- organization +- advisory acknowledgement + +Anonymous reporting and anonymous credit requests will be respected where practical. + +--- + +## Safe-Harbour Intent + +The project supports good-faith security research conducted within the boundaries of this policy. + +Good-faith research means activity intended to: + +- identify and report vulnerabilities +- avoid harm +- respect privacy +- minimize data access +- avoid persistence +- avoid service disruption +- give maintainers reasonable time to respond +- comply with applicable law and authorization + +This statement expresses project policy and intent. It is not legal advice and cannot authorize testing against systems, software, accounts, or services owned by third parties. + +--- + +## Third-Party Vulnerabilities + +When a report affects a third-party dependency or platform, maintainers may: + +- confirm whether WinDroid Runtime is affected +- notify the upstream project +- apply a temporary mitigation +- update or remove the dependency +- delay public disclosure to coordinate with upstream +- document that no project-specific fix is available + +Reporters should avoid publicly disclosing an unpatched upstream vulnerability through the WinDroid Runtime repository. + +--- + +## Security Contact Changes + +The security contact may change as Nova Systems Lab develops. + +The current contact listed in this file should always be treated as authoritative for this repository. + +Changes to the security-reporting process must be reviewed through a pull request. + +--- + +## Related Documents + +This security policy should be read together with: + +- [`README.md`](README.md) +- [`LICENSE`](LICENSE) +- [`CONTRIBUTING.md`](CONTRIBUTING.md) +- [`docs/legal-notes.md`](docs/legal-notes.md) +- `NOTICE`, when added +- project architecture documentation +- dependency and release documentation + +--- + +## Final Principle + +When security behaviour is uncertain, prefer the safer design. + +Do not silently execute, elevate, download, install, expose, transmit, or modify anything that a user would reasonably expect to control. \ No newline at end of file diff --git a/docs/legal-notes.md b/docs/legal-notes.md new file mode 100644 index 0000000..c6a1fd8 --- /dev/null +++ b/docs/legal-notes.md @@ -0,0 +1,1109 @@ +# Legal, Licensing, and Trademark Boundaries + +This document defines the legal, licensing, branding, contribution, and distribution boundaries for the WinDroid Runtime project. + +It applies to maintainers, contributors, documentation authors, release managers, designers, testers, and anyone representing the project publicly. + +> [!IMPORTANT] +> This document is an internal project policy and risk-management guide. It is not legal advice and does not replace review by a qualified lawyer. +> +> Maintainers should seek qualified legal advice before commercial distribution, bundling third-party system images, incorporating proprietary software, entering licensing agreements, making compatibility-certification claims, or distributing components whose legal status is unclear. + +--- + +## 1. Project Independence + +WinDroid Runtime is an independent open-source project. + +It is not: + +- affiliated with Microsoft +- endorsed, sponsored, or approved by Microsoft +- affiliated with Google +- endorsed, sponsored, or approved by Google +- affiliated with Amazon +- endorsed, sponsored, or approved by Amazon +- an official or unofficial continuation of Windows Subsystem for Android +- a fork of Windows Subsystem for Android +- a redistribution of Windows Subsystem for Android +- an official Android product +- an Android-certified product +- an official Android Open Source Project +- an official Nova Systems Lab legal entity product unless and until such an entity is formally established + +The project may refer to third-party products when reasonably necessary to describe: + +- compatibility +- interoperability +- supported development workflows +- historical context +- technical research +- build requirements +- operating-system requirements + +Such references must be truthful, limited to what is necessary, and must not imply partnership, endorsement, certification, ownership, sponsorship, or official status. + +--- + +## 2. Independent Implementation Requirement + +WinDroid Runtime must be developed as an original and independently implemented project. + +Contributors must not submit, upload, reproduce, or incorporate: + +- Microsoft WSA binaries +- files extracted from a WSA installation +- decompiled or reconstructed WSA source code +- proprietary Windows components +- confidential Microsoft documentation +- leaked Microsoft source code +- internal SDKs obtained without authorization +- copied implementations from closed-source Android emulators +- proprietary Android runtime components +- proprietary device firmware without redistribution permission +- code copied from commercial products +- confidential employer or client material +- code obtained in breach of a contract, licence, access restriction, or terms of service +- code generated from unlawfully obtained source material +- assets or implementations whose origin cannot be reasonably explained + +Technical behaviour may be studied through: + +- publicly documented APIs +- publicly available standards +- official development documentation +- legitimate testing and observation +- properly licensed open-source projects +- independently written experiments +- black-box interoperability testing where lawful +- independently designed compatibility research +- clean-room methods where appropriate and lawful + +A contributor must be able to explain the lawful and properly licensed origin of any substantial code, binary, image, document, dataset, model, or asset submitted to the project. + +Maintainers may reject any contribution where origin, authorship, permission, or licensing cannot be established with reasonable confidence. + +--- + +## 3. Microsoft and Windows Boundaries + +The following are Microsoft product names, trademarks, service marks, or other brand identifiers and should be used only in accordance with Microsoft’s published guidelines: + +- Microsoft +- Windows +- Windows 10 +- Windows 11 +- Windows Subsystem for Android +- WSA +- Hyper-V +- Windows Hypervisor Platform +- WinUI +- Windows App SDK +- Visual Studio +- .NET +- Microsoft Store + +These names may be used in accurate factual statements such as: + +- “Designed for Windows 11” +- “Built with WinUI 3” +- “Built using the Windows App SDK” +- “Researching Windows Hypervisor Platform support” +- “Compatible with supported Windows environments” +- “Not affiliated with Microsoft” +- “Inspired by the gap left after the discontinuation of Windows Subsystem for Android” + +Any factual reference should: + +- be accurate +- be no more prominent than the WinDroid Runtime name +- be limited to what is necessary +- clearly describe the actual relationship +- avoid suggesting certification unless certification has actually been obtained +- avoid implying that Microsoft produced, maintains, or supports the project + +Microsoft names and identifiers must not be used in ways that suggest: + +- Microsoft created the project +- Microsoft sponsors or recommends the project +- WinDroid Runtime is an official successor to WSA +- WinDroid Runtime is part of Windows +- the project contains Microsoft technology that it does not contain +- the project is certified by Microsoft +- the project is an official Microsoft application +- the project has access to Microsoft source code or internal systems + +The project must not use, without documented permission: + +- Microsoft logos +- Windows logos +- WSA application icons +- Microsoft product icons +- Microsoft badges +- Microsoft-owned illustrations +- Microsoft product artwork +- copied Microsoft interface assets +- Microsoft branding as part of the WinDroid logo +- Microsoft logos as application icons +- packaging that imitates an official Microsoft product +- screenshots designed to imply that WinDroid is a Microsoft product + +Screenshots containing Microsoft products or interfaces may be used only where lawful and reasonably necessary for: + +- documentation +- compatibility explanation +- troubleshooting +- technical comparison +- development instructions + +Such screenshots must not imply ownership, endorsement, certification, or official affiliation and should avoid unnecessary display of Microsoft logos, artwork, icons, or proprietary visual assets. + +--- + +## 4. Windows API and Platform Usage + +WinDroid Runtime may use officially documented Windows APIs, frameworks, development tools, and platform services subject to their applicable licences and terms. + +Use of a Microsoft API, framework, SDK, package, or development tool does not by itself mean that Microsoft: + +- endorses the project +- certifies the project +- sponsors the project +- accepts responsibility for the project +- grants permission to use Microsoft branding + +Any Microsoft package, SDK, runtime, redistributable, or binary included in a release must be reviewed for: + +- redistribution permission +- licence requirements +- version restrictions +- attribution requirements +- packaging requirements +- end-user licence terms +- platform restrictions + +--- + +## 5. Android, AOSP, and Google Boundaries + +Android Open Source Project components and proprietary Google software must be treated as separate categories. + +The availability of AOSP source code does not grant permission to distribute proprietary Google applications, services, branding, certification materials, or device-specific packages. + +WinDroid Runtime must not bundle, redistribute, represent as included, or automatically obtain without appropriate permission: + +- Google Play Store +- Google Play Services +- Google Mobile Services +- Google Services Framework +- proprietary Google applications +- Google account integration components +- Google certification files +- device-specific Google application packages +- proprietary Google APIs or libraries without an appropriate licence +- Google-controlled security keys or credentials +- device certification identifiers +- proprietary vendor packages obtained from devices without redistribution permission + +The project may support or research: + +- user-supplied APK installation +- ADB-based package management +- open-source Android applications +- open-source application repositories +- independently obtained Android images +- lawfully distributable Android images +- AOSP-based development and research +- Generic System Image research where licensing permits +- compatibility with applications that do not require proprietary Google services +- optional user-directed integrations that do not redistribute restricted components + +Any future Google Play or Google Mobile Services integration must require: + +- documented authorization +- applicable licensing +- required certification +- compatibility review +- security review +- legal review +- written maintainer approval + +The following terms may be used factually where relevant: + +- Android +- Android Debug Bridge +- ADB +- Android Open Source Project +- AOSP +- Google Play +- Google Mobile Services + +They must not be used to imply that WinDroid Runtime is: + +- an official Android product +- certified by Google +- endorsed by Google +- supplied with Google Play +- guaranteed to support every Android application +- compliant with Android compatibility requirements unless formally verified +- licensed to redistribute proprietary Google software + +Use of the Android name, robot, wordmark, Google Play badge, or related branding must follow Google’s current published brand guidelines. + +Factual compatibility statements do not authorize use of Google-controlled logos, badges, wordmarks, certification marks, or marketing artwork. + +--- + +## 6. AOSP Component Licensing + +AOSP is not governed by one single licence across every component. + +Before incorporating AOSP code, maintainers must review the licence of each component individually. + +AOSP-related components may include code under: + +- Apache License 2.0 +- GNU General Public License +- GNU Lesser General Public License +- BSD licences +- MIT-style licences +- other open-source licences +- component-specific notices or exceptions + +The project must preserve all obligations that apply to incorporated components, including where relevant: + +- source-code availability +- licence-text distribution +- modification notices +- attribution notices +- copyright notices +- NOTICE files +- reciprocal licensing requirements +- installation information +- written offers +- build instructions + +Code must not be described simply as “AOSP licensed” without identifying the actual licence governing the relevant component. + +--- + +## 7. Linux Kernel and Copyleft Components + +Any Linux kernel, kernel module, driver, or GPL-licensed component considered for use must be reviewed separately from Apache-licensed project code. + +The project must not assume that the Apache License 2.0 automatically governs incorporated GPL, LGPL, or other copyleft components. + +Before distribution, maintainers must determine: + +- whether the component is modified or unmodified +- whether the component is linked, combined, or distributed separately +- whether source code must be made available +- whether corresponding source obligations apply +- whether scripts or build instructions must be supplied +- whether licence notices must accompany binaries +- whether the intended combination is licence-compatible + +Copyleft obligations must not be avoided through misleading packaging or documentation. + +Where legal or licensing compatibility is uncertain, the component must not be included in a public release until reviewed. + +--- + +## 8. Amazon Boundaries + +WinDroid Runtime is not affiliated with Amazon and is not a continuation of Amazon Appstore integration previously associated with WSA. + +The project must not: + +- bundle Amazon Appstore components without permission +- use Amazon branding as part of its identity +- imply that Amazon supports the project +- redistribute proprietary Amazon applications +- use Amazon logos without permission +- claim official Amazon Appstore compatibility without verification +- use Amazon credentials, APIs, or services outside their applicable terms + +Factual references to Amazon or Amazon Appstore may be made when discussing: + +- compatibility +- technical history +- previous Android-on-Windows systems +- application availability +- documented integration behaviour + +--- + +## 9. WinDroid Branding + +WinDroid Runtime branding must remain visually and verbally distinct from Microsoft, Google, Android, Amazon, emulator vendors, and other existing products. + +Current internal project names include: + +- WinDroid Runtime +- WinDroid Studio +- WinDroid Core +- WinDroid ADB +- WinDroid Engine + +Project branding should: + +- use original logos and artwork +- avoid copying Windows or Android visual identities +- avoid official-looking Microsoft or Google product presentation +- clearly state the project’s independent status +- remain consistent across repositories, applications, documentation, websites, and releases +- remain subordinate to any future approved Nova Systems Lab branding policy + +Before adopting new names, logos, domains, package identifiers, publisher names, or public-facing product identities, maintainers should perform a reasonable naming and trademark-conflict review. + +No contributor may independently register project-related: + +- trademarks +- domains +- social-media accounts +- package names +- application-store listings +- organization accounts +- donation accounts +- publisher identities + +on behalf of WinDroid Runtime or Nova Systems Lab without explicit maintainer approval. + +Registration of a name, domain, account, or package identifier does not automatically transfer ownership to the project. + +--- + +## 10. Nova Systems Lab Status + +Nova Systems Lab currently functions as the GitHub organization and public project umbrella under which WinDroid Runtime is developed. + +Unless separately registered as a legal entity, Nova Systems Lab must not be represented as: + +- a registered company +- an incorporated nonprofit +- a legal foundation +- a formal employer +- a party capable of independently owning rights merely by being a GitHub organization + +Copyright remains with the individual or legal entity that created the relevant contribution unless rights are formally assigned. + +Project notices may use wording such as: + +```text +Copyright 2026 Samrat Banerjee and Nova Systems Lab contributors +``` + +This wording does not by itself transfer contributor copyright to Nova Systems Lab. + +Any future transfer of copyright, trademarks, domains, or other assets to a registered legal entity must be documented separately. + +--- + +## 11. Repository Licence + +Unless otherwise stated, original code and documentation in this repository are licensed under the Apache License 2.0. + +Contributions intentionally submitted for inclusion in the repository are expected to be provided under the Apache License 2.0 unless: + +- the contributor clearly states otherwise before submission +- the contribution is rejected +- a separate written agreement has been approved by the maintainers + +The Apache License 2.0 grants specified copyright and patent permissions under its terms. + +It does not grant general permission to use a licensor’s: + +- trade names +- trademarks +- service marks +- product names + +except for reasonable and customary descriptive use and required notice reproduction. + +Every contributor must ensure that they have the right to submit their contribution. + +Contributors must not remove or improperly alter: + +- copyright notices +- licence notices +- attribution notices +- patent notices +- required `NOTICE` content +- third-party licence files +- source-identification information +- modification notices required by an upstream licence + +Where required by an incorporated dependency or source file, modifications must be identified appropriately. + +--- + +## 12. Copyright Ownership + +The repository licence governs permission to use contributions but does not automatically transfer ownership of copyright. + +Unless a separate written assignment exists: + +- each contributor retains copyright in their original contribution +- each contribution is licensed under the repository licence +- maintainers retain copyright in their original work +- Nova Systems Lab does not automatically own contributor copyright +- accepting a pull request does not by itself transfer ownership + +The project should not claim exclusive ownership over work created by independent contributors unless there is a valid written assignment. + +Copyright notices should be accurate and should not erase previous or third-party copyright holders. + +--- + +## 13. Apache License Compliance + +When redistributing Apache-licensed work or derivative works, the project must review and satisfy applicable requirements, including: + +- providing a copy of the Apache License 2.0 +- marking modified files where required +- retaining applicable copyright notices +- retaining applicable patent notices +- retaining applicable trademark notices +- retaining applicable attribution notices +- reproducing required `NOTICE` content where applicable +- not using the licence to claim trademark authorization + +A `NOTICE` file should be created when: + +- required by an incorporated work +- attribution notices need to be distributed +- the project has release-level notices that should accompany binaries + +A `NOTICE` file must not be used to add restrictions that modify the Apache License. + +--- + +## 14. Third-Party Dependencies + +Every new dependency must be reviewed before it is added. + +The review should consider: + +- dependency name +- version +- source +- licence name and version +- whether commercial and non-commercial use are allowed +- whether modification is allowed +- whether redistribution is allowed +- attribution requirements +- source-disclosure requirements +- patent clauses +- trademark restrictions +- binary redistribution terms +- platform restrictions +- field-of-use restrictions +- compatibility with Apache License 2.0 +- maintenance status +- security status +- whether the dependency is genuinely necessary +- whether a standard-library or platform alternative exists + +Dependencies must not be added solely because they are: + +- publicly downloadable +- available from a package manager +- free of charge +- visible on GitHub +- included in another application +- technically convenient + +Public availability does not automatically mean redistribution is permitted. + +Where practical, pull requests adding dependencies should include: + +```text +Dependency: +Version: +Source: +Licence: +Purpose: +Redistribution requirements: +Relevant notices: +Alternatives considered: +Security or maintenance concerns: +``` + +Dependencies with unclear, custom, non-commercial, research-only, source-available, or restrictive licences require explicit maintainer review. + +--- + +## 15. Binary Components + +Binary-only components require heightened review. + +Before adding or distributing a binary, maintainers must determine: + +- who owns it +- where it came from +- whether redistribution is allowed +- whether modification is allowed +- whether reverse engineering is restricted +- whether the binary is architecture-specific +- whether it includes additional bundled software +- whether it collects data +- whether it contacts third-party services +- whether it requires separate end-user terms +- whether source-code obligations apply +- whether checksums and provenance can be recorded + +Unknown, leaked, extracted, repackaged, or unverifiable binaries must not be distributed. + +--- + +## 16. Android Images and System Images + +WinDroid Runtime must not assume that an Android image may be redistributed merely because it can be downloaded or booted. + +Each image must be reviewed for: + +- source +- publisher +- component licences +- vendor components +- proprietary applications +- firmware +- drivers +- codec licences +- Google components +- device-specific packages +- redistribution terms +- modification rights +- export restrictions +- required notices + +The project should prefer: + +- images built from properly licensed source +- reproducible build processes +- clear component manifests +- documented provenance +- user-supplied images where redistribution is not permitted +- download instructions pointing users to lawful official sources + +The project must not host or mirror images whose redistribution rights are unclear. + +--- + +## 17. APK and Application Distribution + +WinDroid Runtime may provide tools that allow users to install APK files they lawfully possess. + +The project must not: + +- host pirated APK files +- provide links intended to bypass paid distribution +- distribute modified proprietary applications without permission +- distribute cracked applications +- bypass licence checks +- bypass digital-rights-management systems +- impersonate application stores +- bundle applications without redistribution rights +- encourage violation of application licences + +Support for APK installation does not mean the project verifies the legality, safety, authenticity, or licence status of every APK selected by a user. + +Documentation should encourage users to obtain applications from lawful and trustworthy sources. + +--- + +## 18. Reverse Engineering and Interoperability Research + +Reverse-engineering and interoperability rights vary by jurisdiction, contract, licence, and applicable law. + +No contributor should assume that conduct permitted in one country is automatically permitted elsewhere. + +Any reverse-engineering-related work must avoid: + +- leaked source code +- stolen credentials +- unauthorized access +- circumvention of access controls +- circumvention of technological protection measures +- violation of confidentiality obligations +- use of employer-confidential information +- copying protected implementation expression +- distribution of proprietary extracted material + +Where interoperability research is necessary, contributors should prefer: + +- public documentation +- standards +- observable behaviour +- independent test programs +- protocol traces created lawfully +- independently written implementations +- documented research methodology +- clean separation between researchers and implementers where appropriate + +Uncertain work should be discussed privately with maintainers before publication or submission. + +--- + +## 19. Security Research and Restricted Material + +The repository must not be used to publish or distribute: + +- stolen credentials +- private signing keys +- leaked certificates +- production access tokens +- exploit chains targeting active users +- malware +- credential-stealing tools +- proprietary keys +- confidential vulnerability reports +- bypasses that create unjustified user risk +- restricted third-party security material + +Legitimate defensive security research may be accepted where it is: + +- relevant to the project +- responsibly disclosed +- lawful +- safely documented +- limited to necessary technical detail +- reviewed by maintainers + +Security vulnerabilities in WinDroid Runtime should be reported according to `SECURITY.md`. + +--- + +## 20. Contributor Certification + +By submitting a contribution, a contributor represents that: + +- they created the contribution or have the right to submit it +- the contribution may be distributed under the repository licence +- the contribution does not knowingly contain unlawfully copied material +- required third-party notices have been preserved +- dependencies and borrowed material have been disclosed +- confidential employer or client material has not been included +- generated content has been reviewed +- the contribution does not knowingly violate another project’s licence +- they have not intentionally concealed the origin of substantial material + +Maintainers may request: + +- source links +- licence files +- attribution information +- design notes +- dependency justification +- provenance explanations +- proof of permission +- replacement of questionable material + +Refusal or inability to provide reasonable provenance information may result in rejection or removal. + +--- + +## 21. Developer Certificate of Origin + +The project may adopt the Developer Certificate of Origin for contributor sign-off. + +Where enabled, contributors may be required to sign commits using: + +```text +Signed-off-by: Name +``` + +Use of sign-off indicates that the contributor certifies their right to submit the contribution under the project’s licence and contribution process. + +Commit sign-off is not a substitute for licence review, provenance review, or legal advice. + +--- + +## 22. AI-Assisted Contributions + +AI-assisted code, documentation, tests, images, or designs must be reviewed as carefully as human-written material. + +Contributors using AI assistance remain responsible for: + +- correctness +- security +- originality +- licence compliance +- attribution +- provenance +- confidential-information handling +- third-party rights +- compliance with repository policy + +AI-generated material must not be submitted when: + +- it reproduces identifiable third-party code without permission +- its origin cannot be reasonably assessed +- it contains confidential information +- it introduces copied branding or artwork +- it creates false legal or compatibility claims +- it includes insecure or unreviewed code +- it is submitted without meaningful human review + +AI assistance must not be used as a justification for ignoring licensing or attribution concerns. + +--- + +## 23. Documentation and Public Claims + +Documentation, release notes, websites, social posts, videos, and interviews must not make unsupported claims. + +The project must not claim: + +- universal Android application compatibility +- Google certification +- Microsoft certification +- official successor status +- production readiness before verification +- security guarantees that have not been established +- legal permission to distribute third-party components without evidence +- performance results without reproducible testing +- compliance with standards that have not been formally tested + +Compatibility claims should be qualified and evidence-based. + +Preferred language includes: + +- “experimental” +- “planned” +- “under research” +- “tested with” +- “currently supports” +- “not yet implemented” +- “compatibility may vary” + +Avoid absolute statements such as: + +- “works with every Android app” +- “fully secure” +- “officially compatible” +- “drop-in WSA replacement” +- “guaranteed safe” +- “legally approved” + +--- + +## 24. Compatibility Testing + +Compatibility testing must use software and images obtained lawfully. + +Test results should record: + +- application name +- application version +- source +- WinDroid version +- Windows version +- runtime backend +- test date +- observed result +- known limitations + +A compatibility result does not grant permission to redistribute the tested application. + +Application names and logos should not be used in project marketing beyond reasonable factual identification without appropriate permission. + +--- + +## 25. Privacy and Telemetry + +Any future telemetry, diagnostics, crash reporting, or analytics feature must be reviewed for: + +- user consent +- data minimization +- transparency +- retention +- security +- third-party processors +- regional legal requirements +- opt-out or opt-in design +- documentation +- sensitive-data handling + +The project must not silently collect: + +- installed application lists +- file paths +- personal identifiers +- account information +- device identifiers +- user documents +- precise usage history +- ADB contents +- logs containing sensitive information + +Telemetry must not be introduced through a dependency without disclosure and review. + +--- + +## 26. Project Assets and Media + +All project logos, icons, screenshots, diagrams, fonts, sounds, videos, and promotional assets must have documented provenance. + +Assets must be: + +- original +- properly licensed +- public domain +- used with written permission +- generated under terms permitting project use + +The project must not use: + +- Microsoft logos +- Windows logos +- Android logos outside permitted guidelines +- Google logos +- Amazon logos +- copied emulator icons +- copyrighted artwork without permission +- commercial fonts without appropriate rights +- stock media without appropriate licensing + +Asset source files and licence information should be retained where practical. + +--- + +## 27. Domains, Accounts, and Package Identifiers + +Project domains, organization accounts, code-signing identities, package identifiers, and application-store accounts are project infrastructure. + +They must not be created, transferred, sold, or closed without maintainer approval. + +Access should follow: + +- least privilege +- multi-factor authentication +- documented recovery methods +- secure credential storage +- separation of personal and project credentials where practical +- transfer planning for future organizational changes + +Contributors must not claim personal ownership over project identity merely because they created an account on the project’s behalf. + +Formal ownership and transfer arrangements should be documented separately. + +--- + +## 28. Commercial Distribution + +Commercial use may be permitted by the applicable open-source licences, but commercial distribution introduces additional obligations and risks. + +Before a commercial release, maintainers should review: + +- third-party licences +- consumer-law obligations +- warranties and disclaimers +- privacy obligations +- export-control issues +- tax and payment requirements +- code-signing requirements +- app-store terms +- trademark clearance +- patent risks +- support commitments +- system-image redistribution +- proprietary codec or firmware inclusion + +No contributor may enter a commercial, sponsorship, licensing, or distribution agreement on behalf of WinDroid Runtime or Nova Systems Lab without explicit authority. + +--- + +## 29. Release Review + +Before publishing a binary release, maintainers should verify: + +- source provenance +- dependency licences +- binary redistribution rights +- required licence files +- required notices +- third-party attributions +- modification notices +- system-image rights +- application bundling rights +- trademark presentation +- release claims +- privacy behaviour +- telemetry behaviour +- security-sensitive components +- code-signing identity +- reproducibility where practical + +A release should not proceed while a material legal, licensing, provenance, trademark, or security concern remains unresolved. + +--- + +## 30. Handling Uncertainty + +Where a contributor or maintainer is uncertain about: + +- licensing +- copyright +- patents +- trademarks +- redistribution +- reverse engineering +- proprietary components +- binary provenance +- application distribution +- system-image distribution +- confidential information +- AI-generated material + +they must stop and request review before merging, publishing, or distributing the material. + +The project should prefer exclusion over uncertain distribution. + +Temporary removal of disputed material does not imply wrongdoing. It is a precautionary project-management action. + +--- + +## 31. Enforcement + +Maintainers may: + +- reject contributions +- request revisions +- request provenance information +- remove files +- remove releases +- disable downloads +- revert commits +- suspend contributor access +- lock discussions +- report suspected infringement +- contact upstream owners +- request formal legal review + +where material appears inconsistent with this policy. + +Repeated or intentional violations may result in removal from the project. + +--- + +## 32. Maintainer Responsibilities + +Maintainers are responsible for: + +- applying this policy consistently +- recording dependency decisions +- preserving licence and attribution files +- reviewing release contents +- avoiding unsupported public claims +- responding to legitimate rights-holder concerns +- documenting exceptions +- protecting project credentials +- reviewing branding changes +- separating project policy from legal advice +- obtaining professional advice when risk is significant + +Maintainer approval does not guarantee that material is legally risk-free. + +--- + +## 33. Current Distribution Policy + +During the early development and research phases, WinDroid Runtime should distribute only: + +- original project source code +- original project documentation +- original project artwork +- properly licensed dependencies +- build outputs whose components are approved for redistribution + +The project should not currently distribute: + +- complete Android system images +- Google applications or services +- WSA-derived files +- proprietary vendor firmware +- proprietary application stores +- copied commercial-emulator components +- device-specific proprietary packages +- third-party APK collections + +This policy may be revised after technical, licensing, and legal review. + +--- + +## 34. Related Repository Documents + +This policy should be read together with: + +- [`README.md`](../README.md) +- [`LICENSE`](../LICENSE) +- [`CONTRIBUTING.md`](../CONTRIBUTING.md) +- [`SECURITY.md`](../SECURITY.md) +- `NOTICE`, when added +- third-party licence and attribution files +- dependency documentation +- release checklists + +Where a conflict exists between this policy and an applicable third-party licence, the applicable licence must be reviewed and followed. + +This policy does not override statutory law, contractual obligations, or third-party licence terms. + +--- + +## 35. Policy Changes + +This document may be updated as: + +- the architecture evolves +- runtime components are selected +- dependencies are added +- distribution methods change +- the project begins publishing binaries +- legal or trademark guidance changes +- Nova Systems Lab’s organizational status changes +- professional legal advice is obtained + +Material changes should be reviewed through a pull request. + +The pull request should explain: + +- what changed +- why it changed +- which project areas are affected +- whether existing releases or assets require review + +--- + +## 36. Contact and Escalation + +Questions about this policy should be raised through an appropriate project discussion or maintainer communication channel. + +Potential security vulnerabilities should follow `SECURITY.md` rather than being posted publicly. + +Potential copyright, trademark, licence, or redistribution concerns should include: + +- the affected file or release +- the relevant rights holder +- the source of the material +- the applicable licence or policy +- the requested corrective action + +Sensitive claims or confidential evidence should not be posted publicly. + +--- + +## Summary + +WinDroid Runtime must remain: + +- independently implemented +- openly licensed +- clearly branded +- transparent about compatibility +- careful with third-party material +- separate from Microsoft, Google, Amazon, and WSA +- conservative about proprietary binaries and system images +- accountable for the provenance of code and assets + +When ownership, licensing, redistribution, branding, or provenance is unclear, do not merge or distribute the material until it has been reviewed. \ No newline at end of file From 5272d31c3442f2096812cadaaf26c355e33b615d Mon Sep 17 00:00:00 2001 From: Samrat Banerjee <106741933+SamratB8@users.noreply.github.com> Date: Mon, 13 Jul 2026 21:19:28 +0530 Subject: [PATCH 04/10] Add Sentry error monitoring --- src/WinDroid.Studio/App.xaml.cs | 24 +++++++++++++++++++++- src/WinDroid.Studio/WinDroid.Studio.csproj | 1 + 2 files changed, 24 insertions(+), 1 deletion(-) diff --git a/src/WinDroid.Studio/App.xaml.cs b/src/WinDroid.Studio/App.xaml.cs index 504f2ec..a48f469 100644 --- a/src/WinDroid.Studio/App.xaml.cs +++ b/src/WinDroid.Studio/App.xaml.cs @@ -1,4 +1,5 @@ using Microsoft.UI.Xaml; +using Sentry; namespace WinDroid.Studio; @@ -7,16 +8,37 @@ namespace WinDroid.Studio; /// public partial class App : Application { + private readonly IDisposable _sentry; private Window? _window; public App() { + _sentry = SentrySdk.Init(options => + { + options.Dsn = Environment.GetEnvironmentVariable("SENTRY_DSN"); + +#if DEBUG + options.Debug = true; +#else + options.Debug = false; +#endif + + options.AutoSessionTracking = true; + }); + InitializeComponent(); } protected override void OnLaunched(LaunchActivatedEventArgs args) { _window = new MainWindow(); + _window.Closed += OnMainWindowClosed; _window.Activate(); } -} + + private async void OnMainWindowClosed(object sender, WindowEventArgs args) + { + await SentrySdk.FlushAsync(TimeSpan.FromSeconds(2)); + _sentry.Dispose(); + } +} \ No newline at end of file diff --git a/src/WinDroid.Studio/WinDroid.Studio.csproj b/src/WinDroid.Studio/WinDroid.Studio.csproj index 206cacb..d0c10bc 100644 --- a/src/WinDroid.Studio/WinDroid.Studio.csproj +++ b/src/WinDroid.Studio/WinDroid.Studio.csproj @@ -22,6 +22,7 @@ + From 023da5355065f6b0125650e831aea3fe02376323 Mon Sep 17 00:00:00 2001 From: Samrat Banerjee <106741933+SamratB8@users.noreply.github.com> Date: Mon, 13 Jul 2026 22:08:04 +0530 Subject: [PATCH 05/10] feat(adb): add ADB path detection service (#3) Add the initial ADB executable path resolution service. - add AdbPathResolver and AdbPathResult - check an optional custom ADB executable path - fall back to searching the current system PATH - support adb.exe and adb - return normalized absolute paths - report missing ADB through a structured failure result - keep the implementation independent from WinUI and process execution Closes #3. --- src/WinDroid.Adb/Models/AdbPathResult.cs | 71 ++++++++ src/WinDroid.Adb/Services/AdbPathResolver.cs | 173 +++++++++++++++++++ 2 files changed, 244 insertions(+) create mode 100644 src/WinDroid.Adb/Models/AdbPathResult.cs create mode 100644 src/WinDroid.Adb/Services/AdbPathResolver.cs diff --git a/src/WinDroid.Adb/Models/AdbPathResult.cs b/src/WinDroid.Adb/Models/AdbPathResult.cs new file mode 100644 index 0000000..f20cfe7 --- /dev/null +++ b/src/WinDroid.Adb/Models/AdbPathResult.cs @@ -0,0 +1,71 @@ +namespace WinDroid.Adb.Models; + +/// +/// Represents the outcome of attempting to locate an ADB executable. +/// +/// +/// A successful result carries a non-empty and a +/// . A failed result carries a +/// and a non-empty +/// . Use and +/// to construct values that honour these invariants. +/// +public sealed class AdbPathResult +{ + /// + /// Gets a value indicating whether an ADB executable was located. + /// + public bool Found { get; init; } + + /// + /// Gets the resolved absolute path to the ADB executable when + /// is ; otherwise + /// . + /// + public string? Path { get; init; } + + /// + /// Gets a concise, user-safe explanation of why resolution failed when + /// is ; otherwise + /// . + /// + public string? ErrorMessage { get; init; } + + /// + /// Creates a successful result for the given resolved executable path. + /// + /// The resolved absolute path to the ADB executable. + /// + /// is , empty, or whitespace. + /// + public static AdbPathResult Success(string path) + { + ArgumentException.ThrowIfNullOrWhiteSpace(path); + + return new AdbPathResult + { + Found = true, + Path = path, + ErrorMessage = null, + }; + } + + /// + /// Creates a failed result with the given user-safe error message. + /// + /// A concise explanation of the failure. + /// + /// is , empty, or whitespace. + /// + public static AdbPathResult Failure(string errorMessage) + { + ArgumentException.ThrowIfNullOrWhiteSpace(errorMessage); + + return new AdbPathResult + { + Found = false, + Path = null, + ErrorMessage = errorMessage, + }; + } +} diff --git a/src/WinDroid.Adb/Services/AdbPathResolver.cs b/src/WinDroid.Adb/Services/AdbPathResolver.cs new file mode 100644 index 0000000..87cfa96 --- /dev/null +++ b/src/WinDroid.Adb/Services/AdbPathResolver.cs @@ -0,0 +1,173 @@ +using WinDroid.Adb.Models; + +namespace WinDroid.Adb.Services; + +/// +/// Locates an ADB executable by checking an optional custom path and then the +/// directories listed in the system PATH environment variable. +/// +/// +/// This type only determines whether an ADB executable exists on disk. It does +/// not launch ADB and does not verify that a located file is a genuine ADB +/// binary. The system PATH is read on every call so that environment +/// changes during the application lifetime are honoured. +/// +public sealed class AdbPathResolver +{ + // The active application target is Windows, where the executable is named + // "adb.exe". The plain "adb" name is also checked so the portable library + // behaves sensibly on non-Windows hosts. "adb.exe" is checked first so + // resolution is deterministic when both names exist in the same directory. + private static readonly string[] ExecutableNames = ["adb.exe", "adb"]; + + /// + /// Attempts to locate an ADB executable. + /// + /// + /// Optional path to an ADB executable, typically supplied from + /// AdbSettings.CustomAdbPath. , empty, or + /// whitespace values are ignored and resolution falls back to the system + /// PATH. + /// + /// + /// A successful containing the resolved path, or + /// a failed result whose explains + /// why ADB could not be found. A missing ADB is an expected outcome and is + /// reported through the result rather than by throwing. + /// + public AdbPathResult Resolve(string? customAdbPath = null) + { + string? normalizedCustomPath = NormalizeToken(customAdbPath); + bool customPathSupplied = normalizedCustomPath is not null; + + if (customPathSupplied && File.Exists(normalizedCustomPath)) + { + string? resolved = GetFullPathSafe(normalizedCustomPath!); + if (resolved is not null) + { + return AdbPathResult.Success(resolved); + } + + // The file exists but its path could not be normalized to an + // absolute path, so fall through to the system PATH search. + } + + string? pathMatch = SearchSystemPath(); + if (pathMatch is not null) + { + return AdbPathResult.Success(pathMatch); + } + + return AdbPathResult.Failure(BuildNotFoundMessage(customPathSupplied)); + } + + /// + /// Searches the directories listed in the system PATH for a known ADB + /// executable name, returning the first match as an absolute path. + /// + private static string? SearchSystemPath() + { + string? pathVariable = Environment.GetEnvironmentVariable("PATH"); + if (string.IsNullOrEmpty(pathVariable)) + { + return null; + } + + var visitedDirectories = new HashSet(StringComparer.OrdinalIgnoreCase); + + foreach (string rawEntry in pathVariable.Split(Path.PathSeparator)) + { + string? directory = NormalizeToken(rawEntry); + if (directory is null || !visitedDirectories.Add(directory)) + { + // Blank or duplicate entry; skip without touching the filesystem. + continue; + } + + string? match = FindExecutableInDirectory(directory); + if (match is not null) + { + return match; + } + } + + return null; + } + + /// + /// Returns the absolute path to the first known ADB executable found in the + /// given directory, or if none is present or the + /// entry cannot be inspected. + /// + private static string? FindExecutableInDirectory(string directory) + { + foreach (string executableName in ExecutableNames) + { + string candidate = Path.Combine(directory, executableName); + + // File.Exists is exception-free and returns false for malformed or + // inaccessible paths, so unusable PATH entries are skipped safely. + if (File.Exists(candidate)) + { + string? resolved = GetFullPathSafe(candidate); + if (resolved is not null) + { + return resolved; + } + + // Exists but cannot be normalized to an absolute path; skip it. + } + } + + return null; + } + + /// + /// Trims surrounding whitespace and a single pair of matching surrounding + /// quotation marks, returning when nothing usable + /// remains. + /// + private static string? NormalizeToken(string? value) + { + if (string.IsNullOrWhiteSpace(value)) + { + return null; + } + + string trimmed = value.Trim(); + + if (trimmed.Length >= 2 && trimmed[0] == '"' && trimmed[^1] == '"') + { + trimmed = trimmed[1..^1].Trim(); + } + + return string.IsNullOrEmpty(trimmed) ? null : trimmed; + } + + /// + /// Produces an absolute, normalized path, returning + /// if the path cannot be normalized. + /// + private static string? GetFullPathSafe(string path) + { + try + { + return Path.GetFullPath(path); + } + catch (Exception ex) when ( + ex is ArgumentException + or PathTooLongException + or NotSupportedException + or System.Security.SecurityException) + { + return null; + } + } + + private static string BuildNotFoundMessage(bool customPathSupplied) => + customPathSupplied + ? "ADB could not be found. The supplied custom path did not point to a " + + "valid ADB executable file, and no ADB executable was found through " + + "the system PATH." + : "ADB could not be found through the system PATH."; +} From ce3464853d332e45e0923e611a8d7225db254068 Mon Sep 17 00:00:00 2001 From: Samrat Banerjee <106741933+SamratB8@users.noreply.github.com> Date: Wed, 15 Jul 2026 18:30:32 +0530 Subject: [PATCH 06/10] Add navigation links and security policy to README Added a navigation section with links to website, organization, discussions, and issues near the top of the README. Also added information about the security policy and contact email for private security reports in the contributing section. --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.md b/README.md index f2b66b8..a8e5a3d 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,11 @@ ![Language](https://img.shields.io/badge/language-C%23-purple) ![License](https://img.shields.io/badge/license-Apache%202.0-green) +[Website](https://novasystemslab.org) · +[Organization](https://novasystemslab.org) · +[Discussions](https://github.com/Nova-Systems-Lab/WinDroid-Runtime/discussions) · +[Issues](https://github.com/Nova-Systems-Lab/WinDroid-Runtime/issues) + **WinDroid Runtime** is an independent Android-compatible runtime and toolkit for Windows. The long-term goal of this project is to build a modern platform that allows Android applications to run, integrate, and feel natural on Windows. The project is being designed from scratch, starting with developer tooling, APK management, ADB integration, and runtime research before moving toward experimental Android runtime and desktop integration research. @@ -347,6 +352,8 @@ For official project work: - Use GitHub Issues for confirmed bugs and actionable tasks. - Use Pull Requests for code and documentation changes. +For private security reports, follow the [security policy](SECURITY.md) or contact [security@novasystemslab.org](mailto:security@novasystemslab.org). + ## Current First Milestone The first practical milestone is to build WinDroid Studio v0.1, a native Windows application that can: From ba1498405db2d6a3050ab9dc590be6bf4984a0ea Mon Sep 17 00:00:00 2001 From: Samrat Banerjee <106741933+SamratB8@users.noreply.github.com> Date: Wed, 15 Jul 2026 21:20:02 +0530 Subject: [PATCH 07/10] feat(adb): add async process runner for executing commands (#4) Add a reusable asynchronous process runner to WinDroid.Adb. - add ProcessRunner and CommandResult - launch executables directly without a shell - pass arguments safely through ProcessStartInfo.ArgumentList - capture stdout and stderr concurrently - return normal and non-zero exit codes - support timeout and caller cancellation - avoid launching when the caller token is already cancelled - terminate the process tree on timeout or cancellation - use bounded cleanup waits - return structured startup failures - keep the implementation separate from UI and ADB command parsing Closes #4. --- src/WinDroid.Adb/Models/CommandResult.cs | 205 ++++++++++++++ src/WinDroid.Adb/Services/ProcessRunner.cs | 301 +++++++++++++++++++++ 2 files changed, 506 insertions(+) create mode 100644 src/WinDroid.Adb/Models/CommandResult.cs create mode 100644 src/WinDroid.Adb/Services/ProcessRunner.cs diff --git a/src/WinDroid.Adb/Models/CommandResult.cs b/src/WinDroid.Adb/Models/CommandResult.cs new file mode 100644 index 0000000..93014a0 --- /dev/null +++ b/src/WinDroid.Adb/Models/CommandResult.cs @@ -0,0 +1,205 @@ +namespace WinDroid.Adb.Models; + +/// +/// Represents the outcome of running an external process. +/// +/// +/// Exactly one high-level outcome applies to any result: +/// +/// +/// Normal completion — is , +/// and are +/// , and is the process exit +/// code (which may be non-zero). +/// +/// +/// Timeout — is and +/// is . +/// +/// +/// Caller cancellation — is . +/// This may occur before the process is started (the caller token was +/// already cancelled, so is ) +/// or after it is started ( is ). +/// +/// +/// Startup failure — is and +/// is non-empty. +/// +/// +/// Use the static factory methods to construct values that honour these +/// invariants. +/// +public sealed class CommandResult +{ + /// + /// Sentinel exit code used when the real process exit code is unavailable, + /// for example after a startup failure or after a process is terminated + /// without a reportable exit code. + /// + public const int UnknownExitCode = -1; + + /// + /// Gets the process exit code, or when it is + /// unavailable. + /// + public int ExitCode { get; init; } + + /// + /// Gets the captured standard output. Never . Holds the + /// text of a completed stream read (including output produced before a + /// terminated process exited); if the stream did not finish draining within + /// the bounded cleanup period, this is an empty string. + /// + public string StandardOutput { get; init; } = string.Empty; + + /// + /// Gets the captured standard error. Never . Holds the + /// text of a completed stream read (including output produced before a + /// terminated process exited); if the stream did not finish draining within + /// the bounded cleanup period, this is an empty string. + /// + public string StandardError { get; init; } = string.Empty; + + /// + /// Gets a value indicating whether the process was started successfully. + /// + public bool Started { get; init; } + + /// + /// Gets a value indicating whether the process was terminated because the + /// timeout elapsed. + /// + public bool TimedOut { get; init; } + + /// + /// Gets a value indicating whether the process was terminated because the + /// caller cancelled the operation. + /// + public bool Cancelled { get; init; } + + /// + /// Gets a concise, user-safe message describing why the process could not be + /// started when is ; otherwise + /// . Never contains a stack trace. + /// + public string? ErrorMessage { get; init; } + + /// + /// Creates a result for a process that ran to completion. + /// + /// The process exit code (may be non-zero). + /// The captured standard output. + /// The captured standard error. + public static CommandResult Completed(int exitCode, string standardOutput, string standardError) + { + ArgumentNullException.ThrowIfNull(standardOutput); + ArgumentNullException.ThrowIfNull(standardError); + + return new CommandResult + { + Started = true, + TimedOut = false, + Cancelled = false, + ExitCode = exitCode, + StandardOutput = standardOutput, + StandardError = standardError, + ErrorMessage = null, + }; + } + + /// + /// Creates a result for a process that was terminated because the timeout + /// elapsed. + /// + /// + /// The exit code observed after termination, or + /// when unavailable. + /// + /// Any standard output captured before termination. + /// Any standard error captured before termination. + public static CommandResult Timeout(int exitCode, string standardOutput, string standardError) + { + ArgumentNullException.ThrowIfNull(standardOutput); + ArgumentNullException.ThrowIfNull(standardError); + + return new CommandResult + { + Started = true, + TimedOut = true, + Cancelled = false, + ExitCode = exitCode, + StandardOutput = standardOutput, + StandardError = standardError, + ErrorMessage = null, + }; + } + + /// + /// Creates a result for a process that was terminated because the caller + /// cancelled the operation. + /// + /// + /// The exit code observed after termination, or + /// when unavailable. + /// + /// Any standard output captured before termination. + /// Any standard error captured before termination. + public static CommandResult Cancellation(int exitCode, string standardOutput, string standardError) + { + ArgumentNullException.ThrowIfNull(standardOutput); + ArgumentNullException.ThrowIfNull(standardError); + + return new CommandResult + { + Started = true, + TimedOut = false, + Cancelled = true, + ExitCode = exitCode, + StandardOutput = standardOutput, + StandardError = standardError, + ErrorMessage = null, + }; + } + + /// + /// Creates a result for an operation that was cancelled before the process + /// was started, because the caller's token was already cancelled. + /// + public static CommandResult CancellationBeforeStart() + { + return new CommandResult + { + Started = false, + TimedOut = false, + Cancelled = true, + ExitCode = UnknownExitCode, + StandardOutput = string.Empty, + StandardError = string.Empty, + ErrorMessage = null, + }; + } + + /// + /// Creates a result for a process that could not be started. + /// + /// A concise, user-safe explanation of the failure. + /// + /// is , empty, or whitespace. + /// + public static CommandResult StartupFailure(string errorMessage) + { + ArgumentException.ThrowIfNullOrWhiteSpace(errorMessage); + + return new CommandResult + { + Started = false, + TimedOut = false, + Cancelled = false, + ExitCode = UnknownExitCode, + StandardOutput = string.Empty, + StandardError = string.Empty, + ErrorMessage = errorMessage, + }; + } +} diff --git a/src/WinDroid.Adb/Services/ProcessRunner.cs b/src/WinDroid.Adb/Services/ProcessRunner.cs new file mode 100644 index 0000000..f8597a8 --- /dev/null +++ b/src/WinDroid.Adb/Services/ProcessRunner.cs @@ -0,0 +1,301 @@ +using System.ComponentModel; +using System.Diagnostics; +using WinDroid.Adb.Models; + +namespace WinDroid.Adb.Services; + +/// +/// Runs external processes asynchronously, capturing standard output, standard +/// error, and the exit code, with optional timeout and cancellation support. +/// +/// +/// This is a low-level primitive. It launches the executable directly (never a +/// shell), passes each argument individually through +/// , and does not interpret output or +/// exit codes. ADB-specific behaviour is layered on top of it elsewhere. +/// +public sealed class ProcessRunner +{ + /// + /// Maximum time to wait for a process to exit after it has been killed, so a + /// misbehaving process cannot make execution hang indefinitely. + /// + private static readonly TimeSpan TerminationWaitTimeout = TimeSpan.FromSeconds(5); + + /// + /// Maximum time to wait for redirected output to finish draining after the + /// process has exited, so a stuck stream cannot make execution hang. + /// + private static readonly TimeSpan OutputDrainTimeout = TimeSpan.FromSeconds(5); + + /// + /// Runs the given executable asynchronously and captures its output and exit + /// code. + /// + /// The path to the executable to run. + /// + /// The arguments to pass. Each entry is added individually to + /// ; no shell quoting is applied. + /// May be for no arguments. Individual entries must not + /// be . + /// + /// + /// Optional maximum run time. When it elapses the process and its child tree + /// are terminated and the result reports . + /// means no timeout. Must be greater than zero when + /// supplied. + /// + /// + /// When cancelled, the process and its child tree are terminated and a result + /// with is returned rather than throwing. + /// + /// A describing the outcome. + /// + /// is , empty, or + /// whitespace, or an entry of is + /// . + /// + /// + /// is less than or equal to zero. + /// + public async Task RunAsync( + string executablePath, + IReadOnlyList? arguments = null, + TimeSpan? timeout = null, + CancellationToken cancellationToken = default) + { + ArgumentException.ThrowIfNullOrWhiteSpace(executablePath); + + if (timeout is { } requestedTimeout && requestedTimeout <= TimeSpan.Zero) + { + throw new ArgumentOutOfRangeException( + nameof(timeout), + timeout, + "Timeout must be greater than zero, or null for no timeout."); + } + + var startInfo = new ProcessStartInfo + { + FileName = executablePath, + UseShellExecute = false, + RedirectStandardOutput = true, + RedirectStandardError = true, + CreateNoWindow = true, + }; + + if (arguments is not null) + { + foreach (string argument in arguments) + { + if (argument is null) + { + throw new ArgumentException( + "Argument values must not be null.", nameof(arguments)); + } + + startInfo.ArgumentList.Add(argument); + } + } + + // Honour an already-cancelled caller token before spending resources on + // launching a process only to immediately terminate it. + if (cancellationToken.IsCancellationRequested) + { + return CommandResult.CancellationBeforeStart(); + } + + using var process = new Process { StartInfo = startInfo }; + + try + { + if (!process.Start()) + { + return CommandResult.StartupFailure( + $"The process '{executablePath}' could not be started."); + } + } + catch (Exception ex) when ( + ex is Win32Exception or InvalidOperationException or PlatformNotSupportedException) + { + return CommandResult.StartupFailure( + $"Failed to start process '{executablePath}'. {ex.Message}"); + } + + // Begin draining both streams immediately. Reading them concurrently + // prevents a full pipe on one stream from blocking the process (and thus + // deadlocking) while we wait on the other. No cancellation token is + // forwarded: each read completes when its stream reaches end-of-file + // (including once the process is terminated), and its captured text is + // returned. A read that does not complete within the bounded drain + // period is reported as an empty string. + Task stdoutTask = process.StandardOutput.ReadToEndAsync(CancellationToken.None); + Task stderrTask = process.StandardError.ReadToEndAsync(CancellationToken.None); + + bool timedOut = false; + bool cancelled = false; + + using (var timeoutCts = new CancellationTokenSource()) + using (var linkedCts = + CancellationTokenSource.CreateLinkedTokenSource(cancellationToken, timeoutCts.Token)) + { + if (timeout is { } activeTimeout) + { + timeoutCts.CancelAfter(activeTimeout); + } + + try + { + await process.WaitForExitAsync(linkedCts.Token).ConfigureAwait(false); + } + catch (OperationCanceledException) + { + if (!process.HasExited) + { + // Caller cancellation takes precedence over timeout when both + // have fired, matching the documented precedence. + if (cancellationToken.IsCancellationRequested) + { + cancelled = true; + } + else + { + timedOut = true; + } + + await TerminateProcessAsync(process).ConfigureAwait(false); + } + + // If the process exited on its own just as the token fired, fall + // through and report normal completion instead of a spurious + // timeout or cancellation. + } + } + + (string standardOutput, string standardError) = + await DrainOutputAsync(stdoutTask, stderrTask).ConfigureAwait(false); + + int exitCode = TryGetExitCode(process); + + if (cancelled) + { + return CommandResult.Cancellation(exitCode, standardOutput, standardError); + } + + if (timedOut) + { + return CommandResult.Timeout(exitCode, standardOutput, standardError); + } + + return CommandResult.Completed(exitCode, standardOutput, standardError); + } + + /// + /// Kills the process and its child tree, then waits a bounded amount of time + /// for it to exit. Tolerates the race where the process has already exited. + /// + private static async Task TerminateProcessAsync(Process process) + { + try + { + process.Kill(entireProcessTree: true); + } + catch (Exception ex) when ( + ex is InvalidOperationException or Win32Exception or NotSupportedException) + { + // The process already exited, could not be accessed, or the tree + // cannot be killed on this platform. Fall through to the bounded wait. + } + + try + { + await process.WaitForExitAsync() + .WaitAsync(TerminationWaitTimeout) + .ConfigureAwait(false); + } + catch (TimeoutException) + { + // The process did not exit within the bounded wait; stop waiting so + // execution cannot hang forever. + } + } + + /// + /// Awaits the two output reads with a bounded wait, returning whatever was + /// captured. Never throws and never hangs indefinitely. + /// + private static async Task<(string StandardOutput, string StandardError)> DrainOutputAsync( + Task stdoutTask, + Task stderrTask) + { + Task bothReads = Task.WhenAll(stdoutTask, stderrTask); + + try + { + // The reads complete when each stream reaches end-of-file, which + // happens once the process exits. The bounded wait guards against a + // process that never releases a stream. + await bothReads.WaitAsync(OutputDrainTimeout).ConfigureAwait(false); + } + catch (TimeoutException) + { + // Draining exceeded the bounded wait; return whatever completed. + } + catch (Exception ex) when (ex is IOException or ObjectDisposedException) + { + // A redirected stream broke (for example, after a kill); return + // whatever completed successfully below. + } + + string standardOutput = stdoutTask.IsCompletedSuccessfully ? stdoutTask.Result : string.Empty; + string standardError = stderrTask.IsCompletedSuccessfully ? stderrTask.Result : string.Empty; + + // A read that did not finish within the bounded drain is abandoned here. + // Observe any eventual fault so it cannot surface as an unobserved task + // exception, without blocking on the unfinished read. + ObserveEventualFault(stdoutTask); + ObserveEventualFault(stderrTask); + + return (standardOutput, standardError); + } + + /// + /// Ensures a read task's eventual fault is observed. If the task has already + /// finished, any fault is observed immediately; otherwise a fault-only + /// continuation observes it later without blocking the caller. + /// + private static void ObserveEventualFault(Task task) + { + if (task.IsCompleted) + { + _ = task.Exception; + return; + } + + _ = task.ContinueWith( + static t => _ = t.Exception, + CancellationToken.None, + TaskContinuationOptions.OnlyOnFaulted | TaskContinuationOptions.ExecuteSynchronously, + TaskScheduler.Default); + } + + /// + /// Returns the process exit code, or + /// when it is not available. + /// + private static int TryGetExitCode(Process process) + { + if (!process.HasExited) + { + return CommandResult.UnknownExitCode; + } + + try + { + return process.ExitCode; + } + catch (InvalidOperationException) + { + return CommandResult.UnknownExitCode; + } + } +} From 6099fe5470177e0eb6a449a6014cfe7768b2fe13 Mon Sep 17 00:00:00 2001 From: Samrat Banerjee <106741933+SamratB8@users.noreply.github.com> Date: Wed, 15 Jul 2026 21:41:20 +0530 Subject: [PATCH 08/10] feat(adb): add adb devices command wrapper (#5) Add a thin wrapper for running the adb devices command. - add AdbDeviceService and GetDevicesAsync - use the existing ProcessRunner - accept a caller-supplied resolved ADB path - pass exactly one argument: devices - forward timeout and cancellation unchanged - return the raw CommandResult unchanged - preserve stdout, stderr, exit code, timeout, cancellation, and startup failures - keep device parsing and UI integration out of scope Closes #5. --- src/WinDroid.Adb/Services/AdbDeviceService.cs | 65 +++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 src/WinDroid.Adb/Services/AdbDeviceService.cs diff --git a/src/WinDroid.Adb/Services/AdbDeviceService.cs b/src/WinDroid.Adb/Services/AdbDeviceService.cs new file mode 100644 index 0000000..6eb5a31 --- /dev/null +++ b/src/WinDroid.Adb/Services/AdbDeviceService.cs @@ -0,0 +1,65 @@ +using WinDroid.Adb.Models; + +namespace WinDroid.Adb.Services; + +/// +/// Runs the adb devices command by delegating to . +/// +/// +/// This wrapper only launches the command and returns the raw +/// . It does not resolve the ADB path (the caller +/// supplies an already-resolved path, typically from +/// ) and it does not parse the output. Parsing of +/// the device listing is intentionally left to a later stage. +/// +public sealed class AdbDeviceService +{ + private readonly ProcessRunner _processRunner; + + /// + /// Initializes a new instance of the class. + /// + /// The process runner used to execute ADB. + /// + /// is . + /// + public AdbDeviceService(ProcessRunner processRunner) + { + ArgumentNullException.ThrowIfNull(processRunner); + + _processRunner = processRunner; + } + + /// + /// Runs adb devices using the supplied ADB executable path and returns + /// the raw result. + /// + /// + /// Path to the ADB executable, already resolved by the caller. It is passed + /// through unchanged; this method does not revalidate or normalize it. + /// + /// + /// Optional maximum run time, forwarded to . + /// means no timeout. + /// + /// + /// Token forwarded to to cancel execution. + /// + /// + /// The unmodified produced by + /// , including its output, exit code, and timeout + /// or cancellation state. + /// + /// + /// is , empty, or whitespace. + /// + public Task GetDevicesAsync( + string adbPath, + TimeSpan? timeout = null, + CancellationToken cancellationToken = default) + { + ArgumentException.ThrowIfNullOrWhiteSpace(adbPath); + + return _processRunner.RunAsync(adbPath, ["devices"], timeout, cancellationToken); + } +} From 9007502c5d974d89b12af51841bcc8adae223e49 Mon Sep 17 00:00:00 2001 From: Samrat Banerjee <106741933+SamratB8@users.noreply.github.com> Date: Wed, 15 Jul 2026 22:06:09 +0530 Subject: [PATCH 09/10] fix(studio): make Sentry initialization optional Prevent WinDroid Studio from crashing at startup when SENTRY_DSN is not configured. - initialize WinUI before optional Sentry setup - read SENTRY_DSN from the environment - only initialize Sentry when the DSN is non-empty - make the Sentry handle nullable - only flush and dispose Sentry when it was initialized - preserve normal window startup and shutdown behavior The app now launches successfully without Sentry configuration. --- src/WinDroid.Studio/App.xaml.cs | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/src/WinDroid.Studio/App.xaml.cs b/src/WinDroid.Studio/App.xaml.cs index a48f469..7a1bdde 100644 --- a/src/WinDroid.Studio/App.xaml.cs +++ b/src/WinDroid.Studio/App.xaml.cs @@ -8,25 +8,30 @@ namespace WinDroid.Studio; /// public partial class App : Application { - private readonly IDisposable _sentry; + private IDisposable? _sentry; private Window? _window; public App() { - _sentry = SentrySdk.Init(options => + InitializeComponent(); + + var sentryDsn = Environment.GetEnvironmentVariable("SENTRY_DSN"); + + if (!string.IsNullOrWhiteSpace(sentryDsn)) { - options.Dsn = Environment.GetEnvironmentVariable("SENTRY_DSN"); + _sentry = SentrySdk.Init(options => + { + options.Dsn = sentryDsn; #if DEBUG - options.Debug = true; + options.Debug = true; #else - options.Debug = false; + options.Debug = false; #endif - options.AutoSessionTracking = true; - }); - - InitializeComponent(); + options.AutoSessionTracking = true; + }); + } } protected override void OnLaunched(LaunchActivatedEventArgs args) @@ -38,6 +43,11 @@ protected override void OnLaunched(LaunchActivatedEventArgs args) private async void OnMainWindowClosed(object sender, WindowEventArgs args) { + if (_sentry is null) + { + return; + } + await SentrySdk.FlushAsync(TimeSpan.FromSeconds(2)); _sentry.Dispose(); } From 4e593f7b7089bd2819d76c04af807230ba7e7c50 Mon Sep 17 00:00:00 2001 From: Samrat Banerjee <106741933+SamratB8@users.noreply.github.com> Date: Thu, 16 Jul 2026 18:57:30 +0530 Subject: [PATCH 10/10] docs(readme): define long-term product and architecture direction --- README.md | 666 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 521 insertions(+), 145 deletions(-) diff --git a/README.md b/README.md index a8e5a3d..634aa35 100644 --- a/README.md +++ b/README.md @@ -1,45 +1,184 @@ # WinDroid Runtime -![Status](https://img.shields.io/badge/status-planning-blue) +![Status](https://img.shields.io/badge/status-early%20development-blue) ![Platform](https://img.shields.io/badge/platform-Windows%2011-blue) ![Language](https://img.shields.io/badge/language-C%23-purple) ![License](https://img.shields.io/badge/license-Apache%202.0-green) [Website](https://novasystemslab.org) · -[Organization](https://novasystemslab.org) · +[Organization](https://github.com/Nova-Systems-Lab) · [Discussions](https://github.com/Nova-Systems-Lab/WinDroid-Runtime/discussions) · [Issues](https://github.com/Nova-Systems-Lab/WinDroid-Runtime/issues) **WinDroid Runtime** is an independent Android-compatible runtime and toolkit for Windows. -The long-term goal of this project is to build a modern platform that allows Android applications to run, integrate, and feel natural on Windows. The project is being designed from scratch, starting with developer tooling, APK management, ADB integration, and runtime research before moving toward experimental Android runtime and desktop integration research. +The long-term goal is to build a modular platform that allows Android applications to run, integrate, and feel natural on Windows. Development begins with WinDroid Studio, ADB integration, APK management, diagnostics, and developer tooling before moving into runtime-engine research, Windows integration, consumer experiences, and later gaming-focused work. -> **Project Status:** Early planning and research phase. -> This repository currently contains the project vision, roadmap, and architecture planning. Production-ready runtime code has not been implemented yet. -> This project is not currently usable as an Android runtime. It is a planning-stage repository for a long-term open-source systems project. +> [!IMPORTANT] +> **Current project status** +> +> WinDroid Runtime is in early development. The repository currently focuses on the native Windows management application and ADB-based tooling. +> +> It is **not yet a usable Android runtime**, and the Android runtime engine, consumer edition, gaming edition, anti-cheat compatibility, and most advanced features described below are long-term plans rather than current capabilities. + +> [!NOTE] +> **Roadmap sequencing** +> +> The current roadmap remains developer-first through Issue #36. After Issue #36 is complete, the project will open a dedicated architecture/RFC discussion to evaluate the future Developer, Desktop, and Gaming experiences. +> +> This does **not** mean those editions will be implemented immediately after Issue #36. That checkpoint begins architecture planning, feasibility work, validation, and prioritisation. Shared platform components will remain unified unless later evidence justifies a different design. --- ## Vision -Windows previously had official Android app support through Windows Subsystem for Android. After its discontinuation, there is a gap for users, developers, and students who want a clean Android-on-Windows experience without relying only on traditional emulators. +Windows previously offered official Android application support through Windows Subsystem for Android. Following its discontinuation, there is renewed interest in clean, secure, and well-integrated Android-on-Windows experiences. + +WinDroid Runtime aims to explore that space through an original, open-source Android-compatible runtime platform built independently from the ground up. + +The long-term product vision is: + +> **One shared runtime platform with specialised experiences for developers, ordinary Windows users, and gamers.** + +```text +WinDroid Platform +├── Shared Runtime Foundation +│ ├── Runtime Engine +│ ├── Android Virtual Device Layer +│ ├── Hardware Acceleration +│ ├── Graphics and Audio +│ ├── App Lifecycle Manager +│ ├── ADB and Debug Bridge +│ ├── Windows Integration Layer +│ ├── Security and Permissions +│ └── Update and Package System +│ +├── WinDroid Developer +│ └── Developers, testers, QA teams, and advanced users +│ +├── WinDroid Desktop +│ └── General users, productivity applications, and managed deployments +│ +└── WinDroid Gaming + └── Gaming-focused performance, input, and compatibility features +``` + +The project will not attempt to satisfy all three markets in its first release. + +--- + +## Product Direction + +### WinDroid Developer + +The first product direction. + +Planned areas include: -WinDroid Runtime aims to explore that space by building an independent, open-source Android-compatible runtime and toolkit for Windows. +- ADB and debugging tools +- APK installation and app management +- Device and environment information +- Logs and crash diagnostics +- Screenshots and file transfer +- Shell access +- Multiple Android environments +- Device and API-level profiles +- Snapshots +- Network and sensor simulation +- Automated testing +- IDE and CI integration +- Team and enterprise deployment tools -The goal is not to reuse or modify Microsoft WSA. The goal is to build an original system from the ground up. +The first practical releases will focus on the smaller and more achievable subset represented by the current GitHub issues. + +### WinDroid Desktop + +A future consumer and productivity experience built on the same shared runtime foundation. + +Potential features include: + +- Simple installation and onboarding +- Reliable Android application execution +- Per-app windows +- Start Menu shortcuts +- Windows notifications +- Clipboard and file sharing +- Camera, microphone, and location permission controls +- Privacy-oriented defaults +- Low idle resource usage +- Offline usability +- No advertisements or mandatory behavioural profiling +- Optional ADB access for advanced users +- Managed deployment for businesses, schools, and kiosks + +This experience will not begin until the runtime foundation reaches suitable compatibility, reliability, security, and usability gates. + +### WinDroid Gaming + +A later gaming-focused experience. + +Potential research and development areas include: + +- High and stable frame rates +- Keyboard and mouse mapping +- Controller support +- Multi-instance execution +- Macros and game profiles +- High-refresh rendering +- Low input latency +- Streaming and recording tools +- Graphics compatibility +- Performance tuning +- Game-specific optimisation +- Anti-cheat compatibility research + +> [!WARNING] +> **Anti-cheat compatibility is a long-term research goal, not a current guarantee.** +> +> WinDroid intends to pursue at least basic compatibility where technically and legally possible. Some anti-cheat systems may reject virtualised, translated, rooted, modified, or otherwise unsupported Android environments by design. Kernel-level or vendor-controlled anti-cheat systems may remain incompatible regardless of WinDroid improvements. +> +> Compatibility will be documented honestly on a per-game and per-version basis. + +Gaming work is planned after developer and desktop foundations because it requires exceptional performance, broad graphics compatibility, low latency, and extensive testing. --- ## Core Goals - Build an independent Android-compatible runtime for Windows. -- Provide a native Windows control application for managing the runtime. +- Provide a native Windows control application for managing the platform. - Support APK installation, uninstallation, launching, and debugging. - Integrate ADB-based developer tools. - Research Android image booting and runtime backends. -- Explore native-feeling Windows integration for Android apps. -- Build a safe, transparent, and open-source project structure. -- Avoid dependency on proprietary WSA binaries or branding. +- Explore native-feeling Windows integration for Android applications. +- Maintain shared runtime, ADB, security, update, and lifecycle components across future editions. +- Design for privacy, offline usability, signed updates, and explicit permission controls. +- Build a transparent and sustainable open-source project structure. +- Avoid dependency on proprietary WSA binaries or misleading branding. +- Communicate unsupported applications, services, games, and anti-cheat limitations honestly. + +--- + +## Current Development Scope + +The current repository work is focused on **WinDroid Studio and the ADB tooling foundation**. + +The present development sequence includes: + +- ADB path detection +- Safe process execution +- Device discovery and parsing +- Connected-device dashboard +- Logging and output +- APK selection and installation +- Installed package listing +- Package launching and uninstalling +- Device details +- ADB server controls +- Basic logcat viewing +- Tests, CI, and contributor infrastructure + +Completing this work demonstrates the management and developer-tooling layer. It does **not** by itself prove the final Android runtime engine. --- @@ -47,23 +186,27 @@ The goal is not to reuse or modify Microsoft WSA. The goal is to build an origin ### WinDroid Studio -The native Windows control application for managing WinDroid Runtime. +The native Windows control application for managing WinDroid Runtime and connected Android targets. -Planned features: +Current and near-term planned features: -- Runtime dashboard -- ADB detection -- Connected device/runtime detection +- Runtime and device dashboard +- ADB detection and configuration +- Connected device/runtime discovery - APK installation -- Installed app list -- App launch/uninstall controls -- Log viewer +- Installed package list +- App launch and uninstall controls +- Device details +- Log and output panel +- Logcat viewer - Runtime settings - Developer tools +WinDroid Studio is currently the developer-first interface. After Issue #36, the project will evaluate whether future user experiences should remain modes within one application or become separate front-end projects. + ### WinDroid Core -Shared project logic used across the runtime and control application. +Shared application logic and contracts. Planned responsibilities: @@ -73,21 +216,27 @@ Planned responsibilities: - Logging - Error handling - Shared models and services +- Security and permission abstractions +- Update and compatibility metadata ### WinDroid ADB Layer -A dedicated service layer for interacting with Android Debug Bridge. +A dedicated service layer for Android Debug Bridge operations. Planned features: - Detect ADB installation -- Start/stop ADB server +- Start and stop the ADB server - List connected devices - Install APK files +- List installed packages +- Launch applications - Uninstall packages -- Launch apps - Capture logs - Run shell commands +- Transfer files +- Capture screenshots +- Return structured command results ### WinDroid Engine @@ -96,136 +245,334 @@ The long-term experimental runtime backend. Research areas: - Android x86/x86_64 images -- AOSP / Generic System Images -- Virtualization on Windows -- QEMU / Hyper-V / Windows Hypervisor Platform research +- AOSP and Generic System Images +- Virtualisation on Windows +- QEMU +- Hyper-V +- Windows Hypervisor Platform - Android boot process +- Hardware acceleration - Graphics, input, audio, networking, and file bridges +- App lifecycle management +- Isolation and permissions +- Updates and rollback +- Runtime compatibility measurement + +--- + +## Architecture Principles + +1. One shared runtime foundation should serve all future product experiences. +2. The first usable product should target developers and technically advanced users. +3. Consumer and gaming experiences should begin only after technical and market validation. +4. WinDroid Studio and the WinDroid runtime engine are architecturally distinct. +5. `WinDroid.Core`, `WinDroid.Adb`, and `WinDroid.Engine` should remain shared. +6. Future editions should not duplicate the runtime engine or low-level service layers. +7. Each market expansion requires its own readiness gate, security review, success metrics, and user research. +8. Proprietary Microsoft, Google, Amazon, store, service, or anti-cheat components will not be redistributed without appropriate rights. +9. Privacy, offline usability, signed updates, and explicit permission controls are foundational requirements. +10. Scope may be reduced, delayed, or redirected when feasibility or user evidence does not support the existing plan. --- ## Development Roadmap -### Phase 0 — Planning and Research +> [!CAUTION] +> Roadmap phases describe intended direction, not fixed release dates or guaranteed features. Later phases depend on feasibility, licensing, contributor capacity, security review, performance, and real user demand. + +### Phase 0 — Planning and Project Foundation - [x] Choose project name -- [x] Define project scope +- [x] Define initial project scope - [x] Add license - [x] Create initial README -- [ ] Write architecture notes - [x] Create contribution guidelines -- [x] Document legal/trademark boundaries - -### Phase 1 — Native Windows Control App - -- [x] Create WinUI 3 / .NET project structure -- [ ] Build initial dashboard UI -- [ ] Add project settings page -- [ ] Add logging system -- [ ] Add basic runtime status panel +- [x] Document legal and trademark boundaries +- [ ] Complete initial architecture documentation +- [ ] Establish compatibility and security research notes -### Phase 2 — ADB Integration +### Phase 1 — Native Windows and ADB Foundation -- [ ] Detect ADB installation -- [ ] Allow custom ADB path -- [ ] Run `adb devices` -- [ ] Parse connected devices/emulators -- [ ] Display device information in the UI -- [ ] Start and stop ADB server +- [x] Create WinUI 3 / .NET solution structure +- [ ] Complete safe ADB process execution +- [ ] Detect and configure ADB +- [ ] Run and parse device commands +- [ ] Display connected devices +- [ ] Add settings persistence +- [ ] Add logging and output +- [ ] Add tests and CI validation -### Phase 3 — APK Management +### Phase 2 — APK and Application Management -- [ ] Select APK file from Windows -- [ ] Install APK to selected target +- [ ] Select APK files +- [ ] Install APKs to selected targets - [ ] List installed packages -- [ ] Launch installed apps -- [ ] Uninstall apps -- [ ] Clear app data -- [ ] Show install/log output clearly +- [ ] Launch installed applications +- [ ] Uninstall applications with confirmation +- [ ] Display command results and failures clearly -### Phase 4 — Developer Tools +### Phase 3 — Initial Developer Tools -- [ ] Add logcat viewer +- [ ] Add connected-device details +- [ ] Add ADB server controls +- [ ] Add basic logcat viewer - [ ] Add screenshot capture -- [ ] Add file push/pull tools +- [ ] Add file push and pull - [ ] Add basic shell command interface - [ ] Add exportable diagnostic reports -### Phase 5 — Runtime Backend Research +### Architecture Checkpoint — After Issue #36 + +After Issue #36 is complete: + +- [ ] Open a dedicated multi-experience architecture/RFC issue +- [ ] Review lessons from the current WinDroid Studio implementation +- [ ] Define what remains shared across all future editions +- [ ] Evaluate one application with modes versus separate front-end applications +- [ ] Define developer, desktop, and gaming readiness gates +- [ ] Define measurable performance and compatibility targets +- [ ] Review licensing, security, privacy, telemetry, and update requirements +- [ ] Conduct targeted user research +- [ ] Decide whether and when additional front-end projects should be created + +This checkpoint starts planning only. It does not begin immediate consumer or gaming implementation. + +### Phase 4 — Runtime Feasibility and Architecture Research -- [ ] Research AOSP x86/x86_64 boot options -- [ ] Research QEMU and Windows Hypervisor Platform +- [ ] Select and evaluate possible Android bases +- [ ] Compare virtual machine, container, compatibility-layer, and hybrid approaches +- [ ] Research supported Windows virtualisation technologies +- [ ] Define graphics, audio, input, storage, and networking strategies +- [ ] Define supported Windows and hardware baselines +- [ ] Complete component-level licensing research +- [ ] Create a security and threat model +- [ ] Define update, rollback, and recovery architecture - [ ] Boot a minimal Android-compatible image -- [ ] Connect to the runtime through ADB -- [ ] Install and launch a test APK inside the runtime +- [ ] Connect to the experimental runtime through ADB +- [ ] Install and launch a test APK -### Phase 6 — Windows Integration Research +### Phase 5 — Developer Runtime Prototype -- [ ] Explore app window forwarding -- [ ] Research input bridge -- [ ] Research clipboard sharing -- [ ] Research file sharing -- [ ] Research notification bridge -- [ ] Research Start Menu and shortcut integration +- [ ] Create repeatable Android environments +- [ ] Add environment and device profiles +- [ ] Add snapshots and recovery +- [ ] Add advanced diagnostics +- [ ] Add network and sensor simulation research +- [ ] Add automated testing hooks +- [ ] Research IDE and CI integration +- [ ] Run external developer testing +- [ ] Measure startup, stability, compatibility, and resource usage -### Phase 7 — Long-Term Runtime Goals +### Phase 6 — Windows Desktop Integration -- [ ] Independent runtime backend +- [ ] Explore per-app window forwarding +- [ ] Research Start Menu and shortcut integration +- [ ] Research notification bridging +- [ ] Research clipboard sharing +- [ ] Research file sharing +- [ ] Add host permission controls +- [ ] Define privacy-preserving defaults +- [ ] Build installer, updater, rollback, and recovery flows +- [ ] Conduct consumer and managed-deployment pilots + +### Phase 7 — Gaming Feasibility Research + +- [ ] Measure graphics performance and frame pacing +- [ ] Research low-latency input +- [ ] Add keyboard and mouse mapping prototypes +- [ ] Research controller support +- [ ] Evaluate multi-instance execution +- [ ] Research streaming and recording integration +- [ ] Build a game compatibility test programme +- [ ] Research basic anti-cheat compatibility +- [ ] Document unsupported anti-cheat systems and external restrictions +- [ ] Proceed only if technically and commercially justified + +### Phase 8 — Long-Term Platform Goals + +- [ ] Stable independent runtime backend +- [ ] Shared runtime foundation across product experiences - [ ] Per-app windows -- [ ] Shared folder controls -- [ ] Audio support -- [ ] Networking support -- [ ] GPU acceleration research +- [ ] Audio, networking, and GPU acceleration - [ ] Compatibility database -- [ ] Installer and public beta +- [ ] Modular installer +- [ ] Stable, Beta, Preview, and Canary release channels +- [ ] Developer preview +- [ ] Desktop pilot +- [ ] Gaming preview, if justified +- [ ] Public beta --- -## Proposed Repository Structure +## Future Product Structure + +No immediate repository division is planned. + +The current structure remains: ```text WinDroid-Runtime/ ├── src/ -│ ├── WinDroid.Studio/ # Native Windows control app -│ ├── WinDroid.Core/ # Shared logic and models -│ ├── WinDroid.Adb/ # ADB integration layer -│ └── WinDroid.Engine/ # Experimental runtime backend -│ -├── docs/ -│ ├── architecture.md -│ ├── roadmap.md -│ ├── research-log.md -│ └── legal-notes.md -│ -├── assets/ -│ └── branding/ -│ -├── README.md -├── LICENSE -├── CONTRIBUTING.md -├── SECURITY.md -└── .gitignore +│ ├── WinDroid.Studio/ # Current developer-first WinUI application +│ ├── WinDroid.Core/ # Shared logic, models, and abstractions +│ ├── WinDroid.Adb/ # Shared ADB integration layer +│ └── WinDroid.Engine/ # Shared experimental runtime backend ``` +After Issue #36 and the architecture/RFC review, a future structure may be considered: + +```text +WinDroid-Runtime/ +├── src/ +│ ├── WinDroid.Core/ # Shared +│ ├── WinDroid.Adb/ # Shared +│ ├── WinDroid.Engine/ # Shared +│ ├── WinDroid.Studio/ # Developer experience +│ ├── WinDroid.Desktop/ # Possible future consumer experience +│ └── WinDroid.Gaming/ # Possible future gaming experience +``` + +This structure is illustrative and has not yet been approved. + +--- + +## Readiness Gates + +### Developer Readiness + +Before broader expansion: + +- Reliable device discovery +- APK installation and uninstallation +- Stable logcat and diagnostics +- Repeatable environment creation +- Crash recovery +- Automated testing +- Measured startup and command reliability +- External technical testers +- Evidence of a specific workflow improvement + +### Desktop Readiness + +Before a consumer-facing release: + +- Simple installation and onboarding +- Stable app lifecycle handling +- Permission controls +- Signed updates and rollback +- No-data-loss recovery +- Acceptable idle resource usage +- Security review +- Compatibility testing +- Clear unsupported-app messaging + +### Gaming Readiness + +Before a gaming-focused release: + +- Proven graphics performance +- Stable frame pacing +- Low-latency input +- Keyboard, mouse, and controller testing +- Multi-instance resource controls +- Game-specific compatibility testing +- A documented anti-cheat compatibility position + +--- + +## Compatibility Programme + +Planned compatibility states: + +```text +Verified +Works with limitations +Launches but unstable +Unsupported +Blocked by external dependency +``` + +Compatibility records may include: + +- WinDroid version +- Android version +- Application or game version +- CPU architecture +- Graphics backend +- Required proprietary services +- Input method +- Known issues +- Test source +- Anti-cheat status where applicable + +Compatibility claims will be version-specific and evidence-based. + +--- + +## Security, Privacy, and Trust + +Planned security principles include: + +- Per-app and per-environment isolation +- Host filesystem boundaries +- Explicit clipboard, file, camera, microphone, and location controls +- ADB disabled by default for consumer users +- Signed update verification +- Rollback and recovery +- Clear handling of administrator privileges +- Unsafe APK warnings +- Log redaction +- Consent before uploading diagnostics +- No automatic upload of sensitive logs +- Offline operation where practical +- Enterprise telemetry controls +- No mandatory advertisements or behavioural profiling + +A complete threat model will be developed during runtime feasibility work. + +--- + +## Licensing and Proprietary Components + +WinDroid Runtime is an independent project and will not redistribute proprietary components without appropriate legal rights. + +This includes, but is not limited to: + +- Microsoft WSA components +- Google Play Store +- Google Mobile Services +- Amazon Appstore components +- Proprietary Android system images +- Proprietary drivers or firmware +- Third-party anti-cheat components +- Store or service credentials + +The project may support APK sideloading and open-source application distribution methods where legally permitted. + +Official Google Play Store or Google Mobile Services integration is not included and will not be bundled unless all applicable permission, licensing, and certification requirements are satisfied. + +--- + ## Current Solution Structure -The initial multi-project solution has been scaffolded. This is foundational -structure only — it establishes the planned architecture and builds cleanly, but -no ADB functionality, Android runtime, or virtualization backend exists yet. +The initial multi-project solution has been scaffolded. ```text WinDroid-Runtime/ ├── src/ -│ ├── WinDroid.Studio/ # WinUI 3 desktop app (unpackaged), minimal window -│ ├── WinDroid.Core/ # Class library (empty foundation) -│ ├── WinDroid.Adb/ # Class library (empty foundation, references Core) -│ └── WinDroid.Engine/ # Class library (empty architectural boundary) +│ ├── WinDroid.Studio/ # WinUI 3 desktop application +│ ├── WinDroid.Core/ # Shared class library +│ ├── WinDroid.Adb/ # ADB class library, references Core +│ └── WinDroid.Engine/ # Isolated runtime-engine boundary │ -├── tests/ # Reserved for future test projects -├── Directory.Build.props # Shared build settings -├── WinDroid.Runtime.slnx # Solution (XML format) +├── tests/ +├── docs/ +├── Directory.Build.props +├── WinDroid.Runtime.slnx ├── README.md ├── LICENSE +├── CONTRIBUTING.md +├── SECURITY.md └── .gitignore ``` @@ -238,17 +585,21 @@ WinDroid.Core -> (no project references) WinDroid.Engine -> (isolated) ``` -### Building +--- + +## Building -Prerequisites (verified with the toolchain used to scaffold this solution): +Prerequisites: - Windows 11 -- .NET SDK 10.0.x (the class libraries target `net8.0`; the app targets - `net8.0-windows10.0.19041.0`) -- Windows App SDK 2.2.0 (restored automatically via NuGet) -- Visual Studio 2026 (or 2022) with the **Windows App SDK C#** / - **.NET Desktop Development** workload and a Windows 10/11 SDK. This workload - may be required to open, build, and run `WinDroid.Studio` (WinUI 3). +- .NET SDK 10.0.x +- Windows App SDK 2.2.0, restored through NuGet +- Visual Studio 2026 or 2022 with: + - Windows App SDK C# + - .NET Desktop Development + - A Windows 10 or Windows 11 SDK + +The class libraries currently target `net8.0`. The application targets `net8.0-windows10.0.19041.0`. Build from the repository root: @@ -260,9 +611,11 @@ dotnet build .\WinDroid.Runtime.slnx --configuration Release --no-restore The solution can also be opened and built directly in Visual Studio. +--- + ## Technology Stack -The planned first-stage stack: +Current stack: - **Language:** C# - **Framework:** .NET @@ -280,16 +633,23 @@ Long-term research may involve: - Hyper-V - Windows Hypervisor Platform - VirtIO -- Graphics/input/audio bridge systems +- Graphics translation +- Input and audio bridges +- Virtualisation and container technologies + +No specific long-term backend is considered final until feasibility research is complete. + +--- ## What This Project Is WinDroid Runtime is: - An independent open-source project -- A Windows-focused Android compatibility/runtime research project +- A Windows-focused Android compatibility and runtime research project - A developer toolkit for Android-on-Windows workflows -- A long-term attempt to explore native-feeling Android app support on Windows +- A long-term platform vision with specialised developer, desktop, and gaming experiences +- A project that intends to validate feasibility and user value incrementally ## What This Project Is Not @@ -297,16 +657,18 @@ WinDroid Runtime is not: - A fork of Microsoft WSA - An official or unofficial continuation of Microsoft WSA -- A Microsoft product -- A Google product -- An Amazon product -- A repackaged emulator +- A Microsoft, Google, or Amazon product - A redistribution of proprietary WSA binaries -- A project that bundles Google Play Store or Google Play Services without proper permission +- A promise that all Android applications or games will work +- A promise of universal anti-cheat compatibility +- A project that currently provides a production-ready Android runtime +- A project that bundles Google Play Store or Google Play Services without permission + +--- ## Legal and Trademark Notice -WinDroid Runtime is not affiliated with, endorsed by, sponsored by, or connected to Microsoft, Google, Amazon, or any related organization. +WinDroid Runtime is not affiliated with, endorsed by, sponsored by, or connected to Microsoft, Google, Amazon, or any related organisation. Windows, Android, Google Play, Amazon Appstore, Microsoft, Google, Amazon, and related names, logos, and trademarks are the property of their respective owners. @@ -314,31 +676,40 @@ This project does not use Microsoft WSA binaries, Microsoft branding, Google Pla For the complete project policy, see [Legal, Licensing, and Trademark Boundaries](docs/legal-notes.md). -## App Store and Google Play Notice - -The project may support APK sideloading and open-source app distribution methods in future versions. - -Official Google Play Store or Google Mobile Services integration is not included and will not be bundled unless proper legal permission, licensing, or certification requirements are satisfied. +--- ## Contributing -This project is currently in the early planning and research stage. +WinDroid Runtime is an early-stage open-source project. -Contributors, mentors, and developers interested in the following areas are welcome: +Contributors, mentors, researchers, and developers interested in the following areas are welcome: -- C# / .NET development -- WinUI 3 desktop application development +- C# and .NET +- WinUI 3 - Android Debug Bridge tooling +- Automated testing and CI - Android internals - AOSP -- Virtualization -- Hyper-V / Windows Hypervisor Platform +- Virtualisation +- Hyper-V and Windows Hypervisor Platform - QEMU - Graphics and input systems -- Open-source project architecture - Security and sandboxing +- Performance measurement +- Compatibility testing +- Technical documentation + +Before starting work: + +1. Read the complete issue and its dependencies. +2. Comment that you would like to work on it. +3. Wait for a maintainer to assign it. +4. Keep the pull request focused. +5. Link the pull request to the issue. + +See [CONTRIBUTING.md](CONTRIBUTING.md) for the complete contribution process. -Contribution guidelines will be added as the project structure becomes more stable. +--- ## Community and Support @@ -354,18 +725,23 @@ For official project work: For private security reports, follow the [security policy](SECURITY.md) or contact [security@novasystemslab.org](mailto:security@novasystemslab.org). +--- + ## Current First Milestone -The first practical milestone is to build WinDroid Studio v0.1, a native Windows application that can: +The first practical milestone is to build the developer-tooling foundation in WinDroid Studio. + +Near-term capabilities include: -- Detect ADB -- List connected Android devices or emulators +- Detect and configure ADB +- List connected Android devices and emulators - Display device information - Install APK files -- Launch installed apps -- View basic logs +- List, launch, and uninstall installed applications +- View command output and basic logs +- Use initial diagnostic tools -This milestone will create the foundation for deeper runtime work later. +This milestone creates the management and developer-tooling foundation for deeper runtime work later. --- @@ -379,7 +755,7 @@ This milestone will create the foundation for deeper runtime work later. >

-WinDroid Runtime is developed under **Nova Systems Lab**, an independent open-source organization focused on systems software, developer tools, platform integration, and experimental runtime technologies. +WinDroid Runtime is developed under **Nova Systems Lab**, an independent open-source organisation focused on systems software, developer tools, platform integration, and experimental runtime technologies. --- @@ -387,4 +763,4 @@ WinDroid Runtime is developed under **Nova Systems Lab**, an independent open-so This project is licensed under the Apache License 2.0. -See the LICENSE file for details. +See the [LICENSE](LICENSE) file for details. \ No newline at end of file