@vellumai/assistant 0.3.0

package/src/security/encrypted-store.ts

@@ -0,0 +1,238 @@
+/**
+ * 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
+ *
+ * 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.
+ *
+ * Provides the same get/set/delete interface as `keychain.ts`.
+ */
+
+import {
+  randomBytes,
+  pbkdf2Sync,
+  createCipheriv,
+  createDecipheriv,
+} from 'node:crypto';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { hostname, userInfo } from 'node:os';
+import { getRootDir, getPlatformName } from '../util/platform.js';
+import { getLogger } from '../util/logger.js';
+
+const log = getLogger('encrypted-store');
+
+const ALGORITHM = 'aes-256-gcm';
+const KEY_LENGTH = 32; // bytes (256 bits)
+const IV_LENGTH = 16; // bytes (128 bits)
+const AUTH_TAG_LENGTH = 16; // bytes
+const PBKDF2_ITERATIONS = 100_000;
+const SALT_LENGTH = 32; // bytes
+
+/** On-disk format for the encrypted store. */
+interface StoreFile {
+  /** Version for future format changes. */
+  version: 1;
+  /** Hex-encoded salt for PBKDF2 key derivation. */
+  salt: string;
+  /** Individual encrypted entries keyed by account name. */
+  entries: Record<string, EncryptedEntry>;
+}
+
+/** A single encrypted value. */
+interface EncryptedEntry {
+  /** Hex-encoded IV. */
+  iv: string;
+  /** Hex-encoded auth tag. */
+  tag: string;
+  /** Hex-encoded ciphertext. */
+  data: string;
+}
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+let storePathOverride: string | null = null;
+
+function getStorePath(): string {
+  return storePathOverride ?? join(getRootDir(), 'protected', 'keys.enc');
+}
+
+/** @internal Test-only: override the store file path. Pass `null` to reset. */
+export function _setStorePath(path: string | null): void {
+  storePathOverride = path;
+}
+
+// ---------------------------------------------------------------------------
+// Machine entropy for key derivation
+// ---------------------------------------------------------------------------
+
+function getMachineEntropy(): string {
+  const parts: string[] = [];
+  try { parts.push(hostname()); } catch { parts.push('unknown-host'); }
+  try { parts.push(userInfo().username); } catch { parts.push('unknown-user'); }
+  parts.push(getPlatformName());
+  parts.push(process.arch);
+  try { parts.push(userInfo().homedir); } catch { parts.push('/tmp'); }
+  return parts.join(':');
+}
+
+function deriveKey(salt: Buffer): Buffer {
+  const entropy = getMachineEntropy();
+  return pbkdf2Sync(entropy, salt, PBKDF2_ITERATIONS, KEY_LENGTH, 'sha512');
+}
+
+// ---------------------------------------------------------------------------
+// Store I/O
+// ---------------------------------------------------------------------------
+
+/**
+ * Read result: distinguishes "file missing" from "file corrupt/unreadable".
+ * - `null`: file does not exist (safe to create)
+ * - `StoreFile`: successfully parsed
+ * - throws: file exists but cannot be parsed (corrupt/invalid)
+ */
+function readStore(): StoreFile | null {
+  const path = getStorePath();
+  if (!existsSync(path)) return null;
+
+  const raw = readFileSync(path, 'utf-8');
+  const parsed = JSON.parse(raw);
+  if (parsed.version !== 1 || typeof parsed.salt !== 'string' || 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;
+}
+
+function writeStore(store: StoreFile): void {
+  const path = getStorePath();
+  const dir = dirname(path);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(path, JSON.stringify(store, null, 2), { mode: 0o600 });
+  // Enforce 0600 even if the file already existed with permissive bits
+  chmodSync(path, 0o600);
+}
+
+function getOrCreateStore(): StoreFile {
+  const path = getStorePath();
+  if (existsSync(path)) {
+    // File exists — must be parseable, otherwise fail to prevent data loss
+    return readStore()!;
+  }
+  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;
+}
+
+// ---------------------------------------------------------------------------
+// Encrypt / Decrypt
+// ---------------------------------------------------------------------------
+
+function encrypt(plaintext: string, key: Buffer): EncryptedEntry {
+  const iv = randomBytes(IV_LENGTH);
+  const cipher = createCipheriv(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
+  const encrypted = Buffer.concat([cipher.update(plaintext, 'utf-8'), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return {
+    iv: iv.toString('hex'),
+    tag: tag.toString('hex'),
+    data: encrypted.toString('hex'),
+  };
+}
+
+function decrypt(entry: EncryptedEntry, key: Buffer): string {
+  const iv = Buffer.from(entry.iv, 'hex');
+  const tag = Buffer.from(entry.tag, 'hex');
+  const data = Buffer.from(entry.data, 'hex');
+  const decipher = createDecipheriv(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
+  decipher.setAuthTag(tag);
+  const decrypted = Buffer.concat([decipher.update(data), decipher.final()]);
+  return decrypted.toString('utf-8');
+}
+
+// ---------------------------------------------------------------------------
+// Public API — matches keychain.ts interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Retrieve a secret from the encrypted store.
+ * Returns `undefined` if the key doesn't exist or decryption fails.
+ */
+export function getKey(account: string): string | undefined {
+  try {
+    const store = readStore();
+    if (!store) return undefined;
+
+    const entry = store.entries[account];
+    if (!entry) return undefined;
+
+    const salt = Buffer.from(store.salt, 'hex');
+    const key = deriveKey(salt);
+    return decrypt(entry, key);
+  } catch (err) {
+    log.debug({ err, account }, 'Failed to read from encrypted store');
+    return undefined;
+  }
+}
+
+/**
+ * Store a secret in the encrypted store.
+ * Returns true on success, false on failure.
+ */
+export function setKey(account: string, value: string): boolean {
+  try {
+    const store = getOrCreateStore();
+    const salt = Buffer.from(store.salt, 'hex');
+    const key = deriveKey(salt);
+    store.entries[account] = encrypt(value, key);
+    writeStore(store);
+    return true;
+  } catch (err) {
+    log.warn({ err, account }, 'Failed to write to encrypted store');
+    return false;
+  }
+}
+
+/**
+ * Delete a secret from the encrypted store.
+ * Returns true on success, false if not found or on failure.
+ */
+export function deleteKey(account: string): boolean {
+  try {
+    const store = readStore();
+    if (!store || !Object.prototype.hasOwnProperty.call(store.entries, account)) return false;
+
+    delete store.entries[account];
+    writeStore(store);
+    return true;
+  } catch (err) {
+    log.debug({ err, account }, 'Failed to delete from encrypted store');
+    return false;
+  }
+}
+
+/**
+ * List all account names in the encrypted store.
+ * Throws if the store file exists but cannot be read/parsed.
+ */
+export function listKeys(): string[] {
+  const store = readStore();
+  if (!store) return [];
+  return Object.keys(store.entries);
+}

package/src/security/keychain.ts

@@ -0,0 +1,252 @@
+/**
+ * OS keychain abstraction — platform-agnostic secure credential storage.
+ *
+ * - macOS: uses the `security` CLI to interact with Keychain
+ * - Linux: uses `secret-tool` (libsecret) for GNOME/KDE keyrings
+ *
+ * All operations are synchronous to match the config loader's sync API.
+ * Callers should check `isKeychainAvailable()` before use and fall back
+ * to encrypted-at-rest storage when the keychain is not accessible.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { isMacOS, isLinux } from '../util/platform.js';
+import { getLogger } from '../util/logger.js';
+
+const log = getLogger('keychain');
+
+const SERVICE_NAME = 'vellum-assistant';
+
+// ---------------------------------------------------------------------------
+// Injectable deps — avoids process-global mock.module for testing
+// ---------------------------------------------------------------------------
+
+const deps = {
+  execFileSync: execFileSync as typeof execFileSync,
+  isMacOS,
+  isLinux,
+};
+
+/** @internal test-only — override deps to avoid mock.module conflicts */
+export function _overrideDeps(overrides: Partial<typeof deps>): void {
+  Object.assign(deps, overrides);
+}
+
+/** @internal test-only — restore original deps */
+export function _resetDeps(): void {
+  deps.execFileSync = execFileSync;
+  deps.isMacOS = isMacOS;
+  deps.isLinux = isLinux;
+}
+
+/** Check if the OS keychain is available on this system. */
+export function isKeychainAvailable(): boolean {
+  try {
+    if (deps.isMacOS()) {
+      // Verify `security` CLI exists and can list keychains
+      deps.execFileSync('security', ['list-keychains'], {
+        stdio: ['ignore', 'ignore', 'ignore'],
+        timeout: 5000,
+      });
+      return true;
+    }
+
+    if (deps.isLinux()) {
+      // Verify `secret-tool` exists
+      deps.execFileSync('which', ['secret-tool'], {
+        stdio: ['ignore', 'ignore', 'ignore'],
+        timeout: 5000,
+      });
+      return true;
+    }
+
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Retrieve a secret from the OS keychain.
+ * Returns `null` if the key doesn't exist.
+ * Throws on runtime errors (keychain unavailable, locked, etc.).
+ */
+export function getKey(account: string): string | null {
+  if (deps.isMacOS()) {
+    return macosGetKey(account);
+  }
+  if (deps.isLinux()) {
+    return linuxGetKey(account);
+  }
+  return null;
+}
+
+/**
+ * Store a secret in the OS keychain.
+ * Returns true on success, false on failure.
+ */
+export function setKey(account: string, value: string): boolean {
+  try {
+    if (deps.isMacOS()) {
+      return macosSetKey(account, value);
+    }
+    if (deps.isLinux()) {
+      return linuxSetKey(account, value);
+    }
+    return false;
+  } catch (err) {
+    log.warn({ err, account }, 'Failed to write to keychain');
+    return false;
+  }
+}
+
+/**
+ * Delete a secret from the OS keychain.
+ * Returns true on success, false if not found or on failure.
+ */
+export function deleteKey(account: string): boolean {
+  try {
+    if (deps.isMacOS()) {
+      return macosDeleteKey(account);
+    }
+    if (deps.isLinux()) {
+      return linuxDeleteKey(account);
+    }
+    return false;
+  } catch (err) {
+    log.debug({ err, account }, 'Failed to delete from keychain');
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// macOS Keychain via `security` CLI
+// ---------------------------------------------------------------------------
+
+function macosGetKey(account: string): string | null {
+  try {
+    const result = deps.execFileSync('security', [
+      'find-generic-password',
+      '-s', SERVICE_NAME,
+      '-a', account,
+      '-w', // output password only
+    ], {
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 5000,
+      encoding: 'utf-8',
+    });
+    // Strip only the trailing newline added by the security CLI
+    return result.replace(/\n$/, '') || null;
+  } catch (err: unknown) {
+    // Exit code 44 = item not found — return null.
+    // All other errors are runtime failures — re-throw.
+    if (err && typeof err === 'object' && 'status' in err && (err as { status: number }).status === 44) {
+      return null;
+    }
+    throw err;
+  }
+}
+
+function macosSetKey(account: string, value: string): boolean {
+  // -U flag handles update-if-exists, no need to delete first.
+  // macOS `security` requires the password as the argument to -w;
+  // it does NOT read from stdin. Using `-w` without a value causes
+  // the next flag to be consumed as the password.
+  try {
+    deps.execFileSync('security', [
+      'add-generic-password',
+      '-s', SERVICE_NAME,
+      '-a', account,
+      '-w', value,
+      '-U', // update if exists
+    ], {
+      stdio: ['ignore', 'ignore', 'ignore'],
+      timeout: 5000,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function macosDeleteKey(account: string): boolean {
+  try {
+    deps.execFileSync('security', [
+      'delete-generic-password',
+      '-s', SERVICE_NAME,
+      '-a', account,
+    ], {
+      stdio: ['ignore', 'ignore', 'ignore'],
+      timeout: 5000,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Linux via `secret-tool` (libsecret)
+// ---------------------------------------------------------------------------
+
+function linuxGetKey(account: string): string | null {
+  try {
+    const result = deps.execFileSync('secret-tool', [
+      'lookup',
+      'service', SERVICE_NAME,
+      'account', account,
+    ], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 5000,
+      encoding: 'utf-8',
+    });
+    // Strip only the trailing newline added by secret-tool
+    return result.replace(/\n$/, '') || null;
+  } catch (err: unknown) {
+    // secret-tool exits with code 1 for BOTH "not found" and runtime errors
+    // (D-Bus failures, keyring locked, etc.). Distinguish by checking stderr:
+    // empty stderr → key not found; non-empty stderr → runtime error.
+    if (err && typeof err === 'object' && 'status' in err && (err as { status: number }).status === 1) {
+      const stderr = String((err as { stderr?: unknown }).stderr ?? '').trim();
+      if (stderr.length > 0) {
+        throw err;
+      }
+      return null;
+    }
+    throw err;
+  }
+}
+
+function linuxSetKey(account: string, value: string): boolean {
+  try {
+    deps.execFileSync('secret-tool', [
+      'store',
+      '--label', `${SERVICE_NAME}: ${account}`,
+      'service', SERVICE_NAME,
+      'account', account,
+    ], {
+      input: value,
+      stdio: ['pipe', 'ignore', 'ignore'],
+      timeout: 5000,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function linuxDeleteKey(account: string): boolean {
+  try {
+    deps.execFileSync('secret-tool', [
+      'clear',
+      'service', SERVICE_NAME,
+      'account', account,
+    ], {
+      stdio: ['ignore', 'ignore', 'ignore'],
+      timeout: 5000,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/security/oauth-callback-registry.ts

@@ -0,0 +1,66 @@
+/**
+ * In-memory registry for pending OAuth callback states.
+ * Used by the gateway-routed OAuth flow to resolve authorization codes
+ * back to the runtime code that initiated the OAuth handshake.
+ */
+
+interface PendingCallback {
+  resolve: (code: string) => void;
+  reject: (error: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+const pendingCallbacks = new Map<string, PendingCallback>();
+const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+export function registerPendingCallback(
+  state: string,
+  resolve: (code: string) => void,
+  reject: (error: Error) => void,
+  ttlMs = DEFAULT_TTL_MS,
+): void {
+  // Clear any existing entry for this state to prevent timer leaks and
+  // cross-callback timeouts when the same state is registered twice.
+  const existing = pendingCallbacks.get(state);
+  if (existing) {
+    clearTimeout(existing.timer);
+    existing.reject(new Error('OAuth callback superseded by new registration'));
+    pendingCallbacks.delete(state);
+  }
+
+  const timer = setTimeout(() => {
+    const entry = pendingCallbacks.get(state);
+    if (entry) {
+      pendingCallbacks.delete(state);
+      entry.reject(new Error('OAuth callback timed out'));
+    }
+  }, ttlMs);
+
+  pendingCallbacks.set(state, { resolve, reject, timer });
+}
+
+export function consumeCallback(state: string, code: string): boolean {
+  const entry = pendingCallbacks.get(state);
+  if (!entry) return false;
+  clearTimeout(entry.timer);
+  pendingCallbacks.delete(state);
+  entry.resolve(code);
+  return true;
+}
+
+export function consumeCallbackError(state: string, error: string): boolean {
+  const entry = pendingCallbacks.get(state);
+  if (!entry) return false;
+  clearTimeout(entry.timer);
+  pendingCallbacks.delete(state);
+  entry.reject(new Error(error));
+  return true;
+}
+
+export function clearAllCallbacks(): void {
+  for (const entry of pendingCallbacks.values()) {
+    clearTimeout(entry.timer);
+    entry.reject(new Error('OAuth callback registry cleared'));
+  }
+  pendingCallbacks.clear();
+}