@rightkit/release 0.2.174 → 0.3.0

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/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,

package/mirror-root-artifact.mjs

@@ -1,11 +1,24 @@
 #!/usr/bin/env node
-import { copyFileSync, lstatSync, mkdirSync, realpathSync, renameSync, rmSync, statSync } from "node:fs";
+// Two forms:
+//   right-release mirror-root-artifact --file <artifact> --package-root <dir> [--name <filename>]
+//   right-release mirror-root-artifact --config <right-release.config.mjs> --platform mac|win [--package-root <dir>]
+// The config form mirrors every entry of `targets.<platform>.mirror`, a list of `"<app-relative file>"` or
+// `{ file, name?, pruneSuffix? }`. `pruneSuffix` (for example "-setup.exe") then removes the other files with that suffix
+// from the managed directory, so it holds exactly the current artifact. Run it as `targets.<platform>.postSign`.
+// Output goes only to RIGHT_RELEASE_ARTIFACT_DIR (outside the repository); it never writes into the repository root.
+import { copyFileSync, lstatSync, mkdirSync, readdirSync, realpathSync, renameSync, rmSync, statSync } from "node:fs";
 import { execFileSync } from "./background-process.mjs";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 
 const args = parseArgs(process.argv.slice(2));
-if (!args.file || !args.packageRoot) {
-  console.error("Usage: right-release mirror-root-artifact --file <artifact> --package-root <dir> [--name <filename>]");
+const usage = "Usage: right-release mirror-root-artifact (--file <artifact> --package-root <dir> [--name <filename>] | --config <file> --platform mac|win [--package-root <dir>])";
+if (!args.config && (!args.file || !args.packageRoot)) {
+  console.error(usage);
+  process.exit(2);
+}
+if (args.config && (!args.platform || args.file)) {
+  console.error(usage);
   process.exit(2);
 }
 if (!process.env.RIGHT_RELEASE_ARTIFACT_DIR) {
@@ -13,33 +26,68 @@ if (!process.env.RIGHT_RELEASE_ARTIFACT_DIR) {
   process.exit(2);
 }
 
-const packageRoot = realpathSync(path.resolve(args.packageRoot));
-const source = path.resolve(packageRoot, args.file);
-const name = args.name || path.basename(source);
+let entries;
+let rootArg = args.packageRoot;
+if (args.config) {
+  const configPath = path.resolve(args.config);
+  const loaded = await import(pathToFileURL(configPath).href);
+  const config = loaded.default ?? loaded.config ?? loaded;
+  const declared = config?.targets?.[args.platform]?.mirror;
+  if (!Array.isArray(declared) || declared.length === 0) {
+    console.error(`right-release mirror-root-artifact: targets.${args.platform}.mirror declares no files in ${args.config}`);
+    process.exit(2);
+  }
+  entries = declared.map((item) => (typeof item === "string" ? { file: item } : item));
+  for (const entry of entries) {
+    const unknown = entry && typeof entry === "object" ? Object.keys(entry).filter((key) => !["file", "name", "pruneSuffix"].includes(key)) : ["(not an object)"];
+    if (typeof entry?.file !== "string" || !entry.file.trim() || unknown.length || path.isAbsolute(entry.file) || entry.file.replaceAll("\\", "/").split("/").includes("..")) {
+      console.error(`right-release mirror-root-artifact: each mirror entry is an app-relative file or { file, name?, pruneSuffix? }: ${JSON.stringify(entry)}`);
+      process.exit(2);
+    }
+  }
+  rootArg ??= path.dirname(configPath);
+} else {
+  entries = [{ file: args.file, name: args.name }];
+}
+
+const packageRoot = realpathSync(path.resolve(rootArg));
 const managedOutput = path.resolve(process.env.RIGHT_RELEASE_ARTIFACT_DIR);
 const repoRoot = path.resolve(git(packageRoot, "rev-parse", "--show-toplevel"));
 if (inside(managedOutput, repoRoot)) {
   console.error(`right-release mirror-root-artifact: managed output must be outside repository: ${managedOutput}`);
   process.exit(2);
 }
-if (name !== path.basename(name) || !/^[A-Za-z0-9][A-Za-z0-9._+-]{0,159}$/.test(name)) {
-  console.error(`right-release mirror-root-artifact: unsafe artifact name: ${name}`);
-  process.exit(2);
-}
-assertSafePath(source);
-if (!statSync(source).isFile()) {
-  console.error(`right-release mirror-root-artifact: source is not a regular file: ${source}`);
-  process.exit(2);
-}
-const destinations = new Set([path.join(managedOutput, name)]);
+const safeName = (name) => name === path.basename(name) && /^[A-Za-z0-9][A-Za-z0-9._+-]{0,159}$/.test(name);
 
-for (const destination of destinations) {
-  if (path.resolve(destination) === source) continue;
-  atomicCopy(source, destination);
+for (const entry of entries) {
+  const source = path.resolve(packageRoot, entry.file);
+  const name = entry.name || path.basename(source);
+  if (!safeName(name)) {
+    console.error(`right-release mirror-root-artifact: unsafe artifact name: ${name}`);
+    process.exit(2);
+  }
+  if (entry.pruneSuffix !== undefined && (typeof entry.pruneSuffix !== "string" || !/^[A-Za-z0-9._+-]{1,40}$/.test(entry.pruneSuffix) || !name.endsWith(entry.pruneSuffix))) {
+    console.error(`right-release mirror-root-artifact: pruneSuffix must be a plain suffix of the artifact name: ${entry.pruneSuffix}`);
+    process.exit(2);
+  }
+  assertSafePath(source);
+  if (!statSync(source).isFile()) {
+    console.error(`right-release mirror-root-artifact: source is not a regular file: ${source}`);
+    process.exit(2);
+  }
+  const destination = path.join(managedOutput, name);
+  if (path.resolve(destination) !== source) atomicCopy(source, destination);
+  if (entry.pruneSuffix) {
+    for (const stale of readdirSync(managedOutput)) {
+      if (stale !== name && stale.endsWith(entry.pruneSuffix) && safeName(stale)) {
+        assertSafePath(path.join(managedOutput, stale));
+        rmSync(path.join(managedOutput, stale), { force: true });
+      }
+    }
+  }
+  console.log(`right-release: managed artifact -> ${destination}`);
 }
 
-console.log(`right-release: managed artifact -> ${[...destinations][0]}`);
-
 function git(cwd, ...commandArgs) {
   return execFileSync("git", commandArgs, { cwd, encoding: "utf8" }).trim();
 }

package/npm-license-notices.mjs

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+// `right-release license-notices npm [--config <file>] [--output <file>] [--product-name <name>] [--check]`: writes the
+// third-party npm license appendix (one HTML file) for an app's production dependency closure, from
+// `pnpm licenses list --prod --json`, the installed packages' own LICENSE / COPYING / NOTICE files, and the lockfile hash.
+//
+//   legal: { npmNotices: { output: "legal/THIRD_PARTY_NPM_LICENSES.html", productName: "ViewRight", exclude: ["@rightkit/"] } }
+//
+// `output` and `productName` may also come from `--output` / `--product-name`. `exclude` is a list of package-name prefixes left
+// out (default `["@rightkit/"]`). A package that ships no license file gets the standard published text for its declared SPDX
+// license (MIT or ISC), labelled as a fallback; any other license without a file is an error, never invented text.
+// The page records the app version, the sha256 of `pnpm-lock.yaml` and `generated-by=right-release license-notices npm`, so the
+// same inputs always produce the same bytes. `--check` writes nothing and exits 1 when the file on disk differs.
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { spawnSync } from "./background-process.mjs";
+import { CommandSpecError, loadAppConfig, relativeInside } from "./command-spec.mjs";
+
+const fail = (message) => { throw new CommandSpecError(message); };
+
+// Generic published SPDX text, used ONLY when an installed package ships no license file of its own.
+export const SPDX_FALLBACK_TEXT = {
+  MIT: `Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.`,
+  ISC: `Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.`,
+};
+
+export const escapeHtml = (value) => String(value)
+  .replaceAll("&", "&amp;")
+  .replaceAll("<", "&lt;")
+  .replaceAll(">", "&gt;")
+  .replaceAll('"', "&quot;");
+
+/** Flatten `pnpm licenses list --json` (license -> entries) into a sorted list, minus excluded name prefixes. */
+export function collectNpmPackages(groups, exclude = ["@rightkit/"]) {
+  return Object.entries(groups)
+    .flatMap(([license, entries]) => entries.map((entry) => ({ ...entry, license })))
+    .filter((entry) => !exclude.some((prefix) => entry.name.startsWith(prefix)))
+    .sort((a, b) => `${a.name}@${a.versions.join(",")}`.localeCompare(`${b.name}@${b.versions.join(",")}`));
+}
+
+/**
+ * Render the appendix. `readNames(dir)` lists a package directory and `readText(file)` reads one file (both injectable).
+ * Returns `{ html, packageCount, fallbackCount }`.
+ */
+export function renderNpmNotices({ productName, version, lockHash, packages, readNames = (dir) => readdirSync(dir), readText = (file) => readFileSync(file, "utf8") }) {
+  let fallbackCount = 0;
+  const sections = packages.map((entry) => {
+    const packageRoot = entry.paths[0];
+    const files = readNames(packageRoot).filter((name) => /^(?:license|copying|notice)(?:[._-]|$)/i.test(name)).sort();
+    let texts;
+    if (files.length) {
+      texts = files.map((name) => `<h3>${escapeHtml(name)}</h3><pre>${escapeHtml(readText(path.join(packageRoot, name)))}</pre>`).join("\n");
+    } else {
+      const fallback = SPDX_FALLBACK_TEXT[entry.license];
+      if (!fallback) {
+        fail(`${entry.name} ${entry.versions.join(", ")} has no packaged license/notice file and no SPDX fallback text for declared license "${entry.license}"; bundle the file or extend SPDX_FALLBACK_TEXT`);
+      }
+      fallbackCount += 1;
+      texts = `<h3>No packaged license file found</h3><p><em>This package's installed npm distribution does not include a LICENSE/COPYING/NOTICE file. The text below is the standard published license text for its declared SPDX license (${escapeHtml(entry.license)}), not package-specific content.</em></p><pre>${escapeHtml(fallback)}</pre>`;
+    }
+    return `<section><h2>${escapeHtml(entry.name)} ${escapeHtml(entry.versions.join(", "))}</h2><p>Declared license: ${escapeHtml(entry.license)}</p>${texts}</section>`;
+  });
+  const html = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><title>${escapeHtml(productName)} npm third-party licenses</title></head><body>
+<h1>${escapeHtml(productName)} npm third-party licenses</h1>
+<p>Build provenance: ${escapeHtml(productName)} ${escapeHtml(version)}; inputs: pnpm-lock.yaml sha256=${lockHash}; generated-by=right-release license-notices npm</p>
+${sections.join("\n")}
+</body></html>\n`;
+  return { html, packageCount: packages.length, fallbackCount };
+}
+
+/** Resolve options from config + flags. */
+export function resolveNoticeOptions(config, flags = {}) {
+  const declared = config?.legal?.npmNotices ?? {};
+  if (typeof declared !== "object" || declared === null || Array.isArray(declared)) fail("legal.npmNotices must be an object");
+  const unknown = Object.keys(declared).filter((key) => !["output", "productName", "exclude"].includes(key));
+  if (unknown.length) fail(`legal.npmNotices has unknown key(s): ${unknown.join(", ")} (allowed: output, productName, exclude)`);
+  const output = flags.output ?? declared.output;
+  const productName = flags.productName ?? declared.productName;
+  const exclude = declared.exclude ?? ["@rightkit/"];
+  if (output === undefined) fail("no output file: set legal.npmNotices.output or pass --output");
+  relativeInside(output, "legal.npmNotices.output");
+  if (typeof productName !== "string" || !productName.trim()) fail("no product name: set legal.npmNotices.productName or pass --product-name");
+  if (!Array.isArray(exclude) || exclude.some((prefix) => typeof prefix !== "string")) fail("legal.npmNotices.exclude must be a list of name prefixes");
+  if ((config?.packageManager ?? "pnpm") !== "pnpm") fail(`license-notices npm supports pnpm apps only (config.packageManager is ${config.packageManager})`);
+  return { output, productName, exclude };
+}
+
+/** Generate (or check) the appendix for the app at `appRoot`. `spawnSyncFn` is injectable. */
+export function generateNpmNotices({ appRoot, config, flags = {}, check = false, spawnSyncFn = spawnSync }) {
+  const { output, productName, exclude } = resolveNoticeOptions(config, flags);
+  const version = JSON.parse(readFileSync(path.join(appRoot, "package.json"), "utf8")).version;
+  const result = spawnSyncFn("pnpm", ["licenses", "list", "--prod", "--json"], {
+    cwd: appRoot,
+    encoding: "utf8",
+    maxBuffer: 64 * 1024 * 1024,
+    shell: process.platform === "win32",
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) fail(result.stderr || "pnpm licenses list failed");
+  const packages = collectNpmPackages(JSON.parse(result.stdout), exclude);
+  const lockHash = createHash("sha256").update(readFileSync(path.join(appRoot, "pnpm-lock.yaml"))).digest("hex");
+  const { html, packageCount, fallbackCount } = renderNpmNotices({ productName, version, lockHash, packages });
+  const target = path.join(appRoot, output);
+  if (check) {
+    const current = existsSync(target) ? readFileSync(target, "utf8") : null;
+    return { target, packageCount, fallbackCount, upToDate: current === html };
+  }
+  mkdirSync(path.dirname(target), { recursive: true });
+  writeFileSync(target, html);
+  return { target, packageCount, fallbackCount, upToDate: true };
+}
+
+export function parseNoticeArgs(argv) {
+  const opts = { config: "right-release.config.mjs", output: undefined, productName: undefined, check: false };
+  const rest = argv[0] === "npm" ? argv.slice(1) : argv;
+  if (argv[0] !== "npm") throw new Error("expected: license-notices npm");
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    if (arg === "--config" || arg === "--output" || arg === "--product-name") {
+      const value = rest[i + 1];
+      if (!value || value.startsWith("--")) throw new Error(`${arg} needs a value`);
+      opts[arg === "--product-name" ? "productName" : arg.slice(2)] = value;
+      i += 1;
+    } else if (arg === "--check") opts.check = true;
+    else throw new Error(`unknown license-notices argument: ${arg}`);
+  }
+  return opts;
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const opts = parseNoticeArgs(argv);
+  const { config, appRoot } = await loadAppConfig(opts.config);
+  const outcome = generateNpmNotices({ appRoot, config, flags: { output: opts.output, productName: opts.productName }, check: opts.check });
+  if (opts.check) {
+    if (!outcome.upToDate) {
+      console.error(`right-release license-notices: ${outcome.target} is out of date; run right-release license-notices npm`);
+      return 1;
+    }
+    console.log(`${outcome.target} is up to date (${outcome.packageCount} package notices)`);
+    return 0;
+  }
+  console.log(`wrote ${outcome.packageCount} package notices (${outcome.fallbackCount} used an SPDX fallback text)`);
+  return 0;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  main().then((code) => { process.exitCode = code; }, (error) => {
+    console.error(`right-release license-notices: ${error.code ? `[${error.code}] ` : ""}${error.message}`);
+    process.exitCode = 1;
+  });
+}

package/ownership-dependency-allowlist.json

@@ -791,6 +791,7 @@
       "repositoryIdentity": "https://github.com/bogusyogi/postright",
       "dependencies": [
         "cargo:jiff",
+        "cargo:serde",
         "cargo:serde_json",
         "cargo:tauri",
         "cargo:tauri-build",