# Backend Server The backend server is the trust anchor for the entire system. Its signing keys are the only compile-time constants; all legitimacy within the system traces back to its ability to sign, and the clients' ability to verify against those pinned keys. It provides two services: run infrastructure (key bundle storage, token signing, relay) and account management (domain registration, certificates, billing). The server exists in two implementations: a **Node.js stub** used during development, and the **Java/Spring production server** which is the long-term target. --- ## Node.js stub (development tool) A minimal Express server implementing only the parts the extension and companion actually touch. Its purpose is to allow end-to-end development and testing of the full run flow without the production infrastructure. **What it does:** - Stores key bundles in memory; destroys on fetch (at-most-once) - Signs key exchange tokens with Ed25519 (Node built-in `crypto` module) - Returns server-controlled run parameters with each signed token - Accepts WebSocket connections from the extension for relay - Forwards relay messages (kem_ciphertext, encrypted credential) from companion to extension - Serves a pre-generated test domain certificate (ML-DSA-44); does not dynamically issue certificates - Accepts domain status queries; returns valid for the hardcoded test domain **What it deliberately omits:** - No persistence — all state is in-memory - No ML-DSA-44 signing at runtime (test cert pre-generated by the dev setup script in `../dev.md`; the stub reads it from `dev/certs/test-registration.b64` at startup) - No account management - No billing or registration flows --- ## Production server Java/Spring. Deferred. The Node stub defines the API contract that production must honour. | Concern | Production | |---|---| | Key bundle storage | Redis (`GETDEL` for atomic at-most-once delivery) | | Domain registrations / accounts | PostgreSQL | | ML-DSA-44 signing | BouncyCastle or liboqs-java | | WebSocket relay | Spring WebSocket | | Account management | Full SaaS (registration, billing, domain admin) | --- ## Signing keys The server holds two secret keys. Neither is ever stored in source code or committed to version control — injected via environment variables or a secrets manager at startup. | Secret key | Algorithm | Corresponding pinned constant | Purpose | |---|---|---|---| | `ED25519_SECRET_KEY` | Ed25519 | `ED25519_PUBLIC_KEY_B64` (extension), `ED25519_PUBKEY` (companion) | Signs key exchange tokens | | `ML_DSA_44_SECRET_KEY` | ML-DSA-44 | `BACKEND_PUBLIC_KEY_B64` (extension) | Signs domain registration certificates | Key regeneration patches all pinned constants in extension and companion source and requires redeployment of all three components. --- ## API surface All request and response body schemas are defined in `../interfaces.md`. This section describes endpoint behaviour; the interfaces document is the normative source for field names, types, and encodings. ### Extension endpoints **`POST /run/bundle`** Extension uploads key bundle at Phase 1. Request: `{ runId, origin, x25519_pubkey_b64, kem_pubkey_b64 }` `origin` is the full HTTPS origin of the site (`https://host:port`), taken from the registration certificate the extension verified. The server bakes it verbatim into the signed token as `url`. The extension must reject any origin whose scheme is not `https:` before the bundle upload is ever attempted. The server: 1. Stores the key bundle associated with the run ID. 2. Computes `alpha_hash = SHA-256(x25519_pub_bytes || kem_pub_bytes)`. 3. Signs `{ alpha_hash, url, runId, expires_at }` with Ed25519 → signed token. 4. Returns signed token and run parameters. Response: `{ signed_token, qr_ttl, max_auto_refresh, pin_ttl }` The server should eventually verify that the origin is registered to an active account before signing — this ownership verification mechanism is deferred for the stub. TTL values in run parameters are server-controlled; clients must not apply local defaults. **`GET /domain/status?domain=`** Extension queries account status during site verification. Response: `{ status: "valid" | "rejected" | "suspended" }` or error if unreachable. **`POST /security/report`** Extension or companion reports a security-class error. Request: `{ runId, error_type, timestamp }`. Server logs and aggregates. Site owner notification mechanism deferred — see `../extension/claude.md`, *Error escalation*. ### Companion endpoints **`GET /run/bundle/:runId`** Companion fetches key bundle at Phase 2. **At-most-once: the bundle is atomically destroyed on this fetch.** A second request for the same run ID returns an error. Response: `{ x25519_pubkey_b64, kem_pubkey_b64 }` or `404` if already consumed or expired. This is a load-bearing security property. Node stub uses `Map.get()` + `Map.delete()` (safe for single-process development). Production uses Redis `GETDEL`. **`GET /run/relay/:runId` (WebSocket upgrade — extension only)** The extension upgrades this endpoint to a WebSocket connection immediately after Phase 1 completes. The server maps the run ID to the live socket and uses it to push relay messages to the extension. If the service worker suspends and the socket drops, the extension is responsible for reconnecting before any relay message arrives. **`POST /run/relay/:runId` (HTTP — companion only)** Companion sends a relay message (kem_ciphertext in Phase 2, encrypted credential in Phase 4) addressed to the run ID. Request: `{ type, payload_b64 }`. Server forwards the complete message object over the extension's WebSocket for that run ID. If the WebSocket is not currently open (service worker suspended), the message is buffered briefly. Buffer lifetime is short (seconds); if the extension does not reconnect within that window the message is discarded and the run must be restarted. ### Admin / website endpoints Domain registration and account management. Deferred for the stub; stub serves a hardcoded test domain certificate. Production endpoints are a full SaaS concern. --- ## WebSocket relay The extension opens a WebSocket connection to `/run/relay/:runId` after completing Phase 1. The server maintains a mapping of run ID → active connection. **Message flow:** 1. Extension opens WS for run ID (after Phase 1). 2. Companion POSTs kem_ciphertext → server pushes to extension WS (Phase 2). 3. Companion POSTs encrypted credential → server pushes to extension WS (Phase 4). 4. WS closes on run end (delivered, error, or TTL expiry). The extension is responsible for keeping its WS connection alive across service worker suspensions using `chrome.alarms` or equivalent. The server-side buffer provides a short grace window but is not a reliable recovery mechanism. --- ## State model | Data | Storage | Lifetime | |---|---|---| | Key bundles | In-memory / Redis | `qr_ttl`; destroyed on fetch or expiry | | Active WS connections (runId → socket) | In-memory | Run lifetime | | Relay message buffer (undelivered) | In-memory | Seconds; discarded if extension does not reconnect | | Domain registration certificates | Static file / DB | Until expiry or renewal | | Account records | Hardcoded / DB | Persistent | | Signing keys | Environment / secrets manager | Permanent | --- ## Security invariants - Signing keys are never stored in source code or version control. - The key bundle is atomically destroyed on first fetch. No partial reads; no second deliveries. - The server cannot decrypt relay messages. It forwards opaque blobs; the run key is never transmitted through it. - The signed token binds `alpha_hash`, `url`, `runId`, and `expires_at` together. Substituting any field invalidates the signature. - Security-class error reports are accepted from any client without authentication — rate-limiting and aggregation are the server's responsibility.