@vercel/connect 0.2.1 → 0.2.3

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

@@ -82,6 +82,25 @@ export interface EveAuthorizationOptions {
      * and rely on `@vercel/oidc` auto-discovery.
      */
     readonly connectOptions?: ConnectOptions;
+    /**
+     * Re-validate the grant against Vercel Connect on every `getToken`
+     * instead of trusting the in-process token cache.
+     *
+     * By default `getToken` returns a cached token as long as it has not
+     * expired, so a grant the user revoked server-side keeps reaching the
+     * tool until the bearer's natural expiry. With `validate: true` each
+     * `getToken` bypasses the local cache and re-checks Connect; a revoked
+     * grant comes back as `no_token` / `user_authorization_required`, which
+     * the adapter maps to {@link ConnectionAuthorizationRequiredError} so
+     * Eve re-runs the consent flow rather than calling the tool with a dead
+     * token.
+     *
+     * This trades a Connect round trip per call for freshness — leave it
+     * off for high-frequency tools where a short revocation window is
+     * acceptable, and turn it on for sensitive actions (payments, deletes,
+     * privileged writes) that must never run on a revoked grant.
+     */
+    readonly validate?: boolean;
     /**
      * Custom call-to-action rendered on the
      * `connection.authorization_required` event. When omitted, Eve
@@ -132,6 +151,33 @@ export interface VercelConnectMetadata {
  */
 export type EveConnectAuthorizationDefinition<TAuthorization extends InteractiveAuthorizationDefinition | NonInteractiveAuthorizationDefinition> = TAuthorization & {
     readonly vercelConnect: VercelConnectMetadata;
+    /**
+     * Drops the in-process Vercel Connect token cache entry for
+     * `principal` so the next `getToken` re-fetches instead of re-serving a
+     * rejected bearer. Eve's runtime calls this from its shared eviction
+     * path when a resolved token is rejected (a downstream `401` mapped to
+     * `requireAuth()`, or an MCP server rejecting the bearer), cascading
+     * invalidation from Eve's per-step cache down into this adapter's cache.
+     *
+     * By default this is a local-cache-only operation: it preserves the
+     * underlying Connect grant (and its refresh token), so the next
+     * `getToken` can refresh a merely-expired access token without forcing
+     * a new consent flow. That is the right default for the automatic
+     * `401` cascade, where the rejected bearer is usually just stale.
+     *
+     * Pass `revoke: true` only when the grant itself is known to be dead
+     * and you want it torn down at Vercel Connect (refresh token included)
+     * so the next `getToken` surfaces `user_authorization_required` and
+     * re-runs consent — e.g. a user-initiated "disconnect this
+     * integration" action. Revocation is destructive and best-effort: a
+     * failed or duplicate revoke is swallowed so it never masks the error
+     * that triggered eviction, and the local cache entry is dropped either
+     * way.
+     */
+    readonly evict: (opts: {
+        readonly principal: ConnectionPrincipal;
+        readonly revoke?: boolean;
+    }) => Promise<void>;
 };
 /**
  * Builds an Eve {@link AuthorizationDefinition} backed by Vercel

package/dist/eve/connection-authorization.js

@@ -30,14 +30,48 @@
  */
 import { ConnectionAuthorizationFailedError, ConnectionAuthorizationRequiredError, } from 'eve/connections';
 import { startAuthorization } from '../authorization.js';
-import { ConnectorInstallationRequiredError, getTokenResponse, NoValidTokenError, UserAuthorizationRequiredError, } from '../token.js';
+import { ConnectorInstallationRequiredError, deleteTokenCacheEntry, getTokenResponse, NoValidTokenError, revokeToken, UserAuthorizationRequiredError, } from '../token.js';
 export function connect(input) {
     const options = normalizeAuthorizationOptions(input);
     const vercelConnect = { connector: options.connector };
+    const evict = makeEvict(options);
     if (options.principalType === 'app') {
-        return { ...buildNonInteractiveDefinition(options), vercelConnect };
+        return { ...buildNonInteractiveDefinition(options), vercelConnect, evict };
     }
-    return { ...buildInteractiveDefinition(options), vercelConnect };
+    return { ...buildInteractiveDefinition(options), vercelConnect, evict };
+}
+/**
+ * Builds the {@link EveConnectAuthorizationDefinition.evict} callback for
+ * a connector. Resolves the same token params {@link getToken} uses for
+ * `principal`, then drops exactly that cache entry — leaving every other
+ * principal's cached token intact.
+ *
+ * When called with `revoke: true` it instead tears the grant down at
+ * Vercel Connect via {@link revokeToken} (best-effort, falling back to a
+ * local cache drop if the revoke request fails).
+ */
+function makeEvict(options) {
+    return async ({ principal, revoke }) => {
+        const params = await buildTokenParams(options, principal);
+        if (revoke) {
+            try {
+                // Destructive: tears down the grant at Vercel Connect (refresh
+                // token included) and clears the in-process cache. Best-effort —
+                // a failed or duplicate revoke must not mask the auth error that
+                // triggered eviction.
+                await revokeToken(options.connector, {
+                    subject: params.subject,
+                    installationId: params.installationId,
+                }, options.connectOptions);
+                return;
+            }
+            catch {
+                // Fall through to the local cache drop so the rejected bearer is
+                // gone even when the server-side revoke failed.
+            }
+        }
+        deleteTokenCacheEntry(options.connector, params);
+    };
 }
 function normalizeAuthorizationOptions(input) {
     if (typeof input === 'string') {
@@ -50,7 +84,7 @@ function buildInteractiveDefinition(options) {
         principalType: 'user',
         async getToken({ principal }) {
             try {
-                const response = await getTokenResponse(options.connector, await buildTokenParams(options, principal), options.connectOptions);
+                const response = await getTokenResponse(options.connector, await buildTokenParams(options, principal), getTokenConnectOptions(options));
                 return { token: response.token, expiresAt: response.expiresAt };
             }
             catch (error) {
@@ -118,7 +152,7 @@ function buildNonInteractiveDefinition(options) {
         principalType: 'app',
         async getToken({ principal }) {
             try {
-                const response = await getTokenResponse(options.connector, await buildTokenParams(options, principal), options.connectOptions);
+                const response = await getTokenResponse(options.connector, await buildTokenParams(options, principal), getTokenConnectOptions(options));
                 return { token: response.token, expiresAt: response.expiresAt };
             }
             catch (error) {
@@ -127,6 +161,18 @@ function buildNonInteractiveDefinition(options) {
         },
     };
 }
+/**
+ * Connect SDK options for `getToken` calls. When {@link
+ * EveAuthorizationOptions.validate} is set, forces a cache-bypassing
+ * re-fetch so a revoked-but-unexpired grant is caught instead of served
+ * from the in-process token cache.
+ */
+function getTokenConnectOptions(options) {
+    if (!options.validate) {
+        return options.connectOptions;
+    }
+    return { ...options.connectOptions, forceRefresh: true };
+}
 async function buildTokenParams(options, principal) {
     const toSubject = options.principalToSubject ?? principalToSubject;
     return {

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { getToken, getTokenResponse, revokeToken, ConnectError, NoValidTokenError, UserAuthorizationRequiredError, ConnectorInstallationRequiredError, type ConnectErrorOptions, type ConnectOptions, type ConnectTokenParams, type ConnectTokenResponse, type ConnectTokenSubject, type ConnectVendorErrorPayload, } from './token.js';
+export { deleteTokenCacheEntry, getToken, getTokenResponse, revokeToken, ConnectError, NoValidTokenError, UserAuthorizationRequiredError, ConnectorInstallationRequiredError, type ConnectErrorOptions, type ConnectOptions, type ConnectTokenParams, type ConnectTokenResponse, type ConnectTokenSubject, type ConnectVendorErrorPayload, } from './token.js';
 export { startAuthorization, type ConnectAuthorizationOptions, type ConnectAuthorizationResponse, } from './authorization.js';
 export type { ConnectAuthorizationDetail } from './authorization-details.js';

package/dist/index.js

@@ -1,2 +1,2 @@
-export { getToken, getTokenResponse, revokeToken, ConnectError, NoValidTokenError, UserAuthorizationRequiredError, ConnectorInstallationRequiredError, } from './token.js';
+export { deleteTokenCacheEntry, getToken, getTokenResponse, revokeToken, ConnectError, NoValidTokenError, UserAuthorizationRequiredError, ConnectorInstallationRequiredError, } from './token.js';
 export { startAuthorization, } from './authorization.js';

package/dist/token.d.ts

@@ -80,6 +80,18 @@ export declare class ConnectorInstallationRequiredError extends ConnectError {
 }
 export interface ConnectOptions {
     vercelToken?: string;
+    /**
+     * Bypass the in-process token cache and re-fetch from Vercel Connect.
+     *
+     * The cache normally serves any token that is not within
+     * {@link ConnectTokenParams.validityBufferMs} of expiry. That means a
+     * grant the user revoked server-side keeps being handed back from the
+     * local cache until it expires. Set `forceRefresh` when the caller
+     * needs Connect to re-validate the grant on this call — a revoked grant
+     * then surfaces as `no_token` / `user_authorization_required` instead of
+     * a stale bearer.
+     */
+    forceRefresh?: boolean;
 }
 export declare function getToken(connector: string, params: ConnectTokenParams, options?: ConnectOptions): Promise<string>;
 export declare function getTokenResponse(connector: string, params: ConnectTokenParams, options?: ConnectOptions): Promise<ConnectTokenResponse>;
@@ -87,4 +99,22 @@ export declare function revokeToken(connector: string, params: {
     subject: ConnectTokenSubject;
     installationId?: string;
 }, options?: ConnectOptions): Promise<void>;
+/**
+ * Remove a single cached token entry for `(connector, params)` from the
+ * in-process cache.
+ *
+ * Targeted counterpart to {@link revokeToken}'s `cache.clear()`: it drops
+ * exactly the entry {@link getTokenResponse} would serve for these
+ * arguments, leaving every other connector/principal untouched. Use it
+ * when a credential is known to be bad (the resource server rejected the
+ * bearer with a `401`) so the next {@link getTokenResponse} re-fetches
+ * instead of re-serving the rejected token — without paying for a Connect
+ * round trip on every call the way {@link ConnectOptions.forceRefresh}
+ * does.
+ *
+ * The cache key is derived from `connector` plus every field of `params`,
+ * so pass the same `params` used for the original {@link getTokenResponse}
+ * call. No-op when no matching entry exists.
+ */
+export declare function deleteTokenCacheEntry(connector: string, params: ConnectTokenParams): void;
 export declare function createConnectErrorFromResponse(response: Response, fallbackMessage: string): Promise<ConnectError>;

package/dist/token.js

@@ -37,16 +37,21 @@ export async function getToken(connector, params, options) {
 }
 export async function getTokenResponse(connector, params, options) {
     const bufferMs = params.validityBufferMs ?? DEFAULT_VALIDITY_BUFFER_MS;
-    const cacheKey = JSON.stringify({ connector, ...params });
-    const cached = cache.get(cacheKey);
-    if (cached) {
-        const now = Date.now();
-        if (cached.response.expiresAt - now > bufferMs) {
-            cached.lastUsed = now;
-            return cached.response;
-        }
+    const cacheKey = tokenCacheKey(connector, params);
+    if (options?.forceRefresh) {
         cache.delete(cacheKey);
     }
+    else {
+        const cached = cache.get(cacheKey);
+        if (cached) {
+            const now = Date.now();
+            if (cached.response.expiresAt - now > bufferMs) {
+                cached.lastUsed = now;
+                return cached.response;
+            }
+            cache.delete(cacheKey);
+        }
+    }
     const vercelToken = options?.vercelToken ?? (await getVercelOidcToken());
     const endpoint = `https://api.vercel.com/v1/connect/token/${encodeURIComponent(connector)}`;
     const response = await fetch(endpoint, {
@@ -85,9 +90,37 @@ export async function revokeToken(connector, params, options) {
     }
     cache.clear();
 }
+/**
+ * Remove a single cached token entry for `(connector, params)` from the
+ * in-process cache.
+ *
+ * Targeted counterpart to {@link revokeToken}'s `cache.clear()`: it drops
+ * exactly the entry {@link getTokenResponse} would serve for these
+ * arguments, leaving every other connector/principal untouched. Use it
+ * when a credential is known to be bad (the resource server rejected the
+ * bearer with a `401`) so the next {@link getTokenResponse} re-fetches
+ * instead of re-serving the rejected token — without paying for a Connect
+ * round trip on every call the way {@link ConnectOptions.forceRefresh}
+ * does.
+ *
+ * The cache key is derived from `connector` plus every field of `params`,
+ * so pass the same `params` used for the original {@link getTokenResponse}
+ * call. No-op when no matching entry exists.
+ */
+export function deleteTokenCacheEntry(connector, params) {
+    cache.delete(tokenCacheKey(connector, params));
+}
 const DEFAULT_VALIDITY_BUFFER_MS = 30_000;
 const MAX_CACHE_SIZE = 100;
 const cache = new Map();
+/**
+ * Cache key for a `(connector, params)` pair. Stable across calls with
+ * equal arguments so {@link getTokenResponse} and
+ * {@link deleteTokenCacheEntry} address the same entry.
+ */
+function tokenCacheKey(connector, params) {
+    return JSON.stringify({ connector, ...params });
+}
 function evictLru() {
     let oldestKey;
     let oldestTime = Infinity;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/connect",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "license": "Apache-2.0",
   "type": "module",
   "repository": {