@vercel/sandbox 0.0.17 → 0.0.19

package/src/utils/get-credentials.ts

@@ -1,4 +1,4 @@
-import { getVercelOidcTokenSync } from "@vercel/oidc";
+import { getVercelOidcToken } from "@vercel/oidc";
 import { decodeBase64Url } from "./decode-base64-url";
 import { z } from "zod";
 
@@ -28,13 +28,13 @@ export interface Credentials {
  * If both methods are used, the object properties take precedence over the
  * environment variable. If neither method is used, an error is thrown.
  */
-export function getCredentials<T>(params?: T | Credentials): Credentials {
+export async function getCredentials(params?: unknown): Promise<Credentials> {
   const credentials = getCredentialsFromParams(params ?? {});
   if (credentials) {
     return credentials;
   }
 
-  const oidcToken = getVercelOidcTokenSync();
+  const oidcToken = await getVercelOidcToken();
   if (oidcToken) {
     return getCredentialsFromOIDCToken(oidcToken);
   }
@@ -50,9 +50,12 @@ export function getCredentials<T>(params?: T | Credentials): Credentials {
  * required fields (`token`, `teamId`, and `projectId`) must be present
  * or none of them, otherwise an error is thrown.
  */
-function getCredentialsFromParams<Params extends Record<string, unknown>>(
-  params: Params | Credentials,
-): Credentials | null {
+function getCredentialsFromParams(params: unknown): Credentials | null {
+  // Type guard: params must be an object
+  if (!params || typeof params !== "object") {
+    return null;
+  }
+
   const missing = [
     "token" in params && typeof params.token === "string" ? null : "token",
     "teamId" in params && typeof params.teamId === "string" ? null : "teamId",
@@ -63,9 +66,9 @@ function getCredentialsFromParams<Params extends Record<string, unknown>>(
 
   if (missing.length === 0) {
     return {
-      token: params.token as string,
-      projectId: params.projectId as string,
-      teamId: params.teamId as string,
+      token: (params as any).token,
+      projectId: (params as any).projectId,
+      teamId: (params as any).teamId,
     };
   }
 
@@ -84,7 +87,9 @@ function getCredentialsFromParams<Params extends Record<string, unknown>>(
  * Schema to validate the payload of the Vercel OIDC token where we expect
  * to find the `teamId` and `projectId`.
  */
-const schema = z.object({
+export const schema = z.object({
+  exp: z.number().optional().describe("Expiry timestamp (seconds since epoch)"),
+  iat: z.number().optional().describe("Issued at timestamp"),
   owner_id: z.string(),
   project_id: z.string(),
 });

package/src/utils/jwt-expiry.test.ts

@@ -0,0 +1,125 @@
+import { assert, beforeEach, describe, expect, test, vi } from "vitest";
+import { JwtExpiry } from "./jwt-expiry";
+import type { getVercelOidcToken } from "@vercel/oidc";
+
+const { getVercelOidcTokenMock } = vi.hoisted(() => {
+  return {
+    getVercelOidcTokenMock: vi.fn<typeof getVercelOidcToken>(),
+  };
+});
+vi.mock("@vercel/oidc", () => ({
+  getVercelOidcToken: getVercelOidcTokenMock,
+}));
+beforeEach(() => {
+  getVercelOidcTokenMock.mockReset();
+});
+
+describe("JwtExpiry", () => {
+  test("refreshes a token", async () => {
+    const token = createMockJWT({
+      owner_id: "team1",
+      project_id: "proj1",
+    });
+    getVercelOidcTokenMock.mockImplementationOnce(async () => "hello world");
+    const expiry = await JwtExpiry.fromToken(token)?.refresh();
+    expect(expiry).toBeInstanceOf(JwtExpiry);
+    expect(expiry?.token).toEqual("hello world");
+  });
+
+  test("isValid returns true for tokens without expiry", () => {
+    // Mock token without exp field (like OIDC tokens without exp)
+    const tokenWithoutExp = createMockJWT({
+      owner_id: "team1",
+      project_id: "proj1",
+    });
+    const expiry = JwtExpiry.fromToken(tokenWithoutExp);
+    assert(expiry, "Expiry should not be null for valid JWT");
+    expect(expiry.isValid()).toBe(false); // No exp field means malformed JWT
+  });
+
+  test("isValid returns true for unexpired tokens", () => {
+    const futureTime = Math.floor(Date.now() / 1000) + 3600; // 1 hour from now
+    const tokenValid = createMockJWT({
+      owner_id: "team1",
+      project_id: "proj1",
+      exp: futureTime,
+    });
+    const expiry = JwtExpiry.fromToken(tokenValid);
+    assert(expiry, "Expiry should not be null for valid JWT");
+    expect(expiry.isValid()).toBe(true);
+  });
+
+  test("isValid returns false for expired tokens", () => {
+    const pastTime = Math.floor(Date.now() / 1000) - 3600; // 1 hour ago
+    const tokenExpired = createMockJWT({
+      owner_id: "team1",
+      project_id: "proj1",
+      exp: pastTime,
+    });
+    const expiry = JwtExpiry.fromToken(tokenExpired);
+    assert(expiry, "Expiry should not be null for valid JWT");
+    expect(expiry.isValid()).toBe(false);
+  });
+
+  test("isValid returns false for tokens expiring within buffer time", () => {
+    const soonTime = Math.floor(Date.now() / 1000) + 120; // 2 minutes from now
+    const tokenExpiringSoon = createMockJWT({
+      owner_id: "team1",
+      project_id: "proj1",
+      exp: soonTime,
+    });
+    const expiry = JwtExpiry.fromToken(tokenExpiringSoon);
+    assert(expiry, "Expiry should not be null for valid JWT");
+    expect(expiry.isValid(5)).toBe(false); // 5 minute buffer
+  });
+
+  test("isValid returns false for malformed JWT tokens", () => {
+    const expiry = JwtExpiry.fromToken("header.invalid-payload.signature");
+    assert(expiry, "Expiry should not be null for valid JWT");
+    expect(expiry.isValid()).toBe(false);
+  });
+
+  test("getExpiryDate returns correct expiry date", () => {
+    const expTime = Math.floor(Date.now() / 1000) + 3600; // 1 hour from now
+    const token = createMockJWT({
+      owner_id: "team1",
+      project_id: "proj1",
+      exp: expTime,
+    });
+    const expiry = JwtExpiry.fromToken(token);
+    assert(expiry, "Expiry should not be null for valid JWT");
+    expect(expiry.getExpiryDate()).toEqual(new Date(expTime * 1000));
+  });
+
+  test("getExpiryDate returns null for tokens without expiry", () => {
+    const token = createMockJWT({ owner_id: "team1", project_id: "proj1" });
+    const expiry = JwtExpiry.fromToken(token);
+    assert(expiry, "Expiry should not be null for valid JWT");
+    expect(expiry.getExpiryDate()).toBeNull();
+  });
+
+  test("getExpiryDate returns null for malformed tokens", () => {
+    const token = "hello.world.hey";
+    const expiry = JwtExpiry.fromToken(token);
+    assert(expiry, "Expiry should not be null for valid JWT");
+    expect(expiry.getExpiryDate()).toBeNull();
+  });
+
+  test("returns null for non-JWT style tokens", () => {
+    expect(JwtExpiry.fromToken("personal-access-token")).toBeNull();
+  });
+});
+
+// Helper function to create mock JWT tokens for testing
+function createMockJWT(payload: any): string {
+  const header = { typ: "JWT", alg: "HS256" };
+  const encodedHeader = Buffer.from(JSON.stringify(header)).toString(
+    "base64url",
+  );
+  const encodedPayload = Buffer.from(JSON.stringify(payload)).toString(
+    "base64url",
+  );
+  const signature = "mock-signature";
+
+  return `${encodedHeader}.${encodedPayload}.${signature}`;
+}

package/src/utils/jwt-expiry.ts

@@ -0,0 +1,105 @@
+import { z } from "zod";
+import { decodeBase64Url } from "./decode-base64-url";
+import { schema } from "./get-credentials";
+import { getVercelOidcToken } from "@vercel/oidc";
+import ms from "ms";
+
+/** Time buffer before token expiry to consider it invalid (in milliseconds) */
+const BUFFER_MS = ms("5m");
+
+export class OidcRefreshError extends Error {
+  name = "OidcRefreshError";
+}
+
+/**
+ * Expiry implementation for JWT tokens (OIDC tokens).
+ * Parses the JWT once and provides fast expiry validation.
+ */
+export class JwtExpiry {
+  private expiryTime: number | null; // Unix timestamp in seconds
+  readonly payload?: Readonly<z.infer<typeof schema>>;
+
+  static fromToken(token: string): JwtExpiry | null {
+    if (!isJwtFormat(token)) {
+      return null;
+    } else {
+      return new JwtExpiry(token);
+    }
+  }
+
+  /**
+   * Creates a new JWT expiry checker.
+   *
+   * @param token - The JWT token to parse
+   */
+  constructor(readonly token: string) {
+    try {
+      const tokenContents = token.split(".")[1];
+      this.payload = schema.parse(decodeBase64Url(tokenContents));
+      this.expiryTime = this.payload.exp || null;
+    } catch {
+      // Malformed token - treat as expired to trigger refresh
+      this.expiryTime = 0;
+    }
+  }
+
+  /**
+   * Checks if the JWT token is valid (not expired).
+   * @returns true if token is valid, false if expired or expiring soon
+   */
+  isValid(): boolean {
+    if (this.expiryTime === null) {
+      return false; // No expiry means malformed JWT
+    }
+
+    const now = Math.floor(Date.now() / 1000);
+    const buffer = BUFFER_MS / 1000;
+    return now + buffer < this.expiryTime;
+  }
+
+  /**
+   * Gets the expiry date of the JWT token.
+   *
+   * @returns Date object representing when the token expires, or null if no expiry
+   */
+  getExpiryDate(): Date | null {
+    return this.expiryTime ? new Date(this.expiryTime * 1000) : null;
+  }
+
+  /**
+   * Refreshes the JWT token by fetching a new OIDC token.
+   *
+   * @returns Promise resolving to a new JwtExpiry instance with fresh token
+   */
+  async refresh(): Promise<JwtExpiry> {
+    try {
+      const freshToken = await getVercelOidcToken();
+      return new JwtExpiry(freshToken);
+    } catch (cause) {
+      throw new OidcRefreshError("Failed to refresh OIDC token", {
+        cause,
+      });
+    }
+  }
+
+  /**
+   * Refreshes the JWT token if it's expired or expiring soon.
+   */
+  async tryRefresh(): Promise<JwtExpiry | null> {
+    if (this.isValid()) {
+      return null; // Still valid, no need to refresh
+    }
+
+    return this.refresh();
+  }
+}
+
+/**
+ * Checks if a token follows JWT format (has 3 parts separated by dots).
+ *
+ * @param token - The token to check
+ * @returns true if token appears to be a JWT, false otherwise
+ */
+function isJwtFormat(token: string): boolean {
+  return token.split(".").length === 3;
+}

package/src/utils/types.test.js

@@ -0,0 +1,7 @@
+import { expect, it } from "vitest";
+import { getPrivateParams } from "./types";
+
+it("getPrivateParams filters unknown params", async () => {
+  const result = getPrivateParams({ foo: 123, __someParam: "abc" });
+  expect(result).toEqual({ __someParam: "abc" });
+});

package/src/utils/types.ts

@@ -0,0 +1,23 @@
+/**
+ * Utility type that extends a type to accept private parameters.
+ *
+ * The private parameters can then be extracted out of the object using
+ * `getPrivateParams`.
+ */
+export type WithPrivate<T> = T & {
+  [K in `__${string}`]?: unknown;
+};
+
+/**
+ * Extract private parameters out of an object.
+ */
+export const getPrivateParams = (params?: object) => {
+  const privateEntries = Object.entries(params ?? {}).filter(([k]) =>
+    k.startsWith("__"),
+  );
+  return Object.fromEntries(privateEntries) as {
+    [K in keyof typeof params as K extends `__${string}`
+      ? K
+      : never]: (typeof params)[K];
+  };
+};

package/src/version.ts

@@ -1,2 +1,2 @@
 // Autogenerated by inject-version.ts
-export const VERSION = "0.0.17";
+export const VERSION = "0.0.19";

package/turbo.json

@@ -0,0 +1,9 @@
+{
+  "extends": ["//"],
+  "tasks": {
+    "version:bump": {
+      "inputs": ["package.json"],
+      "outputs": ["src/version.ts"]
+    }
+  }
+}