@rightkit/release 0.3.0 → 0.4.1

package/android-play-upload.mjs

@@ -27,6 +27,7 @@ import { pathToFileURL } from "node:url";
 import { spawnSync } from "./background-process.mjs";
 import { describeAabProblems, scanAabBuffer } from "./android-aab-scan.mjs";
 import { sealedManifestAllowsContentDevtools } from "./devtools-policy.mjs";
+import { targetDistribution } from "./target-distribution.mjs";
 import { AndroidReleaseError, createAndroidCredentialStore, resolveAndroidSecret, validateSecretSource } from "./android-release.mjs";
 import { assertArtifactUnchanged, digestBytes, verifyPublicationRelease } from "./publication-artifacts.mjs";
 import { assertPrimaryReleaseCheckout } from "./release-invocation.mjs";
@@ -199,7 +200,7 @@ export async function authorizePlayUpload({ releaseId, configName = "right-relea
   if (!existsSync(configPath)) refuse("PLAY_CONFIG_INVALID", `release config is required: ${configName}`);
   // The config is a module that runs on import: loaded only after the tree is proven clean.
   const config = (await import(`${pathToFileURL(configPath).href}?upload=${Date.now()}`)).default;
-  const distribution = validatePlayDistribution(config?.distribution);
+  const distribution = validatePlayDistribution(targetDistribution(config, "android"));
   const sealedDir = path.join(repoRoot, ".right-release", "sealed", releaseId, "android");
   const sealed = verifyPublicationRelease({ sealedDir, repoRoot, appRoot: path.dirname(configPath), commit, app: config.app, version: config.version, platform: "android", configPath, releaseId });
   const entries = sealed.manifest.files.filter((entry) => entry.role === "aab");

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/apple-profile-renew.mjs

@@ -43,12 +43,20 @@ export function appleProfileAuth(env = process.env, { config = {}, root = proces
 // Only this in-process signer reads key material. Never send it to a subprocess,
 // include it in diagnostics, or expose it in returned renewal plans.
 export function signAppleApiJwt({ keyPath, keyId, issuer }, now = new Date()) {
+  let key;
+  try { key = createPrivateKey(readFileSync(keyPath)); } catch { fail("APPLE_PROFILE_KEY_INVALID", "Unable to sign API JWT with configured .p8 key."); }
+  return signAppleApiJwtWithKey(key, { keyId, issuer }, now);
+}
+
+// The same ES256 App Store Connect JWT from a key that is already in memory (a KeyObject, for example one read from the
+// macOS Keychain by ios-asc-credentials.mjs). No file is read. lifetimeSeconds is at most Apple's 1200 second limit.
+export function signAppleApiJwtWithKey(key, { keyId, issuer }, now = new Date(), { lifetimeSeconds = 600 } = {}) {
   try {
-    const key = createPrivateKey(readFileSync(keyPath));
-    if (key.asymmetricKeyType !== "ec" || key.asymmetricKeyDetails?.namedCurve !== "prime256v1") throw new Error();
+    if (!Number.isInteger(lifetimeSeconds) || lifetimeSeconds < 1 || lifetimeSeconds > 1200) throw new Error();
+    if (key?.asymmetricKeyType !== "ec" || key.asymmetricKeyDetails?.namedCurve !== "prime256v1") throw new Error();
     const iat = Math.floor(now.getTime() / 1000);
     const encoded = (value) => Buffer.from(JSON.stringify(value)).toString("base64url");
-    const payload = `${encoded({ alg: "ES256", kid: keyId, typ: "JWT" })}.${encoded({ iss: issuer, iat, exp: iat + 600, aud: "appstoreconnect-v1" })}`;
+    const payload = `${encoded({ alg: "ES256", kid: keyId, typ: "JWT" })}.${encoded({ iss: issuer, iat, exp: iat + lifetimeSeconds, aud: "appstoreconnect-v1" })}`;
     return `${payload}.${sign("sha256", Buffer.from(payload), { key, dsaEncoding: "ieee-p1363" }).toString("base64url")}`;
   } catch { fail("APPLE_PROFILE_KEY_INVALID", "Unable to sign API JWT with configured .p8 key."); }
 }

package/artifact-storage.mjs

@@ -6,6 +6,7 @@ import {
   mkdirSync,
   readFileSync,
   readdirSync,
+  realpathSync,
   renameSync,
   rmSync,
   statSync,
@@ -20,6 +21,21 @@ export const DEFAULT_MANAGED_ROOT = resolveManagedRoots().dataRoot;
 
 const SAFE_COMPONENT = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,159}$/;
 
+/**
+ * The configured root, canonicalised once: an owner may move the managed root to another volume and leave a symlink at the
+ * configured path (2026-10-18: /Volumes/D/.rightkit-managed -> /Volumes/E/.rightkit-managed). Every path below it is still checked
+ * for symlinks by its consumer (ensurePrivateDirectory refuses symlink ancestors); only the root itself is resolved here.
+ * Used only where a strict ancestor walk needs it (codesign-environment.mjs): resolveManagedRoot stays lexical, because the
+ * Mac signing agent's allowed roots are recorded in that lexical spelling.
+ */
+export function canonicalManagedRoot(root, { realpath = realpathSync.native } = {}) {
+  const resolved = path.resolve(root);
+  try { return realpath(resolved); } catch (error) {
+    if (error?.code === "ENOENT") return resolved;
+    throw error;
+  }
+}
+
 export function resolveManagedRoot({ env = process.env, exists = existsSync } = {}) {
   if (env.RIGHTKIT_DATA_ROOT || env.RIGHTKIT_MANAGED_ROOT || env.RIGHTKIT_EXTERNAL_ROOT) return path.resolve(resolveManagedRoots({ env }).dataRoot);
   // Workstation default only when its drive exists; hosted CI runners fall back to RUNNER_TEMP, then the system temp dir.
@@ -310,15 +326,32 @@ function ensureDirectory(directory) {
   mkdirSync(directory, { recursive: true });
 }
 
-function assertSafeMutation(target) {
+/**
+ * The managed roots an owner configures (env overrides and the workstation default), as spelled. Only these exact paths may
+ * themselves be symlinks (2026-10-18: /Volumes/D/.rightkit-managed -> /Volumes/E/.rightkit-managed); every path below them,
+ * and every other ancestor, is still refused when it is a symlink.
+ */
+export function configuredManagedRootSpellings({ env = process.env } = {}) {
+  const spellings = [DEFAULT_MANAGED_ROOT, env.RIGHTKIT_DATA_ROOT, env.RIGHTKIT_MANAGED_ROOT, env.RIGHTKIT_EXTERNAL_ROOT]
+    .filter((value) => typeof value === "string" && value.length > 0)
+    .map((value) => path.resolve(value));
+  return new Set(process.platform === "win32" ? spellings.map((value) => value.toLowerCase()) : spellings);
+}
+
+function isConfiguredManagedRoot(candidate, roots) {
+  return roots.has(process.platform === "win32" ? path.resolve(candidate).toLowerCase() : path.resolve(candidate));
+}
+
+export function assertSafeMutation(target, { env = process.env } = {}) {
   const absolute = path.resolve(target);
   const root = path.parse(absolute).root;
   const relative = path.relative(root, absolute);
+  const managedRoots = configuredManagedRootSpellings({ env });
   let current = root;
   for (const segment of relative ? relative.split(path.sep) : []) {
     current = path.join(current, segment);
     try {
-      if (lstatSync(current).isSymbolicLink()) throw new Error(`refusing filesystem mutation through symlink: ${current}`);
+      if (lstatSync(current).isSymbolicLink() && !isConfiguredManagedRoot(current, managedRoots)) throw new Error(`refusing filesystem mutation through symlink: ${current}`);
     } catch (error) {
       if (error.code === "ENOENT") continue;
       throw error;

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;
+  });
+}