@byok-sdk/keys 0.2.1 → 0.3.0

package/README.md

@@ -105,6 +105,13 @@ dependency and the workspace release floor.
 | `TruthStoreProviderProfileStore` | Node 22.22+ plus an injected tenant-bound `TruthStore` | stale CAS or malformed/hash-mismatched authority fails closed; never falls back to SQLite |
 | `byok-pi-provider-launcher` | Node 22.5+ (`node:sqlite`) and macOS/Windows for authenticated profiles | fails closed; `auth_mode: none` does not require a credential backend |
 
+On macOS, an isolated host may select one explicit credential authority with
+`MacOsKeychainSecretStore({ keychainPath: '/absolute/path/to/keychain-db' })`
+or the launcher's `--macos-keychain-path` flag. The path must be absolute and
+single-line. Once selected, availability and every credential operation use
+that keychain only; the store never also searches the user default keychain.
+The launcher rejects this macOS-only flag on other platforms.
+
 Only on-disk profile persistence needs the newer runtime. `node:sqlite` shipped
 in Node 22.5 and spent part of the 22.x line behind `--experimental-sqlite`, so
 a version-number comparison would be wrong in both directions; call

package/dist/bin/pi-provider-launcher.js

@@ -2,7 +2,7 @@
 import { spawn } from 'child_process';
 import { promises, mkdirSync, existsSync, chmodSync } from 'fs';
 import os from 'os';
-import path, { dirname } from 'path';
+import path2, { dirname } from 'path';
 import { z } from 'zod';
 import { createRequire } from 'module';
 
@@ -100,6 +100,7 @@ var MacOsKeychainSecretStore = class _MacOsKeychainSecretStore {
   #account;
   #allowUnprefixedRead;
   #commandRunner;
+  #keychainPath;
   #platform;
   #servicePrefix;
   #storagePrefix;
@@ -107,6 +108,7 @@ var MacOsKeychainSecretStore = class _MacOsKeychainSecretStore {
     this.#account = options.account ?? "local-device";
     this.#allowUnprefixedRead = options.allowUnprefixedRead ?? false;
     this.#commandRunner = options.commandRunner ?? runCommand;
+    this.#keychainPath = assertKeychainPath(options.keychainPath);
     this.#platform = options.platform ?? process.platform;
     this.#servicePrefix = options.servicePrefix ?? DEFAULT_SECRET_SERVICE_PREFIX;
     this.#storagePrefix = options.storagePrefix ?? DEFAULT_KEYCHAIN_SECRET_STORAGE_PREFIX;
@@ -114,9 +116,7 @@ var MacOsKeychainSecretStore = class _MacOsKeychainSecretStore {
   async available() {
     if (this.#platform !== "darwin") return false;
     const result = await this.#commandRunner("/usr/bin/security", [
-      "default-keychain",
-      "-d",
-      "user"
+      ...this.#keychainPath === void 0 ? ["default-keychain", "-d", "user"] : ["show-keychain-info", this.#keychainPath]
     ]);
     return result.exitCode === 0;
   }
@@ -128,7 +128,8 @@ var MacOsKeychainSecretStore = class _MacOsKeychainSecretStore {
       "-a",
       this.#account,
       "-s",
-      service
+      service,
+      ...this.#keychainPath === void 0 ? [] : [this.#keychainPath]
     ]);
     if (result.exitCode === SECURITY_ITEM_NOT_FOUND) return false;
     if (result.exitCode !== 0) {
@@ -148,7 +149,8 @@ var MacOsKeychainSecretStore = class _MacOsKeychainSecretStore {
       this.#account,
       "-s",
       service,
-      "-w"
+      "-w",
+      ...this.#keychainPath === void 0 ? [] : [this.#keychainPath]
     ]);
     if (result.exitCode === SECURITY_ITEM_NOT_FOUND) return void 0;
     if (result.exitCode !== 0) {
@@ -167,6 +169,7 @@ var MacOsKeychainSecretStore = class _MacOsKeychainSecretStore {
       account: this.#account,
       allowUnprefixedRead: this.#allowUnprefixedRead,
       commandRunner: this.#commandRunner,
+      keychainPath: this.#keychainPath,
       platform: this.#platform,
       servicePrefix: `${this.#servicePrefix}.scope.${assertSecretNamespace(namespace)}`,
       storagePrefix: this.#storagePrefix
@@ -190,7 +193,8 @@ var MacOsKeychainSecretStore = class _MacOsKeychainSecretStore {
       "-s",
       quoteSecurityInteractiveArgument(service),
       "-w",
-      quoteSecurityInteractiveArgument(storedSecret)
+      quoteSecurityInteractiveArgument(storedSecret),
+      ...this.#keychainPath === void 0 ? [] : [quoteSecurityInteractiveArgument(this.#keychainPath)]
     ].join(" ");
     const result = await this.#commandRunner(
       "/usr/bin/security",
@@ -249,6 +253,16 @@ function quoteSecurityInteractiveArgument(value) {
   }
   return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
 }
+function assertKeychainPath(keychainPath) {
+  if (keychainPath === void 0) return void 0;
+  if (keychainPath.length === 0 || !path2.posix.isAbsolute(keychainPath) || /[\u0000\r\n]/u.test(keychainPath)) {
+    throw new ByokKeysError(
+      "KEYCHAIN_ARGUMENT_INVALID",
+      "macOS keychain path must be a non-empty absolute single-line path"
+    );
+  }
+  return keychainPath;
+}
 
 // src/pi-provider-projection.ts
 var PI_PROJECTED_KEY_ENV = "PI_PROVIDER_API_KEY";
@@ -476,7 +490,8 @@ function parsePiProviderLauncherOptions(args) {
     "--provider",
     "--model",
     "--session-dir",
-    "--secret-service-prefix"
+    "--secret-service-prefix",
+    "--macos-keychain-path"
   ]);
   const values = /* @__PURE__ */ new Map();
   for (let index = 0; index < ownArgs.length; index += 2) {
@@ -505,10 +520,14 @@ function parsePiProviderLauncherOptions(args) {
   if (modelId.length > 160) throw new Error("--model exceeds 160 characters");
   const profileDbPath = required("--profile-db");
   const sessionDir = required("--session-dir");
-  if (!path.isAbsolute(profileDbPath) || !path.isAbsolute(sessionDir)) {
+  if (!path2.isAbsolute(profileDbPath) || !path2.isAbsolute(sessionDir)) {
     throw new Error("launcher profile database and session directory must be absolute paths");
   }
   const secretServicePrefix = values.get("--secret-service-prefix");
+  const macosKeychainPath = values.get("--macos-keychain-path");
+  if (macosKeychainPath !== void 0 && !path2.posix.isAbsolute(macosKeychainPath)) {
+    throw new Error("--macos-keychain-path must be an absolute path");
+  }
   return {
     piBin: required("--pi-bin"),
     profileDbPath,
@@ -516,6 +535,7 @@ function parsePiProviderLauncherOptions(args) {
     modelId,
     sessionDir,
     ...secretServicePrefix ? { secretServicePrefix } : {},
+    ...macosKeychainPath !== void 0 ? { macosKeychainPath } : {},
     piArgs
   };
 }
@@ -604,19 +624,19 @@ function loadSqliteModule() {
     );
   }
 }
-function openSqliteDatabase(path3, options, faults) {
+function openSqliteDatabase(path4, options, faults) {
   const { DatabaseSync } = loadSqliteModule();
   const readOnly = options?.readOnly === true;
-  if (path3 !== ":memory:" && !readOnly) {
-    mkdirSync(dirname(path3), { mode: SECURE_DIR_MODE, recursive: true });
+  if (path4 !== ":memory:" && !readOnly) {
+    mkdirSync(dirname(path4), { mode: SECURE_DIR_MODE, recursive: true });
   }
-  const database = new DatabaseSync(path3, {
+  const database = new DatabaseSync(path4, {
     timeout: DEFAULT_BUSY_TIMEOUT_MS,
     ...options
   });
   try {
     faults?.onStep?.("after-open");
-    if (path3 !== ":memory:" && !readOnly) {
+    if (path4 !== ":memory:" && !readOnly) {
       database.exec("PRAGMA journal_mode = WAL");
       faults?.onStep?.("after-wal");
       database.exec("PRAGMA synchronous = FULL");
@@ -1045,10 +1065,19 @@ function assertWindowsCredentialSecret(secret) {
 }
 
 // src/bin/pi-provider-launcher.ts
-function createSecretStore(servicePrefix) {
+function createSecretStore(servicePrefix, macosKeychainPath) {
+  if (macosKeychainPath !== void 0 && process.platform !== "darwin") {
+    throw new ByokKeysError(
+      "KEYCHAIN_UNAVAILABLE",
+      "macOS keychain path is only supported on darwin"
+    );
+  }
   switch (process.platform) {
     case "darwin":
-      return new MacOsKeychainSecretStore({ servicePrefix });
+      return new MacOsKeychainSecretStore({
+        keychainPath: macosKeychainPath,
+        servicePrefix
+      });
     case "win32":
       return new WindowsCredentialManagerSecretStore({ servicePrefix });
     default:
@@ -1059,6 +1088,12 @@ function createSecretStore(servicePrefix) {
   }
 }
 async function run(options) {
+  if (options.macosKeychainPath !== void 0 && process.platform !== "darwin") {
+    throw new ByokKeysError(
+      "KEYCHAIN_UNAVAILABLE",
+      "macOS keychain path is only supported on darwin"
+    );
+  }
   const profiles = new SqliteProviderProfileStore({
     path: options.profileDbPath,
     readOnly: true
@@ -1076,14 +1111,17 @@ async function run(options) {
     }
     const secret = await resolvePiProviderSecret(
       profile,
-      () => createSecretStore(options.secretServicePrefix)
+      () => createSecretStore(
+        options.secretServicePrefix,
+        options.macosKeychainPath
+      )
     );
-    projectionDir = await promises.mkdtemp(path.join(os.tmpdir(), "byok-pi-provider-"));
+    projectionDir = await promises.mkdtemp(path2.join(os.tmpdir(), "byok-pi-provider-"));
     await promises.chmod(projectionDir, 448).catch(() => {
     });
     await ensurePiSessionDirectory(options.sessionDir);
     await promises.writeFile(
-      path.join(projectionDir, "models.json"),
+      path2.join(projectionDir, "models.json"),
       `${JSON.stringify(buildPiProviderProjection(profile))}
 `,
       { mode: 384 }