Implement Rust-owned Android local and HTTPS onboarding (#95)

docs/android/onboarding.md

@@ -0,0 +1,69 @@
+# Android onboarding (#95)
+
+Compose collects inputs and renders the typed Rust setup state. `NativePrivateSession`
+shares one private runtime and Android Keystore callback between the shell and setup.
+Blocking calls and progress polling run on IO workers. Internet access is allowed;
+cleartext connections remain disabled. The storage API rejects every non-HTTPS
+onboarding endpoint and credential-bearing URL before opening transport.
+
+Native loading initializes Rust's Android platform certificate verifier with the
+application Context before HTTPS can run. Its official JVM support comes from the
+checksum-pinned Cargo component, is verified and locked by Gradle, and is retained
+by Release shrinking. Certificate validation uses the operating system trust store.
+
+Local setup generates or imports a private GPG key, verifies its passphrase, creates
+Git and the upstream `.gpg-id`, and commits the configuration. No server, camera,
+or biometric permission is needed. Encrypted prepared keys survive process death;
+passphrases and tokens remain in memory only. Form secrets survive rotation through
+a ViewModel and are excluded from saved-state Bundles. After process death transport
+and passphrase inputs must be entered again.
+
+HTTPS setup discovers branches with a temporary Rust repository, selects the branch,
+and checks the selected private key against the cloned root recipient policy. Reusing
+an existing clone requires the same authoritative origin and current branch and
+preserves its contents. Adding a remote to a local store validates network/TLS/token
+access before saving anything, and accepts an authenticated empty remote.
+
+Setup serializes against the private runtime lock. Its private transaction journal
+contains only paths, credential identities and an ownership identifier. Replacement
+vault/key directories are synced before installation; the configuration is the commit
+point. Recovery restores previous directories and removes only a newly created origin
+and a credential matching the protected ownership record. Missing or corrupt journals
+with backups retain those backups and report recovery. Cancellation before the commit
+boundary discards staging; once installation starts, the transaction finishes or rolls
+back. Existing data and credentials are never replaced by initial setup.
+
+Tokens and the temporary credential ownership record use the injected Android
+Keystore backend. Explicit token replacement preserves the configured identities and
+never returns the previous token to Kotlin. Neither Git URLs nor configuration files
+contain credentials. No live repository is opened through SAF and no application
+component launches a subprocess.
+
+Rust regression fixtures cover pass-compatible encrypted entries, process restart,
+authentication/TLS/network/cancellation failures, mismatched recipients, existing
+clones/remotes/tokens, protected-store failure, interrupted installation, credential
+ownership and low-storage recovery. Emulator tests exercise the generated native API
+and staged Compose forms; runtime and packaging checks use the three documented ARM
+emulator configurations. Real private-server access still depends on supplied account
+credentials; synthetic fixtures establish failure and rollback contracts independently.
+
+## Validation (2026-10-09)
+
+The required Rust formatting, warnings-as-errors workspace check, Clippy and all
+workspace tests passed (459 tests). Android verification passed lint, JVM tests,
+Kotlin formatting, module boundaries, both ARM ABI builds, Debug/Release APK and
+Release AAB audits, 16 KB alignment, UniFFI parity, backup/manifest checks and
+dependency/license inventories. Instrumentation and five cold starts passed on
+ARM64 API 26/4 KB, API 37/4 KB and API 37/strict 16 KB emulators. ARMv7 was
+built and audited; a compatible ARMv7 emulator image was not available.
+
+Computer use verified blank generation rejection, manual import availability,
+key selection and masked passphrase retention through rotation, successful
+encrypted local-store creation, and the optional HTTPS action in Preferences.
+The user entered the disposable GPG passphrase directly into the emulator.
+No private-server credential was requested or used for this validation; native
+transport fixtures cover clone success, token replacement and rollback boundaries.
+An opt-in native integration test also fetched branches from the public
+`octocat/Hello-World` HTTPS repository, connected an isolated local store and replaced
+its synthetic token on all three emulators. Run that test with instrumentation
+argument `ironstorage_https_integration=true`; routine CI remains network independent.