@rightkit/release 0.2.142 → 0.2.144

package/publish-update.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 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";
@@ -9,9 +10,10 @@ import { registerRightAppsRelease } from "./rightapps-register.mjs";
 import { recordPublishedVersion } from "./artifact-storage.mjs";
 import { assertPrimaryReleaseCheckout } from "./release-invocation.mjs";
 import { assertCleanSource } from "./source-gate.mjs";
-import { verifyPublicationRelease, PublicationError, assertArtifactUnchanged } from "./publication-artifacts.mjs";
+import { verifyPublicationRelease, PublicationError, assertArtifactUnchanged, digestBytes } from "./publication-artifacts.mjs";
 import { uploadVerifiedR2Artifact } from "./r2-verified-upload.mjs";
 import { verifyPlatformTrust } from "./github-release.mjs";
+import { assertInstalledQaAdmission } from "./release-qa-receipt.mjs";
 
 const TOOL_ROOT = path.dirname(fileURLToPath(import.meta.url));
 const API_BASE = process.env.RIGHTAPPS_API_URL || "https://api.spoares.com";
@@ -67,6 +69,11 @@ if (!dryRun || releaseId) {
   if (!installer) throw new PublicationError("PUBLICATION_SIGNATURE_MISSING", "sealed installer required for platform trust verification");
   verifyPlatformTrust({ sealed, installer: path.join(sealed.sealedDir, installer.name) });
   for (const artifact of sealed.artifacts.values()) assertArtifactUnchanged(artifact);
+  // Hardening step 4: installed QA on these exact artifact hashes and commit must have passed (R2 patch + update tiers).
+  if (!dryRun) {
+    try { assertInstalledQaAdmission({ repoRoot, manifest: sealed.manifest, platform, configName: path.relative(process.cwd(), configPath) || configName, releaseConfigSha256: digestBytes(readFileSync(configPath)) }); }
+    catch (error) { if (error?.code !== "QA_ADMISSION_REFUSED") throw error; fail(error.message); }
+  }
 }
 const artifactFile = (declared) => {
   if (!sealed) return path.resolve(root, declared);

package/release-qa-command.mjs

@@ -0,0 +1,145 @@
+#!/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]
+//
+// The release config declares the app's QA plan:
+//   qa: { version: "1", config: "rightkit-qa.toml", runner?: "<path to rightkit-qa>",
+//         args?: { source?: [..], installed?: [..] },                                   // {sealedDir} {releaseId} expand
+//         checks: { "smoke.launch": ["app.launch"], journey: ["journey.*"] } }          // floor id -> evidence check names
+// Every id in release-qa-floor.json must be mapped; skipped/failed/missing required checks fail the receipt.
+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 { spawnSync } from "./background-process.mjs";
+import { assertPrimaryReleaseCheckout } from "./release-invocation.mjs";
+import { assertCleanSource } from "./source-gate.mjs";
+import { verifySealedRelease } from "./release-state.mjs";
+import { darwinKeyFile, PROTECTED_SECRETS } from "./protected-credentials.mjs";
+import {
+  buildQaReceipt, currentPolicyBundleDigest, dependencyClosure, ensureQaReceiptKey, evaluateRequiredChecks, loadQaFloor,
+  qaReceiptPath, QA_STAGES, sealQaReceipt, sourceIdentity, validateAppQaConfig, writeQaReceipt,
+} from "./release-qa-receipt.mjs";
+
+const sha256File = (file) => createHash("sha256").update(readFileSync(file)).digest("hex");
+
+// First `right-release qa` on a host creates the MAC key as an owner-only file in the per-user RightKit directory.
+function provisionKeyOnHost(value, platform = process.platform) {
+  const spec = PROTECTED_SECRETS["qa-receipt-key"];
+  let file;
+  if (platform === "darwin") file = darwinKeyFile(process.env, spec);
+  else if (platform === "win32") file = path.join(process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming"), "RightKit", spec.file);
+  else throw new Error("no protected credential store on this platform; set RIGHTKIT_QA_RECEIPT_KEY in hosted CI");
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeFileSync(file, value, { mode: 0o600, flag: "wx" });
+}
+
+function resolveRunner({ qa, appRoot, platform = process.platform, runner = spawnSync }) {
+  if (qa.runner) { const file = path.resolve(appRoot, qa.runner); if (!existsSync(file)) throw new Error(`qa.runner does not exist: ${file}`); return realpathSync(file); }
+  const found = runner(platform === "win32" ? "where" : "which", ["rightkit-qa"], { encoding: "utf8", windowsHide: true });
+  const file = String(found.stdout ?? "").split(/\r?\n/)[0].trim();
+  if (found.status !== 0 || !file) throw new Error("rightkit-qa runner not found on PATH; install it (RightKit crates/rightkit-qa) or set qa.runner in the release config");
+  return realpathSync(file);
+}
+
+export function evidencePathFromOutput(stdout) {
+  const line = String(stdout).split(/\r?\n/).reverse().find((item) => item.startsWith("[qa]") && /evidence\s+\S/.test(item));
+  return line?.match(/evidence\s+(.+?)\s*$/)?.[1] ?? null;
+}
+
+/** Run the QA plan through the runner, then seal a receipt. `deps` are test seams; production uses the defaults. */
+export async function runQa({ stage, platform, releaseIdArg, configPath, deps = {} }) {
+  const gitRunner = deps.gitRunner ?? spawnSync;
+  const appRoot = path.dirname(configPath);
+  const repoRoot = String(gitRunner("git", ["-C", appRoot, "rev-parse", "--show-toplevel"], { encoding: "utf8", windowsHide: true }).stdout ?? "").trim();
+  if (!repoRoot) throw new Error("release config must live inside a Git repository");
+  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;
+  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);
+  if (problems.length) throw new Error(`release config QA plan does not meet the protected QA floor:\n- ${problems.join("\n- ")}`);
+
+  let releaseId = releaseIdArg;
+  let sealed = null;
+  let artifacts = [];
+  let sourceReceiptDigest = null;
+  if (stage === "source") releaseId = `${config.app}-${config.version}-${source.commit.slice(0, 8)}`;
+  else {
+    if (!releaseId) throw new Error("--release <sealed-id> is required for the installed stage");
+    sealed = verifySealedRelease(path.join(repoRoot, ".right-release", "sealed", releaseId, platform === "win" ? "windows" : "mac"));
+    if (sealed.manifest.commit !== source.commit) throw new Error("sealed release was built from a different commit than the current checkout");
+    sourceReceiptDigest = sealed.manifest.qa?.sourceReceiptDigest ?? null;
+    if (!sourceReceiptDigest) throw new Error("sealed release records no source QA receipt; it was not built through the QA gate; rebuild after `right-release qa --stage source`");
+    artifacts = sealed.manifest.files.map((file) => ({ name: file.name, sha256: file.sha256, sizeBytes: file.sizeBytes }));
+  }
+
+  const key = ensureQaReceiptKey({ env: deps.env ?? process.env, credentialStore: deps.credentialStore, provision: deps.provision ?? provisionKeyOnHost });
+  const runnerFile = deps.runnerFile ?? resolveRunner({ qa: config.qa, appRoot });
+  const runnerSha = sha256File(runnerFile);
+  const qaConfig = path.resolve(appRoot, config.qa.config);
+  if (!existsSync(qaConfig)) throw new Error(`qa.config does not exist: ${qaConfig}`);
+  const expand = (value) => String(value).replaceAll("{sealedDir}", sealed?.sealedDir ?? "").replaceAll("{releaseId}", releaseId);
+  const args = ["run", "--config", qaConfig, ...((config.qa.args?.[stage] ?? []).map(expand))];
+  const run = (deps.spawnRunner ?? spawnSync)(runnerFile, args, {
+    cwd: appRoot, encoding: "utf8", windowsHide: true, maxBuffer: 64 * 1024 * 1024,
+    env: { ...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 } : {}) },
+  });
+  if (!deps.quiet) { process.stdout.write(String(run.stdout ?? "")); process.stderr.write(String(run.stderr ?? "")); }
+  const evidenceFile = evidencePathFromOutput(run.stdout);
+  let evidence = null, evidenceSha256 = null;
+  if (evidenceFile && existsSync(evidenceFile)) {
+    const bytes = readFileSync(evidenceFile);
+    evidenceSha256 = createHash("sha256").update(bytes).digest("hex");
+    evidence = JSON.parse(bytes.toString("utf8"));
+  }
+  const required = evaluateRequiredChecks({ floor, stage, qa: config.qa, evidence });
+  // A passing receipt needs the runner to exit cleanly AND an evidence bundle that itself passed.
+  if (run.status !== 0 && evidence) evidence = { ...evidence, status: "failed" };
+  const receipt = sealQaReceipt(buildQaReceipt({
+    stage, app: config.app, platform, releaseId, source, closure: dependencyClosure(repoRoot, source.commit, gitRunner),
+    releaseConfigSha256: sha256File(configPath), qa: config.qa, floor, floorDigest,
+    policyBundleDigest: deps.policyBundleDigest ?? currentPolicyBundleDigest(deps.floorDir),
+    runner: { basename: path.basename(runnerFile).replace(/\.exe$/i, ""), path: runnerFile, sha256: runnerSha },
+    evidence, evidenceSha256, required, artifacts, sourceReceiptDigest,
+  }), key);
+  const file = qaReceiptPath({ repoRoot, releaseId, platform, stage });
+  writeQaReceipt(file, receipt);
+  return { receipt, file };
+}
+
+function usage(code) {
+  console.log("usage: right-release qa --stage source|installed --platform mac|win [--release <sealed-id>] [--config right-release.config.mjs]");
+  process.exit(code);
+}
+
+export async function main(args) {
+  let stage = "", platform = process.platform === "win32" ? "win" : "mac", releaseId = "", configName = "right-release.config.mjs";
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--stage") stage = args[++index];
+    else if (arg === "--platform") platform = args[++index];
+    else if (arg === "--release") releaseId = args[++index];
+    else if (arg === "--config") configName = args[++index];
+    else if (arg === "-h" || arg === "--help") usage(0);
+    else { console.error(`right-release qa: unknown argument: ${arg}`); process.exit(2); }
+  }
+  if (!QA_STAGES.includes(stage)) { console.error("right-release qa: --stage must be source or installed"); process.exit(2); }
+  if (platform !== "win" && platform !== "mac") { console.error("right-release qa: --platform must be win or mac"); process.exit(2); }
+  try {
+    const { receipt, file } = await runQa({ stage, platform, releaseIdArg: releaseId, configPath: path.resolve(configName) });
+    console.log(`right-release qa: ${stage} receipt ${receipt.status} ${receipt.digest.slice(0, 16)} -> ${file}`);
+    for (const item of receipt.required) console.log(`  ${item.id}: ${item.status}`);
+    process.exit(receipt.status === "passed" ? 0 : 1);
+  } catch (error) {
+    console.error(`right-release qa: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+if (process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) await main(process.argv.slice(2));

package/release-qa-floor.json

@@ -0,0 +1,9 @@
+{
+  "schema": 1,
+  "version": 1,
+  "runner": "rightkit-qa",
+  "stages": {
+    "source": { "required": ["smoke.launch", "journey"] },
+    "installed": { "required": ["smoke.launch", "journey"] }
+  }
+}

package/release-qa-receipt.mjs

@@ -0,0 +1,276 @@
+// Release QA receipts (hardening step 4): no signed release on any channel without a passing, artifact-bound
+// QA receipt for the exact commit.
+//
+//   source stage    admits the candidate build/sign: QA ran against the committed source.
+//   installed stage admits upload/publication: QA ran on the built, sealed artifacts (exact sha256) and chains
+//                   to the source receipt digest recorded in the sealed manifest.
+//
+// A receipt is written only by `right-release qa`, which runs RightKit's own runner (`rightkit-qa`), digests the
+// runner binary and the evidence bundle it produced, evaluates the protected QA floor, and MACs the result with a
+// key held in the protected credential store (Keychain / protected file / CI secret) — not app-writable JSON.
+// The floor, this verifier, and the receipt schema are pinned in the protected policy bundle.
+import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "./background-process.mjs";
+import { canonicalJson, canonicalRepositoryIdentity } from "./ownership-approval.mjs";
+import { OWNERSHIP_LOCKFILES } from "./ownership-lockfiles.mjs";
+import { QA_FLOOR_FILE, runningPolicyBundle } from "./ownership-policy-bundle.mjs";
+import { createCredentialStore, ProtectedSecretMissingError } from "./protected-credentials.mjs";
+import { isManagedHost } from "./managed-host-secrets.mjs";
+import { SCANNER_VERSION } from "./ownership.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const HEX64 = /^[a-f0-9]{64}$/;
+export const QA_RECEIPT_SCHEMA = 1;
+export const QA_STAGES = Object.freeze(["source", "installed"]);
+export const QA_KEY_ENV = "RIGHTKIT_QA_RECEIPT_KEY";
+const MAC_DOMAIN = "rightkit-qa-receipt-v1\0";
+
+export class QaAdmissionError extends Error {
+  constructor(message, { command } = {}) {
+    super(command ? `${message}\n  run: ${command}` : message);
+    this.name = "QaAdmissionError";
+    this.code = "QA_ADMISSION_REFUSED";
+    this.command = command ?? null;
+  }
+}
+
+const sha256Hex = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const digestOf = (value) => sha256Hex(canonicalJson(value));
+const platformDirOf = (platform) => (platform === "win" ? "windows" : platform);
+
+/** Exact command an agent must run to obtain the missing/invalid receipt. */
+export function qaCommandFor({ stage, platform, releaseId, configName = "right-release.config.mjs" }) {
+  return `right-release qa --stage ${stage} --platform ${platform}${stage === "installed" ? ` --release ${releaseId}` : ""} --config ${configName}`;
+}
+
+export function qaReceiptPath({ repoRoot, releaseId, platform, stage }) {
+  return path.join(repoRoot, ".right-release", "qa", releaseId, platformDirOf(platform), `${stage}.receipt.json`);
+}
+
+export function loadQaFloor(dir = here) {
+  const file = path.join(dir, QA_FLOOR_FILE);
+  let floor;
+  try { floor = JSON.parse(readFileSync(file, "utf8")); } catch (error) { throw new Error(`QA floor is unreadable (${QA_FLOOR_FILE}): ${error.message}`); }
+  const problems = validateQaFloor(floor);
+  if (problems.length) throw new Error(`QA floor is invalid: ${problems.join("; ")}`);
+  return { floor, digest: digestOf(floor) };
+}
+
+export function validateQaFloor(floor) {
+  const problems = [];
+  if (!floor || typeof floor !== "object" || Array.isArray(floor)) return ["floor must be an object"];
+  if (floor.schema !== 1) problems.push("floor schema must be 1");
+  if (!Number.isInteger(floor.version) || floor.version < 1) problems.push("floor version must be a positive integer");
+  if (typeof floor.runner !== "string" || !floor.runner) problems.push("floor runner is required");
+  for (const stage of QA_STAGES) {
+    const required = floor.stages?.[stage]?.required;
+    if (!Array.isArray(required) || required.length === 0 || required.some((id) => typeof id !== "string" || !id)) problems.push(`floor stage ${stage} must list required check ids`);
+  }
+  return problems;
+}
+
+/** The app's release config declares how floor ids map to evidence check names (exact, or `prefix*`). */
+export function validateAppQaConfig(qa, floor, stage) {
+  const problems = [];
+  if (!qa || typeof qa !== "object") return [`release config must declare qa { version, config, checks } (floor requires ${floor.stages[stage].required.join(", ")})`];
+  if (typeof qa.version !== "string" && typeof qa.version !== "number") problems.push("qa.version is required");
+  if (typeof qa.config !== "string" || !qa.config) problems.push("qa.config (rightkit-qa.toml path) is required");
+  for (const id of floor.stages[stage].required) {
+    const patterns = qa.checks?.[id];
+    if (!Array.isArray(patterns) || patterns.length === 0 || patterns.some((p) => typeof p !== "string" || !p)) problems.push(`qa.checks must map required floor check "${id}" to evidence check names`);
+  }
+  return problems;
+}
+
+const matches = (pattern, name) => (pattern.endsWith("*") ? name.startsWith(pattern.slice(0, -1)) : name === pattern);
+
+/** Per required id: passed only when at least one mapped evidence check exists and every match passed. */
+export function evaluateRequiredChecks({ floor, stage, qa, evidence }) {
+  const evidenceChecks = Array.isArray(evidence?.checks) ? evidence.checks : [];
+  return floor.stages[stage].required.map((id) => {
+    const patterns = qa.checks?.[id] ?? [];
+    const found = evidenceChecks.filter((check) => patterns.some((pattern) => matches(pattern, String(check.name))));
+    const bad = found.filter((check) => check.status !== "passed");
+    const status = found.length === 0 ? "missing" : bad.length ? "failed" : "passed";
+    return { id, status, evidenceChecks: found.map((check) => ({ name: String(check.name), status: String(check.status) })) };
+  });
+}
+
+function git(repoRoot, args, { runner = spawnSync, binary = false } = {}) {
+  const result = runner("git", ["-C", repoRoot, ...args], { encoding: binary ? "buffer" : "utf8", windowsHide: true, maxBuffer: 256 * 1024 * 1024 });
+  if (result?.status !== 0) throw new Error(`QA receipt: git ${args.join(" ")} failed`);
+  return binary ? result.stdout : String(result.stdout).trim();
+}
+
+/** Dependency closure: sha256 of every committed lockfile at the exact commit. */
+export function dependencyClosure(repoRoot, commit, runner) {
+  const names = git(repoRoot, ["ls-tree", "-r", "--name-only", commit], { runner }).split("\n").filter(Boolean);
+  const lockfiles = names.filter((name) => OWNERSHIP_LOCKFILES.includes(path.posix.basename(name))).sort()
+    .map((name) => ({ path: name, sha256: sha256Hex(git(repoRoot, ["show", `${commit}:${name}`], { runner, binary: true })) }));
+  return { lockfiles, digest: digestOf(lockfiles) };
+}
+
+export function sourceIdentity(repoRoot, runner) {
+  const commit = git(repoRoot, ["rev-parse", "HEAD"], { runner });
+  return {
+    commit,
+    tree: git(repoRoot, ["rev-parse", `${commit}^{tree}`], { runner }),
+    repositoryIdentity: canonicalRepositoryIdentity(git(repoRoot, ["remote", "get-url", "origin"], { runner })),
+  };
+}
+
+export function currentPolicyBundleDigest(dir = here) {
+  return runningPolicyBundle({ scannerVersion: SCANNER_VERSION, dir }).digest;
+}
+
+/** MAC key from the protected store (Keychain / protected file). Hosted CI may supply it as a per-run secret. */
+export function resolveQaReceiptKey({ env = process.env, credentialStore } = {}) {
+  const store = credentialStore ?? createCredentialStore({ env });
+  try { return store.read("qa-receipt-key"); }
+  catch (error) {
+    if (!(error instanceof ProtectedSecretMissingError)) throw error;
+    const fallback = !isManagedHost(env) && env.GITHUB_ACTIONS === "true" ? String(env[QA_KEY_ENV] ?? "").trim() : "";
+    if (fallback) return fallback;
+    throw error;
+  }
+}
+
+/** First `right-release qa` on a host creates the key. macOS Keychain / Windows protected file. */
+export function ensureQaReceiptKey({ env = process.env, credentialStore, platform = process.platform, provision } = {}) {
+  try { return resolveQaReceiptKey({ env, credentialStore }); }
+  catch (error) {
+    if (!(error instanceof ProtectedSecretMissingError) || !provision) throw error;
+    provision(randomBytes(32).toString("hex"), platform);
+    return resolveQaReceiptKey({ env, credentialStore });
+  }
+}
+
+const mac = (key, digest) => createHmac("sha256", key).update(`${MAC_DOMAIN}${digest}`).digest("hex");
+
+/** Seal a receipt body: digest over the canonical body, MAC over the digest. */
+export function sealQaReceipt(body, key) {
+  const digest = digestOf(body);
+  return { ...body, digest, mac: mac(key, digest) };
+}
+
+export function receiptDigest(receipt) {
+  const { digest, mac: _mac, ...body } = receipt;
+  return digestOf(body);
+}
+
+export function buildQaReceipt({
+  stage, app, platform, releaseId, source, closure, releaseConfigSha256, qa, floor, floorDigest, policyBundleDigest,
+  runner, evidence, evidenceSha256, required, artifacts = [], sourceReceiptDigest = null, now = new Date(),
+}) {
+  const evidenceOk = evidence?.status === "passed" && Boolean(evidence?.finishedAt);
+  const status = evidenceOk && required.every((item) => item.status === "passed") ? "passed" : "failed";
+  return {
+    schema: QA_RECEIPT_SCHEMA, stage, app, platform, releaseId,
+    repositoryIdentity: source.repositoryIdentity, commit: source.commit, tree: source.tree,
+    dependencyClosure: closure,
+    buildConfig: { releaseConfigSha256, platform },
+    qaPlan: { version: String(qa.version), configPath: qa.config, planDigest: digestOf({ version: String(qa.version), config: qa.config, checks: qa.checks ?? {}, args: qa.args ?? {} }) },
+    floor: { version: floor.version, digest: floorDigest },
+    policyBundleDigest,
+    runner,
+    evidence: { sha256: evidenceSha256, runId: evidence?.runId ?? null, status: evidence?.status ?? null, schemaVersion: evidence?.schemaVersion ?? null },
+    required, checks: (evidence?.checks ?? []).map((check) => ({ name: String(check.name), status: String(check.status) })),
+    artifacts, sourceReceiptDigest, status, createdAt: now.toISOString(),
+  };
+}
+
+/**
+ * Verify a receipt against the exact current state. Returns { ok, reason, receipt }.
+ * `expected.artifacts` ([{name, sha256}]) must equal the receipt's artifacts exactly (installed stage).
+ */
+export function verifyQaReceipt(receipt, { key, stage, repoRoot, releaseConfigSha256, floorDir = here, artifacts, sourceReceiptDigest, gitRunner, policyBundleDigest, source, closure }) {
+  const refuse = (reason) => ({ ok: false, reason });
+  if (!receipt || receipt.schema !== QA_RECEIPT_SCHEMA) return refuse("receipt is missing or has an unsupported schema");
+  if (receipt.stage !== stage) return refuse(`receipt is for stage ${receipt.stage}, not ${stage}`);
+  if (!HEX64.test(receipt.digest ?? "") || !HEX64.test(receipt.mac ?? "")) return refuse("receipt is unsealed");
+  if (receiptDigest(receipt) !== receipt.digest) return refuse("receipt contents do not match its digest");
+  const expectedMac = Buffer.from(mac(key, receipt.digest), "hex");
+  if (!timingSafeEqual(expectedMac, Buffer.from(receipt.mac, "hex"))) return refuse("receipt MAC is invalid (not written by this host's `right-release qa`)");
+  if (receipt.status !== "passed") return refuse("receipt records a failed QA run");
+  let floor;
+  try { floor = loadQaFloor(floorDir); } catch (error) { return refuse(error.message); }
+  if (receipt.floor?.digest !== floor.digest) return refuse("QA floor changed since the receipt was written");
+  let bundle;
+  try { bundle = policyBundleDigest ?? currentPolicyBundleDigest(floorDir); } catch (error) { return refuse(`policy bundle could not be computed: ${error.message}`); }
+  if (receipt.policyBundleDigest !== bundle) return refuse("protected policy bundle changed since the receipt was written");
+  if (receipt.evidence?.status !== "passed") return refuse("evidence bundle did not pass");
+  // Every floor-required check must be recorded and passed — skipped, failed, or missing refuses.
+  for (const id of floor.floor.stages[stage].required) {
+    const item = (receipt.required ?? []).find((entry) => entry.id === id);
+    if (!item) return refuse(`required check ${id} is not recorded in the receipt`);
+    if (item.status !== "passed") return refuse(`required check ${id} is ${item.status}`);
+    if (!item.evidenceChecks?.length || item.evidenceChecks.some((check) => check.status !== "passed")) return refuse(`required check ${id} has incomplete or non-passing evidence`);
+  }
+  let current, currentClosure;
+  try { current = source ?? sourceIdentity(repoRoot, gitRunner); currentClosure = closure ?? dependencyClosure(repoRoot, current.commit, gitRunner); }
+  catch (error) { return refuse(error.message); }
+  if (receipt.commit !== current.commit) return refuse(`receipt is for commit ${String(receipt.commit).slice(0, 12)}, current commit is ${current.commit.slice(0, 12)}`);
+  if (receipt.tree !== current.tree) return refuse("receipt source tree differs from the current commit tree");
+  if (receipt.repositoryIdentity !== current.repositoryIdentity) return refuse("receipt repository identity differs");
+  if (receipt.dependencyClosure?.digest !== currentClosure.digest) return refuse("dependency closure (lockfile digests) changed since the receipt was written");
+  if (releaseConfigSha256 !== undefined && receipt.buildConfig?.releaseConfigSha256 !== releaseConfigSha256) return refuse("release config changed since the receipt was written");
+  if (receipt.runner?.basename !== floor.floor.runner || !HEX64.test(receipt.runner?.sha256 ?? "")) return refuse(`receipt was not produced by the ${floor.floor.runner} runner`);
+  if (stage === "installed") {
+    const wanted = [...(artifacts ?? [])].map((item) => `${item.name}:${item.sha256}`).sort();
+    const have = (receipt.artifacts ?? []).map((item) => `${item.name}:${item.sha256}`).sort();
+    if (!wanted.length || JSON.stringify(wanted) !== JSON.stringify(have)) return refuse("receipt artifact hashes do not match the sealed artifacts");
+    if (!sourceReceiptDigest || receipt.sourceReceiptDigest !== sourceReceiptDigest) return refuse("installed QA is not chained to the source QA receipt sealed into this release");
+  }
+  return { ok: true, receipt };
+}
+
+export function readQaReceipt(file) {
+  try { return JSON.parse(readFileSync(file, "utf8")); } catch { return null; }
+}
+
+export function writeQaReceipt(file, receipt) {
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify(receipt, null, 2)}\n`);
+}
+
+function loadKeyOrRefuse(opts, command) {
+  try { return (opts.resolveKey ?? resolveQaReceiptKey)({ env: opts.env, credentialStore: opts.credentialStore }); }
+  catch (error) { throw new QaAdmissionError(`QA receipt key is unavailable (${error.message})`, { command }); }
+}
+
+/**
+ * Build gate: source QA must have passed for this exact commit before a candidate is built/signed.
+ * Returns the receipt digest to record in the sealed manifest.
+ */
+export function assertSourceQaAdmission({ repoRoot, releaseId, platform, configName, releaseConfigSha256, ...opts }) {
+  const command = qaCommandFor({ stage: "source", platform, releaseId, configName });
+  const receipt = readQaReceipt(qaReceiptPath({ repoRoot, releaseId, platform, stage: "source" }));
+  if (!receipt) throw new QaAdmissionError(`no source QA receipt for ${releaseId} (${platform}); a candidate cannot be built or signed without passing source QA`, { command });
+  const verdict = verifyQaReceipt(receipt, { key: loadKeyOrRefuse(opts, command), stage: "source", repoRoot, releaseConfigSha256, floorDir: opts.floorDir, gitRunner: opts.gitRunner, policyBundleDigest: opts.policyBundleDigest, source: opts.source, closure: opts.closure });
+  if (!verdict.ok) throw new QaAdmissionError(`source QA receipt rejected: ${verdict.reason}`, { command });
+  return { digest: receipt.digest, floorDigest: receipt.floor.digest };
+}
+
+/**
+ * Upload/publication gate for every provider (R2 + RightApps, GitHub Releases, updater channels): an installed-QA
+ * receipt for the exact sealed artifact hashes and commit must exist and pass. Dev builds never reach this gate —
+ * install-app --dev and the devArtifact lane never upload — and there is deliberately no manifest flag that skips it.
+ */
+export function assertInstalledQaAdmission({ repoRoot, manifest, platform, configName, releaseConfigSha256, ...opts }) {
+  const releaseId = manifest.releaseId;
+  const command = qaCommandFor({ stage: "installed", platform, releaseId, configName });
+  const receipt = readQaReceipt(qaReceiptPath({ repoRoot, releaseId, platform, stage: "installed" }));
+  if (!receipt) throw new QaAdmissionError(`no installed QA receipt for ${releaseId} (${platform}); nothing is published or uploaded without passing installed QA on these exact artifacts`, { command });
+  const verdict = verifyQaReceipt(receipt, {
+    key: loadKeyOrRefuse(opts, command), stage: "installed", repoRoot, releaseConfigSha256, floorDir: opts.floorDir,
+    artifacts: (manifest.files ?? []).map((file) => ({ name: file.name, sha256: file.sha256 })),
+    sourceReceiptDigest: manifest.qa?.sourceReceiptDigest,
+    gitRunner: opts.gitRunner, policyBundleDigest: opts.policyBundleDigest, source: opts.source, closure: opts.closure,
+  });
+  if (!verdict.ok) throw new QaAdmissionError(`installed QA receipt rejected: ${verdict.reason}`, { command });
+  if (receipt.commit !== manifest.commit) throw new QaAdmissionError("installed QA receipt commit differs from the sealed release commit", { command });
+  return { digest: receipt.digest };
+}

package/release.mjs

@@ -711,7 +711,7 @@ async function validateRightKitPackageContract(root, appName, hostedWorkflows) {
   if (pkg.packageManager !== RIGHTKIT_VERSIONS.packageManager) {
     fail(`${appName ?? pkg.name ?? "app"} packageManager must be ${RIGHTKIT_VERSIONS.packageManager}, got ${pkg.packageManager ?? "<missing>"}`);
   }
-  if (JSON.stringify(scripts).includes("../tools/right-release") || JSON.stringify(scripts).includes("../tools/rightkit/packages/release")) {
+  if (JSON.stringify(scripts).includes("../tools/right-release") || JSON.stringify(scripts).includes("../rightkit/packages/release")) {
     fail(`${appName ?? pkg.name ?? "app"} package.json must call the right-release bin, not parent-workspace release source`);
   }
   const rightKitDeps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };

package/rightkit-drift.mjs

@@ -33,7 +33,7 @@ const latestFor = (versions, ecosystem, name) => versions.registry
 export function dependencyManifests(appRoot) {
   const listed = spawnSync("git", ["-C", appRoot, "ls-files", "-z", "--", "package.json", "*/package.json", "Cargo.toml", "*/Cargo.toml"], { encoding: "utf8", windowsHide: true, maxBuffer: 16 * 1024 * 1024 });
   const files = listed.status === 0 ? listed.stdout.split("\0").filter(Boolean) : ["package.json", "Cargo.toml"].filter((file) => existsSync(path.join(appRoot, file)));
-  return files.filter((file) => !/(^|\/)(node_modules|vendor|target|dist)\//.test(file) && !file.startsWith("tools/rightkit/"));
+  return files.filter((file) => !/(^|\/)(node_modules|vendor|target|dist)\//.test(file) && !file.startsWith("rightkit/"));
 }
 
 /** Pins behind the latest published RightKit version. Workspace, path, git and range-less specs are skipped. */