sentinelayer-cli 0.41.0 → 0.42.0

package/src/net/test-egress-guard.js

@@ -0,0 +1,158 @@
+// Fail-closed network egress guard for test processes.
+//
+// Why: on 2026-09-29 raw unit-test runs on a logged-in developer machine synced
+// tens of thousands of junk sessions to the production API, and a later audit
+// found read paths (fetchSessionFromApi, listSessionsFromApi, pollSessionEvents,
+// ...) that ignore SENTINELAYER_SKIP_REMOTE_SYNC entirely. An env flag that each
+// call site must remember to check is not a safety boundary.
+//
+// SCOPE (stated exactly): this wraps `globalThis.fetch` only. It does not cover
+// node:http/https/net, a separately imported undici, or child tools (git, curl).
+// At the time of writing, src/ makes its network calls through globalThis.fetch
+// (and injected fetchImpl defaults to it).
+//
+// One normalization, validated AND dispatched: every call is converted ONCE with
+// native Request semantics (`new Request(input, init)`, the same conversion fetch
+// itself performs), then that exact Request's URL is checked and that exact
+// Request is what reaches the network. The guard never validates one URL
+// representation and dispatches another (e.g. an object whose .url and
+// toString() disagree, or a getter that answers differently on a second read).
+//
+// Policy, inside a test process:
+// - natively, only numeric loopback: 127.0.0.1 or [::1]. Host names (localhost,
+//   *.test, *.invalid, *.localhost) are refused: a name is not proof of loopback
+//   routing, and tests that use fixture names replace globalThis.fetch with a mock.
+// - redirects in the default "follow" mode are walked manually and EVERY hop is
+//   checked against the same policy. Only 301/302/303/307/308 are followed. A
+//   303, or a 301/302 after POST, becomes GET (body headers dropped); a 307/308
+//   that would re-send a body is refused (use redirect: "manual" in such a test).
+//   On an origin change Authorization/Proxy-Authorization/Cookie are dropped, as
+//   native fetch does. Explicit "manual"/"error" modes pass through unchanged.
+// - data: and blob: never leave the process and are allowed.
+//
+// Activation: NODE_TEST_CONTEXT (set by `node --test` for test files) or
+// SENTINELAYER_TEST_EGRESS_GUARD=1 (set by tests/setup-env.mjs and inherited by
+// spawned children). Production processes set neither, so there it is a no-op.
+// A test that installs its own `globalThis.fetch` mock replaces the wrapper, and
+// restoring the saved original puts the guard back.
+
+const GUARD_MARKER = Symbol.for("sentinelayer.testEgressGuard");
+const NUMERIC_LOOPBACK_HOSTS = new Set(["127.0.0.1", "[::1]"]);
+const MAX_REDIRECTS = 20;
+// Only these are redirects (as in native fetch); a 300/304/305/306 with a Location header is returned as-is.
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+// Dropped when a redirect changes origin (as native undici does), so credentials never cross origins.
+const CROSS_ORIGIN_STRIPPED_HEADERS = ["authorization", "proxy-authorization", "cookie"];
+// Dropped when a redirect turns the request into a body-less GET (fetch spec request-body-header names).
+const BODY_HEADERS = ["content-type", "content-length", "content-encoding", "content-language", "content-location"];
+
+export class TestEgressBlockedError extends Error {
+  constructor(target, detail = "") {
+    super(
+      `test egress blocked: ${target}${detail ? ` (${detail})` : ""} ` +
+        "(tests may only reach 127.0.0.1 or [::1] natively; mock fetch for anything else)",
+    );
+    this.name = "TestEgressBlockedError";
+    this.code = "TEST_EGRESS_BLOCKED";
+  }
+}
+
+export function isTestEgressGuardRequested(env = process.env) {
+  return Boolean(String(env.NODE_TEST_CONTEXT || "").trim()) ||
+    String(env.SENTINELAYER_TEST_EGRESS_GUARD || "").trim() === "1";
+}
+
+// Policy on an already-canonical URL string (a Request's .url, or a redirect target resolved with new URL()).
+export function isAllowedTestDestination(url) {
+  let parsed;
+  try {
+    parsed = new URL(String(url));
+  } catch {
+    return false; // unparseable: refuse rather than guess
+  }
+  if (parsed.protocol === "data:" || parsed.protocol === "blob:") return true; // never leaves the process
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return false;
+  // WHATWG URL canonicalizes IPv4 forms (127.1, 0x7f.0.0.1) to dotted decimal.
+  return NUMERIC_LOOPBACK_HOSTS.has(parsed.hostname.toLowerCase());
+}
+
+const blockedForTests = [];
+
+export function getBlockedTestEgress() {
+  return blockedForTests.slice();
+}
+
+function originOf(url) {
+  try {
+    return new URL(String(url)).origin;
+  } catch {
+    return "<unparseable>";
+  }
+}
+
+function block(url, detail) {
+  const origin = originOf(url);
+  blockedForTests.push(origin);
+  return new TestEgressBlockedError(origin, detail);
+}
+
+export function installTestEgressGuard({ env = process.env, force = false } = {}) {
+  if (!force && !isTestEgressGuardRequested(env)) return false;
+  const nativeFetch = globalThis.fetch;
+  const NativeRequest = globalThis.Request;
+  if (typeof nativeFetch !== "function" || typeof NativeRequest !== "function") return false;
+  if (nativeFetch[GUARD_MARKER]) return true; // idempotent
+
+  async function followChecked(thisArg, request, hops) {
+    const response = await nativeFetch.call(thisArg, new NativeRequest(request, { redirect: "manual" }));
+    const location = response.headers.get("location");
+    if (!REDIRECT_STATUSES.has(response.status) || location === null) return response;
+    let next;
+    try {
+      next = new URL(location, request.url).href;
+    } catch {
+      throw block(location, "unparseable redirect location");
+    }
+    if (!isAllowedTestDestination(next)) throw block(next, `redirect hop ${hops + 1}`);
+    if (hops + 1 > MAX_REDIRECTS) throw new TypeError("test fetch: too many redirects");
+    const method = request.method.toUpperCase();
+    const toGet = response.status === 303 ? method !== "HEAD"
+      : (response.status === 301 || response.status === 302) && method === "POST";
+    if (!toGet && request.body !== null && method !== "GET" && method !== "HEAD") {
+      throw block(next, `redirect ${response.status} would re-send a request body; use redirect: "manual"`);
+    }
+    const headers = new Headers(request.headers);
+    if (new URL(next).origin !== new URL(request.url).origin) {
+      for (const name of CROSS_ORIGIN_STRIPPED_HEADERS) headers.delete(name);
+    }
+    if (toGet) {
+      for (const name of BODY_HEADERS) headers.delete(name);
+    }
+    const nextRequest = new NativeRequest(next, {
+      method: toGet ? "GET" : method,
+      headers,
+      signal: request.signal,
+      redirect: "manual",
+    });
+    return followChecked(thisArg, nextRequest, hops + 1);
+  }
+
+  const guarded = function guardedTestFetch(input, init) {
+    let request;
+    try {
+      request = new NativeRequest(input, init); // the ONE conversion; exactly what fetch would do
+    } catch (error) {
+      return Promise.reject(error); // the same TypeError native fetch would raise
+    }
+    if (!isAllowedTestDestination(request.url)) return Promise.reject(block(request.url));
+    if (request.redirect !== "follow") return nativeFetch.call(this, request);
+    return followChecked(this, request, 0);
+  };
+  Object.defineProperty(guarded, GUARD_MARKER, { value: true });
+  globalThis.fetch = guarded;
+  return true;
+}
+
+export function isTestEgressGuardInstalled() {
+  return Boolean(typeof globalThis.fetch === "function" && globalThis.fetch[GUARD_MARKER]);
+}

package/src/review/investor-dd-orchestrator.js

@@ -352,10 +352,18 @@ export async function runInvestorDd({
 
   const streamPath = path.join(artifactBase, "stream.ndjson");
   const streamHandle = await fsp.open(streamPath, "w");
+  let streamClosePromise = null;
+
+  const closeStream = () => {
+    streamClosePromise ??= streamHandle.close();
+    return streamClosePromise;
+  };
 
   const emit = (event) => {
     const enriched = { ...event, at: new Date().toISOString(), runId };
-    streamHandle.write(`${JSON.stringify(enriched)}\n`).catch(() => {});
+    if (!streamClosePromise) {
+      streamHandle.write(`${JSON.stringify(enriched)}\n`).catch(() => {});
+    }
     try {
       onEvent(enriched);
     } catch {
@@ -363,6 +371,7 @@ export async function runInvestorDd({
     }
   };
 
+  try {
   const startTime = Date.now();
   emit({ type: "investor_dd_start", rootPath, personas });
 
@@ -593,7 +602,7 @@ export async function runInvestorDd({
   await writeJson(path.join(artifactBase, "progress.json"), ddProgress);
   await writeJson(path.join(artifactBase, "summary.json"), summary);
 
-  await streamHandle.close();
+  await closeStream();
 
   const artifactFiles = await fsp.readdir(artifactBase);
   const manifest = {};
@@ -624,4 +633,7 @@ export async function runInvestorDd({
   }
 
   return runResult;
+  } finally {
+    await closeStream();
+  }
 }

package/src/session/admission-auth.js

@@ -0,0 +1,312 @@
+// admission-auth.js — which credential a session command runs on.
+//
+// An admitted agent must act with ITS admission credential: room-scoped, expiring,
+// revocable, and limited to what the owner approved. The human's own token is
+// broader (every room they belong to, owner rights where they have them), so
+// quietly falling back to it would let an agent step around its grant.
+//
+// A command that knows its (session, agent) wraps its work in withAgentAdmission:
+//
+//   - nothing stored for that pair  -> the legacy path, unchanged (human token)
+//   - a live credential             -> every session API call made inside the
+//                                      callback resolves to that credential, sent
+//                                      only to the API that issued it
+//   - a tombstone (expired, malformed, bound elsewhere) -> refused before any
+//                                      request is made; never treated as absence
+//
+// The scope is an AsyncLocalStorage context (src/auth/admission-scope.js) that
+// resolveActiveAuthSession consults first. It therefore covers every helper a
+// command calls, however deep, and every credential lookup, not only the session
+// transport's.
+// A revoked credential looks live here; the API refuses it (401) and the command
+// fails. There is no retry with another credential anywhere on this path.
+
+import path from "node:path";
+import process from "node:process";
+
+import { admittedAgentScope } from "../auth/admission-scope.js";
+import { readAdmissionCredentialState } from "./admission.js";
+
+export class AdmissionCredentialRefused extends Error {
+  constructor(message, { reason, sessionId, agentId } = {}) {
+    super(message);
+    this.name = "AdmissionCredentialRefused";
+    this.code = "ADMISSION_CREDENTIAL_REFUSED";
+    this.reason = reason;
+    this.sessionId = sessionId;
+    this.agentId = agentId;
+  }
+}
+
+const REFUSAL_HINT = {
+  expired: "its admission has expired",
+  malformed: "its stored admission credential is unreadable",
+  bound_to_another_session_or_agent: "its stored admission credential names a different session or agent",
+  no_issuing_authority: "its stored admission credential does not record the API that issued it",
+};
+
+/**
+ * THE canonical agent id: exactly what every session command acts as. Commands
+ * canonicalise through this (normalizeAgentId delegates here), so the identity that
+ * authorises and the identity that executes are computed by one function.
+ */
+export function canonicalAgentId(value) {
+  return String(value ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/**
+ * Refuse, before any I/O, an agent id whose canonical form is a DIFFERENT identity than
+ * its spelling (case folding aside): "a:b" would act as "a-b", a separate identity with
+ * its own key and credential. Two spellings are never silently aliased.
+ */
+export function assertCanonicalAgentId(value, source) {
+  const raw = String(value ?? "").trim();
+  if (!raw) return;
+  const canonical = canonicalAgentId(raw);
+  if (canonical !== raw.toLowerCase()) {
+    throw new AdmissionCredentialRefused(
+      `${source} "${raw}" is not a canonical agent id: commands would act as "${canonical || "(none)"}", ` +
+        `a different identity. Use the canonical spelling.`,
+      { reason: "non_canonical_agent_id" }
+    );
+  }
+}
+
+// Options whose value decides WHICH identity, and so which credential, a command
+// runs as. Given more than once they are ambiguous (Commander keeps the LAST value),
+// so they are refused outright rather than guessed at.
+const IDENTITY_OPTIONS = ["--agent", "--session", "--id", "--path"];
+
+// Options end at a bare `--`; everything after it is an operand, as Commander reads it.
+function optionTokens(args) {
+  const tokens = args.map((arg) => String(arg ?? ""));
+  const end = tokens.indexOf("--");
+  return end < 0 ? tokens : tokens.slice(0, end);
+}
+
+function optionValue(args, name) {
+  const tokens = optionTokens(args);
+  for (let i = 0; i < tokens.length; i += 1) {
+    const arg = tokens[i];
+    if (arg === name) return String(tokens[i + 1] || "").trim();
+    if (arg.startsWith(`${name}=`)) return arg.slice(name.length + 1).trim();
+  }
+  return "";
+}
+
+/** Refuse a `session` command that gives an identity-deciding option more than once. */
+export function assertUnambiguousIdentityOptions(args = []) {
+  if (String(args[0] || "").trim().toLowerCase() !== "session") return;
+  const tokens = optionTokens(args);
+  for (const name of IDENTITY_OPTIONS) {
+    const count = tokens.filter((t) => t === name || t.startsWith(`${name}=`)).length;
+    if (count > 1) {
+      throw new AdmissionCredentialRefused(
+        `${name} is given ${count} times. It decides which identity and credential this ` +
+          `command runs as, so it may be given at most once.`,
+        { reason: "ambiguous_identity_option" }
+      );
+    }
+  }
+}
+
+// Who `--agent` names, per `session` subcommand ("group sub" for nested groups).
+//   actor   -- the named agent performs the operation: it runs on THAT agent's
+//              admission (or refuses, if what is stored is a tombstone)
+//   target  -- a human acts ON that agent (stop its listener, kill or unregister
+//              it): it stays on the human's own credential, so an owner can always
+//              recover from a misbehaving or expired agent
+//   control -- join: the human's control plane; it scopes its own post-claim steps
+// A `session` subcommand missing from this table fails CLOSED when an admission
+// is stored for its (session, agent): new commands must be classified.
+export const SESSION_AGENT_PRINCIPAL = Object.freeze({
+  say: "actor",
+  "post-agent": "actor",
+  observe: "actor",
+  action: "actor",
+  react: "actor",
+  reply: "actor",
+  comment: "actor",
+  edit: "actor",
+  read: "actor",
+  listen: "actor",
+  pins: "actor",
+  recap: "actor",
+  now: "actor",
+  lock: "actor",
+  unlock: "actor",
+  renew: "actor",
+  guard: "actor",
+  "guard-hook": "actor",
+  "guard-install": "actor",
+  "codex-notify": "actor",
+  daemon: "actor",
+  "checkpoint create": "actor",
+  "checkpoint generate": "actor",
+  "ticket list": "actor",
+  "ticket claim": "actor",
+  "ticket renew": "actor",
+  "ticket release": "actor",
+  "ticket submit": "actor",
+  "ticket events": "actor",
+  kill: "target",
+  "stop-listener": "target",
+  leave: "target",
+  "guard-uninstall": "target",
+  join: "control",
+});
+const SESSION_COMMAND_GROUPS = new Set(["checkpoint", "ticket"]);
+
+async function implicitAgent(sessionId, targetPath, env) {
+  // The same identity the command itself resolves when --agent is omitted
+  // (SENTINELAYER_AGENT_ID, then the sole joined local agent). Imported lazily:
+  // the commands module imports this one.
+  const { resolveSessionSayIdentity } = await import("../commands/session.js");
+  const identity = await resolveSessionSayIdentity({ sessionId, agentId: "", targetPath, env }).catch(() => null);
+  const agentId = String(identity?.agentId || "").trim();
+  return agentId && agentId !== "cli-user" ? agentId : "";
+}
+
+/**
+ * The (session, agent) a `session` command must run as, when this machine holds an
+ * admission for it -- live OR tombstoned -- else null. Used by BOTH the auth gate
+ * and the dispatch choke point in runCli, so the two can never disagree.
+ *
+ * Only ACTOR commands are scoped (see SESSION_AGENT_PRINCIPAL). The agent is
+ * --agent, else SENTINELAYER_AGENT_ID, else the implicit joined identity. A
+ * subcommand outside the table is scoped only if it NAMES an agent with --agent,
+ * and then it refuses (unclassified); otherwise it is a human command. The
+ * session is --session or any positional argument for which an admission is stored:
+ * a credential file is keyed by (session, agent), so a positional that is not a
+ * session can never match one. An unclassified subcommand with a stored admission
+ * throws: it is never silently run on the human token.
+ */
+export async function resolveAgentAdmissionTarget(args = [], { env = process.env, homeDir } = {}) {
+  if (String(args[0] || "").trim().toLowerCase() !== "session") return null;
+  assertUnambiguousIdentityOptions(args);
+  const tokens = args.map((a) => String(a ?? "").trim());
+  const terminator = tokens.indexOf("--");
+  const positional = [
+    ...(terminator < 0 ? tokens : tokens.slice(0, terminator)).slice(1).filter((a) => a && !a.startsWith("-")),
+    ...(terminator < 0 ? [] : tokens.slice(terminator + 1).filter(Boolean)),
+  ];
+  if (!positional.length) return null;
+  // Every `session` subcommand, join included: an identity-changing spelling is refused
+  // before any lookup, dispatch or request.
+  assertCanonicalAgentId(optionValue(args, "--agent"), "--agent");
+  assertCanonicalAgentId(env.SENTINELAYER_AGENT_ID, "SENTINELAYER_AGENT_ID");
+  let command = positional[0].toLowerCase();
+  let rest = positional.slice(1);
+  if (SESSION_COMMAND_GROUPS.has(command) && rest.length) {
+    command = `${command} ${rest[0].toLowerCase()}`;
+    rest = rest.slice(1);
+  }
+  const principal = SESSION_AGENT_PRINCIPAL[command];
+  if (principal === "target" || principal === "control") return null;
+  const flagAgent = optionValue(args, "--agent");
+  // A subcommand outside the table that names NO agent is a human command (archive,
+  // members, ...): it is not agent-attributed, whatever SENTINELAYER_AGENT_ID says.
+  if (!principal && !flagAgent) return null;
+  const explicitAgent = flagAgent || String(env.SENTINELAYER_AGENT_ID || "").trim();
+  const candidates = [optionValue(args, "--session"), optionValue(args, "--id"), ...rest].filter(Boolean);
+  for (const sessionId of candidates) {
+    const targetPath = path.resolve(process.cwd(), optionValue(args, "--path") || ".");
+    const agentId = explicitAgent || (await implicitAgent(sessionId, targetPath, env));
+    if (!agentId) continue;
+    const held = await readAdmissionCredentialState(sessionId, agentId, { homeDir }).catch(() => ({ state: "none" }));
+    if (held.state === "none") continue;
+    if (!principal) {
+      throw new AdmissionCredentialRefused(
+        `\`sl session ${command}\` is not classified as acting as "${agentId}" or on it, and "${agentId}" ` +
+          `holds an admission in session ${sessionId}. Refusing rather than guessing which credential it should use.`,
+        { reason: "unclassified_command", sessionId, agentId }
+      );
+    }
+    return { sessionId, agentId };
+  }
+  return null;
+}
+
+/**
+ * preAction guard: the identity Commander ACTUALLY resolved for this action must be
+ * the one whose admission scope (if any) the dispatch was wrapped in. Computed from
+ * Commander's own resolved options -- counting only values given on the command line,
+ * not defaults such as read's `--agent cli-user` -- so no argv reading of ours can
+ * disagree with execution. A mismatch refuses before the action runs.
+ */
+export async function assertDispatchMatchesScope(actionCommand, { env = process.env, homeDir } = {}) {
+  const names = [];
+  for (let cmd = actionCommand; cmd && cmd.parent; cmd = cmd.parent) names.unshift(cmd.name());
+  if (String(names[0] || "").toLowerCase() !== "session") return;
+  const command = names.slice(1).join(" ").toLowerCase();
+  const principal = SESSION_AGENT_PRINCIPAL[command];
+  const opts = actionCommand.opts();
+  const given = (key) =>
+    actionCommand.getOptionValueSource?.(key) === "cli" ? String(opts[key] ?? "").trim() : "";
+  let actual = null;
+  if (principal === "actor" || (!principal && given("agent"))) {
+    const sessionId = given("session") || given("id") || String(actionCommand.processedArgs?.[0] ?? "").trim();
+    const targetPath = path.resolve(process.cwd(), String(opts.path || "."));
+    const agentId =
+      given("agent") ||
+      String(env.SENTINELAYER_AGENT_ID || "").trim() ||
+      (sessionId ? await implicitAgent(sessionId, targetPath, env) : "");
+    if (sessionId && agentId) {
+      const held = await readAdmissionCredentialState(sessionId, agentId, { homeDir }).catch(() => ({ state: "none" }));
+      if (held.state !== "none") actual = { sessionId, agentId };
+    }
+  }
+  const inForce = currentAdmittedAgent();
+  const key = (pair) => (pair ? `${String(pair.sessionId).toLowerCase()}/${String(pair.agentId).toLowerCase()}` : "none");
+  if (key(actual) !== key(inForce)) {
+    throw new AdmissionCredentialRefused(
+      `Refusing: \`sl session ${command}\` resolved to ${key(actual)} but was dispatched under ` +
+        `${key(inForce)}. Authorization and execution must name the same identity.`,
+      { reason: "scope_mismatch" }
+    );
+  }
+}
+
+/** Run `fn` with the right credential for (sessionId, agentId). See the module header. */
+export async function withAgentAdmission(sessionId, agentId, fn, { homeDir, now } = {}) {
+  const held = await readAdmissionCredentialState(sessionId, agentId, { homeDir, now });
+  if (held.state === "none") return fn({ admitted: false });
+  if (held.state !== "live") {
+    const why = REFUSAL_HINT[held.reason] || `its stored admission is unusable (${held.reason})`;
+    throw new AdmissionCredentialRefused(
+      `Agent "${agentId}" cannot act in session ${sessionId}: ${why}. ` +
+        `It will not fall back to your own credentials. Request a new admission with ` +
+        `\`sl session join ${sessionId} --agent ${agentId} --goal "<what it is here to do>"\`.`,
+      { reason: held.reason, sessionId, agentId }
+    );
+  }
+  const credential = Object.freeze({ ...held.credential });
+  try {
+    return await admittedAgentScope.run(credential, () =>
+      fn({ admitted: true, admissionId: credential.admissionId, agentId: credential.agentId })
+    );
+  } catch (error) {
+    if (error instanceof Error && /\bapi_401\b|not_authenticated/.test(error.message)) {
+      error.message +=
+        ` The API no longer accepts agent "${agentId}"'s admission for this room (revoked, expired,` +
+        ` or outside its grant). It did not fall back to your own credentials.`;
+    }
+    throw error;
+  }
+}
+
+/** The admission this code is running under, without the token, or null. */
+export function currentAdmittedAgent() {
+  const credential = admittedAgentScope.getStore();
+  if (!credential) return null;
+  return {
+    admissionId: credential.admissionId,
+    sessionId: credential.sessionId,
+    agentId: credential.agentId,
+    expiresAt: credential.expiresAt,
+  };
+}

package/src/session/admission-preimage.js

@@ -0,0 +1,90 @@
+// admission-preimage.js — the bytes an agent signs to claim an admission.
+//
+// This MUST reproduce sentinelayer-api src/services/canonical_preimage.py byte for
+// byte, or every claim signature fails to verify. The API SPEC ("Agent Passport
+// Contract", preimage construction) is normative:
+//
+//   ASCII(domain) || 0x00 || JCS( select(payload, fields) with every string NFC )
+//
+// It deliberately COMPOSES rather than re-implements. JSON encoding is the one JCS
+// encoder this CLI already has (src/engram/canonical.js); the NFC step is applied
+// here, BEFORE encoding, because that is where the API format puts it. The engram
+// encoder must stay non-normalising (content addressing needs NFC != NFD), so the
+// normalisation belongs to this format, not to the shared encoder.
+//
+// Rules copied from the Python, each a refusal rather than a coercion:
+//   - the domain is required and ASCII
+//   - fields is a non-empty SET: the caller's order is ignored
+//   - a named field absent from the payload is an error, never an omission
+//   - object keys are ASCII, so UTF-16 and code-point key order agree
+//   - no floats: integers must be safe integers (enforced by the encoder)
+//   - every key is an OWN data property, "__proto__" included. Objects built here
+//     have a null prototype, so assigning that key defines it rather than invoking
+//     the legacy prototype setter (which would silently drop it from the bytes).
+//
+// Conformance: tests/fixtures/admission/canonical-preimage-vectors-v1.json is
+// generated FROM the Python implementation; tests/unit.admission-preimage.test.mjs
+// asserts these bytes match every vector exactly.
+
+import { canonicalize } from "../engram/canonical.js";
+
+const ASCII = /^[\x00-\x7f]*$/;
+
+export class CanonicalPreimageError extends TypeError {}
+
+function nfcDeep(value, path) {
+  if (typeof value === "string") return value.normalize("NFC");
+  if (value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map((item, i) => nfcDeep(item, `${path}[${i}]`));
+  const out = Object.create(null);
+  for (const [key, item] of Object.entries(value)) {
+    if (!ASCII.test(key)) {
+      throw new CanonicalPreimageError(`object keys must be ASCII at ${path}: ${JSON.stringify(key)}`);
+    }
+    out[key] = nfcDeep(item, `${path}.${key}`);
+  }
+  return out;
+}
+
+/** The exact bytes to sign or verify, as a Buffer. */
+export function canonicalPreimage(payload, { domain, fields }) {
+  const normalizedDomain = String(domain ?? "").normalize("NFC").trim();
+  if (!normalizedDomain) throw new CanonicalPreimageError("domain is required");
+  if (!ASCII.test(normalizedDomain)) throw new CanonicalPreimageError("domain must be ASCII");
+  if (!Array.isArray(fields) || fields.length === 0) {
+    throw new CanonicalPreimageError(
+      "fields is required: an empty selection would sign nothing while appearing to sign a document"
+    );
+  }
+  if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new CanonicalPreimageError("payload must be an object");
+  }
+  const selected = Object.create(null);
+  const missing = [];
+  for (const name of fields) {
+    if (typeof name !== "string" || !ASCII.test(name)) {
+      throw new CanonicalPreimageError(`field names must be ASCII strings: ${JSON.stringify(name)}`);
+    }
+    if (!Object.prototype.hasOwnProperty.call(payload, name)) {
+      missing.push(name);
+      continue;
+    }
+    selected[name] = payload[name];
+  }
+  if (missing.length) {
+    throw new CanonicalPreimageError(
+      `fields absent from payload cannot be covered: ${missing.sort().join(", ")}`
+    );
+  }
+  let body;
+  try {
+    body = canonicalize(nfcDeep(selected, "$"));
+  } catch (error) {
+    throw new CanonicalPreimageError(error.message);
+  }
+  return Buffer.concat([
+    Buffer.from(normalizedDomain, "ascii"),
+    Buffer.from([0x00]),
+    Buffer.from(body, "utf8"),
+  ]);
+}