@vellumai/assistant 0.12.0 → 0.12.1-dev.202609142113.d1590bc

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

@@ -308,6 +308,66 @@ describe("BYOOAuthConnection", () => {
       expect((init as RequestInit).method).toBe("GET");
     });
 
+    test("follows a cross-origin redirect without the credential and returns the target's bytes", async () => {
+      // Real fetch against two loopback origins: the credential goes to the
+      // host the caller named, the redirect target sees no Authorization,
+      // and the target's bytes come back as the response body. This is the
+      // path a Slack file download takes when files.slack.com answers with a
+      // 302 to its CDN.
+      globalThis.fetch = originalFetch;
+      await setupCredential("google");
+      const bytes = Buffer.from([
+        0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
+      ]);
+      const seen: { origin?: string | null; target?: string | null } = {};
+
+      const target = Bun.serve({
+        port: 0,
+        hostname: "127.0.0.1",
+        fetch: (req) => {
+          seen.target = req.headers.get("authorization");
+          return new Response(bytes, {
+            status: 200,
+            headers: { "content-type": "image/png" },
+          });
+        },
+      });
+      const origin = Bun.serve({
+        port: 0,
+        hostname: "127.0.0.1",
+        fetch: (req) => {
+          seen.origin = req.headers.get("authorization");
+          return new Response(null, {
+            status: 302,
+            headers: { Location: `http://127.0.0.1:${target.port}/signed` },
+          });
+        },
+      });
+
+      try {
+        const conn = new BYOOAuthConnection({
+          id: "conn-google",
+          provider: "google",
+          baseUrl: `http://127.0.0.1:${origin.port}`,
+          accountInfo: null,
+        });
+
+        const result = await conn.request({
+          method: "GET",
+          path: "/files-pri/T0123-F0456/download/shot.png",
+        });
+
+        expect(seen.origin).toBe("Bearer test-access-token");
+        expect(seen.target).toBeNull();
+        expect(result.status).toBe(200);
+        expect(Buffer.isBuffer(result.body)).toBe(true);
+        expect(Buffer.from(result.body as Buffer).equals(bytes)).toBe(true);
+      } finally {
+        origin.stop(true);
+        target.stop(true);
+      }
+    });
+
     test("appends query parameters", async () => {
       await setupCredential("google");
       const conn = createConnection();
@@ -708,6 +768,51 @@ describe("BYOOAuthConnection", () => {
       expect(headers.get("Authorization")).toBe("Bearer test-access-token");
     });
 
+    test("sends the token in the provider's own header when one is configured", async () => {
+      // Shopify's Admin API reads X-Shopify-Access-Token and ignores
+      // Authorization, so a Bearer header reaches the shop unauthenticated.
+      await setupCredential("google");
+      const conn = new BYOOAuthConnection({
+        id: "conn-google",
+        provider: "google",
+        baseUrl: "https://example-store.myshopify.com",
+        accountInfo: null,
+        tokenHeader: { name: "X-Shopify-Access-Token", valuePrefix: "" },
+      });
+
+      await conn.request({
+        method: "GET",
+        path: "/admin/api/2026-07/shop.json",
+        // A caller-supplied Authorization must not ride along.
+        headers: { Authorization: "Bearer caller-supplied" },
+      });
+
+      const [url, init] = mockFetch.mock.calls[0];
+      expect(url).toBe(
+        "https://example-store.myshopify.com/admin/api/2026-07/shop.json",
+      );
+      const headers = (init as RequestInit).headers as Headers;
+      expect(headers.get("X-Shopify-Access-Token")).toBe("test-access-token");
+      expect(headers.has("Authorization")).toBe(false);
+    });
+
+    test("keeps the value prefix from the token header template", async () => {
+      await setupCredential("google");
+      const conn = new BYOOAuthConnection({
+        id: "conn-google",
+        provider: "google",
+        baseUrl: "https://discord.com/api",
+        accountInfo: null,
+        tokenHeader: { name: "Authorization", valuePrefix: "Bot " },
+      });
+
+      await conn.request({ method: "GET", path: "/users/@me" });
+
+      const [, init] = mockFetch.mock.calls[0];
+      const headers = (init as RequestInit).headers as Headers;
+      expect(headers.get("Authorization")).toBe("Bot test-access-token");
+    });
+
     test("uses Telegram Bot API token URL format without Bearer auth", async () => {
       await setupTelegramCredential();
       const conn = createConnection("telegram");

package/src/oauth/byo-connection.ts

@@ -21,11 +21,29 @@ const log = getLogger("byo-oauth-connection");
 /** Default per-request timeout to prevent hung requests from blocking indefinitely. */
 const REQUEST_TIMEOUT_MS = 30_000;
 
+/**
+ * How the access token is attached to an outbound request. Almost every
+ * provider reads `Authorization: Bearer <token>`; a few use their own header
+ * (Shopify's Admin API reads `X-Shopify-Access-Token` and ignores
+ * Authorization entirely). Derived from the provider's header-type injection
+ * template so the seed is the single source of truth.
+ */
+export interface BYOTokenHeader {
+  name: string;
+  /** Text placed before the token, e.g. `"Bearer "`, `"Bot "`, or `""`. */
+  valuePrefix: string;
+}
+
 export interface BYOOAuthConnectionOptions {
   id: string;
   provider: string;
   baseUrl: string;
   accountInfo: string | null;
+  /**
+   * Token header override. When omitted the connection falls back to
+   * `Authorization: Bearer` (or `Bot` for discord_channel).
+   */
+  tokenHeader?: BYOTokenHeader | null;
 }
 
 export class BYOOAuthConnection implements OAuthConnection {
@@ -34,12 +52,14 @@ export class BYOOAuthConnection implements OAuthConnection {
   readonly accountInfo: string | null;
 
   private readonly baseUrl: string;
+  private readonly tokenHeader: BYOTokenHeader | null;
 
   constructor(opts: BYOOAuthConnectionOptions) {
     this.id = opts.id;
     this.provider = opts.provider;
     this.baseUrl = opts.baseUrl;
     this.accountInfo = opts.accountInfo;
+    this.tokenHeader = opts.tokenHeader ?? null;
   }
 
   async request(req: OAuthConnectionRequest): Promise<OAuthConnectionResponse> {
@@ -51,8 +71,12 @@ export class BYOOAuthConnection implements OAuthConnection {
         // Discord bot tokens authenticate with the `Bot ` scheme, not
         // `Bearer`. Sending Bearer here reaches Discord as an unusable
         // credential and comes back 401, which reads as a revoked token.
-        const authScheme =
-          this.provider === "discord_channel" ? "Bot" : "Bearer";
+        // Providers with their own token header (Shopify) override the
+        // whole thing via `tokenHeader`.
+        const tokenHeader: BYOTokenHeader = this.tokenHeader ?? {
+          name: "Authorization",
+          valuePrefix: this.provider === "discord_channel" ? "Bot " : "Bearer ",
+        };
         const requestPath = isTelegram
           ? buildTelegramBotApiPath(req.path, token)
           : req.path;
@@ -93,16 +117,22 @@ export class BYOOAuthConnection implements OAuthConnection {
           }
         }
         if (!isTelegram) {
-          headers.set("Authorization", `${authScheme} ${token}`);
+          // The credential always wins over a caller-supplied value, and a
+          // provider that reads its own header must not also receive a
+          // stray Authorization the caller happened to send.
+          if (tokenHeader.name.toLowerCase() !== "authorization") {
+            headers.delete("Authorization");
+          }
+          headers.set(tokenHeader.name, `${tokenHeader.valuePrefix}${token}`);
         }
 
         const resp = await fetch(fullUrl, {
           method: req.method,
           headers,
           body: hasBody
-            ? (binaryBody !== undefined
-                ? Buffer.from(binaryBody)
-                : (rawBody ?? JSON.stringify(req.body)))
+            ? binaryBody !== undefined
+              ? Buffer.from(binaryBody)
+              : (rawBody ?? JSON.stringify(req.body))
             : undefined,
           // Following a redirect would replay a POST as a GET against a URL
           // the caller never asked for, and hide the 3xx from them.

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

@@ -75,6 +75,7 @@ import {
   resolveEffectiveBaseUrl,
   resolveOAuthConnection,
   resolveOAuthConnectionWithMeta,
+  resolveTokenHeader,
 } from "./connection-resolver.js";
 import { PlatformOAuthConnection } from "./platform-connection.js";
 
@@ -753,3 +754,75 @@ describe("resolveEffectiveBaseUrl", () => {
     ).toBe("https://gmail.googleapis.com/gmail/v1/users/me");
   });
 });
+
+describe("resolveTokenHeader", () => {
+  const shopify = JSON.stringify([
+    {
+      hostPattern: "*.myshopify.com",
+      injectionType: "header",
+      headerName: "X-Shopify-Access-Token",
+      valuePrefix: "",
+    },
+  ]);
+
+  test("returns null when the provider declares no templates", () => {
+    expect(resolveTokenHeader(undefined, "https://api.example.com")).toBeNull();
+    expect(resolveTokenHeader(null, "https://api.example.com")).toBeNull();
+    expect(resolveTokenHeader("[]", "https://api.example.com")).toBeNull();
+  });
+
+  test("returns null for malformed JSON", () => {
+    expect(
+      resolveTokenHeader("{not json", "https://api.example.com"),
+    ).toBeNull();
+  });
+
+  test("ignores non-header injection templates", () => {
+    const query = JSON.stringify([
+      {
+        hostPattern: "api.example.com",
+        injectionType: "query",
+        headerName: "",
+      },
+    ]);
+    expect(resolveTokenHeader(query, "https://api.example.com")).toBeNull();
+  });
+
+  test("picks the template whose wildcard host pattern matches the base URL", () => {
+    const templates = JSON.stringify([
+      {
+        hostPattern: "api.other.com",
+        injectionType: "header",
+        headerName: "Authorization",
+        valuePrefix: "Bearer ",
+      },
+      ...JSON.parse(shopify),
+    ]);
+    expect(
+      resolveTokenHeader(templates, "https://example-store.myshopify.com"),
+    ).toEqual({ name: "X-Shopify-Access-Token", valuePrefix: "" });
+  });
+
+  test("falls back to the first header template when the host cannot be matched", () => {
+    // A still-templated base URL is not a parseable URL.
+    expect(resolveTokenHeader(shopify, "https://{tenant_host}")).toEqual({
+      name: "X-Shopify-Access-Token",
+      valuePrefix: "",
+    });
+  });
+
+  test("preserves the Bot prefix for discord_channel", () => {
+    const discord = JSON.stringify([
+      {
+        hostPattern: "discord.com",
+        injectionType: "header",
+        headerName: "Authorization",
+        valuePrefix: "Bot ",
+      },
+    ]);
+    expect(resolveTokenHeader(discord, "https://discord.com/api")).toEqual({
+      name: "Authorization",
+      valuePrefix: "Bot ",
+    });
+  });
+});

package/src/oauth/connection-resolver.ts

@@ -6,7 +6,7 @@ import {
 } from "../config/schemas/services.js";
 import { VellumPlatformClient } from "../platform/client.js";
 import { getLogger } from "../util/logger.js";
-import { BYOOAuthConnection } from "./byo-connection.js";
+import { BYOOAuthConnection, type BYOTokenHeader } from "./byo-connection.js";
 import type { OAuthConnection } from "./connection.js";
 import { getConnectionAccessTokenResult } from "./credential-token-resolver.js";
 import { syncManualTokenConnection } from "./manual-token-connection.js";
@@ -215,15 +215,108 @@ export async function resolveOAuthConnectionWithMeta(
     );
   }
 
+  const effectiveBaseUrl = resolveEffectiveBaseUrl(
+    conn.provider,
+    baseUrl,
+    conn.metadata,
+  );
   const connection = new BYOOAuthConnection({
     id: conn.id,
     provider: conn.provider,
-    baseUrl: resolveEffectiveBaseUrl(conn.provider, baseUrl, conn.metadata),
+    baseUrl: effectiveBaseUrl,
     accountInfo: conn.accountInfo,
+    tokenHeader: resolveTokenHeader(
+      providerRow?.injectionTemplates,
+      effectiveBaseUrl,
+    ),
   });
   return { connection, ambiguous, allAccounts };
 }
 
+/**
+ * Pick the header a provider expects its access token in from the seed's
+ * header-type injection templates.
+ *
+ * Prefers the template whose `hostPattern` matches the base URL's host
+ * (`*.myshopify.com` style globs included), then falls back to the first
+ * header template. Returns `null` when the provider declares none, which
+ * leaves `BYOOAuthConnection` on its `Authorization: Bearer` default.
+ *
+ * Shopify is why this exists: its Admin API reads `X-Shopify-Access-Token`
+ * and ignores `Authorization`, so a Bearer header reaches the shop as an
+ * unauthenticated request and comes back 401.
+ */
+export function resolveTokenHeader(
+  rawTemplates: string | null | undefined,
+  baseUrl: string,
+): BYOTokenHeader | null {
+  if (!rawTemplates) {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(rawTemplates);
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(parsed)) {
+    return null;
+  }
+
+  const headerTemplates = parsed.filter(
+    (
+      t,
+    ): t is {
+      hostPattern?: unknown;
+      headerName: string;
+      valuePrefix?: unknown;
+    } =>
+      typeof t === "object" &&
+      t !== null &&
+      (t as { injectionType?: unknown }).injectionType === "header" &&
+      typeof (t as { headerName?: unknown }).headerName === "string" &&
+      (t as { headerName: string }).headerName.trim() !== "",
+  );
+  if (headerTemplates.length === 0) {
+    return null;
+  }
+
+  let host = "";
+  try {
+    host = new URL(baseUrl).hostname.toLowerCase();
+  } catch {
+    // Templated or malformed base URLs (e.g. a still-unfilled
+    // `https://{tenant_host}`) cannot be matched by host; fall through to
+    // the first header template.
+  }
+  const matching =
+    host === ""
+      ? undefined
+      : headerTemplates.find(
+          (t) =>
+            typeof t.hostPattern === "string" &&
+            hostMatchesPattern(host, t.hostPattern),
+        );
+  const chosen = matching ?? headerTemplates[0];
+  return {
+    name: chosen.headerName.trim(),
+    valuePrefix:
+      typeof chosen.valuePrefix === "string" ? chosen.valuePrefix : "",
+  };
+}
+
+function hostMatchesPattern(host: string, pattern: string): boolean {
+  const p = pattern.trim().toLowerCase();
+  if (p === "") {
+    return false;
+  }
+  if (p.startsWith("*.")) {
+    const suffix = p.slice(1); // ".myshopify.com"
+    return host.endsWith(suffix) && host.length > suffix.length;
+  }
+  return host === p;
+}
+
 /**
  * Resolve the effective API base URL for a connection, preferring per-tenant
  * values stored on the connection's `metadata` over the provider's static

package/src/oauth/scope-utils.ts

@@ -72,6 +72,30 @@ export function expectedScopesForStoredToken(
   return parsed.length > 0 ? parsed : defaultScopes;
 }
 
+/**
+ * The required scopes a stored grant lacks. Requirements come from the request
+ * that produced the stored token ({@link expectedScopesForStoredToken}), so a
+ * provider's bot-only scopes are never demanded of a user token. An empty
+ * requirement or an unrecorded grant reports nothing, because unknown scope
+ * data must never read as a failure.
+ */
+export function missingScopesForStoredToken(
+  defaultScopes: string[],
+  authorizeParams: Record<string, string> | undefined,
+  scopeSeparator: string | undefined,
+  grantedScopes: string[],
+): string[] {
+  const expected = expectedScopesForStoredToken(
+    defaultScopes,
+    authorizeParams,
+    scopeSeparator,
+  );
+  if (expected.length === 0 || grantedScopes.length === 0) {
+    return [];
+  }
+  return scopeDifference(expected, grantedScopes);
+}
+
 const GMAIL_FULL_ACCESS_SCOPE = "https://mail.google.com/";
 const GMAIL_READONLY_SCOPE = "https://www.googleapis.com/auth/gmail.readonly";