openai 7.5.0 → 7.7.0

package/src/helpers/zod.ts

@@ -3,7 +3,12 @@ import type * as z3 from 'zod/v3';
 import * as z4 from 'zod/v4';
 import type * as z4Mini from 'zod/v4-mini';
 import type { AutoParseableResponseFormat, AutoParseableTextFormat, AutoParseableTool } from '../lib/parser';
-import { makeParseableResponseFormat, makeParseableTextFormat, makeParseableTool } from '../lib/parser';
+import {
+  makeParseableResponseFormat,
+  makeParseableTextFormat,
+  makeParseableTool,
+  parseResponseFormatContent,
+} from '../lib/parser';
 import { zodToJsonSchema as _zodToJsonSchema } from '../_vendor/zod-to-json-schema';
 import type { AutoParseableResponseTool } from '../lib/ResponsesParser';
 import { makeParseableResponseTool } from '../lib/ResponsesParser';
@@ -12,6 +17,7 @@ import type { RealtimeFunctionTool } from '../resources/realtime/realtime';
 import { forEachJSONSchemaChild, toStrictJsonSchema } from '../lib/transform';
 import type { JSONSchema } from '../lib/jsonschema';
 import { hasOwn } from '../internal/utils/values';
+import { assertJSONSerializableSchema, assertSupportedZodV3Schema } from './zod-v3-strict-schema';
 
 type ZodV4Schema = z4.ZodType | z4Mini.ZodMiniType;
 type ZodSchema = z3.ZodType | ZodV4Schema;
@@ -128,6 +134,7 @@ function zodV3ToJsonSchema(
   schema: z3.ZodType,
   options: { name: string; schemaDefinitions?: ZodSchemaDefinitions | undefined },
 ): Record<string, unknown> {
+  assertSupportedZodV3Schema(schema, options.schemaDefinitions as Record<string, z3.ZodType> | undefined);
   const rootName = getZodV3RootName(options.name, options.schemaDefinitions);
   const jsonSchema = _zodToJsonSchema(schema, {
     openaiStrictMode: true,
@@ -140,7 +147,9 @@ function zodV3ToJsonSchema(
       : undefined),
   });
 
-  return escapeSchemaDefinitionRefs(jsonSchema, options.schemaDefinitions);
+  const escapedSchema = escapeSchemaDefinitionRefs(jsonSchema, options.schemaDefinitions);
+  assertJSONSerializableSchema(escapedSchema);
+  return escapedSchema;
 }
 
 function zodV4ToJsonSchema(
@@ -202,11 +211,15 @@ function parseZodObject<ZodInput extends ZodTypeLike>(
   zodObject: ZodInput,
   content: string,
 ): InferZodType<ZodInput> {
-  const parsed = JSON.parse(content);
+  const parsed = parseResponseFormatContent({ type: 'json_schema', $parseRaw: undefined }, content);
   const parser = (zodObject as { parse?: (data: unknown) => unknown }).parse;
 
   if (typeof parser === 'function') {
-    return parser.call(zodObject, parsed) as InferZodType<ZodInput>;
+    const result = parser.call(zodObject, parsed) as InferZodType<ZodInput>;
+    if (!isZodV4(zodObject as unknown as ZodSchema)) {
+      assertJSONSerializableSchema(result);
+    }
+    return result;
   }
 
   return z4.parse(zodObject as unknown as ZodV4Schema, parsed) as InferZodType<ZodInput>;

package/src/index.ts

@@ -2,7 +2,7 @@ export { OpenAI as default } from './client';
 
 export { type Uploadable, toFile, toStreamingFile } from './core/uploads';
 export { APIPromise } from './core/api-promise';
-export { OpenAI, type ClientOptions } from './client';
+export { OpenAI, type ClientOptions, type DataResidency } from './client';
 export { PagePromise } from './core/pagination';
 export {
   OpenAIError,

package/src/internal/assistant-stream-delta.ts

@@ -6,6 +6,28 @@ const MAX_EXTERNALLY_MUTABLE_ASSISTANT_STREAM_ARRAY_LENGTH = 65_536;
 
 type AssistantStreamRecord = Record<string, unknown>;
 
+function getAssistantStreamDiagnosticProperty(property: string): string {
+  switch (property) {
+    case 'value':
+    case 'arguments':
+    case 'input':
+    case 'text':
+    case 'content':
+    case 'annotations':
+    case 'metadata':
+    case 'name':
+    case 'role':
+    case 'status':
+    case 'tool_calls':
+    case 'step_details': {
+      return property;
+    }
+    default: {
+      return 'unknown';
+    }
+  }
+}
+
 interface AssistantStreamArrayState {
   length: number;
   ownEntryCount: number;
@@ -87,12 +109,13 @@ function getAssistantStreamDeltaIndex(
   const { index } = deltaEntry;
 
   if (kind === 'array' && (index === null || index === undefined)) {
-    console.error(deltaEntry);
     throw new Error('Expected array delta entry to have an `index` property');
   }
 
   if (kind === 'array' && typeof index !== 'number') {
-    throw new TypeError(`Expected array delta entry \`index\` property to be a number but got ${index}`);
+    throw new TypeError(
+      'Expected array delta entry `index` property to be a number but got an invalid value',
+    );
   }
 
   if (
@@ -101,7 +124,8 @@ function getAssistantStreamDeltaIndex(
     (index as number) >= baselineLength + MAX_ASSISTANT_STREAM_ARRAY_GROWTH ||
     (index as number) >= MAX_EXTERNALLY_MUTABLE_ASSISTANT_STREAM_ARRAY_LENGTH
   ) {
-    throw new OpenAIError(`Assistant stream delta contains an invalid ${kind} index: ${index}`);
+    const safeIndex = typeof index === 'number' ? index : 'unknown';
+    throw new OpenAIError(`Assistant stream delta contains an invalid ${kind} index: ${safeIndex}`);
   }
 
   return index as number;
@@ -139,7 +163,7 @@ function assertValidAssistantStreamArrayDelta(
 
   for (const deltaEntry of delta) {
     if (!isObj(deltaEntry)) {
-      throw new Error(`Expected array delta entry to be an object but got: ${deltaEntry}`);
+      throw new Error('Expected array delta entry to be an object but got an invalid value');
     }
 
     const validatedIndex = getAssistantStreamDeltaIndex(deltaEntry, kind, projectedArray.baselineLength);
@@ -259,11 +283,12 @@ export function defineAssistantStreamArrayEntry(accumulator: unknown[], index: n
 function getRequiredAssistantStreamArrayIndex(deltaEntry: AssistantStreamRecord): number {
   const { index } = deltaEntry;
   if (index === null || index === undefined) {
-    console.error(deltaEntry);
     throw new Error('Expected array delta entry to have an `index` property');
   }
   if (typeof index !== 'number') {
-    throw new TypeError(`Expected array delta entry \`index\` property to be a number but got ${index}`);
+    throw new TypeError(
+      'Expected array delta entry `index` property to be a number but got an invalid value',
+    );
   }
   return index;
 }
@@ -286,7 +311,7 @@ function applyAssistantStreamArrayDelta(
 
   for (const deltaEntry of delta) {
     if (!isObj(deltaEntry)) {
-      throw new Error(`Expected array delta entry to be an object but got: ${deltaEntry}`);
+      throw new Error('Expected array delta entry to be an object but got an invalid value');
     }
 
     const index = getRequiredAssistantStreamArrayIndex(deltaEntry);
@@ -349,9 +374,7 @@ function applyAssistantStreamDelta(
       applyAssistantStreamArrayDelta(accumulatedValue, deltaValue, applyAssistantStreamDelta);
       continue;
     } else {
-      throw new TypeError(
-        `Unhandled record type: ${key}, deltaValue: ${deltaValue}, accValue: ${accumulatedValue}`,
-      );
+      throw new TypeError(`Unhandled record type: ${getAssistantStreamDiagnosticProperty(key)}`);
     }
     accumulator[key] = accumulatedValue;
   }

package/src/internal/auth/x509-token-exchange.ts

@@ -0,0 +1,310 @@
+import {
+  APIConnectionError,
+  APIConnectionTimeoutError,
+  APIError,
+  OAuthError,
+  OpenAIError,
+} from '../../core/error';
+import { hasOwn } from '../utils/values';
+import { sendX509Request } from './x509-transport-capability';
+import { isRetryableX509TransportFailure } from './x509-transport-registry';
+import {
+  isTransientX509ConnectionError,
+  markRetryableX509IssuerError,
+  markTransientX509ConnectionError,
+  rememberX509OAuthError,
+} from '#x509-transport-state';
+import type { X509ExchangedToken, X509Transport } from './x509-transport-registry';
+
+export type { X509ExchangedToken } from './x509-transport-registry';
+
+const TOKEN_EXCHANGE_URL = new URL('https://mtls.auth.openai.com/oauth/token');
+const TOKEN_EXCHANGE_GRANT = 'urn:ietf:params:oauth:grant-type:token-exchange';
+const X509_SUBJECT_TOKEN = 'urn:openai:params:oauth:token-type:x509';
+const ACCESS_TOKEN_TYPE = 'urn:ietf:params:oauth:token-type:access_token';
+const SAFE_ACCESS_TOKEN = /^[A-Za-z0-9._~+/-]+=*$/u;
+const SAFE_OAUTH_ERRORS = new Set(['invalid_grant', 'invalid_subject_token', 'token_exchange_server_error']);
+const SAFE_RESPONSE_HEADERS = ['retry-after', 'retry-after-ms', 'x-should-retry', 'x-request-id'];
+const MAX_TOKEN_EXCHANGE_DURATION_MS = 5000;
+
+function transientConnectionError(message: string, failure: unknown): APIConnectionError {
+  const error = new APIConnectionError({ message });
+  if (isRetryableX509TransportFailure(failure)) {
+    markTransientX509ConnectionError(error);
+  }
+  return error;
+}
+
+/** Parameters for one certificate-authenticated OAuth exchange. */
+export interface X509TokenExchangeOptions {
+  /** Frozen, caller-owned certificate transport shared with the eventual API request. */
+  transport: X509Transport;
+
+  /** Identity provider enrolled for the workload certificate. */
+  identityProviderId: string;
+
+  /** OpenAI service account selected for the verified certificate identity. */
+  serviceAccountId: string;
+
+  /** Optional caller cancellation propagated through request and response consumption. */
+  signal?: AbortSignal | undefined;
+}
+
+async function cancelReader(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  reason?: unknown,
+): Promise<void> {
+  try {
+    await reader.cancel(reason);
+  } catch {
+    // Response retirement is best-effort and must never replace the sanitized exchange result.
+  }
+}
+
+function cancelResponseBody(response: Response): void {
+  if (!response.body) {
+    return;
+  }
+
+  const reader = response.body.getReader();
+  try {
+    void cancelReader(reader);
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+async function readResponseBody(response: Response, signal?: AbortSignal): Promise<unknown> {
+  if (!response.body) {
+    throw new OpenAIError('X.509 workload identity token exchange returned invalid JSON.');
+  }
+
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let totalBytes = 0;
+  const cancel = () => {
+    void cancelReader(reader, signal?.reason);
+  };
+  signal?.addEventListener('abort', cancel, { once: true });
+
+  try {
+    while (true) {
+      signal?.throwIfAborted();
+      // oxlint-disable-next-line no-await-in-loop -- Token-response chunks must be consumed in wire order.
+      const chunk = await reader.read();
+      signal?.throwIfAborted();
+      if (chunk.done) {
+        break;
+      }
+      chunks.push(chunk.value);
+      totalBytes += chunk.value.byteLength;
+    }
+  } catch (error) {
+    cancel();
+    if (signal?.aborted) {
+      signal.throwIfAborted();
+    }
+    throw transientConnectionError('X.509 workload identity token response could not be read.', error);
+  } finally {
+    signal?.removeEventListener('abort', cancel);
+    reader.releaseLock();
+  }
+
+  const bytes = new Uint8Array(totalBytes);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+
+  try {
+    return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+  } catch {
+    throw new OpenAIError('X.509 workload identity token exchange returned invalid JSON.');
+  }
+}
+
+function validateTokenResponse(value: unknown): X509ExchangedToken {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new OpenAIError('X.509 workload identity token exchange returned an invalid token response.');
+  }
+
+  const response = value as Record<string, unknown>;
+  if (
+    !hasOwn(response, 'access_token') ||
+    typeof response['access_token'] !== 'string' ||
+    !SAFE_ACCESS_TOKEN.test(response['access_token'])
+  ) {
+    throw new OpenAIError('X.509 workload identity token exchange returned an invalid access token.');
+  }
+  if (!hasOwn(response, 'token_type') || !hasOwn(response, 'issued_token_type')) {
+    throw new OpenAIError('X.509 workload identity token exchange returned an invalid token type.');
+  }
+  const tokenType = response['token_type'];
+  if (
+    typeof tokenType !== 'string' ||
+    tokenType.toLowerCase() !== 'bearer' ||
+    response['issued_token_type'] !== ACCESS_TOKEN_TYPE
+  ) {
+    throw new OpenAIError('X.509 workload identity token exchange returned an invalid token type.');
+  }
+
+  if (!hasOwn(response, 'expires_in')) {
+    throw new OpenAIError('X.509 workload identity token exchange returned an invalid token lifetime.');
+  }
+  const expiresIn = response['expires_in'];
+  if (typeof expiresIn !== 'number' || !Number.isFinite(expiresIn) || expiresIn <= 0 || expiresIn > 3600) {
+    throw new OpenAIError('X.509 workload identity token exchange returned an invalid token lifetime.');
+  }
+
+  return { accessToken: response['access_token'], expiresIn };
+}
+
+function safeResponseHeaders(response: Response, includeRetryHints = false): Headers {
+  const headers = new Headers();
+  for (const name of SAFE_RESPONSE_HEADERS) {
+    if (name !== 'x-request-id' && !includeRetryHints) {
+      continue;
+    }
+    const value = response.headers.get(name);
+    if (value !== null) {
+      headers.set(name, value);
+    }
+  }
+  return headers;
+}
+
+function readOAuthErrorCode(value: unknown): string | undefined {
+  if (typeof value === 'string') {
+    return value;
+  }
+  if (typeof value === 'object' && value !== null && hasOwn(value, 'code')) {
+    const code: unknown = Object.getOwnPropertyDescriptor(value, 'code')?.value;
+    return typeof code === 'string' ? code : undefined;
+  }
+  return undefined;
+}
+
+async function oauthError(
+  response: Response,
+  signal?: AbortSignal,
+  callerSignal?: AbortSignal,
+): Promise<OAuthError> {
+  let errorCode: { error: string } | undefined;
+
+  try {
+    const parsed = await readResponseBody(response, signal);
+    if (typeof parsed === 'object' && parsed !== null && hasOwn(parsed, 'error')) {
+      const code = readOAuthErrorCode(Object.getOwnPropertyDescriptor(parsed, 'error')?.value);
+      if (code !== undefined && SAFE_OAUTH_ERRORS.has(code)) {
+        errorCode = { error: code };
+      }
+    }
+  } catch {
+    callerSignal?.throwIfAborted();
+    if (
+      signal?.aborted &&
+      !(signal.reason instanceof APIConnectionTimeoutError && isTransientX509ConnectionError(signal.reason))
+    ) {
+      signal.throwIfAborted();
+    }
+  }
+
+  const { status } = response;
+  if (status !== 400 && status !== 401 && status !== 403) {
+    throw new OpenAIError('X.509 workload identity received an invalid OAuth error status.');
+  }
+  const headers = safeResponseHeaders(response);
+  const error = new OAuthError(status, errorCode, headers);
+  rememberX509OAuthError(error, { status, error: errorCode, headers });
+  return error;
+}
+
+/** Exchanges one enrolled client certificate for a validated OpenAI workload access token. */
+export async function exchangeX509Token(options: X509TokenExchangeOptions): Promise<X509ExchangedToken> {
+  const { signal: callerSignal } = options;
+  callerSignal?.throwIfAborted();
+  const { identityProviderId, serviceAccountId, transport } = options;
+  if (
+    typeof identityProviderId !== 'string' ||
+    identityProviderId.trim().length === 0 ||
+    typeof serviceAccountId !== 'string' ||
+    serviceAccountId.trim().length === 0
+  ) {
+    throw new OpenAIError(
+      'X.509 workload identity requires nonempty provider and service-account identifiers.',
+    );
+  }
+
+  const timeoutController = new AbortController();
+  const signal = callerSignal
+    ? AbortSignal.any([callerSignal, timeoutController.signal])
+    : timeoutController.signal;
+  const timeout = setTimeout(() => {
+    const error = new APIConnectionTimeoutError({
+      message: 'X.509 workload identity token exchange timed out.',
+    });
+    markTransientX509ConnectionError(error);
+    timeoutController.abort(error);
+  }, MAX_TOKEN_EXCHANGE_DURATION_MS);
+  timeout.unref();
+
+  try {
+    const body = JSON.stringify({
+      grant_type: TOKEN_EXCHANGE_GRANT,
+      subject_token_type: X509_SUBJECT_TOKEN,
+      identity_provider_id: identityProviderId,
+      service_account_id: serviceAccountId,
+    });
+
+    let response: Response;
+    try {
+      response = await sendX509Request(transport, TOKEN_EXCHANGE_URL, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body,
+        redirect: 'manual',
+        signal,
+      });
+    } catch (error) {
+      signal.throwIfAborted();
+      throw transientConnectionError('X.509 workload identity token exchange connection failed.', error);
+    }
+    signal.throwIfAborted();
+
+    if (response.ok) {
+      try {
+        return validateTokenResponse(await readResponseBody(response, signal));
+      } catch (error) {
+        signal.throwIfAborted();
+        if (error instanceof APIConnectionError) {
+          throw error;
+        }
+        if (error instanceof OpenAIError) {
+          throw APIError.generate(response.status, undefined, error.message, safeResponseHeaders(response));
+        }
+        throw error;
+      }
+    }
+    if (response.status === 400 || response.status === 401 || response.status === 403) {
+      throw await oauthError(response, signal, callerSignal);
+    }
+
+    cancelResponseBody(response);
+    const retryableStatus =
+      response.status === 408 || response.status === 409 || response.status === 429 || response.status >= 500;
+    const headers = safeResponseHeaders(response, retryableStatus);
+    const error = APIError.generate(
+      response.status,
+      undefined,
+      'X.509 workload identity token exchange failed.',
+      headers,
+    );
+    if (retryableStatus && headers.get('x-should-retry') !== 'false') {
+      markRetryableX509IssuerError(error);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+  }
+}

package/src/internal/auth/x509-transport-capability.ts

@@ -0,0 +1,219 @@
+import { types } from 'node:util';
+import { Agent, ProxyAgent, Request, fetch } from 'undici';
+import { OpenAIError } from '../../core/error';
+import { x509TransportBrand } from './x509-transport-registry';
+import type { RegisteredX509Transport, X509Transport } from './x509-transport-registry';
+import { findRegisteredX509Transport, rememberRegisteredX509Transport } from '#x509-transport-state';
+
+export type { X509Transport } from './x509-transport-registry';
+
+/** Explicitly supported, application-owned Undici proxy configurations. */
+export type X509ProxyMode = 'direct' | 'http-connect' | 'https-connect';
+
+/** Application attestation for one caller-owned static-certificate Undici transport. */
+export interface X509TransportOptions {
+  /** X.509 transport currently supports genuine Node.js runtimes only. */
+  runtime: 'node';
+
+  /** Caller-owned Undici Agent or ProxyAgent; the SDK never closes or inspects it. */
+  dispatcher: Agent | ProxyAgent;
+
+  /** Attests that the dispatcher uses one static workload-certificate identity. */
+  certificateIdentity: 'static';
+
+  /** Attests that proxy TLS and CONNECT credentials are independently configured. */
+  proxy: X509ProxyMode;
+}
+
+const allowedOptionNames = new Set(['runtime', 'dispatcher', 'certificateIdentity', 'proxy']);
+const transportBrand: typeof x509TransportBrand = x509TransportBrand;
+
+class NodeX509Transport implements X509Transport {
+  declare readonly [transportBrand]: true;
+
+  readonly #dispatcher: Agent | ProxyAgent;
+
+  constructor(dispatcher: Agent | ProxyAgent) {
+    this.#dispatcher = dispatcher;
+    Object.freeze(this);
+  }
+
+  static dispatcher(value: object): Agent | ProxyAgent | undefined {
+    return #dispatcher in value ? value.#dispatcher : undefined;
+  }
+}
+
+/** Registers only a genuine frozen capability whose JavaScript private dispatcher cannot be forged. */
+export function registerX509Transport(transport: X509Transport, registered: RegisteredX509Transport): void {
+  if (
+    !transport ||
+    typeof transport !== 'object' ||
+    types.isProxy(transport) ||
+    !Object.isFrozen(transport) ||
+    !NodeX509Transport.dispatcher(transport)
+  ) {
+    throw new OpenAIError('Only a genuine frozen X.509 transport capability can be registered.');
+  }
+  if (findRegisteredX509Transport(transport)) {
+    throw new OpenAIError('An approved X.509 transport capability cannot be registered more than once.');
+  }
+  rememberRegisteredX509Transport(transport, Object.freeze(registered));
+}
+
+function dataOption(options: X509TransportOptions, name: keyof X509TransportOptions): unknown {
+  const descriptor = Object.getOwnPropertyDescriptor(options, name);
+  if (!descriptor || !('value' in descriptor)) {
+    throw new Error(`X.509 transport option \`${name}\` must be an own plain data property.`);
+  }
+  return descriptor.value;
+}
+
+function assertNodeRuntime(): void {
+  if (
+    typeof process === 'undefined' ||
+    process.release.name !== 'node' ||
+    'bun' in process.versions ||
+    'Bun' in globalThis ||
+    'Deno' in globalThis
+  ) {
+    throw new Error('X.509 transport requires a genuine Node.js runtime.');
+  }
+}
+
+function attestedDispatcher(options: X509TransportOptions): Agent | ProxyAgent {
+  const dispatcher = dataOption(options, 'dispatcher');
+  if (!dispatcher || typeof dispatcher !== 'object') {
+    throw new Error('X.509 transport requires a caller-owned Undici Agent or ProxyAgent.');
+  }
+  if (types.isProxy(dispatcher)) {
+    throw new Error('X.509 transport does not accept a dispatcher proxy.');
+  }
+
+  const isDirect = dispatcher instanceof Agent;
+  const isConnect = dispatcher instanceof ProxyAgent;
+  if (!isDirect && !isConnect) {
+    throw new Error('X.509 transport requires a caller-owned Undici Agent or ProxyAgent.');
+  }
+
+  const proxy = dataOption(options, 'proxy');
+  if (proxy !== 'direct' && proxy !== 'http-connect' && proxy !== 'https-connect') {
+    throw new Error('X.509 transport requires an explicitly supported proxy mode.');
+  }
+  if ((proxy === 'direct') !== isDirect) {
+    throw new Error('An X.509 CONNECT proxy requires an Undici ProxyAgent.');
+  }
+
+  return dispatcher;
+}
+
+function assertRequestDispatcherSupport(dispatcher: Agent | ProxyAgent): void {
+  let observesRequestDispatcher = false;
+
+  // about:blank never reaches the network; the getter checks the actual fetch contract.
+  void Promise.allSettled([
+    fetch('about:blank', {
+      get dispatcher() {
+        observesRequestDispatcher = true;
+        return dispatcher;
+      },
+    }),
+  ]);
+
+  if (!observesRequestDispatcher) {
+    throw new Error('X.509 transport requires Undici 5.2.0 or later with per-request dispatcher support.');
+  }
+}
+
+function assertConnectProxySupport(): void {
+  const targetOrigin = 'https://127.0.0.1:65535';
+  let routedOrigin: string | undefined;
+  const probe = new ProxyAgent({
+    uri: 'http://127.0.0.1:1',
+    factory(origin) {
+      routedOrigin = String(origin);
+      throw new Error('X.509 CONNECT capability probe');
+    },
+  });
+
+  // The throwing factory reveals the actual routing decision before any socket opens.
+  const request = fetch(targetOrigin, { dispatcher: probe });
+  void Promise.allSettled([request, probe.close()]);
+
+  if (routedOrigin !== targetOrigin) {
+    throw new Error('X.509 CONNECT proxy requires Undici 5.5.1 or later with target TLS tunneling.');
+  }
+}
+
+/**
+ * Creates a frozen, opaque capability for one caller-owned Undici transport.
+ *
+ * `certificateIdentity: 'static'` is an application attestation: the SDK does
+ * not inspect certificates, private dispatcher internals, callbacks, or TLS
+ * options and cannot cryptographically prove certificate selection. Configure
+ * one static identity without custom dispatcher factories. For HTTPS CONNECT,
+ * independently configure `proxyTls` and `requestTls` so workload credentials
+ * never reach the proxy. Rotation requires creating a fresh dispatcher and
+ * capability; the application remains responsible for draining the old one.
+ *
+ * This Node-only preview entrypoint requires the optional `undici` peer at
+ * version 5.2.0 or later. CONNECT proxy modes require version 5.5.1 or
+ * later; ordinary SDK clients retain broader compatibility.
+ */
+export function createX509Transport(options: X509TransportOptions): X509Transport {
+  assertNodeRuntime();
+
+  if (!options || typeof options !== 'object' || types.isProxy(options)) {
+    throw new Error('X.509 transport configuration must be a non-proxy object.');
+  }
+
+  for (const name of Reflect.ownKeys(options)) {
+    if (typeof name !== 'string' || !allowedOptionNames.has(name)) {
+      throw new Error(`Unsupported X.509 transport option: \`${String(name)}\`.`);
+    }
+  }
+
+  if (dataOption(options, 'runtime') !== 'node') {
+    throw new Error('X.509 transport requires an explicitly attested Node.js runtime.');
+  }
+
+  if (dataOption(options, 'certificateIdentity') !== 'static') {
+    throw new Error('X.509 transport requires an explicitly attested static client certificate.');
+  }
+
+  const dispatcher = attestedDispatcher(options);
+  assertRequestDispatcherSupport(dispatcher);
+  if (dispatcher instanceof ProxyAgent) {
+    assertConnectProxySupport();
+  }
+  return new NodeX509Transport(dispatcher);
+}
+
+/** Dispatches through the opaque attested transport without accepting replacement dispatchers. */
+export async function sendX509Request(
+  transport: X509Transport,
+  target: URL,
+  options: RequestInit,
+): Promise<Response> {
+  if (!transport || typeof transport !== 'object' || types.isProxy(transport)) {
+    throw new Error('Invalid X.509 transport capability.');
+  }
+
+  const dispatcher = NodeX509Transport.dispatcher(transport);
+  if (!dispatcher) {
+    throw new Error('Invalid X.509 transport capability.');
+  }
+
+  const normalizedTarget = new URL(target.href);
+  if (normalizedTarget.protocol !== 'https:') {
+    throw new Error('X.509 transport requires an HTTPS destination.');
+  }
+
+  if (Object.getOwnPropertyDescriptor(options, 'dispatcher')) {
+    throw new Error('X.509 transport does not allow a per-request dispatcher override.');
+  }
+
+  const requestOptions: Omit<RequestInit, 'dispatcher'> = options;
+  const request = new Request(normalizedTarget, requestOptions);
+  const response = await fetch(request, { dispatcher, redirect: 'manual' });
+  return response;
+}