@rightkit/release 0.6.5 → 0.6.6

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,6 +13,7 @@ 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 = [
@@ -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,28 @@ 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;
+    }
+    const bytes = fs.readFileSync(file);
+    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";
@@ -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");

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,12 +17,15 @@
 //   { "$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";
@@ -198,7 +206,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;
     });
   }
@@ -313,7 +321,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 +354,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,

package/release-qa-command.mjs

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
 // right-release qa: run RightKit's own QA runner (rightkit-qa) and write the sealed, MAC'd QA receipt.
 //
-//   right-release qa --stage source    --platform mac|win [--config right-release.config.mjs]
-//   right-release qa --stage installed --platform mac|win --release <sealed-id> [--config right-release.config.mjs]
+//   right-release qa --stage source    --platform mac|win [--config right-release.config.json]
+//   right-release qa --stage installed --platform mac|win --release <sealed-id> [--config right-release.config.json]
 //   right-release qa audit [--app <dir>] [--json] [--since <YYYY-MM-DD>]   (release-qa-audit.mjs; exit 1 when an uploaded build lacks passing QA)
+//   right-release qa policy show | set --app <app> --mode warn|refuse --set-by <name> [--stage source|installed]
+//                         | approve-runner --runner <file> --version <v> --platform mac|win --set-by <name> [--note <text>]   (release-qa-policy.mjs)
 //
 // The release config declares the app's QA plan:
 //   qa: { version: "1", config: "rightkit-qa.toml", runner?: "<path to rightkit-qa>",
@@ -20,14 +22,16 @@ import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { pathToFileURL, fileURLToPath } from "node:url";
+import { fileURLToPath } from "node:url";
 import { spawnSync } from "./background-process.mjs";
+import { defaultReleaseConfigFile, importReleaseConfig } from "./release-config.mjs";
 import { assertPrimaryReleaseCheckout } from "./release-invocation.mjs";
 import { assertCleanSource } from "./source-gate.mjs";
 import { verifySealedRelease } from "./release-state.mjs";
 import { auditMain } from "./release-qa-audit.mjs";
 import { journeyRequiredItem, QA_RUN_ENV, relativePosix, validateJourneysReceipt } from "./release-qa-hardening.mjs";
 import { prepareInstalledArtifacts } from "./release-qa-installed.mjs";
+import { main as policyMain } from "./release-qa-policy.mjs";
 import { darwinKeyFile, PROTECTED_SECRETS } from "./protected-credentials.mjs";
 import {
   buildQaReceipt, currentPolicyBundleDigest, dependencyClosure, ensureQaReceiptKey, evaluateRequiredChecks, loadQaFloor,
@@ -55,6 +59,32 @@ function resolveRunner({ qa, appRoot, platform = process.platform, runner = spaw
   return realpathSync(file);
 }
 
+// Windows installs land in `%LOCALAPPDATA%\<Product>`; the runner learns the product folder names from
+// RIGHTKIT_QA_INSTALLED_DIRS. Compared as strings with both separators so the answer never depends on the host OS.
+const WIN_ABSOLUTE = /^(?:[A-Za-z]:[\\/]|\\\\)/;
+const pathParts = (value) => String(value).split(/[\\/]+/).filter(Boolean);
+const productDirOk = (name) => name.length <= 255 && ![".", ".."].includes(name) && !/[\u0000-\u001f\u007f;:]/.test(name);
+
+/**
+ * Product folder names under %LOCALAPPDATA% that hold the app's installed copy, from the release config's
+ * `development.targets.win.install.expectedInstalledPath` (the one place a config names the installed path; the
+ * desktop-app-template sets it to `<LOCALAPPDATA>\<Product>\<exe>`). Only an absolute path inside LOCALAPPDATA
+ * counts (case-insensitive, either separator); the name is the first component below it and a file must sit under it.
+ * `Programs` is already a runner root, so it is dropped. Returns an array of distinct names (today at most one: the
+ * config declares one installed path).
+ */
+export function installedDirNames(config, env = process.env) {
+  const localAppData = Object.entries(env ?? {}).find(([key]) => key.toLowerCase() === "localappdata")?.[1];
+  const installed = config?.development?.targets?.win?.install?.expectedInstalledPath;
+  if (typeof localAppData !== "string" || !WIN_ABSOLUTE.test(localAppData) || typeof installed !== "string" || !WIN_ABSOLUTE.test(installed)) return [];
+  const root = pathParts(localAppData).map((part) => part.toLowerCase());
+  const parts = pathParts(installed);
+  if (parts.some((part) => part === "." || part === "..")) return [];
+  if (parts.length < root.length + 2 || !root.every((part, index) => parts[index].toLowerCase() === part)) return [];
+  const name = parts[root.length];
+  return name.toLowerCase() === "programs" || !productDirOk(name) ? [] : [name];
+}
+
 /** `rightkit-qa journeys run` prints `run <id> (<run dir>)` first; the receipt is `<run dir>/receipt.json`. */
 export function journeysReceiptFromOutput(stdout) {
   const dir = String(stdout ?? "").match(/^run \S+ \((.+)\)\s*$/m)?.[1];
@@ -77,7 +107,7 @@ export async function runQa({ stage, platform, releaseIdArg, configPath, carryTo
   if (!deps.skipPrimaryCheckout) assertPrimaryReleaseCheckout(repoRoot);
   assertCleanSource({ status: String(gitRunner("git", ["-C", repoRoot, "status", "--porcelain=v1", "-z", "--untracked-files=all"], { encoding: "utf8", windowsHide: true }).stdout ?? ""), commandId: "right-release qa" });
   const source = sourceIdentity(repoRoot, gitRunner);
-  const config = (await import(`${pathToFileURL(configPath).href}?qa=${source.commit}`)).default;
+  const config = await importReleaseConfig(configPath, { query: `qa=${source.commit}` });
   if (!config?.app || !config?.version) throw new Error("release config must expose app and version");
   const { floor, digest: floorDigest } = loadQaFloor(deps.floorDir);
   const problems = validateAppQaConfig(config.qa, floor, stage);
@@ -117,7 +147,11 @@ export async function runQa({ stage, platform, releaseIdArg, configPath, carryTo
   try {
     const expand = (value) => String(value).replaceAll("{sealedDir}", sealed?.sealedDir ?? "").replaceAll("{releaseId}", releaseId)
       .replaceAll("{installedApp}", installedQa?.installedApp ?? "").replaceAll("{installedDir}", installedQa?.installedDir ?? "").replaceAll("{qaRoot}", installedQa?.qaRoot ?? "");
-    const runEnv = { ...process.env, RIGHT_RELEASE_QA_STAGE: stage, RIGHT_RELEASE_QA_COMMIT: source.commit, RIGHT_RELEASE_QA_RELEASE_ID: releaseId, ...(sealed ? { RIGHT_RELEASE_QA_SEALED_DIR: sealed.sealedDir } : {}), ...(installedQa?.env ?? {}) };
+    const installedDirs = installedDirNames(config, deps.env ?? process.env);
+    const runEnv = {
+      ...process.env, RIGHT_RELEASE_QA_STAGE: stage, RIGHT_RELEASE_QA_COMMIT: source.commit, RIGHT_RELEASE_QA_RELEASE_ID: releaseId,
+      ...(sealed ? { RIGHT_RELEASE_QA_SEALED_DIR: sealed.sealedDir } : {}), ...(installedDirs.length ? { RIGHTKIT_QA_INSTALLED_DIRS: installedDirs.join(";") } : {}), ...(installedQa?.env ?? {}),
+    };
     const args = ["run", "--config", qaConfig, ...((config.qa.args?.[stage] ?? []).map(expand))];
     run = (deps.spawnRunner ?? spawnSync)(runnerFile, args, {
       cwd: appRoot, encoding: "utf8", windowsHide: true, maxBuffer: 64 * 1024 * 1024,
@@ -181,13 +215,14 @@ export async function runQa({ stage, platform, releaseIdArg, configPath, carryTo
 }
 
 function usage(code) {
-  console.log("usage: right-release qa --stage source|installed --platform mac|win [--release <sealed-id>] [--config right-release.config.mjs] [--carry-to <dir>]\n       (seals the QA receipt; admission is warn or refuse per app in qa-admission-policy.json; refused inside a QA run)\n       right-release qa audit [--app <dir>] [--json] [--since <YYYY-MM-DD>]");
+  console.log("usage: right-release qa --stage source|installed --platform mac|win [--release <sealed-id>] [--config right-release.config.json] [--carry-to <dir>]\n       (seals the QA receipt; admission is warn or refuse per app in qa-admission-policy.json; refused inside a QA run)\n       right-release qa audit [--app <dir>] [--json] [--since <YYYY-MM-DD>]\n       right-release qa policy show | set --app <app> --mode warn|refuse --set-by <name> [--stage source|installed]\n                             | approve-runner --runner <file> --version <v> --platform mac|win --set-by <name> [--note <text>]");
   process.exit(code);
 }
 
 export async function main(args) {
   if (args[0] === "audit") process.exit(auditMain(args.slice(1)));
-  let stage = "", platform = process.platform === "win32" ? "win" : "mac", releaseId = "", configName = "right-release.config.mjs", carryTo = null;
+  if (args[0] === "policy") process.exit(policyMain(args.slice(1), { program: "right-release qa policy" }));
+  let stage = "", platform = process.platform === "win32" ? "win" : "mac", releaseId = "", configName = defaultReleaseConfigFile(), carryTo = null;
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
     if (arg === "--stage") stage = args[++index];

package/release-qa-hardening.mjs

@@ -7,7 +7,8 @@
 //              passed", not "one matching check passed".
 //   admit side `hardenQaReceipt` re-checks the sealed receipt at admission, independently of what the run side
 //              claimed: platform and release id, the approved runner digest, the critical journey set recomputed
-//              from the manifest committed at the receipt's commit, and the signing/test-execution separation.
+//              from the manifest committed at the receipt's commit, and the signing/test-execution separation. The
+//              runner digest must be approved for the platform being sealed or published (qa-admission-policy.json).
 //
 // Signing outside test execution, what is checked here: the receipt records the pids of the test processes it
 // spawned and the window in which they ran; admission refuses a receipt whose window does not end before the
@@ -119,10 +120,16 @@ export function hardenQaReceipt({
   if (receipt.platform !== platform) refuse(`receipt is for platform ${receipt.platform}, this is ${platform}`);
   if (receipt.releaseId !== releaseId) refuse(`receipt is for release ${receipt.releaseId}, this is ${releaseId}`);
 
-  // 2. The qualifying runner is pinned by an approved digest.
+  // 2. The qualifying runner is pinned by an approved digest, approved for this platform (an entry with no platform
+  //    approves every platform).
   const approved = approvedRunnerDigests(policy);
   if (!approved.length) refuse("no rightkit-qa runner digest is approved in qa-admission-policy.json");
-  if (!approved.includes(receipt.runner?.sha256)) refuse(`rightkit-qa runner sha256 ${String(receipt.runner?.sha256).slice(0, 16)} is not an approved runner`);
+  const digest = receipt.runner?.sha256;
+  if (!approved.includes(digest)) refuse(`rightkit-qa runner sha256 ${String(digest).slice(0, 16)} is not an approved runner`);
+  const entries = policy.approvedRunners.filter((runner) => runner.sha256 === digest);
+  if (!entries.some((runner) => !runner.platform || runner.platform === platform)) {
+    refuse(`rightkit-qa runner sha256 ${digest.slice(0, 16)} is approved only for ${[...new Set(entries.map((runner) => runner.platform))].sort().join(", ")}, this is ${platform}`);
+  }
 
   // 3. The journey floor id means every release-critical journey required on this platform passed.
   const mapping = floor?.journeys;