@vercel/oidc 3.7.1 → 3.8.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @vercel/oidc
 
+## 3.8.0
+
+### Minor Changes
+
+- d29a8f9: Cache exchanged OIDC tokens in memory, keyed by a hash of the source token, audience, and jti, so repeated exchanges reuse the result instead of calling the token-exchange endpoint every time. Cached tokens are evicted when the API-provided expiry passes, and the cache is bounded with least-recently-used eviction to avoid unbounded growth. Add a `skipCache` option (surfaced as `skipTokenCache` on `awsCredentialsProvider`) to bypass the cache. `jti` and the cache-skip flags are now only accepted alongside an `audience`, since they only take effect during a token exchange.
+
 ## 3.7.1
 
 ### Patch Changes

package/dist/exchange-vercel-oidc-token.d.ts

@@ -5,6 +5,7 @@
  * @property {string} token - The token to exchange.
  * @property {string} audience - Optional audience to set on the exchanged token.
  * @property {string} jti - Optional JTI to set on the exchanged token.
+ * @property {boolean} skipCache - Optional flag to bypass the in-memory cache.
  */
 export interface ExchangeVercelOidcTokenOptions {
     /**
@@ -21,6 +22,12 @@ export interface ExchangeVercelOidcTokenOptions {
      * @default undefined
      */
     jti?: string;
+    /**
+     * When `true`, bypasses the in-memory exchange cache and performs a fresh
+     * token exchange. The freshly exchanged token still replaces any cached entry.
+     * @default false
+     */
+    skipCache?: boolean;
 }
 /**
  * Exchanges a Vercel OIDC token for a Vercel token with a custom audience.
@@ -29,6 +36,7 @@ export interface ExchangeVercelOidcTokenOptions {
  * @param {string} options.token - The token to exchange.
  * @param {string} options.audience - Optional audience to set on the exchanged token.
  * @param {string} options.jti - Optional JTI to set on the exchanged token.
+ * @param {boolean} options.skipCache - Optional flag to bypass the in-memory cache and force a fresh exchange.
  * @throws {Error} If the token exchange fails.
  * @returns {Promise<string>} A promise that resolves to the exchanged token.
  */

package/dist/exchange-vercel-oidc-token.js

@@ -22,7 +22,66 @@ __export(exchange_vercel_oidc_token_exports, {
 });
 module.exports = __toCommonJS(exchange_vercel_oidc_token_exports);
 var import_version = require("./version");
+class TokenCache {
+  constructor(maxEntries) {
+    this.maxEntries = maxEntries;
+    this.entries = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Returns a cached token for the key when present and unexpired, refreshing
+   * its recency for LRU eviction. Expired entries are removed on access.
+   */
+  get(key) {
+    const entry = this.entries.get(key);
+    if (entry === void 0) {
+      return void 0;
+    }
+    if (entry.expiresAt <= Date.now()) {
+      this.entries.delete(key);
+      return void 0;
+    }
+    this.entries.delete(key);
+    this.entries.set(key, entry);
+    return entry.token;
+  }
+  /**
+   * Stores a token under the key and evicts the least-recently-used entries
+   * once the cache exceeds its size limit.
+   */
+  set({
+    key,
+    token,
+    expiresAt
+  }) {
+    this.entries.delete(key);
+    this.entries.set(key, { token, expiresAt });
+    while (this.entries.size > this.maxEntries) {
+      const oldest = this.entries.keys().next().value;
+      if (oldest === void 0) {
+        break;
+      }
+      this.entries.delete(oldest);
+    }
+  }
+}
+const MAX_CACHE_ENTRIES = 1e3;
+const tokenCache = new TokenCache(MAX_CACHE_ENTRIES);
+async function getCacheKey(options) {
+  const input = JSON.stringify([options.token, options.audience, options.jti]);
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(input)
+  );
+  return Array.from(new Uint8Array(digest)).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
 async function exchangeVercelOidcToken(options) {
+  const cacheKey = await getCacheKey(options);
+  if (!options.skipCache) {
+    const cached = tokenCache.get(cacheKey);
+    if (cached !== void 0) {
+      return cached;
+    }
+  }
   const response = await fetch("https://oidc.vercel.com/~token", {
     method: "POST",
     headers: {
@@ -52,7 +111,15 @@ async function exchangeVercelOidcToken(options) {
       "Failed to exchange token: response did not contain a token"
     );
   }
-  return data.token;
+  const { token } = data;
+  const expiry = "expiry" in data && typeof data.expiry === "number" ? data.expiry : void 0;
+  if (expiry !== void 0) {
+    const expiresAt = expiry * 1e3;
+    if (expiresAt > Date.now()) {
+      tokenCache.set({ key: cacheKey, token, expiresAt });
+    }
+  }
+  return token;
 }
 async function readErrorMessage(response) {
   try {

package/dist/exchange-vercel-oidc-token.test.d.ts

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

package/dist/exchange-vercel-oidc-token.test.js

@@ -0,0 +1,129 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var import_vitest = require("vitest");
+function jsonResponse(body, ok = true) {
+  return {
+    ok,
+    status: ok ? 200 : 400,
+    statusText: ok ? "OK" : "Bad Request",
+    json: async () => body
+  };
+}
+function futureExpiry(secondsFromNow = 3600) {
+  return Math.floor(Date.now() / 1e3) + secondsFromNow;
+}
+(0, import_vitest.describe)("exchangeVercelOidcToken", () => {
+  let fetchMock;
+  (0, import_vitest.beforeEach)(() => {
+    import_vitest.vi.resetModules();
+    fetchMock = import_vitest.vi.fn();
+    import_vitest.vi.stubGlobal("fetch", fetchMock);
+  });
+  (0, import_vitest.afterEach)(() => {
+    import_vitest.vi.unstubAllGlobals();
+    import_vitest.vi.useRealTimers();
+  });
+  async function loadExchange() {
+    const mod = await import("./exchange-vercel-oidc-token");
+    return mod.exchangeVercelOidcToken;
+  }
+  (0, import_vitest.it)("reuses the cached token when the API returns an expiry", async () => {
+    const exchange = await loadExchange();
+    fetchMock.mockResolvedValue(
+      jsonResponse({ token: "exchanged", expiry: futureExpiry() })
+    );
+    const first = await exchange({
+      token: "t",
+      audience: "https://a.example.com"
+    });
+    const second = await exchange({
+      token: "t",
+      audience: "https://a.example.com"
+    });
+    (0, import_vitest.expect)(first).toBe("exchanged");
+    (0, import_vitest.expect)(second).toBe("exchanged");
+    (0, import_vitest.expect)(fetchMock).toHaveBeenCalledTimes(1);
+  });
+  (0, import_vitest.it)("does not cache when the API omits the expiry", async () => {
+    const exchange = await loadExchange();
+    fetchMock.mockResolvedValue(jsonResponse({ token: "exchanged" }));
+    await exchange({ token: "t", audience: "https://a.example.com" });
+    await exchange({ token: "t", audience: "https://a.example.com" });
+    (0, import_vitest.expect)(fetchMock).toHaveBeenCalledTimes(2);
+  });
+  (0, import_vitest.it)("skipCache bypasses the cache but still refreshes it", async () => {
+    const exchange = await loadExchange();
+    fetchMock.mockResolvedValue(
+      jsonResponse({ token: "exchanged", expiry: futureExpiry() })
+    );
+    await exchange({ token: "t", audience: "https://a.example.com" });
+    await exchange({
+      token: "t",
+      audience: "https://a.example.com",
+      skipCache: true
+    });
+    await exchange({ token: "t", audience: "https://a.example.com" });
+    (0, import_vitest.expect)(fetchMock).toHaveBeenCalledTimes(2);
+  });
+  (0, import_vitest.it)("re-exchanges once the cached token has expired", async () => {
+    import_vitest.vi.useFakeTimers();
+    import_vitest.vi.setSystemTime(/* @__PURE__ */ new Date("2025-01-01T00:00:00Z"));
+    const exchange = await loadExchange();
+    fetchMock.mockResolvedValue(
+      jsonResponse({ token: "exchanged", expiry: futureExpiry(60) })
+    );
+    await exchange({ token: "t", audience: "https://a.example.com" });
+    import_vitest.vi.advanceTimersByTime(61e3);
+    await exchange({ token: "t", audience: "https://a.example.com" });
+    (0, import_vitest.expect)(fetchMock).toHaveBeenCalledTimes(2);
+  });
+  (0, import_vitest.it)("keys the cache by token, audience, and jti", async () => {
+    const exchange = await loadExchange();
+    fetchMock.mockResolvedValue(
+      jsonResponse({ token: "exchanged", expiry: futureExpiry() })
+    );
+    await exchange({ token: "t", audience: "https://a.example.com" });
+    await exchange({ token: "t", audience: "https://b.example.com" });
+    await exchange({ token: "t", audience: "https://a.example.com", jti: "x" });
+    await exchange({ token: "u", audience: "https://a.example.com" });
+    (0, import_vitest.expect)(fetchMock).toHaveBeenCalledTimes(4);
+  });
+  (0, import_vitest.it)("evicts the least-recently-used entry beyond the size limit", async () => {
+    const exchange = await loadExchange();
+    fetchMock.mockResolvedValue(
+      jsonResponse({ token: "exchanged", expiry: futureExpiry() })
+    );
+    for (let i = 0; i <= 1e3; i++) {
+      await exchange({
+        token: `token-${i}`,
+        audience: "https://a.example.com"
+      });
+    }
+    (0, import_vitest.expect)(fetchMock).toHaveBeenCalledTimes(1001);
+    await exchange({ token: "token-0", audience: "https://a.example.com" });
+    (0, import_vitest.expect)(fetchMock).toHaveBeenCalledTimes(1002);
+    await exchange({ token: "token-1000", audience: "https://a.example.com" });
+    (0, import_vitest.expect)(fetchMock).toHaveBeenCalledTimes(1002);
+  });
+});

package/dist/get-vercel-oidc-token-with-refresh.d.ts

@@ -1,8 +1,4 @@
-import { type ExchangeVercelOidcTokenOptions } from './exchange-vercel-oidc-token';
-/**
- * Options for getting the Vercel OIDC token.
- */
-export interface GetVercelOidcTokenOptions extends Omit<ExchangeVercelOidcTokenOptions, 'token'> {
+interface GetVercelOidcTokenBaseOptions {
     /**
      * Optional team ID (team_*) or slug to use for token refresh.
      * When provided, this team will be used instead of reading from `.vercel/project.json`.
@@ -20,6 +16,37 @@ export interface GetVercelOidcTokenOptions extends Omit<ExchangeVercelOidcTokenO
      */
     expirationBufferMs?: number;
 }
+/**
+ * Options for getting the Vercel OIDC token.
+ *
+ * `jti` and `skipCache` are only accepted when `audience` is provided, because
+ * they only take effect while exchanging the token for a custom audience —
+ * without an `audience` there is no exchange.
+ */
+export type GetVercelOidcTokenOptions = (GetVercelOidcTokenBaseOptions & {
+    /**
+     * Audience to set on the exchanged token.
+     */
+    audience: string;
+    /**
+     * Optional JTI to set on the exchanged token.
+     * @default undefined
+     */
+    jti?: string;
+    /**
+     * When `true`, bypasses the in-memory exchange cache and performs a fresh
+     * token exchange.
+     * @default false
+     */
+    skipCache?: boolean;
+}) | (GetVercelOidcTokenBaseOptions & {
+    /**
+     * @default undefined
+     */
+    audience?: undefined;
+    jti?: never;
+    skipCache?: never;
+});
 /**
  * Gets the current OIDC token from the request context or the environment variable.
  *
@@ -59,3 +86,4 @@ export interface GetVercelOidcTokenOptions extends Omit<ExchangeVercelOidcTokenO
  * ```
  */
 export declare function getVercelOidcToken(options?: GetVercelOidcTokenOptions): Promise<string>;
+export {};

package/dist/get-vercel-oidc-token-with-refresh.js

@@ -66,7 +66,8 @@ ${error.message}`;
     token = await (0, import_exchange_vercel_oidc_token.exchangeVercelOidcToken)({
       token,
       audience: options.audience,
-      jti: options.jti
+      jti: options.jti,
+      skipCache: options.skipCache
     });
   }
   return token;

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const version = "3.7.1";
+export declare const version = "3.8.0";

package/dist/version.js

@@ -21,7 +21,7 @@ __export(version_exports, {
   version: () => version
 });
 module.exports = __toCommonJS(version_exports);
-const version = "3.7.1";
+const version = "3.8.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   version

package/docs/functions/exchangeVercelOidcToken.md

@@ -6,7 +6,7 @@
 
 > **exchangeVercelOidcToken**(`options`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`string`\>
 
-Defined in: [packages/oidc/src/exchange-vercel-oidc-token.ts:38](https://github.com/vercel/vercel/blob/main/packages/oidc/src/exchange-vercel-oidc-token.ts#L38)
+Defined in: [packages/oidc/src/exchange-vercel-oidc-token.ts:138](https://github.com/vercel/vercel/blob/main/packages/oidc/src/exchange-vercel-oidc-token.ts#L138)
 
 Exchanges a Vercel OIDC token for a Vercel token with a custom audience.
 

package/docs/functions/getVercelOidcToken.md

@@ -6,7 +6,7 @@
 
 > **getVercelOidcToken**(`options?`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`string`\>
 
-Defined in: [packages/oidc/src/get-vercel-oidc-token-with-refresh.ts:69](https://github.com/vercel/vercel/blob/main/packages/oidc/src/get-vercel-oidc-token-with-refresh.ts#L69)
+Defined in: [packages/oidc/src/get-vercel-oidc-token-with-refresh.ts:96](https://github.com/vercel/vercel/blob/main/packages/oidc/src/get-vercel-oidc-token-with-refresh.ts#L96)
 
 Gets the current OIDC token from the request context or the environment variable.
 

package/docs/interfaces/ExchangeVercelOidcTokenOptions.md

@@ -4,7 +4,7 @@
 
 # Interface: ExchangeVercelOidcTokenOptions
 
-Defined in: [packages/oidc/src/exchange-vercel-oidc-token.ts:11](https://github.com/vercel/vercel/blob/main/packages/oidc/src/exchange-vercel-oidc-token.ts#L11)
+Defined in: [packages/oidc/src/exchange-vercel-oidc-token.ts:12](https://github.com/vercel/vercel/blob/main/packages/oidc/src/exchange-vercel-oidc-token.ts#L12)
 
 The options for the `exchangeVercelOidcToken` function.
 
@@ -14,7 +14,7 @@ The options for the `exchangeVercelOidcToken` function.
 
 > `optional` **audience?**: `string`
 
-Defined in: [packages/oidc/src/exchange-vercel-oidc-token.ts:20](https://github.com/vercel/vercel/blob/main/packages/oidc/src/exchange-vercel-oidc-token.ts#L20)
+Defined in: [packages/oidc/src/exchange-vercel-oidc-token.ts:21](https://github.com/vercel/vercel/blob/main/packages/oidc/src/exchange-vercel-oidc-token.ts#L21)
 
 Optional audience to set on the exchanged token.
 
@@ -24,16 +24,26 @@ Optional audience to set on the exchanged token.
 
 > `optional` **jti?**: `string`
 
-Defined in: [packages/oidc/src/exchange-vercel-oidc-token.ts:25](https://github.com/vercel/vercel/blob/main/packages/oidc/src/exchange-vercel-oidc-token.ts#L25)
+Defined in: [packages/oidc/src/exchange-vercel-oidc-token.ts:26](https://github.com/vercel/vercel/blob/main/packages/oidc/src/exchange-vercel-oidc-token.ts#L26)
 
 Optional JTI to set on the exchanged token.
 
 ---
 
+### skipCache?
+
+> `optional` **skipCache?**: `boolean`
+
+Defined in: [packages/oidc/src/exchange-vercel-oidc-token.ts:32](https://github.com/vercel/vercel/blob/main/packages/oidc/src/exchange-vercel-oidc-token.ts#L32)
+
+Optional flag to bypass the in-memory cache.
+
+---
+
 ### token
 
 > **token**: `string`
 
-Defined in: [packages/oidc/src/exchange-vercel-oidc-token.ts:15](https://github.com/vercel/vercel/blob/main/packages/oidc/src/exchange-vercel-oidc-token.ts#L15)
+Defined in: [packages/oidc/src/exchange-vercel-oidc-token.ts:16](https://github.com/vercel/vercel/blob/main/packages/oidc/src/exchange-vercel-oidc-token.ts#L16)
 
 The token to exchange.

package/package.json

@@ -18,7 +18,7 @@
       "require": "./dist/index.js"
     }
   },
-  "version": "3.7.1",
+  "version": "3.8.0",
   "repository": {
     "directory": "packages/oidc",
     "type": "git",
@@ -29,8 +29,8 @@
   },
   "dependencies": {
     "jose": "^5.9.6",
-    "@vercel/cli-config": "0.2.0",
-    "@vercel/cli-exec": "1.0.0"
+    "@vercel/cli-exec": "1.0.0",
+    "@vercel/cli-config": "0.2.0"
   },
   "devDependencies": {
     "prettier": "3.8.3",