@rightkit/release 0.2.172 → 0.2.174

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-package-recipe.mjs

@@ -0,0 +1,304 @@
+// Declarative macOS packaging recipe (bogusyogi/rightkit#345). A mac target that sets `macPackage` and has no
+// `prePackage` / `package` hook scripts is packaged by this module instead of a per-app mac-dmg.mjs:
+//
+//   1. universal check   every Mach-O (main executable + nested) must hold x86_64 and arm64 (macPackage.universal)
+//   2. sign nested code  Developer ID, hardened runtime, no entitlements, deepest first
+//   3. sign the app      Developer ID, hardened runtime, optional entitlements
+//   4. build the DMG     branded, from the signed app (dmg-build)
+//   5. sign the DMG      Developer ID with a secure timestamp (no hardened runtime, as for a disk image)
+//   6. notarize + staple the DMG and the app (macos-notarization), when macPackage.notarize
+//   7. updater tarball   tar.gz of the stapled app's Contents + the updater signature, when macPackage.updater
+//
+// Every external effect is injectable through `deps`; nothing here reads the host unless a default is used.
+// Fails closed: every problem throws MacPackageRecipeError, and a failure after the DMG exists removes the
+// half-processed DMG / updater files so a later seal cannot pick up an artifact that skipped a step.
+import * as nodeFs from "node:fs";
+import path from "node:path";
+import { buildDmg } from "./dmg-build.mjs";
+import { spawnSync } from "./background-process.mjs";
+import { signMacosEntries } from "./mac-sign-core.mjs";
+import { mainExecutableName } from "./mac-bundle-signing.mjs";
+import { notarizeMacosArtifact } from "./macos-notarization.mjs";
+import { resolveMacosDeveloperIdIdentity } from "./macos-signing-identity.mjs";
+import { runMacCodesignCommands, signMacUpdaterFiles } from "./macos-signing-session.mjs";
+import { discoverNestedCode } from "./swift-mac-app.mjs";
+
+/**
+ * Typed error. Codes: MAC_PACKAGE_CONFIG_INVALID, MAC_PACKAGE_HOST_UNSUPPORTED, MAC_PACKAGE_INPUT_MISSING,
+ * MAC_PACKAGE_UNIVERSAL_FAILED, MAC_PACKAGE_SIGN_FAILED, MAC_PACKAGE_DMG_FAILED, MAC_PACKAGE_NOTARIZE_FAILED,
+ * MAC_PACKAGE_UPDATER_FAILED.
+ */
+export class MacPackageRecipeError extends Error {
+  constructor(code, message, options) { super(message, options); this.name = "MacPackageRecipeError"; this.code = code; }
+}
+
+export const MAC_PACKAGE_STEPS = Object.freeze(["universal", "sign-nested", "sign-app", "dmg", "sign-dmg", "notarize", "updater"]);
+const UNIVERSAL_ARCHS = ["x86_64", "arm64"];
+const MACPACKAGE_KEYS = ["universal", "dmg", "notarize", "updater", "nested", "entitlements"];
+const DMG_KEYS = ["name", "background", "windowSize", "iconPositions"];
+const ICON_KEYS = ["app", "applications"];
+
+const invalid = (message) => new MacPackageRecipeError("MAC_PACKAGE_CONFIG_INVALID", `macPackage: ${message}`);
+const isPlainObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const rejectUnknown = (object, allowed, label) => {
+  const unknown = Object.keys(object).filter((key) => !allowed.includes(key));
+  if (unknown.length) throw invalid(`${label} has unknown key(s): ${unknown.join(", ")} (allowed: ${allowed.join(", ")})`);
+};
+const integerPair = (value, label, min) => {
+  if (!Array.isArray(value) || value.length !== 2 || value.some((n) => !Number.isInteger(n) || n < min || n > 32767)) {
+    throw invalid(`${label} must be [x, y] integers ${min}..32767`);
+  }
+  return [...value];
+};
+const requireBoolean = (value, label) => {
+  if (typeof value !== "boolean") throw invalid(`${label} is required and must be true or false`);
+  return value;
+};
+
+/** A bundle-relative glob: forward slashes only, no `..`, no absolute path, only `*`, `**` and `?` wildcards. */
+function validateGlob(pattern, label) {
+  if (typeof pattern !== "string" || !pattern.trim()) throw invalid(`${label} must be a non-empty string`);
+  if (pattern.startsWith("/") || /^[A-Za-z]:/.test(pattern) || pattern.includes("\\")) throw invalid(`${label} must be a bundle-relative path with forward slashes: ${pattern}`);
+  if (/[[\]{}()!]/.test(pattern)) throw invalid(`${label} supports only *, ** and ? wildcards: ${pattern}`);
+  const segments = pattern.split("/");
+  if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) throw invalid(`${label} must not contain empty, '.' or '..' segments: ${pattern}`);
+  if (segments.some((segment) => segment.includes("**") && segment !== "**")) throw invalid(`${label}: '**' must be a whole path segment: ${pattern}`);
+  return pattern;
+}
+
+/** Strictly validate and normalize a `macPackage` value. Unknown keys, wrong types and missing fields throw. */
+export function validateMacPackageConfig(macPackage) {
+  if (!isPlainObject(macPackage)) throw invalid("must be an object");
+  rejectUnknown(macPackage, MACPACKAGE_KEYS, "macPackage");
+  const universal = macPackage.universal === undefined ? false : requireBoolean(macPackage.universal, "universal");
+  const notarize = requireBoolean(macPackage.notarize, "notarize");
+  const updater = requireBoolean(macPackage.updater, "updater");
+  const dmg = macPackage.dmg;
+  if (!isPlainObject(dmg)) throw invalid("dmg is required and must be an object");
+  rejectUnknown(dmg, DMG_KEYS, "dmg");
+  if (typeof dmg.name !== "string" || !dmg.name.trim() || /[\0\r\n/:]/.test(dmg.name) || Buffer.byteLength(dmg.name) > 255) {
+    throw invalid("dmg.name must be a non-empty volume name without NUL, CR, LF, '/' or ':'");
+  }
+  const normalized = { name: dmg.name };
+  if (dmg.background !== undefined) {
+    if (typeof dmg.background !== "string" || !/\.(png|tiff?)$/i.test(dmg.background)) throw invalid("dmg.background must be a path to a PNG or TIFF file");
+    normalized.background = dmg.background;
+  }
+  if (dmg.windowSize !== undefined) normalized.windowSize = integerPair(dmg.windowSize, "dmg.windowSize", 1);
+  if (dmg.iconPositions !== undefined) {
+    if (!isPlainObject(dmg.iconPositions)) throw invalid("dmg.iconPositions must be an object with app and/or applications");
+    rejectUnknown(dmg.iconPositions, ICON_KEYS, "dmg.iconPositions");
+    normalized.iconPositions = Object.fromEntries(Object.entries(dmg.iconPositions).map(([key, value]) => [key, integerPair(value, `dmg.iconPositions.${key}`, 0)]));
+  }
+  let nested = [];
+  if (macPackage.nested !== undefined) {
+    if (!Array.isArray(macPackage.nested) || !macPackage.nested.length) throw invalid("nested must be a non-empty array of bundle-relative globs");
+    nested = macPackage.nested.map((pattern, index) => validateGlob(pattern, `nested[${index}]`));
+    if (new Set(nested).size !== nested.length) throw invalid("nested globs must be unique");
+  }
+  if (macPackage.entitlements !== undefined && (typeof macPackage.entitlements !== "string" || !macPackage.entitlements.trim())) throw invalid("entitlements must be a path string");
+  return { universal, dmg: normalized, notarize, updater, nested, ...(macPackage.entitlements ? { entitlements: macPackage.entitlements } : {}) };
+}
+
+/**
+ * Validate the mac target around `macPackage`: the declarative recipe and the hook scripts are mutually exclusive, and the
+ * app / DMG paths come from the existing `notarize.app` and `notarize.file` fields so there is one source of truth.
+ */
+export function validateMacPackageTarget(target) {
+  if (!isPlainObject(target)) throw invalid("the mac target must be an object");
+  if (target.prePackage !== undefined || target.package !== undefined) throw invalid("a target with macPackage must not also declare prePackage or package; delete the hook scripts");
+  if (target.dmg !== undefined) throw invalid("a target with macPackage must not also declare targets.mac.dmg; use macPackage.dmg");
+  const recipe = validateMacPackageConfig(target.macPackage);
+  const app = target.notarize?.app;
+  const file = target.notarize?.file;
+  if (typeof app !== "string" || !/\.app\/?$/.test(app)) throw invalid("notarize.app must name the .app bundle the recipe signs and packs");
+  if (typeof file !== "string" || !/\.dmg$/i.test(file)) throw invalid("notarize.file must name the .dmg the recipe produces");
+  return { recipe, app, dmgFile: file };
+}
+
+/** Bundle-relative glob to RegExp; `**` spans path segments, `*` and `?` stay inside one. */
+export function globToRegExp(pattern) {
+  const segments = pattern.split("/");
+  const body = segments.map((segment, index) => {
+    const last = index === segments.length - 1;
+    if (segment === "**") return last ? ".+" : "(?:[^/]+/)*";
+    return `${segment.replace(/[.+^$|\\]/g, "\\$&").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]")}${last ? "" : "/"}`;
+  }).join("");
+  return new RegExp(`^${body}$`);
+}
+
+function listTree(root, fs) {
+  const found = [];
+  const walk = (dir, prefix) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+      found.push(relative);
+      if (entry.isDirectory() && !entry.isSymbolicLink()) walk(path.join(dir, entry.name), relative);
+    }
+  };
+  walk(root, "");
+  return found;
+}
+
+const depth = (file) => file.split(/[\\/]/).length;
+const tail = (text, lines = 20) => String(text ?? "").split(/\r?\n/).slice(-lines).join("\n");
+
+const defaultInspect = (cmd, args) => {
+  const result = spawnSync(cmd, args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+  const output = `${result.stdout ?? ""}\n${result.stderr ?? ""}`;
+  if (result.error || result.status !== 0) throw new Error(`${cmd} ${args.join(" ")} failed: ${output.trim() || result.error?.message}`);
+  return output;
+};
+
+/**
+ * Run the declarative mac package recipe. Returns { steps, app, dmg, updater, receipt, signing } where `steps` lists the
+ * steps that actually ran, in order. Throws MacPackageRecipeError on the first failure.
+ *
+ * deps (all optional): platform, env, fs, resolveArtifact(root, p), resolveIdentity({env}), signOne(codesignArgs),
+ * inspect(cmd, args) -> output, evidence(file), hashFile(file), discover(app, mainName), mainName(app),
+ * listFiles(dir) -> bundle-relative posix paths, buildDmg(options), notarize(options), run(cmd, args, opts),
+ * signUpdater(files, options), receiptPath, log(event).
+ */
+export function runMacPackageRecipe({ appRoot, config = {}, target, deps = {} }) {
+  const { recipe, app: declaredApp, dmgFile } = validateMacPackageTarget(target);
+  const {
+    platform = process.platform, env = process.env, fs = nodeFs,
+    resolveArtifact = (root, p) => path.resolve(root, p),
+    resolveIdentity = resolveMacosDeveloperIdIdentity,
+    signOne = (codesignArgs) => runMacCodesignCommands([codesignArgs], { env })[0],
+    inspect = defaultInspect, evidence, hashFile,
+    discover = discoverNestedCode, mainName = mainExecutableName,
+    listFiles = (dir) => listTree(dir, fs),
+    buildDmg: build = buildDmg, notarize = notarizeMacosArtifact,
+    run = spawnSync, signUpdater = (files, options) => signMacUpdaterFiles(files, options),
+    log = () => {},
+  } = deps;
+  const appName = config.app ?? path.basename(appRoot ?? ".");
+  if (typeof appRoot !== "string" || !path.isAbsolute(appRoot)) throw invalid("appRoot must be an absolute path");
+  if (platform !== "darwin") throw new MacPackageRecipeError("MAC_PACKAGE_HOST_UNSUPPORTED", `macPackage signs and notarizes on macOS only (host: ${platform})`);
+
+  const app = path.resolve(resolveArtifact(appRoot, declaredApp));
+  const dmg = path.resolve(resolveArtifact(appRoot, dmgFile));
+  const updater = `${app}.tar.gz`;
+  const receiptPath = deps.receiptPath ?? path.join(path.resolve(env.RIGHT_RELEASE_STATE_ROOT ?? path.join(appRoot, ".right-release"), "receipts"), `${appName}-mac-notarization.json`);
+  const missing = (what, file) => new MacPackageRecipeError("MAC_PACKAGE_INPUT_MISSING", `${what} not found: ${file}`);
+  const wrap = (code, step, error) => (error instanceof MacPackageRecipeError ? error
+    : new MacPackageRecipeError(code, `macPackage ${step} failed: ${error?.message ?? error}`, { cause: error }));
+
+  // Resolve every input before any effect so a typo cannot leave a half-signed app.
+  if (!fs.existsSync(app)) throw missing("app bundle", app);
+  const infoPlist = path.join(app, "Contents", "Info.plist");
+  if (!fs.existsSync(infoPlist)) throw missing("Contents/Info.plist in the app bundle", infoPlist);
+  const entitlements = recipe.entitlements ? path.resolve(appRoot, recipe.entitlements) : undefined;
+  if (entitlements && !fs.existsSync(entitlements)) throw missing("entitlements file", entitlements);
+  const background = recipe.dmg.background ? path.resolve(appRoot, recipe.dmg.background) : undefined;
+  if (background && !fs.existsSync(background)) throw missing("dmg.background file", background);
+
+  const executable = mainName(app);
+  const mainBinary = path.join(app, "Contents", "MacOS", executable);
+  const nestedSet = new Set(discover(app, executable).map((file) => path.resolve(file)));
+  if (recipe.nested.length) {
+    const tree = listFiles(app);
+    for (const pattern of recipe.nested) {
+      const matcher = globToRegExp(pattern);
+      const hits = tree.filter((relative) => matcher.test(relative));
+      if (!hits.length) throw new MacPackageRecipeError("MAC_PACKAGE_INPUT_MISSING", `macPackage.nested glob matched nothing inside ${path.basename(app)}: ${pattern}`);
+      for (const hit of hits) nestedSet.add(path.resolve(app, hit));
+    }
+  }
+  nestedSet.delete(mainBinary);
+  nestedSet.delete(app);
+  // Inside-out: a path nested deeper is always signed before the code that contains it.
+  const nested = [...nestedSet].sort((a, b) => depth(b) - depth(a));
+
+  const steps = [];
+  const record = (step) => { steps.push(step); log({ event: "mac-package-step", step, app: appName }); };
+  const signOptions = { signOne, inspect, ...(evidence ? { evidence } : {}), ...(hashFile ? { hashFile } : {}) };
+  let signing = [];
+  let receipt;
+  let updaterFiles = [];
+  try {
+    // 1) universal: verify every Mach-O holds both architectures. A thin slice makes the whole app Intel- or
+    //    Apple-Silicon-only, which compiles, signs and notarizes fine and then fails on half the users' Macs.
+    if (recipe.universal) {
+      const archsOf = (file) => String(inspect("lipo", ["-archs", file])).trim().split(/\s+/);
+      const assertFat = (file) => {
+        const archs = archsOf(file);
+        const lacking = UNIVERSAL_ARCHS.filter((arch) => !archs.includes(arch));
+        if (lacking.length) throw new Error(`${path.relative(app, file)} is not universal (has: ${archs.join(" ")}; missing: ${lacking.join(" ")})`);
+      };
+      try {
+        assertFat(mainBinary); // an unreadable main executable is a failure, not a skip
+        for (const file of nested) {
+          let isFile = false;
+          try { isFile = fs.statSync(file).isFile(); } catch { /* absent: signing reports it */ }
+          if (!isFile) continue; // code bundles are covered by the Mach-O files inside them
+          try { archsOf(file); } catch { continue; } // lipo rejects non-Mach-O files (scripts, resources matched by a glob)
+          assertFat(file);
+        }
+      } catch (error) { throw wrap("MAC_PACKAGE_UNIVERSAL_FAILED", "universal check", error); }
+      record("universal");
+    }
+
+    // 2-3) sign nested code, then the app. One identity for the whole run.
+    let identity;
+    try { identity = resolveIdentity({ env }); } catch (error) { throw wrap("MAC_PACKAGE_SIGN_FAILED", "identity lookup", error); }
+    if (typeof identity !== "string" || !identity.trim()) throw new MacPackageRecipeError("MAC_PACKAGE_SIGN_FAILED", "macPackage signing identity is empty");
+    if (nested.length) {
+      try { signing.push(...signMacosEntries(nested.map((file) => ({ file, hardenedRuntime: true, options: [] })), { identity, ...signOptions })); }
+      catch (error) { throw wrap("MAC_PACKAGE_SIGN_FAILED", "nested code signing", error); }
+      record("sign-nested");
+    }
+    try { signing.push(...signMacosEntries([{ file: app, hardenedRuntime: true, options: [], ...(entitlements ? { entitlements } : {}) }], { identity, ...signOptions })); }
+    catch (error) { throw wrap("MAC_PACKAGE_SIGN_FAILED", "app signing", error); }
+    record("sign-app");
+
+    // 4) branded DMG from the signed app.
+    fs.rmSync(dmg, { force: true });
+    try {
+      build({
+        app, out: dmg, volname: recipe.dmg.name,
+        ...(background ? { background } : {}),
+        ...(recipe.dmg.windowSize ? { window: recipe.dmg.windowSize } : {}),
+        ...(recipe.dmg.iconPositions?.app ? { appPosition: recipe.dmg.iconPositions.app } : {}),
+        ...(recipe.dmg.iconPositions?.applications ? { applicationsPosition: recipe.dmg.iconPositions.applications } : {}),
+      });
+    } catch (error) { throw wrap("MAC_PACKAGE_DMG_FAILED", "DMG build", error); }
+    if (!fs.existsSync(dmg)) throw new MacPackageRecipeError("MAC_PACKAGE_DMG_FAILED", `DMG build reported success but ${dmg} does not exist`);
+    record("dmg");
+
+    // 5) sign the DMG: secure timestamp, no hardened runtime (a disk image has none).
+    try { signing.push(...signMacosEntries([{ file: dmg, hardenedRuntime: false, options: [] }], { identity, ...signOptions })); }
+    catch (error) { throw wrap("MAC_PACKAGE_SIGN_FAILED", "DMG signing", error); }
+    record("sign-dmg");
+
+    // 6) notarize + staple. The DMG submission covers the app inside it; the app is stapled too so the updater tarball carries the ticket.
+    if (recipe.notarize) {
+      try { receipt = notarize({ archive: dmg, app, receiptPath, env, run }); }
+      catch (error) { throw wrap("MAC_PACKAGE_NOTARIZE_FAILED", "notarization", error); }
+      if (!receipt || receipt.notarization?.status !== "Accepted") throw new MacPackageRecipeError("MAC_PACKAGE_NOTARIZE_FAILED", `macPackage notarization did not report Accepted for ${dmg}`);
+      record("notarize");
+    }
+
+    // 7) updater tarball from the final (stapled) app, then its signature.
+    if (recipe.updater) {
+      updaterFiles = [updater, `${updater}.sig`];
+      for (const file of updaterFiles) fs.rmSync(file, { force: true });
+      // bsdtar otherwise serializes extended attributes as AppleDouble `._*` entries, which Tauri's extractor writes
+      // into the bundle and invalidates the seal. The explicit App.app/ directory entry is omitted for the same extractor.
+      let packed;
+      try { packed = run("tar", ["-czf", updater, "-C", path.dirname(app), path.join(path.basename(app), "Contents")], { cwd: appRoot, env: { ...env, COPYFILE_DISABLE: "1" }, encoding: "utf8", stdio: "pipe" }); }
+      catch (error) { throw wrap("MAC_PACKAGE_UPDATER_FAILED", "updater tar", error); }
+      if (!packed || packed.error || packed.status !== 0) throw new MacPackageRecipeError("MAC_PACKAGE_UPDATER_FAILED", `macPackage updater tar failed: ${packed?.error?.message ?? (tail(packed?.stderr) || packed?.status)}`);
+      try { signUpdater([updater], { cwd: appRoot, env }); }
+      catch (error) { throw wrap("MAC_PACKAGE_UPDATER_FAILED", "updater signing", error); }
+      for (const file of updaterFiles) if (!fs.existsSync(file)) throw missing("updater artifact", file);
+      record("updater");
+    }
+  } catch (error) {
+    // Fail closed: never leave a DMG or updater that skipped a step where the seal can find it.
+    for (const file of [dmg, ...updaterFiles]) { try { fs.rmSync(file, { force: true }); } catch { /* best effort */ } }
+    throw error;
+  }
+  return { steps, app, dmg, updater: recipe.updater ? updater : null, receipt: receipt ?? null, receiptPath: receipt ? receiptPath : null, signing };
+}

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/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/media-sidecar.mjs

@@ -187,7 +187,7 @@ export function sourceOfferText({ rows, contact, crateVersion }) {
     "The licence text and build notes are in this folder. You may replace these programs with your own build of the same source.",
     "",
     `Source code and build recipe: ${rows[0].attribution.sourceUrl}`,
-    `Build recipes, pinned sources and notes: https://github.com/Orthic-Labs/rightkit/tree/main/crates/rightkit-ffmpeg${crateVersion ? ` (crate rightkit-ffmpeg ${crateVersion}, published on crates.io)` : ""}`,
+    `Build recipes, pinned sources and notes: https://github.com/bogusyogi/rightkit/tree/main/crates/rightkit-ffmpeg${crateVersion ? ` (crate rightkit-ffmpeg ${crateVersion}, published on crates.io)` : ""}`,
     `To request the corresponding source on physical media, or if a link is unavailable, write to: ${contact}`,
     "",
     "Programs shipped",