From 95b9cccf07208306d045fbc1096483e9ad4620aa Mon Sep 17 00:00:00 2001 From: Yaojia Wang Date: Mon, 6 Jul 2026 14:51:37 +0200 Subject: [PATCH] =?UTF-8?q?feat(relay):=20Phase1=20foundation=20=E2=80=94?= =?UTF-8?q?=20P3=20Postgres=20store=20+=20async=20capability=20verifier=20?= =?UTF-8?q?+=20compose?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit RELAY-PHASE1 Wave A (2/3) + E1 infra: - A1: createPgStores() Postgres adapter for all 9 P3 store ports + runMigrations(); writable-CTE atomic INV8 status swaps; 0002_routes.sql. 23/23 pg tests, 96.72% cov. - A3: real capability verifier delegating to relay-auth verifyCapabilityToken; sync->async seam across authz/provision/main. Full CP suite 15 files/101 pass, tsc clean. - E1: deploy/docker-compose.yml (Postgres16+Redis7, loopback-only) + .env.example. - docs: PLAN_RELAY_PHASE1.md file-level execution spec; PROGRESS_LOG RELAY-PHASE1 section. --- .gitignore | 3 + control-plane/db/migrations/0002_routes.sql | 15 + control-plane/package.json | 1 + control-plane/src/api/authz.ts | 13 +- control-plane/src/api/provision.ts | 12 +- control-plane/src/boot/verifier.ts | 38 ++ control-plane/src/db/migrate.ts | 48 ++ control-plane/src/main.ts | 19 +- control-plane/src/store/pg.ts | 600 ++++++++++++++++++++ control-plane/test/api-extra.test.ts | 2 +- control-plane/test/api.test.ts | 3 +- control-plane/test/store/pg.test.ts | 390 +++++++++++++ control-plane/test/verifier.test.ts | 78 +++ deploy/.env.example | 43 ++ deploy/docker-compose.yml | 48 ++ docs/PLAN_RELAY_PHASE1.md | 172 ++++++ docs/PROGRESS_LOG.md | 19 + 17 files changed, 1488 insertions(+), 16 deletions(-) create mode 100644 control-plane/db/migrations/0002_routes.sql create mode 100644 control-plane/src/boot/verifier.ts create mode 100644 control-plane/src/db/migrate.ts create mode 100644 control-plane/src/store/pg.ts create mode 100644 control-plane/test/store/pg.test.ts create mode 100644 control-plane/test/verifier.test.ts create mode 100644 deploy/.env.example create mode 100644 deploy/docker-compose.yml create mode 100644 docs/PLAN_RELAY_PHASE1.md diff --git a/.gitignore b/.gitignore index bec3a54..d0d37f2 100644 --- a/.gitignore +++ b/.gitignore @@ -18,3 +18,6 @@ npm-debug.log* # test coverage coverage/ .gstack/ + +# deploy secrets (RELAY-PHASE1) — .env.example is committed, .env is not +deploy/.env diff --git a/control-plane/db/migrations/0002_routes.sql b/control-plane/db/migrations/0002_routes.sql new file mode 100644 index 0000000..606886c --- /dev/null +++ b/control-plane/db/migrations/0002_routes.sql @@ -0,0 +1,15 @@ +-- A1 — routes table (P3-owned). Not present in 0001_init.sql: the RouteStore port is a +-- Redis-like live routing table (INV7 — NOT source of truth). This Postgres adapter needs a +-- durable backing for it. Postgres has no per-key TTL, so we store an explicit `expires_at` +-- and treat `expires_at <= now()` as ABSENT (fail-closed, INV7); expired rows are lazily +-- DELETEd on access. This mirrors `store/memory.ts` memRouteStore() semantics exactly. +-- +-- No FK to hosts(host_id): routes are an ephemeral location cache keyed by host_id, decoupled +-- from the ownership source of truth (matches memory.ts, where routes live independently). +CREATE TABLE IF NOT EXISTS routes ( + host_id uuid PRIMARY KEY, + relay_node_id text NOT NULL, + updated_at timestamptz NOT NULL, + expires_at timestamptz NOT NULL +); +CREATE INDEX IF NOT EXISTS routes_node_idx ON routes(relay_node_id); diff --git a/control-plane/package.json b/control-plane/package.json index a5b5158..0375ec7 100644 --- a/control-plane/package.json +++ b/control-plane/package.json @@ -16,6 +16,7 @@ }, "dependencies": { "relay-contracts": "file:../relay-contracts", + "relay-auth": "file:../relay-auth", "fastify": "^4.28.1", "ioredis": "^5.4.1", "pg": "^8.12.0", diff --git a/control-plane/src/api/authz.ts b/control-plane/src/api/authz.ts index d94eb69..80fa9c3 100644 --- a/control-plane/src/api/authz.ts +++ b/control-plane/src/api/authz.ts @@ -20,9 +20,12 @@ export class AuthzError extends Error { } } -/** P5's verifier, injected. Mirrors the frozen `verifyCapabilityToken` signature (§4.3). */ +/** + * P5's verifier, injected. Mirrors the frozen `verifyCapabilityToken` signature (§4.3), which is + * ASYNC (Ed25519 verify over WebCrypto) — so this seam returns a Promise and all call sites await. + */ export interface CapabilityVerifier { - verify(raw: string, expectedAud: string, now: number): CapabilityToken + verify(raw: string, expectedAud: string, now: number): Promise } /** Minimal request shape we read for the bearer token (never a body account field). */ @@ -49,19 +52,19 @@ function extractRawToken(req: AuthRequest): string | null { } export interface Authorizer { - principalFromRequest(req: AuthRequest): AdminPrincipal + principalFromRequest(req: AuthRequest): Promise requireRight(principal: AdminPrincipal, right: CapabilityRight): void } export function createAuthorizer(deps: AuthzDeps): Authorizer { const now = deps.now ?? (() => Math.floor(Date.now() / 1000)) return { - principalFromRequest(req) { + async 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()) + token = await deps.verifier.verify(raw, deps.expectedAud, now()) } catch (err: unknown) { throw new AuthzError(401, `invalid capability token: ${err instanceof Error ? err.message : 'rejected'}`) } diff --git a/control-plane/src/api/provision.ts b/control-plane/src/api/provision.ts index 39f116a..fdfdbbf 100644 --- a/control-plane/src/api/provision.ts +++ b/control-plane/src/api/provision.ts @@ -56,12 +56,12 @@ function assertOwnAccount(principal: AdminPrincipal, pathAccountId: string): voi export function buildRouter(deps: ProvisionDeps): FastifyPluginAsync { return async (app) => { - const principal = (req: FastifyRequest): AdminPrincipal => + const principal = (req: FastifyRequest): Promise => deps.authorizer.principalFromRequest({ headers: req.headers }) app.post('/accounts', async (req, reply) => { try { - const p = principal(req) + const p = await 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) @@ -73,7 +73,7 @@ export function buildRouter(deps: ProvisionDeps): FastifyPluginAsync { app.post('/accounts/:id/pairing-codes', async (req, reply) => { try { - const p = principal(req) + const p = await principal(req) deps.authorizer.requireRight(p, 'manage') assertOwnAccount(p, (req.params as { id: string }).id) const issued = await deps.pairingIssuer.issuePairingCode(p.accountId) @@ -85,7 +85,7 @@ export function buildRouter(deps: ProvisionDeps): FastifyPluginAsync { app.post('/accounts/:id/status', async (req, reply) => { try { - const p = principal(req) + const p = await principal(req) deps.authorizer.requireRight(p, 'manage') assertOwnAccount(p, (req.params as { id: string }).id) const { status } = StatusSchema.parse(req.body) @@ -98,7 +98,7 @@ export function buildRouter(deps: ProvisionDeps): FastifyPluginAsync { app.get('/accounts/:id/hosts', async (req, reply) => { try { - const p = principal(req) + const p = await 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') }))) @@ -109,7 +109,7 @@ export function buildRouter(deps: ProvisionDeps): FastifyPluginAsync { app.delete('/hosts/:hostId', async (req, reply) => { try { - const p = principal(req) + const p = await 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) diff --git a/control-plane/src/boot/verifier.ts b/control-plane/src/boot/verifier.ts new file mode 100644 index 0000000..8872100 --- /dev/null +++ b/control-plane/src/boot/verifier.ts @@ -0,0 +1,38 @@ +/** + * A3 — REAL capability verifier, backed by relay-auth's `verifyCapabilityToken` (P5). Replaces the + * fail-closed `refuseAllVerifier` stub. The frozen §4.3 verify signature is ASYNC (Ed25519 verify + * over WebCrypto) and reads its verifying key from relay-auth's startup registry (config/keys.ts), + * never as a parameter — so we (a) adapt it to the async `CapabilityVerifier` seam and (b) load the + * key at boot from the CP env's already-validated pubkey. + * + * KEY BRIDGE (INV9): the CP env var is `CAPABILITY_SIGN_PUBKEY_B64` (base64), parsed+validated in + * `env.ts` to `env.capabilitySignPubkey` (32 raw Ed25519 bytes). relay-auth's own env loader expects + * a DIFFERENT var name (`RELAY_AUTH_VERIFY_PUBKEY`, base64url), so we do NOT use it — we import the + * 32 raw bytes to a non-exportable verify-only CryptoKey via WebCrypto and call relay-auth's + * `configureVerifyKey(CryptoKey)` directly. + */ +import { verifyCapabilityToken, configureVerifyKey } from 'relay-auth' +import type { CapabilityToken } from 'relay-contracts' +import type { CapabilityVerifier } from '../api/authz.js' + +/** The real verifier: delegates verbatim to P5's frozen §4.3 `verifyCapabilityToken`. */ +export function createCapabilityVerifier(): CapabilityVerifier { + return { + verify(raw: string, expectedAud: string, now: number): Promise { + return verifyCapabilityToken(raw, expectedAud, now) + }, + } +} + +/** + * Load the §4.3 verifying key into relay-auth's startup registry from the CP env's raw 32-byte + * Ed25519 public key (`env.capabilitySignPubkey`). Non-exportable, `verify`-only. Must run before + * the real verifier serves any request, else `verifyCapabilityToken` throws `KeyConfigError`. + */ +export async function configureCapabilityVerifyKey(pubkeyRaw: Uint8Array): Promise { + // Copy into a fresh ArrayBuffer-backed view (WebCrypto's BufferSource typing / no shared pool). + const bytes = new Uint8Array(pubkeyRaw.length) + bytes.set(pubkeyRaw) + const key = await globalThis.crypto.subtle.importKey('raw', bytes, { name: 'Ed25519' }, false, ['verify']) + configureVerifyKey(key) +} diff --git a/control-plane/src/db/migrate.ts b/control-plane/src/db/migrate.ts new file mode 100644 index 0000000..95d3db9 --- /dev/null +++ b/control-plane/src/db/migrate.ts @@ -0,0 +1,48 @@ +/** + * A1 — migration runner. Reads every `db/migrations/*.sql` in filename order and executes it + * over the parameterized `query` wrapper (db/pool.ts). All migrations are `IF NOT EXISTS`, so + * `runMigrations` is idempotent and safe to run at every boot / test setup. + * + * `createQuery` ALWAYS routes through the extended (parameterized) protocol — even with `[]` + * params — which rejects multi-statement command strings. So each file is split into its + * top-level statements (on `;`, after stripping `-- line comments`) and each statement is run + * as its own single-command `query(stmt, [])`. Our migrations are plain IF-NOT-EXISTS DDL with + * no `;` inside string literals and no dollar-quoted bodies, so this split is safe. + */ +import { readdir, readFile } from 'node:fs/promises' +import { dirname, join } from 'node:path' +import { fileURLToPath } from 'node:url' +import type { QueryFn } from './pool.js' + +/** Absolute path to `control-plane/db/migrations`, resolved relative to this source file. */ +function migrationsDir(): string { + const here = dirname(fileURLToPath(import.meta.url)) // .../control-plane/src/db + return join(here, '..', '..', 'db', 'migrations') // .../control-plane/db/migrations +} + +/** Strip `-- line comments`, then split into non-empty top-level statements on `;`. */ +export function splitStatements(sql: string): readonly string[] { + const withoutComments = sql + .split('\n') + .map((line) => { + const idx = line.indexOf('--') + return idx >= 0 ? line.slice(0, idx) : line + }) + .join('\n') + return withoutComments + .split(';') + .map((stmt) => stmt.trim()) + .filter((stmt) => stmt.length > 0) +} + +/** Apply all `*.sql` migrations in filename order. Idempotent (every migration is IF NOT EXISTS). */ +export async function runMigrations(query: QueryFn): Promise { + const dir = migrationsDir() + const files = (await readdir(dir)).filter((f) => f.endsWith('.sql')).sort() + for (const file of files) { + const sql = await readFile(join(dir, file), 'utf8') + for (const stmt of splitStatements(sql)) { + await query(stmt, []) + } + } +} diff --git a/control-plane/src/main.ts b/control-plane/src/main.ts index d06b071..8c40c48 100644 --- a/control-plane/src/main.ts +++ b/control-plane/src/main.ts @@ -30,6 +30,7 @@ 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 { configureCapabilityVerifyKey } from './boot/verifier.js' import type { RevocationBus } from 'relay-contracts' export interface ControlPlaneOverrides { @@ -40,9 +41,13 @@ export interface ControlPlaneOverrides { readonly caChainDer?: readonly Uint8Array[] } -/** Default fail-closed verifier — refuses everything until P5 is wired (INV6). */ +/** + * Default fail-closed verifier — refuses everything until a real (P5) verifier is injected (INV6). + * Async-shaped to match `CapabilityVerifier`: an async body that throws rejects the promise, so the + * authorizer's `await` surfaces it as a 401. + */ const refuseAllVerifier: CapabilityVerifier = { - verify() { + async verify(): Promise { throw new Error('capability verification not configured (P5 integration point)') }, } @@ -92,8 +97,16 @@ export async function buildControlPlane( const deprovisioner = createDeprovisioner({ hosts, routing }) void bus // reserved for the node-coordinator / revoker wiring (drain + revoke publishers) + // A real (injected) verifier is P5's async `verifyCapabilityToken`, which reads its Ed25519 key + // from relay-auth's startup registry — so load that key from env at boot. The fail-closed default + // never reads a key, so leave relay-auth's registry untouched when nothing is injected (INV6). + const verifier = overrides.verifier ?? refuseAllVerifier + if (overrides.verifier !== undefined) { + await configureCapabilityVerifyKey(env.capabilitySignPubkey) + } + const authorizer = createAuthorizer({ - verifier: overrides.verifier ?? refuseAllVerifier, + verifier, expectedAud: env.baseDomain, }) diff --git a/control-plane/src/store/pg.ts b/control-plane/src/store/pg.ts new file mode 100644 index 0000000..c7a6956 --- /dev/null +++ b/control-plane/src/store/pg.ts @@ -0,0 +1,600 @@ +/** + * A1 — Postgres adapter for the repository ports (store/ports.ts). Each store maps its port + * methods to PARAMETERIZED SQL over the injected `query` wrapper (db/pool.ts) — values ALWAYS + * travel as bound params, never string-interpolated (SQLi structurally impossible, §7). + * + * This adapter MUST reproduce store/memory.ts observable semantics EXACTLY: + * - INV8 versioning: `swapStatus` appends a `*_status_versions` row AND bumps the single-row + * `status`/`status_version` pointer ATOMICALLY. Postgres has real transactions, but we get + * the same all-or-nothing with a single writable-CTE statement (no explicit tx / PoolClient). + * - `insert` duplicates throw (PK / UNIQUE violation, pg code 23505 → `throw new Error`). + * - `casRedeem` is a single-winner CAS of `redeemed_at` from null. + * - `RouteStore` fails closed on TTL: `expires_at <= now()` ⇒ absent (INV7), lazily DELETEd. + * - metering/audit are append-only with inclusive `[from,to]` time-window queries. + * + * Timestamps: DB columns are `timestamptz` (node-pg returns them as JS `Date`); records use ISO + * strings. `toIso` normalizes Date|string → ISO so returned records match memory.ts string shapes. + */ +import type { + AccountRecord, + AccountStatus, + AccountStatusVersionRow, + HostRecord, + HostStatus, + HostStatusVersionRow, + MeteringSampleRow, + PairingCodeRecord, + PlanTier, + RouteEntry, + SessionRecord, +} from '../model/records.js' +import type { QueryFn } from '../db/pool.js' +import type { + AccountStore, + AuditRow, + AuditStore, + CasOutcome, + HostStore, + MeteringStore, + NodeRow, + NodeStatus, + NodeStore, + PairingRow, + PairingStore, + RouteStore, + SessionStore, + Stores, + SubdomainStore, +} from './ports.js' + +// ---- helpers ---------------------------------------------------------------------------------- + +const toIso = (v: Date | string): string => (v instanceof Date ? v : new Date(v)).toISOString() +const toIsoN = (v: Date | string | null): string | null => (v === null ? null : toIso(v)) + +/** pg unique/PK violation. */ +function isUniqueViolation(err: unknown): err is { code: string; constraint?: string } { + return typeof err === 'object' && err !== null && (err as { code?: unknown }).code === '23505' +} + +// ---- raw DB row shapes ------------------------------------------------------------------------ + +interface AccountRow { + account_id: string + plan: PlanTier + created_at: Date | string + status: AccountStatus +} +interface HostRow { + host_id: string + account_id: string + subdomain: string + agent_pubkey: Buffer + enroll_fpr: string + status: HostStatus + last_seen: Date | string + created_at: Date | string + revoked_at: Date | string | null +} +interface SessionRow { + session_id: string + host_id: string + account_id: string + created_at: Date | string + last_attach_at: Date | string +} +interface AccountVersionRow { + account_id: string + version: number + status: AccountStatus + changed_at: Date | string + changed_by: string +} +interface HostVersionRow { + host_id: string + version: number + status: HostStatus + revoked_at: Date | string | null + changed_at: Date | string + changed_by: string +} + +function mapAccount(r: AccountRow): AccountRecord { + return { accountId: r.account_id, plan: r.plan, createdAt: toIso(r.created_at), status: r.status } +} +function mapHost(r: HostRow): HostRecord { + return { + hostId: r.host_id, + accountId: r.account_id, + subdomain: r.subdomain, + agentPubkey: new Uint8Array(r.agent_pubkey), + enrollFpr: r.enroll_fpr, + status: r.status, + lastSeen: toIso(r.last_seen), + createdAt: toIso(r.created_at), + revokedAt: toIsoN(r.revoked_at), + } +} + +// ---- AccountStore ----------------------------------------------------------------------------- + +function pgAccountStore(query: QueryFn): AccountStore { + return { + async insert(rec) { + // Writable CTE: create the row AND its INV8 version-1 companion in ONE statement. + // version-1 changed_at = created_at, changed_by = 'system' (matches memory.ts). + try { + await query( + `WITH ins AS ( + INSERT INTO accounts (account_id, plan, created_at, status, status_version) + VALUES ($1, $2, $3, $4, 1) + RETURNING account_id, created_at, status + ) + INSERT INTO account_status_versions (account_id, version, status, changed_at, changed_by) + SELECT account_id, 1, status, created_at, 'system' FROM ins`, + [rec.accountId, rec.plan, rec.createdAt, rec.status], + ) + } catch (err) { + if (isUniqueViolation(err)) throw new Error('duplicate accountId') + throw err + } + }, + async get(accountId) { + const rows = await query( + `SELECT account_id, plan, created_at, status FROM accounts WHERE account_id = $1`, + [accountId], + ) + const row = rows[0] + return row === undefined ? null : mapAccount(row) + }, + async swapStatus(accountId, status, changedBy) { + // Atomic INV8: bump pointer + append version row in one writable-CTE statement. + const rows = await query( + `WITH upd AS ( + UPDATE accounts SET status = $2, status_version = status_version + 1 + WHERE account_id = $1 + RETURNING account_id, plan, created_at, status, status_version + ), + ins AS ( + INSERT INTO account_status_versions (account_id, version, status, changed_by) + SELECT account_id, status_version, status, $3 FROM upd + ) + SELECT account_id, plan, created_at, status FROM upd`, + [accountId, status, changedBy], + ) + const row = rows[0] + if (row === undefined) throw new Error('account not found') + return mapAccount(row) + }, + async versions(accountId) { + const rows = await query( + `SELECT account_id, version, status, changed_at, changed_by + FROM account_status_versions WHERE account_id = $1 ORDER BY version ASC`, + [accountId], + ) + return rows.map( + (r): AccountStatusVersionRow => ({ + accountId: r.account_id, + version: r.version, + status: r.status, + changedAt: toIso(r.changed_at), + changedBy: r.changed_by, + }), + ) + }, + } +} + +// ---- HostStore -------------------------------------------------------------------------------- + +function pgHostStore(query: QueryFn): HostStore { + return { + async insert(rec) { + try { + await query( + `WITH ins AS ( + INSERT INTO hosts + (host_id, account_id, subdomain, agent_pubkey, enroll_fpr, status, last_seen, created_at, revoked_at, status_version) + VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, 1) + RETURNING host_id, created_at, status, revoked_at + ) + INSERT INTO host_status_versions (host_id, version, status, revoked_at, changed_at, changed_by) + SELECT host_id, 1, status, revoked_at, created_at, 'system' FROM ins`, + [ + rec.hostId, + rec.accountId, + rec.subdomain, + Buffer.from(rec.agentPubkey), + rec.enrollFpr, + rec.status, + rec.lastSeen, + rec.createdAt, + rec.revokedAt, + ], + ) + } catch (err) { + if (isUniqueViolation(err)) { + // subdomain UNIQUE is the subdomain single-winner substrate; PK is host_id. + throw new Error(err.constraint?.includes('subdomain') ? 'duplicate subdomain' : 'duplicate hostId') + } + throw err + } + }, + async get(hostId) { + const rows = await query(`SELECT * FROM hosts WHERE host_id = $1`, [hostId]) + const row = rows[0] + return row === undefined ? null : mapHost(row) + }, + async getBySubdomain(subdomain) { + const rows = await query(`SELECT * FROM hosts WHERE subdomain = $1`, [subdomain]) + const row = rows[0] + return row === undefined ? null : mapHost(row) + }, + async listByAccount(accountId) { + const rows = await query(`SELECT * FROM hosts WHERE account_id = $1 ORDER BY created_at ASC`, [ + accountId, + ]) + return rows.map(mapHost) + }, + async swapStatus(hostId, status, revokedAt, changedBy) { + const rows = await query( + `WITH upd AS ( + UPDATE hosts SET status = $2, revoked_at = $3, status_version = status_version + 1 + WHERE host_id = $1 + RETURNING host_id, account_id, subdomain, agent_pubkey, enroll_fpr, status, last_seen, created_at, revoked_at, status_version + ), + ins AS ( + INSERT INTO host_status_versions (host_id, version, status, revoked_at, changed_by) + SELECT host_id, status_version, status, revoked_at, $4 FROM upd + ) + SELECT host_id, account_id, subdomain, agent_pubkey, enroll_fpr, status, last_seen, created_at, revoked_at FROM upd`, + [hostId, status, revokedAt, changedBy], + ) + const row = rows[0] + if (row === undefined) throw new Error('host not found') + return mapHost(row) + }, + async touchLastSeen(hostId, ts) { + // Advisory cache — NO version row (INV7). Silent no-op if absent (matches memory.ts). + await query(`UPDATE hosts SET last_seen = $2 WHERE host_id = $1`, [hostId, ts]) + }, + async versions(hostId) { + const rows = await query( + `SELECT host_id, version, status, revoked_at, changed_at, changed_by + FROM host_status_versions WHERE host_id = $1 ORDER BY version ASC`, + [hostId], + ) + return rows.map( + (r): HostStatusVersionRow => ({ + hostId: r.host_id, + version: r.version, + status: r.status, + revokedAt: toIsoN(r.revoked_at), + changedAt: toIso(r.changed_at), + changedBy: r.changed_by, + }), + ) + }, + } +} + +// ---- SessionStore ----------------------------------------------------------------------------- + +function pgSessionStore(query: QueryFn): SessionStore { + return { + async insert(rec) { + try { + await query( + `INSERT INTO sessions (session_id, host_id, account_id, created_at, last_attach_at) + VALUES ($1, $2, $3, $4, $5)`, + [rec.sessionId, rec.hostId, rec.accountId, rec.createdAt, rec.lastAttachAt], + ) + } catch (err) { + if (isUniqueViolation(err)) throw new Error('duplicate sessionId') + throw err + } + }, + async get(sessionId) { + const rows = await query(`SELECT * FROM sessions WHERE session_id = $1`, [sessionId]) + const row = rows[0] + if (row === undefined) return null + return { + sessionId: row.session_id, + hostId: row.host_id, + accountId: row.account_id, + createdAt: toIso(row.created_at), + lastAttachAt: toIso(row.last_attach_at), + } + }, + } +} + +// ---- SubdomainStore --------------------------------------------------------------------------- + +/** + * No separate reservations table exists in the schema — the `hosts.subdomain UNIQUE` constraint + * is the single-winner substrate (the true winner is decided at host insert). So `reserve`/`isTaken` + * just report whether a host already owns the label (matches memory.ts intent). Two concurrent + * `reserve()`s can both see "free" before any host row exists; that is fine, because the actual + * single-winner is enforced when the losing insert hits the UNIQUE violation (INV1). + */ +function pgSubdomainStore(query: QueryFn): SubdomainStore { + const taken = async (subdomain: string): Promise => { + const rows = await query<{ one: number }>(`SELECT 1 AS one FROM hosts WHERE subdomain = $1 LIMIT 1`, [ + subdomain, + ]) + return rows.length > 0 + } + return { + async reserve(subdomain) { + return !(await taken(subdomain)) + }, + async isTaken(subdomain) { + return taken(subdomain) + }, + } +} + +// ---- PairingStore ----------------------------------------------------------------------------- + +interface PairingCodeRow { + code_hash: string + account_id: string + expires_at: Date | string + redeemed_at: Date | string | null + redeem_attempts: number +} + +function pgPairingStore(query: QueryFn): PairingStore { + return { + async insert(rec) { + try { + await query( + `INSERT INTO pairing_codes (code_hash, account_id, expires_at, redeemed_at, redeem_attempts) + VALUES ($1, $2, $3, $4, 0)`, + [rec.codeHash, rec.accountId, rec.expiresAt, rec.redeemedAt], + ) + } catch (err) { + if (isUniqueViolation(err)) throw new Error('duplicate code_hash') + throw err + } + }, + async get(codeHash): Promise { + const rows = await query(`SELECT * FROM pairing_codes WHERE code_hash = $1`, [codeHash]) + const row = rows[0] + if (row === undefined) return null + const record: PairingCodeRecord = { + codeHash: row.code_hash, + accountId: row.account_id, + expiresAt: toIso(row.expires_at), + redeemedAt: toIsoN(row.redeemed_at), + } + return { record, redeemAttempts: row.redeem_attempts } + }, + async casRedeem(codeHash, nowIso): Promise { + // Single-winner CAS: only the row with redeemed_at IS NULL is updated; exactly one wins. + const won = await query<{ code_hash: string }>( + `UPDATE pairing_codes SET redeemed_at = $2 + WHERE code_hash = $1 AND redeemed_at IS NULL + RETURNING code_hash`, + [codeHash, nowIso], + ) + if (won.length === 1) return 'ok' + // 0 rows: either already redeemed or unknown — distinguish by existence. + const exists = await query<{ one: number }>(`SELECT 1 AS one FROM pairing_codes WHERE code_hash = $1`, [ + codeHash, + ]) + return exists.length > 0 ? 'already_redeemed' : 'unknown' + }, + async registerFailure(codeHash) { + const rows = await query<{ redeem_attempts: number }>( + `UPDATE pairing_codes SET redeem_attempts = redeem_attempts + 1 + WHERE code_hash = $1 + RETURNING redeem_attempts`, + [codeHash], + ) + const row = rows[0] + return row === undefined ? 0 : row.redeem_attempts // 0 for unknown code (matches memory.ts) + }, + } +} + +// ---- RouteStore ------------------------------------------------------------------------------- + +interface RouteRow { + host_id: string + relay_node_id: string + updated_at: Date | string +} + +function pgRouteStore(query: QueryFn): RouteStore { + const mapEntry = (r: RouteRow): RouteEntry => ({ relayNodeId: r.relay_node_id, updatedAt: toIso(r.updated_at) }) + return { + async set(hostId, entry, ttlSec) { + // Postgres has no per-key TTL: store an explicit expires_at = now() + ttl (server clock). + await query( + `INSERT INTO routes (host_id, relay_node_id, updated_at, expires_at) + VALUES ($1, $2, $3, now() + make_interval(secs => $4)) + ON CONFLICT (host_id) DO UPDATE SET + relay_node_id = EXCLUDED.relay_node_id, + updated_at = EXCLUDED.updated_at, + expires_at = EXCLUDED.expires_at`, + [hostId, entry.relayNodeId, entry.updatedAt, ttlSec], + ) + }, + async refreshTtl(hostId, ttlSec) { + // Refresh only a still-live key (fail closed on already-expired/absent, INV7). + const rows = await query<{ host_id: string }>( + `UPDATE routes SET expires_at = now() + make_interval(secs => $2) + WHERE host_id = $1 AND expires_at > now() + RETURNING host_id`, + [hostId, ttlSec], + ) + return rows.length === 1 + }, + async get(hostId) { + // Lazily reap the expired row, then a surviving row is guaranteed live (INV7 fail-closed). + await query(`DELETE FROM routes WHERE host_id = $1 AND expires_at <= now()`, [hostId]) + const rows = await query( + `SELECT host_id, relay_node_id, updated_at FROM routes WHERE host_id = $1`, + [hostId], + ) + const row = rows[0] + return row === undefined ? null : mapEntry(row) + }, + async delete(hostId) { + await query(`DELETE FROM routes WHERE host_id = $1`, [hostId]) + }, + async listByNode(nodeId) { + await query(`DELETE FROM routes WHERE expires_at <= now()`, []) + const rows = await query( + `SELECT host_id, relay_node_id, updated_at FROM routes + WHERE relay_node_id = $1 AND expires_at > now() ORDER BY host_id ASC`, + [nodeId], + ) + return rows.map((r) => ({ hostId: r.host_id, entry: mapEntry(r) })) + }, + } +} + +// ---- NodeStore -------------------------------------------------------------------------------- + +interface NodeDbRow { + node_id: string + addr: string + status: NodeStatus + last_seen: Date | string +} + +function pgNodeStore(query: QueryFn): NodeStore { + return { + async upsert(row) { + await query( + `INSERT INTO relay_nodes (node_id, addr, status, last_seen) + VALUES ($1, $2, $3, $4) + ON CONFLICT (node_id) DO UPDATE SET + addr = EXCLUDED.addr, status = EXCLUDED.status, last_seen = EXCLUDED.last_seen`, + [row.nodeId, row.addr, row.status, row.lastSeen], + ) + }, + async get(nodeId) { + const rows = await query(`SELECT * FROM relay_nodes WHERE node_id = $1`, [nodeId]) + const row = rows[0] + if (row === undefined) return null + return { nodeId: row.node_id, addr: row.addr, status: row.status, lastSeen: toIso(row.last_seen) } + }, + async setStatus(nodeId, status) { + const rows = await query<{ node_id: string }>( + `UPDATE relay_nodes SET status = $2 WHERE node_id = $1 RETURNING node_id`, + [nodeId, status], + ) + if (rows.length === 0) throw new Error('node not found') + }, + async touch(nodeId, ts) { + // Silent no-op if absent (matches memory.ts). + await query(`UPDATE relay_nodes SET last_seen = $2 WHERE node_id = $1`, [nodeId, ts]) + }, + async delete(nodeId) { + await query(`DELETE FROM relay_nodes WHERE node_id = $1`, [nodeId]) + }, + } +} + +// ---- MeteringStore ---------------------------------------------------------------------------- + +interface MeteringDbRow { + host_id: string + account_id: string + node_id: string + concurrent_viewers: number + sampled_at: Date | string +} + +function pgMeteringStore(query: QueryFn): MeteringStore { + return { + async append(row) { + await query( + `INSERT INTO metering_samples (host_id, account_id, node_id, concurrent_viewers, sampled_at) + VALUES ($1, $2, $3, $4, $5)`, + [row.hostId, row.accountId, row.nodeId, row.concurrentViewers, row.sampledAt], + ) + }, + async query(accountId, fromIso, toIso2) { + const rows = await query( + `SELECT host_id, account_id, node_id, concurrent_viewers, sampled_at + FROM metering_samples + WHERE account_id = $1 AND sampled_at >= $2 AND sampled_at <= $3 + ORDER BY id ASC`, + [accountId, fromIso, toIso2], + ) + return rows.map( + (r): MeteringSampleRow => ({ + hostId: r.host_id, + accountId: r.account_id, + nodeId: r.node_id, + concurrentViewers: r.concurrent_viewers, + sampledAt: toIso(r.sampled_at), + }), + ) + }, + } +} + +// ---- AuditStore ------------------------------------------------------------------------------- + +interface AuditDbRow { + action: string + principal_id: string + account_id: string + host_id: string | null + ts: Date | string + meta: Record +} + +function pgAuditStore(query: QueryFn): AuditStore { + return { + async append(row) { + await query( + `INSERT INTO audit_log (action, principal_id, account_id, host_id, ts, meta) + VALUES ($1, $2, $3, $4, $5, $6::jsonb)`, + [row.action, row.principalId, row.accountId, row.hostId, row.ts, JSON.stringify(row.meta)], + ) + }, + async query(accountId, fromIso, toIso2) { + const rows = await query( + `SELECT action, principal_id, account_id, host_id, ts, meta + FROM audit_log + WHERE account_id = $1 AND ts >= $2 AND ts <= $3 + ORDER BY id ASC`, + [accountId, fromIso, toIso2], + ) + return rows.map( + (r): AuditRow => ({ + action: r.action, + principalId: r.principal_id, + accountId: r.account_id, + hostId: r.host_id, + ts: toIso(r.ts), + meta: r.meta, + }), + ) + }, + } +} + +// ---- assembly --------------------------------------------------------------------------------- + +/** Build a full Postgres-backed store set (all ports mapped to parameterized SQL over `query`). */ +export function createPgStores(query: QueryFn): Stores { + return { + accounts: pgAccountStore(query), + hosts: pgHostStore(query), + sessions: pgSessionStore(query), + subdomains: pgSubdomainStore(query), + pairing: pgPairingStore(query), + routes: pgRouteStore(query), + nodes: pgNodeStore(query), + metering: pgMeteringStore(query), + audit: pgAuditStore(query), + } +} diff --git a/control-plane/test/api-extra.test.ts b/control-plane/test/api-extra.test.ts index 0ce0ebe..fe29234 100644 --- a/control-plane/test/api-extra.test.ts +++ b/control-plane/test/api-extra.test.ts @@ -24,7 +24,7 @@ const env = loadEnv({ }) const verifier: CapabilityVerifier = { - verify(raw, expectedAud, now): CapabilityToken { + async verify(raw, expectedAud, now): Promise { 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' } }, diff --git a/control-plane/test/api.test.ts b/control-plane/test/api.test.ts index 21bb02e..8fc96d2 100644 --- a/control-plane/test/api.test.ts +++ b/control-plane/test/api.test.ts @@ -25,8 +25,9 @@ const env = loadEnv({ }) // Fake P5 verifier: 'tokenA'→account A (manage), 'attachA'→account A (attach only). Else reject. +// Async to match the `CapabilityVerifier` seam (real §4.3 verify is async). const verifier: CapabilityVerifier = { - verify(raw, expectedAud, now): CapabilityToken { + async verify(raw, expectedAud, now): Promise { 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[] } diff --git a/control-plane/test/store/pg.test.ts b/control-plane/test/store/pg.test.ts new file mode 100644 index 0000000..23c7a28 --- /dev/null +++ b/control-plane/test/store/pg.test.ts @@ -0,0 +1,390 @@ +/** + * A1 — integration tests for the Postgres store adapter (src/store/pg.ts) + migration runner + * (src/db/migrate.ts). Exercises EVERY port method and the tricky semantics that must match + * store/memory.ts: INV8 version history, casRedeem single-winner, registerFailure, subdomain + * reserve/isTaken, route TTL fail-closed + listByNode, append-only metering/audit time windows. + * + * Gated on PG_TEST_URL. If unset, a disposable postgres:16 container is started on port 5433. + */ +import { afterAll, beforeAll, describe, expect, test } from 'vitest' +import { execSync } from 'node:child_process' +import { randomUUID } from 'node:crypto' +import { setTimeout as sleep } from 'node:timers/promises' +import { createPgPool, createQuery, type QueryFn } from '../../src/db/pool.js' +import { runMigrations } from '../../src/db/migrate.js' +import { createPgStores } from '../../src/store/pg.js' +import type { Stores } from '../../src/store/ports.js' +import type { AccountRecord, HostRecord } from '../../src/model/records.js' + +const CONTAINER = 'cp_pg_a1_test' +const PORT = 5433 +const READY_TIMEOUT_MS = 60_000 + +let pool: ReturnType | undefined +let query: QueryFn +let stores: Stores +let startedContainer = false + +beforeAll(async () => { + let url = process.env.PG_TEST_URL + if (!url) { + try { + execSync(`docker rm -f ${CONTAINER}`, { stdio: 'ignore' }) + } catch { + /* nothing to remove */ + } + execSync( + `docker run -d --rm --name ${CONTAINER} -e POSTGRES_PASSWORD=test -e POSTGRES_DB=cp -p ${PORT}:5432 postgres:16`, + { stdio: 'ignore' }, + ) + startedContainer = true + url = `postgres://postgres:test@127.0.0.1:${PORT}/cp` + } + + pool = createPgPool(url) + query = createQuery(pool) + + // Poll until the server accepts queries. + const deadline = Date.now() + READY_TIMEOUT_MS + for (;;) { + try { + await query('SELECT 1', []) + break + } catch (err) { + if (Date.now() > deadline) throw err + await sleep(500) + } + } + + await runMigrations(query) + // Idempotency: a second run must not throw (all migrations are IF NOT EXISTS). + await runMigrations(query) + stores = createPgStores(query) +}, 180_000) + +afterAll(async () => { + await pool?.end() + if (startedContainer) { + try { + execSync(`docker rm -f ${CONTAINER}`, { stdio: 'ignore' }) + } catch { + /* best effort */ + } + } +}) + +// ---- fixtures --------------------------------------------------------------------------------- + +function newAccount(): AccountRecord { + return { accountId: randomUUID(), plan: 'free', createdAt: new Date().toISOString(), status: 'active' } +} +async function makeAccount(): Promise { + const rec = newAccount() + await stores.accounts.insert(rec) + return rec +} +async function makeHost(accountId: string, subdomain = `sub-${randomUUID().slice(0, 8)}`): Promise { + const rec: HostRecord = { + hostId: randomUUID(), + accountId, + subdomain, + agentPubkey: new Uint8Array([1, 2, 3, 4]), + enrollFpr: `fpr-${subdomain}`, + status: 'offline', + lastSeen: new Date().toISOString(), + createdAt: new Date().toISOString(), + revokedAt: null, + } + await stores.hosts.insert(rec) + return rec +} + +// ---- AccountStore ----------------------------------------------------------------------------- + +describe('AccountStore', () => { + test('insert + get round-trips the record', async () => { + const rec = await makeAccount() + expect(await stores.accounts.get(rec.accountId)).toEqual(rec) + }) + + test('get returns null for unknown account', async () => { + expect(await stores.accounts.get(randomUUID())).toBeNull() + }) + + test('duplicate insert throws', async () => { + const rec = await makeAccount() + await expect(stores.accounts.insert(rec)).rejects.toThrow('duplicate accountId') + }) + + test('swapStatus bumps status + appends INV8 version history atomically', async () => { + const rec = await makeAccount() + expect(await stores.accounts.versions(rec.accountId)).toEqual([ + { accountId: rec.accountId, version: 1, status: 'active', changedAt: rec.createdAt, changedBy: 'system' }, + ]) + + const swapped = await stores.accounts.swapStatus(rec.accountId, 'suspended', 'admin-1') + expect(swapped.status).toBe('suspended') + expect(swapped.accountId).toBe(rec.accountId) + expect((await stores.accounts.get(rec.accountId))?.status).toBe('suspended') + + const versions = await stores.accounts.versions(rec.accountId) + expect(versions.length).toBe(2) + expect(versions[1]).toMatchObject({ version: 2, status: 'suspended', changedBy: 'admin-1' }) + }) + + test('swapStatus on unknown account throws', async () => { + await expect(stores.accounts.swapStatus(randomUUID(), 'suspended', 'x')).rejects.toThrow('account not found') + }) +}) + +// ---- HostStore -------------------------------------------------------------------------------- + +describe('HostStore', () => { + test('insert + get + getBySubdomain + listByAccount', async () => { + const acct = await makeAccount() + const host = await makeHost(acct.accountId) + expect(await stores.hosts.get(host.hostId)).toEqual(host) + expect(await stores.hosts.getBySubdomain(host.subdomain)).toEqual(host) + expect(await stores.hosts.listByAccount(acct.accountId)).toEqual([host]) + }) + + test('get / getBySubdomain return null when absent', async () => { + expect(await stores.hosts.get(randomUUID())).toBeNull() + expect(await stores.hosts.getBySubdomain(`missing-${randomUUID()}`)).toBeNull() + }) + + test('duplicate hostId and duplicate subdomain throw distinctly', async () => { + const acct = await makeAccount() + const host = await makeHost(acct.accountId) + await expect(stores.hosts.insert(host)).rejects.toThrow('duplicate hostId') + + const clash: HostRecord = { ...host, hostId: randomUUID() } + await expect(stores.hosts.insert(clash)).rejects.toThrow('duplicate subdomain') + }) + + test('swapStatus to revoked sets revokedAt + version history', async () => { + const acct = await makeAccount() + const host = await makeHost(acct.accountId) + const revokedAt = new Date().toISOString() + const swapped = await stores.hosts.swapStatus(host.hostId, 'revoked', revokedAt, 'admin-2') + expect(swapped.status).toBe('revoked') + expect(swapped.revokedAt).toBe(revokedAt) + + const versions = await stores.hosts.versions(host.hostId) + expect(versions.length).toBe(2) + expect(versions[0]).toMatchObject({ version: 1, status: 'offline', revokedAt: null, changedBy: 'system' }) + expect(versions[1]).toMatchObject({ version: 2, status: 'revoked', revokedAt, changedBy: 'admin-2' }) + }) + + test('swapStatus on unknown host throws', async () => { + await expect(stores.hosts.swapStatus(randomUUID(), 'online', null, 'x')).rejects.toThrow('host not found') + }) + + test('touchLastSeen updates the advisory cache (no version row)', async () => { + const acct = await makeAccount() + const host = await makeHost(acct.accountId) + const ts = new Date(Date.now() + 5000).toISOString() + await stores.hosts.touchLastSeen(host.hostId, ts) + expect((await stores.hosts.get(host.hostId))?.lastSeen).toBe(ts) + expect((await stores.hosts.versions(host.hostId)).length).toBe(1) // unchanged + await stores.hosts.touchLastSeen(randomUUID(), ts) // no-op on absent host, no throw + }) +}) + +// ---- SessionStore ----------------------------------------------------------------------------- + +describe('SessionStore', () => { + test('insert + get + duplicate + missing', async () => { + const acct = await makeAccount() + const host = await makeHost(acct.accountId) + const rec = { + sessionId: randomUUID(), + hostId: host.hostId, + accountId: acct.accountId, + createdAt: new Date().toISOString(), + lastAttachAt: new Date().toISOString(), + } + await stores.sessions.insert(rec) + expect(await stores.sessions.get(rec.sessionId)).toEqual(rec) + await expect(stores.sessions.insert(rec)).rejects.toThrow('duplicate sessionId') + expect(await stores.sessions.get(randomUUID())).toBeNull() + }) +}) + +// ---- SubdomainStore --------------------------------------------------------------------------- + +describe('SubdomainStore', () => { + test('reserve/isTaken reflect host ownership of the label', async () => { + const sub = `claim-${randomUUID().slice(0, 8)}` + expect(await stores.subdomains.isTaken(sub)).toBe(false) + expect(await stores.subdomains.reserve(sub)).toBe(true) // free (no host owns it yet) + + const acct = await makeAccount() + await makeHost(acct.accountId, sub) + + expect(await stores.subdomains.isTaken(sub)).toBe(true) + expect(await stores.subdomains.reserve(sub)).toBe(false) // a host now owns it + }) +}) + +// ---- PairingStore ----------------------------------------------------------------------------- + +describe('PairingStore', () => { + test('insert + get + casRedeem single-winner + registerFailure', async () => { + const acct = await makeAccount() + const codeHash = `code-${randomUUID()}` + const rec = { + codeHash, + accountId: acct.accountId, + expiresAt: new Date(Date.now() + 60_000).toISOString(), + redeemedAt: null, + } + await stores.pairing.insert(rec) + await expect(stores.pairing.insert(rec)).rejects.toThrow('duplicate code_hash') + + const got = await stores.pairing.get(codeHash) + expect(got).toEqual({ record: rec, redeemAttempts: 0 }) + + const now = new Date().toISOString() + expect(await stores.pairing.casRedeem(codeHash, now)).toBe('ok') + expect(await stores.pairing.casRedeem(codeHash, now)).toBe('already_redeemed') + expect(await stores.pairing.casRedeem(`unknown-${randomUUID()}`, now)).toBe('unknown') + expect((await stores.pairing.get(codeHash))?.record.redeemedAt).toBe(now) + }) + + test('registerFailure increments; unknown code returns 0', async () => { + const acct = await makeAccount() + const codeHash = `code-${randomUUID()}` + await stores.pairing.insert({ + codeHash, + accountId: acct.accountId, + expiresAt: new Date(Date.now() + 60_000).toISOString(), + redeemedAt: null, + }) + expect(await stores.pairing.registerFailure(codeHash)).toBe(1) + expect(await stores.pairing.registerFailure(codeHash)).toBe(2) + expect((await stores.pairing.get(codeHash))?.redeemAttempts).toBe(2) + expect(await stores.pairing.registerFailure(`unknown-${randomUUID()}`)).toBe(0) + }) + + test('get returns null for unknown code', async () => { + expect(await stores.pairing.get(`nope-${randomUUID()}`)).toBeNull() + }) +}) + +// ---- RouteStore ------------------------------------------------------------------------------- + +describe('RouteStore', () => { + test('set → get → refreshTtl → delete', async () => { + const hostId = randomUUID() + const entry = { relayNodeId: 'node-A', updatedAt: new Date().toISOString() } + await stores.routes.set(hostId, entry, 60) + expect(await stores.routes.get(hostId)).toEqual(entry) + expect(await stores.routes.refreshTtl(hostId, 60)).toBe(true) + await stores.routes.delete(hostId) + expect(await stores.routes.get(hostId)).toBeNull() + }) + + test('expired route fails closed (get null, refreshTtl false)', async () => { + const hostId = randomUUID() + const entry = { relayNodeId: 'node-A', updatedAt: new Date().toISOString() } + await stores.routes.set(hostId, entry, -1) // already expired + expect(await stores.routes.get(hostId)).toBeNull() + expect(await stores.routes.refreshTtl(hostId, 60)).toBe(false) + expect(await stores.routes.refreshTtl(randomUUID(), 60)).toBe(false) // absent + }) + + test('listByNode returns only live routes targeting the node', async () => { + const node = `node-${randomUUID().slice(0, 8)}` + const live1 = randomUUID() + const live2 = randomUUID() + const expired = randomUUID() + const otherNode = randomUUID() + await stores.routes.set(live1, { relayNodeId: node, updatedAt: new Date().toISOString() }, 60) + await stores.routes.set(live2, { relayNodeId: node, updatedAt: new Date().toISOString() }, 60) + await stores.routes.set(expired, { relayNodeId: node, updatedAt: new Date().toISOString() }, -1) + await stores.routes.set(otherNode, { relayNodeId: 'someone-else', updatedAt: new Date().toISOString() }, 60) + + const listed = await stores.routes.listByNode(node) + const hostIds = listed.map((r) => r.hostId).sort() + expect(hostIds).toEqual([live1, live2].sort()) + expect(listed.every((r) => r.entry.relayNodeId === node)).toBe(true) + }) +}) + +// ---- NodeStore -------------------------------------------------------------------------------- + +describe('NodeStore', () => { + test('upsert + get + setStatus + touch + delete', async () => { + const nodeId = `relay-${randomUUID().slice(0, 8)}` + const row = { nodeId, addr: '10.0.0.1:9000', status: 'active' as const, lastSeen: new Date().toISOString() } + await stores.nodes.upsert(row) + expect(await stores.nodes.get(nodeId)).toEqual(row) + + await stores.nodes.upsert({ ...row, addr: '10.0.0.2:9000' }) // upsert overwrites + expect((await stores.nodes.get(nodeId))?.addr).toBe('10.0.0.2:9000') + + await stores.nodes.setStatus(nodeId, 'draining') + expect((await stores.nodes.get(nodeId))?.status).toBe('draining') + + const later = new Date(Date.now() + 1000).toISOString() + await stores.nodes.touch(nodeId, later) + expect((await stores.nodes.get(nodeId))?.lastSeen).toBe(later) + + await stores.nodes.delete(nodeId) + expect(await stores.nodes.get(nodeId)).toBeNull() + }) + + test('setStatus on unknown node throws; touch is a silent no-op', async () => { + await expect(stores.nodes.setStatus(`ghost-${randomUUID()}`, 'draining')).rejects.toThrow('node not found') + await stores.nodes.touch(`ghost-${randomUUID()}`, new Date().toISOString()) // no throw + }) +}) + +// ---- MeteringStore ---------------------------------------------------------------------------- + +describe('MeteringStore', () => { + test('append-only + inclusive [from,to] time-window query filtered by account', async () => { + const acct = await makeAccount() + const other = await makeAccount() + const host = await makeHost(acct.accountId) + const otherHost = await makeHost(other.accountId) + + const t0 = '2026-01-01T00:00:00.000Z' + const t1 = '2026-01-01T01:00:00.000Z' + const t2 = '2026-01-01T02:00:00.000Z' + + await stores.metering.append({ hostId: host.hostId, accountId: acct.accountId, nodeId: 'n1', concurrentViewers: 3, sampledAt: t0 }) + await stores.metering.append({ hostId: host.hostId, accountId: acct.accountId, nodeId: 'n1', concurrentViewers: 5, sampledAt: t1 }) + await stores.metering.append({ hostId: host.hostId, accountId: acct.accountId, nodeId: 'n1', concurrentViewers: 9, sampledAt: t2 }) + await stores.metering.append({ hostId: otherHost.hostId, accountId: other.accountId, nodeId: 'n1', concurrentViewers: 1, sampledAt: t1 }) + + const inWindow = await stores.metering.query(acct.accountId, t0, t1) + expect(inWindow.map((r) => r.concurrentViewers)).toEqual([3, 5]) // t2 excluded, other acct excluded + expect(inWindow[0]).toMatchObject({ hostId: host.hostId, accountId: acct.accountId, sampledAt: t0 }) + + const all = await stores.metering.query(acct.accountId, t0, t2) + expect(all.length).toBe(3) + }) +}) + +// ---- AuditStore ------------------------------------------------------------------------------- + +describe('AuditStore', () => { + test('append-only + time-window query + null hostId + meta jsonb round-trip', async () => { + const accountId = randomUUID() + const t0 = '2026-02-01T00:00:00.000Z' + const t1 = '2026-02-01T01:00:00.000Z' + const t2 = '2026-02-01T02:00:00.000Z' + + await stores.audit.append({ action: 'provision', principalId: 'p1', accountId, hostId: 'h1', ts: t0, meta: { ip: '1.2.3.4' } }) + await stores.audit.append({ action: 'revoke', principalId: 'p2', accountId, hostId: null, ts: t1, meta: {} }) + await stores.audit.append({ action: 'late', principalId: 'p3', accountId, hostId: null, ts: t2, meta: {} }) + await stores.audit.append({ action: 'other', principalId: 'p9', accountId: randomUUID(), hostId: null, ts: t1, meta: {} }) + + const rows = await stores.audit.query(accountId, t0, t1) + expect(rows.map((r) => r.action)).toEqual(['provision', 'revoke']) // t2 + other account excluded + expect(rows[0]).toEqual({ action: 'provision', principalId: 'p1', accountId, hostId: 'h1', ts: t0, meta: { ip: '1.2.3.4' } }) + expect(rows[1]?.hostId).toBeNull() + }) +}) diff --git a/control-plane/test/verifier.test.ts b/control-plane/test/verifier.test.ts new file mode 100644 index 0000000..b5eb18f --- /dev/null +++ b/control-plane/test/verifier.test.ts @@ -0,0 +1,78 @@ +/** + * A3 — REAL capability verifier (boot/verifier.ts) backed by relay-auth's async `verifyCapabilityToken`. + * Mints tokens with the paired Ed25519 private key via P5's `issueCapabilityToken`, configures the + * matching public key, and asserts: a good token verifies; wrong `aud`, past `exp`, and a token + * signed by a NON-matching key all reject (deny-by-default, INV6). + */ +import { describe, test, expect, beforeAll } from 'vitest' +import { issueCapabilityToken } from 'relay-auth' +import type { AuthenticatedPrincipal } from 'relay-auth' +import { encodeBase64UrlBytes } from 'relay-contracts' +import { createCapabilityVerifier, configureCapabilityVerifyKey } from '../src/boot/verifier.js' +import type { CapabilityVerifier } from '../src/api/authz.js' + +const ACCOUNT_A = '11111111-1111-4111-8111-111111111111' +const AUD = 'term.example.com' +const NOW = 1_000_000 +// A base64url SHA-256 JWK thumbprint is exactly 43 chars of [A-Za-z0-9_-]; 32 bytes → 43 base64url chars. +const CNF_JKT = encodeBase64UrlBytes(new Uint8Array(32).fill(7)) + +const principal: AuthenticatedPrincipal = { + kind: 'human', + accountId: ACCOUNT_A, + principalId: 'cred-1', + amr: ['passkey'], + authAt: NOW - 10, + stepUpAt: null, +} + +type KeyPair = { publicKey: CryptoKey; privateKey: CryptoKey } +async function genKeyPair(): Promise { + // generateKey's named-algorithm overload is typed as CryptoKey; Ed25519 yields a pair at runtime. + return (await globalThis.crypto.subtle.generateKey({ name: 'Ed25519' }, true, ['sign', 'verify'])) as unknown as KeyPair +} + +function mint(signingKey: CryptoKey, now: number): Promise { + return issueCapabilityToken( + { principal, aud: AUD, host: 'host-1', rights: ['manage'], ttlSeconds: 60, cnfJkt: CNF_JKT }, + signingKey, + now, + ) +} + +describe('A3 real capability verifier (relay-auth verifyCapabilityToken)', () => { + let signingKey: CryptoKey + let verifier: CapabilityVerifier + + beforeAll(async () => { + const pair = await genKeyPair() + signingKey = pair.privateKey + const rawPub = new Uint8Array(await globalThis.crypto.subtle.exportKey('raw', pair.publicKey)) + await configureCapabilityVerifyKey(rawPub) + verifier = createCapabilityVerifier() + }) + + test('verifies a token signed by the configured key and returns the account principal', async () => { + const raw = await mint(signingKey, NOW) + const token = await verifier.verify(raw, AUD, NOW) + expect(token.sub).toBe(ACCOUNT_A) + expect(token.aud).toBe(AUD) + expect(token.rights).toContain('manage') + }) + + test('rejects a token minted for a different aud (Host-confusion guard)', async () => { + const raw = await mint(signingKey, NOW) + await expect(verifier.verify(raw, 'evil.example.com', NOW)).rejects.toThrow() + }) + + test('rejects an expired token', async () => { + const raw = await mint(signingKey, NOW) // exp = NOW + 60 + await expect(verifier.verify(raw, AUD, NOW + 120)).rejects.toThrow() + }) + + test('rejects a token signed by a NON-matching key (bad signature)', async () => { + const other = await genKeyPair() + const raw = await mint(other.privateKey, NOW) + await expect(verifier.verify(raw, AUD, NOW)).rejects.toThrow() + }) +}) diff --git a/deploy/.env.example b/deploy/.env.example new file mode 100644 index 0000000..662c723 --- /dev/null +++ b/deploy/.env.example @@ -0,0 +1,43 @@ +# RELAY-PHASE1 env template. Copy to deploy/.env (gitignored) and fill. NEVER commit real secrets. +# Convert relative → absolute paths on the VPS. See docs/PLAN_RELAY_PHASE1.md §3. + +# ── Docker Compose (deploy/docker-compose.yml) ──────────────────────────────────────────────── +POSTGRES_DB=relay +POSTGRES_USER=relay +POSTGRES_PASSWORD= # REQUIRED — strong random + +# ── Shared datastores (loopback; both processes) ───────────────────────────────────────────── +PG_URL=postgres://relay:CHANGEME@127.0.0.1:5432/relay +REDIS_URL=redis://127.0.0.1:6379 + +# ── Deployment identity ────────────────────────────────────────────────────────────────────── +BASE_DOMAIN=term.example.com # your ICP-filed domain; browser hits . +RELAY_NODE_ID=relay-1 +RELAY_TRUST_DOMAIN=relay.example.com # SPIFFE trust domain for agent certs + +# ── P5 capability keypair — CONTROL-PLANE SIGNS, RELAY VERIFIES. Same public key on both. ──── +# Generate an Ed25519 keypair; keep the PRIVATE key only where tokens are minted (never on disk here). +CAPABILITY_SIGN_PUBKEY_B64= # control-plane env: raw 32-byte Ed25519 pubkey, base64 +RELAY_AUTH_VERIFY_PUBKEY= # relay env: SAME key, base64url + +# ── Control-plane (P3) ─────────────────────────────────────────────────────────────────────── +CP_BIND_HOST=127.0.0.1 # admin API stays loopback-only (front only via the relay) +CP_BIND_PORT=8080 +CA_INTERMEDIATE_KMS_KEY_REF=dev-local # Phase 1: dev in-process signer accepts any ref (KMS → Phase 2) +CA_INTERMEDIATE_CERT_PATH=/etc/relay/ca/intermediate.cert.pem +NODE_MTLS_TRUST_BUNDLE_PATH=/etc/relay/ca/agent-ca.bundle.pem +# HEARTBEAT_TTL_SEC=15 PAIRING_TTL_SEC=600 PAIRING_MAX_REDEEM_ATTEMPTS=5 (defaults) + +# ── Relay data-plane (P1, relay-run Phase 1) ───────────────────────────────────────────────── +BIND_HOST=0.0.0.0 +BIND_PORT=443 # browser WSS (open in the Aliyun security group) +TLS_CERT_PATH=/etc/relay/tls/fullchain.pem # Let's Encrypt for . +TLS_KEY_PATH=/etc/relay/tls/privkey.pem +AGENT_BIND_PORT=8444 # agent mTLS (open in the security group) +AGENT_CA_CERT_PATH=/etc/relay/ca/agent-ca.cert.pem # private enrollment CA — NOT Let's Encrypt +AGENT_CA_CHAIN_PATH=/etc/relay/ca/agent-ca.bundle.pem + +# ── Agent (P2) — runs on YOUR laptop, not the VPS. Shown here for reference. ────────────────── +# RELAY_URL=wss://.term.example.com:8444 +# ENROLL_URL=https://.term.example.com/enroll (or the CP host) +# HOST_ID=... SUBDOMAIN= LOCAL_TARGET_URL=ws://127.0.0.1:3000 STATE_DIR=~/.web-terminal-agent diff --git a/deploy/docker-compose.yml b/deploy/docker-compose.yml new file mode 100644 index 0000000..b3d4b54 --- /dev/null +++ b/deploy/docker-compose.yml @@ -0,0 +1,48 @@ +# RELAY-PHASE1 · E1 — Postgres + Redis for the rendezvous-relay control-plane (P3) on the VPS. +# +# Both services bind to 127.0.0.1 ONLY — they are the relay's private state, never exposed on the +# public interface (INV9-adjacent; open only :443 + AGENT_PORT in the cloud security group). The +# control-plane / relay processes reach them over loopback. +# +# Usage on 8.138.1.192: +# cp deploy/.env.example deploy/.env # then fill secrets +# docker compose --env-file deploy/.env -f deploy/docker-compose.yml up -d +# +# PG_URL for the app = postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@127.0.0.1:5432/${POSTGRES_DB} +# REDIS_URL for the app = redis://127.0.0.1:6379 + +services: + postgres: + image: postgres:16 + restart: unless-stopped + environment: + POSTGRES_DB: ${POSTGRES_DB:-relay} + POSTGRES_USER: ${POSTGRES_USER:-relay} + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in deploy/.env} + ports: + - "127.0.0.1:5432:5432" # loopback-only + volumes: + - relay_pgdata:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-relay} -d ${POSTGRES_DB:-relay}"] + interval: 5s + timeout: 3s + retries: 10 + + redis: + image: redis:7 + restart: unless-stopped + command: ["redis-server", "--appendonly", "yes"] + ports: + - "127.0.0.1:6379:6379" # loopback-only + volumes: + - relay_redisdata:/data + healthcheck: + test: ["CMD", "redis-cli", "ping"] + interval: 5s + timeout: 3s + retries: 10 + +volumes: + relay_pgdata: + relay_redisdata: diff --git a/docs/PLAN_RELAY_PHASE1.md b/docs/PLAN_RELAY_PHASE1.md new file mode 100644 index 0000000..97d79f4 --- /dev/null +++ b/docs/PLAN_RELAY_PHASE1.md @@ -0,0 +1,172 @@ +# PLAN_RELAY_PHASE1 — deploy the native rendezvous-relay to a single VPS (staging, durable) + +> **Decision (2026-07-06):** Build **Phase 1 "1b — full durable staging"** on cloud VPS `8.138.1.192` +> (Alibaba Cloud, mainland). Real **Postgres + Redis via Docker Compose on the VPS**; real **TLS on +> `:443` via Let's Encrypt** against an **already ICP-filed domain**; agent runs on the operator's own +> machine and dials OUT. This plan is the file-level execution spec derived from a full code audit of +> the 7 relay packages. It supersedes the high-level phasing in [DEPLOY_RELAY.md](./DEPLOY_RELAY.md) §4 +> for the concrete build; that doc still holds for the *why* and the security runbook (§7). +> +> **Scope OUT (→ Phase 2):** real KMS custody of the CA (dev in-process signer is accepted for +> staging), F6 recoverable-replay transport (`loadReplay` stays fail-closed — not on the terminal path), +> WebAuthn/passkey step-up (staging uses `NO_STEPUP_POLICY` — single operator), wildcard multi-tenant +> subdomains, metering/alerting. Single tenant, single host, single relay node. + +--- + +## 0. Target (what "done" means) + +From the operator's laptop (agent dialing out) and any browser: + +1. `https://.` serves the relay-web bundle (same origin as the WSS endpoint). +2. Operator logs in, picks the host, and gets a live shell **spliced by the real relay-node** — the + relay only sees ciphertext (INV2); E2E is browser↔agent. +3. Agent enrolled once via a pairing code → holds a SPIFFE mTLS cert → dials `wss://…:AGENT_PORT`. +4. **Restart-safe:** bouncing the relay/control-plane process does NOT lose the host registration or + kill the operator's PTY (state is in Postgres/Redis; INV7). +5. Revoking the host tears the tunnel down within the INV12 budget (Redis `relay:revocations`). + +--- + +## 1. Code audit summary — what exists vs. what must be built + +Security-critical *logic* is written and injectable across all 7 packages. Phase 1 = build the +integration + infra layer they were designed to receive. Grounded gaps: + +| Area | State (file evidence) | Task | +|---|---|---| +| P3 Postgres adapter | **absent** — `store/pg.ts` does not exist; only `db/pool.ts` (`createPgPool`/`createQuery`) + full `db/migrations/0001_init.sql`. `memory.ts` is the semantics reference (INV8 versioning, CAS). | **A1** | +| P3 migration runner | none | **A1** | +| P3 server entrypoint | **absent** — no `.listen()`, no `start`; only `buildControlPlane(env, overrides)` factory (`main.ts:60`). | **A2** | +| P3 Redis revocation bus | `createRedisRevocationBus(RedisPublisher)` exists (`routing/bus.ts:42`) but no `ioredis` client instantiated; `main.ts:93` leaves `bus` inert. | **A2** | +| P3 F2 capability verifier | throwing stub `refuseAllVerifier` (`main.ts:44`). Must inject relay-auth `verifyCapabilityToken`. **Impedance:** CP's `CapabilityVerifier.verify` is **sync** (`api/authz.ts:24`), relay-auth's is **async** → seam must go async. | **A3** | +| relay EnforceDeps over shared store | relay-run uses its own in-RAM fakes (`relay-run/src/wiring/memory-stores.ts`), a **separate world** from the CP. Must implement `HostRegistryPort`/`SessionRegistryPort`/`RevocationStore`/`TokenBucketStore`/`AuditSink` over the **same** Postgres/Redis. | **B1** | +| relay `MtlsVerifier` | stub returns seeded host for any cert (`relay-world.ts:149`). Must use relay-auth `verifyAgentCert(leaf, caChain, now, hosts)` against the shared host registry + pinned agent CA. | **B2** | +| relay `RouteResolver` | one-entry in-RAM map (`data-plane.ts:110`). Must resolve subdomain→hostId from `hosts.getBySubdomain`. | **B3** | +| relay revocation subscriber | not wired. Subscribe `relay:revocations` → `killsScope` → `closeStream`. | **B4** | +| relay-run Phase-1 entry | `main.ts` hardcodes `127.0.0.1:8443`, `baseDomain='term.localhost'`, self-signed certs, dials no agent, `NO_STEP_UP`. | **B5** | +| agent build | `noEmit:true`, no `build` script, `dist/cli.js` never produced. | **C1** | +| agent runnable entry | `cli.ts` exports `parseArgs`/`runCli` but has **no `main()`/argv bootstrap, no `CliDeps` factory, no concrete `runTunnel`** (only assembled in `test/acceptance/cafeDemo.test.ts`). | **C2** | +| relay-web static serve | `build.mjs` emits `public/build/`; **no HTTP server** ships. Must serve `public/` same-origin as WSS. | **D1** | +| Infra | no Dockerfiles/compose/systemd anywhere. | **E** | + +--- + +## 2. Build order (waves by dependency) + +``` +A (P3 durable + serving) ──▶ B (relay data-plane on shared store) ──▶ E (infra + wire-up) + └──▶ C (agent buildable + runnable) ──────────▶ + └──▶ D (relay-web served) ────────────────────▶ +``` + +A is the foundation (both planes read the same store). B/C/D can proceed once A's store contract is +green. E stands up infra and does the end-to-end enroll→dial→click-through. + +### Wave A — control-plane durable + serving +- **A1 · PG store adapter + migration runner.** `Owns: control-plane/src/store/pg.ts`, + `control-plane/src/db/migrate.ts`, `control-plane/test/store/pg.test.ts`. + `createPgStores(query: QueryFn): Stores` implementing all 9 ports (`store/ports.ts`) with **byte-for-byte + semantics parity with `memory.ts`**: INV8 status-version+pointer swaps in one transaction, `casRedeem` + single-winner, `registerFailure` increment, `reserve` single-winner on the `subdomain UNIQUE` + constraint, TTL on routes (store `expires_at`, filter on read — Postgres has no key TTL). Map + snake_case columns ↔ camelCase records. Migration runner applies `db/migrations/*.sql` idempotently. + **Verify:** TDD against a real Postgres (Testcontainers or a Docker `postgres:16` on + `127.0.0.1:5432`); run the SAME behavioral suite the memory store passes. +- **A2 · P3 server entrypoint + Redis wiring.** `Owns: control-plane/src/server.ts`, + `control-plane/src/boot/redis.ts`, `package.json` (`start` script). + `loadEnv(process.env)` → `createPgPool(PG_URL)`+`createQuery` → `createPgStores` → migrate → + `ioredis` client → `createRedisRevocationBus(redis)` → `buildControlPlane(env, {stores, bus, + verifier, caChainDer})` → `app.listen({host:'0.0.0.0', port})`. Graceful SIGTERM. **Verify:** boots + against Docker PG+Redis; `POST /accounts` then `POST /accounts/:id/pairing-codes` round-trips. +- **A3 · F2 capability verifier (async).** `Owns: control-plane/src/api/authz.ts` (make + `CapabilityVerifier.verify` return `Promise`, await at call sites), `control-plane/src/boot/verifier.ts`, + `control-plane/src/main.ts` (default + `overrides.verifier` plumb + call `loadVerifyKeyFromEnv`). + Real verifier delegates to relay-auth `verifyCapabilityToken(raw, expectedAud, now)`; configure the + verify key from `CAPABILITY_SIGN_PUBKEY_B64` at boot. **Verify:** a token signed by the matching key + verifies; a foreign/expired token 401s; unblocks programmatic account/pairing seeding. + +### Wave B — relay data-plane on the shared store (P1 via relay-run) +- **B1 · shared-store EnforceDeps.** `Owns: relay-run/src/wiring/stores-pg.ts`, + `relay-run/test/stores-pg.test.ts`. Implement relay-auth's `HostRegistryPort`, `SessionRegistryPort`, + `RevocationStore`, `TokenBucketStore` (Redis token bucket), `AuditSink` (append to `audit_log`) over + the SAME PG/Redis as P3. Replace `memory-stores.ts` in the Phase-1 path. +- **B2 · registry-backed `MtlsVerifier`.** `Owns: relay-run/src/wiring/mtls-verifier.ts`. Wrap + relay-auth `verifyAgentCert(leafPem, caChainPem, now, hosts)`; pin the agent CA bundle; return + `{hostId, accountId}` only for enrolled+unrevoked hosts (INV4/INV14). +- **B3 · store-backed `RouteResolver`.** `Owns: relay-run/src/wiring/route-resolver.ts`. + `resolve(subdomain)` → `hosts.getBySubdomain` → hostId (or null). +- **B4 · revocation subscriber.** `Owns: relay-run/src/wiring/revocation-subscriber.ts` (or reuse + `term-relay/data-plane/revocation-subscriber.ts`). ioredis SUBSCRIBE `relay:revocations` → parse + `KillSignal` → `killsScope(signal, hostAccountId, hostId)` → `node.closeStream(...)`. +- **B5 · relay-run Phase-1 entry.** `Owns: relay-run/src/main-phase1.ts`, `relay-run/package.json` + (`start:phase1`). Env-driven (no hardcoding, CLAUDE §Config): bind `0.0.0.0`; `BASE_DOMAIN` + + computed `allowedOrigins` (port-less on :443, exact-match at `onUpgrade.ts:102`); real LE cert/key + paths for browser WSS; **separate** private agent-CA bundle for mTLS; `loadVerifyKeyFromEnv` at + startup; compose B1–B4; keep `NO_STEPUP_POLICY` (staging). Leave the Phase-0 `main.ts` untouched for dev. + +### Wave C — agent buildable + runnable (P2) +- **C1 · agent build.** `Owns: agent/tsconfig.build.json`, `agent/package.json` (`build`). Emit + `dist/cli.js` (esbuild bundle or `tsc` emit; keep `src` tsconfig `noEmit` for typecheck). +- **C2 · CLI bootstrap + `runTunnel`.** `Owns: agent/src/main.ts` (shebang + argv → `runCli`), + `agent/src/transport/runTunnel.ts`, `agent/src/cli/deps.ts` (`CliDeps` factory). Assemble + `dialRelay`→`holdTunnel`→`createStreamRouter`→`dialLoopback` + heartbeat/backoff, porting the proven + wiring from `test/acceptance/cafeDemo.test.ts`. **Verify:** `web-terminal-agent pair ` then + `web-terminal-agent run` enrolls + dials against a local Phase-1 relay. + +### Wave D — serve relay-web (P6) +- **D1 · same-origin static server.** `Owns: relay-run/src/servers/static-web.ts` (fold into the + browser HTTPS server so the bundle is served from the SAME origin/cert as the WSS, keeping + Origin/CSP aligned). Serve `relay-web/public/` (built). Add `npm --prefix relay-web run build` to the + deploy step. `loadReplay` stays fail-closed (Phase 2). + +### Wave E — infra + integration on 8.138.1.192 +- **E1 · Docker Compose** `Owns: deploy/docker-compose.yml`, `deploy/.env.example`. `postgres:16` + + `redis:7`, volumes, bound to `127.0.0.1` (not public). Health checks. +- **E2 · DNS + TLS.** A-record `.` → `8.138.1.192`; Let's Encrypt cert + (HTTP-01 on :80 or DNS-01) for that subdomain → `TLS_CERT_PATH`/`TLS_KEY_PATH`. +- **E3 · Enrollment CA.** Generate the private agent CA (staging may reuse the CP dev signer's CA) → + `CA_INTERMEDIATE_CERT_PATH`, `NODE_MTLS_TRUST_BUNDLE_PATH`, `AGENT_CA_CERT_PATH`. **Never** LE for mTLS. +- **E4 · Env + systemd + security group.** `deploy/control-plane.env`, `deploy/relay.env`, + `deploy/*.service`; open inbound `:443` (browser) + `AGENT_PORT` (agent mTLS) in the Aliyun security + group; keep CP admin + PG + Redis loopback-only. +- **E5 · End-to-end.** `POST /accounts` → `POST /accounts/:id/pairing-codes` → agent `pair`+`run` on + the laptop → browser opens `https://.` → click through to the shell. Confirm + restart-safety + revocation teardown. + +--- + +## 3. Environment / config reference (Phase 1, this VPS) + +**control-plane** (`control-plane/src/env.ts`, all required unless defaulted): +`PG_URL`, `REDIS_URL`, `CAPABILITY_SIGN_PUBKEY_B64` (32-byte Ed25519, base64), `CA_INTERMEDIATE_KMS_KEY_REF` +(dev signer accepts any ref), `CA_INTERMEDIATE_CERT_PATH`, `NODE_MTLS_TRUST_BUNDLE_PATH`, `BASE_DOMAIN`; +defaulted `HEARTBEAT_TTL_SEC`=15, `PAIRING_TTL_SEC`=600, `PAIRING_MAX_REDEEM_ATTEMPTS`=5. + +**relay-run Phase 1** (`term-relay/data-plane/config.ts` + new): `BASE_DOMAIN`, `BIND_HOST`=0.0.0.0, +`BIND_PORT`=443, `TLS_CERT_PATH`, `TLS_KEY_PATH`, `AGENT_BIND_PORT`, `AGENT_CA_CERT_PATH`, +`AGENT_CA_CHAIN_PATH`, `RELAY_NODE_ID`, `RELAY_AUTH_VERIFY_PUBKEY` (= `CAPABILITY_SIGN_PUBKEY_B64`, +base64url), `RELAY_TRUST_DOMAIN`, `PG_URL`, `REDIS_URL`. + +**agent** (`agent/src/config/agentConfig.ts`): `RELAY_URL` (`wss://…:AGENT_PORT`), `ENROLL_URL` +(`https:///enroll`), `HOST_ID`, `SUBDOMAIN`, `LOCAL_TARGET_URL` (`ws://127.0.0.1:3000` — the +base app), `STATE_DIR` (`~/.web-terminal-agent`). + +> **Key agreement (linchpin):** the P5 capability-signing keypair — CP signs, relay verifies. CP env +> `CAPABILITY_SIGN_PUBKEY_B64` and relay env `RELAY_AUTH_VERIFY_PUBKEY` MUST be the SAME public key. +> The **agent enrollment CA** (mTLS) and the **browser LE cert** are two independent trust chains. + +--- + +## 4. Invariants to preserve (do not regress) +INV2 opaque splice (relay sees only ciphertext) · INV3 accountId only from authenticated material · +INV7 PTY≠WS, relay nodes stateless/restart-safe · INV8 immutable versioned status · INV10 zero-payload +audit · INV12 revocation teardown budget · INV14 registry-gated mTLS. Origin/CSWSH exact-match on every +browser upgrade. Config via env only — no hardcoded hosts/ports/secrets. + +--- + +## 5. Progress +Tracked in [PROGRESS_LOG.md](./PROGRESS_LOG.md) under a `RELAY-PHASE1` heading. Task IDs: `A1–A3`, +`B1–B5`, `C1–C2`, `D1`, `E1–E5`. Orchestrator appends one entry per task on completion (status, files, +verification command+result, deviations, next). diff --git a/docs/PROGRESS_LOG.md b/docs/PROGRESS_LOG.md index c8c5270..4b69323 100644 --- a/docs/PROGRESS_LOG.md +++ b/docs/PROGRESS_LOG.md @@ -24,6 +24,25 @@ > 新会话读到的第一块。保持准确,只描述"此刻"。 +### 🚧 RELAY-PHASE1 — 把原生 rendezvous-relay 部署到单台 VPS(8.138.1.192,阿里云;2026-07-06) +- **目标**: DEPLOY_RELAY §4 的 **Phase 1「1b 全量持久化 staging」**。VPS 上 Docker 自建 Postgres+Redis;已备案域名走 443 + Let's Encrypt;agent 跑在操作者本机向外拨号。完整文件级方案见 [PLAN_RELAY_PHASE1.md](./PLAN_RELAY_PHASE1.md)。 +- **进度**: 地基 Wave A 已 2/3。**A1 (PG store 适配器+迁移) DONE**、**A3 (F2 异步能力验证器) DONE**、E1 (docker-compose+env 模板) DONE。全套 `npx vitest run`(control-plane)= **15 files / 101 tests pass**(A1 的 pg 测试 + A3 的 verifier 测试并存无冲突)。 +- **下一步**: **A2** — P3 server 入口(`loadEnv→createPgStores→runMigrations→ioredis→createRedisRevocationBus→buildControlPlane→listen`)+ Redis 撤销总线接线(`main.ts:93` 现为 inert)。然后 Wave B(relay 数据面读同一持久 store)。 +- **未做/推迟到 Phase 2**: 真 KMS(dev signer 暂用)、F6 replay(`loadReplay` fail-closed)、WebAuthn step-up(staging 用 `NO_STEPUP_POLICY`)、通配多租户。 + +#### [x] A1 — Postgres store 适配器(P3)+ 迁移运行器(2026-07-06) +- **交付**: `createPgStores(query): Stores` 把 9 个 store 端口映射为参数化 SQL(零字符串拼接);`runMigrations(query)` 按文件名顺序跑 `db/migrations/*.sql`(幂等)。 +- **文件(全在 Owns 内)**: `control-plane/src/store/pg.ts`、`src/db/migrate.ts`、`db/migrations/0002_routes.sql`(新增 — 0001 无 routes 表)、`test/store/pg.test.ts`。 +- **语义对齐 memory.ts**: INV8 accounts/hosts `swapStatus` 用单条 **writable CTE**(UPDATE 指针 + INSERT 版本行)原子完成,无显式事务;重复插入捕获 pg `23505`→`throw duplicate`;`casRedeem` 单赢家 `UPDATE...WHERE redeemed_at IS NULL RETURNING`;RouteStore 存 `expires_at`,`expires_at<=now()` 视为不存在(fail-closed INV7)+ 惰性 DELETE。 +- **验证(实测)**: `npx vitest run test/store/pg.test.ts` → **23/23 通过**(自起 `postgres:16` 一次性容器 :5433,afterAll 自动 `docker rm -f`);`pg.ts` 覆盖 **96.72% stmts / 100% funcs**。 +- **偏差**: ① `0002_routes.sql` 新增;② SubdomainStore 无独立预留表,按 `hosts.subdomain UNIQUE` 归属裁决;③ migrate 按 `;` 切分逐条执行(参数化路径拒绝多语句)。**阻塞**: 无。 + +#### [x] A3 — 真能力验证器(relay-auth verifyCapabilityToken)+ 同步→异步 seam(2026-07-06) +- **交付**: 抛异常的 `refuseAllVerifier` stub 换成委托 P5 异步 `verifyCapabilityToken` 的真验证器;`await` 贯通整个 authorizer 路径。默认仍 fail-closed(异步化后 reject→401)。 +- **文件**: `src/api/authz.ts`(`CapabilityVerifier.verify`→`Promise`)、`src/api/provision.ts`(5 个路由 call site 改 `await principal(req)`)、`src/boot/verifier.ts`(新;`configureCapabilityVerifyKey` 把 `env.capabilitySignPubkey` 32 字节导入 WebCrypto verify key 后调 relay-auth `configureVerifyKey`,桥接 `CAPABILITY_SIGN_PUBKEY_B64` vs `RELAY_AUTH_VERIFY_PUBKEY` 命名差)、`src/main.ts`、`package.json`(加 `relay-auth: file:../relay-auth`)、`test/verifier.test.ts`(新)+ 更新 api 测试 stub 为异步。 +- **验证(实测)**: `npx tsc --noEmit` 全项目干净;`npx vitest run` **15 files / 101 tests pass**。 +- **偏差**: 手建 `control-plane/node_modules/relay-auth` 符号链接以配合新 file: 依赖(`npm install` 会重建)。**阻塞**: 无。 + ### ✅ 修复:项目面板把父文件夹当项目 & 会话点亮所有祖先项目(2026-07-06,分支 `feat/ios-client`) - **现象(用户截图)**: 只在 `web-terminal` 跑了一个会话,但 "Active now" 同时显示 `web-terminal`/`Documents`/`yiukai` 三张卡,且父文件夹本身被列为项目。 - **根因(`src/http/projects.ts`)**: ① `belongsTo` 纯前缀匹配 → 会话按 cwd 归属到**每一个**祖先项目;② 历史合并(`mergeHistory`)把曾经跑过会话的 cwd(如 `~`、`~/Documents`)原样列为项目。