@rightkit/release 0.6.8 → 0.6.11

package/snapshot-git.mjs

@@ -0,0 +1,166 @@
+// The sealed git invocation of the gate (item 5 D3, signed/item5-sage-decisions-2.md; docs/GATE-CONTRACT.md §1 "exact snapshot",
+// rightkit#1255). The snapshot's identity and every object read the gate makes depend on the commit's objects and the snapshot's
+// bytes ONLY. The checkout's git configuration cannot reach them: no `filter.*` clean or smudge driver, no core.autocrlf or eol
+// conversion, no attributes from the checkout's `.git/info/attributes` or any attributes file, no hooks, no system, global or user
+// configuration, no replace refs, no inherited GIT_* variable. (Probes P3a to P3d of the decision: today's unsealed invocation ran a
+// checkout filter and hid a byte tamper and a line-ending tamper behind the commit's own id.)
+//
+// ONE runner serves every identity operation: `<sha>^{tree}`, `ls-tree`, `cat-file --batch`, `read-tree`, `add -A`, `write-tree` and
+// the 5.09d ignore oracle (`check-ignore`). Only resolving a revision NAME to a commit runs against the checkout's own git directory
+// (it needs the refs), under the same environment plus GIT_NO_REPLACE_OBJECTS (`discoveryGit`).
+//
+// The private git directory T (mkdtemp, mode 0700, outside the checkout and the snapshot, removed afterwards) holds:
+//   HEAD `ref: refs/heads/none`; an empty refs/; objects/info/alternates naming `<checkout git common dir>/objects` (so every read is
+//   still against the checkout's object database, and every object `add` and `write-tree` writes lands in T, never in the
+//   checkout); `config` with only core.repositoryformatversion and core.bare (plus extensions.objectFormat for SHA-256);
+//   info/attributes SEALED_ATTRIBUTES (the highest-precedence attribute source); an empty info/exclude (so the only ignore rules are
+//   the commit's own `.gitignore` files); an empty hooks/; an empty file `empty`.
+// The environment is built from nothing (sealedEnv). The `-c` flags are SEALED_CONFIG, in this order (sealedConfigArgs).
+//
+// The exact flags live in SEALED_GIT, one frozen constant: the broker (rustright check_admission.rs `sealed_git()`) implements the
+// identical invocation, and the three-way compare of row 5.11 cites this constant.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "./background-process.mjs";
+
+/** info/attributes of T, the highest-precedence attribute source: nothing converts, rewrites, identifies or re-encodes a byte. */
+export const SEALED_ATTRIBUTES = "* -text -ident -filter -working-tree-encoding !eol\n";
+
+/** The `-c key=value` list, in order. `@FILEMODE` is true on darwin and linux and false on win32 (NTFS has no exec bit: a 100755 lives in the seeded index, signed 5.04); `@T/x` is T/x. */
+export const SEALED_CONFIG = Object.freeze([
+  ["core.autocrlf", "false"], ["core.safecrlf", "false"], ["core.eol", "lf"],
+  ["core.fileMode", "@FILEMODE"], ["core.symlinks", "true"],
+  ["core.ignoreCase", "false"], ["core.precomposeUnicode", "false"],
+  ["core.attributesFile", "@T/empty"], ["core.excludesFile", "@T/empty"], ["core.hooksPath", "@T/hooks"],
+  ["core.fsmonitor", "false"], ["core.untrackedCache", "false"], ["core.splitIndex", "false"],
+  ["core.sparseCheckout", "false"], ["index.sparse", "false"], ["core.useReplaceRefs", "false"],
+].map((pair) => Object.freeze(pair)));
+
+/** Environment variables the invocation sets to a fixed value; the others (PATH, HOME, XDG_CONFIG_HOME, LC_ALL, GIT_CONFIG_GLOBAL, GIT_INDEX_FILE, GIT_DIR, GIT_WORK_TREE, and on Windows SystemRoot, WINDIR, PATHEXT, TEMP, TMP) are built by sealedEnv. */
+export const SEALED_ENV_FIXED = Object.freeze({
+  GIT_CONFIG_NOSYSTEM: "1", GIT_ATTR_NOSYSTEM: "1", GIT_NO_REPLACE_OBJECTS: "1", GIT_NO_LAZY_FETCH: "1", GIT_TERMINAL_PROMPT: "0", GIT_OPTIONAL_LOCKS: "0",
+});
+
+/** The sealed invocation, whole: what the three-way compare (5.11) and the broker's `sealed_git()` cite. */
+export const SEALED_GIT = Object.freeze({
+  attributes: SEALED_ATTRIBUTES,
+  config: SEALED_CONFIG,
+  envFixed: SEALED_ENV_FIXED,
+  envBuilt: Object.freeze(["PATH", "HOME", "XDG_CONFIG_HOME", "LC_ALL", "GIT_CONFIG_GLOBAL", "GIT_INDEX_FILE", "GIT_DIR", "GIT_WORK_TREE", "SystemRoot", "WINDIR", "PATHEXT", "TEMP", "TMP"]),
+  layout: Object.freeze({ head: "ref: refs/heads/none\n", alternates: "<git common dir>/objects", excludeIsEmpty: true, hooksIsEmpty: true, workingDirectory: "the snapshot" }),
+  gitVersionNote: "GIT_NO_LAZY_FETCH needs git 2.45 or later; older git ignores it",
+});
+
+const MAX_BUFFER = 1 << 30;
+const WINDOWS_ENV = ["SystemRoot", "WINDIR", "PATHEXT"];
+
+/** `-c k=v ...` for T and `platform`, in SEALED_CONFIG's order. */
+export function sealedConfigArgs(T, platform = process.platform) {
+  const out = [];
+  for (const [key, value] of SEALED_CONFIG) {
+    const v = value === "@FILEMODE" ? (platform === "win32" ? "false" : "true") : value.startsWith("@T/") ? path.join(T, value.slice(3)) : value;
+    out.push("-c", `${key}=${v}`);
+  }
+  return out;
+}
+
+const fromEnv = (base, name) => { const k = Object.keys(base).find((x) => x.toLowerCase() === name.toLowerCase()); return k === undefined ? undefined : base[k]; };
+
+/** The environment for git: built from nothing, never inherited. `T` is the private git directory (or the discovery home), `snapshot` the work tree. */
+export function sealedEnv(T, { snapshot, platform = process.platform, base = process.env, gitDir = T, index = true } = {}) {
+  const env = {};
+  const p = fromEnv(base, "PATH");
+  if (p !== undefined) env.PATH = p;
+  if (platform === "win32") {
+    for (const name of WINDOWS_ENV) { const v = fromEnv(base, name); if (v !== undefined) env[name] = v; }
+    env.TEMP = T; env.TMP = T;
+  }
+  env.HOME = T; env.XDG_CONFIG_HOME = T; env.LC_ALL = "C";
+  env.GIT_CONFIG_GLOBAL = path.join(T, "empty");
+  Object.assign(env, SEALED_ENV_FIXED);
+  if (index) env.GIT_INDEX_FILE = path.join(T, "index");
+  if (gitDir) env.GIT_DIR = gitDir;
+  if (snapshot) env.GIT_WORK_TREE = snapshot;
+  return env;
+}
+
+/** Creates T. `commonDir` (the checkout's git common directory) wires the object database; `objectFormat` is "sha1" or "sha256". */
+export function createSealedGitDir({ commonDir, objectFormat = "sha1" } = {}) {
+  const T = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "rk-sealed-git-")));
+  try {
+    for (const d of ["refs", path.join("objects", "info"), "info", "hooks"]) fs.mkdirSync(path.join(T, d), { recursive: true });
+    fs.writeFileSync(path.join(T, "HEAD"), SEALED_GIT.layout.head);
+    fs.writeFileSync(path.join(T, "config"), `[core]\n\trepositoryformatversion = ${objectFormat === "sha256" ? 1 : 0}\n\tbare = false\n${objectFormat === "sha256" ? "[extensions]\n\tobjectFormat = sha256\n" : ""}`);
+    fs.writeFileSync(path.join(T, "info", "attributes"), SEALED_ATTRIBUTES);
+    fs.writeFileSync(path.join(T, "info", "exclude"), "");
+    fs.writeFileSync(path.join(T, "empty"), "");
+    if (commonDir) fs.writeFileSync(path.join(T, "objects", "info", "alternates"), `${commonDir}/objects\n`);
+  } catch (error) {
+    fs.rmSync(T, { recursive: true, force: true });
+    throw error;
+  }
+  return T;
+}
+
+const why = (r, args) => `git ${args.filter((a) => a !== "-c" && !/^(core|index)\./.test(a)).join(" ")}: ${r.error ? r.error.message : String(r.stderr ?? "").trim() || `exit ${r.status}`}`;
+
+/**
+ * Runs `fn(git)` with a fresh T; `git.run(args, { input, binary, cwd })` returns the spawn result, `git.ok(...)` its stdout or throws an
+ * Error naming the command. The working directory is `snapshot` when given, else T. T is removed afterwards.
+ */
+export function withSealedGit({ commonDir, objectFormat, snapshot, platform = process.platform } = {}, fn) {
+  const T = createSealedGitDir({ commonDir, objectFormat });
+  const env = sealedEnv(T, { snapshot, platform });
+  const prefix = sealedConfigArgs(T, platform);
+  const run = (args, { input, binary = false, cwd } = {}) => spawnSync("git", [...prefix, ...args], { cwd: cwd ?? snapshot ?? T, env, input, maxBuffer: MAX_BUFFER, ...(binary ? {} : { encoding: "utf8" }) });
+  const ok = (args, options) => { const r = run(args, options); if (r.error || r.status !== 0) throw new Error(why(r, args)); return r.stdout; };
+  try { return fn({ run, ok, T, env }); } finally { fs.rmSync(T, { recursive: true, force: true }); }
+}
+
+// --- discovery: finding a repository and resolving a revision NAME, the only reads that need the checkout's own git directory -------------
+
+let home = null;
+/** One empty home directory per process for discovery runs, removed at exit. */
+function discoveryHome() {
+  if (home && fs.existsSync(home)) return home;
+  home = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "rk-git-home-")));
+  fs.writeFileSync(path.join(home, "empty"), "");
+  const mine = home;
+  process.once("exit", () => { try { fs.rmSync(mine, { recursive: true, force: true }); } catch { /* best effort */ } });
+  return home;
+}
+
+/** git run in `cwd` against the checkout's own repository (found from `cwd`), under the sealed environment (no GIT_DIR, no index) plus GIT_NO_REPLACE_OBJECTS. Returns the spawn result. */
+export function discoveryRun(cwd, args, { platform = process.platform, input } = {}) {
+  const env = sealedEnv(discoveryHome(), { platform, gitDir: null, index: false });
+  return spawnSync("git", args, { cwd, env, input, encoding: "utf8", maxBuffer: MAX_BUFFER });
+}
+/** As discoveryRun, returning trimmed-by-caller stdout or throwing an Error naming the command. */
+export function discoveryGit(cwd, args, options) {
+  const r = discoveryRun(cwd, args, options);
+  if (r.error || r.status !== 0) throw new Error(why(r, args));
+  return r.stdout;
+}
+
+const infoCache = new Map();
+/** `{ commonDir, objectFormat }` of the repository `checkout` belongs to, found by discovery and cached per canonical path. */
+export function sealedRepoInfo(checkout) {
+  let key;
+  try { key = fs.realpathSync.native(checkout); } catch { key = path.resolve(checkout); }
+  const cached = infoCache.get(key);
+  if (cached && fs.existsSync(path.join(cached.commonDir, "objects"))) return cached;
+  let common;
+  try { common = discoveryGit(key, ["rev-parse", "--path-format=absolute", "--git-common-dir"]).trim(); }
+  catch { common = path.resolve(key, discoveryGit(key, ["rev-parse", "--git-common-dir"]).trim()); }
+  const info = { commonDir: common, objectFormat: discoveryGit(key, ["rev-parse", "--show-object-format"]).trim() || "sha1" };
+  infoCache.set(key, info);
+  return info;
+}
+
+/** A single sealed git command against `checkout`'s object database (T is made and removed around it). Returns the spawn result. */
+export function sealedRun(checkout, args, options = {}) {
+  const info = options.repo ?? sealedRepoInfo(checkout);
+  return withSealedGit({ ...info, snapshot: options.snapshot }, (git) => git.run(args, options));
+}

package/snapshot-request.mjs

@@ -0,0 +1,363 @@
+// The gate's half of a broker snapshot build (joint plan step 4d; GATE-CONTRACT "Broker interface"; the reader is RustRight's
+// rustright-cli shims.rs `snapshot_carrier`, the verifier rustright-protocol attestation.rs `verify_receipt`).
+//
+// For each `rustright cargo` request that builds the commit snapshot on a broker host the gate:
+//   1. picks a fresh nonce (RIGHTKIT_ATTEST_NONCE: an attested request; the carrier must carry the same nonce);
+//   2. writes the carrier `rightkit.snapshot-request/1` as an owner-only file under `<control root>/snapshot-requests/` (the
+//      directory the client accepts, never a link) and points RIGHTKIT_SNAPSHOT_REQUEST at it as `{"path","sha256"}` (at most
+//      4096 bytes; the file at most 4 MiB). The carrier binds the commit and tree, the snapshot and its expected tree, the
+//      declared inputs, the build-ownership handle, the cargo working directory (primaryCwd) and sha256 of the canonical cargo
+//      argv (without `cargo`), so it cannot be replayed onto another request;
+//   3. after the run, verifies the signed receipt: the provenance signature against this host's enrolled pins (never from the
+//      receipt), the job id, the nonce, the signed result (SUCCEEDED, exit 0), the request digest it recomputes over the EXTENDED core (the base core plus commit,
+//      snapshot, declaredInputs and ownership), and the signed snapshotEvidence: the receipt's copies equal the signed ones,
+//      the commit and handle are the carrier's, and the snapshot held the expected tree at START and at exit.
+// The carrier is set only on that one cargo invocation and is removed after it; nothing the gate exports carries it.
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { canonicalJson, ProvenanceError, verifyProvenance } from "./provenance-verify.mjs";
+
+export const SNAPSHOT_REQUEST_SCHEMA = "rightkit.snapshot-request/1";
+export const SNAPSHOT_REQUEST_ENV = "RIGHTKIT_SNAPSHOT_REQUEST";
+export const ATTEST_NONCE_ENV = "RIGHTKIT_ATTEST_NONCE";
+export const REQUEST_ID_FILE_ENV = "RIGHTKIT_REQUEST_ID_FILE";
+export const REQUEST_REF_SCHEMA = "rustright.request-ref.v1";
+export const DESCRIPTOR_MAX_BYTES = 4096;
+export const CARRIER_MAX_BYTES = 4 * 1024 * 1024;
+/** rustright-cli shims.rs MANAGED_RUST_ENVIRONMENT_KEYS: what the client records as `observedEnv` for a cargo request. */
+export const MANAGED_RUST_ENVIRONMENT_KEYS = Object.freeze([
+  "CARGO_HOME", "CARGO_TARGET_DIR", "CARGO_BUILD_TARGET", "CARGO_BUILD_TARGET_DIR", "CARGO_BUILD_BUILD_DIR", "CARGO_BUILD_RUSTC",
+  "CARGO_BUILD_RUSTDOC", "CARGO_BUILD_RUSTC_WRAPPER", "CARGO_BUILD_RUSTC_WORKSPACE_WRAPPER", "CARGO_BUILD_RUSTFLAGS",
+  "CARGO_ENCODED_RUSTFLAGS", "CARGO_INSTALL_ROOT", "RUSTUP_HOME", "RUSTC", "RUSTDOC", "RUSTFLAGS", "RUSTDOCFLAGS", "RUSTC_WRAPPER",
+  "RUSTC_WORKSPACE_WRAPPER",
+]);
+/** The fields the broker copies onto the receipt and signs in payload.snapshotEvidence (attestation.rs). */
+export const SNAPSHOT_EVIDENCE_FIELDS = Object.freeze(["requestId", "brokerVersion", "executor", "commit", "snapshot", "declaredInputDigests", "ownership", "outputDir"]);
+/** The stage evidence the broker signs in payload.stageEvidence and copies onto the receipt (attestation.rs STAGE_EVIDENCE_FIELDS). */
+export const STAGE_EVIDENCE_FIELDS = Object.freeze(["freshness", "attribution", "toolchain"]);
+const SIGNED_TOP_LEVEL_FIELDS = Object.freeze(["verdict", "refreshed", "exit", "signal", "timingsMs", "diagnosticsPath"]);
+const TIMING_KEYS =Object.freeze(["admission", "queue", "bind", "cargo", "afterExitBind", "diagnostics"]);
+/** `<toolchain>|cargo:<sha256>|rustc:<sha256>` (rustright toolchain_identity). */
+const TOOLCHAIN_FORMAT = /^[^|\s][^|]*\|cargo:[0-9a-f]{64}\|rustc:[0-9a-f]{64}$/;
+
+/** The compile-class cargo commands (and their aliases): the ones whose receipt carries attribution and toolchain. */
+export const COMPILE_CLASS_COMMANDS = Object.freeze(["check", "clippy", "build", "doc", "rustc", "test", "b", "c", "t", "d"]);
+const GLOBAL_VALUE_OPTIONS = new Set(["--color", "--explain"]);
+
+/** The cargo subcommand of an argv (without `cargo`): after an optional `+toolchain` and the global options, before `--`; null when there is none. */
+export function cargoSubcommandOf(argv) {
+  const words = [...argv];
+  for (let i = words[0]?.startsWith("+") ? 1 : 0; i < words.length; i += 1) {
+    const w = words[i];
+    if (w === "--") return null;
+    if (GLOBAL_VALUE_OPTIONS.has(w)) { i += 1; continue; }
+    if (w.startsWith("-")) continue;
+    return w;
+  }
+  return null;
+}
+export const isCompileClass = (argv) => COMPILE_CLASS_COMMANDS.includes(cargoSubcommandOf(argv));
+
+/** Where the gate's declared compile inputs are listed, as read from the snapshot (GATE-CONTRACT "Request"; the broker's COMPILE_INPUTS). */
+export const COMPILE_INPUTS = ".rightkit/compile-inputs.json";
+export const MAX_DECLARATION_BYTES = 1024 * 1024;
+const MAX_INPUT_FILES = 200_000;
+const MAX_INPUT_BYTES = 4 * 1024 * 1024 * 1024;
+
+export class SnapshotRequestError extends Error {
+  constructor(code, message) { super(message); this.name = "SnapshotRequestError"; this.code = code; }
+}
+const fail = (code, message) => { throw new SnapshotRequestError(code, message); };
+const sha256 = (data) => crypto.createHash("sha256").update(data).digest("hex");
+const objectId = (s) => typeof s === "string" && /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(s);
+
+/** A fresh attestation nonce: 64 lowercase hex characters. */
+export const freshNonce = () => crypto.randomBytes(32).toString("hex");
+
+/** sha256 of the canonical JSON of the cargo argv (without `cargo`), as the client computes it. */
+export const argvSha256 = (argv) => sha256(canonicalJson([...argv]));
+
+/**
+ * The managed Rust variables the client will report as observedEnv, from the environment the gate runs it with. RustRight's
+ * capture_managed_rust_environment (shims.rs) matches the name case-insensitively on every platform and keeps the key exactly as
+ * spelled (`Cargo_Home` stays `Cargo_Home`), so the digest binds that spelling. On Windows the child sees only one of several
+ * names that differ by case: Node passes the first in sorted order (child_process "env" on Windows), so the rest are not observed.
+ */
+export function observedEnvOf(env, platform = process.platform) {
+  const out = {};
+  const entries = Object.entries(env ?? {});
+  if (platform === "win32") entries.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  const seen = new Set();
+  for (const [key, value] of entries) {
+    const upper = key.toUpperCase();
+    if (platform === "win32") { if (seen.has(upper)) continue; seen.add(upper); }
+    if (MANAGED_RUST_ENVIRONMENT_KEYS.includes(upper) && typeof value === "string") out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * Writes the carrier for one cargo request and returns `{ file, sha256, descriptor, carrier, env }`; `env` is what that one
+ * invocation adds (carrier descriptor, nonce, request-id file). Refuses before writing anything the reader would refuse.
+ */
+export function writeSnapshotRequest({ controlRoot, commit, snapshot, declaredInputs = [], handle, primaryCwd, argv, nonce = freshNonce(), requestIdFile, uuid = crypto.randomUUID }) {
+  if (!objectId(commit?.sha) || !objectId(commit?.tree)) fail("invalid", "commit sha and tree must be full lowercase object ids");
+  if (!snapshot?.path || !path.isAbsolute(snapshot.path) || snapshot.expectedTree !== commit.tree) fail("invalid", "the snapshot needs an absolute path and the commit's tree as expectedTree");
+  if (typeof handle !== "string" || !handle.trim()) fail("invalid", "the build-ownership handle is missing");
+  if (!primaryCwd || !path.isAbsolute(primaryCwd)) fail("invalid", "primaryCwd must be the cargo request's absolute working directory");
+  if (!Array.isArray(argv) || !argv.every((a) => typeof a === "string")) fail("invalid", "argv must be the cargo arguments (without cargo)");
+  if (typeof nonce !== "string" || !/^[0-9a-f]{64,128}$/.test(nonce)) fail("invalid", "the nonce must be 64 to 128 lowercase hex characters");
+  if (!Array.isArray(declaredInputs) || declaredInputs.some((p) => typeof p !== "string" || !p || path.isAbsolute(p) || path.posix.isAbsolute(p))) fail("invalid", "declared inputs must be relative paths");
+  if (!controlRoot || !path.isAbsolute(controlRoot)) fail("invalid", "the control root must be absolute");
+  const dir = path.join(controlRoot, "snapshot-requests");
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const meta = fs.lstatSync(dir);
+  if (meta.isSymbolicLink() || !meta.isDirectory()) fail("invalid", `${dir} is not a real directory`);
+  const carrier = {
+    schema: SNAPSHOT_REQUEST_SCHEMA,
+    commit: { sha: commit.sha, tree: commit.tree },
+    snapshot: { path: snapshot.path, expectedTree: snapshot.expectedTree },
+    declaredInputs: { inputs: [...declaredInputs] },
+    ownership: { handle },
+    primaryCwd,
+    argvSha256: argvSha256(argv),
+    nonce,
+  };
+  const bytes = Buffer.from(JSON.stringify(carrier), "utf8");
+  if (bytes.length > CARRIER_MAX_BYTES) fail("too-large", `the snapshot request is ${bytes.length} bytes, more than ${CARRIER_MAX_BYTES}`);
+  const file = path.join(dir, `${uuid()}.json`);
+  fs.writeFileSync(file, bytes, { flag: "wx", mode: 0o600 });
+  const digest = sha256(bytes);
+  const descriptor = JSON.stringify({ path: file, sha256: digest });
+  if (Buffer.byteLength(descriptor) > DESCRIPTOR_MAX_BYTES) { fs.rmSync(file, { force: true }); fail("too-large", "the snapshot request descriptor exceeds 4096 bytes"); }
+  const env = { [SNAPSHOT_REQUEST_ENV]: descriptor, [ATTEST_NONCE_ENV]: nonce, ...(requestIdFile ? { [REQUEST_ID_FILE_ENV]: requestIdFile } : {}) };
+  return { file, sha256: digest, descriptor, carrier, env };
+}
+
+/** The request core the broker digests for a snapshot cargo request: the base core plus commit, snapshot, declaredInputs and ownership. */
+export function snapshotRequestCore({ argv, workspace, observedEnv = {}, carrier }) {
+  return {
+    adapter: null, env: {}, inputManifest: null, nonce: carrier.nonce, observedEnv, outputs: [], requestedArgv: [...argv], shim: "cargo", workspace,
+    commit: carrier.commit, snapshot: carrier.snapshot, declaredInputs: carrier.declaredInputs, ownership: carrier.ownership,
+  };
+}
+export const requestDigestOf = (core) => sha256(canonicalJson(core));
+
+/** The request reference the client writes at submit (RIGHTKIT_REQUEST_ID_FILE), or a throw. */
+export function readRequestRef(file) {
+  let ref;
+  try { ref = JSON.parse(fs.readFileSync(file, "utf8")); } catch (e) { fail("request", `no request reference at ${file} (${e.message})`); }
+  if (ref?.schema !== REQUEST_REF_SCHEMA || typeof ref.requestId !== "string" || !ref.requestId || typeof ref.workspace !== "string" || !path.isAbsolute(ref.workspace)) fail("request", `${file} is not a ${REQUEST_REF_SCHEMA}`);
+  return ref;
+}
+
+const same = (a, b) => canonicalJson(a ?? null) === canonicalJson(b ?? null);
+
+// ---- declared compile inputs, read and digested the way the broker does (check_admission.rs declared_inputs / snapshot_inputs) ----
+
+const lstatOrNull = (p) => { try { return fs.lstatSync(p); } catch (e) { if (e.code === "ENOENT") return null; throw e; } };
+
+/**
+ * The declared inputs of a snapshot: `inputs` of `.rightkit/compile-inputs.json` read FROM THE SNAPSHOT, never the checkout. No
+ * manifest means an empty set; a link on its path, a file that is not regular, an oversized or malformed manifest, or an input that
+ * is not a plain relative path (absolute, `.`/`..`, inside `.git`, the manifest itself) is refused before any request is made.
+ */
+export function readDeclaredInputs(snapshotRoot) {
+  const parts = COMPILE_INPUTS.split("/");
+  let at = snapshotRoot; let meta = null;
+  for (const part of parts) {
+    at = path.join(at, part);
+    meta = lstatOrNull(at);
+    if (meta === null) return [];
+    if (meta.isSymbolicLink()) fail("declared-inputs", `${COMPILE_INPUTS} runs through a link at ${at}`);
+  }
+  if (!meta.isFile()) fail("declared-inputs", `${COMPILE_INPUTS} is not a regular file`);
+  if (meta.size > MAX_DECLARATION_BYTES) fail("declared-inputs", `${COMPILE_INPUTS} is larger than ${MAX_DECLARATION_BYTES} bytes`);
+  let value;
+  try { value = JSON.parse(fs.readFileSync(at, "utf8")); } catch (e) { fail("declared-inputs", `${COMPILE_INPUTS} is not JSON (${e.message})`); }
+  if (!value || typeof value !== "object" || !Array.isArray(value.inputs)) fail("declared-inputs", `${COMPILE_INPUTS}: \`inputs\` must be a list of paths`);
+  for (const input of value.inputs) {
+    if (typeof input !== "string" || !input) fail("declared-inputs", `${COMPILE_INPUTS}: every input is a non-empty relative path`);
+    const components = input.split(/[\\/]/);
+    if (path.isAbsolute(input) || path.posix.isAbsolute(input) || path.win32.isAbsolute(input) || components.some((c) => c === "" || c === "." || c === "..")) fail("declared-inputs", `${COMPILE_INPUTS}: ${input} is not a plain relative path inside the snapshot`);
+    if (components.some((c) => c.toLowerCase() === ".git")) fail("declared-inputs", `${COMPILE_INPUTS}: ${input} is inside .git; repository metadata is never a compile input`);
+    if (components.length <= parts.length && components.every((c, i) => c === parts[i])) fail("declared-inputs", `${COMPILE_INPUTS}: ${input} overlaps the declaration file itself`);
+  }
+  return [...value.inputs];
+}
+
+/**
+ * The `declaredInputDigests` the broker records for these inputs, computed here from the snapshot: per input, sha256 over, for each
+ * regular file in directory order (names sorted by their bytes), the file's relative name, a NUL, its bytes and a NUL. A link
+ * anywhere, a special file, or a limit breach is a refusal. Child names are joined with the platform's separator, as the broker's
+ * `Path::join` does.
+ */
+export function declaredInputDigestsOf(snapshotRoot, inputs, { platform = process.platform } = {}) {
+  const sep = platform === "win32" ? "\\" : "/";
+  let files = 0; let bytes = 0;
+  const walk = (full, name, hasher) => {
+    const meta = fs.lstatSync(full);
+    if (meta.isSymbolicLink()) fail("declared-inputs", `declared compile input holds a link at ${name}`);
+    if (meta.isDirectory()) {
+      const children = fs.readdirSync(full).sort((a, b) => Buffer.compare(Buffer.from(a, "utf8"), Buffer.from(b, "utf8")));
+      for (const child of children) walk(path.join(full, child), name.endsWith("/") || name.endsWith("\\") ? `${name}${child}` : `${name}${sep}${child}`, hasher);
+      return;
+    }
+    if (!meta.isFile()) fail("declared-inputs", `declared compile input ${name} is not a regular file or directory`);
+    files += 1;
+    if (files > MAX_INPUT_FILES) fail("declared-inputs", `the declared compile inputs exceed ${MAX_INPUT_FILES} files`);
+    hasher.update(name); hasher.update(Buffer.from([0]));
+    const fd = fs.openSync(full, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    try {
+      const after = fs.fstatSync(fd);
+      if (!after.isFile() || (process.platform !== "win32" && (after.dev !== meta.dev || after.ino !== meta.ino))) fail("declared-inputs", `${name} changed while it was read`);
+      const chunk = Buffer.allocUnsafe(64 * 1024);
+      for (;;) {
+        const n = fs.readSync(fd, chunk, 0, chunk.length, null);
+        if (n === 0) break;
+        bytes += n;
+        if (bytes > MAX_INPUT_BYTES) fail("declared-inputs", `the declared compile inputs exceed ${MAX_INPUT_BYTES} bytes`);
+        hasher.update(chunk.subarray(0, n));
+      }
+    } finally { fs.closeSync(fd); }
+    hasher.update(Buffer.from([0]));
+  };
+  return inputs.map((input) => {
+    // Every component of the declared path is walked without following a link.
+    let at = snapshotRoot;
+    for (const part of input.split(/[\\/]/)) {
+      at = path.join(at, part);
+      let meta;
+      try { meta = fs.lstatSync(at); } catch (e) { fail("declared-inputs", `${input}: ${e.message}`); }
+      if (meta.isSymbolicLink()) fail("declared-inputs", `${input} runs through a link at ${at}`);
+    }
+    const hasher = crypto.createHash("sha256");
+    walk(at, input, hasher);
+    return { path: input, sha256: hasher.digest("hex") };
+  });
+}
+
+// ---- the receipt ----
+
+const inside = (child, parent, platform) => {
+  const norm = (p) => (platform === "win32" ? path.win32.resolve(p).toLowerCase() : path.resolve(p));
+  const rel = (platform === "win32" ? path.win32 : path).relative(norm(parent), norm(child));
+  return rel === "" || !(rel === ".." || /^\.\.[\\/]/.test(rel) || path.isAbsolute(rel) || path.win32.isAbsolute(rel));
+};
+
+/**
+ * The generation target the broker pins an app's outputs to: `<root>/<12 hex>/g/<NNN>/target` under one of the managed `ws` roots
+ * (`<external data root>/rightkit-build-control/ws`; BROKER-CONTRACT "Source identity", output pinning). The 12-hex key is
+ * rustright-state's workspace_key, which the gate never computes (the snapshot's own key is `snapshots/<sha256(repo path)[:16]>`, a
+ * different thing); it reads the receipt's outputDir and checks only this shape. The generation number (3+ digits) is the broker's.
+ */
+export function isGenerationTarget(outputDir, outputRoots, platform = process.platform) {
+  const mod = platform === "win32" ? path.win32 : path;
+  for (const root of outputRoots) {
+    const rel = mod.relative(platform === "win32" ? mod.resolve(root).toLowerCase() : mod.resolve(root), platform === "win32" ? mod.resolve(outputDir).toLowerCase() : mod.resolve(outputDir));
+    const segments = rel.split(/[\\/]/);
+    if (segments.length === 4 && segments[0] !== ".." && !mod.isAbsolute(rel) && /^[0-9a-f]{12}$/.test(segments[0]) && segments[1] === "g" && /^[0-9]{3,}$/.test(segments[2]) && segments[3] === "target") return true;
+  }
+  return false;
+}
+
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+/**
+ * Verifies the receipt of one snapshot cargo request. `pins` come from this host's enrollment, never from the receipt.
+ * Returns `{ payload, evidence }`; throws ProvenanceError (legacy, signature, pins, job, nonce, request) or SnapshotRequestError (evidence).
+ *
+ * Beyond the signature, the job, the nonce and the request digest, the receipt must carry (item 7 row 7.22):
+ *   - signed SUCCEEDED with exit 0, and signed snapshotEvidence equal to the receipt's copies (commit, ownership handle, request id,
+ *     snapshot path, `treeAtStart` = `treeAtExit` = the expected tree);
+ *   - `declaredInputDigests` equal to the gate's own digest of the snapshot's declared inputs, read from the snapshot now;
+ *   - `outputDir` absolute, outside the snapshot and the checkout, and a managed generation target under one of `outputRoots`;
+ *   - signed stageEvidence (freshness, attribution, toolchain) equal to the receipt's;
+ *   - verdict, timingsMs, exit, diagnosticsPath, brokerVersion, executor and refreshed present with their types.
+ * `checkout` and `outputRoots` are required: without them nothing can be said about where the outputs went, so it refuses.
+ */
+export function verifySnapshotReceipt(receipt, { pins, jobId, carrier, argv, workspace, observedEnv = {}, checkout, outputRoots, platform = process.platform, canonicalPath = (p) => fs.realpathSync.native(p), digestInputs = declaredInputDigestsOf, readInputs = readDeclaredInputs }) {
+  const requestDigest = requestDigestOf(snapshotRequestCore({ argv, workspace, observedEnv, carrier }));
+  const payload = verifyProvenance(receipt, pins, { jobId, nonce: carrier.nonce, requestDigest });
+  // The signed outcome, not the client's exit code: a passing row needs the broker to have signed SUCCEEDED with exit 0 and no
+  // signal (service.rs provenance_payload `result`). An authentic FAILED, or a payload without a result, is not a success.
+  const result = payload.result;
+  if (!result || typeof result !== "object") fail("result", "the signed payload carries no result: the broker did not sign this request's outcome");
+  if (result.status !== "SUCCEEDED" || result.exitCode !== 0 || (result.signal !== undefined && result.signal !== null)) {
+    fail("result", `the broker signed ${result.status ?? "no status"} (exit ${result.exitCode ?? "none"}${result.signal ? `, signal ${result.signal}` : ""}), not SUCCEEDED with exit 0`);
+  }
+  const evidence = payload.snapshotEvidence;
+  if (!evidence || typeof evidence !== "object") fail("evidence", "the signed payload carries no snapshotEvidence: the broker did not build this as a snapshot request");
+  for (const name of SNAPSHOT_EVIDENCE_FIELDS) {
+    if (evidence[name] === undefined || !same(receipt[name], evidence[name])) fail("evidence", `receipt ${name} differs from the signed snapshot evidence`);
+  }
+  if (!same(evidence.commit, carrier.commit)) fail("evidence", "the signed commit is not the one this request carried");
+  if (evidence.ownership?.handle !== carrier.ownership.handle) fail("evidence", "the signed ownership handle is not this gate's");
+  if (evidence.requestId !== jobId) fail("evidence", "the signed request id is not this job");
+  const snap = evidence.snapshot ?? {};
+  let samePath = false;
+  try { samePath = canonicalPath(snap.path) === canonicalPath(carrier.snapshot.path); } catch { samePath = false; }
+  if (!samePath) fail("evidence", `the signed snapshot ${snap.path} is not ${carrier.snapshot.path}`);
+  if (snap.treeAtStart !== carrier.snapshot.expectedTree || snap.treeAtExit !== carrier.snapshot.expectedTree) {
+    fail("evidence", `the snapshot was tree ${snap.treeAtStart} at START and ${snap.treeAtExit} at exit, not ${carrier.snapshot.expectedTree} throughout: the build changed a tracked file (or added or removed one) in the commit's snapshot, so the result is discarded; that is the app owner's defect to fix (write generated output to an ignored path or an output directory, or generate before commit)`);
+  }
+  // Declared inputs: what the broker digested in place must be what the gate digests in the snapshot, from the same manifest.
+  let gateInputs; let gateDigests;
+  try {
+    gateInputs = readInputs(carrier.snapshot.path);
+    gateDigests = digestInputs(carrier.snapshot.path, gateInputs, { platform });
+  } catch (e) { fail("evidence", `the gate cannot digest the snapshot's declared inputs (${e.message})`); }
+  if (!same(gateInputs, carrier.declaredInputs?.inputs)) fail("evidence", "the snapshot's declared inputs are not the ones this request carried");
+  if (!same(evidence.declaredInputDigests, gateDigests)) fail("evidence", "the signed declaredInputDigests are not the gate's own digest of the snapshot's declared inputs");
+  // Output directory: where the outputs went must be the broker's managed generation target, never under the snapshot or the checkout.
+  const out = evidence.outputDir;
+  if (typeof out !== "string" || !path.isAbsolute(out) && !path.win32.isAbsolute(out)) fail("evidence", "the signed evidence names no absolute output directory");
+  if (!checkout || !path.isAbsolute(checkout) || !Array.isArray(outputRoots) || outputRoots.length === 0) fail("evidence", "the gate has no checkout or managed output root to judge the output directory against");
+  const canon = (p) => { try { return canonicalPath(p); } catch { return p; } };
+  if (inside(out, carrier.snapshot.path, platform) || inside(out, canon(carrier.snapshot.path), platform)) fail("evidence", `the output directory ${out} is inside the snapshot`);
+  if (inside(out, checkout, platform) || inside(out, canon(checkout), platform)) fail("evidence", `the output directory ${out} is inside the checkout`);
+  if (!isGenerationTarget(out, outputRoots, platform)) fail("evidence", `the output directory ${out} is not a managed generation target (<ws root>/<repo-key>/g/<generation>/target) under ${outputRoots.join(", ")}`);
+  // Stage evidence is signed with the rest and must equal the receipt's copy. `freshness` is required for every carried command;
+  // `attribution` and `toolchain` only for a compile-class command (check, clippy, build, doc, rustc, test: the broker emits them
+  // for compiles only), so metadata, fetch --locked, fmt --check or tree --locked pass without them. When either side carries one
+  // anyway, both must carry the same value.
+  const stage = payload.stageEvidence;
+  if (!isObject(stage)) fail("evidence", "the signed payload carries no stageEvidence");
+  const compile = isCompileClass(argv);
+  for (const name of STAGE_EVIDENCE_FIELDS) {
+    const signed = stage[name] ?? null; const copy = receipt[name] ?? null;
+    const required = name === "freshness" || compile;
+    if (required && (signed === null || copy === null)) fail("evidence", `${name} is missing from the signed stage evidence or the receipt${name === "freshness" ? "" : ` (a compile-class command, cargo ${cargoSubcommandOf(argv)}, carries it)`}`);
+    if (!same(copy, signed)) fail("evidence", `receipt ${name} differs from the signed stage evidence`);
+  }
+  // Shapes RustRight emits (item 4 row 4.18): attribution is `{available, ...}`, and an unavailable one names its reason
+  // (`cargo-json-message-format-not-requested` without a JSON message stream; a consumer that needs per-package attribution treats
+  // `available:false` as FAILED, not partial); toolchain is `<toolchain>|cargo:<sha256>|rustc:<sha256>`.
+  const attribution = receipt.attribution ?? null; const toolchain = receipt.toolchain ?? null;
+  if (attribution !== null) {
+    if (!isObject(attribution) || typeof attribution.available !== "boolean") fail("evidence", "receipt attribution is not {available, ...}");
+    if (attribution.available === false && !(typeof attribution.reason === "string" && attribution.reason !== "")) fail("evidence", "receipt attribution is unavailable and names no reason");
+  }
+  if (toolchain !== null && !(typeof toolchain === "string" && TOOLCHAIN_FORMAT.test(toolchain))) fail("evidence", "receipt toolchain is not <toolchain>|cargo:<sha256>|rustc:<sha256>");
+  // Fields the signature does not cover must still be present with their types (the consumer reads them). Every carried command:
+  // verdict, refreshed, exit (an integer, or null with a signal) and signal, timingsMs{admission, queue, bind, cargo, afterExitBind,
+  // diagnostics} (each a number or null) and diagnosticsPath (a path, or null). Success needs exit 0 and no signal, as signed.
+  const timingsOk = isObject(receipt.timingsMs) && TIMING_KEYS.every((k) => Object.hasOwn(receipt.timingsMs, k) && (receipt.timingsMs[k] === null || Number.isFinite(receipt.timingsMs[k])));
+  const typed = [
+    ["verdict", isObject(receipt.verdict)], ["timingsMs", timingsOk], ["exit", receipt.exit === null || Number.isSafeInteger(receipt.exit)],
+    ["signal", receipt.signal === null || typeof receipt.signal === "string" || Number.isSafeInteger(receipt.signal)],
+    ["diagnosticsPath", receipt.diagnosticsPath === null || (typeof receipt.diagnosticsPath === "string" && receipt.diagnosticsPath !== "")], ["brokerVersion", typeof receipt.brokerVersion === "string" && receipt.brokerVersion !== ""],
+    ["executor", typeof receipt.executor === "string" && receipt.executor !== ""], ["refreshed", Array.isArray(receipt.refreshed)],
+  ];
+  for (const [name, ok] of typed) if (!ok) fail("evidence", `receipt ${name} is missing or has the wrong type`);
+  if (receipt.exit !== 0 || receipt.signal !== null) fail("evidence", `receipt exit ${receipt.exit} and signal ${receipt.signal} are not a success (exit 0, no signal)`);
+  // RustRight signs these top-level fields in the payload (item 4 row 4.18): when the signed payload carries one, the receipt's copy must equal it.
+  for (const name of SIGNED_TOP_LEVEL_FIELDS) {
+    if (payload[name] !== undefined && !same(receipt[name], payload[name])) fail("evidence", `receipt ${name} differs from the signed payload`);
+  }
+  return { payload, evidence, attribution, toolchain };
+}
+
+export { ProvenanceError };

package/snapshot-root-config.mjs

@@ -0,0 +1,76 @@
+// The gate's per-user host configuration file (docs/GATE-CONTRACT.md §1 "Broker interface" Snapshot root: "a durable root named in
+// gate configuration"; item 5 row 5.16). It is the ONE place a Linux host names its snapshot root.
+//
+//   File:     <home>/.config/rightkit/gate.json   (home = the account's passwd home directory)
+//   Content:  { "schema": "rightkit.gate-host-config/1", "snapshotRoot": "/absolute/normalised/durable/path" }
+//
+// Why a file and not a variable or a flag: two concurrent gate runs on one host could otherwise choose two roots for one repository,
+// and "one snapshot per repository per host" (GC §1) would be false. So nothing in the process environment or on a command line
+// selects the root, and nothing here reads one: not RIGHTKIT_SNAPSHOT_ROOT (removed as a source), not XDG_CONFIG_HOME, not HOME.
+// The file's own location comes from the account database (`os.userInfo().homedir`), the one home directory an environment
+// variable cannot move. The contract's named default (`$XDG_STATE_HOME/rightkit/snapshots`, else `~/.local/state/rightkit/snapshots`)
+// applies only when no file exists.
+//
+// The file is outside every repository, snapshot and scratch directory by construction (a dot directory of the account's home).
+// It must be what a persistent per-user setting is, or it is refused (fail closed, never ignored, because an ignored file would
+// silently pick the default root): a regular file (a link is never followed: a dotfiles link into a repository would put the
+// setting inside one), owned by this user, writable by no group or other principal, in a directory owned by this user that no group or
+// other principal can write; valid JSON of exactly the schema above (an unknown key is a typo that would silently pick the default);
+// and a `snapshotRoot` that is an absolute, normalised POSIX path (no `..`, no `.`, no doubled or trailing separator).
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const HOST_CONFIG_SCHEMA = "rightkit.gate-host-config/1";
+export const HOST_CONFIG_DIR = path.posix.join(".config", "rightkit");
+export const HOST_CONFIG_NAME = "gate.json";
+
+export class HostConfigError extends Error {
+  constructor(message) { super(message); this.code = "host-config"; }
+}
+
+/** The account's home directory from the account database, not from HOME (which any process can change); HOME only if there is no entry. */
+export function accountHome() {
+  try { const h = os.userInfo().homedir; if (h) return h; } catch { /* no passwd entry (a container with an arbitrary uid) */ }
+  return os.homedir();
+}
+
+/** Where the gate's host configuration file lives for `home` (default: this account's). */
+export function hostConfigFile(home = accountHome()) {
+  return path.posix.join(home, HOST_CONFIG_DIR, HOST_CONFIG_NAME);
+}
+
+const groupOrOtherWrites = (mode) => (Number(mode) & 0o022) !== 0;
+
+/**
+ * The snapshot root the file at `file` names, or null when there is no such file. Throws HostConfigError when the file exists but
+ * is not an acceptable host configuration (see the header). `getuid` is injectable for the ownership rule; where the host has no
+ * uid (Windows) the ownership and mode rules do not apply, and the Windows root is the managed root's, never a file's.
+ */
+export function readSnapshotRootConfig(file, { getuid = process.getuid?.bind(process) } = {}) {
+  let st;
+  try { st = fs.lstatSync(file); } catch (e) { if (e.code === "ENOENT" || e.code === "ENOTDIR") return null; throw new HostConfigError(`gate host configuration ${file} cannot be inspected: ${e.code ?? e.message}`); }
+  const refuse = (why) => new HostConfigError(`gate host configuration ${file} ${why}`);
+  if (!st.isFile()) throw refuse("is not a regular file (a link is never followed: a setting reached through one could live inside a repository)");
+  if (getuid) {
+    const uid = getuid();
+    let dirSt;
+    try { dirSt = fs.lstatSync(path.dirname(file)); } catch (e) { throw refuse(`has a directory that cannot be inspected: ${e.code ?? e.message}`); }
+    if (st.uid !== uid) throw refuse(`is owned by uid ${st.uid}, not by this user (uid ${uid})`);
+    if (groupOrOtherWrites(st.mode)) throw refuse(`is writable by group or other (mode ${(Number(st.mode) & 0o777).toString(8)}); only this user may change where snapshots live`);
+    if (!dirSt.isDirectory() || dirSt.uid !== uid || groupOrOtherWrites(dirSt.mode)) throw refuse("is in a directory that is not a real directory owned by this user and closed to group and other writes");
+  }
+  let doc;
+  try { doc = JSON.parse(fs.readFileSync(file, "utf8")); } catch (e) { throw refuse(`cannot be read as JSON: ${e.message}`); }
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) throw refuse("is not a JSON object");
+  if (doc.schema !== HOST_CONFIG_SCHEMA) throw refuse(`has schema ${JSON.stringify(doc.schema)}, not ${JSON.stringify(HOST_CONFIG_SCHEMA)}`);
+  const unknown = Object.keys(doc).filter((k) => k !== "schema" && k !== "snapshotRoot");
+  if (unknown.length) throw refuse(`has unknown key(s) ${unknown.map((k) => JSON.stringify(k)).join(", ")} (only "schema" and "snapshotRoot" exist; a misspelled key would silently select the default root)`);
+  if (doc.snapshotRoot === undefined) return null;
+  const root = doc.snapshotRoot;
+  if (typeof root !== "string" || !root || root.includes("\0")) throw refuse('has a "snapshotRoot" that is not a non-empty string');
+  if (!path.posix.isAbsolute(root)) throw refuse(`names the relative "snapshotRoot" ${JSON.stringify(root)}; it must be absolute`);
+  if (root === "/" || root.endsWith("/") || path.posix.normalize(root) !== root) throw refuse(`names the "snapshotRoot" ${JSON.stringify(root)}, which is not a normalised path below the filesystem root (no "..", ".", doubled or trailing separators)`);
+  return root;
+}