@rightkit/release 0.2.173 → 0.3.0

package/development-signing.mjs

@@ -4,6 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "./background-process.mjs";
 import { runMacCodesignCommands } from "./macos-signing-session.mjs";
+import { bundleRelativePath, compileBundlePathMap, globToRegExp, isGlobPattern, lookupBundlePath, resolveBundleIdentifier, validateBundleRelativeKey, validateIdentifierTemplate, validateSigningIdentifier } from "./mac-bundle-signing.mjs";
 
 export class MacosDevelopmentSigningError extends Error {
   constructor(code, message, details = {}) {
@@ -100,7 +101,8 @@ export function resolveMacosDevelopmentSigning({ root, bundle, descriptor = {},
     if (existsSync(file)) mac = { ...mac, ...JSON.parse(readFileSync(file, "utf8")).bundle?.macOS };
   }
   const sign = config.targets?.mac?.sign ?? {};
-  const entitlements = sign.entitlements ? path.resolve(root, sign.entitlements) : mac.entitlements ? path.resolve(tauriRoot, mac.entitlements) : null;
+  // `sign.entitlements` is the app-level file when a string; an object is the per-path map (readDevSigningSettings).
+  const entitlements = typeof sign.entitlements === "string" && sign.entitlements ? path.resolve(root, sign.entitlements) : mac.entitlements ? path.resolve(tauriRoot, mac.entitlements) : null;
   if (entitlements && !existsSync(entitlements)) throw new MacosDevelopmentSigningError("DEV_MAC_SIGNING_CONFIG_INVALID", `Configured entitlements file is missing: ${entitlements}`);
   // CI-only ad hoc: no Keychain, no provisioning profile (a profile authorizes restricted entitlements that an ad hoc signature cannot carry).
   if (ciAdhoc) return { identity: "-", certificateSha1: "-", teamIdentifier: null, entitlements, provisioningProfile: null, mode: CI_ADHOC_SIGNING, adhoc: true };
@@ -158,9 +160,128 @@ function macho(file) {
   } finally { closeSync(fd); }
 }
 
+const invalidConfig = (message) => { throw new MacosDevelopmentSigningError("DEV_MAC_SIGNING_CONFIG_INVALID", message); };
+const ASSERT_KEYS = new Set(["path", "identifier", "teamIdentifier", "authority"]);
+
+/**
+ * Declarative per-binary signing settings of a dev install. Everything is optional; with none declared the result is
+ * empty and signing is exactly what it was before these keys existed.
+ *   install.identifiers / sign.identifiers          { path-or-glob: "--identifier value" }   ("." is the bundle)
+ *   install.identifierTemplate / sign.identifierTemplate   default identifier for remaining plain Mach-O files
+ *   install.entitlements / sign.entitlements (object)      { path-or-glob: plist path } (a string sign.entitlements is the app file)
+ *   install.timestamp                               true adds --timestamp (a secure timestamp contacts Apple's server)
+ *   install.assert                                  [{ path-or-glob, identifier?, teamIdentifier?, authority? }]
+ *   install.assertTeamSignedNested                  true: every Mach-O in the bundle carries the app's TeamIdentifier
+ * install.* entries win over sign.* entries (so one declaration in `sign` keeps dev and release identifiers identical).
+ * `root` resolves entitlement plist paths and checks they exist; without it only the shape is validated.
+ */
+export function readDevSigningSettings(descriptor = {}, config = {}, { root, exists = existsSync } = {}) {
+  const sign = config?.targets?.mac?.sign ?? {};
+  const identifier = (raw, label) => validateSigningIdentifier(raw, label, invalidConfig);
+  const identifiers = [...compileBundlePathMap(descriptor.identifiers, "install.identifiers", { reject: invalidConfig, value: identifier }),
+    ...compileBundlePathMap(sign.identifiers, "sign.identifiers", { reject: invalidConfig, value: identifier })];
+  const templateSource = descriptor.identifierTemplate !== undefined ? ["install.identifierTemplate", descriptor.identifierTemplate] : sign.identifierTemplate !== undefined ? ["sign.identifierTemplate", sign.identifierTemplate] : null;
+  const identifierTemplate = templateSource ? validateIdentifierTemplate(templateSource[1], templateSource[0], invalidConfig) : undefined;
+  const plistPath = (raw, label) => {
+    if (typeof raw !== "string" || !raw.trim()) invalidConfig(`${label} must be an entitlements plist path`);
+    if (!root) return raw;
+    const file = path.resolve(root, raw);
+    if (!exists(file)) invalidConfig(`${label} entitlements file not found: ${file}`);
+    return file;
+  };
+  const signMap = typeof sign.entitlements === "object" && sign.entitlements !== null && !Array.isArray(sign.entitlements) ? sign.entitlements : undefined;
+  const entitlements = [...compileBundlePathMap(descriptor.entitlements, "install.entitlements", { reject: invalidConfig, value: plistPath }),
+    ...compileBundlePathMap(signMap, "sign.entitlements", { reject: invalidConfig, value: plistPath })];
+  if (descriptor.timestamp !== undefined && typeof descriptor.timestamp !== "boolean") invalidConfig("install.timestamp must be true or false");
+  if (descriptor.assertTeamSignedNested !== undefined && typeof descriptor.assertTeamSignedNested !== "boolean") invalidConfig("install.assertTeamSignedNested must be true or false");
+  const rawAssertions = descriptor.assert ?? [];
+  if (!Array.isArray(rawAssertions)) invalidConfig("install.assert must be an array of { path, identifier?, teamIdentifier?, authority? }");
+  const assertions = rawAssertions.map((item, index) => {
+    const label = `install.assert[${index}]`;
+    if (!item || typeof item !== "object" || Array.isArray(item)) invalidConfig(`${label} must be an object`);
+    for (const key of Object.keys(item)) if (!ASSERT_KEYS.has(key)) invalidConfig(`${label}.${key} is not a known key (path, identifier, teamIdentifier, authority)`);
+    validateBundleRelativeKey(item.path, `${label}.path`, invalidConfig);
+    const checks = ["identifier", "teamIdentifier", "authority"].filter((key) => item[key] !== undefined);
+    if (!checks.length) invalidConfig(`${label} needs at least one of identifier, teamIdentifier, authority`);
+    for (const key of checks) if (typeof item[key] !== "string" || !item[key].trim()) invalidConfig(`${label}.${key} must be a non-empty string`);
+    return { path: item.path, ...Object.fromEntries(checks.map((key) => [key, item[key]])) };
+  });
+  return { identifiers, identifierTemplate, entitlements, timestamp: descriptor.timestamp === true, assertions, assertTeamSignedNested: descriptor.assertTeamSignedNested === true };
+}
+
+function listBundleFiles(bundle) {
+  const out = [];
+  const walk = (directory) => {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      const file = path.join(directory, entry.name);
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) walk(file);
+      else if (entry.isFile()) out.push(bundleRelativePath(bundle, file));
+    }
+  };
+  walk(bundle);
+  return out;
+}
+
+/**
+ * Post-sign identity assertions, read from `codesign -dvv` (stdout and stderr: codesign reports on stderr). Fails closed with
+ * DEV_MAC_SIGNING_ASSERT_FAILED listing every mismatch. A glob that matches no file is a failure, so a typo cannot pass.
+ * `assertTeamSignedNested` additionally requires every Mach-O in the bundle (dylibs included) to be signed by
+ * `teamIdentifier`, not ad hoc. Used on the signed staging copy and again on the installed copy (a failure there rolls back).
+ * Injectable: run, listFiles(bundle) -> bundle-relative file paths, isMachO(file), join.
+ */
+export function assertSignedIdentities({ root, bundle, settings, teamIdentifier, identity, env = process.env, run = spawnSync, listFiles = listBundleFiles, isMachO = macho, join = path.join, label = "signed bundle" }) {
+  const { assertions = [], assertTeamSignedNested = false } = settings ?? {};
+  if (!assertions.length && !assertTeamSignedNested) return { checked: 0 };
+  const reports = new Map();
+  const report = (file) => {
+    if (!reports.has(file)) {
+      const result = run("codesign", ["-dvv", file], captureOptions(root, env));
+      if (result.error || result.status !== 0) {
+        throw new MacosDevelopmentSigningError("DEV_MAC_SIGNING_ASSERT_FAILED", `${label}: cannot inspect the signing identity of ${file}: ${result.error?.message || output(result) || `exit ${result.status ?? "unavailable"}`}`, { identity });
+      }
+      const text = output(result);
+      reports.set(file, { identifier: /^Identifier=(.+)$/m.exec(text)?.[1]?.trim(), team: /^TeamIdentifier=(.+)$/m.exec(text)?.[1]?.trim(), authorities: [...text.matchAll(/^Authority=(.+)$/gm)].map((match) => match[1].trim()), adhoc: /^Signature=adhoc$/m.test(text) });
+    }
+    return reports.get(file);
+  };
+  const absolute = (relative) => (relative === "." ? bundle : join(bundle, ...relative.split("/")));
+  let files;
+  const listed = () => (files ??= listFiles(bundle));
+  const problems = [];
+  let checked = 0;
+  for (const item of assertions) {
+    const targets = isGlobPattern(item.path) ? listed().filter((relative) => globToRegExp(item.path).test(relative)) : [item.path];
+    if (!targets.length) { problems.push(`${item.path}: matches no file in the bundle`); continue; }
+    for (const relative of targets) {
+      const actual = report(absolute(relative));
+      checked += 1;
+      if (item.identifier !== undefined && actual.identifier !== item.identifier) problems.push(`${relative}: Identifier=${actual.identifier ?? "missing"}, expected ${item.identifier}`);
+      if (item.teamIdentifier !== undefined && actual.team !== item.teamIdentifier) problems.push(`${relative}: TeamIdentifier=${actual.team ?? "missing"}, expected ${item.teamIdentifier}`);
+      if (item.authority !== undefined && !actual.authorities.includes(item.authority)) problems.push(`${relative}: Authority does not include ${JSON.stringify(item.authority)} (found ${actual.authorities.map((name) => JSON.stringify(name)).join(", ") || "none"})`);
+    }
+  }
+  if (assertTeamSignedNested) {
+    if (!teamIdentifier) problems.push("assertTeamSignedNested: the expected TeamIdentifier is unknown (ad hoc signing has none)");
+    else {
+      for (const relative of [".", ...listed().filter((entry) => isMachO(absolute(entry)))]) {
+        const actual = report(absolute(relative));
+        checked += 1;
+        if (actual.adhoc || actual.team !== teamIdentifier) problems.push(`${relative}: ${actual.adhoc ? "ad hoc signed" : `TeamIdentifier=${actual.team ?? "missing"}`}, expected TeamIdentifier=${teamIdentifier}`);
+      }
+    }
+  }
+  if (problems.length) {
+    throw new MacosDevelopmentSigningError("DEV_MAC_SIGNING_ASSERT_FAILED", `${label}: signing identity assertions failed (${problems.length}): ${problems.slice(0, 20).join("; ")}${problems.length > 20 ? "; ..." : ""}. Refusing dev installation.`, { identity, problems });
+  }
+  return { checked };
+}
+
 export function signMacosDevelopmentBundle(options) {
   const { root, bundle, env = process.env, run = spawnSync } = options;
   const context = { root, env, run };
+  // Declared per-binary settings are validated before any Keychain or codesign call.
+  const settings = readDevSigningSettings(options.descriptor, options.config, { root });
   const signing = resolveMacosDevelopmentSigning({ ...options, env, run });
   const { identity, certificateSha1, teamIdentifier, entitlements, provisioningProfile } = signing;
   const embedded = path.join(bundle, "Contents", "embedded.provisionprofile");
@@ -218,12 +339,20 @@ export function signMacosDevelopmentBundle(options) {
     const commands = [];
     for (const target of ordered) {
       // Bind the exact profile-authorized certificate even when names collide in Keychain.
-      const args = ["--force", "--options", "runtime", "--sign", certificateSha1];
+      const relative = bundleRelativePath(bundle, target.file);
+      let identifier;
+      try {
+        identifier = resolveBundleIdentifier({ relative, identifiers: settings.identifiers, template: settings.identifierTemplate, bundleId: options.descriptor?.bundleId ?? appInfo.CFBundleIdentifier, plain: !target.info });
+      } catch (cause) { throw new MacosDevelopmentSigningError("DEV_MAC_SIGNING_CONFIG_INVALID", cause.message, { cause }); }
+      // --timestamp only when declared (install.timestamp): it needs Apple's timestamp server, and dev builds otherwise sign offline.
+      const args = ["--force", "--options", "runtime", ...(settings.timestamp ? ["--timestamp"] : []), ...(identifier ? ["--identifier", identifier] : []), "--sign", certificateSha1];
       const parent = target.file === bundle;
+      const mappedEntitlements = lookupBundlePath(settings.entitlements, relative || ".");
       const profiledHelper = target.info && existsSync(path.join(target.file, "Contents/embedded.provisionprofile")) && target.info.CFBundleIdentifier === appInfo.CFBundleIdentifier;
       if (profiledHelper && !parent && provisioningProfile) copyFileSync(embedded, path.join(target.file, "Contents/embedded.provisionprofile"));
       const variant = !parent && entitlementVariants.find((item) => path.basename(target.file).replace(/\.(app|xpc|appex|bundle)$/, "").toLowerCase().endsWith(item.suffix));
-      if (variant) args.push("--entitlements", entitlementFile(variant.file));
+      if (mappedEntitlements) args.push("--entitlements", entitlementFile(mappedEntitlements));
+      else if (variant) args.push("--entitlements", entitlementFile(variant.file));
       else if (entitlements && (parent || profiledHelper)) args.push("--entitlements", entitlementFile(entitlements));
       else {
         const existing = run("codesign", ["--display", "--entitlements", ":-", target.file], captureOptions(root, env));
@@ -248,7 +377,9 @@ export function signMacosDevelopmentBundle(options) {
     const requirement = output(checked("codesign", ["--display", "-r-", bundle], context, "DEV_MAC_SIGNATURE_INVALID", identity));
     const designated = /^designated => (.+)$/m.exec(requirement)?.[1]?.trim();
     if (!designated || /\bcdhash\b/.test(designated)) throw new MacosDevelopmentSigningError("DEV_MAC_SIGNING_UNSTABLE_REQUIREMENT", `Signing identity ${JSON.stringify(identity)}: designated requirement ${designated ? JSON.stringify(designated) : "is missing"} is not stable across rebuilds (cdhash-bound). Refusing dev installation.`, { identity, designatedRequirement: designated });
-    return { ...signing, provisioningProfile: provisioningProfile ? embedded : null, verified: "strict-deep", designatedRequirement: designated, signedTargets: ordered.length };
+    // Declared identity assertions (install.assert, install.assertTeamSignedNested) on the signed staging copy, before any install.
+    const asserted = assertSignedIdentities({ root, bundle, settings, teamIdentifier, identity, env, run, label: "signed staging copy", ...(options.listFiles ? { listFiles: options.listFiles } : {}), ...(options.isMachO ? { isMachO: options.isMachO } : {}) });
+    return { ...signing, provisioningProfile: provisioningProfile ? embedded : null, verified: "strict-deep", designatedRequirement: designated, signedTargets: ordered.length, ...(asserted.checked ? { assertedIdentities: asserted.checked } : {}) };
   } finally { rmSync(scratch, { recursive: true, force: true }); }
 }
 

package/development.mjs

@@ -105,7 +105,7 @@ export function runDevelopment({ root, platform, config, buildOnly = false, dryR
     // Android: cargo-ndk (Cargo dev profile) fills the generated jniLibs, then the Gradle debug build packages it.
     if (target.ndk) { rmSync(target.ndk.jniLibs, { recursive: true, force: true }); execute(androidDevelopmentNdkCommand(target.ndk), { root, env: childEnv, dryRun, run, label: "native build" }); }
     for (const command of target.build) execute(command, { root, env: childEnv, dryRun, run, label: "build" });
-    // Dev and QA binaries run from one stable staged path, copied in place (<name>.previous kept), never from the
+    // Dev and QA binaries run from one stable staged path, copied in place (no backup of the old copy), never from the
     // broker's per-generation target folder or a hashed dev-targets folder.
     const staged = target.stage?.length ? stageDevelopmentBinaries(target.stage, { root, platform: platform === "win" ? "win32" : process.platform }) : [];
     for (const file of staged) console.log(`right-release dev: staged ${file}`);
@@ -114,7 +114,7 @@ export function runDevelopment({ root, platform, config, buildOnly = false, dryR
       // installTauriDevId is async: the lease is held until it settles, so a broker cutover cannot land mid-install.
       const built = resolveTauriArtifact(target.install, { root, platform, env: childEnv });
       releaseLease = false;
-      return installTauriDevId({ appRoot: root, config: target.install, built, env: childEnv })
+      return installTauriDevId({ appRoot: root, config: target.install, releaseConfig: config, built, env: childEnv })
         .then((outcome) => ({ built: true, installed: true, ...(staged.length ? { staged } : {}), devid: outcome }))
         .finally(() => lease.release());
     }
@@ -140,9 +140,10 @@ function install(descriptor, { root, platform, config, env, run, sinceMs = null,
     // was running, pass /R so the installer relaunches it as the user (RunAsUser, outside this process tree).
     const running = isWindowsProcessRunning(path.basename(descriptor.expectedInstalledPath), { run });
     if (running) console.log(`right-release dev: ${descriptor.productName} is running; the installer will close it and relaunch it`);
-    // The silent installer updates the fixed path in place. Keep the copy it replaces once, as <exe>.previous (never run).
+    // The silent installer updates the fixed path in place. NO backup of the old copy (Orthic-Labs/rightkit#348): a stale
+    // <exe>.previous left by an older RightKit is removed, nothing is copied, and a failed install is reinstalled from an older build.
     const installedBefore = path.resolve(root, descriptor.expectedInstalledPath);
-    if (existsSync(installedBefore) && statSync(installedBefore).isFile()) copyFileSync(installedBefore, previousPathOf(installedBefore));
+    rmSync(previousPathOf(installedBefore), { recursive: true, force: true });
     const result = run(app, windowsInstallerArguments({ running }), { cwd: root, env, stdio: "inherit", windowsHide: true, shell: false });
     if (result.status !== 0) throw new Error(`development installer failed (${result.status}): ${app}`);
     const installed = path.resolve(root, descriptor.expectedInstalledPath);
@@ -156,7 +157,6 @@ function install(descriptor, { root, platform, config, env, run, sinceMs = null,
   mkdirSync(path.dirname(destination), { recursive: true });
   // Fixed staging name (not per-pid): the copy is signed and verified here, then renamed into place. Nothing runs from it.
   const staging = stagingPathOf(destination);
-  const previous = previousPathOf(destination);
   rmSync(staging, { recursive: true, force: true });
   cpSync(app, staging, { recursive: true, verbatimSymlinks: true });
   let signing;
@@ -167,7 +167,7 @@ function install(descriptor, { root, platform, config, env, run, sinceMs = null,
     if (!signing.adhoc && existsSync(destination)) assertStableDesignatedRequirement({ root, installed: destination, expected: signing.designatedRequirement, env, run });
     executableName = readBundleExecutable(staging, { root, env, run });
   } catch (error) { rmSync(staging, { recursive: true, force: true }); throw error; }
-  swapInstalledMacosBundle({ staging, destination, previous, executableName });
+  swapInstalledMacosBundle({ staging, destination, executableName });
   if (signing.provisioningProfile) signing.provisioningProfile = path.join(destination, "Contents", "embedded.provisionprofile");
   if (signing.adhoc) console.log(`right-release dev: installed ${destination}; signing=ci-adhoc (ad hoc signed on a CI runner; NOT a release artifact); signature=adhoc; TeamIdentifier=none`);
   else console.log(`right-release dev: installed ${destination}; identity=${signing.identity}; TeamIdentifier=${signing.teamIdentifier}; profile=${signing.provisioningProfile ?? "none"}; designated=${signing.designatedRequirement}`);
@@ -181,12 +181,13 @@ export class DevelopmentInstallError extends Error {
 const NODE_FS = { existsSync, lstatSync, mkdirSync, copyFileSync, readFileSync, renameSync, rmSync, statSync };
 
 /**
- * Move the signed staging bundle into place, keeping the previous app as `<destination>.previous`, and verify it: Info.plist exists and
+ * Move the signed staging bundle into place IN PLACE with NO backup (Orthic-Labs/rightkit#348: the old app is removed,
+ * never kept as `<destination>.previous`; a stale `.previous` is removed too), and verify it: Info.plist exists and
  * the installed main executable (`executableName`, the staged CFBundleExecutable read through plutil by the caller) exists with the same SHA-256 as the staged one. Any failure removes the
- * new install, renames `.previous` back and throws a DevelopmentInstallError (code DEV_INSTALL_VERIFICATION_FAILED,
+ * new (absent or partial) install, does NOT restore the old app (reinstall from an older DMG), and throws a DevelopmentInstallError (code DEV_INSTALL_VERIFICATION_FAILED,
  * DEV_INSTALL_EXECUTABLE_MISSING or DEV_INSTALL_EXECUTABLE_MISMATCH). `fs` is the file-system seam (tests inject it).
  */
-export function swapInstalledMacosBundle({ staging, destination, previous = previousPathOf(destination), executableName, fs = NODE_FS }) {
+export function swapInstalledMacosBundle({ staging, destination, executableName, fs = NODE_FS }) {
   if (typeof executableName !== "string" || !executableName) throw new DevelopmentInstallError("DEV_INSTALL_VERIFICATION_FAILED", "swapInstalledMacosBundle requires the staged CFBundleExecutable name");
   const executable = path.join("Contents", "MacOS", executableName);
   const digest = (file) => createHash("sha256").update(fs.readFileSync(file)).digest("hex");
@@ -196,9 +197,9 @@ export function swapInstalledMacosBundle({ staging, destination, previous = prev
     fs.rmSync(staging, { recursive: true, force: true });
     throw new DevelopmentInstallError("DEV_INSTALL_EXECUTABLE_MISSING", `staged app has no main executable ${executable}: ${staging} (${error.message})`);
   }
-  // The old app becomes `<destination>.previous` (replacing any older one) and stays there for rollback; any failure renames it back.
+  // The old app is removed and the staged one renamed over it; no old copy survives, even on failure.
   swapInPlace({
-    staging, destination, previous, fs,
+    staging, destination, previous: null, fs,
     verify: () => {
       if (!fs.existsSync(path.join(destination, "Contents", "Info.plist"))) throw new DevelopmentInstallError("DEV_INSTALL_VERIFICATION_FAILED", `installed app verification failed: ${destination}`);
       const installed = path.join(destination, executable);

package/dist-scan.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// Fails when a built web bundle (vite `dist/`) carries dev, mock or fixture code (replaces per-app
+// checkReleaseBundle.mjs copies). Scans text files for forbidden marker strings and flags chunk file
+// names that match a forbidden name pattern. Read-only: it never writes, builds or follows a symlink.
+// Usage: right-release dist-scan --dist <dir> --forbid <string>... [--forbid-file <path>]
+//          [--forbid-name <regex>]... [--ext js,mjs,css,html,json,map]
+// A --forbid-file is JSON (`["a","b"]` or `{ "forbid": [...], "forbidNames": [...] }`) or plain text with
+// one marker per line (blank lines and `#` comments ignored).
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const DEFAULT_EXTENSIONS = Object.freeze(["js", "mjs", "css", "html", "json", "map"]);
+export const DEFAULT_FORBIDDEN_NAMES = Object.freeze([/^(devSource|mockDataSource|fixtures)[-.]/]);
+
+export function parseForbidFile(text, name = "forbid file") {
+  const trimmed = text.trim();
+  if (trimmed.startsWith("[") || trimmed.startsWith("{")) {
+    let data;
+    try { data = JSON.parse(trimmed); } catch (error) { throw new Error(`${name}: invalid JSON (${error.message})`); }
+    const forbid = Array.isArray(data) ? data : data.forbid ?? [];
+    const forbidNames = Array.isArray(data) ? [] : data.forbidNames ?? [];
+    if (!Array.isArray(forbid) || !Array.isArray(forbidNames) || ![...forbid, ...forbidNames].every((s) => typeof s === "string" && s)) throw new Error(`${name}: entries must be non-empty strings`);
+    return { forbid, forbidNames };
+  }
+  return { forbid: trimmed.split(/\r?\n/).map((l) => l.trim()).filter((l) => l && !l.startsWith("#")), forbidNames: [] };
+}
+
+/** Scan `dist`. Returns { dist, files, scanned, markers, offenders: [{file, reason}] }. */
+export function scanDist(dist, { forbid = [], forbidNames = [], extensions = DEFAULT_EXTENSIONS } = {}) {
+  const root = resolve(dist);
+  if (!existsSync(root) || !statSync(root).isDirectory()) throw new Error(`No ${root}: build first.`);
+  const nameRes = [...DEFAULT_FORBIDDEN_NAMES, ...forbidNames.map((pattern) => {
+    try { return new RegExp(pattern); } catch (error) { throw new Error(`--forbid-name ${JSON.stringify(pattern)} is not a regular expression (${error.message})`); }
+  })];
+  const extRe = new RegExp(`\\.(${extensions.map((e) => e.replace(/[^\w]/g, "")).filter(Boolean).join("|")})$`);
+  const offenders = [];
+  let files = 0;
+  let scanned = 0;
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const path = join(dir, entry.name);
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) { walk(path); continue; }
+      files += 1;
+      const rel = relative(root, path);
+      if (nameRes.some((re) => re.test(basename(path)))) offenders.push({ file: rel, reason: "forbidden chunk name" });
+      if (!extRe.test(path)) continue;
+      scanned += 1;
+      const text = readFileSync(path, "utf8");
+      for (const marker of forbid) if (text.includes(marker)) offenders.push({ file: rel, reason: `marker: ${marker}` });
+    }
+  };
+  walk(root);
+  return { dist: root, files, scanned, markers: forbid.length, offenders };
+}
+
+export function distScanFailed(result) {
+  return result.offenders.length > 0 || result.files === 0 || result.markers === 0;
+}
+
+const USAGE = "usage: right-release dist-scan --dist <dir> --forbid <string>... [--forbid-file <path>] [--forbid-name <regex>]... [--ext js,css,...]";
+
+export function parseArgs(argv) {
+  const out = { dist: null, forbid: [], forbidNames: [], extensions: undefined };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const value = () => { const v = argv[++i]; if (v === undefined || v.startsWith("--")) throw new Error(`${a} needs a value`); return v; };
+    if (a === "--dist") out.dist = value();
+    else if (a === "--forbid") out.forbid.push(value());
+    else if (a === "--forbid-name") out.forbidNames.push(value());
+    else if (a === "--ext") out.extensions = value().split(",").filter(Boolean);
+    else if (a === "--forbid-file") {
+      const file = value();
+      const parsed = parseForbidFile(readFileSync(file, "utf8"), file);
+      out.forbid.push(...parsed.forbid);
+      out.forbidNames.push(...parsed.forbidNames);
+    } else throw new Error(`unknown argument ${a}`);
+  }
+  if (!out.dist) throw new Error("--dist is required");
+  return out;
+}
+
+export function main(argv) {
+  let result;
+  try {
+    const args = parseArgs(argv);
+    if (args.forbid.length === 0) throw new Error("no --forbid markers given");
+    result = scanDist(args.dist, args);
+  } catch (error) {
+    console.error(`right-release dist-scan: ${error.message}\n${USAGE}`);
+    return 2;
+  }
+  if (distScanFailed(result)) {
+    console.error(`Release bundle contains forbidden code:\n${result.offenders.map((o) => `${o.file}: ${o.reason}`).join("\n") || `no files in ${result.dist}`}`);
+    return 1;
+  }
+  console.log(`Release bundle clean: ${result.markers} markers absent from ${result.dist} (${result.scanned} files scanned)`);
+  return 0;
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) process.exit(main(process.argv.slice(2)));

package/dmg-build.mjs

@@ -7,6 +7,10 @@ import { readDmgSpec } from "./dmg-spec.mjs";
 import { detachWithRetrySync } from "./hdiutil-detach.mjs";
 import { assertReleaseExecutionAllowed } from "./execution-policy.mjs";
 import { assertNoQaControl } from "./qa-control-scan.mjs";
+import { signMacosEntries, validateCodesignIdentifier } from "./mac-sign-core.mjs";
+import { MACOS_PORTABLE_SIGNING_CONTRACT } from "./macos-signing-contract.mjs";
+import { resolveMacosDeveloperIdIdentity } from "./macos-signing-identity.mjs";
+import { runMacCodesignCommands } from "./macos-signing-session.mjs";
 
 const fail = (code, message) => Object.assign(new Error(message), { code });
 const pair = (value, label, positive = false) => {
@@ -25,12 +29,44 @@ export function resolveDmgOptions(input = {}) {
   return spec ? { ...readDmgSpec(spec, { app: explicit.app }), ...definedOnly(explicit) } : explicit;
 }
 
+/**
+ * Developer ID sign a finished disk image (#646): secure timestamp, no hardened runtime (a disk image has none), an
+ * optional stable `--identifier`, strict verification, and an optional signing receipt (the sign-macos.mjs shape) so a
+ * later notarize step can bind to it. It never notarizes or uploads. Developer ID only: no ad hoc or Apple Development fallback.
+ */
+export function signBuiltDmg({ file, identifier, receipt }) {
+  const identity = resolveMacosDeveloperIdIdentity();
+  const files = signMacosEntries([{ file, hardenedRuntime: false, options: [], ...(identifier ? { identifier } : {}) }], {
+    identity,
+    signOne: (codesignArgs) => runMacCodesignCommands([codesignArgs])[0],
+    inspect: (tool, args) => {
+      const result = spawnSync(tool, args, { encoding: "utf8" });
+      const output = `${result.stdout ?? ""}\n${result.stderr ?? ""}`;
+      if (result.status !== 0) throw new Error(`${tool} ${args.join(" ")} failed: ${output.trim()}`);
+      return output;
+    },
+  });
+  if (receipt) {
+    mkdirSync(path.dirname(receipt), { recursive: true });
+    writeFileSync(receipt, `${JSON.stringify({ schema: 1, signingContract: MACOS_PORTABLE_SIGNING_CONTRACT, identity, files }, null, 2)}\n`);
+  }
+  return files;
+}
+
+/**
+ * Build the branded DMG; with `sign: true` (CLI `--sign`) it is then Developer ID signed (`identifier`, `signReceipt`
+ * optional) and a signing failure removes the unsigned image so nothing downstream can pick it up. `signDmg` is injectable.
+ */
 export function buildDmg(input = {},
 { platform = process.platform, run = spawnSync, makeAlias = backgroundAlias,
-  log = (event) => console.error(JSON.stringify(event)), sleep } = {}) {
+  log = (event) => console.error(JSON.stringify(event)), sleep, signDmg = signBuiltDmg } = {}) {
   if (platform !== "darwin") throw fail("DMG_NATIVE_HOST_REQUIRED", "DMG creation requires macOS");
   let { app, out, volname, background, iconSize = 128, appPosition = [158, 231],
-    applicationsPosition = [492, 231], window = [660, 400], windowPosition = [100, 100], volumeIcon } = resolveDmgOptions(input);
+    applicationsPosition = [492, 231], window = [660, 400], windowPosition = [100, 100], volumeIcon,
+    sign = false, identifier, signReceipt } = resolveDmgOptions(input);
+  if (identifier !== undefined && !sign) throw fail("DMG_INVALID_OPTIONS", "--identifier needs --sign");
+  if (signReceipt !== undefined && !sign) throw fail("DMG_INVALID_OPTIONS", "--receipt needs --sign");
+  if (identifier !== undefined) { try { validateCodesignIdentifier(identifier, "--identifier"); } catch (error) { throw fail("DMG_INVALID_OPTIONS", error.message); } }
   if (!app || !out || !volname) throw fail("DMG_INVALID_OPTIONS", "--app, --out & --volname are required");
   app = path.resolve(app); out = path.resolve(out);
   if (!app.endsWith(".app") || !statSync(app).isDirectory() || !existsSync(path.join(app, "Contents", "Info.plist"))) {
@@ -103,8 +139,18 @@ export function buildDmg(input = {},
     command("/usr/bin/hdiutil", ["convert", rw, "-format", "UDZO", "-imagekey", "zlib-level=9", "-o", compressed]);
     command("/usr/bin/hdiutil", ["verify", compressed]);
     renameSync(compressed, out);
-    log({ event: "dmg-build-completed", out, format: "UDZO" });
-    return { out, format: "UDZO" };
+    let signed;
+    if (sign) {
+      // Developer ID sign the finished image. A failure removes the unsigned image: nothing downstream may pick it up.
+      try { signed = signDmg({ file: out, ...(identifier ? { identifier } : {}), ...(signReceipt ? { receipt: path.resolve(signReceipt) } : {}) }); }
+      catch (error) {
+        rmSync(out, { force: true });
+        throw fail("DMG_SIGN_FAILED", `signing ${out} failed (the unsigned image was removed): ${error.message}`);
+      }
+      log({ event: "dmg-signed", out, ...(identifier ? { identifier } : {}) });
+    }
+    log({ event: "dmg-build-completed", out, format: "UDZO", signed: Boolean(sign) });
+    return { out, format: "UDZO", ...(sign ? { signed: true, signing: signed } : {}) };
   } catch (error) {
     log({ event: "dmg-build-failed", out, code: error.code ?? "DMG_BUILD_FAILED", message: error.message });
     throw error;
@@ -122,8 +168,11 @@ export function parseDmgArguments(args) {
   if (args[0] !== "build") throw fail("DMG_INVALID_OPTIONS", "expected dmg build");
   const flags = new Map([["--app", "app"], ["--out", "out"], ["--volname", "volname"], ["--background", "background"],
     ["--icon-size", "iconSize"], ["--app-position", "appPosition"], ["--applications-position", "applicationsPosition"], ["--window", "window"], ["--window-position", "windowPosition"], ["--volume-icon", "volumeIcon"], ["--spec", "spec"]]);
+  flags.set("--identifier", "identifier"); flags.set("--receipt", "signReceipt");
   const options = {};
   for (let i = 1; i < args.length; i += 2) {
+    // `--sign` is the one value-less flag: Developer ID sign the finished image (#646).
+    if (args[i] === "--sign") { if (options.sign !== undefined) throw fail("DMG_INVALID_OPTIONS", "invalid option: --sign"); options.sign = true; i -= 1; continue; }
     const key = flags.get(args[i]);
     if (!key || options[key] !== undefined || !args[i + 1] || args[i + 1].startsWith("--")) throw fail("DMG_INVALID_OPTIONS", `invalid option: ${args[i]}`);
     options[key] = args[i + 1];

package/icon-pack.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// App icon packers (bogusyogi/rightkit#675): assemble a Windows ICO or a macOS ICNS from per-size PNG frames, so
+// hand-tuned small frames (16/24/32/48) are kept exactly as drawn instead of being down-scaled from one master.
+//   right-release icons ico  --out <file.ico>  --frame <PNG>... [--dir <folder of <size>.png>]
+//   right-release icons icns --out <file.icns> --frame <PNG>... [--dir <folder of <size>.png>]
+// Every frame must be a square PNG; its size comes from its IHDR, never from the file name. ICO frames are stored
+// as PNG (Vista+), sizes 1..256. ICNS accepts 16, 32, 64, 128, 256, 512 and 1024. Pure Buffer work, any host.
+// Rendering a master image to PNG frames and DMG background art stay with the app's design source
+// (dmg background: generate-dmg-background.py).
+import { readFileSync, readdirSync, writeFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+export const ICNS_TYPES = Object.freeze({ 16: "icp4", 32: "icp5", 64: "icp6", 128: "ic07", 256: "ic08", 512: "ic09", 1024: "ic10" });
+function fail(message, code = "ICON_INVALID") { throw Object.assign(new Error(message), { code }); }
+
+/** Read the pixel size of a square PNG from its IHDR. */
+export function pngSize(bytes, label = "frame") {
+  const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+  if (buf.length < 33 || !buf.subarray(0, 8).equals(PNG_MAGIC) || buf.toString("latin1", 12, 16) !== "IHDR") fail(`${label} is not a PNG`);
+  const width = buf.readUInt32BE(16), height = buf.readUInt32BE(20);
+  if (width !== height) fail(`${label} must be square, got ${width}x${height}`);
+  // Walk the chunk list: IHDR first (13 bytes), at least one IDAT, IEND last with nothing after it.
+  if (buf.readUInt32BE(8) !== 13) fail(`${label} has a malformed IHDR chunk`);
+  let at = 8, idat = false, iend = false, first = true;
+  while (at < buf.length) {
+    if (at + 12 > buf.length) fail(`${label} is a truncated PNG`);
+    const length = buf.readUInt32BE(at), type = buf.toString("latin1", at + 4, at + 8);
+    if (at + 12 + length > buf.length) fail(`${label} is a truncated PNG`);
+    if (iend) fail(`${label} has data after IEND`);
+    if (first && type !== "IHDR") fail(`${label} is not a PNG`);
+    first = false;
+    if (type === "IDAT") idat = true;
+    if (type === "IEND") iend = true;
+    at += 12 + length;
+  }
+  if (!idat) fail(`${label} has no image data (IDAT)`);
+  if (!iend) fail(`${label} is missing IEND`);
+  const depth = buf[24], colorType = buf[25];
+  if (depth !== 8 || colorType !== 6) fail(`${label} must be 8-bit RGBA (color type 6, bit depth 8), got bit depth ${depth}, color type ${colorType}`);
+  return width;
+}
+
+function normalizeFrames(frames, { min = 1, max = 1024, only = null } = {}) {
+  if (!Array.isArray(frames) || frames.length === 0) fail("at least one PNG frame is required", "ICON_USAGE");
+  const bySize = new Map();
+  for (const frame of frames) {
+    const bytes = Buffer.isBuffer(frame) ? frame : Buffer.from(frame);
+    const size = pngSize(bytes);
+    if (size < min || size > max || (only && !only.includes(size))) fail(`unsupported frame size ${size}${only ? ` (allowed: ${only.join(", ")})` : ` (allowed ${min}..${max})`}`);
+    if (bySize.has(size)) fail(`duplicate ${size}x${size} frame`);
+    bySize.set(size, bytes);
+  }
+  return [...bySize.entries()].sort((a, b) => a[0] - b[0]);
+}
+
+/** @param {Buffer[]} frames PNG buffers, one per size (1..256). @returns {Buffer} ICO file. */
+export function packIco(frames) {
+  const sorted = normalizeFrames(frames, { max: 256 });
+  const header = Buffer.alloc(6 + 16 * sorted.length);
+  header.writeUInt16LE(0, 0); header.writeUInt16LE(1, 2); header.writeUInt16LE(sorted.length, 4);
+  let offset = header.length;
+  sorted.forEach(([size, png], i) => {
+    const at = 6 + i * 16;
+    header[at] = size === 256 ? 0 : size; header[at + 1] = size === 256 ? 0 : size;
+    header.writeUInt16LE(1, at + 4); header.writeUInt16LE(32, at + 6);
+    header.writeUInt32LE(png.length, at + 8); header.writeUInt32LE(offset, at + 12);
+    offset += png.length;
+  });
+  return Buffer.concat([header, ...sorted.map(([, png]) => png)]);
+}
+
+/** @param {Buffer[]} frames PNG buffers (16, 32, 64, 128, 256, 512, 1024). @returns {Buffer} ICNS file. */
+export function packIcns(frames) {
+  const sorted = normalizeFrames(frames, { only: Object.keys(ICNS_TYPES).map(Number) });
+  const chunks = sorted.map(([size, png]) => {
+    const head = Buffer.alloc(8);
+    head.write(ICNS_TYPES[size], 0, "latin1"); head.writeUInt32BE(png.length + 8, 4);
+    return Buffer.concat([head, png]);
+  });
+  const total = 8 + chunks.reduce((n, c) => n + c.length, 0);
+  const head = Buffer.alloc(8);
+  head.write("icns", 0, "latin1"); head.writeUInt32BE(total, 4);
+  return Buffer.concat([head, ...chunks]);
+}
+
+function parseArgs(argv) {
+  const [kind, ...rest] = argv;
+  const opts = { kind, out: null, frames: [], dirs: [] };
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i], value = rest[i + 1];
+    if (!["--out", "--frame", "--dir"].includes(arg)) fail(`unknown icons argument: ${arg}`, "ICON_USAGE");
+    if (value === undefined || value.startsWith("--")) fail(`${arg} needs a value`, "ICON_USAGE");
+    i += 1;
+    if (arg === "--out") opts.out = value; else if (arg === "--frame") opts.frames.push(value); else opts.dirs.push(value);
+  }
+  if (!["ico", "icns"].includes(kind) || !opts.out) fail("usage: right-release icons ico|icns --out <file> --frame <PNG>... [--dir <folder>]", "ICON_USAGE");
+  for (const dir of opts.dirs) for (const name of readdirSync(dir).filter((n) => n.toLowerCase().endsWith(".png")).sort()) opts.frames.push(path.join(dir, name));
+  return opts;
+}
+
+export function main(argv = process.argv.slice(2), out = console) {
+  try {
+    const opts = parseArgs(argv);
+    const frames = opts.frames.map((file) => readFileSync(file));
+    const bytes = opts.kind === "ico" ? packIco(frames) : packIcns(frames);
+    mkdirSync(path.dirname(path.resolve(opts.out)), { recursive: true });
+    writeFileSync(opts.out, bytes);
+    out.log(JSON.stringify({ out: opts.out, kind: opts.kind, frames: opts.frames.length, bytes: bytes.length }));
+    return 0;
+  } catch (error) {
+    out.error(error.message);
+    return error.code === "ICON_USAGE" ? 2 : 1;
+  }
+}
+
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) process.exit(main());