@rightkit/release 0.2.151 → 0.2.153

package/github-release.mjs

@@ -367,7 +367,10 @@ function runCombined(command, args, commandRunner = spawnSync) {
 }
 
 function usage(code) {
-  console.log("usage: right-release github (--release <sealed-id> | --addon <config>) --platform mac|win [--repo owner/repo] [--dry-run]");
+  console.log([
+    "usage: right-release github --release <sealed-id> --tier patch|update --platform mac|win [--config right-release.config.mjs] [--repo owner/repo] [--dry-run]",
+    "       right-release github --addon <config> --platform mac|win [--repo owner/repo] [--dry-run]",
+  ].join("\n"));
   process.exit(code);
 }
 
@@ -375,33 +378,48 @@ const realOrSelf = (file) => { try { return realpathSync(file); } catch { return
 if (process.argv[1] && realOrSelf(process.argv[1]) === realOrSelf(fileURLToPath(import.meta.url))) {
   const args = process.argv.slice(2);
   const options = { platform: process.platform === "win32" ? "win" : "mac", releaseId: "", addon: "", repo: "", dryRun: false };
+  let tier = "";
+  let configName = "right-release.config.mjs";
   for (let index = 0; index < args.length; index += 1) {
     if (args[index] === "--platform") options.platform = args[++index];
     else if (args[index] === "--release") options.releaseId = args[++index];
     else if (args[index] === "--addon") options.addon = args[++index];
     else if (args[index] === "--repo") options.repo = args[++index];
+    else if (args[index] === "--tier") tier = args[++index];
+    else if (args[index].startsWith("--tier=")) tier = args[index].slice("--tier=".length);
+    else if (args[index] === "--config") configName = args[++index];
     else if (args[index] === "--dry-run") options.dryRun = true;
     else if (args[index] === "-h" || args[index] === "--help") usage(0);
     else throw new Error(`unknown argument: ${args[index]}`);
   }
   if (Boolean(options.releaseId) === Boolean(options.addon)) usage(2);
-  const repoRoot = runCommand("git", ["rev-parse", "--show-toplevel"]);
+  if (options.addon && (tier || configName !== "right-release.config.mjs")) throw new Error("--tier and --config apply to --release only; an add-on takes its configuration from --addon");
   let plan;
   if (options.addon) {
+    const repoRoot = runCommand("git", ["rev-parse", "--show-toplevel"]);
     const configPath = path.resolve(options.addon);
     const config = (await import(`${pathToFileURL(configPath).href}?github=${Date.now()}`)).default;
     options.repo ||= config.distribution?.repository ?? "";
     if (config.distribution?.provider !== "github-releases") throw new Error("add-on config must select github-releases distribution");
     plan = prepareGitHubAddonRelease({ repoRoot, config, configRoot: path.dirname(configPath), ...options });
   } else {
-    options.repo ||= repositoryFromRemote(repoRoot);
+    // A sealed installer release has one authorization, shared with `right-release upload`: an explicit tier, the
+    // primary checkout, a clean tree, a sealed commit equal to HEAD, ownership evidence, and the configured
+    // github-releases provider and repository. It finishes before any plan is built or any gh call is made.
+    const { authorizeGitHubUpload } = await import("./github-upload-gate.mjs");
+    let authority;
+    try {
+      authority = await authorizeGitHubUpload({ command: "right-release github", tier, releaseId: options.releaseId, platform: options.platform, configName, repo: options.repo });
+    } catch (error) {
+      console.error(`right-release github: ${error.message}`);
+      process.exit(1);
+    }
+    options.repo = authority.repo;
     // Hardening step 4: the direct GitHub lane is a publication path too; installed QA is recorded like `upload` does, never enforced.
     if (!options.dryRun) {
-      const sealed = verifySealedRelease(path.join(repoRoot, ".right-release", "sealed", options.releaseId, options.platform === "win" ? "windows" : "mac"));
-      const configPath = path.resolve("right-release.config.mjs");
-      admitInstalledQa({ repoRoot, manifest: sealed.manifest, platform: options.platform, configName: "right-release.config.mjs", releaseConfigSha256: existsSync(configPath) ? createHash("sha256").update(readFileSync(configPath)).digest("hex") : undefined }, { provider: "github-releases" });
+      admitInstalledQa({ repoRoot: authority.repoRoot, manifest: authority.sealed.manifest, platform: options.platform, configName: path.relative(process.cwd(), authority.configPath) || configName, releaseConfigSha256: sha256(authority.configPath) }, { provider: "github-releases" });
     }
-    plan = prepareGitHubRelease({ repoRoot, ...options });
+    plan = prepareGitHubRelease({ repoRoot: authority.repoRoot, releaseId: options.releaseId, platform: options.platform, repo: options.repo });
   }
   const result = publishGitHubRelease(plan, options);
   console.log(`right-release github: ${result.status} ${result.tag}`);

package/github-upload-gate.mjs

@@ -0,0 +1,84 @@
+// Authorization shared by every command that can send a sealed installer release to GitHub Releases.
+//
+// `right-release upload` (alias `publish`) and `right-release github --release` both end in
+// publishGitHubRelease(). Each calls authorizeGitHubUpload() before it plans or contacts GitHub, so the
+// rules below exist once:
+//   - an explicit tier, patch or update, never inferred;
+//   - the primary checkout, a clean tree, and a sealed release built from the current HEAD;
+//   - sealed ownership evidence that still matches the committed source;
+//   - an explicit distribution.provider of github-releases and a distribution.repository, with any --repo
+//     argument required to equal it (the origin remote is never consulted).
+// Order matters: the release config is a module that runs on import, so it is loaded only after the tree is
+// proven clean and the sealed commit equals HEAD.
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { spawnSync } from "./background-process.mjs";
+import { verifyOwnershipEvidence } from "./ownership-evidence.mjs";
+import { assertPrimaryReleaseCheckout } from "./release-invocation.mjs";
+import { verifySealedRelease } from "./release-state.mjs";
+import { assertCleanSource } from "./source-gate.mjs";
+
+/** Throws unless the operator named a tier. There is no default and no inference from the version or the notes. */
+export function assertUploadTier(tier) {
+  if (tier !== "patch" && tier !== "update") throw new Error("tier is required (patch|update)");
+  return tier;
+}
+
+/**
+ * Returns the GitHub repository a release config publishes to, or throws.
+ * `requestedRepo` is an optional command-line `--repo`; it may only restate the configured repository.
+ */
+export function resolveGitHubDistribution(releaseConfig, requestedRepo = "") {
+  if (releaseConfig?.distribution?.provider !== "github-releases") {
+    throw new Error("release config distribution.provider must be github-releases");
+  }
+  const configuredRepo = releaseConfig?.distribution?.repository ?? "";
+  if (!configuredRepo) throw new Error("release config distribution.repository is required for github-releases");
+  if (requestedRepo && requestedRepo !== configuredRepo) throw new Error(`--repo must match configured distribution.repository (${configuredRepo})`);
+  return configuredRepo;
+}
+
+/**
+ * Runs every local check that must pass before a sealed release may be planned for GitHub. Performs no network
+ * call and writes nothing. Resolves with the verified inputs the caller needs; throws an Error on the first refusal.
+ */
+export async function authorizeGitHubUpload({
+  command = "right-release upload",
+  tier,
+  releaseId,
+  platform,
+  configName = "right-release.config.mjs",
+  repo = "",
+  cwd = process.cwd(),
+}) {
+  assertUploadTier(tier);
+  if (!releaseId) throw new Error("--release is required");
+  if (platform !== "win" && platform !== "mac") throw new Error("--platform must be win or mac");
+
+  const repoRoot = git(cwd, ["rev-parse", "--show-toplevel"]);
+  assertPrimaryReleaseCheckout(repoRoot);
+  const candidateCommit = git(repoRoot, ["rev-parse", "HEAD"]);
+  assertCleanSource({
+    status: git(repoRoot, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]),
+    commandId: command,
+  });
+  const platformDir = platform === "win" ? "windows" : "mac";
+  const sealed = verifySealedRelease(path.join(repoRoot, ".right-release", "sealed", releaseId, platformDir));
+  if (sealed.manifest.commit !== candidateCommit) throw new Error("sealed release was built from a different commit than the current checkout");
+
+  const configPath = path.resolve(cwd, configName);
+  if (!existsSync(configPath)) throw new Error(`release config is required: ${configName}`);
+  const releaseConfig = (await import(`${pathToFileURL(configPath).href}?upload=${Date.now()}`)).default;
+  const ownership = verifyOwnershipEvidence(sealed.manifest.ownershipEvidence, repoRoot, path.dirname(configPath));
+  if (!ownership.ok) throw new Error(`sealed ownership evidence rejected: ${ownership.reason}`);
+  const configuredRepo = resolveGitHubDistribution(releaseConfig, repo);
+
+  return { repoRoot, platformDir, sealed, configPath, releaseConfig, repo: configuredRepo };
+}
+
+function git(cwd, runArgs) {
+  const result = spawnSync("git", runArgs, { cwd, encoding: "utf8", windowsHide: true });
+  if (result.status !== 0) throw new Error(`git ${runArgs.join(" ")} failed: ${result.stderr}`);
+  return result.stdout.trim();
+}

package/hardeningscan.mjs

@@ -4,6 +4,7 @@ import { createReadStream, readFileSync, realpathSync } from "node:fs";
 import { lstat, readdir } from "node:fs/promises";
 import path from "node:path";
 import { HARDENING_RULES } from "./hardening-evidence.mjs";
+import { QA_CONTROL_MARKER } from "./qa-control-scan.mjs";
 
 const rawArgs = process.argv.slice(2);
 if (rawArgs.length === 0 || rawArgs.includes("-h") || rawArgs.includes("--help")) {
@@ -68,6 +69,8 @@ const contentRules = [
   ["secret-env-name", /OPENAI_API_KEY|ANTHROPIC_API_KEY|APPLE_PASSWORD|NOTARY_PROFILE/gi, "secret/env key name leaked"],
   ["gpl-flag", /--enable-gpl|--enable-nonfree/gi, "GPL/nonfree ffmpeg flag leaked"],
   ["stale-model", /tdt_w15_p6/gi, "stale TDT p6 string leaked"],
+  // Not allowable through hardening evidence: a shipped artifact never contains the QA control server.
+  ["qa-control-marker", new RegExp(QA_CONTROL_MARKER, "g"), "QA control server shipped (rightkit-qa-driver qa-control)"],
   ["experiment-model", /Canary-Qwen|Nemotron|dqlstm|bias-experiments/gi, "experiment/model-history marker leaked"],
 ];
 

package/inventory-check.mjs

@@ -24,11 +24,11 @@ const CACHE_TTL_MS = 60 * 60 * 1000;
 const CONCURRENCY = 8;
 const REQUEST_TIMEOUT_MS = 15_000;
 const CRATES_API_INTERVAL_MS = 1000;
-const USER_AGENT = "rightkit-inventory-check/1 (+https://github.com/bogusyogi/rightkit)";
+const USER_AGENT = "rightkit-inventory-check/1 (+https://github.com/Orthic-Labs/rightkit)";
 const EXCLUDED_PREFIX = "build-control-";
 const OWNER_PROBE_CRATE = "rightkit-fs";
-const EXTRA_ACCOUNT_CRATES = Object.freeze(["agent-room-core"]);
-const SWIFT_REPO = "bogusyogi/rightkit-swift";
+const EXTRA_ACCOUNT_CRATES = Object.freeze([]);
+const SWIFT_REPO = "Orthic-Labs/rightkit"; // RightKitSwift is tagged on the public repository itself
 const SWIFT_KEY = "rightkit-swift";
 const SWIFT_NAME = "RightKitSwift";
 const SKIP_DIRS = new Set(["node_modules", ".git", "target", "dist", "build", ".cache"]);
@@ -628,7 +628,7 @@ async function checkThirdParty({ repoRoot, records, live, findings }) {
   for (const { where, manifest } of cargoSources) {
     if (!manifest) continue;
     for (const dep of cargoDeclarations(manifest)) {
-      if (internalCargo.has(dep.name) || dep.name.startsWith("rightkit-") || dep.name.startsWith("agent-room")) continue;
+      if (internalCargo.has(dep.name) || dep.name.startsWith("rightkit-")) continue;
       add("cargo", dep.name, dep.req, where);
     }
   }

package/mac-bundle-signing.mjs

@@ -6,7 +6,7 @@ import { discoverNestedCode } from "./swift-mac-app.mjs";
 
 const fail = (message) => Object.assign(new Error(message), { code: "MAC_SIGN_ENTRY_INVALID" });
 
-function mainExecutableName(app) {
+export function mainExecutableName(app) {
   try {
     const plist = readFileSync(path.join(app, "Contents", "Info.plist"), "utf8");
     const match = /<key>CFBundleExecutable<\/key>\s*<string>([^<]+)<\/string>/.exec(plist);

package/mac-sign-core.mjs

@@ -0,0 +1,97 @@
+// Signing loop for sign-macos.mjs, separated from the CLI so tests can drive it with a fake signer.
+// One entry = one codesign invocation, in the given order (the caller orders inside-out).
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileEvidence } from "./macos-file-evidence.mjs";
+import { CODESIGN_OPTION_FLAGS } from "./mac-signing-matrix.mjs";
+
+export const SIGN_MANIFEST_SCHEMA = 1;
+
+/** `--options` value: hardened runtime first (unless disabled), then the extra names. */
+export function codesignOptionsValue({ hardenedRuntime = true, options = [] } = {}) {
+  return [...(hardenedRuntime ? ["runtime"] : []), ...options.filter((item) => item !== "runtime")].join(",");
+}
+
+const IDENTIFIER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9.-]{0,254}$/;
+
+/** A codesign `--identifier` value: reverse-DNS characters (letters, digits, `.`, `-`), no spaces, no leading dash. Returns it, or throws. */
+export function validateCodesignIdentifier(identifier, label = "codesign identifier") {
+  if (typeof identifier !== "string" || !IDENTIFIER_PATTERN.test(identifier)) {
+    throw Object.assign(new Error(`${label} must be 1-255 characters of letters, digits, '.' and '-', starting with a letter or digit: ${JSON.stringify(identifier)}`), { code: "MAC_SIGN_IDENTIFIER_INVALID" });
+  }
+  return identifier;
+}
+
+/**
+ * codesign argv for one entry. With no entitlements/options/identifier it is the historical `--force --options runtime --timestamp --sign <id> <file>`.
+ * An optional `identifier` adds `--identifier <id>` between `--timestamp` and `--sign`.
+ */
+export function macCodesignArgs({ file, identity, entitlements, hardenedRuntime, options, identifier }) {
+  const flags = codesignOptionsValue({ hardenedRuntime, options });
+  if (identifier !== undefined) validateCodesignIdentifier(identifier);
+  return ["--force", ...(flags ? ["--options", flags] : []), "--timestamp",
+    ...(identifier !== undefined ? ["--identifier", identifier] : []), "--sign", identity,
+    ...(entitlements ? ["--entitlements", path.resolve(entitlements)] : []), file];
+}
+
+/** Parse the JSON manifest release.mjs writes for a signing step with per-file settings. */
+export function parseSignManifest(text) {
+  let manifest;
+  try { manifest = JSON.parse(text); } catch { throw new Error("signing manifest is not valid JSON"); }
+  if (manifest?.schema !== SIGN_MANIFEST_SCHEMA || !Array.isArray(manifest.entries) || !manifest.entries.length) throw new Error(`signing manifest must be { schema: ${SIGN_MANIFEST_SCHEMA}, entries: [...] } with at least one entry`);
+  return manifest.entries.map((entry, index) => {
+    const label = `signing manifest entry ${index}`;
+    if (!entry || typeof entry.file !== "string" || !path.isAbsolute(entry.file)) throw new Error(`${label}: file must be an absolute path`);
+    if (entry.entitlements !== undefined && (typeof entry.entitlements !== "string" || !path.isAbsolute(entry.entitlements))) throw new Error(`${label}: entitlements must be an absolute path`);
+    if (entry.options !== undefined && (!Array.isArray(entry.options) || entry.options.some((item) => !CODESIGN_OPTION_FLAGS.includes(item)))) throw new Error(`${label}: options must be codesign option names (${CODESIGN_OPTION_FLAGS.join(", ")})`);
+    if (entry.hardenedRuntime !== undefined && typeof entry.hardenedRuntime !== "boolean") throw new Error(`${label}: hardenedRuntime must be a boolean`);
+    if (entry.identifier !== undefined) validateCodesignIdentifier(entry.identifier, `${label}: identifier`);
+    return { file: entry.file, ...(entry.identifier !== undefined ? { identifier: entry.identifier } : {}), ...(entry.entitlements ? { entitlements: entry.entitlements } : {}), hardenedRuntime: entry.hardenedRuntime ?? true, options: entry.options ?? [] };
+  });
+}
+
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * Sign, verify and record evidence for each entry. Throws Error(message) on the first failure.
+ * Injectable: signOne(args) -> spawn-style result, inspect(cmd, args) -> output string (throws on failure),
+ * evidence(file), hashFile(file).
+ * Optional per-file identifiers: `identifiers` is a map from bundle-relative path (resolved against `bundle`; the bundle itself is `.`) to a codesign
+ * identifier, or a function (relativePath, entry) -> identifier | undefined. An entry's own `identifier` wins; with neither,
+ * no `--identifier` is passed. Every identifier is validated before anything is signed.
+ */
+export function signMacosEntries(entries, { identity, signOne, inspect, evidence = fileEvidence, hashFile = (file) => fileEvidence(file).sha256, identifiers, bundle }) {
+  const planned = entries.map((entry) => {
+    const relative = bundle ? path.relative(bundle, entry.file).split(path.sep).join("/") || "." : entry.file;
+    const mapped = typeof identifiers === "function" ? identifiers(relative, entry) : identifiers ? Object.hasOwn(identifiers, relative) ? identifiers[relative] : undefined : undefined;
+    const identifier = entry.identifier ?? mapped;
+    if (identifier !== undefined) validateCodesignIdentifier(identifier, `identifier for ${relative}`);
+    return identifier === undefined ? entry : { ...entry, identifier };
+  });
+  const records = [];
+  for (const entry of planned) {
+    const before = evidence(entry.file);
+    const signed = signOne(macCodesignArgs({ ...entry, identity }));
+    if (!signed || signed.error || signed.status !== 0) throw new Error(`codesign failed: ${signed?.stderr ?? signed?.error?.message ?? signed?.status}`);
+    const verification = inspect("codesign", ["--verify", "--strict", "--verbose=4", entry.file]);
+    const details = inspect("codesign", ["-dvv", entry.file]);
+    if (!/valid on disk/i.test(verification) || !/satisfies its designated requirement/i.test(verification)) {
+      throw new Error(`strict codesign verification failed for ${entry.file}`);
+    }
+    if (!new RegExp(`^Authority=${escapeRegExp(identity)}$`, "m").test(details) && !details.includes(`Authority=${identity}`)) {
+      throw new Error(`codesign identity mismatch for ${entry.file}: expected ${identity}`);
+    }
+    const record = { file: entry.file, before, after: evidence(entry.file), codesign: "strict-valid", identity, timestampPresent: /(?:Timestamp|Signed Time)[=:]/i.test(details) };
+    if (!record.timestampPresent) throw new Error(`Developer ID timestamp is missing for ${entry.file}`);
+    record.codesignOptions = codesignOptionsValue(entry);
+    if (entry.identifier !== undefined) {
+      if (!details.includes(`Identifier=${entry.identifier}\n`)) throw new Error(`codesign identifier mismatch for ${entry.file}: expected ${entry.identifier}`);
+      record.identifier = entry.identifier;
+    }
+    if (entry.entitlements) record.entitlements = { file: path.resolve(entry.entitlements), sha256: hashFile(entry.entitlements) };
+    records.push(record);
+  }
+  return records;
+}
+
+export const readSignManifest = (file) => parseSignManifest(readFileSync(file, "utf8"));

package/mac-signing-matrix.mjs

@@ -0,0 +1,186 @@
+// Per-file macOS signing matrix for `sign.prePackageFiles[]` object entries and `sign.nestedCode`.
+//
+//   sign: {
+//     prePackageFiles: ["dist/tool", { file: "dist/App.app", entitlements: "release/app.entitlements.plist" }],
+//     nestedCode: { "Contents/Helpers/Helper": { options: ["library"] },
+//                   "Contents/PlugIns/Ext.appex": { entitlements: "release/ext.entitlements.plist" } },
+//   }
+//
+// This module owns the config shape (validation, fail-early at `right-release doctor`) and the
+// inside-out plan. It never runs codesign: sign-macos.mjs (via mac-sign-core.mjs) executes the plan.
+import { existsSync, lstatSync, openSync, closeSync, readSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import { expandMacSigningEntries, mainExecutableName } from "./mac-bundle-signing.mjs";
+
+const invalid = (message) => Object.assign(new Error(message), { code: "MAC_SIGN_CONFIG_INVALID" });
+
+/** codesign `--options` names accepted in `options[]` (man codesign, OPTION FLAGS). `runtime` is always on. */
+export const CODESIGN_OPTION_FLAGS = Object.freeze(["expires", "hard", "host", "kill", "library", "runtime"]);
+const ENTRY_KEYS = new Set(["file", "entitlements", "hardenedRuntime", "options"]);
+const SETTING_KEYS = new Set(["entitlements", "hardenedRuntime", "options"]);
+
+const isPlainObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+
+/** Plist sniff: XML plists contain `<plist`, binary plists start with `bplist00`. Catches wrong or empty files. */
+function looksLikePlist(file) {
+  const fd = openSync(file, "r");
+  try {
+    const buffer = Buffer.alloc(4096);
+    const length = readSync(fd, buffer, 0, buffer.length, 0);
+    const head = buffer.subarray(0, length);
+    return head.subarray(0, 8).toString("latin1") === "bplist00" || head.toString("utf8").includes("<plist");
+  } finally { closeSync(fd); }
+}
+
+function validateSettings(settings, label, { root, errors, isFile }) {
+  const out = { entitlements: undefined, hardenedRuntime: true, options: [] };
+  if (settings.entitlements !== undefined) {
+    const value = settings.entitlements;
+    if (typeof value !== "string" || !value.trim()) errors.push(`${label}.entitlements must be a non-empty path string`);
+    else if (path.isAbsolute(value) || /^[A-Za-z]:/.test(value)) errors.push(`${label}.entitlements must be relative to the release config directory: ${value}`);
+    else {
+      const resolved = path.resolve(root, value);
+      const relative = path.relative(root, resolved);
+      if (relative.startsWith("..") || path.isAbsolute(relative)) errors.push(`${label}.entitlements must stay inside the release config directory: ${value}`);
+      else if (!isFile(resolved)) errors.push(`${label}.entitlements file not found: ${value}`);
+      else if (!looksLikePlist(resolved)) errors.push(`${label}.entitlements is not a property list (expected an XML or binary plist): ${value}`);
+      else out.entitlements = resolved;
+    }
+  }
+  if (settings.hardenedRuntime !== undefined) {
+    if (typeof settings.hardenedRuntime !== "boolean") errors.push(`${label}.hardenedRuntime must be a boolean`);
+    else if (settings.hardenedRuntime === false) errors.push(`${label}.hardenedRuntime: false is not allowed: macOS Developer ID signing is notarized and notarization rejects code without the hardened runtime (omit the field; it defaults to true)`);
+  }
+  if (settings.options !== undefined) {
+    if (!Array.isArray(settings.options) || settings.options.some((item) => typeof item !== "string")) errors.push(`${label}.options must be an array of codesign --options names`);
+    else {
+      const seen = new Set();
+      for (const item of settings.options) {
+        if (!CODESIGN_OPTION_FLAGS.includes(item)) errors.push(`${label}.options: unsupported codesign option ${JSON.stringify(item)} (allowed: ${CODESIGN_OPTION_FLAGS.join(", ")})`);
+        else if (seen.has(item)) errors.push(`${label}.options: duplicate option ${JSON.stringify(item)}`);
+        seen.add(item);
+      }
+      out.options = settings.options.filter((item) => item !== "runtime");
+    }
+  }
+  return out;
+}
+
+function validateNestedKey(key) {
+  if (!key.trim() || key !== key.trim()) return "must be a non-empty path without surrounding whitespace";
+  if (key.includes("\0") || key.includes("\\")) return "must use forward slashes and no NUL";
+  if (path.posix.isAbsolute(key) || /^[A-Za-z]:/.test(key)) return "must be relative to the .app bundle";
+  const segments = key.split("/");
+  if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) return "must not contain empty, '.' or '..' segments or a trailing slash";
+  if (segments[0] !== "Contents" || segments.length < 2) return "must name code inside the bundle, starting with Contents/";
+  return null;
+}
+
+/**
+ * Validate and normalize `sign` for a macOS target. Collects every problem, then throws one
+ * MAC_SIGN_CONFIG_INVALID error. Returns { entries, nestedCode } where
+ *   entries:    [{ file, entitlements?: absolute, options: [] }]   (file stays as declared)
+ *   nestedCode: [{ key, entitlements?: absolute, options: [] }]
+ * Injectable: isFile.
+ */
+export function validateMacSigningConfig(sign, { root, isFile = (file) => existsSync(file) && statSync(file).isFile() } = {}) {
+  const errors = [];
+  const entries = [];
+  const nestedCode = [];
+  if (!isPlainObject(sign)) throw invalid("sign must be an object");
+  const context = { root: path.resolve(root), errors, isFile };
+  if (!Array.isArray(sign.prePackageFiles) || !sign.prePackageFiles.length) errors.push("sign.prePackageFiles must be a non-empty array");
+  else {
+    const seen = new Set();
+    sign.prePackageFiles.forEach((entry, index) => {
+      const label = `sign.prePackageFiles[${index}]`;
+      let file;
+      let settings = {};
+      if (typeof entry === "string") file = entry;
+      else if (isPlainObject(entry)) {
+        for (const key of Object.keys(entry)) if (!ENTRY_KEYS.has(key)) errors.push(`${label}: unknown key ${JSON.stringify(key)} (allowed: ${[...ENTRY_KEYS].join(", ")})`);
+        file = entry.file;
+        settings = entry;
+      } else { errors.push(`${label} must be a path string or { file, entitlements?, hardenedRuntime?, options? }`); return; }
+      if (typeof file !== "string" || !file.trim()) { errors.push(`${label}.file must be a non-empty path string`); return; }
+      if (seen.has(file)) errors.push(`${label}: duplicate signing entry ${file}`);
+      seen.add(file);
+      const normalized = validateSettings(settings, label, context);
+      entries.push({ file, ...(normalized.entitlements ? { entitlements: normalized.entitlements } : {}), options: normalized.options });
+    });
+  }
+  if (sign.nestedCode !== undefined) {
+    if (!isPlainObject(sign.nestedCode)) errors.push("sign.nestedCode must be an object keyed by path inside the .app bundle");
+    else {
+      for (const [key, settings] of Object.entries(sign.nestedCode)) {
+        const label = `sign.nestedCode[${JSON.stringify(key)}]`;
+        const keyProblem = validateNestedKey(key);
+        if (keyProblem) errors.push(`${label}: key ${keyProblem}`);
+        if (!isPlainObject(settings)) { errors.push(`${label} must be an object { entitlements?, hardenedRuntime?, options? }`); continue; }
+        for (const name of Object.keys(settings)) if (!SETTING_KEYS.has(name)) errors.push(`${label}: unknown key ${JSON.stringify(name)} (allowed: ${[...SETTING_KEYS].join(", ")})`);
+        const normalized = validateSettings(settings, label, context);
+        nestedCode.push({ key, ...(normalized.entitlements ? { entitlements: normalized.entitlements } : {}), options: normalized.options });
+      }
+      if (nestedCode.length) {
+        const apps = entries.filter((entry) => /\.app\/?$/.test(entry.file));
+        if (apps.length !== 1) errors.push(`sign.nestedCode needs exactly one .app entry in sign.prePackageFiles to resolve its paths against (found ${apps.length})`);
+      }
+    }
+  }
+  if (errors.length) throw invalid(`invalid macOS signing configuration:\n${errors.map((line) => `- ${line}`).join("\n")}`);
+  return { entries, nestedCode };
+}
+
+/** True when an entry or nested item carries anything beyond the default (hardened runtime, no entitlements). */
+export const hasNonDefaultSettings = (item) => Boolean(item.entitlements) || (item.options?.length ?? 0) > 0;
+
+const depth = (file) => file.split(path.sep).length;
+
+/**
+ * Inside-out signing plan for a macOS target.
+ *   entries:    [{ file: absolute, entitlements?, options }]  top-level signing entries, in declared order
+ *   nestedCode: validated `sign.nestedCode` items (paths relative to the single .app entry)
+ * Returns { nested, top }: `nested` is every nested code item of each .app entry, deepest first,
+ * defaults unless named by nestedCode; `top` is the entries themselves. Fails (before any signing) when
+ * a nestedCode path is missing, is a symlink, escapes the bundle, or names the bundle's main executable.
+ * Injectable: expand, lstat, realpath, mainName.
+ */
+export function planMacSigning({ entries, nestedCode = [], expand = expandMacSigningEntries, lstat = lstatSync, realpath = realpathSync, mainName = mainExecutableName }) {
+  const { nested: discovered } = expand(entries.map((entry) => entry.file));
+  const byPath = new Map(discovered.map((file) => [file, { file, options: [] }]));
+  if (nestedCode.length) {
+    const app = entries.find((entry) => /\.app\/?$/.test(entry.file));
+    if (!app) throw invalid("sign.nestedCode requires an .app entry in sign.prePackageFiles");
+    const appReal = realpath(app.file);
+    const mainReal = path.join(appReal, "Contents", "MacOS", mainName(app.file));
+    for (const item of nestedCode) {
+      const label = `sign.nestedCode[${JSON.stringify(item.key)}]`;
+      const file = path.join(app.file, ...item.key.split("/"));
+      let info;
+      try { info = lstat(file); } catch { throw invalid(`${label}: not found inside ${app.file}`); }
+      if (info.isSymbolicLink()) throw invalid(`${label}: symlinks cannot be signed; name the real file`);
+      const real = realpath(file);
+      if (real !== appReal && !real.startsWith(appReal + path.sep)) throw invalid(`${label}: resolves outside the bundle`);
+      if (real === mainReal) throw invalid(`${label}: the main executable is signed with the bundle; set entitlements on its sign.prePackageFiles entry`);
+      byPath.set(file, { file, ...(item.entitlements ? { entitlements: item.entitlements } : {}), options: item.options });
+    }
+  }
+  const nested = [...byPath.values()].sort((a, b) => depth(b.file) - depth(a.file) || a.file.localeCompare(b.file));
+  return { nested, top: entries };
+}
+
+/** Receipt-side check: every entry's recorded entitlements digest and options match the plan. */
+export function matrixReceiptProblems(evidenceFiles, entries, hashFile) {
+  const problems = [];
+  const byFile = new Map((evidenceFiles ?? []).map((item) => [path.resolve(item.file), item]));
+  for (const entry of entries) {
+    const item = byFile.get(path.resolve(entry.file));
+    if (!item) { problems.push(`missing receipt entry for ${entry.file}`); continue; }
+    const wantOptions = ["runtime", ...(entry.options ?? [])].join(",");
+    if ((item.codesignOptions ?? "runtime") !== wantOptions) problems.push(`${entry.file}: signed with options ${item.codesignOptions ?? "runtime"}, expected ${wantOptions}`);
+    if (entry.entitlements) {
+      if (item.entitlements?.sha256 !== hashFile(entry.entitlements)) problems.push(`${entry.file}: receipt entitlements digest does not match ${entry.entitlements}`);
+    } else if (item.entitlements) problems.push(`${entry.file}: signed with entitlements the plan did not declare`);
+  }
+  return problems;
+}

package/msix-appinstaller.mjs

@@ -12,12 +12,15 @@ export function generateAppInstaller(o) {
   if (!o.name || !o.publisher) errors.push("name and publisher are required");
   const hours = o.hoursBetweenUpdateChecks ?? 24;
   if (!Number.isInteger(hours) || hours < 0 || hours > 255) errors.push("hoursBetweenUpdateChecks must be an integer 0-255");
+  if (o.updateBlocksActivation && !o.showPrompt) errors.push("updateBlocksActivation requires showPrompt: true (App Installer schema)");
+  if (o.automaticBackgroundTask !== undefined && typeof o.automaticBackgroundTask !== "boolean") errors.push("automaticBackgroundTask must be a boolean");
   if (errors.length) throw fail(errors.join("; "));
   return `<?xml version="1.0" encoding="utf-8"?>
 <AppInstaller xmlns="http://schemas.microsoft.com/appx/appinstaller/2018" Version="${xml(o.version)}" Uri="${xml(o.uri)}">
   <MainPackage Name="${xml(o.name)}" Publisher="${xml(o.publisher)}" Version="${xml(o.version)}" ProcessorArchitecture="${o.architecture}" Uri="${xml(o.msixUri)}" />
   <UpdateSettings>
-    <OnLaunch HoursBetweenUpdateChecks="${hours}" ShowPrompt="${o.showPrompt ? "true" : "false"}" UpdateBlocksActivation="${o.updateBlocksActivation ? "true" : "false"}" />
+    <OnLaunch HoursBetweenUpdateChecks="${hours}" ShowPrompt="${o.showPrompt ? "true" : "false"}" UpdateBlocksActivation="${o.updateBlocksActivation ? "true" : "false"}" />${o.automaticBackgroundTask === false ? "" : `
+    <AutomaticBackgroundTask />`}
   </UpdateSettings>
 </AppInstaller>
 `;

package/msix-config.mjs

@@ -12,7 +12,7 @@
 //     virtualization: { fileSystemWrite: "enabled|disabled", registryWrite: "enabled|disabled" },  // explicit, required
 //     assets: { storeLogo, square150, square44 },
 //     runtime: { dlls: ["swiftCore.dll", ...], systemDlls?: [], dependencies?: [{ name, minVersion, provides: [] }] },
-//     appInstaller?: { uri, msixUri, out, hoursBetweenUpdateChecks?, showPrompt?, updateBlocksActivation? },
+//     appInstaller?: { uri, msixUri, out, hoursBetweenUpdateChecks?, showPrompt?, updateBlocksActivation? (needs showPrompt), automaticBackgroundTask? (default true) },
 //   },
 //   updater?: { kind: "tauri" | "appinstaller", artifacts: [...] },   // tauri stays the default
 //   installer: { artifacts: [{ file: "<out>.msix", key }] },
@@ -27,6 +27,8 @@ export const updaterKind = (target) => target?.updater?.kind ?? "tauri";
 
 const isHttps = (value) => { try { return new URL(value).protocol === "https:"; } catch { return false; } };
 
+const versionedUri = (value, version) => { try { return decodeURIComponent(new URL(value).pathname).includes(version); } catch { return false; } };
+
 /** Returns an array of human-readable problems (empty when valid). */
 export function validateMsixTarget(target, app = "app") {
   const e = [];
@@ -56,6 +58,8 @@ export function validateMsixTarget(target, app = "app") {
     else {
       if (!isHttps(a.uri)) at("msix.appInstaller.uri must be an https URL");
       if (!isHttps(a.msixUri)) at("msix.appInstaller.msixUri must be an https URL");
+      else if (id.version && !versionedUri(a.msixUri, id.version)) at(`msix.appInstaller.msixUri must contain the package version ${id.version} in its path so each release keeps its own install source`);
+      if (a.updateBlocksActivation && !a.showPrompt) at("msix.appInstaller.updateBlocksActivation requires showPrompt: true");
       if (!/\.appinstaller$/i.test(a.out ?? "")) at("msix.appInstaller.out must end with .appinstaller");
     }
   }

package/msix-repair-guard.mjs

@@ -0,0 +1,24 @@
+// Canonical MSIX repair guard (W08): the PowerShell script an app writes outside its package so a per-user scheduled task can
+// re-add a package that an interrupted update left `Modified, NeedsRemediation`. This module returns the script text and its
+// SHA-256 so consumers (SwiftRight's SwiftRightBridge embeds a copy) can pin the exact bytes.
+//
+// The script file is stored with LF line endings and ASCII only (see .gitattributes); the hash covers those bytes.
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const MSIX_REPAIR_GUARD_FILE = "msix-repair-guard.ps1";
+export const MSIX_REPAIR_GUARD_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), MSIX_REPAIR_GUARD_FILE);
+
+export function msixRepairGuardSha256(text) {
+  return createHash("sha256").update(Buffer.from(String(text).replace(/\r\n/g, "\n"), "utf8")).digest("hex");
+}
+
+/** The guard script, its SHA-256 (hex, over the LF-normalised bytes) and the guard protocol version it declares. */
+export function msixRepairGuard() {
+  const text = readFileSync(MSIX_REPAIR_GUARD_PATH, "utf8").replace(/\r\n/g, "\n");
+  const match = /^\$GuardVersion = (\d+)$/m.exec(text);
+  if (!match) throw new Error("msix-repair-guard.ps1 declares no $GuardVersion");
+  return { file: MSIX_REPAIR_GUARD_FILE, text, sha256: msixRepairGuardSha256(text), guardVersion: Number(match[1]) };
+}