@rightkit/release 0.2.173 → 0.3.0

package/mac-bundle-signing.mjs

@@ -1,5 +1,5 @@
 // Directory entries (.app bundles) in `sign.prePackageFiles`: sign nested code inside-out first
-// (no entitlements), then the bundle itself, reusing the swift-mac-app inside-out discovery.
+// (no entitlements unless declared per path), then the bundle itself, reusing the swift-mac-app inside-out discovery.
 import { existsSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
 import { discoverNestedCode } from "./swift-mac-app.mjs";
@@ -31,3 +31,145 @@ export function expandMacSigningEntries(files, { isDirectory = (f) => statSync(f
   }
   return { nested: [...new Set(nested)], files };
 }
+
+// ---------------------------------------------------------------------------------------------------------------------
+// Declarative per-binary signing settings, shared by the dev installer (development-signing.mjs) and release nested code.
+//
+//   identifiers:        { "<bundle-relative path or glob>": "<--identifier value>" }
+//   identifierTemplate: "<bundleId>.runtime.<relpath>"  (default identifier for the remaining plain Mach-O files)
+//   entitlements:       { "<bundle-relative path or glob>": "<entitlements plist path>" }
+//
+// Paths are relative to the .app bundle with `/` separators (`Contents/MacOS/engine`); "." names the bundle itself.
+// An exact key beats a glob; among globs the first declared wins. `*` and `?` stay inside one path segment, `**` crosses
+// segments. Nothing declared means nothing changes: no `--identifier`, no entitlements (release nested code stays unentitled).
+// ---------------------------------------------------------------------------------------------------------------------
+
+/** A codesign `--identifier` value. Must not start with `-` (argv safety). */
+export const SIGNING_IDENTIFIER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9.-]{0,254}$/; // same charset as release validation and the signing agent
+const TEMPLATE_TOKENS = new Set(["bundleId", "relpath", "basename"]);
+const BUNDLE_DIRECTORY = /\.(app|framework|xpc|appex|bundle)$/;
+const sanitizePart = (value) => String(value).replace(/[^A-Za-z0-9.-]+/g, ".");
+
+export const isGlobPattern = (pattern) => /[*?]/.test(pattern);
+
+export function globToRegExp(glob) {
+  let out = "";
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === "*") {
+      if (glob[i + 1] === "*") {
+        if (glob[i + 2] === "/") { out += "(?:.*/)?"; i += 2; } else { out += ".*"; i += 1; }
+      } else out += "[^/]*";
+    } else if (c === "?") out += "[^/]";
+    else out += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp(`^${out}$`);
+}
+
+/** Bundle-relative POSIX path of `file` inside `app`; "" for the bundle itself. */
+export const bundleRelativePath = (app, file) => path.relative(app, file).split(path.sep).join("/");
+
+export function validateBundleRelativeKey(key, label, reject) {
+  if (typeof key !== "string" || !key.trim() || key !== key.trim()) reject(`${label}: keys must be non-empty bundle-relative paths`);
+  if (key !== "." && (key.startsWith("/") || /^[A-Za-z]:/.test(key) || key.includes("\\") || key.split("/").includes(".."))) {
+    reject(`${label}: ${JSON.stringify(key)} must be a path inside the .app bundle (relative, no "..", "/" separators)`);
+  }
+}
+
+export function validateSigningIdentifier(value, label, reject) {
+  if (typeof value !== "string" || !SIGNING_IDENTIFIER_PATTERN.test(value)) reject(`${label} must be a codesign identifier (letters, digits, "." "_" "-"; not starting with "-"), got ${JSON.stringify(value)}`);
+  return value;
+}
+
+/** `<relpath>` and `<basename>` are the bundle-relative path / file name with runs outside [A-Za-z0-9.-] replaced by ".". */
+export function expandIdentifierTemplate(template, { bundleId, relpath }) {
+  return template.replace(/<(bundleId|relpath|basename)>/g, (_, token) => {
+    if (token === "bundleId") {
+      if (!bundleId) throw fail("identifier template uses <bundleId> but the bundle identifier is unknown");
+      return bundleId;
+    }
+    return sanitizePart(token === "relpath" ? relpath : path.posix.basename(relpath));
+  });
+}
+
+export function validateIdentifierTemplate(template, label, reject) {
+  if (typeof template !== "string" || !template) reject(`${label} must be a non-empty string such as "<bundleId>.runtime.<relpath>"`);
+  const tokens = [...template.matchAll(/<([^<>]*)>/g)].map((match) => match[1]);
+  if (tokens.some((token) => !TEMPLATE_TOKENS.has(token))) reject(`${label} may only use <bundleId>, <relpath> and <basename>`);
+  if (!tokens.includes("relpath") && !tokens.includes("basename")) reject(`${label} must contain <relpath> or <basename> so each binary gets its own identifier`);
+  const rest = template.replace(/<[^<>]*>/g, "");
+  if (rest.includes("<") || rest.includes(">")) reject(`${label} has an unbalanced "<" or ">"`);
+  validateSigningIdentifier(expandIdentifierTemplate(template, { bundleId: "a.b", relpath: "Contents/x" }), `${label} (expanded)`, reject);
+  return template;
+}
+
+/** Compile `{ pattern: value }` into lookup entries. `value(raw, label)` validates and transforms each value. */
+export function compileBundlePathMap(map, label, { reject, value = (raw) => raw }) {
+  if (map === undefined) return [];
+  if (!map || typeof map !== "object" || Array.isArray(map)) reject(`${label} must be an object mapping bundle-relative paths or globs to values`);
+  return Object.entries(map).map(([pattern, raw]) => {
+    validateBundleRelativeKey(pattern, label, reject);
+    return { pattern, regex: isGlobPattern(pattern) ? globToRegExp(pattern) : null, value: value(raw, `${label}[${JSON.stringify(pattern)}]`) };
+  });
+}
+
+/** Exact key first, then the first matching glob. undefined when nothing matches. */
+export function lookupBundlePath(entries, relative) {
+  const exact = entries.find((entry) => !entry.regex && entry.pattern === relative);
+  if (exact) return exact.value;
+  return entries.find((entry) => entry.regex?.test(relative))?.value;
+}
+
+/**
+ * The `--identifier` for one path, or undefined (codesign then derives it as before). The map applies to anything,
+ * including "." for the bundle; the template applies only to plain Mach-O files (`plain`), never to bundles.
+ */
+export function resolveBundleIdentifier({ relative, identifiers = [], template, bundleId, plain }) {
+  const explicit = lookupBundlePath(identifiers, relative || ".");
+  if (explicit !== undefined) return explicit;
+  if (!template || !plain || !relative) return undefined;
+  const expanded = expandIdentifierTemplate(template, { bundleId, relpath: relative });
+  if (!SIGNING_IDENTIFIER_PATTERN.test(expanded)) throw fail(`identifier template produced an invalid identifier for ${relative}: ${JSON.stringify(expanded)}`);
+  return expanded;
+}
+
+/** CFBundleIdentifier of a bundle (XML plist only; undefined when unreadable). */
+export function bundleIdentifierOf(app) {
+  try {
+    const plist = readFileSync(path.join(app, "Contents", "Info.plist"), "utf8");
+    return /<key>CFBundleIdentifier<\/key>\s*<string>([^<]+)<\/string>/.exec(plist)?.[1];
+  } catch { return undefined; }
+}
+
+/**
+ * Release nested-code settings from `sign.identifiers`, `sign.identifierTemplate` and a per-path `sign.entitlements` object.
+ * Returns Map<absolute nested file, { identifier?, entitlements?: absolute }> holding only files with something declared;
+ * every other file keeps today's behaviour (no entitlements, no --identifier). A string `sign.entitlements` is the
+ * app-level file and is ignored here. Paths in the map are resolved against `root`; a missing file is an error.
+ * The caller (release signing) adds the flags with `nestedSigningFlags`.
+ */
+export function resolveNestedSigningSettings(nested, { app, sign = {}, bundleId = bundleIdentifierOf(app), root, exists = existsSync }) {
+  const reject = (message) => { throw fail(message); };
+  const identifiers = compileBundlePathMap(sign.identifiers, "sign.identifiers", { reject, value: (raw, label) => validateSigningIdentifier(raw, label, reject) });
+  const template = sign.identifierTemplate === undefined ? undefined : validateIdentifierTemplate(sign.identifierTemplate, "sign.identifierTemplate", reject);
+  const perPath = typeof sign.entitlements === "object" && sign.entitlements !== null && !Array.isArray(sign.entitlements) ? sign.entitlements : undefined;
+  const entitlements = compileBundlePathMap(perPath, "sign.entitlements", { reject, value: (raw, label) => {
+    if (typeof raw !== "string" || !raw.trim()) reject(`${label} must be an entitlements plist path`);
+    const file = path.resolve(root, raw);
+    if (!exists(file)) reject(`${label} entitlements file not found: ${file}`);
+    return file;
+  } });
+  const settings = new Map();
+  if (!identifiers.length && !template && !entitlements.length) return settings;
+  for (const file of nested) {
+    const relative = bundleRelativePath(app, file);
+    const identifier = resolveBundleIdentifier({ relative, identifiers, template, bundleId, plain: !BUNDLE_DIRECTORY.test(file) });
+    const entitlementsFile = lookupBundlePath(entitlements, relative);
+    if (identifier !== undefined || entitlementsFile !== undefined) {
+      settings.set(file, { ...(identifier !== undefined ? { identifier } : {}), ...(entitlementsFile !== undefined ? { entitlements: entitlementsFile } : {}) });
+    }
+  }
+  return settings;
+}
+
+export const nestedSigningFlags = (settings) => [...(settings?.identifier ? ["--identifier", settings.identifier] : []), ...(settings?.entitlements ? ["--entitlements", settings.entitlements] : [])];

package/mac-signing-matrix.mjs

@@ -11,7 +11,7 @@
 // inside-out plan. It never runs codesign: sign-macos.mjs (via mac-sign-core.mjs) executes the plan.
 import { existsSync, lstatSync, openSync, closeSync, readSync, realpathSync, statSync } from "node:fs";
 import path from "node:path";
-import { expandMacSigningEntries, mainExecutableName } from "./mac-bundle-signing.mjs";
+import { expandMacSigningEntries, mainExecutableName, resolveNestedSigningSettings } from "./mac-bundle-signing.mjs";
 
 const invalid = (message) => Object.assign(new Error(message), { code: "MAC_SIGN_CONFIG_INVALID" });
 
@@ -85,11 +85,57 @@ function validateNestedKey(key) {
   return null;
 }
 
+// Per-path nested signing maps: `sign.identifiers`, `sign.identifierTemplate` and an object-valued `sign.entitlements`.
+// Same strictness as the per-item settings above: reverse-DNS identifiers, contained relative plist paths that exist.
+function validateNestedSigningMaps(sign, { root, errors, isFile }) {
+  const declared = {};
+  const check = (map, label, value) => {
+    if (!isPlainObject(map)) { errors.push(`${label} must be an object mapping bundle-relative paths or globs to values`); return; }
+    for (const [key, raw] of Object.entries(map)) {
+      const entry = `${label}[${JSON.stringify(key)}]`;
+      if (!key.trim() || key !== key.trim() || key.includes("\0") || key.includes("\\") || path.posix.isAbsolute(key) || /^[A-Za-z]:/.test(key) || key.split("/").includes("..")) {
+        errors.push(`${entry}: key must be a bundle-relative path (no "..", no absolute path, "/" separators)`);
+      }
+      value(raw, entry);
+    }
+  };
+  if (sign.identifiers !== undefined) {
+    check(sign.identifiers, "sign.identifiers", (raw, entry) => {
+      if (typeof raw !== "string" || !IDENTIFIER_PATTERN.test(raw)) errors.push(`${entry} must be 1-255 characters of letters, digits, '.' and '-', starting with a letter or digit`);
+    });
+    declared.identifiers = sign.identifiers;
+  }
+  if (sign.identifierTemplate !== undefined) {
+    const template = sign.identifierTemplate;
+    if (typeof template !== "string" || !template) errors.push("sign.identifierTemplate must be a non-empty string such as \"<bundleId>.runtime.<relpath>\"");
+    else if (!/^[A-Za-z0-9.-]*$/.test(template.replace(/<[^<>]*>/g, ""))) errors.push("sign.identifierTemplate literal text may only contain letters, digits, '.' and '-' around <bundleId>, <relpath> and <basename>");
+    else declared.identifierTemplate = template;
+  }
+  if (isPlainObject(sign.entitlements)) {
+    check(sign.entitlements, "sign.entitlements", (raw, entry) => {
+      if (typeof raw !== "string" || !raw.trim()) { errors.push(`${entry} must be a non-empty path string`); return; }
+      if (path.isAbsolute(raw) || /^[A-Za-z]:/.test(raw) || raw.includes("\0")) { errors.push(`${entry} must be relative to the release config directory: ${raw}`); return; }
+      const resolved = path.resolve(root, raw);
+      const relative = path.relative(root, resolved);
+      if (relative.startsWith("..") || path.isAbsolute(relative)) errors.push(`${entry} must stay inside the release config directory: ${raw}`);
+      else if (!isFile(resolved)) errors.push(`${entry} entitlements file not found: ${raw}`);
+      else if (!looksLikePlist(resolved)) errors.push(`${entry} is not a property list (expected an XML or binary plist): ${raw}`);
+    });
+    declared.entitlements = sign.entitlements;
+  }
+  if (errors.length || !Object.keys(declared).length) return undefined;
+  // Delegate key globs and template tokens to the shared resolver so release and development read them identically.
+  try { resolveNestedSigningSettings([], { app: "x.app", sign: declared, bundleId: "a.b", root, exists: () => true }); }
+  catch (error) { errors.push(error.message); return undefined; }
+  return declared;
+}
+
 /**
  * Validate and normalize `sign` for a macOS target. Collects every problem, then throws one
- * MAC_SIGN_CONFIG_INVALID error. Returns { entries, nestedCode } where
- *   entries:    [{ file, identifier?, entitlements?: absolute, options: [] }]   (file stays as declared)
- *   nestedCode: [{ key, identifier?, entitlements?: absolute, options: [] }]
+ * MAC_SIGN_CONFIG_INVALID error. Returns { entries, nestedCode, nestedSigning? } where
+ *   entries:       [{ file, identifier?, entitlements?: absolute, options: [] }]   (file stays as declared)
+ *   nestedCode:    [{ key, identifier?, entitlements?: absolute, options: [] }]
+ *   nestedSigning: { identifiers?, identifierTemplate?, entitlements? } as declared; present only when one is declared
  * Injectable: isFile.
  */
 export function validateMacSigningConfig(sign, { root, isFile = (file) => existsSync(file) && statSync(file).isFile() } = {}) {
@@ -136,8 +182,10 @@ export function validateMacSigningConfig(sign, { root, isFile = (file) => exists
       }
     }
   }
+  const nestedSigning = validateNestedSigningMaps(sign, context);
+  if (nestedSigning && !entries.some((entry) => /\.app\/?$/.test(entry.file))) errors.push("sign.identifiers, sign.identifierTemplate and per-path sign.entitlements need a .app entry in sign.prePackageFiles to resolve their paths against");
   if (errors.length) throw invalid(`invalid macOS signing configuration:\n${errors.map((line) => `- ${line}`).join("\n")}`);
-  return { entries, nestedCode };
+  return { entries, nestedCode, ...(nestedSigning ? { nestedSigning } : {}) };
 }
 
 /** True when an entry or nested item carries anything beyond the default (hardened runtime, no entitlements). */
@@ -154,7 +202,7 @@ const depth = (file) => file.split(path.sep).length;
  * a nestedCode path is missing, is a symlink, escapes the bundle, or names the bundle's main executable.
  * Injectable: expand, lstat, realpath, mainName.
  */
-export function planMacSigning({ entries, nestedCode = [], expand = expandMacSigningEntries, lstat = lstatSync, realpath = realpathSync, mainName = mainExecutableName }) {
+export function planMacSigning({ entries, nestedCode = [], nestedSigning, root, resolveSettings = resolveNestedSigningSettings, expand = expandMacSigningEntries, lstat = lstatSync, realpath = realpathSync, mainName = mainExecutableName }) {
   const { nested: discovered } = expand(entries.map((entry) => entry.file));
   const byPath = new Map(discovered.map((file) => [file, { file, options: [] }]));
   if (nestedCode.length) {
@@ -174,6 +222,25 @@ export function planMacSigning({ entries, nestedCode = [], expand = expandMacSig
       byPath.set(file, { file, ...(item.identifier ? { identifier: item.identifier } : {}), ...(item.entitlements ? { entitlements: item.entitlements } : {}), options: item.options });
     }
   }
+  // Per-path maps (sign.identifiers / identifierTemplate / per-path sign.entitlements) fill in only what a nestedCode item left
+  // unset. Nothing declared: this block is skipped and the items stay exactly as discovered.
+  if (nestedSigning && Object.keys(nestedSigning).length) {
+    const apps = entries.map((entry) => entry.file).filter((file) => /\.app\/?$/.test(file)).map((file) => file.replace(/\/+$/, ""));
+    for (const app of apps) {
+      const own = [...byPath.values()].filter((item) => item.file.startsWith(app + path.sep) || item.file.startsWith(`${app}/`));
+      let settings;
+      try { settings = resolveSettings(own.map((item) => item.file), { app, sign: nestedSigning, root: root ?? process.cwd() }); }
+      catch (error) { throw invalid(error.message); }
+      for (const item of own) {
+        const found = settings.get(item.file);
+        if (!found) continue;
+        const identifier = item.identifier ?? found.identifier;
+        if (identifier !== undefined && !IDENTIFIER_PATTERN.test(identifier)) throw invalid(`signing identifier for ${path.relative(app, item.file)} must be letters, digits, '.' and '-': ${JSON.stringify(identifier)}`);
+        const entitlements = item.entitlements ?? found.entitlements;
+        byPath.set(item.file, { ...item, ...(identifier !== undefined ? { identifier } : {}), ...(entitlements ? { entitlements } : {}) });
+      }
+    }
+  }
   const nested = [...byPath.values()].sort((a, b) => depth(b.file) - depth(a.file) || a.file.localeCompare(b.file));
   return { nested, top: entries };
 }

package/macho-approval-hash.mjs

@@ -0,0 +1,181 @@
+// Signing-independent approval hashes for staged prebuilt binaries (Orthic-Labs/rightkit#490).
+//
+// `raw-sha256`                        the sha256 of the file bytes (Windows and Linux binaries).
+// `macho-codesign-strip-linkedit-v1`  the sha256 of a thin little-endian 64-bit Mach-O after its code signature is removed:
+//                                      LC_CODE_SIGNATURE and the trailing signature blob are gone, the __LINKEDIT filesize is
+//                                      whatever `codesign --remove-signature` leaves, and the __LINKEDIT vmsize is normalised to
+//                                      the page-rounded filesize, so a signed and an unsigned copy of the same build hash alike.
+//
+// This is the algorithm GenRight's `local-image-approval-hash.mjs` recorded as `approval_hash_algorithm` in its runtime
+// manifest, moved here so apps stop carrying it. Every layout surprise (a fat or big-endian file, a duplicate or non-terminal
+// signature, a load command that changed, padding that is not zero) is a typed refusal, never a guess. The signature is removed
+// from a private copy with `/usr/bin/codesign --remove-signature`; the input file is never modified. macOS only for Mach-O.
+import { createHash, randomBytes } from "node:crypto";
+import { chmodSync, lstatSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "./background-process.mjs";
+
+export const APPROVAL_RAW_SHA256 = "raw-sha256";
+export const APPROVAL_MACHO_STRIP_LINKEDIT_V1 = "macho-codesign-strip-linkedit-v1";
+export const APPROVAL_ALGORITHMS = Object.freeze([APPROVAL_RAW_SHA256, APPROVAL_MACHO_STRIP_LINKEDIT_V1]);
+
+const LC_CODE_SIGNATURE = 0x1d;
+const LC_SEGMENT_64 = 0x19;
+const MH_MAGIC_64 = 0xfeedfacf;
+const CPU_TYPE_X86_64 = 0x01000007;
+const CPU_TYPE_ARM64 = 0x0100000c;
+
+export class ApprovalHashError extends Error {
+  constructor(code, message) { super(message); this.name = "ApprovalHashError"; this.code = code; }
+}
+const fail = (message, code = "APPROVAL_HASH_INVALID_MACHO") => { throw new ApprovalHashError(code, `backend integrity: ${message}`); };
+
+/** Parse a thin 64-bit little-endian Mach-O. Exported for tests. */
+export function parseMachO(bytes) {
+  if (bytes.length < 32 || bytes.readUInt32LE(0) !== MH_MAGIC_64) fail("only little-endian 64-bit thin Mach-O is supported");
+  const cpuType = bytes.readUInt32LE(4);
+  if (![CPU_TYPE_X86_64, CPU_TYPE_ARM64].includes(cpuType)) fail("unsupported Mach-O CPU type");
+  const ncmds = bytes.readUInt32LE(16);
+  const sizeofcmds = bytes.readUInt32LE(20);
+  const commandEnd = 32 + sizeofcmds;
+  if (ncmds > 65_536 || commandEnd > bytes.length || sizeofcmds > bytes.length / 2) fail("invalid Mach-O load command table");
+  let cursor = 32;
+  let signature = null;
+  let linkedit = null;
+  const normalizedCommands = [];
+  for (let index = 0; index < ncmds; index += 1) {
+    if (cursor + 8 > commandEnd) fail("truncated Mach-O load command");
+    const command = bytes.readUInt32LE(cursor);
+    const commandSize = bytes.readUInt32LE(cursor + 4);
+    if (commandSize < 8 || commandSize % 4 !== 0 || cursor + commandSize > commandEnd) fail("invalid Mach-O load command size");
+    const commandBytes = Buffer.from(bytes.subarray(cursor, cursor + commandSize));
+    if (command === LC_CODE_SIGNATURE) {
+      if (commandSize !== 16 || signature) fail("invalid duplicate code signature command");
+      const offset = bytes.readUInt32LE(cursor + 8);
+      const size = bytes.readUInt32LE(cursor + 12);
+      if (!size || offset + size > bytes.length) fail("invalid code signature extent");
+      signature = { offset, size };
+    } else if (command === LC_SEGMENT_64) {
+      if (commandSize < 72) fail("truncated Mach-O segment command");
+      const sectionCount = commandBytes.readUInt32LE(64);
+      if (sectionCount > 65_536 || 72 + sectionCount * 80 > commandSize) fail("invalid Mach-O segment sections");
+      const segmentName = commandBytes.subarray(8, 24).toString("utf8").replace(/\0.*$/s, "");
+      if (segmentName === "__LINKEDIT") {
+        if (linkedit) fail("duplicate __LINKEDIT segment");
+        const vmsize = commandBytes.readBigUInt64LE(32);
+        const fileoff = commandBytes.readBigUInt64LE(40);
+        const filesize = commandBytes.readBigUInt64LE(48);
+        if (fileoff + filesize > BigInt(bytes.length) || vmsize < filesize) fail("invalid __LINKEDIT extent");
+        // vmsize and filesize legitimately differ after the signature is removed: they are normalised, never compared raw.
+        commandBytes.fill(0, 32, 40);
+        commandBytes.fill(0, 48, 56);
+        linkedit = { fileoff, filesize, vmsize, vmsizeOffset: cursor + 32 };
+      }
+    }
+    if (command !== LC_CODE_SIGNATURE) normalizedCommands.push(commandBytes);
+    cursor += commandSize;
+  }
+  if (cursor !== commandEnd) fail("load commands do not fill declared table");
+  if (!linkedit) fail("missing __LINKEDIT segment");
+  if (signature && (BigInt(signature.offset) < linkedit.fileoff
+      || signature.offset + signature.size !== bytes.length
+      || linkedit.fileoff + linkedit.filesize !== BigInt(bytes.length))) {
+    fail("signature is not terminal __LINKEDIT data");
+  }
+  return { bytes, cpuType, ncmds, sizeofcmds, signature, linkedit, normalizedCommands };
+}
+
+/**
+ * Every byte outside the explicitly permitted ranges must be identical between the captured original and the stripped copy.
+ * Permitted: header ncmds/sizeofcmds (checked by the caller), the load-command table (compared command by command, with only
+ * the signature command removed and __LINKEDIT vmsize/filesize normalised), the zeroed tail the shorter table leaves, and the
+ * signature blob plus its alignment padding at the end of __LINKEDIT. Code, data and all __LINKEDIT content before the
+ * signature are compared byte for byte.
+ */
+function assertOnlySignatureDiffers(before, after) {
+  const a = before.bytes;
+  const b = after.bytes;
+  if (!before.signature) {
+    if (a.length !== b.length || !a.equals(b)) fail("unsigned Mach-O changed during normalization");
+    return;
+  }
+  const same = (from, to, label) => {
+    if (from === to) return;
+    if (!a.subarray(from, to).equals(b.subarray(from, to))) fail(`signature removal changed ${label}`);
+  };
+  const beforeTable = 32 + before.sizeofcmds;
+  const afterTable = 32 + after.sizeofcmds;
+  same(0, 16, "Mach-O header");
+  same(24, 32, "Mach-O header");
+  if (b.subarray(afterTable, beforeTable).some((byte) => byte !== 0)) fail("signature removal left nonzero bytes after the load commands");
+  const keptEnd = Number(after.linkedit.fileoff + after.linkedit.filesize);
+  if (b.length !== keptEnd) fail("stripped Mach-O does not end at __LINKEDIT");
+  same(beforeTable, keptEnd, "executable or data bytes");
+}
+
+/**
+ * The approval digest of an already-unsigned copy and its signed original: verifies that signature removal changed
+ * nothing but the signature, then hashes the unsigned bytes with the normalised __LINKEDIT vmsize. Exported for tests.
+ */
+export function machoApprovalDigest(beforeBytes, afterBytes) {
+  const before = parseMachO(beforeBytes);
+  const after = parseMachO(Buffer.from(afterBytes));
+  if (after.signature) fail("signature remains after normalization");
+  if (before.signature && (before.ncmds !== after.ncmds + 1 || before.sizeofcmds !== after.sizeofcmds + 16)) fail("signature removal changed Mach-O command layout");
+  if (before.signature) {
+    const beforeLinkeditEnd = before.linkedit.fileoff + before.linkedit.filesize;
+    const afterLinkeditEnd = after.linkedit.fileoff + after.linkedit.filesize;
+    const removedPadding = BigInt(before.signature.offset) - afterLinkeditEnd;
+    if (beforeLinkeditEnd !== BigInt(before.signature.offset + before.signature.size)
+      || after.linkedit.fileoff !== before.linkedit.fileoff
+      || afterLinkeditEnd > BigInt(before.signature.offset)
+      || removedPadding < 0n || removedPadding > 15n
+      || BigInt(after.bytes.length) !== afterLinkeditEnd) {
+      fail("code signature is outside trailing __LINKEDIT data");
+    }
+    const start = Number(afterLinkeditEnd);
+    const end = before.signature.offset;
+    if (before.bytes.subarray(start, end).some((byte) => byte !== 0)) fail("nonzero alignment padding before code signature");
+  }
+  assertOnlySignatureDiffers(before, after);
+  if (before.normalizedCommands.length !== after.normalizedCommands.length
+    || before.normalizedCommands.some((command, index) => !command.equals(after.normalizedCommands[index]))) {
+    fail("signature removal changed non-signature load commands");
+  }
+  const pageSize = before.cpuType === CPU_TYPE_ARM64 ? 16n * 1024n : 4096n;
+  const roundedSize = ((after.linkedit.filesize + pageSize - 1n) / pageSize) * pageSize;
+  if (after.linkedit.vmsize < roundedSize) fail("invalid __LINKEDIT virtual size");
+  after.bytes.writeBigUInt64LE(roundedSize, after.linkedit.vmsizeOffset);
+  return createHash("sha256").update(after.bytes).digest("hex");
+}
+
+/** Default signature removal: `/usr/bin/codesign --remove-signature <copy>` (macOS only). */
+function removeSignatureWithCodesign(copy) {
+  const result = spawnSync("/usr/bin/codesign", ["--remove-signature", copy], { stdio: "ignore", timeout: 15_000, windowsHide: true });
+  if (result.error || result.status !== 0) throw new ApprovalHashError("APPROVAL_HASH_CODESIGN_FAILED", `backend integrity: codesign normalization failed (${result.error?.message ?? result.status})`);
+}
+
+/**
+ * The approval digest of `file` under `algorithm`. `removeSignature(copyPath)` is injectable for tests and for hosts that
+ * strip signatures another way; the default needs macOS. The input file is never modified.
+ */
+export function approvalDigest(file, algorithm, { platform = process.platform, removeSignature = removeSignatureWithCodesign, tmpdir = os.tmpdir() } = {}) {
+  if (algorithm === APPROVAL_RAW_SHA256) return createHash("sha256").update(readFileSync(file)).digest("hex");
+  if (algorithm !== APPROVAL_MACHO_STRIP_LINKEDIT_V1) throw new ApprovalHashError("APPROVAL_HASH_ALGORITHM_UNKNOWN", `unknown approval hash algorithm ${JSON.stringify(algorithm)} (supported: ${APPROVAL_ALGORITHMS.join(", ")})`);
+  if (platform !== "darwin") throw new ApprovalHashError("APPROVAL_HASH_HOST_UNSUPPORTED", `${APPROVAL_MACHO_STRIP_LINKEDIT_V1} needs macOS (codesign); this host is ${platform}`);
+  if (!lstatSync(file).isFile()) fail("expected regular Mach-O file");
+  const original = readFileSync(file);
+  const before = parseMachO(original);
+  const directory = mkdtempSync(path.join(tmpdir, `rightkit-macho-${process.pid}-${randomBytes(8).toString("hex")}-`), { mode: 0o700 });
+  const copy = path.join(directory, "binary");
+  try {
+    // The copy is written from the captured bytes, never re-read from the path, so the validated snapshot is the one stripped.
+    writeFileSync(copy, original, { mode: 0o700 });
+    chmodSync(copy, 0o700);
+    if (before.signature) removeSignature(copy);
+    return machoApprovalDigest(original, readFileSync(copy));
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+}

package/macos-signing-session.mjs

@@ -5,7 +5,7 @@ import { spawnSync } from "./background-process.mjs";
 
 import { requestSigningAgentSync, validateNotaryAgentReport } from "./signing-agent-client.mjs";
 import { installSigningAgent, requireMacGuiSession } from "./signing-agent-install.mjs";
-import { signingAgentPaths, defaultSigningRoots, ensurePrivateDirectory, privatePath, within, NOTARIZATION_TIMEOUT_MS, MAX_NOTARIZATION_TIMEOUT_MS } from "./rightkit-signing-agent.mjs";
+import { signingAgentPaths, defaultSigningRoots, ensurePrivateDirectory, privatePath, within, NOTARIZATION_TIMEOUT_MS, MAX_NOTARIZATION_TIMEOUT_MS, AGENT_IDENTIFIER_PATTERN, CODESIGN_IDENTIFIER_SCHEMA } from "./rightkit-signing-agent.mjs";
 import { refuseManagedEnvSecrets } from "./managed-host-secrets.mjs";
 
 export class MacSigningSessionError extends Error {
@@ -48,11 +48,13 @@ export function codesignAgentItems(commands) {
       else if (option === "--timestamp" && item.timestamp === undefined) item.timestamp = true;
       else if (option === "--options" && args[i + 1] === "runtime" && item.runtime === undefined) { item.runtime = true; i++; }
       else if (option === "--sign" && item.identity === undefined) item.identity = args[++i];
+      else if (option === "--identifier" && item.identifier === undefined) item.identifier = args[++i];
       else if (option === "--entitlements" && item.entitlements === undefined) item.entitlements = args[++i];
       else if (option === "--preserve-metadata=entitlements" && item.preserveEntitlements === undefined) item.preserveEntitlements = true;
       else throw new TypeError(`Unsupported agent codesign option: ${option}`);
     }
     item.path = args.at(-1);
+    if (item.identifier !== undefined && !AGENT_IDENTIFIER_PATTERN.test(item.identifier)) throw new TypeError("Agent signing requires a reverse-DNS codesign identifier");
     if (!item.identity || item.identity === "-" || !path.isAbsolute(item.path ?? "")
       || (item.entitlements !== undefined && !path.isAbsolute(item.entitlements))) throw new TypeError("Agent signing requires real identity & absolute paths");
     return item;
@@ -76,6 +78,8 @@ export function runMacGuiSigning({ kind, commands, files, cwd = process.cwd(), e
   try {
     if (kind === "codesign") {
       plan.items = codesignAgentItems(commands);
+      // Only a request that carries a typed identifier uses schema 2; every other codesign request stays schema 1.
+      if (plan.items.some((item) => item.identifier !== undefined)) plan.schema = CODESIGN_IDENTIFIER_SCHEMA;
       // Development signing generates entitlements in TMPDIR. Copy only those
       // plist bytes into managed private staging, never broaden signing roots.
       for (const item of plan.items) {
@@ -99,7 +103,13 @@ export function runMacGuiSigning({ kind, commands, files, cwd = process.cwd(), e
     let report;
     try { report = request(plan, clientOptions); }
     catch (error) {
-      if (error.code !== "MAC_SIGNING_AGENT_UNAVAILABLE") throw error;
+      let missing = error.code === "MAC_SIGNING_AGENT_UNAVAILABLE";
+      // An installed agent that predates typed identifiers refuses schema 2: upgrade it once, never loop on a rejected request.
+      if (!missing && plan.schema === CODESIGN_IDENTIFIER_SCHEMA && error.code === "MAC_SIGNING_AGENT_PROTOCOL") {
+        const health = request({ schema: 1, type: "health" }, { home, timeoutMs: 1500 });
+        missing = !health.capabilities?.includes("codesign-identifier");
+      }
+      if (!missing) throw error;
       requireMacGuiSession({ run, uid });
       install({ home, username, uid, run, io, managedRoot: env.RIGHTKIT_MANAGED_ROOT });
       report = request(plan, clientOptions); // One install attempt, one retry.

package/managed-cargo.mjs

@@ -3,7 +3,7 @@ import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";
-import { spawnSync } from "./background-process.mjs";
+import { spawn as spawnProcess, spawnSync } from "./background-process.mjs";
 
 export function managedRuntimeClient(env = process.env, platform = process.platform, exists = existsSync) {
   const roots = managedControlCandidates({ env, platform });
@@ -72,3 +72,51 @@ export function runCargoSync(args, options = {}, { platform = process.platform,
 function unavailable(message) {
   return { status: null, stdout: "", stderr: message, error: Object.assign(new Error(message), { code: 'RK_BROKER_UNAVAILABLE' }) };
 }
+
+/**
+ * Async `spawnSync` look-alike for the batch publisher: runs the command through the release spawn boundary
+ * (background-process.mjs), collects stdout and stderr, and resolves `{ status, signal, stdout, stderr, error }`.
+ * It never rejects: a spawn failure, a timeout or an exceeded `maxBuffer` resolves with `error` set, which is
+ * exactly how callers already read a failed `spawnSync`.
+ */
+export function spawnCollect(command, args, options = {}, { spawnAsync = spawnProcess } = {}) {
+  const { timeout, maxBuffer = 512 * 1024 * 1024, encoding: _encoding, stdio: _stdio, ...rest } = options;
+  return new Promise((resolve) => {
+    let child;
+    try { child = spawnAsync(command, args, { ...rest, stdio: ["ignore", "pipe", "pipe"] }); } catch (error) { resolve({ status: null, signal: null, stdout: "", stderr: "", error }); return; }
+    const out = []; const err = [];
+    let size = 0; let settled = false; let timer; let failure;
+    const finish = (result) => { if (settled) return; settled = true; clearTimeout(timer); resolve(result); };
+    const take = (chunks) => (chunk) => {
+      size += chunk.length;
+      if (size > maxBuffer) { failure ??= new Error(`output exceeded maxBuffer (${maxBuffer} bytes)`); child.kill("SIGKILL"); return; }
+      chunks.push(chunk);
+    };
+    child.stdout.on("data", take(out));
+    child.stderr.on("data", take(err));
+    child.on("error", (error) => finish({ status: null, signal: null, stdout: "", stderr: "", error }));
+    child.on("close", (status, signal) => finish({
+      status, signal, stdout: Buffer.concat(out).toString("utf8"), stderr: Buffer.concat(err).toString("utf8"), error: failure,
+    }));
+    if (timeout) timer = setTimeout(() => { failure ??= new Error(`timed out after ${timeout}ms`); child.kill("SIGKILL"); }, timeout);
+  });
+}
+
+/**
+ * Async twin of `runCargoSync`: the same client, broker-socket and darwin-never-direct selection (it asks
+ * `runCargoSync` to choose, with a spawn that only records the invocation), then runs the chosen invocation
+ * without blocking the event loop so independent crates can publish concurrently. The broker still
+ * serializes the builds themselves.
+ */
+export async function runCargoAsync(args, options = {}, deps = {}) {
+  const { spawnAsync = spawnCollect, ...syncDeps } = deps;
+  let chosen;
+  const probe = runCargoSync(args, options, { ...syncDeps, spawn: (command, commandArgs, commandOptions) => { chosen = { command, args: commandArgs, options: commandOptions }; return { status: 0, stdout: "", stderr: "" }; } });
+  if (!chosen) return probe;
+  const result = await spawnAsync(chosen.command, chosen.args, chosen.options);
+  const platform = syncDeps.platform ?? process.platform;
+  if (platform === 'darwin' && result.status !== 0 && /RK_BROKER_UNAVAILABLE|RightKit broker (?:unavailable|endpoint is not configured)/i.test(String(result.stderr ?? ''))) {
+    return { ...result, error: unavailable(String(result.stderr).trim()).error };
+  }
+  return result;
+}

package/media-sidecar.mjs

@@ -3,6 +3,7 @@
 //   targets.mac.mediaSidecar = {
 //     arch: "aarch64",                       // catalog arch (default: build host); one arch per build
 //     variant: "decode",                     // catalog variant (default "decode")
+//     variants: { ffmpeg: "export-ass" },    // optional per-tool variant override (a tool not named uses `variant`)
 //     tools: ["ffmpeg", "ffprobe"],          // default both
 //     stageDir: "src-tauri/binaries",        // Tauri externalBin directory (default)
 //     bundleDir: "Contents/MacOS",           // mac only: where Tauri puts externalBin (or "Contents/Resources")
@@ -26,7 +27,7 @@ export const MEDIA_SIDECAR_TOOLS = Object.freeze(["ffmpeg", "ffprobe"]);
 const PLATFORM_OS = Object.freeze({ mac: "macos", win: "windows", linux: "linux" });
 const ARCHES = new Set(["aarch64", "x86_64"]);
 const SHA256 = /^[0-9a-f]{64}$/;
-const CONFIG_KEYS = new Set(["arch", "variant", "tools", "stageDir", "bundleDir", "notices", "catalog", "stage"]);
+const CONFIG_KEYS = new Set(["arch", "variant", "variants", "tools", "stageDir", "bundleDir", "notices", "catalog", "stage"]);
 const BUNDLE_DIRS = new Set(["Contents/MacOS", "Contents/Resources"]);
 
 const invalid = (code, message) => Object.assign(new Error(message), { code });
@@ -87,6 +88,18 @@ export function validateMediaSidecarConfig(raw, { platform, hostArch = hostCatal
   if (!Array.isArray(tools) || !tools.length || new Set(tools).size !== tools.length || tools.some((tool) => !MEDIA_SIDECAR_TOOLS.includes(tool))) {
     errors.push(`tools must be a non-empty list without duplicates drawn from ${MEDIA_SIDECAR_TOOLS.join(", ")}`);
   }
+  // One entry may mix variants (for example the export-ass ffmpeg with the decode ffprobe): `variants` maps a tool to its variant.
+  let variants;
+  if (raw.variants !== undefined) {
+    if (!isObject(raw.variants) || !Object.keys(raw.variants).length) errors.push("variants must be an object mapping a tool to a catalog variant slug");
+    else {
+      for (const [tool, slug] of Object.entries(raw.variants)) {
+        if (!MEDIA_SIDECAR_TOOLS.includes(tool) || (Array.isArray(tools) && !tools.includes(tool))) errors.push(`variants.${tool}: not one of the configured tools`);
+        if (typeof slug !== "string" || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug)) errors.push(`variants.${tool} must be a catalog variant slug: ${JSON.stringify(slug)}`);
+      }
+      variants = { ...raw.variants };
+    }
+  }
   const stageDir = relativePath(raw.stageDir ?? "src-tauri/binaries", "stageDir");
   let bundleDir;
   if (os === "macos") {
@@ -109,7 +122,7 @@ export function validateMediaSidecarConfig(raw, { platform, hostArch = hostCatal
     else stage = raw.stage;
   }
   if (errors.length) throw invalid("MEDIA_SIDECAR_CONFIG_INVALID", `invalid mediaSidecar configuration:\n${errors.map((line) => `- ${line}`).join("\n")}`);
-  return { os, arch, variant, tools: [...tools], stageDir, ...(bundleDir ? { bundleDir } : {}), notices, ...(catalog ? { catalog } : {}), ...(stage ? { stage } : {}) };
+  return { os, arch, variant, ...(variants ? { variants } : {}), tools: [...tools], stageDir, ...(bundleDir ? { bundleDir } : {}), notices, ...(catalog ? { catalog } : {}), ...(stage ? { stage } : {}) };
 }
 
 /** `sign.nestedCode` entries for the macOS bundle: the sidecar executables, hardened runtime, no entitlements. */
@@ -126,9 +139,10 @@ export function mediaSidecarNestedCode(config) {
 export function selectSidecarRows(catalog, config) {
   if (!isObject(catalog) || !Array.isArray(catalog.artifacts)) throw invalid("MEDIA_SIDECAR_CATALOG_INVALID", "catalog has no artifacts array");
   return config.tools.map((tool) => {
-    const matches = catalog.artifacts.filter((row) => row.tool === tool && (row.variant ?? "decode") === config.variant
+    const variant = config.variants?.[tool] ?? config.variant;
+    const matches = catalog.artifacts.filter((row) => row.tool === tool && (row.variant ?? "decode") === variant
       && String(row.os).toLowerCase() === config.os && String(row.arch).toLowerCase() === config.arch);
-    const where = `${tool} ${config.variant} ${config.os}/${config.arch}`;
+    const where = `${tool} ${variant} ${config.os}/${config.arch}`;
     if (matches.length === 0) throw invalid("MEDIA_SIDECAR_NO_ROW", `the rightkit-ffmpeg catalog has no ${where} row`);
     if (matches.length > 1) throw invalid("MEDIA_SIDECAR_AMBIGUOUS_ROW", `the rightkit-ffmpeg catalog has ${matches.length} ${where} rows`);
     const [row] = matches;
@@ -152,6 +166,7 @@ export function planMediaSidecar({ config, catalog, crateDir, crateVersion, cata
     artifactId: row.id,
     version: row.version,
     contentSha256: row.contentSha256,
+    ...(config.variants ? { variant: row.variant ?? "decode" } : {}),
     stagedPath: path.resolve(root, config.stageDir, stagedFileName(row.tool, config.os, config.arch)),
     bundledName: bundledFileName(row.tool, config.os),
     ...(config.bundleDir ? { bundlePath: `${config.bundleDir}/${bundledFileName(row.tool, config.os)}` } : {}),
@@ -242,6 +257,7 @@ export function buildMediaSidecarReceipt(plan, preSign, signed, { notices = [],
         tool: file.tool,
         artifactId: file.artifactId,
         version: file.version,
+        ...(file.variant ? { variant: file.variant } : {}),
         catalogContentSha256: file.contentSha256,
         preSignSha256: file.preSignSha256,
         signedSha256: after.sha256,