@rightkit/release 0.4.0 → 0.5.0

package/pipeline-receipts.mjs

@@ -0,0 +1,302 @@
+// Pipeline stage receipts and their verifier (architecture-v3 sections 4-5, "Receipts").
+//
+// A receipt records a fact about one stage of one request. It never authorizes execution alone: the
+// broker (RustRight) signs receipts and issues short-lived capabilities; this module only checks that
+// a chain of receipts is well formed, linked, fresh and complete. Signature checking is an injected
+// interface (`verifySignature`); this module does no cryptography beyond SHA-256 hashing and invents none.
+//
+// Chain: ADMISSION -> SCAN_A -> ROUTE -> SCAN_B -> BUILD -> SIGN -> QUALIFIED -> PUBLISH_INTENT -> PUBLISHED.
+// Each stage requires exactly its predecessor; `parents` carries that predecessor's receipt hash.
+import crypto from "node:crypto";
+import { canonicalJson, digestScanSet, scanClassOf } from "./deterministic-scans.mjs";
+
+export const RECEIPT_SCHEMA = "rightkit.pipeline-receipt/1";
+export const STAGES = Object.freeze(["ADMISSION", "SCAN_A", "ROUTE", "SCAN_B", "BUILD", "SIGN", "QUALIFIED", "PUBLISH_INTENT", "PUBLISHED"]);
+export const OPERATIONS = Object.freeze(["dev", "build", "qualify", "sign", "publish"]);
+/** The last stage each operation may reach. */
+export const OPERATION_LAST_STAGE = Object.freeze({ dev: "BUILD", build: "BUILD", sign: "SIGN", qualify: "QUALIFIED", publish: "PUBLISHED" });
+/** Each stage requires only these predecessors. */
+export const PREREQUISITES = Object.freeze({
+  ADMISSION: [], SCAN_A: ["ADMISSION"], ROUTE: ["SCAN_A"], SCAN_B: ["ROUTE"], BUILD: ["SCAN_B"],
+  SIGN: ["BUILD"], QUALIFIED: ["SIGN"], PUBLISH_INTENT: ["QUALIFIED"], PUBLISHED: ["PUBLISH_INTENT"],
+});
+const RELEASE_ID_STAGES = new Set(["SIGN", "QUALIFIED", "PUBLISH_INTENT", "PUBLISHED"]);
+/** Stages only a publishable request may reach: signing and everything after it. A dev or non-publishable chain stops at BUILD. */
+const PUBLISHABLE_ONLY_STAGES = new Set(RELEASE_ID_STAGES);
+
+/**
+ * What ADMISSION's evidence allows for `stage`, as [{ code, message }]. ADMISSION is the sole authority:
+ * a missing or malformed ADMISSION authorizes nothing, and `publishable` must be exactly true to reach SIGN or later.
+ */
+function admissionProblems(admission, stage) {
+  const out = [];
+  if (!admission) return [{ code: "STAGE_NOT_AUTHORIZED", message: `no valid ADMISSION evidence authorizes ${stage}` }];
+  if (!Array.isArray(admission.authorizedStages) || !admission.authorizedStages.includes(stage)) out.push({ code: "STAGE_NOT_AUTHORIZED", message: `ADMISSION does not authorize ${stage}` });
+  if (admission.publishable !== true && PUBLISHABLE_ONLY_STAGES.has(stage)) out.push({ code: "NOT_PUBLISHABLE", message: `ADMISSION does not mark this request publishable:true; it cannot reach ${stage}` });
+  return out;
+}
+
+const ENVELOPE_STRINGS = ["receiptId", "jobId", "requestId", "repositoryId", "commit", "inputDigest", "configDigest", "policyDigest", "stagePlanDigest", "runtimeDigest", "executor", "issuedAt", "expiresAt", "keyId", "signature"];
+const HEX64 = /^[0-9a-f]{64}$/;
+const sha256 = (value) => crypto.createHash("sha256").update(value).digest("hex");
+
+/** Domain-separated bytes a signature covers: receipt type bound in, signature field excluded. */
+export function signingBytes(receipt) {
+  const { signature, ...rest } = receipt;
+  return Buffer.from(`${RECEIPT_SCHEMA}\0${receipt.type}\0${canonicalJson(rest)}`, "utf8");
+}
+
+/** The hash a child receipt records in `parents`: covers the whole receipt including its signature. */
+export function receiptHash(receipt) {
+  return sha256(Buffer.concat([Buffer.from(`${RECEIPT_SCHEMA}.hash\0`, "utf8"), Buffer.from(canonicalJson(receipt), "utf8")]));
+}
+
+/** In-memory request ledger for tests and single-process brokers: records which job owns a requestId. */
+export function createMemoryLedger() {
+  const owners = new Map(); const consumed = new Set();
+  return {
+    requestOwner: (requestId) => owners.get(requestId),
+    isConsumed: (receiptId) => consumed.has(receiptId),
+    record(chain) { for (const r of chain) { if (!owners.has(r.requestId)) owners.set(r.requestId, r.jobId); consumed.add(r.receiptId); } },
+  };
+}
+
+const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const nonEmptyString = (v) => typeof v === "string" && v.trim() !== "";
+const isHex = (v) => typeof v === "string" && HEX64.test(v);
+const nonEmptyArray = (v) => Array.isArray(v) && v.length > 0;
+
+/** Stage-specific evidence checks. Each returns a list of problem messages. */
+const STAGE_EVIDENCE = {
+  ADMISSION(e) {
+    const p = [];
+    for (const f of ["inputManifestDigest", "dependencyManifestDigest", "toolchainManifestDigest"]) if (!isHex(e[f])) p.push(`${f} must be a sha256 hex digest`);
+    if (!nonEmptyArray(e.authorizedStages) || e.authorizedStages.some((s) => !STAGES.includes(s))) p.push("authorizedStages must list known stages");
+    if (typeof e.publishable !== "boolean") p.push("publishable must be a boolean");
+    return p;
+  },
+  SCAN_A: (e, ctx) => scanEvidence(e, "A", ctx),
+  ROUTE(e, ctx) {
+    const p = [];
+    const d = e.decision;
+    if (!isObj(d)) return ["decision is required"];
+    if (!["local", "ci"].includes(d.executor)) p.push("decision.executor must be local or ci");
+    if (!["public", "private"].includes(d.visibility)) p.push("decision.visibility must be public or private (unknown visibility is rejected)");
+    if (d.visibility === "private" && d.executor !== "local") p.push("a private repository never routes to CI");
+    if (typeof d.localGrant !== "boolean") p.push("decision.localGrant must be a boolean");
+    if (d.executor === "local" && !nonEmptyString(String(e.leaseFence ?? ""))) p.push("a local route needs a leaseFence");
+    if (d.executor === "ci" && !isObj(e.dispatchBinding)) p.push("a CI route needs a dispatchBinding");
+    if (!nonEmptyString(d.policyVersion)) p.push("decision.policyVersion is required");
+    return p;
+  },
+  SCAN_B: (e, ctx) => scanEvidence(e, "B", ctx),
+  BUILD(e) {
+    const p = [];
+    if (!isHex(e.artifactManifestDigest)) p.push("artifactManifestDigest must be a sha256 hex digest");
+    if (!nonEmptyArray(e.artifacts) || e.artifacts.some((a) => !nonEmptyString(a?.path) || !isHex(a?.sha256))) p.push("artifacts must list path and sha256 for every output");
+    for (const f of ["generationEvidenceDigest", "provenanceDigest"]) if (!isHex(e[f])) p.push(`${f} must be a sha256 hex digest`);
+    if (!nonEmptyArray(e.targetMatrix)) p.push("targetMatrix must list the built targets");
+    return p;
+  },
+  SIGN(e, ctx) {
+    const p = [];
+    if (!["SIGN", "SEAL"].includes(e.mode)) p.push("mode must be SIGN or SEAL");
+    for (const f of ["inputManifestDigest", "outputManifestDigest", "signingEvidenceDigest"]) if (!isHex(e[f])) p.push(`${f} must be a sha256 hex digest`);
+    if (!nonEmptyString(e.signingProfile)) p.push("signingProfile is required");
+    const build = ctx.byStage.BUILD;
+    if (build && e.inputManifestDigest !== build.evidence?.artifactManifestDigest) p.push("inputManifestDigest does not equal the BUILD artifactManifestDigest");
+    return p;
+  },
+  QUALIFIED(e, ctx) {
+    const p = [];
+    if (!isHex(e.artifactManifestDigest)) p.push("artifactManifestDigest must be a sha256 hex digest");
+    if (!nonEmptyArray(e.testMatrix) || e.testMatrix.some((t) => !nonEmptyString(t?.name) || t?.status !== "pass")) p.push("testMatrix must be non-empty and every row must pass");
+    const sign = ctx.byStage.SIGN;
+    if (sign && e.artifactManifestDigest !== sign.evidence?.outputManifestDigest) p.push("artifactManifestDigest does not equal the SIGN outputManifestDigest (qualification covers the final signed bytes)");
+    return p;
+  },
+  PUBLISH_INTENT(e, ctx) {
+    const p = [];
+    if (!isHex(e.releaseManifestDigest)) p.push("releaseManifestDigest must be a sha256 hex digest");
+    if (!nonEmptyArray(e.destinations) || e.destinations.some((d) => !nonEmptyString(d?.id) || !nonEmptyString(d?.identity) || !nonEmptyString(d?.version) || !isHex(d?.expectedDigest) || !nonEmptyString(d?.idempotencyKey))) {
+      p.push("destinations must name id, identity, version, expectedDigest and idempotencyKey");
+    }
+    const q = ctx.byStage.QUALIFIED;
+    if (q && e.releaseManifestDigest !== q.evidence?.artifactManifestDigest) p.push("releaseManifestDigest does not equal the QUALIFIED artifactManifestDigest");
+    return p;
+  },
+  PUBLISHED(e, ctx) {
+    const p = [];
+    const intent = ctx.byStage.PUBLISH_INTENT;
+    if (!nonEmptyArray(e.entries)) return ["entries must list every destination outcome"];
+    for (const d of intent?.evidence?.destinations ?? []) {
+      const entry = e.entries.find((x) => x?.destinationId === d.id);
+      if (!entry) p.push(`no entry for destination ${d.id}`);
+      else if (entry.outcome !== "verified") p.push(`destination ${d.id} is ${entry.outcome}, not verified`);
+      else if (entry.remoteDigest !== d.expectedDigest) p.push(`destination ${d.id} readback digest differs from the intent`);
+    }
+    return p;
+  },
+};
+
+function scanEvidence(e, cls, ctx) {
+  const p = [];
+  const other = cls === "A" ? "B" : "A";
+  if (e.scanClass !== cls) p.push(`scanClass must be ${cls}`);
+  if (!nonEmptyArray(e.scans)) return [...p, "scans must list every required scan result"];
+  if (cls === "A" && !isHex(e.advisorySnapshotDigest)) p.push("advisorySnapshotDigest must be a sha256 hex digest");
+  if (cls === "A" && !nonEmptyString(e.advisorySnapshotTime)) p.push("advisorySnapshotTime is required");
+  for (const s of e.scans) {
+    const derived = scanClassOf(s?.id);
+    if (s?.class === other || derived === other) p.push(`${cls === "A" ? "SCAN_A claims" : "SCAN_B carries"} class ${other} scan ${s?.id}`);
+    else if (s?.class !== cls) p.push(`scan ${s?.id} has class ${s?.class}, expected ${cls}`);
+    if (s?.status !== "pass") p.push(`scan ${s?.id} is ${s?.status}, not pass`);
+  }
+  const ids = new Set(e.scans.map((s) => s?.id));
+  const required = ctx.requiredScans?.[cls];
+  const declared = Array.isArray(e.requiredScanIds) ? e.requiredScanIds : null;
+  if (!declared) p.push("requiredScanIds is required");
+  // The required set comes only from the injected policy matrix. A receipt's own declaration is never trusted:
+  // without the policy, verification fails closed.
+  if (!Array.isArray(required) || required.some((id) => typeof id !== "string")) {
+    p.push(`trusted required scan set for class ${cls} is not supplied by policy; verification fails closed`);
+    return p;
+  }
+  for (const id of required) if (!ids.has(id)) p.push(`required class ${cls} scan ${id} is missing`);
+  if (declared && canonicalJson([...required].sort()) !== canonicalJson([...declared].sort())) p.push(`requiredScanIds differ from the trusted class ${cls} set`);
+  if (e.scanSetDigest !== digestScanSet(e.scans)) p.push("scanSetDigest does not match the listed scans");
+  if (cls === "B" && !nonEmptyArray(required)) p.push("SCAN_B must require at least one class B scan");
+  return p;
+}
+
+/**
+ * Verify a chain of receipts (ADMISSION first, ending at the stage being authorized).
+ *
+ * options:
+ *   verifySignature({ receipt, keyId, signingBytes, signature }) -> boolean   REQUIRED (the broker supplies keys)
+ *   now                 ISO string or Date, default current time
+ *   expected            { requestId, operation, inputDigest, stage, repositoryId, commit, jobId, releaseId, targetSet } (each optional but checked when given)
+ *   requiredScans       { A: [ids], B: [ids] } trusted required sets from the policy matrix: REQUIRED; absence rejects (NO_SCAN_POLICY)
+ *   ledger              { requestOwner(requestId), isConsumed(receiptId) }   REQUIRED: without it verification fails (NO_LEDGER)
+ *   keyAllowed          (keyId, receipt) -> boolean, for revocations
+ * Returns { ok, problems: [{ code, stage, message }], head }. Never throws on a bad receipt.
+ */
+export function verifyReceiptChain(chain, options = {}) {
+  const problems = [];
+  const bad = (code, stage, message) => problems.push({ code, stage: stage ?? null, message });
+  if (typeof options.verifySignature !== "function") return { ok: false, problems: [{ code: "NO_SIGNATURE_VERIFIER", stage: null, message: "a signature verifier must be supplied by the broker" }], head: null };
+  if (!Array.isArray(chain) || chain.length === 0) return { ok: false, problems: [{ code: "EMPTY_CHAIN", stage: null, message: "no receipts" }], head: null };
+  const now = new Date(options.now ?? Date.now()).getTime();
+  const expected = options.expected ?? {};
+  const byStage = {};
+  let previous = null;
+  // Replay protection is mandatory: without a ledger the chain cannot be proven fresh, so it fails closed.
+  if (typeof options.ledger?.requestOwner !== "function" || typeof options.ledger?.isConsumed !== "function") {
+    bad("NO_LEDGER", null, "a request ledger with requestOwner and isConsumed must be supplied; replay cannot be ruled out without it");
+  }
+  // One release id for the whole chain: the ADMISSION one when it has it, else the first release-stage one.
+  const releaseRef = chain.find((r) => isObj(r) && nonEmptyString(r.releaseId))?.releaseId;
+  // ADMISSION fixes which stages may run and whether the request may publish at all.
+  const admission = isObj(chain[0]) && chain[0].type === "ADMISSION" && isObj(chain[0].evidence) ? chain[0].evidence : null;
+
+  chain.forEach((receipt, index) => {
+    const stage = isObj(receipt) ? receipt.type : null;
+    if (!isObj(receipt)) { bad("MALFORMED", null, `receipt ${index} is not an object`); return; }
+    if (receipt.schema !== RECEIPT_SCHEMA) bad("SCHEMA", stage, `schema must be ${RECEIPT_SCHEMA}`);
+    if (!STAGES.includes(stage)) { bad("UNKNOWN_STAGE", stage, `unknown receipt type ${JSON.stringify(stage)}`); return; }
+    const wantStage = STAGES[index];
+    if (stage !== wantStage) bad("WRONG_STAGE", stage, `position ${index} requires ${wantStage}, got ${stage}`);
+    for (const f of ENVELOPE_STRINGS) if (!nonEmptyString(receipt[f])) bad("ENVELOPE", stage, `${f} is required`);
+    if (!Number.isInteger(receipt.attempt) || receipt.attempt < 1) bad("ENVELOPE", stage, "attempt must be an integer >= 1");
+    if (!Array.isArray(receipt.targetSet)) bad("ENVELOPE", stage, "targetSet must be an array");
+    if (!OPERATIONS.includes(receipt.operation)) bad("WRONG_OPERATION", stage, `unknown operation ${JSON.stringify(receipt.operation)}`);
+    if (RELEASE_ID_STAGES.has(stage) && !nonEmptyString(receipt.releaseId)) bad("ENVELOPE", stage, "releaseId is required");
+    if (!isObj(receipt.evidence)) bad("EVIDENCE", stage, "evidence is required");
+
+    // The operation bounds how far a request may go.
+    const last = OPERATION_LAST_STAGE[receipt.operation];
+    if (last && STAGES.indexOf(stage) > STAGES.indexOf(last)) bad("WRONG_OPERATION", stage, `operation ${receipt.operation} does not authorize ${stage}`);
+
+    // ADMISSION bounds the chain: only its authorized stages, and nothing from SIGN on unless publishable:true.
+    for (const x of admissionProblems(admission, stage)) bad(x.code, stage, x.message);
+
+    // Binding to the caller's expectations.
+    if (expected.requestId !== undefined && receipt.requestId !== expected.requestId) bad("WRONG_REQUEST_ID", stage, "requestId differs from the expected request");
+    if (expected.operation !== undefined && receipt.operation !== expected.operation) bad("WRONG_OPERATION", stage, `operation ${receipt.operation} differs from expected ${expected.operation}`);
+    if (expected.inputDigest !== undefined && receipt.inputDigest !== expected.inputDigest) bad("WRONG_INPUT_DIGEST", stage, "inputDigest differs from the expected input");
+    for (const f of ["repositoryId", "commit", "jobId", "releaseId"]) if (expected[f] !== undefined && receipt[f] !== expected[f]) bad("BINDING", stage, `${f} differs from the expected value`);
+    if (expected.targetSet !== undefined && canonicalJson(receipt.targetSet ?? null) !== canonicalJson(expected.targetSet)) bad("BINDING", stage, "targetSet differs from the expected value");
+    if (releaseRef !== undefined && receipt.releaseId !== undefined && receipt.releaseId !== releaseRef) bad("BINDING", stage, "releaseId differs from the chain's release");
+
+    // Consistency across the chain.
+    const first = chain[0];
+    if (index > 0 && isObj(first)) {
+      for (const f of ["requestId", "jobId", "repositoryId", "commit", "inputDigest", "configDigest", "policyDigest", "stagePlanDigest", "operation", "targetSet"]) {
+        if (f === "targetSet" ? canonicalJson(receipt[f] ?? null) !== canonicalJson(first[f] ?? null) : receipt[f] !== first[f]) bad(f === "requestId" ? "WRONG_REQUEST_ID" : f === "inputDigest" ? "WRONG_INPUT_DIGEST" : f === "operation" ? "WRONG_OPERATION" : "BINDING", stage, `${f} differs from the ADMISSION receipt`);
+      }
+    }
+
+    // Freshness.
+    const issued = Date.parse(receipt.issuedAt); const expires = Date.parse(receipt.expiresAt);
+    if (Number.isNaN(issued) || Number.isNaN(expires)) bad("ENVELOPE", stage, "issuedAt and expiresAt must be ISO timestamps");
+    else {
+      if (expires <= issued) bad("ENVELOPE", stage, "expiresAt must be after issuedAt");
+      if (expires <= now) bad("EXPIRED", stage, `expired at ${receipt.expiresAt}`);
+      if (issued > now + 60_000) bad("ENVELOPE", stage, "issuedAt is in the future");
+      if (previous && issued < Date.parse(previous.issuedAt)) bad("ORDER", stage, "issued before its parent receipt");
+    }
+
+    // Hash chain.
+    const wantParents = previous ? [receiptHash(previous)] : [];
+    if (!Array.isArray(receipt.parents) || canonicalJson(receipt.parents) !== canonicalJson(wantParents)) bad("BROKEN_CHAIN", stage, previous ? `parents must be exactly [hash of ${previous.type}]` : "ADMISSION has no parents");
+
+    // Replay (the ledger is required; see NO_LEDGER above).
+    if (typeof options.ledger?.requestOwner === "function" && typeof options.ledger?.isConsumed === "function") {
+      const owner = options.ledger.requestOwner(receipt.requestId);
+      if (owner !== undefined && owner !== receipt.jobId) bad("REPLAYED_REQUEST_ID", stage, "requestId already belongs to another job");
+      if (options.ledger.isConsumed(receipt.receiptId)) bad("REPLAYED_RECEIPT", stage, "receipt already consumed");
+    }
+
+    // Signature (injected).
+    if (options.keyAllowed && !options.keyAllowed(receipt.keyId, receipt)) bad("KEY_REVOKED", stage, `key ${receipt.keyId} is not allowed for this receipt`);
+    let signatureOk = false;
+    try { signatureOk = options.verifySignature({ receipt, keyId: receipt.keyId, signingBytes: signingBytes(receipt), signature: receipt.signature }) === true; } catch { signatureOk = false; }
+    if (!signatureOk) bad("BAD_SIGNATURE", stage, "signature did not verify");
+
+    byStage[stage] = receipt;
+    // Stage evidence last: it can look at the earlier stages collected so far.
+    if (isObj(receipt.evidence) && STAGE_EVIDENCE[stage]) {
+      for (const message of STAGE_EVIDENCE[stage](receipt.evidence, { byStage, requiredScans: options.requiredScans })) {
+        const code = /trusted required scan set/.test(message) ? "NO_SCAN_POLICY" : /missing|claims|carries/.test(message) && (stage === "SCAN_A" || stage === "SCAN_B") ? (/claims|carries/.test(message) ? "SCAN_CLASS_MIX" : "SCAN_INCOMPLETE") : "EVIDENCE";
+        bad(code, stage, message);
+      }
+    }
+    previous = receipt;
+  });
+
+  const head = chain[chain.length - 1];
+  if (expected.stage !== undefined) {
+    if (!STAGES.includes(expected.stage)) bad("WRONG_STAGE", null, `unknown expected stage ${expected.stage}`);
+    else if (head?.type !== expected.stage) bad("WRONG_STAGE", head?.type, `chain ends at ${head?.type}, expected ${expected.stage}`);
+  }
+  return { ok: problems.length === 0, problems, head: isObj(head) ? { type: head.type, hash: receiptHash(head) } : null };
+}
+
+/**
+ * Verify that a new stage may start: the chain so far must verify and end at the stage `stage` requires.
+ * Returns the same result shape; `authorizes` is the stage the chain authorizes next (or null).
+ */
+export function authorizeNextStage(chain, stage, options = {}) {
+  const need = PREREQUISITES[stage];
+  if (!need) return { ok: false, problems: [{ code: "UNKNOWN_STAGE", stage, message: `unknown stage ${stage}` }], head: null, authorizes: null };
+  if (need.length === 0) return { ok: !chain?.length, problems: chain?.length ? [{ code: "WRONG_STAGE", stage, message: "ADMISSION starts a chain" }] : [], head: null, authorizes: chain?.length ? null : stage };
+  const result = verifyReceiptChain(chain, { ...options, expected: { ...(options.expected ?? {}), stage: need[0] } });
+  // The requested stage itself must sit inside the operation's boundary and ADMISSION's authorized stages.
+  const first = Array.isArray(chain) ? chain[0] : null;
+  const last = OPERATION_LAST_STAGE[first?.operation];
+  if (!last || STAGES.indexOf(stage) > STAGES.indexOf(last)) result.problems.push({ code: "WRONG_OPERATION", stage, message: `operation ${first?.operation} does not authorize ${stage}` });
+  const admission = first?.type === "ADMISSION" && isObj(first.evidence) ? first.evidence : null;
+  for (const x of admissionProblems(admission, stage)) result.problems.push({ code: x.code, stage, message: x.message });
+  result.ok = result.problems.length === 0;
+  return { ...result, authorizes: result.ok ? stage : null };
+}

package/pipeline-scan.mjs

@@ -0,0 +1,285 @@
+// M24 `--enforce` inventory: find every way an app can own, or indirectly start, a build, sign, notarize, package or upload step.
+//
+// Sources read (R2 framework hooks, R3 tool inventory, R1 alias traversal):
+//   - the release config (`right-release.config.json`: every command admitted by R1; a legacy `.mjs` config is a finding and is never opened),
+//   - package.json scripts and npm lifecycle hooks, with aliases followed to the helper files they reach,
+//   - helper and pipeline scripts under scripts/, tools/, ci/, build/, bin/, packaging/ and the app root,
+//   - GitHub workflows (a `# Managed by right-git` workflow is RightKit-owned and only inventoried),
+//   - Tauri before-dev / before-build / before-bundle hooks and signing keys in tauri.conf.json,
+//   - Cargo `build.rs` (signing or upload is forbidden; spawning an interpreter or RightKit is a generator that must be admitted),
+//   - Xcode script phases (`project.pbxproj`, XcodeGen `project.yml`).
+// A finding names its file, line, stage and ownership (`app-owned` when the app wrote the pipeline step, `unknown` when ownership could
+// not be established, which blocks exactly like an app-owned step). Every finding blocks `--enforce`. This is a static scan: it cannot
+// prove native behaviour, and ordinary product runtime code (src/, crates) is never read except build.rs.
+import { existsSync, lstatSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { admitHookString, admitTauriHook } from "./pipeline-admission.mjs";
+import { loadGeneratorRegistry, makeGeneratorAdmitter } from "./pipeline-generators.mjs";
+import { ownershipOfCode, ruleOfCode, validateConfigPipeline } from "./pipeline-config.mjs";
+import { classifyAction, dispatchesRightKit, scanTextForPipelineTools, segmentTokens, splitSegments } from "./pipeline-tools.mjs";
+import { LEGACY_RELEASE_CONFIG_FILE, RELEASE_CONFIG_FILE, loadReleaseConfigSync } from "./release-config.mjs";
+import { PIPELINE_DISPATCH_SUBCOMMANDS } from "./pipeline-admission.mjs";
+
+export const PIPELINE_SCAN_SCHEMA = 1;
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+const MAX_FILES = 5000;
+const SKIP_DIRS = new Set(["node_modules", "target", "dist", ".git", ".cache", ".right-release", ".pnpm-store", "coverage", "Pods", "DerivedData", ".build", ".swiftpm"]);
+const SCRIPT_DIRS = ["scripts", "script", "tools", "tool", "ci", ".ci", "build", "bin", "packaging", "installer", "installers", "release", "deploy", ".husky", ".githooks"];
+const SHELL_EXT = /\.(?:sh|ps1|bat|cmd|command|bash|zsh)$/i;
+const CODE_EXT = /\.(?:mjs|cjs|js|ts|mts|py|rb)$/i;
+const HELPER_REF = /\.(?:sh|ps1|bat|cmd|command|bash|zsh|mjs|cjs|js|py)$/i;
+const MANAGED_MARKER = /#\s*Managed by right-git/i;
+const AUTO_LIFECYCLE = new Set(["preinstall", "install", "postinstall", "prepublish", "preprepare", "prepare", "postprepare", "prepack", "postpack", "prepublishOnly", "publish", "postpublish"]);
+const posix = (value) => value.split(path.sep).join("/");
+
+const defaultFs = {
+  readText: (file) => readFileSync(file, "utf8"),
+  exists: (file) => existsSync(file),
+  readdir: (dir) => readdirSync(dir, { withFileTypes: true }).map((entry) => ({ name: entry.name, isDirectory: entry.isDirectory(), isSymlink: entry.isSymbolicLink(), isFile: entry.isFile() })),
+  size: (file) => lstatSync(file).size,
+};
+
+const lineAt = (text, index) => { let line = 1; for (let i = 0; i < index && i < text.length; i += 1) if (text[i] === "\n") line += 1; return line; };
+
+/** Run the inventory for one app. `fs` is injectable. Returns `{ schema, app, root, findings, inventory, scanned }`. */
+export function scanApp({ appRoot, registry, fs = defaultFs } = {}) {
+  const root = path.resolve(appRoot);
+  const findings = [];
+  const inventory = [];
+  const visited = new Set();
+  let budget = MAX_FILES;
+  const rel = (file) => posix(path.relative(root, file));
+  const add = (finding) => findings.push({ severity: "block", ownership: ownershipOfCode(finding.code), rule: ruleOfCode(finding.code), line: 1, ...finding });
+  const read = (file, label = rel(file)) => {
+    if (budget <= 0) { add({ code: "R0-too-many-files", file: label, stage: "scan", message: `more than ${MAX_FILES} files reached; the inventory is incomplete and unknown ownership blocks` }); return null; }
+    budget -= 1;
+    try {
+      if (fs.size && fs.size(file) > MAX_FILE_BYTES) { add({ code: "R0-unreadable", file: label, stage: "scan", message: `${label} is larger than ${MAX_FILE_BYTES} bytes and cannot be inspected` }); return null; }
+      return fs.readText(file);
+    } catch (error) {
+      add({ code: "R0-unreadable", file: label, stage: "scan", message: `${label} cannot be read (${error.message})` });
+      return null;
+    }
+  };
+
+  // ---- package.json ------------------------------------------------------------------------------------------------------------
+  let scripts;
+  let packageText = "";
+  const packageFile = path.join(root, "package.json");
+  if (fs.exists(packageFile)) {
+    packageText = read(packageFile) ?? "";
+    try {
+      const parsed = JSON.parse(packageText || "{}");
+      if (parsed.scripts && typeof parsed.scripts === "object" && !Array.isArray(parsed.scripts)) scripts = parsed.scripts;
+    } catch (error) { add({ code: "R0-package-json", file: "package.json", stage: "scan", message: `package.json is not valid JSON (${error.message}); script ownership is unknown` }); }
+  }
+
+  // ---- release config (R1) -----------------------------------------------------------------------------------------------------
+  const configFile = path.join(root, RELEASE_CONFIG_FILE);
+  const legacyFile = path.join(root, LEGACY_RELEASE_CONFIG_FILE);
+  let config;
+  if (fs.exists(legacyFile)) {
+    add({ code: "R0-legacy-config", file: LEGACY_RELEASE_CONFIG_FILE, stage: "config", ownership: "app-owned", message: `${LEGACY_RELEASE_CONFIG_FILE} is an executable release config; it is never imported, evaluated or converted. Replace it with ${RELEASE_CONFIG_FILE}.` });
+    inventory.push({ kind: "config", file: LEGACY_RELEASE_CONFIG_FILE, ownership: "app-owned-executable" });
+  }
+  let admitGenerator;
+  const useRegistry = registry ?? (() => { try { return loadGeneratorRegistry(); } catch { return undefined; } })();
+  if (fs.exists(configFile)) {
+    inventory.push({ kind: "config", file: RELEASE_CONFIG_FILE, ownership: "rightkit-schema" });
+    try {
+      const loaded = loadReleaseConfigSync(configFile, { validatePipeline: false, readText: (target) => fs.readText(target) });
+      config = loaded.config;
+      for (const finding of validateConfigPipeline(config, { scripts, registry: useRegistry, appRoot: root, lineOf: loaded.lineOf })) {
+        add({ code: finding.code, file: RELEASE_CONFIG_FILE, line: finding.line, stage: finding.stage, ownership: finding.ownership, message: `${finding.pointer}: ${finding.message}` });
+      }
+    } catch (error) {
+      add({ code: `R0-${String(error.code ?? "config-invalid").toLowerCase().replace(/^release_config_/, "config-").replaceAll("_", "-")}`, file: RELEASE_CONFIG_FILE, line: error.line ?? 1, stage: "config", ownership: "unknown", message: error.message });
+    }
+  } else if (!fs.exists(legacyFile)) {
+    add({ code: "R0-config-missing", file: RELEASE_CONFIG_FILE, stage: "config", ownership: "unknown", message: `${RELEASE_CONFIG_FILE} is missing: the app's pipeline ownership cannot be established` });
+  }
+  if (useRegistry) admitGenerator = makeGeneratorAdmitter({ registry: useRegistry, app: config?.app ?? path.basename(root), appRoot: root, readBytes: (file) => Buffer.from(fs.readText(file), "utf8") });
+  const aliasOptions = { scripts, admitGenerator };
+
+  // ---- helper queue (scripts reachable from pipeline entries, scripts directories) ----------------------------------------------
+  const queue = [];
+  const enqueue = (file, via) => { const key = path.resolve(file); if (!visited.has(key)) { visited.add(key); queue.push({ file: key, via }); } };
+  const refsIn = (text) => {
+    const refs = new Set();
+    for (const line of String(text).split(/\r?\n/)) {
+      for (const segment of splitSegments(line)) {
+        for (const token of segmentTokens(segment)) {
+          if (!HELPER_REF.test(token) || token.startsWith("-") || /^[a-z]+:\/\//i.test(token)) continue;
+          const normalized = token.replaceAll("\\", "/").replace(/^(?:\.\/)+/, "");
+          if (path.posix.isAbsolute(normalized) || /^[A-Za-z]:/.test(normalized) || normalized.split("/").includes("..") || normalized.includes("$") || normalized.includes("*")) continue;
+          refs.add(normalized);
+        }
+      }
+    }
+    return [...refs];
+  };
+
+  if (scripts) {
+    const scriptNames = Object.keys(scripts);
+    for (const name of scriptNames) {
+      const body = scripts[name];
+      const lineOfScript = () => { const at = packageText.search(new RegExp(`"${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}"\\s*:`)); return at >= 0 ? lineAt(packageText, at) : 1; };
+      if (typeof body !== "string") { add({ code: "R1-alias-unknown", file: "package.json", line: lineOfScript(), stage: "script", message: `package script "${name}" is not a string` }); continue; }
+      inventory.push({ kind: "package-script", file: "package.json", name, ownership: "app-script" });
+      for (const hit of scanTextForPipelineTools(body, { kind: "shell" })) {
+        add({ code: `R3-${hit.id}`, file: "package.json", line: lineOfScript(), stage: hit.stage, ownership: "app-owned", tool: hit.tool, message: `script "${name}" runs ${hit.tool} (${hit.stage}); build, sign, notarize, package and upload run only inside RightKit (right-release)` });
+      }
+      const lifecycle = AUTO_LIFECYCLE.has(name) || (/^(?:pre|post)(.+)$/.test(name) && scriptNames.includes(name.replace(/^(?:pre|post)/, "")));
+      if (lifecycle) {
+        const admitted = admitHookString(body, aliasOptions, [name]);
+        if (!admitted.admitted) add({ code: admitted.code.replace(/^R\d/, "R2"), file: "package.json", line: lineOfScript(), stage: "hook", message: `npm lifecycle hook "${name}": ${admitted.reason}` });
+      }
+      for (const ref of refsIn(body)) enqueue(path.join(root, ref), `package.json scripts.${name}`);
+    }
+  }
+
+  // ---- script directories and root-level scripts -------------------------------------------------------------------------------
+  const walkDir = (dir, depth) => {
+    let entries;
+    try { entries = fs.readdir(dir); } catch { return; }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory) { if (depth > 0 && !SKIP_DIRS.has(entry.name)) walkDir(full, depth - 1); continue; }
+      if (!(SHELL_EXT.test(entry.name) || CODE_EXT.test(entry.name) || /^(?:Makefile|justfile)$/i.test(entry.name))) continue;
+      if (entry.isSymlink) { add({ code: "R0-symlink", file: rel(full), stage: "scan", message: `${rel(full)} is a symlink; a linked script's owner cannot be established` }); continue; }
+      enqueue(full, `pipeline directory ${rel(dir) || "."}`);
+    }
+  };
+  for (const dir of SCRIPT_DIRS) if (fs.exists(path.join(root, dir))) walkDir(path.join(root, dir), 4);
+  try {
+    for (const entry of fs.readdir(root)) {
+      if (entry.isDirectory || entry.isSymlink) continue;
+      if (SHELL_EXT.test(entry.name) || /^(?:Makefile|justfile)$/i.test(entry.name) || /^(?:package|build|release|sign|notarize|install|deploy)[-_.a-z0-9]*\.(?:mjs|cjs|js|py)$/i.test(entry.name)) enqueue(path.join(root, entry.name), "app root");
+    }
+  } catch { /* an unreadable root is reported by the reads above */ }
+
+  // The queue grows while it drains: a helper's own references join it.
+  for (let index = 0; index < queue.length; index += 1) {
+    const { file, via } = queue[index];
+    const label = rel(file);
+    if (!fs.exists(file)) { add({ code: "R1-helper-missing", file: label, stage: "script", ownership: "unknown", message: `${label} is reached from ${via} but does not exist; an unknown reachable script blocks` }); continue; }
+    const text = read(file, label);
+    if (text === null) continue;
+    const isShell = SHELL_EXT.test(file) || /(?:Makefile|justfile)$/i.test(file);
+    inventory.push({ kind: "helper-script", file: label, via, ownership: "app-owned" });
+    for (const hit of scanTextForPipelineTools(text, { kind: isShell ? "shell" : "code" })) {
+      add({ code: `R3-${hit.id}`, file: label, line: hit.line, stage: hit.stage, ownership: "app-owned", tool: hit.tool, message: `${label} (from ${via}) runs ${hit.tool} (${hit.stage}); this is an app-owned pipeline script` });
+    }
+    if (isShell) for (const ref of refsIn(text)) enqueue(path.resolve(path.dirname(file), ref).startsWith(root) && fs.exists(path.resolve(path.dirname(file), ref)) ? path.resolve(path.dirname(file), ref) : path.join(root, ref), `${label}`);
+  }
+
+  // ---- GitHub workflows --------------------------------------------------------------------------------------------------------
+  const workflowDir = path.join(root, ".github", "workflows");
+  if (fs.exists(workflowDir)) {
+    for (const entry of fs.readdir(workflowDir)) {
+      if (entry.isDirectory || !/\.ya?ml$/i.test(entry.name)) continue;
+      const file = path.join(workflowDir, entry.name);
+      const label = rel(file);
+      const text = read(file, label);
+      if (text === null) continue;
+      const managed = MANAGED_MARKER.test(text.split(/\r?\n/).slice(0, 10).join("\n"));
+      inventory.push({ kind: "workflow", file: label, ownership: managed ? "rightkit-managed" : "app-owned" });
+      if (managed) continue;
+      for (const hit of scanTextForPipelineTools(text, { kind: "shell" })) {
+        add({ code: `R3-${hit.id}`, file: label, line: hit.line, stage: hit.stage, ownership: "app-owned", tool: hit.tool, message: `workflow ${label} runs ${hit.tool} (${hit.stage}); pipeline workflows are generated and owned by right-git (carry the "Managed by right-git" marker)` });
+      }
+      text.split(/\r?\n/).forEach((lineText, i) => {
+        const uses = /^\s*(?:-\s+)?uses\s*:\s*(\S+)/.exec(lineText);
+        const hit = uses ? classifyAction(uses[1]) : null;
+        if (hit) add({ code: `R3-${hit.id}`, file: label, line: i + 1, stage: hit.stage, ownership: "app-owned", tool: hit.tool, message: `workflow ${label} uses ${hit.tool}, an action that ${hit.stage}s on its own` });
+      });
+    }
+  }
+
+  // ---- framework hooks: Tauri, build.rs, Xcode --------------------------------------------------------------------------------
+  const projectFiles = [];
+  const find = (dir, depth) => {
+    let entries;
+    try { entries = fs.readdir(dir); } catch { return; }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory) {
+        if (/\.xcodeproj$/i.test(entry.name)) { projectFiles.push({ kind: "xcode", file: path.join(full, "project.pbxproj") }); continue; }
+        if (depth > 0 && !SKIP_DIRS.has(entry.name) && !entry.name.startsWith(".")) find(full, depth - 1);
+        continue;
+      }
+      if (/^tauri(?:\.[A-Za-z0-9_-]+)?\.conf\.json$/i.test(entry.name)) projectFiles.push({ kind: "tauri", file: full });
+      else if (entry.name === "build.rs") projectFiles.push({ kind: "build-rs", file: full });
+      else if (entry.name === "project.yml" || entry.name === "project.yaml") projectFiles.push({ kind: "xcodegen", file: full });
+    }
+  };
+  find(root, 4);
+  for (const item of projectFiles) {
+    if (!fs.exists(item.file)) continue;
+    const label = rel(item.file);
+    const text = read(item.file, label);
+    if (text === null) continue;
+    if (item.kind === "tauri") scanTauriConf(text, label);
+    else if (item.kind === "build-rs") scanBuildRs(text, label);
+    else scanXcode(text, label, item.kind);
+  }
+
+  function scanTauriConf(text, label) {
+    inventory.push({ kind: "tauri-config", file: label, ownership: "framework-config" });
+    let parsed;
+    try { parsed = JSON.parse(text); } catch (error) { add({ code: "R0-unreadable", file: label, stage: "hook", message: `${label} is not valid JSON (${error.message}); its hooks are unknown` }); return; }
+    const keyLine = (key) => { const at = text.search(new RegExp(`"${key}"\\s*:`)); return at >= 0 ? lineAt(text, at) : 1; };
+    for (const key of ["beforeDevCommand", "beforeBuildCommand", "beforeBundleCommand"]) {
+      const entry = parsed?.build?.[key];
+      if (entry === undefined || entry === null || entry === "") continue;
+      const problem = admitTauriHook(entry, aliasOptions, `${label} build.${key}`);
+      if (problem) add({ code: problem.code.replace(/^R\d/, "R2"), file: label, line: keyLine(key), stage: "hook", message: problem.reason });
+    }
+    const windows = parsed?.bundle?.windows ?? {};
+    if (windows.signCommand !== undefined && windows.signCommand !== null) add({ code: "R3-tauri-sign-hook", file: label, line: keyLine("signCommand"), stage: "sign", ownership: "app-owned", message: `${label} bundle.windows.signCommand is a sign hook; signing is RightKit's` });
+    if (typeof windows.certificateThumbprint === "string" && windows.certificateThumbprint) add({ code: "R3-tauri-sign-config", file: label, line: keyLine("certificateThumbprint"), stage: "sign", ownership: "app-owned", message: `${label} bundle.windows.certificateThumbprint selects a signing identity; signing is RightKit's` });
+    const identity = parsed?.bundle?.macOS?.signingIdentity;
+    if (typeof identity === "string" && identity !== "-" && identity !== "") add({ code: "R3-tauri-sign-config", file: label, line: keyLine("signingIdentity"), stage: "sign", ownership: "app-owned", message: `${label} bundle.macOS.signingIdentity selects a signing identity; signing is RightKit's` });
+  }
+
+  function scanBuildRs(text, label) {
+    inventory.push({ kind: "build-rs", file: label, ownership: "product-compile" });
+    for (const hit of scanTextForPipelineTools(text, { kind: "code" })) {
+      add({ code: `R2-build-rs-${hit.id}`, file: label, line: hit.line, stage: hit.stage, ownership: "app-owned", tool: hit.tool, message: `${label} runs ${hit.tool} (${hit.stage}); signing, packaging or upload from build.rs is forbidden` });
+    }
+    text.split(/\r?\n/).forEach((lineText, i) => {
+      if (/^\s*\/\//.test(lineText)) return;
+      const spawn = /Command::new\(\s*"([^"]+)"/.exec(lineText);
+      if (!spawn) return;
+      const name = path.basename(spawn[1]).toLowerCase().replace(/\.(?:exe|cmd|bat)$/, "");
+      if (name === "rightkit" || name === "right-release") add({ code: "R2-build-rs-dispatch", file: label, line: i + 1, stage: "hook", ownership: "app-owned", message: `${label} starts ${name} from build.rs; a generator cannot dispatch another pipeline` });
+      else if (["node", "python", "python3", "py", "bash", "sh", "zsh", "pwsh", "powershell", "cmd", "pnpm", "npm", "npx", "yarn", "deno", "bun", "ruby", "perl"].includes(name)) add({ code: "R4-build-rs-generator", file: label, line: i + 1, stage: "generator", ownership: "unknown", message: `${label} runs ${name} from build.rs; a pipeline generator must be an admitted shared step (pipeline-generators.json), not app code` });
+    });
+  }
+
+  function scanXcode(text, label, kind) {
+    inventory.push({ kind: kind === "xcode" ? "xcode-project" : "xcodegen-spec", file: label, ownership: "framework-config" });
+    let bodies;
+    if (kind === "xcode") {
+      bodies = [...text.matchAll(/shellScript\s*=\s*"((?:[^"\\]|\\.)*)"\s*;/g)].map((match) => ({ line: lineAt(text, match.index), script: match[1].replace(/\\n/g, "\n").replace(/\\t/g, "\t").replace(/\\"/g, '"').replace(/\\\\/g, "\\") }));
+    } else bodies = [{ line: 1, script: text }];
+    for (const body of bodies) {
+      for (const hit of scanTextForPipelineTools(body.script, { kind: "shell" })) {
+        add({ code: `R2-xcode-script-${hit.id}`, file: label, line: kind === "xcode" ? body.line : hit.line, stage: hit.stage, ownership: "app-owned", tool: hit.tool, message: `${label} script phase runs ${hit.tool} (${hit.stage}); archive, export, signing and upload belong to RightKit` });
+      }
+      for (const segment of body.script.split(/\r?\n/).flatMap(splitSegments)) {
+        const tokens = segmentTokens(segment);
+        if (dispatchesRightKit(tokens) && (tokens[0] === "rightkit" || PIPELINE_DISPATCH_SUBCOMMANDS.has(tokens[1]))) add({ code: "R2-xcode-script-dispatch", file: label, line: kind === "xcode" ? body.line : 1, stage: "hook", ownership: "app-owned", message: `${label} script phase starts a RightKit pipeline run; a hook cannot dispatch another pipeline` });
+      }
+    }
+  }
+
+  findings.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : a.line - b.line));
+  return { schema: PIPELINE_SCAN_SCHEMA, app: config?.app ?? path.basename(root), root, findings, inventory, scanned: visited.size };
+}
+
+export function formatScan(report) {
+  const lines = [`M24 pipeline scan: ${report.app} (${report.root}) - ${report.findings.length} blocking finding(s), ${report.inventory.length} inventoried entrypoint(s)`];
+  for (const finding of report.findings) lines.push(`  ${finding.file}:${finding.line} [${finding.code}] ${finding.stage} (${finding.ownership}) ${finding.message}`);
+  return `${lines.join("\n")}\n`;
+}