@vellumai/assistant 0.5.1 → 0.5.3

package/src/oauth/oauth-store.ts

@@ -45,7 +45,9 @@ export type OAuthConnectionRow = typeof oauthConnections.$inferSelect;
  * Seed well-known provider profiles into the database. Uses INSERT … ON
  * CONFLICT DO UPDATE so that implementation fields (authUrl, tokenUrl,
  * tokenEndpointAuthMethod, userinfoUrl, extraParams, callbackTransport,
- * pingUrl) propagate to existing installations on every startup, while
+ * pingUrl, managedServiceConfigKey) and display metadata (displayName,
+ * description, dashboardUrl, clientIdPlaceholder, requiresClientSecret)
+ * propagate to existing installations on every startup, while
  * user-customizable fields (defaultScopes, scopePolicy, baseUrl) are
  * only written on the initial insert.
  */
@@ -62,6 +64,12 @@ export function seedProviders(
     scopePolicy: Record<string, unknown>;
     extraParams?: Record<string, string>;
     callbackTransport?: string;
+    managedServiceConfigKey?: string;
+    displayName?: string;
+    description?: string;
+    dashboardUrl?: string | null;
+    clientIdPlaceholder?: string | null;
+    requiresClientSecret?: boolean;
   }>,
 ): void {
   const db = getDb();
@@ -77,6 +85,12 @@ export function seedProviders(
     const scopePolicy = JSON.stringify(p.scopePolicy);
     const extraParams = p.extraParams ? JSON.stringify(p.extraParams) : null;
     const callbackTransport = p.callbackTransport ?? null;
+    const managedServiceConfigKey = p.managedServiceConfigKey ?? null;
+    const displayName = p.displayName ?? null;
+    const description = p.description ?? null;
+    const dashboardUrl = p.dashboardUrl ?? null;
+    const clientIdPlaceholder = p.clientIdPlaceholder ?? null;
+    const requiresClientSecret = p.requiresClientSecret !== false ? 1 : 0;
 
     db.insert(oauthProviders)
       .values({
@@ -91,6 +105,12 @@ export function seedProviders(
         extraParams,
         callbackTransport,
         pingUrl,
+        managedServiceConfigKey,
+        displayName,
+        description,
+        dashboardUrl,
+        clientIdPlaceholder,
+        requiresClientSecret,
         createdAt: now,
         updatedAt: now,
       })
@@ -104,6 +124,12 @@ export function seedProviders(
           extraParams,
           callbackTransport,
           pingUrl,
+          managedServiceConfigKey,
+          displayName,
+          description,
+          dashboardUrl,
+          clientIdPlaceholder,
+          requiresClientSecret,
           updatedAt: now,
         },
       })
@@ -143,6 +169,12 @@ export function registerProvider(params: {
   scopePolicy: Record<string, unknown>;
   extraParams?: Record<string, string>;
   callbackTransport?: string;
+  managedServiceConfigKey?: string;
+  displayName?: string;
+  description?: string;
+  dashboardUrl?: string;
+  clientIdPlaceholder?: string;
+  requiresClientSecret?: number;
 }): OAuthProviderRow {
   const db = getDb();
   const now = Date.now();
@@ -164,6 +196,12 @@ export function registerProvider(params: {
     extraParams: params.extraParams ? JSON.stringify(params.extraParams) : null,
     callbackTransport: params.callbackTransport ?? null,
     pingUrl: params.pingUrl ?? null,
+    managedServiceConfigKey: params.managedServiceConfigKey ?? null,
+    displayName: params.displayName ?? null,
+    description: params.description ?? null,
+    dashboardUrl: params.dashboardUrl ?? null,
+    clientIdPlaceholder: params.clientIdPlaceholder ?? null,
+    requiresClientSecret: params.requiresClientSecret ?? 1,
     createdAt: now,
     updatedAt: now,
   };
@@ -232,6 +270,16 @@ export async function upsertApp(
       if (!stored) {
         throw new Error("Failed to store client_secret in secure storage");
       }
+      // Bump updatedAt so the rollback guard in the new-row insertion path
+      // can detect that a concurrent caller has claimed this row. Without
+      // this, a concurrent inserter's rollback DELETE would still match on
+      // the original updatedAt and delete the row we just validated.
+      const newUpdatedAt = Date.now();
+      db.update(oauthApps)
+        .set({ updatedAt: newUpdatedAt })
+        .where(eq(oauthApps.id, existingRow.id))
+        .run();
+      return { ...existingRow, updatedAt: newUpdatedAt };
     }
     if (clientSecretCredentialPath) {
       db.update(oauthApps)
@@ -272,7 +320,14 @@ export async function upsertApp(
     if (!stored) {
       // Roll back the just-inserted row to avoid an orphaned app pointing
       // at a non-existent client_secret in secure storage.
-      db.delete(oauthApps).where(eq(oauthApps.id, id)).run();
+      //
+      // Guard: only delete if updatedAt still matches our insertion timestamp.
+      // A concurrent upsertApp call may have observed this row, successfully
+      // stored the secret, and updated the row — deleting it would orphan that
+      // caller's valid reference.
+      db.delete(oauthApps)
+        .where(and(eq(oauthApps.id, id), eq(oauthApps.updatedAt, now)))
+        .run();
       throw new Error("Failed to store client_secret in secure storage");
     }
   }
@@ -286,6 +341,15 @@ export function getApp(id: string): OAuthAppRow | undefined {
   return db.select().from(oauthApps).where(eq(oauthApps.id, id)).get();
 }
 
+/** Read an app client_secret from secure storage. */
+export async function getAppClientSecret(
+  appOrId: OAuthAppRow | string,
+): Promise<string | undefined> {
+  const app = typeof appOrId === "string" ? getApp(appOrId) : appOrId;
+  if (!app) return undefined;
+  return getSecureKeyAsync(app.clientSecretCredentialPath);
+}
+
 /** Look up an app by (provider_key, client_id). */
 export function getAppByProviderAndClientId(
   providerKey: string,
@@ -407,71 +471,59 @@ export function getConnection(id: string): OAuthConnectionRow | undefined {
 
 /**
  * Get the most recent active connection for a provider.
- * When `clientId` is provided, only connections linked to the matching app are considered.
- * Returns undefined if no active connection exists.
+ *
+ * Optional filters narrow the result:
+ * - `account` — match a specific account identifier (e.g. email).
+ * - `clientId` — restrict to connections linked to a specific OAuth app.
+ *
+ * Returns `undefined` when no matching active connection exists.
  */
-export function getConnectionByProvider(
+export function getActiveConnection(
   providerKey: string,
-  clientId?: string,
+  options?: { clientId?: string; account?: string },
 ): OAuthConnectionRow | undefined {
+  const { clientId, account } = options ?? {};
   const db = getDb();
 
+  const conditions = [
+    eq(oauthConnections.providerKey, providerKey),
+    eq(oauthConnections.status, "active"),
+  ];
+
+  if (account) {
+    conditions.push(eq(oauthConnections.accountInfo, account));
+  }
+
   if (clientId) {
     const app = getAppByProviderAndClientId(providerKey, clientId);
     if (!app) return undefined;
-    return db
-      .select()
-      .from(oauthConnections)
-      .where(
-        and(
-          eq(oauthConnections.providerKey, providerKey),
-          eq(oauthConnections.oauthAppId, app.id),
-          eq(oauthConnections.status, "active"),
-        ),
-      )
-      .orderBy(desc(oauthConnections.createdAt), sql`rowid DESC`)
-      .limit(1)
-      .get();
+    conditions.push(eq(oauthConnections.oauthAppId, app.id));
   }
 
   return db
     .select()
     .from(oauthConnections)
-    .where(
-      and(
-        eq(oauthConnections.providerKey, providerKey),
-        eq(oauthConnections.status, "active"),
-      ),
-    )
+    .where(and(...conditions))
     .orderBy(desc(oauthConnections.createdAt), sql`rowid DESC`)
     .limit(1)
     .get();
 }
 
-/**
- * Get the active connection for a provider matching a specific account.
- * Falls back to getConnectionByProvider when accountInfo is undefined.
- */
+/** @deprecated Use {@link getActiveConnection} instead. */
+export function getConnectionByProvider(
+  providerKey: string,
+  clientId?: string,
+): OAuthConnectionRow | undefined {
+  return getActiveConnection(providerKey, { clientId });
+}
+
+/** @deprecated Use {@link getActiveConnection} instead. */
 export function getConnectionByProviderAndAccount(
   providerKey: string,
   accountInfo?: string,
+  clientId?: string,
 ): OAuthConnectionRow | undefined {
-  if (!accountInfo) return getConnectionByProvider(providerKey);
-
-  const db = getDb();
-  return db
-    .select()
-    .from(oauthConnections)
-    .where(
-      and(
-        eq(oauthConnections.providerKey, providerKey),
-        eq(oauthConnections.accountInfo, accountInfo),
-        eq(oauthConnections.status, "active"),
-      ),
-    )
-    .orderBy(desc(oauthConnections.createdAt), sql`rowid DESC`)
-    .limit(1)
-    .get();
+  return getActiveConnection(providerKey, { clientId, account: accountInfo });
 }
 
 /**
@@ -505,7 +557,7 @@ export function listActiveConnectionsByProvider(
 export async function isProviderConnected(
   providerKey: string,
 ): Promise<boolean> {
-  const conn = getConnectionByProvider(providerKey);
+  const conn = getActiveConnection(providerKey);
   if (!conn || conn.status !== "active") return false;
   return (
     (await getSecureKeyAsync(oauthConnectionAccessTokenPath(conn.id))) !==
@@ -623,7 +675,7 @@ export async function disconnectOAuthProvider(
 ): Promise<"disconnected" | "not-found" | "error"> {
   const conn = connectionId
     ? getConnection(connectionId)
-    : getConnectionByProvider(providerKey, clientId);
+    : getActiveConnection(providerKey, { clientId });
   if (!conn) return "not-found";
 
   // Wrap the assistant's secure-key functions into the SecureKeyBackend

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

@@ -12,7 +12,6 @@ const DEFAULT_OPTIONS = {
   providerKey: "integration:google",
   externalId: "ext-123",
   accountInfo: "user@example.com",
-  grantedScopes: ["https://www.googleapis.com/auth/gmail.readonly"],
   assistantId: "asst-abc",
   platformBaseUrl: "https://platform.example.com",
   apiKey: "test-api-key",

package/src/oauth/platform-connection.ts

@@ -24,7 +24,6 @@ export interface PlatformOAuthConnectionOptions {
   providerKey: string;
   externalId: string;
   accountInfo: string | null;
-  grantedScopes: string[];
   assistantId: string;
   platformBaseUrl: string;
   apiKey: string;
@@ -35,18 +34,27 @@ export class PlatformOAuthConnection implements OAuthConnection {
   readonly providerKey: string;
   readonly externalId: string;
   readonly accountInfo: string | null;
-  readonly grantedScopes: string[];
 
   private readonly assistantId: string;
   private readonly platformBaseUrl: string;
   private readonly apiKey: string;
 
   constructor(options: PlatformOAuthConnectionOptions) {
+    const missing: string[] = [];
+    if (!options.platformBaseUrl) missing.push("platform base URL");
+    if (!options.apiKey) missing.push("assistant API key");
+    if (!options.assistantId) missing.push("assistant ID");
+    if (missing.length > 0) {
+      throw new BackendError(
+        `Platform-managed connection for "${options.providerKey}" cannot be created: missing ${missing.join(", ")}. ` +
+          `Log in to the Vellum platform or switch to using your own OAuth app.`,
+      );
+    }
+
     this.id = options.id;
     this.providerKey = options.providerKey;
     this.externalId = options.externalId;
     this.accountInfo = options.accountInfo;
-    this.grantedScopes = options.grantedScopes;
     this.assistantId = options.assistantId;
     this.platformBaseUrl = options.platformBaseUrl.replace(/\/+$/, "");
     this.apiKey = options.apiKey;

package/src/oauth/seed-providers.ts

@@ -5,9 +5,11 @@ import { seedProviders } from "./oauth-store.js";
  *
  * These values are upserted into the `oauth_providers` SQLite table on
  * every startup. Only Vellum implementation fields (authUrl, tokenUrl,
- * tokenEndpointAuthMethod, extraParams, callbackTransport, pingUrl) are
- * overwritten on subsequent startups — user-customizable
- * fields (defaultScopes, scopePolicy, userinfoUrl, baseUrl) are only
+ * tokenEndpointAuthMethod, userinfoUrl, extraParams, callbackTransport,
+ * pingUrl, managedServiceConfigKey) and display metadata (displayName,
+ * description, dashboardUrl, clientIdPlaceholder, requiresClientSecret)
+ * are overwritten on subsequent startups — user-customizable
+ * fields (defaultScopes, scopePolicy, baseUrl) are only
  * written on initial insert and preserved across restarts.
  *
  * Code-side behavioral fields (identityVerifier, injectionTemplates,
@@ -32,6 +34,12 @@ const PROVIDER_SEED_DATA: Record<
     };
     extraParams?: Record<string, string>;
     callbackTransport?: string;
+    managedServiceConfigKey?: string;
+    displayName: string;
+    description: string;
+    dashboardUrl: string | null;
+    clientIdPlaceholder: string | null;
+    requiresClientSecret?: boolean;
   }
 > = {
   "integration:google": {
@@ -41,6 +49,10 @@ const PROVIDER_SEED_DATA: Record<
     userinfoUrl: "https://www.googleapis.com/oauth2/v2/userinfo",
     pingUrl: "https://www.googleapis.com/oauth2/v2/userinfo",
     baseUrl: "https://gmail.googleapis.com/gmail/v1/users/me",
+    displayName: "Google",
+    description: "Gmail, Calendar, and Contacts",
+    dashboardUrl: "https://console.cloud.google.com/apis/credentials",
+    clientIdPlaceholder: "123456789.apps.googleusercontent.com",
     defaultScopes: [
       "https://www.googleapis.com/auth/gmail.readonly",
       "https://www.googleapis.com/auth/gmail.modify",
@@ -60,6 +72,7 @@ const PROVIDER_SEED_DATA: Record<
     },
     extraParams: { access_type: "offline", prompt: "consent" },
     callbackTransport: "loopback",
+    managedServiceConfigKey: "google-oauth",
   },
 
   "integration:slack": {
@@ -68,6 +81,10 @@ const PROVIDER_SEED_DATA: Record<
     tokenUrl: "https://slack.com/api/oauth.v2.access",
     pingUrl: "https://slack.com/api/auth.test",
     baseUrl: "https://slack.com/api",
+    displayName: "Slack",
+    description: "Workspace messaging",
+    dashboardUrl: "https://api.slack.com/apps",
+    clientIdPlaceholder: null,
     defaultScopes: [
       "channels:read",
       "channels:history",
@@ -101,6 +118,10 @@ const PROVIDER_SEED_DATA: Record<
     tokenUrl: "https://api.notion.com/v1/oauth/token",
     pingUrl: "https://api.notion.com/v1/users/me",
     baseUrl: "https://api.notion.com",
+    displayName: "Notion",
+    description: "Pages and databases",
+    dashboardUrl: "https://www.notion.so/my-integrations",
+    clientIdPlaceholder: null,
     defaultScopes: [],
     scopePolicy: {
       allowAdditionalScopes: false,
@@ -118,6 +139,10 @@ const PROVIDER_SEED_DATA: Record<
     tokenUrl: "https://api.x.com/2/oauth2/token",
     pingUrl: "https://api.x.com/2/users/me",
     baseUrl: "https://api.x.com",
+    displayName: "Twitter",
+    description: "Posts and direct messages",
+    dashboardUrl: "https://developer.twitter.com/en/portal/dashboard",
+    clientIdPlaceholder: null,
     defaultScopes: [
       "tweet.read",
       "tweet.write",
@@ -139,6 +164,10 @@ const PROVIDER_SEED_DATA: Record<
     tokenUrl: "https://github.com/login/oauth/access_token",
     pingUrl: "https://api.github.com/user",
     baseUrl: "https://api.github.com",
+    displayName: "GitHub",
+    description: "Repositories and issues",
+    dashboardUrl: "https://github.com/settings/developers",
+    clientIdPlaceholder: null,
     defaultScopes: ["repo", "read:user", "notifications"],
     scopePolicy: {
       allowAdditionalScopes: true,
@@ -159,6 +188,10 @@ const PROVIDER_SEED_DATA: Record<
     tokenUrl: "https://api.linear.app/oauth/token",
     pingUrl: "https://api.linear.app/graphql",
     baseUrl: "https://api.linear.app",
+    displayName: "Linear",
+    description: "Issues and projects",
+    dashboardUrl: "https://linear.app/settings/api",
+    clientIdPlaceholder: null,
     defaultScopes: ["read", "write", "issues:create"],
     scopePolicy: {
       allowAdditionalScopes: false,
@@ -175,6 +208,10 @@ const PROVIDER_SEED_DATA: Record<
     tokenUrl: "https://accounts.spotify.com/api/token",
     pingUrl: "https://api.spotify.com/v1/me",
     baseUrl: "https://api.spotify.com/v1",
+    displayName: "Spotify",
+    description: "Music and playlists",
+    dashboardUrl: "https://developer.spotify.com/dashboard",
+    clientIdPlaceholder: null,
     defaultScopes: [
       "user-read-playback-state",
       "user-modify-playback-state",
@@ -201,6 +238,10 @@ const PROVIDER_SEED_DATA: Record<
     tokenUrl: "https://todoist.com/oauth/access_token",
     pingUrl: "https://api.todoist.com/rest/v2/projects",
     baseUrl: "https://api.todoist.com/rest/v2",
+    displayName: "Todoist",
+    description: "Tasks and projects",
+    dashboardUrl: "https://developer.todoist.com/appconsole.html",
+    clientIdPlaceholder: null,
     defaultScopes: ["data:read_write"],
     scopePolicy: {
       allowAdditionalScopes: false,
@@ -216,6 +257,10 @@ const PROVIDER_SEED_DATA: Record<
     tokenUrl: "https://discord.com/api/v10/oauth2/token",
     pingUrl: "https://discord.com/api/v10/users/@me",
     baseUrl: "https://discord.com/api/v10",
+    displayName: "Discord",
+    description: "Servers and messages",
+    dashboardUrl: "https://discord.com/developers/applications",
+    clientIdPlaceholder: null,
     defaultScopes: [
       "identify",
       "guilds",
@@ -236,6 +281,10 @@ const PROVIDER_SEED_DATA: Record<
     tokenUrl: "https://api.dropboxapi.com/oauth2/token",
     pingUrl: "https://api.dropboxapi.com/2/users/get_current_account",
     baseUrl: "https://api.dropboxapi.com/2",
+    displayName: "Dropbox",
+    description: "Files and folders",
+    dashboardUrl: "https://www.dropbox.com/developers/apps",
+    clientIdPlaceholder: null,
     defaultScopes: [
       "files.metadata.read",
       "files.content.read",
@@ -257,6 +306,10 @@ const PROVIDER_SEED_DATA: Record<
     tokenUrl: "https://app.asana.com/-/oauth_token",
     pingUrl: "https://app.asana.com/api/1.0/users/me",
     baseUrl: "https://app.asana.com/api/1.0",
+    displayName: "Asana",
+    description: "Tasks and projects",
+    dashboardUrl: "https://app.asana.com/0/my-apps",
+    clientIdPlaceholder: null,
     defaultScopes: ["default"],
     scopePolicy: {
       allowAdditionalScopes: false,
@@ -272,6 +325,10 @@ const PROVIDER_SEED_DATA: Record<
     tokenUrl: "https://airtable.com/oauth2/v1/token",
     pingUrl: "https://api.airtable.com/v0/meta/whoami",
     baseUrl: "https://api.airtable.com/v0",
+    displayName: "Airtable",
+    description: "Bases and records",
+    dashboardUrl: "https://airtable.com/create/tokens",
+    clientIdPlaceholder: null,
     defaultScopes: [
       "data.records:read",
       "data.records:write",
@@ -292,6 +349,10 @@ const PROVIDER_SEED_DATA: Record<
     tokenUrl: "https://api.hubapi.com/oauth/v1/token",
     pingUrl: "https://api.hubapi.com/crm/v3/objects/contacts?limit=1",
     baseUrl: "https://api.hubapi.com",
+    displayName: "HubSpot",
+    description: "CRM contacts and deals",
+    dashboardUrl: "https://developers.hubspot.com/",
+    clientIdPlaceholder: null,
     defaultScopes: [
       "crm.objects.contacts.read",
       "crm.objects.contacts.write",
@@ -316,6 +377,10 @@ const PROVIDER_SEED_DATA: Record<
     tokenUrl: "https://api.figma.com/v1/oauth/token",
     pingUrl: "https://api.figma.com/v1/me",
     baseUrl: "https://api.figma.com/v1",
+    displayName: "Figma",
+    description: "Design files and comments",
+    dashboardUrl: "https://www.figma.com/developers/apps",
+    clientIdPlaceholder: null,
     defaultScopes: ["files:read", "file_comments:write"],
     scopePolicy: {
       allowAdditionalScopes: false,
@@ -335,6 +400,11 @@ const PROVIDER_SEED_DATA: Record<
     tokenUrl: "urn:manual-token",
     pingUrl: "https://slack.com/api/auth.test",
     baseUrl: "https://slack.com/api",
+    displayName: "Slack Channel",
+    description: "Channel bot token",
+    dashboardUrl: null,
+    clientIdPlaceholder: null,
+    requiresClientSecret: false,
     defaultScopes: [],
     scopePolicy: {
       allowAdditionalScopes: false,
@@ -348,6 +418,11 @@ const PROVIDER_SEED_DATA: Record<
     authUrl: "urn:manual-token",
     tokenUrl: "urn:manual-token",
     baseUrl: "https://api.telegram.org",
+    displayName: "Telegram",
+    description: "Bot messaging",
+    dashboardUrl: null,
+    clientIdPlaceholder: null,
+    requiresClientSecret: false,
     defaultScopes: [],
     scopePolicy: {
       allowAdditionalScopes: false,

package/src/oauth/token-persistence.ts

@@ -28,9 +28,8 @@ import {
 import { runPostConnectHook } from "../tools/credentials/post-connect-hooks.js";
 import {
   createConnection,
+  getActiveConnection,
   getApp,
-  getConnectionByProvider,
-  getConnectionByProviderAndAccount,
   listActiveConnectionsByProvider,
   updateConnection,
   upsertApp,
@@ -59,8 +58,12 @@ export interface StoreOAuth2TokensParams {
   clientId: string;
   clientSecret?: string;
   userinfoUrl?: string;
-  /** Fallback account info from an identity verifier (e.g. @username, email). */
-  identityAccountInfo?: string;
+  /**
+   * Best-effort account identifier parsed from the provider's identity
+   * endpoint (e.g. email, @username, display name). The format varies by
+   * provider and may be undefined if the API call fails.
+   */
+  parsedAccountIdentifier?: string;
   /** Pre-resolved oauth_app ID — skips the upsertApp() call if provided. */
   oauthAppId?: string;
 }
@@ -94,6 +97,10 @@ export async function storeOAuth2Tokens(
     ? Date.now() + tokens.expiresIn * 1000
     : null;
 
+  // Account identifier parsing is best-effort. The format varies by provider
+  // (email for Google, username for GitHub, display name for Spotify, etc.)
+  // and may be undefined if the userinfo/identity API call fails or the
+  // required scope wasn't granted.
   let accountInfo: string | undefined;
   if (userinfoUrl && grantedScopes.some((s) => s.includes("userinfo"))) {
     try {
@@ -109,7 +116,7 @@ export async function storeOAuth2Tokens(
     }
   }
 
-  const resolvedAccountInfo = accountInfo ?? params.identityAccountInfo;
+  const resolvedAccountInfo = accountInfo ?? params.parsedAccountIdentifier;
 
   // -------------------------------------------------------------------
   // SQLite oauth_app + oauth_connection + new-format secure keys
@@ -144,12 +151,11 @@ export async function storeOAuth2Tokens(
   //    lookup so that re-auth without userinfo still updates the right row.
   //    However, treat provider-only matches as ambiguous when multiple active
   //    connections exist to avoid overwriting the wrong account's tokens.
-  let existingConn: ReturnType<typeof getConnectionByProvider>;
+  let existingConn: ReturnType<typeof getActiveConnection>;
   if (resolvedAccountInfo) {
-    existingConn = getConnectionByProviderAndAccount(
-      service,
-      resolvedAccountInfo,
-    );
+    existingConn = getActiveConnection(service, {
+      account: resolvedAccountInfo,
+    });
   } else {
     const activeConns = listActiveConnectionsByProvider(service);
     // Only reuse the provider-only match when it's unambiguous (single connection).