approval-md 0.2.0 → 0.3.0

package/dist/src/codex/runner.d.ts

@@ -0,0 +1,178 @@
+/**
+ * The confined Codex session runner (APRV-325.3).
+ *
+ * APRV-325.2 made the canonical workspace writable through one door. That is
+ * worth nothing on its own: a door beside an open window is decoration. This
+ * module is the window being closed — the shell a Codex session runs gets a
+ * DISPOSABLE workspace of its own, no write authority over the canonical one,
+ * no write authority over the gate, no ambient credentials, no egress, and no
+ * way to ask for any of it back.
+ *
+ * ## Five removals, and where each is enforced
+ *
+ * | what the shell does not get | enforced by |
+ * |---|---|
+ * | canonical workspace writes | Seatbelt `(deny file-write*)` with an allow-list that names only the disposable workspace |
+ * | gate writes (log, policy, vault, keys) | the same deny; the gate home is not on the allow-list |
+ * | reads of anything but the two workspaces | Seatbelt `(deny file-read*)` with an allow-list of two roots (APRV-347's read jail) |
+ * | ambient credentials | `core/child-env.ts`, then {@link CONFINED_ENV_ALLOW} |
+ * | credential material on disk | Seatbelt `denyRead` over the vault, the env map and the sealing keys, emitted after the jail's allows so it is the last word |
+ * | external egress | Seatbelt `(deny network-outbound)`, loopback included |
+ * | mutable executor code | the broker, the CLI and the pinned Node live under the root-owned install root, which is on neither allow-list |
+ *
+ * ## No opt-out, and no raw fallback
+ *
+ * `approval run` has `--no-sandbox`, because an operator holding a human's grant
+ * may deliberately reach the world. A confined session has no such flag and no
+ * such path: {@link planConfinedSession} REFUSES when the host cannot apply a
+ * profile, where `core/sandbox.ts`'s ordinary posture table would record
+ * `unsupported` and proceed. That difference is the whole point — an
+ * unsupported host that ran the shell anyway would be a session advertised as
+ * confined and not confined, which is worse than no session at all.
+ * `APPROVAL_SANDBOX_FORCE_UNAVAILABLE` and `APPROVAL_SANDBOX_REQUIRED` still
+ * only tighten, so neither is a way in.
+ *
+ * ## What it does not claim
+ *
+ * This confines a CHILD PROCESS on macOS. It is not isolation and it is not a
+ * claim about the Codex desktop application, which runs outside anything this
+ * runtime spawns; `docs/codex-boundary-probe.md` holds what was measured there.
+ * Inbound sockets are not denied (`core/sandbox.ts`'s stated limit), and a
+ * confined child can still write inside its own disposable workspace, which is
+ * the point of giving it one.
+ */
+import { type DetectOptions, type SandboxMechanism } from "../core/sandbox.js";
+import type { BrokerInstallation } from "./broker.js";
+export declare const CONFINED_SESSION_VERSION: "approval.codex.confined-session.v1";
+/**
+ * The ONLY environment variables a confined session passes through.
+ *
+ * An ALLOW-list, and for the reason the write rules are one. `core/child-env.ts`
+ * strips a named family (`APPROVAL_`, `TELEGRAM_`, `VAULT_`, `AGENTMAIL_`) and
+ * that is right for `approval run`, which runs a command a human approved and
+ * whose environment is the operator's own. It is not enough here: a Codex
+ * session's host carries `OPENAI_API_KEY`, `GITHUB_TOKEN`, `AWS_SECRET_ACCESS_KEY`,
+ * an `SSH_AUTH_SOCK` and whatever else the operator's shell exports, and none of
+ * those is under a prefix this runtime knows. A deny-list would have to keep up
+ * with every provider anyone ever adds; this names the handful a shell needs to
+ * function, so a credential nobody thought of is absent rather than forgotten.
+ *
+ * `core/child-env.ts` still runs FIRST, so its credential-bearing count is
+ * reported on the same terms as everywhere else in the runtime. This list then
+ * narrows what survives; it can only ever remove more.
+ *
+ * This is a control over NAMES and therefore best-effort by construction: a
+ * credential exported under a name on this list still passes. The load-bearing
+ * control beside it is that egress is denied, so a secret that does reach the
+ * child has nowhere to go.
+ */
+export declare const CONFINED_ENV_ALLOW: readonly string[];
+/** How long a confined command may run before it is killed. */
+export declare const DEFAULT_CONFINED_TIMEOUT_MS = 120000;
+/**
+ * Why a confined session could not be prepared or run. Frozen, distinct, and
+ * pinned by `tests/codex-confine.test.ts` (SPEC.md §11.1 invariant 6).
+ */
+export declare const CONFINE_REFUSAL_CODES: readonly [
+/** This host has no sandbox mechanism in this build. A confined session refuses. */
+"sandbox-unsupported", 
+/** The mechanism exists and did not work. */
+"sandbox-unavailable", 
+/** The disposable workspace could not be created. */
+"workspace-unavailable", 
+/** The command could not be resolved, so it was never wrapped. */
+"command-unresolvable", 
+/** The command was killed at the deadline. No canonical effect is possible. */
+"timeout"];
+export type ConfineRefusalCode = (typeof CONFINE_REFUSAL_CODES)[number];
+export interface ConfineRefusal {
+    ok: false;
+    code: ConfineRefusalCode;
+    message: string;
+}
+export interface ConfinedSession {
+    version: typeof CONFINED_SESSION_VERSION;
+    /** The scratch tree the shell may write. Removed by {@link ConfinedSession.dispose}. */
+    workspace: string;
+    /** The canonical workspace: readable, never writable from inside. */
+    canonical: string;
+    mechanism: SandboxMechanism;
+    /** Absolute subtrees the profile allows writes to. */
+    writeAllow: readonly string[];
+    /**
+     * Absolute directories the profile allows reads of (APRV-347's read jail),
+     * with everything else denied.
+     *
+     * Two roots, and no more: the disposable workspace, and the canonical
+     * workspace. A session has to READ the tree it is reasoning about, which is
+     * why the canonical workspace is here and why write confinement rather than
+     * read denial is what stops it changing one. Everything the operator's home
+     * holds beside it — other repositories, other credentials, `~/.ssh`, the gate
+     * home — is outside the jail and unreadable, which is the half `denyRead`
+     * alone could never cover, because a deny-list has to have heard of a path to
+     * deny it.
+     *
+     * `core/sandbox.ts` adds the fixed runtime set and the executable's own
+     * install prefix itself, so nothing here has to name a toolchain.
+     */
+    readAllow: readonly string[];
+    /** Absolute paths the profile denies reads of, inside the jail or out. */
+    denyRead: readonly string[];
+    /** The child's environment: {@link CONFINED_ENV_ALLOW} and the session's own. */
+    env: Record<string, string>;
+    /**
+     * How many credential-bearing variables `core/child-env.ts` withheld. A
+     * COUNT, never a name: a name is half of a credential, and SPEC.md §11.1's
+     * raw-secrets invariant is not satisfied by leaking the other half slowly.
+     */
+    envStripped: number;
+    /** How many source variables did not survive the allow-list, in total. */
+    envWithheld: number;
+    /** Remove the disposable workspace. Idempotent, never throws. */
+    dispose: () => void;
+}
+export interface ConfineOptions {
+    /** Forwarded to `core/sandbox.ts`'s probe. Tests inject a platform here. */
+    detect?: DetectOptions;
+    /** The environment to derive the child's from. Defaults to this process's. */
+    source?: NodeJS.ProcessEnv;
+    /** Where the disposable workspace is created. Defaults to `os.tmpdir()`. */
+    scratchRoot?: string;
+}
+export type ConfinedSessionResult = {
+    ok: true;
+    session: ConfinedSession;
+} | ConfineRefusal;
+/**
+ * Prepare one confined session, or refuse.
+ *
+ * The refusal on an unsupported host is deliberate and is the one place this
+ * module is STRICTER than `core/sandbox.ts`'s posture table. See the header.
+ */
+export declare function planConfinedSession(installation: BrokerInstallation, options?: ConfineOptions): ConfinedSessionResult;
+export interface ConfinedRun {
+    ok: true;
+    /** The child's own exit code, or `128 + signal` when a signal killed it. */
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    /** True when the deadline killed it. The exit code is then the signal's. */
+    timedOut: boolean;
+}
+export type ConfinedRunResult = ConfinedRun | ConfineRefusal;
+export interface ConfinedRunOptions {
+    timeoutMs?: number;
+    /** Working directory for the child. Defaults to the disposable workspace. */
+    cwd?: string;
+    maxBuffer?: number;
+}
+/**
+ * Run one command inside a prepared session.
+ *
+ * The command is resolved BEFORE it is wrapped, for `core/sandbox.ts`'s reason:
+ * an `execvp` failure inside `sandbox-exec` exits 71, and 71 recorded as the
+ * child's exit code is a lie about a command that never ran. Here it is a
+ * refusal instead of an unwrapped spawn, because an unwrapped spawn is exactly
+ * the raw fallback this session must not have.
+ */
+export declare function runConfined(session: ConfinedSession, command: string, args: readonly string[], options?: ConfinedRunOptions): ConfinedRunResult;

package/dist/src/codex/runner.js

@@ -0,0 +1,231 @@
+/**
+ * The confined Codex session runner (APRV-325.3).
+ *
+ * APRV-325.2 made the canonical workspace writable through one door. That is
+ * worth nothing on its own: a door beside an open window is decoration. This
+ * module is the window being closed — the shell a Codex session runs gets a
+ * DISPOSABLE workspace of its own, no write authority over the canonical one,
+ * no write authority over the gate, no ambient credentials, no egress, and no
+ * way to ask for any of it back.
+ *
+ * ## Five removals, and where each is enforced
+ *
+ * | what the shell does not get | enforced by |
+ * |---|---|
+ * | canonical workspace writes | Seatbelt `(deny file-write*)` with an allow-list that names only the disposable workspace |
+ * | gate writes (log, policy, vault, keys) | the same deny; the gate home is not on the allow-list |
+ * | reads of anything but the two workspaces | Seatbelt `(deny file-read*)` with an allow-list of two roots (APRV-347's read jail) |
+ * | ambient credentials | `core/child-env.ts`, then {@link CONFINED_ENV_ALLOW} |
+ * | credential material on disk | Seatbelt `denyRead` over the vault, the env map and the sealing keys, emitted after the jail's allows so it is the last word |
+ * | external egress | Seatbelt `(deny network-outbound)`, loopback included |
+ * | mutable executor code | the broker, the CLI and the pinned Node live under the root-owned install root, which is on neither allow-list |
+ *
+ * ## No opt-out, and no raw fallback
+ *
+ * `approval run` has `--no-sandbox`, because an operator holding a human's grant
+ * may deliberately reach the world. A confined session has no such flag and no
+ * such path: {@link planConfinedSession} REFUSES when the host cannot apply a
+ * profile, where `core/sandbox.ts`'s ordinary posture table would record
+ * `unsupported` and proceed. That difference is the whole point — an
+ * unsupported host that ran the shell anyway would be a session advertised as
+ * confined and not confined, which is worse than no session at all.
+ * `APPROVAL_SANDBOX_FORCE_UNAVAILABLE` and `APPROVAL_SANDBOX_REQUIRED` still
+ * only tighten, so neither is a way in.
+ *
+ * ## What it does not claim
+ *
+ * This confines a CHILD PROCESS on macOS. It is not isolation and it is not a
+ * claim about the Codex desktop application, which runs outside anything this
+ * runtime spawns; `docs/codex-boundary-probe.md` holds what was measured there.
+ * Inbound sockets are not denied (`core/sandbox.ts`'s stated limit), and a
+ * confined child can still write inside its own disposable workspace, which is
+ * the point of giving it one.
+ */
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { childEnvironment } from "../core/child-env.js";
+import { credentialPathsFor, detectSandbox, resolveExecutable, wrapForSandbox, } from "../core/sandbox.js";
+export const CONFINED_SESSION_VERSION = "approval.codex.confined-session.v1";
+/**
+ * The ONLY environment variables a confined session passes through.
+ *
+ * An ALLOW-list, and for the reason the write rules are one. `core/child-env.ts`
+ * strips a named family (`APPROVAL_`, `TELEGRAM_`, `VAULT_`, `AGENTMAIL_`) and
+ * that is right for `approval run`, which runs a command a human approved and
+ * whose environment is the operator's own. It is not enough here: a Codex
+ * session's host carries `OPENAI_API_KEY`, `GITHUB_TOKEN`, `AWS_SECRET_ACCESS_KEY`,
+ * an `SSH_AUTH_SOCK` and whatever else the operator's shell exports, and none of
+ * those is under a prefix this runtime knows. A deny-list would have to keep up
+ * with every provider anyone ever adds; this names the handful a shell needs to
+ * function, so a credential nobody thought of is absent rather than forgotten.
+ *
+ * `core/child-env.ts` still runs FIRST, so its credential-bearing count is
+ * reported on the same terms as everywhere else in the runtime. This list then
+ * narrows what survives; it can only ever remove more.
+ *
+ * This is a control over NAMES and therefore best-effort by construction: a
+ * credential exported under a name on this list still passes. The load-bearing
+ * control beside it is that egress is denied, so a secret that does reach the
+ * child has nowhere to go.
+ */
+export const CONFINED_ENV_ALLOW = [
+    "PATH",
+    "HOME",
+    "SHELL",
+    "USER",
+    "LOGNAME",
+    "LANG",
+    "LC_ALL",
+    "LC_CTYPE",
+    "TERM",
+    "LINES",
+    "COLUMNS",
+];
+/** How long a confined command may run before it is killed. */
+export const DEFAULT_CONFINED_TIMEOUT_MS = 120_000;
+/**
+ * Why a confined session could not be prepared or run. Frozen, distinct, and
+ * pinned by `tests/codex-confine.test.ts` (SPEC.md §11.1 invariant 6).
+ */
+export const CONFINE_REFUSAL_CODES = [
+    /** This host has no sandbox mechanism in this build. A confined session refuses. */
+    "sandbox-unsupported",
+    /** The mechanism exists and did not work. */
+    "sandbox-unavailable",
+    /** The disposable workspace could not be created. */
+    "workspace-unavailable",
+    /** The command could not be resolved, so it was never wrapped. */
+    "command-unresolvable",
+    /** The command was killed at the deadline. No canonical effect is possible. */
+    "timeout",
+];
+function refuse(code, message) {
+    return { ok: false, code, message };
+}
+/**
+ * Prepare one confined session, or refuse.
+ *
+ * The refusal on an unsupported host is deliberate and is the one place this
+ * module is STRICTER than `core/sandbox.ts`'s posture table. See the header.
+ */
+export function planConfinedSession(installation, options = {}) {
+    const detection = detectSandbox(options.detect ?? {});
+    if (!detection.supported) {
+        return refuse("sandbox-unsupported", `a confined Codex session needs a sandbox mechanism and this build has none for this host: ${detection.reason}. Unlike \`approval run\`, this verb does not proceed and record \`unsupported\`: a session advertised as confined and not confined is worse than no session`);
+    }
+    if (!detection.available || detection.mechanism === null) {
+        return refuse("sandbox-unavailable", `the sandbox mechanism is present and did not work: ${detection.reason}. There is no opt-out and no raw fallback`);
+    }
+    let workspace;
+    try {
+        const root = options.scratchRoot === undefined ? tmpdir() : options.scratchRoot;
+        workspace = realpathSync(mkdtempSync(join(root, "approval-codex-session-")));
+    }
+    catch (cause) {
+        return refuse("workspace-unavailable", `the disposable session workspace could not be created: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    const source = options.source ?? process.env;
+    const { env: filtered, stripped } = childEnvironment({ source });
+    // Then the allow-list, which can only ever remove more. See CONFINED_ENV_ALLOW.
+    const env = {};
+    for (const name of CONFINED_ENV_ALLOW) {
+        const value = filtered[name];
+        if (value !== undefined)
+            env[name] = value;
+    }
+    const withheld = Object.values(source).filter((value) => value !== undefined).length -
+        Object.keys(env).length;
+    // The child's own view of "somewhere to put temporary files" is inside the
+    // room. Left alone it would point at a directory the profile denies, and a
+    // shell whose TMPDIR is unwritable fails in ways that look like the sandbox
+    // being broken rather than doing its job.
+    env["TMPDIR"] = workspace;
+    env["APPROVAL_CODEX_SESSION_WORKSPACE"] = workspace;
+    return {
+        ok: true,
+        session: {
+            version: CONFINED_SESSION_VERSION,
+            workspace,
+            canonical: installation.root,
+            mechanism: detection.mechanism,
+            // The ONLY writable subtree. The canonical workspace, the gate home, the
+            // install root and the rest of the filesystem are absent, which is what
+            // makes this an allow-list rather than a wish.
+            writeAllow: [workspace],
+            readAllow: [workspace, installation.root],
+            denyRead: credentialPathsFor(installation.logPath),
+            env,
+            envStripped: stripped,
+            envWithheld: Math.max(0, withheld),
+            dispose: () => {
+                try {
+                    rmSync(workspace, { recursive: true, force: true });
+                }
+                catch {
+                    // A scratch directory that outlives the session is visible to a person
+                    // and costs nothing; failing to remove it must not fail the session.
+                }
+            },
+        },
+    };
+}
+/**
+ * Run one command inside a prepared session.
+ *
+ * The command is resolved BEFORE it is wrapped, for `core/sandbox.ts`'s reason:
+ * an `execvp` failure inside `sandbox-exec` exits 71, and 71 recorded as the
+ * child's exit code is a lie about a command that never ran. Here it is a
+ * refusal instead of an unwrapped spawn, because an unwrapped spawn is exactly
+ * the raw fallback this session must not have.
+ */
+export function runConfined(session, command, args, options = {}) {
+    const resolved = resolveExecutable(command, session.env);
+    if (resolved === null) {
+        return refuse("command-unresolvable", `${JSON.stringify(command)} could not be resolved on the session's PATH. It was NOT spawned unwrapped: a confined session has no raw fallback`);
+    }
+    const wrapped = wrapForSandbox(session.mechanism, resolved, args, {
+        loopback: false,
+        denyRead: session.denyRead,
+        writeAllow: session.writeAllow,
+        allowRead: session.readAllow,
+    });
+    try {
+        const result = spawnSync(wrapped.command, wrapped.args, {
+            cwd: options.cwd ?? session.workspace,
+            env: session.env,
+            encoding: "utf8",
+            timeout: options.timeoutMs ?? DEFAULT_CONFINED_TIMEOUT_MS,
+            maxBuffer: options.maxBuffer ?? 4 * 1024 * 1024,
+        });
+        const timedOut = result.signal !== null && result.error !== undefined;
+        return {
+            ok: true,
+            exitCode: exitCodeOf(result.status, result.signal),
+            stdout: result.stdout ?? "",
+            stderr: result.stderr ?? "",
+            timedOut,
+        };
+    }
+    finally {
+        // The profile file, not the workspace: the session owns that and disposes
+        // of it when it ends, so several commands share one room.
+        try {
+            rmSync(wrapped.cleanup, { recursive: true, force: true });
+        }
+        catch {
+            // Same reasoning as the workspace: visible, and never a reason to fail.
+        }
+    }
+}
+/** The shell's convention, so a signal death is distinguishable from an exit. */
+function exitCodeOf(status, signal) {
+    if (status !== null)
+        return status;
+    if (signal === null)
+        return 1;
+    const numbers = { SIGTERM: 15, SIGKILL: 9, SIGINT: 2, SIGHUP: 1 };
+    return 128 + (numbers[signal] ?? 0);
+}
+//# sourceMappingURL=runner.js.map

package/dist/src/codex/runner.js.map

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

package/dist/src/codex/serve.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The strict Codex broker server (APRV-325.2): one tool, and nothing else.
+ *
+ * This is deliberately NOT `src/mcp/server.ts` with a flag. That server
+ * publishes the whole agent verb catalog — `run` spawns argv on the host,
+ * `adapter <name>` spends vault credentials, `journal write` writes a local
+ * file — and its tool list is derived from the verb registry, so a verb added
+ * tomorrow appears on it. A constrained Codex session is the case where that
+ * derivation is exactly wrong: the session must reach ONE door, the door must
+ * be the same door next month, and the way to guarantee that is a server whose
+ * catalog is a literal of length one.
+ *
+ * Everything else follows from the same reasoning:
+ *
+ * - **The catalog is a literal.** {@link BROKER_TOOLS} is checked at CALL time
+ *   as well as at list time, so a client that crafted the name itself is
+ *   refused by the same check that filtered the list (the defence in depth
+ *   `mcp-guest-restricted` keeps on the broad server).
+ * - **The input schema has no authority in it.** `operations` and
+ *   `expected_policy_sha256`, `additionalProperties: false`, and the broker
+ *   refuses an unknown key a second time. There is no `--as`, no path, no
+ *   class, no token and no sandbox flag to remove, because none was ever
+ *   published.
+ * - **Identity and every path come from the manifest**, which lives under a
+ *   root-owned install root. The operator who installed it chose them; this
+ *   process cannot be argued into different ones.
+ * - **A refusal is a RESULT, not a JSON-RPC error**, for the reason the broad
+ *   server gives: the call was well formed and the runtime's answer was no,
+ *   which the caller has to be able to read as data and branch on.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { type Tool } from "@modelcontextprotocol/sdk/types.js";
+import { type BrokerInstallation, type BrokerOptions } from "./broker.js";
+export declare const BROKER_TOOL_NAME: "codex_workspace_apply";
+/** The whole published contract of this server. */
+export declare const BROKER_TOOL: Tool;
+export interface BrokerServerOptions {
+    installation: BrokerInstallation;
+    /** Forwarded to the broker. `tokens` is deliberately absent: see below. */
+    broker?: Omit<BrokerOptions, "tokens">;
+}
+export declare const BROKER_INSTRUCTIONS = "This server is the ONLY way a change reaches the canonical workspace in this session. It publishes exactly one tool, `codex_workspace_apply`, and no other name is callable whether or not something advertised it. You cannot name the acting identity, the workspace root, the policy file, the log, an action class, a reversibility, a grant token or a sandbox posture: all of those belong to the installation an operator owns, and a call that mentions one is refused rather than quietly overridden. Read the policy, hash its exact bytes, and send that digest as `expected_policy_sha256`; if it has changed since, you are told so instead of being evaluated against something you did not read. Every proposal is all-or-nothing: the operations are staged, journaled and applied under a workspace lock, and the outcome you are given is what reading the workspace back proved, not what this process believes it did. When the policy sends a class to a human, the refusal names the action keys awaiting a decision; call again with the same bytes once they have decided, and the same call will apply. Shell, network and credentials are not here and are not coming: this door is for workspace changes.";
+/**
+ * Build the strict server. Nothing is connected until `Server.connect`.
+ *
+ * `tokens` is omitted from what a caller of this constructor may forward for
+ * the same reason `--as` is absent from the published schema: a raw grant token
+ * is spend material, and a server process holding one for every class would be
+ * a server that executes a human's decision without the human. The manual path
+ * works through sealed delivery instead — the human grants, the token is sealed
+ * to the key the request minted, and `core/execute.ts` opens it at the start.
+ */
+export declare function createCodexBrokerServer(options: BrokerServerOptions): Server;
+/** Build the strict server and connect it. Resolves once connected. */
+export declare function serveCodexBroker(options: BrokerServerOptions, transport: Transport): Promise<Server>;

package/dist/src/codex/serve.js

@@ -0,0 +1,98 @@
+/**
+ * The strict Codex broker server (APRV-325.2): one tool, and nothing else.
+ *
+ * This is deliberately NOT `src/mcp/server.ts` with a flag. That server
+ * publishes the whole agent verb catalog — `run` spawns argv on the host,
+ * `adapter <name>` spends vault credentials, `journal write` writes a local
+ * file — and its tool list is derived from the verb registry, so a verb added
+ * tomorrow appears on it. A constrained Codex session is the case where that
+ * derivation is exactly wrong: the session must reach ONE door, the door must
+ * be the same door next month, and the way to guarantee that is a server whose
+ * catalog is a literal of length one.
+ *
+ * Everything else follows from the same reasoning:
+ *
+ * - **The catalog is a literal.** {@link BROKER_TOOLS} is checked at CALL time
+ *   as well as at list time, so a client that crafted the name itself is
+ *   refused by the same check that filtered the list (the defence in depth
+ *   `mcp-guest-restricted` keeps on the broad server).
+ * - **The input schema has no authority in it.** `operations` and
+ *   `expected_policy_sha256`, `additionalProperties: false`, and the broker
+ *   refuses an unknown key a second time. There is no `--as`, no path, no
+ *   class, no token and no sandbox flag to remove, because none was ever
+ *   published.
+ * - **Identity and every path come from the manifest**, which lives under a
+ *   root-owned install root. The operator who installed it chose them; this
+ *   process cannot be argued into different ones.
+ * - **A refusal is a RESULT, not a JSON-RPC error**, for the reason the broad
+ *   server gives: the call was well formed and the runtime's answer was no,
+ *   which the caller has to be able to read as data and branch on.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
+import { SPEC_VERSION } from "../core/version.js";
+import { applyWorkspaceChange, BROKER_TOOLS, } from "./broker.js";
+export const BROKER_TOOL_NAME = "codex_workspace_apply";
+/** The whole published contract of this server. */
+export const BROKER_TOOL = {
+    name: BROKER_TOOL_NAME,
+    title: "apply a bounded workspace change through the approval gate",
+    description: "Apply a bounded, typed change to the canonical workspace through approval.md's gate. Every operation is create, replace, delete or move on a relative path inside the workspace; `replace`, `delete` and `move` state the SHA-256 of the bytes they expect to find and are refused if the workspace has moved on. `expected_policy_sha256` is the digest of the policy you read, and a proposal built against a different one is refused rather than silently re-evaluated. The acting identity, the workspace root, the policy, the log and every class are the installation's and cannot be named here. A class the policy resolves to a human decision is refused with `approval-required` and the action keys a person must grant; ask again once they have. Nothing partially applies: either the whole proposal took, or it did not, or the answer is honestly unknown and a person owns it.",
+    inputSchema: {
+        type: "object",
+        additionalProperties: false,
+        required: ["operations", "expected_policy_sha256"],
+        properties: {
+            operations: {
+                type: "array",
+                minItems: 1,
+                maxItems: 64,
+                description: "The bounded closed change language. `{kind:\"create\", path, after_base64}`, `{kind:\"replace\", path, expected_before_sha256, after_base64}`, `{kind:\"delete\", path, expected_before_sha256}`, `{kind:\"move\", from, to, expected_before_sha256}`. Paths are relative NFC POSIX paths inside the workspace; images are canonical base64, at most 1 MiB each and 8 MiB combined.",
+                items: { type: "object" },
+            },
+            expected_policy_sha256: {
+                type: "string",
+                pattern: "^[0-9a-f]{64}$",
+                description: "SHA-256 of the exact APPROVAL.md bytes this proposal was built against. A mismatch refuses `attestation-drift`.",
+            },
+        },
+    },
+};
+export const BROKER_INSTRUCTIONS = "This server is the ONLY way a change reaches the canonical workspace in this session. It publishes exactly one tool, `codex_workspace_apply`, and no other name is callable whether or not something advertised it. You cannot name the acting identity, the workspace root, the policy file, the log, an action class, a reversibility, a grant token or a sandbox posture: all of those belong to the installation an operator owns, and a call that mentions one is refused rather than quietly overridden. Read the policy, hash its exact bytes, and send that digest as `expected_policy_sha256`; if it has changed since, you are told so instead of being evaluated against something you did not read. Every proposal is all-or-nothing: the operations are staged, journaled and applied under a workspace lock, and the outcome you are given is what reading the workspace back proved, not what this process believes it did. When the policy sends a class to a human, the refusal names the action keys awaiting a decision; call again with the same bytes once they have decided, and the same call will apply. Shell, network and credentials are not here and are not coming: this door is for workspace changes.";
+/**
+ * Build the strict server. Nothing is connected until `Server.connect`.
+ *
+ * `tokens` is omitted from what a caller of this constructor may forward for
+ * the same reason `--as` is absent from the published schema: a raw grant token
+ * is spend material, and a server process holding one for every class would be
+ * a server that executes a human's decision without the human. The manual path
+ * works through sealed delivery instead — the human grants, the token is sealed
+ * to the key the request minted, and `core/execute.ts` opens it at the start.
+ */
+export function createCodexBrokerServer(options) {
+    const server = new Server({ name: "approval-md-codex-broker", version: SPEC_VERSION }, { capabilities: { tools: {} }, instructions: BROKER_INSTRUCTIONS });
+    server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: [BROKER_TOOL] }));
+    server.setRequestHandler(CallToolRequestSchema, (request) => {
+        const name = request.params.name;
+        if (!BROKER_TOOLS.has(name)) {
+            throw new McpError(ErrorCode.InvalidParams, `unknown tool ${JSON.stringify(name)}: this server publishes exactly ${[...BROKER_TOOLS].join(", ")}. Shell, network, credential and gate-authority verbs are not withheld here, they are absent`);
+        }
+        const result = applyWorkspaceChange(name, options.installation, request.params.arguments, options.broker ?? {});
+        const payload = result.ok
+            ? { ...result }
+            : { error: { code: result.code, message: result.message, ...(result.detail === undefined ? {} : { detail: result.detail }), ...(result.pending === undefined ? {} : { pending: result.pending }), ...(result.state === undefined ? {} : { state: result.state }) } };
+        return {
+            content: [{ type: "text", text: JSON.stringify(payload) }],
+            structuredContent: payload,
+            ...(result.ok ? {} : { isError: true }),
+        };
+    });
+    return server;
+}
+/** Build the strict server and connect it. Resolves once connected. */
+export async function serveCodexBroker(options, transport) {
+    const server = createCodexBrokerServer(options);
+    await server.connect(transport);
+    return server;
+}
+//# sourceMappingURL=serve.js.map

package/dist/src/codex/serve.js.map

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