7.8 KiB
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
cryptomodule) - 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 fromdev/certs/test-registration.b64at 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:
- Stores the key bundle associated with the run ID.
- Computes
alpha_hash = SHA-256(x25519_pub_bytes || kem_pub_bytes). - Signs
{ alpha_hash, url, runId, expires_at }with Ed25519 → signed token. - 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=<hostname>
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:
- Extension opens WS for run ID (after Phase 1).
- Companion POSTs kem_ciphertext → server pushes to extension WS (Phase 2).
- Companion POSTs encrypted credential → server pushes to extension WS (Phase 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, andexpires_attogether. 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.