440 lines
22 KiB
Markdown
440 lines
22 KiB
Markdown
# Browser Extension
|
||
|
||
The extension is the central hub of the LOCQR system. It interacts with websites
|
||
through the JS SDK, communicates with the backend server directly and as a relay
|
||
to the companion, and presents its own UI outside of the website's DOM. For GYBBR
|
||
it additionally acts as an isolated cryptographic vault (see below).
|
||
|
||
## Tech stack
|
||
|
||
- Manifest V3
|
||
- TypeScript
|
||
- Background: service worker
|
||
- Persistent session state: `chrome.storage.session` (survives service worker
|
||
suspension, cleared on browser close)
|
||
- External messaging: `externally_connectable` — declared in manifest; allows
|
||
the JS SDK (running in the page context) to open a Port directly to the
|
||
service worker without a content script
|
||
- Compiled-in key constants: `BACKEND_PUBLIC_KEY_B64` (ML-DSA-44),
|
||
`ED25519_PUBLIC_KEY_B64` (Ed25519)
|
||
|
||
## Internal components
|
||
|
||
### Background service worker
|
||
|
||
Owns all cryptographic operations, run state, backend communication, and
|
||
site verification logic. It is the only context that ever holds private key
|
||
material. It has no access to the website DOM and cannot be reached by website
|
||
scripts.
|
||
|
||
The service worker may be suspended by the browser at any time. In-memory state
|
||
that must survive suspension is stored in `chrome.storage.session` before the
|
||
worker yields. In-memory state that must not survive (e.g. LOCQR run keys)
|
||
is left in memory only and intentionally discarded on suspension.
|
||
|
||
### Popup UI
|
||
|
||
Rendered in the extension's own window, outside the website's display boundaries.
|
||
This physical separation is a deliberate security property: a phishing or
|
||
look-alike site cannot replicate or overlay the extension popup.
|
||
|
||
The popup can always be opened regardless of the current tab state. It always
|
||
shows at minimum the current state. What it displays and which interactions it
|
||
offers are fully determined by the per-tab state machine defined below. Visual
|
||
design, layout, icon assets, and animation details are specified in `gui.md`.
|
||
|
||
### External messaging
|
||
|
||
The SDK communicates with the service worker directly via `externally_connectable`
|
||
— no content script is required. The SDK opens a long-lived Port to the
|
||
extension; the service worker receives the Port connection, reads the real page
|
||
URL from `sender.tab.url` (browser-provided, cannot be spoofed), and
|
||
communicates bidirectionally through the Port for the lifetime of the run.
|
||
|
||
## State model
|
||
|
||
State is per-tab. Every tab runs its own independent instance of the state
|
||
machine. The popup reflects the state of the currently active tab.
|
||
|
||
### States
|
||
|
||
**Verification states**
|
||
|
||
- `unverified` — initial state on every page load; cert check not yet complete.
|
||
- `not_registered` — SDK connected without supplying a certificate.
|
||
- `cert_invalid` — certificate present but fails local verification. Sub-reasons
|
||
determine the security classification and user-facing response:
|
||
|
||
*Security-class* (possible attack; extension notifies backend; user sees an
|
||
explicit security warning, not a generic error):
|
||
- `domain_mismatch` — cert's domain field does not match the page origin. Most
|
||
likely a phishing site serving a stolen or misrouted cert. A `domain_mismatch`
|
||
where the cert's domain is itself a valid registered LOCQR domain is a
|
||
stronger attack signal than an unrecognised domain.
|
||
- `signature_invalid` — cert is parseable but signature fails against the
|
||
pinned `BACKEND_PUBLIC_KEY_B64`. Indicates a forged or tampered cert.
|
||
- `malformed` — cert cannot be parsed. May indicate garbage served
|
||
deliberately by an attacker, or a severely broken deployment.
|
||
|
||
*Operational-class* (admin error; user is informed; no backend notification):
|
||
- `insecure_origin` — page is served over HTTP. LOCQR requires HTTPS; the
|
||
extension will not activate on any non-HTTPS origin. Checked before any
|
||
other cert logic.
|
||
- `expired` — `expires_at` is in the past; admin must renew.
|
||
- `not_yet_valid` — `issued_at` is in the future; cert deployed prematurely.
|
||
|
||
- `account_error` — certificate valid locally; backend cannot confirm the
|
||
account. Sub-reasons:
|
||
- `rejected` — account is suspended or deactivated.
|
||
- `unreachable` — backend could not be reached; status unknown. Displayed
|
||
distinctly from a confirmed rejection.
|
||
- `idle` — certificate valid, account confirmed; no active run.
|
||
|
||
**Run states** (only reachable from `idle`)
|
||
|
||
- `phase_1` — ephemeral keypairs generated; key bundle uploading to backend;
|
||
awaiting signed token. On success the backend returns the signed token together
|
||
with server-controlled run parameters (see *Session parameters* below).
|
||
- `phase_2` — QR code displayed with a countdown derived from `qr_ttl`. The
|
||
extension tracks `auto_refresh_remaining`. On TTL expiry:
|
||
- If `auto_refresh_remaining > 0`: new keypairs are generated, a new key bundle
|
||
is uploaded, and a new QR is displayed automatically; counter decremented.
|
||
The old key bundle is abandoned and will expire server-side.
|
||
- If `auto_refresh_remaining == 0`: transition to `run_error / ttl_exhausted`;
|
||
user is offered a manual retry.
|
||
Awaiting companion scan and key exchange.
|
||
- `phase_3` — run key derived; PIN displayed with a countdown derived from
|
||
`pin_ttl`. Awaiting user confirmation on the popup. On TTL expiry: transition
|
||
to `run_error / pin_timeout`.
|
||
- `phase_4` — user confirmed PIN (`POST /run/relay/:runId/confirm` sent to
|
||
unlock the companion, interfaces.md's "PIN confirmation" — fire-and-forget;
|
||
this transition itself is the extension's own real local gate and doesn't
|
||
wait on that call); awaiting encrypted credential from relay.
|
||
- `delivered` — credential decrypted and handed to the JS SDK; transitions
|
||
automatically to `idle` after brief display.
|
||
- `run_error` — run failed or aborted at any phase; reason and class
|
||
held for display. Two classes currently apply to the extension:
|
||
|
||
*Timeout / user class* (expected; user offered retry):
|
||
- `ttl_exhausted` — QR auto-refreshes used up; user must manually retry.
|
||
- `pin_timeout` — user did not confirm PIN within `pin_ttl`; run abandoned.
|
||
- `user_abort` — user cancelled at any phase.
|
||
|
||
*Network class* (transient; user offered retry):
|
||
- `backend_unreachable` — backend could not be reached during Phase 1 or
|
||
Phase 4.
|
||
- `relay_timeout` — no message received from relay within expected window.
|
||
- `relay_error` — relay returned an error or malformed response.
|
||
|
||
A *Security-class* (extension notifies backend; user sees an explicit
|
||
security warning; no retry offered) also exists in the shared
|
||
`RunErrorReason` vocabulary — `gui.md`'s "Security warning — mid-run"
|
||
template is built for it — but the extension has no member of it today.
|
||
`alpha_hash_mismatch` and `pin_mismatch` were listed here in an earlier
|
||
draft; both turned out to be companion-only detections copied across by
|
||
sharing one `RunErrorReason` enum with `mobile/claude.md` (see that
|
||
file's near-identical wording) — the extension never receives a second,
|
||
independent value to compare against its own alpha_hash or PIN, so
|
||
neither is actually detectable on this side. A human comparing the two
|
||
devices' screens and declining to confirm is exactly what `user_abort`
|
||
already covers. `bundle_consumed` (see the design note below) is the one
|
||
concrete candidate for a real extension-side security-class reason, if
|
||
the server is ever extended to push it over the relay.
|
||
|
||
### Transitions
|
||
|
||
```
|
||
page load
|
||
→ unverified
|
||
→ not_registered (cert absent)
|
||
→ cert_invalid (cert present; local check fails)
|
||
→ account_error (cert valid locally; backend rejects or unreachable)
|
||
→ idle (cert valid; account confirmed)
|
||
|
||
idle
|
||
→ phase_1 (SDK login request received)
|
||
|
||
phase_1
|
||
→ phase_2 (key bundle uploaded; signed token + run
|
||
parameters received)
|
||
→ run_error/backend_unreachable (backend unreachable; upload fails)
|
||
|
||
phase_2
|
||
→ phase_3 (kem_ciphertext received via relay WebSocket;
|
||
run key derived)
|
||
→ phase_1 (auto-refresh) (qr_ttl expired; auto_refresh_remaining > 0;
|
||
old bundle abandoned)
|
||
→ run_error/ttl_exhausted (qr_ttl expired; auto_refresh_remaining == 0;
|
||
also the outcome when the companion aborted
|
||
on bundle_consumed — extension cannot
|
||
distinguish these cases)
|
||
→ run_error/relay_error (relay error)
|
||
→ run_error/user_abort (user cancels)
|
||
|
||
phase_3
|
||
→ phase_4 (user confirms PIN)
|
||
→ run_error/pin_timeout (pin_ttl expired)
|
||
→ run_error/user_abort (user rejects or cancels — the mechanism
|
||
for a PIN the user sees not matching;
|
||
see the run_error note above)
|
||
|
||
phase_4
|
||
→ delivered (credential received; GCM auth passes)
|
||
→ run_error/relay_timeout (no message within expected window)
|
||
→ run_error/relay_error (relay error or GCM auth failure)
|
||
→ run_error/user_abort (user cancels)
|
||
|
||
delivered
|
||
→ idle (automatic after brief display)
|
||
|
||
run_error
|
||
→ phase_1 (user retries; security-class errors do not offer
|
||
retry)
|
||
→ idle (user dismisses)
|
||
```
|
||
|
||
User abort at any run phase transitions to `run_error / user_abort`.
|
||
Network errors and timeouts are expected events, not failures — the user is
|
||
offered a retry without a warning. Security-class errors do not offer retry;
|
||
the user must dismiss and the error is reported to the backend.
|
||
|
||
**Design note — `bundle_consumed` not signalled to extension.** When a QR
|
||
hijacker fetches the key bundle before the legitimate companion, the companion
|
||
detects a `404`, enters `error/bundle_consumed`, and reports to
|
||
`/security/report`. The extension has no way to learn this: the bundle is
|
||
already gone, and the server has no record linking the second-fetch failure
|
||
to the extension's open WebSocket. The extension simply times out on QR TTL
|
||
expiry and enters `run_error/ttl_exhausted`. To give the extension an
|
||
immediate security-class signal, the server would need to push
|
||
`{ type: "bundle_consumed" }` over the relay WebSocket on the second-fetch
|
||
attempt — which requires a short-lived "consumed run IDs" record on the
|
||
server, separate from the deleted bundle. This is straightforward to add if
|
||
the UX distinction between "timeout" and "possible hijack" proves important.
|
||
|
||
### Run parameters
|
||
|
||
All timing values are server-controlled. The backend returns a session
|
||
parameters blob alongside the signed token at the end of Phase 1. The
|
||
extension uses these values directly and does not apply any local defaults
|
||
or overrides.
|
||
|
||
| Parameter | Governs |
|
||
|---|---|
|
||
| `qr_ttl` | How long a single QR code remains valid (Phase 2 countdown) |
|
||
| `max_auto_refresh` | How many times the QR is automatically refreshed before the user must retry manually |
|
||
| `pin_ttl` | How long the user has to confirm the PIN (Phase 3 countdown) |
|
||
|
||
Further per-phase timeouts (e.g. Phase 4 relay wait) may be added to this blob
|
||
as the design progresses.
|
||
|
||
### Navigation rules
|
||
|
||
Navigation is detected via `chrome.tabs.onUpdated`, which fires whenever a
|
||
tab's URL changes. No content script is required; the extension observes URL
|
||
transitions from the background service worker. On same-domain SPA navigation
|
||
where `onUpdated` does not fire (hash changes, History API pushState without a
|
||
full page load), the open Port from the SDK remains active — the extension
|
||
retains its state until the SDK reconnects on a new page load. This is an
|
||
acceptable risk given that a legitimate same-domain navigation produces a new
|
||
SDK Port connection, and the extension resets if a new connection arrives with
|
||
a different or absent cert.
|
||
|
||
Pages with no LOCQR SDK installed never open a Port. Those tabs remain in
|
||
`unverified` (neutral icon) indefinitely. This is the correct behaviour for
|
||
non-LOCQR pages; no timeout or fallback transition is applied.
|
||
|
||
**Cross-domain navigation** — all tab state is discarded; the tab re-enters
|
||
`unverified`. Any in-flight run (key bundle on the backend, open relay
|
||
connection) is abandoned; the key bundle expires via TTL.
|
||
|
||
**Same-domain navigation** — the certificate is re-checked on the new page:
|
||
- Cert valid and identical to the current cert → state preserved; active run
|
||
continues uninterrupted.
|
||
- Cert valid but different (e.g. renewed by admin) → active run discarded;
|
||
tab moves to `idle` under the new cert.
|
||
- Cert invalid or absent → active run discarded; tab moves to `cert_invalid`
|
||
or `not_registered`.
|
||
|
||
A cert change mid-run terminates the run because the cert is an implicit
|
||
precondition of the run's trust basis: the URL in the signed token is
|
||
legitimised by the cert that was valid when the run started.
|
||
|
||
### UI mapping
|
||
|
||
The icon is always visible in the browser toolbar. The popup can always be
|
||
opened; it always shows at minimum the current state.
|
||
|
||
| State | Icon | Popup content | Popup actions |
|
||
|---|---|---|---|
|
||
| `unverified` | neutral | Checking… | — |
|
||
| `not_registered` | inactive | Site not registered with LOCQR | — (future: register site) |
|
||
| `cert_invalid / insecure_origin` | error | LOCQR requires HTTPS | — |
|
||
| `cert_invalid` (operational) | error | Certificate error; reason shown | — |
|
||
| `cert_invalid` (security) | security warning | Security warning; specific reason | — |
|
||
| `account_error / rejected` | error | Account inactive | — |
|
||
| `account_error / unreachable` | error | Cannot reach LOCQR server | — |
|
||
| `idle` | ready | Site verified; ready | Start run |
|
||
| `phase_1` | animated | Connecting… | Abort |
|
||
| `phase_2` | animated | QR code | Abort |
|
||
| `phase_3` | animated | PIN; confirm or reject | Confirm, Abort |
|
||
| `phase_4` | animated | Waiting for credential… | Abort |
|
||
| `delivered` | success | Credential delivered | — |
|
||
| `run_error` (timeout/user) | error | Reason shown (expired, cancelled) | Retry, Dismiss |
|
||
| `run_error` (network) | error | Network error; reason shown | Retry, Dismiss |
|
||
| `run_error` (security) | security warning | Security warning; specific reason | Dismiss only |
|
||
|
||
Exact icon assets, animation details, and transition design are specified in
|
||
`gui.md`. The mapping above is a simple state → icon lookup; `gui.md` defines
|
||
what each icon looks like, whether it is static or animated, and how transitions
|
||
between icons are rendered. Security-class errors must use a visually distinct
|
||
icon from generic errors — the distinction must be obvious to a user who does
|
||
not read the popup text.
|
||
|
||
### Error escalation
|
||
|
||
Security-class errors (cert and run) are reported to the backend
|
||
immediately. The backend is the natural hub for escalation: it can aggregate
|
||
signals across users and sites, detect patterns (e.g. multiple users hitting
|
||
`domain_mismatch` for the same domain), and act as the notification path to
|
||
site owners.
|
||
|
||
Site owner notification is a required but deferred design decision. Owners
|
||
need to know about security-class errors against their domain — a surge of
|
||
`signature_invalid` or `domain_mismatch` events is actionable intelligence.
|
||
The mechanism (dashboard alert, email, webhook) and the aggregation policy
|
||
(per-event vs. rate-limited summary) are not yet decided. The extension's
|
||
responsibility ends at reporting to the backend; delivery to the site owner
|
||
is a backend and account-management concern.
|
||
|
||
### Data storage
|
||
|
||
| Data | Location | Lifetime |
|
||
|---|---|---|
|
||
| Compiled-in pubkeys | Source constants | Build time |
|
||
| Per-tab state machine state | In-memory (worker) | Tab lifetime |
|
||
| Site verification result | `chrome.storage.session` | Browser session |
|
||
| Run parameters (qr_ttl, max_auto_refresh, pin_ttl) | In-memory | Phase 1–4; discarded on delivery or error |
|
||
| auto_refresh_remaining counter | In-memory | Phase 2 only |
|
||
| Ephemeral keypairs (X25519, ML-KEM-768) | In-memory | Phase 1–2 only |
|
||
| Run key | In-memory | Phase 3–4; discarded on delivery or error |
|
||
| GYBBR identity keys | `chrome.storage.session` | Browser session (see below) |
|
||
|
||
Private key material is never written to `chrome.storage.local`, `localStorage`,
|
||
`IndexedDB`, or any other persistent store.
|
||
|
||
## Cryptographic responsibilities
|
||
|
||
Operations the extension performs locally, in the service worker:
|
||
|
||
- **Site verification:** receives the ML-DSA-44 registration certificate from
|
||
the SDK via Port; reads the real page origin from `sender.tab.url`; rejects
|
||
immediately if the scheme is not `https:`; verifies the signature against
|
||
`BACKEND_PUBLIC_KEY_B64`, checks validity window and domain match against the
|
||
origin hostname, then queries the backend for account status.
|
||
- **Session initiation:** generates ephemeral X25519 and ML-KEM-768 keypairs,
|
||
computes `alpha_hash`, uploads key bundle to backend, receives and verifies
|
||
Ed25519-signed token.
|
||
- **Run key derivation:** ML-KEM-768 decapsulation, X25519 key agreement,
|
||
HKDF-SHA256 combining both shared secrets with `salt=runId_utf8`,
|
||
`info="locqr-run-key-v1"`, `length=32`.
|
||
- **PIN derivation:** HKDF-SHA256 over the run key with `info="locqr-pin-v1"`.
|
||
- **Payload decryption:** AES-256-GCM decryption of the credential received from
|
||
the companion via the backend relay.
|
||
|
||
All algorithm parameters, canonical serialisation, and normative ordering rules
|
||
are specified in `../crypto.md`.
|
||
|
||
## Backend API surface
|
||
|
||
The extension communicates with the backend over HTTPS. Endpoints used:
|
||
|
||
- Upload key bundle (run ID, X25519 pubkey, ML-KEM-768 pubkey) →
|
||
receive Ed25519-signed token and run parameters.
|
||
- Open and maintain a WebSocket connection to `/run/relay/:runId` for
|
||
incoming relay messages (kem_ciphertext in Phase 2, encrypted credential in
|
||
Phase 4).
|
||
- Post PIN confirmation to `/run/relay/:runId/confirm` (phase_3 → phase_4,
|
||
unlocks the companion — interfaces.md's "PIN confirmation").
|
||
- Query account status for a domain (site verification, step 3).
|
||
- Report security-class errors to `/security/report`.
|
||
|
||
Endpoint definitions and all request/response schemas are in `../interfaces.md`.
|
||
Endpoint behaviour is in `../server/claude.md`.
|
||
|
||
## Website / SDK interface
|
||
|
||
The SDK opens a Port to the service worker via `externally_connectable`. The
|
||
service worker receives the connection, verifies the cert supplied by the SDK,
|
||
and responds with the verification outcome and authorised feature set. All
|
||
subsequent SDK↔extension communication uses this Port.
|
||
|
||
The extension does not respond to SDK requests from a tab whose verification
|
||
outcome is not valid. A site that supplies no cert, an invalid cert, or whose
|
||
account is not in good standing receives only the verification error response;
|
||
no further extension services are available.
|
||
|
||
Port message schemas (message types, `LocqrError`, `Credential`) are defined
|
||
in `../interfaces.md`. The SDK surface exposed to websites is defined in
|
||
`../sdk/claude.md`.
|
||
|
||
## Security invariants
|
||
|
||
- Private key material (ephemeral or identity) never leaves the service worker
|
||
context. It is never serialised, logged, or passed to any other context.
|
||
- Session keys are discarded immediately after credential delivery. They are not
|
||
stored in `chrome.storage.session` or anywhere else.
|
||
- The extension verifies the backend's Ed25519 signature on the signed token
|
||
before displaying the QR code. It does not proceed if verification fails.
|
||
- Site verification runs when the SDK connects via Port. A valid outcome is
|
||
required before any extension service is offered, including the crypto vault.
|
||
- The extension never activates on a non-HTTPS origin. HTTP pages receive
|
||
`cert_invalid / insecure_origin` immediately; no cert is inspected, no
|
||
backend is contacted.
|
||
- The popup UI is rendered outside the website DOM. It cannot be spoofed by
|
||
website content.
|
||
|
||
---
|
||
|
||
## GYBBR: cryptographic vault (deferred)
|
||
|
||
The extension doubles as an isolated cryptographic vault for GYBBR. This
|
||
functionality is deferred and will be designed in a separate document; the
|
||
summary here captures the intended model so that architectural decisions for
|
||
the LOCQR core do not inadvertently foreclose it.
|
||
|
||
### Vault model
|
||
|
||
The vault exposes a key-ID-based API to registered sites. A website never
|
||
receives key material in cleartext; it only receives operation results. The
|
||
canonical request form is "encrypt/decrypt this data under key A" or, for
|
||
cross-key operations, "re-encrypt from key A to key B."
|
||
|
||
Keys are loaded from the website in their encrypted form and decrypted inside
|
||
the vault using the user's master identity key. The master identity key is
|
||
delivered to the extension via the standard LOCQR run and held in
|
||
`chrome.storage.session` for the duration of the browser session. The
|
||
vault never needs to destroy keys; key-encrypted-under-master leaves and
|
||
re-enters the vault across browser sessions.
|
||
|
||
### Threat model
|
||
|
||
A session hijack or XSS attack against the website can intercept SDK calls and
|
||
observe operation results (ciphertext, plaintext of things the page requested
|
||
decrypted). It cannot extract key material from the vault, forge operations the
|
||
site is not authorised to request, or access keys scoped to a different domain.
|
||
|
||
### Domain isolation
|
||
|
||
Key material is namespaced by the domain of the registered site. A key created
|
||
or loaded for site A is inaccessible to site B even if both use the LOCQR
|
||
extension and the same underlying key scheme. This isolation is enforced by the
|
||
extension, not by the website.
|
||
|
||
### Feature sets via registration certificate
|
||
|
||
The registration certificate issued by the backend can encode which extension
|
||
features a site is permitted to use (e.g. standard LOCQR login only, or login
|
||
plus crypto vault). This allows the extension to offer different feature sets to
|
||
different sites under a single consistent trust model, with the backend as the
|
||
authority on what each registered domain may access.
|