# 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.