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

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

@@ -0,0 +1,256 @@
+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) {
+  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("neutral_codex_launch_manifest_invalid");
+  } catch { fail("neutral_codex_launch_manifest_invalid"); }
+}
+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 codexBinding(s, command, input, oldId) {
+  const b = s.codex;
+  if (command === "ResolveCodexNeutralBinding" || command === "VerifyCodexNeutralBinding") {
+    if (!b) fail("neutral_codex_binding_configuration_required");
+    checkBindingPaths(b);
+    const active = s.caps.filter(c => c.adapterId === "codex" && c.state === "active");
+    const cap = unique(active.filter(c => capMatches(c, b)),
+      active.length ? "neutral_codex_capability_binding_mismatch" : "neutral_codex_capability_missing", "neutral_codex_capability_ambiguous");
+    if (command.startsWith("Resolve")) return { binding: b, record: cap };
+    const {secret, ...record} = cap;
+    return { binding: b, record };
+  }
+  if (command === "SaveCodexNeutralBinding" || command === "RemoveCodexNeutralBinding") {
+    checkBindingPaths(input);
+    if (command.startsWith("Remove")) {
+      if (!equal(b, input)) fail("neutral_codex_binding_invalid");
+      s.codex = null;
+      return { removed: true };
+    }
+    if (b && !equal(b, input)) fail("neutral_codex_binding_invalid");
+    s.codex = input;
+    return { binding: input };
+  }
+  const { previousBinding: previous, replacementBinding: next, replacementRecord } = input;
+  checkBindingPaths(previous);
+  checkBindingPaths(next);
+  if (!fieldsMatch(previous, next, ["contract","region","principalId","delegateId","hostInstallationId","profileId","adapterId","version","runtimeRoot"])) {
+    fail("neutral_codex_capability_binding_mismatch");
+  }
+  if (!equal(b, previous)) fail("neutral_codex_binding_invalid");
+  const active = s.caps.filter(c => capMatches(c, next));
+  if (command === "ReplaceCodexNeutralBinding") {
+    if (!equal(previous.scopes, next.scopes)) fail("neutral_codex_capability_binding_mismatch");
+    if (active.length !== 1) fail("neutral_codex_capability_ambiguous");
+    s.codex = next;
+    return { binding: next };
+  }
+  if (command !== "MigrateCodexNeutralBinding") fail("host_protected_store_command_invalid");
+  const old = s.caps.find(c => c.capabilityId === oldId);
+  if (!old || !capMatches(old, previous) || !capMatches(replacementRecord, next)) fail("neutral_codex_capability_binding_mismatch");
+  const other = active.filter(c => c.capabilityId !== oldId);
+  if (other.length > 1) fail("neutral_codex_capability_ambiguous");
+  if (!other.length) addCapability(s, replacementRecord);
+  revokeCapability(s, old);
+  s.codex = 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;
+        return {disconnected:true,client:input.client};
+    }
+    if (q.command.endsWith("CodexNeutralBinding")) return codexBinding(s,q.command,input,q.capabilityId);
+    if (q.command.includes("Transport")) return transport(s,q,input);
+    fail("host_protected_store_command_unsupported");
+  });
+}

package/plugins/hellolynk-codex/runtime/bootstrap/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
+  }
+}

package/plugins/hellolynk-codex/runtime/bootstrap/core/hellolynk-host-protected-store.mjs

@@ -1,3 +1,5 @@
+import { invokeDarwinHost } from "./hellolynk-darwin-host.mjs";
+import { checkDarwinPath, DARWIN_HELPER, invokeDarwinHelper } from "./hellolynk-darwin-vault.mjs";
 import { randomBytes } from "node:crypto";
 import { lstat, mkdir } from "node:fs/promises";
 import { createConnection } from "node:net";
@@ -142,7 +144,7 @@ const READ_ONLY_COMMANDS = new Set([
 ]);
 
 export function defaultClaudeCodeStoreRoot(env = process.env) {
-  return defaultNeutralHostStoreRoot("win32", env);
+  return defaultNeutralHostStoreRoot(process.platform, env);
 }
 
 function assertClaudeCodeStoreRoot(root) {
@@ -154,9 +156,9 @@ function assertClaudeCodeStoreRoot(root) {
 
 export function createHostProtectedStore(options = {}) {
   const platform = options.platform || process.platform;
-  if (platform !== "win32") throw codeError("host_protected_store_platform_unsupported");
+  if (!["darwin", "win32"].includes(platform)) throw codeError("host_protected_store_platform_unsupported");
   const root = assertRoot(options.root || defaultNeutralHostStoreRoot(platform, options.env));
-  const helperPath = resolve(options.helperPath || SCRIPT_PATH);
+  const helperPath = resolve(options.helperPath || (platform === "darwin" ? DARWIN_HELPER : SCRIPT_PATH));
   const clock = normalizeClock(options.clock);
   const random = typeof options.randomBytes === "function" ? options.randomBytes : randomBytes;
   const readOnly = options.readOnly === true;
@@ -166,12 +168,12 @@ export function createHostProtectedStore(options = {}) {
     verifyPath: ({ path, directory }) => verifyHostProtectedStorePath({
       root,
       path,
-      directory,
+      directory, platform,
       helperPath,
       signal: options.signal,
     }),
   } : { root });
-  const nativeInvoke = (command, invokeOptions) => invokeWindowsStore({
+  const nativeInvoke = (command, invokeOptions) => (platform === "darwin" ? invokeDarwinHost : invokeWindowsStore)({
     command, root, helperPath, verifyOnly: readOnly, ...(readOnly ? { signal: options.signal } : {}), ...invokeOptions,
   });
   const baseInvoke = options.invoke || ((command, invokeOptions) => serializeRootInvoke(root, () => nativeInvoke(command, invokeOptions)));
@@ -180,7 +182,7 @@ export function createHostProtectedStore(options = {}) {
     // Each peer lookup creates a read-only store. Reuse its successful DPAPI
     // result across those instances, while checking live paths and the file
     // on every use. Registration/account checks remain in the public methods.
-    if (readOnly && !options.invoke && NEUTRAL_BINDING_READ.test(command)) {
+    if (platform === "win32" && readOnly && !options.invoke && NEUTRAL_BINDING_READ.test(command)) {
       return readNeutralBinding(command, invokeOptions);
     }
     try {
@@ -271,6 +273,7 @@ export function createHostProtectedStore(options = {}) {
 
   async function resolveCapability(capabilityId) {
     const id = assertCapabilityId(capabilityId);
+    if (platform === "darwin") return currentCapability(await load(id));
     for (let attempt = 0; attempt < 2; attempt += 1) {
       const fingerprint = await readCapabilityStoreFingerprint();
       if (fingerprint !== capabilityCacheFingerprint) {
@@ -1347,13 +1350,22 @@ async function protectedPathFingerprint(root, target, helperPath, directory, sig
 }
 
 export async function verifyHostProtectedStorePath(options = {}) {
-  const root = assertRoot(options.root || defaultNeutralHostStoreRoot("win32", options.env));
+  const platform = options.platform || process.platform;
+  const root = assertRoot(options.root || defaultNeutralHostStoreRoot(platform, options.env));
   const target = resolve(String(options.path || ""));
   const relativeTarget = relative(root, target);
   if (!isAbsolute(String(options.path || ""))
-    || (relativeTarget !== "" && (isAbsolute(relativeTarget) || relativeTarget === ".." || relativeTarget.startsWith(`..\\`)))) {
+    || (relativeTarget !== "" && (isAbsolute(relativeTarget) || relativeTarget === ".." || relativeTarget.startsWith("../") || relativeTarget.startsWith(`..\\`)))) {
     throw codeError("host_protected_store_path_invalid");
   }
+  if (platform === "darwin") {
+    checkDarwinPath(root, { directory: true, privateMode: true });
+    checkDarwinPath(target, { directory: options.directory === true, privateMode: true });
+    const helper = options.helperPath || DARWIN_HELPER;
+    await invokeDarwinHelper(helper, ["verify-acl", root], options.signal);
+    if (target !== root) await invokeDarwinHelper(helper, ["verify-acl", target], options.signal);
+    return Object.freeze({ verified: true });
+  }
   const helperPath = resolve(options.helperPath || SCRIPT_PATH);
   const directory = options.directory === true;
   const key = JSON.stringify([root, target, helperPath, directory]);

package/plugins/hellolynk-codex/runtime/bootstrap/core/hellolynk-neutral-host-installation-store.mjs

@@ -12,10 +12,9 @@ import {
 } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, parse, resolve } from "node:path";
 import { spawn } from "node:child_process";
-import { homedir } from "node:os";
 import { performance } from "node:perf_hooks";
 import { withLocalProcessLock } from "./hellolynk-local-process-lock.mjs";
-import { readClientProfile } from "./hellolynk-client-profile.mjs";
+import { defaultHelloLynkClientRoot, readClientProfile } from "./hellolynk-client-profile.mjs";
 import { assertIdentifier } from "./hellolynk-host-auth.mjs";
 import runtimeSafety from "./hellolynk-runtime-safety.cjs";
 
@@ -46,10 +45,7 @@ export function defaultNeutralHostStoreRoot(platform = process.platform, env = p
     }
     return root;
   }
-  const home = resolve(String(env.HOME || env.USERPROFILE || homedir()));
-  if (platform === "win32") return resolve(String(env.LOCALAPPDATA || join(home, "AppData", "Local")), "HelloLynk", "host");
-  if (platform === "darwin") return join(home, "Library", "Application Support", "HelloLynk", "host");
-  return resolve(String(env.XDG_DATA_HOME || join(home, ".local", "share")), "hellolynk", "host");
+  return join(defaultHelloLynkClientRoot(platform, env), "host");
 }
 
 export function createNeutralHostInstallationStore(options = {}) {
@@ -344,7 +340,7 @@ async function assertReadOnlyPath(path, directory, verifyPath) {
   if (metadata.isSymbolicLink() || (directory ? !metadata.isDirectory() : !metadata.isFile())) {
     throw codeError(directory ? "host_store_root_invalid" : "host_registry_path_invalid");
   }
-  if (process.platform === "win32") {
+  if (process.platform === "win32" || (process.platform === "darwin" && verifyPath)) {
     await verifyPath({ path, directory });
   }
 }

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