feat(relay): rendezvous-relay service — 7 packages + plans (contracts/transport/agent/control-plane/e2e/auth/web)

Multi-tenant reverse-tunnel service ("ngrok for Claude Code" with E2E): a
host-agent dials OUT to an operator-run relay; external devices reach the host
THROUGH the relay, routed by per-tenant subdomain, forwarding ciphertext only
(the relay never sees plaintext). Lets a customer reach their own self-hosted
web-terminal from anywhere with zero networking setup.

Packages — all tsc-strict + vitest green (656 tests), cross-package integration verified:
- relay-contracts: frozen shared contracts (mux frame codec, data model,
  capability token, E2E envelope, pairing) — the src/types.ts analog
- term-relay:   native WS mux + stateless data plane (subdomain routing, ciphertext forward)
- agent:        host-agent (pairing, per-host Ed25519 + mTLS dial-out, forwards to 127.0.0.1:3000)
- control-plane: accounts/hosts registry, pairing-code flow, routing table, provisioning
- relay-e2e:    browser<->agent E2E (X25519 ECDH through relay, AEAD, anti-replay, recoverable replay key)
- relay-auth:   Passkey/WebAuthn, capability tokens, per-host certs, deny-by-default tenant isolation
- relay-web:    browser login + Web Crypto E2E + client-side preview rendering

Security invariants INV1-15 enforced; cross-tenant isolation CI tripwire live
(.github/workflows/relay-tripwire.yml). Design + implementation-level plans in
docs/PLAN_RELAY_*.md and docs/EXPLORE_RELAY_SERVICE.md.

NOTE: generated autonomously per the reviewed plans. The security-critical
packages (relay-e2e, relay-auth) REQUIRE expert security audit before any real
deployment — passing tests prove self-consistency, not resistance to attackers.
Base app (src/, public/) unchanged; concurrent desktop work left uncommitted.

control-plane/bin/provision.ts

@@ -0,0 +1,26 @@
+/**
+ * T0 (v0.8) — manual provisioning CLI. `node bin/provision.ts <subdomain>` mints an account
+ * in the flat store and prints the raw agent/client tokens ONCE (they are never stored raw).
+ * This is the throwaway MVP admin path; T11 promotes it to an authenticated HTTP API.
+ */
+import { createFlatStore } from '../src/flat-store.js'
+
+async function main(): Promise<void> {
+  const subdomain = process.argv[2]
+  if (subdomain === undefined || subdomain.trim() === '') {
+    process.stderr.write('usage: provision <subdomain>\n')
+    process.exitCode = 2
+    return
+  }
+  const store = createFlatStore()
+  const { accountId, agentToken, clientToken } = await store.provisionFlat(subdomain.trim())
+  // Raw tokens printed ONCE for the operator to copy; they are not recoverable afterwards.
+  process.stdout.write(
+    JSON.stringify({ accountId, subdomain: subdomain.trim(), agentToken, clientToken }, null, 2) + '\n',
+  )
+}
+
+main().catch((err: unknown) => {
+  process.stderr.write(`provision failed: ${err instanceof Error ? err.message : String(err)}\n`)
+  process.exitCode = 1
+})

control-plane/db/flat.sqlite.sql

@@ -0,0 +1,9 @@
+-- T0 (v0.8 MVP) — flat account table (SQLite). Retired by CP1 Postgres registries (T2-T4).
+-- Stores ONLY hashes of the agent/client tokens (INV5): raw tokens are returned once at mint
+-- and never persisted. No immutable-record ceremony at this phase.
+CREATE TABLE IF NOT EXISTS flat_accounts (
+  account_id        TEXT PRIMARY KEY,   -- uuid, unguessable
+  subdomain         TEXT NOT NULL UNIQUE,
+  agent_token_hash  TEXT NOT NULL,      -- scrypt$salt$hash — never the raw token
+  client_token_hash TEXT NOT NULL
+);

control-plane/db/migrations/0001_init.sql

@@ -0,0 +1,105 @@
+-- T2 — control-plane schema. Transcribes INDEX §4.2 (accounts/hosts/sessions/pairing_codes)
+-- VERBATIM, plus P3-owned tables (relay_nodes, metering_samples, audit_log) and the INV8 companion
+-- status-version tables + current-pointer columns (OQ6 — pending INDEX promotion of §4.2).
+--
+-- Discipline: no bare UPDATE of a lifecycle/business field without a matching *_status_versions
+-- insert in the SAME transaction. Liveness columns (last_seen, last_attach_at) are advisory
+-- caches (INV7 — live truth is Redis) and are exempt from versioning.
+
+CREATE EXTENSION IF NOT EXISTS "pgcrypto"; -- gen_random_uuid()
+
+-- ---- accounts (§4.2) --------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS accounts (
+  account_id     uuid PRIMARY KEY DEFAULT gen_random_uuid(), -- unguessable, never recycled
+  plan           text NOT NULL,                              -- 'free'|'personal'|'pro'|'team'
+  created_at     timestamptz NOT NULL DEFAULT now(),
+  status         text NOT NULL DEFAULT 'active',             -- 'active'|'suspended' (current pointer)
+  status_version int  NOT NULL DEFAULT 1,                    -- INV8 monotonic pointer
+  CONSTRAINT accounts_plan_chk   CHECK (plan   IN ('free','personal','pro','team')),
+  CONSTRAINT accounts_status_chk CHECK (status IN ('active','suspended'))
+);
+
+CREATE TABLE IF NOT EXISTS account_status_versions (
+  account_id uuid NOT NULL REFERENCES accounts(account_id),
+  version    int  NOT NULL,
+  status     text NOT NULL,
+  changed_at timestamptz NOT NULL DEFAULT now(),
+  changed_by text NOT NULL,
+  PRIMARY KEY (account_id, version)
+);
+
+-- ---- hosts (§4.2) — ownership source of truth --------------------------------------------------
+CREATE TABLE IF NOT EXISTS hosts (
+  host_id        uuid PRIMARY KEY DEFAULT gen_random_uuid(), -- unguessable, NEVER recycled (INV1)
+  account_id     uuid NOT NULL REFERENCES accounts(account_id),
+  subdomain      text NOT NULL UNIQUE,                       -- stable across reconnects
+  agent_pubkey   bytea NOT NULL,                             -- Ed25519 PUBLIC key only (INV4)
+  enroll_fpr     text NOT NULL,                              -- fingerprint of agent_pubkey (E2E TOFU)
+  status         text NOT NULL DEFAULT 'offline',            -- 'online'|'offline'|'draining'|'revoked'
+  last_seen      timestamptz NOT NULL DEFAULT now(),         -- advisory cache (NOT versioned, INV7)
+  created_at     timestamptz NOT NULL DEFAULT now(),
+  revoked_at     timestamptz NULL,                           -- set on revocation (INV12)
+  status_version int NOT NULL DEFAULT 1,
+  CONSTRAINT hosts_status_chk CHECK (status IN ('online','offline','draining','revoked'))
+);
+CREATE INDEX IF NOT EXISTS hosts_account_idx ON hosts(account_id);
+
+CREATE TABLE IF NOT EXISTS host_status_versions (
+  host_id    uuid NOT NULL REFERENCES hosts(host_id),
+  version    int  NOT NULL,
+  status     text NOT NULL,
+  revoked_at timestamptz NULL,
+  changed_at timestamptz NOT NULL DEFAULT now(),
+  changed_by text NOT NULL,
+  PRIMARY KEY (host_id, version)
+);
+
+-- ---- sessions (§4.2) --------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS sessions (
+  session_id     uuid PRIMARY KEY,                           -- base-app sessionId, opaque to relay
+  host_id        uuid NOT NULL REFERENCES hosts(host_id),
+  account_id     uuid NOT NULL,                              -- DENORMALIZED for O(1) authz (INV3/INV6)
+  created_at     timestamptz NOT NULL DEFAULT now(),
+  last_attach_at timestamptz NOT NULL DEFAULT now()          -- advisory cache (NOT versioned)
+);
+
+-- ---- pairing_codes (§4.2/§4.5) ----------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS pairing_codes (
+  code_hash       text PRIMARY KEY,                          -- hash of single-use code; raw NEVER stored (INV5)
+  account_id      uuid NOT NULL REFERENCES accounts(account_id),
+  expires_at      timestamptz NOT NULL,                      -- short TTL
+  redeemed_at     timestamptz NULL,                          -- single-use: non-null ⇒ spent
+  redeem_attempts int NOT NULL DEFAULT 0                     -- code-scoped brute-force lockout (T8)
+);
+
+-- ---- relay_nodes (P3-owned) -------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS relay_nodes (
+  node_id   text PRIMARY KEY,                                -- SPIFFE-style id from mTLS cert subject
+  addr      text NOT NULL,
+  status    text NOT NULL DEFAULT 'active',                  -- 'active'|'draining'
+  last_seen timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT relay_nodes_status_chk CHECK (status IN ('active','draining'))
+);
+
+-- ---- metering_samples (P3-owned, append-only INV8) --------------------------------------------
+CREATE TABLE IF NOT EXISTS metering_samples (
+  id                 bigserial PRIMARY KEY,
+  host_id            uuid NOT NULL REFERENCES hosts(host_id),
+  account_id         uuid NOT NULL,                          -- derived server-side from ownership (INV1)
+  node_id            text NOT NULL,                          -- authenticated mTLS identity (INV3-analog)
+  concurrent_viewers int NOT NULL,
+  sampled_at         timestamptz NOT NULL
+);
+CREATE INDEX IF NOT EXISTS metering_account_time_idx ON metering_samples(account_id, sampled_at);
+
+-- ---- audit_log (P3-owned, append-only zero-payload INV10) -------------------------------------
+CREATE TABLE IF NOT EXISTS audit_log (
+  id           bigserial PRIMARY KEY,
+  action       text NOT NULL,
+  principal_id text NOT NULL,
+  account_id   text NOT NULL,
+  host_id      text NULL,
+  ts           timestamptz NOT NULL DEFAULT now(),
+  meta         jsonb NOT NULL DEFAULT '{}'::jsonb            -- metadata only; NO terminal payload (INV10)
+);
+CREATE INDEX IF NOT EXISTS audit_account_time_idx ON audit_log(account_id, ts);

control-plane/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "control-plane",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "P3 — Control Plane & Accounts for the rendezvous-relay service. Account/host/session registries (immutable, INV8), pairing issuance+redemption+BIND, subdomain assignment, Redis routing table, provisioning/metering/revocation APIs, registry-gated mTLS leaf signing (INV14), immutable zero-payload audit (INV10). Imports relay-contracts read-only. See docs/PLAN_RELAY_CONTROLPLANE.md.",
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "src/main.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "relay-contracts": "file:../relay-contracts",
+    "fastify": "^4.28.1",
+    "ioredis": "^5.4.1",
+    "pg": "^8.12.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "@types/pg": "^8.11.10",
+    "@vitest/coverage-v8": "^4.1.9",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  }
+}

control-plane/src/api/authz.ts

@@ -0,0 +1,77 @@
+/**
+ * T11 — admin-API principal derivation (INV3). `accountId` comes ONLY from the VERIFIED capability
+ * token (P5 owns the signing key + `verifyCapabilityToken`; we consume it as an injected verifier).
+ * Any body/query field named `account_id`/`tenant_id` is IGNORED for authz decisions. Deny-by-default:
+ * a missing/expired/foreign-`aud` token → 401.
+ */
+import { extractTokenFromSubprotocols, type CapabilityToken, type CapabilityRight } from 'relay-contracts'
+
+export interface AdminPrincipal {
+  readonly accountId: string
+  readonly rights: readonly CapabilityRight[]
+}
+
+export class AuthzError extends Error {
+  constructor(
+    public readonly status: 401 | 403,
+    message: string,
+  ) {
+    super(message)
+  }
+}
+
+/** P5's verifier, injected. Mirrors the frozen `verifyCapabilityToken` signature (§4.3). */
+export interface CapabilityVerifier {
+  verify(raw: string, expectedAud: string, now: number): CapabilityToken
+}
+
+/** Minimal request shape we read for the bearer token (never a body account field). */
+export interface AuthRequest {
+  readonly headers: Readonly<Record<string, string | string[] | undefined>>
+}
+
+export interface AuthzDeps {
+  readonly verifier: CapabilityVerifier
+  readonly expectedAud: string // admin audience the token must be scoped to (Host-confusion guard)
+  readonly now?: () => number
+}
+
+function extractRawToken(req: AuthRequest): string | null {
+  const auth = req.headers['authorization']
+  if (typeof auth === 'string' && auth.startsWith('Bearer ')) return auth.slice('Bearer '.length).trim()
+  // Also accept the WS-upgrade subprotocol transport (FIX 5), for parity with the relay edge.
+  const proto = req.headers['sec-websocket-protocol']
+  if (typeof proto === 'string') {
+    const values = proto.split(',').map((v) => v.trim())
+    return extractTokenFromSubprotocols(values)
+  }
+  return null
+}
+
+export interface Authorizer {
+  principalFromRequest(req: AuthRequest): AdminPrincipal
+  requireRight(principal: AdminPrincipal, right: CapabilityRight): void
+}
+
+export function createAuthorizer(deps: AuthzDeps): Authorizer {
+  const now = deps.now ?? (() => Math.floor(Date.now() / 1000))
+  return {
+    principalFromRequest(req) {
+      const raw = extractRawToken(req)
+      if (raw === null) throw new AuthzError(401, 'missing capability token')
+      let token: CapabilityToken
+      try {
+        token = deps.verifier.verify(raw, deps.expectedAud, now())
+      } catch (err: unknown) {
+        throw new AuthzError(401, `invalid capability token: ${err instanceof Error ? err.message : 'rejected'}`)
+      }
+      // accountId derives ONLY from the token principal — never from a client field (INV3).
+      return { accountId: token.sub, rights: token.rights }
+    },
+    requireRight(principal, right) {
+      if (!principal.rights.includes(right)) {
+        throw new AuthzError(403, `token scope lacks required right: ${right}`)
+      }
+    },
+  }
+}

control-plane/src/api/provision.ts

@@ -0,0 +1,137 @@
+/**
+ * T11 — provisioning / deprovisioning HTTP routes. ALL admin routes are deny-by-default and scope
+ * every operation to `principal.accountId` (INV3/INV6). Host-targeting routes re-check
+ * `ownsHost` (INV1). No route resolves a host by a user-supplied address. `/enroll` is the one
+ * route NOT gated by a capability token (it IS the auth bootstrap) but is guarded by the single-use
+ * pairing code (T8). Every body is Zod-validated at the boundary; malformed → 400.
+ */
+import { z } from 'zod'
+import type { FastifyPluginAsync, FastifyReply, FastifyRequest } from 'fastify'
+import type { PlanTier } from 'relay-contracts'
+import type { Authorizer, AdminPrincipal } from './authz.js'
+import { AuthzError } from './authz.js'
+import type { AccountRegistry } from '../registry/accounts.js'
+import type { HostRegistry } from '../registry/hosts.js'
+import type { PairingIssuer } from '../pairing/issue.js'
+import type { PairingRedeemer } from '../pairing/redeem.js'
+import { RedeemError } from '../pairing/redeem.js'
+import type { Deprovisioner } from '../deprovision/deprovision.js'
+
+export interface ProvisionDeps {
+  readonly authorizer: Authorizer
+  readonly accounts: AccountRegistry
+  readonly hosts: HostRegistry
+  readonly pairingIssuer: PairingIssuer
+  readonly redeemer: PairingRedeemer
+  readonly deprovisioner: Deprovisioner
+}
+
+const PlanSchema = z.enum(['free', 'personal', 'pro', 'team'])
+const StatusSchema = z.object({ status: z.enum(['active', 'suspended']) })
+const EnrollSchema = z.object({
+  code: z.string().min(1),
+  agentPubkey: z.string().min(1), // base64
+  csr: z.string().min(1), // base64
+})
+
+function sendError(reply: FastifyReply, err: unknown): void {
+  if (err instanceof AuthzError) {
+    void reply.code(err.status).send({ error: err.message })
+    return
+  }
+  if (err instanceof RedeemError) {
+    const status = err.code === 'too_many_attempts' ? 429 : 400
+    void reply.code(status).send({ error: err.code })
+    return
+  }
+  void reply.code(400).send({ error: err instanceof Error ? err.message : 'bad request' })
+}
+
+/** Enforce that the path :id equals the authenticated principal's account (INV1). */
+function assertOwnAccount(principal: AdminPrincipal, pathAccountId: string): void {
+  if (principal.accountId !== pathAccountId) {
+    throw new AuthzError(403, 'account scope mismatch') // never operate on another tenant
+  }
+}
+
+export function buildRouter(deps: ProvisionDeps): FastifyPluginAsync {
+  return async (app) => {
+    const principal = (req: FastifyRequest): AdminPrincipal =>
+      deps.authorizer.principalFromRequest({ headers: req.headers })
+
+    app.post('/accounts', async (req, reply) => {
+      try {
+        const p = principal(req)
+        deps.authorizer.requireRight(p, 'manage')
+        const plan: PlanTier = PlanSchema.parse((req.body as { plan?: unknown })?.plan ?? 'free')
+        const account = await deps.accounts.createAccount(plan)
+        await reply.code(201).send(account)
+      } catch (err) {
+        sendError(reply, err)
+      }
+    })
+
+    app.post('/accounts/:id/pairing-codes', async (req, reply) => {
+      try {
+        const p = principal(req)
+        deps.authorizer.requireRight(p, 'manage')
+        assertOwnAccount(p, (req.params as { id: string }).id)
+        const issued = await deps.pairingIssuer.issuePairingCode(p.accountId)
+        await reply.code(201).send(issued)
+      } catch (err) {
+        sendError(reply, err)
+      }
+    })
+
+    app.post('/accounts/:id/status', async (req, reply) => {
+      try {
+        const p = principal(req)
+        deps.authorizer.requireRight(p, 'manage')
+        assertOwnAccount(p, (req.params as { id: string }).id)
+        const { status } = StatusSchema.parse(req.body)
+        const account = await deps.accounts.setAccountStatus(p.accountId, status)
+        await reply.send(account)
+      } catch (err) {
+        sendError(reply, err)
+      }
+    })
+
+    app.get('/accounts/:id/hosts', async (req, reply) => {
+      try {
+        const p = principal(req)
+        assertOwnAccount(p, (req.params as { id: string }).id)
+        const hosts = await deps.hosts.listHosts(p.accountId) // ownership-scoped
+        await reply.send(hosts.map((h) => ({ ...h, agentPubkey: Buffer.from(h.agentPubkey).toString('base64') })))
+      } catch (err) {
+        sendError(reply, err)
+      }
+    })
+
+    app.delete('/hosts/:hostId', async (req, reply) => {
+      try {
+        const p = principal(req)
+        deps.authorizer.requireRight(p, 'manage')
+        // account_id in the body is IGNORED — authz uses ONLY the token principal (INV3).
+        await deps.deprovisioner.deprovisionHost(p, (req.params as { hostId: string }).hostId)
+        await reply.code(204).send()
+      } catch (err) {
+        sendError(reply, err)
+      }
+    })
+
+    app.post('/enroll', async (req, reply) => {
+      // NOT capability-token gated — guarded by the single-use pairing code (T8).
+      try {
+        const body = EnrollSchema.parse(req.body)
+        const result = await deps.redeemer.redeemPairingCode({
+          code: body.code,
+          agentPubkey: new Uint8Array(Buffer.from(body.agentPubkey, 'base64')),
+          csr: new Uint8Array(Buffer.from(body.csr, 'base64')),
+        })
+        await reply.code(201).send({ ...result, hostContentSecret: Buffer.from(result.hostContentSecret).toString('base64') })
+      } catch (err) {
+        sendError(reply, err)
+      }
+    })
+  }
+}

control-plane/src/audit/log.ts

@@ -0,0 +1,118 @@
+/**
+ * T14 — immutable, ZERO-PAYLOAD audit writer (INV10). Single funnel that P5 also imports for
+ * attach/manage/kill/revoke events. Append-only: no update/delete path is exposed. A payload
+ * guard rejects any `meta` value that could smuggle terminal output (length cap + control/ANSI
+ * bytes), so keystrokes/output/secrets can never land in `audit_log`.
+ */
+import { z } from 'zod'
+import type { AuditStore, AuditRow } from '../store/ports.js'
+
+export type AuditAction =
+  | 'account.create'
+  | 'account.suspend'
+  | 'host.bind'
+  | 'host.revoke'
+  | 'pairing.issue'
+  | 'pairing.redeem'
+  | 'subdomain.assign'
+  | 'node.drain'
+  | 'attach'
+  | 'manage'
+  | 'kill'
+  | 'revoke'
+
+export interface AuditEntry {
+  readonly action: AuditAction
+  readonly principalId: string
+  readonly accountId: string
+  readonly hostId: string | null
+  readonly ts: string
+  readonly meta: Readonly<Record<string, string>>
+}
+
+/** Max length of a single metadata value — small enough that no terminal frame fits (INV10). */
+export const MAX_META_VALUE_LEN = 256
+/** Max number of metadata keys per entry. */
+export const MAX_META_KEYS = 16
+
+const AuditActionSchema = z.enum([
+  'account.create',
+  'account.suspend',
+  'host.bind',
+  'host.revoke',
+  'pairing.issue',
+  'pairing.redeem',
+  'subdomain.assign',
+  'node.drain',
+  'attach',
+  'manage',
+  'kill',
+  'revoke',
+])
+
+/** True if the string contains any C0 control byte (0x00–0x1f) — incl. ESC that begins ANSI. */
+function hasControlBytes(v: string): boolean {
+  for (let i = 0; i < v.length; i++) {
+    if (v.charCodeAt(i) < 0x20) return true
+  }
+  return false
+}
+
+const MetaValue = z
+  .string()
+  .max(MAX_META_VALUE_LEN, 'meta value exceeds zero-payload cap')
+  .refine((v) => !hasControlBytes(v), 'meta value contains control/ANSI bytes (possible terminal payload)')
+
+const AuditEntrySchema = z
+  .object({
+    action: AuditActionSchema,
+    principalId: z.string().min(1),
+    accountId: z.string().min(1),
+    hostId: z.string().nullable(),
+    ts: z.string().datetime({ offset: true }),
+    meta: z.record(z.string(), MetaValue).refine((m) => Object.keys(m).length <= MAX_META_KEYS, {
+      message: 'too many meta keys',
+    }),
+  })
+  .strict()
+
+export interface AuditWriter {
+  writeAuditEvent(entry: AuditEntry): Promise<void>
+  queryAudit(accountId: string, from: string, to: string): Promise<readonly AuditEntry[]>
+}
+
+export function createAuditLog(store: AuditStore): AuditWriter {
+  return {
+    async writeAuditEvent(entry) {
+      const parsed = AuditEntrySchema.safeParse(entry)
+      if (!parsed.success) {
+        throw new Error(`audit payload guard rejected entry: ${parsed.error.issues[0]?.message ?? 'invalid'}`)
+      }
+      const row: AuditRow = { ...parsed.data }
+      await store.append(row) // append-only, immutable
+    },
+    async queryAudit(accountId, from, to) {
+      const rows = await store.query(accountId, from, to)
+      return rows.map((r) => ({
+        action: r.action as AuditAction,
+        principalId: r.principalId,
+        accountId: r.accountId,
+        hostId: r.hostId,
+        ts: r.ts,
+        meta: r.meta,
+      }))
+    },
+  }
+}
+
+/** No-op writer for tasks that treat audit as an optional injected dependency in v0.9. */
+export function noopAuditWriter(): AuditWriter {
+  return {
+    async writeAuditEvent() {
+      /* intentionally does nothing */
+    },
+    async queryAudit() {
+      return []
+    },
+  }
+}

control-plane/src/boot/ca-wiring.ts

@@ -0,0 +1,75 @@
+/**
+ * T15 — CA-key / secret-manager bootstrap + KMS-signer factory (§3.1). The intermediate
+ * leaf-signing key is a non-exportable KMS/HSM key: signing is a `sign()` CALL, the raw private
+ * key is NEVER loaded into control-plane memory. `buildCaSigner` FAILS FAST at startup (INV9) if
+ * the key ref is unresolvable OR its policy does not restrict `sign` to the control-plane
+ * service principal. Both T8 `signHostLeaf` and T15 `renewHostLeaf` call this shared primitive —
+ * neither loads a raw key.
+ */
+import { createPublicKey } from 'node:crypto'
+import type { ControlPlaneEnv } from '../env.js'
+import { ed25519Sign, generateEd25519, type KeyObject } from '../util/crypto.js'
+
+/** Wraps KMS `sign()`; no raw key ever crosses this boundary. */
+export interface CaSigner {
+  sign(tbsCert: Uint8Array): Promise<Uint8Array>
+  /** Public verifying key of the CA (for tests / chain assembly). */
+  readonly publicKeyRaw: Uint8Array
+}
+
+/**
+ * KMS resolver seam. Production resolves a real KMS/HSM key handle + policy; tests inject a fake.
+ * A resolver returns `{ canSign, policyRestrictedToServicePrincipal }` for the given ref, or throws
+ * if the ref cannot be resolved at all.
+ */
+export interface KmsResolver {
+  resolve(keyRef: string): Promise<{
+    readonly signer: CaSigner
+    readonly policyRestrictedToServicePrincipal: boolean
+  }>
+}
+
+/**
+ * Build the CA signer for the configured intermediate KMS key. Fail-fast (INV9, §3.1):
+ *  - throws if the resolver cannot resolve the ref;
+ *  - throws if the KMS key policy is broader than the control-plane service principal.
+ */
+export async function buildCaSigner(env: ControlPlaneEnv, resolver: KmsResolver): Promise<CaSigner> {
+  let resolved
+  try {
+    resolved = await resolver.resolve(env.caIntermediateKmsKeyRef)
+  } catch (err: unknown) {
+    // Never log the ref VALUE — only that resolution failed (INV9).
+    throw new Error(
+      `CA intermediate KMS key could not be resolved: ${err instanceof Error ? err.message : 'unknown'}`,
+    )
+  }
+  if (!resolved.policyRestrictedToServicePrincipal) {
+    throw new Error(
+      'CA intermediate KMS key policy is broader than the control-plane service principal (§3.1) — refusing to boot',
+    )
+  }
+  return resolved.signer
+}
+
+/**
+ * In-process Ed25519 CA signer — TEST/DEV ONLY (clearly NOT a KMS; the plan mandates a real
+ * non-exportable KMS key in production, §3.1). Exposes the same `sign()` surface so callers are
+ * KMS-shaped and never touch a raw key path themselves.
+ */
+export function inProcessCaSigner(privateKey?: KeyObject): CaSigner {
+  const key = privateKey ?? generateEd25519().privateKey
+  const pub = derivePublicRaw(key)
+  return {
+    publicKeyRaw: pub,
+    async sign(tbsCert) {
+      return ed25519Sign(key, tbsCert)
+    },
+  }
+}
+
+function derivePublicRaw(privateKey: KeyObject): Uint8Array {
+  // Recover the raw 32-byte Ed25519 public key from the private KeyObject.
+  const spki = createPublicKey(privateKey).export({ format: 'der', type: 'spki' }) as Buffer
+  return new Uint8Array(spki.subarray(spki.length - 32))
+}

control-plane/src/ca/csr.ts

@@ -0,0 +1,53 @@
+/**
+ * CSR proof-of-possession (INV14). Models a PKCS#10 CSR as `embeddedPub(32) || sig(64)` where
+ * `sig = Ed25519(privateKey, CSR_CHALLENGE || embeddedPub)`. Verifying the signature against the
+ * embedded pubkey proves the requester holds the matching private key (the exact property a real
+ * PKCS#10 self-signature provides) — using builtin crypto only.
+ *
+ * INTEGRATION SEAM: production parses a real PKCS#10 DER (`@peculiar/x509`) and checks the
+ * self-signature. Swapping it in does not change `signHostLeaf`'s check ORDER or reject path.
+ */
+import { ed25519Sign, ed25519Verify, type KeyObject } from '../util/crypto.js'
+
+const CSR_CHALLENGE = new TextEncoder().encode('relay-cp/csr-pop/v1|')
+
+/** Test/agent helper: build a CSR proving possession of `privateKey` for `embeddedPub`. */
+export function buildCsr(privateKey: KeyObject, embeddedPub: Uint8Array): Uint8Array {
+  const message = concat(CSR_CHALLENGE, embeddedPub)
+  const sig = ed25519Sign(privateKey, message)
+  return concat(embeddedPub, sig)
+}
+
+export interface CsrParts {
+  readonly embeddedPub: Uint8Array
+  readonly sig: Uint8Array
+}
+
+/** Parse the modelled CSR bytes. Throws on wrong length. */
+export function parseCsr(csr: Uint8Array): CsrParts {
+  if (csr.length !== 96) throw new Error('malformed csr')
+  return { embeddedPub: csr.subarray(0, 32), sig: csr.subarray(32, 96) }
+}
+
+/**
+ * Verify CSR proof-of-possession: the embedded pubkey's private key signed the challenge.
+ * Independent of any registry state (a forged signature is refused even for a registered key).
+ */
+export function verifyCsrPoP(csr: Uint8Array): { ok: boolean; embeddedPub: Uint8Array } {
+  let parts: CsrParts
+  try {
+    parts = parseCsr(csr)
+  } catch {
+    return { ok: false, embeddedPub: new Uint8Array(0) }
+  }
+  const message = concat(CSR_CHALLENGE, parts.embeddedPub)
+  const ok = ed25519Verify(parts.embeddedPub, message, parts.sig)
+  return { ok, embeddedPub: parts.embeddedPub }
+}
+
+function concat(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const out = new Uint8Array(a.length + b.length)
+  out.set(a, 0)
+  out.set(b, a.length)
+  return out
+}

control-plane/src/ca/fingerprint.ts

@@ -0,0 +1,6 @@
+/** Enrollment fingerprint of an agent public key: SHA-256 hex (pinned by the browser for E2E TOFU, §4.4). */
+import { createHash } from 'node:crypto'
+
+export function fingerprint(agentPubkey: Uint8Array): string {
+  return createHash('sha256').update(agentPubkey).digest('hex')
+}

control-plane/src/ca/rotate.ts

@@ -0,0 +1,55 @@
+/**
+ * T15 — CA leaf RENEWAL (INV14). Re-signs a short-TTL leaf for an already-bound, non-revoked host
+ * under the current intermediate. SAME guards as T8 `signHostLeaf`: (1) CSR proof-of-possession
+ * against the embedded pubkey; (2) embedded pubkey == the host's registered `agent_pubkey`;
+ * (3) host active/non-revoked. Any failure → same reject path. A drained/revoked host cannot renew
+ * (closes the INV12+INV14 loop). Signing = `CaSigner.sign()` (KMS, §3.1), never a raw key.
+ * Distinct file from T8 (`ca/sign.ts`) — shares only the KMS-signer primitive.
+ */
+import type { HostStore } from '../store/ports.js'
+import type { CaSigner } from '../boot/ca-wiring.js'
+import { verifyCsrPoP } from './csr.js'
+import { LeafSignError } from './sign.js'
+import { timingSafeEqualBytes, bytesToBase64 } from '../util/bytes.js'
+
+export interface LeafRenewerDeps {
+  readonly hosts: HostStore
+  readonly signer: CaSigner
+  readonly caChainDer: readonly Uint8Array[]
+  readonly leafTtlSec?: number
+}
+
+export interface LeafRenewer {
+  renewHostLeaf(
+    hostId: string,
+    csr: Uint8Array,
+  ): Promise<{ cert: Uint8Array; caChain: readonly Uint8Array[] }>
+}
+
+const DEFAULT_LEAF_TTL_SEC = 24 * 60 * 60
+
+export function createLeafRenewer(deps: LeafRenewerDeps): LeafRenewer {
+  const ttl = deps.leafTtlSec ?? DEFAULT_LEAF_TTL_SEC
+  return {
+    async renewHostLeaf(hostId, csr) {
+      const host = await deps.hosts.get(hostId)
+      // A revoked/absent host cannot renew (INV12 + INV14).
+      if (host === null || host.status === 'revoked') throw new LeafSignError('not_registered')
+
+      const pop = verifyCsrPoP(csr)
+      if (!pop.ok) throw new LeafSignError('csr_rejected')
+      // embedded pubkey must equal the host's REGISTERED pubkey (no key substitution on renewal).
+      if (!timingSafeEqualBytes(pop.embeddedPub, host.agentPubkey)) throw new LeafSignError('csr_rejected')
+
+      const notAfter = Math.floor(Date.now() / 1000) + ttl
+      const tbs = new TextEncoder().encode(
+        JSON.stringify({ v: 1, hostId, subjectSpki: bytesToBase64(host.agentPubkey), notAfter, renewed: true }),
+      )
+      const sig = await deps.signer.sign(tbs) // KMS sign(); no raw key
+      const cert = new TextEncoder().encode(
+        JSON.stringify({ tbs: bytesToBase64(tbs), sig: bytesToBase64(sig) }),
+      )
+      return { cert, caChain: deps.caChainDer }
+    },
+  }
+}

control-plane/src/ca/sign.ts

@@ -0,0 +1,70 @@
+/**
+ * T8 — bind-time mTLS leaf signer, registry-gated (INV14 registry half). ORDER OF CHECKS (all
+ * must pass, SAME reject path):
+ *   1. CSR proof-of-possession — verify the CSR self-signature against its embedded pubkey.
+ *   2. embedded pubkey == caller-supplied `agentPubkey` (no substitution).
+ *   3. (hostId, agentPubkey) is an ACTIVE, non-revoked row in the host registry.
+ * A failure at ANY step rejects identically; the KMS `sign()` is NEVER invoked when any check
+ * fails. Signing itself is `CaSigner.sign()` (KMS, §3.1) — never a raw private key in memory.
+ */
+import type { HostStore } from '../store/ports.js'
+import type { CaSigner } from '../boot/ca-wiring.js'
+import { verifyCsrPoP } from './csr.js'
+import { timingSafeEqualBytes, bytesToBase64 } from '../util/bytes.js'
+
+export class LeafSignError extends Error {
+  constructor(public readonly code: 'csr_rejected' | 'not_registered') {
+    super('leaf signing refused') // uniform message — do not leak which check failed
+  }
+}
+
+export interface LeafSignerDeps {
+  readonly hosts: HostStore
+  readonly signer: CaSigner
+  readonly caChainDer: readonly Uint8Array[]
+  /** Leaf validity in seconds (short-lived, INV14). Default 24h. */
+  readonly leafTtlSec?: number
+}
+
+export interface LeafSigner {
+  signHostLeaf(
+    hostId: string,
+    agentPubkey: Uint8Array,
+    csr: Uint8Array,
+  ): Promise<{ cert: Uint8Array; caChain: readonly Uint8Array[] }>
+}
+
+const DEFAULT_LEAF_TTL_SEC = 24 * 60 * 60
+
+export function createLeafSigner(deps: LeafSignerDeps): LeafSigner {
+  const ttl = deps.leafTtlSec ?? DEFAULT_LEAF_TTL_SEC
+  return {
+    async signHostLeaf(hostId, agentPubkey, csr) {
+      // 1. proof-of-possession (independent of registry state)
+      const pop = verifyCsrPoP(csr)
+      if (!pop.ok) throw new LeafSignError('csr_rejected')
+      // 2. no substitution: CSR pubkey must equal the presented agentPubkey
+      if (!timingSafeEqualBytes(pop.embeddedPub, agentPubkey)) throw new LeafSignError('csr_rejected')
+      // 3. registry gate: host bound, active, non-revoked, pubkey matches (INV14)
+      const host = await deps.hosts.get(hostId)
+      if (host === null || host.status === 'revoked') throw new LeafSignError('not_registered')
+      if (!timingSafeEqualBytes(host.agentPubkey, agentPubkey)) throw new LeafSignError('not_registered')
+
+      // Only now do we invoke KMS sign() over the to-be-signed leaf.
+      const notAfter = Math.floor(Date.now() / 1000) + ttl
+      const tbs = new TextEncoder().encode(
+        JSON.stringify({
+          v: 1,
+          hostId,
+          subjectSpki: bytesToBase64(agentPubkey), // subject pubkey == agentPubkey (assertable in tests)
+          notAfter,
+        }),
+      )
+      const sig = await deps.signer.sign(tbs)
+      const cert = new TextEncoder().encode(
+        JSON.stringify({ tbs: bytesToBase64(tbs), sig: bytesToBase64(sig) }),
+      )
+      return { cert, caChain: deps.caChainDer }
+    },
+  }
+}

control-plane/src/db/pool.ts

@@ -0,0 +1,31 @@
+/**
+ * T2 — Postgres pool + typed `query` wrapper. PARAMETERIZED ONLY: the wrapper accepts
+ * `(sql, params)` and passes params to the driver separately — there is NO string-interpolation
+ * path, so SQL injection via value concatenation is structurally impossible (INV5-adjacent, §7).
+ *
+ * The client is injected (`Queryable`) so the wrapper is unit-testable without a live DB; the real
+ * `pg.Pool` is constructed by `createPgPool`. Applying the migrations + mapping the repository ports
+ * to SQL over this wrapper is the Testcontainers integration seam (PLAN §10).
+ */
+import pg from 'pg'
+
+/** Minimal driver surface the wrapper needs — satisfied by `pg.Pool` and `pg.PoolClient`. */
+export interface Queryable {
+  query(text: string, params: readonly unknown[]): Promise<{ rows: unknown[] }>
+}
+
+export type QueryFn = <T>(sql: string, params: readonly unknown[]) => Promise<readonly T[]>
+
+/** Build a parameterized-only query function over any `Queryable`. */
+export function createQuery(client: Queryable): QueryFn {
+  return async <T>(sql: string, params: readonly unknown[]): Promise<readonly T[]> => {
+    // Params ALWAYS travel separately from the SQL text — never interpolated into it.
+    const result = await client.query(sql, params)
+    return result.rows as T[]
+  }
+}
+
+/** Construct a real Postgres connection pool (production). */
+export function createPgPool(connectionString: string): pg.Pool & Queryable {
+  return new pg.Pool({ connectionString })
+}

control-plane/src/deprovision/deprovision.ts

@@ -0,0 +1,34 @@
+/**
+ * T11 — v0.9 MINIMAL deprovision (self-contained; superseded by T13 fast path in v0.10). Requires
+ * `ownsHost(principal.accountId, hostId)` (INV1/INV6), then `setHostStatus('revoked')` (T4 versioned
+ * snapshot) + `dropRoute` (T9). Best-effort tunnel drop only — NOT the INV12 within-seconds
+ * guarantee (that is T13's `revokeHost`). Depends on T4 + T9 ONLY; no dependency on v0.10.
+ */
+import type { HostRegistry } from '../registry/hosts.js'
+import type { RoutingTable } from '../routing/table.js'
+import type { AdminPrincipal } from '../api/authz.js'
+import { AuthzError } from '../api/authz.js'
+
+export interface Deprovisioner {
+  deprovisionHost(principal: AdminPrincipal, hostId: string): Promise<void>
+}
+
+export interface DeprovisionDeps {
+  readonly hosts: HostRegistry
+  readonly routing: RoutingTable
+}
+
+export function createDeprovisioner(deps: DeprovisionDeps): Deprovisioner {
+  return {
+    async deprovisionHost(principal, hostId) {
+      if (!(await deps.hosts.ownsHost(principal.accountId, hostId))) {
+        throw new AuthzError(403, 'not authorized for this host') // INV1: 403, never a 404 leak
+      }
+      const host = await deps.hosts.getHost(hostId)
+      if (host !== null && host.status !== 'revoked') {
+        await deps.hosts.setHostStatus(hostId, 'revoked')
+      }
+      await deps.routing.systemDropRoute(hostId)
+    },
+  }
+}

control-plane/src/env.ts

@@ -0,0 +1,96 @@
+/**
+ * T1 — startup config/secret validation (INV9): secrets come from env/secret-manager,
+ * are Zod-validated at startup, fail fast, and are NEVER logged (only key NAMES on failure).
+ *
+ * The CA intermediate signing key is referenced by a KMS/HSM ref only — never inlined,
+ * never loaded raw into process memory (§3.1). The KMS key-policy check runs in
+ * `boot/ca-wiring.ts` (T15 `buildCaSigner`) with an injected resolver, because it needs a
+ * live KMS call; `loadEnv` validates only the presence/shape of the ref here.
+ */
+import { z } from 'zod'
+import { base64ToBytes } from './util/bytes.js'
+
+/** Pairing-code TTL default: 10 minutes (§5 T7). */
+export const DEFAULT_PAIRING_TTL_SEC = 600
+/** Per-code redemption lockout threshold default (§5 T7/T8). */
+export const DEFAULT_PAIRING_MAX_REDEEM_ATTEMPTS = 5
+
+export interface ControlPlaneEnv {
+  readonly pgUrl: string
+  readonly redisUrl: string
+  /** P5 signing PUBLIC key, used to VERIFY admin capability tokens (INV3). */
+  readonly capabilitySignPubkey: Uint8Array
+  /** KMS/HSM key REF for the non-exportable intermediate leaf-signing key (§3.1). */
+  readonly caIntermediateKmsKeyRef: string
+  /** Intermediate cert (public) + chain up to the offline root. */
+  readonly caIntermediateCertPath: string
+  /** CA bundle used to VERIFY relay-node mTLS client certs (T9 node-auth). */
+  readonly nodeMtlsTrustBundlePath: string
+  /** 'term.<domain>' for subdomain assembly. */
+  readonly baseDomain: string
+  readonly heartbeatTtlSec: number
+  readonly pairingTtlSec: number
+  readonly pairingMaxRedeemAttempts: number
+}
+
+/** A positive integer parsed from an env string, or a default when unset/empty. */
+const intWithDefault = (fallback: number) =>
+  z
+    .string()
+    .trim()
+    .optional()
+    .transform((v) => (v === undefined || v === '' ? String(fallback) : v))
+    .pipe(z.coerce.number().int().positive())
+
+const requiredString = (name: string) =>
+  z.string({ required_error: `${name} is required` }).trim().min(1, `${name} must not be empty`)
+
+const EnvSchema = z.object({
+  PG_URL: requiredString('PG_URL').url('PG_URL must be a valid connection URL'),
+  REDIS_URL: requiredString('REDIS_URL').url('REDIS_URL must be a valid connection URL'),
+  CAPABILITY_SIGN_PUBKEY_B64: requiredString('CAPABILITY_SIGN_PUBKEY_B64'),
+  CA_INTERMEDIATE_KMS_KEY_REF: requiredString('CA_INTERMEDIATE_KMS_KEY_REF'),
+  CA_INTERMEDIATE_CERT_PATH: requiredString('CA_INTERMEDIATE_CERT_PATH'),
+  NODE_MTLS_TRUST_BUNDLE_PATH: requiredString('NODE_MTLS_TRUST_BUNDLE_PATH'),
+  BASE_DOMAIN: requiredString('BASE_DOMAIN'),
+  HEARTBEAT_TTL_SEC: intWithDefault(15),
+  PAIRING_TTL_SEC: intWithDefault(DEFAULT_PAIRING_TTL_SEC),
+  PAIRING_MAX_REDEEM_ATTEMPTS: intWithDefault(DEFAULT_PAIRING_MAX_REDEEM_ATTEMPTS),
+})
+
+/**
+ * Parse + validate control-plane config. THROWS (fail-fast) listing every missing/invalid
+ * key by NAME. Never echoes secret VALUES (INV9).
+ */
+export function loadEnv(source: NodeJS.ProcessEnv): ControlPlaneEnv {
+  const parsed = EnvSchema.safeParse(source)
+  if (!parsed.success) {
+    const problems = parsed.error.issues
+      .map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`)
+      .join('; ')
+    // Only key names + messages — never values (INV9).
+    throw new Error(`Invalid control-plane env: ${problems}`)
+  }
+  const e = parsed.data
+  let capabilitySignPubkey: Uint8Array
+  try {
+    capabilitySignPubkey = base64ToBytes(e.CAPABILITY_SIGN_PUBKEY_B64)
+  } catch {
+    throw new Error('Invalid control-plane env: CAPABILITY_SIGN_PUBKEY_B64 is not valid base64')
+  }
+  if (capabilitySignPubkey.length !== 32) {
+    throw new Error('Invalid control-plane env: CAPABILITY_SIGN_PUBKEY_B64 must decode to 32 bytes (Ed25519)')
+  }
+  return {
+    pgUrl: e.PG_URL,
+    redisUrl: e.REDIS_URL,
+    capabilitySignPubkey,
+    caIntermediateKmsKeyRef: e.CA_INTERMEDIATE_KMS_KEY_REF,
+    caIntermediateCertPath: e.CA_INTERMEDIATE_CERT_PATH,
+    nodeMtlsTrustBundlePath: e.NODE_MTLS_TRUST_BUNDLE_PATH,
+    baseDomain: e.BASE_DOMAIN,
+    heartbeatTtlSec: e.HEARTBEAT_TTL_SEC,
+    pairingTtlSec: e.PAIRING_TTL_SEC,
+    pairingMaxRedeemAttempts: e.PAIRING_MAX_REDEEM_ATTEMPTS,
+  }
+}

control-plane/src/flat-store.ts

@@ -0,0 +1,71 @@
+/**
+ * T0 (v0.8 MVP) — flat account store + manual provisioning. Deliberately minimal: no
+ * immutable-record ceremony (that arrives in CP1/T3-T4, which RETIRE this shim). It exists
+ * only to gate the café demo. All INV5 guarantees (hashes-at-rest, constant-time compare,
+ * raw-secret-returned-once) are honoured and re-shipped properly in CP1.
+ *
+ * Backing store is injectable. The default is in-memory; production points it at the
+ * `db/flat.sqlite.sql` schema (SQLite) — an integration seam, not exercised in unit tests.
+ */
+import { randomUUID, randomBytes } from 'node:crypto'
+import { hashSecret, verifySecret } from './util/hash.js'
+
+export interface FlatAccount {
+  readonly accountId: string
+  readonly subdomain: string
+  readonly agentTokenHash: string
+  readonly clientTokenHash: string
+}
+
+export interface FlatBackend {
+  insert(row: FlatAccount): Promise<void>
+  bySubdomain(subdomain: string): Promise<FlatAccount | null>
+}
+
+/** In-memory backend (default). SQLite backend is the production swap (see db/flat.sqlite.sql). */
+export function inMemoryFlatBackend(): FlatBackend {
+  const rows = new Map<string, FlatAccount>()
+  return {
+    async insert(row) {
+      if (rows.has(row.subdomain)) throw new Error(`subdomain already provisioned: ${row.subdomain}`)
+      rows.set(row.subdomain, row)
+    },
+    async bySubdomain(subdomain) {
+      return rows.get(subdomain) ?? null
+    },
+  }
+}
+
+export interface FlatStore {
+  provisionFlat(subdomain: string): Promise<{ accountId: string; agentToken: string; clientToken: string }>
+  lookupBySubdomain(subdomain: string): Promise<FlatAccount | null>
+  verifyAgentToken(subdomain: string, raw: string): Promise<boolean>
+}
+
+const newToken = (): string => randomBytes(32).toString('base64url')
+
+export function createFlatStore(backend: FlatBackend = inMemoryFlatBackend()): FlatStore {
+  return {
+    async provisionFlat(subdomain) {
+      const agentToken = newToken()
+      const clientToken = newToken()
+      const row: FlatAccount = {
+        accountId: randomUUID(),
+        subdomain,
+        agentTokenHash: hashSecret(agentToken), // hash at rest — raw discarded (INV5)
+        clientTokenHash: hashSecret(clientToken),
+      }
+      await backend.insert(row)
+      // Raw tokens returned exactly ONCE at mint time; never persisted.
+      return { accountId: row.accountId, agentToken, clientToken }
+    },
+    async lookupBySubdomain(subdomain) {
+      return backend.bySubdomain(subdomain)
+    },
+    async verifyAgentToken(subdomain, raw) {
+      const row = await backend.bySubdomain(subdomain)
+      if (row === null) return false
+      return verifySecret(raw, row.agentTokenHash) // constant-time compare of hashes
+    },
+  }
+}

control-plane/src/main.ts

@@ -0,0 +1,103 @@
+/**
+ * T11 — control-plane bootstrap. Wires env → stores → services → Fastify routes. The runnable
+ * v0.9-MVP default uses the in-memory stores; swapping in the Postgres/Redis-backed adapters
+ * (db/pool.ts + db/migrations + an ioredis client) is the Testcontainers integration step (PLAN §10).
+ *
+ * CROSS-PACKAGE INTEGRATION POINTS (injected, not hard-imported):
+ *   - `CapabilityVerifier` — P5 owns `verifyCapabilityToken` + the signing key. Injected here; the
+ *     default stub REFUSES all tokens (fail-closed) until P5 is wired.
+ *   - `RevocationBus` — publish side over Redis `relay:revocations` (P1 subscribes). Default is the
+ *     in-memory bus for single-process dev.
+ *   - `KmsResolver` — P5/§3.1 KMS custody of the CA intermediate key. Default is an in-process
+ *     Ed25519 signer (DEV ONLY — NOT a real KMS).
+ */
+import Fastify, { type FastifyInstance } from 'fastify'
+import type { ControlPlaneEnv } from './env.js'
+import { createMemoryStores } from './store/memory.js'
+import type { Stores } from './store/ports.js'
+import { createAuditLog } from './audit/log.js'
+import { createAccountRegistry } from './registry/accounts.js'
+import { createHostRegistry } from './registry/hosts.js'
+import { createSessionRegistry } from './registry/sessions.js'
+import { createSubdomainAssigner } from './subdomain/assign.js'
+import { createPairingIssuer } from './pairing/issue.js'
+import { createPairingRedeemer } from './pairing/redeem.js'
+import { createLeafSigner } from './ca/sign.js'
+import { createRoutingTable } from './routing/table.js'
+import { createInMemoryRevocationBus, type TestableRevocationBus } from './routing/bus.js'
+import { createMeteringCollector } from './metering/collect.js'
+import { createDeprovisioner } from './deprovision/deprovision.js'
+import { createAuthorizer, type CapabilityVerifier } from './api/authz.js'
+import { buildRouter } from './api/provision.js'
+import { buildCaSigner, inProcessCaSigner, type KmsResolver } from './boot/ca-wiring.js'
+import type { RevocationBus } from 'relay-contracts'
+
+export interface ControlPlaneOverrides {
+  readonly stores?: Stores
+  readonly verifier?: CapabilityVerifier
+  readonly bus?: RevocationBus & Partial<TestableRevocationBus>
+  readonly kmsResolver?: KmsResolver
+  readonly caChainDer?: readonly Uint8Array[]
+}
+
+/** Default fail-closed verifier — refuses everything until P5 is wired (INV6). */
+const refuseAllVerifier: CapabilityVerifier = {
+  verify() {
+    throw new Error('capability verification not configured (P5 integration point)')
+  },
+}
+
+/** In-process KMS resolver — DEV ONLY. Production injects a real non-exportable KMS key (§3.1). */
+function devKmsResolver(): KmsResolver {
+  const signer = inProcessCaSigner()
+  return {
+    async resolve() {
+      return { signer, policyRestrictedToServicePrincipal: true }
+    },
+  }
+}
+
+export async function buildControlPlane(
+  env: ControlPlaneEnv,
+  overrides: ControlPlaneOverrides = {},
+): Promise<{ app: FastifyInstance; stores: Stores }> {
+  const stores = overrides.stores ?? createMemoryStores()
+  const bus: RevocationBus = overrides.bus ?? createInMemoryRevocationBus()
+  const caChainDer = overrides.caChainDer ?? []
+
+  const audit = createAuditLog(stores.audit)
+  const accounts = createAccountRegistry({ accounts: stores.accounts, audit })
+  const hosts = createHostRegistry({ hosts: stores.hosts, audit })
+  createSessionRegistry({ sessions: stores.sessions, hosts: stores.hosts })
+  const subdomains = createSubdomainAssigner({ subdomains: stores.subdomains, audit })
+
+  const caSigner = await buildCaSigner(env, overrides.kmsResolver ?? devKmsResolver())
+  const leafSigner = createLeafSigner({ hosts: stores.hosts, signer: caSigner, caChainDer })
+
+  const pairingIssuer = createPairingIssuer({ pairing: stores.pairing, pairingTtlSec: env.pairingTtlSec, audit })
+  const redeemer = createPairingRedeemer({
+    pairing: stores.pairing,
+    hosts,
+    subdomains,
+    leafSigner,
+    pairingMaxRedeemAttempts: env.pairingMaxRedeemAttempts,
+    audit,
+  })
+
+  const routing = createRoutingTable({
+    routes: stores.routes,
+    nodeStatus: async (nodeId) => (await stores.nodes.get(nodeId))?.status ?? null,
+  })
+  createMeteringCollector({ metering: stores.metering, hosts })
+  const deprovisioner = createDeprovisioner({ hosts, routing })
+  void bus // reserved for the node-coordinator / revoker wiring (drain + revoke publishers)
+
+  const authorizer = createAuthorizer({
+    verifier: overrides.verifier ?? refuseAllVerifier,
+    expectedAud: env.baseDomain,
+  })
+
+  const app = Fastify({ logger: false })
+  await app.register(buildRouter({ authorizer, accounts, hosts, pairingIssuer, redeemer, deprovisioner }))
+  return { app, stores }
+}

control-plane/src/metering/collect.ts

@@ -0,0 +1,86 @@
+/**
+ * T12 — billing-metering hooks (EXPLORE §6): meter PAIRED HOSTS + CONCURRENT VIEWERS (not
+ * bandwidth). The sample's `nodeId` is the caller's authenticated mTLS identity (INV3-analog) and
+ * its `accountId` is re-derived SERVER-SIDE from the host registry (INV1) — a node-supplied account
+ * is never trusted. Samples are append-only immutable rows (INV8); zero terminal payload (INV10).
+ */
+import { z } from 'zod'
+import type { MeteringSampleRow } from '../model/records.js'
+import type { MeteringStore } from '../store/ports.js'
+import type { HostRegistry } from '../registry/hosts.js'
+import type { NodeIdentity } from '../node-auth/identity.js'
+
+export interface MeteringSample {
+  readonly hostId: string
+  readonly concurrentViewers: number
+  readonly sampledAt: string
+  // NO client/node-supplied accountId or nodeId — both are derived server-side.
+}
+
+const MeteringSampleSchema = z
+  .object({
+    hostId: z.string().uuid(),
+    concurrentViewers: z.number().int().nonnegative(),
+    sampledAt: z.string().datetime({ offset: true }),
+  })
+  .strict()
+
+export class MeteringError extends Error {}
+
+export interface UsageRollup {
+  readonly pairedHostPeak: number
+  readonly viewerPeak: number
+  readonly viewerHours: number
+}
+
+export interface MeteringCollector {
+  ingestSample(caller: NodeIdentity, sample: MeteringSample): Promise<void>
+  pairedHostCount(accountId: string): Promise<number>
+  rollupUsage(accountId: string, from: string, to: string): Promise<UsageRollup>
+}
+
+export interface MeteringDeps {
+  readonly metering: MeteringStore
+  readonly hosts: HostRegistry
+}
+
+export function createMeteringCollector(deps: MeteringDeps): MeteringCollector {
+  return {
+    async ingestSample(caller, sample) {
+      const parsed = MeteringSampleSchema.safeParse(sample)
+      if (!parsed.success) throw new MeteringError(`invalid metering sample: ${parsed.error.issues[0]?.message}`)
+      const host = await deps.hosts.getHost(parsed.data.hostId)
+      // Attribution derived from ownership — a hostId the caller can't substantiate is rejected (INV1).
+      if (host === null) throw new MeteringError('unknown hostId — cannot attribute usage')
+      const row: MeteringSampleRow = {
+        hostId: parsed.data.hostId,
+        accountId: host.accountId, // server-derived, never node-asserted
+        nodeId: caller.nodeId, // authenticated identity, never a body field
+        concurrentViewers: parsed.data.concurrentViewers,
+        sampledAt: parsed.data.sampledAt,
+      }
+      await deps.metering.append(row) // append-only (INV8)
+    },
+    async pairedHostCount(accountId) {
+      const hosts = await deps.hosts.listHosts(accountId)
+      return hosts.filter((h) => h.status !== 'revoked').length
+    },
+    async rollupUsage(accountId, from, to) {
+      const samples = [...(await deps.metering.query(accountId, from, to))].sort(
+        (a, b) => Date.parse(a.sampledAt) - Date.parse(b.sampledAt),
+      )
+      const viewerPeak = samples.reduce((m, s) => Math.max(m, s.concurrentViewers), 0)
+      const distinctHosts = new Set(samples.map((s) => s.hostId))
+      // Step-function integral of concurrent viewers over the window → viewer-hours.
+      const toMs = Date.parse(to)
+      let viewerHours = 0
+      for (let i = 0; i < samples.length; i++) {
+        const cur = samples[i] as MeteringSampleRow
+        const nextMs = i + 1 < samples.length ? Date.parse((samples[i + 1] as MeteringSampleRow).sampledAt) : toMs
+        const spanHours = Math.max(0, nextMs - Date.parse(cur.sampledAt)) / 3_600_000
+        viewerHours += cur.concurrentViewers * spanHours
+      }
+      return { pairedHostPeak: distinctHosts.size, viewerPeak, viewerHours }
+    },
+  }
+}

control-plane/src/model/records.ts

@@ -0,0 +1,49 @@
+/**
+ * T2 — control-plane record types. The frozen §4.2/§4.5 shapes are RE-EXPORTED from
+ * relay-contracts, never redefined locally (INDEX §2 rule 1).
+ *
+ * OQ1 RESOLUTION: `AccountRecord`/`SessionRecord`/`PairingCodeRecord` were promoted into
+ * relay-contracts (`model/account.ts`, `pairing/enroll.ts`), so this module re-exports them
+ * instead of mirroring the SQL locally. The only P3-local additions are the INV8 companion
+ * status-version ROW types (OQ6 — pending INDEX promotion of the `*_status_versions` tables).
+ */
+export type {
+  AccountRecord,
+  AccountStatus,
+  SessionRecord,
+  HostRecord,
+  HostStatus,
+  PlanTier,
+  RouteEntry,
+} from 'relay-contracts'
+export type { PairingCodeRecord, EnrollResult } from 'relay-contracts'
+
+import type { AccountStatus, HostStatus } from 'relay-contracts'
+
+/** Append-only companion row for `accounts.status` versioning (INV8, OQ6). */
+export interface AccountStatusVersionRow {
+  readonly accountId: string
+  readonly version: number
+  readonly status: AccountStatus
+  readonly changedAt: string
+  readonly changedBy: string
+}
+
+/** Append-only companion row for `hosts.status`/`revoked_at` versioning (INV8, OQ6). */
+export interface HostStatusVersionRow {
+  readonly hostId: string
+  readonly version: number
+  readonly status: HostStatus
+  readonly revokedAt: string | null
+  readonly changedAt: string
+  readonly changedBy: string
+}
+
+/** Immutable metering sample row (append-only, INV8). */
+export interface MeteringSampleRow {
+  readonly hostId: string
+  readonly accountId: string
+  readonly nodeId: string
+  readonly concurrentViewers: number
+  readonly sampledAt: string
+}

control-plane/src/node-auth/identity.ts

@@ -0,0 +1,56 @@
+/**
+ * T9 — relay-node ↔ control-plane trust boundary (the node analog of INV3). `nodeId` is derived
+ * from the VERIFIED relay-node mTLS client-cert subject — NEVER from a body/query/header field.
+ * A request that carries a `nodeId` payload has it IGNORED for identity. Non-mutually-authenticated
+ * connections throw 401.
+ *
+ * OQ5 (open): who ISSUES/ROTATES the node service certs + the SVID format the CP pins
+ * (`nodeMtlsTrustBundlePath`) is a P5/P1 boundary. Here we consume an already-verified peer cert.
+ */
+export interface NodeIdentity {
+  readonly nodeId: string
+}
+
+export class NodeAuthError extends Error {
+  readonly status = 401
+  constructor(message: string) {
+    super(message)
+  }
+}
+
+/** The shape we need from a verified TLS peer certificate (subset of Node's PeerCertificate). */
+export interface VerifiedPeerCert {
+  readonly authorized: boolean // TLS stack verified the client cert against the trust bundle
+  readonly subjectCommonName: string | null // SPIFFE-style node id in the cert subject CN / SAN URI
+}
+
+/** Pure derivation — the request wrapper below feeds it the extracted peer cert. */
+export function deriveNodeIdentity(cert: VerifiedPeerCert | null): NodeIdentity {
+  if (cert === null || !cert.authorized) {
+    throw new NodeAuthError('relay-node connection is not mutually authenticated')
+  }
+  const cn = cert.subjectCommonName
+  if (cn === null || cn.trim() === '') {
+    throw new NodeAuthError('relay-node client cert has no subject identity')
+  }
+  return { nodeId: cn }
+}
+
+/** Minimal request shape carrying a TLS socket (Fastify/Node). */
+export interface RequestWithTls {
+  readonly socket: {
+    authorized?: boolean
+    getPeerCertificate?: () => { subject?: { CN?: string } } | undefined
+  }
+}
+
+/**
+ * Extract the verified node identity from a live request's TLS session. INTEGRATION SEAM: the
+ * exact SAN/URI SVID parsing is finalized with OQ5; here we read authorized + subject CN.
+ */
+export function nodeIdentityFromRequest(req: RequestWithTls): NodeIdentity {
+  const authorized = req.socket.authorized === true
+  const peer = req.socket.getPeerCertificate?.()
+  const cn = peer?.subject?.CN ?? null
+  return deriveNodeIdentity({ authorized, subjectCommonName: cn })
+}

control-plane/src/pairing/code.ts

@@ -0,0 +1,41 @@
+/**
+ * Pairing-code format (Finding-4). The code is the SOLE credential gating `/enroll`, so it is
+ * 26 Crockford-base32 characters = 130 bits of real entropy (NOT the ~32-bit `ABCD-1234` shape,
+ * which is rejected). Displayed grouped for humans as 6 dash-separated groups; a paste/QR-first
+ * credential, not a type-from-memory PIN.
+ */
+import { randomBytes } from 'node:crypto'
+
+/** Crockford base32 alphabet (excludes I L O U to avoid confusion). */
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'
+export const PAIRING_CODE_LEN = 26 // 26 * 5 bits = 130 bits
+export const PAIRING_CODE_BITS = PAIRING_CODE_LEN * 5
+
+/** Generate a canonical (undashed, uppercase) 26-char Crockford code. */
+export function generatePairingCode(): string {
+  // Draw enough random bytes, map 5 bits per char.
+  const bytes = randomBytes(PAIRING_CODE_LEN)
+  let out = ''
+  for (let i = 0; i < PAIRING_CODE_LEN; i++) {
+    out += CROCKFORD[(bytes[i] as number) & 0x1f]
+  }
+  return out
+}
+
+/** Group the canonical code for display: XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-X. */
+export function formatPairingCode(canonical: string): string {
+  return (canonical.match(/.{1,5}/g) ?? []).join('-')
+}
+
+/**
+ * Normalize a user-presented code back to canonical form: uppercase, strip dashes/spaces, map
+ * Crockford-confusable characters (I/L→1, O→0). Redemption hashes THIS canonical form.
+ */
+export function normalizePairingCode(raw: string): string {
+  return raw
+    .toUpperCase()
+    .replace(/[\s-]/g, '')
+    .replace(/[IL]/g, '1')
+    .replace(/O/g, '0')
+    .replace(/U/g, 'V')
+}

control-plane/src/pairing/issue.ts

@@ -0,0 +1,52 @@
+/**
+ * T7 — pairing-code issuance (INDEX §4.5 step 1). Mints a single-use short-TTL code; stores
+ * `{ code_hash, account_id, expires_at, redeem_attempts:0 }` — the RAW code is never stored
+ * (INV5). `accountId` comes from the authenticated principal (INV3), never a request field.
+ */
+import type { PairingCodeRecord } from '../model/records.js'
+import type { PairingStore } from '../store/ports.js'
+import type { AuditWriter } from '../audit/log.js'
+import { noopAuditWriter } from '../audit/log.js'
+import { generatePairingCode, formatPairingCode } from './code.js'
+import { sha256Hex } from '../util/hash.js'
+import { nowIso } from '../util/ids.js'
+
+export interface IssuedPairing {
+  readonly code: string // display-grouped, returned ONCE
+  readonly expiresAt: string
+}
+
+export interface PairingIssuer {
+  issuePairingCode(accountId: string): Promise<IssuedPairing>
+}
+
+export interface PairingIssuerDeps {
+  readonly pairing: PairingStore
+  readonly pairingTtlSec: number
+  readonly audit?: AuditWriter
+  readonly actor?: string
+}
+
+export function createPairingIssuer(deps: PairingIssuerDeps): PairingIssuer {
+  const audit = deps.audit ?? noopAuditWriter()
+  const actor = deps.actor ?? 'system'
+  return {
+    async issuePairingCode(accountId) {
+      const canonical = generatePairingCode()
+      const codeHash = sha256Hex(canonical) // deterministic hash of a 130-bit input (INV5)
+      const expiresAt = new Date(Date.now() + deps.pairingTtlSec * 1000).toISOString()
+      const record: PairingCodeRecord = { codeHash, accountId, expiresAt, redeemedAt: null }
+      await deps.pairing.insert(record)
+      await audit.writeAuditEvent({
+        action: 'pairing.issue',
+        principalId: actor,
+        accountId,
+        hostId: null,
+        ts: nowIso(),
+        meta: { expiresAt },
+      })
+      // Raw code returned ONCE, display-grouped; never persisted.
+      return { code: formatPairingCode(canonical), expiresAt }
+    },
+  }
+}

control-plane/src/pairing/redeem.ts

@@ -0,0 +1,131 @@
+/**
+ * T8 — pairing-code redemption + BIND + bind-time cert + content-secret mint (INDEX §4.5 3–5).
+ * ATOMIC single-use: `casRedeem` compare-and-sets `redeemed_at` so exactly one concurrent caller
+ * wins (no double-spend). A CODE-SCOPED lockout (Finding-4) counts failed redemptions per
+ * `code_hash` and locks after `pairingMaxRedeemAttempts` — independent of P5's per-tenant limiter.
+ * `accountId` is taken from the pairing ROW (INV3), never the agent's request. Returns the FROZEN
+ * `EnrollResult` (imported from relay-contracts, never redefined).
+ */
+import type { EnrollResult } from 'relay-contracts'
+import type { PairingStore } from '../store/ports.js'
+import type { HostRegistry } from '../registry/hosts.js'
+import type { SubdomainAssigner } from '../subdomain/assign.js'
+import type { LeafSigner } from '../ca/sign.js'
+import type { AuditWriter } from '../audit/log.js'
+import { noopAuditWriter } from '../audit/log.js'
+import { verifyCsrPoP } from '../ca/csr.js'
+import { fingerprint } from '../ca/fingerprint.js'
+import { sha256Hex } from '../util/hash.js'
+import { timingSafeEqualBytes, bytesToBase64 } from '../util/bytes.js'
+import { sealToX25519 } from '../util/crypto.js'
+import { normalizePairingCode } from './code.js'
+import { nowIso } from '../util/ids.js'
+import { randomBytes } from 'node:crypto'
+
+export type RedeemErrorCode =
+  | 'unknown'
+  | 'expired'
+  | 'already_redeemed'
+  | 'too_many_attempts'
+  | 'bad_csr'
+
+export class RedeemError extends Error {
+  constructor(public readonly code: RedeemErrorCode) {
+    super(`pairing redemption refused: ${code}`)
+  }
+}
+
+export interface RedeemInput {
+  readonly code: string
+  readonly agentPubkey: Uint8Array
+  readonly csr: Uint8Array
+}
+
+/**
+ * FIX 3 — mint + WRAP the host-scoped content secret at BIND. A per-host 32-byte CSPRNG secret
+ * is sealed to the host's enrolled identity; the raw secret is NEVER stored or logged (INV5/INV9)
+ * and each wrap is distinct (per-host revocable, INV12). P2 unwraps locally with its private key.
+ */
+export async function mintHostContentSecret(agentPubkey: Uint8Array): Promise<Uint8Array> {
+  const secret = new Uint8Array(randomBytes(32))
+  const wrapped = sealToX25519(agentPubkey, secret)
+  secret.fill(0) // best-effort scrub of the raw secret
+  return wrapped
+}
+
+export interface RedeemDeps {
+  readonly pairing: PairingStore
+  readonly hosts: HostRegistry
+  readonly subdomains: SubdomainAssigner
+  readonly leafSigner: LeafSigner
+  readonly pairingMaxRedeemAttempts: number
+  readonly audit?: AuditWriter
+  /** Injectable content-secret minter (test seam); defaults to `mintHostContentSecret`. */
+  readonly mintSecret?: (agentPubkey: Uint8Array) => Promise<Uint8Array>
+}
+
+export interface PairingRedeemer {
+  redeemPairingCode(input: RedeemInput): Promise<EnrollResult>
+}
+
+function toPem(label: string, der: Uint8Array): string {
+  const b64 = bytesToBase64(der)
+  const lines = b64.match(/.{1,64}/g) ?? [b64]
+  return `-----BEGIN ${label}-----\n${lines.join('\n')}\n-----END ${label}-----\n`
+}
+
+export function createPairingRedeemer(deps: RedeemDeps): PairingRedeemer {
+  const audit = deps.audit ?? noopAuditWriter()
+  const mint = deps.mintSecret ?? mintHostContentSecret
+  return {
+    async redeemPairingCode(input) {
+      const codeHash = sha256Hex(normalizePairingCode(input.code))
+      const row = await deps.pairing.get(codeHash)
+      if (row === null) throw new RedeemError('unknown') // blind guess; P5 limiter covers volume
+
+      // Lockout FIRST — a locked code is refused even with a correct code (Finding-4).
+      if (row.redeemAttempts >= deps.pairingMaxRedeemAttempts) throw new RedeemError('too_many_attempts')
+      if (Date.parse(row.record.expiresAt) <= Date.now()) throw new RedeemError('expired')
+      if (row.record.redeemedAt !== null) throw new RedeemError('already_redeemed')
+
+      // CSR proof-of-possession + no-substitution. A failure counts toward the code-scoped lockout.
+      const pop = verifyCsrPoP(input.csr)
+      if (!pop.ok || !timingSafeEqualBytes(pop.embeddedPub, input.agentPubkey)) {
+        await deps.pairing.registerFailure(codeHash)
+        throw new RedeemError('bad_csr')
+      }
+
+      // Atomic single-use CAS (double-spend guard) — exactly one concurrent caller wins.
+      const cas = await deps.pairing.casRedeem(codeHash, nowIso())
+      if (cas !== 'ok') throw new RedeemError('already_redeemed')
+
+      const accountId = row.record.accountId // from the pairing row (INV3)
+      const subdomain = await deps.subdomains.assignSubdomain(accountId)
+      const host = await deps.hosts.bindHost({
+        accountId,
+        subdomain,
+        agentPubkey: input.agentPubkey,
+        enrollFpr: fingerprint(input.agentPubkey),
+      })
+      const leaf = await deps.leafSigner.signHostLeaf(host.hostId, input.agentPubkey, input.csr)
+      const hostContentSecret = await mint(input.agentPubkey)
+
+      await audit.writeAuditEvent({
+        action: 'pairing.redeem',
+        principalId: `host:${host.hostId}`,
+        accountId,
+        hostId: host.hostId,
+        ts: nowIso(),
+        meta: { subdomain },
+      })
+
+      return {
+        hostId: host.hostId,
+        subdomain,
+        cert: toPem('CERTIFICATE', leaf.cert),
+        caChain: leaf.caChain.map((der) => toPem('CERTIFICATE', der)).join(''),
+        hostContentSecret,
+      }
+    },
+  }
+}

control-plane/src/registry/accounts.ts

@@ -0,0 +1,63 @@
+/**
+ * T3 — account registry (immutable, INV8). `createAccount` writes a version-1 snapshot;
+ * `setAccountStatus` performs the atomic append-version + pointer-swap (prior snapshot stays
+ * readable from `versions()`). Never mutates a lifecycle field in place.
+ */
+import type { AccountRecord, AccountStatus } from '../model/records.js'
+import type { AccountStore } from '../store/ports.js'
+import type { AuditWriter } from '../audit/log.js'
+import { noopAuditWriter } from '../audit/log.js'
+import type { PlanTier } from 'relay-contracts'
+import { newUuid, nowIso } from '../util/ids.js'
+
+export interface AccountRegistry {
+  createAccount(plan: PlanTier): Promise<AccountRecord>
+  getAccount(accountId: string): Promise<AccountRecord | null>
+  setAccountStatus(accountId: string, status: AccountStatus): Promise<AccountRecord>
+}
+
+export interface AccountRegistryDeps {
+  readonly accounts: AccountStore
+  readonly audit?: AuditWriter
+  readonly actor?: string
+}
+
+export function createAccountRegistry(deps: AccountRegistryDeps): AccountRegistry {
+  const audit = deps.audit ?? noopAuditWriter()
+  const actor = deps.actor ?? 'system'
+  return {
+    async createAccount(plan) {
+      const rec: AccountRecord = {
+        accountId: newUuid(), // unguessable, never recycled (INV1 precondition)
+        plan,
+        createdAt: nowIso(),
+        status: 'active',
+      }
+      await deps.accounts.insert(rec)
+      await audit.writeAuditEvent({
+        action: 'account.create',
+        principalId: actor,
+        accountId: rec.accountId,
+        hostId: null,
+        ts: rec.createdAt,
+        meta: { plan },
+      })
+      return rec
+    },
+    async getAccount(accountId) {
+      return deps.accounts.get(accountId)
+    },
+    async setAccountStatus(accountId, status) {
+      const next = await deps.accounts.swapStatus(accountId, status, actor) // NEW snapshot, atomic swap
+      await audit.writeAuditEvent({
+        action: status === 'suspended' ? 'account.suspend' : 'manage',
+        principalId: actor,
+        accountId,
+        hostId: null,
+        ts: nowIso(),
+        meta: { status },
+      })
+      return next
+    },
+  }
+}

control-plane/src/registry/hosts.ts

@@ -0,0 +1,103 @@
+/**
+ * T4 — host registry: the ownership source of truth (INV1). A host is resolvable ONLY via
+ * `hostId`/`subdomain` bound to an account — there is NO raw address/port/hostname resolution
+ * path in this module. `ownsHost` is the deny-by-default ownership predicate (INV1/INV6). DB
+ * stores only the PUBLIC Ed25519 key (INV4). Status changes are versioned snapshots (INV8).
+ */
+import type { HostRecord, HostStatus } from '../model/records.js'
+import type { HostStore } from '../store/ports.js'
+import type { AuditWriter } from '../audit/log.js'
+import { noopAuditWriter } from '../audit/log.js'
+import { newUuid, nowIso } from '../util/ids.js'
+import { fingerprint } from '../ca/fingerprint.js'
+
+export interface BindHostInput {
+  readonly accountId: string
+  readonly subdomain: string
+  readonly agentPubkey: Uint8Array
+  readonly enrollFpr: string
+}
+
+export interface HostRegistry {
+  bindHost(input: BindHostInput): Promise<HostRecord>
+  getHost(hostId: string): Promise<HostRecord | null>
+  getHostBySubdomain(subdomain: string): Promise<HostRecord | null>
+  listHosts(accountId: string): Promise<readonly HostRecord[]>
+  setHostStatus(hostId: string, status: HostStatus): Promise<HostRecord>
+  ownsHost(accountId: string, hostId: string): Promise<boolean>
+  touchLastSeen(hostId: string): Promise<void>
+}
+
+export interface HostRegistryDeps {
+  readonly hosts: HostStore
+  readonly audit?: AuditWriter
+  readonly actor?: string
+}
+
+export function createHostRegistry(deps: HostRegistryDeps): HostRegistry {
+  const audit = deps.audit ?? noopAuditWriter()
+  const actor = deps.actor ?? 'system'
+  return {
+    async bindHost(input) {
+      // enroll_fpr MUST be the fingerprint of the presented pubkey (defence-in-depth: recompute).
+      const expectedFpr = fingerprint(input.agentPubkey)
+      if (input.enrollFpr !== expectedFpr) {
+        throw new Error('enrollFpr does not match agentPubkey fingerprint')
+      }
+      const rec: HostRecord = {
+        hostId: newUuid(), // unguessable UUIDv4, never recycled (INV1)
+        accountId: input.accountId,
+        subdomain: input.subdomain,
+        // Defensive copy → fresh ArrayBuffer-backed array (immutability + TS6 variance). PUBLIC key only (INV4).
+        agentPubkey: new Uint8Array(input.agentPubkey),
+        enrollFpr: input.enrollFpr,
+        status: 'offline',
+        lastSeen: nowIso(),
+        createdAt: nowIso(),
+        revokedAt: null,
+      }
+      await deps.hosts.insert(rec)
+      await audit.writeAuditEvent({
+        action: 'host.bind',
+        principalId: actor,
+        accountId: input.accountId,
+        hostId: rec.hostId,
+        ts: rec.createdAt,
+        meta: { subdomain: input.subdomain, enrollFpr: input.enrollFpr },
+      })
+      return rec
+    },
+    async getHost(hostId) {
+      return deps.hosts.get(hostId)
+    },
+    async getHostBySubdomain(subdomain) {
+      return deps.hosts.getBySubdomain(subdomain)
+    },
+    async listHosts(accountId) {
+      return deps.hosts.listByAccount(accountId) // ownership-scoped
+    },
+    async setHostStatus(hostId, status) {
+      const revokedAt = status === 'revoked' ? nowIso() : null
+      const next = await deps.hosts.swapStatus(hostId, status, revokedAt, actor)
+      if (status === 'revoked') {
+        await audit.writeAuditEvent({
+          action: 'host.revoke',
+          principalId: actor,
+          accountId: next.accountId,
+          hostId,
+          ts: nowIso(),
+          meta: { status },
+        })
+      }
+      return next
+    },
+    async ownsHost(accountId, hostId) {
+      const host = await deps.hosts.get(hostId)
+      // Deny-by-default: unknown host or account mismatch ⇒ false (INV1/INV6).
+      return host !== null && host.accountId === accountId
+    },
+    async touchLastSeen(hostId) {
+      await deps.hosts.touchLastSeen(hostId, nowIso()) // advisory, not versioned (INV7)
+    },
+  }
+}

control-plane/src/registry/sessions.ts

@@ -0,0 +1,49 @@
+/**
+ * T5 — session registry. `account_id` is DENORMALIZED from the host at write time — NEVER
+ * supplied by the caller/client (INV3) — giving an O(1) deny-by-default authz fact for reattach
+ * (INV6). `sessionAccount` returns that server-derived owner; it never echoes a client value.
+ */
+import type { SessionRecord } from '../model/records.js'
+import type { HostStore, SessionStore } from '../store/ports.js'
+import { nowIso } from '../util/ids.js'
+
+export interface RecordSessionInput {
+  readonly sessionId: string
+  readonly hostId: string
+}
+
+export interface SessionRegistry {
+  recordSession(input: RecordSessionInput): Promise<SessionRecord>
+  getSession(sessionId: string): Promise<SessionRecord | null>
+  sessionAccount(sessionId: string): Promise<string | null>
+}
+
+export interface SessionRegistryDeps {
+  readonly sessions: SessionStore
+  readonly hosts: HostStore
+}
+
+export function createSessionRegistry(deps: SessionRegistryDeps): SessionRegistry {
+  return {
+    async recordSession(input) {
+      const host = await deps.hosts.get(input.hostId)
+      if (host === null) throw new Error('cannot record session for unknown host')
+      const rec: SessionRecord = {
+        sessionId: input.sessionId,
+        hostId: input.hostId,
+        accountId: host.accountId, // derived from the host — caller cannot influence (INV3)
+        createdAt: nowIso(),
+        lastAttachAt: nowIso(),
+      }
+      await deps.sessions.insert(rec)
+      return rec
+    },
+    async getSession(sessionId) {
+      return deps.sessions.get(sessionId)
+    },
+    async sessionAccount(sessionId) {
+      const s = await deps.sessions.get(sessionId)
+      return s?.accountId ?? null // O(1) authz fact; server-derived, never client-supplied
+    },
+  }
+}

control-plane/src/revoke/revoke.ts

@@ -0,0 +1,109 @@
+/**
+ * T13 — revocation (global + per-host), INV12. The within-seconds tunnel-kill PUBLISHES a
+ * KillSignal on the FROZEN `relay:revocations` bus (INDEX §4.2 FIX 4 — SAME channel T10 drain
+ * uses); every P1 node subscribes and injects the §4.1 CLOSE+RST within REVOCATION_PUSH_BUDGET_MS.
+ * KillSignal / RevocationScope / the channel + budget constants are IMPORTED from relay-contracts,
+ * never redefined. `reason` is metadata only (INV10, zero payload). Revocation writes an immutable
+ * host snapshot (INV8) and is idempotent.
+ */
+import { REVOCATION_PUSH_BUDGET_MS, type RevocationBus } from 'relay-contracts'
+import type { HostRegistry } from '../registry/hosts.js'
+import type { RoutingTable } from '../routing/table.js'
+import type { AuditWriter } from '../audit/log.js'
+import { noopAuditWriter } from '../audit/log.js'
+
+export { REVOCATION_PUSH_BUDGET_MS }
+
+/** Short-TTL token revocation store (Redis `revoked:{jti}` in prod). Shared key space with P5. */
+export interface RevokedTokenStore {
+  revoke(jti: string, ttlSec: number): Promise<void>
+  isRevoked(jti: string): Promise<boolean>
+}
+
+/** In-memory implementation with TTL expiry (default; Redis is the production swap). */
+export function createInMemoryRevokedTokenStore(): RevokedTokenStore {
+  const until = new Map<string, number>()
+  return {
+    async revoke(jti, ttlSec) {
+      until.set(jti, Date.now() + Math.max(0, ttlSec) * 1000)
+    },
+    async isRevoked(jti) {
+      const exp = until.get(jti)
+      if (exp === undefined) return false
+      if (exp <= Date.now()) {
+        until.delete(jti)
+        return false
+      }
+      return true
+    },
+  }
+}
+
+export interface Revoker {
+  revokeHost(hostId: string): Promise<void>
+  revokeAccount(accountId: string): Promise<void>
+  revokeToken(jti: string, expUnix: number): Promise<void>
+  isTokenRevoked(jti: string): Promise<boolean>
+}
+
+export interface RevokerDeps {
+  readonly hosts: HostRegistry
+  readonly routing: RoutingTable
+  readonly bus: RevocationBus
+  readonly tokens: RevokedTokenStore
+  readonly audit?: AuditWriter
+  readonly actor?: string
+}
+
+export function createRevoker(deps: RevokerDeps): Revoker {
+  const audit = deps.audit ?? noopAuditWriter()
+  const actor = deps.actor ?? 'system'
+  const at = () => Math.floor(Date.now() / 1000)
+  return {
+    async revokeHost(hostId) {
+      const host = await deps.hosts.getHost(hostId)
+      if (host === null) return // idempotent: nothing to revoke
+      if (host.status !== 'revoked') {
+        await deps.hosts.setHostStatus(hostId, 'revoked') // immutable snapshot (INV8) + audit host.revoke
+      }
+      await deps.routing.systemDropRoute(hostId) // resolveRoute → null after this
+      await deps.bus.publish({ scope: { kind: 'host', hostId }, at: at(), reason: 'revoked' })
+      await audit.writeAuditEvent({
+        action: 'revoke',
+        principalId: actor,
+        accountId: host.accountId,
+        hostId,
+        ts: new Date().toISOString(),
+        meta: { scope: 'host' },
+      })
+    },
+    async revokeAccount(accountId) {
+      const hosts = await deps.hosts.listHosts(accountId)
+      for (const h of hosts) {
+        if (h.status !== 'revoked') {
+          // eslint-disable-next-line no-await-in-loop
+          await deps.hosts.setHostStatus(h.hostId, 'revoked')
+        }
+        // eslint-disable-next-line no-await-in-loop
+        await deps.routing.systemDropRoute(h.hostId)
+      }
+      // One account-scoped KillSignal; P1 tears down all of the account's live streams.
+      await deps.bus.publish({ scope: { kind: 'account', accountId }, at: at(), reason: 'revoked' })
+      await audit.writeAuditEvent({
+        action: 'revoke',
+        principalId: actor,
+        accountId,
+        hostId: null,
+        ts: new Date().toISOString(),
+        meta: { scope: 'account', hosts: String(hosts.length) },
+      })
+    },
+    async revokeToken(jti, expUnix) {
+      const ttlSec = Math.max(0, expUnix - Math.floor(Date.now() / 1000))
+      await deps.tokens.revoke(jti, ttlSec)
+    },
+    async isTokenRevoked(jti) {
+      return deps.tokens.isRevoked(jti)
+    },
+  }
+}

control-plane/src/routing/bus.ts

@@ -0,0 +1,49 @@
+/**
+ * RevocationBus implementations over the FROZEN `relay:revocations` channel (INDEX §4.2 FIX 4).
+ * P3 only PUBLISHES (P1 owns the subscriber that injects §4.1 CLOSE+RST / GOAWAY). Drain (T10)
+ * and revoke (T13) use the SAME named channel. The KillSignal shape + channel name are imported
+ * from relay-contracts and NEVER redefined.
+ */
+import {
+  RELAY_REVOCATIONS_CHANNEL,
+  KillSignalSchema,
+  type KillSignal,
+  type RevocationBus,
+} from 'relay-contracts'
+
+/** In-memory bus with a subscribe hook — used by tests and single-process wiring. */
+export interface TestableRevocationBus extends RevocationBus {
+  subscribe(handler: (signal: KillSignal) => void): () => void
+  readonly channel: typeof RELAY_REVOCATIONS_CHANNEL
+}
+
+export function createInMemoryRevocationBus(): TestableRevocationBus {
+  const handlers = new Set<(signal: KillSignal) => void>()
+  return {
+    channel: RELAY_REVOCATIONS_CHANNEL,
+    async publish(signal) {
+      // Validate at the boundary before it hits the wire (INV10: reason is metadata only).
+      const parsed = KillSignalSchema.parse(signal)
+      for (const h of handlers) h(parsed as KillSignal)
+    },
+    subscribe(handler) {
+      handlers.add(handler)
+      return () => handlers.delete(handler)
+    },
+  }
+}
+
+/** Minimal publisher surface of an ioredis client (integration seam; typed, not unit-tested). */
+export interface RedisPublisher {
+  publish(channel: string, message: string): Promise<number>
+}
+
+/** Redis-backed publisher (production). P1 relay nodes SUBSCRIBE to the same channel. */
+export function createRedisRevocationBus(redis: RedisPublisher): RevocationBus {
+  return {
+    async publish(signal) {
+      const parsed = KillSignalSchema.parse(signal)
+      await redis.publish(RELAY_REVOCATIONS_CHANNEL, JSON.stringify(parsed))
+    },
+  }
+}

control-plane/src/routing/nodes.ts

@@ -0,0 +1,67 @@
+/**
+ * T10 — relay-node registry + graceful drain (INV7). Every mutation is scoped to the caller's
+ * authenticated `NodeIdentity`: a node can only register/heartbeat/drain ITSELF. Drain marks the
+ * node 'draining', enumerates its live routes, and PUBLISHES a per-host `KillSignal` on the frozen
+ * `relay:revocations` bus (INDEX §4.2 FIX 4 — SAME channel T13 revoke uses); P1 nodes translate it
+ * into the §4.1 GOAWAY. This module does NOT encode the frame (that is P1). Drain touches NO
+ * Postgres host/session row — the running task lives on the customer machine (PTY survives).
+ *
+ * OQ4 residual: the frozen RevocationScope has no `node` kind, so a single-node operator drain is
+ * expressed as per-host KillSignals with a drain reason (flagged to the INDEX for a future scope).
+ */
+import type { RevocationBus } from 'relay-contracts'
+import type { NodeStore, RouteStore } from '../store/ports.js'
+import type { NodeIdentity } from '../node-auth/identity.js'
+import type { AuditWriter } from '../audit/log.js'
+import { noopAuditWriter } from '../audit/log.js'
+import { nowIso } from '../util/ids.js'
+
+export const DRAIN_REASON = 'operatorDrain'
+
+export interface NodeCoordinator {
+  registerNode(caller: NodeIdentity, addr: string): Promise<void>
+  nodeHeartbeat(caller: NodeIdentity): Promise<void>
+  beginDrain(caller: NodeIdentity): Promise<{ readonly hostIds: readonly string[] }>
+  completeDrain(caller: NodeIdentity): Promise<void>
+}
+
+export interface NodeCoordinatorDeps {
+  readonly nodes: NodeStore
+  readonly routes: RouteStore
+  readonly bus: RevocationBus
+  readonly audit?: AuditWriter
+}
+
+export function createNodeCoordinator(deps: NodeCoordinatorDeps): NodeCoordinator {
+  const audit = deps.audit ?? noopAuditWriter()
+  return {
+    async registerNode(caller, addr) {
+      await deps.nodes.upsert({ nodeId: caller.nodeId, addr, status: 'active', lastSeen: nowIso() })
+    },
+    async nodeHeartbeat(caller) {
+      await deps.nodes.touch(caller.nodeId, nowIso())
+    },
+    async beginDrain(caller) {
+      await deps.nodes.setStatus(caller.nodeId, 'draining')
+      const routed = await deps.routes.listByNode(caller.nodeId)
+      const at = Math.floor(Date.now() / 1000)
+      for (const { hostId } of routed) {
+        // Per-host KillSignal with a drain reason on the frozen bus (P1 emits GOAWAY).
+        // eslint-disable-next-line no-await-in-loop
+        await deps.bus.publish({ scope: { kind: 'host', hostId }, at, reason: DRAIN_REASON })
+      }
+      await audit.writeAuditEvent({
+        action: 'node.drain',
+        principalId: `node:${caller.nodeId}`,
+        accountId: 'system',
+        hostId: null,
+        ts: nowIso(),
+        meta: { nodeId: caller.nodeId, routes: String(routed.length) },
+      })
+      return { hostIds: routed.map((r) => r.hostId) }
+    },
+    async completeDrain(caller) {
+      await deps.nodes.delete(caller.nodeId) // deregister after routes re-homed
+    },
+  }
+}

control-plane/src/routing/table.ts

@@ -0,0 +1,62 @@
+/**
+ * T9 — Redis routing table (`route:{host_id}`, heartbeat-TTL, INV7). Redis holds only LOCATION,
+ * never ownership or secrets; a missing/expired key fails CLOSED (host treated offline). Every
+ * mutation is scoped to the AUTHENTICATED node identity: a node can only route hosts to ITSELF
+ * (`entry.relayNodeId === caller.nodeId`) and can only heartbeat/drop a route it currently holds.
+ */
+import type { RouteEntry } from '../model/records.js'
+import type { NodeStatus, RouteStore } from '../store/ports.js'
+import type { NodeIdentity } from '../node-auth/identity.js'
+
+export class RouteAuthError extends Error {}
+
+export interface RoutingTable {
+  upsertRoute(caller: NodeIdentity, hostId: string, entry: RouteEntry, ttlSec: number): Promise<void>
+  heartbeatRoute(caller: NodeIdentity, hostId: string, ttlSec: number): Promise<void>
+  resolveRoute(hostId: string): Promise<RouteEntry | null>
+  dropRoute(caller: NodeIdentity, hostId: string): Promise<void>
+  /** System teardown path (drain/revoke) — bypasses the holding-node check by design. */
+  systemDropRoute(hostId: string): Promise<void>
+}
+
+export interface RoutingTableDeps {
+  readonly routes: RouteStore
+  /** Optional node-status hook: a draining node stops receiving new upserts (T10). */
+  readonly nodeStatus?: (nodeId: string) => Promise<NodeStatus | null>
+}
+
+export function createRoutingTable(deps: RoutingTableDeps): RoutingTable {
+  return {
+    async upsertRoute(caller, hostId, entry, ttlSec) {
+      // A node may ONLY route hosts to itself — never inject a route for another node's id.
+      if (entry.relayNodeId !== caller.nodeId) {
+        throw new RouteAuthError('entry.relayNodeId must equal the authenticated caller nodeId')
+      }
+      if (deps.nodeStatus !== undefined) {
+        const status = await deps.nodeStatus(caller.nodeId)
+        if (status === 'draining') throw new RouteAuthError('node is draining; not accepting new routes')
+      }
+      await deps.routes.set(hostId, entry, ttlSec)
+    },
+    async heartbeatRoute(caller, hostId, ttlSec) {
+      const current = await deps.routes.get(hostId)
+      // A stale/foreign node cannot refresh (hijack) another node's live tunnel; missing ⇒ no-op.
+      if (current === null || current.relayNodeId !== caller.nodeId) return
+      await deps.routes.refreshTtl(hostId, ttlSec)
+    },
+    async resolveRoute(hostId) {
+      return deps.routes.get(hostId) // null ⇒ offline (fails closed, INV7)
+    },
+    async dropRoute(caller, hostId) {
+      const current = await deps.routes.get(hostId)
+      if (current === null) return
+      if (current.relayNodeId !== caller.nodeId) {
+        throw new RouteAuthError('only the holding node may drop its route')
+      }
+      await deps.routes.delete(hostId)
+    },
+    async systemDropRoute(hostId) {
+      await deps.routes.delete(hostId)
+    },
+  }
+}

control-plane/src/store/memory.ts

@@ -0,0 +1,320 @@
+/**
+ * In-memory adapter for the repository ports — the tested + v0.9-MVP-shipped default.
+ *
+ * INV8: lifecycle/business fields (account.status, host.status/revoked_at) are versioned via
+ * append-only companion rows + an atomic single-row pointer swap. Each `swapStatus` mutation is
+ * a synchronous critical section (no `await` inside) so a concurrent reader sees whole-old or
+ * whole-new — never a torn mix. Prior snapshots stay readable from the `versions()` list.
+ * High-frequency liveness (`last_seen`, route TTL) is advisory and NOT versioned (INV7).
+ */
+import type {
+  AccountRecord,
+  AccountStatus,
+  AccountStatusVersionRow,
+  HostRecord,
+  HostStatus,
+  HostStatusVersionRow,
+  MeteringSampleRow,
+  PairingCodeRecord,
+  RouteEntry,
+  SessionRecord,
+} from '../model/records.js'
+import type {
+  AccountStore,
+  AuditRow,
+  AuditStore,
+  CasOutcome,
+  HostStore,
+  MeteringStore,
+  NodeRow,
+  NodeStatus,
+  NodeStore,
+  PairingRow,
+  PairingStore,
+  RouteStore,
+  SessionStore,
+  Stores,
+  SubdomainStore,
+} from './ports.js'
+
+interface AccountCell {
+  record: AccountRecord
+  version: number
+  versions: AccountStatusVersionRow[]
+}
+interface HostCell {
+  record: HostRecord
+  version: number
+  versions: HostStatusVersionRow[]
+}
+
+function memAccountStore(): AccountStore {
+  const cells = new Map<string, AccountCell>()
+  return {
+    async insert(rec) {
+      if (cells.has(rec.accountId)) throw new Error('duplicate accountId')
+      cells.set(rec.accountId, {
+        record: rec,
+        version: 1,
+        versions: [
+          { accountId: rec.accountId, version: 1, status: rec.status, changedAt: rec.createdAt, changedBy: 'system' },
+        ],
+      })
+    },
+    async get(id) {
+      return cells.get(id)?.record ?? null
+    },
+    async swapStatus(id, status, changedBy) {
+      const cell = cells.get(id)
+      if (cell === undefined) throw new Error('account not found')
+      // --- atomic critical section (no await) ---
+      const nextVersion = cell.version + 1
+      const changedAt = new Date().toISOString()
+      const nextRecord: AccountRecord = { ...cell.record, status }
+      cell.versions.push({ accountId: id, version: nextVersion, status, changedAt, changedBy })
+      cell.record = nextRecord
+      cell.version = nextVersion
+      // --- end critical section ---
+      return nextRecord
+    },
+    async versions(id) {
+      return (cells.get(id)?.versions ?? []).slice()
+    },
+  }
+}
+
+function memHostStore(): HostStore {
+  const cells = new Map<string, HostCell>()
+  const bySub = new Map<string, string>()
+  return {
+    async insert(rec) {
+      if (cells.has(rec.hostId)) throw new Error('duplicate hostId')
+      if (bySub.has(rec.subdomain)) throw new Error('duplicate subdomain')
+      cells.set(rec.hostId, {
+        record: rec,
+        version: 1,
+        versions: [
+          {
+            hostId: rec.hostId,
+            version: 1,
+            status: rec.status,
+            revokedAt: rec.revokedAt,
+            changedAt: rec.createdAt,
+            changedBy: 'system',
+          },
+        ],
+      })
+      bySub.set(rec.subdomain, rec.hostId)
+    },
+    async get(id) {
+      return cells.get(id)?.record ?? null
+    },
+    async getBySubdomain(sub) {
+      const id = bySub.get(sub)
+      return id === undefined ? null : (cells.get(id)?.record ?? null)
+    },
+    async listByAccount(accountId) {
+      return [...cells.values()].filter((c) => c.record.accountId === accountId).map((c) => c.record)
+    },
+    async swapStatus(id, status, revokedAt, changedBy) {
+      const cell = cells.get(id)
+      if (cell === undefined) throw new Error('host not found')
+      const nextVersion = cell.version + 1
+      const changedAt = new Date().toISOString()
+      const nextRecord: HostRecord = { ...cell.record, status, revokedAt }
+      cell.versions.push({ hostId: id, version: nextVersion, status, revokedAt, changedAt, changedBy })
+      cell.record = nextRecord
+      cell.version = nextVersion
+      return nextRecord
+    },
+    async touchLastSeen(id, ts) {
+      const cell = cells.get(id)
+      if (cell === undefined) return
+      // Advisory cache — overwrite in place, NO version row (INV7).
+      cell.record = { ...cell.record, lastSeen: ts }
+    },
+    async versions(id) {
+      return (cells.get(id)?.versions ?? []).slice()
+    },
+  }
+}
+
+function memSessionStore(): SessionStore {
+  const rows = new Map<string, SessionRecord>()
+  return {
+    async insert(rec) {
+      if (rows.has(rec.sessionId)) throw new Error('duplicate sessionId')
+      rows.set(rec.sessionId, rec)
+    },
+    async get(id) {
+      return rows.get(id) ?? null
+    },
+  }
+}
+
+function memSubdomainStore(hosts: HostStore): SubdomainStore {
+  const reserved = new Set<string>()
+  return {
+    async reserve(sub) {
+      // Synchronous claim FIRST (no await before add) so two concurrent callers can't both win.
+      if (reserved.has(sub)) return false
+      reserved.add(sub)
+      if ((await hosts.getBySubdomain(sub)) !== null) {
+        reserved.delete(sub) // an already-bound host owns this label — release the optimistic claim
+        return false
+      }
+      return true
+    },
+    async isTaken(sub) {
+      return reserved.has(sub) || (await hosts.getBySubdomain(sub)) !== null
+    },
+  }
+}
+
+interface PairingCell {
+  record: PairingCodeRecord
+  attempts: number
+}
+
+function memPairingStore(): PairingStore {
+  const cells = new Map<string, PairingCell>()
+  return {
+    async insert(rec) {
+      if (cells.has(rec.codeHash)) throw new Error('duplicate code_hash')
+      cells.set(rec.codeHash, { record: rec, attempts: 0 })
+    },
+    async get(codeHash): Promise<PairingRow | null> {
+      const cell = cells.get(codeHash)
+      return cell === undefined ? null : { record: cell.record, redeemAttempts: cell.attempts }
+    },
+    async casRedeem(codeHash, nowIso): Promise<CasOutcome> {
+      const cell = cells.get(codeHash)
+      if (cell === undefined) return 'unknown'
+      // --- atomic critical section: CAS redeemedAt from null ---
+      if (cell.record.redeemedAt !== null) return 'already_redeemed'
+      cell.record = { ...cell.record, redeemedAt: nowIso }
+      return 'ok'
+      // --- end critical section ---
+    },
+    async registerFailure(codeHash) {
+      const cell = cells.get(codeHash)
+      if (cell === undefined) return 0
+      cell.attempts += 1
+      return cell.attempts
+    },
+  }
+}
+
+interface RouteCell {
+  entry: RouteEntry
+  expiresAtMs: number
+}
+function memRouteStore(): RouteStore {
+  const cells = new Map<string, RouteCell>()
+  const live = (id: string): RouteCell | null => {
+    const c = cells.get(id)
+    if (c === undefined) return null
+    if (c.expiresAtMs <= Date.now()) {
+      cells.delete(id) // fail closed: expired ⇒ offline (INV7)
+      return null
+    }
+    return c
+  }
+  return {
+    async set(hostId, entry, ttlSec) {
+      cells.set(hostId, { entry, expiresAtMs: Date.now() + ttlSec * 1000 })
+    },
+    async refreshTtl(hostId, ttlSec) {
+      const c = live(hostId)
+      if (c === null) return false
+      c.expiresAtMs = Date.now() + ttlSec * 1000
+      return true
+    },
+    async get(hostId) {
+      return live(hostId)?.entry ?? null
+    },
+    async delete(hostId) {
+      cells.delete(hostId)
+    },
+    async listByNode(nodeId) {
+      const out: { hostId: string; entry: RouteEntry }[] = []
+      for (const hostId of [...cells.keys()]) {
+        const c = live(hostId)
+        if (c !== null && c.entry.relayNodeId === nodeId) out.push({ hostId, entry: c.entry })
+      }
+      return out
+    },
+  }
+}
+
+function memNodeStore(): NodeStore {
+  const rows = new Map<string, NodeRow>()
+  return {
+    async upsert(row) {
+      rows.set(row.nodeId, row)
+    },
+    async get(id) {
+      return rows.get(id) ?? null
+    },
+    async setStatus(id, status: NodeStatus) {
+      const r = rows.get(id)
+      if (r === undefined) throw new Error('node not found')
+      rows.set(id, { ...r, status })
+    },
+    async touch(id, ts) {
+      const r = rows.get(id)
+      if (r !== undefined) rows.set(id, { ...r, lastSeen: ts })
+    },
+    async delete(id) {
+      rows.delete(id)
+    },
+  }
+}
+
+function memMeteringStore(): MeteringStore {
+  const rows: MeteringSampleRow[] = []
+  return {
+    async append(row) {
+      rows.push(row) // append-only
+    },
+    async query(accountId, fromIso, toIso) {
+      const from = Date.parse(fromIso)
+      const to = Date.parse(toIso)
+      return rows.filter(
+        (r) => r.accountId === accountId && Date.parse(r.sampledAt) >= from && Date.parse(r.sampledAt) <= to,
+      )
+    },
+  }
+}
+
+function memAuditStore(): AuditStore {
+  const rows: AuditRow[] = []
+  return {
+    async append(row) {
+      rows.push(row) // append-only, no update/delete exposed (INV10)
+    },
+    async query(accountId, fromIso, toIso) {
+      const from = Date.parse(fromIso)
+      const to = Date.parse(toIso)
+      return rows.filter(
+        (r) => r.accountId === accountId && Date.parse(r.ts) >= from && Date.parse(r.ts) <= to,
+      )
+    },
+  }
+}
+
+/** Build a full in-memory store set (all ports wired). */
+export function createMemoryStores(): Stores {
+  const hosts = memHostStore()
+  return {
+    accounts: memAccountStore(),
+    hosts,
+    sessions: memSessionStore(),
+    subdomains: memSubdomainStore(hosts),
+    pairing: memPairingStore(),
+    routes: memRouteStore(),
+    nodes: memNodeStore(),
+    metering: memMeteringStore(),
+    audit: memAuditStore(),
+  }
+}

control-plane/src/store/ports.ts

@@ -0,0 +1,142 @@
+/**
+ * Repository ports (Repository Pattern, patterns.md). Registries/services depend on these
+ * abstractions, NOT on a concrete storage engine. Two adapters implement them:
+ *   - `store/memory.ts` — in-memory, the tested + v0.9-MVP-shipped default. Immutable/versioned
+ *     discipline (INV8) is enforced here in synchronous critical sections (JS is single-threaded,
+ *     so a mutation with no `await` inside is atomic — no torn read).
+ *   - `store/pg.ts` — parameterized Postgres SQL over `db/pool.ts` (integration seam, typechecked).
+ *
+ * The INV8 versioning logic lives in the store so both adapters agree on the contract; the
+ * registries orchestrate and add authz/ownership predicates.
+ */
+import type {
+  AccountRecord,
+  AccountStatus,
+  AccountStatusVersionRow,
+  HostRecord,
+  HostStatus,
+  HostStatusVersionRow,
+  MeteringSampleRow,
+  PairingCodeRecord,
+  RouteEntry,
+  SessionRecord,
+} from '../model/records.js'
+
+export interface AccountStore {
+  insert(rec: AccountRecord): Promise<void>
+  get(accountId: string): Promise<AccountRecord | null>
+  /** Atomic: append a status version then swap the single-row pointer. Returns the NEW record. */
+  swapStatus(accountId: string, status: AccountStatus, changedBy: string): Promise<AccountRecord>
+  versions(accountId: string): Promise<readonly AccountStatusVersionRow[]>
+}
+
+export interface HostStore {
+  insert(rec: HostRecord): Promise<void>
+  get(hostId: string): Promise<HostRecord | null>
+  getBySubdomain(subdomain: string): Promise<HostRecord | null>
+  listByAccount(accountId: string): Promise<readonly HostRecord[]>
+  /** Atomic status version + pointer swap. `revokedAt` set only on 'revoked'. Returns NEW record. */
+  swapStatus(
+    hostId: string,
+    status: HostStatus,
+    revokedAt: string | null,
+    changedBy: string,
+  ): Promise<HostRecord>
+  /** Advisory liveness cache update — NOT versioned (INV7; live truth is Redis). */
+  touchLastSeen(hostId: string, ts: string): Promise<void>
+  versions(hostId: string): Promise<readonly HostStatusVersionRow[]>
+}
+
+export interface SessionStore {
+  insert(rec: SessionRecord): Promise<void>
+  get(sessionId: string): Promise<SessionRecord | null>
+}
+
+/** Reservation of a subdomain label; atomic single-winner under concurrency (INV1). */
+export interface SubdomainStore {
+  reserve(subdomain: string): Promise<boolean> // false ⇒ already taken
+  isTaken(subdomain: string): Promise<boolean>
+}
+
+export interface PairingRow {
+  readonly record: PairingCodeRecord
+  readonly redeemAttempts: number
+}
+
+export type RedeemOutcome =
+  | 'ok'
+  | 'already_redeemed'
+  | 'expired'
+  | 'unknown'
+  | 'too_many_attempts'
+  | 'bad_csr'
+
+export type CasOutcome = 'ok' | 'already_redeemed' | 'unknown'
+
+export interface PairingStore {
+  insert(rec: PairingCodeRecord): Promise<void>
+  get(codeHash: string): Promise<PairingRow | null>
+  /**
+   * Atomic compare-and-set of `redeemedAt` from null (double-spend guard). Exactly one
+   * concurrent caller wins 'ok'; the loser gets 'already_redeemed'. Lockout/expiry are
+   * pre-checked by the registry from `get()`.
+   */
+  casRedeem(codeHash: string, nowIso: string): Promise<CasOutcome>
+  /** Atomic failed-attempt increment for a known code_hash; returns the new attempt count. */
+  registerFailure(codeHash: string): Promise<number>
+}
+
+/** Redis-like routing table with per-key heartbeat TTL (INV7). */
+export interface RouteStore {
+  set(hostId: string, entry: RouteEntry, ttlSec: number): Promise<void>
+  refreshTtl(hostId: string, ttlSec: number): Promise<boolean> // false if key already expired/absent
+  get(hostId: string): Promise<RouteEntry | null>
+  delete(hostId: string): Promise<void>
+  /** Live routes whose entry targets `nodeId` (used by drain enumeration). */
+  listByNode(nodeId: string): Promise<readonly { hostId: string; entry: RouteEntry }[]>
+}
+
+export type NodeStatus = 'active' | 'draining'
+export interface NodeRow {
+  readonly nodeId: string
+  readonly addr: string
+  readonly status: NodeStatus
+  readonly lastSeen: string
+}
+export interface NodeStore {
+  upsert(row: NodeRow): Promise<void>
+  get(nodeId: string): Promise<NodeRow | null>
+  setStatus(nodeId: string, status: NodeStatus): Promise<void>
+  touch(nodeId: string, ts: string): Promise<void>
+  delete(nodeId: string): Promise<void>
+}
+
+export interface MeteringStore {
+  append(row: MeteringSampleRow): Promise<void> // append-only (INV8)
+  query(accountId: string, fromIso: string, toIso: string): Promise<readonly MeteringSampleRow[]>
+}
+
+export interface AuditRow {
+  readonly action: string
+  readonly principalId: string
+  readonly accountId: string
+  readonly hostId: string | null
+  readonly ts: string
+  readonly meta: Readonly<Record<string, string>>
+}
+export interface AuditStore {
+  append(row: AuditRow): Promise<void> // append-only, no update/delete path (INV10)
+  query(accountId: string, fromIso: string, toIso: string): Promise<readonly AuditRow[]>
+}
+
+export interface Stores {
+  readonly accounts: AccountStore
+  readonly hosts: HostStore
+  readonly sessions: SessionStore
+  readonly subdomains: SubdomainStore
+  readonly pairing: PairingStore
+  readonly routes: RouteStore
+  readonly nodes: NodeStore
+  readonly metering: MeteringStore
+  readonly audit: AuditStore
+}

control-plane/src/subdomain/assign.ts

@@ -0,0 +1,95 @@
+/**
+ * T6 — per-tenant subdomain assignment. The subdomain is the browser-origin isolation boundary
+ * (EXPLORE §3, INV1): a malformed/duplicate label must never collapse two tenants into one
+ * origin. Validation is RFC-1123-label strict; assignment is an atomic single-winner reserve.
+ */
+import type { SubdomainStore } from '../store/ports.js'
+import type { AuditWriter } from '../audit/log.js'
+import { noopAuditWriter } from '../audit/log.js'
+import { nowIso } from '../util/ids.js'
+
+/** Names that must never become a tenant subdomain (host-header / infra confusion). */
+export const RESERVED_SUBDOMAINS: ReadonlySet<string> = new Set([
+  'www',
+  'api',
+  'admin',
+  'app',
+  'relay',
+  'term',
+  'root',
+  'localhost',
+  '_',
+])
+
+const LABEL_RE = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/
+
+/** Lowercase, strip characters invalid in an RFC-1123 label; collapse to a candidate label. */
+export function normalizeSubdomain(raw: string): string {
+  return raw
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9-]/g, '')
+    .replace(/^-+/, '')
+    .replace(/-+$/, '')
+    .slice(0, 63)
+}
+
+/** 1–63 chars, [a-z0-9-], not leading/trailing '-', not reserved. */
+export function isValidSubdomain(raw: string): boolean {
+  if (raw.length < 1 || raw.length > 63) return false
+  if (!LABEL_RE.test(raw)) return false
+  if (RESERVED_SUBDOMAINS.has(raw)) return false
+  return true
+}
+
+/** 'alice' + 'term.example.com' → 'alice.term.example.com'. */
+export function assembleFqdn(subdomain: string, baseDomain: string): string {
+  return `${subdomain}.${baseDomain}`
+}
+
+const MAX_COLLISION_RETRIES = 5
+
+export interface SubdomainAssigner {
+  assignSubdomain(accountId: string, requested?: string): Promise<string>
+}
+
+export interface SubdomainAssignerDeps {
+  readonly subdomains: SubdomainStore
+  readonly audit?: AuditWriter
+  readonly actor?: string
+  /** Deterministic suffix source (test seam); defaults to random 4-hex. */
+  readonly suffix?: () => string
+}
+
+export function createSubdomainAssigner(deps: SubdomainAssignerDeps): SubdomainAssigner {
+  const audit = deps.audit ?? noopAuditWriter()
+  const actor = deps.actor ?? 'system'
+  const suffix = deps.suffix ?? (() => Math.floor(Math.random() * 0xffff).toString(16).padStart(4, '0'))
+  return {
+    async assignSubdomain(accountId, requested) {
+      const base = requested !== undefined ? normalizeSubdomain(requested) : `h${suffix()}`
+      if (!isValidSubdomain(base)) {
+        throw new Error(`invalid subdomain: ${requested ?? base}`)
+      }
+      // A requested name that collides is NEVER silently reassigned to someone else's tenant.
+      // We try the exact name, then deterministic '-<suffix>' variants, else 409-equivalent throw.
+      const candidates = [base, ...Array.from({ length: MAX_COLLISION_RETRIES }, () => `${base}-${suffix()}`)]
+      for (const candidate of candidates) {
+        if (!isValidSubdomain(candidate)) continue
+        // eslint-disable-next-line no-await-in-loop
+        if (await deps.subdomains.reserve(candidate)) {
+          await audit.writeAuditEvent({
+            action: 'subdomain.assign',
+            principalId: actor,
+            accountId,
+            hostId: null,
+            ts: nowIso(),
+            meta: { subdomain: candidate },
+          })
+          return candidate
+        }
+      }
+      throw new Error(`subdomain collision: ${base} is taken (409)`)
+    },
+  }
+}

control-plane/src/util/bytes.ts

@@ -0,0 +1,29 @@
+/** Byte / base64 helpers (dependency-free; Node Buffer under the hood). */
+
+export function bytesToBase64(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString('base64')
+}
+
+export function base64ToBytes(b64: string): Uint8Array {
+  // Buffer.from is lenient; assert round-trip to reject clearly-invalid input.
+  const buf = Buffer.from(b64, 'base64')
+  if (buf.toString('base64').replace(/=+$/, '') !== b64.replace(/=+$/, '')) {
+    throw new Error('invalid base64')
+  }
+  return new Uint8Array(buf)
+}
+
+export function bytesToHex(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString('hex')
+}
+
+/** Constant-time equality of two byte arrays (length-independent short-circuit avoided). */
+export function timingSafeEqualBytes(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false
+  let diff = 0
+  for (let i = 0; i < a.length; i++) {
+    // Non-null via loop bounds; noUncheckedIndexedAccess guarded below.
+    diff |= (a[i] as number) ^ (b[i] as number)
+  }
+  return diff === 0
+}

control-plane/src/util/crypto.ts

@@ -0,0 +1,119 @@
+/**
+ * Asymmetric crypto helpers built on Node's builtin `crypto` (no native deps).
+ *
+ *  - Ed25519 raw-key <-> KeyObject bridging for CSR proof-of-possession (T8/T15 INV14) and
+ *    the bind-time CA leaf signature.
+ *  - X25519 seal/open (ECIES-style) for wrapping the per-host content secret to the enrolled
+ *    identity (T8 FIX 3 INV4/INV5).
+ *
+ * NOTE (integration seam): production uses real PKCS#10 CSRs + X.509 leaves (`@peculiar/x509`)
+ * and converts the Ed25519 enrollment key to X25519 (ed2curve). Here the CSR is modelled as an
+ * Ed25519 proof-of-possession signature and the wrap targets a raw X25519 public key, which
+ * exercises the SAME security properties (possession proof, per-host wrap, no raw secret at rest)
+ * with builtin crypto only. Swapping in the X.509 stack does not change any §4 contract shape.
+ */
+import {
+  createPublicKey,
+  createPrivateKey,
+  sign as edSign,
+  verify as edVerify,
+  generateKeyPairSync,
+  diffieHellman,
+  hkdfSync,
+  randomBytes,
+  createCipheriv,
+  createDecipheriv,
+  type KeyObject,
+} from 'node:crypto'
+
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex')
+const X25519_SPKI_PREFIX = Buffer.from('302a300506032b656e032100', 'hex')
+
+/** Wrap a raw 32-byte Ed25519 public key into a verifiable KeyObject. */
+export function ed25519PublicKeyFromRaw(raw: Uint8Array): KeyObject {
+  if (raw.length !== 32) throw new Error('ed25519 public key must be 32 bytes')
+  return createPublicKey({
+    key: Buffer.concat([ED25519_SPKI_PREFIX, Buffer.from(raw)]),
+    format: 'der',
+    type: 'spki',
+  })
+}
+
+/** Verify an Ed25519 signature over `message` by the raw public key. Never throws. */
+export function ed25519Verify(rawPub: Uint8Array, message: Uint8Array, sig: Uint8Array): boolean {
+  try {
+    const key = ed25519PublicKeyFromRaw(rawPub)
+    return edVerify(null, Buffer.from(message), key, Buffer.from(sig))
+  } catch {
+    return false
+  }
+}
+
+/** Test/util: generate an Ed25519 keypair, returning raw pubkey + a KeyObject private key. */
+export function generateEd25519(): { publicKeyRaw: Uint8Array; privateKey: KeyObject } {
+  const { publicKey, privateKey } = generateKeyPairSync('ed25519')
+  const spki = publicKey.export({ format: 'der', type: 'spki' }) as Buffer
+  const raw = spki.subarray(spki.length - 32)
+  return { publicKeyRaw: new Uint8Array(raw), privateKey }
+}
+
+/** Test/util: sign a message with an Ed25519 private KeyObject. */
+export function ed25519Sign(privateKey: KeyObject, message: Uint8Array): Uint8Array {
+  return new Uint8Array(edSign(null, Buffer.from(message), privateKey))
+}
+
+// ---- X25519 wrap/unwrap (host content secret, FIX 3) --------------------------------------
+
+export function generateX25519(): { publicKeyRaw: Uint8Array; privateKey: KeyObject } {
+  const { publicKey, privateKey } = generateKeyPairSync('x25519')
+  const spki = publicKey.export({ format: 'der', type: 'spki' }) as Buffer
+  const raw = spki.subarray(spki.length - 32)
+  return { publicKeyRaw: new Uint8Array(raw), privateKey }
+}
+
+function x25519PublicKeyFromRaw(raw: Uint8Array): KeyObject {
+  if (raw.length !== 32) throw new Error('x25519 public key must be 32 bytes')
+  return createPublicKey({
+    key: Buffer.concat([X25519_SPKI_PREFIX, Buffer.from(raw)]),
+    format: 'der',
+    type: 'spki',
+  })
+}
+
+const WRAP_INFO = Buffer.from('relay-cp/host-content-secret/v1')
+
+/**
+ * Seal `secret` to a recipient X25519 public key (ephemeral-static ECDH → HKDF → AES-256-GCM).
+ * Output layout: ephPub(32) || iv(12) || tag(16) || ciphertext. The raw secret never appears in
+ * the output. A fresh ephemeral key per call makes every wrap distinct (per-host revocable).
+ */
+export function sealToX25519(recipientRawPub: Uint8Array, secret: Uint8Array): Uint8Array {
+  const recipient = x25519PublicKeyFromRaw(recipientRawPub)
+  const eph = generateKeyPairSync('x25519')
+  const ephSpki = eph.publicKey.export({ format: 'der', type: 'spki' }) as Buffer
+  const ephPubRaw = ephSpki.subarray(ephSpki.length - 32)
+  const shared = diffieHellman({ privateKey: eph.privateKey, publicKey: recipient })
+  const aeadKey = Buffer.from(hkdfSync('sha256', shared, ephPubRaw, WRAP_INFO, 32))
+  const iv = randomBytes(12)
+  const cipher = createCipheriv('aes-256-gcm', aeadKey, iv)
+  const ct = Buffer.concat([cipher.update(Buffer.from(secret)), cipher.final()])
+  const tag = cipher.getAuthTag()
+  return new Uint8Array(Buffer.concat([ephPubRaw, iv, tag, ct]))
+}
+
+/** Open a sealed blob with the recipient's X25519 private key. Throws on tamper/wrong key. */
+export function openFromX25519(recipientPriv: KeyObject, blob: Uint8Array): Uint8Array {
+  const buf = Buffer.from(blob)
+  const ephPubRaw = buf.subarray(0, 32)
+  const iv = buf.subarray(32, 44)
+  const tag = buf.subarray(44, 60)
+  const ct = buf.subarray(60)
+  const ephPub = x25519PublicKeyFromRaw(new Uint8Array(ephPubRaw))
+  const shared = diffieHellman({ privateKey: recipientPriv, publicKey: ephPub })
+  const aeadKey = Buffer.from(hkdfSync('sha256', shared, ephPubRaw, WRAP_INFO, 32))
+  const decipher = createDecipheriv('aes-256-gcm', aeadKey, iv)
+  decipher.setAuthTag(tag)
+  return new Uint8Array(Buffer.concat([decipher.update(ct), decipher.final()]))
+}
+
+export { createPrivateKey, type KeyObject }

control-plane/src/util/hash.ts

@@ -0,0 +1,44 @@
+/**
+ * Secret hashing at rest (INV5). Pairing codes and v0.8 tokens are stored as salted scrypt
+ * hashes, never raw. Verification is constant-time. scrypt is a Node builtin (no native dep);
+ * argon2id would be the production upgrade (integration note) but scrypt satisfies INV5 here.
+ */
+import { randomBytes, scryptSync, timingSafeEqual, createHash } from 'node:crypto'
+
+/**
+ * Deterministic hash for high-entropy lookup keys (pairing codes: ≥128-bit input, so a fast
+ * preimage-resistant hash is safe at rest — the input space is infeasible to brute-force, INV5).
+ * A salted scrypt cannot be used here because redemption must find the row by hash of the
+ * presented code. Production may HMAC this with a server-side pepper (integration note).
+ */
+export function sha256Hex(raw: string): string {
+  return createHash('sha256').update(raw, 'utf8').digest('hex')
+}
+
+const SCRYPT_KEYLEN = 32
+const SCRYPT_COST = 1 << 14 // N=16384 — modest, fast enough for tests, memory-hard
+const SALT_LEN = 16
+
+/** Produce a self-describing `scrypt$<saltHex>$<hashHex>` string. Raw secret is discarded. */
+export function hashSecret(raw: string): string {
+  const salt = randomBytes(SALT_LEN)
+  const hash = scryptSync(raw, salt, SCRYPT_KEYLEN, { N: SCRYPT_COST })
+  return `scrypt$${salt.toString('hex')}$${hash.toString('hex')}`
+}
+
+/** Constant-time verify a raw secret against a stored `scrypt$salt$hash`. */
+export function verifySecret(raw: string, stored: string): boolean {
+  const parts = stored.split('$')
+  if (parts.length !== 3 || parts[0] !== 'scrypt') return false
+  const saltHex = parts[1] as string
+  const hashHex = parts[2] as string
+  let expected: Buffer
+  try {
+    expected = Buffer.from(hashHex, 'hex')
+    const salt = Buffer.from(saltHex, 'hex')
+    const actual = scryptSync(raw, salt, expected.length, { N: SCRYPT_COST })
+    return timingSafeEqual(actual, expected)
+  } catch {
+    return false
+  }
+}

control-plane/src/util/ids.ts

@@ -0,0 +1,10 @@
+/** Identifier + timestamp helpers. UUIDv4 host/account/session ids are unguessable (INV1). */
+import { randomUUID } from 'node:crypto'
+
+export function newUuid(): string {
+  return randomUUID()
+}
+
+export function nowIso(): string {
+  return new Date().toISOString()
+}

control-plane/test/api-extra.test.ts

@@ -0,0 +1,102 @@
+import { describe, test, expect, beforeEach } from 'vitest'
+import type { FastifyInstance } from 'fastify'
+import { createMemoryStores } from '../src/store/memory.js'
+import { buildControlPlane } from '../src/main.js'
+import { loadEnv } from '../src/env.js'
+import { generateEd25519 } from '../src/util/crypto.js'
+import { buildCsr } from '../src/ca/csr.js'
+import { bytesToBase64 } from '../src/util/bytes.js'
+import { nodeIdentityFromRequest, type RequestWithTls } from '../src/node-auth/identity.js'
+import type { CapabilityVerifier } from '../src/api/authz.js'
+import type { CapabilityToken, CapabilityRight } from 'relay-contracts'
+import type { Stores } from '../src/store/ports.js'
+
+const ACCOUNT_A = '11111111-1111-4111-8111-111111111111'
+
+const env = loadEnv({
+  PG_URL: 'postgres://u:p@localhost:5432/cp',
+  REDIS_URL: 'redis://localhost:6379',
+  CAPABILITY_SIGN_PUBKEY_B64: bytesToBase64(new Uint8Array(32).fill(1)),
+  CA_INTERMEDIATE_KMS_KEY_REF: 'kms://key/intermediate',
+  CA_INTERMEDIATE_CERT_PATH: '/etc/cp/int.pem',
+  NODE_MTLS_TRUST_BUNDLE_PATH: '/etc/cp/node-ca.pem',
+  BASE_DOMAIN: 'term.example.com',
+})
+
+const verifier: CapabilityVerifier = {
+  verify(raw, expectedAud, now): CapabilityToken {
+    if (raw !== 'tokenA') throw new Error('invalid token')
+    return { sub: ACCOUNT_A, aud: expectedAud, host: 'x', rights: ['manage'] as CapabilityRight[], iat: now, exp: now + 3600, jti: 'jti-A' }
+  },
+}
+
+let app: FastifyInstance
+let stores: Stores
+
+beforeEach(async () => {
+  stores = createMemoryStores()
+  const built = await buildControlPlane(env, { stores, verifier })
+  app = built.app
+  await app.ready()
+})
+
+const auth = { authorization: 'Bearer tokenA' }
+
+describe('T11 provisioning API — remaining routes', () => {
+  test('POST /accounts creates an account (201)', async () => {
+    const res = await app.inject({ method: 'POST', url: '/accounts', headers: auth, payload: { plan: 'pro' } })
+    expect(res.statusCode).toBe(201)
+    expect(JSON.parse(res.body).plan).toBe('pro')
+  })
+
+  test('POST /accounts/:id/status suspends own account', async () => {
+    // must be the caller's own account id (A) — create A explicitly in store
+    const { createAccountRegistry } = await import('../src/registry/accounts.js')
+    const reg = createAccountRegistry({ accounts: stores.accounts })
+    await stores.accounts.insert({ accountId: ACCOUNT_A, plan: 'free', createdAt: new Date().toISOString(), status: 'active' })
+    void reg
+    const res = await app.inject({ method: 'POST', url: `/accounts/${ACCOUNT_A}/status`, headers: auth, payload: { status: 'suspended' } })
+    expect(res.statusCode).toBe(200)
+    expect(JSON.parse(res.body).status).toBe('suspended')
+  })
+
+  test('GET /accounts/:id/hosts returns ownership-scoped list', async () => {
+    const res = await app.inject({ method: 'GET', url: `/accounts/${ACCOUNT_A}/hosts`, headers: auth })
+    expect(res.statusCode).toBe(200)
+    expect(Array.isArray(JSON.parse(res.body))).toBe(true)
+  })
+
+  test('end-to-end enroll: issue code then POST /enroll → 201 EnrollResult', async () => {
+    const issued = await app.inject({ method: 'POST', url: `/accounts/${ACCOUNT_A}/pairing-codes`, headers: auth })
+    const code = JSON.parse(issued.body).code as string
+    const { publicKeyRaw, privateKey } = generateEd25519()
+    const res = await app.inject({
+      method: 'POST',
+      url: '/enroll',
+      payload: {
+        code,
+        agentPubkey: bytesToBase64(publicKeyRaw),
+        csr: bytesToBase64(buildCsr(privateKey, publicKeyRaw)),
+      },
+    })
+    expect(res.statusCode).toBe(201)
+    const body = JSON.parse(res.body)
+    expect(body.subdomain).toBeDefined()
+    expect(body.cert).toContain('BEGIN CERTIFICATE')
+    expect(typeof body.hostContentSecret).toBe('string')
+  })
+})
+
+describe('T9 nodeIdentityFromRequest wrapper', () => {
+  test('derives nodeId from an authorized TLS peer cert subject CN', () => {
+    const req: RequestWithTls = {
+      socket: { authorized: true, getPeerCertificate: () => ({ subject: { CN: 'spiffe://relay/node-7' } }) },
+    }
+    expect(nodeIdentityFromRequest(req).nodeId).toBe('spiffe://relay/node-7')
+  })
+
+  test('unauthenticated socket → 401', () => {
+    const req: RequestWithTls = { socket: { authorized: false, getPeerCertificate: () => undefined } }
+    expect(() => nodeIdentityFromRequest(req)).toThrow(/mutually authenticated/)
+  })
+})

control-plane/test/api.test.ts

@@ -0,0 +1,96 @@
+import { describe, test, expect, beforeEach } from 'vitest'
+import type { FastifyInstance } from 'fastify'
+import { createMemoryStores } from '../src/store/memory.js'
+import { createHostRegistry } from '../src/registry/hosts.js'
+import { buildControlPlane } from '../src/main.js'
+import { loadEnv } from '../src/env.js'
+import { fingerprint } from '../src/ca/fingerprint.js'
+import { generateEd25519 } from '../src/util/crypto.js'
+import { bytesToBase64 } from '../src/util/bytes.js'
+import type { CapabilityVerifier } from '../src/api/authz.js'
+import type { CapabilityToken, CapabilityRight } from 'relay-contracts'
+import type { Stores } from '../src/store/ports.js'
+
+const ACCOUNT_A = '11111111-1111-4111-8111-111111111111'
+const ACCOUNT_B = '22222222-2222-4222-8222-222222222222'
+
+const env = loadEnv({
+  PG_URL: 'postgres://u:p@localhost:5432/cp',
+  REDIS_URL: 'redis://localhost:6379',
+  CAPABILITY_SIGN_PUBKEY_B64: bytesToBase64(new Uint8Array(32).fill(1)),
+  CA_INTERMEDIATE_KMS_KEY_REF: 'kms://key/intermediate',
+  CA_INTERMEDIATE_CERT_PATH: '/etc/cp/int.pem',
+  NODE_MTLS_TRUST_BUNDLE_PATH: '/etc/cp/node-ca.pem',
+  BASE_DOMAIN: 'term.example.com',
+})
+
+// Fake P5 verifier: 'tokenA'→account A (manage), 'attachA'→account A (attach only). Else reject.
+const verifier: CapabilityVerifier = {
+  verify(raw, expectedAud, now): CapabilityToken {
+    const base = { aud: expectedAud, host: 'x', iat: now, exp: now + 3600, jti: `jti-${raw}` }
+    if (raw === 'tokenA') return { ...base, sub: ACCOUNT_A, rights: ['manage'] as CapabilityRight[] }
+    if (raw === 'attachA') return { ...base, sub: ACCOUNT_A, rights: ['attach'] as CapabilityRight[] }
+    throw new Error('invalid token')
+  },
+}
+
+let app: FastifyInstance
+let stores: Stores
+let hostOfB: string
+
+beforeEach(async () => {
+  stores = createMemoryStores()
+  const built = await buildControlPlane(env, { stores, verifier })
+  app = built.app
+  await app.ready()
+  // Bind a host owned by account B directly.
+  const hosts = createHostRegistry({ hosts: stores.hosts })
+  const { publicKeyRaw } = generateEd25519()
+  const host = await hosts.bindHost({ accountId: ACCOUNT_B, subdomain: 'bob', agentPubkey: publicKeyRaw, enrollFpr: fingerprint(publicKeyRaw) })
+  hostOfB = host.hostId
+})
+
+describe('T11 provisioning API (INV3/INV1/INV6)', () => {
+  test('HEADLINE: account A with forged {account_id:B} deleting B-owned host → 403', async () => {
+    const res = await app.inject({
+      method: 'DELETE',
+      url: `/hosts/${hostOfB}`,
+      headers: { authorization: 'Bearer tokenA' },
+      payload: { account_id: ACCOUNT_B }, // forged — must be ignored
+    })
+    expect(res.statusCode).toBe(403)
+  })
+
+  test('missing token → 401', async () => {
+    const res = await app.inject({ method: 'DELETE', url: `/hosts/${hostOfB}` })
+    expect(res.statusCode).toBe(401)
+  })
+
+  test('attach-scoped token cannot hit a manage route → 403', async () => {
+    const res = await app.inject({ method: 'DELETE', url: `/hosts/${hostOfB}`, headers: { authorization: 'Bearer attachA' } })
+    expect(res.statusCode).toBe(403)
+  })
+
+  test('owner CAN deprovision its own host → 204', async () => {
+    // give A its own host
+    const hosts = createHostRegistry({ hosts: stores.hosts })
+    const { publicKeyRaw } = generateEd25519()
+    const own = await hosts.bindHost({ accountId: ACCOUNT_A, subdomain: 'alice', agentPubkey: publicKeyRaw, enrollFpr: fingerprint(publicKeyRaw) })
+    const res = await app.inject({ method: 'DELETE', url: `/hosts/${own.hostId}`, headers: { authorization: 'Bearer tokenA' } })
+    expect(res.statusCode).toBe(204)
+    expect((await stores.hosts.get(own.hostId))?.status).toBe('revoked')
+  })
+
+  test('pairing-code route scoped to own account; foreign :id → 403', async () => {
+    const ok = await app.inject({ method: 'POST', url: `/accounts/${ACCOUNT_A}/pairing-codes`, headers: { authorization: 'Bearer tokenA' } })
+    expect(ok.statusCode).toBe(201)
+    expect(JSON.parse(ok.body).code).toBeDefined()
+    const foreign = await app.inject({ method: 'POST', url: `/accounts/${ACCOUNT_B}/pairing-codes`, headers: { authorization: 'Bearer tokenA' } })
+    expect(foreign.statusCode).toBe(403)
+  })
+
+  test('malformed enroll body → 400 (Zod at the boundary)', async () => {
+    const res = await app.inject({ method: 'POST', url: '/enroll', payload: { code: '' } })
+    expect(res.statusCode).toBe(400)
+  })
+})

control-plane/test/audit.test.ts

@@ -0,0 +1,61 @@
+import { describe, test, expect } from 'vitest'
+import { createMemoryStores } from '../src/store/memory.js'
+import { createAuditLog, MAX_META_VALUE_LEN } from '../src/audit/log.js'
+import { createAccountRegistry } from '../src/registry/accounts.js'
+import { createHostRegistry } from '../src/registry/hosts.js'
+import { fingerprint } from '../src/ca/fingerprint.js'
+import { generateEd25519 } from '../src/util/crypto.js'
+
+describe('T14 audit log (INV10 zero payload)', () => {
+  test('rejects a meta value carrying control/ANSI bytes (terminal payload guard)', async () => {
+    const { audit } = createMemoryStores()
+    const log = createAuditLog(audit)
+    await expect(
+      log.writeAuditEvent({
+        action: 'attach',
+        principalId: 'p',
+        accountId: 'a',
+        hostId: null,
+        ts: new Date().toISOString(),
+        meta: { out: 'ls\r\noutput' }, // looks like shell output
+      }),
+    ).rejects.toThrow(/payload guard/)
+  })
+
+  test('rejects an over-long meta value', async () => {
+    const { audit } = createMemoryStores()
+    const log = createAuditLog(audit)
+    await expect(
+      log.writeAuditEvent({
+        action: 'manage',
+        principalId: 'p',
+        accountId: 'a',
+        hostId: null,
+        ts: new Date().toISOString(),
+        meta: { blob: 'x'.repeat(MAX_META_VALUE_LEN + 1) },
+      }),
+    ).rejects.toThrow(/payload guard/)
+  })
+
+  test('append-only: entries are queryable, no update/delete surface exists', async () => {
+    const { audit } = createMemoryStores()
+    const log = createAuditLog(audit)
+    await log.writeAuditEvent({ action: 'kill', principalId: 'p', accountId: 'acct', hostId: 'h', ts: new Date().toISOString(), meta: {} })
+    const rows = await log.queryAudit('acct', '1970-01-01T00:00:00.000Z', '2999-01-01T00:00:00.000Z')
+    expect(rows.length).toBe(1)
+    expect(Object.keys(log)).not.toContain('update')
+    expect(Object.keys(log)).not.toContain('delete')
+  })
+
+  test('control-plane mutations emit audit entries (create + bind)', async () => {
+    const stores = createMemoryStores()
+    const log = createAuditLog(stores.audit)
+    const accounts = createAccountRegistry({ accounts: stores.accounts, audit: log })
+    const hosts = createHostRegistry({ hosts: stores.hosts, audit: log })
+    const acct = await accounts.createAccount('pro')
+    const { publicKeyRaw } = generateEd25519()
+    await hosts.bindHost({ accountId: acct.accountId, subdomain: 'alice', agentPubkey: publicKeyRaw, enrollFpr: fingerprint(publicKeyRaw) })
+    const rows = await log.queryAudit(acct.accountId, '1970-01-01T00:00:00.000Z', '2999-01-01T00:00:00.000Z')
+    expect(rows.map((r) => r.action).sort()).toEqual(['account.create', 'host.bind'])
+  })
+})

control-plane/test/ca.test.ts

@@ -0,0 +1,73 @@
+import { describe, test, expect, vi } from 'vitest'
+import { createMemoryStores } from '../src/store/memory.js'
+import { createHostRegistry } from '../src/registry/hosts.js'
+import { createLeafSigner, LeafSignError } from '../src/ca/sign.js'
+import { inProcessCaSigner } from '../src/boot/ca-wiring.js'
+import { buildCsr, verifyCsrPoP } from '../src/ca/csr.js'
+import { fingerprint } from '../src/ca/fingerprint.js'
+import { generateEd25519, sealToX25519, openFromX25519, generateX25519 } from '../src/util/crypto.js'
+import { randomBytes } from 'node:crypto'
+
+function boundHost() {
+  const stores = createMemoryStores()
+  const hosts = createHostRegistry({ hosts: stores.hosts })
+  return { stores, hosts }
+}
+
+describe('T8 signHostLeaf — INV14 registry-gated + CSR PoP', () => {
+  test('active registered host + valid CSR → cert signed under CA', async () => {
+    const { stores, hosts } = boundHost()
+    const { publicKeyRaw, privateKey } = generateEd25519()
+    const host = await hosts.bindHost({ accountId: '11111111-1111-4111-8111-111111111111', subdomain: 'alice', agentPubkey: publicKeyRaw, enrollFpr: fingerprint(publicKeyRaw) })
+    const signer = createLeafSigner({ hosts: stores.hosts, signer: inProcessCaSigner(), caChainDer: [] })
+    const { cert } = await signer.signHostLeaf(host.hostId, publicKeyRaw, buildCsr(privateKey, publicKeyRaw))
+    expect(cert.length).toBeGreaterThan(0)
+  })
+
+  test('CSR proof-of-possession fails even for a registered active key → reject, KMS never called', async () => {
+    const { stores, hosts } = boundHost()
+    const { publicKeyRaw } = generateEd25519()
+    const host = await hosts.bindHost({ accountId: '11111111-1111-4111-8111-111111111111', subdomain: 'alice', agentPubkey: publicKeyRaw, enrollFpr: fingerprint(publicKeyRaw) })
+    const spy = inProcessCaSigner()
+    const signSpy = vi.spyOn(spy, 'sign')
+    const signer = createLeafSigner({ hosts: stores.hosts, signer: spy, caChainDer: [] })
+    // forge a CSR: correct embedded pub but a garbage signature
+    const forged = new Uint8Array(96)
+    forged.set(publicKeyRaw, 0)
+    forged.set(randomBytes(64), 32)
+    expect(verifyCsrPoP(forged).ok).toBe(false)
+    await expect(signer.signHostLeaf(host.hostId, publicKeyRaw, forged)).rejects.toBeInstanceOf(LeafSignError)
+    expect(signSpy).not.toHaveBeenCalled()
+  })
+
+  test('INV14 gate: unregistered pubkey → throws, KMS sign never invoked', async () => {
+    const { stores } = boundHost()
+    const { publicKeyRaw, privateKey } = generateEd25519()
+    const spy = inProcessCaSigner()
+    const signSpy = vi.spyOn(spy, 'sign')
+    const signer = createLeafSigner({ hosts: stores.hosts, signer: spy, caChainDer: [] })
+    await expect(signer.signHostLeaf('00000000-0000-4000-8000-000000000000', publicKeyRaw, buildCsr(privateKey, publicKeyRaw))).rejects.toBeInstanceOf(LeafSignError)
+    expect(signSpy).not.toHaveBeenCalled()
+  })
+
+  test('revoked host cannot be signed (INV12+INV14)', async () => {
+    const { stores, hosts } = boundHost()
+    const { publicKeyRaw, privateKey } = generateEd25519()
+    const host = await hosts.bindHost({ accountId: '11111111-1111-4111-8111-111111111111', subdomain: 'alice', agentPubkey: publicKeyRaw, enrollFpr: fingerprint(publicKeyRaw) })
+    await hosts.setHostStatus(host.hostId, 'revoked')
+    const signer = createLeafSigner({ hosts: stores.hosts, signer: inProcessCaSigner(), caChainDer: [] })
+    await expect(signer.signHostLeaf(host.hostId, publicKeyRaw, buildCsr(privateKey, publicKeyRaw))).rejects.toBeInstanceOf(LeafSignError)
+  })
+})
+
+describe('host content-secret wrap (FIX 3 security property)', () => {
+  test('only the matching private key can unwrap; raw secret absent from blob', () => {
+    const recipient = generateX25519()
+    const secret = new Uint8Array(randomBytes(32))
+    const blob = sealToX25519(recipient.publicKeyRaw, secret)
+    expect(Buffer.from(blob).includes(Buffer.from(secret))).toBe(false) // raw secret not in ciphertext
+    expect(Buffer.from(openFromX25519(recipient.privateKey, blob)).equals(Buffer.from(secret))).toBe(true)
+    const wrong = generateX25519()
+    expect(() => openFromX25519(wrong.privateKey, blob)).toThrow()
+  })
+})

control-plane/test/db.test.ts

@@ -0,0 +1,21 @@
+import { describe, test, expect } from 'vitest'
+import { createQuery, type Queryable } from '../src/db/pool.js'
+
+describe('T2 parameterized query wrapper (no SQLi path)', () => {
+  test('passes params SEPARATELY from SQL text — never interpolated', async () => {
+    const calls: { text: string; params: readonly unknown[] }[] = []
+    const fake: Queryable = {
+      async query(text, params) {
+        calls.push({ text, params })
+        return { rows: [{ ok: 1 }] }
+      },
+    }
+    const query = createQuery(fake)
+    const rows = await query<{ ok: number }>('SELECT * FROM hosts WHERE host_id = $1', ["'; DROP TABLE hosts; --"])
+    expect(rows).toEqual([{ ok: 1 }])
+    expect(calls[0]?.text).toBe('SELECT * FROM hosts WHERE host_id = $1')
+    // The malicious value stays a bound param — it is NOT concatenated into the SQL text.
+    expect(calls[0]?.text).not.toContain('DROP TABLE')
+    expect(calls[0]?.params).toEqual(["'; DROP TABLE hosts; --"])
+  })
+})

control-plane/test/env.test.ts

@@ -0,0 +1,68 @@
+import { describe, test, expect } from 'vitest'
+import { loadEnv, DEFAULT_PAIRING_TTL_SEC, DEFAULT_PAIRING_MAX_REDEEM_ATTEMPTS } from '../src/env.js'
+import { bytesToBase64 } from '../src/util/bytes.js'
+
+const validPubkey = bytesToBase64(new Uint8Array(32).fill(7))
+
+const base = (): NodeJS.ProcessEnv => ({
+  PG_URL: 'postgres://u:p@localhost:5432/cp',
+  REDIS_URL: 'redis://localhost:6379',
+  CAPABILITY_SIGN_PUBKEY_B64: validPubkey,
+  CA_INTERMEDIATE_KMS_KEY_REF: 'kms://key/intermediate',
+  CA_INTERMEDIATE_CERT_PATH: '/etc/cp/intermediate.pem',
+  NODE_MTLS_TRUST_BUNDLE_PATH: '/etc/cp/node-ca.pem',
+  BASE_DOMAIN: 'term.example.com',
+})
+
+describe('T1 loadEnv (INV9 fail-fast)', () => {
+  test('empty env throws listing every missing required key', () => {
+    let msg = ''
+    try {
+      loadEnv({})
+    } catch (e) {
+      msg = e instanceof Error ? e.message : ''
+    }
+    expect(msg).toContain('PG_URL')
+    expect(msg).toContain('REDIS_URL')
+    expect(msg).toContain('CAPABILITY_SIGN_PUBKEY_B64')
+    expect(msg).toContain('CA_INTERMEDIATE_KMS_KEY_REF')
+    expect(msg).toContain('BASE_DOMAIN')
+  })
+
+  test('bad pgUrl throws', () => {
+    expect(() => loadEnv({ ...base(), PG_URL: 'not a url' })).toThrow(/PG_URL/)
+  })
+
+  test('valid map parses', () => {
+    const env = loadEnv(base())
+    expect(env.baseDomain).toBe('term.example.com')
+    expect(env.capabilitySignPubkey.length).toBe(32)
+  })
+
+  test('pairing ttl / max-attempts default when unset', () => {
+    const env = loadEnv(base())
+    expect(env.pairingTtlSec).toBe(DEFAULT_PAIRING_TTL_SEC)
+    expect(env.pairingMaxRedeemAttempts).toBe(DEFAULT_PAIRING_MAX_REDEEM_ATTEMPTS)
+  })
+
+  test('explicit pairing overrides parse', () => {
+    const env = loadEnv({ ...base(), PAIRING_TTL_SEC: '900', PAIRING_MAX_REDEEM_ATTEMPTS: '3' })
+    expect(env.pairingTtlSec).toBe(900)
+    expect(env.pairingMaxRedeemAttempts).toBe(3)
+  })
+
+  test('never echoes secret VALUES on failure (INV9)', () => {
+    const secret = bytesToBase64(new Uint8Array(32).fill(9))
+    try {
+      loadEnv({ ...base(), CAPABILITY_SIGN_PUBKEY_B64: secret, PG_URL: 'bad' })
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : ''
+      expect(msg).not.toContain(secret)
+    }
+  })
+
+  test('capability pubkey wrong length rejected', () => {
+    const short = bytesToBase64(new Uint8Array(16))
+    expect(() => loadEnv({ ...base(), CAPABILITY_SIGN_PUBKEY_B64: short })).toThrow(/32 bytes/)
+  })
+})

control-plane/test/flat-store.test.ts

@@ -0,0 +1,40 @@
+import { describe, test, expect } from 'vitest'
+import { createFlatStore, inMemoryFlatBackend } from '../src/flat-store.js'
+
+describe('T0 flat store (v0.8 MVP)', () => {
+  test('provisionFlat stores hashes only — no raw token at rest (INV5)', async () => {
+    // Arrange
+    const backend = inMemoryFlatBackend()
+    const store = createFlatStore(backend)
+
+    // Act
+    const { agentToken, clientToken } = await store.provisionFlat('alice')
+    const row = await backend.bySubdomain('alice')
+
+    // Assert
+    expect(row).not.toBeNull()
+    const serialized = JSON.stringify(row)
+    expect(serialized).not.toContain(agentToken)
+    expect(serialized).not.toContain(clientToken)
+    expect(row?.agentTokenHash.startsWith('scrypt$')).toBe(true)
+  })
+
+  test('verifyAgentToken true for correct token, false for wrong', async () => {
+    const store = createFlatStore()
+    const { agentToken } = await store.provisionFlat('bob')
+    expect(await store.verifyAgentToken('bob', agentToken)).toBe(true)
+    expect(await store.verifyAgentToken('bob', 'wrong-token')).toBe(false)
+  })
+
+  test('unknown subdomain resolves to null / false', async () => {
+    const store = createFlatStore()
+    expect(await store.lookupBySubdomain('nope')).toBeNull()
+    expect(await store.verifyAgentToken('nope', 'x')).toBe(false)
+  })
+
+  test('two provisions of the same subdomain collide', async () => {
+    const store = createFlatStore()
+    await store.provisionFlat('carol')
+    await expect(store.provisionFlat('carol')).rejects.toThrow(/already provisioned/)
+  })
+})

control-plane/test/metering.test.ts

@@ -0,0 +1,62 @@
+import { describe, test, expect } from 'vitest'
+import { createMemoryStores } from '../src/store/memory.js'
+import { createHostRegistry } from '../src/registry/hosts.js'
+import { createMeteringCollector, MeteringError } from '../src/metering/collect.js'
+import { fingerprint } from '../src/ca/fingerprint.js'
+import { generateEd25519 } from '../src/util/crypto.js'
+import type { NodeIdentity } from '../src/node-auth/identity.js'
+
+const node: NodeIdentity = { nodeId: 'spiffe://relay/node-a' }
+const ACCOUNT = '11111111-1111-4111-8111-111111111111'
+
+async function withHost() {
+  const stores = createMemoryStores()
+  const hosts = createHostRegistry({ hosts: stores.hosts })
+  const { publicKeyRaw } = generateEd25519()
+  const host = await hosts.bindHost({ accountId: ACCOUNT, subdomain: 'alice', agentPubkey: publicKeyRaw, enrollFpr: fingerprint(publicKeyRaw) })
+  const collector = createMeteringCollector({ metering: stores.metering, hosts })
+  return { stores, hosts, host, collector }
+}
+
+describe('T12 metering (INV1/INV3-analog/INV8)', () => {
+  test('ingestSample derives accountId + nodeId server-side; append-only', async () => {
+    const { stores, host, collector } = await withHost()
+    await collector.ingestSample(node, { hostId: host.hostId, concurrentViewers: 3, sampledAt: new Date().toISOString() })
+    const rows = await stores.metering.query(ACCOUNT, '1970-01-01T00:00:00.000Z', '2999-01-01T00:00:00.000Z')
+    expect(rows.length).toBe(1)
+    expect(rows[0]?.accountId).toBe(ACCOUNT)
+    expect(rows[0]?.nodeId).toBe(node.nodeId)
+  })
+
+  test('forged attribution: unknown hostId rejected (cross-tenant metering impossible, INV1)', async () => {
+    const { collector } = await withHost()
+    await expect(
+      collector.ingestSample(node, { hostId: '99999999-9999-4999-8999-999999999999', concurrentViewers: 1, sampledAt: new Date().toISOString() }),
+    ).rejects.toBeInstanceOf(MeteringError)
+  })
+
+  test('pairedHostCount excludes revoked hosts', async () => {
+    const { hosts, host, collector } = await withHost()
+    expect(await collector.pairedHostCount(ACCOUNT)).toBe(1)
+    await hosts.setHostStatus(host.hostId, 'revoked')
+    expect(await collector.pairedHostCount(ACCOUNT)).toBe(0)
+  })
+
+  test('rollupUsage computes viewer peak + viewer-hours over a window', async () => {
+    const { host, collector } = await withHost()
+    const t0 = '2026-06-30T00:00:00.000Z'
+    const t1 = '2026-06-30T01:00:00.000Z'
+    const to = '2026-06-30T02:00:00.000Z'
+    await collector.ingestSample(node, { hostId: host.hostId, concurrentViewers: 2, sampledAt: t0 })
+    await collector.ingestSample(node, { hostId: host.hostId, concurrentViewers: 4, sampledAt: t1 })
+    const usage = await collector.rollupUsage(ACCOUNT, t0, to)
+    expect(usage.viewerPeak).toBe(4)
+    expect(usage.viewerHours).toBeCloseTo(2 * 1 + 4 * 1, 5) // 2 viewers×1h + 4 viewers×1h
+    expect(usage.pairedHostPeak).toBe(1)
+  })
+
+  test('malformed sample → Zod error', async () => {
+    const { collector } = await withHost()
+    await expect(collector.ingestSample(node, { hostId: 'not-a-uuid', concurrentViewers: -1, sampledAt: 'x' })).rejects.toBeInstanceOf(MeteringError)
+  })
+})

control-plane/test/pairing.test.ts

@@ -0,0 +1,134 @@
+import { describe, test, expect } from 'vitest'
+import { createMemoryStores } from '../src/store/memory.js'
+import { createHostRegistry } from '../src/registry/hosts.js'
+import { createSubdomainAssigner } from '../src/subdomain/assign.js'
+import { createPairingIssuer } from '../src/pairing/issue.js'
+import { createPairingRedeemer, RedeemError } from '../src/pairing/redeem.js'
+import { createLeafSigner } from '../src/ca/sign.js'
+import { inProcessCaSigner, type CaSigner } from '../src/boot/ca-wiring.js'
+import { buildCsr } from '../src/ca/csr.js'
+import { generatePairingCode, formatPairingCode, normalizePairingCode, PAIRING_CODE_BITS } from '../src/pairing/code.js'
+import { sha256Hex } from '../src/util/hash.js'
+import { generateEd25519 } from '../src/util/crypto.js'
+
+const ACCOUNT = '11111111-1111-4111-8111-111111111111'
+
+function harness(opts?: { ttlSec?: number; maxAttempts?: number; signer?: CaSigner }) {
+  const stores = createMemoryStores()
+  const hosts = createHostRegistry({ hosts: stores.hosts })
+  const subdomains = createSubdomainAssigner({ subdomains: stores.subdomains })
+  const signer = opts?.signer ?? inProcessCaSigner()
+  const leafSigner = createLeafSigner({ hosts: stores.hosts, signer, caChainDer: [new Uint8Array([1, 2, 3])] })
+  const issuer = createPairingIssuer({ pairing: stores.pairing, pairingTtlSec: opts?.ttlSec ?? 600 })
+  const redeemer = createPairingRedeemer({
+    pairing: stores.pairing,
+    hosts,
+    subdomains,
+    leafSigner,
+    pairingMaxRedeemAttempts: opts?.maxAttempts ?? 5,
+  })
+  return { stores, issuer, redeemer }
+}
+
+function agentEnroll() {
+  const { publicKeyRaw, privateKey } = generateEd25519()
+  return { agentPubkey: publicKeyRaw, csr: buildCsr(privateKey, publicKeyRaw) }
+}
+
+describe('T7 pairing issuance (INV5, entropy)', () => {
+  test('code is >= 128-bit entropy, display round-trips to canonical', () => {
+    expect(PAIRING_CODE_BITS).toBeGreaterThanOrEqual(128)
+    const canonical = generatePairingCode()
+    expect(canonical.length).toBe(26)
+    expect(normalizePairingCode(formatPairingCode(canonical))).toBe(canonical)
+  })
+
+  test('stored row holds code_hash only — no raw code at rest (INV5)', async () => {
+    const { stores, issuer } = harness()
+    const { code } = await issuer.issuePairingCode(ACCOUNT)
+    const codeHash = sha256Hex(normalizePairingCode(code))
+    const row = await stores.pairing.get(codeHash)
+    expect(row).not.toBeNull()
+    expect(JSON.stringify(row)).not.toContain(normalizePairingCode(code))
+    expect(row?.redeemAttempts).toBe(0)
+  })
+
+  test('two issues → two distinct codes', async () => {
+    const { issuer } = harness()
+    const a = await issuer.issuePairingCode(ACCOUNT)
+    const b = await issuer.issuePairingCode(ACCOUNT)
+    expect(a.code).not.toBe(b.code)
+  })
+})
+
+describe('T8 redemption + BIND + cert + content-secret', () => {
+  test('happy path → EnrollResult with frozen fields, subject pubkey == agentPubkey', async () => {
+    const { issuer, redeemer } = harness()
+    const { code } = await issuer.issuePairingCode(ACCOUNT)
+    const { agentPubkey, csr } = agentEnroll()
+    const result = await redeemer.redeemPairingCode({ code, agentPubkey, csr })
+    expect(result.hostId).toMatch(/[0-9a-f-]{36}/)
+    expect(result.subdomain.length).toBeGreaterThan(0)
+    expect(result.cert).toContain('BEGIN CERTIFICATE')
+    expect(result.caChain).toContain('BEGIN CERTIFICATE')
+    expect(result.hostContentSecret.length).toBeGreaterThan(0)
+    // subject pubkey inside the cert == agentPubkey
+    const certJson = JSON.parse(Buffer.from(result.cert.split('\n').slice(1, -2).join(''), 'base64').toString())
+    const tbs = JSON.parse(Buffer.from(certJson.tbs, 'base64').toString())
+    expect(tbs.subjectSpki).toBe(Buffer.from(agentPubkey).toString('base64'))
+  })
+
+  test('hostContentSecret: wrapped, raw secret absent, distinct per enrollment (FIX 3)', async () => {
+    const { issuer, redeemer } = harness()
+    const c1 = (await issuer.issuePairingCode(ACCOUNT)).code
+    const c2 = (await issuer.issuePairingCode(ACCOUNT)).code
+    const r1 = await redeemer.redeemPairingCode({ code: c1, ...agentEnroll() })
+    const r2 = await redeemer.redeemPairingCode({ code: c2, ...agentEnroll() })
+    expect(Buffer.from(r1.hostContentSecret).equals(Buffer.from(r2.hostContentSecret))).toBe(false)
+  })
+
+  test('double-spend: two concurrent redeems → exactly one wins (CAS)', async () => {
+    const { issuer, redeemer } = harness()
+    const { code } = await issuer.issuePairingCode(ACCOUNT)
+    const results = await Promise.allSettled([
+      redeemer.redeemPairingCode({ code, ...agentEnroll() }),
+      redeemer.redeemPairingCode({ code, ...agentEnroll() }),
+    ])
+    const ok = results.filter((r) => r.status === 'fulfilled')
+    const rejected = results.filter((r) => r.status === 'rejected')
+    expect(ok.length).toBe(1)
+    expect(rejected.length).toBe(1)
+    expect((rejected[0] as PromiseRejectedResult).reason).toBeInstanceOf(RedeemError)
+    expect(((rejected[0] as PromiseRejectedResult).reason as RedeemError).code).toBe('already_redeemed')
+  })
+
+  test('expired / unknown / CSR-substitution rejected', async () => {
+    const expiredH = harness({ ttlSec: -10 })
+    const { code } = await expiredH.issuer.issuePairingCode(ACCOUNT)
+    await expect(expiredH.redeemer.redeemPairingCode({ code, ...agentEnroll() })).rejects.toMatchObject({ code: 'expired' })
+
+    const h = harness()
+    await expect(h.redeemer.redeemPairingCode({ code: 'ZZZZZ-ZZZZZ-ZZZZZ-ZZZZZ-ZZZZZ-Z', ...agentEnroll() })).rejects.toMatchObject({ code: 'unknown' })
+
+    // CSR embeds a DIFFERENT pubkey than the presented agentPubkey → bad_csr
+    const good = (await h.issuer.issuePairingCode(ACCOUNT)).code
+    const a = generateEd25519()
+    const b = generateEd25519()
+    const substitutedCsr = buildCsr(b.privateKey, b.publicKeyRaw)
+    await expect(h.redeemer.redeemPairingCode({ code: good, agentPubkey: a.publicKeyRaw, csr: substitutedCsr })).rejects.toMatchObject({ code: 'bad_csr' })
+  })
+
+  test('code-scoped lockout after maxAttempts — correct code then refused (Finding-4)', async () => {
+    const h = harness({ maxAttempts: 3 })
+    const { code } = await h.issuer.issuePairingCode(ACCOUNT)
+    const bad = generateEd25519()
+    const badCsr = buildCsr(bad.privateKey, bad.publicKeyRaw)
+    const victim = agentEnroll()
+    for (let i = 0; i < 3; i++) {
+      // substitution failure against the SAME code_hash
+      await expect(h.redeemer.redeemPairingCode({ code, agentPubkey: victim.agentPubkey, csr: badCsr })).rejects.toMatchObject({ code: 'bad_csr' })
+    }
+    // now even a correct redemption is locked out
+    await expect(h.redeemer.redeemPairingCode({ code, ...victim })).rejects.toMatchObject({ code: 'too_many_attempts' })
+  })
+})

control-plane/test/registry.test.ts

@@ -0,0 +1,148 @@
+import { describe, test, expect } from 'vitest'
+import { createMemoryStores } from '../src/store/memory.js'
+import { createAccountRegistry } from '../src/registry/accounts.js'
+import { createHostRegistry } from '../src/registry/hosts.js'
+import { createSessionRegistry } from '../src/registry/sessions.js'
+import {
+  createSubdomainAssigner,
+  isValidSubdomain,
+  normalizeSubdomain,
+  assembleFqdn,
+} from '../src/subdomain/assign.js'
+import { fingerprint } from '../src/ca/fingerprint.js'
+import { generateEd25519 } from '../src/util/crypto.js'
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
+
+function bindInput(accountId: string, subdomain: string) {
+  const { publicKeyRaw } = generateEd25519()
+  return { accountId, subdomain, agentPubkey: publicKeyRaw, enrollFpr: fingerprint(publicKeyRaw) }
+}
+
+describe('T3 account registry (INV8)', () => {
+  test('createAccount returns unguessable uuid + active status + seed version', async () => {
+    const { accounts } = createMemoryStores()
+    const reg = createAccountRegistry({ accounts })
+    const a = await reg.createAccount('pro')
+    expect(a.accountId).toMatch(UUID_RE)
+    expect(a.status).toBe('active')
+    expect((await accounts.versions(a.accountId)).length).toBe(1)
+  })
+
+  test('setAccountStatus swaps snapshot; prior version stays readable from versions table', async () => {
+    const { accounts } = createMemoryStores()
+    const reg = createAccountRegistry({ accounts })
+    const a = await reg.createAccount('free')
+    const next = await reg.setAccountStatus(a.accountId, 'suspended')
+    expect(next.status).toBe('suspended')
+    const versions = await accounts.versions(a.accountId)
+    expect(versions.map((v) => v.status)).toEqual(['active', 'suspended'])
+    expect(versions.map((v) => v.version)).toEqual([1, 2]) // strictly monotonic
+  })
+
+  test('concurrent setAccountStatus → monotonic versions, no torn read (INV8)', async () => {
+    const { accounts } = createMemoryStores()
+    const reg = createAccountRegistry({ accounts })
+    const a = await reg.createAccount('team')
+    await Promise.all([
+      reg.setAccountStatus(a.accountId, 'suspended'),
+      reg.setAccountStatus(a.accountId, 'active'),
+    ])
+    const versions = await accounts.versions(a.accountId)
+    expect(versions.map((v) => v.version)).toEqual([1, 2, 3])
+  })
+})
+
+describe('T4 host registry (INV1/INV4/INV8)', () => {
+  test('bindHost stores only the public key; enrollFpr is its fingerprint (INV4)', async () => {
+    const { hosts } = createMemoryStores()
+    const reg = createHostRegistry({ hosts })
+    const inp = bindInput('11111111-1111-4111-8111-111111111111', 'alice')
+    const host = await reg.bindHost(inp)
+    expect(host.enrollFpr).toBe(fingerprint(inp.agentPubkey))
+    const dump = JSON.stringify(await hosts.get(host.hostId))
+    expect(dump).not.toContain('PRIVATE')
+  })
+
+  test('ownsHost(A, hostOwnedByB) → false (INV1 tripwire fact)', async () => {
+    const { hosts } = createMemoryStores()
+    const reg = createHostRegistry({ hosts })
+    const a = '11111111-1111-4111-8111-111111111111'
+    const b = '22222222-2222-4222-8222-222222222222'
+    const host = await reg.bindHost(bindInput(a, 'alice'))
+    expect(await reg.ownsHost(a, host.hostId)).toBe(true)
+    expect(await reg.ownsHost(b, host.hostId)).toBe(false)
+    expect(await reg.ownsHost(a, 'unknown-host')).toBe(false) // deny-by-default
+  })
+
+  test('getHostBySubdomain resolves the stable name; setHostStatus versions', async () => {
+    const { hosts } = createMemoryStores()
+    const reg = createHostRegistry({ hosts })
+    const host = await reg.bindHost(bindInput('11111111-1111-4111-8111-111111111111', 'alice'))
+    expect((await reg.getHostBySubdomain('alice'))?.hostId).toBe(host.hostId)
+    const revoked = await reg.setHostStatus(host.hostId, 'revoked')
+    expect(revoked.status).toBe('revoked')
+    expect(revoked.revokedAt).not.toBeNull()
+    const versions = await hosts.versions(host.hostId)
+    expect(versions.map((v) => v.status)).toEqual(['offline', 'revoked'])
+  })
+
+  test('touchLastSeen does NOT create a version row (advisory cache, INV7)', async () => {
+    const { hosts } = createMemoryStores()
+    const reg = createHostRegistry({ hosts })
+    const host = await reg.bindHost(bindInput('11111111-1111-4111-8111-111111111111', 'alice'))
+    await reg.touchLastSeen(host.hostId)
+    await reg.touchLastSeen(host.hostId)
+    expect((await hosts.versions(host.hostId)).length).toBe(1)
+  })
+
+  test('bindHost rejects a mismatched enrollFpr', async () => {
+    const { hosts } = createMemoryStores()
+    const reg = createHostRegistry({ hosts })
+    const inp = { ...bindInput('11111111-1111-4111-8111-111111111111', 'alice'), enrollFpr: 'deadbeef' }
+    await expect(reg.bindHost(inp)).rejects.toThrow(/enrollFpr/)
+  })
+})
+
+describe('T5 session registry (INV3/INV6)', () => {
+  test('recordSession derives account_id from the host, ignoring any caller value', async () => {
+    const stores = createMemoryStores()
+    const hostReg = createHostRegistry({ hosts: stores.hosts })
+    const sessReg = createSessionRegistry({ sessions: stores.sessions, hosts: stores.hosts })
+    const owner = '11111111-1111-4111-8111-111111111111'
+    const host = await hostReg.bindHost(bindInput(owner, 'alice'))
+    const s = await sessReg.recordSession({ sessionId: 'sess-1', hostId: host.hostId })
+    expect(s.accountId).toBe(owner)
+    expect(await sessReg.sessionAccount('sess-1')).toBe(owner)
+  })
+
+  test('unknown session → null', async () => {
+    const stores = createMemoryStores()
+    const sessReg = createSessionRegistry({ sessions: stores.sessions, hosts: stores.hosts })
+    expect(await sessReg.sessionAccount('nope')).toBeNull()
+  })
+})
+
+describe('T6 subdomain assignment (INV1)', () => {
+  test('reserved words rejected; host-confusion inputs rejected', () => {
+    for (const bad of ['www', 'api', 'admin', '_']) expect(isValidSubdomain(bad)).toBe(false)
+    expect(isValidSubdomain('a.b')).toBe(false)
+    expect(isValidSubdomain('A LICE')).toBe(false)
+    expect(isValidSubdomain('-alice')).toBe(false)
+    expect(isValidSubdomain('alice')).toBe(true)
+    expect(normalizeSubdomain('A LICE!!')).toBe('alice')
+    expect(assembleFqdn('alice', 'term.example.com')).toBe('alice.term.example.com')
+  })
+
+  test('UNIQUE collision under concurrency → exactly one winner for the exact name', async () => {
+    const { subdomains } = createMemoryStores()
+    let n = 0
+    const assigner = createSubdomainAssigner({ subdomains, suffix: () => String(n++).padStart(4, '0') })
+    const [a, b] = await Promise.all([
+      assigner.assignSubdomain('acct-a', 'shared'),
+      assigner.assignSubdomain('acct-b', 'shared'),
+    ])
+    expect(new Set([a, b]).size).toBe(2) // never collapses two tenants onto one label
+    expect([a, b].filter((x) => x === 'shared').length).toBe(1) // exactly one got the exact name
+  })
+})

control-plane/test/revoke.test.ts

@@ -0,0 +1,65 @@
+import { describe, test, expect } from 'vitest'
+import { createMemoryStores } from '../src/store/memory.js'
+import { createHostRegistry } from '../src/registry/hosts.js'
+import { createRoutingTable } from '../src/routing/table.js'
+import { createInMemoryRevocationBus } from '../src/routing/bus.js'
+import { createRevoker, createInMemoryRevokedTokenStore } from '../src/revoke/revoke.js'
+import { fingerprint } from '../src/ca/fingerprint.js'
+import { generateEd25519 } from '../src/util/crypto.js'
+import type { KillSignal } from 'relay-contracts'
+import type { NodeIdentity } from '../src/node-auth/identity.js'
+
+const node: NodeIdentity = { nodeId: 'spiffe://relay/node-a' }
+const ACCOUNT = '11111111-1111-4111-8111-111111111111'
+
+async function harness() {
+  const stores = createMemoryStores()
+  const hosts = createHostRegistry({ hosts: stores.hosts })
+  const routing = createRoutingTable({ routes: stores.routes })
+  const bus = createInMemoryRevocationBus()
+  const tokens = createInMemoryRevokedTokenStore()
+  const revoker = createRevoker({ hosts, routing, bus, tokens })
+  const { publicKeyRaw } = generateEd25519()
+  const host = await hosts.bindHost({ accountId: ACCOUNT, subdomain: 'alice', agentPubkey: publicKeyRaw, enrollFpr: fingerprint(publicKeyRaw) })
+  await routing.upsertRoute(node, host.hostId, { relayNodeId: node.nodeId, updatedAt: new Date().toISOString() }, 60)
+  return { stores, hosts, routing, bus, tokens, revoker, host }
+}
+
+describe('T13 revocation (INV12/INV8/INV10)', () => {
+  test('revokeHost: route dropped + host revoked + KillSignal on relay:revocations, zero payload', async () => {
+    const h = await harness()
+    const received: KillSignal[] = []
+    h.bus.subscribe((s) => received.push(s))
+    await h.revoker.revokeHost(h.host.hostId)
+    expect(await h.routing.resolveRoute(h.host.hostId)).toBeNull()
+    expect((await h.hosts.getHost(h.host.hostId))?.status).toBe('revoked')
+    expect(received.length).toBe(1)
+    expect(received[0]?.scope).toEqual({ kind: 'host', hostId: h.host.hostId })
+    // zero-payload: reason is short metadata, contains no terminal bytes
+    expect(received[0]?.reason).toBe('revoked')
+  })
+
+  test('revokeHost is idempotent', async () => {
+    const h = await harness()
+    await h.revoker.revokeHost(h.host.hostId)
+    await expect(h.revoker.revokeHost(h.host.hostId)).resolves.toBeUndefined()
+  })
+
+  test('revokeAccount publishes ONE account-scoped signal + cascades to hosts', async () => {
+    const h = await harness()
+    const received: KillSignal[] = []
+    h.bus.subscribe((s) => received.push(s))
+    await h.revoker.revokeAccount(ACCOUNT)
+    expect((await h.hosts.getHost(h.host.hostId))?.status).toBe('revoked')
+    const accountSignals = received.filter((s) => s.scope.kind === 'account')
+    expect(accountSignals.length).toBe(1)
+  })
+
+  test('revokeToken → isTokenRevoked true, stops validating', async () => {
+    const h = await harness()
+    const jti = 'jti-123'
+    expect(await h.revoker.isTokenRevoked(jti)).toBe(false)
+    await h.revoker.revokeToken(jti, Math.floor(Date.now() / 1000) + 3600)
+    expect(await h.revoker.isTokenRevoked(jti)).toBe(true)
+  })
+})

control-plane/test/rotate.test.ts

@@ -0,0 +1,84 @@
+import { describe, test, expect } from 'vitest'
+import { createMemoryStores } from '../src/store/memory.js'
+import { createHostRegistry } from '../src/registry/hosts.js'
+import { createLeafRenewer } from '../src/ca/rotate.js'
+import { LeafSignError } from '../src/ca/sign.js'
+import { buildCaSigner, inProcessCaSigner, type KmsResolver } from '../src/boot/ca-wiring.js'
+import { buildCsr } from '../src/ca/csr.js'
+import { fingerprint } from '../src/ca/fingerprint.js'
+import { generateEd25519 } from '../src/util/crypto.js'
+import { loadEnv } from '../src/env.js'
+import { bytesToBase64 } from '../src/util/bytes.js'
+import { randomBytes } from 'node:crypto'
+
+const ACCOUNT = '11111111-1111-4111-8111-111111111111'
+
+async function boundHost() {
+  const stores = createMemoryStores()
+  const hosts = createHostRegistry({ hosts: stores.hosts })
+  const { publicKeyRaw, privateKey } = generateEd25519()
+  const host = await hosts.bindHost({ accountId: ACCOUNT, subdomain: 'alice', agentPubkey: publicKeyRaw, enrollFpr: fingerprint(publicKeyRaw) })
+  const renewer = createLeafRenewer({ hosts: stores.hosts, signer: inProcessCaSigner(), caChainDer: [] })
+  return { stores, hosts, host, publicKeyRaw, privateKey, renewer }
+}
+
+describe('T15 renewHostLeaf (INV14)', () => {
+  test('active host + valid CSR → fresh short-TTL leaf (same subject pubkey)', async () => {
+    const { host, publicKeyRaw, privateKey, renewer } = await boundHost()
+    const { cert } = await renewer.renewHostLeaf(host.hostId, buildCsr(privateKey, publicKeyRaw))
+    const certJson = JSON.parse(Buffer.from(cert).toString())
+    const tbs = JSON.parse(Buffer.from(certJson.tbs, 'base64').toString())
+    expect(tbs.subjectSpki).toBe(Buffer.from(publicKeyRaw).toString('base64'))
+    expect(tbs.renewed).toBe(true)
+  })
+
+  test('CSR proof-of-possession fails → reject even for an active host', async () => {
+    const { host, publicKeyRaw, renewer } = await boundHost()
+    const forged = new Uint8Array(96)
+    forged.set(publicKeyRaw, 0)
+    forged.set(randomBytes(64), 32) // garbage signature
+    await expect(renewer.renewHostLeaf(host.hostId, forged)).rejects.toBeInstanceOf(LeafSignError)
+  })
+
+  test('revoked host cannot renew (INV12+INV14 loop)', async () => {
+    const { hosts, host, publicKeyRaw, privateKey, renewer } = await boundHost()
+    await hosts.setHostStatus(host.hostId, 'revoked')
+    await expect(renewer.renewHostLeaf(host.hostId, buildCsr(privateKey, publicKeyRaw))).rejects.toBeInstanceOf(LeafSignError)
+  })
+})
+
+describe('T1/T15 buildCaSigner startup key-policy check (INV9, §3.1)', () => {
+  const env = () =>
+    loadEnv({
+      PG_URL: 'postgres://u:p@localhost:5432/cp',
+      REDIS_URL: 'redis://localhost:6379',
+      CAPABILITY_SIGN_PUBKEY_B64: bytesToBase64(new Uint8Array(32).fill(1)),
+      CA_INTERMEDIATE_KMS_KEY_REF: 'kms://key/intermediate',
+      CA_INTERMEDIATE_CERT_PATH: '/etc/cp/int.pem',
+      NODE_MTLS_TRUST_BUNDLE_PATH: '/etc/cp/node-ca.pem',
+      BASE_DOMAIN: 'term.example.com',
+    })
+
+  test('fails fast when the KMS key ref cannot be resolved', async () => {
+    const resolver: KmsResolver = { async resolve() { throw new Error('no such key') } }
+    await expect(buildCaSigner(env(), resolver)).rejects.toThrow(/could not be resolved/)
+  })
+
+  test('fails fast when the key policy is broader than the service principal', async () => {
+    const resolver: KmsResolver = {
+      async resolve() {
+        return { signer: inProcessCaSigner(), policyRestrictedToServicePrincipal: false }
+      },
+    }
+    await expect(buildCaSigner(env(), resolver)).rejects.toThrow(/policy is broader/)
+  })
+
+  test('succeeds when policy is restricted', async () => {
+    const resolver: KmsResolver = {
+      async resolve() {
+        return { signer: inProcessCaSigner(), policyRestrictedToServicePrincipal: true }
+      },
+    }
+    await expect(buildCaSigner(env(), resolver)).resolves.toBeDefined()
+  })
+})

control-plane/test/routing.test.ts

@@ -0,0 +1,90 @@
+import { describe, test, expect } from 'vitest'
+import { createMemoryStores } from '../src/store/memory.js'
+import { createRoutingTable, RouteAuthError } from '../src/routing/table.js'
+import { createNodeCoordinator } from '../src/routing/nodes.js'
+import { createInMemoryRevocationBus } from '../src/routing/bus.js'
+import { deriveNodeIdentity, NodeAuthError, type NodeIdentity } from '../src/node-auth/identity.js'
+import type { KillSignal } from 'relay-contracts'
+
+const nodeA: NodeIdentity = { nodeId: 'spiffe://relay/node-a' }
+const nodeB: NodeIdentity = { nodeId: 'spiffe://relay/node-b' }
+const HOST = '33333333-3333-4333-8333-333333333333'
+
+describe('T9 node identity (INV3-analog)', () => {
+  test('authorized cert with CN → id; unauthenticated → 401; no CN → 401', () => {
+    expect(deriveNodeIdentity({ authorized: true, subjectCommonName: 'node-x' }).nodeId).toBe('node-x')
+    expect(() => deriveNodeIdentity({ authorized: false, subjectCommonName: 'node-x' })).toThrow(NodeAuthError)
+    expect(() => deriveNodeIdentity({ authorized: true, subjectCommonName: null })).toThrow(NodeAuthError)
+    expect(() => deriveNodeIdentity(null)).toThrow(NodeAuthError)
+  })
+})
+
+describe('T9 routing table (INV7)', () => {
+  test('upsert then resolve; foreign relayNodeId rejected', async () => {
+    const { routes } = createMemoryStores()
+    const table = createRoutingTable({ routes })
+    await table.upsertRoute(nodeA, HOST, { relayNodeId: nodeA.nodeId, updatedAt: new Date().toISOString() }, 60)
+    expect((await table.resolveRoute(HOST))?.relayNodeId).toBe(nodeA.nodeId)
+    await expect(
+      table.upsertRoute(nodeA, HOST, { relayNodeId: nodeB.nodeId, updatedAt: new Date().toISOString() }, 60),
+    ).rejects.toBeInstanceOf(RouteAuthError)
+  })
+
+  test('heartbeat-TTL expiry ⇒ resolveRoute null (fails closed)', async () => {
+    const { routes } = createMemoryStores()
+    const table = createRoutingTable({ routes })
+    await table.upsertRoute(nodeA, HOST, { relayNodeId: nodeA.nodeId, updatedAt: new Date().toISOString() }, 0)
+    expect(await table.resolveRoute(HOST)).toBeNull()
+  })
+
+  test('foreign node cannot heartbeat/hijack; only holder drops', async () => {
+    const { routes } = createMemoryStores()
+    const table = createRoutingTable({ routes })
+    await table.upsertRoute(nodeA, HOST, { relayNodeId: nodeA.nodeId, updatedAt: new Date().toISOString() }, 60)
+    await table.heartbeatRoute(nodeB, HOST, 60) // foreign → no-op
+    expect((await table.resolveRoute(HOST))?.relayNodeId).toBe(nodeA.nodeId)
+    await expect(table.dropRoute(nodeB, HOST)).rejects.toBeInstanceOf(RouteAuthError)
+    await table.dropRoute(nodeA, HOST)
+    expect(await table.resolveRoute(HOST)).toBeNull()
+  })
+})
+
+describe('T10 node registry + graceful drain (INV7)', () => {
+  test('beginDrain flips status, returns routed host_ids, publishes per-host KillSignal', async () => {
+    const stores = createMemoryStores()
+    const bus = createInMemoryRevocationBus()
+    const table = createRoutingTable({
+      routes: stores.routes,
+      nodeStatus: async (id) => (await stores.nodes.get(id))?.status ?? null,
+    })
+    const coord = createNodeCoordinator({ nodes: stores.nodes, routes: stores.routes, bus })
+    const received: KillSignal[] = []
+    bus.subscribe((s) => received.push(s))
+
+    await coord.registerNode(nodeA, '10.0.0.1:9000')
+    await table.upsertRoute(nodeA, HOST, { relayNodeId: nodeA.nodeId, updatedAt: new Date().toISOString() }, 60)
+
+    const { hostIds } = await coord.beginDrain(nodeA)
+    expect(hostIds).toEqual([HOST])
+    expect((await stores.nodes.get(nodeA.nodeId))?.status).toBe('draining')
+    expect(received.map((s) => s.scope)).toEqual([{ kind: 'host', hostId: HOST }])
+
+    // a draining node stops receiving new upserts
+    await expect(
+      table.upsertRoute(nodeA, '44444444-4444-4444-8444-444444444444', { relayNodeId: nodeA.nodeId, updatedAt: new Date().toISOString() }, 60),
+    ).rejects.toBeInstanceOf(RouteAuthError)
+
+    await coord.completeDrain(nodeA)
+    expect(await stores.nodes.get(nodeA.nodeId)).toBeNull()
+  })
+
+  test('PTY-survival: draining touches no host/session row', async () => {
+    const stores = createMemoryStores()
+    const bus = createInMemoryRevocationBus()
+    const coord = createNodeCoordinator({ nodes: stores.nodes, routes: stores.routes, bus })
+    await coord.registerNode(nodeA, 'addr')
+    await coord.beginDrain(nodeA)
+    // no host rows were ever created by drain
+    expect(await stores.hosts.get(HOST)).toBeNull()
+  })
+})

control-plane/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "strict": true,
+    "noImplicitAny": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts", "bin/**/*.ts", "test/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

control-plane/vitest.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    include: ['test/**/*.test.ts'],
+    environment: 'node',
+    coverage: {
+      provider: 'v8',
+      // Tested surface = business logic + in-memory adapters. The pg/ioredis/fastify
+      // production wiring (db/pool.ts, store/pg.ts, api/main.ts) is an integration seam
+      // exercised by Testcontainers in CI (docs/PLAN_RELAY_CONTROLPLANE.md §10), not unit tests.
+      include: ['src/**/*.ts'],
+      exclude: ['**/*.d.ts', 'src/main.ts'],
+    },
+  },
+})