@hellolynk-ai/codex-plugin 0.2.102 → 0.2.103

package/plugins/hellolynk-codex/runtime/core/hellolynk-client-account.mjs

@@ -68,7 +68,7 @@ export function withClientAccountLock(client, root, operation) {
 
 export function createClientAccountActions(options) {
   const client = options?.client;
-  const root = options?.storeRoot || defaultNeutralHostStoreRoot("win32", options?.env || process.env);
+  const root = options?.storeRoot || defaultNeutralHostStoreRoot(process.platform, options?.env || process.env);
   statePath(client, clientAccountBaseRoot(root));
   const readAccountState = () => {
     const state = readClientAccount(client, root);

package/plugins/hellolynk-codex/runtime/core/hellolynk-client-update-entry.mjs

@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { clientAccountBaseRoot } from "./hellolynk-client-account.mjs";
 import { startClientUpdateRuntime } from "./hellolynk-client-update-runtime.mjs";
+import { clientUpdateCatalogId, MAC_CLIENT_VERSION } from "./hellolynk-client-update.mjs";
 
 const running = new Map();
 
@@ -9,7 +10,9 @@ const running = new Map();
 // to the Host. A checkout or an uninstalled test fixture never self-updates.
 export function startInstalledClientUpdate(options = {}) {
   const { client, packageRoot, storeRoot } = options;
-  if (process.platform !== "win32" || !path.isAbsolute(String(packageRoot || ""))) return Promise.resolve(null);
+  const catalogId = clientUpdateCatalogId(client, process.platform);
+  const mac = process.platform === "darwin";
+  if (!catalogId || (mac && process.arch !== "arm64") || !path.isAbsolute(String(packageRoot || ""))) return Promise.resolve(null);
   let baseRoot;
   try { baseRoot = clientAccountBaseRoot(storeRoot); } catch { return Promise.resolve(null); }
   const key = `${client}\0${path.resolve(packageRoot)}\0${baseRoot}`;
@@ -21,8 +24,9 @@ export function startInstalledClientUpdate(options = {}) {
     const metadata = await fs.lstat(packageFile);
     if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.nlink !== 1 || metadata.size > 64 * 1024) return null;
     const manifest = JSON.parse(await fs.readFile(packageFile, "utf8"));
-    if (manifest.hellolynkClient?.client !== client
-      || !/^\d+\.\d+\.\d+$/.test(manifest.version || "")) return null;
+    const version = mac ? MAC_CLIENT_VERSION : /^\d+\.\d+\.\d+$/u;
+    if (manifest.hellolynkClient?.client !== client || !version.test(manifest.version || "")
+      || (mac && (manifest.os?.[0] !== "darwin" || manifest.cpu?.[0] !== "arm64"))) return null;
     return startClientUpdateRuntime({
       root: baseRoot, client, currentVersion: manifest.version,
       installContext: { ...options.installContext, packageRoot: path.resolve(packageRoot) },

package/plugins/hellolynk-codex/runtime/core/hellolynk-client-update-runtime.mjs

@@ -4,7 +4,8 @@ import os from "node:os";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { createClientUpdateManager, extractClientUpdateArchive, compareClientUpdateVersions, CLIENT_UPDATE_CLIENTS } from "./hellolynk-client-update.mjs";
+import { createClientUpdateManager, extractClientUpdateArchive, compareClientUpdateVersions, clientUpdateCatalogId,
+  CLIENT_UPDATE_CLIENTS, CLIENT_UPDATE_RELEASES, MAC_CLIENT_VERSION } from "./hellolynk-client-update.mjs";
 import { withNeutralHostStoreLock } from "./hellolynk-neutral-host-installation-store.mjs";
 import { readClientAccount } from "./hellolynk-client-account.mjs";
 import runtimeSafety from "./hellolynk-runtime-safety.cjs";
@@ -26,7 +27,7 @@ const RETRY_AFTER_MS = 10 * 60_000;
 // waits only for DSH's lease, and a downloaded update is applied by a worker in
 // the background. Checking the network is always detached.
 export async function startClientUpdateRuntime(options = {}) {
-  if ((options.platform || process.platform) !== "win32") return disabled();
+  if (!clientUpdateCatalogId(options.client, options.platform || process.platform)) return disabled();
   let config;
   try { config = normalize(options); await verifyInstalledContext(config); }
   catch { return disabled(); }
@@ -94,8 +95,8 @@ export async function runClientUpdateWorker(options = {}) {
 function createRuntime(config, options) {
   const { root, client, currentVersion, installContext } = config;
   const directory = path.join(root, "client-updates", client);
-  const statePath = path.join(directory, "runtime.json"), leasePath = path.join(directory, "leases.json"), installedPath = path.join(directory, "installed.json");
-  const manager = createClientUpdateManager({ ...options, root, client, currentVersion });
+  const statePath = path.join(directory, "runtime-v2.json"), leasePath = path.join(directory, "leases.json"), installedPath = path.join(directory, "installed.json");
+  const manager = createClientUpdateManager({ ...options, root, client, currentVersion, platform: config.platform });
   const alive = options.isProcessAlive || processAlive;
   async function gate(operation) {
     await safeDirectory(directory);
@@ -200,7 +201,8 @@ function createRuntime(config, options) {
       const attempted = runtime.sha256 === downloaded.sha256 && !(runtime.stage === "applying" || retryable);
       if (downloaded.stage !== "downloaded" || downloaded.error || attempted) return;
       // A damaged worker record means no known worker.
-      const worker = await readJson(path.join(directory, "worker.json"), null).catch((error) => { if (!damaged(error)) throw error; return null; });
+      const workerPath = path.join(directory, "worker-v2.json");
+      const worker = await readJson(workerPath, null).catch((error) => { if (!damaged(error)) throw error; return null; });
       if (worker?.client === client && Number.isSafeInteger(worker.pid) && alive(worker.pid)) return;
       const launch = options.spawnWorker || launchWorker;
       let pid;
@@ -210,13 +212,13 @@ function createRuntime(config, options) {
       } catch (error) {
         // Retain only this rejected launch attempt, not raw errors or proof of
         // worker absence. Keep an earlier PID's conservative liveness check.
-        await atomicJson(path.join(directory, "worker.json"), { client,
+        await atomicJson(workerPath, { client,
           ...(worker?.client === client && Number.isSafeInteger(worker.pid) ? { pid: worker.pid } : {}),
           sha256: downloaded.sha256, error: "client_update_worker_launch_failed", failedAt: Date.now(),
         }).catch(() => {});
         throw error;
       }
-      await atomicJson(path.join(directory, "worker.json"), { client, pid });
+      await atomicJson(workerPath, { client, pid });
     });
   }
   async function applyPending() {
@@ -236,7 +238,7 @@ function createRuntime(config, options) {
           if (sha(await safeFile(path.join(proof.packageRoot, "hellolynk-client-pack-manifest.json")))
             !== sha(await safeFile(path.join(installContext.packageRoot, "hellolynk-client-pack-manifest.json")))) throw failure("adoption_invalid");
           const doctor = await (options.runInstaller || runInstaller)({ executable: installContext.nodePath || process.execPath,
-            args: [path.join(installContext.packageRoot, "bin", "hellolynk-client-setup.mjs"), "doctor"], cwd: installContext.packageRoot, root, timeoutMs: 180_000 });
+            args: [path.join(installContext.packageRoot, "bin", "hellolynk-client-setup.mjs"), "doctor", "--json"], cwd: installContext.packageRoot, root, timeoutMs: 180_000 });
           if (!doctorProves(doctor, client, currentVersion)) throw failure("adoption_invalid");
           const adoptedRoot = path.join(path.dirname(root), "releases", `${client}-${sha(await safeFile(path.join(proof.packageRoot, "hellolynk-client-pack-manifest.json")))}`);
           if (!options.runInstaller) await verifyPackage(adoptedRoot, client, currentVersion);
@@ -274,7 +276,7 @@ function createRuntime(config, options) {
       try {
         await verifyPackage(packageRoot, client, version);
         const inspected = await run({ executable: installContext.nodePath || process.execPath,
-          args: [path.join(packageRoot, "bin", "hellolynk-client-setup.mjs"), "doctor"], cwd: packageRoot, root, timeoutMs: 180_000 });
+          args: [path.join(packageRoot, "bin", "hellolynk-client-setup.mjs"), "doctor", "--json"], cwd: packageRoot, root, timeoutMs: 180_000 });
         return doctorProves(inspected, client, version);
       } catch { return false; }
     };
@@ -397,7 +399,7 @@ async function prepareCandidate(config, record) {
   const directory = path.join(config.root, "client-updates", config.client);
   if (!HASH.test(record.sha256) || typeof record.version !== "string" || !/^[0-9A-Za-z.+-]{1,100}$/.test(record.version)
     || typeof record.filename !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}\.zip$/.test(record.filename)) throw failure("candidate_invalid");
-  const artifactPath = path.join(directory, "releases", `${record.version}-${record.sha256}`, record.filename);
+  const artifactPath = path.join(directory, CLIENT_UPDATE_RELEASES, `${record.version}-${record.sha256}`, record.filename);
   if (artifactPath !== record.artifactPath) throw failure("candidate_path_invalid");
   const archive = await safeFile(artifactPath, 64 * 1024 * 1024);
   if (archive.length !== record.bytes || sha(archive) !== record.sha256) throw failure("artifact_integrity_invalid");
@@ -406,43 +408,63 @@ async function prepareCandidate(config, record) {
   const extractedRoot = path.join(temporaryRoot, "extracted");
   try {
     // Re-extract the hash-verified archive; never execute a mutable earlier
-    // extractedRoot or an executable path supplied by state.json.
+    // extractedRoot or an executable path supplied by update state.
     const sealed = path.join(temporaryRoot, record.filename);
     await fs.writeFile(sealed, archive, { flag: "wx", mode: 0o600 });
-    await extractClientUpdateArchive({ archivePath: sealed, destination: extractedRoot });
-    let packageRoot;
-    if (config.client === "dsh") {
-      const descriptor = await readJson(path.join(extractedRoot, "trusted-release.json"));
-      const manifestBytes = await safeFile(path.join(extractedRoot, "dist", "package", "hellolynk-dsh-nav-build.json"));
-      if (descriptor?.contract !== "hellolynk-dsh-nav-release-v1" || descriptor.manifestSha256 !== sha(manifestBytes)) throw failure("package_pin_invalid");
-      const manifest = JSON.parse(manifestBytes.toString("utf8"));
-      if (manifest.contract !== "hellolynk-dsh-nav-build-v3") throw failure("package_pin_invalid");
-      await verifyRecords(path.join(extractedRoot, "dist", "package"), manifest.packageFiles, ["hellolynk-dsh-nav-build.json"]);
-      packageRoot = path.join(extractedRoot, "dist", "package", "runtime", "connect");
-      await safeFile(path.join(extractedRoot, "scripts", "install.mjs"));
-    } else {
-      const candidates = [extractedRoot, path.join(extractedRoot, "package"), path.join(extractedRoot, `hellolynk-${config.client}-${record.version}`, "package")];
-      const matches = [];
-      for (const candidate of candidates) if (await exists(path.join(candidate, "package.json"))) matches.push(candidate);
-      if (matches.length !== 1) throw failure("package_identity_invalid");
-      packageRoot = matches[0];
-    }
-    await verifyPackage(packageRoot, config.client, record.version);
+    await extractClientUpdateArchive({ archivePath: sealed, destination: extractedRoot, platform: config.platform });
+    const { packageRoot } = await verifyExtractedClientUpdatePackage(extractedRoot,
+      { client: config.client, platform: config.platform, version: record.version });
     return { temporaryRoot, extractedRoot, artifactPath: sealed, packageRoot, setupPath: path.join(packageRoot, "bin", "hellolynk-client-setup.mjs") };
   } catch (error) { await fs.rm(temporaryRoot, { recursive: true, force: true }); throw error; }
 }
 
+export async function verifyExtractedClientUpdatePackage(extractedRoot, { client, platform, version }) {
+  if (!CLIENT_UPDATE_CLIENTS.includes(client) || typeof version !== "string" || !VERSION.test(version)) throw failure("package_identity_invalid");
+  let packageRoot;
+  if (client === "dsh") {
+    const descriptor = await readJson(path.join(extractedRoot, "trusted-release.json"));
+    const manifestBytes = await safeFile(path.join(extractedRoot, "dist", "package", "hellolynk-dsh-nav-build.json"));
+    if (descriptor?.contract !== "hellolynk-dsh-nav-release-v1" || descriptor.manifestSha256 !== sha(manifestBytes)) throw failure("package_pin_invalid");
+    const manifest = JSON.parse(manifestBytes.toString("utf8"));
+    if (manifest.contract !== "hellolynk-dsh-nav-build-v3") throw failure("package_pin_invalid");
+    await verifyRecords(path.join(extractedRoot, "dist", "package"), manifest.packageFiles, ["hellolynk-dsh-nav-build.json"]);
+    packageRoot = path.join(extractedRoot, "dist", "package", "runtime", "connect");
+    await safeFile(path.join(extractedRoot, "scripts", "install.mjs"));
+  } else {
+    const id = clientUpdateCatalogId(client, platform) || client;
+    const candidates = [extractedRoot, path.join(extractedRoot, "package"), path.join(extractedRoot, `hellolynk-${id}-${version}`, "package")];
+    const matches = [];
+    for (const candidate of candidates) if (await exists(path.join(candidate, "package.json"))) matches.push(candidate);
+    if (matches.length !== 1) throw failure("package_identity_invalid");
+    packageRoot = matches[0];
+  }
+  const checked = await verifyPackage(packageRoot, client, version);
+  return { packageRoot, ...checked };
+}
+
 async function verifyPackage(root, client, version) {
   const pkg = await readJson(path.join(root, "package.json"));
   const manifestBytes = await safeFile(path.join(root, "hellolynk-client-pack-manifest.json"));
   const pin = await readJson(path.join(root, "hellolynk-client-pack-pin.json"));
   const manifest = JSON.parse(manifestBytes.toString("utf8"));
   if (pkg.version !== version || pkg.hellolynkClient?.client !== client || pkg.name !== NAMES[client]
+    || (MAC_CLIENT_VERSION.test(version) && (!clientUpdateCatalogId(client, "darwin") || pkg.os?.[0] !== "darwin" || pkg.cpu?.[0] !== "arm64"))
     || manifest.contract !== "hellolynk-client-npm-pack-manifest-v1" || manifest.client !== client
     || manifest.packageName !== pkg.name || manifest.version !== version
     || pin.contract !== "hellolynk-client-npm-pack-pin-v1" || pin.manifestSha256 !== sha(manifestBytes)) throw failure("package_identity_invalid");
   await verifyRecords(root, manifest.files, ["hellolynk-client-pack-manifest.json", "hellolynk-client-pack-pin.json"]);
   if (!manifest.files.some((file) => file.path === "bin/hellolynk-client-setup.mjs")) throw failure("package_pin_invalid");
+  if (MAC_CLIENT_VERSION.test(version)) {
+    const helpers = client === "codex"
+      ? ["plugins/hellolynk-codex/runtime/platform/darwin", "plugins/hellolynk-codex/runtime/bootstrap/platform/darwin"]
+      : ["runtime/platform/darwin"];
+    for (const relative of helpers) {
+      const file = `${relative}/hellolynk-keychain-helper.bin`;
+      if (!manifest.files.some(record => record.path === file)
+        || (process.platform !== "win32" && !((await fs.lstat(path.join(root, file))).mode & 0o100))) throw failure("package_pin_invalid");
+    }
+  }
+  return { coreRoot: pkg.hellolynkClient.coreRoot, files: manifest.files };
 }
 async function verifyRecords(root, records, allowedExtra) {
   if (!Array.isArray(records) || records.length < 1 || records.length > 5000) throw failure("package_pin_invalid");
@@ -471,7 +493,9 @@ async function verifyInstalledContext(config) {
   await verifyPackage(context.packageRoot, config.client, config.currentVersion);
 }
 function normalize(value) {
+  const platform = value.platform || process.platform;
   if (!CLIENT_UPDATE_CLIENTS.includes(value.client) || typeof value.currentVersion !== "string" || !VERSION.test(value.currentVersion)
+    || (platform === "darwin" && !MAC_CLIENT_VERSION.test(value.currentVersion))
     || !path.isAbsolute(String(value.root || "")) || !path.isAbsolute(String(value.installContext?.packageRoot || ""))) throw failure("configuration_invalid");
   const context = { packageRoot: path.resolve(value.installContext.packageRoot) };
   for (const name of ["nodePath", "dshProfile", "dshRoot"]) {
@@ -484,7 +508,7 @@ function normalize(value) {
     if (!HASH.test(value.installContext.expectedInstalledManifestSha256)) throw failure("configuration_invalid");
     context.expectedInstalledManifestSha256 = value.installContext.expectedInstalledManifestSha256;
   }
-  return { root: path.resolve(value.root), client: value.client, currentVersion: value.currentVersion, installContext: context };
+  return { root: path.resolve(value.root), client: value.client, currentVersion: value.currentVersion, platform, installContext: context };
 }
 async function launchWorker(config) {
   // A host may execute this module from an ephemeral captured import graph.
@@ -510,8 +534,9 @@ async function launchWorker(config) {
 async function runInstaller({ executable, args, cwd, root, timeoutMs }) {
   executable = await runtimeSafety.resolveHelloLynkStandaloneNode({ preferredExecutable: executable });
   const env = { ...runtimeSafety.standaloneHelloLynkNodeEnvironment(process.env), HELLOLYNK_NEUTRAL_STORE_ROOT: root };
+  const mac = process.platform === "darwin";
   return new Promise((resolve, reject) => {
-    const child = spawn(executable, args, { cwd, env, windowsHide: true, stdio: ["ignore", "pipe", "pipe"], shell: false });
+    const child = spawn(executable, args, { cwd, env, detached: mac, windowsHide: true, stdio: ["ignore", "pipe", "pipe"], shell: false });
     let stdout = "", stderr = "", finished = false, terminalError = null;
     const timer = setTimeout(() => terminate(failure("installer_timeout")), timeoutMs);
     function finish(error, value) { if (finished) return; finished = true; clearTimeout(timer); error ? reject(error) : resolve(value); }
@@ -529,6 +554,9 @@ async function runInstaller({ executable, args, cwd, root, timeoutMs }) {
           killer.on("error", () => { clearTimeout(killTimer); if (!finished) killChild(); });
           killer.once("close", () => { clearTimeout(killTimer); if (!finished) killChild(); });
         } catch { killChild(); }
+      } else if (mac && child.pid) {
+        // The installer owns this process group, including a synchronous Codex CLI.
+        try { process.kill(-child.pid, "SIGKILL"); } catch { killChild(); }
       } else killChild();
     }
     child.on("error", () => {
@@ -580,7 +608,8 @@ function damaged(error) { return error instanceof SyntaxError || error?.code ===
 // Windows paths compare case-insensitively and may differ by a link or short name.
 async function samePath(left, right) {
   if (typeof left !== "string" || typeof right !== "string" || !path.isAbsolute(left) || !path.isAbsolute(right)) return false;
-  const same = (a, b) => path.resolve(a).toLowerCase() === path.resolve(b).toLowerCase();
+  const canonical = (value) => process.platform === "win32" ? path.resolve(value).toLowerCase() : path.resolve(value);
+  const same = (a, b) => canonical(a) === canonical(b);
   if (same(left, right)) return true;
   try { return same(await fs.realpath(left), await fs.realpath(right)); } catch { return false; }
 }

package/plugins/hellolynk-codex/runtime/core/hellolynk-client-update.mjs

@@ -6,20 +6,39 @@ import { withNeutralHostStoreLock } from "./hellolynk-neutral-host-installation-
 
 const CATALOG = "https://hellolynk.com/downloads/clients.json";
 export const CLIENT_UPDATE_CLIENTS = Object.freeze(["codex", "openclaw", "trae-work", "workbuddy", "dsh", "claude-code"]);
+export const MAC_CLIENT_VERSION = /^\d+\.\d+\.\d+-macos\.[1-9]\d*$/u;
 const HOUR = 3_600_000;
 const MAX_ARTIFACT = 64 * 1024 * 1024;
 const HASH = /^[a-f0-9]{64}$/;
-const CONTRACT = "hellolynk-client-update-v1";
+const CONTRACT = "hellolynk-client-update-v2";
+export const CLIENT_UPDATE_RELEASES = "releases-v2";
+// The release freeze pins only public Ed25519 keys here. An empty set refuses all updates.
+export const CLIENT_UPDATE_CATALOG_KEYS = Object.freeze({
+  "ed25519-20261109-primary-d4fd7f46475dac48": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAucQohi+be+ksjQhRzYD8ZiyZMUz6Vi/DSphQ3iVOWDM=\n-----END PUBLIC KEY-----\n",
+  "ed25519-20261109-backup-5e3d08a775320304": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA2vxHpcgLZQc1cXqxq3dcmZRmE0fAFyeRC3umMVGAosA=\n-----END PUBLIC KEY-----\n"
+});
+export const CLIENT_UPDATE_CATALOG_LIMIT = 256 * 1024;
 // A failed integrity or path check keeps a downloaded package from installing. Every other failure is transient.
-const BLOCKING = /^client_update_(?:same_version_changed|version_rollback|artifact_integrity_invalid|archive_[a-z_]+|path_invalid|url_invalid|redirect_invalid)$/;
+const BLOCKING = /^client_update_(?:catalog_signature_invalid|same_version_changed|version_rollback|artifact_integrity_invalid|archive_[a-z_]+|path_invalid|url_invalid|redirect_invalid)$/;
+
+export function clientUpdateCatalogId(client, platform) {
+  if (platform === "win32") return client;
+  if (platform === "darwin" && (client === "codex" || client === "claude-code")) return `${client}-macos`;
+  return null;
+}
 
 // This component only stages verified files. Host lifecycle and client-native
 // installation remain the responsibility of the caller.
 export function createClientUpdateManager(options = {}) {
   const { client, currentVersion, platform = process.platform } = options;
   if (!CLIENT_UPDATE_CLIENTS.includes(client) || !semver(currentVersion) || !path.isAbsolute(String(options.root || ""))) fail("configuration_invalid");
+  const catalogId = clientUpdateCatalogId(client, platform);
+  const mac = platform === "darwin";
+  if (mac && !MAC_CLIENT_VERSION.test(currentVersion)) fail("configuration_invalid");
   const root = path.join(path.resolve(options.root), "client-updates", client);
-  const stateFile = path.join(root, "state.json");
+  // A still-running unsigned updater may read, rewrite and prune its own cache.
+  const stateFile = path.join(root, "state-v2.json");
+  const releases = path.join(root, CLIENT_UPDATE_RELEASES);
   const fetcher = options.fetchImpl || globalThis.fetch;
   const clock = options.clock || Date.now;
   const timeoutMs = bounded(options.timeoutMs, 30_000, 50, 120_000);
@@ -60,7 +79,7 @@ export function createClientUpdateManager(options = {}) {
     }
   }
 
-  function releasePath(record) { return path.join(root, "releases", `${record.version}-${record.sha256}`); }
+  function releasePath(record) { return path.join(releases, `${record.version}-${record.sha256}`); }
   async function save(record) {
     await safeDirectory(root);
     const temporary = path.join(root, `.state-${crypto.randomUUID()}.tmp`);
@@ -80,12 +99,13 @@ export function createClientUpdateManager(options = {}) {
       let old = await readState();
       const now = clock();
       if (!force && old.checkedAt > 0 && now >= old.checkedAt && now - old.checkedAt < 23 * HOUR) return old;
-      if (platform !== "win32") return save({ ...old, stage: "unsupported", checkedAt: now });
+      if (!catalogId) return save({ ...old, stage: "unsupported", checkedAt: now });
       try {
-        const metadata = await request(CATALOG, { limit: 256 * 1024, timeout: timeoutMs, kind: "catalog" });
+        const metadata = await request(CATALOG, { limit: CLIENT_UPDATE_CATALOG_LIMIT, timeout: timeoutMs, kind: "catalog" });
         let catalog;
         try { catalog = JSON.parse(metadata.toString("utf8")); } catch { fail("catalog_invalid"); }
-        const artifact = validateCatalog(catalog, client);
+        const verified = verifyClientUpdateCatalog(catalog, options.catalogKeys);
+        const artifact = validateClientUpdateCatalogEntry(verified, catalogId, mac);
         // The catalog has no build for this client: there is nothing to install.
         if (!artifact) {
           // A downloaded package keeps its stage and any integrity block; only an empty cache is "current".
@@ -134,12 +154,12 @@ export function createClientUpdateManager(options = {}) {
         if (!bytes) fail("source_unavailable");
         const release = releasePath(artifact);
         await safeDirectory(path.dirname(release));
-        const stage = path.join(root, "releases", `.stage-${crypto.randomUUID()}`);
+        const stage = path.join(releases, `.stage-${crypto.randomUUID()}`);
         await fs.mkdir(stage, { mode: 0o700 });
         try {
           const archivePath = path.join(stage, artifact.filename);
           await fs.writeFile(archivePath, bytes, { flag: "wx", mode: 0o600 });
-          await extractClientUpdateArchive({ archivePath, destination: path.join(stage, "extracted") });
+          await extractClientUpdateArchive({ archivePath, destination: path.join(stage, "extracted"), platform });
           await fs.rename(stage, release).catch(async (error) => {
             if (!["EEXIST", "ENOTEMPTY", "EPERM"].includes(error.code)) throw error;
             try {
@@ -147,7 +167,7 @@ export function createClientUpdateManager(options = {}) {
               return;
             } catch { /* Preserve damaged evidence without reusing it. */ }
             await safeAncestors(release, true);
-            const quarantine = path.join(root, "releases", `.corrupt-${artifact.sha256}-${crypto.randomUUID()}`);
+            const quarantine = path.join(releases, `.corrupt-${artifact.sha256}-${crypto.randomUUID()}`);
             await fs.rename(release, quarantine);
             try { await fs.rename(stage, release); }
             catch (replacement) { await fs.rename(quarantine, release).catch(() => {}); throw replacement; }
@@ -172,7 +192,7 @@ export function createClientUpdateManager(options = {}) {
     });
   }
 
-  // After an install only the package state.json names stays cached; older
+  // After an install only the package the signed state names stays cached; older
   // versions and quarantined copies go. Holding the check lock means no
   // download is in flight to be mistaken for leftovers.
   async function prune() {
@@ -180,7 +200,7 @@ export function createClientUpdateManager(options = {}) {
     return withNeutralHostStoreLock(root, "client-update", async () => {
       const state = await readState();
       if (!semver(state.version) || !HASH.test(String(state.sha256 || ""))) return [];
-      const keep = path.basename(releasePath(state)), releases = path.join(root, "releases"), removed = [];
+      const keep = path.basename(releasePath(state)), removed = [];
       await safeAncestors(releases, true);
       let entries;
       try { entries = await fs.readdir(releases, { withFileTypes: true }); }
@@ -267,15 +287,36 @@ export function createClientUpdateManager(options = {}) {
   });
 }
 
-function validateCatalog(catalog, client) {
+export function verifyClientUpdateCatalog(catalog, keys = CLIENT_UPDATE_CATALOG_KEYS) {
+  const signed = catalog?.signed;
+  if (!signed || typeof signed.keyId !== "string" || !/^[A-Za-z0-9_-]{1,64}$/.test(signed.keyId)
+    || !Object.hasOwn(keys, signed.keyId) || typeof signed.payload !== "string" || !signed.payload
+    || signed.payload.length > CLIENT_UPDATE_CATALOG_LIMIT || typeof signed.signature !== "string"
+    || !/^[A-Za-z0-9_-]{86}$/.test(signed.signature)) fail("catalog_signature_invalid");
+  const payload = Buffer.from(signed.payload, "base64");
+  const signature = Buffer.from(signed.signature, "base64url");
+  if (payload.toString("base64") !== signed.payload || signature.toString("base64url") !== signed.signature) fail("catalog_signature_invalid");
+  let valid = false;
+  try {
+    const key = crypto.createPublicKey(keys[signed.keyId]);
+    valid = key.asymmetricKeyType === "ed25519" && crypto.verify(null, payload, key, signature);
+  } catch { /* Invalid pins and invalid signatures both fail closed. */ }
+  if (!valid) fail("catalog_signature_invalid");
+  const json = payload.toString("utf8");
+  if (!Buffer.from(json, "utf8").equals(payload)) fail("catalog_invalid");
+  try { return JSON.parse(json); } catch { fail("catalog_invalid"); }
+}
+
+export function validateClientUpdateCatalogEntry(catalog, client, mac) {
   if (!catalog || !Array.isArray(catalog.clients) || catalog.clients.length > 32) fail("catalog_invalid");
   const matches = catalog.clients.filter((item) => item?.client === client);
   if (matches.length === 0) return null;
   if (matches.length > 1) fail("catalog_invalid");
   const item = matches[0];
-  if (!semver(item.version) || !HASH.test(String(item.sha256 || "")) || !safeFilename(item.filename)
+  if (!semver(item.version) || (mac && !MAC_CLIENT_VERSION.test(item.version))
+    || !HASH.test(String(item.sha256 || "")) || !safeFilename(item.filename)
     || !Number.isSafeInteger(item.bytes) || item.bytes < 4 || item.bytes > MAX_ARTIFACT
-    || !Array.isArray(item.platforms) || !item.platforms.includes("Windows")) fail("catalog_invalid");
+    || !Array.isArray(item.platforms) || !item.platforms.includes(mac ? "macOS" : "Windows")) fail("catalog_invalid");
   const official = new URL(String(item.url || ""), CATALOG);
   if (official.origin !== "https://hellolynk.com" || !official.pathname.startsWith("/downloads/")) fail("catalog_invalid");
   validateUrl(official, "artifact");
@@ -309,7 +350,7 @@ function validateUrl(url, kind, redirected = false, initial = url) {
   if (!direct && !githubCdn) fail("url_invalid");
 }
 
-export async function extractClientUpdateArchive({ archivePath, destination, maxTotalBytes = 128 * 1024 * 1024, maxFileBytes = 32 * 1024 * 1024, maxEntries = 4096 }) {
+export async function extractClientUpdateArchive({ archivePath, destination, platform = process.platform, maxTotalBytes = 128 * 1024 * 1024, maxFileBytes = 32 * 1024 * 1024, maxEntries = 4096 }) {
   if (!path.isAbsolute(archivePath) || !path.isAbsolute(destination)) fail("archive_path_invalid");
   await safeAncestors(archivePath, false);
   const stat = await fs.lstat(archivePath);
@@ -360,7 +401,7 @@ export async function extractClientUpdateArchive({ archivePath, destination, max
     total += size;
     if (total > maxTotalBytes) fail("archive_too_large");
     spans.push([local, start + packed]);
-    entries.push({ segments, directory, start, packed, size, method, crc });
+    entries.push({ segments, directory, start, packed, size, method, crc, mode });
     cursor += 46 + nameLength + extraLength + commentLength;
   }
   if (cursor !== eocd) fail("archive_invalid");
@@ -377,7 +418,10 @@ export async function extractClientUpdateArchive({ archivePath, destination, max
     try { body = entry.method === 0 ? compressed : inflateRawSync(compressed, { maxOutputLength: Math.max(1, entry.size) }); }
     catch { fail("archive_integrity_invalid"); }
     if (body.length !== entry.size || crc32(body) !== entry.crc) fail("archive_integrity_invalid");
-    await fs.writeFile(target, body, { flag: "wx", mode: 0o600 });
+    // A Mac update runs a bundled Keychain helper. Keep its execute bit without
+    // inheriting group/other access or special permission bits from the ZIP.
+    const ownerExecute = platform === "darwin" ? entry.mode & 0o100 : 0;
+    await fs.writeFile(target, body, { flag: "wx", mode: 0o600 | ownerExecute });
   }
   return Object.freeze({ files: entries.filter((item) => !item.directory).length, bytes: total });
 }