locqr/mobile/claude.md

# Mobile Companion App

The companion is the credential store and the mobile half of the LOCQR run.
It holds all user credentials at rest, performs the mobile side of the
cryptographic key exchange, authenticates the user via biometric or device PIN
before each delivery, and sends the encrypted credential to the backend relay.

The companion exists in two implementations: a **web stub** used during
development, and the **native app** that is the production target.

---

## Web stub (development tool)

The web stub is a single-page web application that implements the full
cryptographic protocol without the security properties of the native app. Its
purpose is to allow end-to-end development and testing of the extension without
requiring a native build.

**What it does:**
- Scans QR codes via the browser `MediaDevices` camera API
- Performs all crypto operations in full (X25519, ML-KEM-768, HKDF, AES-256-GCM)
  using WebCrypto and a WASM ML-KEM library
- Derives and displays the PIN
- Delivers a credential — either a hardcoded payload or any credential entered
  or received during the current browser session
- Communicates with the backend relay over HTTPS

**What it deliberately omits:**
- No persistent credential storage
- No biometric or device PIN gate (replaced by a simple button)
- No hardware-backed key storage
- No platform security guarantees

The stub is a first-class development artifact. It should be maintained
alongside the extension so that the full run can always be exercised
in a browser.

The visual design specified in `gui.md` does not apply to the stub. Adhere to
it only where doing so costs nothing — the stub's purpose is functional
correctness, not UI fidelity.

---

## Native app

Visual design, screen layouts, and interaction details for the native app are
specified in `gui.md`.

### Platform

Android-first, written in Kotlin. iOS is deferred.

| Concern | Android |
|---|---|
| Credential encryption key | Android Keystore (hardware-backed where available) |
| Biometric auth | `BiometricPrompt` API |
| QR scanning | ML Kit Barcode Scanning |
| Compile-time constants | `BuildConfig` fields set at build time |

### Compile-time constants

| Constant | Algorithm | Purpose |
|---|---|---|
| `ED25519_PUBKEY` | Ed25519 | Verifies signed tokens from backend |

Pinned at build time. Any signed token that does not verify against this key
is rejected before any other processing occurs.

---

## State model

The companion's run flow is linear. There is at most one active run at a time.

The companion's home screen is freely accessible without authentication, following
the pattern of transaction-gated apps (e.g. PayPal). Biometric or device PIN is
required at the point the user initiates a run — when they tap "Scan QR" —
before the camera opens. The vault remains unlocked for the duration of the run.
Lock policy after run completion (immediate re-lock vs. timeout window) is a
deferred UX decision.

### States

- `idle` — home screen; freely accessible; no active run.
- `authenticating` — biometric or device PIN prompt active; triggered by tapping
  "Scan QR."
- `scanning` — authentication passed; vault unlocked; camera active.
- `verifying` — QR parsed; running: Ed25519 signature check, TTL check, backend
  bundle fetch, alpha_hash recomputation.
- `key_exchange` — verification passed; performing X25519 key agreement and
  ML-KEM-768 encapsulation; sending `kem_ciphertext` to backend relay.
- `pin_display` — run key derived; PIN displayed to user. User reads
  the PIN, confirms the match on the extension, then taps Continue on the
  companion to advance. The companion does not receive a signal from the
  extension; the two devices proceed independently from this point.
- `credential_select` — credentials for the current site presented; vault
  already unlocked from biometric at session initiation. If exactly one
  credential is stored for the site it may be pre-selected. If multiple are
  stored the user must choose.
- `delivering` — credential selected; encrypted with AES-256-GCM under the
  run key; ciphertext sent to backend relay.
- `complete` — ciphertext sent; run key discarded; brief confirmation shown;
  returns to `idle`.
- `error` — run failed at any phase; reason and class held for display.

### Transitions

```
idle
  → authenticating            (user taps "Scan QR")

authenticating
  → scanning                  (biometric or PIN accepted; vault unlocked)
  → idle                      (auth failed or user cancels)

scanning
  → verifying                 (QR code parsed)
  → idle                      (user cancels)

verifying
  → key_exchange              (all checks pass)
  → error/ttl_expired         (TTL in QR token has passed)
  → error/signature_invalid   (security: Ed25519 signature fails)
  → error/alpha_hash_mismatch (security: key bundle does not match QR commitment)
  → error/bundle_consumed     (security: backend reports bundle already fetched)
  → error/backend_unreachable (network: cannot fetch key bundle)
  → idle                      (user cancels)

key_exchange
  → pin_display               (kem_ciphertext sent; run key derived)
  → error/relay_error         (network: cannot send kem_ciphertext)

pin_display
  → credential_select         (user taps Continue)
  → idle                      (user cancels; run key discarded)

credential_select
  → delivering                (user selects credential)
  → idle                      (user cancels; run key discarded)

delivering
  → complete                  (ciphertext sent to relay)
  → error/relay_error         (network: relay unreachable or error)

complete
  → idle                      (automatic after brief display)

error
  → authenticating            (user retries; security-class errors do not offer retry)
  → idle                      (user dismisses)
```

### Error classes

*Security-class* (companion notifies backend; user sees explicit security
warning; no retry offered):
- `signature_invalid` — Ed25519 signature on the QR token does not verify
  against the pinned `ED25519_PUBKEY`.
- `alpha_hash_mismatch` — key bundle fetched from backend does not match the
  commitment in the QR. Indicates tampering between the extension and backend.
- `bundle_consumed` — backend reports the bundle was already fetched before the
  legitimate companion reached it. Possible QR hijack.

*Timeout / user class* (expected; retry offered):
- `ttl_expired` — the TTL in the signed token had already passed when the
  companion scanned.
- `user_abort` — user cancelled at any phase.

*Network class* (transient; retry offered):
- `backend_unreachable` — key bundle fetch failed.
- `relay_error` — could not send `kem_ciphertext` or credential ciphertext.

---

## Credential storage

Credentials are the companion's primary data. The companion is the only entity
in the system that holds them; there is no server-side copy.

### Structure

Credentials are stored per domain. Each domain maps to an ordered list of
credential entries. A credential entry holds at minimum a label, a username,
and a password. TOTP secrets are a planned addition (deferred; see
`../flows.md`).

### Encryption at rest

The credential store is encrypted under a key held in the platform secure
enclave (Android Keystore). The key never leaves the enclave; all encrypt and
decrypt operations are performed in hardware. The encrypted store can be backed
up to user-controlled storage without exposing credentials — the backup is
useless without the enclave key, which does not travel with it.

Backup and restore, device-to-device transfer, and multiple-device sync are
deferred. See `../flows.md` — *Companion loss, replacement, and recovery*.

---

## Cryptographic responsibilities

- **QR verification:** Ed25519 signature check against pinned `ED25519_PUBKEY`;
  TTL check; recomputation of `alpha_hash` from the fetched key bundle.
- **Key exchange:** X25519 key agreement against the extension's public key;
  ML-KEM-768 encapsulation against the extension's ML-KEM-768 public key →
  `kem_ciphertext` and `kem_shared_secret`.
- **Session key derivation:**
  `HKDF-SHA256(x25519_shared || kem_shared_secret, salt=runId_utf8, info="locqr-run-key-v1", length=32)` —
  classical value precedes post-quantum per the normative ordering rule in `../crypto.md`.
- **PIN derivation:** `HKDF-SHA256(run_key, salt=[], info="locqr-pin-v1",
  length=4)`, displayed as a zero-padded six-digit decimal.
- **Payload encryption:** AES-256-GCM with a fresh nonce; exactly one
  encryption per run key.

All algorithm parameters and normative ordering rules are in `../crypto.md`.

---

## Backend API surface

- Fetch key bundle by run ID (at-most-once; bundle destroyed on fetch).
- Send `kem_ciphertext` to relay addressed to run ID (Phase 2).
- Send encrypted credential ciphertext to relay addressed to run ID (Phase 4).
- Report security-class errors to `/security/report`.

Request/response schemas are in `../interfaces.md`. Endpoint behaviour is in
`../server/claude.md`.

---

## Security invariants

- The run key is never written to persistent storage. It is discarded
  immediately on `complete` or on any transition to `idle` or `error`.
- Biometric or device PIN authentication is required to initiate a run
  (before the camera opens). The vault remains unlocked for the run duration.
  Authentication is not re-requested mid-run.
- Any signed token that does not verify against the pinned `ED25519_PUBKEY` is
  rejected before any network call is made.
- The companion does not proceed past `verifying` if the alpha_hash recomputed
  from the fetched key bundle does not match the value in the QR token.
- Security-class errors are reported to the backend. No retry is offered.
- The companion operates anonymously with respect to the backend. It holds no
  registered identity and requires no user account.