createOpenAIMinter

createOpenAIMinter(options): (input) => Promise<MintResult>

Defined in: packages/realtime-openai-server/src/lib/openai-mint.ts:208

Creates a transport-agnostic minter that exchanges a server-held OpenAI API key for a short-lived realtime client secret on behalf of the browser, so the browser never sees OPENAI_API_KEY.

The minter validates input against OpenAITokenRequest. When that request includes a model, the request model overrides the configured default. It then calls OpenAI’s client_secrets endpoint with the server-held key in the Authorization header, and maps the upstream response to an OpenAITokenGrant. The API key is only ever sent upstream — it is never echoed back in the result. Redirects are rejected rather than forwarding that server-held credential to another URL; redirect and network failures return upstream-failure without an upstream status. Callers own all transport concerns: parsing the request body into input, and mapping MintResult to a status code / response body.

This mint operation is an unauthenticated bootstrap: anyone who can invoke it can mint a short-lived OpenAI realtime credential. Production transport code must authenticate and authorize callers, enforce a trusted model policy instead of accepting arbitrary model overrides, and add origin controls, rate limits, and abuse controls before exposing the minter. The example below treats authentication, CSRF, origin, model selection, shared rate limiting, and redacted telemetry as mandatory app-provided fail-closed contracts. Keep the exact server-side origin allowlist check first. When authentication and CSRF validation are not demonstrably cheap and constant-time, run an app-provided fail-closed pre-auth transport throttle before both controls. Key it from a trusted server- or proxy-derived IP-equivalent client address, and reject browser-controlled forwarding headers rather than treating them as trusted address data. Retain the shared principal-keyed limit after authentication and CSRF validation. Both throttles must deny on store failure, return a bounded retry delay, and use the same generic 429 body. Browser input may request a model, but it must never define or widen the trusted server-side model allowlist.

Only handles provider: 'openai' requests — a google minter is a sibling. sessionId is accepted and validated but currently unused by this minter; it’s reserved for the sidechannel receiver to bind the minted session to the Maelstrom session.

Parameters

options

CreateOpenAIMinterOptions

Returns

(input) => Promise<MintResult>

Example

import { isOk } from '@maelstrom-co/protocol';
import {
  createOpenAIMinter,
  mintFailureHttpStatus,
} from '@maelstrom-co/realtime-openai-server';
import { requireAuthenticatedRealtimeSession } from './auth';
import {
  areRealtimeMintAuthAndCsrfCheapAndConstantTime,
  consumeRealtimeMintPreAuthRateLimit,
  consumeRealtimeMintRateLimit,
  isTrustedRealtimeMintOrigin,
  isValidRealtimeMintCsrf,
  resolveTrustedRealtimeMintClientAddress,
  resolveAllowedRealtimeModel,
} from './realtime-mint-policy';
import { reportRedactedRealtimeMintFailure } from './redacted-telemetry';

const mint = createOpenAIMinter({
  apiKey: process.env.OPENAI_API_KEY!,
  model: 'gpt-realtime-2.1',
});
const headers = { 'Cache-Control': 'private, no-store' };

export async function POST(request: Request): Promise<Response> {
  try {
    if (!isTrustedRealtimeMintOrigin(request)) {
      return Response.json({ error: 'request-denied' }, { status: 403, headers });
    }

    if (!areRealtimeMintAuthAndCsrfCheapAndConstantTime()) {
      const clientAddress = resolveTrustedRealtimeMintClientAddress(request);
      if (clientAddress === null) {
        return Response.json({ error: 'request-denied' }, { status: 403, headers });
      }

      const preAuthRateLimit =
        await consumeRealtimeMintPreAuthRateLimit(clientAddress);
      if (!preAuthRateLimit.allowed) {
        return Response.json(
          { error: 'rate-limited' },
          {
            status: 429,
            headers: {
              ...headers,
              'Retry-After': String(preAuthRateLimit.retryAfterSeconds),
            },
          },
        );
      }
    }

    const authenticated = await requireAuthenticatedRealtimeSession(request);
    if (authenticated === null) {
      return Response.json({ error: 'unauthorized' }, { status: 401, headers });
    }

    if (!isValidRealtimeMintCsrf(request, authenticated)) {
      return Response.json({ error: 'request-denied' }, { status: 403, headers });
    }

    const rateLimit = await consumeRealtimeMintRateLimit(authenticated.principalId);
    if (!rateLimit.allowed) {
      return Response.json(
        { error: 'rate-limited' },
        {
          status: 429,
          headers: { ...headers, 'Retry-After': String(rateLimit.retryAfterSeconds) },
        },
      );
    }

    let input: unknown;
    try {
      input = await request.json();
    } catch {
      return Response.json({ error: 'invalid-request' }, { status: 400, headers });
    }

    const model = resolveAllowedRealtimeModel(authenticated, input);
    if (model === null) {
      return Response.json({ error: 'request-denied' }, { status: 403, headers });
    }

    const result = await mint({
      provider: 'openai',
      sessionId: authenticated.sessionId,
      model,
    });
    if (isOk(result)) return Response.json(result.value, { headers });

    return Response.json(
      { error: 'mint-failed' },
      { status: mintFailureHttpStatus(result.error.reason), headers },
    );
  } catch (error) {
    try {
      await reportRedactedRealtimeMintFailure({
        source: 'openai-token-route',
        error,
      });
    } catch {
      // Telemetry failure must not escape the HTTP boundary.
    }
    return Response.json({ error: 'mint-failed' }, { status: 500, headers });
  }
}

OpenAI recommends an OpenAI-Safety-Identifier header for client-secret creation. This minter does not yet expose a public upstream-header option, so adding that support remains a follow-up rather than an implied capability of this example.