@mnemom/mnemom 0.17.32 → 0.17.33

package/dist/lib/runner/proxy.js

@@ -0,0 +1,153 @@
+/**
+ * The runner's own model proxy (ruling 34.11, 34.12 (7); Doors W3.11).
+ *
+ * A served phase's Claude Code (and a code phase's child) points ANTHROPIC_BASE_URL here, on
+ * loopback. The proxy forwards each request to the gateway and decides every Mnemom header itself:
+ * any `x-mnemom-*` the phase sent is dropped, the lease key goes in X-Mnemom-Api-Key, and the job's
+ * sealed contract goes in `x-mnemom-contract` (exactly one, the sealed version). The phase never
+ * sees the lease key. A 409 `contract_mismatch` from the gateway (34.11) is reported to the job,
+ * which refetches and continues only on a higher sealed version, else fails closed.
+ */
+import { createServer, request as httpRequest, } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { applySealedContract, CONTRACT_HEADER } from "./contract-header.js";
+export const LEASE_KEY_HEADER = "x-mnemom-api-key";
+/** Hop-by-hop headers (RFC 9110 7.6.1) and the ones the proxy owns. */
+const DROP = new Set([
+    "connection",
+    "keep-alive",
+    "proxy-connection",
+    "transfer-encoding",
+    "upgrade",
+    "te",
+    "trailer",
+    "host",
+    "content-length",
+]);
+/** Outbound headers for one request: the phase's own, minus anything the proxy decides. */
+export function outboundHeaders(incoming, state) {
+    const kept = {};
+    for (const [name, value] of Object.entries(incoming)) {
+        const lower = name.toLowerCase();
+        if (DROP.has(lower) || lower.startsWith("x-mnemom-"))
+            continue;
+        kept[lower] = value;
+    }
+    kept[LEASE_KEY_HEADER] = state.leaseKey;
+    return applySealedContract(kept, state.contractValue);
+}
+/** The largest 409 body the proxy reads for a contract mismatch. */
+export const MISMATCH_BODY_MAX = 64 * 1024;
+function mismatchVersion(body) {
+    try {
+        const b = JSON.parse(body);
+        const code = typeof b.error === "object" && b.error ? b.error.code : (b.error ?? b.code);
+        if (code !== "contract_mismatch")
+            return undefined;
+        const v = (typeof b.error === "object" && b.error ? b.error.details?.expected_version : undefined) ??
+            b.expected_version;
+        return Number.isSafeInteger(v) ? v : null;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The client for the gateway's scheme: TLS for https, plain only for a local http gateway. */
+export function requestFor(protocol) {
+    return protocol === "https:" ? httpsRequest : httpRequest;
+}
+/**
+ * The phase's answer when the gateway fails: a 502 if nothing was sent yet, else the connection is
+ * cut, so a truncated body is never mistaken for a whole one.
+ */
+export function upstreamFailed(res, e) {
+    if (res.headersSent) {
+        res.destroy(e);
+        return;
+    }
+    res.writeHead(502, { "content-type": "application/json" });
+    res.end(JSON.stringify({ error: { code: "runner_proxy_upstream", message: e.message } }));
+}
+export async function startModelProxy(gatewayUrl, state) {
+    const upstream = new URL(gatewayUrl);
+    const send = requestFor(upstream.protocol);
+    const basePath = upstream.pathname.replace(/\/+$/, "");
+    const forwarded = [];
+    const proxy = {
+        url: "",
+        forwarded,
+        contractMismatch: null,
+        close: async () => { },
+    };
+    const server = createServer((req, res) => {
+        const headers = outboundHeaders(req.headers, state);
+        const sent = headers[CONTRACT_HEADER];
+        const out = send({
+            protocol: upstream.protocol,
+            hostname: upstream.hostname,
+            port: upstream.port || undefined,
+            method: req.method,
+            path: `${basePath}${req.url ?? "/"}`,
+            headers,
+        }, (up) => {
+            const status = up.statusCode ?? 502;
+            forwarded.push({
+                method: req.method ?? "GET",
+                path: req.url ?? "/",
+                contract: sent,
+                status,
+            });
+            if (status === 409) {
+                // Buffered to read the mismatch, up to a cap; a larger body is relayed unread.
+                const chunks = [];
+                let size = 0;
+                up.on("error", (e) => upstreamFailed(res, e));
+                const onData = (c) => {
+                    chunks.push(c);
+                    size += c.length;
+                    if (size <= MISMATCH_BODY_MAX)
+                        return;
+                    up.off("data", onData);
+                    up.off("end", onEnd);
+                    res.writeHead(status, up.headers);
+                    for (const b of chunks)
+                        res.write(b);
+                    up.pipe(res);
+                };
+                const onEnd = () => {
+                    const body = Buffer.concat(chunks);
+                    const v = mismatchVersion(body.toString("utf8"));
+                    if (v !== undefined)
+                        proxy.contractMismatch = { expected_version: v };
+                    res.writeHead(status, up.headers);
+                    res.end(body);
+                };
+                up.on("data", onData);
+                up.on("end", onEnd);
+                return;
+            }
+            res.writeHead(status, up.headers);
+            // A gateway that drops mid-body errors the response, not the request.
+            up.on("error", (e) => upstreamFailed(res, e));
+            up.pipe(res);
+        });
+        out.on("error", (e) => {
+            forwarded.push({
+                method: req.method ?? "GET",
+                path: req.url ?? "/",
+                contract: sent,
+                status: 502,
+            });
+            upstreamFailed(res, e);
+        });
+        req.pipe(out);
+    });
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const { port } = server.address();
+    proxy.url = `http://127.0.0.1:${port}`;
+    proxy.close = () => new Promise((resolve) => {
+        server.closeAllConnections?.();
+        server.close(() => resolve());
+    });
+    return proxy;
+}

package/dist/lib/runner/settings.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Thin runner settings (Doors W-L13, W4.4): what the runner does on a Mnemom error, and how a job
+ * lands once its PR is open.
+ *
+ * Fail mode (decision 20, OD-2): served-phase jobs fail CLOSED by default. A Mnemom error (claim,
+ * bundle fetch, bundle verification, the job read, the gateway) stops the job and leaves it for
+ * the lease to lapse back to ready; nothing runs unverified or ungoverned. `open` lets a job that
+ * already holds a verified bundle carry on through a transient error on a later call. It never
+ * lets an unverified bundle run: verification failures stop the job in every mode. An unknown
+ * value reads as the default, closed, with a warning, so a typo can never weaken the runner.
+ *
+ * Merge strategy (W4.4, T15): the bundle may name `merge_on_green` (our fleet) or `external`
+ * (a person merges). A bundle that names none resolves to `external`: the job opens the PR and
+ * stops.
+ */
+import type { MergeStrategy, ServedPhaseBundle } from "./bundle.js";
+export type RunnerFailMode = "closed" | "open";
+export declare const RUNNER_FAIL_MODE_ENV = "MNEMOM_RUNNER_FAIL_MODE";
+export declare const DEFAULT_RUNNER_FAIL_MODE: RunnerFailMode;
+export interface ResolvedFailMode {
+    mode: RunnerFailMode;
+    /** Set when a value was given but not recognised (the default applied). */
+    warning?: string;
+}
+/**
+ * The fail mode for one runner. Precedence: the `--fail-mode` flag, then MNEMOM_RUNNER_FAIL_MODE,
+ * then closed. Matching is case-insensitive and trims whitespace; an empty value counts as unset.
+ */
+export declare function resolveFailMode(flag: string | undefined, env: string | undefined): ResolvedFailMode;
+/** The bundle's merge strategy, `external` when it names none. */
+export declare function resolveMergeStrategy(bundle: Pick<ServedPhaseBundle, "merge_strategy">): MergeStrategy;

package/dist/lib/runner/settings.js

@@ -0,0 +1,44 @@
+/**
+ * Thin runner settings (Doors W-L13, W4.4): what the runner does on a Mnemom error, and how a job
+ * lands once its PR is open.
+ *
+ * Fail mode (decision 20, OD-2): served-phase jobs fail CLOSED by default. A Mnemom error (claim,
+ * bundle fetch, bundle verification, the job read, the gateway) stops the job and leaves it for
+ * the lease to lapse back to ready; nothing runs unverified or ungoverned. `open` lets a job that
+ * already holds a verified bundle carry on through a transient error on a later call. It never
+ * lets an unverified bundle run: verification failures stop the job in every mode. An unknown
+ * value reads as the default, closed, with a warning, so a typo can never weaken the runner.
+ *
+ * Merge strategy (W4.4, T15): the bundle may name `merge_on_green` (our fleet) or `external`
+ * (a person merges). A bundle that names none resolves to `external`: the job opens the PR and
+ * stops.
+ */
+export const RUNNER_FAIL_MODE_ENV = "MNEMOM_RUNNER_FAIL_MODE";
+export const DEFAULT_RUNNER_FAIL_MODE = "closed";
+/**
+ * The fail mode for one runner. Precedence: the `--fail-mode` flag, then MNEMOM_RUNNER_FAIL_MODE,
+ * then closed. Matching is case-insensitive and trims whitespace; an empty value counts as unset.
+ */
+export function resolveFailMode(flag, env) {
+    for (const [source, raw] of [
+        ["--fail-mode", flag],
+        [RUNNER_FAIL_MODE_ENV, env],
+    ]) {
+        if (raw === undefined)
+            continue;
+        const v = raw.trim().toLowerCase();
+        if (v === "")
+            continue;
+        if (v === "closed" || v === "open")
+            return { mode: v };
+        return {
+            mode: DEFAULT_RUNNER_FAIL_MODE,
+            warning: `${source}=${JSON.stringify(raw)} is not closed or open; failing closed`,
+        };
+    }
+    return { mode: DEFAULT_RUNNER_FAIL_MODE };
+}
+/** The bundle's merge strategy, `external` when it names none. */
+export function resolveMergeStrategy(bundle) {
+    return bundle.merge_strategy ?? "external";
+}

package/dist/lib/statusline-feed.js

@@ -12,7 +12,7 @@
 import { renameSync, writeFileSync } from "node:fs";
 import { getRecordTotals } from "./api.js";
 import { readRecordState } from "./conduct-receipt.js";
-import { LINEAGE_KEY_RE, MMU_RE } from "./statusline.js";
+import { LINEAGE_KEY_RE, toFedTotals } from "./statusline.js";
 /** How often the launcher re-reads the totals. */
 export const FEED_INTERVAL_MS = 10_000;
 /**
@@ -32,18 +32,17 @@ export async function feedOnce(o) {
         const totals = await (o.fetchTotals ?? getRecordTotals)(o.orgId, key);
         if (!totals || totals.lineage_key !== key)
             return false;
-        // Persist only amounts the bin would render: a malformed reply never replaces a good feed.
-        const mu = totals.mu_charged_mmu;
-        if (typeof totals.model_cost_mmu !== "string" || !MMU_RE.test(totals.model_cost_mmu)) {
-            return false;
-        }
-        if (mu !== null && (typeof mu !== "string" || !MMU_RE.test(mu)))
-            return false;
-        const tmp = `${o.feedFile}.tmp`;
-        writeFileSync(tmp, JSON.stringify({
+        // Persist only the amounts the bin would render, rebuilt from the checked values (never
+        // the reply itself): a malformed reply never replaces a good feed. The path is the
+        // launcher's own feedFile; nothing in the reply names where it is written.
+        const fed = toFedTotals({
             model_cost_mmu: totals.model_cost_mmu,
             mu_charged_mmu: totals.mu_charged_mmu,
-        }));
+        });
+        if (!fed)
+            return false;
+        const tmp = `${o.feedFile}.tmp`;
+        writeFileSync(tmp, JSON.stringify(fed));
         renameSync(tmp, o.feedFile);
         return true;
     }

package/dist/lib/statusline.d.ts

@@ -38,6 +38,12 @@ export interface FedTotals {
     /** null: no billing row yet, shown "μ not charged" (OD-9). */
     mu_charged_mmu: string | null;
 }
+/**
+ * The totals the segment renders, rebuilt from only the two checked amounts, or null when
+ * either is off. The one shape check for both sides of the feed: the launcher writes only
+ * what this returns (lib/statusline-feed.ts) and the bin reads only what this accepts.
+ */
+export declare function toFedTotals(d: Record<string, unknown>): FedTotals | null;
 /** The feed file's totals, or null when it is absent or anything in it is off. */
 export declare function readFeed(path: string): FedTotals | null;
 /** Model cost in dollars: 1000 mmu = 1 μ = 1¢. Under half a cent reads "<$0.01", never "$0.00". */

package/dist/lib/statusline.js

@@ -37,19 +37,29 @@ export const FEED_ENV = "MNEMOM_STATUSLINE_FEED";
 export const LINEAGE_KEY_RE = /^(cid|cr):[0-9a-f]{16}$/;
 /** A millimu amount as the record route returns it: a decimal string, no sign, no leading 0. */
 export const MMU_RE = /^(0|[1-9][0-9]{0,18})$/;
+/** `v` when it is a millimu decimal string (MMU_RE), else undefined. */
+function mmu(v) {
+    return typeof v === "string" && MMU_RE.test(v) ? v : undefined;
+}
+/**
+ * The totals the segment renders, rebuilt from only the two checked amounts, or null when
+ * either is off. The one shape check for both sides of the feed: the launcher writes only
+ * what this returns (lib/statusline-feed.ts) and the bin reads only what this accepts.
+ */
+export function toFedTotals(d) {
+    const cost = mmu(d.model_cost_mmu);
+    if (cost === undefined)
+        return null;
+    if (d.mu_charged_mmu === null)
+        return { model_cost_mmu: cost, mu_charged_mmu: null };
+    const mu = mmu(d.mu_charged_mmu);
+    return mu === undefined ? null : { model_cost_mmu: cost, mu_charged_mmu: mu };
+}
 /** The feed file's totals, or null when it is absent or anything in it is off. */
 export function readFeed(path) {
     try {
         const d = parseJson(readFileSync(path, "utf8"));
-        if (!d)
-            return null;
-        const cost = d.model_cost_mmu;
-        const mu = d.mu_charged_mmu;
-        if (typeof cost !== "string" || !MMU_RE.test(cost))
-            return null;
-        if (mu !== null && (typeof mu !== "string" || !MMU_RE.test(mu)))
-            return null;
-        return { model_cost_mmu: cost, mu_charged_mmu: mu };
+        return d ? toFedTotals(d) : null;
     }
     catch {
         return null;

package/dist/rc-proxy.mjs

@@ -13,6 +13,15 @@
 //
 // WHAT IT DOES
 //   * Listens on 127.0.0.1 (ephemeral port) as an HTTP CONNECT proxy.
+//   * Serves only the caller that holds this session's proxy credential (MNE-9233). Loopback is not
+//     a boundary: every local process, any other user and every other seat's session can reach the
+//     port, and this proxy injects the owner's keys. The launcher mints the credential per session,
+//     hands it here on stdin and to Claude Code as the userinfo of HTTPS_PROXY
+//     (`http://mnemom:<credential>@127.0.0.1:<port>`), which Claude Code sends as
+//     `Proxy-Authorization: Basic` on CONNECT (measured on Claude Code 2.1.312) and on absolute-form
+//     requests (its bundled axios builds the header from the proxy URL's userinfo). Any other caller
+//     gets 407 before anything is tunnelled, terminated or injected. `Proxy-Authorization` is
+//     hop-by-hop: it is never forwarded upstream or to the gateway.
 //   * Terminates TLS for api.anthropic.com ONLY, with an ephemeral CA (397 days, key held in
 //     memory only) minted at startup into a private 0700 dir under ~/.mnemom/rc (removed on
 //     exit; see rc-state.mjs for why not the OS temp dir), and a 7-day leaf re-minted every 24 h
@@ -52,8 +61,9 @@
 //         (diagnostic only: it forwards continue-deltas the API rejects).
 //
 // SECRETS
-// Arrive on stdin as three newline-terminated lines: Anthropic key, Mnemom key (may be
-// empty), OpenAI egress key (may be empty). Never argv, never env, never disk, never logged.
+// Arrive on stdin as four newline-terminated lines: Anthropic key, Mnemom key (may be
+// empty), OpenAI egress key (may be empty), the per-session proxy credential (required).
+// Never argv, never env, never disk, never logged.
 // The log (MNEMOM_AGENT_RC_PROXY_LOG, else stderr) carries method/path/status/latency and the
 // gateway's `x-mnemom-agent` / `x-mnemom-goal-verdict` response headers only. Gateway error
 // bodies (status ≥ 400) are logged truncated so a 4xx is diagnosable (compressed ones as
@@ -84,7 +94,8 @@
 //   MNEMOM_AGENT_TURN_HEADER          0/off: no x-mnemom-turn header (default on in implicit mode;
 //                                  see turn-origin.mjs)
 //
-// stdout: exactly one line, `READY <port> <ca.pem path>`, once listening. Node ≥ 18, no deps.
+// stdout: exactly one line, `READY <port> <ca.pem path>`, once listening (no secret on it). Node ≥ 18,
+// no deps.
 import http from "node:http";
 import https from "node:https";
 import net from "node:net";
@@ -165,7 +176,7 @@ const log = (line, retry = true) => {
   process.stderr.write(s);
 };
 
-// --- secrets: three lines on stdin ------------------------------------------------------
+// --- secrets: four lines on stdin -------------------------------------------------------
 let secrets;
 try {
   const lines = fs.readFileSync(0, "utf8").split("\n");
@@ -173,15 +184,34 @@ try {
     anthropic: (lines[0] || "").trim(),
     mnemom: (lines[1] || "").trim(),
     openai: (lines[2] || "").trim(),
+    proxy: (lines[3] || "").trim(),
   };
 } catch {
-  die("expected three lines of secrets on stdin (anthropic, mnemom, openai)");
+  die("expected four lines on stdin (anthropic, mnemom, openai, proxy credential)");
 }
 if (AGENT_ID && !secrets.mnemom)
   die("a pinned agent (MNEMOM_AGENT_RC_AGENT_ID) needs the Mnemom key (stdin line 2)");
 if (SUBSCRIPTION) {
   if (!secrets.mnemom) die("subscription login needs the Mnemom key (stdin line 2)");
 } else if (!secrets.anthropic) die("the Anthropic key (stdin line 1) is empty");
+// Fail closed: with no credential there is nothing to check a caller against.
+if (!secrets.proxy) die("the proxy credential (stdin line 4) is empty");
+
+// --- caller authentication (MNE-9233; see WHAT IT DOES) -------------------------------------
+// `Proxy-Authorization: Basic base64("mnemom:<credential>")`, compared in constant time. The
+// header value is never logged.
+const PROXY_USER = "mnemom";
+const PROXY_AUTH_EXPECTED = Buffer.from(`${PROXY_USER}:${secrets.proxy}`, "utf8");
+function callerAuthorized(header) {
+  const m = /^basic\s+([A-Za-z0-9+/]+={0,2})\s*$/i.exec(typeof header === "string" ? header : "");
+  if (!m) return false;
+  const got = Buffer.from(m[1], "base64");
+  return (
+    got.length === PROXY_AUTH_EXPECTED.length && crypto.timingSafeEqual(got, PROXY_AUTH_EXPECTED)
+  );
+}
+const PROXY_REALM = 'Basic realm="mnemom-code-rc-proxy"';
+const PROXY_407_NOTE = "407 proxy authentication required (no or wrong Proxy-Authorization)";
 
 // --- ephemeral CA + rotating leaf for api.anthropic.com ---------------------------------
 // Private 0700 dir under ~/.mnemom/rc (rc-state.mjs), removed on exit. Claude Code reads NODE_EXTRA_CA_CERTS
@@ -389,6 +419,7 @@ const upstreamAgent = new https.Agent({ keepAlive: true, maxSockets: 32 });
 const HOP = new Set([
   "connection",
   "proxy-connection",
+  "proxy-authorization", // this session's proxy credential: never leaves the proxy
   "keep-alive",
   "upgrade",
   "host",
@@ -490,9 +521,34 @@ function rejectThread(res, tag, thread) {
   );
 }
 
+// 407 for an absolute-form request without this session's credential: nothing is parsed,
+// forwarded or injected, and the connection is closed.
+function refusePlain(req, res) {
+  req.resume(); // discard any body
+  let host = "-";
+  try {
+    host = new URL(req.url).host || "-";
+  } catch {
+    /* not absolute-form: logged as "-" */
+  }
+  res.writeHead(407, {
+    "proxy-authenticate": PROXY_REALM,
+    "content-type": "text/plain",
+    connection: "close",
+  });
+  res.end("mnemom-code-rc-proxy: proxy authentication required\n");
+  log(`${req.method} ${host} -> ${PROXY_407_NOTE}`);
+}
+
 // One handler serves both the MITM'd TLS stream (origin-form URLs, host = api.anthropic.com)
 // and absolute-form plaintext requests sent straight to the proxy port.
 function handle(req, res, viaPlain) {
+  // A request on the proxy port must carry the credential. One inside the MITM'd TLS stream
+  // already did, on the CONNECT that opened the tunnel.
+  if (viaPlain && !callerAuthorized(req.headers["proxy-authorization"])) {
+    refusePlain(req, res);
+    return;
+  }
   let host = MITM_HOST,
     port = 443,
     urlPath = req.url,
@@ -681,6 +737,14 @@ proxy.on("connect", (req, sock, head) => {
   const [host, portStr] = req.url.split(":");
   const port = Number(portStr || 443);
   sock.on("error", () => {});
+  if (!callerAuthorized(req.headers["proxy-authorization"])) {
+    // Before the MITM arm and before any upstream socket: an unauthenticated caller gets neither.
+    sock.end(
+      `HTTP/1.1 407 Proxy Authentication Required\r\nProxy-Authenticate: ${PROXY_REALM}\r\nContent-Length: 0\r\nConnection: close\r\n\r\n`,
+    );
+    log(`CONNECT ${req.url} -> ${PROXY_407_NOTE}`);
+    return;
+  }
   if (host === MITM_HOST && port === 443) {
     // A timer can run late (laptop sleep): never hand out a leaf that is about to expire.
     if (leaves.current().notAfter - Date.now() < LEAF_MIN_LEFT_MS) rotateLeaf("expiring");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemom/mnemom",
-  "version": "0.17.32",
+  "version": "0.17.33",
   "description": "Transparent AI agent tracing",
   "type": "module",
   "bin": {
@@ -24,6 +24,7 @@
     "smol-toml": "^1.9.0"
   },
   "devDependencies": {
+    "@mnemom/aip-verifier": "https://github.com/mnemom/aip/releases/download/aip-verifier-v0.6.0/mnemom-aip-verifier-0.6.0.tgz",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.10.0",
     "@vitest/coverage-v8": "^4.1.12",