@vercel/oidc 3.8.10 → 4.0.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @vercel/oidc
 
+## 4.0.1
+
+### Patch Changes
+
+- d032cfb: Add experimental Connect event delivery authentication scoped to project, environment, registered path, preview branch and delivery purpose, with envelope schema validation. Distinguish OIDC identity failures from temporary signing-key outages.
+
+  Preserve optional MCP event metadata and opaque cursors within the total delivery body limit.
+
+## 4.0.0
+
+### Major Changes
+
+- ec76b68: Read the Vercel OIDC token from the file specified by `VERCEL_OIDC_TOKEN_FILE` on each call.
+
 ## 3.8.10
 
 ### Patch Changes

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

@@ -48,18 +48,20 @@ export type GetVercelOidcTokenOptions = (GetVercelOidcTokenBaseOptions & {
     skipCache?: never;
 });
 /**
- * Gets the current OIDC token from the request context or the environment variable.
+ * Gets the current OIDC token from the request context, the Vercel OIDC token
+ * file, or the environment variable.
  *
  * Do not cache this value, as it is subject to change in production!
  *
- * This function is used to retrieve the OIDC token from the request context or the environment variable.
- * It checks for the `x-vercel-oidc-token` header in the request context and falls back to the `VERCEL_OIDC_TOKEN` environment variable if the header is not present.
+ * It checks for the `x-vercel-oidc-token` header in the request context, then
+ * reads the file named by `VERCEL_OIDC_TOKEN_FILE` when set, then falls back to
+ * the `VERCEL_OIDC_TOKEN` environment variable.
  *
  * Unlike the `getVercelOidcTokenSync` function, this function will refresh the token if it is expired in a development environment.
  *
  * @param {GetVercelOidcTokenOptions} [options] - Optional configuration for token retrieval.
  * @returns {Promise<string>} A promise that resolves to the OIDC token.
- * @throws {Error} If the `x-vercel-oidc-token` header is missing from the request context and the environment variable `VERCEL_OIDC_TOKEN` is not set. If the token
+ * @throws {Error} If no token source is available or the configured file cannot be read. If the token
  * is expired in a development environment, will also throw an error if the token cannot be refreshed: no CLI credentials are available, CLI credentials are expired, no project configuration is available
  * or the token refresh request fails.
  *

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

@@ -31,14 +31,17 @@ __export(get_vercel_oidc_token_with_refresh_exports, {
   getVercelOidcToken: () => getVercelOidcToken
 });
 module.exports = __toCommonJS(get_vercel_oidc_token_with_refresh_exports);
+var import_promises = require("node:fs/promises");
 var import_exchange_vercel_oidc_token = require("./exchange-vercel-oidc-token");
+var import_get_context = require("./get-context");
 var import_get_vercel_oidc_token_sync = require("./get-vercel-oidc-token-sync");
 var import_token_error = require("./token-error");
 async function getVercelOidcToken(options) {
   let token = "";
   let err;
+  const tokenFromFile = (0, import_get_context.getContext)().headers?.["x-vercel-oidc-token"] ? null : await tryOidcTokenFromFile();
   try {
-    token = (0, import_get_vercel_oidc_token_sync.getVercelOidcTokenSync)();
+    token = tokenFromFile ?? (0, import_get_vercel_oidc_token_sync.getVercelOidcTokenSync)();
   } catch (error) {
     err = error;
   }
@@ -72,6 +75,19 @@ ${error.message}`;
   }
   return token;
 }
+async function tryOidcTokenFromFile() {
+  const tokenFile = process.env.VERCEL_OIDC_TOKEN_FILE;
+  if (!tokenFile) {
+    return null;
+  }
+  const token = (await (0, import_promises.readFile)(tokenFile, "utf8")).trim();
+  if (!token) {
+    throw new import_token_error.VercelOidcTokenError(
+      `The Vercel OIDC token file is empty: ${tokenFile}`
+    );
+  }
+  return token;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   getVercelOidcToken

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

@@ -30,6 +30,9 @@ var import_token_io = require("./token-io");
 var import_cli_config = require("@vercel/cli-config");
 var import_get_vercel_oidc_token_with_refresh = require("./get-vercel-oidc-token-with-refresh");
 var tokenUtil = __toESM(require("./token-util"));
+const requestHeaders = import_vitest.vi.hoisted(() => ({
+  current: {}
+}));
 import_vitest.vi.mock("@vercel/cli-config", async (importOriginal) => ({
   ...await importOriginal(),
   getGlobalPathConfig: import_vitest.vi.fn(),
@@ -42,7 +45,7 @@ import_vitest.vi.mock("@vercel/cli-exec", () => ({
 }));
 import_vitest.vi.mock("./token-io");
 import_vitest.vi.mock("./get-context", () => ({
-  getContext: () => ({ headers: {} })
+  getContext: () => ({ headers: requestHeaders.current })
 }));
 (0, import_vitest.describe)("getVercelOidcToken - Error Scenarios", () => {
   let rootDir;
@@ -54,7 +57,9 @@ import_vitest.vi.mock("./get-context", () => ({
   (0, import_vitest.beforeEach)(() => {
     import_vitest.vi.clearAllMocks();
     import_vitest.vi.restoreAllMocks();
+    requestHeaders.current = {};
     process.env.VERCEL_OIDC_TOKEN = void 0;
+    delete process.env.VERCEL_OIDC_TOKEN_FILE;
     const random = `test-${(0, import_crypto.randomUUID)()}`;
     rootDir = path.join(os.tmpdir(), random);
     userDataDir = path.join(rootDir, "data");
@@ -198,6 +203,124 @@ import_vitest.vi.mock("./get-context", () => ({
     const token = await (0, import_get_vercel_oidc_token_with_refresh.getVercelOidcToken)();
     (0, import_vitest.expect)(token).toBe(validToken);
   });
+  (0, import_vitest.test)("reads the Vercel OIDC token file on each call after rotation", async () => {
+    delete process.env.VERCEL_OIDC_TOKEN;
+    const tokenFile = path.join(rootDir, "oidc-token");
+    process.env.VERCEL_OIDC_TOKEN_FILE = tokenFile;
+    const firstToken = createValidToken("first");
+    const secondToken = createValidToken("second");
+    fs.writeFileSync(tokenFile, `${firstToken}
+`);
+    (0, import_vitest.expect)(await (0, import_get_vercel_oidc_token_with_refresh.getVercelOidcToken)()).toBe(firstToken);
+    fs.writeFileSync(tokenFile, `${secondToken}
+`);
+    (0, import_vitest.expect)(await (0, import_get_vercel_oidc_token_with_refresh.getVercelOidcToken)()).toBe(secondToken);
+  });
+  (0, import_vitest.test)("prefers the advertised file over a static environment token", async () => {
+    process.env.VERCEL_OIDC_TOKEN = createValidToken("stale");
+    const tokenFile = path.join(rootDir, "oidc-token");
+    process.env.VERCEL_OIDC_TOKEN_FILE = tokenFile;
+    const currentToken = createValidToken("current");
+    fs.writeFileSync(tokenFile, currentToken);
+    const fetchSpy = import_vitest.vi.spyOn(globalThis, "fetch");
+    (0, import_vitest.expect)(
+      await (0, import_get_vercel_oidc_token_with_refresh.getVercelOidcToken)({
+        team: teamId,
+        project: projectId,
+        expirationBufferMs: 6e4
+      })
+    ).toBe(currentToken);
+    (0, import_vitest.expect)(fetchSpy).not.toHaveBeenCalled();
+  });
+  (0, import_vitest.test)("keeps the request token ahead of the advertised file", async () => {
+    const requestToken = createValidToken("request");
+    requestHeaders.current = { "x-vercel-oidc-token": requestToken };
+    process.env.VERCEL_OIDC_TOKEN_FILE = path.join(rootDir, "missing-token");
+    const fetchSpy = import_vitest.vi.spyOn(globalThis, "fetch");
+    (0, import_vitest.expect)(
+      await (0, import_get_vercel_oidc_token_with_refresh.getVercelOidcToken)({
+        team: teamId,
+        project: projectId,
+        expirationBufferMs: 6e4
+      })
+    ).toBe(requestToken);
+    (0, import_vitest.expect)(fetchSpy).not.toHaveBeenCalled();
+  });
+  (0, import_vitest.test)("includes the file path when the Vercel OIDC token file is empty", async () => {
+    delete process.env.VERCEL_OIDC_TOKEN;
+    const tokenFile = path.join(rootDir, "oidc-token");
+    process.env.VERCEL_OIDC_TOKEN_FILE = tokenFile;
+    fs.writeFileSync(tokenFile, " \n");
+    await (0, import_vitest.expect)((0, import_get_vercel_oidc_token_with_refresh.getVercelOidcToken)()).rejects.toThrow(
+      `The Vercel OIDC token file is empty: ${tokenFile}`
+    );
+  });
+  (0, import_vitest.test)("rejects a missing advertised token file instead of using the environment token", async () => {
+    process.env.VERCEL_OIDC_TOKEN = createValidToken("environment");
+    process.env.VERCEL_OIDC_TOKEN_FILE = path.join(rootDir, "missing-token");
+    await (0, import_vitest.expect)((0, import_get_vercel_oidc_token_with_refresh.getVercelOidcToken)()).rejects.toThrow("ENOENT");
+  });
+  (0, import_vitest.test)("refreshes an expired file token using the provided team and project", async () => {
+    delete process.env.VERCEL_OIDC_TOKEN;
+    const tokenFile = path.join(rootDir, "oidc-token");
+    process.env.VERCEL_OIDC_TOKEN_FILE = tokenFile;
+    fs.writeFileSync(tokenFile, createExpiredToken());
+    fs.writeFileSync(
+      path.join(cliDataDir, "auth.json"),
+      JSON.stringify({ token: "test-auth-token" })
+    );
+    const refreshedToken = createValidToken("refreshed");
+    const fetchSpy = import_vitest.vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({ token: refreshedToken }))
+    );
+    (0, import_vitest.expect)(await (0, import_get_vercel_oidc_token_with_refresh.getVercelOidcToken)({ team: teamId, project: projectId })).toBe(
+      refreshedToken
+    );
+    (0, import_vitest.expect)(fetchSpy).toHaveBeenCalledWith(
+      `https://api.vercel.com/v1/projects/${projectId}/token?source=vercel-oidc-refresh&teamId=${teamId}`,
+      import_vitest.expect.objectContaining({ method: "POST" })
+    );
+  });
+  (0, import_vitest.test)("refreshes a file token within the expiration buffer before audience exchange", async () => {
+    delete process.env.VERCEL_OIDC_TOKEN;
+    const tokenFile = path.join(rootDir, "oidc-token");
+    process.env.VERCEL_OIDC_TOKEN_FILE = tokenFile;
+    fs.writeFileSync(
+      tokenFile,
+      createValidToken("near-expiry", Math.floor(Date.now() / 1e3) + 30)
+    );
+    fs.writeFileSync(
+      path.join(cliDataDir, "auth.json"),
+      JSON.stringify({ token: "test-auth-token" })
+    );
+    const refreshedToken = createValidToken("refreshed");
+    const fetchSpy = import_vitest.vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(
+      new Response(JSON.stringify({ token: refreshedToken }))
+    ).mockResolvedValueOnce(
+      new Response(JSON.stringify({ token: "audience-specific-token" }))
+    );
+    (0, import_vitest.expect)(
+      await (0, import_get_vercel_oidc_token_with_refresh.getVercelOidcToken)({
+        team: teamId,
+        project: projectId,
+        expirationBufferMs: 6e4,
+        audience: "custom-audience",
+        jti: "custom-jti",
+        skipCache: true
+      })
+    ).toBe("audience-specific-token");
+    (0, import_vitest.expect)(fetchSpy).toHaveBeenCalledWith(
+      "https://oidc.vercel.com/~token",
+      import_vitest.expect.objectContaining({
+        method: "POST",
+        body: JSON.stringify({
+          token: refreshedToken,
+          aud: "custom-audience",
+          jti: "custom-jti"
+        })
+      })
+    );
+  });
   (0, import_vitest.test)("should refresh when token is expired but all configs are valid", async () => {
     fs.writeFileSync(
       path.join(cliDataDir, "auth.json"),
@@ -356,14 +479,14 @@ function createExpiredToken() {
   ).toString("base64url");
   return `${header}.${payload}.fake_signature`;
 }
-function createValidToken(value = "valid-token") {
+function createValidToken(value = "valid-token", expiresAt = Math.floor(Date.now() / 1e3) + 43200) {
   const header = Buffer.from(
     JSON.stringify({ alg: "RS256", typ: "JWT" })
   ).toString("base64url");
   const payload = Buffer.from(
     JSON.stringify({
       sub: "test-sub",
-      exp: Math.floor(Date.now() / 1e3) + 43200,
+      exp: expiresAt,
       iat: Math.floor(Date.now() / 1e3)
     })
   ).toString("base64url");

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

@@ -28,6 +28,13 @@ const VERCEL_OIDC_JWKS_URL = new URL(
 );
 const DEFAULT_ALGORITHMS = ["RS256"];
 const VERCEL_OIDC_JWKS = (0, import_jose.createRemoteJWKSet)(VERCEL_OIDC_JWKS_URL);
+class VercelOidcTokenValidationError extends TypeError {
+  constructor(message) {
+    super(message);
+    this.code = "ERR_VERCEL_OIDC_TOKEN_VALIDATION";
+    this.name = "VercelOidcTokenValidationError";
+  }
+}
 async function verifyVercelOidcToken(token, options) {
   const {
     algorithms,
@@ -72,7 +79,7 @@ function hasAudienceVerification(audience) {
 }
 function validateIssuer(actual) {
   if (actual !== VERCEL_OIDC_ISSUER && (typeof actual !== "string" || !actual.startsWith(`${VERCEL_OIDC_ISSUER}/`))) {
-    throw new TypeError(
+    throw new VercelOidcTokenValidationError(
       `Expected Vercel OIDC token iss claim to be "${VERCEL_OIDC_ISSUER}" or to start with "${VERCEL_OIDC_ISSUER}/".`
     );
   }
@@ -96,7 +103,7 @@ function validateClaim({
     return;
   }
   if (actual !== expected) {
-    throw new TypeError(
+    throw new VercelOidcTokenValidationError(
       Array.isArray(expected) ? `Expected Vercel OIDC token ${claim} claim to be one of: ${expected.map((value) => `"${value}"`).join(", ")}.` : `Expected Vercel OIDC token ${claim} claim to be "${expected}".`
     );
   }
@@ -110,7 +117,7 @@ function validateOptionalClaim({
     return;
   }
   if (actual !== expected) {
-    throw new TypeError(
+    throw new VercelOidcTokenValidationError(
       `Expected Vercel OIDC token ${claim} claim to be "${expected}".`
     );
   }

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

@@ -227,6 +227,17 @@ import_vitest.vi.mock("jose", () => ({
       "Expected VERCEL_PROJECT_ID to be set or projectId to be provided. Pass projectId: '*' to allow any project_id claim."
     );
   });
+  (0, import_vitest.test)("distinguishes token identity failures from signing-key outages", async () => {
+    mockVerifiedPayload({ project_id: "prj_other" });
+    const failure = (0, import_verify_vercel_oidc_token.verifyVercelOidcToken)("token");
+    await (0, import_vitest.expect)(failure).rejects.toBeInstanceOf(TypeError);
+    await (0, import_vitest.expect)(failure).rejects.toMatchObject({
+      code: "ERR_VERCEL_OIDC_TOKEN_VALIDATION"
+    });
+    const outage = new TypeError("fetch failed");
+    import_vitest.vi.mocked(import_jose.jwtVerify).mockRejectedValueOnce(outage);
+    await (0, import_vitest.expect)((0, import_verify_vercel_oidc_token.verifyVercelOidcToken)("token")).rejects.toBe(outage);
+  });
   (0, import_vitest.test)("rejects a token from a different owner", async () => {
     mockVerifiedPayload({
       owner_id: "team_other"

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const version = "3.8.10";
+export declare const version = "4.0.1";

package/dist/version.js

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

package/docs/functions/getVercelOidcToken.md

@@ -6,14 +6,16 @@
 
 > **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:96](https://github.com/vercel/vercel/blob/main/packages/oidc/src/get-vercel-oidc-token-with-refresh.ts#L96)
+Defined in: [packages/oidc/src/get-vercel-oidc-token-with-refresh.ts:100](https://github.com/vercel/vercel/blob/main/packages/oidc/src/get-vercel-oidc-token-with-refresh.ts#L100)
 
-Gets the current OIDC token from the request context or the environment variable.
+Gets the current OIDC token from the request context, the Vercel OIDC token
+file, or the environment variable.
 
 Do not cache this value, as it is subject to change in production!
 
-This function is used to retrieve the OIDC token from the request context or the environment variable.
-It checks for the `x-vercel-oidc-token` header in the request context and falls back to the `VERCEL_OIDC_TOKEN` environment variable if the header is not present.
+It checks for the `x-vercel-oidc-token` header in the request context, then
+reads the file named by `VERCEL_OIDC_TOKEN_FILE` when set, then falls back to
+the `VERCEL_OIDC_TOKEN` environment variable.
 
 Unlike the `getVercelOidcTokenSync` function, this function will refresh the token if it is expired in a development environment.
 
@@ -33,7 +35,7 @@ A promise that resolves to the OIDC token.
 
 ## Throws
 
-If the `x-vercel-oidc-token` header is missing from the request context and the environment variable `VERCEL_OIDC_TOKEN` is not set. If the token
+If no token source is available or the configured file cannot be read. If the token
 is expired in a development environment, will also throw an error if the token cannot be refreshed: no CLI credentials are available, CLI credentials are expired, no project configuration is available
 or the token refresh request fails.
 

package/docs/functions/verifyVercelOidcToken.md

@@ -6,7 +6,7 @@
 
 > **verifyVercelOidcToken**\<`PayloadType`\>(`token`, `options?`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`JWTVerifyResult`\<`PayloadType`\>\>
 
-Defined in: [packages/oidc/src/verify-vercel-oidc-token.ts:53](https://github.com/vercel/vercel/blob/main/packages/oidc/src/verify-vercel-oidc-token.ts#L53)
+Defined in: [packages/oidc/src/verify-vercel-oidc-token.ts:63](https://github.com/vercel/vercel/blob/main/packages/oidc/src/verify-vercel-oidc-token.ts#L63)
 
 Verifies a Vercel OIDC token against Vercel's remote JWKS.
 

package/docs/type-aliases/VercelOidcPayload.md

@@ -6,7 +6,7 @@
 
 > **VercelOidcPayload** = `JWTPayload` & `object`
 
-Defined in: [packages/oidc/src/verify-vercel-oidc-token.ts:16](https://github.com/vercel/vercel/blob/main/packages/oidc/src/verify-vercel-oidc-token.ts#L16)
+Defined in: [packages/oidc/src/verify-vercel-oidc-token.ts:26](https://github.com/vercel/vercel/blob/main/packages/oidc/src/verify-vercel-oidc-token.ts#L26)
 
 ## Type Declaration
 

package/package.json

@@ -18,7 +18,7 @@
       "require": "./dist/index.js"
     }
   },
-  "version": "3.8.10",
+  "version": "4.0.1",
   "repository": {
     "directory": "packages/oidc",
     "type": "git",