feat: add first-run setup wizard

2026-07-24 18:15:30 +00:00
parent 3b883bd534
commit 5b3263ef14
17 changed files with 2831 additions and 103 deletions
@@ -10,6 +10,8 @@ Required unblock evidence: run the required preflight and focused Android tests

 The `v0.1.0-beta.1` Android package metadata and direct-gateway build/install guide are present in source. On 2026-07-24, the required recovery preflight passed and the source-current offline Gradle `:app:testDebugUnitTest :app:assembleDebug` command passed. Installation verification cannot be completed in the current sandbox.

+The first-run Setup Wizard is also source-complete and unit/build verified, including None/Bearer/password choices and direct password-session cookie handling. No real None/Bearer/password credential flow has been exercised against a live gateway, so R2 must include the chosen authentication mode and observed connection result without recording credentials.
+
 ADB is installed, but the R1 evidence above confirms that its daemon sockets are prohibited and that no emulator executable, AVD, `/dev/kvm`, USB device bus, or running target is available. Therefore no source-current beta APK package inspection, clean uninstall/install, launch, or direct-gateway device connection was verified here. No APK was published or uploaded, and no final release criterion is claimed.

 Required unblock evidence: in a permitted environment, run the preflight and Android checks from `docs/ANDROID_BETA_BUILD.md`, record `aapt` package/version output and the APK SHA-256, clean-install on one named real device or emulator, launch the app, configure the upstream Hermes gateway directly, and record the connection result in `docs/ROADMAP.md`.
@@ -95,6 +95,20 @@ Security and reliability rules:
 - A later milestone may add opt-in mDNS/QR setup, certificate pinning/identity binding, and richer connectivity observation only after direct-gateway basics are verified.
 - The current upstream identity-binding limitation and the stronger contract needed are tracked in `docs/BLOCKERS.md`.

+## First-run setup and authentication
+
+The Android app owns one versioned setup profile. First launch shows welcome/privacy guidance and requires an explicit Remote HTTPS URL; a Local HTTPS URL is optional and represents the same logical gateway for local-first routing. A valid existing profile bypasses mandatory setup, while legacy/current valid profiles are marked migrated once without requiring credential re-entry. Settings reopens the same wizard state for later edits.
+
+Supported client authentication modes are:
+
+- **None** — probes and compatible requests carry no authorization credential.
+- **Bearer** — the token is encrypted at rest and sent only to the selected configured gateway through the existing authorization-header path.
+- **Username/password** — the client posts directly to the configured Remote gateway's `/auth/password-login`, accepts only allowlisted Hermes session-cookie names from `Set-Cookie`, encrypts the password and resulting cookie at rest, and sends only the cookie pair on subsequent authenticated checks.
+
+Raw bearer tokens, passwords, and session cookies are excluded from Compose wizard state string output, connection forms, diagnostics, and logs. Changing the remote URL or username invalidates credentials bound to the previous gateway/account; editing may retain an existing encrypted credential only while its binding remains unchanged. Login redirects are disabled, cookie values are validated against header injection, and unsuccessful login clears the prior session cookie.
+
+Setup completion is gated on the same local-first compatibility test used by connection Settings: Local is attempted first when configured, then Remote is used as fallback. This source contract has unit/build verification only; no real gateway credentials, attached Android target, clean install, or release flow has been verified.
+
 ## Android Contract Milestones

 1. Auth and connection: validate local + remote URLs, store bearer tokens securely, probe `GET /health`, use `GET /v1/models` as the first authenticated check, and make local-first fallback observable/retryable.
@@ -2,6 +2,15 @@

 ## Current Milestone: Native Android Direct Gateway Contract

+### P0 First-run Setup Wizard — completed 2026-07-24
+
+- Welcome/privacy guidance precedes configuration; Remote HTTPS is required and Local HTTPS is optional for the same logical gateway profile.
+- Authentication choices are None, Bearer token, or username/password. Password login exchanges credentials directly with the configured remote gateway and stores encrypted credentials/session state outside Compose UI models.
+- Test-and-finish uses the existing local-first route selection, requires a successful compatibility check before completion, and exposes the same profile for later Settings edits.
+- Existing valid profiles skip mandatory setup; legacy/current valid profiles receive a one-time setup-version migration without forcing re-entry.
+- Compose semantics, minimum touch targets, adaptive layout behavior, and phone/tablet/light/dark previews cover the wizard source contract.
+- Source verification passed with 104 unit tests and debug assembly. No real device, release, or real gateway credential walkthrough has been performed; those remain part of R1/R2 evidence.
+
 Status: in progress. Android foundation work is complete, and the beta path now targets a remote upstream Hermes Agent gateway/API server directly. The legacy `apps/companion` server is compatibility-only and not required for future Android releases.

 Done: