@vellumai/assistant 0.4.55 → 0.4.57

package/src/security/encrypted-store.ts

@@ -1,12 +1,12 @@
 /**
- * Encrypted-at-rest key storage — fallback for systems without OS keychain.
+ * Encrypted-at-rest key storage -- fallback for systems without OS keychain.
  *
- * Uses AES-256-GCM with a key derived from machine-specific entropy:
- *   - hostname, username, platform, arch, homedir
- *   - PBKDF2 with 100k iterations + a persisted random salt
+ * v2 stores use a cryptographically random 32-byte `store.key` file as the
+ * AES-256-GCM key directly (no key derivation). The key file lives alongside
+ * `keys.enc` in `~/.vellum/protected/`.
  *
- * Secrets are stored in `~/.vellum/keys.enc` as a JSON blob encrypted
- * with the derived key. Each entry has its own IV for authenticated encryption.
+ * v1 stores (legacy) derived the AES key from machine-specific entropy via
+ * PBKDF2. Existing v1 stores are automatically migrated to v2 on first access.
  *
  * Provides the same get/set/delete interface as `keychain.ts`.
  */
@@ -17,10 +17,17 @@ import {
   pbkdf2Sync,
   randomBytes,
 } from "node:crypto";
-import { chmodSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import {
+  chmodSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
 import { hostname, userInfo } from "node:os";
 import { dirname, join } from "node:path";
 
+import { getIsContainerized } from "../config/env-registry.js";
 import { ensureDir, pathExists } from "../util/fs.js";
 import { getLogger } from "../util/logger.js";
 import { getPlatformName, getRootDir } from "../util/platform.js";
@@ -35,18 +42,27 @@ const PBKDF2_ITERATIONS =
   // In tests, PBKDF2 key derivation dominates runtime (~1-2s per file).
   // 1 iteration is sufficient for correctness; 100k is for brute-force resistance.
   process.env.BUN_TEST === "1" ? 1 : 100_000;
-const SALT_LENGTH = 32; // bytes
 
-/** On-disk format for the encrypted store. */
-interface StoreFile {
-  /** Version for future format changes. */
+// ---------------------------------------------------------------------------
+// On-disk formats
+// ---------------------------------------------------------------------------
+
+/** v1 on-disk format (legacy): PBKDF2-derived key from machine entropy. */
+interface StoreFileV1 {
   version: 1;
   /** Hex-encoded salt for PBKDF2 key derivation. */
   salt: string;
-  /** Individual encrypted entries keyed by account name. */
   entries: Record<string, EncryptedEntry>;
 }
 
+/** v2 on-disk format: random store.key used directly as AES key. */
+interface StoreFileV2 {
+  version: 2;
+  entries: Record<string, EncryptedEntry>;
+}
+
+type StoreFile = StoreFileV1 | StoreFileV2;
+
 /** A single encrypted value. */
 interface EncryptedEntry {
   /** Hex-encoded IV. */
@@ -73,9 +89,74 @@ export function _setStorePath(path: string | null): void {
 }
 
 // ---------------------------------------------------------------------------
-// Machine entropy for key derivation
+// Store key file (v2)
 // ---------------------------------------------------------------------------
 
+const STORE_KEY_FILENAME = "store.key";
+const STORE_KEY_LENGTH = 32; // bytes
+
+let storeKeyPathOverride: string | null = null;
+
+/** @internal Test-only: override the store key file path. Pass `null` to reset. */
+export function _setStoreKeyPath(path: string | null): void {
+  storeKeyPathOverride = path;
+}
+
+function getStoreKeyPath(): string {
+  return (
+    storeKeyPathOverride ??
+    join(dirname(getStorePath()), STORE_KEY_FILENAME)
+  );
+}
+
+/**
+ * Read the store.key file. Returns the raw 32-byte key buffer, or null
+ * if the file is missing, wrong size, or unreadable.
+ */
+function readStoreKey(): Buffer | null {
+  const keyPath = getStoreKeyPath();
+  if (!pathExists(keyPath)) return null;
+  try {
+    const buf = readFileSync(keyPath);
+    if (buf.length !== STORE_KEY_LENGTH) return null;
+    return buf;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Generate a cryptographically random store key and write it atomically
+ * to `<dir>/store.key` with 0o600 permissions. Returns the key buffer.
+ */
+function generateAndWriteStoreKey(dir: string): Buffer {
+  ensureDir(dir);
+  const key = randomBytes(STORE_KEY_LENGTH);
+  const keyPath = join(dir, STORE_KEY_FILENAME);
+  const tmpPath = keyPath + `.tmp.${process.pid}`;
+  writeFileSync(tmpPath, key, { mode: 0o600 });
+  chmodSync(tmpPath, 0o600);
+  renameSync(tmpPath, keyPath);
+  return key;
+}
+
+/**
+ * Read the existing store key, or generate and write a new one if missing.
+ */
+function getOrReadStoreKey(dir: string): Buffer {
+  const existing = readStoreKey();
+  if (existing) return existing;
+  return generateAndWriteStoreKey(dir);
+}
+
+// ---------------------------------------------------------------------------
+// Machine entropy for key derivation (legacy v1 only)
+// ---------------------------------------------------------------------------
+
+/**
+ * @deprecated @internal Kept only for v1->v2 migration path.
+ * Derives entropy from publicly-knowable machine properties.
+ */
 function getMachineEntropy(): string {
   const parts: string[] = [];
   try {
@@ -98,11 +179,75 @@ function getMachineEntropy(): string {
   return parts.join(":");
 }
 
+/**
+ * @deprecated @internal Kept only for v1->v2 migration path.
+ * Derives an AES key from machine entropy via PBKDF2.
+ */
 function deriveKey(salt: Buffer): Buffer {
   const entropy = getMachineEntropy();
   return pbkdf2Sync(entropy, salt, PBKDF2_ITERATIONS, KEY_LENGTH, "sha512");
 }
 
+// ---------------------------------------------------------------------------
+// Key resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the AES key for a given store format.
+ * - v2: reads store.key file (returns null if missing)
+ * - v1: derives key from machine entropy via PBKDF2
+ */
+function getKeyForStore(store: StoreFile): Buffer | null {
+  if (store.version === 2) {
+    return readStoreKey();
+  }
+  return deriveKey(Buffer.from(store.salt, "hex"));
+}
+
+// ---------------------------------------------------------------------------
+// v1 -> v2 migration
+// ---------------------------------------------------------------------------
+
+/**
+ * Migrate a v1 store to v2 format:
+ * 1. Get or generate a random store.key
+ * 2. Decrypt each entry with the legacy PBKDF2-derived key
+ * 3. Re-encrypt each entry with the random store key
+ *
+ * Entries that fail to decrypt (corrupt/tampered) are logged and skipped.
+ * Returns null if a fatal error occurs (e.g. can't write store.key).
+ */
+function migrateV1ToV2(store: StoreFileV1): StoreFileV2 | null {
+  const protectedDir = dirname(getStorePath());
+
+  let storeKey: Buffer;
+  try {
+    storeKey = getOrReadStoreKey(protectedDir);
+  } catch (err) {
+    log.error({ err }, "Failed to create store.key during v1->v2 migration");
+    return null;
+  }
+
+  // Derive the legacy key for decryption
+  const legacyKey = deriveKey(Buffer.from(store.salt, "hex"));
+
+  const newEntries: Record<string, EncryptedEntry> = Object.create(null);
+
+  for (const [account, entry] of Object.entries(store.entries)) {
+    try {
+      const plaintext = decrypt(entry, legacyKey);
+      newEntries[account] = encrypt(plaintext, storeKey);
+    } catch (err) {
+      log.warn(
+        { err, account },
+        "Skipping corrupt entry during v1->v2 migration",
+      );
+    }
+  }
+
+  return { version: 2, entries: newEntries };
+}
+
 // ---------------------------------------------------------------------------
 // Store I/O
 // ---------------------------------------------------------------------------
@@ -123,25 +268,34 @@ function readStore(): StoreFile | null {
 
   try {
     const parsed = JSON.parse(raw);
-    if (
-      parsed.version !== 1 ||
-      typeof parsed.salt !== "string" ||
-      typeof parsed.entries !== "object"
-    ) {
+
+    if (typeof parsed.entries !== "object") {
       throw new Error("Encrypted store has invalid format");
     }
-    // Use null-prototype object for entries to prevent prototype pollution
-    const safeEntries: Record<string, EncryptedEntry> = Object.create(null);
-    Object.assign(safeEntries, parsed.entries);
-    parsed.entries = safeEntries;
-    return parsed as StoreFile;
+
+    // Accept v2 (no salt required) or v1 (salt required)
+    if (parsed.version === 2) {
+      const safeEntries: Record<string, EncryptedEntry> = Object.create(null);
+      Object.assign(safeEntries, parsed.entries);
+      parsed.entries = safeEntries;
+      return parsed as StoreFileV2;
+    }
+
+    if (parsed.version === 1 && typeof parsed.salt === "string") {
+      const safeEntries: Record<string, EncryptedEntry> = Object.create(null);
+      Object.assign(safeEntries, parsed.entries);
+      parsed.entries = safeEntries;
+      return parsed as StoreFileV1;
+    }
+
+    throw new Error("Encrypted store has invalid format");
   } catch (err) {
-    // Corrupted or invalid store file — back it up and start fresh so the
+    // Corrupted or invalid store file -- back it up and start fresh so the
     // daemon doesn't crash on every credential access.
     const backupPath = `${path}.corrupt.${Date.now()}`;
     log.error(
       { err, backupPath },
-      "Encrypted store is corrupt — backing up and resetting",
+      "Encrypted store is corrupt -- backing up and resetting",
     );
     try {
       renameSync(path, backupPath);
@@ -152,27 +306,83 @@ function readStore(): StoreFile | null {
   }
 }
 
+/**
+ * Well-known filename for the persisted machine entropy (legacy).
+ * Written alongside `keys.enc` so the CES sidecar could derive the same AES key.
+ * Superseded by `store.key` in v2 format.
+ */
+const ENTROPY_FILENAME = "entropy.key";
+
+/**
+ * Ensure the `store.key` file exists and is accessible on the shared mount
+ * (containerized/managed mode). Best-effort delete the old `entropy.key` file
+ * since v2 stores no longer need it.
+ */
+function persistStoreKey(protectedDir: string): void {
+  if (!getIsContainerized()) return;
+  try {
+    const storeKeyPath = join(protectedDir, STORE_KEY_FILENAME);
+    if (!pathExists(storeKeyPath)) {
+      // store.key should already exist from normal creation, but ensure it
+      getOrReadStoreKey(protectedDir);
+    }
+  } catch {
+    // Best-effort
+  }
+
+  // Best-effort cleanup of legacy entropy.key
+  try {
+    const entropyPath = join(protectedDir, ENTROPY_FILENAME);
+    if (pathExists(entropyPath)) {
+      unlinkSync(entropyPath);
+    }
+  } catch {
+    // Best-effort -- don't fail if cleanup of old file doesn't work.
+  }
+}
+
 function writeStore(store: StoreFile): void {
   const path = getStorePath();
-  ensureDir(dirname(path));
-  writeFileSync(path, JSON.stringify(store, null, 2), { mode: 0o600 });
-  // Enforce 0600 even if the file already existed with permissive bits
-  chmodSync(path, 0o600);
+  const protectedDir = dirname(path);
+  ensureDir(protectedDir);
+  // Atomic write: write to temp file then rename to avoid partial/corrupt writes.
+  // Use pid suffix to prevent cross-process collisions while ensuring same-process
+  // retries overwrite the stale temp file (avoids orphaned temp files on failure).
+  const tmpPath = path + `.tmp.${process.pid}`;
+  writeFileSync(tmpPath, JSON.stringify(store, null, 2), { mode: 0o600 });
+  chmodSync(tmpPath, 0o600);
+  renameSync(tmpPath, path);
+
+  // Keep store.key in sync so the managed CES sidecar can decrypt.
+  persistStoreKey(protectedDir);
 }
 
-function getOrCreateStore(): StoreFile {
+function getOrCreateStore(): StoreFileV2 {
   const existing = readStore();
-  if (existing) return existing;
 
-  const salt = randomBytes(SALT_LENGTH);
-  const entries: Record<string, EncryptedEntry> = Object.create(null);
-  const store: StoreFile = {
-    version: 1,
-    salt: salt.toString("hex"),
-    entries,
-  };
-  writeStore(store);
-  return store;
+  if (!existing) {
+    // Fresh store: generate store.key and create v2 format
+    const protectedDir = dirname(getStorePath());
+    getOrReadStoreKey(protectedDir);
+    const entries: Record<string, EncryptedEntry> = Object.create(null);
+    const store: StoreFileV2 = { version: 2, entries };
+    writeStore(store);
+    return store;
+  }
+
+  if (existing.version === 1) {
+    // Migrate v1 -> v2
+    const migrated = migrateV1ToV2(existing);
+    if (migrated) {
+      writeStore(migrated);
+      return migrated;
+    }
+    // Migration failed fatally -- fall through and use v1 as-is won't work
+    // because we can't get the key. Throw so callers handle the error.
+    throw new Error("Failed to migrate encrypted store from v1 to v2");
+  }
+
+  return existing;
 }
 
 // ---------------------------------------------------------------------------
@@ -209,7 +419,7 @@ function decrypt(entry: EncryptedEntry, key: Buffer): string {
 }
 
 // ---------------------------------------------------------------------------
-// Public API — matches keychain.ts interface
+// Public API -- matches keychain.ts interface
 // ---------------------------------------------------------------------------
 
 /**
@@ -221,11 +431,30 @@ export function getKey(account: string): string | undefined {
     const store = readStore();
     if (!store) return undefined;
 
+    // If v1, trigger migration
+    if (store.version === 1) {
+      const migrated = migrateV1ToV2(store);
+      if (migrated) {
+        writeStore(migrated);
+        const entry = migrated.entries[account];
+        if (!entry) return undefined;
+        const key = getKeyForStore(migrated);
+        if (!key) return undefined;
+        return decrypt(entry, key);
+      }
+      // Migration failed -- try reading with legacy key
+      const entry = store.entries[account];
+      if (!entry) return undefined;
+      const key = getKeyForStore(store);
+      if (!key) return undefined;
+      return decrypt(entry, key);
+    }
+
     const entry = store.entries[account];
     if (!entry) return undefined;
 
-    const salt = Buffer.from(store.salt, "hex");
-    const key = deriveKey(salt);
+    const key = getKeyForStore(store);
+    if (!key) return undefined;
     return decrypt(entry, key);
   } catch (err) {
     log.debug({ err, account }, "Failed to read from encrypted store");
@@ -240,8 +469,8 @@ export function getKey(account: string): string | undefined {
 export function setKey(account: string, value: string): boolean {
   try {
     const store = getOrCreateStore();
-    const salt = Buffer.from(store.salt, "hex");
-    const key = deriveKey(salt);
+    const key = getKeyForStore(store);
+    if (!key) return false;
     store.entries[account] = encrypt(value, key);
     writeStore(store);
     return true;
@@ -251,7 +480,7 @@ export function setKey(account: string, value: string): boolean {
   }
 }
 
-/** Result of a delete operation — distinguishes success, not-found, and error. */
+/** Result of a delete operation -- distinguishes success, not-found, and error. */
 export type DeleteKeyResult = "deleted" | "not-found" | "error";
 
 /**
@@ -261,8 +490,23 @@ export type DeleteKeyResult = "deleted" | "not-found" | "error";
  */
 export function deleteKey(account: string): DeleteKeyResult {
   try {
-    const store = readStore();
-    if (!store || !Object.prototype.hasOwnProperty.call(store.entries, account))
+    const existing = readStore();
+    if (!existing) return "not-found";
+
+    // Ensure v1→v2 migration happens when a store exists
+    let store: StoreFileV2;
+    if (existing.version === 1) {
+      const migrated = migrateV1ToV2(existing);
+      if (!migrated) {
+        throw new Error("Failed to migrate encrypted store from v1 to v2");
+      }
+      writeStore(migrated);
+      store = migrated;
+    } else {
+      store = existing;
+    }
+
+    if (!Object.prototype.hasOwnProperty.call(store.entries, account))
       return "not-found";
 
     delete store.entries[account];

package/src/security/keychain-broker-client.ts

@@ -25,6 +25,9 @@ const log = getLogger("keychain-broker-client");
 
 const REQUEST_TIMEOUT_MS = 5_000;
 
+/** Cooldown periods (ms) after consecutive connection failures: 30s, 60s, 2min, 5min, then cap at 5min. */
+const RECONNECT_COOLDOWN_MS = [30_000, 60_000, 120_000, 300_000];
+
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -89,10 +92,12 @@ export function createBrokerClient(): KeychainBrokerClient {
   let socket: Socket | null = null;
   /** Promise that resolves when the in-flight connect() completes. */
   let connectPromise: Promise<Socket> | null = null;
-  let permanentlyUnavailable = false;
+  /** Timestamp when the broker became unavailable, or null if available. */
+  let unavailableSince: number | null = null;
+  /** Number of consecutive connection failures (drives cooldown escalation). */
+  let consecutiveFailures = 0;
   /** Cached token string, or undefined if not yet successfully read. */
   let cachedToken: string | undefined;
-  let hasTriedReconnect = false;
 
   /** Buffer for incoming data — responses are newline-delimited JSON. */
   let inBuffer = "";
@@ -188,7 +193,8 @@ export function createBrokerClient(): KeychainBrokerClient {
 
       sock.on("connect", () => {
         socket = sock;
-        hasTriedReconnect = false;
+        consecutiveFailures = 0;
+        unavailableSince = null;
         resolve(sock);
       });
 
@@ -206,8 +212,26 @@ export function createBrokerClient(): KeychainBrokerClient {
     });
   }
 
+  /** Compute the cooldown duration for the current failure count. The first
+   *  two failures (initial + immediate retry) map to index 0 (30s). */
+  function getCooldownMs(): number {
+    const idx = Math.min(
+      Math.max(consecutiveFailures - 2, 0),
+      RECONNECT_COOLDOWN_MS.length - 1,
+    );
+    return RECONNECT_COOLDOWN_MS[idx];
+  }
+
   async function ensureConnected(): Promise<Socket | null> {
-    if (permanentlyUnavailable) return null;
+    // If in cooldown, check whether the cooldown period has elapsed.
+    if (unavailableSince != null) {
+      if (Date.now() - unavailableSince < getCooldownMs()) {
+        return null;
+      }
+      // Cooldown elapsed — clear and attempt reconnection below.
+      unavailableSince = null;
+    }
+
     if (socket && !socket.destroyed) return socket;
 
     // If a connect() is already in flight, wait for it instead of returning
@@ -225,24 +249,31 @@ export function createBrokerClient(): KeychainBrokerClient {
       const sock = await connectPromise;
       return sock;
     } catch {
-      // First connection failed — try once more
-      if (!hasTriedReconnect) {
-        hasTriedReconnect = true;
+      consecutiveFailures++;
+
+      // First failure triggers one immediate retry (preserves the original
+      // "try once more" behavior).
+      if (consecutiveFailures === 1) {
         connectPromise = connect();
         try {
           return await connectPromise;
         } catch {
-          // Reconnect also failed — mark unavailable
+          consecutiveFailures++;
+          unavailableSince = Date.now();
           log.warn(
-            "Keychain broker reconnect failed, marking unavailable for this process",
+            `Keychain broker reconnect failed, will retry in ${getCooldownMs() / 1000}s`,
           );
-          permanentlyUnavailable = true;
           return null;
         } finally {
           connectPromise = null;
         }
       }
-      permanentlyUnavailable = true;
+
+      // Subsequent failures — enter cooldown.
+      unavailableSince = Date.now();
+      log.warn(
+        `Keychain broker connection failed (attempt ${consecutiveFailures}), will retry in ${getCooldownMs() / 1000}s`,
+      );
       return null;
     } finally {
       connectPromise = null;
@@ -334,7 +365,9 @@ export function createBrokerClient(): KeychainBrokerClient {
 
   return {
     isAvailable(): boolean {
-      if (permanentlyUnavailable) return false;
+      if (unavailableSince != null) {
+        if (Date.now() - unavailableSince < getCooldownMs()) return false;
+      }
       if (!pathExists(getSocketPath())) return false;
       return pathExists(getTokenPath());
     },

package/src/security/secure-keys.ts

@@ -11,6 +11,11 @@
  * Deletes clean up both stores regardless of mode.
  */
 
+import type {
+  SecureKeyBackend,
+  SecureKeyDeleteResult,
+} from "@vellumai/credential-storage";
+
 import { getLogger } from "../util/logger.js";
 import type { CredentialBackend, DeleteResult } from "./credential-backend.js";
 import {
@@ -20,6 +25,13 @@ import {
 
 export type { DeleteResult } from "./credential-backend.js";
 
+/**
+ * Re-export shared-package secure-key abstractions so downstream consumers
+ * can import from this module without a direct @vellumai/credential-storage
+ * dependency.
+ */
+export type { SecureKeyBackend, SecureKeyDeleteResult };
+
 const log = getLogger("secure-keys");
 
 let _keychain: CredentialBackend | undefined;
@@ -147,6 +159,40 @@ export async function deleteSecureKeyAsync(
   return "not-found";
 }
 
+// ---------------------------------------------------------------------------
+// Provider API key lookup — secure store + env var fallback
+// ---------------------------------------------------------------------------
+
+/**
+ * Env var names keyed by provider. The convention is `<PROVIDER>_API_KEY`.
+ * Ollama is intentionally omitted — it doesn't require an API key.
+ */
+const PROVIDER_ENV_VARS: Record<string, string> = {
+  anthropic: "ANTHROPIC_API_KEY",
+  openai: "OPENAI_API_KEY",
+  gemini: "GEMINI_API_KEY",
+  fireworks: "FIREWORKS_API_KEY",
+  openrouter: "OPENROUTER_API_KEY",
+  brave: "BRAVE_API_KEY",
+  perplexity: "PERPLEXITY_API_KEY",
+};
+
+/**
+ * Retrieve a provider API key, checking secure storage first and falling
+ * back to the corresponding `<PROVIDER>_API_KEY` environment variable.
+ *
+ * Use this instead of raw `getSecureKeyAsync` when looking up provider
+ * API keys so that env-var-only setups continue to work.
+ */
+export async function getProviderKeyAsync(
+  provider: string,
+): Promise<string | undefined> {
+  const stored = await getSecureKeyAsync(provider);
+  if (stored) return stored;
+  const envVar = PROVIDER_ENV_VARS[provider];
+  return envVar ? process.env[envVar] : undefined;
+}
+
 // ---------------------------------------------------------------------------
 // Test helpers
 // ---------------------------------------------------------------------------