@vercel/connect 2.4.0 → 2.5.0

package/README.md

@@ -243,3 +243,26 @@ const providers = [connect({ connector: 'linear' })];
 ```
 
 See the source under `src/` for the full API (additional helpers like `revokeToken`, `getTokenResponse`, `startAuthorization`, `experimental_startInstallation`, typed error classes, and per-adapter options).
+
+Experimental [MCP event subscription management](./docs/mcp-events.md) is available through `@vercel/connect/mcp`.
+
+### Experimental eve event integration
+
+`connect()` also exposes a runtime-only `vercelConnect.experimental_events`
+bridge for eve's event-enabled connections. eve can create a managed AI SDK
+adapter using the current authenticated principal and its framework-owned
+receiver path. It reuses the provider's `createSubject` mapping and
+`tokenParams`, including scopes, installation, audience, and resources. Creating
+the provider or adapter performs no network requests or subscriptions.
+
+The bridge also verifies Connect deliveries with the existing MCP event verifier.
+eve must then authorize each delivery against its saved session/subscription
+binding before invoking an authored callback. The bridge does not implement
+eve's inbox, session dispatch, or persistence. Those require the matching eve
+integration release.
+
+Event management uses deployment OIDC and the default Connect region, independently
+of the provider's `connectOptions.vercelToken` and `connectOptions.region`
+credential options. Event request failures use the provider's usual error
+translation. Compiler metadata must omit the live bridge and continue serializing
+only `connector` and `requirement`.

package/dist/ai-sdk/connect-events-adapter.d.ts

@@ -0,0 +1,77 @@
+import { type McpSubscribeInput, type McpSubscription } from '../mcp/events.js';
+import type { JsonObject } from '../internal/json.js';
+import type { EventRequestOptions } from '../internal/event-request.js';
+import type { ConnectTokenParams } from '../token.js';
+/** Trusted server-side scope. Create a separate adapter for each account. */
+export interface Experimental_ConnectEventsAdapterOptions {
+    connector: string;
+    /** Use the same resolved parameters as connectAuthProvider. */
+    tokenParams: ConnectTokenParams;
+    destination: {
+        path: string;
+    };
+    /** Overrides the client transport URL. Connect must authorize the endpoint. */
+    mcpUrl?: string;
+}
+export type Experimental_ConnectEventsSubscribeInput = Pick<McpSubscribeInput, 'name' | 'idempotencyKey'> & {
+    arguments: JsonObject;
+    context?: JsonObject;
+    options?: Experimental_ConnectEventsRequestOptions;
+} & ({
+    ttlMs: number;
+    expiresAt?: never;
+} | {
+    expiresAt: string | null;
+    ttlMs?: never;
+});
+/** A Connect watch, not an upstream MCP subscription grant. */
+export type Experimental_ConnectEventsSubscription = Pick<McpSubscription, 'id' | 'name' | 'status' | 'expiresAt' | 'cleanupStatus'> & {
+    arguments: JsonObject;
+};
+export interface Experimental_ConnectEventsListInput {
+    cursor?: string;
+    limit?: number;
+    status?: McpSubscription['status'];
+    options?: Experimental_ConnectEventsRequestOptions;
+}
+export type Experimental_ConnectEventsRequestOptions = EventRequestOptions;
+/**
+ * Structurally compatible with AI SDK's experimental managed events adapter.
+ * Requires the transport-context contract from vercel/ai#22325. No AI SDK
+ * dependency is required to bind operations directly with createAdapter().
+ * Listing is scoped to the bound account and workload project/environment,
+ * not to an individual conversation or context.
+ */
+export interface Experimental_ConnectEventsAdapter {
+    createAdapter(context: {
+        transport: {
+            type: 'http' | 'sse';
+            url: string;
+        } | {
+            type: 'custom';
+        };
+    }): Experimental_ConnectEventOperations;
+}
+/** Subscription operations bound to a single account, destination and endpoint. */
+export interface Experimental_ConnectEventOperations {
+    subscribe(input: Experimental_ConnectEventsSubscribeInput): Promise<Experimental_ConnectEventsSubscription>;
+    getSubscription(input: {
+        id: string;
+        options?: Experimental_ConnectEventsRequestOptions;
+    }): Promise<Experimental_ConnectEventsSubscription>;
+    listSubscriptions(input?: Experimental_ConnectEventsListInput): Promise<{
+        subscriptions: Experimental_ConnectEventsSubscription[];
+        nextCursor?: string;
+    }>;
+    unsubscribe(input: {
+        id: string;
+        options?: Experimental_ConnectEventsRequestOptions;
+    }): Promise<Experimental_ConnectEventsSubscription>;
+}
+/**
+ * Configure Connect-managed subscriptions without allocating a webhook or
+ * retaining a workload token. Connect owns upstream verification and subscription management;
+ * the application owns its receiver, authorization bindings and durable inbox.
+ * Connect manages provider renewal separately from the application's deadline.
+ */
+export declare function experimental_connectEventsAdapter({ connector, tokenParams: configuredTokenParams, destination: { path }, mcpUrl: configuredMcpUrl, }: Experimental_ConnectEventsAdapterOptions): Experimental_ConnectEventsAdapter;

package/dist/ai-sdk/connect-events-adapter.js

@@ -0,0 +1,87 @@
+import { getSubscription, listSubscriptions, subscribe, unsubscribe, } from '../mcp/events.js';
+import { snapshotEventTokenParams } from '../internal/event-token-params.js';
+/**
+ * Configure Connect-managed subscriptions without allocating a webhook or
+ * retaining a workload token. Connect owns upstream verification and subscription management;
+ * the application owns its receiver, authorization bindings and durable inbox.
+ * Connect manages provider renewal separately from the application's deadline.
+ */
+export function experimental_connectEventsAdapter({ connector, tokenParams: configuredTokenParams, destination: { path }, mcpUrl: configuredMcpUrl, }) {
+    if (typeof connector !== 'string' ||
+        !connector ||
+        typeof path !== 'string' ||
+        !path) {
+        throw new TypeError('A connector and destination path are required.');
+    }
+    const tokenParams = snapshotEventTokenParams(configuredTokenParams);
+    return {
+        createAdapter({ transport }) {
+            const mcpUrl = configuredMcpUrl ??
+                (transport.type === 'custom' ? undefined : transport.url);
+            return {
+                async subscribe(input) {
+                    // Select fields explicitly so extra runtime properties cannot override
+                    // the bound scope or turn provider arguments into delivery configuration.
+                    return toSubscription(await subscribe(connector, {
+                        tokenParams,
+                        mcpUrl,
+                        name: input.name,
+                        arguments: input.arguments,
+                        destination: { path },
+                        context: input.context,
+                        idempotencyKey: input.idempotencyKey,
+                        ...monitoringLifetime(input),
+                    }, requestOptions(input.options)));
+                },
+                async getSubscription({ id, options }) {
+                    return toSubscription(await getSubscription(connector, { id, expectedSubject: tokenParams.subject }, requestOptions(options)));
+                },
+                async listSubscriptions({ cursor, limit, status, options } = {}) {
+                    const page = await listSubscriptions(connector, { tokenParams, cursor, limit, status }, requestOptions(options));
+                    return {
+                        subscriptions: page.subscriptions.map(toSubscription),
+                        ...(page.pagination.next === null
+                            ? {}
+                            : { nextCursor: page.pagination.next }),
+                    };
+                },
+                async unsubscribe({ id, options }) {
+                    return toSubscription(await unsubscribe(connector, { id, expectedSubject: tokenParams.subject }, requestOptions(options)));
+                },
+            };
+        },
+    };
+}
+function requestOptions(options) {
+    // AI SDK inputs cannot override the workload identity or API region.
+    return options === undefined
+        ? undefined
+        : {
+            signal: options.signal,
+            timeout: options.timeout,
+            maxTotalTimeout: options.maxTotalTimeout,
+        };
+}
+function monitoringLifetime(input) {
+    if (input.ttlMs !== undefined && input.expiresAt === undefined) {
+        return { ttlMs: input.ttlMs };
+    }
+    if (input.ttlMs === undefined && input.expiresAt !== undefined) {
+        return { expiresAt: input.expiresAt };
+    }
+    throw new TypeError('Provide exactly one of ttlMs or expiresAt.');
+}
+function toSubscription(subscription) {
+    return {
+        id: subscription.id,
+        name: subscription.name,
+        // The HTTP response is parsed JSON. Keep the narrower JSON type in this
+        // adapter without changing the base API's Record<string, unknown> contract.
+        arguments: subscription.arguments,
+        status: subscription.status,
+        expiresAt: subscription.expiresAt,
+        ...(subscription.cleanupStatus === undefined
+            ? {}
+            : { cleanupStatus: subscription.cleanupStatus }),
+    };
+}

package/dist/ai-sdk/index.d.ts

@@ -52,3 +52,4 @@
  */
 export { CONNECT_DISCOVERY_STATE, CONNECT_MANAGED_REDIRECT_URL, connectAuthProvider, ConsentRequiredError, getConsentChallenge, isConsentRequiredError, type ConnectAuthProviderOptions, type ConnectConsentMode, type ConnectOAuthClientInformation, type ConnectOAuthClientMetadata, type ConnectOAuthClientProvider, type ConnectOAuthDiscoveryState, type ConnectOAuthTokens, type ConsentChallenge, } from '../mcp/connect-auth-provider.js';
 export { ConnectError, ConnectorInstallationRequiredError, NoValidTokenError, UserAuthorizationRequiredError, type ConnectErrorOptions, type ConnectTokenExchangeSubject, type ConnectTokenParams, type ConnectTokenSubject, type ConnectVendorErrorPayload, } from '../token.js';
+export { experimental_connectEventsAdapter, type Experimental_ConnectEventsAdapter, type Experimental_ConnectEventOperations, type Experimental_ConnectEventsAdapterOptions, type Experimental_ConnectEventsListInput, type Experimental_ConnectEventsRequestOptions, type Experimental_ConnectEventsSubscribeInput, type Experimental_ConnectEventsSubscription, } from './connect-events-adapter.js';

package/dist/ai-sdk/index.js

@@ -52,3 +52,4 @@
  */
 export { CONNECT_DISCOVERY_STATE, CONNECT_MANAGED_REDIRECT_URL, connectAuthProvider, ConsentRequiredError, getConsentChallenge, isConsentRequiredError, } from '../mcp/connect-auth-provider.js';
 export { ConnectError, ConnectorInstallationRequiredError, NoValidTokenError, UserAuthorizationRequiredError, } from '../token.js';
+export { experimental_connectEventsAdapter, } from './connect-events-adapter.js';

package/dist/eve/connection-authorization.d.ts

@@ -29,6 +29,8 @@
  * project, but the rest of `@vercel/connect` works without it.
  */
 import { type ConnectionPrincipal, type InteractiveAuthorizationDefinition, type NonInteractiveAuthorizationDefinition } from 'eve/connections';
+import { type Experimental_ConnectEventOperations } from '../ai-sdk/connect-events-adapter.js';
+import { type McpEventDelivery } from '../mcp/verify-event.js';
 import type { ConnectOptions, ConnectTokenParams, ConnectTokenSubject } from '../token.js';
 /**
  * Authorization phase passed to {@link EveAuthorizationOptions.onError}
@@ -186,6 +188,19 @@ export interface EveAuthorizationOptions {
 }
 /** Input accepted by {@link connect}. */
 export type EveAuthorizationInput = string | EveAuthorizationOptions;
+/** Runtime bridge consumed only by event-enabled eve connections. */
+export interface Experimental_EveEventsBackend {
+    createAdapter(input: {
+        principal: ConnectionPrincipal;
+        connection: EveConnectionAuthorizationContext;
+        destination: {
+            path: string;
+        };
+    }): Promise<Experimental_ConnectEventOperations>;
+    verify(request: Request, options: {
+        path: string;
+    }): Promise<McpEventDelivery>;
+}
 /**
  * Structurally-readable marker exposed on every {@link connect} return
  * value so downstream tooling can detect Vercel Connect-backed
@@ -204,13 +219,16 @@ export type EveAuthorizationInput = string | EveAuthorizationOptions;
  * Eve's build tooling. It remains optional so existing connector-only metadata
  * assignments stay source-compatible.
  *
- * The marker is purely metadata — it does not influence the runtime
- * token-fetching identity, which continues to be driven by the
+ * The connector and requirement are serializable metadata. The optional
+ * events bridge is a live runtime capability and must not be serialized.
+ * Token-fetching identity continues to be driven by the
  * `getToken` / `startAuthorization` / `completeAuthorization`
  * callbacks. When auto-provisioning is enabled, the same connector value is
  * also sent as the managed OAuth UID.
  */
 export interface VercelConnectMetadata {
+    /** Live capability; compilers must omit this from serializable metadata. */
+    readonly experimental_events?: Experimental_EveEventsBackend;
     /** Raw connector UID or service-connector key passed to the helper. */
     readonly connector: string;
     /** Complete credential requirement consumed by eve build tooling. */

package/dist/eve/connection-authorization.js

@@ -30,6 +30,8 @@
  */
 import { ConnectionAuthorizationFailedError, ConnectionAuthorizationRequiredError, } from 'eve/connections';
 import { startAuthorization } from '../authorization.js';
+import { experimental_connectEventsAdapter, } from '../ai-sdk/connect-events-adapter.js';
+import { verifyMcpEvent } from '../mcp/verify-event.js';
 import { ConnectError, ConnectorInstallationRequiredError, deleteTokenCacheEntry, getTokenResponse, NoValidTokenError, revokeToken, UserAuthorizationRequiredError, } from '../token.js';
 import { provisionEveOAuthConnector } from './provision-oauth-connector.js';
 export function connect(input) {
@@ -44,11 +46,23 @@ export function connect(input) {
     const vercelConnect = requirement === undefined
         ? { connector: options.connector }
         : { connector: options.connector, requirement };
+    const eventMetadata = {
+        ...vercelConnect,
+        experimental_events: buildEventsBackend(options),
+    };
     const evict = makeEvict(options);
     if (options.principalType === 'app') {
-        return { ...buildNonInteractiveDefinition(options), vercelConnect, evict };
+        return {
+            ...buildNonInteractiveDefinition(options),
+            vercelConnect: eventMetadata,
+            evict,
+        };
     }
-    return { ...buildInteractiveDefinition(options), vercelConnect, evict };
+    return {
+        ...buildInteractiveDefinition(options),
+        vercelConnect: eventMetadata,
+        evict,
+    };
 }
 /**
  * Builds the {@link EveConnectAuthorizationDefinition.evict} callback for
@@ -83,6 +97,35 @@ function makeEvict(options) {
         deleteTokenCacheEntry(options.connector, params);
     };
 }
+function buildEventsBackend(options) {
+    return {
+        verify: verifyMcpEvent,
+        async createAdapter({ principal, connection, destination }) {
+            // Apply the same error translation to subject resolution and requests.
+            async function call(operation) {
+                try {
+                    return await operation();
+                }
+                catch (error) {
+                    throw translate(error, 'getToken', options);
+                }
+            }
+            const adapter = await call(async () => experimental_connectEventsAdapter({
+                connector: options.connector,
+                tokenParams: await buildTokenParams(options, principal, connection),
+                destination,
+            }).createAdapter({
+                transport: { type: 'http', url: connection.url },
+            }));
+            return {
+                subscribe: input => call(() => adapter.subscribe(input)),
+                getSubscription: input => call(() => adapter.getSubscription(input)),
+                listSubscriptions: input => call(() => adapter.listSubscriptions(input)),
+                unsubscribe: input => call(() => adapter.unsubscribe(input)),
+            };
+        },
+    };
+}
 function normalizeAuthorizationOptions(input) {
     if (typeof input === 'string') {
         return { connector: input };

package/dist/eve/index.d.ts

@@ -6,7 +6,7 @@
  * this barrel re-exports the public API so consumers import
  * everything from `@vercel/connect/eve`.
  */
-export { connect, type EveAuthorizationInput, type EveAuthorizationOptions, type EveConnectAuthorizationDefinition, type EveConnectionAuthorizationContext, type ConnectAuthorizationPhase, type VercelConnectMetadata, } from './connection-authorization.js';
+export { connect, type EveAuthorizationInput, type EveAuthorizationOptions, type EveConnectAuthorizationDefinition, type EveConnectionAuthorizationContext, type ConnectAuthorizationPhase, type VercelConnectMetadata, type Experimental_EveEventsBackend, } from './connection-authorization.js';
 export { CONNECT_OAUTH_ISSUER, connectOAuth, type ConnectOAuthAudienceEnvironment, type ConnectOAuthEnvironment, type ConnectOAuthOptions, } from './connect-oauth.js';
 export { connectDiscordCredentials, type ConnectDiscordCredentialsParams, } from './discord-credentials.js';
 export { connectGitHubCredentials, type ConnectGitHubCredentialsParams, } from './github-credentials.js';

package/dist/internal/event-request.d.ts

@@ -0,0 +1,10 @@
+export interface EventRequestOptions {
+    /** Cancels this request, not a subscription already accepted by Connect. */
+    signal?: AbortSignal;
+    /** Request deadline in milliseconds, including credential resolution. */
+    timeout?: number;
+    /** Overall deadline in milliseconds. The earlier supplied deadline wins. */
+    maxTotalTimeout?: number;
+}
+/** Bound credential resolution, fetch and response parsing with one deadline. */
+export declare function eventRequest<T>(options: EventRequestOptions | undefined, run: (signal: AbortSignal | undefined) => Promise<T>): Promise<T>;

package/dist/internal/event-request.js

@@ -0,0 +1,31 @@
+/** Bound credential resolution, fetch and response parsing with one deadline. */
+export async function eventRequest(options, run) {
+    const { signal: externalSignal, timeout, maxTotalTimeout } = options ?? {};
+    externalSignal?.throwIfAborted();
+    const deadlines = [timeout, maxTotalTimeout].filter((value) => value !== undefined);
+    if (deadlines.some(value => !Number.isInteger(value) || value <= 0 || value > 2_147_483_647)) {
+        throw new TypeError('Request timeouts must be positive 32-bit integers.');
+    }
+    const controller = deadlines.length ? new AbortController() : undefined;
+    const signal = controller?.signal ?? externalSignal;
+    const forwardAbort = () => controller?.abort(externalSignal?.reason);
+    externalSignal?.addEventListener('abort', forwardAbort, { once: true });
+    const timer = controller
+        ? setTimeout(() => controller.abort(new DOMException('Request timed out.', 'TimeoutError')), Math.min(...deadlines))
+        : undefined;
+    let onAbort;
+    try {
+        const aborted = new Promise((_, reject) => {
+            onAbort = () => reject(signal?.reason);
+            signal?.addEventListener('abort', onAbort, { once: true });
+        });
+        return await Promise.race([run(signal), aborted]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        externalSignal?.removeEventListener('abort', forwardAbort);
+        if (onAbort)
+            signal?.removeEventListener('abort', onAbort);
+    }
+}

package/dist/internal/event-token-params.d.ts

@@ -0,0 +1,3 @@
+import type { ConnectTokenParams } from '../token.js';
+/** Copy only credential fields; extra properties cannot become routing input. */
+export declare function snapshotEventTokenParams(params: ConnectTokenParams): ConnectTokenParams;

package/dist/internal/event-token-params.js

@@ -0,0 +1,94 @@
+/** Copy only credential fields; extra properties cannot become routing input. */
+export function snapshotEventTokenParams(params) {
+    if (!params || typeof params !== 'object')
+        throw invalid();
+    const subject = snapshotSubject(params.subject);
+    for (const field of ['scopes', 'audience', 'resources']) {
+        const value = params[field];
+        if (value !== undefined &&
+            (!Array.isArray(value) || !value.every(nonEmptyString))) {
+            throw invalid();
+        }
+    }
+    if (params.installationId !== undefined &&
+        !nonEmptyString(params.installationId))
+        throw invalid();
+    if (params.validityBufferMs !== undefined &&
+        (!Number.isSafeInteger(params.validityBufferMs) ||
+            params.validityBufferMs < 0))
+        throw invalid();
+    if (params.authorizationDetails !== undefined &&
+        (!Array.isArray(params.authorizationDetails) ||
+            !params.authorizationDetails.every(detail => object(detail) && nonEmptyString(detail.type))))
+        throw invalid();
+    // Snapshot nested arrays/details before any asynchronous credential lookup.
+    // Reject non-JSON values instead of silently changing credential constraints.
+    return JSON.parse(JSON.stringify({
+        subject,
+        installationId: params.installationId,
+        scopes: params.scopes,
+        audience: params.audience,
+        resources: params.resources,
+        authorizationDetails: params.authorizationDetails,
+        validityBufferMs: params.validityBufferMs,
+    }, (_key, value) => {
+        if (typeof value === 'function' ||
+            typeof value === 'symbol' ||
+            typeof value === 'bigint' ||
+            (typeof value === 'number' && !Number.isFinite(value)))
+            throw invalid();
+        return value;
+    }));
+}
+function snapshotSubject(subject) {
+    if (!subject || typeof subject !== 'object')
+        throw invalid();
+    switch (subject.type) {
+        case 'app':
+            return { type: 'app' };
+        case 'user':
+            if (!nonEmptyString(subject.id) ||
+                !optionalString(subject.issuer) ||
+                !optionalString(subject.experimental_idp))
+                throw invalid();
+            return {
+                type: 'user',
+                id: subject.id,
+                issuer: subject.issuer,
+                experimental_idp: subject.experimental_idp,
+            };
+        case 'jwt-bearer':
+            if (!nonEmptyString(subject.sub) ||
+                !optionalString(subject.iss) ||
+                !optionalString(subject.aud) ||
+                (subject.additionalClaims !== undefined &&
+                    !object(subject.additionalClaims)))
+                throw invalid();
+            return {
+                type: 'jwt-bearer',
+                sub: subject.sub,
+                iss: subject.iss,
+                aud: subject.aud,
+                additionalClaims: subject.additionalClaims,
+            };
+        case 'token':
+        case undefined:
+            if (!nonEmptyString(subject.token))
+                throw invalid();
+            return { type: subject.type, token: subject.token };
+        default:
+            throw invalid();
+    }
+}
+function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function optionalString(value) {
+    return value === undefined || nonEmptyString(value);
+}
+function invalid() {
+    return new TypeError('Valid resolved ConnectTokenParams are required.');
+}

package/dist/internal/json.d.ts

@@ -0,0 +1,5 @@
+/** JSON types kept local so Connect does not require an AI SDK dependency. */
+export type JsonValue = null | string | number | boolean | JsonObject | JsonValue[];
+export type JsonObject = {
+    [key: string]: JsonValue | undefined;
+};

package/dist/internal/json.js

@@ -0,0 +1 @@
+export {};

package/dist/mcp/events.d.ts

@@ -0,0 +1,98 @@
+import { type EventRequestOptions } from '../internal/event-request.js';
+import { type ConnectOptions, type ConnectTokenParams } from '../token.js';
+export type McpEventSubject = Extract<ConnectTokenParams['subject'], {
+    type: 'app' | 'user';
+}>;
+export interface McpEventDescriptor {
+    name: string;
+    description?: string;
+    delivery: ('webhook' | 'poll' | 'push')[];
+    inputSchema: Record<string, unknown>;
+    payloadSchema: Record<string, unknown>;
+}
+export type McpSubscriptionStatus = 'pending' | 'active' | 'needs_auth' | 'stopped' | 'expired' | 'failed';
+export interface McpSubscription {
+    id: string;
+    connectorId: string;
+    projectId: string;
+    environment: string;
+    subject: McpEventSubject;
+    name: string;
+    arguments: Record<string, unknown>;
+    destination: {
+        path: string;
+    };
+    context: Record<string, unknown>;
+    status: McpSubscriptionStatus;
+    /** ISO deadline, or null for an explicitly indefinite watch. */
+    expiresAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+    cleanupStatus?: 'pending' | 'complete' | 'exhausted';
+    stopReason?: string;
+    lastError?: string;
+}
+export type McpSubscribeInput = McpEventSourceInput & {
+    name: string;
+    arguments: Record<string, unknown>;
+    destination: {
+        path: string;
+    };
+    context?: Record<string, unknown>;
+    idempotencyKey: string;
+} & ({
+    ttlMs: number;
+    expiresAt?: never;
+} | {
+    expiresAt: string | null;
+    ttlMs?: never;
+});
+/** Upstream credential selection, separate from event and pagination fields. */
+export interface McpEventScope {
+    /** Derive from authenticated application state, never model output. */
+    tokenParams: ConnectTokenParams;
+}
+/** MCP endpoint selection for operations that contact the upstream server. */
+export interface McpEventSourceInput extends McpEventScope {
+    /** Defaults to the connector endpoint. Connect must authorize this URL. */
+    mcpUrl?: string;
+}
+/** Lookup uses the globally unique ID; ownership is checked independently. */
+export interface McpSubscriptionLookupInput {
+    id: string;
+    /**
+     * Optional assertion against the stored creation subject, not a request for
+     * upstream credentials. Account-bound callers should always supply it.
+     */
+    expectedSubject?: ConnectTokenParams['subject'];
+}
+export type McpEventOptions = Pick<ConnectOptions, 'vercelToken' | 'region'> & EventRequestOptions;
+export declare function discoverEvents(connector: string, params: McpEventSourceInput, options?: McpEventOptions): Promise<{
+    status: "supported" | "unsupported" | "unavailable" | "needs_auth";
+}>;
+/** Optional account-scoped catalog discovery; does not poll event occurrences. */
+export declare function listEventTypes(connector: string, params: McpEventSourceInput & {
+    cursor?: string;
+}, options?: McpEventOptions): Promise<{
+    events: McpEventDescriptor[];
+    nextCursor?: string;
+}>;
+export declare function subscribe(connector: string, params: McpSubscribeInput, options?: McpEventOptions): Promise<McpSubscription>;
+export declare function listSubscriptions(connector: string, params: McpEventScope & {
+    cursor?: string;
+    status?: McpSubscriptionStatus;
+    limit?: number;
+}, options?: McpEventOptions): Promise<{
+    subscriptions: McpSubscription[];
+    pagination: {
+        next: string | null;
+    };
+}>;
+export declare function getSubscription(connector: string, params: McpSubscriptionLookupInput, options?: McpEventOptions): Promise<McpSubscription>;
+export declare function unsubscribe(connector: string, params: McpSubscriptionLookupInput, options?: McpEventOptions): Promise<McpSubscription>;
+/** Stops only this connector/subject/project/environment scope. */
+export declare function unsubscribeAll(connector: string, params: McpEventScope & {
+    idempotencyKey: string;
+}, options?: McpEventOptions): Promise<{
+    accepted: true;
+}>;

package/dist/mcp/events.js

@@ -0,0 +1,65 @@
+import { getVercelOidcToken } from '@vercel/oidc';
+import { eventRequest, } from '../internal/event-request.js';
+import { resolveBaseUrl } from '../internal/base-url.js';
+import { createConnectErrorFromResponse, } from '../token.js';
+export function discoverEvents(connector, params, options) {
+    return request(connector, 'events/discover', params, options);
+}
+/** Optional account-scoped catalog discovery; does not poll event occurrences. */
+export function listEventTypes(connector, params, options) {
+    const url = new URL('/v1/connect/mcp-events/event-types', resolveBaseUrl(options));
+    url.searchParams.set('connector', connector);
+    url.searchParams.set('tokenRequest', JSON.stringify(params.tokenParams));
+    if (params.cursor !== undefined)
+        url.searchParams.set('cursor', params.cursor);
+    if (params.mcpUrl !== undefined)
+        url.searchParams.set('sourceUrl', params.mcpUrl);
+    return send(url, { method: 'GET' }, options);
+}
+export function subscribe(connector, params, options) {
+    return request(connector, 'subscriptions', params, options);
+}
+export function listSubscriptions(connector, params, options) {
+    return request(connector, 'subscriptions/actions/list', params, options);
+}
+export function getSubscription(connector, params, options) {
+    return request(connector, 'subscriptions/actions/get', params, options);
+}
+export function unsubscribe(connector, params, options) {
+    return request(connector, 'subscriptions/actions/unsubscribe', params, options);
+}
+/** Stops only this connector/subject/project/environment scope. */
+export function unsubscribeAll(connector, params, options) {
+    return request(connector, 'subscriptions/actions/unsubscribe-all', params, options);
+}
+async function request(connector, operation, params, options) {
+    // Serialize before awaiting auth so caller mutation cannot change the subject.
+    const { mcpUrl, ...fields } = params;
+    const body = JSON.stringify({
+        ...fields,
+        source: { type: 'mcp', url: mcpUrl },
+    });
+    const url = new URL(`/v1/connect/connectors/${encodeURIComponent(connector)}/${operation}`, resolveBaseUrl(options));
+    return send(url, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body }, options);
+}
+function send(url, init, options) {
+    const { vercelToken } = options ?? {};
+    return eventRequest(options, async (signal) => {
+        signal?.throwIfAborted();
+        const token = vercelToken ?? (await getVercelOidcToken());
+        signal?.throwIfAborted();
+        const response = await fetch(url.toString(), {
+            ...init,
+            redirect: 'error',
+            headers: {
+                Accept: 'application/json',
+                ...init.headers,
+                Authorization: `Bearer ${token}`,
+            },
+            ...(signal === undefined ? {} : { signal }),
+        });
+        if (!response.ok)
+            throw await createConnectErrorFromResponse(response, 'Failed to manage event subscriptions');
+        return (await response.json());
+    });
+}

package/dist/mcp/index.d.ts

@@ -34,3 +34,5 @@
  */
 export { CONNECT_DISCOVERY_STATE, CONNECT_MANAGED_REDIRECT_URL, connectAuthProvider, ConsentRequiredError, getConsentChallenge, isConsentRequiredError, type ConnectAuthProviderOptions, type ConnectConsentMode, type ConnectOAuthClientInformation, type ConnectOAuthClientMetadata, type ConnectOAuthClientProvider, type ConnectOAuthDiscoveryState, type ConnectOAuthTokens, type ConsentChallenge, } from './connect-auth-provider.js';
 export { ConnectError, ConnectorInstallationRequiredError, NoValidTokenError, UserAuthorizationRequiredError, type ConnectErrorOptions, type ConnectTokenExchangeSubject, type ConnectTokenParams, type ConnectTokenSubject, type ConnectVendorErrorPayload, } from '../token.js';
+export { discoverEvents as experimental_discoverEvents, listEventTypes as experimental_listEventTypes, subscribe as experimental_subscribe, listSubscriptions as experimental_listSubscriptions, getSubscription as experimental_getSubscription, unsubscribe as experimental_unsubscribe, unsubscribeAll as experimental_unsubscribeAll, type McpEventScope as Experimental_McpEventScope, type McpEventSourceInput as Experimental_McpEventSourceInput, type McpEventOptions as Experimental_McpEventOptions, type McpEventDescriptor as Experimental_McpEventDescriptor, type McpEventSubject as Experimental_McpEventSubject, type McpSubscribeInput as Experimental_McpSubscribeInput, type McpSubscription as Experimental_McpSubscription, type McpSubscriptionStatus as Experimental_McpSubscriptionStatus, type McpSubscriptionLookupInput as Experimental_McpSubscriptionLookupInput, } from './events.js';
+export { verifyMcpEvent as experimental_verifyMcpEvent, McpEventVerificationError as Experimental_McpEventVerificationError, type McpEventDelivery as Experimental_McpEventDelivery, type VerifyMcpEventOptions as Experimental_VerifyMcpEventOptions, } from './verify-event.js';

package/dist/mcp/index.js

@@ -34,3 +34,5 @@
  */
 export { CONNECT_DISCOVERY_STATE, CONNECT_MANAGED_REDIRECT_URL, connectAuthProvider, ConsentRequiredError, getConsentChallenge, isConsentRequiredError, } from './connect-auth-provider.js';
 export { ConnectError, ConnectorInstallationRequiredError, NoValidTokenError, UserAuthorizationRequiredError, } from '../token.js';
+export { discoverEvents as experimental_discoverEvents, listEventTypes as experimental_listEventTypes, subscribe as experimental_subscribe, listSubscriptions as experimental_listSubscriptions, getSubscription as experimental_getSubscription, unsubscribe as experimental_unsubscribe, unsubscribeAll as experimental_unsubscribeAll, } from './events.js';
+export { verifyMcpEvent as experimental_verifyMcpEvent, McpEventVerificationError as Experimental_McpEventVerificationError, } from './verify-event.js';

package/dist/mcp/verify-event.d.ts

@@ -0,0 +1,67 @@
+interface McpDeliveryEnvelope {
+    version: 1;
+    deliveryId: string;
+    subscriptionId: string;
+    source: {
+        type: 'mcp';
+        connectorId: string;
+    };
+    context: Record<string, unknown>;
+}
+export type McpEventDelivery = McpDeliveryEnvelope & ({
+    event: {
+        eventId: string;
+        name: string;
+        timestamp: string;
+        data: Record<string, unknown>;
+        cursor: string | null;
+        _meta?: Record<string, unknown>;
+    };
+} | {
+    control: {
+        type: 'gap';
+        cursor: string | null;
+        truncated?: true;
+    };
+} | {
+    control: {
+        type: 'terminated';
+        error: {
+            code: number;
+            message: string;
+            data?: unknown;
+        };
+    };
+});
+export interface VerifyMcpEventOptions {
+    /** Registered destination path from trusted server configuration. */
+    path: string;
+    /** Optional additional owner restriction. Defaults to VERCEL_ORG_ID when set. */
+    ownerId?: string;
+    /** Existing Vercel OIDC audience, normally https://vercel.com/<team-slug>. */
+    audience?: string;
+    /** Match the project's issuer mode: global or https://oidc.vercel.com/<team-slug>. */
+    issuer?: string;
+    /** Defaults to VERCEL_PROJECT_ID. Wildcards are not supported. */
+    projectId?: string;
+    /** Defaults to VERCEL_TARGET_ENV, then VERCEL_ENV. */
+    environment?: string;
+    /** Required for a custom environment; use its stable env_ ID. */
+    customEnvironmentId?: string;
+    /** Required for preview; defaults to VERCEL_GIT_COMMIT_REF. */
+    branch?: string;
+}
+export declare class McpEventVerificationError extends Error {
+    readonly code: 'invalid_delivery' | 'configuration_error' | 'verification_unavailable';
+    constructor(code: McpEventVerificationError['code']);
+}
+/**
+ * Authenticate Connect's delivery token and validate the event envelope.
+ * Consumes the body. Does not acknowledge, deduplicate, or start application work.
+ * Persist acceptance by deliveryId before returning success to Connect.
+ *
+ * Generic Request URLs and forwarded headers cannot establish a trusted public
+ * route. Supply the registered path; project and environment default to env vars.
+ */
+export declare function verifyMcpEvent(request: Request, options: VerifyMcpEventOptions): Promise<McpEventDelivery>;
+export {};

package/dist/mcp/verify-event.js

@@ -0,0 +1,247 @@
+import { verifyVercelOidcToken } from '@vercel/oidc';
+import { readNonEmptyEnv } from '../internal/env.js';
+export class McpEventVerificationError extends Error {
+    code;
+    constructor(code) {
+        super(code === 'configuration_error'
+            ? 'Trusted MCP event receiver configuration is missing or invalid.'
+            : code === 'verification_unavailable'
+                ? 'MCP event verification is temporarily unavailable.'
+                : 'Invalid MCP event delivery.');
+        this.name = 'McpEventVerificationError';
+        this.code = code;
+    }
+}
+/**
+ * Authenticate Connect's delivery token and validate the event envelope.
+ * Consumes the body. Does not acknowledge, deduplicate, or start application work.
+ * Persist acceptance by deliveryId before returning success to Connect.
+ *
+ * Generic Request URLs and forwarded headers cannot establish a trusted public
+ * route. Supply the registered path; project and environment default to env vars.
+ */
+export async function verifyMcpEvent(request, options) {
+    const config = receiverConfig(options);
+    const token = request.headers
+        .get('authorization')
+        ?.match(/^Bearer\s+(.+)$/i)?.[1];
+    if (!token ||
+        request.method !== 'POST' ||
+        !/^application\/json(?:\s*;\s*charset=utf-8)?$/i.test(request.headers.get('content-type') ?? '') ||
+        (request.headers.has('content-encoding') &&
+            request.headers.get('content-encoding') !== 'identity'))
+        throw invalid();
+    let verified;
+    try {
+        verified = await verifyVercelOidcToken(token, {
+            issuer: config.issuer,
+            audience: config.audience,
+            ownerId: config.ownerId,
+            projectId: config.projectId,
+            environment: config.environment,
+            algorithms: ['RS256'],
+            typ: 'JWT',
+            requiredClaims: [
+                'iss',
+                'aud',
+                'iat',
+                'exp',
+                'owner_id',
+                'project_id',
+                'environment',
+            ],
+            maxTokenAge: 300,
+            clockTolerance: 60,
+        });
+    }
+    catch (error) {
+        const code = isObject(error) ? error.code : undefined;
+        if (typeof code === 'string' &&
+            (/^(ERR_JWT_|ERR_JWS_)/.test(code) ||
+                [
+                    'ERR_JWKS_NO_MATCHING_KEY',
+                    'ERR_JOSE_ALG_NOT_ALLOWED',
+                    'ERR_JOSE_NOT_SUPPORTED',
+                    'ERR_VERCEL_OIDC_TOKEN_VALIDATION',
+                ].includes(code)))
+            throw invalid();
+        throw new McpEventVerificationError('verification_unavailable');
+    }
+    // The reserved purpose distinguishes Connect deliveries from ordinary project
+    // tokens. Trust the envelope received over HTTPS; no body signature is used.
+    verifyDeliveryIdentity(verified, config);
+    const bytes = await readBody(request);
+    let delivery;
+    try {
+        delivery = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+    }
+    catch {
+        throw invalid();
+    }
+    if (!isDelivery(delivery))
+        throw invalid();
+    return delivery;
+}
+// Signature, algorithm, issuer, audience, identity, and token age are checked
+// by the OIDC verifier above. These checks restrict the delivery's purpose and
+// destination; they do not bind the token to an individual envelope.
+function verifyDeliveryIdentity(verified, config) {
+    const { payload, protectedHeader } = verified;
+    const claims = payload.connect;
+    if (!isString(protectedHeader.kid) ||
+        protectedHeader.jku !== undefined ||
+        protectedHeader.x5u !== undefined ||
+        !Number.isInteger(payload.iat) ||
+        !Number.isInteger(payload.exp) ||
+        payload.exp <= payload.iat ||
+        payload.exp - payload.iat > 300 ||
+        payload.custom_environment_id !== config.customEnvironmentId ||
+        !isObject(claims) ||
+        claims.purpose !== 'mcp_event_delivery' ||
+        claims.version !== 1 ||
+        claims.destinationPath !== config.path ||
+        claims.previewBranch !== config.previewBranch)
+        throw invalid();
+}
+function receiverConfig(options) {
+    const projectId = options?.projectId ?? readNonEmptyEnv('VERCEL_PROJECT_ID');
+    const environment = options?.environment ??
+        readNonEmptyEnv('VERCEL_TARGET_ENV') ??
+        readNonEmptyEnv('VERCEL_ENV');
+    const previewBranch = environment === 'preview'
+        ? (options?.branch ?? readNonEmptyEnv('VERCEL_GIT_COMMIT_REF'))
+        : undefined;
+    const ownerId = options?.ownerId ?? readNonEmptyEnv('VERCEL_ORG_ID');
+    if (!options ||
+        !isString(projectId) ||
+        projectId === '*' ||
+        !isString(environment) ||
+        environment === '*' ||
+        environment === 'development' ||
+        (ownerId !== undefined && (!isString(ownerId) || ownerId === '*')) ||
+        (options.audience !== undefined &&
+            (!isString(options.audience) || options.audience === '*')) ||
+        (options.issuer !== undefined &&
+            !/^https:\/\/oidc\.vercel\.com(?:\/[A-Za-z0-9_-]+)?$/.test(options.issuer)) ||
+        (environment === 'preview' &&
+            (!isString(previewBranch) || previewBranch === '*')) ||
+        (environment !== 'preview' && options.branch !== undefined) ||
+        (!['production', 'preview'].includes(environment) &&
+            !/^env_[A-Za-z0-9]+$/.test(options.customEnvironmentId ?? '')) ||
+        (['production', 'preview'].includes(environment) &&
+            options.customEnvironmentId !== undefined))
+        throw new McpEventVerificationError('configuration_error');
+    try {
+        const url = new URL(options.path, 'https://receiver.invalid');
+        if (!options.path.startsWith('/') ||
+            options.path.startsWith('//') ||
+            url.origin !== 'https://receiver.invalid' ||
+            url.pathname !== options.path ||
+            url.search ||
+            url.hash)
+            throw new Error();
+    }
+    catch {
+        throw new McpEventVerificationError('configuration_error');
+    }
+    return { ...options, ownerId, projectId, environment, previewBranch };
+}
+async function readBody(request) {
+    const reader = request.body?.getReader();
+    if (!reader)
+        throw invalid();
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > 300 * 1024) {
+                await reader.cancel();
+                throw invalid();
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const body = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        body.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return body;
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function hasOnly(value, keys) {
+    return Object.keys(value).every(key => keys.includes(key));
+}
+function isDelivery(value) {
+    if (!isObject(value) ||
+        value.version !== 1 ||
+        !hasOnly(value, [
+            'version',
+            'deliveryId',
+            'subscriptionId',
+            'source',
+            'event',
+            'control',
+            'context',
+        ]) ||
+        !isString(value.deliveryId) ||
+        !isString(value.subscriptionId) ||
+        !isObject(value.context))
+        return false;
+    const { source, event, control } = value;
+    if (!(isObject(source) &&
+        hasOnly(source, ['type', 'connectorId']) &&
+        source.type === 'mcp' &&
+        isString(source.connectorId)))
+        return false;
+    if ('control' in value) {
+        if ('event' in value || !isObject(control))
+            return false;
+        if (control.type === 'gap')
+            return (hasOnly(control, ['type', 'cursor', 'truncated']) &&
+                isCursor(control.cursor) &&
+                (control.truncated === undefined || control.truncated === true));
+        if (control.type === 'terminated')
+            return (hasOnly(control, ['type', 'error']) &&
+                isObject(control.error) &&
+                hasOnly(control.error, ['code', 'message', 'data']) &&
+                Number.isSafeInteger(control.error.code) &&
+                typeof control.error.message === 'string');
+        return false;
+    }
+    return (isObject(event) &&
+        hasOnly(event, [
+            'eventId',
+            'name',
+            'timestamp',
+            'data',
+            'cursor',
+            '_meta',
+        ]) &&
+        isString(event.eventId) &&
+        isString(event.name) &&
+        isString(event.timestamp) &&
+        Number.isFinite(Date.parse(event.timestamp)) &&
+        isObject(event.data) &&
+        isCursor(event.cursor) &&
+        (event._meta === undefined || isObject(event._meta)));
+}
+function isCursor(value) {
+    return value === null || typeof value === 'string';
+}
+function invalid() {
+    return new McpEventVerificationError('invalid_delivery');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/connect",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "license": "Apache-2.0",
   "type": "module",
   "repository": {
@@ -50,11 +50,11 @@
     "dist"
   ],
   "dependencies": {
-    "@vercel/oidc": "4.0.0"
+    "@vercel/oidc": "4.0.1"
   },
   "peerDependencies": {
     "@ai-sdk/mcp": "^1 || ^2",
-    "@auth/core": ">=0.37.0",
+    "@auth/core": ">=0.41.3",
     "@chat-adapter/slack": "^4.0.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "ai": "^6 || ^7.0.0-beta.0",
@@ -86,13 +86,14 @@
   },
   "devDependencies": {
     "@ai-sdk/mcp": "2.0.0-beta.37",
-    "@auth/core": "0.37.4",
+    "@auth/core": "0.41.3",
     "@chat-adapter/slack": "4.31.0",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@tanstack/ai-mcp": "0.3.10",
     "ai": "7.0.26",
     "better-auth": "1.5.5",
     "eve": "0.39.1",
+    "jose5": "npm:jose@5.9.6",
     "typescript": "^5"
   },
   "private": false,