happy path working with stub companion app

This commit is contained in:
2026-08-18 02:16:05 +02:00
parent 3c11a88a33
commit bc025d007c
41 changed files with 1512 additions and 102 deletions
+18 -21
View File
@@ -90,21 +90,21 @@ deferred UX decision.
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 and taps Continue on the companion once they've compared it.
- `awaiting_confirmation` — user has tapped Continue; polling
`GET /run/relay/:runId/confirm` (interfaces.md, "PIN confirmation") for
the extension's own confirmation, which only exists once its user has
separately clicked Confirm there. Advancing requires both: this device's
local tap and the other device's remote signal, neither one alone.
Superseded design note: an earlier version of this document had the
companion proceed the instant its own user tapped Continue, with "the
companion does not receive a signal from the extension." That turned out
to be weaker than necessary for no real benefit — Bluetooth-style
Numeric Comparison pairing has always communicated the confirmation
between devices as part of completing the handshake, and there was no
good reason for this protocol to do less. See interfaces.md's "PIN
confirmation" section for the wire-level detail.
- `pin_display` — run key derived; PIN displayed to user for comparison
against the extension's independently-derived PIN — that visual
comparison is the actual anti-MITM check, not a gate the companion enforces
itself. No local action is required or offered here: the companion polls
`GET /run/relay/:runId/confirm` (interfaces.md, "PIN confirmation")
automatically the instant the PIN is derived, and advances the moment the
extension's user clicks Confirm there — that single click is the only
human action gating the run. Design history: this document previously
described a two-way handshake (companion's own tap *and* the extension's
signal, neither sufficient alone), reasoning from Bluetooth-style Numeric
Comparison pairing. That was reverted — no benefit was found in a second,
companion-side tap once the PIN is already independently displayed and
visually checked; it was pure friction on a device that has nothing
further to decide. See interfaces.md's "PIN confirmation" section for the
wire-level detail.
- `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
@@ -143,11 +143,8 @@ key_exchange
→ error/relay_error (network: cannot send kem_ciphertext)
pin_display
→ awaiting_confirmation (user taps Continue)
→ idle (user cancels; run key discarded)
awaiting_confirmation
→ credential_select (extension's confirmation received)
→ credential_select (extension's confirmation received — polled
automatically, no local action)
→ error/confirmation_timeout (bounded wait elapses with no confirmation —
network class, retry offered)
→ idle (user cancels; run key discarded)
@@ -244,7 +241,7 @@ All algorithm parameters and normative ordering rules are in `../crypto.md`.
- Fetch key bundle by run ID (at-most-once; bundle destroyed on fetch).
- Send `kem_ciphertext` to relay addressed to run ID (Phase 2).
- Poll for the extension's PIN confirmation, addressed to run ID
(`awaiting_confirmation`, above).
(`pin_display`, above).
- Send encrypted credential ciphertext to relay addressed to run ID (Phase 4).
- Report security-class errors to `/security/report`.