openai 7.5.0 → 7.7.0

package/src/lib/webhook-signature.ts

@@ -0,0 +1,164 @@
+import { InvalidWebhookSignatureError } from '../error';
+import { fromBase64 } from '../internal/utils/base64';
+import { encodeUTF8 } from '../internal/utils/bytes';
+
+const MAX_DIRECT_WEBHOOK_VERIFICATIONS = 32;
+const SHA256_SIGNATURE_LENGTH = 32;
+
+/**
+ * Checks whether a webhook header requires constant-work HMAC signing without
+ * retaining an unbounded number of signature candidates.
+ *
+ * @internal
+ */
+export function webhookSignatureRequiresSigning(signatureHeader: string): boolean {
+  return (
+    signatureHeader.split(' ', MAX_DIRECT_WEBHOOK_VERIFICATIONS + 1).length > MAX_DIRECT_WEBHOOK_VERIFICATIONS
+  );
+}
+
+function* signatureCandidates(signatureHeader: string): Generator<string> {
+  let start = 0;
+
+  while (start <= signatureHeader.length) {
+    const separator = signatureHeader.indexOf(' ', start);
+    const candidate = signatureHeader.slice(start, separator === -1 ? undefined : separator);
+    yield candidate.startsWith('v1,') ? candidate.slice(3) : candidate;
+
+    if (separator === -1) {
+      break;
+    }
+    start = separator + 1;
+  }
+}
+
+function decodeSignature(signature: string): Uint8Array | undefined {
+  try {
+    const signatureBytes = fromBase64(signature);
+    return signatureBytes.byteLength === SHA256_SIGNATURE_LENGTH ? signatureBytes : undefined;
+  } catch {
+    // Invalid base64 does not prevent trying the next value.
+    return undefined;
+  }
+}
+
+function firstValidLengthSignature(signatureHeader: string): Uint8Array | undefined {
+  for (const signature of signatureCandidates(signatureHeader)) {
+    const signatureBytes = decodeSignature(signature);
+    if (signatureBytes) {
+      return signatureBytes;
+    }
+  }
+
+  return undefined;
+}
+
+function selectMatchingSignature(
+  signatureHeader: string,
+  expectedSignature: Uint8Array,
+  firstSignature: Uint8Array,
+): Uint8Array {
+  let matchingSignature = firstSignature;
+
+  for (const signature of signatureCandidates(signatureHeader)) {
+    const signatureBytes = decodeSignature(signature);
+    if (!signatureBytes) {
+      continue;
+    }
+
+    let difference = 0;
+    for (const [index, byte] of signatureBytes.entries()) {
+      // oxlint-disable-next-line no-bitwise -- Compare every HMAC byte without short-circuiting on shared prefixes.
+      difference |= byte ^ (expectedSignature[index] ?? 0);
+    }
+    if (difference === 0) {
+      matchingSignature = signatureBytes;
+    }
+  }
+
+  return matchingSignature;
+}
+
+/**
+ * Checks the timestamp and HMAC signatures after the resource has validated its
+ * crypto capabilities, secret, and required headers.
+ *
+ * @internal
+ */
+export async function verifyWebhookSignature(
+  payload: string,
+  signatureHeader: string,
+  timestamp: string,
+  webhookId: string,
+  secret: string,
+  tolerance: number,
+): Promise<void> {
+  // oxlint-disable-next-line unicorn/prefer-number-coercion -- Preserve numeric-prefix parsing while signing the original timestamp text.
+  const timestampSeconds = Number.parseInt(timestamp, 10);
+  if (Number.isNaN(timestampSeconds)) {
+    throw new InvalidWebhookSignatureError('Invalid webhook timestamp format');
+  }
+
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  if (nowSeconds - timestampSeconds > tolerance) {
+    throw new InvalidWebhookSignatureError('Webhook timestamp is too old');
+  }
+  if (timestampSeconds > nowSeconds + tolerance) {
+    throw new InvalidWebhookSignatureError('Webhook timestamp is too new');
+  }
+
+  // Multiple signatures are space-separated; accept a matching value at any position.
+  const useBoundedVerification = webhookSignatureRequiresSigning(signatureHeader);
+  const firstSignature = useBoundedVerification ? firstValidLengthSignature(signatureHeader) : undefined;
+
+  if (useBoundedVerification && !firstSignature) {
+    throw new InvalidWebhookSignatureError(
+      'The given webhook signature does not match the expected signature',
+    );
+  }
+
+  const decodedSecret = Uint8Array.from(
+    secret.startsWith('whsec_') ? fromBase64(secret.slice('whsec_'.length)) : encodeUTF8(secret),
+  );
+  const signedPayload = webhookId ? `${webhookId}.${timestamp}.${payload}` : `${timestamp}.${payload}`;
+  const signedPayloadBytes = Uint8Array.from(encodeUTF8(signedPayload));
+  const key = await crypto.subtle.importKey(
+    'raw',
+    decodedSecret,
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    useBoundedVerification ? ['sign', 'verify'] : ['verify'],
+  );
+
+  if (useBoundedVerification && firstSignature) {
+    const expectedSignature = new Uint8Array(await crypto.subtle.sign('HMAC', key, signedPayloadBytes));
+    const signatureToVerify = selectMatchingSignature(signatureHeader, expectedSignature, firstSignature);
+
+    try {
+      if (await crypto.subtle.verify('HMAC', key, Uint8Array.from(signatureToVerify), signedPayloadBytes)) {
+        return;
+      }
+    } catch {
+      // Provider verification failures have the same typed mismatch as the direct path.
+    }
+
+    throw new InvalidWebhookSignatureError(
+      'The given webhook signature does not match the expected signature',
+    );
+  }
+
+  for (const signature of signatureCandidates(signatureHeader)) {
+    try {
+      const signatureBytes = Uint8Array.from(fromBase64(signature));
+      // oxlint-disable-next-line no-await-in-loop -- Check signatures in order and stop at the first match.
+      const isValid = await crypto.subtle.verify('HMAC', key, signatureBytes, signedPayloadBytes);
+      if (isValid) {
+        return;
+      }
+    } catch {
+      // Invalid base64 or signature format does not prevent trying the next value.
+    }
+  }
+
+  throw new InvalidWebhookSignatureError('The given webhook signature does not match the expected signature');
+}

package/src/realtime/internal-base.ts

@@ -8,6 +8,20 @@ import { EventEmitter } from '../lib/EventEmitter';
 import { OpenAIError } from '../error';
 import type OpenAI from '../index';
 import { AzureOpenAI } from '../index';
+import { assertX509WebSocketSupported } from '../internal/auth/x509-workload-identity-auth';
+
+/** Parses frame data without exposing malformed payloads through JSON syntax errors. */
+export function parseRealtimeEvent(data: string): RealtimeServerEvent {
+  try {
+    return JSON.parse(data) as RealtimeServerEvent;
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new SyntaxError('Could not parse Realtime WebSocket event data as JSON.');
+    }
+
+    throw error;
+  }
+}
 
 function safeErrorValue(value: unknown): string {
   try {
@@ -239,6 +253,7 @@ export function buildRealtimeURL(
   client: Pick<OpenAI, 'apiKey' | 'baseURL'>,
   connection: string | RealtimeConnectionConfig,
 ): URL {
+  assertX509WebSocketSupported(client);
   const config: RealtimeConnectionConfig =
     typeof connection === 'string' ? { model: connection } : connection;
   const baseURL = client.baseURL;

package/src/realtime/websocket.ts

@@ -2,12 +2,13 @@ import type { AzureOpenAI } from '../index';
 import { assertBedrockWebSocketOrigin } from '../internal/bedrock';
 import { OpenAI } from '../index';
 import { OpenAIError } from '../error';
-import type { RealtimeClientEvent, RealtimeServerEvent } from '../resources/realtime/realtime';
+import type { RealtimeClientEvent } from '../resources/realtime/realtime';
 import {
   OpenAIRealtimeEmitter,
   buildRealtimeURL,
   getAzureRealtimeConnection,
   isAzure,
+  parseRealtimeEvent,
 } from './internal-base';
 import type { AzureRealtimeConnectionConfig, RealtimeConnectionConfig } from './internal-base';
 import { isRunningInBrowser } from '../internal/detect-platform';
@@ -25,10 +26,82 @@ type _WebSocket = typeof globalThis extends {
     InstanceType<ws>
   : any;
 
-/** Removes Azure credential query values from the publicly exposed connection URL. */
-function redactAzureCredentials(url: URL): void {
-  const hasAuthorization = url.searchParams.has('Authorization');
-  if (url.searchParams.has('api-key') || !hasAuthorization) {
+type RuntimeScope = typeof globalThis & {
+  process?: { versions?: { node?: string } };
+  WorkerGlobalScope?: typeof Object;
+  WorkerNavigator?: typeof Object;
+  Deno?: { version?: { deno?: string } };
+  Bun?: { version?: string };
+  EdgeRuntime?: unknown;
+  WebSocketPair?: unknown;
+};
+
+/** Identifies browser pages and workers without blocking trusted server runtimes. */
+function isRunningInBrowserOrBrowserWorker(): boolean {
+  if (isRunningInBrowser()) {
+    return true;
+  }
+
+  const scope = globalThis as RuntimeScope;
+  return (
+    typeof scope.WorkerGlobalScope === 'function' &&
+    scope instanceof scope.WorkerGlobalScope &&
+    typeof scope.WorkerNavigator === 'function' &&
+    scope.navigator instanceof scope.WorkerNavigator &&
+    typeof scope.navigator?.userAgent === 'string' &&
+    scope.navigator.userAgent !== 'Cloudflare-Workers' &&
+    scope.process?.versions?.node === undefined &&
+    scope.Deno === undefined &&
+    scope.Bun === undefined &&
+    scope.EdgeRuntime === undefined &&
+    scope.WebSocketPair === undefined
+  );
+}
+
+/** Reports whether the runtime supports request headers in native WebSocket options. */
+function supportsWebSocketRequestHeaders(): boolean {
+  const scope = globalThis as RuntimeScope;
+  if (
+    isRunningInBrowserOrBrowserWorker() ||
+    scope.EdgeRuntime !== undefined ||
+    scope.WebSocketPair !== undefined ||
+    scope.navigator?.userAgent === 'Cloudflare-Workers'
+  ) {
+    return false;
+  }
+
+  if (scope.Deno !== undefined) {
+    const [major, minor] = (scope.Deno.version?.deno ?? '').split('.').map(Number);
+    return major !== undefined && minor !== undefined && (major > 2 || (major === 2 && minor >= 5));
+  }
+
+  if (typeof scope.Bun?.version === 'string') {
+    return true;
+  }
+
+  return (
+    Object.prototype.toString.call(scope.process) === '[object process]' &&
+    typeof scope.process?.versions?.node === 'string'
+  );
+}
+
+/** Removes Azure credentials while preserving the existing public URL redaction contract. */
+function redactAzureCredentials(url: URL, isBearerToken: boolean): void {
+  let hasApiKey = !isBearerToken;
+  let hasAuthorization = isBearerToken;
+  const parameterNames = [...url.searchParams.keys()];
+
+  for (const name of parameterNames) {
+    if (name.toLowerCase() === 'api-key') {
+      hasApiKey = true;
+      url.searchParams.delete(name);
+    } else if (name.toLowerCase() === 'authorization') {
+      hasAuthorization = true;
+      url.searchParams.delete(name);
+    }
+  }
+
+  if (hasApiKey) {
     url.searchParams.set('api-key', '<REDACTED>');
   }
   if (hasAuthorization) {
@@ -36,6 +109,32 @@ function redactAzureCredentials(url: URL): void {
   }
 }
 
+/** Opens an Azure native socket with header authentication and a credential-free URL. */
+function createAzureWebSocket(
+  url: URL,
+  apiKey: string | null,
+  isBearerToken: boolean,
+  protocols: string[],
+): _WebSocket {
+  if (!supportsWebSocketRequestHeaders()) {
+    throw new OpenAIError(
+      'Azure OpenAI Realtime credentials require a WebSocket transport that supports request headers; use openai/realtime/ws or a server-side authentication proxy.',
+    );
+  }
+  if (!apiKey) {
+    throw new Error('Azure OpenAI Realtime requires an API key');
+  }
+
+  redactAzureCredentials(url, isBearerToken);
+  const socketURL = new URL(url);
+  socketURL.searchParams.delete('api-key');
+  socketURL.searchParams.delete('Authorization');
+  const headers = isBearerToken ? { Authorization: `Bearer ${apiKey}` } : { 'api-key': apiKey };
+
+  // @ts-ignore
+  return new WebSocket(socketURL.toString(), { protocols, headers });
+}
+
 /**
  * Connects to the Realtime API using the runtime's native `WebSocket` implementation.
  *
@@ -85,7 +184,7 @@ export class OpenAIRealtimeWebSocket extends OpenAIRealtimeEmitter {
       props.dangerouslyAllowBrowser ??
       (client as any)?._options?.dangerouslyAllowBrowser ??
       (client?.apiKey?.startsWith('ek_') ? true : null);
-    if (!dangerouslyAllowBrowser && isRunningInBrowser()) {
+    if (!dangerouslyAllowBrowser && isRunningInBrowserOrBrowserWorker()) {
       throw new OpenAIError(
         "It looks like you're running in a browser-like environment.\n\nThis is disabled by default, as it risks exposing your secret API credentials to attackers.\n\nYou can avoid this error by creating an ephemeral session token:\nhttps://platform.openai.com/docs/api-reference/realtime-sessions\n",
       );
@@ -104,18 +203,34 @@ export class OpenAIRealtimeWebSocket extends OpenAIRealtimeEmitter {
 
     this.url = buildRealtimeURL(client, props);
     props.onURL?.(this.url);
+    if (this.url.protocol !== 'wss:') {
+      throw new OpenAIError('Realtime WebSocket URLs must use the wss: protocol.');
+    }
     assertBedrockWebSocketOrigin(client, this.url);
 
-    // @ts-ignore
-    this.socket = new WebSocket(this.url.toString(), [
-      'realtime',
-      ...(isAzure(client) ? [] : [`openai-insecure-api-key.${client.apiKey}`]),
-    ]);
+    const azure = isAzure(client);
+    const protocols = ['realtime', ...(azure ? [] : [`openai-insecure-api-key.${client.apiKey}`])];
+
+    this.socket = azure
+      ? createAzureWebSocket(this.url, client.apiKey, props.__resolvedApiKey === true, protocols)
+      : new WebSocket(this.url.toString(), protocols);
 
     this.socket.addEventListener('message', (websocketEvent: MessageEvent) => {
       const event = (() => {
         try {
-          return JSON.parse(websocketEvent.data.toString()) as RealtimeServerEvent;
+          const parsedEvent = parseRealtimeEvent(websocketEvent.data.toString());
+
+          if (
+            typeof parsedEvent !== 'object' ||
+            parsedEvent === null ||
+            Array.isArray(parsedEvent) ||
+            !Object.getOwnPropertyDescriptor(parsedEvent, 'type') ||
+            typeof parsedEvent.type !== 'string'
+          ) {
+            throw new TypeError('Realtime WebSocket event must be an object with a string type.');
+          }
+
+          return parsedEvent;
         } catch (err) {
           this._onError(null, 'could not parse websocket event', err);
           return null;
@@ -137,10 +252,6 @@ export class OpenAIRealtimeWebSocket extends OpenAIRealtimeEmitter {
     this.socket.addEventListener('error', (event: any) => {
       this._onError(null, event.message, null);
     });
-
-    if (isAzure(client)) {
-      redactAzureCredentials(this.url);
-    }
   }
 
   /**
@@ -174,8 +285,9 @@ export class OpenAIRealtimeWebSocket extends OpenAIRealtimeEmitter {
   /**
    * Opens a native Azure deployment or transcription session, or an existing sideband call.
    *
-   * Azure credentials are included only in the initial connection URL and are
-   * redacted from the exposed `url` property immediately after connection setup.
+   * Azure credentials are sent in WebSocket handshake headers and never appear
+   * in the native socket URL. Browser WebSockets cannot set these headers;
+   * use a server-side authentication proxy or the Node.js `ws` transport.
    *
    * @param client Azure OpenAI client that supplies the endpoint and credential.
    * @param options Deployment, transcription intent, or call ID, plus browser-safety settings.
@@ -194,19 +306,10 @@ export class OpenAIRealtimeWebSocket extends OpenAIRealtimeEmitter {
     if (!apiKey) {
       throw new Error('Azure OpenAI Realtime requires an API key');
     }
-    const azureApiKey = apiKey;
-    function onURL(url: URL) {
-      if (isApiKeyProvider) {
-        url.searchParams.set('Authorization', `Bearer ${azureApiKey}`);
-      } else {
-        url.searchParams.set('api-key', azureApiKey);
-      }
-    }
     const { dangerouslyAllowBrowser } = options;
     return new OpenAIRealtimeWebSocket(
       {
         ...connection,
-        onURL,
         ...(dangerouslyAllowBrowser === undefined ? {} : { dangerouslyAllowBrowser }),
         __resolvedApiKey: isApiKeyProvider,
       },

package/src/realtime/ws.ts

@@ -3,12 +3,13 @@ import { assertBedrockWebSocketOrigin } from '../internal/bedrock';
 import { protectWebSocketOptionsFromCredentialRedirects } from '../internal/ws';
 import type { AzureOpenAI } from '../index';
 import { OpenAI } from '../index';
-import type { RealtimeClientEvent, RealtimeServerEvent } from '../resources/realtime/realtime';
+import type { RealtimeClientEvent } from '../resources/realtime/realtime';
 import {
   OpenAIRealtimeEmitter,
   buildRealtimeURL,
   getAzureRealtimeConnection,
   isAzure,
+  parseRealtimeEvent,
 } from './internal-base';
 import type { AzureRealtimeConnectionConfig, RealtimeConnectionConfig } from './internal-base';
 
@@ -76,7 +77,19 @@ export class OpenAIRealtimeWS extends OpenAIRealtimeEmitter {
     this.socket.on('message', (wsEvent) => {
       const event = (() => {
         try {
-          return JSON.parse(wsEvent.toString()) as RealtimeServerEvent;
+          const parsedEvent = parseRealtimeEvent(wsEvent.toString());
+
+          if (
+            typeof parsedEvent !== 'object' ||
+            parsedEvent === null ||
+            Array.isArray(parsedEvent) ||
+            !Object.getOwnPropertyDescriptor(parsedEvent, 'type') ||
+            typeof parsedEvent.type !== 'string'
+          ) {
+            throw new TypeError('Realtime WebSocket event must be an object with a string type.');
+          }
+
+          return parsedEvent;
         } catch (err) {
           this._onError(null, 'could not parse websocket event', err);
           return null;

package/src/resources/admin/organization/index.ts

@@ -59,6 +59,7 @@ export { Organization } from './organization';
 export {
   Projects,
   type Project,
+  type ProjectResidency,
   type ProjectCreateParams,
   type ProjectUpdateParams,
   type ProjectListParams,
@@ -90,6 +91,7 @@ export {
 } from './spend-limit';
 export {
   Usage,
+  type CostQuantityUnit,
   type UsageAudioSpeechesResponse,
   type UsageAudioTranscriptionsResponse,
   type UsageCodeInterpreterSessionsResponse,

package/src/resources/admin/organization/organization.ts

@@ -71,6 +71,7 @@ import {
 } from './spend-limit';
 import * as UsageAPI from './usage';
 import {
+  CostQuantityUnit,
   Usage,
   UsageAudioSpeechesParams,
   UsageAudioSpeechesResponse,
@@ -111,6 +112,7 @@ import {
   Project,
   ProjectCreateParams,
   ProjectListParams,
+  ProjectResidency,
   ProjectUpdateParams,
   Projects,
   ProjectsPage,
@@ -173,6 +175,7 @@ export declare namespace Organization {
 
   export {
     Usage as Usage,
+    type CostQuantityUnit as CostQuantityUnit,
     type UsageAudioSpeechesResponse as UsageAudioSpeechesResponse,
     type UsageAudioTranscriptionsResponse as UsageAudioTranscriptionsResponse,
     type UsageCodeInterpreterSessionsResponse as UsageCodeInterpreterSessionsResponse,
@@ -280,6 +283,7 @@ export declare namespace Organization {
   export {
     Projects as Projects,
     type Project as Project,
+    type ProjectResidency as ProjectResidency,
     type ProjectsPage as ProjectsPage,
     type ProjectCreateParams as ProjectCreateParams,
     type ProjectUpdateParams as ProjectUpdateParams,

package/src/resources/admin/organization/projects/index.ts

@@ -46,6 +46,7 @@ export {
 export {
   Projects,
   type Project,
+  type ProjectResidency,
   type ProjectCreateParams,
   type ProjectUpdateParams,
   type ProjectListParams,

package/src/resources/admin/organization/projects/projects.ts

@@ -273,12 +273,31 @@ export interface Project {
    */
   name?: string | null;
 
+  /**
+   * The residency configuration for the project.
+   */
+  residency?: ProjectResidency;
+
   /**
    * `active` or `archived`
    */
   status?: string | null;
 }
 
+export type ProjectResidency =
+  | 'GLOBAL'
+  | 'US_STORAGE_PROCESSING'
+  | 'EU_STORAGE_PROCESSING'
+  | 'JP_STORAGE'
+  | 'KR_STORAGE'
+  | 'CA_STORAGE'
+  | 'SG_STORAGE'
+  | 'IN_STORAGE'
+  | 'AU_STORAGE'
+  | 'GB_STORAGE'
+  | 'AE_STORAGE'
+  | 'AE_STORAGE_PROCESSING';
+
 export interface ProjectCreateParams {
   /**
    * The friendly name of the project, this name appears in reports.
@@ -291,12 +310,23 @@ export interface ProjectCreateParams {
   external_key_id?: string | null;
 
   /**
-   * Create the project with the specified data residency region. Your organization
-   * must have access to Data residency functionality in order to use. See
+   * @deprecated Create the project with the specified data residency region. Your
+   * organization must have access to Data residency functionality in order to use.
+   * See
    * [data residency controls](https://platform.openai.com/docs/guides/your-data#data-residency-controls)
-   * to review the functionality and limitations of setting this field.
+   * to review the functionality and limitations of setting this field. Deprecated:
+   * use `residency` instead. Do not provide both `geography` and `residency`.
    */
   geography?: string | null;
+
+  /**
+   * Create the project with the specified residency configuration. Your organization
+   * must have access to the requested residency configuration in order to use it.
+   * See
+   * [data residency controls](https://platform.openai.com/docs/guides/your-data#data-residency-controls)
+   * to review the functionality and limitations of setting this field.
+   */
+  residency?: ProjectResidency | null;
 }
 
 export interface ProjectUpdateParams {
@@ -306,7 +336,9 @@ export interface ProjectUpdateParams {
   external_key_id?: string | null;
 
   /**
-   * Geography for the project.
+   * @deprecated Geography for the project. Deprecated: use `residency` when creating
+   * a project to configure data residency. This field is retained for backward
+   * compatibility.
    */
   geography?: string | null;
 
@@ -340,6 +372,7 @@ Projects.Certificates = Certificates;
 export declare namespace Projects {
   export {
     type Project as Project,
+    type ProjectResidency as ProjectResidency,
     type ProjectsPage as ProjectsPage,
     type ProjectCreateParams as ProjectCreateParams,
     type ProjectUpdateParams as ProjectUpdateParams,