@vercel/connect 0.0.4-alpha.2

package/dist/ash/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Public surface of the `@vercel/connect/ash` subpath.
+ *
+ * Holds Ash-specific helpers that adapt the Vercel Connect SDK to
+ * Ash's connection runtime. Each helper lives in its own module;
+ * this barrel re-exports the public API so consumers import
+ * everything from `@vercel/connect/ash`.
+ */
+export { connect, type AshAuthorizationInput, type AshAuthorizationOptions, type ConnectAuthorizationPhase, type ConnectAuthorizationState, } from "./connection-authorization.js";
+export { connectSlackCredentials } from "./slack-credentials.js";

package/dist/ash/index.js

@@ -0,0 +1,10 @@
+/**
+ * Public surface of the `@vercel/connect/ash` subpath.
+ *
+ * Holds Ash-specific helpers that adapt the Vercel Connect SDK to
+ * Ash's connection runtime. Each helper lives in its own module;
+ * this barrel re-exports the public API so consumers import
+ * everything from `@vercel/connect/ash`.
+ */
+export { connect, } from "./connection-authorization.js";
+export { connectSlackCredentials } from "./slack-credentials.js";

package/dist/ash/slack-credentials.d.ts

@@ -0,0 +1,25 @@
+import type { SlackChannelCredentials } from "experimental-ash/channels/slack";
+/**
+ * Build {@link SlackChannelCredentials} backed by a Vercel Connect
+ * connector that stores a Slack workspace's bot token.
+ *
+ * The returned `botToken` is a function form, invoked once per
+ * inbound webhook so the chat adapter always picks up a fresh token
+ * from Vercel Connect (rotation, refresh, multi-workspace tenancy
+ * are all handled server-side).
+ *
+ * Slack bot tokens are app-scoped — one token per workspace install,
+ * shared across every end-user — so this helper calls Vercel Connect
+ * with `subject: { type: "app" }`. End-user identity (per-user OAuth
+ * into Slack) is a separate concern handled elsewhere.
+ *
+ * ```ts
+ * import { slackRoute } from "experimental-ash/channels/slack";
+ * import { connectSlackCredentials } from "@vercel/connect/ash";
+ *
+ * export default slackRoute({
+ *   credentials: connectSlackCredentials("scl_..."),
+ * });
+ * ```
+ */
+export declare function connectSlackCredentials(connector: string): SlackChannelCredentials;

package/dist/ash/slack-credentials.js

@@ -0,0 +1,31 @@
+import { getToken } from "../index.js";
+import { vercelOidc } from "experimental-ash/channels/auth";
+/**
+ * Build {@link SlackChannelCredentials} backed by a Vercel Connect
+ * connector that stores a Slack workspace's bot token.
+ *
+ * The returned `botToken` is a function form, invoked once per
+ * inbound webhook so the chat adapter always picks up a fresh token
+ * from Vercel Connect (rotation, refresh, multi-workspace tenancy
+ * are all handled server-side).
+ *
+ * Slack bot tokens are app-scoped — one token per workspace install,
+ * shared across every end-user — so this helper calls Vercel Connect
+ * with `subject: { type: "app" }`. End-user identity (per-user OAuth
+ * into Slack) is a separate concern handled elsewhere.
+ *
+ * ```ts
+ * import { slackRoute } from "experimental-ash/channels/slack";
+ * import { connectSlackCredentials } from "@vercel/connect/ash";
+ *
+ * export default slackRoute({
+ *   credentials: connectSlackCredentials("scl_..."),
+ * });
+ * ```
+ */
+export function connectSlackCredentials(connector) {
+    return {
+        botToken: () => getToken(connector, { subject: { type: "app" } }),
+        webhookVerifier: vercelOidc(),
+    };
+}

package/dist/authjs/connect-provider.d.ts

@@ -0,0 +1,43 @@
+import type { OAuth2Config } from "@auth/core/providers";
+/** Userinfo payload returned by Vercel Connect's OIDC userinfo endpoint. */
+export interface ConnectProfile {
+    sub: string;
+    email?: string;
+    email_verified?: boolean;
+    name?: string;
+    picture?: string;
+}
+/** Options accepted by {@link connect}. */
+export interface AuthJsConnectOptions {
+    /**
+     * Provider id surfaced by Auth.js (e.g. `"slack-via-connect"`).
+     * Becomes the path segment in callback URLs and the `provider`
+     * field on accounts.
+     */
+    readonly id: string;
+    /** Human-readable display name used by Auth.js sign-in UIs. */
+    readonly name: string;
+    /**
+     * Vercel Connect OAuth connector identifier. Accepts either the
+     * opaque service connector key (`scl_...`) or the human-readable
+     * UID (`oauth/mcp-linear-app`).
+     */
+    readonly connector: string;
+    /**
+     * Scopes to request. `offline_access` is added automatically so
+     * the Vercel Connect side can mint refresh tokens. Defaults to
+     * `["*"]`.
+     */
+    readonly scopes?: readonly string[];
+    /**
+     * Override the Vercel OIDC token fetcher. Defaults to
+     * {@link getVercelOidcToken} from `@vercel/oidc`. Useful for tests
+     * or non-Vercel runtimes that mint the OIDC token differently.
+     */
+    readonly getVercelOidcToken?: () => Promise<string>;
+}
+/**
+ * Builds an Auth.js `OAuth2Config` for Vercel Connect. Push the
+ * result into `AuthConfig.providers`.
+ */
+export declare function connect(options: AuthJsConnectOptions): OAuth2Config<ConnectProfile>;

package/dist/authjs/connect-provider.js

@@ -0,0 +1,95 @@
+/**
+ * Auth.js (NextAuth core) adapter helper for `@vercel/connect`.
+ *
+ * {@link connect} returns an `OAuth2Config` provider entry for use
+ * in `AuthConfig.providers`. Vercel Connect's OAuth client
+ * authentication is non-standard — the "client secret" is a
+ * per-request Vercel OIDC token — so we declare
+ * `token_endpoint_auth_method: "none"` and inject the real
+ * Authorization headers via the `customFetch` symbol.
+ *
+ * ```ts
+ * import type { AuthConfig } from "@auth/core";
+ * import { connect } from "@vercel/connect/authjs";
+ *
+ * export const authConfig: AuthConfig = {
+ *   providers: [
+ *     connect({
+ *       id: "slack",
+ *       name: "Slack",
+ *       connector: process.env.CONNECTOR_SLACK!,
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+import { customFetch } from "@auth/core";
+import { getVercelOidcToken } from "@vercel/oidc";
+import { tryGetVercelTeamId, withTeamId } from "../internal/team-id.js";
+const CONNECT_AUTHORIZATION_URL = "https://vercel.com/api/connex/oauth/authorize";
+const CONNECT_TOKEN_URL = "https://vercel.com/api/connex/oauth/token";
+const CONNECT_USERINFO_URL = "https://vercel.com/api/connex/oauth/userinfo";
+/**
+ * Builds an Auth.js `OAuth2Config` for Vercel Connect. Push the
+ * result into `AuthConfig.providers`.
+ */
+export function connect(options) {
+    const fetchVercelToken = options.getVercelOidcToken ?? getVercelOidcToken;
+    const scope = Array.from(new Set([...(options.scopes ?? ["*"]), "offline_access"])).join(" ");
+    return {
+        id: options.id,
+        name: options.name,
+        type: "oauth",
+        clientId: options.connector,
+        // The token endpoint expects client_secret_basic, but the secret
+        // is a Vercel OIDC token that has to be fetched per-request. We
+        // rely on the customFetch hook below to inject the real
+        // Authorization header — Auth.js skips building one because we
+        // declared "none" here.
+        client: { token_endpoint_auth_method: "none" },
+        authorization: {
+            // Best-effort: scope the Vercel Connect consent UI to the
+            // deployment's Vercel team when we can read it from the OIDC
+            // token. Falls back to the unqualified URL when the token isn't
+            // present (e.g. running outside Vercel).
+            url: withTeamId(CONNECT_AUTHORIZATION_URL, tryGetVercelTeamId()),
+            params: { scope },
+        },
+        token: CONNECT_TOKEN_URL,
+        userinfo: CONNECT_USERINFO_URL,
+        checks: ["pkce"],
+        profile(profile) {
+            return {
+                id: profile.sub,
+                name: profile.name,
+                email: profile.email ?? null,
+                image: profile.picture,
+            };
+        },
+        [customFetch]: async (input, init) => {
+            const url = typeof input === "string"
+                ? input
+                : input instanceof URL
+                    ? input.href
+                    : input.url;
+            if (url.startsWith(CONNECT_TOKEN_URL)) {
+                const vercelToken = await fetchVercelToken();
+                const credentials = `${encodeURIComponent(options.connector)}:${encodeURIComponent(vercelToken)}`;
+                const headers = new Headers(init?.headers);
+                headers.set("authorization", `Basic ${btoa(credentials)}`);
+                return fetch(input, { ...init, headers });
+            }
+            if (url.startsWith(CONNECT_USERINFO_URL)) {
+                const headers = new Headers(init?.headers);
+                const accessToken = (headers.get("authorization") ?? "").replace(/^Bearer\s+/i, "");
+                const vercelToken = await fetchVercelToken();
+                const triple = [options.connector, vercelToken, accessToken]
+                    .map(encodeURIComponent)
+                    .join(":");
+                headers.set("authorization", `Bearer ${btoa(triple)}`);
+                return fetch(input, { ...init, headers });
+            }
+            return fetch(input, init);
+        },
+    };
+}

package/dist/authjs/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Public surface of the `@vercel/connect/authjs` subpath.
+ *
+ * Holds Auth.js (NextAuth core) helpers for adapting Vercel Connect
+ * to the `OAuth2Config` provider shape. `@auth/core` is an optional
+ * peer dependency: importing this entrypoint requires it to be
+ * installed in the consumer project, but the rest of
+ * `@vercel/connect` works without it.
+ */
+export { connect, type AuthJsConnectOptions, type ConnectProfile, } from "./connect-provider.js";

package/dist/authjs/index.js

@@ -0,0 +1,10 @@
+/**
+ * Public surface of the `@vercel/connect/authjs` subpath.
+ *
+ * Holds Auth.js (NextAuth core) helpers for adapting Vercel Connect
+ * to the `OAuth2Config` provider shape. `@auth/core` is an optional
+ * peer dependency: importing this entrypoint requires it to be
+ * installed in the consumer project, but the rest of
+ * `@vercel/connect` works without it.
+ */
+export { connect, } from "./connect-provider.js";

package/dist/authorization.d.ts

@@ -0,0 +1,12 @@
+import type { ConnectTokenParams } from "./token.js";
+export interface ConnectAuthorizationOptions {
+    vercelToken?: string;
+    callbackUrl?: string;
+    webhook?: string;
+}
+export interface ConnectAuthorizationResponse {
+    request: string;
+    verifier: string;
+    url: string;
+}
+export declare function startAuthorization(connector: string, params: ConnectTokenParams, options?: ConnectAuthorizationOptions): Promise<ConnectAuthorizationResponse>;

package/dist/authorization.js

@@ -0,0 +1,68 @@
+import { getVercelOidcToken } from "@vercel/oidc";
+export async function startAuthorization(connector, params, options) {
+    if (!connector) {
+        throw new Error("connector is required");
+    }
+    if (options?.callbackUrl !== undefined) {
+        validateCallbackUrl(options.callbackUrl);
+    }
+    if (options?.webhook !== undefined) {
+        validateWebhookUrl(options.webhook);
+    }
+    const vercelToken = options?.vercelToken ?? (await getVercelOidcToken());
+    const endpoint = `https://api.vercel.com/v1/connex/authorize/${encodeURIComponent(connector)}`;
+    const body = {
+        ...params,
+        ...(options?.callbackUrl !== undefined && {
+            returnUrl: options.callbackUrl,
+        }),
+        ...(options?.webhook !== undefined && { webhook: options.webhook }),
+    };
+    const response = await fetch(endpoint, {
+        method: "POST",
+        headers: {
+            Accept: "application/json",
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${vercelToken}`,
+        },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        let errorText;
+        try {
+            errorText = await response.text();
+        }
+        catch { }
+        throw new Error(`Failed to start authorization: ${response.status} ${response.statusText}${errorText ? ` - ${errorText}` : ""}`);
+    }
+    const { request, verifier, url } = await response.json();
+    return { request, verifier, url };
+}
+function validateCallbackUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`Invalid callbackUrl: ${value}`);
+    }
+    if (url.protocol === "https:")
+        return;
+    if (url.protocol === "http:" &&
+        (url.hostname === "localhost" || url.hostname === "127.0.0.1")) {
+        return;
+    }
+    throw new Error(`callbackUrl must be https:// or http://localhost, got: ${value}`);
+}
+function validateWebhookUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`Invalid webhook URL: ${value}`);
+    }
+    if (url.protocol !== "https:") {
+        throw new Error(`webhook must be https://, got: ${value}`);
+    }
+}

package/dist/betterauth/connect-provider.d.ts

@@ -0,0 +1,32 @@
+import type { GenericOAuthConfig } from "better-auth/plugins/generic-oauth";
+/** Options accepted by {@link connect}. */
+export interface BetterAuthConnectOptions {
+    /**
+     * Provider id used by Better Auth's generic OAuth plugin (e.g.
+     * `"slack"`). Surfaces in the sign-in URL and account
+     * rows; pick something stable that names the upstream IdP.
+     */
+    readonly providerId: string;
+    /**
+     * Vercel Connect OAuth connector identifier. Accepts either the
+     * opaque service connector key (`scl_...`) or the human-readable
+     * UID (`oauth/mcp-linear-app`).
+     */
+    readonly connector: string;
+    /**
+     * Scopes to request. `offline_access` is added automatically so the
+     * Vercel Connect side can mint refresh tokens. Defaults to `["*"]`.
+     */
+    readonly scopes?: readonly string[];
+    /**
+     * Override the Vercel OIDC token fetcher. Defaults to
+     * {@link getVercelOidcToken} from `@vercel/oidc`. Useful for tests
+     * or non-Vercel runtimes that mint the OIDC token differently.
+     */
+    readonly getVercelOidcToken?: () => Promise<string>;
+}
+/**
+ * Builds a `GenericOAuthConfig` entry for Vercel Connect. Pass the
+ * result into `genericOAuth({ config: [...] })`.
+ */
+export declare function connect(options: BetterAuthConnectOptions): GenericOAuthConfig;

package/dist/betterauth/connect-provider.js

@@ -0,0 +1,107 @@
+/**
+ * Better Auth adapter helper for `@vercel/connect`.
+ *
+ * {@link connect} returns a `GenericOAuthConfig` entry that drops
+ * into `genericOAuth({ config: [...] })` from
+ * `better-auth/plugins/generic-oauth`. Vercel Connect's OAuth client
+ * authentication is non-standard — the "client secret" is a Vercel
+ * OIDC token that has to be fetched per-request — so we override
+ * `getToken` and `getUserInfo` to inject the right Authorization
+ * headers instead of relying on Better Auth's built-in flow.
+ *
+ * ```ts
+ * import { betterAuth } from "better-auth";
+ * import { genericOAuth } from "better-auth/plugins/generic-oauth";
+ * import { connect } from "@vercel/connect/betterauth";
+ *
+ * export const auth = betterAuth({
+ *   plugins: [
+ *     genericOAuth({
+ *       config: [
+ *         connect({
+ *           providerId: "slack",
+ *           connector: process.env.CONNECTOR_SLACK!,
+ *         }),
+ *       ],
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+import { getVercelOidcToken } from "@vercel/oidc";
+import { getOAuth2Tokens } from "better-auth/oauth2";
+import { tryGetVercelTeamId, withTeamId } from "../internal/team-id.js";
+const CONNECT_AUTHORIZATION_URL = "https://vercel.com/api/connex/oauth/authorize";
+const CONNECT_TOKEN_URL = "https://vercel.com/api/connex/oauth/token";
+const CONNECT_USERINFO_URL = "https://vercel.com/api/connex/oauth/userinfo";
+/**
+ * Builds a `GenericOAuthConfig` entry for Vercel Connect. Pass the
+ * result into `genericOAuth({ config: [...] })`.
+ */
+export function connect(options) {
+    const fetchVercelToken = options.getVercelOidcToken ?? getVercelOidcToken;
+    const scopes = Array.from(new Set([...(options.scopes ?? ["*"]), "offline_access"]));
+    return {
+        providerId: options.providerId,
+        clientId: options.connector,
+        // Best-effort: scope the Vercel Connect consent UI to the
+        // deployment's Vercel team when we can read it from the OIDC
+        // token. Falls back to the unqualified URL when the token isn't
+        // present (e.g. running outside Vercel).
+        authorizationUrl: withTeamId(CONNECT_AUTHORIZATION_URL, tryGetVercelTeamId()),
+        scopes,
+        pkce: true,
+        tokenUrl: CONNECT_TOKEN_URL,
+        getToken: async ({ code, redirectURI, codeVerifier, deviceId }) => {
+            const vercelToken = await fetchVercelToken();
+            const credentials = `${encodeURIComponent(options.connector)}:${encodeURIComponent(vercelToken)}`;
+            const basicAuth = btoa(credentials);
+            const body = new URLSearchParams({
+                grant_type: "authorization_code",
+                code,
+                redirect_uri: redirectURI,
+            });
+            if (codeVerifier)
+                body.set("code_verifier", codeVerifier);
+            if (deviceId)
+                body.set("device_id", deviceId);
+            const response = await fetch(CONNECT_TOKEN_URL, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    Accept: "application/json",
+                    Authorization: `Basic ${basicAuth}`,
+                },
+                body: body.toString(),
+            });
+            if (!response.ok) {
+                throw new Error(`Failed to exchange Vercel Connect authorization code: ${response.status} ${response.statusText}: ${await response.text()}`);
+            }
+            return getOAuth2Tokens(await response.json());
+        },
+        getUserInfo: async (tokens) => {
+            if (!tokens.accessToken) {
+                throw new Error("Missing access token for Vercel Connect userinfo request");
+            }
+            const vercelToken = await fetchVercelToken();
+            const triple = [options.connector, vercelToken, tokens.accessToken]
+                .map(encodeURIComponent)
+                .join(":");
+            const bearerToken = btoa(triple);
+            const response = await fetch(CONNECT_USERINFO_URL, {
+                headers: { Authorization: `Bearer ${bearerToken}` },
+            });
+            if (!response.ok) {
+                throw new Error(`Failed to fetch Vercel Connect user info: ${response.status} ${response.statusText}: ${await response.text()}`);
+            }
+            const user = (await response.json());
+            return {
+                id: user.sub,
+                email: user.email,
+                emailVerified: user.email_verified ?? false,
+                name: user.name,
+                image: user.picture,
+            };
+        },
+    };
+}

package/dist/betterauth/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Public surface of the `@vercel/connect/betterauth` subpath.
+ *
+ * Holds Better Auth-specific helpers for adapting Vercel Connect to
+ * the `genericOAuth` plugin. `better-auth` is an optional peer
+ * dependency: importing this entrypoint requires it to be installed
+ * in the consumer project, but the rest of `@vercel/connect` works
+ * without it.
+ */
+export { connect, type BetterAuthConnectOptions } from "./connect-provider.js";

package/dist/betterauth/index.js

@@ -0,0 +1,10 @@
+/**
+ * Public surface of the `@vercel/connect/betterauth` subpath.
+ *
+ * Holds Better Auth-specific helpers for adapting Vercel Connect to
+ * the `genericOAuth` plugin. `better-auth` is an optional peer
+ * dependency: importing this entrypoint requires it to be installed
+ * in the consumer project, but the rest of `@vercel/connect` works
+ * without it.
+ */
+export { connect } from "./connect-provider.js";

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { getToken, getTokenResponse, NoValidTokenError, UserAuthorizationRequiredError, ConnectorInstallationRequiredError, type ConnectOptions, type ConnectTokenParams, type ConnectTokenResponse, } from "./token.js";
+export { startAuthorization, type ConnectAuthorizationOptions, type ConnectAuthorizationResponse, } from "./authorization.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { getToken, getTokenResponse, NoValidTokenError, UserAuthorizationRequiredError, ConnectorInstallationRequiredError, } from "./token.js";
+export { startAuthorization, } from "./authorization.js";

package/dist/internal/team-id.d.ts

@@ -0,0 +1,3 @@
+export declare function tryGetVercelTeamId(): string | undefined;
+export declare function extractTeamIdFromOidcToken(token: string): string | undefined;
+export declare function withTeamId(baseUrl: string, teamId: string | undefined): string;

package/dist/internal/team-id.js

@@ -0,0 +1,47 @@
+/**
+ * Best-effort Vercel team-id extraction for the OAuth adapters.
+ *
+ * Vercel Connect's `/api/connex/oauth/authorize` endpoint accepts an
+ * optional `?teamId=...` query parameter that scopes the consent UI
+ * to a specific team. The team id lives inside the Vercel OIDC
+ * token's `owner_id` claim, so we decode the JWT payload (no
+ * signature verification — we're reading our own token) and pull it
+ * out.
+ *
+ * Failure is silent: the helper returns `undefined` if the token
+ * isn't available (e.g. running outside Vercel) or the payload can't
+ * be decoded. Adapters then fall back to an unqualified
+ * authorization URL.
+ */
+import { getVercelOidcTokenSync } from "@vercel/oidc";
+export function tryGetVercelTeamId() {
+    let token;
+    try {
+        token = getVercelOidcTokenSync();
+    }
+    catch {
+        return undefined;
+    }
+    return extractTeamIdFromOidcToken(token);
+}
+export function extractTeamIdFromOidcToken(token) {
+    try {
+        const parts = token.split(".");
+        if (parts.length < 2)
+            return undefined;
+        const padded = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+        const padLen = (4 - (padded.length % 4)) % 4;
+        const claims = JSON.parse(atob(padded + "=".repeat(padLen)));
+        return typeof claims.owner_id === "string" ? claims.owner_id : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function withTeamId(baseUrl, teamId) {
+    if (!teamId)
+        return baseUrl;
+    const url = new URL(baseUrl);
+    url.searchParams.set("teamId", teamId);
+    return url.toString();
+}

package/dist/token.d.ts

@@ -0,0 +1,47 @@
+export interface ConnectTokenParams {
+    subject: {
+        type: "app";
+    } | {
+        type: "user";
+        id: string;
+        issuer?: string;
+    };
+    installationId?: string;
+    audience?: string[];
+    scopes?: string[];
+    resources?: string[];
+    authorizationDetails?: Array<{
+        type: string;
+    } & Record<string, unknown>>;
+    /**
+     * Buffer time in milliseconds before token expiration to consider it invalid.
+     * If the token expires within this buffer, it will be refreshed.
+     * Defaults to 30 seconds.
+     */
+    validityBufferMs?: number;
+}
+export interface ConnectTokenResponse {
+    token: string;
+    /** Token expiration timestamp in milliseconds since epoch. */
+    expiresAt: number;
+    name?: string;
+    installationId?: string;
+    tenantId?: string;
+    externalSubject?: string;
+    /** Driver-specific metadata stored during OAuth */
+    metadata?: Record<string, unknown>;
+}
+export declare class NoValidTokenError extends Error {
+    constructor(message: string);
+}
+export declare class UserAuthorizationRequiredError extends Error {
+    constructor(message: string);
+}
+export declare class ConnectorInstallationRequiredError extends Error {
+    constructor(message: string);
+}
+export interface ConnectOptions {
+    vercelToken?: string;
+}
+export declare function getToken(connector: string, params: ConnectTokenParams, options?: ConnectOptions): Promise<string>;
+export declare function getTokenResponse(connector: string, params: ConnectTokenParams, options?: ConnectOptions): Promise<ConnectTokenResponse>;