@vellumai/assistant 0.4.46 → 0.4.49

package/src/oauth/byo-connection.ts

@@ -0,0 +1,128 @@
+/**
+ * BYO (Bring-Your-Own) OAuth connection implementation.
+ *
+ * Wraps the existing `withValidToken` token management infrastructure to
+ * provide the OAuthConnection interface. Delegates all token resolution,
+ * proactive refresh, circuit breaker, and retry-on-401 logic to
+ * `withValidToken` from `token-manager.ts`.
+ */
+
+import { withValidToken } from "../security/token-manager.js";
+import { getLogger } from "../util/logger.js";
+import type {
+  OAuthConnection,
+  OAuthConnectionRequest,
+  OAuthConnectionResponse,
+} from "./connection.js";
+
+const log = getLogger("byo-oauth-connection");
+
+/** Default per-request timeout to prevent hung requests from blocking indefinitely. */
+const REQUEST_TIMEOUT_MS = 30_000;
+
+export interface BYOOAuthConnectionOptions {
+  id: string;
+  providerKey: string;
+  baseUrl: string;
+  accountInfo: string | null;
+  grantedScopes: string[];
+  credentialService: string;
+}
+
+export class BYOOAuthConnection implements OAuthConnection {
+  readonly id: string;
+  readonly providerKey: string;
+  readonly accountInfo: string | null;
+  readonly grantedScopes: string[];
+
+  private readonly baseUrl: string;
+  private readonly credentialService: string;
+
+  constructor(opts: BYOOAuthConnectionOptions) {
+    this.id = opts.id;
+    this.providerKey = opts.providerKey;
+    this.baseUrl = opts.baseUrl;
+    this.accountInfo = opts.accountInfo;
+    this.grantedScopes = opts.grantedScopes;
+    this.credentialService = opts.credentialService;
+  }
+
+  async request(req: OAuthConnectionRequest): Promise<OAuthConnectionResponse> {
+    return withValidToken(this.credentialService, async (token) => {
+      const effectiveBaseUrl = req.baseUrl ?? this.baseUrl;
+      let fullUrl = `${effectiveBaseUrl}${req.path}`;
+
+      if (req.query && Object.keys(req.query).length > 0) {
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(req.query)) {
+          if (Array.isArray(value)) {
+            for (const v of value) params.append(key, v);
+          } else {
+            params.append(key, value);
+          }
+        }
+        fullUrl += `?${params.toString()}`;
+      }
+
+      log.debug(
+        { method: req.method, url: fullUrl, provider: this.providerKey },
+        "Making authenticated request",
+      );
+
+      // Use the Headers API for case-insensitive merging. Set defaults
+      // first so caller-supplied headers (in any casing) override them.
+      const headers = new Headers();
+      if (req.body) {
+        headers.set("Content-Type", "application/json");
+      }
+      if (req.headers) {
+        for (const [key, value] of Object.entries(req.headers)) {
+          headers.set(key, value);
+        }
+      }
+      headers.set("Authorization", `Bearer ${token}`);
+
+      const resp = await fetch(fullUrl, {
+        method: req.method,
+        headers,
+        body: req.body ? JSON.stringify(req.body) : undefined,
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      });
+
+      if (resp.status === 401) {
+        // Throw with a status property so withValidToken detects the 401
+        // and triggers its refresh-and-retry logic.
+        const err = new Error(`HTTP 401 from ${this.providerKey}`);
+        (err as Error & { status: number }).status = 401;
+        throw err;
+      }
+
+      return buildResponse(resp);
+    });
+  }
+
+  async withToken<T>(fn: (token: string) => Promise<T>): Promise<T> {
+    return withValidToken(this.credentialService, fn);
+  }
+}
+
+async function buildResponse(resp: Response): Promise<OAuthConnectionResponse> {
+  const headers: Record<string, string> = {};
+  resp.headers.forEach((value, key) => {
+    headers[key] = value;
+  });
+
+  let body: unknown;
+  const text = await resp.text().catch(() => "");
+  if (text) {
+    try {
+      body = JSON.parse(text);
+    } catch {
+      body = text;
+    }
+  } else {
+    body = null;
+  }
+
+  return { status: resp.status, headers, body };
+}

package/src/oauth/connect-orchestrator.ts

@@ -12,7 +12,7 @@
  * - Ensuring metadata is writable (assertMetadataWritable)
  *
  * The orchestrator handles:
- * - Provider profile resolution
+ * - Provider config resolution (from DB)
  * - Scope policy enforcement
  * - Building the OAuth2Config
  * - Running the interactive or deferred flow
@@ -23,13 +23,54 @@
 import type { TokenEndpointAuthMethod } from "../security/oauth2.js";
 import { prepareOAuth2Flow, startOAuth2Flow } from "../security/oauth2.js";
 import { getLogger } from "../util/logger.js";
-import type { OAuthConnectResult } from "./connect-types.js";
-import { getProviderProfile, resolveService } from "./provider-profiles.js";
+import type {
+  OAuthConnectResult,
+  OAuthProviderBehavior,
+  OAuthScopePolicy,
+} from "./connect-types.js";
+import { getProvider } from "./oauth-store.js";
+import { getProviderBehavior, resolveService } from "./provider-behaviors.js";
 import { resolveScopes } from "./scope-policy.js";
 import { storeOAuth2Tokens } from "./token-persistence.js";
 
 const log = getLogger("oauth-connect-orchestrator");
 
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Look up the code-side behavioral fields for a provider.
+ * Returns an empty object when no behavior is registered.
+ */
+function resolveBehavior(providerKey: string): {
+  identityVerifier?: OAuthProviderBehavior["identityVerifier"];
+  setup?: OAuthProviderBehavior["setup"];
+  setupSkillId?: string;
+  postConnectHookId?: string;
+  injectionTemplates?: OAuthProviderBehavior["injectionTemplates"];
+} {
+  const behavior = getProviderBehavior(providerKey);
+  if (!behavior) return {};
+  return {
+    identityVerifier: behavior.identityVerifier,
+    setup: behavior.setup,
+    setupSkillId: behavior.setupSkillId,
+    postConnectHookId: behavior.postConnectHookId,
+    injectionTemplates: behavior.injectionTemplates,
+  };
+}
+
+/** Safely parse a JSON string, returning a fallback on failure or null/undefined input. */
+function safeJsonParse<T>(value: string | null | undefined, fallback: T): T {
+  if (value == null) return fallback;
+  try {
+    return JSON.parse(value) as T;
+  } catch {
+    return fallback;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Options
 // ---------------------------------------------------------------------------
@@ -52,14 +93,17 @@ export interface OAuthConnectOptions {
   /** Tools allowed to use the resulting credential. */
   allowedTools?: string[];
 
-  // Optional overrides — when provided, these take precedence over the
-  // provider profile. This lets callers connect custom / unknown providers.
-  authUrl?: string;
-  tokenUrl?: string;
-  scopes?: string[];
-  extraParams?: Record<string, string>;
-  userinfoUrl?: string;
-  tokenEndpointAuthMethod?: TokenEndpointAuthMethod;
+  /**
+   * Called when the deferred (non-interactive) flow completes — either
+   * successfully after tokens are stored, or on failure. Lets callers
+   * surface the outcome via SSE events, logs, etc.
+   */
+  onDeferredComplete?: (result: {
+    success: boolean;
+    service: string;
+    accountInfo?: string;
+    error?: string;
+  }) => void;
 }
 
 // ---------------------------------------------------------------------------
@@ -78,42 +122,69 @@ export async function orchestrateOAuthConnect(
   options: OAuthConnectOptions,
 ): Promise<OAuthConnectResult> {
   const resolvedService = resolveService(options.service);
-  const profile = getProviderProfile(resolvedService);
 
-  // Merge explicit overrides with profile defaults
-  const authUrl = options.authUrl ?? profile?.authUrl;
-  const tokenUrl = options.tokenUrl ?? profile?.tokenUrl;
-  const extraParams = options.extraParams ?? profile?.extraParams;
-  const userinfoUrl = options.userinfoUrl ?? profile?.userinfoUrl;
-  const tokenEndpointAuthMethod =
-    options.tokenEndpointAuthMethod ?? profile?.tokenEndpointAuthMethod;
+  // Read provider config from the DB
+  const providerRow = getProvider(resolvedService);
+  if (!providerRow) {
+    return {
+      success: false,
+      error: `No OAuth provider registered for "${resolvedService}". Ensure the provider is seeded in the database.`,
+      safeError: true,
+    };
+  }
+
+  // Behavioral/code-side fields come from the behavior registry
+  const behavior = resolveBehavior(resolvedService);
 
-  // Scopes: use explicit override, then try scope policy resolution, then profile defaults
-  let finalScopes: string[];
-  if (options.scopes) {
-    // Explicit scopes override — bypass policy (caller takes responsibility)
-    finalScopes = options.scopes;
-  } else if (profile) {
-    const scopeResult = resolveScopes(profile, options.requestedScopes);
-    if (!scopeResult.ok) {
-      const guidance = scopeResult.allowedScopes
-        ? ` Allowed scopes: ${scopeResult.allowedScopes.join(", ")}`
-        : "";
-      return {
-        success: false,
-        error: `${scopeResult.error}${guidance}`,
-        safeError: true,
-      };
-    }
-    finalScopes = scopeResult.scopes;
-  } else {
-    // No profile and no explicit scopes — cannot proceed
+  // Deserialize JSON fields from the DB row
+  const dbDefaultScopes = safeJsonParse<string[]>(
+    providerRow.defaultScopes,
+    [],
+  );
+  const dbScopePolicy = safeJsonParse<OAuthScopePolicy>(
+    providerRow.scopePolicy,
+    {
+      allowAdditionalScopes: false,
+      allowedOptionalScopes: [],
+      forbiddenScopes: [],
+    },
+  );
+  const dbExtraParams = safeJsonParse<Record<string, string> | undefined>(
+    providerRow.extraParams,
+    undefined,
+  );
+
+  // Resolve all protocol-level config from the DB
+  const authUrl = providerRow.authUrl;
+  const tokenUrl = providerRow.tokenUrl;
+  const extraParams = dbExtraParams;
+  const userinfoUrl = providerRow.userinfoUrl ?? undefined;
+  const tokenEndpointAuthMethod = providerRow.tokenEndpointAuthMethod as
+    | TokenEndpointAuthMethod
+    | undefined;
+  const callbackTransport =
+    (providerRow.callbackTransport as "loopback" | "gateway" | null) ??
+    "gateway";
+  const loopbackPort = providerRow.loopbackPort;
+
+  // Resolve scopes via the scope policy engine
+  const scopeProfile = {
+    service: resolvedService,
+    defaultScopes: dbDefaultScopes,
+    scopePolicy: dbScopePolicy,
+  };
+  const scopeResult = resolveScopes(scopeProfile, options.requestedScopes);
+  if (!scopeResult.ok) {
+    const guidance = scopeResult.allowedScopes
+      ? ` Allowed scopes: ${scopeResult.allowedScopes.join(", ")}`
+      : "";
     return {
       success: false,
-      error: `No well-known OAuth config found for "${options.service}" and no scopes were provided`,
+      error: `${scopeResult.error}${guidance}`,
       safeError: true,
     };
   }
+  const finalScopes = scopeResult.scopes;
 
   if (!authUrl) {
     return {
@@ -149,7 +220,7 @@ export async function orchestrateOAuthConnect(
     tokenEndpointAuthMethod,
     userinfoUrl,
     allowedTools: options.allowedTools,
-    wellKnownInjectionTemplates: profile?.injectionTemplates,
+    wellKnownInjectionTemplates: behavior.injectionTemplates,
   };
 
   // -----------------------------------------------------------------------
@@ -157,8 +228,6 @@ export async function orchestrateOAuthConnect(
   // -----------------------------------------------------------------------
   if (!options.isInteractive) {
     try {
-      const callbackTransport = profile?.callbackTransport ?? "gateway";
-
       // Gateway transport needs a public ingress URL
       if (callbackTransport !== "loopback") {
         const { loadConfig } = await import("../config/loader.js");
@@ -179,7 +248,7 @@ export async function orchestrateOAuthConnect(
       const prepared = await prepareOAuth2Flow(
         oauthConfig,
         callbackTransport === "loopback"
-          ? { callbackTransport, loopbackPort: profile?.loopbackPort }
+          ? { callbackTransport, loopbackPort: loopbackPort ?? undefined }
           : undefined,
       );
 
@@ -189,10 +258,10 @@ export async function orchestrateOAuthConnect(
           try {
             let accountInfo: string | undefined;
 
-            // Run identity verifier if available
-            if (profile?.identityVerifier) {
+            // Run identity verifier if available (code-side behavior)
+            if (behavior.identityVerifier) {
               try {
-                accountInfo = await profile.identityVerifier(
+                accountInfo = await behavior.identityVerifier(
                   result.tokens.accessToken,
                 );
               } catch {
@@ -214,11 +283,21 @@ export async function orchestrateOAuthConnect(
               },
               "Deferred OAuth2 flow completed — tokens stored",
             );
+            options.onDeferredComplete?.({
+              success: true,
+              service: resolvedService,
+              accountInfo: stored.accountInfo ?? accountInfo,
+            });
           } catch (err) {
             log.error(
               { err, service: resolvedService },
               "Failed to store tokens from deferred OAuth2 flow",
             );
+            options.onDeferredComplete?.({
+              success: false,
+              service: resolvedService,
+              error: err instanceof Error ? err.message : "Unknown error",
+            });
           }
         })
         .catch((err) => {
@@ -226,6 +305,11 @@ export async function orchestrateOAuthConnect(
             { err, service: resolvedService },
             "Deferred OAuth2 flow failed",
           );
+          options.onDeferredComplete?.({
+            success: false,
+            service: resolvedService,
+            error: err instanceof Error ? err.message : "Unknown error",
+          });
         });
 
       return {
@@ -266,19 +350,18 @@ export async function orchestrateOAuthConnect(
           }
         },
       },
-      profile?.callbackTransport
-        ? {
-            callbackTransport: profile.callbackTransport,
-            loopbackPort: profile.loopbackPort,
-          }
-        : undefined,
+      callbackTransport === "loopback"
+        ? { callbackTransport, loopbackPort: loopbackPort ?? undefined }
+        : callbackTransport === "gateway"
+          ? { callbackTransport }
+          : undefined,
     );
 
-    // Run identity verifier if available
+    // Run identity verifier if available (code-side behavior)
     let verifiedIdentity: string | undefined;
-    if (profile?.identityVerifier) {
+    if (behavior.identityVerifier) {
       try {
-        verifiedIdentity = await profile.identityVerifier(tokens.accessToken);
+        verifiedIdentity = await behavior.identityVerifier(tokens.accessToken);
       } catch {
         // Non-fatal
       }

package/src/oauth/connect-types.ts

@@ -1,11 +1,15 @@
 /**
  * Shared types for the OAuth provider extensibility layer.
  *
- * These types are consumed by the provider profile registry, the token
+ * These types are consumed by the provider behavior registry, the token
  * persistence module, and the credential vault orchestrator.
+ *
+ * Protocol-level OAuth config (authUrl, tokenUrl, scopes, etc.) is now
+ * stored exclusively in the `oauth_providers` SQLite table. This file
+ * only defines code-side behavioral types that cannot be serialised to
+ * a DB row (functions, templates, UI metadata).
  */
 
-import type { TokenEndpointAuthMethod } from "../security/oauth2.js";
 import type { CredentialInjectionTemplate } from "../tools/credentials/policy-types.js";
 
 // ---------------------------------------------------------------------------
@@ -23,31 +27,21 @@ export interface OAuthScopePolicy {
 }
 
 // ---------------------------------------------------------------------------
-// Provider profile
+// Provider behavior
 // ---------------------------------------------------------------------------
 
-/** Full configuration profile for a well-known OAuth provider. */
-export interface OAuthProviderProfile {
+/**
+ * Code-side behavioral configuration for a well-known OAuth provider.
+ *
+ * Protocol-level fields (authUrl, tokenUrl, defaultScopes, scopePolicy,
+ * tokenEndpointAuthMethod, callbackTransport, loopbackPort, userinfoUrl,
+ * extraParams) are stored in the `oauth_providers` DB table. This
+ * interface contains only fields that require code references (functions,
+ * templates, skill IDs) and cannot be serialised to a DB row.
+ */
+export interface OAuthProviderBehavior {
   /** Canonical service key (e.g. "integration:twitter"). */
   service: string;
-  /** OAuth2 authorization endpoint. */
-  authUrl: string;
-  /** OAuth2 token endpoint. */
-  tokenUrl: string;
-  /** Default scopes requested during authorization. */
-  defaultScopes: string[];
-  /** Policy governing additional/forbidden scopes. */
-  scopePolicy: OAuthScopePolicy;
-  /** How to send client credentials at the token endpoint. */
-  tokenEndpointAuthMethod?: TokenEndpointAuthMethod;
-  /** Force a specific callback transport. */
-  callbackTransport?: "loopback" | "gateway";
-  /** Fixed port for loopback transport (e.g. Slack). */
-  loopbackPort?: number;
-  /** Endpoint to fetch user identity info after authorization. */
-  userinfoUrl?: string;
-  /** Extra query parameters appended to the authorization URL. */
-  extraParams?: Record<string, string>;
   /**
    * Async function that verifies the user's identity after a successful
    * token exchange. Returns a human-readable account identifier (e.g.

package/src/oauth/connection-resolver.ts

@@ -0,0 +1,58 @@
+import { getSecureKey } from "../security/secure-keys.js";
+import { BYOOAuthConnection } from "./byo-connection.js";
+import type { OAuthConnection } from "./connection.js";
+import { getApp, getConnectionByProvider, getProvider } from "./oauth-store.js";
+
+/**
+ * Resolve an OAuthConnection for a given credential service.
+ *
+ * Reads exclusively from the SQLite oauth-store. Throws if no connection
+ * exists (authorization required).
+ */
+export function resolveOAuthConnection(
+  credentialService: string,
+): OAuthConnection {
+  const conn = getConnectionByProvider(credentialService);
+  if (!conn) {
+    throw new Error(
+      `No credential found for "${credentialService}". Authorization required.`,
+    );
+  }
+
+  const accessToken = getSecureKey(`oauth_connection/${conn.id}/access_token`);
+
+  if (!accessToken) {
+    throw new Error(
+      `No access token found for "${credentialService}". Authorization required.`,
+    );
+  }
+
+  // Look up the provider by credentialService first; fall back to the
+  // connection's app's canonical providerKey so custom credential_service
+  // overrides (e.g. "integration:github-work") still resolve to the well-known
+  // provider's base URL. We traverse conn -> oauthApp -> providerKey because
+  // conn.providerKey equals credentialService (getConnectionByProvider queries
+  // WHERE providerKey = credentialService), whereas the app's providerKey is a
+  // foreign key to the oauthProviders table.
+  const provider =
+    getProvider(credentialService) ??
+    getProvider(getApp(conn.oauthAppId)?.providerKey ?? "");
+  const baseUrl = provider?.baseUrl;
+
+  if (!baseUrl) {
+    throw new Error(`No base URL configured for "${credentialService}".`);
+  }
+
+  const grantedScopes: string[] = conn.grantedScopes
+    ? JSON.parse(conn.grantedScopes)
+    : [];
+
+  return new BYOOAuthConnection({
+    id: conn.id,
+    providerKey: conn.providerKey,
+    baseUrl,
+    accountInfo: conn.accountInfo,
+    grantedScopes,
+    credentialService,
+  });
+}

package/src/oauth/connection.ts

@@ -0,0 +1,38 @@
+export interface OAuthConnectionRequest {
+  method: string;
+  path: string; // relative, e.g. "/2/tweets"
+  query?: Record<string, string | string[]>;
+  headers?: Record<string, string>;
+  body?: unknown; // JSON-serializable
+  /**
+   * Override the connection's default base URL for this request.
+   * Required for providers that span multiple API hosts sharing
+   * one OAuth token (e.g. Google: Gmail, Calendar, People all
+   * use the same credential but different base URLs).
+   */
+  baseUrl?: string;
+}
+
+export interface OAuthConnectionResponse {
+  status: number;
+  headers: Record<string, string>;
+  body: unknown;
+}
+
+export interface OAuthConnection {
+  /** Make an authenticated HTTP request through this connection. */
+  request(req: OAuthConnectionRequest): Promise<OAuthConnectionResponse>;
+
+  /**
+   * Execute a callback with a valid raw access token. This is an escape hatch
+   * for provider-specific endpoints that don't fit the relative-path model
+   * (e.g. Gmail batch API on a different host). Throws for platform connections
+   * where raw tokens are not available locally.
+   */
+  withToken<T>(fn: (token: string) => Promise<T>): Promise<T>;
+
+  readonly id: string;
+  readonly providerKey: string;
+  readonly accountInfo: string | null;
+  readonly grantedScopes: string[];
+}

package/src/oauth/manual-token-connection.ts

@@ -0,0 +1,104 @@
+/**
+ * Helpers for managing oauth_connection records for non-OAuth (manual-token)
+ * providers like slack_channel and telegram.
+ *
+ * These providers store credentials via the keychain (setSecureKeyAsync) but
+ * also maintain an oauth_connection row so that getConnectionByProvider() can
+ * be used as the single source of truth for connection status across the
+ * codebase.
+ */
+
+import { credentialKey } from "../security/credential-key.js";
+import { getSecureKey } from "../security/secure-keys.js";
+import {
+  createConnection,
+  deleteConnection,
+  getConnectionByProvider,
+  updateConnection,
+  upsertApp,
+} from "./oauth-store.js";
+
+/** Sentinel client_id used for non-OAuth providers that don't have a real app. */
+const MANUAL_TOKEN_CLIENT_ID = "manual-config";
+
+/**
+ * Ensure an active oauth_connection row exists for the given manual-token
+ * provider. Creates the synthetic oauth_app row on first use.
+ *
+ * @param providerKey - The provider key (e.g. "slack_channel", "telegram")
+ * @param accountInfo - Optional account info to store (e.g. team name, bot username)
+ */
+export async function ensureManualTokenConnection(
+  providerKey: string,
+  accountInfo?: string,
+): Promise<void> {
+  const existing = getConnectionByProvider(providerKey);
+  if (existing) {
+    // Update account info if provided
+    if (accountInfo !== undefined) {
+      updateConnection(existing.id, { accountInfo });
+    }
+    return;
+  }
+
+  // Create synthetic app + connection
+  const app = await upsertApp(providerKey, MANUAL_TOKEN_CLIENT_ID);
+
+  createConnection({
+    oauthAppId: app.id,
+    providerKey,
+    accountInfo,
+    grantedScopes: [],
+    hasRefreshToken: false,
+  });
+}
+
+/**
+ * Remove the oauth_connection row for a manual-token provider.
+ *
+ * Note: This only removes the oauth_connection row. The caller is still
+ * responsible for deleting the keychain credentials separately.
+ */
+export function removeManualTokenConnection(providerKey: string): void {
+  const conn = getConnectionByProvider(providerKey);
+  if (!conn) return;
+  deleteConnection(conn.id);
+}
+
+/**
+ * Backfill oauth_connection rows for manual-token providers that already
+ * have valid keychain credentials but are missing connection records.
+ *
+ * This handles the upgrade path from installations that stored credentials
+ * before the oauth_connection migration. Without this, existing Telegram
+ * and Slack channel integrations would appear disconnected after upgrading
+ * until the user reconfigures them.
+ *
+ * Safe to call on every startup — skips providers that already have a
+ * connection row.
+ */
+export async function backfillManualTokenConnections(): Promise<void> {
+  // Telegram: requires both bot_token and webhook_secret
+  if (!getConnectionByProvider("telegram")) {
+    const hasBotToken = !!getSecureKey(credentialKey("telegram", "bot_token"));
+    const hasWebhookSecret = !!getSecureKey(
+      credentialKey("telegram", "webhook_secret"),
+    );
+    if (hasBotToken && hasWebhookSecret) {
+      await ensureManualTokenConnection("telegram");
+    }
+  }
+
+  // Slack channel: requires both bot_token and app_token
+  if (!getConnectionByProvider("slack_channel")) {
+    const hasBotToken = !!getSecureKey(
+      credentialKey("slack_channel", "bot_token"),
+    );
+    const hasAppToken = !!getSecureKey(
+      credentialKey("slack_channel", "app_token"),
+    );
+    if (hasBotToken && hasAppToken) {
+      await ensureManualTokenConnection("slack_channel");
+    }
+  }
+}