work in progress

This commit is contained in:
2026-08-16 22:00:08 +02:00
parent a914ef1ec4
commit 3c11a88a33
60 changed files with 4487 additions and 41 deletions
+29 -5
View File
@@ -90,10 +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, 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.
- `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.
- `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
@@ -132,7 +143,13 @@ key_exchange
→ error/relay_error (network: cannot send kem_ciphertext)
pin_display
→ credential_select (user taps Continue)
→ awaiting_confirmation (user taps Continue)
→ idle (user cancels; run key discarded)
awaiting_confirmation
→ credential_select (extension's confirmation received)
→ error/confirmation_timeout (bounded wait elapses with no confirmation —
network class, retry offered)
→ idle (user cancels; run key discarded)
credential_select
@@ -170,6 +187,11 @@ warning; no retry offered):
*Network class* (transient; retry offered):
- `backend_unreachable` — key bundle fetch failed.
- `relay_error` — could not send `kem_ciphertext` or credential ciphertext.
- `confirmation_timeout` — polled for the extension's PIN confirmation
past a bounded wait with no response. Not security-class: the absence of
a signal isn't evidence of tampering, just that the other side hasn't
(yet, or ever) clicked Confirm — could be an inattentive user, a closed
tab, or a genuine network issue.
---
@@ -221,6 +243,8 @@ 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).
- Send encrypted credential ciphertext to relay addressed to run ID (Phase 4).
- Report security-class errors to `/security/report`.