@vellumai/credential-executor 0.4.55 → 0.4.57

package/src/materializers/local-secure-key-backend.ts

@@ -0,0 +1,309 @@
+/**
+ * CES-native SecureKeyBackend for **local mode only**.
+ *
+ * In local mode, CES runs as a child process of the assistant on the same
+ * machine as the same user and can read/write the assistant's encrypted key
+ * store file at `<vellumRoot>/protected/keys.enc`.
+ *
+ * This implementation replicates the encryption/decryption logic from the
+ * assistant's `encrypted-store.ts` without importing assistant-internal
+ * modules. Writes are needed for OAuth token refresh — when CES refreshes
+ * an expired access token, the new token must be persisted back to the
+ * encrypted store so subsequent reads (by both CES and the assistant)
+ * see the updated value.
+ *
+ * Two store formats are supported:
+ *
+ * - **v2 (primary):** AES-256-GCM with a random 32-byte key stored at
+ *   `<vellumRoot>/protected/store.key`. The key is machine-independent —
+ *   any process that can read the key file can decrypt the store.
+ *
+ * - **v1 (legacy):** AES-256-GCM with a key derived from machine-specific
+ *   entropy via PBKDF2. The derivation includes `userInfo().username` and
+ *   `userInfo().homedir`, so the key is only correct when CES runs as the
+ *   same OS user as the assistant.
+ *
+ * **Managed-mode restriction (v1 only):** For legacy v1 stores, the
+ * different container user identity produces a different PBKDF2-derived
+ * key, causing silent decryption failures. v2 stores use a
+ * UID-independent `store.key` file that can be shared via volume mount,
+ * removing this technical barrier. Managed deployments currently use
+ * `platform_oauth` handles exclusively as a policy choice (simpler
+ * lifecycle, centralized token management).
+ */
+
+import {
+  createCipheriv,
+  createDecipheriv,
+  pbkdf2Sync,
+  randomBytes,
+} from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { hostname, userInfo } from "node:os";
+import { dirname, join } from "node:path";
+
+import type {
+  SecureKeyBackend,
+  SecureKeyDeleteResult,
+} from "@vellumai/credential-storage";
+
+// ---------------------------------------------------------------------------
+// Constants (must match assistant/src/security/encrypted-store.ts)
+// ---------------------------------------------------------------------------
+
+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 =
+  process.env.BUN_TEST === "1" ? 1 : 100_000;
+
+// ---------------------------------------------------------------------------
+// On-disk format (must match assistant/src/security/encrypted-store.ts)
+// ---------------------------------------------------------------------------
+
+interface EncryptedEntry {
+  iv: string;
+  tag: string;
+  data: string;
+}
+
+interface StoreFileV1 {
+  version: 1;
+  salt: string;
+  entries: Record<string, EncryptedEntry>;
+}
+
+interface StoreFileV2 {
+  version: 2;
+  entries: Record<string, EncryptedEntry>;
+}
+
+type StoreFile = StoreFileV1 | StoreFileV2;
+
+// ---------------------------------------------------------------------------
+// Store key file (v2 format)
+// ---------------------------------------------------------------------------
+
+const STORE_KEY_FILENAME = "store.key";
+
+/**
+ * Read the v2 store key file from `<vellumRoot>/protected/store.key`.
+ * Returns the raw 32-byte key buffer, or null if the file is missing,
+ * wrong size, or unreadable.
+ */
+function readStoreKey(vellumRoot: string): Buffer | null {
+  try {
+    const keyPath = join(vellumRoot, "protected", STORE_KEY_FILENAME);
+    if (!existsSync(keyPath)) return null;
+    const buf = readFileSync(keyPath);
+    if (buf.length !== KEY_LENGTH) return null;
+    return buf;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Machine entropy (must match assistant/src/security/encrypted-store.ts)
+// ---------------------------------------------------------------------------
+
+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(process.platform);
+  parts.push(process.arch);
+  try {
+    parts.push(userInfo().homedir);
+  } catch {
+    parts.push("/tmp");
+  }
+  return parts.join(":");
+}
+
+function deriveKey(salt: Buffer, entropyOverride?: string): Buffer {
+  const entropy = entropyOverride ?? getMachineEntropy();
+  return pbkdf2Sync(entropy, salt, PBKDF2_ITERATIONS, KEY_LENGTH, "sha512");
+}
+
+// ---------------------------------------------------------------------------
+// Decrypt
+// ---------------------------------------------------------------------------
+
+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");
+}
+
+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"),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Store writer
+// ---------------------------------------------------------------------------
+
+function writeStore(store: StoreFile, storePath: string): void {
+  const protectedDir = dirname(storePath);
+  mkdirSync(protectedDir, { recursive: true });
+  // Atomic write: write to temp file then rename to avoid partial/corrupt writes.
+  const tmpPath = storePath + `.tmp.${process.pid}`;
+  writeFileSync(tmpPath, JSON.stringify(store, null, 2), { mode: 0o600 });
+  chmodSync(tmpPath, 0o600);
+  renameSync(tmpPath, storePath);
+}
+
+// ---------------------------------------------------------------------------
+// Store reader
+// ---------------------------------------------------------------------------
+
+function readStore(storePath: string): StoreFile | null {
+  try {
+    const raw = readFileSync(storePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.entries !== "object") return null;
+
+    if (parsed.version === 1 && typeof parsed.salt === "string") {
+      return parsed as StoreFileV1;
+    }
+    if (parsed.version === 2) {
+      return parsed as StoreFileV2;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Backend implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a SecureKeyBackend backed by the assistant's encrypted key store.
+ *
+ * Supports `get` and `set` operations. `set` is needed for persisting
+ * refreshed OAuth tokens. `delete` remains unsupported (returns "error")
+ * because CES never needs to remove keys.
+ *
+ * @param vellumRoot - The Vellum root directory (e.g. `~/.vellum`).
+ * @param options.entropyOverride - If provided, used instead of local
+ *   machine entropy for key derivation. In managed mode the CES sidecar
+ *   runs in a different container with a different hostname/user, so it
+ *   must use the assistant's entropy (read from the shared data mount)
+ *   to derive the same AES key.
+ * @param options.entropyGetter - If provided, called on each `get()`/`set()`
+ *   to lazily resolve entropy. This handles the startup race where the
+ *   entropy file may not exist at construction time but appears later.
+ *   Takes precedence over `entropyOverride`.
+ */
+export function createLocalSecureKeyBackend(
+  vellumRoot: string,
+  options?: { entropyOverride?: string; entropyGetter?: () => string | undefined },
+): SecureKeyBackend {
+  const storePath = join(vellumRoot, "protected", "keys.enc");
+  const staticEntropy = options?.entropyOverride;
+  const entropyGetter = options?.entropyGetter;
+
+  return {
+    async get(key: string): Promise<string | undefined> {
+      try {
+        const store = readStore(storePath);
+        if (!store) return undefined;
+
+        const entry = store.entries[key];
+        if (!entry) return undefined;
+
+        let aesKey: Buffer;
+        if (store.version === 2) {
+          const storeKey = readStoreKey(vellumRoot);
+          if (!storeKey) return undefined;
+          aesKey = storeKey;
+        } else {
+          // v1: derive key from machine entropy via PBKDF2
+          const entropy = entropyGetter?.() ?? staticEntropy;
+          const salt = Buffer.from(store.salt, "hex");
+          aesKey = deriveKey(salt, entropy);
+        }
+
+        return decrypt(entry, aesKey);
+      } catch {
+        return undefined;
+      }
+    },
+
+    // NOTE: read-modify-write without file locking. The atomic rename
+    // (writeStore) prevents corruption from partial writes, but concurrent
+    // set() calls can lose updates. The window is small in practice because
+    // CES serialises refresh via RefreshDeduplicator. File locking is a
+    // future improvement.
+    async set(key: string, value: string): Promise<boolean> {
+      try {
+        const store = readStore(storePath);
+        if (!store) return false;
+
+        let aesKey: Buffer;
+        if (store.version === 2) {
+          const storeKey = readStoreKey(vellumRoot);
+          if (!storeKey) return false;
+          aesKey = storeKey;
+        } else {
+          // v1: derive key from machine entropy via PBKDF2
+          const entropy = entropyGetter?.() ?? staticEntropy;
+          const salt = Buffer.from(store.salt, "hex");
+          aesKey = deriveKey(salt, entropy);
+        }
+
+        store.entries[key] = encrypt(value, aesKey);
+        writeStore(store, storePath);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+
+    // CES never deletes keys — only reads and writes (for token refresh).
+    async delete(_key: string): Promise<SecureKeyDeleteResult> {
+      return "error";
+    },
+
+    async list(): Promise<string[]> {
+      try {
+        const store = readStore(storePath);
+        if (!store) return [];
+        return Object.keys(store.entries);
+      } catch {
+        return [];
+      }
+    },
+  };
+}

package/src/materializers/local-token-refresh.ts

@@ -0,0 +1,263 @@
+/**
+ * OAuth token refresh implementation for CES local mode.
+ *
+ * Performs the actual OAuth2 token refresh by:
+ * 1. Looking up the connection's provider and app configuration from the
+ *    assistant's SQLite database (read-only).
+ * 2. Retrieving the client secret from the secure-key backend.
+ * 3. Calling the provider's token endpoint with the refresh token.
+ * 4. Returning a `TokenRefreshResult` for the `LocalMaterialiser` to persist.
+ *
+ * This module does NOT import any assistant-internal modules. It queries
+ * the SQLite database directly (like `local-oauth-lookup.ts`) and performs
+ * the HTTP refresh call inline (replicating the logic from the assistant's
+ * `security/oauth2.ts:refreshOAuth2Token`).
+ */
+
+import Database from "bun:sqlite";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+  computeExpiresAt,
+  type SecureKeyBackend,
+  type TokenRefreshResult,
+} from "@vellumai/credential-storage";
+
+import type { TokenRefreshFn } from "./local.js";
+
+// ---------------------------------------------------------------------------
+// SQLite row shapes (match assistant schema without importing Drizzle)
+// ---------------------------------------------------------------------------
+
+interface OAuthConnectionRow {
+  id: string;
+  oauth_app_id: string;
+  provider_key: string;
+}
+
+interface OAuthAppRow {
+  id: string;
+  provider_key: string;
+  client_id: string;
+  client_secret_credential_path: string;
+}
+
+interface OAuthProviderRow {
+  provider_key: string;
+  token_url: string;
+  token_endpoint_auth_method: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Token endpoint auth method (matches assistant/src/security/oauth2.ts)
+// ---------------------------------------------------------------------------
+
+type TokenEndpointAuthMethod = "client_secret_basic" | "client_secret_post";
+
+// ---------------------------------------------------------------------------
+// Refresh config resolution
+// ---------------------------------------------------------------------------
+
+interface RefreshConfig {
+  tokenUrl: string;
+  clientId: string;
+  clientSecret?: string;
+  authMethod: TokenEndpointAuthMethod;
+}
+
+/**
+ * Resolve the OAuth refresh configuration for a connection by querying
+ * the assistant's SQLite database (read-only) and the secure-key backend.
+ */
+async function resolveRefreshConfig(
+  dbPath: string,
+  connectionId: string,
+  secureKeyBackend: SecureKeyBackend,
+): Promise<RefreshConfig | { error: string }> {
+  if (!existsSync(dbPath)) {
+    return { error: `Database not found at ${dbPath}` };
+  }
+
+  let db: Database | undefined;
+  try {
+    db = new Database(dbPath, { readonly: true });
+
+    // 1. Look up the connection to get oauth_app_id and provider_key
+    const conn = db
+      .query<OAuthConnectionRow, [string, string]>(
+        `SELECT id, oauth_app_id, provider_key FROM oauth_connections WHERE id = ? AND status = ? LIMIT 1`,
+      )
+      .get(connectionId, "active");
+
+    if (!conn) {
+      return { error: `No active OAuth connection found for "${connectionId}"` };
+    }
+
+    // 2. Look up the app to get client_id and client_secret_credential_path
+    const app = db
+      .query<OAuthAppRow, [string]>(
+        `SELECT id, provider_key, client_id, client_secret_credential_path FROM oauth_apps WHERE id = ? LIMIT 1`,
+      )
+      .get(conn.oauth_app_id);
+
+    if (!app) {
+      return { error: `No OAuth app found for connection "${connectionId}"` };
+    }
+
+    // 3. Look up the provider to get token_url and auth method
+    const provider = db
+      .query<OAuthProviderRow, [string]>(
+        `SELECT provider_key, token_url, token_endpoint_auth_method FROM oauth_providers WHERE provider_key = ? LIMIT 1`,
+      )
+      .get(conn.provider_key);
+
+    if (!provider) {
+      return { error: `No OAuth provider found for "${conn.provider_key}"` };
+    }
+
+    if (!provider.token_url || !app.client_id) {
+      return { error: `Missing OAuth2 refresh config for "${conn.provider_key}"` };
+    }
+
+    // 4. Retrieve the client secret from secure storage
+    const clientSecret = await secureKeyBackend.get(
+      app.client_secret_credential_path,
+    );
+
+    const authMethod = (provider.token_endpoint_auth_method as TokenEndpointAuthMethod | null) ?? "client_secret_post";
+
+    return {
+      tokenUrl: provider.token_url,
+      clientId: app.client_id,
+      clientSecret,
+      authMethod,
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { error: `Failed to resolve refresh config: ${msg}` };
+  } finally {
+    db?.close();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// HTTP token refresh (replicates assistant/src/security/oauth2.ts logic)
+// ---------------------------------------------------------------------------
+
+interface RefreshTokenResponse {
+  accessToken: string;
+  refreshToken?: string;
+  expiresIn?: number;
+}
+
+async function performTokenRefresh(
+  config: RefreshConfig,
+  refreshToken: string,
+): Promise<RefreshTokenResponse> {
+  const body: Record<string, string> = {
+    grant_type: "refresh_token",
+    refresh_token: refreshToken,
+  };
+
+  const headers: Record<string, string> = {
+    "Content-Type": "application/x-www-form-urlencoded",
+  };
+
+  if (config.clientSecret && config.authMethod === "client_secret_basic") {
+    const credentials = Buffer.from(
+      `${config.clientId}:${config.clientSecret}`,
+    ).toString("base64");
+    headers["Authorization"] = `Basic ${credentials}`;
+  } else {
+    body.client_id = config.clientId;
+    if (config.clientSecret) {
+      body.client_secret = config.clientSecret;
+    }
+  }
+
+  const resp = await fetch(config.tokenUrl, {
+    method: "POST",
+    headers,
+    body: new URLSearchParams(body),
+  });
+
+  if (!resp.ok) {
+    const rawBody = await resp.text().catch(() => "");
+    let errorCode = "";
+    try {
+      const parsed = JSON.parse(rawBody) as Record<string, unknown>;
+      if (parsed.error) {
+        errorCode = String(parsed.error);
+      }
+    } catch {
+      // non-JSON response
+    }
+    const detail = errorCode
+      ? `HTTP ${resp.status}: ${errorCode}`
+      : `HTTP ${resp.status}`;
+    throw new Error(`OAuth2 token refresh failed (${detail})`);
+  }
+
+  const data = (await resp.json()) as Record<string, unknown>;
+
+  return {
+    accessToken: data.access_token as string,
+    refreshToken: (data.refresh_token as string | undefined) ?? refreshToken,
+    expiresIn: data.expires_in as number | undefined,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Public factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a `TokenRefreshFn` for CES local mode.
+ *
+ * The returned function looks up OAuth configuration from the assistant's
+ * SQLite database (read-only) and performs the HTTP token refresh call.
+ * Token persistence is handled by the `LocalMaterialiser` after this
+ * function returns.
+ *
+ * @param vellumRoot - The Vellum root directory (e.g. `~/.vellum`).
+ * @param secureKeyBackend - Backend for retrieving the OAuth client secret.
+ */
+export function createLocalTokenRefreshFn(
+  vellumRoot: string,
+  secureKeyBackend: SecureKeyBackend,
+): TokenRefreshFn {
+  const dbPath = join(vellumRoot, "workspace", "data", "db", "assistant.db");
+
+  return async (
+    connectionId: string,
+    refreshToken: string,
+  ): Promise<TokenRefreshResult> => {
+    // 1. Resolve the refresh config from SQLite + secure storage
+    const config = await resolveRefreshConfig(
+      dbPath,
+      connectionId,
+      secureKeyBackend,
+    );
+
+    if ("error" in config) {
+      return { success: false, error: config.error };
+    }
+
+    // 2. Perform the HTTP token refresh
+    try {
+      const result = await performTokenRefresh(config, refreshToken);
+      const expiresAt = computeExpiresAt(result.expiresIn ?? null);
+
+      return {
+        success: true,
+        accessToken: result.accessToken,
+        expiresAt,
+        refreshToken: result.refreshToken,
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return { success: false, error: message };
+    }
+  };
+}

package/src/materializers/local.ts

@@ -22,6 +22,7 @@
  */
 
 import {
+  type InjectionTemplate,
   type SecureKeyBackend,
   type TokenRefreshResult,
   getStoredAccessToken,
@@ -55,6 +56,8 @@ export interface MaterialisedCredential {
   handleType: HandleType;
   /** For OAuth: the token expiry timestamp (null if unknown). */
   expiresAt?: number | null;
+  /** Injection templates from the credential metadata (local_static only). */
+  injectionTemplates?: InjectionTemplate[];
 }
 
 export type MaterialisationResult =
@@ -152,6 +155,7 @@ export class LocalMaterialiser {
       credential: {
         value: secretValue,
         handleType: HandleType.LocalStatic,
+        injectionTemplates: subject.metadata.injectionTemplates,
       },
     };
   }
@@ -181,11 +185,22 @@ export class LocalMaterialiser {
     }
 
     // 2. Check if the token is expired and needs refresh
-    if (
-      isTokenExpired(connection.expiresAt) &&
-      connection.hasRefreshToken
-    ) {
-      return this.refreshAndMaterialise(subject, connectionId);
+    if (connection.hasRefreshToken) {
+      // For refreshable tokens, use the proactive buffer so we can refresh
+      // before the token actually expires.
+      if (isTokenExpired(connection.expiresAt)) {
+        return this.refreshAndMaterialise(subject, connectionId);
+      }
+    } else {
+      // For non-refreshable tokens, check against the hard expiry — use
+      // every valid second rather than the 5-minute proactive buffer.
+      if (connection.expiresAt && Date.now() >= connection.expiresAt) {
+        return {
+          ok: false,
+          error: `Token for OAuth connection "${connectionId}" is expired and no refresh ` +
+            `token is available. Re-authorization required.`,
+        };
+      }
     }
 
     // 3. Token is valid — return it
@@ -263,6 +278,7 @@ export class LocalMaterialiser {
             connectionId,
             {
               accessToken: result.accessToken,
+              refreshToken: result.refreshToken,
               expiresIn: result.expiresAt
                 ? Math.floor((result.expiresAt - Date.now()) / 1000)
                 : null,