@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/agent-proxy/server.js

@@ -0,0 +1,258 @@
+/**
+ * The runner's local proxy: the one door through which the agent host
+ * reaches anything that needs a credential of the runner's (#2016).
+ *
+ * The host holds no key. Its model clients, its checkpoint saver and its
+ * model-registry reads all call this server on loopback with the host's
+ * token, a random value minted at each host start (`agent-host/
+ * supervisor.ts`); a lane (`lanes.ts`) swaps that token for the runner's
+ * credential and forwards the bytes (`relay.ts`). What a host token buys is
+ * bounded here, and nothing else in the runner serves the host:
+ *
+ *  - Only the current host's token is accepted, in `Authorization: Bearer`
+ *    or `x-api-key` (the two places the host's SDKs put a key), compared in
+ *    constant time.
+ *  - A model call must carry the key of a turn that is live on this runner
+ *    (`X-Stigmer-Turn-Key`), and name that turn's own execution
+ *    (`X-Stigmer-Execution-Id`). The remote adapter mints a key for each
+ *    turn, opens the turn here with it, hands it to the host with the turn,
+ *    and closes the turn when it settles (`agent-host/remote-adapter.ts`);
+ *    the host's clients stamp both headers from the turn's execution context
+ *    (`shared/execution-context.ts`). One host serves every turn of the
+ *    runner with one token, so the key is what keeps a turn to its own
+ *    execution.
+ *  - A checkpoint call must carry a live turn's key and name only that
+ *    turn's own thread (the `threadId` its engine checkpoints under), in
+ *    its query or, for a write, in every entry of its body.
+ *  - The model registry is exempt from the live-turn rule: it is the
+ *    catalog every caller may read, and the platform's proxy serves it even
+ *    to visitors.
+ *  - No lane reaches the Stigmer API beyond the registry: execution reads,
+ *    status writes, credential exchanges stay the runner's own calls.
+ *  - The Cursor SDK's traffic has a listener of its own, TLS on loopback,
+ *    under the same token and live-turn rules (`cursor-lane.ts`).
+ *  - The telemetry lane (`otlp/v1/traces`, `otlp/v1/metrics`) forwards the
+ *    host's OTLP exports to the operator's collector with the collector's
+ *    login (`otlp-forward.ts`). Like the registry it needs no live turn: a
+ *    batch leaves on the span processor's schedule, often after its turn.
+ *
+ * Every refusal is answered in the shape the providers' SDKs parse as an
+ * API error, and logged once with its reason (never a token or a body).
+ *
+ * The residual, stated plainly: while a turn is live, whoever holds the
+ * host's token can make model calls on the runner's account through this
+ * server, as the agent's engine does by design — model calls only, each
+ * lane serving its provider's inference paths and nothing else under its
+ * root (`lanes.ts`). It can no longer take a key away. And at any time it
+ * can send telemetry, which lands in the operator's collector beside the
+ * real spans; it reads nothing back and never reaches the collector's login.
+ */
+import { createServer } from "node:http";
+import { timingSafeEqual } from "node:crypto";
+import { TURN_KEY_HEADER } from "../shared/execution-context.js";
+import { CursorLane } from "./cursor-lane.js";
+import { LaneRefusal, checkpointUpstream, isModelProviderLane, modelUpstream, registryUpstream } from "./lanes.js";
+import { RequestTooLargeError, bearerOf, readBody, relay, replyError } from "./relay.js";
+import { OTLP_LANE_PREFIX } from "../otel-export.js";
+import { OtlpForward, otlpSignalOf } from "./otlp-forward.js";
+const LLM_PREFIX = "/v1/proxy/llm/";
+const CHECKPOINT_PREFIX = "/v1/proxy/checkpoints";
+const REGISTRY_PATH = "/v1/proxy/model-registry";
+export class AgentProxy {
+    server;
+    endpoint;
+    config;
+    hostToken;
+    /** Live turns: each one's execution, the thread it checkpoints under, and its key. */
+    live = new Set();
+    cursor;
+    otlp = new OtlpForward();
+    constructor(server, endpoint, config) {
+        this.server = server;
+        this.endpoint = endpoint;
+        this.config = config;
+    }
+    /** Listen on ephemeral loopback ports and forward with `config`'s credentials, read per request. */
+    static async start(config) {
+        let proxy;
+        const server = createServer((req, res) => {
+            void proxy.handle(req, res);
+        });
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(0, "127.0.0.1", () => resolve());
+        });
+        server.unref();
+        const { port } = server.address();
+        proxy = new AgentProxy(server, `http://127.0.0.1:${port}`, config);
+        const self = proxy;
+        proxy.cursor = await CursorLane.start(config, {
+            isHostToken: (presented) => self.isHostToken(presented),
+            requireLiveExecution: (req) => self.requireLiveExecution(req),
+        });
+        return proxy;
+    }
+    /** The Cursor lane, `https://2130706433:<port>`, 127.0.0.1 written as one number so the Cursor SDK keeps certificate checks on (`agent-proxy/cursor-lane.ts`). */
+    get cursorEndpoint() {
+        return this.cursor.endpoint;
+    }
+    /** The certificate the Cursor lane serves, which the host trusts (PEM). */
+    get cursorCertificate() {
+        return this.cursor.certPem;
+    }
+    authorizeHost(token) {
+        this.hostToken = Buffer.from(token);
+        this.cursor.resetCustody();
+    }
+    openTurn(turn) {
+        const live = { executionId: turn.executionId, threadId: turn.threadId, key: Buffer.from(turn.turnKey) };
+        this.live.add(live);
+        return () => {
+            this.live.delete(live);
+        };
+    }
+    async close() {
+        await Promise.all([
+            this.cursor.close(),
+            this.otlp.close(),
+            new Promise((resolve) => {
+                this.server.closeAllConnections();
+                this.server.close(() => resolve());
+            }),
+        ]);
+    }
+    async handle(req, res) {
+        const url = new URL(req.url ?? "/", "http://agent-proxy");
+        const path = url.pathname;
+        try {
+            if (!this.authenticated(req))
+                throw new LaneRefusal(401, "the agent proxy accepts the current agent host's token only");
+            if (path === REGISTRY_PATH) {
+                if (req.method !== "GET")
+                    throw new LaneRefusal(405, "the model registry is read with GET");
+                await relay(res, registryUpstream(req));
+                return;
+            }
+            if (path.startsWith(OTLP_LANE_PREFIX)) {
+                const signal = otlpSignalOf(path.slice(OTLP_LANE_PREFIX.length));
+                if (signal === undefined)
+                    throw new LaneRefusal(404, `the telemetry lane serves v1/traces and v1/metrics, not ${path}`);
+                await this.otlp.serve(req, res, signal);
+                return;
+            }
+            if (path.startsWith(LLM_PREFIX)) {
+                const [lane = "", ...segments] = path.slice(LLM_PREFIX.length).split("/");
+                if (!isModelProviderLane(lane))
+                    throw new LaneRefusal(404, `no model lane '${lane}'`);
+                this.requireLiveExecution(req);
+                const body = await readBody(req);
+                const rest = `/${segments.join("/")}${url.search}`;
+                await relay(res, await modelUpstream(this.config, lane, rest, req, body));
+                return;
+            }
+            if (path === CHECKPOINT_PREFIX || path.startsWith(`${CHECKPOINT_PREFIX}/`)) {
+                const body = await readBody(req);
+                this.requireLiveThreads(req, url, body, req.method === "PUT" && path === `${CHECKPOINT_PREFIX}/writes`);
+                await relay(res, checkpointUpstream(this.config, `${path.slice(CHECKPOINT_PREFIX.length)}${url.search}`, req, body));
+                return;
+            }
+            throw new LaneRefusal(404, `the agent proxy serves no lane at ${path}`);
+        }
+        catch (err) {
+            const refusal = err instanceof LaneRefusal ? err
+                : err instanceof RequestTooLargeError ? new LaneRefusal(413, err.message)
+                    : new LaneRefusal(502, err instanceof Error ? err.message : String(err));
+            console.warn(`[agent-proxy] refused ${req.method ?? "?"} ${path}: ${refusal.status} ${refusal.message}`);
+            replyError(res, refusal.status, refusal.message);
+        }
+    }
+    authenticated(req) {
+        return this.isHostToken(bearerOf(req.headers.authorization) ?? headerValue(req.headers["x-api-key"]));
+    }
+    isHostToken(presented) {
+        const expected = this.hostToken;
+        if (!expected)
+            return false;
+        if (presented === undefined)
+            return false;
+        const candidate = Buffer.from(presented);
+        return candidate.length === expected.length && timingSafeEqual(candidate, expected);
+    }
+    /** The live turn whose key the request carries, compared in constant time. */
+    liveTurnOf(req) {
+        const presented = headerValue(req.headers[TURN_KEY_HEADER]);
+        if (!presented)
+            throw new LaneRefusal(403, "a call must carry its turn's key (X-Stigmer-Turn-Key)");
+        const candidate = Buffer.from(presented);
+        for (const turn of this.live) {
+            if (candidate.length === turn.key.length && timingSafeEqual(candidate, turn.key))
+                return turn;
+        }
+        throw new LaneRefusal(403, "the turn key names no turn running on this runner");
+    }
+    requireLiveExecution(req) {
+        const turn = this.liveTurnOf(req);
+        const executionId = headerValue(req.headers["x-stigmer-execution-id"]);
+        if (!executionId)
+            throw new LaneRefusal(403, "a model call must name its execution (X-Stigmer-Execution-Id)");
+        if (executionId !== turn.executionId)
+            throw new LaneRefusal(403, `the turn key is not execution ${executionId}'s`);
+    }
+    /** Every thread a checkpoint call names must be its turn's own. */
+    requireLiveThreads(req, url, body, isWriteBatch) {
+        const turn = this.liveTurnOf(req);
+        const threads = new Set();
+        const queried = url.searchParams.get("thread_id");
+        if (queried !== null)
+            threads.add(queried);
+        for (const thread of threadsInBody(body))
+            threads.add(thread);
+        // An empty write batch names no thread and writes nothing: LangGraph sends
+        // one for a task whose writes all go to untracked channels, and the
+        // platform answers it as a no-op.
+        if (threads.size === 0 && isWriteBatch && isEmptyWriteBatch(body))
+            return;
+        if (threads.size === 0)
+            throw new LaneRefusal(403, "a checkpoint call must name its thread");
+        for (const thread of threads) {
+            if (thread !== turn.threadId)
+                throw new LaneRefusal(403, `thread ${thread} is not the turn's own`);
+        }
+    }
+}
+/** A body that is exactly a write batch with no writes. */
+function isEmptyWriteBatch(body) {
+    if (body.length === 0)
+        return false;
+    const parsed = JSON.parse(body.toString("utf8"));
+    return typeof parsed === "object" && parsed !== null && Array.isArray(parsed.writes) && parsed.writes.length === 0;
+}
+/** The `thread_id`s a checkpoint write names: the checkpoint's own, or each write entry's. */
+function threadsInBody(body) {
+    if (body.length === 0)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(body.toString("utf8"));
+    }
+    catch {
+        throw new LaneRefusal(400, "a checkpoint write must be JSON");
+    }
+    const threads = [];
+    const collect = (value) => {
+        if (typeof value === "object" && value !== null && "thread_id" in value) {
+            const thread = value.thread_id;
+            threads.push(typeof thread === "string" ? thread : "");
+        }
+    };
+    collect(parsed);
+    const writes = typeof parsed === "object" && parsed !== null ? parsed.writes : undefined;
+    if (Array.isArray(writes))
+        for (const write of writes)
+            collect(write);
+    return threads;
+}
+function headerValue(value) {
+    return Array.isArray(value) ? value[0] : value;
+}
+//# sourceMappingURL=server.js.map

package/dist/agent-proxy/server.js.map

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

package/dist/attach/entry.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The attach entry's logic, kept apart from `main.ts` (the process boundary)
+ * so it is tested: the configuration read from the sandbox's environment, the
+ * waiter it starts (`waiter.ts`), and how a signal stops it.
+ *
+ * Configuration:
+ *
+ *   - `STIGMER_ATTACH_PORT`: the listener's port, 80 by default, the port a
+ *     Substrate router reaches without a `CONNECT` tunnel.
+ *   - `STIGMER_SANDBOX_NAME_FILE`: the file holding this sandbox's name, read
+ *     on every push because a clone has its own; `/run/ate/actor-name` by
+ *     default, where a template's actor-metadata volume projects it.
+ *
+ * The runner it starts is the package's own entry, `../main.js` beside this
+ * module, run by the same Node. Every other variable is passed to the runner
+ * unchanged; these two are not (`WAITER_ENV_KEYS`).
+ */
+import { type AttachWaiter, type AttachWaiterOptions } from "./waiter.js";
+export interface AttachEntryConfig {
+    readonly port: number;
+    readonly sandboxNameFile: string;
+    readonly runnerEntry: string;
+}
+/** The entry's configuration from the sandbox's environment. Throws on an unusable port. */
+export declare function attachEntryConfig(env: NodeJS.ProcessEnv): AttachEntryConfig;
+/** What the entry needs from its process; `main.ts` passes the real ones. */
+export interface AttachEntryHost {
+    onSignal(signal: "SIGTERM" | "SIGINT", handler: () => void): void;
+    exit(code: number): void;
+    log(message: string): void;
+}
+/**
+ * Start the waiter for this sandbox and stop it on SIGTERM or SIGINT: the
+ * runner first, waiting for its graceful shutdown, then the process.
+ */
+export declare function runAttachEntry(env: NodeJS.ProcessEnv, host: AttachEntryHost, start?: (options: AttachWaiterOptions) => Promise<AttachWaiter>): Promise<AttachWaiter>;

package/dist/attach/entry.js

@@ -0,0 +1,69 @@
+/**
+ * The attach entry's logic, kept apart from `main.ts` (the process boundary)
+ * so it is tested: the configuration read from the sandbox's environment, the
+ * waiter it starts (`waiter.ts`), and how a signal stops it.
+ *
+ * Configuration:
+ *
+ *   - `STIGMER_ATTACH_PORT`: the listener's port, 80 by default, the port a
+ *     Substrate router reaches without a `CONNECT` tunnel.
+ *   - `STIGMER_SANDBOX_NAME_FILE`: the file holding this sandbox's name, read
+ *     on every push because a clone has its own; `/run/ate/actor-name` by
+ *     default, where a template's actor-metadata volume projects it.
+ *
+ * The runner it starts is the package's own entry, `../main.js` beside this
+ * module, run by the same Node. Every other variable is passed to the runner
+ * unchanged; these two are not (`WAITER_ENV_KEYS`).
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { startAttachWaiter } from "./waiter.js";
+const DEFAULT_PORT = 80;
+const DEFAULT_SANDBOX_NAME_FILE = "/run/ate/actor-name";
+/** The entry's configuration from the sandbox's environment. Throws on an unusable port. */
+export function attachEntryConfig(env) {
+    const rawPort = env.STIGMER_ATTACH_PORT;
+    let port = DEFAULT_PORT;
+    if (rawPort !== undefined && rawPort !== "") {
+        port = Number(rawPort);
+        if (!Number.isInteger(port) || port < 1 || port > 65535) {
+            throw new Error(`STIGMER_ATTACH_PORT must be a port number; got ${rawPort}`);
+        }
+    }
+    return {
+        port,
+        sandboxNameFile: env.STIGMER_SANDBOX_NAME_FILE || DEFAULT_SANDBOX_NAME_FILE,
+        runnerEntry: join(dirname(fileURLToPath(import.meta.url)), "..", "main.js"),
+    };
+}
+/**
+ * Start the waiter for this sandbox and stop it on SIGTERM or SIGINT: the
+ * runner first, waiting for its graceful shutdown, then the process.
+ */
+export async function runAttachEntry(env, host, start = startAttachWaiter) {
+    const config = attachEntryConfig(env);
+    const waiter = await start({
+        port: config.port,
+        readSandboxName: () => readFileSync(config.sandboxNameFile, "utf8").trim(),
+        runnerEntry: config.runnerEntry,
+        baseEnv: env,
+        log: host.log,
+    });
+    host.log(`[attach] waiting for a push on port ${waiter.port}`);
+    let stopping = false;
+    const stop = (signal) => {
+        if (stopping)
+            return;
+        stopping = true;
+        host.log(`[attach] received ${signal}; stopping the runner`);
+        waiter.close().then(() => host.exit(0), (err) => {
+            host.log(`[attach] stop failed: ${err instanceof Error ? err.message : String(err)}`);
+            host.exit(1);
+        });
+    };
+    host.onSignal("SIGTERM", () => stop("SIGTERM"));
+    host.onSignal("SIGINT", () => stop("SIGINT"));
+    return waiter;
+}
+//# sourceMappingURL=entry.js.map

package/dist/attach/entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.js","sourceRoot":"","sources":["../../src/attach/entry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAA+C,MAAM,aAAa,CAAC;AAE7F,MAAM,YAAY,GAAG,EAAE,CAAC;AACxB,MAAM,yBAAyB,GAAG,qBAAqB,CAAC;AAQxD,4FAA4F;AAC5F,MAAM,UAAU,iBAAiB,CAAC,GAAsB;IACtD,MAAM,OAAO,GAAG,GAAG,CAAC,mBAAmB,CAAC;IACxC,IAAI,IAAI,GAAG,YAAY,CAAC;IACxB,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QAC5C,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;QACvB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;YACxD,MAAM,IAAI,KAAK,CAAC,kDAAkD,OAAO,EAAE,CAAC,CAAC;QAC/E,CAAC;IACH,CAAC;IACD,OAAO;QACL,IAAI;QACJ,eAAe,EAAE,GAAG,CAAC,yBAAyB,IAAI,yBAAyB;QAC3E,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC;KAC5E,CAAC;AACJ,CAAC;AASD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,GAAsB,EACtB,IAAqB,EACrB,QAAiE,iBAAiB;IAElF,MAAM,MAAM,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACtC,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC;QACzB,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,eAAe,EAAE,GAAG,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE;QAC1E,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,OAAO,EAAE,GAAG;QACZ,GAAG,EAAE,IAAI,CAAC,GAAG;KACd,CAAC,CAAC;IACH,IAAI,CAAC,GAAG,CAAC,uCAAuC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IAE/D,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,MAAM,IAAI,GAAG,CAAC,MAAc,EAAE,EAAE;QAC9B,IAAI,QAAQ;YAAE,OAAO;QACrB,QAAQ,GAAG,IAAI,CAAC;QAChB,IAAI,CAAC,GAAG,CAAC,qBAAqB,MAAM,uBAAuB,CAAC,CAAC;QAC7D,MAAM,CAAC,KAAK,EAAE,CAAC,IAAI,CACjB,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAClB,CAAC,GAAY,EAAE,EAAE;YACf,IAAI,CAAC,GAAG,CAAC,yBAAyB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACtF,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACf,CAAC,CACF,CAAC;IACJ,CAAC,CAAC;IACF,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;IAChD,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC9C,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/attach/main.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Entry point of a sandbox that waits to be attached: `node <dist>/attach/main.js`.
+ *
+ * It starts the attach waiter and nothing else; `waiter.ts` says why a
+ * sandbox snapshot holds a waiter and never a runner, and `entry.ts` holds
+ * the configuration and the signal handling. It loads none of the runner's
+ * machinery, only Node built-ins, two leaf modules (the secret-name list and
+ * the claim reader) and the codecs' dependency-free `connection` subpath
+ * (`__tests__/import-graph.test.ts` pins the graph), so
+ * the snapshot holds a small idle process. This file is only the
+ * process boundary; `scripts/verify-attach-boot.mjs` boots it under plain
+ * Node.
+ */
+export {};

package/dist/attach/main.js

@@ -0,0 +1,25 @@
+/**
+ * Entry point of a sandbox that waits to be attached: `node <dist>/attach/main.js`.
+ *
+ * It starts the attach waiter and nothing else; `waiter.ts` says why a
+ * sandbox snapshot holds a waiter and never a runner, and `entry.ts` holds
+ * the configuration and the signal handling. It loads none of the runner's
+ * machinery, only Node built-ins, two leaf modules (the secret-name list and
+ * the claim reader) and the codecs' dependency-free `connection` subpath
+ * (`__tests__/import-graph.test.ts` pins the graph), so
+ * the snapshot holds a small idle process. This file is only the
+ * process boundary; `scripts/verify-attach-boot.mjs` boots it under plain
+ * Node.
+ */
+import { runAttachEntry } from "./entry.js";
+/* v8 ignore start -- @preserve: the process boundary; its logic is entry.ts (tested) and scripts/verify-attach-boot.mjs boots this file under plain Node */
+runAttachEntry(process.env, {
+    onSignal: (signal, handler) => process.on(signal, handler),
+    exit: (code) => process.exit(code),
+    log: (message) => console.warn(message),
+}).catch((err) => {
+    console.error("[attach] fatal:", err);
+    process.exit(1);
+});
+/* v8 ignore stop */
+//# sourceMappingURL=main.js.map

package/dist/attach/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/attach/main.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,4JAA4J;AAC5J,cAAc,CAAC,OAAO,CAAC,GAAG,EAAE;IAC1B,QAAQ,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC;IAC1D,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;IAClC,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC;CACxC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IACxB,OAAO,CAAC,KAAK,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC;IACtC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC;AACH,oBAAoB"}

package/dist/attach/push.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The attach push: what a sandbox driver sends a waiting sandbox to make it
+ * serve one task queue, and the checks a push passes before the waiter starts
+ * a runner for it.
+ *
+ * A push carries the per-sandbox half of what a sandbox pod receives at
+ * start: the queue it serves (`STIGMER_TASK_QUEUE`) and the runner's secret
+ * values (`RUNNER_SECRET_ENV_KEYS`). Everything per-target and non-secret
+ * belongs in the sandbox's own environment instead, including the Temporal
+ * connection settings a pod's Secret also carries but that are not secrets
+ * (the server's CA, a client certificate, the server name); and nothing
+ * secret may be there: a snapshot of a waiting sandbox is cloned into every
+ * sandbox started from it, so it must hold no credential (the waiter's
+ * module header, `waiter.ts`).
+ *
+ * The checks, in order:
+ *
+ *   1. Shape. A JSON object with a string `taskQueue` and a `secrets` object
+ *      of strings whose names are all in `RUNNER_SECRET_ENV_KEYS`: the push
+ *      cannot set any other environment variable of the runner.
+ *   2. Binding. The queue names one scope and one id (`session:`,
+ *      `mcpconnect:`), and the sandbox serving it must be the one the server
+ *      names for that scope and id: `sbx-<code>-<first 12 hex of sha256(id)>`,
+ *      byte-identical to the server's `sandboxBaseName`
+ *      (`stigmer-server/src/sandbox/naming.ts`, the one home of the
+ *      derivation; this package's test loads that module and compares the two,
+ *      since the runner imports nothing from the server). A queue pushed to another sandbox is refused,
+ *      so one session's work never runs on another session's workspace. The
+ *      binding reads no token, so it holds on every edition, including one
+ *      whose tokens name an execution rather than a session, or that runs
+ *      tokenless.
+ *   3. Token. A non-empty `STIGMER_TOKEN` must be JWT-shaped and, when it
+ *      carries `exp`, unexpired. The runner never verifies signatures (the
+ *      server does, `client/token-claims.ts`); whoever can reach the waiter
+ *      is the sandbox's driver, which is the deployment's to keep true.
+ *
+ * Status codes: 400 for a malformed push (a NUL byte in any value included:
+ * no process can receive it), 403 for one that fails the binding
+ * or carries an unusable token. Every refusal also carries a stable `code`
+ * (`malformed`, `binding`, `token_unusable`; the waiter adds its own), which
+ * a driver acts on; the reason's wording is for people and may change.
+ */
+/** A push that passed every check. */
+export interface AttachPush {
+    readonly taskQueue: string;
+    readonly secrets: Readonly<Record<string, string>>;
+}
+/**
+ * The stable code of every way a push can be refused, by this module or by
+ * the waiter (`waiter.ts`).
+ */
+export type PushRefusalCode = "malformed" | "binding" | "token_unusable" | "too_large" | "method_not_allowed" | "other_queue" | "secrets_changed" | "token_mismatch" | "runner_start_failed" | "unreadable";
+export type PushVerdict = {
+    readonly ok: true;
+    readonly push: AttachPush;
+} | {
+    readonly ok: false;
+    readonly status: 400 | 403;
+    readonly code: PushRefusalCode;
+    readonly reason: string;
+};
+/**
+ * The name of the only sandbox allowed to serve a queue, or undefined when the
+ * queue is not one a sandbox serves.
+ */
+export declare function sandboxNameForQueue(taskQueue: string): string | undefined;
+/**
+ * Check a parsed push body against this sandbox's own name and the current
+ * time (seconds since the epoch).
+ */
+export declare function verifyAttachPush(body: unknown, sandboxName: string, nowSeconds: number): PushVerdict;

package/dist/attach/push.js

@@ -0,0 +1,123 @@
+/**
+ * The attach push: what a sandbox driver sends a waiting sandbox to make it
+ * serve one task queue, and the checks a push passes before the waiter starts
+ * a runner for it.
+ *
+ * A push carries the per-sandbox half of what a sandbox pod receives at
+ * start: the queue it serves (`STIGMER_TASK_QUEUE`) and the runner's secret
+ * values (`RUNNER_SECRET_ENV_KEYS`). Everything per-target and non-secret
+ * belongs in the sandbox's own environment instead, including the Temporal
+ * connection settings a pod's Secret also carries but that are not secrets
+ * (the server's CA, a client certificate, the server name); and nothing
+ * secret may be there: a snapshot of a waiting sandbox is cloned into every
+ * sandbox started from it, so it must hold no credential (the waiter's
+ * module header, `waiter.ts`).
+ *
+ * The checks, in order:
+ *
+ *   1. Shape. A JSON object with a string `taskQueue` and a `secrets` object
+ *      of strings whose names are all in `RUNNER_SECRET_ENV_KEYS`: the push
+ *      cannot set any other environment variable of the runner.
+ *   2. Binding. The queue names one scope and one id (`session:`,
+ *      `mcpconnect:`), and the sandbox serving it must be the one the server
+ *      names for that scope and id: `sbx-<code>-<first 12 hex of sha256(id)>`,
+ *      byte-identical to the server's `sandboxBaseName`
+ *      (`stigmer-server/src/sandbox/naming.ts`, the one home of the
+ *      derivation; this package's test loads that module and compares the two,
+ *      since the runner imports nothing from the server). A queue pushed to another sandbox is refused,
+ *      so one session's work never runs on another session's workspace. The
+ *      binding reads no token, so it holds on every edition, including one
+ *      whose tokens name an execution rather than a session, or that runs
+ *      tokenless.
+ *   3. Token. A non-empty `STIGMER_TOKEN` must be JWT-shaped and, when it
+ *      carries `exp`, unexpired. The runner never verifies signatures (the
+ *      server does, `client/token-claims.ts`); whoever can reach the waiter
+ *      is the sandbox's driver, which is the deployment's to keep true.
+ *
+ * Status codes: 400 for a malformed push (a NUL byte in any value included:
+ * no process can receive it), 403 for one that fails the binding
+ * or carries an unusable token. Every refusal also carries a stable `code`
+ * (`malformed`, `binding`, `token_unusable`; the waiter adds its own), which
+ * a driver acts on; the reason's wording is for people and may change.
+ */
+import { createHash } from "node:crypto";
+import { RUNNER_SECRET_ENV_KEYS } from "../shared/runner-credential-keys.js";
+import { expiryClaimOf, isJwtShaped } from "../client/token-claims.js";
+/** The queue kinds a sandbox serves, with the server's scope codes for each. */
+const QUEUE_KINDS = [
+    { prefix: "session:", code: "ses" },
+    { prefix: "mcpconnect:", code: "mcp" },
+];
+const SECRET_NAMES = new Set(RUNNER_SECRET_ENV_KEYS);
+/**
+ * The name of the only sandbox allowed to serve a queue, or undefined when the
+ * queue is not one a sandbox serves.
+ */
+export function sandboxNameForQueue(taskQueue) {
+    for (const kind of QUEUE_KINDS) {
+        if (taskQueue.startsWith(kind.prefix)) {
+            const id = taskQueue.slice(kind.prefix.length);
+            if (id === "")
+                return undefined;
+            const digest = createHash("sha256").update(id).digest("hex").slice(0, 12);
+            return `sbx-${kind.code}-${digest}`;
+        }
+    }
+    return undefined;
+}
+function refuse(status, code, reason) {
+    return { ok: false, status, code, reason };
+}
+/**
+ * Check a parsed push body against this sandbox's own name and the current
+ * time (seconds since the epoch).
+ */
+export function verifyAttachPush(body, sandboxName, nowSeconds) {
+    if (typeof body !== "object" || body === null || Array.isArray(body)) {
+        return refuse(400, "malformed", "the push must be a JSON object");
+    }
+    const { taskQueue, secrets } = body;
+    if (typeof taskQueue !== "string" || taskQueue === "") {
+        return refuse(400, "malformed", "taskQueue must be a non-empty string");
+    }
+    // An environment value holding a NUL byte cannot reach a process (Node
+    // refuses it at spawn), so it is refused here rather than at the start.
+    if (taskQueue.includes("\u0000")) {
+        return refuse(400, "malformed", "taskQueue holds a NUL byte");
+    }
+    if (typeof secrets !== "object" || secrets === null || Array.isArray(secrets)) {
+        return refuse(400, "malformed", "secrets must be an object of strings");
+    }
+    const accepted = {};
+    for (const [name, value] of Object.entries(secrets)) {
+        if (!SECRET_NAMES.has(name)) {
+            return refuse(400, "malformed", `secrets may only name the runner's secret variables; got ${name}`);
+        }
+        if (typeof value !== "string") {
+            return refuse(400, "malformed", `secret ${name} must be a string`);
+        }
+        if (value.includes("\u0000")) {
+            return refuse(400, "malformed", `secret ${name} holds a NUL byte`);
+        }
+        accepted[name] = value;
+    }
+    const expected = sandboxNameForQueue(taskQueue);
+    if (expected === undefined) {
+        return refuse(403, "binding", `${taskQueue} is not a queue a sandbox serves`);
+    }
+    if (expected !== sandboxName) {
+        return refuse(403, "binding", `this sandbox does not serve ${taskQueue}`);
+    }
+    const token = accepted.STIGMER_TOKEN ?? "";
+    if (token !== "") {
+        if (!isJwtShaped(token)) {
+            return refuse(403, "token_unusable", "STIGMER_TOKEN is not a JWT");
+        }
+        const expiry = expiryClaimOf(token);
+        if (expiry !== undefined && expiry <= nowSeconds) {
+            return refuse(403, "token_unusable", "STIGMER_TOKEN has expired");
+        }
+    }
+    return { ok: true, push: { taskQueue, secrets: accepted } };
+}
+//# sourceMappingURL=push.js.map

package/dist/attach/push.js.map

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