openai 7.4.0 → 7.6.0

package/src/auth/subject-token-providers.ts

@@ -1,3 +1,4 @@
+import type * as FsPromises from 'node:fs/promises';
 import type { SubjectTokenProvider } from './types';
 import type { Fetch } from '../internal/builtin-types';
 import * as Shims from '../internal/shims';
@@ -6,24 +7,181 @@ import { SubjectTokenProviderError } from '../core/error';
 const DEFAULT_RESOURCE = 'https://management.azure.com/';
 const DEFAULT_AZURE_API_VERSION = '2018-02-01';
 const AZURE_IMDS_BASE_URL = 'http://169.254.169.254/metadata/identity/oauth2/token';
+const MAX_AZURE_IMDS_JSON_ERROR_CAUSES = 32;
+const getOwnErrorDescriptor = Object.getOwnPropertyDescriptor;
+const getErrorPrototype = Object.getPrototypeOf;
+const errorObjectToString = Object.prototype.toString;
+const errorFunctionToString = Function.prototype.toString;
+const nativeErrorSource = errorFunctionToString.call(Error);
+const nativeSyntaxErrorSource = errorFunctionToString.call(SyntaxError);
+const nativeErrorBrandDescriptor = getOwnErrorDescriptor(Error, 'isError');
+const nativeErrorBrand =
+  nativeErrorBrandDescriptor &&
+  'value' in nativeErrorBrandDescriptor &&
+  typeof nativeErrorBrandDescriptor.value === 'function'
+    ? (nativeErrorBrandDescriptor.value as (error: object) => boolean)
+    : undefined;
 
+type AzureJSONErrorKind = 'error' | 'syntax' | 'tagged-wrapper' | 'unknown' | 'unsafe';
+
+function hasNativeErrorPrototype(prototype: object, kind: 'Error' | 'SyntaxError'): boolean {
+  const name = getOwnErrorDescriptor(prototype, 'name');
+  const constructor = getOwnErrorDescriptor(prototype, 'constructor');
+  if (
+    !name ||
+    !('value' in name) ||
+    name.value !== kind ||
+    !constructor ||
+    !('value' in constructor) ||
+    typeof constructor.value !== 'function'
+  ) {
+    return false;
+  }
+
+  const originalPrototype = getOwnErrorDescriptor(constructor.value, 'prototype');
+  const nativeSource = kind === 'Error' ? nativeErrorSource : nativeSyntaxErrorSource;
+  return Boolean(
+    originalPrototype &&
+    'value' in originalPrototype &&
+    originalPrototype.value === prototype &&
+    errorFunctionToString.call(constructor.value) === nativeSource,
+  );
+}
+
+function classifyCrossRealmAzureError(error: object): AzureJSONErrorKind {
+  try {
+    const prototypes: object[] = [];
+    let tagged = false;
+    for (
+      let prototype: object | null = error;
+      prototype !== null;
+      prototype = getErrorPrototype(prototype) as object | null
+    ) {
+      if (prototypes.length >= MAX_AZURE_IMDS_JSON_ERROR_CAUSES) {
+        return 'unsafe';
+      }
+      prototypes.push(prototype);
+      if (!nativeErrorBrand && getOwnErrorDescriptor(prototype, Symbol.toStringTag)) {
+        tagged = true;
+      }
+    }
+
+    if (
+      nativeErrorBrand
+        ? !nativeErrorBrand(error)
+        : !tagged && errorObjectToString.call(error) !== '[object Error]'
+    ) {
+      return 'unknown';
+    }
+
+    let genericErrorPrototype = false;
+    for (let index = 1; index < prototypes.length; index += 1) {
+      const prototype = prototypes[index];
+      if (!prototype) {
+        return 'unsafe';
+      }
+      if (hasNativeErrorPrototype(prototype, 'SyntaxError')) {
+        return tagged ? 'unsafe' : 'syntax';
+      }
+      if (tagged && hasNativeErrorPrototype(prototype, 'Error')) {
+        genericErrorPrototype = true;
+      }
+    }
+
+    if (!tagged) {
+      return 'error';
+    }
+    return genericErrorPrototype ? 'tagged-wrapper' : 'unknown';
+  } catch {
+    return 'unsafe';
+  }
+}
+
+function inspectAzureJSONErrorCause(error: unknown): boolean {
+  const visited = new Set<object>();
+  let current = error;
+
+  for (let depth = 0; depth < MAX_AZURE_IMDS_JSON_ERROR_CAUSES; depth += 1) {
+    if (current instanceof SyntaxError) {
+      return true;
+    }
+    if (typeof current !== 'object' || current === null) {
+      return false;
+    }
+    const kind = current instanceof Error ? 'error' : classifyCrossRealmAzureError(current);
+    if (kind === 'syntax' || kind === 'unsafe') {
+      return true;
+    }
+    if (kind !== 'error' && kind !== 'tagged-wrapper') {
+      return false;
+    }
+    if (kind === 'error') {
+      const parserType = getOwnErrorDescriptor(current, 'type');
+      if (parserType && 'value' in parserType && parserType.value === 'invalid-json') {
+        return true;
+      }
+    }
+    if (visited.has(current)) {
+      return true;
+    }
+    visited.add(current);
+
+    let cause: PropertyDescriptor | undefined;
+    try {
+      cause = getOwnErrorDescriptor(current, 'cause');
+    } catch {
+      return true;
+    }
+    if (!cause || !('value' in cause)) {
+      return false;
+    }
+    current = cause.value;
+  }
+
+  return true;
+}
+
+function isMalformedAzureJSONError(error: unknown): boolean {
+  try {
+    return inspectAzureJSONErrorCause(error);
+  } catch {
+    return true;
+  }
+}
+
+/** Reads the UTF-8 contents of a Kubernetes service-account token file. */
 type ReadFile = (path: string) => Promise<string>;
 
-let fsPromisesModule: Promise<typeof import('node:fs/promises')> | undefined;
+let fsPromisesModule: Promise<typeof FsPromises> | undefined;
 
 async function defaultReadFile(path: string): Promise<string> {
-  fsPromisesModule ??= import('fs/promises').catch((error) => {
+  fsPromisesModule ??= import('node:fs/promises').catch((error) => {
     fsPromisesModule = undefined;
     throw error;
   });
 
   const { readFile } = await fsPromisesModule;
-  return readFile(path, 'utf8');
+  return readFile(path, 'utf-8');
 }
 
+/**
+ * Reads a Kubernetes service-account JWT from its mounted token file.
+ *
+ * The file is read again for each token exchange so projected or rotated tokens
+ * are picked up automatically. The default reader requires Node.js filesystem
+ * access; provide `config.readFile` when using another compatible runtime.
+ *
+ * @param tokenPath Path to the token file; defaults to
+ * `/var/run/secrets/kubernetes.io/serviceaccount/token`.
+ * @param config Optional replacement for the default UTF-8 file reader.
+ * @returns A JWT subject-token provider suitable for `workloadIdentity.provider`.
+ * @throws {SubjectTokenProviderError} When the returned provider cannot read the
+ * token file or the file contains no token.
+ */
 export function k8sServiceAccountTokenProvider(
-  tokenPath: string = '/var/run/secrets/kubernetes.io/serviceaccount/token',
+  tokenPath = '/var/run/secrets/kubernetes.io/serviceaccount/token',
   config?: {
+    /** Reads token-file contents; defaults to Node.js `fs/promises.readFile`. */
     readFile?: ReadFile;
   },
 ): SubjectTokenProvider {
@@ -61,19 +219,45 @@ export function k8sServiceAccountTokenProvider(
   };
 }
 
+/**
+ * Retrieves an Azure managed-identity access token from the Instance Metadata Service.
+ *
+ * Run this provider in an Azure-hosted workload that can reach the link-local
+ * metadata endpoint. Select a user-assigned identity with `objectId`, `clientId`,
+ * or `msiResId`; otherwise Azure selects the available managed identity.
+ *
+ * @param resource Azure resource identifier; defaults to
+ * `https://management.azure.com/`.
+ * @param config Managed-identity selection, metadata API version, request
+ * timeout, and optional `fetch` implementation.
+ * @returns A JWT subject-token provider suitable for `workloadIdentity.provider`.
+ * @throws {SubjectTokenProviderError} When the returned provider cannot retrieve
+ * an access token, the metadata response is invalid, or the request times out.
+ */
 export function azureManagedIdentityTokenProvider(
   resource: string = DEFAULT_RESOURCE,
   config?: {
+    /** Object ID of the user-assigned managed identity to request. */
     objectId?: string;
+
+    /** Client ID of the user-assigned managed identity to request. */
     clientId?: string;
+
+    /** Azure resource ID of the user-assigned managed identity to request. */
     msiResId?: string;
+
+    /** Azure Instance Metadata Service API version; defaults to `2018-02-01`. */
     apiVersion?: string;
+
+    /** Metadata request timeout in milliseconds; defaults to 10,000. */
     timeout?: number;
+
+    /** Fetch implementation used for metadata requests; defaults to the runtime fetch. */
     fetch?: Fetch;
   },
 ): SubjectTokenProvider {
   const apiVersion = config?.apiVersion ?? DEFAULT_AZURE_API_VERSION;
-  const timeout = config?.timeout ?? 10000;
+  const timeout = config?.timeout ?? 10_000;
 
   return {
     tokenType: 'jwt',
@@ -104,13 +288,43 @@ export function azureManagedIdentityTokenProvider(
         });
 
         if (!response.ok) {
+          let abortListener: (() => void) | undefined;
+
+          try {
+            // oxlint-disable-next-line promise/avoid-new -- AbortSignal is callback-only across supported runtimes.
+            const requestAborted = new Promise<void>((resolve) => {
+              abortListener = () => resolve();
+              if (controller.signal.aborted) {
+                abortListener();
+              } else {
+                controller.signal.addEventListener('abort', abortListener, { once: true });
+              }
+            });
+
+            await Promise.race([Shims.CancelReadableStream(response.body), requestAborted]);
+          } catch {
+            controller.abort();
+          } finally {
+            if (abortListener) {
+              controller.signal.removeEventListener('abort', abortListener);
+            }
+          }
+
           throw new SubjectTokenProviderError(
             `Failed to fetch token from Azure IMDS: status ${response.status}`,
             'azure-imds',
           );
         }
 
-        const data = (await response.json()) as { access_token?: string };
+        let data: { access_token?: string };
+        try {
+          data = (await response.json()) as { access_token?: string };
+        } catch (error) {
+          if (isMalformedAzureJSONError(error)) {
+            throw new SyntaxError('IMDS response contains invalid JSON');
+          }
+          throw error;
+        }
 
         if (!data.access_token) {
           throw new SubjectTokenProviderError("IMDS response missing 'access_token' field", 'azure-imds');
@@ -133,11 +347,30 @@ export function azureManagedIdentityTokenProvider(
   };
 }
 
+/**
+ * Retrieves a Google Cloud identity token from the default service account's metadata endpoint.
+ *
+ * Run this provider in a Google Cloud workload with access to its Compute Engine
+ * metadata server. A fresh identity token is requested for each token exchange.
+ *
+ * @param audience Intended identity-token audience; defaults to
+ * `https://api.openai.com/v1`.
+ * @param config Optional metadata request timeout and `fetch` implementation.
+ * @returns An identity-token subject-token provider for `workloadIdentity.provider`.
+ * @throws {SubjectTokenProviderError} When the returned provider cannot retrieve
+ * a nonempty identity token or the metadata request times out.
+ */
 export function gcpIDTokenProvider(
-  audience: string = 'https://api.openai.com/v1',
-  config?: { timeout?: number; fetch?: Fetch },
+  audience = 'https://api.openai.com/v1',
+  config?: {
+    /** Metadata request timeout in milliseconds; defaults to 10,000. */
+    timeout?: number;
+
+    /** Fetch implementation used for metadata requests; defaults to the runtime fetch. */
+    fetch?: Fetch;
+  },
 ): SubjectTokenProvider {
-  const timeout = config?.timeout || 10000;
+  const timeout = config?.timeout ?? 10_000;
 
   return {
     tokenType: 'id',
@@ -159,11 +392,33 @@ export function gcpIDTokenProvider(
         });
 
         if (!response.ok) {
-          const errorText = await response.text();
-          throw new Error(`GCP Metadata Server returned ${response.status}: ${errorText}`);
+          let abortListener: (() => void) | undefined;
+
+          try {
+            // oxlint-disable-next-line promise/avoid-new -- AbortSignal is callback-only across supported runtimes.
+            const requestAborted = new Promise<void>((resolve) => {
+              abortListener = () => resolve();
+              if (controller.signal.aborted) {
+                abortListener();
+              } else {
+                controller.signal.addEventListener('abort', abortListener, { once: true });
+              }
+            });
+
+            await Promise.race([Shims.CancelReadableStream(response.body), requestAborted]);
+          } catch {
+            controller.abort();
+          } finally {
+            if (abortListener) {
+              controller.signal.removeEventListener('abort', abortListener);
+            }
+          }
+
+          throw new Error(`GCP Metadata Server returned ${response.status}`);
         }
 
-        const token = (await response.text()).trim();
+        const tokenText = await response.text();
+        const token = tokenText.trim();
         if (!token) {
           throw new Error('GCP metadata server returned an empty token');
         }

package/src/auth/types.ts

@@ -1,28 +1,65 @@
+/** Supplies a fresh external identity token for an OpenAI workload-identity exchange. */
 export interface SubjectTokenProvider {
+  /** Whether the provider returns a signed JWT or an OpenID Connect identity token. */
   tokenType: 'jwt' | 'id';
+
+  /** Returns a fresh subject token whenever the SDK needs to exchange or refresh its access token. */
   getToken: () => Promise<string>;
 }
 
+/** Configures federation from an external workload identity into an OpenAI service account. */
 export interface WorkloadIdentity {
-  /**Optional client identifier for token exchange compatibility.*/
+  /** Optional OAuth client identifier included in the token-exchange request. */
   clientId?: string;
 
-  /**Identity provider resource id in WIFAPI.*/
+  /** Identifier of the OpenAI identity-provider resource that trusts the external workload. */
   identityProviderId: string;
 
-  /**OpenAI Service account id to bind the verified external identity to.*/
+  /** Identifier of the OpenAI service account that receives the verified external identity. */
   serviceAccountId: string;
 
-  /**The provider configuration for obtaining the subject token.*/
+  /** Provider that obtains the external subject token for each token exchange. */
   provider: SubjectTokenProvider;
 
-  /**Optional buffer time in seconds to refresh the OpenAI token before it expires. Defaults to 1200 seconds (20 minutes).*/
+  /** Seconds before expiration when access-token refresh begins; defaults to 1,200 seconds. */
   refreshBufferSeconds?: number;
 }
 
+/** Configures OpenAI-only federation from an explicitly attested X.509 client certificate. */
+export interface X509WorkloadIdentity {
+  /** Selects certificate-authenticated OAuth federation without an external subject token. */
+  type: 'x509';
+
+  /** Identity-provider resource enrolled for the caller-owned client certificate. */
+  identityProviderId: string;
+
+  /** OpenAI service account authorized for the verified certificate identity. */
+  serviceAccountId: string;
+
+  /** Optional milliseconds before expiry when the certificate-backed token should refresh. */
+  refreshBufferMs?: number;
+
+  /** X.509 federation proves certificate possession instead of supplying a subject token. */
+  provider?: never;
+
+  /** X.509 federation does not send an OAuth client identifier. */
+  clientId?: never;
+
+  /** X.509 federation does not accept subject-token refresh configuration. */
+  refreshBufferSeconds?: never;
+}
+
+/** OAuth token-exchange response returned by the OpenAI workload-identity endpoint. */
 export interface TokenExchangeResponse {
+  /** OpenAI access token to use as the request's bearer credential. */
   access_token: string;
+
+  /** OAuth token-type URN describing the issued access token. */
   issued_token_type: string;
+
+  /** Authorization scheme associated with the access token, normally `Bearer`. */
   token_type: string;
+
+  /** Token lifetime in seconds; the SDK assumes 3,600 seconds when omitted. */
   expires_in?: number;
 }

package/src/auth/workload-identity-auth.ts

@@ -14,45 +14,171 @@ const SUBJECT_TOKEN_TYPES: Record<WorkloadIdentity['provider']['tokenType'], str
 };
 
 const TOKEN_EXCHANGE_GRANT_TYPE = 'urn:ietf:params:oauth:grant-type:token-exchange';
+const NATIVE_RESPONSE_PROTOTYPE = Response.prototype;
+const READ_NATIVE_RESPONSE_BODY = NATIVE_RESPONSE_PROTOTYPE.arrayBuffer;
 
+function isResponsePrototype(response: Response, prototype: object): boolean {
+  const constructor = Object.getOwnPropertyDescriptor(prototype, 'constructor')?.value;
+  if (
+    prototype === response ||
+    typeof constructor !== 'function' ||
+    Object.getOwnPropertyDescriptor(constructor, 'name')?.value !== 'Response' ||
+    Object.getOwnPropertyDescriptor(constructor, 'prototype')?.value !== prototype
+  ) {
+    return false;
+  }
+
+  const tag = Object.getOwnPropertyDescriptor(prototype, Symbol.toStringTag);
+  return (
+    (tag?.value === 'Response' || typeof tag?.get === 'function') &&
+    typeof Object.getOwnPropertyDescriptor(prototype, 'headers')?.get === 'function' &&
+    typeof Object.getOwnPropertyDescriptor(prototype, 'ok')?.get === 'function' &&
+    typeof Object.getOwnPropertyDescriptor(prototype, 'status')?.get === 'function'
+  );
+}
+
+function isResponseBodyPrototype(prototype: object, responsePrototype: object | null): boolean {
+  if (prototype === responsePrototype) {
+    return true;
+  }
+
+  const constructor = Object.getOwnPropertyDescriptor(prototype, 'constructor')?.value;
+  return (
+    responsePrototype !== null &&
+    Object.getPrototypeOf(responsePrototype) === prototype &&
+    typeof constructor === 'function' &&
+    Object.getOwnPropertyDescriptor(constructor, 'name')?.value === 'Body' &&
+    Object.getOwnPropertyDescriptor(constructor, 'prototype')?.value === prototype
+  );
+}
+
+function decodeNativeResponseBody(body: ArrayBuffer): string {
+  const scope = globalThis as typeof globalThis & { Bun?: { version?: unknown } };
+  return new TextDecoder('utf-8', { ignoreBOM: typeof scope.Bun?.version === 'string' }).decode(body);
+}
+
+async function parseOAuthTokenResponse(response: Response): Promise<unknown> {
+  let readText: ((this: Response) => Promise<string>) | undefined;
+  let responsePrototype: object | null = null;
+  for (
+    let depth = 0, prototype: object | null = response;
+    prototype !== null && depth < 16;
+    prototype = Object.getPrototypeOf(prototype), depth += 1
+  ) {
+    if (prototype === NATIVE_RESPONSE_PROTOTYPE) {
+      break;
+    }
+
+    if (isResponsePrototype(response, prototype)) {
+      responsePrototype = prototype;
+    }
+
+    const parser = Object.getOwnPropertyDescriptor(prototype, 'json');
+    if (!parser) {
+      continue;
+    }
+
+    if (typeof parser.value !== 'function') {
+      break;
+    }
+
+    const bodyReader = Object.getOwnPropertyDescriptor(prototype, 'text')?.value;
+    if (typeof bodyReader === 'function' && isResponseBodyPrototype(prototype, responsePrototype)) {
+      readText = bodyReader;
+      break;
+    }
+
+    // Custom parsers own their results and failures; rejection provenance cannot be inferred.
+    return parser.value.call(response);
+  }
+
+  const body =
+    readText === undefined
+      ? decodeNativeResponseBody(await READ_NATIVE_RESPONSE_BODY.call(response))
+      : await readText.call(response);
+  try {
+    return JSON.parse(body);
+  } catch {
+    throw new SyntaxError('Token exchange response contains invalid JSON');
+  }
+}
+
+function isUnsafeAccessToken(accessToken: string): boolean {
+  const scope = globalThis as typeof globalThis & { Bun?: { version?: unknown } };
+  if (typeof scope.Bun?.version === 'string') {
+    return /[^\t\u0020-\u007E]|^[\t ]|[\t ]$/u.test(accessToken);
+  }
+  return /[^\t\u0020-\u007E\u0080-\u00FF]|^[\t ]|[\t ]$/u.test(accessToken);
+}
+
+/**
+ * Exchanges external workload-identity tokens for cached OpenAI access tokens.
+ *
+ * Concurrent token exchanges are shared. Valid cached tokens are returned while
+ * a proactive refresh runs in the background; expired or missing tokens wait
+ * for a successful exchange before they are returned.
+ */
 export class WorkloadIdentityAuth {
   private cachedToken: CachedToken | null = null;
   private refreshPromise: Promise<string> | null = null;
+  private tokenGeneration = 0;
   private readonly config: WorkloadIdentity;
   private readonly tokenExchangeUrl: string = 'https://auth.openai.com/oauth/token';
   private readonly fetch: Fetch;
 
+  /**
+   * Creates a workload-identity token cache and OAuth token-exchange client.
+   *
+   * @param config External identity provider, OpenAI service account, and refresh settings.
+   * @param fetch Optional fetch implementation for calls to the OpenAI token endpoint.
+   */
   constructor(config: WorkloadIdentity, fetch?: Fetch) {
     this.config = config;
     this.fetch = fetch ?? Shims.getDefaultFetch();
   }
 
+  /**
+   * Returns a valid OpenAI access token, exchanging or refreshing credentials as needed.
+   *
+   * Cached tokens nearing expiration are returned immediately while a background
+   * refresh runs. Concurrent callers share the same in-flight token exchange.
+   *
+   * @throws {OAuthError} When the token endpoint rejects the subject token or identity.
+   * @throws {APIError} When another unsuccessful HTTP response prevents token exchange.
+   * @throws {OpenAIError} When a successful exchange has an invalid access token or expiration.
+   */
   async getToken(): Promise<string> {
-    if (!this.cachedToken || this.isTokenExpired(this.cachedToken)) {
+    if (!this.cachedToken || WorkloadIdentityAuth.isTokenExpired(this.cachedToken)) {
       if (this.refreshPromise) {
         return await this.refreshPromise;
       }
 
-      this.refreshPromise = this.refreshToken();
+      const refreshPromise = this.refreshToken(this.tokenGeneration);
+      this.refreshPromise = refreshPromise;
 
       try {
-        const token = await this.refreshPromise;
-        return token;
+        return await refreshPromise;
       } finally {
-        this.refreshPromise = null;
+        if (this.refreshPromise === refreshPromise) {
+          this.refreshPromise = null;
+        }
       }
     }
 
     if (this.needsRefresh(this.cachedToken) && !this.refreshPromise) {
-      this.refreshPromise = this.refreshToken().finally(() => {
-        this.refreshPromise = null;
+      const refreshPromise = this.refreshToken(this.tokenGeneration).finally(() => {
+        if (this.refreshPromise === refreshPromise) {
+          this.refreshPromise = null;
+        }
       });
+      this.refreshPromise = refreshPromise;
+      void refreshPromise.catch(() => null);
     }
 
     return this.cachedToken.token;
   }
 
-  private async refreshToken(): Promise<string> {
+  private async refreshToken(generation: number): Promise<string> {
     const subjectToken = await this.config.provider.getToken();
     const body: Record<string, string> = {
       grant_type: TOKEN_EXCHANGE_GRANT_TYPE,
@@ -72,6 +198,7 @@ export class WorkloadIdentityAuth {
         'Content-Type': 'application/json',
       },
       body: JSON.stringify(body),
+      redirect: 'manual',
     });
 
     if (!response.ok) {
@@ -80,7 +207,9 @@ export class WorkloadIdentityAuth {
 
       try {
         body = JSON.parse(errorText);
-      } catch {}
+      } catch {
+        // Ignore non-JSON error bodies.
+      }
 
       if (response.status === 400 || response.status === 401 || response.status === 403) {
         throw new OAuthError(response.status as 400 | 401 | 403, body, response.headers);
@@ -93,30 +222,41 @@ export class WorkloadIdentityAuth {
       );
     }
 
-    const tokenResponse: unknown = await response.json();
+    const tokenResponse: unknown = await parseOAuthTokenResponse(response);
+    const accessToken =
+      typeof tokenResponse === 'object' && tokenResponse !== null && 'access_token' in tokenResponse
+        ? tokenResponse.access_token
+        : undefined;
     if (
-      typeof tokenResponse !== 'object' ||
-      tokenResponse === null ||
-      !('access_token' in tokenResponse) ||
-      typeof tokenResponse.access_token !== 'string' ||
-      tokenResponse.access_token.trim().length === 0
+      typeof accessToken !== 'string' ||
+      accessToken.trim().length === 0 ||
+      isUnsafeAccessToken(accessToken)
     ) {
       throw new OpenAIError("Token exchange response missing 'access_token' field");
     }
 
-    const accessToken = tokenResponse.access_token;
     const expiresIn = (tokenResponse as Partial<TokenExchangeResponse>).expires_in ?? 3600;
-    const expiresAt = Date.now() + expiresIn * 1000;
+    if (typeof expiresIn !== 'number' || !Number.isFinite(expiresIn) || expiresIn <= 0) {
+      throw new OpenAIError("Token exchange response has invalid 'expires_in' field");
+    }
 
-    this.cachedToken = {
-      token: accessToken,
-      expiresAt,
-    };
+    const now = Date.now();
+    const expiresAt = now + expiresIn * 1000;
+    if (!Number.isSafeInteger(expiresAt) || expiresAt <= now) {
+      throw new OpenAIError("Token exchange response has invalid 'expires_in' field");
+    }
+
+    if (this.tokenGeneration === generation) {
+      this.cachedToken = {
+        token: accessToken,
+        expiresAt,
+      };
+    }
 
     return accessToken;
   }
 
-  private isTokenExpired(cachedToken: CachedToken): boolean {
+  private static isTokenExpired(cachedToken: CachedToken): boolean {
     return Date.now() >= cachedToken.expiresAt;
   }
 
@@ -126,7 +266,9 @@ export class WorkloadIdentityAuth {
     return Date.now() >= cachedToken.expiresAt - bufferMs;
   }
 
+  /** Discards the cached access token so the next request performs a fresh exchange. */
   invalidateToken(): void {
+    this.tokenGeneration += 1;
     this.cachedToken = null;
     this.refreshPromise = null;
   }