@rebyteai/agent-sdk 0.2.0

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,226 @@
+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.
+   *
+   * The application attests that its dispatcher, factories, TLS verification,
+   * certificate selection, and CONNECT proxy configuration are trustworthy.
+   * Use `fromX509` when the SDK should own and enforce transport configuration.
+   */
+  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
+ * trusted dispatcher factories, verified target and proxy TLS, one static
+ * certificate identity, and independently scoped CONNECT credentials.
+ * Prefer the SDK-owned `fromX509` credential when these guarantees should be
+ * enforced at construction. Rotation requires a fresh caller-owned dispatcher
+ * and capability; the application remains responsible for draining it.
+ *
+ * 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;
+}

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

@@ -0,0 +1,127 @@
+import { OpenAIError } from '../../core/error';
+import type { NullableHeaders } from '../headers';
+import type { X509WorkloadIdentity } from '../../auth/types';
+import type { ReadableStream } from '../shim-types';
+import type { MergedRequestInit } from '../types';
+import { findRegisteredX509Transport } from '#x509-transport-state';
+
+const transientX509TransportCodes = new Set([
+  'ECONNRESET',
+  'ECONNREFUSED',
+  'ENETUNREACH',
+  'EHOSTUNREACH',
+  'ENETDOWN',
+  'EPIPE',
+  'ETIMEDOUT',
+  'EAI_AGAIN',
+  'UND_ERR_CONNECT_TIMEOUT',
+  'UND_ERR_HEADERS_TIMEOUT',
+  'UND_ERR_BODY_TIMEOUT',
+  'UND_ERR_SOCKET',
+]);
+
+/** Retries only known temporary failures when neither error layer reports a permanent code. */
+export function isRetryableX509TransportFailure(failure: unknown): boolean {
+  const cause =
+    typeof failure === 'object' && failure !== null
+      ? Object.getOwnPropertyDescriptor(failure, 'cause')?.value
+      : undefined;
+  let retryable = false;
+  for (const candidate of [failure, cause]) {
+    const code =
+      typeof candidate === 'object' && candidate !== null
+        ? Object.getOwnPropertyDescriptor(candidate, 'code')?.value
+        : undefined;
+    if (typeof code === 'string') {
+      if (!transientX509TransportCodes.has(code)) {
+        return false;
+      }
+      retryable = true;
+    }
+  }
+  return retryable;
+}
+
+export const x509TransportBrand: unique symbol = Symbol('X.509 transport capability');
+
+/** Opaque identity of one frozen, caller-owned, explicitly attested X.509 transport. */
+export interface X509Transport {
+  /** Prevents ordinary objects from satisfying the transport capability contract. */
+  readonly [x509TransportBrand]: true;
+}
+
+/** Immutable selectors and transport privately registered for an SDK-owned credential. */
+export interface RegisteredX509Credential {
+  readonly identity: X509WorkloadIdentity;
+  readonly transport: X509Transport;
+}
+
+/** Validated short-lived token exchanged using a registered certificate identity. */
+export interface X509ExchangedToken {
+  /** Header-safe, in-memory OpenAI bearer credential. */
+  accessToken: string;
+
+  /** Issuer-approved positive token lifetime in seconds. */
+  expiresIn: number;
+}
+
+/** One logical certificate-authenticated operation and its immutable starting deadline. */
+export interface X509RequestScope {
+  wallStartedAt: number;
+  monotonicStartedAt: number;
+  deadlineArmed?: boolean;
+  preparationStartedAt?: number;
+  preparationWallStartedAt?: number;
+  request?: { signal: AbortSignal | null | undefined; timeout: number; fetchOptions: MergedRequestInit };
+  phase?: 'planning' | 'authorizing';
+  effectiveSignal?: AbortSignal;
+  materializedBody?: ReadableStream;
+  owner?: object;
+  requestOwner?: object;
+  apiURL?: string;
+  tenant?: { organization: string | null; project: string | null };
+  defaultHeaders?: NullableHeaders;
+  requestHeaders?: NullableHeaders;
+  token?: string;
+  tokenGeneration?: number;
+  headers?: Headers;
+  authorization?: string | null;
+}
+
+/** Private, peer-independent operations attached to one approved transport generation. */
+export interface RegisteredX509Transport {
+  /** Dispatches one request through the exact frozen certificate capability. */
+  dispatch: (target: URL, options: RequestInit) => Promise<Response>;
+
+  /** Exchanges the same certificate identity for an OpenAI service-account bearer. */
+  exchange: (
+    identityProviderId: string,
+    serviceAccountId: string,
+    signal?: AbortSignal,
+  ) => Promise<X509ExchangedToken>;
+
+  /** Establishes one isolated Node async context without exposing Node dependencies to the root SDK. */
+  run: <T>(operation: () => T) => T;
+
+  /** Resolves only the current logical request's private certificate-authentication scope. */
+  current: () => X509RequestScope | undefined;
+
+  /** Re-enters the original request scope when response parsing resumes outside its promise chain. */
+  resume: <T>(scope: X509RequestScope, operation: () => T) => T;
+
+  /** Waits for retry backoff using an abortable timer that keeps an active request alive. */
+  sleep: (duration: number, signal?: AbortSignal | null) => Promise<void>;
+}
+
+/** Resolves a previously registered opaque capability without importing an optional transport peer. */
+export function resolveX509Transport(value: unknown): RegisteredX509Transport {
+  if (!value || typeof value !== 'object') {
+    throw new OpenAIError('X.509 workload identity requires an approved X.509 transport capability.');
+  }
+
+  const registered: RegisteredX509Transport | undefined = findRegisteredX509Transport(value);
+  if (!registered) {
+    throw new OpenAIError('X.509 workload identity requires an approved X.509 transport capability.');
+  }
+  return registered;
+}