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

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

package/plugins/hellolynk-codex/runtime/core/hellolynk-darwin-host.mjs

@@ -0,0 +1,269 @@
+import { isDeepStrictEqual as equal } from "node:util";
+import { join } from "node:path";
+import { checkDarwinPath, vaultError, withDarwinVault } from "./hellolynk-darwin-vault.mjs";
+
+const permanent = 253402300799999;
+const month = 30 * 86400000;
+function fail(code) { throw vaultError(code); }
+function fieldsMatch(a, b, fields) { return fields.every(field => equal(a[field], b[field])); }
+function sameOwner(a, b) { return fieldsMatch(a, b, ["principalId", "hostInstallationId"]); }
+function used(records, field, id) { return records.some(r => r[field].toLowerCase() === id.toLowerCase()); }
+function unique(records, missing, ambiguous) {
+  if (records.length !== 1) fail(records.length ? ambiguous : missing);
+  return records[0];
+}
+function checkBindingPaths(b, code) {
+  try {
+    checkDarwinPath(b.runtimeRoot, { directory: true });
+    checkDarwinPath(b.releaseRoot, { directory: true });
+    if (checkDarwinPath(b.profileManifestPath).size > 65536 ||
+        checkDarwinPath(join(b.releaseRoot, b.runnerRelativePath)).size > 1048576) fail(code);
+  } catch { fail(code); }
+}
+function capMatches(cap, b) {
+  return cap.state === "active" && fieldsMatch(cap, b,
+    ["region", "principalId", "delegateId", "hostInstallationId", "adapterId", "version", "scopes"]);
+}
+function addCapability(s, r) {
+  if (used(s.caps, "capabilityId", r.capabilityId)) fail("host_capability_id_conflict");
+  s.caps.push(r);
+}
+function revokeCapability(s, r) {
+  if (!r) fail("host_capability_missing");
+  if (r.state === "active") {
+    const revokedAt = Date.now();
+    if (revokedAt < r.issuedAt) fail("host_capability_state_invalid");
+    // Keep the identifier spent while discarding the retired secret.
+    r = s.caps[s.caps.indexOf(r)] = { capabilityId: r.capabilityId, issuedAt: r.issuedAt, state: "revoked", revokedAt };
+  }
+  return { capabilityId: r.capabilityId, revokedAt: r.revokedAt, state: "revoked" };
+}
+function neutralBinding(s, adapter, action, input, oldId) {
+  const codex = adapter === "codex";
+  const key = codex ? "codex" : "claudeCode";
+  const error = suffix => `neutral_${adapter.replace("-", "_")}_${suffix}`;
+  const check = binding => checkBindingPaths(binding, error("launch_manifest_invalid"));
+  const b = s[key];
+  if (action === "Resolve" || action === "Verify") {
+    if (!b) fail(error("binding_configuration_required"));
+    // Claude retains its identity across uninstall; Verify can inspect a
+    // retained binding whose old release is gone. Resolve always needs it.
+    if (codex || action === "Resolve") check(b);
+    const active = s.caps.filter(c => c.adapterId === adapter && c.state === "active");
+    const cap = unique(active.filter(c => capMatches(c, b)),
+      error(active.length ? "capability_binding_mismatch" : "capability_missing"), error("capability_ambiguous"));
+    if (action === "Resolve") return { binding: b, record: cap };
+    const {secret, ...record} = cap;
+    return { binding: b, record };
+  }
+  if (action === "Save" || action === "Remove") {
+    if (input.adapterId !== adapter) fail(error("binding_invalid"));
+    if (action === "Remove") {
+      if (codex) check(input);
+      if (!equal(b, input)) fail(error("binding_invalid"));
+      if (codex) s.codex = null;
+      else delete s.claudeCode;
+      return { removed: true };
+    }
+    check(input);
+    if (b && !equal(b, input)) fail(error("binding_invalid"));
+    s[key] = input;
+    return { binding: input };
+  }
+  const { previousBinding: previous, replacementBinding: next, replacementRecord } = input;
+  if (codex) check(previous);
+  check(next);
+  if (next.adapterId !== adapter || !fieldsMatch(previous, next, ["contract","region","principalId","delegateId","hostInstallationId","profileId","adapterId","version","runtimeRoot"])) {
+    fail(error("capability_binding_mismatch"));
+  }
+  if (!equal(b, previous)) fail(error("binding_invalid"));
+  const active = s.caps.filter(c => capMatches(c, next));
+  if (codex && action === "Replace") {
+    if (!equal(previous.scopes, next.scopes)) fail(error("capability_binding_mismatch"));
+    if (active.length !== 1) fail(error("capability_ambiguous"));
+    s[key] = next;
+    return { binding: next };
+  }
+  if (action !== "Migrate") fail("host_protected_store_command_invalid");
+  const old = s.caps.find(c => c.capabilityId === oldId);
+  if (!old || !capMatches(old, previous) || !capMatches(replacementRecord, next)) fail(error("capability_binding_mismatch"));
+  const other = active.filter(c => c.capabilityId !== oldId);
+  if (other.length > 1) fail(error("capability_ambiguous"));
+  if (!other.length) addCapability(s, replacementRecord);
+  revokeCapability(s, old);
+  s[key] = next;
+  return { binding: next, record: other[0] || replacementRecord, replacedCapabilityId: oldId };
+}
+
+function retireSession(s, r) {
+  s.sessions.splice(s.sessions.indexOf(r), 1);
+  s.retiredSessions.push(r.sessionId.toLowerCase());
+}
+function revokeCredential(s, r, timestamp) {
+  if (timestamp < r.issuedAt) fail("host_transport_credential_revoke_timestamp_invalid");
+  const sessions = s.sessions.filter(session => session.credentialId === r.credentialId);
+  if (r.state === "active") {
+    sessions.forEach(session => retireSession(s, session));
+    const { credentialId, issuedAt, principalId, hostInstallationId } = r;
+    r = s.credentials[s.credentials.indexOf(r)] = { credentialId, issuedAt, principalId, hostInstallationId, state:"revoked", revokedAt:timestamp };
+  }
+  return { credentialId:r.credentialId, state:"revoked", revokedAt:r.revokedAt, cascadedSessionCount:sessions.length };
+}
+function exactFields(value, fields) {
+  return value && typeof value === "object" && equal(Object.keys(value).sort(), fields.sort());
+}
+function checkEnrollment(value, record) {
+  const a = value?.approval, approved = a?.hostTransportCredential;
+  if (!exactFields(value, ["baseUrl","hellolynkId","hostId","deviceLabel","requestId","proof","approval","intents"])
+      || !exactFields(a, ["status","principalId","hellolynkId","region","hostId","hostTransportCredential"])
+      || !exactFields(approved, ["credentialId","credential","createdAt","expiresAt"])
+      || a.status !== "approved" || a.principalId !== record.principalId || a.hostId !== record.hostInstallationId
+      || value.hostId !== a.hostId || a.hellolynkId !== value.hellolynkId || approved.credentialId !== record.credentialId
+      || approved.credential !== record.secret || Date.parse(approved.createdAt) !== record.issuedAt
+      || Date.parse(approved.expiresAt) !== record.expiresAt) fail("device_enrollment_transport_approval_mismatch");
+  if (record.expiresAt <= Date.now()) fail("host_transport_credential_expired");
+}
+
+function transport(s, q, input) {
+  const {command, timestamp} = q;
+  const id = q.credentialId || input?.credentialId;
+  const credential = s.credentials.find(r => r.credentialId === id);
+  const owned = query => s.credentials.filter(r => r.state === "active" && sameOwner(r, query));
+  if (command === "SaveTransportCredential" || command === "SaveEnrollmentTransportCredential") {
+    const upgrade = command === "SaveEnrollmentTransportCredential";
+    if (upgrade) checkEnrollment(s.enrollment.value, input);
+    if (credential) {
+      if (!equal(credential,input)) fail("host_transport_credential_immutable_conflict");
+    } else {
+      if (used(s.credentials, "credentialId", id)) fail("host_transport_credential_immutable_conflict");
+      const old = owned(input);
+      if (old.length > 1 || (old.length && !upgrade)) fail("host_transport_credential_ambiguous");
+      if (old.length) revokeCredential(s,old[0],Date.now());
+      s.credentials.push(input);
+    }
+    return { record: input };
+  }
+  if (command === "VerifyTransportCredentialLifetimeMigration" || command === "MigrateTransportCredentialLifetime") {
+    const record = unique(owned(q), "host_transport_migration_credential_inactive_or_ambiguous", "host_transport_migration_credential_inactive_or_ambiguous");
+    if (record.expiresAt !== permanent && record.expiresAt - record.issuedAt !== month) fail("host_transport_migration_lifetime_invalid");
+    if (command.startsWith("Verify")) return { record };
+    if (record.expiresAt-record.issuedAt !== month || !equal(record,input.previous)) fail("host_transport_migration_compare_failed");
+    const proof = input.proof;
+    if (proof.credentialId !== record.credentialId || proof.hostId !== q.hostInstallationId || proof.principalId !== q.principalId
+        || Date.parse(proof.credentialCreatedAt) !== record.issuedAt || Date.parse(proof.credentialExpiresAt) !== permanent) fail("host_transport_migration_proof_invalid");
+    record.expiresAt = permanent;
+    return { credentialId: record.credentialId, expiresAt: permanent, status:"migrated" };
+  }
+  if (command === "LoadTransportCredential" || command === "RevokeTransportCredential") {
+    if (command.startsWith("Load") && credential?.state !== "active") fail("host_transport_credential_inactive");
+    if (!credential) fail("host_transport_credential_missing");
+    if (!sameOwner(credential,q)) fail("host_transport_credential_owner_mismatch");
+    if (command.startsWith("Revoke")) return revokeCredential(s,credential,timestamp);
+    if (credential.expiresAt <= timestamp) fail("host_transport_credential_expired");
+    return { record: credential };
+  }
+  const sessionId = q.sessionId || input?.sessionId;
+  const session = s.sessions.find(r => r.sessionId === sessionId);
+  if (command === "SaveTransportSession" || command === "ReplaceTransportSession") {
+    if (credential?.state !== "active") fail("host_transport_credential_inactive");
+    if (!sameOwner(credential,input) || credential.expiresAt <= timestamp || input.expiresAt > credential.expiresAt) fail("host_transport_session_credential_mismatch");
+    if (s.retiredSessions.includes(sessionId.toLowerCase())) fail("host_transport_session_retired");
+    if (session) {
+      if (!equal(session,input)) fail("host_transport_session_immutable_conflict");
+    } else {
+      if (used(s.sessions, "sessionId", sessionId)) fail("host_transport_session_duplicate");
+      const previous = s.sessions.filter(r => sameOwner(r,input));
+      if (previous.length && command.startsWith("Save")) fail("host_transport_session_ambiguous");
+      previous.forEach(r => retireSession(s,r));
+      s.sessions.push(input);
+    }
+    return { record: input };
+  }
+  if (command === "LoadTransportSession" || command === "RemoveTransportSession") {
+    if (session && !sameOwner(session,q)) fail("host_transport_session_owner_mismatch");
+    if (command.startsWith("Remove")) {
+      if (session) retireSession(s,session);
+      return { sessionId, removed: Boolean(session) };
+    }
+    if (!session) fail("host_transport_session_invalid");
+    const parent = s.credentials.find(c => c.credentialId === session.credentialId);
+    if (parent?.state !== "active" || parent.expiresAt <= timestamp) fail("host_transport_credential_inactive");
+    if (session.expiresAt <= timestamp) fail("host_transport_session_expired");
+    return { record: session };
+  }
+  if (command === "ResolveTransport" || command === "VerifyTransport") {
+    const c = unique(owned(q),"host_transport_credential_required","host_transport_credential_ambiguous");
+    if (c.expiresAt <= timestamp) fail("host_transport_credential_expired");
+    const sessions = s.sessions.filter(r => r.credentialId === c.credentialId && sameOwner(r,q));
+    if (sessions.length > 1) fail("host_transport_session_ambiguous");
+    let selected = sessions[0] || null;
+    if (selected && selected.expiresAt <= timestamp) {
+      if (command.startsWith("Resolve")) retireSession(s,selected);
+      selected = null;
+    }
+    if (command.startsWith("Resolve")) return { credential:c, session:selected };
+    const publicFields = ({credentialId,principalId,hostInstallationId,expiresAt}) => ({credentialId,principalId,hostInstallationId,expiresAt});
+    return { credential:publicFields(c), session:selected && {...publicFields(selected),sessionId:selected.sessionId} };
+  }
+  fail("host_protected_store_command_invalid");
+}
+
+function emptyHost(enrollment = { contract:"hellolynk-device-enrollment-v1", revision:0, value:null }) {
+  return { caps:[], credentials:[], sessions:[], retiredSessions:[], codex:null, enrollment };
+}
+
+// On Windows the enrollment file exists independently of the capability file.
+// An unclaimed Mac Host may have only its enrollment in the shared vault. Read
+// its authenticated state without creating, repairing or replacing anything.
+export function verifyDarwinUnclaimedAuthorization(root) {
+  return withDarwinVault({ root, readOnly:true }, document => {
+    const enrollment = document?.host?.enrollment;
+    if (!exactFields(enrollment, ["contract", "revision", "value"])
+        || enrollment.contract !== "hellolynk-device-enrollment-v1"
+        || !Number.isSafeInteger(enrollment.revision) || enrollment.revision < 0
+        || (enrollment.value !== null && (typeof enrollment.value !== "object" || Array.isArray(enrollment.value)))) {
+      fail("device_enrollment_store_invalid");
+    }
+    if (!equal(document, { host:emptyHost(enrollment) })) fail("host_unclaimed_authorization_present");
+  });
+}
+
+export function invokeDarwinHost(q) {
+  const readOnly = q.verifyOnly || q.command.startsWith("Verify");
+  return withDarwinVault({ root:q.root, helperPath:q.helperPath, readOnly, signal:q.signal }, document => {
+    const s = document.host || emptyHost();
+    if (!readOnly) document.host = s;
+    const input = q.stdin ? JSON.parse(q.stdin) : null;
+    const old = s.caps.find(c => c.capabilityId === q.capabilityId);
+    switch (q.command) {
+      case "Status": return {contract:"hellolynk-host-protected-store-v1",protected:true};
+      case "LoadDeviceEnrollment": return s.enrollment;
+      case "SaveDeviceEnrollment":
+        if (s.enrollment.revision !== input.expectedRevision) fail("device_enrollment_revision_conflict");
+        s.enrollment.value = input.value;
+        s.enrollment.revision++;
+        return s.enrollment;
+      case "Issue": addCapability(s,input); return {record:input};
+      case "Load":
+        if (old?.state !== "active") fail("host_capability_inactive");
+        return {record:old};
+      case "Revoke": return revokeCapability(s,old);
+      case "Rotate":
+        if (old?.state !== "active") fail("host_capability_inactive");
+        addCapability(s,input);
+        revokeCapability(s,old);
+        return {record:input, replacedCapabilityId:q.capabilityId};
+      case "DisconnectLocalClient":
+        for (const cap of s.caps.filter(c => c.adapterId === input.client && c.state === "active")) revokeCapability(s,cap);
+        if (input.client === "codex") s.codex = null;
+        if (input.client === "claude-code") delete s.claudeCode;
+        return {disconnected:true,client:input.client};
+    }
+    const bindingCommand = /^(Resolve|Verify|Save|Remove|Replace|Migrate)(Codex|ClaudeCode)NeutralBinding$/.exec(q.command);
+    if (bindingCommand) {
+      return neutralBinding(s, bindingCommand[2] === "Codex" ? "codex" : "claude-code", bindingCommand[1], input, q.capabilityId);
+    }
+    if (q.command.includes("Transport")) return transport(s,q,input);
+    fail("host_protected_store_command_unsupported");
+  });
+}

package/plugins/hellolynk-codex/runtime/core/hellolynk-darwin-vault.mjs

@@ -0,0 +1,153 @@
+// macOS-only storage. Keychain holds the wrapping key. The SQLite rollback
+// journal and database contain a single authenticated, root-bound ciphertext.
+import { spawn } from "node:child_process";
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { closeSync, constants, lstatSync, mkdirSync, openSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+
+export const DARWIN_HELPER = fileURLToPath(new URL("../platform/darwin/hellolynk-keychain-helper.bin", import.meta.url));
+export const DARWIN_VAULT_FILE = "protected-v1.sqlite";
+// Neither the wrapping-key process nor the approval UI needs a caller's
+// shell, language runtime, dynamic-loader overrides or credential environment.
+export function darwinHelperEnvironment() {
+  return { HOME: homedir(), PATH: "/usr/bin:/bin", LANG: "en_US.UTF-8" };
+}
+export function vaultError(code) { return Object.assign(new Error(code), { code }); }
+
+// Validate before creating any missing components (including in a supplied
+// storeRoot). Never follow links or create children below a linked ancestor.
+export function checkDarwinPath(target, { directory = false, privateMode = false, create = false, missing = false } = {}) {
+  if (target === "/" || target !== resolve(target)) throw vaultError("macos_vault_path_invalid");
+  const parts = target.slice(1).split("/");
+  let current = "/";
+  for (const [index, name] of parts.entries()) {
+    current = join(current, name);
+    const dir = index < parts.length - 1 || directory;
+    let st = lstatSync(current, { throwIfNoEntry: false });
+    if (!st && create && dir) {
+      try { mkdirSync(current, { mode: 0o700 }); }
+      catch (error) { if (error.code !== "EEXIST") throw error; }
+      st = lstatSync(current);
+    }
+    if (!st && missing) return null;
+    if (!st || st.isSymbolicLink() || (dir ? !st.isDirectory() : !st.isFile())) throw vaultError("macos_vault_path_invalid");
+    if (index < parts.length - 1 && ((st.uid !== 0 && st.uid !== process.getuid()) ||
+      ((st.mode & 0o022) && !(st.uid === 0 && (st.mode & 0o1000))))) {
+      throw vaultError("macos_vault_ancestor_invalid");
+    }
+    if (index === parts.length - 1) {
+      if (privateMode && (st.uid !== process.getuid() || (st.mode & 0o077) || (!dir && st.nlink !== 1))) {
+        throw vaultError("macos_vault_permissions_invalid");
+      }
+      return st;
+    }
+  }
+}
+
+export async function invokeDarwinHelper(helper, args, signal) {
+  const st = checkDarwinPath(helper);
+  if ((st.mode & 0o022) || (st.uid !== 0 && st.uid !== process.getuid())) throw vaultError("macos_vault_helper_invalid");
+  signal?.throwIfAborted();
+  return new Promise((ok, reject) => {
+    const child = spawn(helper, args, { stdio: ["ignore", "ignore", "pipe", "pipe"],
+      env: darwinHelperEnvironment(), signal });
+    const chunks = [];
+    let size = 0, stderr = "";
+    const timer = setTimeout(() => child.kill("SIGKILL"), 30_000);
+    child.stdio[3].on("data", chunk => {
+      size += chunk.length;
+      if (size <= 32) chunks.push(chunk);
+      else child.kill("SIGKILL");
+    });
+    child.stderr.on("data", chunk => {
+      stderr += chunk;
+      if (stderr.length > 256) child.kill("SIGKILL");
+    });
+    child.on("error", error => { clearTimeout(timer); reject(error); });
+    child.on("close", code => {
+      clearTimeout(timer);
+      const data = Buffer.concat(chunks);
+      chunks.forEach(chunk => chunk.fill(0));
+      if (code === 0 && data.length === (args[0] === "key" ? 32 : 0)) return ok(data);
+      data.fill(0);
+      reject(vaultError(/^macos_[a-z0-9_]{1,100}$/.test(stderr.trim()) ? stderr.trim() : "macos_vault_helper_failed"));
+    });
+  });
+}
+
+function openDocument(key, aad, bytes) {
+  try {
+    const blob = Buffer.from(bytes);
+    const cipher = createDecipheriv("aes-256-gcm", key, blob.subarray(0, 12));
+    cipher.setAAD(aad);
+    cipher.setAuthTag(blob.subarray(12, 28));
+    return Buffer.concat([cipher.update(blob.subarray(28)), cipher.final()]);
+  } catch { throw vaultError("macos_vault_authentication_failed"); }
+}
+
+function sealDocument(key, aad, plain) {
+  const nonce = randomBytes(12);
+  const cipher = createCipheriv("aes-256-gcm", key, nonce);
+  cipher.setAAD(aad);
+  const body = Buffer.concat([cipher.update(plain), cipher.final()]);
+  return Buffer.concat([nonce, cipher.getAuthTag(), body]);
+}
+
+// The callback is synchronous. No event-loop work or network I/O is performed
+// while SQLite owns the write lock. Concurrent first writers share SecItemAdd's
+// winning key and re-read the committed document after BEGIN IMMEDIATE.
+export async function withDarwinVault({ root, helperPath = DARWIN_HELPER, readOnly = false, allowMissing = false, signal }, operation) {
+  const { DatabaseSync } = await import("node:sqlite");
+  const directory = checkDarwinPath(root, { directory: true, privateMode: true, create: !readOnly, missing: readOnly && allowMissing });
+  const path = join(root, DARWIN_VAULT_FILE);
+  let stat = directory && checkDarwinPath(path, { privateMode: true, missing: true });
+  if (!stat) {
+    if (readOnly) {
+      if (allowMissing) return operation({});
+      throw vaultError("host_protected_store_path_invalid");
+    }
+    try { closeSync(openSync(path, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600)); }
+    catch (error) { if (error.code !== "EEXIST") throw error; }
+    stat = checkDarwinPath(path, { privateMode: true });
+  }
+  const newFile = stat.size === 0;
+  const key = await invokeDarwinHelper(helperPath, ["key", root, !readOnly && newFile ? "create" : "load"], signal);
+  let db, plain, encoded;
+  try {
+    signal?.throwIfAborted();
+    checkDarwinPath(path, { privateMode: true });
+    checkDarwinPath(path + "-journal", { privateMode: true, missing: true });
+    for (const suffix of ["-wal", "-shm"]) {
+      if (lstatSync(path + suffix, { throwIfNoEntry: false })) throw vaultError("macos_vault_journal_invalid");
+    }
+    db = new DatabaseSync(path, { readOnly, allowExtension: false });
+    db.exec("PRAGMA trusted_schema=OFF; PRAGMA busy_timeout=10000");
+    if (db.prepare("PRAGMA journal_mode").get().journal_mode !== "delete") throw vaultError("macos_vault_journal_invalid");
+    db.exec(readOnly ? "BEGIN" : "BEGIN IMMEDIATE");
+    const schema = db.prepare("SELECT sql FROM sqlite_schema WHERE name = 'vault' AND type = 'table'").get();
+    if (!schema) {
+      if (!newFile || readOnly) throw vaultError("macos_vault_format_invalid");
+      db.exec("CREATE TABLE vault (id INTEGER PRIMARY KEY CHECK(id=1), sealed BLOB NOT NULL)");
+    }
+    const row = db.prepare("SELECT sealed FROM vault WHERE id=1").get();
+    if (schema && !row) throw vaultError("macos_vault_format_invalid");
+    const aad = Buffer.from("hellolynk-macos-vault-v1\0" + root);
+    plain = row ? openDocument(key, aad, row.sealed) : Buffer.from("{}");
+    const state = JSON.parse(plain);
+    const result = operation(state);
+    encoded = Buffer.from(JSON.stringify(state));
+    if (!row || !plain.equals(encoded)) {
+      if (readOnly) throw vaultError("host_protected_store_read_only");
+      db.prepare("INSERT OR REPLACE INTO vault(id,sealed) VALUES(1,?)").run(sealDocument(key, aad, encoded));
+    }
+    db.exec("COMMIT");
+    return result;
+  } finally {
+    key.fill(0);
+    plain?.fill(0);
+    encoded?.fill(0);
+    db?.close(); // closes or rolls back a transaction whose callback failed
+  }
+}