@vercel/oidc 3.0.5 → 3.2.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @vercel/oidc
 
+## 3.2.0
+
+### Minor Changes
+
+- - Add optional `team` and `project` parameters to `getVercelOidcToken()` to allow explicit control over token refresh behavior instead of always reading from `.vercel/project.json` ([#14864](https://github.com/vercel/vercel/pull/14864))
+  - Add `expirationBufferMs` option to both `getVercelOidcToken()` and `getVercelToken()` to proactively refresh tokens before they expire (useful for avoiding auth errors mid-request)
+  - Export `getVercelToken()` function with `GetVercelTokenOptions` interface to allow refreshing CLI tokens with configurable expiration buffer
+
+## 3.1.0
+
+### Minor Changes
+
+- Allow vercel/oidc to refresh the vercel CLI auth token when running locally ([#14543](https://github.com/vercel/vercel/pull/14543))
+
+### Patch Changes
+
+- improve error messages for package consumers ([#14449](https://github.com/vercel/vercel/pull/14449))
+
 ## 3.0.5
 
 ### Patch Changes

package/README.md

@@ -1,3 +1,41 @@
 # `@vercel/oidc`
 
 Runtime OIDC helper methods intended to be used with your Vercel Functions
+
+## Usage
+
+### Getting an OIDC Token
+
+```typescript
+import { getVercelOidcToken } from '@vercel/oidc';
+
+// Get token using project.json configuration
+const token = await getVercelOidcToken();
+
+// Get token with explicit project and team (supports both IDs and slugs)
+const token = await getVercelOidcToken({
+  project: 'my-project', // or 'prj_abc123'
+  team: 'my-team', // or 'team_xyz789'
+});
+
+// Get token with expiration buffer (refresh if expires within 5 minutes)
+const token = await getVercelOidcToken({
+  expirationBufferMs: 5 * 60 * 1000,
+});
+```
+
+## API
+
+### `getVercelOidcToken(options?)`
+
+Gets the current OIDC token from the request context or environment variable. Will refresh the token if expired in development.
+
+**Options:**
+
+- `project?: string` - Project ID (prj\_\*) or slug
+- `team?: string` - Team ID (team\_\*) or slug
+- `expirationBufferMs?: number` - Buffer time in ms before expiry to trigger refresh (default: 0)
+
+### `getVercelOidcTokenSync()`
+
+Synchronously gets the current OIDC token without refreshing. Use `getVercelOidcToken()` if you need automatic refresh in development.

package/dist/auth-config.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Auth configuration stored in ~/.../com.vercel.cli/auth.json
+ */
+export interface AuthConfig {
+    /** An `access_token` obtained using the OAuth Device Authorization flow. */
+    token?: string;
+    /** A `refresh_token` obtained using the OAuth Device Authorization flow. */
+    refreshToken?: string;
+    /**
+     * The absolute time (seconds) when the token expires.
+     * Used to optimistically check if the token is still valid.
+     */
+    expiresAt?: number;
+    /** Whether to skip writing this config to disk. */
+    skipWrite?: boolean;
+}
+/**
+ * Read the auth config from disk
+ * Returns null if the file doesn't exist or cannot be read
+ */
+export declare function readAuthConfig(): AuthConfig | null;
+/**
+ * Write the auth config to disk with proper permissions
+ */
+export declare function writeAuthConfig(config: AuthConfig): void;
+/**
+ * Check if an access token is valid (not expired)
+ * Copied from packages/cli/src/util/client.ts:72-81
+ */
+export declare function isValidAccessToken(authConfig: AuthConfig, expirationBufferMs?: number): boolean;

package/dist/auth-config.js

@@ -0,0 +1,85 @@
+"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 __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var auth_config_exports = {};
+__export(auth_config_exports, {
+  isValidAccessToken: () => isValidAccessToken,
+  readAuthConfig: () => readAuthConfig,
+  writeAuthConfig: () => writeAuthConfig
+});
+module.exports = __toCommonJS(auth_config_exports);
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var import_token_util = require("./token-util");
+function getAuthConfigPath() {
+  const dataDir = (0, import_token_util.getVercelDataDir)();
+  if (!dataDir) {
+    throw new Error(
+      `Unable to find Vercel CLI data directory. Your platform: ${process.platform}. Supported: darwin, linux, win32.`
+    );
+  }
+  return path.join(dataDir, "auth.json");
+}
+function readAuthConfig() {
+  try {
+    const authPath = getAuthConfigPath();
+    if (!fs.existsSync(authPath)) {
+      return null;
+    }
+    const content = fs.readFileSync(authPath, "utf8");
+    if (!content) {
+      return null;
+    }
+    return JSON.parse(content);
+  } catch (error) {
+    return null;
+  }
+}
+function writeAuthConfig(config) {
+  const authPath = getAuthConfigPath();
+  const authDir = path.dirname(authPath);
+  if (!fs.existsSync(authDir)) {
+    fs.mkdirSync(authDir, { mode: 504, recursive: true });
+  }
+  fs.writeFileSync(authPath, JSON.stringify(config, null, 2), { mode: 384 });
+}
+function isValidAccessToken(authConfig, expirationBufferMs = 0) {
+  if (!authConfig.token)
+    return false;
+  if (typeof authConfig.expiresAt !== "number")
+    return true;
+  const nowInSeconds = Math.floor(Date.now() / 1e3);
+  const bufferInSeconds = expirationBufferMs / 1e3;
+  return authConfig.expiresAt >= nowInSeconds + bufferInSeconds;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  isValidAccessToken,
+  readAuthConfig,
+  writeAuthConfig
+});

package/dist/auth-errors.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Error thrown when no authentication configuration is found.
+ * This typically means the user needs to log in.
+ */
+export declare class AccessTokenMissingError extends Error {
+    name: string;
+    constructor();
+}
+/**
+ * Error thrown when attempting to refresh the authentication token fails.
+ * This includes cases where no refresh token is available.
+ */
+export declare class RefreshAccessTokenFailedError extends Error {
+    name: string;
+    constructor(cause?: unknown);
+}

package/dist/auth-errors.js

@@ -0,0 +1,43 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var auth_errors_exports = {};
+__export(auth_errors_exports, {
+  AccessTokenMissingError: () => AccessTokenMissingError,
+  RefreshAccessTokenFailedError: () => RefreshAccessTokenFailedError
+});
+module.exports = __toCommonJS(auth_errors_exports);
+class AccessTokenMissingError extends Error {
+  constructor() {
+    super(
+      "No authentication found. Please log in with the Vercel CLI (vercel login)."
+    );
+    this.name = "AccessTokenMissingError";
+  }
+}
+class RefreshAccessTokenFailedError extends Error {
+  constructor(cause) {
+    super("Failed to refresh authentication token.", { cause });
+    this.name = "RefreshAccessTokenFailedError";
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AccessTokenMissingError,
+  RefreshAccessTokenFailedError
+});

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

@@ -1,3 +1,24 @@
+/**
+ * Options for getting the Vercel OIDC token.
+ */
+export interface GetVercelOidcTokenOptions {
+    /**
+     * 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`.
+     */
+    team?: string;
+    /**
+     * Optional project ID (prj_*) or slug to use for token refresh.
+     * When provided, this project will be used instead of reading from `.vercel/project.json`.
+     */
+    project?: string;
+    /**
+     * Optional time buffer in milliseconds before token expiry to consider it expired.
+     * When provided, the token will be refreshed if it expires within this buffer time.
+     * @default 0
+     */
+    expirationBufferMs?: number;
+}
 /**
  * Gets the current OIDC token from the request context or the environment variable.
  *
@@ -8,6 +29,7 @@
  *
  * 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
  * 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
@@ -23,8 +45,19 @@
  *   console.error('Error:', error.message);
  * });
  * ```
+ *
+ * @example
+ *
+ * ```js
+ * // Using the OIDC token with explicit team and project (supports IDs and slugs)
+ * getVercelOidcToken({ team: 'my-team', project: 'my-project' }).then((token) => {
+ *   console.log('OIDC Token:', token);
+ * }).catch((error) => {
+ *   console.error('Error:', error.message);
+ * });
+ * ```
  */
-export declare function getVercelOidcToken(): Promise<string>;
+export declare function getVercelOidcToken(options?: GetVercelOidcTokenOptions): Promise<string>;
 /**
  * Gets the current OIDC token from the request context or the environment variable.
  *

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

@@ -34,7 +34,7 @@ __export(get_vercel_oidc_token_exports, {
 module.exports = __toCommonJS(get_vercel_oidc_token_exports);
 var import_get_context = require("./get-context");
 var import_token_error = require("./token-error");
-async function getVercelOidcToken() {
+async function getVercelOidcToken(options) {
   let token = "";
   let err;
   try {
@@ -47,16 +47,20 @@ async function getVercelOidcToken() {
       await import("./token-util.js"),
       await import("./token.js")
     ]);
-    if (!token || isExpired(getTokenPayload(token))) {
-      await refreshToken();
+    if (!token || isExpired(getTokenPayload(token), options?.expirationBufferMs)) {
+      await refreshToken(options);
       token = getVercelOidcTokenSync();
     }
   } catch (error) {
-    if (err?.message && error instanceof Error) {
-      error.message = `${err.message}
+    let message = err instanceof Error ? err.message : "";
+    if (error instanceof Error) {
+      message = `${message}
 ${error.message}`;
     }
-    throw new import_token_error.VercelOidcTokenError(`Failed to refresh OIDC token`, error);
+    if (message) {
+      throw new import_token_error.VercelOidcTokenError(message);
+    }
+    throw error;
   }
   return token;
 }

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

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