agent-tempo 1.0.1

package/dist/http/auth.d.ts

@@ -0,0 +1,67 @@
+import { type PersistedConfig } from '../config';
+/**
+ * Is the bind address effectively loopback? `0.0.0.0` is NOT loopback
+ * (it binds every interface, including external ones).
+ */
+export declare function isLoopbackBindAddr(bindAddr: string): boolean;
+/**
+ * Parse an `Origin` header to a hostname. Returns `null` when the header
+ * is absent, empty, or unparseable as a URL — caller decides the policy.
+ */
+export declare function originHost(originHeader: string | undefined): string | null;
+/**
+ * Decide whether bearer mode applies to this request, given the daemon's
+ * bind addr and the request's `Origin` header.
+ *
+ * - bind addr non-loopback → always bearer (`true`)
+ * - no Origin header on loopback bind → loopback mode (`false`)
+ * - Origin host is loopback on loopback bind → loopback mode (`false`)
+ * - Origin host is non-loopback OR unparseable on loopback bind → bearer (`true`)
+ */
+export declare function bearerRequired(bindAddr: string, originHeader: string | undefined): boolean;
+/**
+ * Extract the Bearer token from an `Authorization` header. Returns `null`
+ * when the header is missing or doesn't start with the `Bearer ` prefix
+ * (case-sensitive per RFC 6750 §2.1). Whitespace inside the token is
+ * preserved — comparison is constant-time exact match.
+ */
+export declare function extractBearerToken(authHeader: string | undefined): string | null;
+/**
+ * Constant-time token comparison.
+ *
+ * **Length-leak tradeoff** (PR-1 review followup): the leading
+ * length-mismatch short-circuit reveals the expected token length to a
+ * timing observer who can measure the difference between "rejected
+ * before constant-time compare" and "ran the full constant-time
+ * compare". Mitigations considered:
+ *
+ *  1. Pad the received token to a fixed length before comparison.
+ *     Adds branching in the pad path that itself can leak via timing.
+ *  2. Use HMAC-then-compare to render length irrelevant at the cost of
+ *     an extra hash per request.
+ *
+ * Neither is worth it for a token whose length is fixed by our own
+ * generator (`crypto.randomBytes(32).toString('base64url')` is always
+ * 43 chars). An attacker observing length learns nothing they can't
+ * trivially guess from inspecting the daemon's source. Without the
+ * length gate `crypto.timingSafeEqual` throws on mismatched lengths,
+ * which would force a try/catch in the hot path with worse timing
+ * properties. Document the assumption here so a future contributor
+ * reading "constant-time" doesn't assume length is also blinded.
+ */
+export declare function tokensMatch(received: string, expected: string): boolean;
+/**
+ * Load (or auto-generate) the daemon's HTTP bearer token.
+ *
+ * - When `bearerRequired` is true and the persisted config has no
+ *   `httpToken`, generate one (`crypto.randomBytes(32).toString('base64url')`)
+ *   and persist it via `saveConfigFile` (which sets 0600 on POSIX).
+ * - When `bearerRequired` is false, return whatever is in the config
+ *   without generating — operators may still want a token saved for
+ *   future use, and we shouldn't write secrets the user didn't request.
+ */
+export declare function loadOrGenerateHttpToken(opts: {
+    bearerRequired: boolean;
+    load?: () => PersistedConfig;
+    save?: (cfg: PersistedConfig) => void;
+}): string | null;

package/dist/http/auth.js

@@ -0,0 +1,177 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isLoopbackBindAddr = isLoopbackBindAddr;
+exports.originHost = originHost;
+exports.bearerRequired = bearerRequired;
+exports.extractBearerToken = extractBearerToken;
+exports.tokensMatch = tokensMatch;
+exports.loadOrGenerateHttpToken = loadOrGenerateHttpToken;
+/**
+ * Authentication for the daemon HTTP surface (SSE-PROTOCOL.md §3).
+ *
+ * **Two modes**:
+ *
+ * - **Loopback** (default, no auth) — bind addr is loopback AND the request
+ *   has no `Origin` header (curl, supervisord) OR `Origin` resolves to a
+ *   loopback host. Single-user dev workflows hit this path.
+ *
+ * - **Bearer** — required when bind addr is non-loopback (`0.0.0.0`) OR
+ *   when the request's `Origin` is non-loopback. Defends against DNS
+ *   rebinding even on a loopback-bound daemon: a malicious page on the
+ *   user's machine resolving `evil.com` to `127.0.0.1` cannot read the
+ *   daemon without the bearer token.
+ *
+ * `/v1/health` is **never authenticated** — it's the liveness probe used
+ * by reverse proxies, supervisord, and the TUI bootstrap state machine.
+ *
+ * **Token storage** (§3.1) — `~/.agent-tempo/config.json` field
+ * `httpToken`. Auto-generated on first daemon boot when bearer mode is
+ * required and no token is set: `crypto.randomBytes(32).toString('base64url')`,
+ * 0600 on POSIX. Rotation = delete the field; next daemon boot regenerates.
+ */
+const crypto = __importStar(require("crypto"));
+const config_1 = require("../config");
+/** Hostnames that count as loopback for §3 mode determination. */
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', '::1', '[::1]', 'localhost']);
+/**
+ * Is the bind address effectively loopback? `0.0.0.0` is NOT loopback
+ * (it binds every interface, including external ones).
+ */
+function isLoopbackBindAddr(bindAddr) {
+    return LOOPBACK_HOSTS.has(bindAddr);
+}
+/**
+ * Parse an `Origin` header to a hostname. Returns `null` when the header
+ * is absent, empty, or unparseable as a URL — caller decides the policy.
+ */
+function originHost(originHeader) {
+    if (!originHeader)
+        return null;
+    try {
+        const url = new URL(originHeader);
+        return url.hostname;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Decide whether bearer mode applies to this request, given the daemon's
+ * bind addr and the request's `Origin` header.
+ *
+ * - bind addr non-loopback → always bearer (`true`)
+ * - no Origin header on loopback bind → loopback mode (`false`)
+ * - Origin host is loopback on loopback bind → loopback mode (`false`)
+ * - Origin host is non-loopback OR unparseable on loopback bind → bearer (`true`)
+ */
+function bearerRequired(bindAddr, originHeader) {
+    if (!isLoopbackBindAddr(bindAddr))
+        return true;
+    if (!originHeader)
+        return false;
+    const host = originHost(originHeader);
+    if (host == null)
+        return true; // unparseable Origin → fail safe
+    return !LOOPBACK_HOSTS.has(host);
+}
+/**
+ * Extract the Bearer token from an `Authorization` header. Returns `null`
+ * when the header is missing or doesn't start with the `Bearer ` prefix
+ * (case-sensitive per RFC 6750 §2.1). Whitespace inside the token is
+ * preserved — comparison is constant-time exact match.
+ */
+function extractBearerToken(authHeader) {
+    if (!authHeader)
+        return null;
+    const prefix = 'Bearer ';
+    if (!authHeader.startsWith(prefix))
+        return null;
+    return authHeader.slice(prefix.length);
+}
+/**
+ * Constant-time token comparison.
+ *
+ * **Length-leak tradeoff** (PR-1 review followup): the leading
+ * length-mismatch short-circuit reveals the expected token length to a
+ * timing observer who can measure the difference between "rejected
+ * before constant-time compare" and "ran the full constant-time
+ * compare". Mitigations considered:
+ *
+ *  1. Pad the received token to a fixed length before comparison.
+ *     Adds branching in the pad path that itself can leak via timing.
+ *  2. Use HMAC-then-compare to render length irrelevant at the cost of
+ *     an extra hash per request.
+ *
+ * Neither is worth it for a token whose length is fixed by our own
+ * generator (`crypto.randomBytes(32).toString('base64url')` is always
+ * 43 chars). An attacker observing length learns nothing they can't
+ * trivially guess from inspecting the daemon's source. Without the
+ * length gate `crypto.timingSafeEqual` throws on mismatched lengths,
+ * which would force a try/catch in the hot path with worse timing
+ * properties. Document the assumption here so a future contributor
+ * reading "constant-time" doesn't assume length is also blinded.
+ */
+function tokensMatch(received, expected) {
+    if (received.length !== expected.length)
+        return false;
+    const a = Buffer.from(received, 'utf8');
+    const b = Buffer.from(expected, 'utf8');
+    return crypto.timingSafeEqual(a, b);
+}
+/**
+ * Load (or auto-generate) the daemon's HTTP bearer token.
+ *
+ * - When `bearerRequired` is true and the persisted config has no
+ *   `httpToken`, generate one (`crypto.randomBytes(32).toString('base64url')`)
+ *   and persist it via `saveConfigFile` (which sets 0600 on POSIX).
+ * - When `bearerRequired` is false, return whatever is in the config
+ *   without generating — operators may still want a token saved for
+ *   future use, and we shouldn't write secrets the user didn't request.
+ */
+function loadOrGenerateHttpToken(opts) {
+    const load = opts.load ?? config_1.loadConfigFile;
+    const save = opts.save ?? config_1.saveConfigFile;
+    const cfg = load();
+    if (cfg.httpToken && typeof cfg.httpToken === 'string' && cfg.httpToken.length > 0) {
+        return cfg.httpToken;
+    }
+    if (!opts.bearerRequired)
+        return null;
+    // Auto-generate. base64url chars are safe inside Authorization values.
+    const token = crypto.randomBytes(32).toString('base64url');
+    save({ ...cfg, httpToken: token });
+    return token;
+}

package/dist/http/body.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Shared HTTP body-reading helpers.
+ *
+ * Extracted from `writes.ts` so catalog/write/dashboard handlers all
+ * use the same JSON parser + size cap. The cap is enforced before
+ * parsing so a 1 GiB upload can't OOM the daemon.
+ *
+ * Sentinels (rather than thrown errors) keep the parse path branch-free
+ * — handlers compare against `BODY_TOO_LARGE` / `BODY_INVALID_JSON` and
+ * map to the appropriate 4xx response.
+ */
+import type { IncomingMessage, ServerResponse } from 'http';
+import { type AgentType } from '../types';
+/** Hard cap on incoming JSON body size (1 MiB). */
+export declare const WRITE_BODY_MAX: number;
+export declare const BODY_TOO_LARGE: unique symbol;
+export declare const BODY_INVALID_JSON: unique symbol;
+export type ReadJsonBodyResult = Record<string, unknown> | typeof BODY_TOO_LARGE | typeof BODY_INVALID_JSON;
+/**
+ * Read the request body up to {@link WRITE_BODY_MAX} bytes and parse
+ * as JSON. Returns the parsed object, an empty object for empty
+ * bodies, or one of the sentinel symbols for cap / parse failures.
+ *
+ * Note on the cap path: returning early from this function ends body
+ * consumption; Node's HTTP server tears down the upload when the
+ * handler ends. Explicit `req.destroy()` would race the response
+ * write — left alone.
+ */
+export declare function readJsonBody(req: IncomingMessage): Promise<ReadJsonBodyResult>;
+/**
+ * Pluck a string field from a parsed JSON body. Returns `undefined`
+ * for absent or non-string values; with `requireNonEmpty: true`, also
+ * filters empty strings (used by routes that accept optional fields
+ * — empty strings shouldn't propagate to downstream Temporal calls
+ * as if the user typed something).
+ */
+export declare function stringField(body: Record<string, unknown>, key: string, opts?: {
+    requireNonEmpty?: boolean;
+}): string | undefined;
+/**
+ * Agent allowlists, derived from {@link AGENT_TYPES} (the SSOT in
+ * `src/types.ts`).
+ *
+ * `'mock'` is dev-mode-only — see ADR 0014 §7. Read at request time so
+ * toggling `AGENT_TEMPO_DEV_MODE` between requests is picked up without
+ * restart (parity with `src/tools/recruit.ts`).
+ *
+ * Deriving from `AGENT_TYPES` rather than hardcoding the list closes the
+ * #541 drift bug: every new adapter (`claude-api`, `opencode`,
+ * `claude-code-headless`, …) added to the SSOT is automatically accepted
+ * by the HTTP recruit endpoint, instead of being silently rejected by an
+ * allowlist that someone forgot to update.
+ */
+export declare const ALLOWED_AGENTS_DEV: readonly AgentType[];
+export declare const ALLOWED_AGENTS_PROD: readonly AgentType[];
+export declare function allowedAgentsForCurrentMode(): readonly AgentType[];
+export declare function isAllowedAgent(s: string, allowed: readonly AgentType[]): s is AgentType;
+/**
+ * Pluck a required `playerId` from a parsed body, validating shape.
+ *
+ * Returns the `playerId` string on success. On any failure (missing or
+ * malformed) writes the appropriate 400 response via `errorResponse` and
+ * returns `undefined`. **Callers MUST check the return value and bail
+ * out** — a missing `if (!playerId) return;` would silently skip the
+ * downstream client call and double-send to the response stream.
+ *
+ * Shared by every per-player route under `/v1/ensembles/:ensemble/<action>`
+ * (restart / destroy / detach / recall — `release` keeps an inline check
+ * because its `playerId` field is optional, not required).
+ */
+export declare function requirePlayerId(res: ServerResponse, body: Record<string, unknown>): string | undefined;

package/dist/http/body.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALLOWED_AGENTS_PROD = exports.ALLOWED_AGENTS_DEV = exports.BODY_INVALID_JSON = exports.BODY_TOO_LARGE = exports.WRITE_BODY_MAX = void 0;
+exports.readJsonBody = readJsonBody;
+exports.stringField = stringField;
+exports.allowedAgentsForCurrentMode = allowedAgentsForCurrentMode;
+exports.isAllowedAgent = isAllowedAgent;
+exports.requirePlayerId = requirePlayerId;
+const types_1 = require("../types");
+const config_1 = require("../config");
+const responses_1 = require("./responses");
+const validation_1 = require("../utils/validation");
+/** Hard cap on incoming JSON body size (1 MiB). */
+exports.WRITE_BODY_MAX = 1024 * 1024;
+exports.BODY_TOO_LARGE = Symbol('body-too-large');
+exports.BODY_INVALID_JSON = Symbol('body-invalid-json');
+/**
+ * Read the request body up to {@link WRITE_BODY_MAX} bytes and parse
+ * as JSON. Returns the parsed object, an empty object for empty
+ * bodies, or one of the sentinel symbols for cap / parse failures.
+ *
+ * Note on the cap path: returning early from this function ends body
+ * consumption; Node's HTTP server tears down the upload when the
+ * handler ends. Explicit `req.destroy()` would race the response
+ * write — left alone.
+ */
+async function readJsonBody(req) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of req) {
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += buf.length;
+        if (total > exports.WRITE_BODY_MAX)
+            return exports.BODY_TOO_LARGE;
+        chunks.push(buf);
+    }
+    if (total === 0)
+        return {};
+    try {
+        const parsed = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return exports.BODY_INVALID_JSON;
+        }
+        return parsed;
+    }
+    catch {
+        return exports.BODY_INVALID_JSON;
+    }
+}
+/**
+ * Pluck a string field from a parsed JSON body. Returns `undefined`
+ * for absent or non-string values; with `requireNonEmpty: true`, also
+ * filters empty strings (used by routes that accept optional fields
+ * — empty strings shouldn't propagate to downstream Temporal calls
+ * as if the user typed something).
+ */
+function stringField(body, key, opts = {}) {
+    const v = body[key];
+    if (typeof v !== 'string')
+        return undefined;
+    if (opts.requireNonEmpty && v.length === 0)
+        return undefined;
+    return v;
+}
+/**
+ * Dev-mode-only agent identifiers — must never appear in {@link ALLOWED_AGENTS_PROD}.
+ *
+ * Currently just `'mock'` (ADR 0014 §7). Listed explicitly so the prod
+ * allowlist below is "everything in {@link AGENT_TYPES} minus this set",
+ * which keeps the dev-only gate auditable and the derived prod list
+ * automatically picks up new adapters as they land in `AGENT_TYPES`
+ * (#541 — the drift bug this constant prevents).
+ */
+const DEV_ONLY_AGENTS = new Set(['mock']);
+/**
+ * Agent allowlists, derived from {@link AGENT_TYPES} (the SSOT in
+ * `src/types.ts`).
+ *
+ * `'mock'` is dev-mode-only — see ADR 0014 §7. Read at request time so
+ * toggling `AGENT_TEMPO_DEV_MODE` between requests is picked up without
+ * restart (parity with `src/tools/recruit.ts`).
+ *
+ * Deriving from `AGENT_TYPES` rather than hardcoding the list closes the
+ * #541 drift bug: every new adapter (`claude-api`, `opencode`,
+ * `claude-code-headless`, …) added to the SSOT is automatically accepted
+ * by the HTTP recruit endpoint, instead of being silently rejected by an
+ * allowlist that someone forgot to update.
+ */
+exports.ALLOWED_AGENTS_DEV = types_1.AGENT_TYPES;
+exports.ALLOWED_AGENTS_PROD = types_1.AGENT_TYPES.filter((a) => !DEV_ONLY_AGENTS.has(a));
+function allowedAgentsForCurrentMode() {
+    return (0, config_1.isDevMode)() ? exports.ALLOWED_AGENTS_DEV : exports.ALLOWED_AGENTS_PROD;
+}
+function isAllowedAgent(s, allowed) {
+    return allowed.includes(s);
+}
+/**
+ * Pluck a required `playerId` from a parsed body, validating shape.
+ *
+ * Returns the `playerId` string on success. On any failure (missing or
+ * malformed) writes the appropriate 400 response via `errorResponse` and
+ * returns `undefined`. **Callers MUST check the return value and bail
+ * out** — a missing `if (!playerId) return;` would silently skip the
+ * downstream client call and double-send to the response stream.
+ *
+ * Shared by every per-player route under `/v1/ensembles/:ensemble/<action>`
+ * (restart / destroy / detach / recall — `release` keeps an inline check
+ * because its `playerId` field is optional, not required).
+ */
+function requirePlayerId(res, body) {
+    const playerId = stringField(body, 'playerId');
+    if (!playerId) {
+        (0, responses_1.errorResponse)(res, 400, { error: 'missing-field', field: 'playerId' });
+        return undefined;
+    }
+    if ((0, validation_1.validatePlayerName)(playerId) !== null) {
+        (0, responses_1.errorResponse)(res, 400, { error: 'invalid-player-name', field: 'playerId' });
+        return undefined;
+    }
+    return playerId;
+}

package/dist/http/catalog.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Daemon HTTP catalog routes — issue #400.
+ *
+ * Three endpoints exposing on-disk catalog data so the dashboard's
+ * Recruit + CreateEnsemble + Loadouts + PlayerTypes wizards can drop
+ * the hardcoded fallbacks shipped during PR-E + PR-F:
+ *
+ *   - GET  /v1/agent-types  → `listAgentTypes()` from ensemble/agent-types.ts
+ *   - GET  /v1/lineups      → `listLineups()` from ensemble/loader.ts
+ *   - POST /v1/ensembles    → recruit a conductor (+ lineup players)
+ *
+ * Auth + CORS gating happens in `server.ts` before the dispatcher
+ * reaches these handlers; no per-handler bearer check needed.
+ *
+ * Response shapes match the issue #400 wire spec; see also
+ * `docs/WIRE-PROTOCOL.md` for the full HTTP catalog.
+ */
+import type { IncomingMessage, ServerResponse } from 'http';
+import type { TempoClient } from '../client/interface';
+export interface AgentTypeRow {
+    name: string;
+    description?: string;
+    source: 'project' | 'user' | 'shipped';
+}
+/**
+ * `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`).
+ */
+export declare function handleListAgentTypes(res: ServerResponse): void;
+export interface LineupRow {
+    name: string;
+    description?: string;
+    players: number;
+    source: 'saved' | 'shipped';
+}
+export declare function handleListLineups(res: ServerResponse): void;
+/**
+ * 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.
+ */
+export declare function handleCreateEnsemble(req: IncomingMessage, res: ServerResponse, client: TempoClient): Promise<void>;