rasmus/locqr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ee1b7e1667
locqr/flows.md

19 KiB
Raw Blame History

Flows

This document describes the individual sequences that make up system operation. Each flow names its actors, lists the steps in order, and identifies the points at which the flow can fail. Cryptographic primitives and algorithm rationale are in crypto.md. Wire formats and message schemas for all cross-component communication are in interfaces.md. The overall architecture and trust model are in claude.md.

Steps are labelled with the actor that performs them. A step may produce output consumed by a later step in the same flow; those dependencies are noted inline.

Domain registration

A website owner registers their domain with the backend before any user session can take place. The registration produces a signed certificate that the extension verifies on each page load.

Actors: Website admin, Backend server

Precondition: Website admin has a backend account.

  1. [Admin] Submits domain URL and any account metadata to the backend via the account management interface.
  2. [Backend] Validates account status and that the domain is not already registered to a different account.
  3. [Backend] Issues a registration certificate: { domain, issued_at, expires_at } signed with ML-DSA-44.
  4. [Backend] Returns the certificate to the admin.
  5. [Admin] Supplies the certificate to the SDK initialisation call in the website code (locqr.init({ cert: '...' })). The SDK forwards it to the extension at connect time. The underlying delivery path is different from serving a static asset, but the effect is the same: the cert travels from the backend to the extension via the website operator.

Success: Certificate is present on the domain, verifiable against BACKEND_PUBLIC_KEY_B64.

Failure — account invalid or domain conflict: Backend rejects at step 2; admin must resolve before retrying.

Failure — certificate expired: Extension detects expiry on the next page load. Admin must renew through the account interface (steps 1–5 with a new expiry).

Site verification

The extension checks every page against the backend's registration records. This check runs when the SDK connects, independently of any user action or login request. Its outcome determines the extension's UI state for that page.

Actors: SDK, Extension, Backend

Precondition: None. The check runs on every SDK connection regardless of whether a session will be initiated.

  1. [SDK] On page load, opens a Port to the extension via externally_connectable, sending the registration certificate (supplied to the SDK at initialisation by the website developer).
  2. [Extension] Receives the cert and reads the real page origin from sender.tab.url (browser-provided; cannot be spoofed by the page). Rejects immediately with insecure_origin if the scheme is not https:.
  3. [Extension] Verifies the ML-DSA-44 signature locally against its pinned BACKEND_PUBLIC_KEY_B64, checks the issued_at and expires_at fields, and confirms the cert's domain matches the origin hostname.
  4. [Extension] Requests the backend to confirm the account associated with the domain is in good standing.
  5. [Backend] Checks account status and responds.
  6. [Extension] Responds to the SDK via the Port with the verification outcome and, on success, the feature set authorised for this site.

Outcome — no certificate supplied: SDK connected without a cert, or cert field is empty. Extension responds with not_registered; SDK stays dormant.

Outcome — local cert error (signature mismatch): Certificate is present but does not verify against the pinned key. Extension marks the site as invalid and shows no LOCQR UI. This should not occur for a legitimately registered site.

Outcome — cert expired: expires_at is in the past. Extension shows an error state; session initiation is blocked until the admin renews.

Outcome — cert not yet valid: issued_at is in the future. Treated as invalid. Extension shows no LOCQR UI.

Outcome — remote error (backend cannot verify): Backend cannot confirm the account — account may be suspended, deactivated, or the backend is unreachable. Extension shows an error state; session initiation is blocked.

Outcome — valid: Signature is correct, certificate is within its validity period, and the account is confirmed in good standing. Extension activates its LOCQR UI for this site. Session initiation becomes available.

LOCQR Run

A run transfers one credential from the companion app to the browser extension, where it is delivered to the current website via the JS SDK. A run has four phases: initiation, scan, key confirmation, and credential delivery. The phases execute sequentially with no overlap.

Actors: User, Website, Extension, Backend, Companion

Precondition: The extension has completed site verification for the current page with a valid outcome. The companion app holds the credential the user intends to transfer. The user is physically present with both devices.

The companion's home screen is accessible without authentication. Biometric or device PIN is required at the point the user initiates a run (taps "Scan QR"), before the camera opens. This gates the entire run rather than a specific phase. The vault remains unlocked for the duration of the run; lock policy after run completion is a companion-internal concern.

Phase 1 — Initiation

  1. [Website] Signals to the extension (via JS SDK) that a login field is active and a credential is needed.
  2. [Extension] Generates ephemeral keypairs: one X25519 and one ML-KEM-768.
  3. [Extension] Computes alpha_hash = SHA-256(x25519_pub_bytes || kem_pub_bytes) (classical bytes precede post-quantum bytes per the normative ordering rule in crypto.md).
  4. [Extension] Generates a run ID and uploads the full key bundle (both public keys) to the backend, along with the run ID and the domain from the verified registration certificate. The server determines all TTL values.
  5. [Backend] Stores the key bundle. Signs { alpha_hash, url, runId, expires_at } with its Ed25519 key → signed token. Returns the signed token together with server-controlled session parameters (qr_ttl, max_auto_refresh, pin_ttl).
  6. [Extension] Receives the signed token and session parameters.
  7. [Extension] Constructs the QR payload from the signed token and displays the QR code.

The extension's ephemeral private keys never leave the extension. The QR carries the commitment (alpha_hash) and the backend's signature, not the keys themselves.

Failure — backend unreachable: Extension cannot store bundle or receive signed token; session does not start.

Phase 2 — Scan

  1. [User] Taps "Scan QR" on the companion. The companion prompts for biometric or device PIN. On success the vault is unlocked and the camera opens. The user scans the QR code.
  2. [Companion] Parses the QR payload and verifies the Ed25519 signature against its pinned ED25519_PUBKEY. Aborts if verification fails.
  3. [Companion] Checks that the TTL has not expired. Aborts if the session window has passed.
  4. [Companion] Fetches the key bundle from the backend using the run ID. The backend destroys the bundle on this fetch (at-most-once delivery).
  5. [Companion] Recomputes alpha_hash from the received keys and compares it to the value from the QR. Aborts if they do not match.
  6. [Companion] Generates its own ephemeral X25519 keypair. Performs X25519 key agreement using its ephemeral private key and the extension's X25519 public key → x25519_shared.
  7. [Companion] Performs ML-KEM-768 encapsulation against the extension's ML-KEM-768 public key → (kem_ciphertext, kem_shared_secret).
  8. [Companion] Derives the run key: run_key = HKDF-SHA256(x25519_shared || kem_shared_secret, salt=runId_utf8, info="locqr-run-key-v1", length=32).
  9. [Companion] Sends the companion's ephemeral X25519 public key and kem_ciphertext to the extension via the backend relay. These are framed as a single kem_ciphertext relay message; see ../interfaces.md for the fixed-offset framing.
  10. [Extension] Performs ML-KEM-768 decapsulation using its private key → kem_shared_secret. Performs X25519 key agreement → x25519_shared.
  11. [Extension] Derives the run key by the same HKDF construction. Both sides now independently hold the same run key.

Failure — TTL expired: Companion detects expiry at step 10 and displays an expiry message. If the extension still has auto-refreshes remaining it will have already replaced the QR; the user should scan the current code. If max_auto_refresh is exhausted the extension has entered session_error / ttl_exhausted and the user must trigger a full restart from Phase 1.

Failure — bundle already consumed: Backend returns a 404 at step 11. This means either the bundle was already fetched (possible QR hijack) or the run expired server-side. Companion aborts, enters error/bundle_consumed (security-class), and reports to /security/report. The legitimate user is protected: the attacker cannot complete the run without the extension's private keys. The extension receives no notification of this event; it simply times out on qr_ttl expiry and enters run_error/ttl_exhausted. See the design note in extension/claude.md for what adding an explicit extension signal would require.

Failure — alpha_hash mismatch: Companion aborts at step 12. The key bundle received from the backend does not match the commitment in the QR. This indicates tampering between extension and backend.

Failure — signature verification failure: Companion aborts at step 9 if the Ed25519 signature does not verify, or if the URL in the signed token does not match the URL the extension reported.

Phase 3 — Key confirmation

  1. [Companion] Derives the PIN from the run key: pin_bytes = HKDF-SHA256(run_key, salt=[], info="locqr-pin-v1", length=4). pin_string = (pin_bytes as uint32 big-endian % 1_000_000), zero-padded to six digits.
  2. [Extension] Derives the same PIN by the same construction and displays it.
  3. [User] Reads the PIN displayed on the companion and confirms the match on the extension.

The confirmation must happen on the extension. This is the point of the PIN: it proves to the extension that the user at the browser is in possession of the companion that completed the key exchange. Confirming elsewhere provides no protection. The extension does not proceed to Phase 4 until the user explicitly confirms.

The PIN does not prevent a race between a legitimate user and a QR hijacker: the at-most-once bundle delivery at step 11 is the load-bearing control against that attack.

Failure — PIN mismatch: User sees different codes on the two devices and does not confirm on the extension. This indicates the run keys differ, which should not happen if all earlier verifications passed. The extension abandons the run. Neither device must attempt to continue.

Phase 4 — Credential delivery

  1. [Companion] Presents the credentials stored for the current site (the URL is known from the signed token parsed at step 9). The vault is already unlocked from the biometric at step 8. If exactly one credential is stored for the site, it may be pre-selected. If multiple are stored, the user must choose.
  2. [User] Selects the credential to deliver.
  3. [Companion] Encrypts the credential with the run key (AES-256-GCM). A fresh nonce is generated for this encryption; one nonce is used per run.
  4. [Companion] Sends the ciphertext to the backend relay, addressed to the run ID.
  5. [Backend] Forwards the ciphertext to the extension. The backend cannot decrypt it.
  6. [Extension] Decrypts the ciphertext using the run key and verifies the GCM authentication tag. If authentication fails, the payload is discarded.
  7. [Extension] Delivers the credential to the website via the JS SDK — resolving the requestCredential() Promise and firing a run:delivered event with the credential payload.

Success: Credential is in the website's login form. The run key is discarded by both extension and companion; no future use is possible.

Failure — decryption or authentication failure: Extension discards the payload at step 27. This should not occur under normal operation; if it does, it indicates a relay integrity failure. User must restart the session.

Credential provisioning

Before a run can deliver a credential, the credential must exist in the companion. There are four provisioning paths.

Manual entry. The user types the credential directly into the companion app. Companion-internal; no cross-entity protocol required.

File import. The user imports credentials from a file on the device (e.g. a password manager export). Companion-internal; no cross-entity protocol required. File format and parsing are deferred.

Website-commanded storage. The website initiates a store operation, sending a credential to the companion for safekeeping. This is the reverse of the run's delivery flow: the website sends encrypted data through the extension to the companion over an established run channel. This path requires its own flow; deferred.

Format-guided generation. The companion generates a credential locally according to a format specification supplied by the website or the extension. This is primarily intended for GYBBR, where credential structure is known, but the generation interface may be generalised to arbitrary format descriptions for other services. The format spec travels from website to extension to companion before or during run initiation; the companion generates the credential locally and never transmits it in cleartext. This path requires its own flow; deferred.

The two companion-internal paths (manual entry, file import) produce a credential that is then available as a run precondition. The two cross-entity paths (website-commanded storage, format-guided generation) reuse the run infrastructure and will reference the run flow.

TOTP / classical 2FA. TOTP secrets (RFC 6238) may be stored in the companion alongside passwords and delivered as part of the same run. The run-initiation biometric or PIN requirement (step 8) means that storing TOTP in the same vault does not reduce 2FA to single-factor: possession of the device and biometric or PIN are still both required. The biometric gates the entire run, not just credential delivery; the second factor is therefore enforced before any data leaves the device, regardless of how many credentials or TOTP codes are transferred. TOTP integration is deferred; the storage and delivery model is compatible with the current architecture without structural changes.

Companion loss, replacement, and recovery

All credentials are stored exclusively on the companion. There is no server-side copy. This is a deliberate security property, but it means the companion is a single point of failure for the user's credential store.

Lost or stolen device

The run-initiation biometric or PIN requirement limits the immediate risk: an attacker with a stolen device cannot trigger a run without clearing that gate. However, the user should assume credentials are at risk if the device is lost and act accordingly — changing passwords for sensitive accounts.

The current architecture has no companion revocation mechanism. The companion holds no registered identity with the backend; it operates anonymously. Introducing revocation would require companion registration, which in turn would require user accounts on the backend — breaking the anonymity of the app as it currently stands. Whether revocation is worth that cost is an open question. Until it is resolved, the run-initiation biometric or PIN is the sole protection against misuse of a stolen device.

New device

When a user replaces their device, credentials must transfer to the new companion. The transfer must happen without exposing credentials to the network in recoverable form. Options under consideration:

Encrypted backup. Credentials are encrypted under a key derived from a master passphrase chosen by the user, and stored in a location the user controls (local file, cloud storage of their choice). Restoring on a new device requires the passphrase. The backup is useless without it. This is the simplest model and places recovery entirely in the user's hands.

Device-to-device transfer. Old and new companions establish a direct encrypted channel — using a mechanism analogous to the QR-based run bootstrap — and transfer the credential store in a single operation. Requires both devices to be present simultaneously. No passphrase needed, but the window of exposure is the transfer itself.

Both options are deferred. Until a backup or transfer mechanism exists, a lost or replaced device means credentials must be re-added manually.

Multiple devices

Holding the companion on more than one device simultaneously implies keeping credential stores in sync. This introduces conflict resolution, ordering, and consistency concerns that are out of scope for the PoC. Deferred.

Error handling

The specific actions taken on error — UI state, SDK events, logging, retry behaviour — are deferred to the entity-level documentation.

Security errors. Failures such as signature verification failure, alpha_hash mismatch, and bundle already consumed are indicators of a potential active attack, not benign operational faults. These warrant a response beyond informing the user: the relevant actors should notify the backend, and the user should receive a clear security warning rather than a generic error message. The exact notification and escalation paths are deferred.

Network errors and timeouts. A run has several points where network failure produces an ambiguous result — the operation may or may not have completed on the remote side. Notable cases:

  • Backend unreachable during Phase 1: the extension cannot store the key bundle or receive a signed token. No run starts; clean failure.
  • Timeout during key bundle fetch (Phase 2, step 11): the companion does not know whether the backend destroyed the bundle before the connection dropped. The run must be abandoned; the user must restart. The extension should proactively expire and discard the bundle on its side.
  • Connection lost during ciphertext relay (Phase 4): the extension cannot distinguish a lost connection from a delayed delivery. It should not attempt to re-use the run key for a retry; the run must be restarted from Phase 1. Network errors are never treated as security events. They do not trigger attack notifications. They require clear user-facing messages and, where safe, an offer to retry from Phase 1.