@ai-codebot/daemon 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ai-codebot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,61 @@
+# @ai-codebot/daemon
+
+The slock **local-runner** daemon (PR4). Dials the cloud relay (`/daemon/connect`)
+over an outbound WSS tunnel, speaks the PR2 frame protocol, and on a `Launch` runs a
+local coding-agent in `cwd=repo` — brokering the model credential through a
+`127.0.0.1` per-launch proxy so the **real LLM key never reaches the agent**.
+
+```
+npx @ai-codebot/daemon connect \
+  --server-url wss://<your-relay-host>/daemon/connect \
+  --api-key ck_machine_… \
+  [--repo <path>] [--model-url <url>] [--cli claude|codex|auto] [--once]
+```
+
+The machine key may also be supplied via `CODEBOT_MACHINE_KEY`. The key is never
+logged.
+
+## Architecture
+
+- `src/frames.ts` — TS + zod mirror of the server's `daemon_frames.py` (snake_case,
+  `MAX_FRAME_BYTES = 256 KiB`). Inbound frames are zod-validated at the boundary.
+- `src/tunnel.ts` — `ws` client. Bearer in the `Authorization` header (never the
+  query), Hello/HelloAck handshake, Pong-on-Ping, exp-backoff + full-jitter
+  reconnect. Close codes: 4401 unauth / 4409 superseded → no reconnect.
+- `src/broker/` — the `127.0.0.1` capability broker (C4). A per-launch
+  `crypto.randomBytes(32)` token is handed to the child as `ANTHROPIC_API_KEY`; the
+  broker stream-pipes requests to the real model endpoint, **injecting the real key**.
+  The real key + the `ck_machine_` machine key are stripped from the child env.
+- `src/spawn/` — PRIMARY = real CLI (fail-fast until the OQ-3 flag contract is
+  verified); FALLBACK = the N2 local tool-loop (read/write/replace/run-tests/finish).
+  `disallowed-tools.ts` is the single source of truth for the blacklist.
+
+## Security invariants (Tier-A)
+
+1. The real model key never reaches the agent (env/argv/token-file/logs).
+2. Per-launch token isolation: wrong token → 401, non-model path → 403, broker dies
+   with the launch.
+3. The `ck_machine_` key is confined to the tunnel layer.
+4. Disallowed tools stripped before spawn; deadline kills child+broker; SIGINT tears
+   down all launches (no orphans / `0600` token files).
+5. No silent fallback: model unreachable / no model / no CLI+no N2 → loud `failed`.
+6. Exactly one `Result` per launch (零静默).
+
+## Tests
+
+```
+pnpm --filter @ai-codebot/daemon test       # automated tsx --test suite (CI)
+node verify-daemon.mjs --server-url ws://127.0.0.1:8001/daemon/connect …   # MANUAL E2E (NOT CI)
+```
+
+Real CLIs + a real local model cannot run in CI; `verify-daemon.mjs` documents the
+owner-run E2E against a SECOND agent-service on `:8001` (never `:8000`).
+
+## OQ-3 (PRIMARY CLI flags — unverified)
+
+The exact headless / JSON-output / disallowed-tools flag NAMES for the shipped
+Claude Code / Codex CLIs are **unverified**. They live behind the `CLI_FLAG_CONTRACT`
+constant in `src/spawn/cli-runner.ts` with `verified: false`; the runner **fails
+fast** (`CliContractUnverifiedError`) rather than emit a possibly-wrong invocation,
+and the launch falls back to the fully-tested N2 path. To enable a CLI: verify the
+real flags, flip `verified: true`, and add an integration proof in `verify-daemon.mjs`.

package/dist/broker/handoff.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Credential handoff to the spawned child (design §5 — C4/C7).
+ *
+ * `buildSpawnEnv` is the env boundary. It is an **allowlist**, never a denylist: it
+ * starts from an EMPTY env, copies ONLY known-safe vars (PATH/HOME/… — the shared
+ * `ENV_ALLOWLIST` source of truth, also used by the N2 `run_tests` scrub), then sets
+ * the model creds to the per-launch capability token + the broker URL. A denylist of
+ * "known provider key vars" is fundamentally incomplete (AWS, AZURE, GOOGLE creds, …
+ * leak through), so the real LLM key, the `ck_machine_` machine key, and ANY other
+ * inherited credential NEVER reach the child's env or argv.
+ *
+ * `createTokenFile` writes the token to a `0600` file inside a fresh per-launch 0700
+ * private dir (`O_EXCL` atomic create — defends a shared `/tmp` against symlink
+ * pre-placement). `removeTokenDir` is the idempotent cleanup contract.
+ */
+import { ENV_ALLOWLIST } from "../spawn/n2-tools.js";
+export declare const CAPABILITY_TOKEN_FILE_ENV = "CODEBOT_CAPABILITY_TOKEN_FILE";
+export declare const AGENT_CAPABILITIES_ENV = "CODEBOT_AGENT_CAPABILITIES";
+export { ENV_ALLOWLIST };
+export interface SpawnEnvParams {
+    /** The localhost broker base URL (`ANTHROPIC_BASE_URL`). */
+    readonly brokerBaseUrl: string;
+    /** The per-launch capability token (`ANTHROPIC_API_KEY`, NOT the real key). */
+    readonly token: string;
+    /** Path to the `0600` token file (`CODEBOT_CAPABILITY_TOKEN_FILE`). */
+    readonly tokenFile: string;
+    /** Advisory capability list (the path allowlist is the real boundary). */
+    readonly capabilities: readonly string[];
+    /** Base env to start from (defaults to the daemon's own env). */
+    readonly baseEnv?: NodeJS.ProcessEnv;
+}
+/**
+ * Build the child env via the shared ALLOWLIST: start empty, copy only known-safe
+ * vars, then set the model creds to the capability token + broker URL. The real key,
+ * the `ck_machine_` machine key, and every other inherited credential are absent by
+ * construction (they were never copied).
+ */
+export declare function buildSpawnEnv(params: SpawnEnvParams): Record<string, string>;
+/** A created token file: its path plus the private dir to remove on teardown. */
+export interface TokenFileHandle {
+    /** Absolute path to the `0600` token file. */
+    readonly path: string;
+    /** The per-launch 0700 private dir holding it (removed by `removeTokenDir`). */
+    readonly dir: string;
+}
+/**
+ * Atomically create the capability token file in a fresh per-launch private dir.
+ *
+ * - `mkdtempSync` makes a unique `codebot-launch-XXXXXX` dir (mode 0700) under the OS
+ *   tmpdir — an attacker cannot guess the path to pre-place a symlink.
+ * - The token file is opened with `O_WRONLY|O_CREAT|O_EXCL, 0600`: create-or-FAIL.
+ *   `O_EXCL` refuses to follow a pre-existing symlink, closing the shared-`/tmp`
+ *   symlink-attack window.
+ */
+export declare function createTokenFile(token: string): TokenFileHandle;
+/** Idempotently remove the per-launch token dir (and the token file within it). */
+export declare function removeTokenDir(dir: string): void;

package/dist/broker/handoff.js

@@ -0,0 +1,87 @@
+/**
+ * Credential handoff to the spawned child (design §5 — C4/C7).
+ *
+ * `buildSpawnEnv` is the env boundary. It is an **allowlist**, never a denylist: it
+ * starts from an EMPTY env, copies ONLY known-safe vars (PATH/HOME/… — the shared
+ * `ENV_ALLOWLIST` source of truth, also used by the N2 `run_tests` scrub), then sets
+ * the model creds to the per-launch capability token + the broker URL. A denylist of
+ * "known provider key vars" is fundamentally incomplete (AWS, AZURE, GOOGLE creds, …
+ * leak through), so the real LLM key, the `ck_machine_` machine key, and ANY other
+ * inherited credential NEVER reach the child's env or argv.
+ *
+ * `createTokenFile` writes the token to a `0600` file inside a fresh per-launch 0700
+ * private dir (`O_EXCL` atomic create — defends a shared `/tmp` against symlink
+ * pre-placement). `removeTokenDir` is the idempotent cleanup contract.
+ */
+import { constants as fsConstants, chmodSync, closeSync, mkdtempSync, openSync, rmSync, writeSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ENV_ALLOWLIST, isAllowedEnvVar } from "../spawn/n2-tools.js";
+import { log } from "../logging.js";
+export const CAPABILITY_TOKEN_FILE_ENV = "CODEBOT_CAPABILITY_TOKEN_FILE";
+export const AGENT_CAPABILITIES_ENV = "CODEBOT_AGENT_CAPABILITIES";
+// Re-exported so `buildSpawnEnv` and the N2 `run_tests` scrub demonstrably share ONE
+// allowlist — there is no second, drifting copy.
+export { ENV_ALLOWLIST };
+const TOKEN_FILE_NAME = "capability.token";
+/**
+ * Build the child env via the shared ALLOWLIST: start empty, copy only known-safe
+ * vars, then set the model creds to the capability token + broker URL. The real key,
+ * the `ck_machine_` machine key, and every other inherited credential are absent by
+ * construction (they were never copied).
+ */
+export function buildSpawnEnv(params) {
+    const base = params.baseEnv ?? process.env;
+    // 1. Start from an EMPTY env and copy ONLY allowlisted, known-safe names.
+    const env = {};
+    for (const [k, v] of Object.entries(base)) {
+        if (v !== undefined && isAllowedEnvVar(k))
+            env[k] = v;
+    }
+    // 2. Set the model creds to the per-launch token + broker URL. The child talks to
+    //    the broker (which holds the real key), never the provider directly.
+    env["ANTHROPIC_BASE_URL"] = params.brokerBaseUrl;
+    env["ANTHROPIC_API_KEY"] = params.token;
+    // OpenAI-compatible CLIs (codex) read these — point them at the broker too.
+    env["OPENAI_BASE_URL"] = params.brokerBaseUrl;
+    env["OPENAI_API_KEY"] = params.token;
+    // 3. Token file + advisory capabilities.
+    env[CAPABILITY_TOKEN_FILE_ENV] = params.tokenFile;
+    env[AGENT_CAPABILITIES_ENV] = params.capabilities.join(",");
+    return env;
+}
+/**
+ * Atomically create the capability token file in a fresh per-launch private dir.
+ *
+ * - `mkdtempSync` makes a unique `codebot-launch-XXXXXX` dir (mode 0700) under the OS
+ *   tmpdir — an attacker cannot guess the path to pre-place a symlink.
+ * - The token file is opened with `O_WRONLY|O_CREAT|O_EXCL, 0600`: create-or-FAIL.
+ *   `O_EXCL` refuses to follow a pre-existing symlink, closing the shared-`/tmp`
+ *   symlink-attack window.
+ */
+export function createTokenFile(token) {
+    // mkdtemp creates the dir with mode 0700 (POSIX); chmod defensively regardless.
+    const dir = mkdtempSync(join(tmpdir(), "codebot-launch-"));
+    chmodSync(dir, 0o700);
+    const path = join(dir, TOKEN_FILE_NAME);
+    const fd = openSync(path, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL, 0o600);
+    try {
+        writeSync(fd, token, null, "utf8");
+    }
+    finally {
+        closeSync(fd);
+    }
+    return { path, dir };
+}
+/** Idempotently remove the per-launch token dir (and the token file within it). */
+export function removeTokenDir(dir) {
+    try {
+        rmSync(dir, { recursive: true, force: true });
+    }
+    catch (err) {
+        log.warn("handoff.token_dir_remove_failed", {
+            error: err.message,
+        });
+    }
+}
+//# sourceMappingURL=handoff.js.map

package/dist/broker/handoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff.js","sourceRoot":"","sources":["../../src/broker/handoff.ts"],"names":[],"mappings":"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"}

package/dist/broker/server.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The 127.0.0.1 per-launch capability broker (design §5 — C4, Tier-A V2).
+ *
+ * Topology:
+ *   CLI ──HTTP──► broker(127.0.0.1:<ephemeral>) ──HTTPS──► real model endpoint
+ *
+ * The spawned agent sees only the per-launch capability TOKEN (as a Bearer); the
+ * broker validates it, then **stream-pipes** the request to the real
+ * `model_override.api_url` with the real `api_key` injected. The real key never
+ * reaches the child (env/argv/token-file/logs).
+ *
+ * Hard rules:
+ *   - Bind 127.0.0.1 only, ephemeral port (`listen(0, "127.0.0.1")`).
+ *   - Bearer must equal the launch token → else 401.
+ *   - Only the model-provider API paths proxy (e.g. `/v1/messages`,
+ *     `/v1/chat/completions`) → other paths 403.
+ *   - STREAM-PIPE, never buffer — SSE / long generations must flow through.
+ *   - The real key is injected ONLY on the upstream request; never logged.
+ */
+import { type Server } from "node:http";
+import type { GrantRegistry } from "./token.js";
+export interface BrokerHandle {
+    /** The localhost base URL to hand the child as `ANTHROPIC_BASE_URL`. */
+    readonly baseUrl: string;
+    /** Idempotent shutdown — stops accepting, closes the listener. */
+    close(): Promise<void>;
+}
+/**
+ * Start the per-launch broker on an ephemeral 127.0.0.1 port. Resolves once the
+ * listener is bound and the base URL is known.
+ */
+export declare function startBroker(grants: GrantRegistry): Promise<{
+    server: Server;
+} & BrokerHandle>;

package/dist/broker/server.js

@@ -0,0 +1,204 @@
+/**
+ * The 127.0.0.1 per-launch capability broker (design §5 — C4, Tier-A V2).
+ *
+ * Topology:
+ *   CLI ──HTTP──► broker(127.0.0.1:<ephemeral>) ──HTTPS──► real model endpoint
+ *
+ * The spawned agent sees only the per-launch capability TOKEN (as a Bearer); the
+ * broker validates it, then **stream-pipes** the request to the real
+ * `model_override.api_url` with the real `api_key` injected. The real key never
+ * reaches the child (env/argv/token-file/logs).
+ *
+ * Hard rules:
+ *   - Bind 127.0.0.1 only, ephemeral port (`listen(0, "127.0.0.1")`).
+ *   - Bearer must equal the launch token → else 401.
+ *   - Only the model-provider API paths proxy (e.g. `/v1/messages`,
+ *     `/v1/chat/completions`) → other paths 403.
+ *   - STREAM-PIPE, never buffer — SSE / long generations must flow through.
+ *   - The real key is injected ONLY on the upstream request; never logged.
+ */
+import { createServer, request as httpRequest, } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { log } from "../logging.js";
+const BEARER_PREFIX = "Bearer ";
+// Allowlisted upstream API paths (the model-provider surface). The inbound path
+// from the agent must EXACTLY equal one of these — anything else is rejected 403.
+// The upstream base-path prefix is added separately in `buildUpstream`, so a
+// prefix/suffix/`..`-traversal trick (e.g. `/attacker/v1/messages`) cannot smuggle
+// the real key onto an arbitrary upstream path.
+const ALLOWED_PATHS = new Set([
+    "/v1/messages",
+    "/v1/chat/completions",
+    "/v1/complete",
+]);
+// Deadline-bound socket guards: a slow-drip request/headers stream must not be able
+// to pin a connection (and thus block launch teardown) indefinitely.
+const REQUEST_TIMEOUT_MS = 10 * 60 * 1000; // whole-request ceiling (long generations)
+const HEADERS_TIMEOUT_MS = 60 * 1000; // headers must arrive within a minute
+function extractBearer(req) {
+    const header = req.headers["authorization"];
+    if (typeof header !== "string" || !header.startsWith(BEARER_PREFIX))
+        return null;
+    const token = header.slice(BEARER_PREFIX.length).trim();
+    return token || null;
+}
+function isAllowedPath(pathname) {
+    // EXACT match only — never `endsWith`. A prefix like `/attacker/v1/messages`
+    // or a `/v1/../x/v1/messages` traversal must NOT inject the real key upstream.
+    return ALLOWED_PATHS.has(pathname);
+}
+function sendJson(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, { "content-type": "application/json" });
+    res.end(payload);
+}
+/**
+ * Build the upstream request options from the grant's real upstream URL, merging
+ * the inbound path/query onto the upstream origin and injecting the real key.
+ */
+function buildUpstream(upstreamUrl, upstreamKey, req) {
+    const base = new URL(upstreamUrl);
+    const inbound = new URL(req.url ?? "/", "http://127.0.0.1");
+    // Preserve any base path on the upstream URL, then append the inbound pathname.
+    const basePath = base.pathname.replace(/\/$/, "");
+    const path = `${basePath}${inbound.pathname}${inbound.search}`;
+    const isHttps = base.protocol === "https:";
+    const headers = {};
+    for (const [k, v] of Object.entries(req.headers)) {
+        if (v === undefined)
+            continue;
+        const lower = k.toLowerCase();
+        // Strip hop-by-hop + the inbound (token) auth/host — we inject our own.
+        if (lower === "host" ||
+            lower === "authorization" ||
+            lower === "connection" ||
+            lower === "x-api-key") {
+            continue;
+        }
+        headers[k] = v;
+    }
+    headers["host"] = base.host;
+    // Inject the REAL upstream credential. Both header styles cover Anthropic
+    // (`x-api-key`) and OpenAI-compatible (`Authorization: Bearer`) providers.
+    headers["authorization"] = `Bearer ${upstreamKey}`;
+    headers["x-api-key"] = upstreamKey;
+    return {
+        isHttps,
+        options: {
+            protocol: base.protocol,
+            hostname: base.hostname,
+            port: base.port ? Number(base.port) : isHttps ? 443 : 80,
+            method: req.method,
+            path,
+            headers,
+        },
+    };
+}
+function handleRequest(req, res, grants) {
+    const token = extractBearer(req);
+    if (token === null) {
+        sendJson(res, 401, { error: "missing bearer token" });
+        return;
+    }
+    const grant = grants.resolve(token);
+    if (grant === null) {
+        // Wrong/expired token. Do NOT echo the token.
+        sendJson(res, 401, { error: "invalid token" });
+        return;
+    }
+    const pathname = new URL(req.url ?? "/", "http://127.0.0.1").pathname;
+    if (!isAllowedPath(pathname)) {
+        log.warn("broker.path_rejected", {
+            launch_id: grant.launchId,
+            path: pathname,
+        });
+        sendJson(res, 403, { error: "path not allowed" });
+        return;
+    }
+    const { isHttps, options } = buildUpstream(grant.upstreamUrl, grant.upstreamKey, req);
+    const doRequest = isHttps ? httpsRequest : httpRequest;
+    const upstream = doRequest(options, (upstreamRes) => {
+        res.writeHead(upstreamRes.statusCode ?? 502, upstreamRes.headers);
+        // A mid-stream upstream TCP reset emits an `error` on the response body stream.
+        // Without a listener that throws as an unhandled EventEmitter error and CRASHES
+        // the daemon — so handle it: log + tear down the client response cleanly.
+        upstreamRes.on("error", (err) => {
+            log.warn("broker.upstream_stream_error", {
+                launch_id: grant.launchId,
+                error: err.message,
+            });
+            res.destroy();
+        });
+        // STREAM-PIPE the response — never buffer (SSE / long generations must flow).
+        upstreamRes.pipe(res);
+    });
+    upstream.on("error", (err) => {
+        log.warn("broker.upstream_error", {
+            launch_id: grant.launchId,
+            error: err.message,
+        });
+        if (!res.headersSent) {
+            sendJson(res, 502, { error: "upstream unreachable" });
+        }
+        else {
+            res.destroy();
+        }
+    });
+    // Reverse direction: if the client connection errors mid-flight, abort upstream.
+    res.on("error", () => upstream.destroy());
+    // STREAM-PIPE the request body upstream — never buffer.
+    req.pipe(upstream);
+    req.on("error", () => upstream.destroy());
+}
+/**
+ * Start the per-launch broker on an ephemeral 127.0.0.1 port. Resolves once the
+ * listener is bound and the base URL is known.
+ */
+export function startBroker(grants) {
+    return new Promise((resolvePromise, reject) => {
+        const server = createServer((req, res) => {
+            try {
+                handleRequest(req, res, grants);
+            }
+            catch (err) {
+                log.error("broker.handler_crash", { error: err.message });
+                if (!res.headersSent)
+                    sendJson(res, 500, { error: "broker error" });
+            }
+        });
+        server.on("error", reject);
+        // Deadline-bound socket guards so a slow-drip request can't pin a connection
+        // (and block launch teardown) forever.
+        server.requestTimeout = REQUEST_TIMEOUT_MS;
+        server.headersTimeout = HEADERS_TIMEOUT_MS;
+        // 127.0.0.1 only — never expose the broker beyond loopback.
+        server.listen(0, "127.0.0.1", () => {
+            const addr = server.address();
+            if (addr === null || typeof addr === "string") {
+                reject(new Error("broker failed to bind an ephemeral port"));
+                return;
+            }
+            const baseUrl = `http://127.0.0.1:${addr.port}`;
+            let closed = false;
+            const handle = {
+                server,
+                baseUrl,
+                close() {
+                    if (closed)
+                        return Promise.resolve();
+                    closed = true;
+                    return new Promise((resolveClose) => {
+                        server.close(() => resolveClose());
+                        // Drop idle keep-alive sockets AND kill active in-flight connections so
+                        // close() resolves promptly — an agent must not be able to hold teardown
+                        // open with a slow-drip / long-lived streaming connection (Node 18.2+).
+                        server.closeIdleConnections?.();
+                        server.closeAllConnections?.();
+                    });
+                },
+            };
+            resolvePromise(handle);
+        });
+    });
+}
+//# sourceMappingURL=server.js.map

package/dist/broker/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/broker/server.ts"],"names":[],"mappings":"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"}

package/dist/broker/token.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Per-launch capability token (design §5 — C4 security crux).
+ *
+ * The spawned coding-agent CLI runs with full shell access (`bypassPermissions`);
+ * if it held the real LLM key it could exfiltrate it. So the agent is handed only
+ * this opaque per-launch token. The broker (`broker/server.ts`) holds the mapping
+ * token -> real upstream credential; the real key NEVER leaves the daemon process.
+ *
+ * - 32 bytes of CSPRNG entropy, base64url-encoded.
+ * - In-memory, keyed by `launch_id`, fresh per launch.
+ * - NEVER logged.
+ */
+export interface CapabilityGrant {
+    readonly launchId: string;
+    readonly token: string;
+    /** Real upstream model endpoint base (e.g. `https://host/v1`). */
+    readonly upstreamUrl: string;
+    /** Real upstream credential — injected by the broker, never handed to the child. */
+    readonly upstreamKey: string;
+}
+/** Mint a fresh capability token (32-byte CSPRNG, base64url). */
+export declare function mintToken(): string;
+/**
+ * In-memory registry of live capability grants, keyed by token. One grant per
+ * launch; the broker validates an incoming Bearer against this and looks up the
+ * real upstream credential to inject. Cleared on launch teardown.
+ */
+export declare class GrantRegistry {
+    private readonly byToken;
+    create(launchId: string, upstreamUrl: string, upstreamKey: string): CapabilityGrant;
+    /** Resolve a Bearer token to its grant, or null if unknown/expired. */
+    resolve(token: string): CapabilityGrant | null;
+    /** Idempotently drop a grant (teardown). */
+    revoke(token: string): void;
+    get size(): number;
+}

package/dist/broker/token.js

@@ -0,0 +1,48 @@
+/**
+ * Per-launch capability token (design §5 — C4 security crux).
+ *
+ * The spawned coding-agent CLI runs with full shell access (`bypassPermissions`);
+ * if it held the real LLM key it could exfiltrate it. So the agent is handed only
+ * this opaque per-launch token. The broker (`broker/server.ts`) holds the mapping
+ * token -> real upstream credential; the real key NEVER leaves the daemon process.
+ *
+ * - 32 bytes of CSPRNG entropy, base64url-encoded.
+ * - In-memory, keyed by `launch_id`, fresh per launch.
+ * - NEVER logged.
+ */
+import { randomBytes } from "node:crypto";
+const TOKEN_BYTES = 32;
+/** Mint a fresh capability token (32-byte CSPRNG, base64url). */
+export function mintToken() {
+    return randomBytes(TOKEN_BYTES).toString("base64url");
+}
+/**
+ * In-memory registry of live capability grants, keyed by token. One grant per
+ * launch; the broker validates an incoming Bearer against this and looks up the
+ * real upstream credential to inject. Cleared on launch teardown.
+ */
+export class GrantRegistry {
+    byToken = new Map();
+    create(launchId, upstreamUrl, upstreamKey) {
+        const grant = {
+            launchId,
+            token: mintToken(),
+            upstreamUrl,
+            upstreamKey,
+        };
+        this.byToken.set(grant.token, grant);
+        return grant;
+    }
+    /** Resolve a Bearer token to its grant, or null if unknown/expired. */
+    resolve(token) {
+        return this.byToken.get(token) ?? null;
+    }
+    /** Idempotently drop a grant (teardown). */
+    revoke(token) {
+        this.byToken.delete(token);
+    }
+    get size() {
+        return this.byToken.size;
+    }
+}
+//# sourceMappingURL=token.js.map

package/dist/broker/token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.js","sourceRoot":"","sources":["../../src/broker/token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,WAAW,GAAG,EAAE,CAAC;AAWvB,iEAAiE;AACjE,MAAM,UAAU,SAAS;IACvB,OAAO,WAAW,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AACxD,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,aAAa;IACP,OAAO,GAAG,IAAI,GAAG,EAA2B,CAAC;IAE9D,MAAM,CACJ,QAAgB,EAChB,WAAmB,EACnB,WAAmB;QAEnB,MAAM,KAAK,GAAoB;YAC7B,QAAQ;YACR,KAAK,EAAE,SAAS,EAAE;YAClB,WAAW;YACX,WAAW;SACZ,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QACrC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,uEAAuE;IACvE,OAAO,CAAC,KAAa;QACnB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC;IACzC,CAAC;IAED,4CAA4C;IAC5C,MAAM,CAAC,KAAa;QAClB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;CACF"}

package/dist/cli.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `codebot-daemon connect …` command wiring (design §3/§4).
+ *
+ * Parses + validates flags, wires the tunnel to the launch manager, and translates
+ * the terminal tunnel exit into a process exit code:
+ *   - 4401 unauth → exit 1 (dead key — don't hammer).
+ *   - 4409 superseded / `--once` done → exit 0 (clean).
+ *
+ * NEVER logs the api key. SIGINT/SIGTERM tears down all live launches first.
+ */
+export declare const DAEMON_VERSION = "0.1.0";
+/** Entry for the `connect` subcommand. Returns the process exit code. */
+export declare function runConnect(argv: readonly string[]): Promise<number>;
+/** Top-level CLI dispatch. */
+export declare function main(argv: readonly string[]): Promise<number>;