@vellumai/credential-executor 0.4.55 → 0.4.56

package/node_modules/@vellumai/credential-storage/src/oauth-runtime.ts

@@ -0,0 +1,340 @@
+/**
+ * OAuth connection persistence, token persistence, and refresh support
+ * primitives.
+ *
+ * This module provides portable, backend-agnostic helpers for:
+ * - Secure-key path conventions for OAuth tokens and client secrets
+ * - Token expiry checking with proactive refresh buffering
+ * - Token refresh circuit breaker to prevent retry storms
+ * - Per-connection refresh deduplication
+ * - Abstract token persistence interface
+ *
+ * It has NO dependency on the assistant daemon, SQLite, Drizzle, or any
+ * service-specific module. The assistant's token-manager.ts and
+ * token-persistence.ts wire in the platform-specific backends and
+ * delegate here for shared logic.
+ */
+
+import type { SecureKeyBackend } from "./index.js";
+
+// ---------------------------------------------------------------------------
+// Secure-key path conventions
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the secure-key path for an OAuth connection's access token.
+ */
+export function oauthConnectionAccessTokenPath(connectionId: string): string {
+  return `oauth_connection/${connectionId}/access_token`;
+}
+
+/**
+ * Build the secure-key path for an OAuth connection's refresh token.
+ */
+export function oauthConnectionRefreshTokenPath(connectionId: string): string {
+  return `oauth_connection/${connectionId}/refresh_token`;
+}
+
+/**
+ * Build the secure-key path for an OAuth app's client secret.
+ */
+export function oauthAppClientSecretPath(appId: string): string {
+  return `oauth_app/${appId}/client_secret`;
+}
+
+// ---------------------------------------------------------------------------
+// Token expiry
+// ---------------------------------------------------------------------------
+
+/** Buffer before expiry to trigger proactive refresh (5 minutes). */
+export const EXPIRY_BUFFER_MS = 5 * 60 * 1000;
+
+/**
+ * Check whether a token is expired or will expire within the buffer window.
+ */
+export function isTokenExpired(
+  expiresAt: number | null,
+  bufferMs: number = EXPIRY_BUFFER_MS
+): boolean {
+  if (!expiresAt) return false;
+  return Date.now() >= expiresAt - bufferMs;
+}
+
+/**
+ * Compute the absolute expiry timestamp from an `expires_in` seconds value.
+ * Returns null if the value is missing or zero.
+ */
+export function computeExpiresAt(
+  expiresIn: number | null | undefined
+): number | null {
+  if (expiresIn == null || expiresIn <= 0) return null;
+  return Date.now() + expiresIn * 1000;
+}
+
+// ---------------------------------------------------------------------------
+// Token refresh circuit breaker
+// ---------------------------------------------------------------------------
+// Prevents retry storms when a provider persistently rejects refresh
+// attempts (e.g. revoked refresh token returning 401 repeatedly).
+// Per-key state: after FAILURE_THRESHOLD consecutive failures, stop
+// attempting refreshes for a cooldown period that doubles on each
+// successive trip (exponential backoff), capped at MAX_COOLDOWN_MS.
+// A successful refresh resets the breaker for that key.
+
+export const REFRESH_FAILURE_THRESHOLD = 3;
+export const INITIAL_COOLDOWN_MS = 30_000;
+export const MAX_COOLDOWN_MS = 10 * 60 * 1000;
+
+export interface RefreshBreakerState {
+  consecutiveFailures: number;
+  openedAt: number;
+  cooldownMs: number;
+}
+
+/**
+ * In-memory token refresh circuit breaker.
+ *
+ * Tracks per-key (typically connection ID) failure state. After
+ * FAILURE_THRESHOLD consecutive failures, the breaker opens for a
+ * cooldown period that doubles on each successive trip.
+ */
+export class RefreshCircuitBreaker {
+  private breakers = new Map<string, RefreshBreakerState>();
+
+  /**
+   * Check whether the breaker is currently open (refusing refresh attempts)
+   * for the given key. If the cooldown has expired, transitions to half-open
+   * by resetting the failure count.
+   */
+  isOpen(key: string): boolean {
+    const state = this.breakers.get(key);
+    if (!state || state.consecutiveFailures < REFRESH_FAILURE_THRESHOLD)
+      return false;
+    if (Date.now() - state.openedAt < state.cooldownMs) return true;
+    // Cooldown expired — transition to half-open: reset failure count so the
+    // next batch of failures must reach the threshold again to re-trip. The
+    // existing cooldownMs is preserved so re-tripping will escalate it.
+    state.consecutiveFailures = 0;
+    return false;
+  }
+
+  /** Get the breaker state for a key, if it exists. */
+  getState(key: string): RefreshBreakerState | undefined {
+    return this.breakers.get(key);
+  }
+
+  /** Record a successful refresh, resetting the breaker for the key. */
+  recordSuccess(key: string): void {
+    this.breakers.delete(key);
+  }
+
+  /** Record a failed refresh attempt, potentially opening the breaker. */
+  recordFailure(key: string): void {
+    const state = this.breakers.get(key);
+    if (!state) {
+      this.breakers.set(key, {
+        consecutiveFailures: 1,
+        openedAt: 0,
+        cooldownMs: INITIAL_COOLDOWN_MS,
+      });
+      return;
+    }
+    state.consecutiveFailures++;
+    if (state.consecutiveFailures >= REFRESH_FAILURE_THRESHOLD) {
+      // Only escalate cooldown on the exact failure that trips the breaker.
+      // Concurrent in-flight failures that arrive after the threshold is
+      // already crossed must not double the cooldown again.
+      if (
+        state.consecutiveFailures === REFRESH_FAILURE_THRESHOLD &&
+        state.openedAt > 0
+      ) {
+        state.cooldownMs = Math.min(state.cooldownMs * 2, MAX_COOLDOWN_MS);
+      }
+      state.openedAt = Date.now();
+    }
+  }
+
+  /** Reset all breaker state (primarily for testing). */
+  clear(): void {
+    this.breakers.clear();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Refresh deduplication
+// ---------------------------------------------------------------------------
+
+/**
+ * Deduplicates concurrent refresh attempts for the same key.
+ *
+ * When multiple callers detect an expired or rejected token for the same
+ * connection simultaneously, only one actual refresh attempt is made.
+ * Other callers join the in-flight promise.
+ */
+export class RefreshDeduplicator {
+  private inflight = new Map<string, Promise<string>>();
+
+  /**
+   * Execute a refresh operation, deduplicating concurrent calls for the same key.
+   * If a refresh is already in flight for the given key, returns the existing promise.
+   */
+  deduplicate(key: string, refreshFn: () => Promise<string>): Promise<string> {
+    const existing = this.inflight.get(key);
+    if (existing) return existing;
+
+    const promise = refreshFn().finally(() => {
+      this.inflight.delete(key);
+    });
+    this.inflight.set(key, promise);
+    return promise;
+  }
+
+  /** Reset all in-flight state (primarily for testing). */
+  clear(): void {
+    this.inflight.clear();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Credential error classification
+// ---------------------------------------------------------------------------
+
+/**
+ * Distinguish credential-specific refresh failures (which need reauthorization)
+ * from transient errors (network timeouts, 5xx) that can be retried.
+ *
+ * Credential errors: 400 with invalid_grant or invalid_client, 401, 403.
+ * Everything else (5xx, network errors, non-credential 400s) is transient.
+ */
+export function isCredentialError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  const msg = err.message;
+  // 401/403 are always credential errors
+  if (/HTTP\s+40[13]\b/.test(msg)) return true;
+  // 400 with invalid_grant means the refresh token is revoked/expired;
+  // invalid_client means client credentials are bad/rotated
+  if (/HTTP\s+400\b/.test(msg) && /invalid_grant|invalid_client/.test(msg))
+    return true;
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Token persistence helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Persist an OAuth access token (and optionally a refresh token) to the
+ * secure-key backend for a given connection ID.
+ *
+ * When `refreshToken` is provided, it is stored. When omitted (undefined),
+ * any existing refresh token is cleared to prevent stale token usage.
+ */
+export async function persistOAuthTokens(
+  backend: SecureKeyBackend,
+  connectionId: string,
+  tokens: {
+    accessToken: string;
+    refreshToken?: string;
+  }
+): Promise<void> {
+  const accessPath = oauthConnectionAccessTokenPath(connectionId);
+  const stored = await backend.set(accessPath, tokens.accessToken);
+  if (!stored) {
+    throw new Error("Failed to store access token in secure storage");
+  }
+
+  const refreshPath = oauthConnectionRefreshTokenPath(connectionId);
+  if (tokens.refreshToken) {
+    await backend.set(refreshPath, tokens.refreshToken);
+  } else {
+    // Re-auth grants that omit refresh_token must clear any stale stored
+    // token — otherwise refresh attempts will use invalid credentials.
+    await backend.delete(refreshPath);
+  }
+}
+
+/**
+ * Retrieve the stored access token for a connection from the secure-key backend.
+ * Returns undefined if no token is stored.
+ */
+export async function getStoredAccessToken(
+  backend: SecureKeyBackend,
+  connectionId: string
+): Promise<string | undefined> {
+  return backend.get(oauthConnectionAccessTokenPath(connectionId));
+}
+
+/**
+ * Retrieve the stored refresh token for a connection from the secure-key backend.
+ * Returns undefined if no token is stored.
+ */
+export async function getStoredRefreshToken(
+  backend: SecureKeyBackend,
+  connectionId: string
+): Promise<string | undefined> {
+  return backend.get(oauthConnectionRefreshTokenPath(connectionId));
+}
+
+/**
+ * Delete all OAuth tokens (access + refresh) for a connection from the
+ * secure-key backend. Returns the individual deletion results.
+ */
+export async function deleteOAuthTokens(
+  backend: SecureKeyBackend,
+  connectionId: string
+): Promise<{
+  accessTokenResult: "deleted" | "not-found" | "error";
+  refreshTokenResult: "deleted" | "not-found" | "error";
+}> {
+  // Delete sequentially to avoid lost updates — the encrypted store uses
+  // read-modify-write, so concurrent deletes can restore a deleted key.
+  const accessTokenResult = await backend.delete(oauthConnectionAccessTokenPath(connectionId));
+  const refreshTokenResult = await backend.delete(oauthConnectionRefreshTokenPath(connectionId));
+  return { accessTokenResult, refreshTokenResult };
+}
+
+/**
+ * Store a refreshed access token in the secure-key backend and update
+ * connection metadata. Returns the new access token on success.
+ *
+ * This is the portable portion of the post-refresh persistence logic.
+ * Callers are responsible for updating their connection store (e.g. SQLite)
+ * with the new expiresAt and hasRefreshToken values.
+ */
+export async function persistRefreshedTokens(
+  backend: SecureKeyBackend,
+  connectionId: string,
+  result: {
+    accessToken: string;
+    refreshToken?: string;
+    expiresIn?: number | null;
+  }
+): Promise<{
+  accessToken: string;
+  expiresAt: number | null;
+  hasRefreshToken: boolean;
+}> {
+  const accessPath = oauthConnectionAccessTokenPath(connectionId);
+  if (!(await backend.set(accessPath, result.accessToken))) {
+    throw new Error(
+      `Failed to store refreshed access token for connection ${connectionId}`
+    );
+  }
+
+  if (result.refreshToken) {
+    const refreshPath = oauthConnectionRefreshTokenPath(connectionId);
+    if (!(await backend.set(refreshPath, result.refreshToken))) {
+      throw new Error(
+        `Failed to store refreshed refresh token for connection ${connectionId}`
+      );
+    }
+  }
+
+  const expiresAt = computeExpiresAt(result.expiresIn);
+
+  return {
+    accessToken: result.accessToken,
+    expiresAt,
+    hasRefreshToken: !!result.refreshToken,
+  };
+}

package/node_modules/@vellumai/credential-storage/src/static-credentials.ts

@@ -0,0 +1,365 @@
+/**
+ * Static credential metadata persistence primitives.
+ *
+ * Provides a portable, path-parameterized metadata store for local static
+ * credential records. This module has NO dependency on the assistant daemon,
+ * platform helpers, or any service-specific code — callers supply the file
+ * path and this module handles versioned JSON persistence with atomic writes.
+ *
+ * The assistant's `metadata-store.ts` wires in the platform-specific data
+ * directory and re-exports convenience functions that delegate here.
+ */
+
+import { randomUUID } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+
+import type { InjectionTemplate, StaticCredentialRecord } from "./index.js";
+
+// ---------------------------------------------------------------------------
+// On-disk schema
+// ---------------------------------------------------------------------------
+
+/** Current on-disk schema version. */
+const CURRENT_VERSION = 5;
+
+interface MetadataFile {
+  version: typeof CURRENT_VERSION;
+  credentials: StaticCredentialRecord[];
+}
+
+/**
+ * Returned when the on-disk file has a version we don't understand.
+ * Callers that mutate state must check for this to avoid overwriting
+ * data written by a newer version of the app.
+ */
+interface UnknownVersionResult {
+  readonly unknownVersion: true;
+}
+
+type LoadResult = MetadataFile | UnknownVersionResult;
+
+function isUnknownVersion(r: LoadResult): r is UnknownVersionResult {
+  return "unknownVersion" in r;
+}
+
+// ---------------------------------------------------------------------------
+// Validation & migration helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true if a value looks like a valid credential record (has required fields).
+ * Filters out corrupted or incomplete entries during migration.
+ */
+function isValidCredentialRecord(
+  record: unknown
+): record is Record<string, unknown> {
+  if (typeof record !== "object" || record == null) return false;
+  const r = record as Record<string, unknown>;
+  return (
+    typeof r.credentialId === "string" &&
+    typeof r.service === "string" &&
+    typeof r.field === "string" &&
+    typeof r.createdAt === "number" &&
+    typeof r.updatedAt === "number"
+  );
+}
+
+/**
+ * Migrate any record to v5 by stripping OAuth-specific fields that are
+ * now exclusively managed by the SQLite oauth-store.
+ */
+function migrateRecordToV5(
+  record: Record<string, unknown>
+): StaticCredentialRecord {
+  return {
+    credentialId: record.credentialId as string,
+    service: record.service as string,
+    field: record.field as string,
+    allowedTools: Array.isArray(record.allowedTools)
+      ? (record.allowedTools as string[])
+      : [],
+    allowedDomains: Array.isArray(record.allowedDomains)
+      ? (record.allowedDomains as string[])
+      : [],
+    usageDescription:
+      typeof record.usageDescription === "string"
+        ? record.usageDescription
+        : undefined,
+    alias: typeof record.alias === "string" ? record.alias : undefined,
+    injectionTemplates: Array.isArray(record.injectionTemplates)
+      ? (record.injectionTemplates as InjectionTemplate[])
+      : undefined,
+    createdAt: record.createdAt as number,
+    updatedAt: record.updatedAt as number,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Filesystem helpers (inlined to avoid assistant-specific imports)
+// ---------------------------------------------------------------------------
+
+function ensureDir(dir: string): void {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+function readTextFileSync(path: string): string | null {
+  try {
+    if (!existsSync(path)) return null;
+    return readFileSync(path, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Core store implementation
+// ---------------------------------------------------------------------------
+
+function loadFile(
+  metadataPath: string,
+  saveFileFn: (data: MetadataFile, path: string) => void
+): LoadResult {
+  const raw = readTextFileSync(metadataPath);
+  if (raw == null) {
+    return { version: CURRENT_VERSION, credentials: [] };
+  }
+  try {
+    const data = JSON.parse(raw);
+    if (typeof data !== "object" || data == null) {
+      return { version: CURRENT_VERSION, credentials: [] };
+    }
+    const fileVersion = typeof data.version === "number" ? data.version : 1;
+    if (
+      fileVersion !== 1 &&
+      fileVersion !== 2 &&
+      fileVersion !== 3 &&
+      fileVersion !== 4 &&
+      fileVersion !== 5
+    ) {
+      // Unrecognized version (future, fractional, negative, zero) — refuse to touch it
+      return { unknownVersion: true };
+    }
+    const rawCredentials: unknown[] = Array.isArray(data.credentials)
+      ? data.credentials
+      : [];
+    // Filter out malformed entries that lack required fields
+    const validRecords = rawCredentials.filter(isValidCredentialRecord);
+
+    if (fileVersion < CURRENT_VERSION) {
+      // Migrate all older versions to v5 by stripping OAuth-specific fields
+      // and removing ghost refresh_token records
+      const filtered = validRecords.filter(
+        (r) => (r as Record<string, unknown>).field !== "refresh_token"
+      );
+      const credentials = filtered.map(migrateRecordToV5);
+      const migrated: MetadataFile = { version: CURRENT_VERSION, credentials };
+      try {
+        saveFileFn(migrated, metadataPath);
+      } catch {
+        /* persist failed — will retry on next write */
+      }
+      return migrated;
+    }
+
+    return {
+      version: CURRENT_VERSION,
+      credentials: (validRecords as unknown) as StaticCredentialRecord[],
+    };
+  } catch {
+    // Corrupted / unparseable file — treat as empty to avoid data loss on next write
+    return { version: CURRENT_VERSION, credentials: [] };
+  }
+}
+
+function saveFile(data: MetadataFile, path: string): void {
+  const dir = dirname(path);
+  ensureDir(dir);
+  const tmpPath = join(dir, `.tmp-${randomUUID()}`);
+  writeFileSync(tmpPath, JSON.stringify(data, null, 2), "utf-8");
+  renameSync(tmpPath, path);
+}
+
+// ---------------------------------------------------------------------------
+// Policy input for upsert
+// ---------------------------------------------------------------------------
+
+/** Policy fields that can be set or updated when upserting a credential. */
+export interface StaticCredentialPolicyInput {
+  allowedTools?: string[];
+  allowedDomains?: string[];
+  usageDescription?: string;
+  /** Pass `null` to explicitly clear a previously-set alias. */
+  alias?: string | null;
+  /** Pass `null` to explicitly clear injection templates. */
+  injectionTemplates?: InjectionTemplate[] | null;
+}
+
+// ---------------------------------------------------------------------------
+// StaticCredentialMetadataStore
+// ---------------------------------------------------------------------------
+
+/**
+ * Portable, path-parameterized metadata store for local static credentials.
+ *
+ * Callers supply the file path; this class handles versioned JSON persistence,
+ * schema migration, and CRUD operations. It has no dependency on the assistant
+ * daemon or platform-specific code.
+ */
+export class StaticCredentialMetadataStore {
+  private metadataPath: string;
+
+  constructor(metadataPath: string) {
+    this.metadataPath = metadataPath;
+  }
+
+  /** Update the metadata file path (primarily for testing). */
+  setPath(path: string): void {
+    this.metadataPath = path;
+  }
+
+  /** Get the current metadata file path. */
+  getPath(): string {
+    return this.metadataPath;
+  }
+
+  /**
+   * Throws if the metadata file has an unrecognized version.
+   * Call this before performing irreversible keychain operations
+   * so the operation fails cleanly before any side effects.
+   */
+  assertWritable(): void {
+    const result = loadFile(this.metadataPath, saveFile);
+    if (isUnknownVersion(result)) {
+      throw new Error(
+        "Credential metadata file has an unrecognized version; refusing to mutate to avoid data loss"
+      );
+    }
+  }
+
+  /**
+   * Create or update a credential metadata record.
+   * If a record with the same service+field exists, it is updated.
+   */
+  upsert(
+    service: string,
+    field: string,
+    policy?: StaticCredentialPolicyInput
+  ): StaticCredentialRecord {
+    const result = loadFile(this.metadataPath, saveFile);
+    if (isUnknownVersion(result)) {
+      throw new Error(
+        "Credential metadata file has an unrecognized version; refusing to mutate to avoid data loss"
+      );
+    }
+    const data = result;
+    const now = Date.now();
+
+    const existing = data.credentials.find(
+      (c) => c.service === service && c.field === field
+    );
+
+    if (existing) {
+      if (policy?.allowedTools !== undefined)
+        existing.allowedTools = policy.allowedTools;
+      if (policy?.allowedDomains !== undefined)
+        existing.allowedDomains = policy.allowedDomains;
+      if (policy?.usageDescription !== undefined)
+        existing.usageDescription = policy.usageDescription;
+      if (policy?.alias !== undefined) {
+        if (policy.alias == null) {
+          delete existing.alias;
+        } else {
+          existing.alias = policy.alias;
+        }
+      }
+      if (policy?.injectionTemplates !== undefined) {
+        if (policy.injectionTemplates == null) {
+          delete existing.injectionTemplates;
+        } else {
+          existing.injectionTemplates = policy.injectionTemplates;
+        }
+      }
+      existing.updatedAt = now;
+      saveFile(data, this.metadataPath);
+      return existing;
+    }
+
+    const record: StaticCredentialRecord = {
+      credentialId: randomUUID(),
+      service,
+      field,
+      allowedTools: policy?.allowedTools ?? [],
+      allowedDomains: policy?.allowedDomains ?? [],
+      usageDescription: policy?.usageDescription,
+      alias: policy?.alias ?? undefined,
+      injectionTemplates: policy?.injectionTemplates ?? undefined,
+      createdAt: now,
+      updatedAt: now,
+    };
+
+    data.credentials.push(record);
+    saveFile(data, this.metadataPath);
+    return record;
+  }
+
+  /**
+   * Get metadata for a credential by service and field.
+   */
+  getByServiceField(
+    service: string,
+    field: string
+  ): StaticCredentialRecord | undefined {
+    const result = loadFile(this.metadataPath, saveFile);
+    if (isUnknownVersion(result)) return undefined;
+    return result.credentials.find(
+      (c) => c.service === service && c.field === field
+    );
+  }
+
+  /**
+   * Get metadata for a credential by its opaque ID.
+   */
+  getById(credentialId: string): StaticCredentialRecord | undefined {
+    const result = loadFile(this.metadataPath, saveFile);
+    if (isUnknownVersion(result)) return undefined;
+    return result.credentials.find((c) => c.credentialId === credentialId);
+  }
+
+  /**
+   * List all credential metadata records.
+   */
+  list(): StaticCredentialRecord[] {
+    const result = loadFile(this.metadataPath, saveFile);
+    if (isUnknownVersion(result)) return [];
+    return result.credentials;
+  }
+
+  /**
+   * Delete metadata for a credential.
+   */
+  delete(service: string, field: string): boolean {
+    const result = loadFile(this.metadataPath, saveFile);
+    if (isUnknownVersion(result)) {
+      throw new Error(
+        "Credential metadata file has an unrecognized version; refusing to mutate to avoid data loss"
+      );
+    }
+    const data = result;
+    const idx = data.credentials.findIndex(
+      (c) => c.service === service && c.field === field
+    );
+    if (idx === -1) return false;
+    data.credentials.splice(idx, 1);
+    saveFile(data, this.metadataPath);
+    return true;
+  }
+}