@rightkit/release 0.6.5 → 0.6.7

package/publish-cargo.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import fs from "node:fs";
 import path from "node:path";
+import { createHash } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { enforcePublicationGate, defaultEvidencePath, provenGateSteps, singleHostOfPolicy, batchClippyMissingFeatureSets } from "./publication-gate.mjs";
 import { runCargoSync } from "./managed-cargo.mjs";
@@ -12,9 +13,10 @@ import { recordPublished, workspaceFeedOptions } from "./rightkit-sync.mjs";
 import { readCargoPackage } from "./crate-graph.mjs";
 import { runtimeBudgetCheck, RUNTIME_BUDGET_CODE } from "./runtime-budgets.mjs";
 import { formatPreflight, PREFLIGHT_FAIL } from "./preflight.mjs";
+import { cargoManifestState } from "./cargo-manifest-text.mjs";
 
 const FORBIDDEN_PACKAGE_PATH = /(^|\/)(?:\.env(?:\.[^/]*)?|target(?:\/.*)?|node_modules(?:\/.*)?|[^/]+\.(?:p8|p12|pem|key))$/i;
-const SECRET_PATTERNS = [
+export const SECRET_PATTERNS = [
   /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/,
   /\bAKIA[0-9A-Z]{16}\b/,
   /\bgh[pousr]_[A-Za-z0-9_]{20,}\b/,
@@ -139,7 +141,202 @@ export function packageFileViolations(files) {
     .filter((file) => FORBIDDEN_PACKAGE_PATH.test(file));
 }
 
-export function scanCrateForSecrets(crateDir) {
+// ---- the secret scan ---------------------------------------------------------------------------------------------------
+//
+// Strict (the default): a crate package, its archive and the local-publish batch scan. `scanCrateForSecrets(dir)` returns the
+// relative paths that are refused by name (FORBIDDEN_PACKAGE_PATH, which includes every .env* file, so env templates too) or whose
+// content matches SECRET_PATTERNS. Nothing published needs a template or a test vector, and the records file below is never read.
+//
+// Repository gate (`{ envTemplates: true }`, deterministic-scans.mjs "secret-scan"): the units of a commit that is not being
+// published. An app legitimately commits env templates (`.env.example`) and test vectors for its own redaction and screening code,
+// and no content heuristic tells a placeholder from a pasted credential, so a file is admitted by a reviewed record, not by a guess.
+// `.rightkit/secret-scan-records.json` in the repository:
+//   { "schema": 1, "records": [ { "path": "<repo-relative>", "sha256": "<hex of the bytes, CRLF read as LF>", "kind": "env-template" | "fixture", "note": "<what it holds and why it is safe>" } ] }
+//  - an env template (.env.example, .env.<name>.example, .env.sample, .env.template) is admitted only by a record of kind
+//    "env-template" whose sha256 is the file's: any edit needs a new record, which is the review, in the pull request diff;
+//  - any other file whose content matches SECRET_PATTERNS is admitted only by a record of kind "fixture" with the file's sha256;
+//  - never recordable: .env and every .env.* that is not a template, *.pem, *.p8, *.p12, *.key (refused by name, and a record naming
+//    one is itself a violation); a template that is not UTF-8 (NUL bytes, a UTF-16 mark), that holds a PEM private key header or one
+//    of the other high-precision credential shapes below, or that sits inside a publishable crate or package is refused even when recorded;
+//  - a malformed records file is a violation and admits nothing.
+// Each violation is `<path>[:<line>]: <reason>`; a hit names the line and the shape, never the matched text.
+export const SECRET_SCAN_RECORDS_FILE = ".rightkit/secret-scan-records.json";
+const RECORD_KINDS = Object.freeze(["env-template", "fixture"]);
+const RECORD_KEYS = Object.freeze(["path", "sha256", "kind", "note"]);
+const RECORD_NOTE_PLACEHOLDER = "<what it holds and why it is safe>";
+const ENV_TEMPLATE = /(^|\/)\.env(?:\.[^/]*)?\.(?:example|sample|template)$/i;
+// Labels of SECRET_PATTERNS, index for index.
+const SECRET_PATTERN_LABELS = Object.freeze(["a PEM private key header", "an AWS access key id (AKIA)", "a GitHub token (gh*_)", "an npm token (npm_)"]);
+// Credential shapes that are never a placeholder, matched in env templates besides SECRET_PATTERNS. Every expression is linear:
+// each quantified class is followed by a delimiter it cannot match or by the end of the match.
+const TEMPLATE_SHAPES = Object.freeze([
+  [/-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----/, "a PEM private key header"],
+  [/github_pat_[A-Za-z0-9_]{22,}/, "a GitHub fine-grained token (github_pat_)"],
+  [/sk_live_[A-Za-z0-9]{16,}/, "a Stripe live key (sk_live_)"],
+  [/xox[abprs]-[A-Za-z0-9-]{10,}/, "a Slack token (xox*-)"],
+  [/AIza[0-9A-Za-z_-]{35}/, "a Google API key (AIza)"],
+  [/hooks\.slack\.com\/services\/T[A-Z0-9]+\/B[A-Z0-9]+\/[A-Za-z0-9]+/, "a Slack webhook URL"],
+]);
+const FILE_SHAPES = Object.freeze(SECRET_PATTERNS.map((pattern, index) => [pattern, SECRET_PATTERN_LABELS[index]]));
+const TEMPLATE_ALL_SHAPES = Object.freeze([...FILE_SHAPES, ...TEMPLATE_SHAPES]);
+const UTF8 = new TextDecoder("utf-8", { fatal: true });
+
+const neverRecordable = (relative) => FORBIDDEN_PACKAGE_PATH.test(relative) && !ENV_TEMPLATE.test(relative);
+const sha256Hex = (bytes) => createHash("sha256").update(bytes).digest("hex");
+// A record's digest reads CRLF as LF, so one record holds on every host: `git archive` (the gate's export) writes CRLF on a
+// Windows host with `core.autocrlf=true` or `core.eol=crlf` for `text=auto` files and LF elsewhere. The content checks still read
+// the bytes as exported; a lone CR is kept, so no other byte is ever ignored.
+const recordDigest = (bytes) => sha256Hex(Buffer.from(Buffer.from(bytes).toString("latin1").replace(/\r\n/g, "\n"), "latin1"));
+const recordLine = (relative, sha256, kind) => JSON.stringify({ path: relative, sha256, kind, note: RECORD_NOTE_PLACEHOLDER });
+const repoRelativePath = (p) => p !== "" && p !== "." && !p.includes("\\") && !p.includes("\0") && !p.startsWith("/") && !/^[A-Za-z]:/.test(p) && !p.endsWith("/")
+  && path.posix.normalize(p) === p && !p.split("/").includes("..");
+
+/** `{ records: Map<path, { sha256, kind, note }>, problems: string[] }` from the text of the records file (undefined: no file). A record with a problem admits nothing. */
+export function parseSecretScanRecords(text) {
+  const records = new Map();
+  const problems = [];
+  const bad = (message) => problems.push(`${SECRET_SCAN_RECORDS_FILE}: ${message}`);
+  if (text === undefined) return { records, problems };
+  let doc;
+  try { doc = JSON.parse(String(text).replace(/^/, "")); } catch (error) { bad(`is not valid JSON (${error.message})`); return { records, problems }; }
+  if (doc === null || typeof doc !== "object" || Array.isArray(doc)) { bad('must be an object { "schema": 1, "records": [...] }'); return { records, problems }; }
+  for (const key of Object.keys(doc)) if (key !== "schema" && key !== "records") bad(`has an unknown key ${JSON.stringify(key)}`);
+  if (doc.schema !== 1) { bad(`schema must be 1 (found ${JSON.stringify(doc.schema)}); no record is read`); return { records, problems }; }
+  if (!Array.isArray(doc.records)) { bad('"records" must be an array'); return { records, problems }; }
+  const counts = new Map();
+  const valid = [];
+  doc.records.forEach((record, index) => {
+    if (record === null || typeof record !== "object" || Array.isArray(record)) { bad(`record ${index} must be an object`); return; }
+    const label = typeof record.path === "string" ? `record ${index} (${JSON.stringify(record.path)})` : `record ${index}`;
+    let ok = true;
+    const fail = (message) => { bad(`${label}: ${message}`); ok = false; };
+    for (const key of Object.keys(record)) if (!RECORD_KEYS.includes(key)) fail(`has an unknown key ${JSON.stringify(key)}`);
+    if (typeof record.path !== "string" || !repoRelativePath(record.path)) fail('"path" must be a normalised repository-relative path with forward slashes');
+    if (typeof record.sha256 !== "string" || !/^[0-9a-f]{64}$/i.test(record.sha256)) fail('"sha256" must be 64 hex characters, the sha256 of the file bytes with CRLF read as LF');
+    if (!RECORD_KINDS.includes(record.kind)) fail(`"kind" must be one of ${RECORD_KINDS.join(", ")}`);
+    if (typeof record.note !== "string" || record.note.trim() === "" || record.note.trim() === RECORD_NOTE_PLACEHOLDER) fail('"note" must say what the file holds and why it is safe');
+    if (typeof record.path === "string") counts.set(record.path, (counts.get(record.path) ?? 0) + 1);
+    if (!ok) return;
+    if (neverRecordable(record.path)) fail("names a path that can never be recorded (.env and every .env.* that is not a template, *.pem, *.p8, *.p12, *.key)");
+    else if (record.kind === "env-template" && !ENV_TEMPLATE.test(record.path)) fail('kind "env-template" names a path that is not an env template (.env.example, .env.<name>.example, .env.sample, .env.template)');
+    else if (record.kind === "fixture" && ENV_TEMPLATE.test(record.path)) fail('kind "fixture" cannot admit an env template; record it as "env-template"');
+    else valid.push(record);
+  });
+  for (const [recorded, count] of counts) if (count > 1) bad(`${JSON.stringify(recorded)} is recorded ${count} times; keep one record per path`);
+  for (const record of valid) if (counts.get(record.path) === 1) records.set(record.path, { sha256: record.sha256.toLowerCase(), kind: record.kind, note: record.note });
+  return { records, problems };
+}
+
+// The records file of the repository being scanned, read as data: a regular file whose real path stays inside the repository.
+function readSecretScanRecords(repoRoot) {
+  const file = path.join(repoRoot, SECRET_SCAN_RECORDS_FILE);
+  try {
+    if (!fs.lstatSync(file).isFile()) return { problems: [`${SECRET_SCAN_RECORDS_FILE}: is not a regular file`] };
+    const relative = path.relative(fs.realpathSync(repoRoot), fs.realpathSync(file));
+    if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return { problems: [`${SECRET_SCAN_RECORDS_FILE}: resolves outside the repository`] };
+    return parseSecretScanRecords(fs.readFileSync(file, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT" || error?.code === "ENOTDIR") return parseSecretScanRecords(undefined);
+    return { problems: [`${SECRET_SCAN_RECORDS_FILE}: cannot be read (${error?.code ?? error?.message})`] };
+  }
+}
+
+/** Why a file is not UTF-8 text (NUL bytes, a UTF-16 byte-order mark, an invalid sequence), or null. */
+function notUtf8(bytes) {
+  if (bytes.length >= 2 && ((bytes[0] === 0xff && bytes[1] === 0xfe) || (bytes[0] === 0xfe && bytes[1] === 0xff))) return "starts with a UTF-16 byte-order mark";
+  if (bytes.includes(0)) return "contains NUL bytes";
+  try { UTF8.decode(bytes); } catch { return "is not valid UTF-8"; }
+  return null;
+}
+
+/**
+ * `[{ label, lines }]` for the shapes that match `text`: at most the first five matching lines of each, found in one pass.
+ * After a hit the search resumes on the next line, so the work is linear in the text however many matches a line holds.
+ */
+function contentHits(text, shapes) {
+  const hits = new Map();
+  for (const [shape, label] of shapes) {
+    const pattern = new RegExp(shape.source, `${shape.flags.replace("g", "")}g`);
+    const lines = hits.get(label) ?? [];
+    let line = 1;
+    let newline = text.indexOf("\n");
+    for (let match = pattern.exec(text); match !== null && lines.length < 5; match = pattern.exec(text)) {
+      while (newline !== -1 && newline < match.index) { line += 1; newline = text.indexOf("\n", newline + 1); }
+      if (!lines.includes(line)) lines.push(line);
+      pattern.lastIndex = newline === -1 ? text.length : newline + 1;
+    }
+    if (lines.length) hits.set(label, lines);
+  }
+  const found = [...hits].map(([label, lines]) => ({ label, lines: [...lines].sort((a, b) => a - b).slice(0, 5) }));
+  return found.sort((a, b) => a.lines[0] - b.lines[0] || (a.label < b.label ? -1 : 1));
+}
+
+const hitsText = (hits) => hits.map((hit) => `${hit.label} (line${hit.lines.length > 1 ? "s" : ""} ${hit.lines.join(", ")})`).join("; ");
+const firstLine = (hits) => Math.min(...hits.flatMap((hit) => hit.lines));
+
+// The publishable crate or package that holds `file`, or null: the nearest Cargo.toml and the nearest package.json at or above
+// it, up to the repository root. A crate is publishable when its [package] does not say publish = false / []; a package when its
+// package.json is not "private": true. A manifest that cannot be read counts as publishable.
+function publishableOwner(file, repoRoot) {
+  const root = path.resolve(repoRoot);
+  const shown = (dir) => path.relative(root, dir).replaceAll("\\", "/") || ".";
+  let cargoDecided = false;
+  let npmDecided = false;
+  for (let dir = path.dirname(path.resolve(file)); ; dir = path.dirname(dir)) {
+    const outside = path.relative(root, dir);
+    if (outside === ".." || outside.startsWith(`..${path.sep}`) || path.isAbsolute(outside)) return null;
+    if (!cargoDecided && fs.existsSync(path.join(dir, "Cargo.toml"))) {
+      cargoDecided = true;
+      let state = null;
+      try { state = cargoManifestState(fs.readFileSync(path.join(dir, "Cargo.toml"), "utf8")); } catch { /* unreadable: publishable */ }
+      if (state === null || (state.hasPackage && !state.unpublished)) return `the publishable crate at ${shown(dir)} (its Cargo.toml [package] does not say publish = false)`;
+    }
+    if (!npmDecided && fs.existsSync(path.join(dir, "package.json"))) {
+      npmDecided = true;
+      let manifest = null;
+      try { manifest = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8").replace(/^/, "")); } catch { /* unreadable: publishable */ }
+      if (manifest?.private !== true) return `the publishable package at ${shown(dir)} (its package.json is not "private": true)`;
+    }
+    if ((cargoDecided && npmDecided) || dir === root || path.dirname(dir) === dir) return null;
+  }
+}
+
+function envTemplateViolations(relative, file, bytes, records, repoRoot) {
+  const owner = publishableOwner(file, repoRoot);
+  const encoding = notUtf8(bytes);
+  const hits = encoding === null ? contentHits(bytes.toString("utf8"), TEMPLATE_ALL_SHAPES) : [];
+  const refused = [];
+  if (owner) refused.push(`${relative}: env template inside ${owner}; a publishable unit never carries one (refused by name, as at publish time and in the archive scan). Move it out of the unit, or mark the unit unpublished`);
+  if (encoding) refused.push(`${relative}: env template ${encoding}, so it cannot be read as UTF-8 text; refused even when recorded. Save it as UTF-8`);
+  if (hits.length) refused.push(`${relative}:${firstLine(hits)}: env template matches ${hitsText(hits)}; refused even when recorded. Replace the value with a placeholder`);
+  if (refused.length) return refused;
+  const sha256 = recordDigest(bytes);
+  const record = records.get(relative);
+  if (record?.kind === "env-template" && record.sha256 === sha256) return [];
+  const line = recordLine(relative, sha256, "env-template");
+  if (record?.kind === "env-template") return [`${relative}: env template changed since it was recorded (recorded sha256 ${record.sha256}, now ${sha256}); after reviewing the change, replace its record in ${SECRET_SCAN_RECORDS_FILE} with: ${line}`];
+  return [`${relative}: env template (sha256 ${sha256}) is not recorded in ${SECRET_SCAN_RECORDS_FILE}; after reviewing that it holds only names and placeholders, add this record: ${line}`];
+}
+
+function fileViolations(relative, bytes, records) {
+  const hits = contentHits(bytes.toString("utf8"), FILE_SHAPES);
+  if (!hits.length) return [];
+  const sha256 = recordDigest(bytes);
+  const record = records.get(relative);
+  if (record?.kind === "fixture" && record.sha256 === sha256) return [];
+  const line = recordLine(relative, sha256, "fixture");
+  const where = `${relative}:${firstLine(hits)}: content matches ${hitsText(hits)}`;
+  if (record?.kind === "fixture") return [`${where}; its fixture record is out of date (recorded sha256 ${record.sha256}, now ${sha256}). After reviewing the change, replace its record in ${SECRET_SCAN_RECORDS_FILE} with: ${line}`];
+  return [`${where}; sha256 ${sha256}. If this is a redaction or screening test vector and not a credential, review it and add this record to ${SECRET_SCAN_RECORDS_FILE}: ${line}`];
+}
+
+/**
+ * Files under `crateDir` that must not be committed or packaged. Strict by default: bare relative paths. With `envTemplates: true`
+ * (the repository gate) the reviewed records of `<repoRoot>/.rightkit/secret-scan-records.json` apply and each violation is a
+ * `<repo-relative path>[:<line>]: <reason>` line; `repoRoot` (default `crateDir`) is the root those paths and the records are relative to.
+ */
+export function scanCrateForSecrets(crateDir, { envTemplates = false, repoRoot = crateDir } = {}) {
+  if (envTemplates) return scanRepositoryForSecrets(crateDir, repoRoot);
   const violations = [];
   for (const file of walkFiles(crateDir)) {
     const relative = path.relative(crateDir, file).replaceAll("\\", "/");
@@ -147,13 +344,31 @@ export function scanCrateForSecrets(crateDir) {
       violations.push(relative);
       continue;
     }
-    const bytes = fs.readFileSync(file);
-    const text = bytes.toString("utf8");
+    const text = fs.readFileSync(file).toString("utf8");
     if (SECRET_PATTERNS.some((pattern) => pattern.test(text))) violations.push(relative);
   }
   return [...new Set(violations)].sort();
 }
 
+function scanRepositoryForSecrets(dir, repoRoot) {
+  const { records = new Map(), problems = [] } = readSecretScanRecords(repoRoot);
+  const violations = [...problems];
+  for (const file of walkFiles(dir)) {
+    const inDir = path.relative(dir, file).replaceAll("\\", "/");
+    const relative = path.relative(repoRoot, file).replaceAll("\\", "/");
+    if (neverRecordable(inDir)) {
+      violations.push(`${relative}: refused by name (an .env file, a key or certificate file, or build output); it is never committed and cannot be recorded`);
+      continue;
+    }
+    // A file that vanished between the walk and the read was a tool's temporary file (pnpm writes `_tmp_<pid>_*` next to a
+    // lockfile it reads), never committed content.
+    let bytes;
+    try { bytes = fs.readFileSync(file); } catch (e) { if (e.code === "ENOENT") continue; throw e; }
+    violations.push(...(ENV_TEMPLATE.test(inDir) ? envTemplateViolations(relative, file, bytes, records, repoRoot) : fileViolations(relative, bytes, records)));
+  }
+  return [...new Set(violations)].sort();
+}
+
 /**
  * Package, qualify and (unless `options.dryRun`) publish one crate. A real publish is refused (HOST_UPLOAD_REFUSED) before anything
  * runs unless `options.capability` is a publish capability (host-upload-refusal.mjs createPublishCapability) created from a

package/publish-update.mjs

@@ -3,11 +3,12 @@ import { readFile } from "node:fs/promises";
 import { readFileSync } from "node:fs";
 import { spawnSync } from "./background-process.mjs";
 import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
 import { pruneReleaseObjects } from "./prune-r2.mjs";
 import { loadReleaseToken } from "./release-token.mjs";
 import { registerRightAppsRelease } from "./rightapps-register.mjs";
 import { recordPublishedVersion } from "./artifact-storage.mjs";
+import { defaultReleaseConfigFile, importReleaseConfig } from "./release-config.mjs";
 import { assertPrimaryReleaseCheckout } from "./release-invocation.mjs";
 import { assertCleanSource } from "./source-gate.mjs";
 import { verifyPublicationRelease, PublicationError, assertArtifactUnchanged, digestBytes } from "./publication-artifacts.mjs";
@@ -15,7 +16,7 @@ import { uploadVerifiedR2Artifact } from "./r2-verified-upload.mjs";
 import { verifyPlatformTrust } from "./github-release.mjs";
 import { admitInstalledQa } from "./release-qa-audit.mjs";
 import { RIGHT_SUITE_API_ORIGIN, RIGHT_SUITE_GATED_ARTIFACT_HOST, RIGHT_SUITE_PUBLIC_INSTALLER_BASE } from "./suite-api.generated.mjs";
-import { assertAssetName, assertGitHubRepository, assertUpdaterKeyId, assertUpdaterPlatform, assertUpdaterSignature, buildLatestJson, githubAssetUrl, githubTag, publishGitHubUpdaterRelease } from "./github-updater-release.mjs";
+import { assertAssetName, assertGitHubRepository, assertUpdaterKeyId, assertUpdaterPlatform, assertUpdaterSignature, buildLatestJson, githubAssetUrl, githubTag, publishGitHubUpdaterRelease, resolveUpdaterTrust } from "./github-updater-release.mjs";
 
 const TOOL_ROOT = path.dirname(fileURLToPath(import.meta.url));
 const API_BASE = process.env.RIGHTAPPS_API_URL || RIGHT_SUITE_API_ORIGIN;
@@ -24,7 +25,7 @@ const PUBLIC_BASE = process.env.RIGHTAPPS_PUBLIC_DOWNLOAD_BASE || RIGHT_SUITE_PU
 const PIPELINE_VERSION = JSON.parse(await readFile(path.join(TOOL_ROOT, "package.json"), "utf8")).version;
 let tier = process.env.RIGHT_RELEASE_TIER || "";
 const args = process.argv.slice(2);
-let configName = "right-release.config.mjs";
+let configName = defaultReleaseConfigFile();
 let platform = process.platform === "win32" ? "win" : "mac";
 let dryRun = false;
 let releaseId = "";
@@ -45,7 +46,8 @@ if (tier !== "patch" && tier !== "update") fail("tier is required (--tier patch|
 if (!["win", "mac"].includes(platform)) throw new PublicationError("PUBLICATION_PLATFORM_INVALID", "--platform must be win or mac");
 const configPath = path.resolve(configName);
 const root = path.dirname(configPath);
-const config = (await import(pathToFileURL(configPath))).default;
+let config;
+try { config = await importReleaseConfig(configPath); } catch (error) { fail(`release config could not be loaded (${configPath}): ${error instanceof Error ? error.message : String(error)}`); }
 const provider = config?.distribution?.provider;
 if (provider !== "r2-rightapps" && provider !== "github-releases") {
   fail("release config distribution.provider must be r2-rightapps or github-releases");
@@ -117,18 +119,21 @@ function git(args) {
 if (!githubLane && tier === "patch" && !installers.length) fail(`${config?.app ?? "app"} ${platform} patch has no installer.artifacts`);
 if ((githubLane || tier === "update") && !artifacts.length) fail(`${config?.app ?? "app"} ${platform} update has no updater.artifacts`);
 
-// Cryptographic gate before any upload: every sealed minisign signature must verify over the
-// exact final artifact bytes against the declared public key. No declared key means the
-// signature cannot be verified, so a sealed (real) publish fails closed; key-id pinning is
-// supplementary only. Integrator owns declaring distribution.updaterPublicKey in app configs
-// (suite key already pinned per-app as tauri plugins.updater.pubkey).
+// Cryptographic gate before any upload: every sealed minisign signature must verify over the exact final artifact
+// bytes against the updater trust root. A Right Suite app takes that key, and its key id, from the Right Suite contract
+// (a declared key must be the contract's) and is always pinned to the id; any other app must declare
+// distribution.updaterPublicKey, and without one a sealed (real) publish fails closed.
 const updaterPublicKey = config.distribution?.updaterPublicKey ?? config.distribution?.updaterPubkey ?? target?.updater?.pubkey ?? target?.updater?.publicKey;
+const trust = sealed && artifacts.length && !appInstallerKind
+  ? resolveUpdaterTrust({ app: config.app, configuredPublicKey: updaterPublicKey, configuredKeyId: config.distribution.updaterKeyId })
+  : null;
 if (sealed) for (const artifact of artifacts) {
   const signature = signatureFor(artifact);
-  if (!appInstallerKind) {
-    if (!updaterPublicKey) throw new PublicationError("PUBLICATION_SIGNATURE_UNVERIFIABLE", `no updater public key declared (distribution.updaterPublicKey); refusing to upload ${path.basename(artifact.file)} with an unverified signature`);
-    assertUpdaterSignature(assertArtifactUnchanged(verifiedArtifact(artifact.file)), signature, updaterPublicKey, `signature of ${path.basename(artifact.file)}`);
-    assertUpdaterKeyId(signature, config.distribution.updaterKeyId, `signature of ${path.basename(artifact.file)}`);
+  if (trust) {
+    const label = `signature of ${path.basename(artifact.file)}`;
+    // The id comes first: a signature by another key would otherwise fail verification without saying whose it is.
+    assertUpdaterKeyId(signature, trust.keyId, label, { app: config.app });
+    assertUpdaterSignature(assertArtifactUnchanged(verifiedArtifact(artifact.file)), signature, trust.publicKey, label);
   }
 }
 let releaseToken = null;
@@ -154,7 +159,7 @@ if (githubLane) {
       const name = assertAssetName(path.basename(file));
       // Same signature source and process as the r2 lane: the sealed minisign .sig written by sign-updater.
       const signature = dryRun ? `<signature:${artifact.signature ?? "msix-authenticode"}>` : signatureFor(artifact);
-      if (!dryRun && !appInstallerKind) assertUpdaterKeyId(signature, config.distribution.updaterKeyId, `signature of ${name}`);
+      if (!dryRun && !appInstallerKind) assertUpdaterKeyId(signature, trust.keyId, `signature of ${name}`, { app: config.app });
       platforms[artifact.platform] = { signature, url: githubAssetUrl(githubRepo, tag, name) };
       assets.set(file, { file, evidence: dryRun ? undefined : verifiedArtifact(file) });
       if (!appInstallerKind) {

package/release-config.mjs

@@ -1,6 +1,11 @@
 // The release config contract (M24): `right-release.config.json`, a finite, versioned JSON schema read by dev, build, doctor, install
-// and upload alike. It is data. RightKit never imports, evaluates or converts an executable (`.mjs`, `.js`, `.cjs`, `.ts`) config: the
-// file name is judged BEFORE anything is opened or imported, including for `--dry-run`, so a legacy config cannot run a single line.
+// and upload alike. A `.json` config is data: it is never imported or evaluated. `loadReleaseConfigSync` judges the file NAME before
+// anything is opened (an executable name handed to it is refused with RELEASE_CONFIG_LEGACY_EXECUTABLE) and loads the file strictly.
+//
+// Legacy branch: an app that has not moved yet owns only a `right-release.config.mjs`. `defaultReleaseConfigFile` keeps naming it while
+// no `right-release.config.json` sits beside it, and `importReleaseConfig` still imports that module (executable, outside M24; the
+// pipeline scanner reports it as R0-legacy-config). The sunset of the legacy branch is tracked separately. As soon as the JSON file
+// exists it wins by default and an explicit `--config x.json` always takes the strict loader; the module is never read for it.
 //
 // Load order (build, dev, upload): resolve the primary checkout and the config path first, then `loadReleaseConfigSync` parses the JSON
 // strictly (no comments, no trailing commas, no duplicate keys), checks `schema: 1` and the finite top-level key set, expands the
@@ -12,15 +17,19 @@
 //   { "$fromJson": { "file": "src-tauri/tauri.conf.json", "pointer": "/version" } }   a string read from an app-relative JSON file
 //   { "$fromToml": { "file": "src-tauri/Cargo.toml", "path": "package.version" } }    a string read from an app-relative TOML file
 //   { "$json": <value> }                                                              JSON.stringify(<value>), for a JSON argument
-//   "{{app}}" "{{version}}" "{{home}}" "{{localAppData}}"                              replaced inside any string value
+//   "{{app}}" "{{version}}" "{{home}}" "{{localAppData}}"                              replaced inside any string value, `$comment`
+//                                                                                     included (write no token in a comment). localAppData is
+//                                                                                     %LOCALAPPDATA% on Windows and <home>/AppData/Local elsewhere
 // Anything else with braces is left alone, and an unknown {{token}} is an error.
 import { createHash } from "node:crypto";
 import { existsSync, lstatSync, readFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 import { parse as parseToml } from "smol-toml";
 import { collectConfigCommands, formatFindings, validateConfigPipeline } from "./pipeline-config.mjs";
 import { loadGeneratorRegistry } from "./pipeline-generators.mjs";
+import { RIGHT_SUITE_APP_KEYS, RIGHT_SUITE_UPDATER_PUBLIC_KEYS } from "./suite-api.generated.mjs";
 
 export const RELEASE_CONFIG_FILE = "right-release.config.json";
 export const LEGACY_RELEASE_CONFIG_FILE = "right-release.config.mjs";
@@ -198,7 +207,7 @@ function expand(node, context, label) {
     return node.replace(/\{\{([A-Za-z][A-Za-z0-9]*)\}\}/g, (_, token) => {
       if (!TEMPLATE_TOKENS.includes(token)) fail("RELEASE_CONFIG_TEMPLATE", `${label}: unknown template token {{${token}}} (allowed: ${TEMPLATE_TOKENS.map((t) => `{{${t}}}`).join(", ")})`);
       const resolved = context.values[token];
-      if (typeof resolved !== "string" || resolved === "") fail("RELEASE_CONFIG_TEMPLATE", `${label}: {{${token}}} is not available${token === "localAppData" ? " (LOCALAPPDATA is not set)" : token === "version" ? " here (version cannot refer to itself)" : ""}`);
+      if (typeof resolved !== "string" || resolved === "") fail("RELEASE_CONFIG_TEMPLATE", `${label}: {{${token}}} is not available${token === "version" ? " here (version cannot refer to itself)" : ""}`);
       return resolved;
     });
   }
@@ -259,16 +268,31 @@ export function validateReleaseConfigShape(config, { file = RELEASE_CONFIG_FILE,
   return config;
 }
 
+// The same rule as UPDATER_KEY_ID_RE in github-updater-release.mjs, kept here because that module's import graph loads the release state
+// machine, which this loader must not depend on.
+const UPDATER_KEY_ID = /^[0-9A-F]{16}$/;
+// A typed template ({ "$fromJson": ... }) is a string only after expansion, so the raw-phase check leaves it to the final one.
+const isTemplateNode = (value) => isObject(value) && Object.keys(value).some((key) => key.startsWith("$"));
+const isBlank = (value) => value === undefined || value === null || (typeof value === "string" && !value.trim());
+
 /**
  * Field-level refusals that need no other part of the config, so a caller (the loader, the doctor) can list them next to every other
- * finding: `[{ name, code, pointer, detail }]`. Today: `targets.<t>.updater.keyFile`. Updater minisign keys come from the OS credential
- * provider (`protected-credentials.mjs`, secret "updater-signing-key", namespace `rightsuite-updater-key`; `sign-updater.mjs` refuses
- * `--key-file`), so a config that names a key file could only fail mid-signing. It is refused up front instead, and never forwarded.
+ * finding: `[{ name, code, pointer, detail }]`.
+ *
+ * `targets.<t>.updater.keyFile`: updater minisign keys come from the OS credential provider (`protected-credentials.mjs`, secret
+ * "updater-signing-key", namespace `rightsuite-updater-key`; `sign-updater.mjs` refuses `--key-file`), so a config that names a key
+ * file could only fail mid-signing. It is refused up front instead, and never forwarded.
+ *
+ * `distribution.updaterKeyId` must be 16 upper-case hex digits and, for a Right Suite app, a key the Right Suite contract accepts; a
+ * Right Suite app must not declare an updater public key of its own (`distribution.updaterPublicKey`, `updaterPubkey`,
+ * `targets.<t>.updater.pubkey` or `publicKey`) unless it is exactly a contract key's text. Publish and seal refuse the same things
+ * (`resolveUpdaterTrust`); here they are found before a build starts.
  */
 export function releaseConfigFieldProblems(config) {
   const problems = [];
-  if (!isObject(config) || !isObject(config.targets)) return problems;
-  for (const [name, target] of Object.entries(config.targets)) {
+  if (!isObject(config)) return problems;
+  const targets = isObject(config.targets) ? Object.entries(config.targets) : [];
+  for (const [name, target] of targets) {
     if (!isObject(target) || !isObject(target.updater) || !Object.prototype.hasOwnProperty.call(target.updater, "keyFile")) continue;
     problems.push({
       name: "updater-key-file",
@@ -277,6 +301,35 @@ export function releaseConfigFieldProblems(config) {
       detail: `targets.${name}.updater.keyFile is not supported: updater signing keys come from the OS credential provider (rightkit-credentials, namespace rightsuite-updater-key; see protected-credentials.mjs and sign-updater.mjs), never from a key file. Remove updater.keyFile from the release config.`,
     });
   }
+  const suiteApp = typeof config.app === "string" && RIGHT_SUITE_APP_KEYS.includes(config.app.toLowerCase());
+  const distribution = isObject(config.distribution) ? config.distribution : {};
+  const keyId = distribution.updaterKeyId;
+  if (keyId !== undefined && !isTemplateNode(keyId)) {
+    const accepted = RIGHT_SUITE_UPDATER_PUBLIC_KEYS.map((key) => key.kid);
+    const detail = typeof keyId !== "string" || !UPDATER_KEY_ID.test(keyId)
+      ? `distribution.updaterKeyId must be the 16 upper-case hex digits of a minisign key id, got ${JSON.stringify(keyId)}.`
+      : suiteApp && !accepted.includes(keyId)
+        ? `distribution.updaterKeyId ${keyId} is not an updater key in the Right Suite contract (accepted: ${accepted.join(", ")}). Remove it to sign with the contract's signing key.`
+        : null;
+    if (detail) problems.push({ name: "updater-key-id", code: "RELEASE_CONFIG_UPDATER_KEY_ID", pointer: "/distribution/updaterKeyId", detail });
+  }
+  if (suiteApp) {
+    const contractTexts = RIGHT_SUITE_UPDATER_PUBLIC_KEYS.map((key) => key.publicKey);
+    const declared = (pointer, label, value) => {
+      if (isBlank(value) || isTemplateNode(value) || contractTexts.includes(value)) return;
+      problems.push({
+        name: "updater-public-key",
+        code: "RELEASE_CONFIG_UPDATER_PUBLIC_KEY",
+        pointer,
+        detail: `${label} is not a Right Suite contract key: ${config.app} is a suite app and takes its updater keys from the contract (contracts/right-suite-api.v1.json), so remove ${label}.`,
+      });
+    };
+    for (const field of ["updaterPublicKey", "updaterPubkey"]) declared(`/distribution/${field}`, `distribution.${field}`, distribution[field]);
+    for (const [name, target] of targets) {
+      if (!isObject(target) || !isObject(target.updater)) continue;
+      for (const field of ["pubkey", "publicKey"]) declared(`/targets/${pointerKey(name)}/updater/${field}`, `targets.${name}.updater.${field}`, target.updater[field]);
+    }
+  }
   return problems;
 }
 
@@ -289,7 +342,7 @@ function packageScripts(appRoot, readText) {
 
 /**
  * Load, validate and expand a release config. Returns `{ config, configPath, appRoot, sha256, inputs, lineOf }`. Throws ReleaseConfigError
- * (RELEASE_CONFIG_LEGACY_EXECUTABLE | _NOT_JSON | _NOT_FOUND | _INVALID_JSON | _SCHEMA | _KEY | _UPDATER_KEY_FILE | _TEMPLATE | _M24). `validatePipeline: false`
+ * (RELEASE_CONFIG_LEGACY_EXECUTABLE | _NOT_JSON | _NOT_FOUND | _INVALID_JSON | _SCHEMA | _KEY | _UPDATER_KEY_FILE | _UPDATER_KEY_ID | _UPDATER_PUBLIC_KEY | _TEMPLATE | _M24). `validatePipeline: false`
  * skips only the M24 command admission (the pipeline scanner reports those findings itself); nothing else is optional.
  * File access, the generator registry, the environment and the home directory are injectable for tests.
  */
@@ -313,7 +366,9 @@ export function loadReleaseConfigSync(file, {
   const raw = parsed.value;
   validateReleaseConfigShape(raw, { file: configPath, phase: "raw" });
   const inputs = new Map();
-  const base = { appRoot, inputs, readBytes, lstat, values: { home: homedir(), localAppData: env.LOCALAPPDATA ?? "", app: "", version: "" } };
+  // {{localAppData}} is %LOCALAPPDATA% on Windows. Elsewhere it is the Windows profile default under the home directory (a path
+  // no other host uses), so one config that names a Windows install path loads on every host instead of failing on the Mac.
+  const base = { appRoot, inputs, readBytes, lstat, values: { home: homedir(), localAppData: env.LOCALAPPDATA || path.join(homedir(), "AppData", "Local"), app: "", version: "" } };
   base.values.app = expand(raw.app, { ...base }, "/app");
   if (raw.version !== undefined) base.values.version = expand(raw.version, { ...base, values: { ...base.values, version: "" } }, "/version");
   const config = expand(raw, base, "");
@@ -344,6 +399,27 @@ export async function loadReleaseConfig(file, options) {
   return loadReleaseConfigSync(file, options).config;
 }
 
+/** True for a `.json` config path: the only extension the strict loader accepts. */
+export const isJsonReleaseConfig = (file) => typeof file === "string" && path.extname(file).toLowerCase() === ".json";
+
+/** The config name a command defaults to: `right-release.config.json` when `dir` holds it, else the legacy module an unmoved app still owns. */
+export function defaultReleaseConfigFile(dir = process.cwd(), { exists = existsSync } = {}) {
+  return exists(path.join(dir, RELEASE_CONFIG_FILE)) ? RELEASE_CONFIG_FILE : LEGACY_RELEASE_CONFIG_FILE;
+}
+
+/**
+ * Load the config at `file` for a command. A `.json` path goes through the strict, M24-validated loader (throws ReleaseConfigError); any
+ * other path is the legacy branch and is imported as before. Legacy-only options: `query` is the cache-busting query a site appends
+ * (`upload=<ts>`, `commit=<sha>`) so a module re-evaluates per run, and `lenient` keeps the `default ?? config ?? module` fallback the
+ * app-root commands accept; every other option goes to `loadReleaseConfigSync`.
+ */
+export async function importReleaseConfig(file, { query, lenient = false, ...loadOptions } = {}) {
+  const absolute = path.resolve(file);
+  if (isJsonReleaseConfig(absolute)) return loadReleaseConfigSync(absolute, loadOptions).config;
+  const loaded = await import(`${pathToFileURL(absolute).href}${query ? `?${query}` : ""}`);
+  return lenient ? loaded.default ?? loaded.config ?? loaded : loaded.default;
+}
+
 /** `{ config, appRoot, configPath }` for the commands that need the app root beside the config. */
 export async function loadAppConfigFile(file = RELEASE_CONFIG_FILE, options) {
   const loaded = loadReleaseConfigSync(file, options);

package/release-dependencies-command.mjs

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
+import { defaultReleaseConfigFile, importReleaseConfig } from "./release-config.mjs";
 import { assertReleaseDependencies } from "./release-dependencies.mjs";
 import { nodeHostTriple } from "./stage-sidecar-command.mjs";
 import { expandPackageRecipeTarget } from "./package-recipe-targets.mjs";
 
 /** Standalone policy check: host target by default, all declared release targets on request. */
 export async function main(argv, { cwd = process.cwd(), platform = process.platform, arch = process.arch, run } = {}) {
-  let configPath = "right-release.config.mjs", selected, allTargets = false;
+  let configPath = defaultReleaseConfigFile(cwd), selected, allTargets = false;
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (["--config", "--platform"].includes(arg)) {
@@ -20,7 +21,7 @@ export async function main(argv, { cwd = process.cwd(), platform = process.platf
   if (allTargets && selected) throw new Error("use --platform or --all-targets");
   const file = path.resolve(cwd, configPath);
   const root = path.dirname(file);
-  const config = (await import(pathToFileURL(file).href)).default;
+  const config = await importReleaseConfig(file);
   if (config?.releaseDependencies === undefined) throw new Error("check-release-dependencies requires releaseDependencies in config");
   const host = { darwin: "mac", win32: "win", linux: "linux" }[platform];
   const platforms = allTargets ? Object.keys(config.targets ?? {}) : [selected ?? host];

package/release-qa-audit.mjs

@@ -1,12 +1,14 @@
 // QA admission plus the ad hoc `right-release qa audit` scan.
 //
 // Per-app policy (qa-admission-policy.json, release-qa-policy.mjs): `warn` is the default, `refuse` is switched on
-// per app once the app has earned it. The gates in release-qa-receipt.mjs verify receipts, and the hardening in
-// release-qa-hardening.mjs re-checks platform, release id, approved runner digest, every release-critical journey
-// and the signing/test separation. In warn mode a refusal becomes a loud stderr warning and a durable record
-// (the sealed manifest `qa` field for the source stage, `state/<releaseId>/<platformDir>/qa-installed.json`
-// for the installed stage). In refuse mode the same refusal throws a QaAdmissionError and nothing is sealed or
-// published. `qa audit` reads the records so a weekly run can flag released builds that lack passing QA.
+// per app once the app has earned it, and separately per stage: the build (source) admission and the publication
+// (installed) admission each read their own mode. The gates in release-qa-receipt.mjs verify receipts, and the
+// hardening in release-qa-hardening.mjs re-checks platform, release id, approved runner digest (for that platform),
+// every release-critical journey and the signing/test separation. In warn mode a refusal becomes a loud stderr
+// warning and a durable record (the sealed manifest `qa` field for the source stage,
+// `state/<releaseId>/<platformDir>/qa-installed.json` for the installed stage). In refuse mode the same refusal
+// throws a QaAdmissionError and nothing is sealed or published. `qa audit` reads the records so a weekly run can
+// flag released builds that lack passing QA.
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { spawnSync } from "./background-process.mjs";
@@ -42,10 +44,10 @@ function admit(check, { warn = (line) => console.error(line), mode = { mode: "wa
   }
 }
 
-function policyContext(opts, hooks = {}) {
+function policyContext(opts, hooks = {}, stage) {
   const loaded = hooks.policy ?? loadAdmissionPolicy({ dir: hooks.policyDir, env: opts.env });
   const app = opts.app ?? opts.manifest?.app ?? appOfReleaseId(opts.releaseId ?? opts.manifest?.releaseId);
-  return { loaded, app, mode: admissionModeFor(loaded.policy, app) };
+  return { loaded, app, mode: admissionModeFor(loaded.policy, app, stage) };
 }
 
 function hardening(stage, opts, loaded, hooks) {
@@ -58,7 +60,7 @@ function hardening(stage, opts, loaded, hooks) {
 
 /** Build stage. Returns the `qa` block sealed into the release manifest. */
 export function admitSourceQa(opts, hooks = {}) {
-  const { loaded, app, mode } = policyContext(opts, hooks);
+  const { loaded, app, mode } = policyContext(opts, hooks, "source");
   const outcome = admit(() => assertSourceQaAdmission({ ...opts, afterVerify: hardening("source", opts, loaded, hooks) }), { ...hooks, mode, app });
   if (outcome.status === "passed") return { status: "passed", sourceReceiptDigest: outcome.result.digest, floorDigest: outcome.result.floorDigest };
   return { status: outcome.status, reason: outcome.reason };
@@ -69,7 +71,7 @@ export const installedQaRecordPath = ({ repoRoot, releaseId, platform }) =>
 
 /** Publication stage (upload, publish-update, github). Records the outcome durably; throws in `refuse` mode. */
 export function admitInstalledQa(opts, { provider, now = () => new Date(), ...hooks } = {}) {
-  const { loaded, app, mode } = policyContext(opts, hooks);
+  const { loaded, app, mode } = policyContext(opts, hooks, "installed");
   const outcome = admit(() => assertInstalledQaAdmission({ ...opts, afterVerify: hardening("installed", opts, loaded, { ...hooks, now }) }), { ...hooks, mode, app });
   const record = {
     status: outcome.status,