agent-tempo 1.0.1

package/dist/http/catalog.js

@@ -0,0 +1,209 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleListAgentTypes = handleListAgentTypes;
+exports.handleListLineups = handleListLineups;
+exports.handleCreateEnsemble = handleCreateEnsemble;
+const responses_1 = require("./responses");
+const agent_types_1 = require("../ensemble/agent-types");
+const loader_1 = require("../ensemble/loader");
+const saver_1 = require("../ensemble/saver");
+const validation_1 = require("../utils/validation");
+const body_1 = require("./body");
+/**
+ * `listAgentTypes()` returns rows with `path` + `nativeResolvable` +
+ * optional `allowedTools` — the dashboard only needs name/description/
+ * source. Strip the rest so we don't leak filesystem paths over the
+ * wire (loopback bind is the common case but the API is also reachable
+ * over LAN behind bearer auth — same privacy contract as `HostProfile`
+ * stripping in `src/types.ts`).
+ */
+function handleListAgentTypes(res) {
+    const types = (0, agent_types_1.listAgentTypes)();
+    const rows = types.map((t) => ({
+        name: t.name,
+        ...(t.description !== undefined && { description: t.description }),
+        source: t.source,
+    }));
+    (0, responses_1.jsonResponse)(res, 200, { agentTypes: rows });
+}
+function handleListLineups(res) {
+    // `listAllLineups()` returns a richer shape (`path` + parsed
+    // `description` / `players`); strip `path` before serving over the
+    // wire — privacy contract parity with the agent-types handler above.
+    const rows = (0, saver_1.listAllLineups)().map((l) => ({
+        name: l.name,
+        ...(l.description !== undefined && { description: l.description }),
+        players: l.players,
+        source: l.source,
+    }));
+    (0, responses_1.jsonResponse)(res, 200, { lineups: rows });
+}
+// ── POST /v1/ensembles ──────────────────────────────────────────────────────
+const ALLOWED_START_MODES = ['hold', 'release'];
+/**
+ * POST `/v1/ensembles` — create a fresh ensemble.
+ *
+ * The bootstrap path is the daemon-side equivalent of the CLI's
+ * `agent-tempo up` codepath, but trimmed to the actions the daemon
+ * can run for a browser caller:
+ *
+ *   1. Validate the body (name regex, lineup exists if specified,
+ *      startMode in {hold, release}).
+ *   2. Reject 409 if an ensemble with that name is already live.
+ *   3. Recruit the conductor (`isConductor: true`) — this bootstraps
+ *      the maestro + scheduler + conductor-session workflows.
+ *   4. Recruit each lineup player. Inherits `host` + `held` from the
+ *      top-level body when the lineup row doesn't specify its own.
+ *   5. Return 201 + the ensemble summary so the dashboard can
+ *      navigate to `/ensemble/:name` without a follow-up snapshot
+ *      fetch.
+ *
+ * Skipped vs CLI `up` (intentional):
+ *   - No Temporal-server start: the daemon serving this request
+ *     already proves Temporal is up.
+ *   - No daemon start / agent-type install / MCP register: a browser
+ *     caller doesn't go through that pre-flight.
+ *   - No interactive "ensemble already exists" choice tree: HTTP is
+ *     stateless; we 409 and let the dashboard surface a useful error.
+ */
+async function handleCreateEnsemble(req, res, client) {
+    const body = await (0, body_1.readJsonBody)(req);
+    if (body === body_1.BODY_TOO_LARGE) {
+        return (0, responses_1.errorResponse)(res, 413, { error: 'body-too-large', limit: body_1.WRITE_BODY_MAX });
+    }
+    if (body === body_1.BODY_INVALID_JSON) {
+        return (0, responses_1.errorResponse)(res, 400, { error: 'invalid-json' });
+    }
+    const parsed = parseBody(body);
+    if ('error' in parsed)
+        return (0, responses_1.errorResponse)(res, 400, parsed.error);
+    const { name, lineup, host, startMode, conductorInstructions } = parsed.body;
+    // 409 — ensemble already exists. `listEnsembles()` returns live
+    // ensembles by Temporal workflow; matches what the dashboard's
+    // `/v1/ensembles` GET sees. Note: TOCTOU between this read and the
+    // recruit below — two concurrent POSTs with the same name could both
+    // pass and both recruit. Acceptable for the browser-driven flow
+    // (user-paced); the proper guard is recruit-side idempotency, not
+    // here.
+    const existing = await client.listEnsembles();
+    if (existing.some((e) => e.name === name)) {
+        return (0, responses_1.errorResponse)(res, 409, { error: 'ensemble-exists', ensemble: name });
+    }
+    // Resolve lineup if specified. We `loadLineup` here (not at recruit
+    // time) so the caller gets a clean 400 for malformed lineups instead
+    // of a half-bootstrapped ensemble with the conductor already alive.
+    let resolved = null;
+    if (lineup) {
+        try {
+            const path = (0, loader_1.resolveLineupPath)(lineup).path;
+            resolved = (0, loader_1.loadLineup)(path);
+        }
+        catch (err) {
+            return (0, responses_1.errorResponse)(res, 400, {
+                error: 'invalid-lineup',
+                lineup,
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    const held = startMode === 'hold';
+    const allowed = (0, body_1.allowedAgentsForCurrentMode)();
+    // 1. Recruit the conductor — bootstraps maestro + scheduler. Lineup's
+    // `conductor` block (if present) wins on name + agent + part; the
+    // top-level `host` is the conductor's spawn target either way.
+    const conductorBlock = resolved?.conductor;
+    const conductorName = conductorBlock?.name ?? 'conductor';
+    const conductorAgent = pickAgent(conductorBlock?.agent, allowed);
+    try {
+        await client.recruit(name, {
+            name: conductorName,
+            workDir: process.cwd(),
+            isConductor: true,
+            ...(conductorAgent !== undefined && { agent: conductorAgent }),
+            ...(host !== undefined && { host }),
+            ...(held && { held: true }),
+            ...(conductorInstructions !== undefined && { initialMessage: conductorInstructions }),
+        });
+    }
+    catch (err) {
+        return (0, responses_1.errorResponse)(res, 500, {
+            error: 'conductor-recruit-failed',
+            message: err instanceof Error ? err.message : String(err),
+        });
+    }
+    // 2. Recruit each lineup player. Errors here are non-fatal — the
+    // ensemble is already alive (conductor is running); we collect
+    // failures and return them in the 201 body so the dashboard can
+    // surface a partial-success toast without rolling back the
+    // conductor. Parallel fan-out keeps a 5+ player ensemble from
+    // stacking N sequential Temporal round-trips on the client.
+    const lineupPlayers = resolved?.players ?? [];
+    const playerErrors = [];
+    const settled = await Promise.allSettled(lineupPlayers.map((player) => {
+        const playerAgent = pickAgent(player.agent, allowed);
+        return client.recruit(name, {
+            name: player.name,
+            workDir: player.workDir ?? process.cwd(),
+            ...(playerAgent !== undefined && { agent: playerAgent }),
+            ...(player.type !== undefined && { playerType: player.type }),
+            ...(host !== undefined && { host }),
+            ...(held && { held: true }),
+            ...(player.instructions !== undefined && { systemPrompt: player.instructions }),
+        });
+    }));
+    settled.forEach((result, i) => {
+        if (result.status === 'rejected') {
+            playerErrors.push({
+                player: lineupPlayers[i].name,
+                error: result.reason instanceof Error ? result.reason.message : String(result.reason),
+            });
+        }
+    });
+    (0, responses_1.jsonResponse)(res, 201, {
+        ensemble: name,
+        conductorPlayerId: conductorName,
+        lineup: lineup ?? null,
+        recruitedPlayers: lineupPlayers.length - playerErrors.length,
+        ...(playerErrors.length > 0 && { playerErrors }),
+    });
+}
+function parseBody(body) {
+    // `requireNonEmpty` filters whitespace-zero strings — empty lineup /
+    // host / instructions shouldn't propagate as if the user typed
+    // something.
+    const name = (0, body_1.stringField)(body, 'name', { requireNonEmpty: true });
+    if (!name)
+        return { error: { error: 'missing-field', field: 'name' } };
+    if ((0, validation_1.validateEnsembleName)(name) !== null) {
+        return { error: { error: 'invalid-ensemble-name', field: 'name' } };
+    }
+    const lineup = (0, body_1.stringField)(body, 'lineup', { requireNonEmpty: true });
+    const host = (0, body_1.stringField)(body, 'host', { requireNonEmpty: true });
+    const startMode = (0, body_1.stringField)(body, 'startMode', { requireNonEmpty: true });
+    if (startMode !== undefined && !isStartMode(startMode)) {
+        return { error: { error: 'invalid-start-mode', allowed: ALLOWED_START_MODES } };
+    }
+    const conductorInstructions = (0, body_1.stringField)(body, 'conductorInstructions', { requireNonEmpty: true });
+    // Lightweight host-name shape check (matches the daemon's existing
+    // hostname rules used by recruit). Skips when omitted.
+    if (host !== undefined && (0, validation_1.validatePlayerName)(host) !== null) {
+        return { error: { error: 'invalid-host', field: 'host' } };
+    }
+    return {
+        body: {
+            name,
+            ...(lineup !== undefined && { lineup }),
+            ...(host !== undefined && { host }),
+            ...(startMode !== undefined && { startMode: startMode }),
+            ...(conductorInstructions !== undefined && { conductorInstructions }),
+        },
+    };
+}
+function isStartMode(s) {
+    return ALLOWED_START_MODES.includes(s);
+}
+function pickAgent(candidate, allowed) {
+    if (candidate === undefined)
+        return undefined;
+    return (0, body_1.isAllowedAgent)(candidate, allowed) ? candidate : undefined;
+}

package/dist/http/cors.d.ts

@@ -0,0 +1,42 @@
+export interface CorsConfig {
+    /** Explicit list from `AGENT_TEMPO_CORS_ORIGINS`. Empty → defaults only. */
+    allowedOrigins: string[];
+}
+/**
+ * Parse the comma-separated env var. Empty / undefined → empty list.
+ * Trims whitespace; rejects empty entries; preserves case (Origin
+ * comparison is case-sensitive per RFC 6454 §4).
+ */
+export declare function parseCorsOrigins(raw: string | undefined): string[];
+/**
+ * Decide if `originHeader` is allowed. Pass `true` for `bearerActive` only
+ * when bearer mode applies to the request — loopback mode short-circuits
+ * to `true` (no enforcement).
+ *
+ * Returns the value to echo on `Access-Control-Allow-Origin`, or `null`
+ * if the origin should be rejected. The default loopback allowlist
+ * (`localhost:*`, `127.0.0.1:*`) matches by hostname only; ports are
+ * always permitted because operators frequently bind dev servers to
+ * arbitrary ports.
+ */
+export declare function evaluateOrigin(originHeader: string | undefined, config: CorsConfig, bearerActive: boolean): {
+    allowed: boolean;
+    echo: string | null;
+};
+/**
+ * Static CORS response headers — independent of the request's Origin.
+ * The dynamic `Access-Control-Allow-Origin` comes from
+ * {@link evaluateOrigin}.
+ */
+export declare function corsResponseHeaders(): Record<string, string>;
+/**
+ * Convenience wrapper — should the daemon enforce CORS at all? `true`
+ * iff the bind addr is non-loopback (every connection is bearer-mode)
+ * OR the operator opted into bearer mode by setting an explicit
+ * allowlist via `AGENT_TEMPO_CORS_ORIGINS`.
+ *
+ * Used at boot time to decide whether to install the CORS middleware
+ * or no-op it. Per-request bearer determination still happens via
+ * {@link bearerRequired} — this helper is a startup short-circuit.
+ */
+export declare function corsEnforced(bindAddr: string, allowedOrigins: string[]): boolean;

package/dist/http/cors.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCorsOrigins = parseCorsOrigins;
+exports.evaluateOrigin = evaluateOrigin;
+exports.corsResponseHeaders = corsResponseHeaders;
+exports.corsEnforced = corsEnforced;
+/**
+ * CORS handling for the daemon HTTP surface (SSE-PROTOCOL.md §3.2).
+ *
+ * **Only enforced in bearer mode.** Loopback-mode requests skip CORS
+ * entirely — there's no cross-origin worry when the daemon and consumer
+ * share a host with no Origin or a loopback Origin.
+ *
+ * **Defaults**:
+ * - Allowlist: `localhost:*` and `127.0.0.1:*` echoed back
+ * - `Access-Control-Allow-Credentials: false` (non-configurable)
+ * - `Access-Control-Allow-Methods: GET, OPTIONS` (non-configurable)
+ * - `Access-Control-Allow-Headers: Authorization, Last-Event-ID` (non-configurable)
+ * - `Access-Control-Max-Age: 600` (non-configurable)
+ *
+ * Override the allowlist via `AGENT_TEMPO_CORS_ORIGINS` — comma-separated
+ * explicit origins (e.g. `https://dashboard.example.com,https://localhost:3000`).
+ * Wildcards are NOT supported. `*` is incompatible with credentials, and
+ * we want operators to opt every origin in deliberately.
+ */
+const auth_1 = require("./auth");
+/** Hostnames that always pass the default allowlist. */
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', '::1', 'localhost']);
+/**
+ * Parse the comma-separated env var. Empty / undefined → empty list.
+ * Trims whitespace; rejects empty entries; preserves case (Origin
+ * comparison is case-sensitive per RFC 6454 §4).
+ */
+function parseCorsOrigins(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/**
+ * Decide if `originHeader` is allowed. Pass `true` for `bearerActive` only
+ * when bearer mode applies to the request — loopback mode short-circuits
+ * to `true` (no enforcement).
+ *
+ * Returns the value to echo on `Access-Control-Allow-Origin`, or `null`
+ * if the origin should be rejected. The default loopback allowlist
+ * (`localhost:*`, `127.0.0.1:*`) matches by hostname only; ports are
+ * always permitted because operators frequently bind dev servers to
+ * arbitrary ports.
+ */
+function evaluateOrigin(originHeader, config, bearerActive) {
+    // Loopback mode: never enforce. No ACAO header set unless caller picks
+    // a permissive value — leave the decision to the response builder.
+    if (!bearerActive)
+        return { allowed: true, echo: null };
+    if (!originHeader) {
+        // Bearer mode but no Origin (e.g. server-to-server fetch). Allow
+        // by default; the bearer token still gates content. Browser fetches
+        // always include Origin — this branch is for non-browser callers.
+        return { allowed: true, echo: null };
+    }
+    // Explicit allowlist takes precedence.
+    if (config.allowedOrigins.length > 0) {
+        if (config.allowedOrigins.includes(originHeader)) {
+            return { allowed: true, echo: originHeader };
+        }
+        return { allowed: false, echo: null };
+    }
+    // Default: any port on a loopback hostname.
+    let host = null;
+    try {
+        const url = new URL(originHeader);
+        host = url.hostname;
+    }
+    catch {
+        return { allowed: false, echo: null };
+    }
+    if (host && LOOPBACK_HOSTS.has(host)) {
+        return { allowed: true, echo: originHeader };
+    }
+    return { allowed: false, echo: null };
+}
+/**
+ * Static CORS response headers — independent of the request's Origin.
+ * The dynamic `Access-Control-Allow-Origin` comes from
+ * {@link evaluateOrigin}.
+ */
+function corsResponseHeaders() {
+    return {
+        'Access-Control-Allow-Methods': 'GET, OPTIONS',
+        'Access-Control-Allow-Headers': 'Authorization, Last-Event-ID',
+        'Access-Control-Allow-Credentials': 'false',
+        'Access-Control-Max-Age': '600',
+        Vary: 'Origin',
+    };
+}
+/**
+ * Convenience wrapper — should the daemon enforce CORS at all? `true`
+ * iff the bind addr is non-loopback (every connection is bearer-mode)
+ * OR the operator opted into bearer mode by setting an explicit
+ * allowlist via `AGENT_TEMPO_CORS_ORIGINS`.
+ *
+ * Used at boot time to decide whether to install the CORS middleware
+ * or no-op it. Per-request bearer determination still happens via
+ * {@link bearerRequired} — this helper is a startup short-circuit.
+ */
+function corsEnforced(bindAddr, allowedOrigins) {
+    return !(0, auth_1.isLoopbackBindAddr)(bindAddr) || allowedOrigins.length > 0;
+}

package/dist/http/dashboard-pair.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Dashboard QR-code pairing flow — PR-8 of #340.
+ *
+ * Replaces the 501 stub `handlePairTokenStub` from
+ * `src/http/dashboard.ts` (PR-1) with the real two-endpoint flow:
+ *
+ *   POST /dashboard/api/pair         (post-auth)
+ *     The CLI invokes this when the operator runs `agent-tempo
+ *     dashboard --pair`. Mints a single-use, 5-minute, base64url
+ *     32-byte token. The token is paired with the operator's bearer
+ *     for delivery on consume.
+ *
+ *   GET  /dashboard/api/pair/:token  (pre-auth carve-out, parallel
+ *                                     to /v1/health)
+ *     The dashboard SPA calls this on first mount when it sees
+ *     `?pair=<token>` in the URL. Exchanges the token for the
+ *     daemon's bearer + a TTL hint. Marks the token used so a
+ *     second consume returns 410 Gone.
+ *
+ * State is in-memory (`Map<token, PendingPairing>`) — daemon restart
+ * invalidates outstanding pairings, which ADR 0013 documents as an
+ * acceptable trade for v1 (operator re-runs `--pair` after a
+ * restart; pairings are inherently transient).
+ *
+ * Token lifecycle:
+ *   created   → mint adds to `pendingPairings`
+ *   consumed  → first GET marks `used: true` + immediately deletes
+ *               from the map so a leaked token can't even attempt a
+ *               second exchange. (The check is "absent or used".)
+ *   expired   → swept every {@link PAIR_SWEEP_INTERVAL_MS} or
+ *               opportunistically on consume; returns 410 in both
+ *               cases.
+ *
+ * Security posture:
+ *   - The token is 32 bytes of `crypto.randomBytes` rendered as
+ *     base64url. ~256 bits of entropy; brute-force is infeasible
+ *     within the 5-min window.
+ *   - The token is short-TTL by design — we don't persist it across
+ *     daemon restarts and we don't surface it on logs above prefix.
+ *   - We never log the full token. `pair.minted` / `pair.consumed`
+ *     log lines carry only the first 8 chars (`tokenPrefix`) for
+ *     correlating with telemetry.
+ *   - The mint endpoint requires a bearer (it's behind the standard
+ *     auth gate). The consume endpoint does NOT require a bearer —
+ *     the token IS the auth, parallel to `/v1/health` per
+ *     `docs/design/340-web-dashboard.md` §4.1.
+ */
+import type { IncomingMessage, ServerResponse } from 'http';
+/** TTL for a pending pairing — 5 minutes, hard ceiling. */
+export declare const PAIR_TTL_MS: number;
+/** How often the sweep removes expired entries; cheaper than per-request. */
+export declare const PAIR_SWEEP_INTERVAL_MS: number;
+/**
+ * Hard cap on simultaneous pending pairings. Defence-in-depth against
+ * an abusive operator (or a script in the operator's terminal)
+ * hammering `agent-tempo dashboard --pair` faster than the 60-second
+ * sweep can reclaim memory. With 5-min TTL the natural ceiling is one
+ * mint per second × 300 seconds = 300 entries; cap at 100 forces a
+ * 503 long before that becomes load-bearing.
+ */
+export declare const MAX_PENDING_PAIRINGS = 100;
+/** Generate a fresh token. Exported for tests. */
+export declare function mintPairToken(): string;
+/**
+ * POST `/dashboard/api/pair` — mint a pairing. Caller is the operator
+ * via `agent-tempo dashboard --pair`; the request has already passed
+ * the bearer-auth gate so we know the operator is authorised. We
+ * accept the operator's bearer from the `Authorization` header and
+ * stamp it onto the pending entry so consume can hand it back.
+ *
+ * Response: `{ token, expiresAt }`. The CLI renders the QR.
+ */
+export declare function handlePairCreate(req: IncomingMessage, res: ServerResponse, bearer: string | null): void;
+/**
+ * GET `/dashboard/api/pair/:token` — exchange the token for the bearer.
+ *
+ * Single-use: even if expired or never minted, return 410 Gone so an
+ * attacker can't distinguish "token never existed" from "token
+ * already consumed". The `error` field stays generic
+ * (`pair-token-invalid`) for the same reason.
+ */
+export declare function handlePairConsume(_req: IncomingMessage, res: ServerResponse, token: string): void;
+/**
+ * Test escape hatch — wipe the in-memory map so each test starts
+ * from zero pendingPairings. Production code MUST NOT call this.
+ *
+ * Following the project's `__<verb><Noun>ForTests` naming convention
+ * (ADR 0006). Also stops the sweep timer so vitest exits cleanly.
+ */
+export declare function __resetPairingsForTests(): void;
+/** Test-only — peek at the current count of pending pairings. */
+export declare function __pendingPairingsCountForTests(): number;
+/** Test-only — manually trigger the sweep at a synthetic `now`. */
+export declare function __sweepExpiredForTests(now: number): number;

package/dist/http/dashboard-pair.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_PENDING_PAIRINGS = exports.PAIR_SWEEP_INTERVAL_MS = exports.PAIR_TTL_MS = void 0;
+exports.mintPairToken = mintPairToken;
+exports.handlePairCreate = handlePairCreate;
+exports.handlePairConsume = handlePairConsume;
+exports.__resetPairingsForTests = __resetPairingsForTests;
+exports.__pendingPairingsCountForTests = __pendingPairingsCountForTests;
+exports.__sweepExpiredForTests = __sweepExpiredForTests;
+const crypto_1 = require("crypto");
+const responses_1 = require("./responses");
+/** TTL for a pending pairing — 5 minutes, hard ceiling. */
+exports.PAIR_TTL_MS = 5 * 60 * 1000;
+/** How often the sweep removes expired entries; cheaper than per-request. */
+exports.PAIR_SWEEP_INTERVAL_MS = 60 * 1000;
+/** Bytes of entropy in the token; rendered as base64url (no padding). */
+const PAIR_TOKEN_BYTES = 32;
+/**
+ * Hard cap on simultaneous pending pairings. Defence-in-depth against
+ * an abusive operator (or a script in the operator's terminal)
+ * hammering `agent-tempo dashboard --pair` faster than the 60-second
+ * sweep can reclaim memory. With 5-min TTL the natural ceiling is one
+ * mint per second × 300 seconds = 300 entries; cap at 100 forces a
+ * 503 long before that becomes load-bearing.
+ */
+exports.MAX_PENDING_PAIRINGS = 100;
+/**
+ * In-memory pending-pairing map. Module-level so a single daemon
+ * shares one map across requests; tests reset via
+ * `__resetPairingsForTests`.
+ */
+const pendingPairings = new Map();
+let sweepTimer = null;
+function scheduleSweep() {
+    if (sweepTimer)
+        return;
+    sweepTimer = setInterval(() => sweepExpired(), exports.PAIR_SWEEP_INTERVAL_MS);
+    // Don't keep the daemon process alive on a sweep timer alone.
+    if (typeof sweepTimer.unref === 'function')
+        sweepTimer.unref();
+}
+/** Strip every entry whose `expiresAt` is in the past. */
+function sweepExpired(now = Date.now()) {
+    let removed = 0;
+    for (const [token, p] of pendingPairings) {
+        if (p.expiresAt <= now) {
+            pendingPairings.delete(token);
+            removed++;
+        }
+    }
+    return removed;
+}
+/** Generate a fresh token. Exported for tests. */
+function mintPairToken() {
+    return (0, crypto_1.randomBytes)(PAIR_TOKEN_BYTES).toString('base64url');
+}
+/** First 8 chars of the token — safe to log for telemetry correlation. */
+function prefix(token) {
+    return token.slice(0, 8);
+}
+const log = (...args) => console.error('[agent-tempo:pair]', ...args);
+/**
+ * POST `/dashboard/api/pair` — mint a pairing. Caller is the operator
+ * via `agent-tempo dashboard --pair`; the request has already passed
+ * the bearer-auth gate so we know the operator is authorised. We
+ * accept the operator's bearer from the `Authorization` header and
+ * stamp it onto the pending entry so consume can hand it back.
+ *
+ * Response: `{ token, expiresAt }`. The CLI renders the QR.
+ */
+function handlePairCreate(req, res, bearer) {
+    if (!bearer) {
+        // Defensive — the caller in `server.ts` already requires bearer
+        // mode for non-loopback binds. On loopback there's no bearer to
+        // hand back, so the pair flow is a no-op (the SPA on the host
+        // doesn't need a token; QR-code-from-mobile is the use case).
+        return (0, responses_1.errorResponse)(res, 400, {
+            error: 'pair-requires-bearer',
+            hint: 'pair flow only meaningful on bearer-protected binds',
+        });
+    }
+    // Opportunistic sweep before the size check — if we're at the cap
+    // because the sweep timer hasn't run yet, expired entries should
+    // free up first rather than turning every retry into a 503.
+    sweepExpired();
+    if (pendingPairings.size >= exports.MAX_PENDING_PAIRINGS) {
+        log('pair.mint-rejected', `reason=cap-exceeded pending=${pendingPairings.size}`);
+        return (0, responses_1.errorResponse)(res, 503, {
+            error: 'pair-pending-cap',
+            hint: 'too many pending pairings — wait for the 5-min TTL to expire and retry',
+        });
+    }
+    const token = mintPairToken();
+    const expiresAt = Date.now() + exports.PAIR_TTL_MS;
+    pendingPairings.set(token, { bearer, expiresAt });
+    scheduleSweep();
+    log('pair.minted', `tokenPrefix=${prefix(token)}`, `expiresAt=${expiresAt}`);
+    // No `Cache-Control` override — `jsonResponse` defaults to `no-store`.
+    (0, responses_1.jsonResponse)(res, 201, { token, expiresAt });
+}
+/**
+ * GET `/dashboard/api/pair/:token` — exchange the token for the bearer.
+ *
+ * Single-use: even if expired or never minted, return 410 Gone so an
+ * attacker can't distinguish "token never existed" from "token
+ * already consumed". The `error` field stays generic
+ * (`pair-token-invalid`) for the same reason.
+ */
+function handlePairConsume(_req, res, token) {
+    const now = Date.now();
+    const entry = pendingPairings.get(token);
+    if (!entry || entry.expiresAt <= now) {
+        if (entry)
+            pendingPairings.delete(token); // expired — clean up
+        log('pair.consume-rejected', `tokenPrefix=${prefix(token)}`, `reason=invalid-or-expired`);
+        return (0, responses_1.errorResponse)(res, 410, { error: 'pair-token-invalid' });
+    }
+    // Single-use: delete IMMEDIATELY before we even write the response
+    // so a duplicate request lands on the "absent" branch above.
+    pendingPairings.delete(token);
+    log('pair.consumed', `tokenPrefix=${prefix(token)}`);
+    (0, responses_1.jsonResponse)(res, 200, {
+        bearer: entry.bearer,
+        expiresAt: entry.expiresAt,
+    });
+}
+/**
+ * Test escape hatch — wipe the in-memory map so each test starts
+ * from zero pendingPairings. Production code MUST NOT call this.
+ *
+ * Following the project's `__<verb><Noun>ForTests` naming convention
+ * (ADR 0006). Also stops the sweep timer so vitest exits cleanly.
+ */
+function __resetPairingsForTests() {
+    pendingPairings.clear();
+    if (sweepTimer) {
+        clearInterval(sweepTimer);
+        sweepTimer = null;
+    }
+}
+/** Test-only — peek at the current count of pending pairings. */
+function __pendingPairingsCountForTests() {
+    return pendingPairings.size;
+}
+/** Test-only — manually trigger the sweep at a synthetic `now`. */
+function __sweepExpiredForTests(now) {
+    return sweepExpired(now);
+}

package/dist/http/dashboard.d.ts

@@ -0,0 +1,20 @@
+import type { IncomingMessage, ServerResponse } from 'http';
+/** Repo-relative path from the compiled `dist/` output — the production default. */
+export declare const DASHBOARD_DIST: string;
+/**
+ * Serve a request under `/dashboard/*`. The caller in `server.ts` has
+ * already URL-parsed the request and gated by prefix, and passes the
+ * normalised `pathname` in to avoid a second parse on the hot path.
+ */
+export declare function handleDashboardStatic(req: IncomingMessage, res: ServerResponse, pathname: string): void;
+/**
+ * Test escape hatch — override the dist root used by
+ * {@link handleDashboardStatic}. Pass `null` to restore the production
+ * default.
+ *
+ * **Do not call from production code.** The double-underscore prefix
+ * marks this as a test-only hook (see ADR 0006). Used by
+ * `tests/http/dashboard-handler.test.ts` to point the handler at a
+ * fixture directory without modifying the real `dashboard/dist/`.
+ */
+export declare function __setDashboardDistRootForTests(override: string | null): void;