openai 7.5.0 → 7.7.0

package/src/client.ts

@@ -3,7 +3,7 @@
 import type { RequestInit, RequestInfo, BodyInit } from './internal/builtin-types';
 import type { HTTPMethod, PromiseOrValue, MergedRequestInit, FinalizedRequestInit } from './internal/types';
 import { uuid4 } from './internal/utils/uuid';
-import { validatePositiveInteger, isAbsoluteURL, safeJSON } from './internal/utils/values';
+import { validatePositiveInteger, isAbsoluteURL, safeJSON, hasOwn } from './internal/utils/values';
 import { sleep } from './internal/utils/sleep';
 export type { Logger, LogLevel } from './internal/utils/log';
 import { castToError, isAbortError } from './internal/errors';
@@ -13,10 +13,22 @@ import * as Shims from './internal/shims';
 import * as Opts from './internal/request-options';
 import { stringifyQuery } from './internal/utils/query';
 import { VERSION } from './version';
+import { resolveDataResidency, type DataResidency } from './internal/data-residency';
+export type { DataResidency } from './internal/data-residency';
 import * as Errors from './core/error';
 import * as Pagination from './core/pagination';
-import type { WorkloadIdentity } from './auth/types';
+import type { WorkloadIdentity, X509WorkloadIdentity } from './auth/types';
 import { WorkloadIdentityAuth } from './auth/workload-identity-auth';
+import {
+  X509_API_BASE_URL,
+  X509WorkloadIdentityAuth,
+  assertX509APIOrigin,
+  assertX509RequestOptions,
+  isX509WorkloadIdentity,
+  snapshotX509RequestOptions,
+} from './internal/auth/x509-workload-identity-auth';
+import type { X509Transport } from './internal/auth/x509-transport-registry';
+import { isTransientX509ConnectionError, markApprovedX509Client } from '#x509-transport-state';
 import { OAuthError, SubjectTokenProviderError } from './core/error';
 import {
   type ConversationCursorPageParams,
@@ -269,6 +281,8 @@ function isRunningInBrowserOrBrowserWorker(): boolean {
 }
 
 const WORKLOAD_IDENTITY_API_KEY_PLACEHOLDER = 'workload-identity-auth';
+const inheritedDataResidencySelection = Symbol('inheritedDataResidencySelection');
+type InternalClientOptions = ClientOptions & { [inheritedDataResidencySelection]?: boolean };
 
 export type ApiKeySetter = () => Promise<string>;
 
@@ -314,6 +328,14 @@ export interface ClientOptions {
    */
   baseURL?: string | null | undefined;
 
+  /**
+   * Select an OpenAI regional endpoint. This overrides an inherited or environment
+   * base URL and is mutually exclusive with an explicit `baseURL` or `provider`.
+   * Availability depends on your project and model; no fallback is performed.
+   * `null` and `undefined` leave ordinary base URL resolution unchanged.
+   */
+  dataResidency?: DataResidency | null | undefined;
+
   /**
    * The maximum amount of time (in milliseconds) that the client should wait for a response
    * from the server before timing out a single request.
@@ -403,7 +425,10 @@ export interface ClientOptions {
    * Workload identity configuration for OAuth2 token exchange authentication.
    * Mutually exclusive with `apiKey`.
    */
-  workloadIdentity?: WorkloadIdentity | undefined;
+  workloadIdentity?: WorkloadIdentity | X509WorkloadIdentity | undefined;
+
+  /** Approved, frozen Node.js certificate transport required only for X.509 workload identity. */
+  x509Transport?: X509Transport | undefined;
 
   /**
    * Configure this client to use a third-party API provider.
@@ -431,11 +456,25 @@ export class OpenAI {
 
   private fetch: Fetch;
   #encoder: Opts.RequestEncoder;
-  #responseAttempts = new WeakMap<AbortController, { timeout: number; retriesRemaining: number }>();
+  #x509Authentication: X509WorkloadIdentityAuth | undefined;
+  #x509Fetch: Fetch | undefined;
+  // Preserve an explicit global selection without storing a second routing URL.
+  #explicitDataResidency = false;
+  #responseAttempts = new WeakMap<
+    AbortController,
+    {
+      timeout: number;
+      retriesRemaining: number;
+      hasStreamingBody: boolean;
+      authentication?: X509WorkloadIdentityAuth;
+      helperMethod?: unknown;
+      continueRequest?: <T>(operation: () => Promise<T>) => Promise<T>;
+    }
+  >();
   protected idempotencyHeader?: string;
   protected _options: ClientOptions;
   private _provider: ProviderRuntime | undefined;
-  private _workloadIdentityAuth?: WorkloadIdentityAuth;
+  private _workloadIdentityAuth?: WorkloadIdentityAuth | X509WorkloadIdentityAuth;
 
   /**
    * API Client for interfacing with the OpenAI API.
@@ -456,30 +495,38 @@ export class OpenAI {
    * @param {boolean} [opts.dangerouslyAllowBrowser=false] - By default, client-side use of this library is not allowed, as it risks exposing your secret API credentials to attackers.
    */
   constructor(clientOptions: ClientOptions = {}) {
+    const residencyBaseURL = resolveDataResidency(clientOptions);
     const provider = clientOptions.provider;
-    if (provider) {
-      const conflictingOptions = (['apiKey', 'adminAPIKey', 'workloadIdentity', 'baseURL'] as const).filter(
-        (key) => clientOptions[key] != null,
-      );
-      if (conflictingOptions.length) {
-        throw new Errors.OpenAIError(
-          `The \`provider\` option cannot be used with ${conflictingOptions
-            .map((key) => `\`${key}\``)
-            .join(', ')}. Configure authentication and the base URL through the provider instead.`,
-        );
-      }
-    }
-
     const {
       baseURL = provider ? null : readEnv('OPENAI_BASE_URL'),
+      dataResidency: _dataResidency,
+      [inheritedDataResidencySelection]: inheritedResidencySelection = false,
       apiKey = provider ? null : (readEnv('OPENAI_API_KEY') ?? null),
       adminAPIKey = provider ? null : (readEnv('OPENAI_ADMIN_KEY') ?? null),
       organization = provider ? null : (readEnv('OPENAI_ORG_ID') ?? null),
       project = provider ? null : (readEnv('OPENAI_PROJECT_ID') ?? null),
       webhookSecret = readEnv('OPENAI_WEBHOOK_SECRET') ?? null,
       workloadIdentity,
+      x509Transport,
       ...opts
-    } = clientOptions;
+    } = clientOptions as InternalClientOptions;
+    if (provider) {
+      const conflictingOptions = (
+        ['apiKey', 'adminAPIKey', 'workloadIdentity', 'x509Transport', 'baseURL', 'dataResidency'] as const
+      ).filter((key) => (key === 'workloadIdentity' ? workloadIdentity : clientOptions[key]) != null);
+      if (conflictingOptions.length) {
+        throw new Errors.OpenAIError(
+          `The \`provider\` option cannot be used with ${conflictingOptions
+            .map((key) => `\`${key}\``)
+            .join(', ')}. Configure authentication and the base URL through the provider instead.`,
+        );
+      }
+    }
+    const identity = isX509WorkloadIdentity(workloadIdentity)
+      ? { x509: workloadIdentity, legacy: undefined }
+      : { x509: undefined, legacy: workloadIdentity };
+    const x509Identity = identity.x509;
+    const usesX509Identity = x509Identity !== undefined;
     const providerRuntime = provider ? configureProvider(provider) : undefined;
     const options: ClientOptions = {
       apiKey,
@@ -488,11 +535,40 @@ export class OpenAI {
       project,
       webhookSecret,
       workloadIdentity,
+      x509Transport,
       provider,
       ...opts,
-      baseURL: providerRuntime?.baseURL ?? (baseURL || `https://api.openai.com/v1`),
+      baseURL:
+        providerRuntime?.baseURL ??
+        residencyBaseURL ??
+        (baseURL || (usesX509Identity ? X509_API_BASE_URL : `https://api.openai.com/v1`)),
     };
 
+    if (x509Transport && !usesX509Identity) {
+      throw new Errors.OpenAIError('An X.509 transport requires an X.509 workload identity.');
+    }
+
+    if (usesX509Identity) {
+      if (residencyBaseURL !== undefined || inheritedResidencySelection) {
+        throw new Errors.OpenAIError('X.509 workload identity does not support data residency selection.');
+      }
+      if (clientOptions.fetch !== undefined) {
+        throw new Errors.OpenAIError(
+          'X.509 workload identity does not support a custom fetch implementation.',
+        );
+      }
+      assertX509APIOrigin(options.baseURL!);
+      assertX509RequestOptions(options.fetchOptions);
+      if (
+        this.fetchWithAuth !== OpenAI.prototype.fetchWithAuth ||
+        this.fetchWithTimeout !== OpenAI.prototype.fetchWithTimeout
+      ) {
+        throw new Errors.OpenAIError(
+          'X.509 workload identity does not support overridden fetch dispatch hooks.',
+        );
+      }
+    }
+
     if (apiKey && workloadIdentity) {
       throw new Errors.OpenAIError('The `apiKey` and `workloadIdentity` options are mutually exclusive');
     }
@@ -510,6 +586,7 @@ export class OpenAI {
     }
 
     this.baseURL = options.baseURL!;
+    this.#explicitDataResidency = residencyBaseURL !== undefined || inheritedResidencySelection;
     this.timeout = options.timeout ?? OpenAI.DEFAULT_TIMEOUT; /* 10 minutes */
     this.logger = options.logger ?? console;
     const defaultLogLevel = 'warn';
@@ -539,8 +616,15 @@ export class OpenAI {
     this._options = options;
     this._provider = providerRuntime;
 
-    if (workloadIdentity) {
-      this._workloadIdentityAuth = new WorkloadIdentityAuth(workloadIdentity, this.fetch);
+    if (x509Identity) {
+      const authentication = new X509WorkloadIdentityAuth(x509Identity, x509Transport, organization, project);
+      this._workloadIdentityAuth = authentication;
+      this.#x509Authentication = authentication;
+      this.#x509Fetch = authentication.fetch();
+      this.fetch = this.#x509Fetch;
+      markApprovedX509Client(this);
+    } else if (identity.legacy) {
+      this._workloadIdentityAuth = new WorkloadIdentityAuth(identity.legacy, this.fetch);
     }
 
     this.apiKey = typeof apiKey === 'string' ? apiKey : null;
@@ -554,8 +638,10 @@ export class OpenAI {
    * Create a new client instance re-using the same options given to the current client with optional overriding.
    */
   withOptions(options: Partial<ClientOptions>): this {
+    const residencyBaseURL = resolveDataResidency(options);
     const inheritedProvider = this._options.provider;
     const provider = options.provider ?? inheritedProvider;
+    const x509Authentication = this.#x509Authentication;
     const inheritedOptions: ClientOptions = {
       ...this._options,
       baseURL: this.baseURL,
@@ -563,19 +649,38 @@ export class OpenAI {
       timeout: this.timeout,
       logger: this.logger,
       logLevel: this.logLevel,
-      fetch: this.fetch,
+      fetch: this.#x509Authentication ? undefined : this.fetch,
       fetchOptions: this.fetchOptions,
       apiKey: this._options.apiKey,
       adminAPIKey: this.adminAPIKey,
-      workloadIdentity: this._options.workloadIdentity,
+      workloadIdentity: x509Authentication?.identitySnapshot() ?? this._options.workloadIdentity,
+      x509Transport: this._options.x509Transport,
       organization: this.organization,
       project: this.project,
       webhookSecret: this.webhookSecret,
     };
+    const currentlyX509 = x509Authentication !== undefined;
+    const nextIdentity = hasOwn(options, 'workloadIdentity')
+      ? options.workloadIdentity
+      : inheritedOptions.workloadIdentity;
+    const nextX509 = isX509WorkloadIdentity(nextIdentity);
+    if (currentlyX509 !== nextX509) {
+      delete inheritedOptions.fetch;
+      delete inheritedOptions.baseURL;
+      if (nextX509) {
+        inheritedOptions.apiKey = null;
+      } else {
+        delete inheritedOptions.x509Transport;
+      }
+    }
+    if (residencyBaseURL !== undefined) {
+      delete inheritedOptions.baseURL;
+    }
     if (provider) {
       delete inheritedOptions.apiKey;
       delete inheritedOptions.adminAPIKey;
       delete inheritedOptions.workloadIdentity;
+      delete inheritedOptions.x509Transport;
       delete inheritedOptions.baseURL;
       if (provider !== inheritedProvider) {
         delete inheritedOptions.organization;
@@ -584,11 +689,27 @@ export class OpenAI {
       }
     }
 
-    const client = new (this.constructor as any as new (props: ClientOptions) => typeof this)({
+    const clientOptions: InternalClientOptions = {
       ...inheritedOptions,
       ...options,
       provider,
-    });
+      [inheritedDataResidencySelection]:
+        this.#explicitDataResidency &&
+        residencyBaseURL === undefined &&
+        !hasOwn(options, 'baseURL') &&
+        !provider,
+    };
+    const client = new (this.constructor as any as new (props: ClientOptions) => typeof this)(clientOptions);
+    if (
+      this.#x509Authentication &&
+      client.#x509Authentication &&
+      this.baseURL === client.baseURL &&
+      this.#x509Authentication.matches(client.#x509Authentication)
+    ) {
+      client._workloadIdentityAuth = this.#x509Authentication;
+      client.#x509Authentication = this.#x509Authentication;
+      client.#x509Fetch = this.#x509Fetch;
+    }
     return client;
   }
 
@@ -596,7 +717,11 @@ export class OpenAI {
    * Check whether the base URL is set to its default.
    */
   #baseURLOverridden(): boolean {
-    return this._provider !== undefined || this.baseURL !== 'https://api.openai.com/v1';
+    return (
+      this.#explicitDataResidency ||
+      this._provider !== undefined ||
+      this.baseURL !== 'https://api.openai.com/v1'
+    );
   }
 
   protected defaultQuery(): Record<string, string | undefined> | undefined {
@@ -633,6 +758,14 @@ export class OpenAI {
       adminAPIKeyAuth: true,
     },
   ): Promise<NullableHeaders | undefined> {
+    const authentication = this.#x509Authentication ?? this._workloadIdentityAuth;
+    if (
+      authentication instanceof X509WorkloadIdentityAuth &&
+      schemes.adminAPIKeyAuth &&
+      this.adminAPIKey !== null
+    ) {
+      return await this.adminAPIKeyAuth(opts);
+    }
     return buildHeaders([
       schemes.bearerAuth ? await this.bearerAuth(opts) : null,
       schemes.adminAPIKeyAuth ? await this.adminAPIKeyAuth(opts) : null,
@@ -640,8 +773,40 @@ export class OpenAI {
   }
 
   protected async bearerAuth(opts: FinalRequestOptions): Promise<NullableHeaders | undefined> {
-    if (this._workloadIdentityAuth) {
-      return buildHeaders([{ Authorization: `Bearer ${await this._workloadIdentityAuth.getToken()}` }]);
+    const authentication = this.#x509Authentication ?? this._workloadIdentityAuth;
+    if (authentication) {
+      if (authentication instanceof X509WorkloadIdentityAuth) {
+        if (
+          authentication === this._workloadIdentityAuth &&
+          (this.fetchWithAuth !== OpenAI.prototype.fetchWithAuth ||
+            this.fetchWithTimeout !== OpenAI.prototype.fetchWithTimeout)
+        ) {
+          throw new Errors.OpenAIError(
+            'X.509 workload identity does not support overridden fetch dispatch hooks.',
+          );
+        }
+        const snapshots = authentication.headerSnapshots();
+        if (
+          !X509WorkloadIdentityAuth.shouldAuthenticate(
+            opts,
+            snapshots.defaultHeaders,
+            snapshots.requestHeaders,
+          )
+        ) {
+          return undefined;
+        }
+      }
+      const token =
+        authentication instanceof X509WorkloadIdentityAuth
+          ? await authentication.getToken(opts, {
+              apiURL: authentication.requestAPIURL(),
+              ...authentication.headerSnapshots(),
+              ...authentication.requestSnapshot(),
+              signal: authentication.effectiveSignal(),
+              ...authentication.tenantSnapshot(),
+            })
+          : await authentication.getToken();
+      return buildHeaders([{ Authorization: `Bearer ${token}` }]);
     }
     if (this.apiKey == null) {
       return undefined;
@@ -788,7 +953,14 @@ export class OpenAI {
     options: PromiseOrValue<FinalRequestOptions>,
     remainingRetries: number | null = null,
   ): APIPromise<Rsp> {
-    return this.responsePromise<Rsp>(this.makeRequest(options, remainingRetries, undefined));
+    const authentication = this.#x509Authentication ?? this._workloadIdentityAuth;
+    const request =
+      authentication instanceof X509WorkloadIdentityAuth
+        ? Promise.resolve(options).then((resolved) =>
+            authentication.runRequest(() => this.makeRequest(resolved, remainingRetries, undefined), this),
+          )
+        : this.makeRequest(options, remainingRetries, undefined);
+    return this.responsePromise<Rsp>(request);
   }
 
   private responsePromise<Rsp>(
@@ -796,7 +968,10 @@ export class OpenAI {
     parse: (client: OpenAI, props: APIResponseProps) => Promise<any> = (client, props) =>
       this.parseResponseWithTimeout<Rsp>(client, props),
   ): APIPromise<Rsp> {
-    const promise = new APIPromise<Rsp>(this, request, parse);
+    const promise = new APIPromise<Rsp>(this, request, (client, props) => {
+      const resume = this.#responseAttempts.get(props.controller)?.continueRequest;
+      return resume ? resume(() => parse(client, props)) : parse(client, props);
+    });
 
     // A body timeout can retry after the original raw response has arrived. Wait for
     // parsing before selecting the response so withResponse() reports the retry.
@@ -826,16 +1001,31 @@ export class OpenAI {
     while (true) {
       const attempt = this.#responseAttempts.get(props.controller);
       const timeout = attempt?.timeout ?? props.options.timeout ?? this.timeout;
-      const remaining = Math.max(0, props.startTime + timeout - Date.now());
-      const callerSignal = props.options.signal;
+      const x509Authentication = attempt?.authentication;
+      const callerSignal = x509Authentication ? props.controller.signal : props.options.signal;
+      const abortError = () =>
+        x509Authentication && callerSignal
+          ? this._makeUserAbortError(callerSignal)
+          : new Errors.APIUserAbortError();
+      let remaining: number;
+      try {
+        remaining =
+          x509Authentication?.remainingTimeout(props.options, timeout) ??
+          Math.max(0, props.startTime + timeout - Date.now());
+      } catch (error) {
+        const cancellation = callerSignal?.aborted ? abortError() : undefined;
+        props.controller.abort();
+        void Shims.CancelReadableStream(props.response.body).catch(() => undefined);
+        throw cancellation ?? error;
+      }
       let timer: ReturnType<typeof setTimeout> | undefined;
       let abortListener: (() => void) | undefined;
       let timedOut = false;
 
       try {
         // Tool runners preserve a completed buffered turn before cancellation stops the next request.
-        if (callerSignal?.aborted && props.options.__metadata?.['helperMethod'] !== 'runTools') {
-          throw new Errors.APIUserAbortError();
+        if (callerSignal?.aborted && attempt?.helperMethod !== 'runTools') {
+          throw abortError();
         }
 
         const timeoutPromise = new Promise<never>((_, reject) => {
@@ -846,23 +1036,34 @@ export class OpenAI {
           }, remaining);
 
           if (callerSignal) {
-            abortListener = () => reject(new Errors.APIUserAbortError());
+            abortListener = () => {
+              if (!timedOut) reject(abortError());
+            };
             callerSignal.addEventListener('abort', abortListener, { once: true });
           }
         });
 
         return await Promise.race([defaultParseResponse<Rsp>(client, props), timeoutPromise]);
       } catch (error) {
-        if (callerSignal?.aborted) {
-          throw new Errors.APIUserAbortError();
+        if (callerSignal?.aborted && !timedOut) {
+          throw abortError();
         }
         if (!timedOut) {
+          if (x509Authentication && error instanceof SyntaxError) {
+            throw new SyntaxError('X.509 workload identity API response contains invalid JSON.');
+          }
+          if (x509Authentication && !(error instanceof Errors.OpenAIError)) {
+            throw new Errors.APIConnectionError({
+              message: 'X.509 workload identity API response body could not be read.',
+            });
+          }
           throw error;
         }
 
         const retriesRemaining = attempt?.retriesRemaining ?? 0;
         if (
           !retriesRemaining ||
+          attempt?.hasStreamingBody ||
           props.options.__metadata?.['hasStreamingBody'] ||
           ((globalThis as any).ReadableStream &&
             props.options.body instanceof (globalThis as any).ReadableStream) ||
@@ -893,6 +1094,52 @@ export class OpenAI {
     }
   }
 
+  /** Keeps terminal X.509 error-body consumption inside the original logical request deadline. */
+  private async readX509ResponseError(
+    response: Response,
+    options: FinalRequestOptions,
+    timeout: number,
+    controller: AbortController,
+    authentication: X509WorkloadIdentityAuth,
+  ): Promise<string> {
+    const deadline = new AbortController();
+    const callerSignal = controller.signal;
+    let timedOut = false;
+    const cancel = () => deadline.abort(callerSignal.reason);
+    callerSignal.addEventListener('abort', cancel, { once: true });
+    if (callerSignal.aborted) {
+      cancel();
+    }
+
+    try {
+      const remaining = authentication.remainingTimeout(options, timeout);
+      const expiration = authentication.waitForRetry(remaining, deadline.signal).then(() => {
+        throw new Errors.APIConnectionTimeoutError();
+      });
+      const body = await Promise.race([
+        response.text().catch(() => 'X.509 workload identity API response body could not be read.'),
+        expiration,
+      ]);
+      if (callerSignal.aborted) {
+        throw this._makeUserAbortError(callerSignal);
+      }
+      return body;
+    } catch (error) {
+      if (error instanceof Errors.APIConnectionTimeoutError) {
+        timedOut = !callerSignal.aborted;
+        controller.abort();
+        void Shims.CancelReadableStream(response.body).catch(() => undefined);
+      }
+      if (callerSignal.aborted && !timedOut) {
+        throw this._makeUserAbortError(callerSignal);
+      }
+      throw error;
+    } finally {
+      callerSignal.removeEventListener('abort', cancel);
+      deadline.abort();
+    }
+  }
+
   private async makeRequest(
     optionsInput: PromiseOrValue<FinalRequestOptions>,
     retriesRemaining: number | null,
@@ -906,18 +1153,85 @@ export class OpenAI {
 
     await this.prepareOptions(options);
 
-    const { req, url, timeout } = await this.buildRequest(options, {
-      retryCount: maxRetries - retriesRemaining,
-    });
-    const hasStreamingBody = options.__metadata?.['hasStreamingBody'] === true;
-
-    await this.prepareRequest(req, { url, options });
-    await this._provider?.prepareRequest?.(req, { url, options });
+    const x509Authentication = this.#x509Authentication;
+    x509Authentication?.beginRequestPlanning();
+    let built: { req: FinalizedRequestInit; url: string; timeout: number };
+    try {
+      const candidate = await this.buildRequest(options, {
+        retryCount: maxRetries - retriesRemaining,
+      });
+      built = { req: candidate.req, url: candidate.url, timeout: candidate.timeout };
+      if (x509Authentication) {
+        validatePositiveInteger('timeout', built.timeout);
+        x509Authentication.authorizePlannedRequest(built.url, built.req, built.timeout);
+        if (X509WorkloadIdentityAuth.isStreamingRequestBody(built.req.body)) {
+          options.__metadata = { ...options.__metadata, hasStreamingBody: true };
+        }
+        await this.prepareRequest(built.req, { url: built.url, options });
+        await this._provider?.prepareRequest?.(built.req, { url: built.url, options });
+        x509Authentication.beginRequestPlanning();
+        x509Authentication.authorizePlannedRequest(built.url, built.req, built.timeout, true);
+        if (X509WorkloadIdentityAuth.isStreamingRequestBody(built.req.body)) {
+          options.__metadata = { ...options.__metadata, hasStreamingBody: true };
+        }
+        const callerSignal = x509Authentication.requestSnapshot().signal;
+        if (callerSignal?.aborted || built.req.signal?.aborted) {
+          throw this._makeUserAbortError(callerSignal?.aborted ? callerSignal : built.req.signal!);
+        }
+        x509Authentication.setEffectiveSignal(
+          built.req.signal || callerSignal
+            ? createRequestController(built.req.signal ?? callerSignal, callerSignal).signal
+            : undefined,
+        );
+        x509Authentication.beginRequestNetwork();
+        const security = options.__security ?? { bearerAuth: true };
+        const authenticationHeaders = await this.authHeaders(options, security);
+        const suppliedHeaders = x509Authentication.headerSnapshots();
+        const supplied = buildHeaders([suppliedHeaders.defaultHeaders, suppliedHeaders.requestHeaders]);
+        for (const [name, value] of authenticationHeaders?.values ?? []) {
+          if (!supplied.nulls.has(name) && !built.req.headers.has(name)) {
+            built.req.headers.set(name, value);
+          }
+        }
+        this.validateHeaders(buildHeaders([supplied, built.req.headers]), security);
+      }
+    } catch (error) {
+      x509Authentication?.retireRequestBody();
+      if (
+        x509Authentication &&
+        retriesRemaining &&
+        !options.__metadata?.['hasStreamingBody'] &&
+        X509WorkloadIdentityAuth.isRetryableFailure(error)
+      ) {
+        return await this.retryRequest(
+          options,
+          retriesRemaining,
+          retryOfRequestLogID ?? 'x509-token-exchange',
+          X509WorkloadIdentityAuth.retryHeaders(error),
+        );
+      }
+      throw error;
+    }
+    const { req, url } = built;
+    const timeout = x509Authentication
+      ? Math.min(built.timeout, x509Authentication.requestSnapshot().timeout)
+      : built.timeout;
+    x509Authentication?.bindRequest(options, req, this.adminAPIKey);
+    let hasStreamingBody = options.__metadata?.['hasStreamingBody'] === true;
+
+    if (!x509Authentication) {
+      await this.prepareRequest(req, { url, options });
+      await this._provider?.prepareRequest?.(req, { url, options });
+    }
+    x509Authentication?.adoptRequestHeaders(req);
+    if (x509Authentication && X509WorkloadIdentityAuth.isStreamingRequestBody(req.body)) {
+      hasStreamingBody = true;
+    }
 
     /** Not an API request ID, just for correlating local log entries. */
     const requestLogID = 'log_' + ((Math.random() * (1 << 24)) | 0).toString(16).padStart(6, '0');
     const retryLogStr = retryOfRequestLogID === undefined ? '' : `, retryOf: ${retryOfRequestLogID}`;
-    const startTime = Date.now();
+    const startTime = x509Authentication?.requestStartedAt(options) ?? Date.now();
 
     loggerFor(this).debug(
       `[${requestLogID}] sending request`,
@@ -925,28 +1239,36 @@ export class OpenAI {
         retryOfRequestLogID,
         method: options.method,
         url,
-        options,
+        options: x509Authentication ? { body: req.body, ...x509Authentication.requestSnapshot() } : options,
         headers: req.headers,
       }),
     );
 
-    if (options.signal?.aborted || req.signal?.aborted) {
-      throw this._makeUserAbortError(options.signal?.aborted ? options.signal : req.signal!);
+    const callerSignal = x509Authentication ? x509Authentication.requestSnapshot().signal : options.signal;
+    if (callerSignal?.aborted || req.signal?.aborted) {
+      throw this._makeUserAbortError(callerSignal?.aborted ? callerSignal : req.signal!);
     }
-
     const security = options.__security ?? { bearerAuth: true };
     // Request hooks may replace the caller signal before it reaches fetch.
     const controller =
-      this.fetchWithTimeout === OpenAI.prototype.fetchWithTimeout
-        ? createRequestController(req.signal)
+      x509Authentication || this.fetchWithTimeout === OpenAI.prototype.fetchWithTimeout
+        ? createRequestController(
+            req.signal ?? (x509Authentication ? callerSignal : undefined),
+            x509Authentication ? callerSignal : undefined,
+          )
         : new AbortController();
-    const response = await this.fetchWithAuth(url, req, timeout, controller, security).catch(castToError);
+    const remainingTimeout = x509Authentication?.remainingTimeout(options, timeout) ?? timeout;
+    const fetchWithAuth = x509Authentication ? OpenAI.prototype.fetchWithAuth : this.fetchWithAuth;
+    x509Authentication?.releaseRequestBody(req.body);
+    const response = await fetchWithAuth
+      .call(this, url, req, remainingTimeout, controller, security)
+      .catch(castToError);
     const headersTime = Date.now();
 
     if (response instanceof globalThis.Error) {
       const retryMessage = `retrying, ${retriesRemaining} attempts remaining`;
-      if (options.signal?.aborted || req.signal?.aborted) {
-        throw this._makeUserAbortError(options.signal?.aborted ? options.signal : req.signal!);
+      if (callerSignal?.aborted || req.signal?.aborted) {
+        throw this._makeUserAbortError(callerSignal?.aborted ? callerSignal : req.signal!);
       }
       // detect native connection timeout errors
       // deno throws "TypeError: error sending request for url (https://example/): client error (Connect): tcp connect error: Operation timed out (os error 60): Operation timed out (os error 60)"
@@ -955,7 +1277,11 @@ export class OpenAI {
       const isTimeout =
         isAbortError(response) ||
         /timed? ?out/i.test(String(response) + ('cause' in response ? String(response.cause) : ''));
-      if (retriesRemaining && !hasStreamingBody) {
+      if (
+        retriesRemaining &&
+        !hasStreamingBody &&
+        (!x509Authentication || isTransientX509ConnectionError(response))
+      ) {
         loggerFor(this).info(
           `[${requestLogID}] connection ${isTimeout ? 'timed out' : 'failed'} - ${retryMessage}`,
         );
@@ -965,7 +1291,7 @@ export class OpenAI {
             retryOfRequestLogID,
             url,
             durationMs: headersTime - startTime,
-            message: response.message,
+            message: x509Authentication ? 'X.509 workload identity API connection failed.' : response.message,
           }),
         );
         return this.retryRequest(options, retriesRemaining, retryOfRequestLogID ?? requestLogID);
@@ -982,7 +1308,7 @@ export class OpenAI {
           retryOfRequestLogID,
           url,
           durationMs: headersTime - startTime,
-          message: response.message,
+          message: x509Authentication ? 'X.509 workload identity API connection failed.' : response.message,
         }),
       );
       if (response instanceof OAuthError || response instanceof SubjectTokenProviderError) {
@@ -1002,8 +1328,14 @@ export class OpenAI {
                 'configure a matching undici fetch and fetchOptions.dispatcher with an Agent whose headersTimeout is at least the SDK timeout.',
             })
           : new Errors.APIConnectionTimeoutError();
+        if (x509Authentication) {
+          throw new Errors.APIConnectionTimeoutError();
+        }
         throw Object.assign(timeoutError, { cause: response });
       }
+      if (x509Authentication) {
+        throw new Errors.APIConnectionError({ message: 'X.509 workload identity API connection failed.' });
+      }
       throw new Errors.APIConnectionError({
         message: getConnectionErrorMessage(response),
         cause: response,
@@ -1019,35 +1351,57 @@ export class OpenAI {
     } with status ${response.status} in ${headersTime - startTime}ms`;
 
     if (!response.ok) {
+      const rejectedX509Credential =
+        response.status === 401 &&
+        x509Authentication &&
+        security.bearerAuth &&
+        x509Authentication.usedWorkloadToken(options);
+      if (rejectedX509Credential) {
+        x509Authentication.invalidateToken();
+      }
       if (
         response.status === 401 &&
-        this._workloadIdentityAuth &&
+        (x509Authentication || this._workloadIdentityAuth) &&
         security.bearerAuth &&
-        !options.__metadata?.['hasStreamingBody'] &&
+        (!x509Authentication || x509Authentication.usedWorkloadToken(options)) &&
+        (!x509Authentication || retriesRemaining > 0) &&
+        !hasStreamingBody &&
         !options.__metadata?.['workloadIdentityTokenRefreshed']
       ) {
-        await Shims.CancelReadableStream(response.body);
-        this._workloadIdentityAuth.invalidateToken();
+        if (x509Authentication) {
+          void Shims.CancelReadableStream(response.body).catch(() => undefined);
+        } else {
+          await Shims.CancelReadableStream(response.body);
+          this._workloadIdentityAuth?.invalidateToken();
+        }
 
-        return this.makeRequest(
-          {
-            ...options,
-            __metadata: {
-              ...options.__metadata,
-              workloadIdentityTokenRefreshed: true,
-            },
+        const replayOptions = {
+          ...options,
+          __metadata: {
+            ...options.__metadata,
+            workloadIdentityTokenRefreshed: true,
           },
-          retriesRemaining,
+        };
+        return this.makeRequest(
+          replayOptions,
+          x509Authentication ? retriesRemaining - 1 : retriesRemaining,
           retryOfRequestLogID ?? requestLogID,
         );
       }
 
-      const shouldRetry = await this.shouldRetry(response);
+      const shouldRetry =
+        rejectedX509Credential && options.__metadata?.['workloadIdentityTokenRefreshed']
+          ? false
+          : await this.shouldRetry(response);
       if (retriesRemaining && shouldRetry && !hasStreamingBody) {
         const retryMessage = `retrying, ${retriesRemaining} attempts remaining`;
 
         // We don't need the body of this response.
-        await Shims.CancelReadableStream(response.body);
+        if (x509Authentication) {
+          void Shims.CancelReadableStream(response.body).catch(() => undefined);
+        } else {
+          await Shims.CancelReadableStream(response.body);
+        }
         loggerFor(this).info(`${responseInfo} - ${retryMessage}`);
         loggerFor(this).debug(
           `[${requestLogID}] response error (${retryMessage})`,
@@ -1075,7 +1429,9 @@ export class OpenAI {
 
       loggerFor(this).info(`${responseInfo} - ${retryMessage}`);
 
-      const errText = await response.text().catch((err: any) => castToError(err).message);
+      const errText = x509Authentication
+        ? await this.readX509ResponseError(response, options, timeout, controller, x509Authentication)
+        : await response.text().catch((err: any) => castToError(err).message);
       const errJSON = safeJSON(errText) as any;
       const errMessage = errJSON ? undefined : errText;
 
@@ -1107,7 +1463,16 @@ export class OpenAI {
       }),
     );
 
-    this.#responseAttempts.set(controller, { timeout, retriesRemaining });
+    const continueRequest = x509Authentication?.continuation();
+    x509Authentication?.releaseRequestCredentials();
+    this.#responseAttempts.set(controller, {
+      timeout,
+      retriesRemaining,
+      hasStreamingBody,
+      ...(x509Authentication ? { authentication: x509Authentication } : {}),
+      helperMethod: options.__metadata?.['helperMethod'],
+      ...(continueRequest ? { continueRequest } : {}),
+    });
     return { response, options, controller, requestLogID, retryOfRequestLogID, startTime };
   }
 
@@ -1131,7 +1496,13 @@ export class OpenAI {
     Page: new (...args: ConstructorParameters<typeof Pagination.AbstractPage>) => PageClass,
     options: PromiseOrValue<FinalRequestOptions>,
   ): Pagination.PagePromise<PageClass, Item> {
-    const request = this.makeRequest(options, null, undefined);
+    const authentication = this.#x509Authentication ?? this._workloadIdentityAuth;
+    const request =
+      authentication instanceof X509WorkloadIdentityAuth
+        ? Promise.resolve(options).then((resolved) =>
+            authentication.runRequest(() => this.makeRequest(resolved, null, undefined), this),
+          )
+        : this.makeRequest(options, null, undefined);
     const page = new Pagination.PagePromise<PageClass, Item>(this as any as OpenAI, request, Page);
     const guarded = this.responsePromise<PageClass>(request, async (client, props) => {
       const body = await this.parseResponseWithTimeout(client, props);
@@ -1155,7 +1526,7 @@ export class OpenAI {
       adminAPIKeyAuth: true,
     },
   ): Promise<Response> {
-    if (this._workloadIdentityAuth && schemes.bearerAuth) {
+    if (this._workloadIdentityAuth && !this.#x509Fetch && schemes.bearerAuth) {
       const headers = init.headers as Headers;
       const authHeader = headers.get('Authorization');
       if (!authHeader || authHeader === `Bearer ${WORKLOAD_IDENTITY_API_KEY_PLACEHOLDER}`) {
@@ -1164,7 +1535,8 @@ export class OpenAI {
       }
     }
 
-    const response = await this.fetchWithTimeout(url, init, timeout, controller);
+    const fetchWithTimeout = this.#x509Fetch ? OpenAI.prototype.fetchWithTimeout : this.fetchWithTimeout;
+    const response = await fetchWithTimeout.call(this, url, init, timeout, controller);
 
     return response;
   }
@@ -1200,7 +1572,7 @@ export class OpenAI {
 
     try {
       // use undefined this binding; fetch errors if bound to something else in browser/cloudflare
-      return await this.fetch.call(undefined, url, fetchOptions);
+      return await (this.#x509Fetch ?? this.fetch).call(undefined, url, fetchOptions);
     } catch (err) {
       if (signal && !composed) signal.removeEventListener('abort', abort);
       throw err;
@@ -1271,7 +1643,21 @@ export class OpenAI {
       const maxRetries = options.maxRetries ?? this.maxRetries;
       timeoutMillis = this.calculateDefaultRetryTimeoutMillis(retriesRemaining, maxRetries);
     }
-    await sleep(timeoutMillis);
+    const x509Authentication = this.#x509Authentication;
+    if (x509Authentication) {
+      const remaining = x509Authentication.remainingTimeout(
+        options,
+        x509Authentication.requestSnapshot().timeout,
+      );
+      if (timeoutMillis >= remaining) {
+        throw new Errors.APIConnectionTimeoutError();
+      }
+    }
+    if (x509Authentication) {
+      await x509Authentication.waitForRetry(timeoutMillis, x509Authentication.effectiveSignal());
+    } else {
+      await sleep(timeoutMillis);
+    }
 
     return this.makeRequest(options, retriesRemaining - 1, requestLogID);
   }
@@ -1295,12 +1681,46 @@ export class OpenAI {
     inputOptions: FinalRequestOptions,
     { retryCount = 0 }: { retryCount?: number } = {},
   ): Promise<{ req: FinalizedRequestInit; url: string; timeout: number }> {
+    if (this.#x509Authentication && !this.#x509Authentication.inRequest(this)) {
+      const authentication = this.#x509Authentication;
+      return await authentication.runRequest(async () => {
+        const built = await OpenAI.prototype.buildRequest.call(this, inputOptions, { retryCount });
+        authentication.releaseRequestBody(built.req.body);
+        return built;
+      }, this);
+    }
     const options = { ...inputOptions };
+    const x509Authentication = this.#x509Authentication;
+    const x509Tenant = x509Authentication?.snapshotTenant(this.organization, this.project);
+    const x509Headers = x509Authentication?.snapshotHeaders(this._options.defaultHeaders, options.headers);
+    if (x509Headers) {
+      options.headers = x509Headers.requestHeaders;
+    }
+    const x509ClientFetchOptions = x509Authentication
+      ? snapshotX509RequestOptions(this.fetchOptions)
+      : undefined;
+    const x509RequestFetchOptions = x509Authentication
+      ? snapshotX509RequestOptions(options.fetchOptions)
+      : undefined;
     const { method, path, query, defaultBaseURL } = options;
 
     const url = this.buildURL(path!, query as Record<string, unknown>, defaultBaseURL);
-    if ('timeout' in options) validatePositiveInteger('timeout', options.timeout);
+    x509Authentication?.snapshotAPIURL(url);
+    const explicitTimeout = 'timeout' in options;
+    if (explicitTimeout) validatePositiveInteger('timeout', options.timeout);
     options.timeout = options.timeout ?? this.timeout;
+    if (x509Authentication && x509RequestFetchOptions) {
+      x509Authentication.snapshotRequest(options.signal, options.timeout, x509RequestFetchOptions);
+    }
+    if (x509Authentication) {
+      const snapshot = x509Authentication.requestSnapshot();
+      options.timeout = snapshot.timeout;
+      if (snapshot.signal === undefined) {
+        delete options.signal;
+      } else {
+        options.signal = snapshot.signal;
+      }
+    }
     const { bodyHeaders, body, isStreamingBody } = this.buildBody({ options });
 
     if (isStreamingBody) {
@@ -1308,9 +1728,18 @@ export class OpenAI {
         ...inputOptions.__metadata,
         hasStreamingBody: true,
       };
+      x509Authentication?.ownRequestBody(body, options.body);
     }
 
-    const reqHeaders = await this.buildHeaders({ options: inputOptions, method, bodyHeaders, retryCount });
+    const reqHeaders = await this.buildHeaders({
+      options: inputOptions,
+      method,
+      bodyHeaders,
+      retryCount,
+      x509Headers,
+      x509Timeout: explicitTimeout ? options.timeout : undefined,
+      x509Tenant,
+    });
 
     const req: FinalizedRequestInit = {
       method,
@@ -1319,8 +1748,8 @@ export class OpenAI {
       ...((globalThis as any).ReadableStream &&
         body instanceof (globalThis as any).ReadableStream && { duplex: 'half' }),
       ...(body && { body }),
-      ...((this.fetchOptions as any) ?? {}),
-      ...((options.fetchOptions as any) ?? {}),
+      ...(((x509Authentication ? x509ClientFetchOptions : this.fetchOptions) as any) ?? {}),
+      ...(((x509Authentication ? x509RequestFetchOptions : options.fetchOptions) as any) ?? {}),
     };
 
     return { req, url, timeout: options.timeout };
@@ -1331,11 +1760,17 @@ export class OpenAI {
     method,
     bodyHeaders,
     retryCount,
+    x509Headers,
+    x509Timeout,
+    x509Tenant,
   }: {
     options: FinalRequestOptions;
     method: HTTPMethod;
     bodyHeaders: HeadersLike;
     retryCount: number;
+    x509Headers?: { defaultHeaders: NullableHeaders; requestHeaders: NullableHeaders } | undefined;
+    x509Timeout: number | undefined;
+    x509Tenant?: { organization: string | null; project: string | null } | undefined;
   }): Promise<Headers> {
     let idempotencyHeaders: HeadersLike = {};
     if (this.idempotencyHeader && method !== 'get') {
@@ -1344,27 +1779,28 @@ export class OpenAI {
     }
 
     const helperMethod = options.__metadata?.['helperMethod'];
+    const timeout = x509Headers ? x509Timeout : options.timeout;
     const headers = buildHeaders([
       idempotencyHeaders,
       {
         Accept: 'application/json',
         ...(!isRunningInBrowserOrBrowserWorker() ? { 'User-Agent': this.getUserAgent() } : undefined),
         'X-Stainless-Retry-Count': String(retryCount),
-        ...(options.timeout ? { 'X-Stainless-Timeout': String(Math.trunc(options.timeout / 1000)) } : {}),
+        ...(timeout ? { 'X-Stainless-Timeout': String(Math.trunc(timeout / 1000)) } : {}),
         ...getPlatformHeaders(),
         ...(typeof helperMethod === 'string' ? { 'X-Stainless-Helper-Method': helperMethod } : {}),
-        'OpenAI-Organization': this.organization,
-        'OpenAI-Project': this.project,
+        'OpenAI-Organization': x509Tenant ? x509Tenant.organization : this.organization,
+        'OpenAI-Project': x509Tenant ? x509Tenant.project : this.project,
       },
-      this._provider
+      this._provider || this.#x509Authentication?.isPlanningRequest()
         ? undefined
         : await this.authHeaders(options, options.__security ?? { bearerAuth: true }),
-      this._options.defaultHeaders,
+      x509Headers?.defaultHeaders ?? this._options.defaultHeaders,
       bodyHeaders,
-      options.headers,
+      x509Headers?.requestHeaders ?? options.headers,
     ]);
 
-    if (!this._provider) {
+    if (!this._provider && !this.#x509Authentication?.isPlanningRequest()) {
       this.validateHeaders(headers, options.__security ?? { bearerAuth: true });
     }
 
@@ -1563,7 +1999,10 @@ OpenAI.Videos = Videos;
 
 const composedCallerSignals = new WeakMap<AbortController, AbortSignal>();
 
-function createRequestController(callerSignal: AbortSignal | null | undefined): AbortController {
+function createRequestController(
+  callerSignal: AbortSignal | null | undefined,
+  originalSignal?: AbortSignal | null,
+): AbortController {
   const controller = new AbortController();
   if (!callerSignal) return controller;
 
@@ -1575,7 +2014,11 @@ function createRequestController(callerSignal: AbortSignal | null | undefined):
   try {
     // Native composition keeps cancellation active after response headers without
     // retaining an abort listener on the caller's signal or changing its reason.
-    const composed = nativeAbortSignal.any([controller.signal, callerSignal]) as AbortSignal;
+    const signals = [controller.signal, callerSignal];
+    if (originalSignal && originalSignal !== callerSignal) {
+      signals.push(originalSignal);
+    }
+    const composed = nativeAbortSignal.any(signals) as AbortSignal;
     Object.defineProperty(controller, 'signal', { value: composed, configurable: true });
     composedCallerSignals.set(controller, callerSignal);
   } catch {
@@ -1619,6 +2062,7 @@ function isUndiciDispatcherVersionMismatchError(error: unknown): boolean {
 }
 
 export declare namespace OpenAI {
+  export { type DataResidency as DataResidency };
   export type RequestOptions = Opts.RequestOptions;
 
   export import Page = Pagination.Page;