@vellumai/assistant 0.5.11 → 0.5.13

package/src/oauth/connect-orchestrator.ts

@@ -25,11 +25,10 @@ import { prepareOAuth2Flow, startOAuth2Flow } from "../security/oauth2.js";
 import { getLogger } from "../util/logger.js";
 import type {
   OAuthConnectResult,
-  OAuthProviderBehavior,
   OAuthScopePolicy,
 } from "./connect-types.js";
+import { verifyIdentity } from "./identity-verifier.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";
 
@@ -39,28 +38,6 @@ 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;
-  loopbackPort?: number;
-} {
-  const behavior = getProviderBehavior(providerKey);
-  if (!behavior) return {};
-  return {
-    identityVerifier: behavior.identityVerifier,
-    setup: behavior.setup,
-    setupSkillId: behavior.setupSkillId,
-    postConnectHookId: behavior.postConnectHookId,
-    loopbackPort: behavior.loopbackPort,
-  };
-}
-
 /** 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;
@@ -76,7 +53,7 @@ function safeJsonParse<T>(value: string | null | undefined, fallback: T): T {
 // ---------------------------------------------------------------------------
 
 export interface OAuthConnectOptions {
-  /** Raw service name (may be an alias like "gmail"). */
+  /** Canonical service name (e.g. "google", "slack"). */
   service: string;
   /** Scopes to request beyond the provider's defaults. */
   requestedScopes?: string[];
@@ -119,11 +96,9 @@ export interface OAuthConnectOptions {
 export async function orchestrateOAuthConnect(
   options: OAuthConnectOptions,
 ): Promise<OAuthConnectResult> {
-  const resolvedService = resolveService(options.service);
   log.info(
     {
-      rawService: options.service,
-      resolvedService,
+      service: options.service,
       isInteractive: options.isInteractive,
       hasOpenUrl: !!options.openUrl,
       hasSendToClient: !!options.sendToClient,
@@ -132,18 +107,15 @@ export async function orchestrateOAuthConnect(
   );
 
   // Read provider config from the DB
-  const providerRow = getProvider(resolvedService);
+  const providerRow = getProvider(options.service);
   if (!providerRow) {
     return {
       success: false,
-      error: `No OAuth provider registered for "${resolvedService}". Ensure the provider is seeded in the database.`,
+      error: `No OAuth provider registered for "${options.service}". Ensure the provider is seeded in the database.`,
       safeError: true,
     };
   }
 
-  // Behavioral/code-side fields come from the behavior registry
-  const behavior = resolveBehavior(resolvedService);
-
   // Deserialize JSON fields from the DB row
   const dbDefaultScopes = safeJsonParse<string[]>(
     providerRow.defaultScopes,
@@ -173,11 +145,11 @@ export async function orchestrateOAuthConnect(
   const callbackTransport =
     (providerRow.callbackTransport as "loopback" | "gateway" | null) ??
     "loopback";
-  const loopbackPort = behavior.loopbackPort;
+  const loopbackPort = providerRow.loopbackPort ?? undefined;
 
   // Resolve scopes via the scope policy engine
   const scopeProfile = {
-    service: resolvedService,
+    service: options.service,
     defaultScopes: dbDefaultScopes,
     scopePolicy: dbScopePolicy,
   };
@@ -211,7 +183,7 @@ export async function orchestrateOAuthConnect(
 
   log.info(
     {
-      service: resolvedService,
+      service: options.service,
       authUrl,
       tokenUrl,
       scopeCount: finalScopes.length,
@@ -235,7 +207,7 @@ export async function orchestrateOAuthConnect(
   };
 
   const storageParams = {
-    service: resolvedService,
+    service: options.service,
     clientId: options.clientId,
     clientSecret: options.clientSecret,
     userinfoUrl,
@@ -276,19 +248,12 @@ export async function orchestrateOAuthConnect(
       prepared.completion
         .then(async (result) => {
           try {
-            let parsedAccountIdentifier: string | undefined;
-
             // Parse account identifier from the provider's identity endpoint.
             // Best-effort — format varies by provider and may fail.
-            if (behavior.identityVerifier) {
-              try {
-                parsedAccountIdentifier = await behavior.identityVerifier(
-                  result.tokens.accessToken,
-                );
-              } catch {
-                // Non-fatal
-              }
-            }
+            const parsedAccountIdentifier = await verifyIdentity(
+              providerRow,
+              result.tokens.accessToken,
+            );
 
             const stored = await storeOAuth2Tokens({
               ...storageParams,
@@ -299,36 +264,36 @@ export async function orchestrateOAuthConnect(
             });
             log.info(
               {
-                service: resolvedService,
+                service: options.service,
                 accountInfo: stored.accountInfo ?? parsedAccountIdentifier,
               },
               "Deferred OAuth2 flow completed — tokens stored",
             );
             options.onDeferredComplete?.({
               success: true,
-              service: resolvedService,
+              service: options.service,
               accountInfo: stored.accountInfo ?? parsedAccountIdentifier,
             });
           } catch (err) {
             log.error(
-              { err, service: resolvedService },
+              { err, service: options.service },
               "Failed to store tokens from deferred OAuth2 flow",
             );
             options.onDeferredComplete?.({
               success: false,
-              service: resolvedService,
+              service: options.service,
               error: err instanceof Error ? err.message : "Unknown error",
             });
           }
         })
         .catch((err) => {
           log.error(
-            { err, service: resolvedService },
+            { err, service: options.service },
             "Deferred OAuth2 flow failed",
           );
           options.onDeferredComplete?.({
             success: false,
-            service: resolvedService,
+            service: options.service,
             error: err instanceof Error ? err.message : "Unknown error",
           });
         });
@@ -338,7 +303,7 @@ export async function orchestrateOAuthConnect(
         deferred: true,
         authUrl: prepared.authUrl,
         state: prepared.state,
-        service: resolvedService,
+        service: options.service,
       };
     } catch (err: unknown) {
       const message =
@@ -347,7 +312,7 @@ export async function orchestrateOAuthConnect(
           : "Unknown error preparing OAuth flow";
       return {
         success: false,
-        error: `Error connecting "${resolvedService}": ${message}`,
+        error: `Error connecting "${options.service}": ${message}`,
       };
     }
   }
@@ -356,7 +321,7 @@ export async function orchestrateOAuthConnect(
   // Interactive path — open browser, block until completion
   // -----------------------------------------------------------------------
   log.info(
-    { service: resolvedService, callbackTransport, loopbackPort },
+    { service: options.service, callbackTransport, loopbackPort },
     "orchestrateOAuthConnect: entering interactive path",
   );
   try {
@@ -365,7 +330,7 @@ export async function orchestrateOAuthConnect(
       {
         openUrl: (url) => {
           log.info(
-            { service: resolvedService, urlLength: url.length },
+            { service: options.service, urlLength: url.length },
             "orchestrateOAuthConnect: openUrl callback fired, delivering auth URL to client",
           );
           if (options.openUrl) {
@@ -376,7 +341,7 @@ export async function orchestrateOAuthConnect(
             options.sendToClient({
               type: "open_url",
               url,
-              title: `Connect ${resolvedService}`,
+              title: `Connect ${options.service}`,
             });
           } else {
             log.warn("orchestrateOAuthConnect: no openUrl or sendToClient available — auth URL will not reach the user");
@@ -391,25 +356,21 @@ export async function orchestrateOAuthConnect(
     );
 
     log.info(
-      { service: resolvedService, grantedScopeCount: grantedScopes.length },
+      { service: options.service, grantedScopeCount: grantedScopes.length },
       "orchestrateOAuthConnect: interactive flow completed, exchanged code for tokens",
     );
 
     // Parse account identifier from the provider's identity endpoint.
     // Best-effort — format varies by provider and may fail.
-    let parsedAccountIdentifier: string | undefined;
-    if (behavior.identityVerifier) {
-      try {
-        parsedAccountIdentifier = await behavior.identityVerifier(
-          tokens.accessToken,
-        );
-        log.info(
-          { service: resolvedService, parsedAccountIdentifier },
-          "orchestrateOAuthConnect: identity verified",
-        );
-      } catch {
-        // Non-fatal
-      }
+    const parsedAccountIdentifier = await verifyIdentity(
+      providerRow,
+      tokens.accessToken,
+    );
+    if (parsedAccountIdentifier) {
+      log.info(
+        { service: options.service, parsedAccountIdentifier },
+        "orchestrateOAuthConnect: identity verified",
+      );
     }
 
     const { accountInfo } = await storeOAuth2Tokens({
@@ -421,7 +382,7 @@ export async function orchestrateOAuthConnect(
     });
 
     log.info(
-      { service: resolvedService, accountInfo },
+      { service: options.service, accountInfo },
       "orchestrateOAuthConnect: tokens stored, connect complete",
     );
 
@@ -435,12 +396,12 @@ export async function orchestrateOAuthConnect(
     const message =
       err instanceof Error ? err.message : "Unknown error during OAuth flow";
     log.error(
-      { service: resolvedService, err },
+      { service: options.service, err },
       "orchestrateOAuthConnect: interactive flow failed",
     );
     return {
       success: false,
-      error: `Error connecting "${resolvedService}": ${message}`,
+      error: `Error connecting "${options.service}": ${message}`,
     };
   }
 }

package/src/oauth/connect-types.ts

@@ -1,17 +1,16 @@
 /**
  * Shared types for the OAuth provider extensibility layer.
  *
- * These types are consumed by the provider behavior registry, the token
- * persistence module, and the credential vault orchestrator.
+ * These types are consumed by 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).
+ * All provider configuration — protocol-level OAuth config (authUrl,
+ * tokenUrl, scopes, etc.) as well as behavioral config (identity
+ * verification, injection templates, setup metadata) — is now stored
+ * exclusively in the `oauth_providers` SQLite table and seeded on
+ * startup via `seed-providers.ts`.
  */
 
-import type { CredentialInjectionTemplate } from "../tools/credentials/policy-types.js";
-
 // ---------------------------------------------------------------------------
 // Scope policy
 // ---------------------------------------------------------------------------
@@ -26,63 +25,6 @@ export interface OAuthScopePolicy {
   forbiddenScopes: string[];
 }
 
-// ---------------------------------------------------------------------------
-// Provider behavior
-// ---------------------------------------------------------------------------
-
-/**
- * Code-side behavioral configuration for a well-known OAuth provider.
- *
- * Protocol-level fields (authUrl, tokenUrl, defaultScopes, scopePolicy,
- * tokenEndpointAuthMethod, callbackTransport, 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;
-  /**
-   * Async function that verifies the user's identity after a successful
-   * token exchange. Returns a human-readable account identifier (e.g.
-   * email or @username) or undefined if verification is not possible.
-   */
-  identityVerifier?: (accessToken: string) => Promise<string | undefined>;
-  /** ID of a post-connect hook to run after token storage. */
-  postConnectHookId?: string;
-  /** Injection templates auto-applied to the access_token credential. */
-  injectionTemplates?: CredentialInjectionTemplate[];
-  /**
-   * Metadata for the generic OAuth setup skill. When present, the
-   * assistant can guide users through app creation and OAuth connection.
-   */
-  setup?: {
-    /** Human-readable provider name (e.g. "Discord", "Linear"). */
-    displayName: string;
-    /** URL of the developer dashboard where the user creates an app. */
-    dashboardUrl: string;
-    /** What the provider calls its apps (e.g. "Discord Application"). */
-    appType: string;
-    /** Whether the provider requires a client_secret for token exchange. */
-    requiresClientSecret: boolean;
-    /** Provider-specific notes the LLM should follow during setup. */
-    notes?: string[];
-  };
-  /**
-   * Bundled skill ID that contains provider-specific setup instructions.
-   * When present, the guardrail for missing client_secret directs the
-   * agent to load this skill rather than embedding instructions inline.
-   */
-  setupSkillId?: string;
-  /**
-   * Fixed port for the loopback OAuth callback server. When set, the
-   * server binds to this port instead of an OS-assigned random port.
-   * Required for providers that need pre-registered redirect URIs
-   * (e.g. Slack, Notion).
-   */
-  loopbackPort?: number;
-}
-
 // ---------------------------------------------------------------------------
 // Connect result
 // ---------------------------------------------------------------------------

package/src/oauth/connection-resolver.test.ts

@@ -79,13 +79,13 @@ function makeMockClient() {
 
 function setupDefaults(): void {
   mockProvider = {
-    providerKey: "integration:google",
+    providerKey: "google",
     baseUrl: "https://gmail.googleapis.com/gmail/v1/users/me",
     managedServiceConfigKey: null,
   };
   mockConnection = {
     id: "conn-1",
-    providerKey: "integration:google",
+    providerKey: "google",
     oauthAppId: "app-1",
     accountInfo: "user@example.com",
     grantedScopes: JSON.stringify(["scope-a", "scope-b"]),
@@ -122,26 +122,26 @@ describe("resolveOAuthConnection", () => {
   });
 
   test("returns BYOOAuthConnection when provider has no managedServiceConfigKey", async () => {
-    const result = await resolveOAuthConnection("integration:google");
+    const result = await resolveOAuthConnection("google");
     expect(result).toBeInstanceOf(BYOOAuthConnection);
     expect(result.id).toBe("conn-1");
-    expect(result.providerKey).toBe("integration:google");
+    expect(result.providerKey).toBe("google");
   });
 
   test("returns PlatformOAuthConnection when managed mode is active", async () => {
     mockProvider!.managedServiceConfigKey = "google-oauth";
 
-    const result = await resolveOAuthConnection("integration:google");
+    const result = await resolveOAuthConnection("google");
     expect(result).toBeInstanceOf(PlatformOAuthConnection);
-    expect(result.id).toBe("integration:google");
-    expect(result.providerKey).toBe("integration:google");
+    expect(result.id).toBe("google");
+    expect(result.providerKey).toBe("google");
     expect(result.accountInfo).toBeNull();
   });
 
   test("passes account through to PlatformOAuthConnection", async () => {
     mockProvider!.managedServiceConfigKey = "google-oauth";
 
-    const result = await resolveOAuthConnection("integration:google", {
+    const result = await resolveOAuthConnection("google", {
       account: "user@example.com",
     });
     expect(result).toBeInstanceOf(PlatformOAuthConnection);
@@ -154,7 +154,7 @@ describe("resolveOAuthConnection", () => {
       mode: "your-own",
     };
 
-    const result = await resolveOAuthConnection("integration:google");
+    const result = await resolveOAuthConnection("google");
     expect(result).toBeInstanceOf(BYOOAuthConnection);
     expect(result.id).toBe("conn-1");
   });
@@ -164,21 +164,21 @@ describe("resolveOAuthConnection", () => {
     mockConnection = undefined;
     mockAccessToken = undefined;
 
-    const result = await resolveOAuthConnection("integration:google");
+    const result = await resolveOAuthConnection("google");
     expect(result).toBeInstanceOf(PlatformOAuthConnection);
   });
 
   test("managed path ignores clientId option", async () => {
     mockProvider!.managedServiceConfigKey = "google-oauth";
 
-    const result = await resolveOAuthConnection("integration:google", {
+    const result = await resolveOAuthConnection("google", {
       clientId: "some-client-id",
     });
     expect(result).toBeInstanceOf(PlatformOAuthConnection);
   });
 
   test("BYO path narrows by clientId when provided", async () => {
-    const result = await resolveOAuthConnection("integration:google", {
+    const result = await resolveOAuthConnection("google", {
       clientId: "client-1",
     });
     expect(result).toBeInstanceOf(BYOOAuthConnection);
@@ -187,7 +187,7 @@ describe("resolveOAuthConnection", () => {
 
   test("BYO path returns no credential when clientId does not match", async () => {
     await expect(
-      resolveOAuthConnection("integration:google", {
+      resolveOAuthConnection("google", {
         clientId: "wrong-client",
       }),
     ).rejects.toThrow(/No active OAuth connection found/);

package/src/oauth/connection-resolver.ts

@@ -29,7 +29,7 @@ export interface ResolveOAuthConnectionOptions {
  * BYO providers resolve from the local SQLite oauth-store and require an
  * active connection row and a stored access token.
  *
- * @param providerKey - Provider identifier (e.g. "integration:google").
+ * @param providerKey - Provider identifier (e.g. "google").
  *   Maps to the `provider_key` primary key in the `oauth_providers` table.
  * @param options.clientId - Optional OAuth app client ID. When multiple BYO
  *   apps exist for the same provider, narrows the connection lookup to the
@@ -59,11 +59,9 @@ export async function resolveOAuthConnection(
         );
       }
 
-      const providerSlug = providerKey.replace(/^integration:/, "");
-
       const connectionId = await resolvePlatformConnectionId({
         client,
-        provider: providerSlug,
+        provider: providerKey,
         account,
       });
 
@@ -74,6 +72,7 @@ export async function resolveOAuthConnection(
         accountInfo: account ?? null,
         client,
         connectionId,
+        baseUrl: provider?.baseUrl ?? undefined,
       });
     }
   }

package/src/oauth/identity-verifier.ts

@@ -0,0 +1,177 @@
+/**
+ * Generic, data-driven identity verifier for OAuth providers.
+ *
+ * Replaces per-provider hand-coded `identityVerifier` functions with a
+ * single function that interprets the declarative identity configuration
+ * stored in the `oauth_providers` DB table (identityUrl, identityMethod,
+ * identityHeaders, identityBody, identityResponsePaths, identityFormat,
+ * identityOkField).
+ */
+
+import type { OAuthProviderRow } from "./oauth-store.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Traverse a nested object by a dot-separated path (e.g. "data.viewer.email"). */
+function getNestedValue(obj: unknown, dotPath: string): unknown {
+  const parts = dotPath.split(".");
+  let current: unknown = obj;
+  for (const part of parts) {
+    if (current == null || typeof current !== "object") return undefined;
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current;
+}
+
+/** 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;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Verify the user's identity after a successful OAuth token exchange.
+ *
+ * Returns a human-readable account identifier (e.g. email, @username, or
+ * a formatted string like "@user (team)") or `undefined` when:
+ * - the provider has no identity URL configured
+ * - the identity request fails or returns a non-OK status
+ * - the response cannot be parsed into an identifier
+ *
+ * This function is intentionally non-throwing — identity verification is
+ * always best-effort.
+ */
+export async function verifyIdentity(
+  providerRow: OAuthProviderRow,
+  accessToken: string,
+): Promise<string | undefined> {
+  const { identityUrl: rawUrl } = providerRow;
+  if (!rawUrl) return undefined;
+
+  try {
+    // Interpolate ${accessToken} in the URL (HubSpot pattern)
+    const urlContainsToken = rawUrl.includes("${accessToken}");
+    const url = rawUrl.replace("${accessToken}", accessToken);
+
+    // Build headers
+    const parsedHeaders = safeJsonParse<Record<string, string>>(
+      providerRow.identityHeaders,
+      {},
+    );
+    const headers: Record<string, string> = {
+      ...parsedHeaders,
+    };
+    // Only add the Authorization header if the token is not embedded in the URL
+    if (!urlContainsToken) {
+      headers["Authorization"] = `Bearer ${accessToken}`;
+    }
+
+    // Build request init
+    const method = providerRow.identityMethod ?? "GET";
+    const init: RequestInit = { method, headers };
+
+    // Add body if present
+    if (providerRow.identityBody != null) {
+      const bodyValue = safeJsonParse<unknown>(
+        providerRow.identityBody,
+        providerRow.identityBody,
+      );
+      if (typeof bodyValue === "string") {
+        init.body = bodyValue;
+      } else {
+        init.body = JSON.stringify(bodyValue);
+      }
+    }
+
+    // Make the request
+    const resp = await fetch(url, init);
+    if (!resp.ok) return undefined;
+
+    const body: unknown = await resp.json();
+
+    // Check OK field (Slack pattern: body.ok must be truthy)
+    if (providerRow.identityOkField) {
+      const okValue = getNestedValue(body, providerRow.identityOkField);
+      if (!okValue) return undefined;
+    }
+
+    // Parse response paths
+    const responsePaths = safeJsonParse<string[]>(
+      providerRow.identityResponsePaths,
+      [],
+    );
+    if (responsePaths.length === 0) return undefined;
+
+    const { identityFormat } = providerRow;
+
+    // Simple mode: no format template — return the first non-null path value
+    if (!identityFormat) {
+      for (const path of responsePaths) {
+        const value = getNestedValue(body, path);
+        if (value != null) return String(value);
+      }
+      return undefined;
+    }
+
+    // Format mode: build a lookup map from all paths, then interpolate
+    const pathValues = new Map<string, string | undefined>();
+    for (const path of responsePaths) {
+      const value = getNestedValue(body, path);
+      pathValues.set(path, value != null ? String(value) : undefined);
+    }
+
+    // Replace ${path} tokens in the format string
+    let result = identityFormat;
+    let allResolved = true;
+    for (const [path, value] of pathValues) {
+      if (value != null) {
+        result = result.replace(`\${${path}}`, value);
+      } else {
+        allResolved = false;
+      }
+    }
+
+    if (allResolved) return result;
+
+    // Fallback: if some tokens couldn't be resolved, try cleaning up
+    // the format string by removing unresolved tokens and their surrounding
+    // punctuation (parentheses, spaces).
+    // First, try removing unresolved tokens with their surrounding parens/space
+    // e.g. "@${user} (${team})" with missing team -> "@user"
+    let cleaned = identityFormat;
+    for (const [path, value] of pathValues) {
+      if (value != null) {
+        cleaned = cleaned.replace(`\${${path}}`, value);
+      } else {
+        // Remove patterns like " (${path})" or " ${path}" or "(${path})"
+        cleaned = cleaned.replace(
+          new RegExp(`\\s*\\(?\\$\\{${path.replace(/\./g, "\\.")}\\}\\)?`, "g"),
+          "",
+        );
+      }
+    }
+
+    cleaned = cleaned.trim();
+    if (cleaned) return cleaned;
+
+    // Last resort: return the first non-null path value
+    for (const value of pathValues.values()) {
+      if (value != null) return value;
+    }
+
+    return undefined;
+  } catch {
+    // Non-fatal — identity verification is best-effort
+    return undefined;
+  }
+}