@hellolynk-ai/codex-plugin 0.2.102 → 0.2.103-macos.1

package/plugins/hellolynk-codex/runtime/bootstrap/core/hellolynk-platform-credential-store.mjs

@@ -1,3 +1,4 @@
+import { checkDarwinPath, DARWIN_HELPER, invokeDarwinHelper, withDarwinVault } from "./hellolynk-darwin-vault.mjs";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { spawn as nodeSpawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
@@ -260,6 +261,14 @@ export async function runWindowsClientTrustCommand(command, options = {}) {
 }
 
 export async function prepareWindowsClientRoot(clientRoot, options = {}) {
+  if ((options.platform || process.platform) === "darwin") {
+    checkDarwinPath(clientRoot, { directory: true, create: true, privateMode: true });
+    for (const sub of ["profiles", "credentials", "e2ee-private-keys", "status", "host", "host/runtime", "releases"]) {
+      checkDarwinPath(join(clientRoot, sub), { directory: true, create: true, privateMode: true });
+    }
+    await invokeDarwinHelper(options.helperPath || DARWIN_HELPER, ["verify-acl", clientRoot]);
+    return "prepared";
+  }
   return runWindowsClientTrustCommand("PrepareRoot", {
     ...options,
     clientRoot,
@@ -272,6 +281,14 @@ export async function secureWindowsClientReleaseTree(clientRoot, releaseId, opti
   if (!/^(?!\.{1,2}$)[A-Za-z0-9.][A-Za-z0-9_.-]{2,191}$/.test(acceptedReleaseId)) {
     throw new HelloLynkCredentialStoreError("client_release_path_invalid");
   }
+  if ((options.platform || process.platform) === "darwin") {
+    checkDarwinPath(clientRoot, { directory: true, privateMode: true });
+    checkDarwinPath(join(clientRoot, "releases"), { directory: true, privateMode: true });
+    const release = join(clientRoot, "releases", acceptedReleaseId);
+    checkDarwinPath(release, { directory: true });
+    await invokeDarwinHelper(options.helperPath || DARWIN_HELPER, [options.verifyOnly ? "verify-tree" : "secure-tree", release]);
+    return options.verifyOnly ? "verified" : "secured";
+  }
   return runWindowsClientTrustCommand(options.verifyOnly === true ? "VerifyReleaseTree" : "SecureReleaseTree", {
     ...options,
     clientRoot,
@@ -460,24 +477,61 @@ export function createPlatformCredentialStore(options = {}) {
   }
 
   if (platform === "darwin") {
-    const helper = options.helperPath || join(
-      homedir(), "Library", "Application Support", "HelloLynk", "bin", "hellolynk-keychain-helper",
-    );
-    const invoke = (command, profileId, stdin) => run(
-      helper,
-      [command.toLowerCase(), profileId],
-      { ...runnerOptions, stdin },
-    );
+    const clientRoot = options.clientRoot || (options.storeRoot ? windowsClientRootForStore(options.storeRoot)
+      : join(homedir(), "Library", "Application Support", "HelloLynk"));
+    if (clientRoot !== resolve(clientRoot) || clientRoot === "/") throw new HelloLynkCredentialStoreError("client_root_path_invalid");
+    const credentials = join(clientRoot, "credentials");
+    const privateKeys = join(clientRoot, "e2ee-private-keys");
+    const root = options.storeRoot || credentials;
+    const e2eeRoot = options.e2eeStoreRoot || privateKeys;
+    if (root !== clientRoot && root !== credentials) throw new HelloLynkCredentialStoreError("credential_store_root_invalid");
+    if (e2eeRoot !== privateKeys) throw new HelloLynkCredentialStoreError("e2ee_private_key_store_root_invalid");
+    function entry(location, section, profile, operation, value) {
+      const slot = section + ":" + assertCredentialProfileId(profile);
+      return withDarwinVault({ root: location, helperPath: options.helperPath, readOnly: operation === "load", allowMissing:true }, data => {
+        if (operation === "save") data[slot] = value;
+        if (operation === "remove") delete data[slot];
+        return data[slot] ?? null;
+      });
+    }
     return {
       platform,
-      async save(profile, credential) {
-        await invoke("Store", assertCredentialProfileId(profile), assertCredential(credential));
-      },
+      async save(profile, credential) { await entry(root, "device", profile, "save", assertCredential(credential)); },
       async load(profile) {
-        return assertCredential(await invoke("Load", assertCredentialProfileId(profile), ""));
+        const value = await entry(root, "device", profile, "load");
+        if (value === null) throw new HelloLynkCredentialStoreError("device_credential_missing");
+        return assertCredential(value);
       },
-      async remove(profile) {
-        await invoke("Remove", assertCredentialProfileId(profile), "");
+      async remove(profile) { await entry(root, "device", profile, "remove"); },
+      runtimeSessions: {
+        async save(profile, session) { await entry(root, "session", profile, "save", assertRuntimeSession(session)); },
+        async load(profile) {
+          const value = await entry(root, "session", profile, "load");
+          return value === null ? null : assertRuntimeSession(value);
+        },
+        async remove(profile) { await entry(root, "session", profile, "remove"); },
+        async withLock(profile, operation) {
+          const id = assertCredentialProfileId(profile);
+          if (typeof operation !== "function") throw new HelloLynkCredentialStoreError("runtime_session_lock_operation_invalid");
+          checkDarwinPath(root, { directory:true, create:true, privateMode:true });
+          return withRuntimeSessionFileLock(root, id, operation, options.runtimeSessionLockDependencies, options.timeoutMs);
+        },
+      },
+      directTextPrivateKeys: {
+        async save(profile, material) { await entry(e2eeRoot, "keys", profile, "save", encodeDirectTextPrivateKeyMaterial(material)); },
+        async load(profile) {
+          const value = await entry(e2eeRoot, "keys", profile, "load");
+          return value === null ? null : decodeDirectTextPrivateKeyMaterial(value);
+        },
+        async remove(profile) { await entry(e2eeRoot, "keys", profile, "remove"); },
+        async preload(profiles) {
+          const ids = [...new Set((Array.isArray(profiles) ? profiles : []).map(assertCredentialProfileId))];
+          if (!ids.length) return;
+          if (ids.length > MAX_E2EE_BATCH_PROFILES) throw new HelloLynkCredentialStoreError("e2ee_private_key_batch_invalid");
+          await withDarwinVault({root:e2eeRoot, helperPath:options.helperPath, readOnly:true, allowMissing:true}, data => {
+            for (const id of ids) if (data["keys:" + id] !== undefined) decodeDirectTextPrivateKeyMaterial(data["keys:" + id]);
+          });
+        },
       },
     };
   }

package/plugins/hellolynk-codex/runtime/bootstrap/platform/darwin/hellolynk-keychain-helper.swift

@@ -0,0 +1,149 @@
+// Rebuild in this directory: xcrun swiftc -O -target arm64-apple-macos13.0 -module-name HelloLynkKeychain hellolynk-keychain-helper.swift -o hellolynk-keychain-helper.bin
+import AppKit
+import CryptoKit
+import Foundation
+import Security
+
+func fail(_ code: String) -> Never {
+    FileHandle.standardError.write(Data((code + "\n").utf8))
+    exit(1)
+}
+
+func requireNoGrantACL(_ path: String) {
+    guard let acl = acl_get_file(path, ACL_TYPE_EXTENDED) else {
+        if errno == ENOENT { return } // A first write creates the file with mode 0600.
+        fail("macos_vault_acl_unavailable")
+    }
+    defer { acl_free(UnsafeMutableRawPointer(acl)) }
+    var entry: acl_entry_t?
+    var selector = ACL_FIRST_ENTRY
+    while acl_get_entry(acl, Int32(selector.rawValue), &entry) == 0 {
+        var tag = ACL_UNDEFINED_TAG
+        guard acl_get_tag_type(entry, &tag) == 0, tag == ACL_EXTENDED_DENY else {
+            fail("macos_vault_acl_invalid")
+        }
+        selector = ACL_NEXT_ENTRY
+    }
+}
+
+// The caller verifies the release path's ancestors and package hashes. Walk
+// with lstat so a symlink or hard link cannot redirect a permission change.
+func secureRelease(_ path: String, verifyOnly: Bool) {
+    var pending = [path]
+    while let entry = pending.popLast() {
+        var st = stat()
+        guard lstat(entry, &st) == 0, st.st_uid == getuid() else { fail("macos_vault_release_invalid") }
+        let type = st.st_mode & S_IFMT
+        guard type == S_IFDIR || (type == S_IFREG && st.st_nlink == 1) else { fail("macos_vault_release_invalid") }
+        let mode: mode_t = type == S_IFDIR || entry.hasSuffix(".bin") ? 0o700 : 0o600
+        if (st.st_mode & 0o7777) != mode {
+            guard !verifyOnly, chmod(entry, mode) == 0 else { fail("macos_vault_release_permissions_invalid") }
+        }
+        requireNoGrantACL(entry)
+        if type == S_IFDIR {
+            guard let names = try? FileManager.default.contentsOfDirectory(atPath: entry) else { fail("macos_vault_release_invalid") }
+            pending.append(contentsOf: names.map { entry + "/" + $0 })
+        }
+    }
+}
+
+func masterKey(_ root: String, create: Bool) -> Data {
+    let account = SHA256.hash(data: Data(root.utf8)).map { String(format: "%02x", $0) }.joined()
+    let base: [String: Any] = [
+        kSecClass as String: kSecClassGenericPassword,
+        kSecAttrService as String: "com.hellolynk.codex.macos-vault.v1",
+        kSecAttrAccount as String: account
+    ]
+    var lookup = base
+    lookup[kSecReturnData as String] = true
+    lookup[kSecMatchLimit as String] = kSecMatchLimitOne
+    var result: CFTypeRef?
+    let status = SecItemCopyMatching(lookup as CFDictionary, &result)
+    if status == errSecSuccess {
+        guard let key = result as? Data, key.count == 32 else { fail("macos_vault_key_invalid") }
+        return key
+    }
+    guard status == errSecItemNotFound else { fail("macos_keychain_access_\(abs(Int(status)))") }
+    guard create else { fail("macos_vault_key_missing") }
+    let key = SymmetricKey(size: .bits256).withUnsafeBytes { Data($0) }
+    var add = base
+    add[kSecValueData as String] = key
+    add[kSecAttrAccessible as String] = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
+    let inserted = SecItemAdd(add as CFDictionary, nil)
+    if inserted == errSecDuplicateItem { return masterKey(root, create: false) }
+    guard inserted == errSecSuccess else { fail("macos_keychain_access_\(abs(Int(inserted)))") }
+    return key
+}
+
+func nativeConfirmation() {
+    let raw = FileHandle.standardInput.readDataToEndOfFile()
+    guard raw.count <= 20480 * 6 + 8192,
+          var v = (try? JSONSerialization.jsonObject(with: raw)) as? [String: Any],
+          let body = v["displayText"] as? String, !body.isEmpty, body.utf8.count <= 20480,
+          let encoded = v["hmacKey"] as? String, encoded.count == 43,
+          let key = Data(base64Encoded: encoded.replacingOccurrences(of: "-", with: "+")
+              .replacingOccurrences(of: "_", with: "/") + "="), key.count == 32,
+          let recipient = v["recipientHelloLynkId"] as? String,
+          v["contract"] as? String == "hellolynk-native-human-confirmation-v1",
+          v["textDigest"] as? String == SHA256.hash(data: Data(body.utf8)).map({ String(format: "%02x", $0) }).joined()
+    else { fail("human_confirmation_request_invalid") }
+
+    var fields = ["contract", "actionId", "decision", "principalId", "delegateId", "hostInstallationId",
+                  "adapterId", "adapterInstanceId", "hostGeneration", "recipientHelloLynkId"]
+    var label = "收件人：" + recipient
+    if v["recipientDelegateId"] != nil || v["recipientInstanceDisplayName"] != nil {
+        guard let name = v["recipientInstanceDisplayName"] as? String, !name.isEmpty, name.utf8.count <= 512,
+              name.range(of: #"[\x00-\x1F\x7F-\x9F\u2028\u2029\u202A-\u202E\u2066-\u2069]"#, options: .regularExpression) == nil,
+              v["recipientDelegateId"] is String else { fail("human_confirmation_request_invalid") }
+        fields += ["recipientDelegateId", "recipientInstanceDisplayName"]
+        label += "\n目标 AI：" + name
+    }
+    fields += ["clientMessageId", "textDigest", "createdAtMs", "expiresAtMs", "challenge"]
+    var expected = Set(fields)
+    expected.remove("decision")
+    expected.formUnion(["displayText", "hmacKey"])
+    guard expected == Set(v.keys) else { fail("human_confirmation_request_invalid") }
+    let app = NSApplication.shared
+    app.setActivationPolicy(.accessory)
+    app.activate(ignoringOtherApps: true)
+    let dialog = NSAlert()
+    dialog.messageText = "是否允许 HelloLynk 发送以下文本？"
+    dialog.informativeText = label
+    dialog.addButton(withTitle: "取消")
+    dialog.addButton(withTitle: "批准发送")
+    let scroll = NSScrollView(frame: NSRect(x: 0, y: 0, width: 500, height: 230))
+    scroll.hasVerticalScroller = true
+    let view = NSTextView(frame: scroll.contentView.bounds)
+    view.isEditable = false
+    view.isRichText = false
+    view.isVerticallyResizable = true
+    view.autoresizingMask = [.width]
+    view.textContainer?.widthTracksTextView = true
+    view.string = body
+    scroll.documentView = view
+    dialog.accessoryView = scroll
+    v["decision"] = dialog.runModal() == .alertSecondButtonReturn ? "approve" : "cancel"
+    let message = fields.map { field -> String in
+        if let text = v[field] as? String { return text }
+        if ["createdAtMs","expiresAtMs"].contains(field), let n = v[field] as? NSNumber { return n.stringValue }
+        fail("human_confirmation_request_invalid")
+    }.joined(separator: "\n")
+    let proof = HMAC<SHA256>.authenticationCode(for: Data(message.utf8), using: SymmetricKey(data: key))
+    v["proof"] = proof.map { String(format: "%02x", $0) }.joined()
+    for field in ["hmacKey", "challenge", "displayText"] { v.removeValue(forKey: field) }
+    guard let output = try? JSONSerialization.data(withJSONObject: v) else { fail("human_confirmation_response_invalid") }
+    FileHandle.standardOutput.write(output)
+}
+
+let args = Array(CommandLine.arguments.dropFirst())
+if args == ["confirm"] { nativeConfirmation() }
+else if args.count == 3, args[0] == "key", args[1].hasPrefix("/"), ["load","create"].contains(args[2]) {
+    requireNoGrantACL(args[1])
+    requireNoGrantACL(args[1] + "/protected-v1.sqlite")
+    let key = masterKey(args[1], create: args[2] == "create")
+    FileHandle(fileDescriptor: 3, closeOnDealloc: false).write(key)
+} else if args.count == 2, ["verify-tree", "secure-tree"].contains(args[0]), args[1].hasPrefix("/") {
+    secureRelease(args[1], verifyOnly: args[0] == "verify-tree")
+} else if args.count == 2, args[0] == "verify-acl", args[1].hasPrefix("/") {
+    requireNoGrantACL(args[1])
+} else { fail("macos_vault_helper_arguments_invalid") }

package/plugins/hellolynk-codex/runtime/connect-activate.mjs

@@ -5,6 +5,7 @@ import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 
+import { verifyDarwinUnclaimedAuthorization } from "./core/hellolynk-darwin-host.mjs";
 import { readClientProfile } from "./core/hellolynk-client-profile.mjs";
 import { createNeutralHostInstallationStore } from "./core/hellolynk-neutral-host-installation-store.mjs";
 import { clientAccountBaseRoot } from "./core/hellolynk-client-account.mjs";
@@ -164,7 +165,7 @@ assert.equal(releaseVerification.verifiedFileCount >= 8, true);
 let transport = null;
 let bootstrapTransportRequired = false;
 let protectedStorePresent = true;
-try { await fs.lstat(path.join(root, "capabilities-v1.dpapi.clixml")); }
+try { await fs.lstat(path.join(root, process.platform === "darwin" ? "protected-v1.sqlite" : "capabilities-v1.dpapi.clixml")); }
 catch (error) {
   if (error?.code !== "ENOENT") throw error;
   protectedStorePresent = false;
@@ -173,6 +174,9 @@ if (!protectedStorePresent) {
   if (!(freshPreBind || recoveryPreBind)) await store.status();
   await verifyHostProtectedStorePath({ root, path: root, directory: true });
   bootstrapTransportRequired = true;
+} else if (process.platform === "darwin" && freshPreBind) {
+  await verifyDarwinUnclaimedAuthorization(root);
+  bootstrapTransportRequired = true;
 } else {
   assert.equal((await store.status()).protected, true);
   try { transport = preflightOnly ? await store.verifyTransport() : await store.resolveTransport(); }

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