@mnemom/mnemom 0.17.32 → 0.17.34-next.1

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,23 @@
 //         (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.
+//
+// SESSION KEY RENEWAL
+// The Mnemom key on line 2 is the launcher's minted session key (MNE-8245): 24h-TTL'd, and a
+// Remote Control seat outlives it. When the launcher passes MNEMOM_AGENT_RC_CONTROL_FD, that fd is
+// a pipe to it carrying newline-delimited lines both ways:
+//   launcher -> proxy  `key <key id> <expires at> <key>`  swap this key in (before the old expires)
+//                      `key-failed <reason>`              a re-mint this proxy asked for failed
+//   proxy -> launcher  `remint <key id>`                  the gateway rejected this key
+// The swap is a single assignment, so every request carries either the old key or the new one.
+// On a gateway 401 that names the Mnemom key (`Invalid Mnemom API key`) for a buffered
+// /v1/messages POST, the proxy holds the 401 back, retries once with a newer key when it already
+// has one, else asks the launcher for one re-mint (single flight, bounded wait) and retries once
+// with it; anything else hands the client the original 401. Never a second retry, and never a
+// request whose body was streamed. Only key ids and expiry times are logged, never a key.
 // 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
@@ -80,11 +104,18 @@
 //                                  is required: it anchors the governed identity.
 //   MNEMOM_AGENT_RC_PROXY_LOG         append log lines to this file instead of stderr (optional)
 //   MNEMOM_AGENT_RC_PARENT_PID        exit when this pid is gone, so no orphan holds the keys
+//   MNEMOM_AGENT_RC_CONTROL_FD        the launcher's control pipe (optional; see SESSION KEY RENEWAL)
+//   MNEMOM_AGENT_RC_MNEMOM_KEY_ID     the line-2 key's id (optional; logged, and named in `remint`)
+//   MNEMOM_AGENT_RC_MNEMOM_KEY_EXPIRES_AT  the line-2 key's expiry (optional; logged)
 //   MNEMOM_AGENT_RC_PORT              listen port (default 0 = ephemeral)
+//   MNEMOM_RC_REMINT_WAIT_MS          how long a key-rejected request waits for the launcher's re-mint
+//                                  (default 20000; unset or empty means the default, "0" is
+//                                  honoured). The launcher never sets it, only tests do
 //   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";
@@ -96,6 +127,12 @@ import { execFileSync } from "node:child_process";
 import { TURN_HEADER, TurnOrigins, turnHeaderEnabled, turnHeaderFor } from "./turn-origin.mjs";
 import { OWNER_FILE, ensureRcStateRoot, keepPrivateDir, sweepRcDirs } from "./rc-state.mjs";
 import { assertUsableCert, makeLeafRotator } from "./rc-certs.mjs";
+import {
+  KEY_401_BODY_MAX,
+  holdBack401,
+  isMnemomKeyRejection,
+  remintWaitMs,
+} from "./rc-key-401.mjs";
 
 const MITM_HOST = "api.anthropic.com";
 const env = process.env;
@@ -165,7 +202,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 +210,141 @@ 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");
+
+// --- Mnemom session key renewal (see SESSION KEY RENEWAL) ----------------------------------
+// Key ids and expiry times are the only parts of a key line that may reach the log.
+const KEY_ID_RE = /^[A-Za-z0-9_.:-]{1,128}$/;
+const EXPIRES_RE = /^[0-9A-Za-z:.+-]{1,40}$/;
+const KEY_RE = /^[\x21-\x7e]{1,4096}$/;
+const keyMeta = {
+  id: KEY_ID_RE.test(env.MNEMOM_AGENT_RC_MNEMOM_KEY_ID || "")
+    ? env.MNEMOM_AGENT_RC_MNEMOM_KEY_ID
+    : "-",
+  expires: EXPIRES_RE.test(env.MNEMOM_AGENT_RC_MNEMOM_KEY_EXPIRES_AT || "")
+    ? env.MNEMOM_AGENT_RC_MNEMOM_KEY_EXPIRES_AT
+    : "-",
+};
+// How long a rejected request waits for the launcher's re-mint (rc-key-401.mjs).
+const REMINT_WAIT_MS = remintWaitMs(env);
+const CONTROL_LINE_MAX = 8192;
+let control = null;
+let remint = null; // { promise, resolve, timer } while a re-mint request is outstanding
+
+function settleRemint(ok) {
+  if (!remint) return;
+  const r = remint;
+  remint = null;
+  clearTimeout(r.timer);
+  r.resolve(ok);
+}
+
+// Resolves true once a new key has been swapped in, false when none is coming.
+function requestRemint() {
+  if (remint) return remint.promise;
+  if (!control) return Promise.resolve(false);
+  let resolve;
+  const promise = new Promise((r) => (resolve = r));
+  const timer = setTimeout(() => {
+    log(`mnemom key re-mint: no answer from the launcher within ${REMINT_WAIT_MS}ms`);
+    settleRemint(false);
+  }, REMINT_WAIT_MS);
+  timer.unref();
+  remint = { promise, resolve, timer };
+  control.write(`remint ${keyMeta.id}\n`);
+  return promise;
+}
+
+function onControlLine(line) {
+  const parts = line.split(" ");
+  const cmd = parts[0];
+  if (
+    cmd === "key" &&
+    parts.length === 4 &&
+    KEY_ID_RE.test(parts[1]) &&
+    EXPIRES_RE.test(parts[2]) &&
+    KEY_RE.test(parts[3])
+  ) {
+    const was = keyMeta.id;
+    secrets.mnemom = parts[3];
+    keyMeta.id = parts[1];
+    keyMeta.expires = parts[2];
+    log(`mnemom key renewed id=${keyMeta.id} expires=${keyMeta.expires} (was id=${was})`);
+    settleRemint(true);
+  } else if (cmd === "key-failed") {
+    const why = parts
+      .slice(1)
+      .join(" ")
+      .replace(/[^A-Za-z0-9 _.-]/g, "")
+      .slice(0, 80);
+    log(`mnemom key re-mint failed in the launcher (${why || "-"}); keeping id=${keyMeta.id}`);
+    settleRemint(false);
+  } else {
+    // Never echo the line: a malformed key line still carries a key.
+    log(`control: ignored a malformed line (${/^[a-z-]{1,16}$/.test(cmd) ? cmd : "?"})`);
+  }
+}
+
+const CONTROL_FD = Number(env.MNEMOM_AGENT_RC_CONTROL_FD || 0);
+if (secrets.mnemom && keyMeta.id !== "-")
+  log(`mnemom key id=${keyMeta.id} expires=${keyMeta.expires}`);
+if (CONTROL_FD > 2) {
+  try {
+    const sock = new net.Socket({ fd: CONTROL_FD, readable: true, writable: true });
+    control = sock;
+    let buf = "";
+    sock.on("data", (c) => {
+      buf += c.toString("utf8");
+      let i;
+      while ((i = buf.indexOf("\n")) >= 0) {
+        const line = buf.slice(0, i);
+        buf = buf.slice(i + 1);
+        onControlLine(line);
+      }
+      if (buf.length > CONTROL_LINE_MAX) {
+        buf = "";
+        log("control: dropped an oversized line");
+      }
+    });
+    const gone = (why) => {
+      if (control !== sock) return;
+      control = null;
+      log(`control channel closed (${why}): no further session key renewal`);
+      settleRemint(false);
+    };
+    sock.on("error", (e) => gone(e.code || e.message));
+    sock.on("close", () => gone("close"));
+  } catch (e) {
+    log(`control channel unavailable (${e.code || e.message}): no session key renewal`);
+  }
+}
+
+// --- 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 +552,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 +654,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,
@@ -534,7 +723,7 @@ function handle(req, res, viaPlain) {
     delete headers["x-mnemom-agent-id"];
     if (AGENT_ID) headers["x-mnemom-agent-id"] = AGENT_ID;
     headers["x-mnemom-conversation-id"] = CONV;
-    if (secrets.mnemom) headers["x-mnemom-api-key"] = secrets.mnemom;
+    // x-mnemom-api-key is set per attempt in forward(): the key can be swapped mid-session.
     if (PROVIDER) headers["x-mnemom-provider"] = PROVIDER;
     if (secrets.openai) headers["x-mnemom-egress-key"] = secrets.openai;
     if (CONTRACT_B64) headers["x-mnemom-contract"] = CONTRACT_B64;
@@ -562,20 +751,96 @@ function handle(req, res, viaPlain) {
   const tag = `${req.method} ${viaPlain ? host : ""}${urlPath}`;
   const leg = toGateway ? "gateway" : "upstream";
 
+  // Gateway-leg response fields for the log line.
+  const identOf = (ur) => {
+    if (!toGateway) return "";
+    const goalRev = ur.headers["x-mnemom-goal-revision"];
+    const goalThread = ur.headers["x-mnemom-goal-thread"];
+    const steer = ur.headers["x-mnemom-goal-steer"];
+    return (
+      ` agent=${ur.headers["x-mnemom-agent"] || "-"} verdict=${ur.headers["x-mnemom-goal-verdict"] || "-"}` +
+      (goalRev ? ` goal-rev=${goalRev}` : "") +
+      (goalThread ? ` goal-thread=${goalThread}` : "") +
+      (steer ? ` steer=${steer}` : "")
+    );
+  };
+  // Gateway error bodies are logged (truncated) so a 4xx is diagnosable — unless the body is
+  // compressed, in which case only its encoding + size is useful (`identity` is not a compression).
+  const errEncOf = (ur) => {
+    const enc = ur.headers["content-encoding"];
+    return enc && enc !== "identity" ? enc : "";
+  };
+  const bodyNoteOf = (errEnc, errBody, errBytes) =>
+    errEnc
+      ? ` body=${errEnc} ${errBytes} bytes`
+      : errBody
+        ? " body=" + errBody.slice(0, 1500).replace(/\s+/g, " ")
+        : "";
+
   // Open the upstream request only once we know we are forwarding. `body` is the fully
   // buffered (normalised) gateway body; undefined means stream the client request through.
-  const forward = (body) => {
+  // `retried` marks the one retry after a rejected Mnemom key (see SESSION KEY RENEWAL).
+  const forward = (body, retried = false) => {
+    const usedKey = toGateway ? secrets.mnemom : "";
+    const usedKeyId = keyMeta.id;
+    // Only this proxy states the Mnemom key, and only to the gateway: a client-supplied one is dropped
+    // on every leg, and no upstream other than the gateway door ever sees it.
+    delete headers["x-mnemom-api-key"];
+    if (usedKey) headers["x-mnemom-api-key"] = usedKey;
     const opts = { ...target, method: req.method, headers };
     if (!net.isIP(target.hostname)) opts.servername = target.hostname; // SNI is for names, not IPs
     const up = (toGateway ? https : proto).request(opts, (ur) => {
+      // A 401 for a buffered request may be the key expiring under a long session: hold it back
+      // (nothing has reached the client yet) and decide once the whole error body is in.
+      if (toGateway && ur.statusCode === 401 && usedKey && body !== undefined && !retried) {
+        // Over KEY_401_BODY_MAX it is not the key rejection (and a decompression-bomb guard): it
+        // streams to the client as is (rc-key-401.mjs).
+        const onOverflow = (held) =>
+          log(
+            `${tag} -> ${leg} ${ur.statusCode} ${Date.now() - started}ms${identOf(ur)} body=${held} bytes (over ${KEY_401_BODY_MAX}: not a key rejection)`,
+          );
+        holdBack401(ur, res, {
+          onOverflow,
+          onBody: (raw) => {
+            const ms = Date.now() - started;
+            const errEnc = errEncOf(ur);
+            const answer = () => {
+              if (res.destroyed) return; // the client left while the re-mint was pending
+              res.writeHead(ur.statusCode, ur.headers);
+              res.end(raw);
+              const errBody = errEnc ? "" : raw.toString("utf8", 0, Math.min(raw.length, 1500));
+              log(
+                `${tag} -> ${leg} ${ur.statusCode} ${ms}ms${identOf(ur)}${bodyNoteOf(errEnc, errBody, raw.length)}`,
+              );
+            };
+            if (!isMnemomKeyRejection(raw, ur.headers["content-encoding"])) {
+              answer();
+              return;
+            }
+            const newer = secrets.mnemom !== usedKey;
+            log(
+              `${tag} -> ${leg} 401 ${ms}ms mnemom key id=${usedKeyId} rejected; ${
+                newer
+                  ? `retrying once with id=${keyMeta.id}`
+                  : "asking the launcher for a fresh key"
+              }`,
+            );
+            (newer ? Promise.resolve(true) : requestRemint()).then((ok) => {
+              // A key line never carries an empty key (KEY_RE), so a changed key is a usable one.
+              if (ok && secrets.mnemom !== usedKey && !res.destroyed) {
+                forward(body, true);
+              } else {
+                answer();
+              }
+            });
+          },
+        });
+        return;
+      }
       res.writeHead(ur.statusCode, ur.headers);
-      // Gateway error bodies are logged (truncated) so a 4xx is diagnosable — unless the
-      // body is compressed, in which case only its encoding + size is useful
-      // (`identity` is not a compression).
       let errBody = "",
         errBytes = 0;
-      const enc = ur.headers["content-encoding"];
-      const errEnc = enc && enc !== "identity" ? enc : "";
+      const errEnc = errEncOf(ur);
       if (toGateway && ur.statusCode >= 400) {
         ur.on("data", (c) => {
           errBytes += c.length;
@@ -583,25 +848,12 @@ function handle(req, res, viaPlain) {
         });
       }
       ur.pipe(res);
-      const goalRev = ur.headers["x-mnemom-goal-revision"];
-      const goalThread = ur.headers["x-mnemom-goal-thread"];
-      const steer = ur.headers["x-mnemom-goal-steer"];
-      const ident = toGateway
-        ? ` agent=${ur.headers["x-mnemom-agent"] || "-"} verdict=${ur.headers["x-mnemom-goal-verdict"] || "-"}` +
-          (goalRev ? ` goal-rev=${goalRev}` : "") +
-          (goalThread ? ` goal-thread=${goalThread}` : "") +
-          (steer ? ` steer=${steer}` : "")
-        : "";
       ur.on("end", () => {
-        let bodyNote = "";
-        if (toGateway && ur.statusCode >= 400) {
-          bodyNote = errEnc
-            ? ` body=${errEnc} ${errBytes} bytes`
-            : errBody
-              ? " body=" + errBody.slice(0, 1500).replace(/\s+/g, " ")
-              : "";
-        }
-        log(`${tag} -> ${leg} ${ur.statusCode} ${Date.now() - started}ms${ident}${bodyNote}`);
+        const bodyNote =
+          toGateway && ur.statusCode >= 400 ? bodyNoteOf(errEnc, errBody, errBytes) : "";
+        log(
+          `${tag} -> ${leg} ${ur.statusCode} ${Date.now() - started}ms${identOf(ur)}${bodyNote}${retried ? " (retry)" : ""}`,
+        );
       });
     });
     up.on("error", (e) => {
@@ -681,6 +933,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.34-next.1",
   "description": "Transparent AI agent tracing",
   "type": "module",
   "bin": {
@@ -17,6 +17,7 @@
     "test": "vitest"
   },
   "dependencies": {
+    "@mnemom/aip-verifier": "https://github.com/mnemom/aip/releases/download/aip-verifier-v0.6.0/mnemom-aip-verifier-0.6.0.tgz",
     "@mnemom/policy-engine": "^0.3.0",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",