@byok-sdk/keys 0.5.0 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # @byok-sdk/keys
 
-Pi launcher configuration in the unpublished 0.5.0 candidate is explicit.
+Pi launcher configuration is explicit, from the published 0.5.0 onward.
 Set `pi_model` on `ProviderRegistry.configure` for profiles used by Pi:
 
 ```ts

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

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
+import path2, { dirname, isAbsolute } from 'path';
 import { spawn } from 'child_process';
-import { promises, mkdirSync, existsSync, chmodSync } from 'fs';
-import os from 'os';
-import path2, { isAbsolute, dirname } from 'path';
 import { z } from 'zod';
 import { createHash } from 'crypto';
+import { promises, mkdirSync, existsSync, chmodSync } from 'fs';
+import { parseImplementationSpawnBinding, assertImplementationSpawnBinding, projectKeysPiInheritedEnvironment } from '@byok-sdk/implementation-identity';
 import { createRequire } from 'module';
 
 // src/errors.ts
@@ -591,6 +591,7 @@ function assertKeychainPath(keychainPath) {
   return keychainPath;
 }
 var PI_PROJECTED_KEY_ENV = "PI_PROVIDER_API_KEY";
+var PI_LAUNCHER_RUNTIME_ENTRIES = ["pi-rpc", "pi-prepared"];
 function piProjectionProviderId(profileRef) {
   return `byok-sdk-${profileRef}`;
 }
@@ -632,7 +633,14 @@ function buildPiProviderArgs(profile, delegatedArgs) {
       if (singleFlags.has(flag)) throw new Error(`Pi launcher duplicate argument ${flag}`);
       singleFlags.add(flag);
     }
-    if (flag === "--no-tools") continue;
+    if (flag === "--no-tools" || flag === "--no-skills" || flag === "--no-extensions") continue;
+    if (flag === "--config") {
+      const value = delegatedArgs[++index];
+      if (typeof value !== "string" || !isAbsolute(value) || /[\u0000\r\n]/u.test(value)) {
+        throw new Error("Pi launcher --config requires an absolute single-line path");
+      }
+      continue;
+    }
     if (flag === "--extension") {
       const value = delegatedArgs[++index];
       if (typeof value !== "string" || !isAbsolute(value) || /[\u0000\r\n]/u.test(value)) {
@@ -672,42 +680,22 @@ function buildPiProviderArgs(profile, delegatedArgs) {
     config.thinkingLevel
   ];
 }
+function buildPiPreparedArgs(delegatedArgs) {
+  if (delegatedArgs.length !== 2 || delegatedArgs[0] !== "--config") {
+    throw new Error("Pi prepared launcher requires exactly --config <path>");
+  }
+  const value = delegatedArgs[1];
+  if (typeof value !== "string" || !isAbsolute(value) || /[\u0000\r\n]/u.test(value)) {
+    throw new Error("Pi launcher --config requires an absolute single-line path");
+  }
+  return [...delegatedArgs];
+}
 function requirePiModelConfig(profile) {
   if (profile.pi_model === void 0) throw new Error("Pi execution requires explicit pi_model configuration");
   return PiModelConfigSchema.parse(profile.pi_model);
 }
 
 // src/pi-provider-launcher-core.ts
-var PI_CHILD_BASE_ENV_NAMES = [
-  "PATH",
-  "HOME",
-  "USERPROFILE",
-  "TMPDIR",
-  "TEMP",
-  "TMP",
-  "LANG",
-  "TZ",
-  "TERM",
-  "SHELL",
-  "HTTP_PROXY",
-  "HTTPS_PROXY",
-  "NO_PROXY",
-  "ALL_PROXY",
-  "http_proxy",
-  "https_proxy",
-  "no_proxy",
-  "all_proxy"
-];
-var PI_CHILD_WINDOWS_ENV_NAMES = [
-  "SystemRoot",
-  "COMSPEC",
-  "PATHEXT",
-  "windir",
-  "SYSTEMDRIVE",
-  "PROGRAMFILES",
-  "APPDATA",
-  "LOCALAPPDATA"
-];
 function parsePiProviderLauncherOptions(args) {
   const separator = args.indexOf("--");
   const ownArgs = separator < 0 ? args : args.slice(0, separator);
@@ -715,6 +703,11 @@ function parsePiProviderLauncherOptions(args) {
   const allowedFlags = /* @__PURE__ */ new Set([
     "--pi-bin",
     "--pi-entry",
+    "--launch-binding",
+    "--pi-cwd",
+    "--pi-fixed-args",
+    "--pi-config-digest",
+    "--runtime-entry",
     "--profile-db",
     "--provider",
     "--model",
@@ -745,6 +738,11 @@ function parsePiProviderLauncherOptions(args) {
     if (value === void 0) throw new Error(`${flag} requires a value`);
     return value;
   };
+  const rawRuntimeEntry = required("--runtime-entry");
+  if (!PI_LAUNCHER_RUNTIME_ENTRIES.includes(rawRuntimeEntry)) {
+    throw new Error(`--runtime-entry must be one of [${PI_LAUNCHER_RUNTIME_ENTRIES.join(", ")}]`);
+  }
+  const runtimeEntry = rawRuntimeEntry;
   const rawProfileRef = required("--provider");
   const profileRef = ProviderProfileRefSchema.safeParse(rawProfileRef);
   if (!profileRef.success) {
@@ -807,9 +805,49 @@ function parsePiProviderLauncherOptions(args) {
   if (piEntry !== void 0 && (!path2.isAbsolute(piEntry) || /[\u0000\r\n]/u.test(piEntry))) {
     throw new Error("--pi-entry requires an absolute single-line path");
   }
+  let launchBinding;
+  let piCwd;
+  let piFixedArgs;
+  if (!validateOnly || ["--launch-binding", "--pi-cwd", "--pi-fixed-args"].some((flag) => values.has(flag))) {
+    let rawBinding;
+    let rawFixedArgs;
+    try {
+      rawBinding = JSON.parse(required("--launch-binding"));
+    } catch {
+      throw new Error("--launch-binding requires a valid JSON binding");
+    }
+    launchBinding = parseImplementationSpawnBinding(rawBinding);
+    if (launchBinding === void 0) throw new Error("invalid implementation spawn binding");
+    piCwd = required("--pi-cwd");
+    try {
+      rawFixedArgs = JSON.parse(required("--pi-fixed-args"));
+    } catch {
+      throw new Error("--pi-fixed-args requires a JSON array");
+    }
+    if (!Array.isArray(rawFixedArgs) || rawFixedArgs.some((arg) => typeof arg !== "string")) {
+      throw new Error("--pi-fixed-args requires a JSON array of strings");
+    }
+    piFixedArgs = rawFixedArgs;
+    if (launchBinding.command !== required("--pi-bin") || launchBinding.entry !== piEntry || launchBinding.cwd !== piCwd || JSON.stringify(launchBinding.fixedArgv) !== JSON.stringify(piFixedArgs)) {
+      throw new Error("launcher arguments differ from implementation spawn binding");
+    }
+    if (launchBinding.envCommitments.PI_CODING_AGENT_SESSION_DIR !== sessionDir || launchBinding.envCommitments.PI_CODING_AGENT_DIR === void 0) {
+      throw new Error("launcher session/projection directories must match binding commitments");
+    }
+  }
+  const piConfigDigest = values.get("--pi-config-digest");
+  if ((!validateOnly || piConfigDigest !== void 0) && !/^[0-9a-f]{64}$/u.test(piConfigDigest ?? "")) {
+    throw new Error("--pi-config-digest requires 64 lowercase hexadecimal characters");
+  }
+  if (piArgs.some((arg) => arg === "--config-digest" || arg.startsWith("--config-digest="))) {
+    throw new Error("delegated --config-digest override is forbidden");
+  }
   return {
+    ...piConfigDigest === void 0 ? {} : { piConfigDigest },
     ...piEntry === void 0 ? {} : { piEntry },
+    runtimeEntry,
     piBin: required("--pi-bin"),
+    ...launchBinding === void 0 ? {} : { launchBinding, piCwd, piFixedArgs },
     profileDbPath,
     profileRef: profileRef.data,
     modelId,
@@ -821,6 +859,20 @@ function parsePiProviderLauncherOptions(args) {
     piArgs
   };
 }
+function assertPiPreparedProviderProfile(profile) {
+  if (profile.adapter === "anthropic") {
+    throw new ByokKeysError(
+      "PROVIDER_PROFILE_INVALID",
+      `${profile.profile_ref} speaks the anthropic adapter; the prepared runtime entry compiles openai-completions only`
+    );
+  }
+  if (profile.auth_mode === "none") {
+    throw new ByokKeysError(
+      "PROVIDER_PROFILE_INVALID",
+      `${profile.profile_ref} declares auth_mode "none"; the prepared runtime entry requires a provider credential`
+    );
+  }
+}
 async function resolvePiProviderSecret(profile, createStore) {
   if (profile.auth_mode === "none") return void 0;
   const secrets = createStore();
@@ -840,33 +892,139 @@ async function resolvePiProviderSecret(profile, createStore) {
   return secret;
 }
 function buildPiProviderChildEnvironment(options) {
-  const platform = options.platform ?? process.platform;
-  const exactNames = new Set([
-    ...PI_CHILD_BASE_ENV_NAMES,
-    ...platform === "win32" ? PI_CHILD_WINDOWS_ENV_NAMES : []
-  ].map((name) => platform === "win32" ? name.toUpperCase() : name));
-  const result = {};
-  for (const [name, value] of Object.entries(options.ambient)) {
-    if (value === void 0) continue;
-    const platformName = platform === "win32" ? name.toUpperCase() : name;
-    const isExact = exactNames.has(platformName);
-    const isPrefixed = platform === "win32" ? platformName.startsWith("LC_") || platformName.startsWith("XDG_") : name.startsWith("LC_") || name.startsWith("XDG_");
-    if (isExact || isPrefixed) result[name] = value;
-  }
-  const mcpPath = options.ambient.BYOK_PI_MCP_CONFIG_PATH;
-  if (mcpPath !== void 0) {
-    if (!path2.isAbsolute(mcpPath) || /[\u0000\r\n]/u.test(mcpPath)) throw new Error("BYOK_PI_MCP_CONFIG_PATH must be an absolute single-line path");
-    result.BYOK_PI_MCP_CONFIG_PATH = mcpPath;
-  }
-  const permissionMode = options.ambient.BYOK_PI_PERMISSION_MODE;
-  if (permissionMode !== void 0) {
-    if (permissionMode !== "auto" && permissionMode !== "readonly") throw new Error("BYOK_PI_PERMISSION_MODE must be auto or readonly");
-    result.BYOK_PI_PERMISSION_MODE = permissionMode;
-  }
-  result.PI_CODING_AGENT_DIR = options.projectionDir;
-  result.PI_CODING_AGENT_SESSION_DIR = options.sessionDir;
+  const binding = parseImplementationSpawnBinding(options.binding);
+  if (binding === void 0) throw new Error("invalid implementation spawn binding");
+  if (binding.envCommitments.PI_CODING_AGENT_SESSION_DIR !== options.sessionDir || binding.envCommitments.PI_CODING_AGENT_DIR === void 0) {
+    throw new Error("launcher session/projection directories must match binding commitments");
+  }
+  const result = {
+    ...projectKeysPiInheritedEnvironment(options.ambient, options.platform),
+    ...binding.envCommitments
+  };
   return result;
 }
+var WINDOWS_PROJECTION_ACL_SCRIPT = String.raw`
+$ErrorActionPreference = 'Stop'
+try {
+  $request = [Console]::In.ReadToEnd() | ConvertFrom-Json
+  $acl = Get-Acl -LiteralPath ([string]$request.path)
+  $sidType = [System.Security.Principal.SecurityIdentifier]
+  $rules = @($acl.Access | ForEach-Object {
+    $sid = if ($_.IdentityReference -is [System.Security.Principal.SecurityIdentifier]) { $_.IdentityReference.Value } else { try { $_.IdentityReference.Translate($sidType).Value } catch { $null } }
+    [ordered]@{
+      sid = $sid
+      allow = $_.AccessControlType -eq [System.Security.AccessControl.AccessControlType]::Allow
+      fullControl = ($_.FileSystemRights -band [System.Security.AccessControl.FileSystemRights]::FullControl) -eq [System.Security.AccessControl.FileSystemRights]::FullControl
+      inherits = ($_.InheritanceFlags -band 3) -eq 3 -and $_.PropagationFlags -eq [System.Security.AccessControl.PropagationFlags]::None
+    }
+  })
+  [ordered]@{
+    reparsePoint = ((Get-Item -LiteralPath ([string]$request.path) -Force).Attributes -band [System.IO.FileAttributes]::ReparsePoint) -ne 0
+    owner = $acl.GetOwner($sidType).Value
+    currentUser = [System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value
+    protected = $acl.AreAccessRulesProtected
+    rules = $rules
+  } | ConvertTo-Json -Depth 4 -Compress
+} catch {
+  [Console]::Error.WriteLine('Pi projection ACL query failed')
+  exit 1
+}
+`;
+async function assertWindowsPiProjectionAcl(directory, options = {}) {
+  const systemRoot = options.systemRoot ?? process.env.SystemRoot;
+  if (systemRoot === void 0 || !path2.win32.isAbsolute(systemRoot) || /[\u0000\r\n]/u.test(systemRoot)) {
+    throw new Error("Windows SystemRoot must be an absolute path");
+  }
+  const result = await (options.run ?? runCommand)(
+    path2.win32.join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe"),
+    ["-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(WINDOWS_PROJECTION_ACL_SCRIPT, "utf16le").toString("base64")],
+    JSON.stringify({ path: directory })
+  );
+  if (result.exitCode !== 0) throw new Error("Pi projection ACL query failed");
+  let acl;
+  try {
+    acl = JSON.parse(result.stdout);
+  } catch {
+    throw new Error("pi_projection_acl_invalid_json");
+  }
+  const recordObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+  if (!recordObject(acl) || Object.keys(acl).sort().join(",") !== "currentUser,owner,protected,reparsePoint,rules" || typeof acl.owner !== "string" || !/^S-1-[0-9-]+$/u.test(acl.owner) || typeof acl.currentUser !== "string" || !/^S-1-[0-9-]+$/u.test(acl.currentUser) || typeof acl.protected !== "boolean" || typeof acl.reparsePoint !== "boolean" || !Array.isArray(acl.rules)) {
+    throw new Error("pi_projection_acl_invalid_shape");
+  }
+  if (acl.reparsePoint) throw new Error("pi_projection_reparse_point: Pi projection path must be a non-symlink directory");
+  if (acl.owner !== acl.currentUser) throw new Error("pi_projection_owner_mismatch: Pi projection directory must be owned by the current user");
+  if (!acl.protected) throw new Error("pi_projection_acl_unprotected");
+  const principals = /* @__PURE__ */ new Set([acl.owner, "S-1-5-18", "S-1-5-32-544"]);
+  let ownerControl = false;
+  for (const rule of acl.rules) {
+    if (!recordObject(rule) || Object.keys(rule).sort().join(",") !== "allow,fullControl,inherits,sid" || typeof rule.sid !== "string" || !/^S-1-[0-9-]+$/u.test(rule.sid) || typeof rule.allow !== "boolean" || typeof rule.fullControl !== "boolean" || typeof rule.inherits !== "boolean") {
+      throw new Error("pi_projection_acl_invalid_ace");
+    }
+    if (!principals.has(rule.sid) || !rule.allow) throw new Error("pi_projection_acl_unauthorized_ace");
+    if (rule.sid === acl.owner && rule.fullControl && rule.inherits) ownerControl = true;
+  }
+  if (!ownerControl) throw new Error("pi_projection_acl_owner_access_missing");
+}
+async function assertPiProjectionDirectory(projectionDir, expectedDir) {
+  if (projectionDir !== expectedDir || !path2.isAbsolute(projectionDir) || path2.normalize(projectionDir) !== projectionDir) {
+    throw new Error("pi_projection_path_mismatch: Pi projection directory differs from committed path");
+  }
+  const stat = await promises.lstat(projectionDir);
+  if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error("pi_projection_not_directory_or_symlink: Pi projection path must be a non-symlink directory");
+  if (await promises.realpath(projectionDir) !== projectionDir) throw new Error("pi_projection_path_not_canonical: Pi projection directory parents must be canonical, without symlinks");
+  if (process.platform === "win32") {
+    await assertWindowsPiProjectionAcl(projectionDir);
+  } else {
+    if (stat.uid !== process.getuid()) throw new Error("pi_projection_owner_mismatch: Pi projection directory must be owned by the current uid");
+    if ((stat.mode & 4095) !== 448) throw new Error("pi_projection_mode_mismatch: Pi projection directory must have mode 0700");
+  }
+  if ((await promises.readdir(projectionDir)).length !== 0) throw new Error("pi_projection_not_empty: Pi projection directory must be empty");
+}
+async function startPiProvider(profile, options, dependencies) {
+  const binding = options.launchBinding;
+  if (options.validateOnly || binding === void 0 || options.piCwd === void 0 || options.piFixedArgs === void 0 || !/^[0-9a-f]{64}$/u.test(options.piConfigDigest ?? "")) {
+    throw new Error("Pi launch requires an explicit spawn binding, cwd and fixed args");
+  }
+  const projection = buildPiProviderProjection(profile);
+  const delegated = options.runtimeEntry === "pi-prepared" ? buildPiPreparedArgs(options.piArgs) : buildPiProviderArgs(profile, options.piArgs);
+  const env = buildPiProviderChildEnvironment({
+    ambient: dependencies.ambient,
+    binding,
+    sessionDir: options.sessionDir});
+  const actual = { command: options.piBin, entry: options.piEntry, fixedArgv: [...options.piFixedArgs], cwd: options.piCwd, env };
+  await assertImplementationSpawnBinding(binding, actual);
+  const projectionDir = env.PI_CODING_AGENT_DIR;
+  await assertPiProjectionDirectory(projectionDir, binding.envCommitments.PI_CODING_AGENT_DIR);
+  await ensurePiSessionDirectory(options.sessionDir);
+  const modelsPath = path2.join(projectionDir, "models.json");
+  let created = false;
+  const cleanup = async () => {
+    if (created) {
+      await promises.unlink(modelsPath);
+      created = false;
+    }
+  };
+  try {
+    const file = await promises.open(modelsPath, "wx", 384);
+    created = true;
+    try {
+      await file.writeFile(`${JSON.stringify(projection)}
+`);
+    } finally {
+      await file.close();
+    }
+    const secret = await resolvePiProviderSecret(profile, dependencies.createSecretStore);
+    if (secret !== void 0) env[PI_PROJECTED_KEY_ENV] = secret;
+    const childArgs = [...actual.entry === void 0 ? [] : [actual.entry], ...actual.fixedArgv, `--config-digest=${options.piConfigDigest}`, ...delegated];
+    const spawnChild = dependencies.spawn ?? spawn;
+    await assertImplementationSpawnBinding(binding, actual);
+    const child = spawnChild(actual.command, childArgs, { env, cwd: actual.cwd, stdio: "inherit" });
+    return { child, cleanup };
+  } catch (error) {
+    await cleanup();
+    throw error;
+  }
+}
 async function ensurePiSessionDirectory(sessionDir) {
   const firstCreated = await promises.mkdir(sessionDir, { recursive: true, mode: 448 });
   if (firstCreated !== void 0) {
@@ -913,19 +1071,19 @@ function loadSqliteModule() {
     );
   }
 }
-function openSqliteDatabase(path4, options, faults) {
+function openSqliteDatabase(path3, options, faults) {
   const { DatabaseSync } = loadSqliteModule();
   const readOnly = options?.readOnly === true;
-  if (path4 !== ":memory:" && !readOnly) {
-    mkdirSync(dirname(path4), { mode: SECURE_DIR_MODE, recursive: true });
+  if (path3 !== ":memory:" && !readOnly) {
+    mkdirSync(dirname(path3), { mode: SECURE_DIR_MODE, recursive: true });
   }
-  const database = new DatabaseSync(path4, {
+  const database = new DatabaseSync(path3, {
     timeout: DEFAULT_BUSY_TIMEOUT_MS,
     ...options
   });
   try {
     faults?.onStep?.("after-open");
-    if (path4 !== ":memory:" && !readOnly) {
+    if (path3 !== ":memory:" && !readOnly) {
       database.exec("PRAGMA journal_mode = WAL");
       faults?.onStep?.("after-wal");
       database.exec("PRAGMA synchronous = FULL");
@@ -978,7 +1136,7 @@ CREATE TABLE IF NOT EXISTS provider_profile (
 function normalizeTableDdl(sql) {
   return sql.replace(/\bIF\s+NOT\s+EXISTS\b/giu, "").replace(/\s+/gu, " ").trim().replace(/;$/u, "").trim();
 }
-function assertProviderProfileSchemaIsCurrent(database, path4) {
+function assertProviderProfileSchemaIsCurrent(database, path3) {
   const row = database.prepare(
     "SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'provider_profile'"
   ).get();
@@ -987,7 +1145,7 @@ function assertProviderProfileSchemaIsCurrent(database, path4) {
   if (normalizeTableDdl(stored) === normalizeTableDdl(SCHEMA)) return;
   throw new ByokKeysError(
     "PROVIDER_STORE_SCHEMA_STALE",
-    `Provider profile store at ${path4} was created by a different @byok-sdk/keys schema; preserve this store and explicitly provision a separate current-schema store before continuing`
+    `Provider profile store at ${path3} was created by a different @byok-sdk/keys schema; preserve this store and explicitly provision a separate current-schema store before continuing`
   );
 }
 var ENABLED_INDEX = `
@@ -1437,7 +1595,7 @@ async function run(options) {
     path: options.profileDbPath,
     readOnly: true
   });
-  let projectionDir;
+  let cleanup;
   try {
     const profile = await profiles.get(options.profileRef);
     if (profile === void 0) {
@@ -1451,34 +1609,15 @@ async function run(options) {
     if (options.expectedBinding !== void 0) {
       assertExactProviderProfileBinding(profile, options.expectedBinding);
     }
-    const projection = buildPiProviderProjection(profile);
+    if (options.runtimeEntry === "pi-prepared") assertPiPreparedProviderProfile(profile);
+    buildPiProviderProjection(profile);
     if (options.validateOnly) return 0;
-    const childArgs = buildPiProviderArgs(profile, options.piArgs);
-    projectionDir = await promises.mkdtemp(path2.join(os.tmpdir(), "byok-pi-provider-"));
-    await promises.chmod(projectionDir, 448).catch(() => {
-    });
-    await ensurePiSessionDirectory(options.sessionDir);
-    const childEnv = buildPiProviderChildEnvironment({
+    const launched = await startPiProvider(profile, options, {
       ambient: process.env,
-      projectionDir,
-      sessionDir: options.sessionDir,
-      secret: void 0
-    });
-    const secret = await resolvePiProviderSecret(
-      profile,
-      () => createSecretStore(options.secretServicePrefix, options.macosKeychainPath)
-    );
-    if (secret !== void 0) childEnv[PI_PROJECTED_KEY_ENV] = secret;
-    await promises.writeFile(
-      path2.join(projectionDir, "models.json"),
-      `${JSON.stringify(projection)}
-`,
-      { mode: 384 }
-    );
-    const child = spawn(options.piBin, [...options.piEntry === void 0 ? [] : [options.piEntry], ...childArgs], {
-      env: childEnv,
-      stdio: "inherit"
+      createSecretStore: () => createSecretStore(options.secretServicePrefix, options.macosKeychainPath)
     });
+    cleanup = launched.cleanup;
+    const child = launched.child;
     const forward = (signal) => {
       if (!child.killed) child.kill(signal);
     };
@@ -1499,9 +1638,7 @@ async function run(options) {
     }
   } finally {
     await profiles.close();
-    if (projectionDir) {
-      await promises.rm(projectionDir, { recursive: true, force: true });
-    }
+    await cleanup?.();
   }
 }
 async function main() {