@mnemom/mnemom 0.17.33 → 0.17.34-next.2

package/dist/rc-proxy.mjs

@@ -64,6 +64,20 @@
 // 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
@@ -90,7 +104,13 @@
 //                                  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)
 //
@@ -107,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;
@@ -197,6 +223,113 @@ if (SUBSCRIPTION) {
 // 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.
@@ -590,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;
@@ -618,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;
@@ -639,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) => {