@vellumai/credential-executor 0.10.7 → 0.10.8-dev.202607102228.5945895

package/src/materializers/local-oauth-lookup.ts

@@ -1,98 +0,0 @@
-/**
- * CES-native read-only OAuth connection lookup for local mode.
- *
- * In local mode, CES runs as a child process of the assistant on the same
- * machine and can read the assistant's SQLite database to look up OAuth
- * connections.
- *
- * This implementation opens the database in read-only mode and queries the
- * `oauth_connections` table directly using raw SQLite queries. It does not
- * use Drizzle ORM to avoid importing assistant-internal schema modules.
- *
- * The lookup is read-only — CES never modifies OAuth connection records.
- */
-
-import Database from "bun:sqlite";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-
-import type { OAuthConnectionRecord } from "@vellumai/credential-storage";
-import { oauthConnectionAccessTokenPath } from "@vellumai/credential-storage";
-import type { OAuthConnectionLookup } from "../subjects/local.js";
-
-// ---------------------------------------------------------------------------
-// Raw SQLite row shape (matches oauth_connections table)
-// ---------------------------------------------------------------------------
-
-interface OAuthConnectionRow {
-  id: string;
-  oauth_app_id: string;
-  provider_key: string;
-  account_info: string | null;
-  granted_scopes: string;
-  expires_at: number | null;
-  has_refresh_token: number;
-  status: string;
-  label: string | null;
-  metadata: string | null;
-  created_at: number;
-  updated_at: number;
-}
-
-// ---------------------------------------------------------------------------
-// Row → OAuthConnectionRecord mapping
-// ---------------------------------------------------------------------------
-
-function rowToRecord(row: OAuthConnectionRow): OAuthConnectionRecord {
-  return {
-    id: row.id,
-    providerKey: row.provider_key,
-    accountInfo: row.account_info,
-    grantedScopes: JSON.parse(row.granted_scopes || "[]"),
-    accessTokenPath: oauthConnectionAccessTokenPath(row.id),
-    hasRefreshToken: row.has_refresh_token === 1,
-    expiresAt: row.expires_at,
-    createdAt: row.created_at,
-    updatedAt: row.updated_at,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Lookup implementation
-// ---------------------------------------------------------------------------
-
-/**
- * Create a read-only OAuth connection lookup backed by the assistant's
- * SQLite database.
- *
- * @param workspaceDir - The workspace directory (e.g. `$VELLUM_WORKSPACE_DIR`).
- */
-export function createLocalOAuthLookup(
-  workspaceDir: string,
-): OAuthConnectionLookup {
-  const dbPath = join(workspaceDir, "data", "db", "assistant.db");
-
-  return {
-    getById(connectionId: string): OAuthConnectionRecord | undefined {
-      if (!existsSync(dbPath)) return undefined;
-
-      let db: Database | undefined;
-      try {
-        db = new Database(dbPath, { readonly: true });
-        const row = db
-          .query<
-            OAuthConnectionRow,
-            [string, string]
-          >(`SELECT * FROM oauth_connections WHERE id = ? AND status = ? LIMIT 1`)
-          .get(connectionId, "active");
-
-        if (!row) return undefined;
-        return rowToRecord(row);
-      } catch {
-        return undefined;
-      } finally {
-        db?.close();
-      }
-    },
-  };
-}

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

@@ -1,287 +0,0 @@
-/**
- * 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;
-  refresh_url: string | null;
-  token_endpoint_auth_method: string | null;
-  token_exchange_body_format: 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;
-  bodyFormat: "form" | "json";
-}
-
-/**
- * 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, refresh_url, token_endpoint_auth_method, token_exchange_body_format FROM oauth_providers WHERE provider_key = ? LIMIT 1`)
-      .get(conn.provider_key);
-
-    if (!provider) {
-      return { error: `No OAuth provider found for "${conn.provider_key}"` };
-    }
-
-    // Resolve the effective token URL: prefer refresh_url, fall back to token_url
-    const tokenUrl = provider.refresh_url || provider.token_url;
-
-    if (!tokenUrl || !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";
-    const bodyFormat =
-      (provider.token_exchange_body_format as "form" | "json" | null) ?? "form";
-
-    return {
-      tokenUrl,
-      clientId: app.client_id,
-      clientSecret,
-      authMethod,
-      bodyFormat,
-    };
-  } 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":
-      config.bodyFormat === "json"
-        ? "application/json"
-        : "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:
-      config.bodyFormat === "json"
-        ? JSON.stringify(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(
-  workspaceDir: string,
-  secureKeyBackend: SecureKeyBackend,
-): TokenRefreshFn {
-  const dbPath = join(workspaceDir, "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

@@ -1,316 +0,0 @@
-/**
- * CES local credential materialisation.
- *
- * Materialises credential values from local storage into per-operation
- * results that the CES execution layer can inject into authenticated
- * requests or commands. Materialised values never persist to assistant-
- * visible state — they exist only for the duration of the execution.
- *
- * Supports two credential types:
- *
- * - **Static secrets** — Retrieved from the secure-key backend using the
- *   storage key from the resolved subject. Fails if the key is missing.
- *
- * - **OAuth tokens** — Retrieved from the secure-key backend using the
- *   connection's access token path. Automatically refreshes expired tokens
- *   using the shared `@vellumai/credential-storage` refresh primitives.
- *   Fails if no access token exists (disconnected connection) or if
- *   refresh fails.
- *
- * Materialisation is fail-closed: missing keys, disconnected connections,
- * and refresh failures all return errors before any outbound work starts.
- */
-
-import {
-  type InjectionTemplate,
-  type SecureKeyBackend,
-  type TokenRefreshResult,
-  getStoredAccessToken,
-  getStoredRefreshToken,
-  isTokenExpired,
-  RefreshCircuitBreaker,
-  RefreshDeduplicator,
-  persistRefreshedTokens,
-} from "@vellumai/credential-storage";
-import { HandleType } from "@vellumai/service-contracts/credential-rpc";
-
-import type {
-  ResolvedLocalSubject,
-  ResolvedOAuthSubject,
-  ResolvedStaticSubject,
-} from "../subjects/local.js";
-
-// ---------------------------------------------------------------------------
-// Materialisation result
-// ---------------------------------------------------------------------------
-
-/**
- * A materialised credential value ready for injection into an execution
- * environment. The value is ephemeral and must not be persisted to any
- * assistant-visible store.
- */
-export interface MaterialisedCredential {
-  /** The credential value (secret, token, etc.). */
-  value: string;
-  /** The handle type that produced this value. */
-  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 =
-  | { ok: true; credential: MaterialisedCredential }
-  | { ok: false; error: string };
-
-// ---------------------------------------------------------------------------
-// Token refresh callback
-// ---------------------------------------------------------------------------
-
-/**
- * Callback for performing the actual OAuth token refresh network call.
- *
- * CES delegates the refresh network call to callers so it remains
- * transport-agnostic. The callback receives the connection ID and
- * refresh token, and returns a `TokenRefreshResult` from the shared
- * credential-storage primitives.
- */
-export type TokenRefreshFn = (
-  connectionId: string,
-  refreshToken: string,
-) => Promise<TokenRefreshResult>;
-
-// ---------------------------------------------------------------------------
-// Local materialiser
-// ---------------------------------------------------------------------------
-
-export interface LocalMaterialiserDeps {
-  /** Secure-key backend for retrieving secret values. */
-  secureKeyBackend: SecureKeyBackend;
-  /** Optional token refresh callback for OAuth tokens. */
-  tokenRefreshFn?: TokenRefreshFn;
-}
-
-/**
- * Local credential materialiser.
- *
- * Stateful: maintains a per-connection circuit breaker and refresh
- * deduplicator for OAuth token refresh. Create one instance per CES
- * process lifetime.
- */
-export class LocalMaterialiser {
-  private readonly backend: SecureKeyBackend;
-  private readonly tokenRefreshFn?: TokenRefreshFn;
-  private readonly circuitBreaker = new RefreshCircuitBreaker();
-  private readonly deduplicator = new RefreshDeduplicator();
-
-  constructor(deps: LocalMaterialiserDeps) {
-    this.backend = deps.secureKeyBackend;
-    this.tokenRefreshFn = deps.tokenRefreshFn;
-  }
-
-  /**
-   * Materialise a resolved local subject into a credential value.
-   *
-   * Dispatches to the appropriate handler based on the subject type.
-   * Returns a discriminated result — never throws for expected failure
-   * modes (missing keys, disconnected connections, expired tokens).
-   */
-  async materialise(
-    subject: ResolvedLocalSubject,
-  ): Promise<MaterialisationResult> {
-    switch (subject.type) {
-      case HandleType.LocalStatic:
-        return this.materialiseStatic(subject);
-      case HandleType.LocalOAuth:
-        return this.materialiseOAuth(subject);
-      default:
-        return {
-          ok: false,
-          error: `Unsupported subject type for local materialisation`,
-        };
-    }
-  }
-
-  // -----------------------------------------------------------------------
-  // Static secret materialisation
-  // -----------------------------------------------------------------------
-
-  private async materialiseStatic(
-    subject: ResolvedStaticSubject,
-  ): Promise<MaterialisationResult> {
-    const secretValue = await this.backend.get(subject.storageKey);
-    if (secretValue === undefined) {
-      return {
-        ok: false,
-        error: `Secure key "${subject.storageKey}" not found in local credential store. ` +
-          `The credential for service="${subject.metadata.service}", field="${subject.metadata.field}" ` +
-          `has metadata but no secret value stored.`,
-      };
-    }
-
-    return {
-      ok: true,
-      credential: {
-        value: secretValue,
-        handleType: HandleType.LocalStatic,
-        injectionTemplates: subject.metadata.injectionTemplates,
-      },
-    };
-  }
-
-  // -----------------------------------------------------------------------
-  // OAuth token materialisation
-  // -----------------------------------------------------------------------
-
-  private async materialiseOAuth(
-    subject: ResolvedOAuthSubject,
-  ): Promise<MaterialisationResult> {
-    const { connection } = subject;
-    const connectionId = connection.id;
-
-    // 1. Get the stored access token
-    const accessToken = await getStoredAccessToken(
-      this.backend,
-      connectionId,
-    );
-
-    if (!accessToken) {
-      return {
-        ok: false,
-        error: `No access token found for OAuth connection "${connectionId}" ` +
-          `(provider="${connection.providerKey}"). The connection is disconnected.`,
-      };
-    }
-
-    // 2. Check if the token is expired and needs refresh
-    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
-    return {
-      ok: true,
-      credential: {
-        value: accessToken,
-        handleType: HandleType.LocalOAuth,
-        expiresAt: connection.expiresAt,
-      },
-    };
-  }
-
-  /**
-   * Refresh an expired OAuth token and return the materialised result.
-   *
-   * Uses the circuit breaker to prevent retry storms and the deduplicator
-   * to coalesce concurrent refresh attempts for the same connection.
-   */
-  private async refreshAndMaterialise(
-    subject: ResolvedOAuthSubject,
-    connectionId: string,
-  ): Promise<MaterialisationResult> {
-    // Check circuit breaker
-    if (this.circuitBreaker.isOpen(connectionId)) {
-      return {
-        ok: false,
-        error: `Token refresh circuit breaker is open for connection "${connectionId}". ` +
-          `Too many consecutive refresh failures. Re-authorization may be required.`,
-      };
-    }
-
-    if (!this.tokenRefreshFn) {
-      return {
-        ok: false,
-        error: `Token for OAuth connection "${connectionId}" is expired but no refresh ` +
-          `function is configured. Re-authorization required.`,
-      };
-    }
-
-    // Get the refresh token
-    const refreshToken = await getStoredRefreshToken(
-      this.backend,
-      connectionId,
-    );
-    if (!refreshToken) {
-      return {
-        ok: false,
-        error: `Token for OAuth connection "${connectionId}" is expired and no refresh ` +
-          `token is available. Re-authorization required.`,
-      };
-    }
-
-    try {
-      // Use deduplicator to prevent concurrent refresh attempts
-      const tokenRefreshFn = this.tokenRefreshFn;
-      const backend = this.backend;
-      const circuitBreaker = this.circuitBreaker;
-
-      const newAccessToken = await this.deduplicator.deduplicate(
-        connectionId,
-        async () => {
-          const result = await tokenRefreshFn(connectionId, refreshToken);
-          if (!result.success) {
-            circuitBreaker.recordFailure(connectionId);
-            throw new Error(result.error);
-          }
-
-          circuitBreaker.recordSuccess(connectionId);
-
-          // Persist the refreshed tokens to the secure-key backend
-          // (but NOT to any assistant-visible state)
-          const persisted = await persistRefreshedTokens(
-            backend,
-            connectionId,
-            {
-              accessToken: result.accessToken,
-              refreshToken: result.refreshToken,
-              expiresIn: result.expiresAt
-                ? Math.floor((result.expiresAt - Date.now()) / 1000)
-                : null,
-            },
-          );
-
-          return persisted.accessToken;
-        },
-      );
-
-      return {
-        ok: true,
-        credential: {
-          value: newAccessToken,
-          handleType: HandleType.LocalOAuth,
-          expiresAt: null, // Refresh result expiry is tracked internally
-        },
-      };
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      return {
-        ok: false,
-        error: `Failed to refresh token for OAuth connection "${connectionId}": ${message}`,
-      };
-    }
-  }
-
-  /**
-   * Reset circuit breaker and deduplicator state (primarily for testing).
-   */
-  reset(): void {
-    this.circuitBreaker.clear();
-    this.deduplicator.clear();
-  }
-}