@rightkit/release 0.4.0 → 0.4.1

package/apple-profile-create.mjs

@@ -4,7 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { spawnSync } from "./background-process.mjs";
-import { appleProfileAuth, decodeAppleProfile, signAppleApiJwt } from "./apple-profile-renew.mjs";
+import { appleProfileAuth, decodeAppleProfile, findAppleSigningCertificate, signAppleApiJwt } from "./apple-profile-renew.mjs";
 
 // right-release apple-profile-create: issue a Mac Development provisioning profile
 // (MAC_APP_DEVELOPMENT) for one explicit bundle id with the ICLOUD/CloudKit capability,
@@ -14,6 +14,7 @@ import { appleProfileAuth, decodeAppleProfile, signAppleApiJwt } from "./apple-p
 
 const ASC = "https://api.appstoreconnect.apple.com";
 const PROFILE_TYPE = "MAC_APP_DEVELOPMENT";
+const DIRECT_TYPE = "MAC_APP_DIRECT";
 export class AppleProfileCreateError extends Error {
   constructor(code, message) { super(message); this.name = "AppleProfileCreateError"; this.code = code; }
 }
@@ -56,7 +57,7 @@ const UDID_PATTERN = /^[A-Fa-f0-9-]{8,64}$/;
 
 export function parseCreateArgs(args) {
   const out = { configPath: undefined, bundleId: "", name: "", containers: [], type: PROFILE_TYPE, certificate: "create", out: "", dryRun: true, apply: false, registerDevices: [], keyOut: "" };
-  const values = { "--config": "configPath", "--bundle-id": "bundleId", "--name": "name", "--type": "type", "--certificate": "certificate", "--out": "out", "--key-out": "keyOut" };
+  const values = { "--config": "configPath", "--bundle-id": "bundleId", "--name": "name", "--type": "type", "--certificate": "certificate", "--out": "out", "--key-out": "keyOut", "--expected-team": "expectedTeam", "--expected-keychain-group": "expectedKeychainGroup" };
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === "--dry-run") out.dryRun = true;
@@ -71,10 +72,10 @@ export function parseCreateArgs(args) {
   }
   if (out.apply && args.includes("--dry-run")) fail("APPLE_PROFILE_USAGE", "--dry-run and --apply are mutually exclusive.");
   out.dryRun = !out.apply;
-  if (out.type !== PROFILE_TYPE) fail("APPLE_PROFILE_USAGE", `--type must be ${PROFILE_TYPE} (the only supported value).`);
+  validateProfileMode(out);
   if (!BUNDLE_PATTERN.test(out.bundleId)) fail("APPLE_PROFILE_USAGE", "--bundle-id must be an explicit bundle identifier (no wildcard).");
   if (!out.name.trim()) fail("APPLE_PROFILE_USAGE", "--name is required.");
-  if (!out.containers.length) fail("APPLE_PROFILE_USAGE", "At least one --icloud-container is required.");
+  if (out.type === PROFILE_TYPE && !out.containers.length) fail("APPLE_PROFILE_USAGE", "At least one --icloud-container is required.");
   for (const container of out.containers) if (!CONTAINER_PATTERN.test(container)) fail("APPLE_PROFILE_USAGE", `Invalid iCloud container identifier: ${container}`);
   for (const udid of out.registerDevices) if (!UDID_PATTERN.test(udid)) fail("APPLE_PROFILE_USAGE", `Invalid device UDID: ${udid}`);
   if (!out.out) fail("APPLE_PROFILE_USAGE", "--out <profile path> is required.");
@@ -82,6 +83,15 @@ export function parseCreateArgs(args) {
   return out;
 }
 
+function validateProfileMode({ type, certificate, containers = [], registerDevices = [], keyOut, expectedTeam, expectedKeychainGroup }) {
+  if (![PROFILE_TYPE, DIRECT_TYPE].includes(type)) fail("APPLE_PROFILE_USAGE", `--type must be ${PROFILE_TYPE} or ${DIRECT_TYPE}.`);
+  if (type !== DIRECT_TYPE) return;
+  if (!/^[A-Z0-9]{10}$/.test(expectedTeam ?? "")) fail("APPLE_PROFILE_USAGE", "Direct profiles require --expected-team <10-character team id>.");
+  if (typeof expectedKeychainGroup !== "string" || !expectedKeychainGroup.startsWith(`${expectedTeam}.`) || !BUNDLE_PATTERN.test(expectedKeychainGroup.slice(expectedTeam.length + 1))) fail("APPLE_PROFILE_USAGE", "Direct profiles require one exact --expected-keychain-group prefixed by expected team (no wildcard).");
+  if (!/^[A-Za-z0-9]{4,40}$/.test(certificate ?? "") || certificate === "create") fail("APPLE_PROFILE_USAGE", "Direct profiles require --certificate <existing ASC certificate id>.");
+  if (containers.length || registerDevices.length || keyOut) fail("APPLE_PROFILE_USAGE", "Direct profiles refuse iCloud containers, device registration & key output.");
+}
+
 // Key material must never ride in config, the environment or arguments. Unlike the
 // renew command this refusal applies on every host.
 export function assertNoInlinePem(env, config, extra = []) {
@@ -113,10 +123,11 @@ function localDevelopmentIdentities(run, now, { tolerant }) {
 
 // ---- main flow ---------------------------------------------------------------------
 
-export async function createAppleProfile({ root, config = {}, bundleId, name, containers, type = PROFILE_TYPE, certificate = "create", out, dryRun = true, registerDevices = [], keyOut = "", env = process.env, run = spawnSync, fetch: fetchApi = globalThis.fetch, jwtSigner = signAppleApiJwt, now = new Date(), log = console.log, platform = process.platform, home = os.homedir() }) {
-  if (type !== PROFILE_TYPE) fail("APPLE_PROFILE_USAGE", `--type must be ${PROFILE_TYPE}.`);
+export async function createAppleProfile({ root, config = {}, bundleId, name, containers = [], type = PROFILE_TYPE, certificate = "create", out, dryRun = true, registerDevices = [], keyOut = "", expectedTeam, expectedKeychainGroup, env = process.env, run = spawnSync, fetch: fetchApi = globalThis.fetch, jwtSigner = signAppleApiJwt, now = new Date(), log = console.log, platform = process.platform, home = os.homedir() }) {
+  validateProfileMode({ type, certificate, containers, registerDevices, keyOut, expectedTeam, expectedKeychainGroup });
   if (!BUNDLE_PATTERN.test(bundleId ?? "")) fail("APPLE_PROFILE_USAGE", "bundleId must be an explicit bundle identifier.");
-  if (!containers?.length) fail("APPLE_PROFILE_USAGE", "At least one iCloud container is required.");
+  if (!name?.trim() || !out) fail("APPLE_PROFILE_USAGE", "Profile name & output path are required.");
+  if (type === PROFILE_TYPE && !containers?.length) fail("APPLE_PROFILE_USAGE", "At least one iCloud container is required.");
   assertNoInlinePem(env, config, [["--certificate", certificate], ["--name", name]]);
   if (!dryRun && platform !== "darwin") fail("APPLE_PROFILE_PLATFORM", "A real run decodes the issued profile and uses the Keychain; run it on the macOS host.");
   const outFile = path.resolve(root, out);
@@ -155,12 +166,14 @@ export async function createAppleProfile({ root, config = {}, bundleId, name, co
     }
     return items;
   };
-  const plan = { dryRun, command: "apple-profile-create", profileType: PROFILE_TYPE, out: outFile, name, calls, planned };
+  const plan = { dryRun, command: "apple-profile-create", profileType: type, out: outFile, name, calls, planned };
   const mutate = async (method, endpoint, body) => {
     if (dryRun) { planned.push({ method, path: endpoint, ...(body ? { body } : {}) }); log(`PLANNED ${method} ${endpoint}${body ? ` ${JSON.stringify(body)}` : ""}`); return null; }
     return request(method, endpoint, body);
   };
 
+  if (type === DIRECT_TYPE) return createDirectProfile({ bundleId, name, certificate, expectedTeam, expectedKeychainGroup, outFile, dryRun, env, run, now, log, request, list, mutate, plan });
+
   // (1) bundle id
   const bundles = await list(query("/v1/bundleIds", { "filter[identifier]": bundleId, limit: "200" }));
   let bundle = bundles.find((item) => item.attributes?.identifier === bundleId && ["MAC_OS", "UNIVERSAL"].includes(item.attributes?.platform));
@@ -290,6 +303,96 @@ export async function createAppleProfile({ root, config = {}, bundleId, name, co
   return { ...plan, profileId: profile.id, identitySha1: certificateSha1 };
 }
 
+// Direct profiles authorize one selected existing Developer ID identity. No device,
+// capability, certificate or key creation is reachable from this branch.
+async function createDirectProfile({ bundleId, name, certificate, expectedTeam, expectedKeychainGroup, outFile, dryRun, env, run, now, log, request, list, mutate, plan }) {
+  const ascCert = (await request("GET", `/v1/certificates/${enc(certificate)}`)).data;
+  if (!ascCert?.id || ascCert.id !== certificate) fail("APPLE_PROFILE_CERT_NOT_IN_ASC", "Selected certificate is absent from ASC.");
+  if (!["DEVELOPER_ID_APPLICATION", "DEVELOPER_ID_APPLICATION_G2"].includes(ascCert.attributes?.certificateType)) fail("APPLE_PROFILE_CERT_TYPE", "Direct profiles require an existing DEVELOPER_ID_APPLICATION or DEVELOPER_ID_APPLICATION_G2 certificate.");
+  if (!(Date.parse(ascCert.attributes?.expirationDate) > now.getTime())) fail("APPLE_PROFILE_CERT_EXPIRED", "Selected ASC certificate is expired.");
+  let leaf;
+  try { leaf = new X509Certificate(Buffer.from(ascCert.attributes?.certificateContent ?? "", "base64")); }
+  catch { fail("APPLE_PROFILE_API_INVALID", "Selected ASC certificate has no valid public DER certificate."); }
+  const certificateSha1 = sha1(leaf.raw);
+  const identity = findAppleSigningCertificate({ type: DIRECT_TYPE, team: expectedTeam }, { env: { ...env, APPLE_SIGNING_IDENTITY: certificateSha1 }, run, now });
+  if (identity.sha1 !== certificateSha1 || serial(identity.serialNumber) !== serial(ascCert.attributes?.serialNumber)) fail("APPLE_PROFILE_CERT_MISMATCH", "Selected ASC certificate does not match local Developer ID identity.");
+  plan.teamIdentifier = expectedTeam;
+  plan.expectedKeychainGroup = expectedKeychainGroup;
+  plan.certificate = { ...identity, id: ascCert.id, mode: "explicit", privateKeyInKeychain: true };
+
+  const bundles = await list(query("/v1/bundleIds", { "filter[identifier]": bundleId, limit: "200" }));
+  const matching = bundles.filter((item) => item.attributes?.identifier === bundleId);
+  if (matching.length > 1 || (matching.length && !["MAC_OS", "UNIVERSAL"].includes(matching[0].attributes?.platform))) fail("APPLE_PROFILE_BUNDLE_CONFLICT", "Existing bundle identifier has conflicting platform or duplicate resources.");
+  let bundle = matching[0];
+  // Look across types so a dedicated name is never silently duplicated.
+  const profiles = (await list(query("/v1/profiles", { "filter[name]": name, limit: "200" }))).filter((item) => item.attributes?.name === name);
+  if (profiles.length > 1) fail("APPLE_PROFILE_NAME_CONFLICT", "More than one profile already uses this dedicated name.");
+  let profile = profiles[0];
+  if (profile) {
+    const [bundleRel, certRel] = await Promise.all([request("GET", `/v1/profiles/${enc(profile.id)}/bundleId`), list(`/v1/profiles/${enc(profile.id)}/certificates`)]);
+    if (!bundle?.id || profile.attributes?.profileType !== DIRECT_TYPE || profile.attributes?.profileState !== "ACTIVE" || !(Date.parse(profile.attributes?.expirationDate) > now.getTime())
+      || bundleRel.data?.id !== bundle.id || certRel.length !== 1 || certRel[0].id !== ascCert.id) fail("APPLE_PROFILE_NAME_CONFLICT", "Existing named profile does not match direct type, bundle & selected certificate.");
+  }
+  plan.bundleId = { identifier: bundleId, id: bundle?.id ?? null, action: bundle ? "reuse" : "create" };
+  if (!bundle) {
+    const result = await mutate("POST", "/v1/bundleIds", { data: { type: "bundleIds", attributes: { identifier: bundleId, name: name.replace(/[^A-Za-z0-9 ]/g, " ").trim() || bundleId, platform: "MAC_OS" } } });
+    if (result) {
+      bundle = result.data;
+      if (!bundle?.id || bundle.attributes?.identifier !== bundleId || !["MAC_OS", "UNIVERSAL"].includes(bundle.attributes?.platform)) fail("APPLE_PROFILE_API_INVALID", "ASC returned an unexpected created bundle identifier.");
+      plan.bundleId.id = bundle.id;
+    }
+  }
+  plan.profile = { id: profile?.id ?? null, action: profile ? "reuse" : "create" };
+  if (!profile) {
+    const body = { data: { type: "profiles", attributes: { name, profileType: DIRECT_TYPE }, relationships: {
+      bundleId: { data: { type: "bundleIds", id: bundle?.id ?? "<new bundleId>" } }, certificates: { data: [{ type: "certificates", id: ascCert.id }] } } } };
+    const result = await mutate("POST", "/v1/profiles", body);
+    if (result) {
+      profile = result.data;
+      if (!profile?.id) fail("APPLE_PROFILE_API_INVALID", "ASC did not return a created profile id.");
+      plan.profile.id = profile.id;
+    }
+  }
+  plan.verification = "Exact team, application identifier, OSX, expiry, all devices, debugging disabled, selected DER fingerprint & exact keychain group authorization; app must request only its exact group.";
+  log(JSON.stringify({ ...plan, calls: undefined }, null, 2));
+  if (dryRun) { plan.writes = `would write ${outFile} (0600)`; return plan; }
+  const content = profile.attributes?.profileContent ?? (await request("GET", `/v1/profiles/${enc(profile.id)}`)).data?.attributes?.profileContent;
+  if (typeof content !== "string" || !content || !/^[A-Za-z0-9+/]+={0,2}$/.test(content)) fail("APPLE_PROFILE_API_INVALID", "ASC profileContent is missing or invalid.");
+  mkdirSync(path.dirname(outFile), { recursive: true });
+  const temporary = `${outFile}.create-${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temporary, Buffer.from(content, "base64"), { flag: "wx", mode: 0o600 });
+    verifyDirectProfile(decodeAppleProfile(temporary, { run }), { bundleId, name, expectedTeam, expectedKeychainGroup, certificateSha1, now });
+    if (existsSync(outFile)) copyFileSync(outFile, `${outFile}.backup-${now.toISOString().replace(/[:.]/g, "-")}-${randomUUID()}`, constants.COPYFILE_EXCL);
+    renameSync(temporary, outFile);
+    chmodSync(outFile, 0o600);
+  } finally { rmSync(temporary, { force: true }); }
+  log(`Wrote ${outFile}; Developer ID identity SHA-1 ${certificateSha1}`);
+  return { ...plan, profileId: profile.id, identitySha1: certificateSha1 };
+}
+
+export function verifyDirectProfile(decoded, { bundleId, name, expectedTeam, expectedKeychainGroup, certificateSha1, now }) {
+  const problems = [], entitlements = decoded.Entitlements ?? {};
+  if (decoded.Name !== name) problems.push("profile name mismatch");
+  if (!Array.isArray(decoded.TeamIdentifier) || decoded.TeamIdentifier.length !== 1 || decoded.TeamIdentifier[0] !== expectedTeam) problems.push("team mismatch");
+  if (entitlements["com.apple.developer.team-identifier"] !== expectedTeam) problems.push("entitlement team mismatch");
+  const appKeys = ["com.apple.application-identifier", "application-identifier"].filter((key) => Object.hasOwn(entitlements, key));
+  if (!appKeys.length || appKeys.some((key) => entitlements[key] !== `${expectedTeam}.${bundleId}`)) problems.push("application identifier mismatch");
+  if (!Array.isArray(decoded.Platform) || !decoded.Platform.includes("OSX")) problems.push("not a macOS profile");
+  if (!(Date.parse(decoded.ExpirationDate) > now.getTime())) problems.push("expired or missing expiration");
+  if (decoded.ProvisionsAllDevices !== true) problems.push("not an all-devices direct profile");
+  const debugKeys = ["get-task-allow", "com.apple.security.get-task-allow"].filter((key) => Object.hasOwn(entitlements, key));
+  // Profiles carry an entitlement allowlist (Apple TN3125). Direct profiles may
+  // omit debugging entirely; every present alias must still be boolean false.
+  if (debugKeys.some((key) => entitlements[key] !== false)) problems.push("debugging is not disabled");
+  if (!certificateSha1 || !(decoded.DeveloperCertificates ?? []).some((data) => sha1(Buffer.from(data, "base64")) === certificateSha1)) problems.push("selected certificate not authorized");
+  const groups = entitlements["keychain-access-groups"];
+  // Apple-issued terminal wildcards may authorize an exact app group. This never
+  // changes the app's requested entitlements or permits wildcard CLI input.
+  if (!Array.isArray(groups) || !groups.some((group) => group === expectedKeychainGroup || (typeof group === "string" && group.startsWith(`${expectedTeam}.`) && /^[^*]+\*$/u.test(group) && expectedKeychainGroup.startsWith(group.slice(0, -1))))) problems.push("keychain group not authorized");
+  if (problems.length) fail("APPLE_PROFILE_VERIFY_FAILED", `Direct profile failed verification: ${problems.join("; ")}.`);
+}
+
 export function verifyIssuedProfile(decoded, { bundleId, containers, certificateSha1, deviceUdids, now }) {
   const other = [], missing = [];
   const entitlements = decoded.Entitlements ?? {};
@@ -345,7 +448,7 @@ async function createCertificate({ commonName, request, run, keyOut, home, log }
 
 export async function main(args = process.argv.slice(2), options = {}) {
   if (args.includes("--help") || args.includes("-h")) {
-    (options.log ?? console.log)("right-release apple-profile-create --bundle-id <id> --name <profile name> --icloud-container <iCloud.x> [--icloud-container ...] --out <profile path>\n  [--config <file>] [--type MAC_APP_DEVELOPMENT] [--certificate <asc cert id>|create] [--register-device <UDID>]... [--key-out <file>] [--dry-run | --apply]\nDefault is --dry-run (GET discovery only). Uses APPLE_API_ISSUER, APPLE_API_KEY & APPLE_API_KEY_PATH or appStoreConnect.* in the config; inline PEM is refused.\nThe ASC API cannot create or assign iCloud containers; the issued profile is verified and the command prints manual steps if the container is missing.");
+    (options.log ?? console.log)("right-release apple-profile-create --bundle-id <id> --name <profile name> --out <profile path>\n  [--config <file>] [--type MAC_APP_DEVELOPMENT|MAC_APP_DIRECT] [--certificate <asc cert id>|create] [--dry-run | --apply]\nDevelopment: --icloud-container <iCloud.x>... [--register-device <UDID>]... [--key-out <file>]\nDirect: --certificate <existing ASC Developer ID cert id> --expected-team <team id> --expected-keychain-group <exact group>; refuses iCloud, devices & key output.\nDefault is --dry-run (GET discovery only). Uses APPLE_API_ISSUER, APPLE_API_KEY & APPLE_API_KEY_PATH or appStoreConnect.* in the config; inline PEM is refused.\nThe ASC API cannot create or assign iCloud containers; the issued profile is verified and the command prints manual steps if the container is missing.");
     return;
   }
   const parsed = parseCreateArgs(args);
@@ -354,7 +457,7 @@ export async function main(args = process.argv.slice(2), options = {}) {
   let config = {};
   if (existsSync(absolute)) { const loaded = await import(pathToFileURL(absolute)); config = loaded.default ?? loaded.config ?? loaded; }
   else if (parsed.configPath) fail("APPLE_PROFILE_USAGE", `Config file not found: ${parsed.configPath}`);
-  return createAppleProfile({ ...options, root: path.dirname(absolute), config, bundleId: parsed.bundleId, name: parsed.name, containers: parsed.containers, type: parsed.type, certificate: parsed.certificate, out: parsed.out, dryRun: parsed.dryRun, registerDevices: parsed.registerDevices, keyOut: parsed.keyOut });
+  return createAppleProfile({ ...options, root: path.dirname(absolute), config, ...parsed });
 }
 
 const realOrSelf = (file) => { try { return realpathSync(file); } catch { return path.resolve(file); } };

package/binary-license-notices.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+// `right-release license-notices binaries [--config <file>] [--output <file>] [--product-name <name>] [--receipt <path>] [--check]`:
+// writes the notice appendix (one HTML file) for the binaries an app ships that no RightKit catalog row covers (a downloaded yt-dlp, a
+// vendored tool, a command-built helper). Catalog-backed sidecars (ffmpeg, onnxruntime, pdfium, whisper) write their own notices when
+// they are staged; everything else must be declared here, with its licence text, or the build has no right to ship it.
+//
+//   legal: { binaryNotices: { output: "legal/THIRD_PARTY_BINARIES.html", productName: "ScrapeRight", receipt: "src-tauri/binaries/stage-sidecar.json",
+//            binaries: [{ name: "yt-dlp", version: "2026.03.17" | "self-updating", license: "Unlicense", sourceUrl: "https://github.com/yt-dlp/yt-dlp",
+//                         files: ["legal/texts/yt-dlp-UNLICENSE.txt"], covers?: ["yt-dlp-helper"] }] } }
+//
+// Every `files` entry is an app-relative text file that must exist; no licence text is ever invented. With a `receipt` (the
+// stage-sidecar receipt, also settable with `--receipt`) every staged file of kind remote, command, cmake or prebuilt must belong to a
+// declared binary - by its entry name, or a name listed in `covers` - or the run fails naming the uncovered ones. The page records the
+// receipt-independent inputs only (declared fields and the sha256 of each text), so the same declaration always produces the same bytes.
+// `--check` writes nothing and exits 1 when the file on disk differs.
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { CommandSpecError, loadAppConfig, relativeInside } from "./command-spec.mjs";
+import { escapeHtml } from "./npm-license-notices.mjs";
+
+const fail = (message) => { throw new CommandSpecError(message); };
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const KEYS = ["output", "productName", "receipt", "binaries"];
+const BINARY_KEYS = ["name", "version", "license", "sourceUrl", "files", "covers"];
+/** Receipt kinds with no catalog row behind them. */
+export const NON_CATALOG_KINDS = Object.freeze(["remote", "command", "cmake", "prebuilt"]);
+
+/** Resolve and validate `legal.binaryNotices` plus flags. */
+export function resolveBinaryNoticeOptions(config, flags = {}) {
+  const declared = config?.legal?.binaryNotices;
+  if (!isObject(declared)) fail("legal.binaryNotices must be an object");
+  const unknown = Object.keys(declared).filter((key) => !KEYS.includes(key));
+  if (unknown.length) fail(`legal.binaryNotices has unknown key(s): ${unknown.join(", ")} (allowed: ${KEYS.join(", ")})`);
+  const output = flags.output ?? declared.output;
+  if (output === undefined) fail("no output file: set legal.binaryNotices.output or pass --output");
+  relativeInside(output, "legal.binaryNotices.output");
+  const productName = flags.productName ?? declared.productName;
+  if (typeof productName !== "string" || !productName.trim()) fail("no product name: set legal.binaryNotices.productName or pass --product-name");
+  const receipt = flags.receipt ?? declared.receipt;
+  if (receipt !== undefined) relativeInside(receipt, "legal.binaryNotices.receipt");
+  if (!Array.isArray(declared.binaries) || !declared.binaries.length) fail("legal.binaryNotices.binaries must be a non-empty list");
+  const names = new Set();
+  const binaries = declared.binaries.map((item, index) => {
+    const label = `legal.binaryNotices.binaries[${index}]`;
+    if (!isObject(item)) fail(`${label} must be an object`);
+    const extra = Object.keys(item).filter((key) => !BINARY_KEYS.includes(key));
+    if (extra.length) fail(`${label} has unknown key(s): ${extra.join(", ")} (allowed: ${BINARY_KEYS.join(", ")})`);
+    for (const key of ["name", "version", "license"]) if (typeof item[key] !== "string" || !item[key].trim()) fail(`${label}.${key} must be a non-empty string`);
+    if (typeof item.sourceUrl !== "string" || !/^https:\/\/[^\s/]+\/\S*$/.test(item.sourceUrl)) fail(`${label}.sourceUrl must be an https:// URL of the source or release`);
+    if (!Array.isArray(item.files) || !item.files.length) fail(`${label}.files must list at least one licence/notice text file`);
+    const files = item.files.map((file, fileIndex) => relativeInside(file, `${label}.files[${fileIndex}]`));
+    const covers = item.covers ?? [];
+    if (!Array.isArray(covers) || covers.some((name) => typeof name !== "string" || !name.trim())) fail(`${label}.covers must be a list of staged entry names`);
+    for (const name of [item.name, ...covers]) {
+      if (names.has(name)) fail(`${label}: ${name} is declared twice`);
+      names.add(name);
+    }
+    return { name: item.name, version: item.version, license: item.license, sourceUrl: item.sourceUrl, files, covers: [...covers] };
+  });
+  return { output, productName, receipt, binaries };
+}
+
+/** The names of staged non-catalog entries that no declared binary covers. */
+export function uncoveredBinaries(receipt, binaries) {
+  const covered = new Set(binaries.flatMap((binary) => [binary.name, ...(binary.covers ?? [])]));
+  const missing = new Set();
+  for (const file of receipt?.files ?? []) {
+    if (!NON_CATALOG_KINDS.includes(file.kind)) continue;
+    const name = file.entryName ?? file.command ?? file.name;
+    if (!covered.has(name)) missing.add(name);
+  }
+  return [...missing].sort();
+}
+
+/** Render the appendix. `texts` maps an app-relative file to its text. Returns the HTML. */
+export function renderBinaryNotices({ productName, binaries, texts }) {
+  const sections = binaries.map((binary) => {
+    const bodies = binary.files.map((file) => `<h3>${escapeHtml(path.posix.basename(file))}</h3><pre>${escapeHtml(texts.get(file))}</pre>`).join("\n");
+    const digests = binary.files.map((file) => `${escapeHtml(path.posix.basename(file))} sha256=${createHash("sha256").update(texts.get(file)).digest("hex")}`).join("; ");
+    return `<section><h2>${escapeHtml(binary.name)} ${escapeHtml(binary.version)}</h2><p>License: ${escapeHtml(binary.license)}</p><p>Source: ${escapeHtml(binary.sourceUrl)}</p><p>Texts: ${digests}</p>\n${bodies}</section>`;
+  });
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><title>${escapeHtml(productName)} bundled program licenses</title></head><body>
+<h1>${escapeHtml(productName)} bundled program licenses</h1>
+<p>Programs shipped with ${escapeHtml(productName)} that are not Cargo or npm dependencies; generated-by=right-release license-notices binaries</p>
+${sections.join("\n")}
+</body></html>
+`;
+}
+
+/** Generate (or check) the appendix for the app at `appRoot`. File access is injectable. */
+export function generateBinaryNotices({ appRoot, config, flags = {}, check = false, exists = existsSync, readText = (file) => readFileSync(file, "utf8"), writeText = (file, text) => { mkdirSync(path.dirname(file), { recursive: true }); writeFileSync(file, text); } }) {
+  const { output, productName, receipt, binaries } = resolveBinaryNoticeOptions(config, flags);
+  const texts = new Map();
+  for (const binary of binaries) {
+    for (const file of binary.files) {
+      const absolute = path.join(appRoot, file);
+      if (!exists(absolute)) fail(`${binary.name}: licence text ${file} does not exist; no text is invented, add the file`);
+      const text = String(readText(absolute)).replace(/\r\n/g, "\n");
+      if (!text.trim()) fail(`${binary.name}: licence text ${file} is empty`);
+      texts.set(file, text);
+    }
+  }
+  let uncovered = [];
+  if (receipt !== undefined) {
+    const receiptFile = path.join(appRoot, receipt);
+    if (!exists(receiptFile)) fail(`the stage-sidecar receipt ${receipt} does not exist; run right-release stage-sidecar first`);
+    let parsed;
+    try { parsed = JSON.parse(readText(receiptFile)); } catch (error) { fail(`the stage-sidecar receipt ${receipt} is not JSON (${error.message})`); }
+    uncovered = uncoveredBinaries(parsed, binaries);
+    if (uncovered.length) fail(`staged program(s) with no declared licence notice: ${uncovered.join(", ")}; declare them in legal.binaryNotices.binaries (name or covers)`);
+  }
+  const html = renderBinaryNotices({ productName, binaries, texts });
+  const target = path.join(appRoot, output);
+  if (check) {
+    const current = exists(target) ? String(readText(target)).replace(/\r\n/g, "\n") : null;
+    return { target, binaryCount: binaries.length, uncovered, upToDate: current === html };
+  }
+  writeText(target, html);
+  return { target, binaryCount: binaries.length, uncovered, upToDate: true };
+}
+
+export function parseBinaryNoticeArgs(argv) {
+  const opts = { config: "right-release.config.mjs", output: undefined, productName: undefined, receipt: undefined, check: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--config" || arg === "--output" || arg === "--product-name" || arg === "--receipt") {
+      const value = argv[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 = parseBinaryNoticeArgs(argv);
+  const { config, appRoot } = await loadAppConfig(opts.config);
+  const outcome = generateBinaryNotices({ appRoot, config, flags: { output: opts.output, productName: opts.productName, receipt: opts.receipt }, 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 binaries`);
+      return 1;
+    }
+    console.log(`${outcome.target} is up to date (${outcome.binaryCount} program notices)`);
+    return 0;
+  }
+  console.log(`wrote ${outcome.binaryCount} program notices to ${outcome.target}`);
+  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/cargo-license-notices.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// `right-release license-notices cargo [--config <file>] [--output <file>] [--check]`: writes the third-party Cargo license appendix
+// (one file) for an app's Rust dependency closure with `cargo about`, run through the managed cargo client (`runCargoSync`: the
+// RightKit broker on a managed host, never a bare-cargo fallback on a managed Mac).
+//
+//   legal: { cargoNotices: { output: "legal/THIRD_PARTY_CARGO_LICENSES.html", template: "legal/about.hbs",
+//                            config?: "legal/about.toml", manifestPath?: "src-tauri/Cargo.toml", features?: ["a"], allFeatures?: true } }
+//
+// `output`, `template`, `config` and `manifestPath` are app-relative and may not leave the app. The run is `cargo about generate --locked
+// --fail [--config <config>] [--manifest-path <path>] [--all-features | --features a,b] <template>`; cargo-about writes the rendered
+// appendix to stdout, which is normalised to LF and one trailing newline so the same lockfile always produces the same bytes. `--fail`
+// makes an unaccepted license or an unresolved clarification an error instead of a warning. `--check` writes nothing and exits 1 when
+// the file on disk differs.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { CommandSpecError, loadAppConfig, relativeInside } from "./command-spec.mjs";
+import { runCargoSync } from "./managed-cargo.mjs";
+
+const fail = (message) => { throw new CommandSpecError(message); };
+const KEYS = ["output", "template", "config", "manifestPath", "features", "allFeatures"];
+
+/** Resolve and validate `legal.cargoNotices` plus flags. */
+export function resolveCargoNoticeOptions(config, flags = {}) {
+  const declared = config?.legal?.cargoNotices ?? {};
+  if (typeof declared !== "object" || declared === null || Array.isArray(declared)) fail("legal.cargoNotices must be an object");
+  const unknown = Object.keys(declared).filter((key) => !KEYS.includes(key));
+  if (unknown.length) fail(`legal.cargoNotices has unknown key(s): ${unknown.join(", ")} (allowed: ${KEYS.join(", ")})`);
+  const output = flags.output ?? declared.output;
+  if (output === undefined) fail("no output file: set legal.cargoNotices.output or pass --output");
+  relativeInside(output, "legal.cargoNotices.output");
+  if (declared.template === undefined) fail("legal.cargoNotices.template (the cargo-about handlebars template) is required");
+  relativeInside(declared.template, "legal.cargoNotices.template");
+  for (const key of ["config", "manifestPath"]) if (declared[key] !== undefined) relativeInside(declared[key], `legal.cargoNotices.${key}`);
+  const features = declared.features ?? [];
+  if (!Array.isArray(features) || features.some((feature) => typeof feature !== "string" || !/^[A-Za-z0-9_/-]+$/.test(feature))) fail("legal.cargoNotices.features must be a list of feature names");
+  if (declared.allFeatures !== undefined && typeof declared.allFeatures !== "boolean") fail("legal.cargoNotices.allFeatures must be a boolean");
+  if (declared.allFeatures === true && features.length) fail("legal.cargoNotices: give allFeatures or features, not both");
+  return { output, template: declared.template, config: declared.config, manifestPath: declared.manifestPath, features, allFeatures: declared.allFeatures === true };
+}
+
+/** The `cargo about` argument list (after the managed client adds `cargo`). */
+export function cargoAboutArgs(options) {
+  return [
+    "about", "generate", "--locked", "--fail",
+    ...(options.config ? ["--config", options.config] : []),
+    ...(options.manifestPath ? ["--manifest-path", options.manifestPath] : []),
+    ...(options.allFeatures ? ["--all-features"] : options.features.length ? ["--features", options.features.join(",")] : []),
+    options.template,
+  ];
+}
+
+const normalise = (text) => `${String(text).replace(/\r\n/g, "\n").replace(/\s+$/, "")}\n`;
+
+/** Generate (or check) the Cargo appendix for the app at `appRoot`. `run` is the managed cargo runner (injectable). */
+export function generateCargoNotices({ appRoot, config, flags = {}, check = false, run = runCargoSync, env = process.env, exists = existsSync, readText = (file) => readFileSync(file, "utf8"), writeText = (file, text) => { mkdirSync(path.dirname(file), { recursive: true }); writeFileSync(file, text); } }) {
+  const options = resolveCargoNoticeOptions(config, flags);
+  for (const key of ["template", "config", "manifestPath"]) {
+    if (options[key] !== undefined && !exists(path.join(appRoot, options[key]))) fail(`legal.cargoNotices.${key} ${options[key]} does not exist`);
+  }
+  const result = run(cargoAboutArgs(options), { cwd: appRoot, env, encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
+  if (result?.error) fail(`cargo about could not start (${result.error.message}); install cargo-about on the build host`);
+  if (result?.status !== 0) fail(`cargo about exited ${result?.status ?? "without status"}${result?.stderr ? `:\n${String(result.stderr).trim()}` : ""}`);
+  const text = normalise(result.stdout ?? "");
+  if (text.trim() === "") fail("cargo about produced no output");
+  const target = path.join(appRoot, options.output);
+  if (check) {
+    const current = exists(target) ? normalise(readText(target)) : null;
+    return { target, bytes: Buffer.byteLength(text), upToDate: current === text };
+  }
+  writeText(target, text);
+  return { target, bytes: Buffer.byteLength(text), upToDate: true };
+}
+
+export function parseCargoNoticeArgs(argv) {
+  const opts = { config: "right-release.config.mjs", output: undefined, check: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--config" || arg === "--output") {
+      const value = argv[i + 1];
+      if (!value || value.startsWith("--")) throw new Error(`${arg} needs a value`);
+      opts[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 = parseCargoNoticeArgs(argv);
+  const { config, appRoot } = await loadAppConfig(opts.config);
+  const outcome = generateCargoNotices({ appRoot, config, flags: { output: opts.output }, 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 cargo`);
+      return 1;
+    }
+    console.log(`${outcome.target} is up to date`);
+    return 0;
+  }
+  console.log(`wrote ${outcome.target} (${outcome.bytes} bytes)`);
+  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/cli/right-release.mjs

@@ -40,6 +40,7 @@ const commands = new Map([
   ["ownership-approval", "ownership-approval-command.mjs"],
   ["ownership-report", "ownership-report-command.mjs"],
   ["ownership-mandatory", "ownership-mandatory-set.mjs"],
+  ["adoption-evidence", "adoption-evidence.mjs"],
   ["swift-package", "swift-package-command.mjs"],
   ["bundle-scan", "runtime-bundle-scan.mjs"],
   ["check-release-dependencies", "release-dependencies-command.mjs"],
@@ -136,6 +137,9 @@ if (first === "--version" || first === "-v") {
   runBinary("python3", [path.join(packageRoot, "generate-dmg-background.py"), ...args.slice(1)]);
 } else if (first === "build" && args.includes("--web")) {
   run("web-build.mjs", args.slice(1).filter((arg) => arg !== "--web"));
+} else if (first === "license-notices" && (args[1] === "cargo" || args[1] === "binaries")) {
+  // `license-notices npm` stays on the commands map; the Rust and native-binary appendices have their own modules.
+  run(args[1] === "cargo" ? "cargo-license-notices.mjs" : "binary-license-notices.mjs", args.slice(2));
 } else if (commands.has(first)) {
   run(commands.get(first), args.slice(1));
 } else if (first.startsWith("-")) {
@@ -217,6 +221,10 @@ Commands:
                                                       Run the app's declared test suites (config tests.suites / tests.runners) in order; stops at the first failure
   license-notices npm [--config <file>] [--output <file>] [--product-name <name>] [--check]
                                                       Write the third-party npm license appendix HTML from pnpm licenses (config legal.npmNotices); --check only compares
+  license-notices cargo [--config <file>] [--output <file>] [--check]
+                                                      Write the third-party Cargo license appendix HTML through cargo about (config legal.cargoNotices); --check only compares
+  license-notices binaries [--config <file>] [--output <file>] [--product-name <name>] [--receipt <path>] [--check]
+                                                      Write the notices for shipped programs that are not Cargo or npm dependencies (config legal.binaryNotices); --check only compares
   toolchain swift --version <x.y.z> --sha256 <pin> [--url <https url>] [--github-env] [--json]
                                                       Windows: install the pinned swift.org Swift toolchain (sha256 verified before it runs), check swift --version, find the runtime bin; --github-env exports what the installer changed to GITHUB_ENV / GITHUB_PATH
   dev --platform win|mac [--config <path>] [--dry-run] [--build-only]
@@ -288,6 +296,8 @@ Commands:
                                                       Report cross-app ownership & pending requests
   ownership-mandatory [--workspace <dir>] [--app <name>]... [--amendment v2.1] [--enforce] [--json]
                                                       Check each app declares every Table 1 owner at its required version (report by default)
+  adoption-evidence --manifest <published-release-manifest.json> [--packets <dir>] [--app <dir> [--adoption <file>] [--target <target>]] [--json]
+                                                      Validate the handoff manifest (derived fields, AP set = frozen packets) and, with --app, an app's adoption record (lock pins, closure, receipts)
   cache status [--json]                              Inspect the shared local build cache
   cache prune [--dry-run|--apply] [--json]           Plan or apply safe shared-target pruning
   cache migrate --config <file> [--dry-run|--apply] [--json]