Lab 01 · Chapter 2 — Build file by file

import { defineConfig } from "vitest/config";

export default defineConfig({
  resolve: {
    alias: {
      "@": new URL("./src", import.meta.url).pathname,
    },
  },
  test: {
    coverage: {
      provider: "v8",
      reporter: ["text", "json-summary"],
      include: ["src/lib/**/*.ts"],
      exclude: ["src/lib/openai.ts"],
      thresholds: {
        lines: 80,
        functions: 80,
        statements: 80,
        branches: 75,
      },
    },
  },
});

declare module "*.css";
declare module "@fontsource-variable/jetbrains-mono";
declare module "@fontsource-variable/manrope";

export const VOICES = [
  { id: "alloy", label: "Alloy", character: "Balanced and versatile" },
  { id: "ash", label: "Ash", character: "Clear and conversational" },
  { id: "ballad", label: "Ballad", character: "Warm and expressive" },
  { id: "coral", label: "Coral", character: "Bright and engaging" },
  { id: "echo", label: "Echo", character: "Calm and measured" },
  { id: "fable", label: "Fable", character: "Narrative and textured" },
  { id: "nova", label: "Nova", character: "Energetic and polished" },
  { id: "onyx", label: "Onyx", character: "Grounded and resonant" },
  { id: "sage", label: "Sage", character: "Composed and thoughtful" },
  { id: "shimmer", label: "Shimmer", character: "Light and articulate" },
  { id: "verse", label: "Verse", character: "Natural and dynamic" },
  { id: "marin", label: "Marin", character: "Natural, high-quality voice" },
  { id: "cedar", label: "Cedar", character: "Natural, high-quality voice" },
] as const;

export const VOICE_IDS = VOICES.map((voice) => voice.id) as [
  (typeof VOICES)[number]["id"],
  ...(typeof VOICES)[number]["id"][],
];

export const AUDIO_FORMATS = ["mp3", "wav", "opus"] as const;

export const MAX_SPEECH_CHARACTERS = 4_096;
export const MAX_INSTRUCTIONS_CHARACTERS = 4_096;

export type VoiceId = (typeof VOICE_IDS)[number];
export type AudioFormat = (typeof AUDIO_FORMATS)[number];

import { z } from "zod";

import {
  AUDIO_FORMATS,
  MAX_INSTRUCTIONS_CHARACTERS,
  MAX_SPEECH_CHARACTERS,
  VOICE_IDS,
} from "@/lib/constants";

export const speechRequestSchema = z
  .object({
    text: z.string().trim().min(1).max(MAX_SPEECH_CHARACTERS),
    voice: z.enum(VOICE_IDS),
    format: z.enum(AUDIO_FORMATS).default("mp3"),
    instructions: z
      .string()
      .trim()
      .max(MAX_INSTRUCTIONS_CHARACTERS)
      .optional()
      .default(""),
    speed: z.coerce.number().min(0.25).max(4).default(1),
  })
  .strict();

export type SpeechRequest = z.infer<typeof speechRequestSchema>;

import { describe, expect, it } from "vitest";

import { speechRequestSchema } from "../src/lib/schemas";

describe("speechRequestSchema", () => {
  it("applies safe defaults to a minimal request", () => {
    const result = speechRequestSchema.parse({ text: "Hello", voice: "marin" });

    expect(result).toEqual({
      text: "Hello",
      voice: "marin",
      format: "mp3",
      instructions: "",
      speed: 1,
    });
  });

  it("trims text and accepts supported controls", () => {
    const result = speechRequestSchema.parse({
      text: "  A clear explanation.  ",
      voice: "cedar",
      format: "wav",
      instructions: "  Speak calmly.  ",
      speed: "1.25",
    });

    expect(result.text).toBe("A clear explanation.");
    expect(result.instructions).toBe("Speak calmly.");
    expect(result.speed).toBe(1.25);
  });

  it("rejects unsupported voices and extra fields", () => {
    expect(() => speechRequestSchema.parse({ text: "Hello", voice: "celebrity" })).toThrow();
    expect(() =>
      speechRequestSchema.parse({ text: "Hello", voice: "marin", apiKey: "never" }),
    ).toThrow();
  });

  it("enforces the upstream text and speed limits", () => {
    expect(() => speechRequestSchema.parse({ text: "x".repeat(4_097), voice: "marin" })).toThrow();
    expect(() => speechRequestSchema.parse({ text: "Hello", voice: "marin", speed: 4.1 })).toThrow();
  });
});

import OpenAI from "openai";
import { ZodError } from "zod";

export class AppError extends Error {
  constructor(
    public readonly status: number,
    public readonly code: string,
    message: string,
    public readonly headers: Record<string, string> = {},
  ) {
    super(message);
    this.name = "AppError";
  }
}

type ErrorBody = {
  error: {
    code: string;
    message: string;
    requestId: string;
  };
};

export function normalizeError(error: unknown): AppError {
  if (error instanceof AppError) return error;

  if (error instanceof ZodError) {
    return new AppError(
      400,
      "invalid_request",
      error.issues[0]?.message ?? "The request is invalid.",
    );
  }

  if (error instanceof SyntaxError) {
    return new AppError(400, "invalid_json", "The request body is not valid JSON.");
  }

  if (error instanceof OpenAI.APIError) {
    if (error.status === 429) {
      return new AppError(
        429,
        "upstream_rate_limit",
        "The voice service is busy. Please try again shortly.",
      );
    }

    if (error.status === 401 || error.status === 403) {
      return new AppError(
        503,
        "upstream_authentication_error",
        "The voice service is temporarily unavailable.",
      );
    }

    return new AppError(
      502,
      "upstream_error",
      "OpenAI could not complete the request. Please try again.",
    );
  }

  if (error instanceof Error && error.name === "AbortError") {
    return new AppError(499, "request_cancelled", "The request was cancelled.");
  }

  return new AppError(500, "internal_error", "Something went wrong. Please try again.");
}

export function errorResponse(
  error: unknown,
  requestId: string,
  headers?: HeadersInit,
): Response {
  const normalized = normalizeError(error);
  const responseHeaders = new Headers(headers);
  for (const [name, value] of Object.entries(normalized.headers)) {
    responseHeaders.set(name, value);
  }
  responseHeaders.set("Cache-Control", "no-store");
  responseHeaders.set("X-Request-Id", requestId);
  const body: ErrorBody = {
    error: {
      code: normalized.code,
      message: normalized.message,
      requestId,
    },
  };

  return Response.json(body, {
    status: normalized.status,
    headers: responseHeaders,
  });
}

type LogLevel = "info" | "error";

type VoiceLog = {
  event: string;
  requestId: string;
  route: "speech";
  durationMs: number;
  status: number;
  model?: string;
  inputSize?: number;
  outputSize?: number;
};

export function logVoiceRequest(level: LogLevel, log: VoiceLog): void {
  const serialized = JSON.stringify({
    timestamp: new Date().toISOString(),
    ...log,
  });

  if (level === "error") {
    console.error(serialized);
  } else {
    console.info(serialized);
  }
}

import OpenAI from "openai";

import { AppError } from "@/lib/errors";

const globalForOpenAI = globalThis as unknown as { openai?: OpenAI };

export function getOpenAIClient(): OpenAI {
  const apiKey = process.env.OPENAI_API_KEY;

  if (!apiKey) {
    throw new AppError(
      503,
      "configuration_error",
      "The voice service is not configured.",
    );
  }

  globalForOpenAI.openai ??= new OpenAI({
    apiKey,
    maxRetries: 2,
    timeout: 45_000,
  });

  return globalForOpenAI.openai;
}

import { Ratelimit, type Duration } from "@upstash/ratelimit";
import { Redis } from "@upstash/redis";

type RateLimitEntry = {
  count: number;
  resetAt: number;
};

export type RateLimitResult = {
  allowed: boolean;
  limit: number;
  remaining: number;
  resetAt: number;
};

type RateLimitOptions = {
  limit: number;
  windowMs: number;
  now?: number;
};

const globalForRateLimit = globalThis as unknown as {
  voicePlaygroundRateLimits?: Map<string, RateLimitEntry>;
  voicePlaygroundDistributedLimiters?: Map<string, Ratelimit>;
};

const entries =
  globalForRateLimit.voicePlaygroundRateLimits ?? new Map<string, RateLimitEntry>();
const distributedLimiters =
  globalForRateLimit.voicePlaygroundDistributedLimiters ?? new Map<string, Ratelimit>();

globalForRateLimit.voicePlaygroundRateLimits = entries;
globalForRateLimit.voicePlaygroundDistributedLimiters = distributedLimiters;

export async function checkRateLimit(
  key: string,
  options: RateLimitOptions,
): Promise<RateLimitResult> {
  const redisUrl = process.env.UPSTASH_REDIS_REST_URL?.trim();
  const redisToken = process.env.UPSTASH_REDIS_REST_TOKEN?.trim();

  if (redisUrl && redisToken) {
    const limiter = getDistributedLimiter(redisUrl, redisToken, options);
    const result = await limiter.limit(key);
    return {
      allowed: result.success,
      limit: result.limit,
      remaining: result.remaining,
      resetAt: result.reset,
    };
  }

  return checkLocalRateLimit(key, options);
}

export function rateLimitHeaders(result: RateLimitResult): Record<string, string> {
  return {
    "RateLimit-Limit": String(result.limit),
    "RateLimit-Remaining": String(result.remaining),
    "RateLimit-Reset": String(Math.ceil(result.resetAt / 1_000)),
    ...(!result.allowed
      ? { "Retry-After": String(Math.max(1, Math.ceil((result.resetAt - Date.now()) / 1_000))) }
      : {}),
  };
}

export function resetRateLimitsForTests(): void {
  entries.clear();
  distributedLimiters.clear();
}

function checkLocalRateLimit(
  key: string,
  { limit, windowMs, now = Date.now() }: RateLimitOptions,
): RateLimitResult {
  const current = entries.get(key);

  if (!current || current.resetAt <= now) {
    const resetAt = now + windowMs;
    entries.set(key, { count: 1, resetAt });
    cleanExpiredEntries(now);
    return { allowed: true, limit, remaining: limit - 1, resetAt };
  }

  if (current.count >= limit) {
    return { allowed: false, limit, remaining: 0, resetAt: current.resetAt };
  }

  current.count += 1;
  return {
    allowed: true,
    limit,
    remaining: Math.max(0, limit - current.count),
    resetAt: current.resetAt,
  };
}

function getDistributedLimiter(
  url: string,
  token: string,
  { limit, windowMs }: RateLimitOptions,
): Ratelimit {
  const cacheKey = `${limit}:${windowMs}`;
  const existing = distributedLimiters.get(cacheKey);
  if (existing) return existing;

  const limiter = new Ratelimit({
    redis: new Redis({ url, token }),
    limiter: Ratelimit.fixedWindow(limit, `${windowMs} ms` as Duration),
    analytics: false,
    prefix: "openai-voice-playground:lab-01",
  });
  distributedLimiters.set(cacheKey, limiter);
  return limiter;
}

function cleanExpiredEntries(now: number): void {
  if (entries.size < 1_000) return;

  for (const [key, entry] of entries) {
    if (entry.resetAt <= now) entries.delete(key);
  }
}

import { AppError } from "@/lib/errors";

export async function readJsonBody(
  request: Request,
  maxBytes: number,
  tooLargeMessage: string,
): Promise<unknown> {
  const contentType = request.headers.get("content-type")?.toLowerCase() ?? "";
  if (!contentType.startsWith("application/json")) {
    throw new AppError(
      415,
      "unsupported_media_type",
      "The request Content-Type must be application/json.",
    );
  }

  const advertisedLength = readContentLength(request);
  if (advertisedLength !== undefined && advertisedLength > maxBytes) {
    throw new AppError(413, "request_too_large", tooLargeMessage);
  }

  if (!request.body) {
    throw new AppError(400, "invalid_json", "The request body is not valid JSON.");
  }

  const reader = request.body.getReader();
  const chunks: Uint8Array[] = [];
  let totalBytes = 0;

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    totalBytes += value.byteLength;
    if (totalBytes > maxBytes) {
      await reader.cancel();
      throw new AppError(413, "request_too_large", tooLargeMessage);
    }
    chunks.push(value);
  }

  const body = new Uint8Array(totalBytes);
  let offset = 0;
  for (const chunk of chunks) {
    body.set(chunk, offset);
    offset += chunk.byteLength;
  }

  try {
    const text = new TextDecoder("utf-8", { fatal: true }).decode(body);
    return JSON.parse(text) as unknown;
  } catch {
    throw new AppError(400, "invalid_json", "The request body is not valid JSON.");
  }
}

function readContentLength(request: Request): number | undefined {
  const value = request.headers.get("content-length");
  if (!value || !/^\d+$/.test(value)) return undefined;
  return Number(value);
}

export type SecurityConfiguration = {
  isProduction: boolean;
  ready: boolean;
  missingVariables: string[];
  clientIpHeader: string;
  distributedRateLimit: boolean;
  requiresAccessToken: boolean;
};

type RuntimeEnvironment = Record<string, string | undefined>;

const HEADER_NAME_PATTERN = /^[a-z0-9-]+$/;
const FORBIDDEN_IDENTITY_HEADERS = new Set([
  "authorization",
  "cookie",
  "proxy-authorization",
]);

export function getSecurityConfiguration(
  environment: RuntimeEnvironment = process.env,
): SecurityConfiguration {
  const isProduction = environment.NODE_ENV === "production";
  const accessToken = environment.PLAYGROUND_ACCESS_TOKEN?.trim();
  const redisUrl = environment.UPSTASH_REDIS_REST_URL?.trim();
  const redisToken = environment.UPSTASH_REDIS_REST_TOKEN?.trim();
  const configuredHeader = environment.CLIENT_IP_HEADER?.trim().toLowerCase();
  const clientIpHeader = configuredHeader || (environment.VERCEL ? "x-vercel-forwarded-for" : "");
  const validClientIpHeader = Boolean(
    clientIpHeader &&
      HEADER_NAME_PATTERN.test(clientIpHeader) &&
      !FORBIDDEN_IDENTITY_HEADERS.has(clientIpHeader),
  );

  const missingVariables: string[] = [];
  if (isProduction) {
    if (!accessToken) missingVariables.push("PLAYGROUND_ACCESS_TOKEN");
    if (!environment.APP_ORIGIN?.trim()) missingVariables.push("APP_ORIGIN");
    if (!redisUrl) missingVariables.push("UPSTASH_REDIS_REST_URL");
    if (!redisToken) missingVariables.push("UPSTASH_REDIS_REST_TOKEN");
    if (!validClientIpHeader) missingVariables.push("CLIENT_IP_HEADER");
  }

  return {
    isProduction,
    ready: missingVariables.length === 0,
    missingVariables,
    clientIpHeader: validClientIpHeader ? clientIpHeader : "x-forwarded-for",
    distributedRateLimit: Boolean(redisUrl && redisToken),
    requiresAccessToken: Boolean(accessToken) || isProduction,
  };
}

import { createHash, timingSafeEqual } from "node:crypto";

import { AppError } from "@/lib/errors";
import {
  checkRateLimit,
  rateLimitHeaders,
  type RateLimitResult,
} from "@/lib/rate-limit";
import { getSecurityConfiguration } from "@/lib/security-config";

const AUTH_ATTEMPTS_PER_MINUTE = 30;
const REQUESTS_PER_MINUTE = 10;
const WINDOW_MS = 60_000;

export async function guardApiRequest(
  request: Request,
  scope: string,
): Promise<RateLimitResult> {
  const security = getSecurityConfiguration();
  if (!security.ready) {
    throw new AppError(
      503,
      "security_configuration_incomplete",
      "The service security configuration is incomplete.",
    );
  }

  assertSameOrigin(request);
  const clientKey = hashIdentifier(getClientAddress(request, security.clientIpHeader));
  const authenticationLimit = await applyRateLimit(
    `authentication:${clientKey}`,
    AUTH_ATTEMPTS_PER_MINUTE,
  );
  assertAccessToken(request, rateLimitHeaders(authenticationLimit));

  return applyRateLimit(`${scope}:${clientKey}`, REQUESTS_PER_MINUTE);
}

export { rateLimitHeaders };

async function applyRateLimit(key: string, limit: number): Promise<RateLimitResult> {
  let result: RateLimitResult;
  try {
    result = await checkRateLimit(key, { limit, windowMs: WINDOW_MS });
  } catch {
    throw new AppError(
      503,
      "rate_limiter_unavailable",
      "The service cannot safely verify request quota right now. Please try again.",
    );
  }

  if (!result.allowed) {
    throw new AppError(
      429,
      "rate_limit_exceeded",
      "Too many requests. Please wait a moment and try again.",
      rateLimitHeaders(result),
    );
  }
  return result;
}

function assertSameOrigin(request: Request): void {
  const fetchSite = request.headers.get("sec-fetch-site");
  if (fetchSite === "cross-site") {
    throw new AppError(403, "cross_origin_request", "Cross-origin requests are blocked.");
  }

  const origin = request.headers.get("origin");
  if (!origin) return;

  const expectedOrigin = process.env.APP_ORIGIN || new URL(request.url).origin;

  try {
    if (new URL(origin).origin !== new URL(expectedOrigin).origin) {
      throw new AppError(
        403,
        "cross_origin_request",
        "Cross-origin requests are blocked.",
      );
    }
  } catch (error) {
    if (error instanceof AppError) throw error;
    throw new AppError(403, "invalid_origin", "The request origin is invalid.");
  }
}

function assertAccessToken(request: Request, headers: Record<string, string>): void {
  const expected = process.env.PLAYGROUND_ACCESS_TOKEN?.trim();
  if (!expected) return;

  const authorization = request.headers.get("authorization");
  const received = authorization?.startsWith("Bearer ")
    ? authorization.slice("Bearer ".length)
    : "";

  if (!safeEqual(received, expected)) {
    throw new AppError(
      401,
      "unauthorized",
      "A valid playground access token is required.",
      headers,
    );
  }
}

function safeEqual(received: string, expected: string): boolean {
  const receivedDigest = createHash("sha256").update(received).digest();
  const expectedDigest = createHash("sha256").update(expected).digest();
  return timingSafeEqual(receivedDigest, expectedDigest);
}

function getClientAddress(request: Request, headerName: string): string {
  const address = request.headers.get(headerName)?.split(",")[0]?.trim();
  return address?.slice(0, 256) || "unidentified-client";
}

function hashIdentifier(value: string): string {
  return createHash("sha256").update(value).digest("hex").slice(0, 32);
}

import { MAX_SPEECH_CHARACTERS } from "@/lib/constants";
import { getSecurityConfiguration } from "@/lib/security-config";

export const runtime = "nodejs";
export const dynamic = "force-dynamic";

export function GET(): Response {
  const security = getSecurityConfiguration();
  const configurationIssues = [
    ...(!process.env.OPENAI_API_KEY ? ["OPENAI_API_KEY"] : []),
    ...security.missingVariables,
  ];

  return Response.json(
    {
      ok: true,
      service: "openai-voice-lab-01-text-to-speech",
      configured: configurationIssues.length === 0,
      configurationIssues,
      requiresAccessToken: security.requiresAccessToken,
      distributedRateLimit: security.distributedRateLimit,
      capabilities: {
        speechModel: "gpt-4o-mini-tts",
        streamedSpeech: true,
      },
      limits: {
        speechCharacters: MAX_SPEECH_CHARACTERS,
        requestsPerMinute: 10,
      },
    },
    {
      headers: {
        "Cache-Control": "no-store",
      },
    },
  );
}

import { randomUUID } from "node:crypto";

import { AppError, errorResponse, normalizeError } from "@/lib/errors";
import { logVoiceRequest } from "@/lib/observability";
import { getOpenAIClient } from "@/lib/openai";
import { readJsonBody } from "@/lib/request-body";
import { guardApiRequest, rateLimitHeaders } from "@/lib/request-guard";
import { speechRequestSchema } from "@/lib/schemas";

export const runtime = "nodejs";
export const dynamic = "force-dynamic";
export const maxDuration = 60;

const MAX_JSON_BYTES = 16 * 1024;
const CONTENT_TYPES = {
  mp3: "audio/mpeg",
  wav: "audio/wav",
  opus: "audio/ogg; codecs=opus",
} as const;

export async function POST(request: Request): Promise<Response> {
  const requestId = randomUUID();
  const startedAt = performance.now();
  let responseHeaders: Record<string, string> = {};

  try {
    const rateLimit = await guardApiRequest(request, "speech");
    responseHeaders = rateLimitHeaders(rateLimit);

    const payload = speechRequestSchema.parse(
      await readJsonBody(request, MAX_JSON_BYTES, "The speech request is too large."),
    );
    const openai = getOpenAIClient();
    const speech = await openai.audio.speech.create(
      {
        model: "gpt-4o-mini-tts",
        input: payload.text,
        voice: payload.voice,
        ...(payload.instructions ? { instructions: payload.instructions } : {}),
        response_format: payload.format,
        speed: payload.speed,
        stream_format: "audio",
      },
      { signal: request.signal },
    );

    if (!speech.body) {
      throw new AppError(502, "empty_audio_stream", "OpenAI returned an empty audio stream.");
    }

    const upstreamHeadersMs = Math.round(performance.now() - startedAt);
    logVoiceRequest("info", {
      event: "speech.stream_started",
      requestId,
      route: "speech",
      durationMs: upstreamHeadersMs,
      status: 200,
      model: "gpt-4o-mini-tts",
      inputSize: payload.text.length,
    });

    return new Response(speech.body, {
      status: 200,
      headers: {
        ...responseHeaders,
        "Cache-Control": "no-store",
        "Content-Disposition": `inline; filename="voice-${requestId}.${payload.format}"`,
        "Content-Type": CONTENT_TYPES[payload.format],
        "Server-Timing": `openai;dur=${upstreamHeadersMs}`,
        "X-Model": "gpt-4o-mini-tts",
        "X-Request-Id": requestId,
      },
    });
  } catch (error) {
    const normalized = normalizeError(error);
    logVoiceRequest("error", {
      event: "speech.failed",
      requestId,
      route: "speech",
      durationMs: Math.round(performance.now() - startedAt),
      status: normalized.status,
    });
    return errorResponse(normalized, requestId, responseHeaders);
  }
}

import { NextRequest, NextResponse } from "next/server";

export function middleware(request: NextRequest) {
  const nonce = btoa(crypto.randomUUID());
  const isDevelopment = process.env.NODE_ENV !== "production";
  const contentSecurityPolicy = [
    "default-src 'self'",
    `script-src 'self' 'nonce-${nonce}' 'strict-dynamic'${isDevelopment ? " 'unsafe-eval'" : ""}`,
    `style-src 'self' 'nonce-${nonce}'${isDevelopment ? " 'unsafe-inline'" : ""}`,
    "img-src 'self' data: blob:",
    "font-src 'self' data:",
    "connect-src 'self'",
    "media-src 'self' blob:",
    "object-src 'none'",
    "base-uri 'self'",
    "form-action 'self'",
    "frame-ancestors 'none'",
    ...(!isDevelopment ? ["upgrade-insecure-requests"] : []),
  ].join("; ");
  const requestHeaders = new Headers(request.headers);
  requestHeaders.set("x-nonce", nonce);
  requestHeaders.set("Content-Security-Policy", contentSecurityPolicy);

  const response = NextResponse.next({ request: { headers: requestHeaders } });
  response.headers.set("Content-Security-Policy", contentSecurityPolicy);
  return response;
}

export const config = {
  matcher: [
    {
      source: "/((?!api|_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)",
      missing: [
        { type: "header", key: "next-router-prefetch" },
        { type: "header", key: "purpose", value: "prefetch" },
      ],
    },
  ],
};

import OpenAI from "openai";
import { describe, expect, it } from "vitest";

import {
  AppError,
  errorResponse,
  normalizeError,
} from "../src/lib/errors";
import { speechRequestSchema } from "../src/lib/schemas";

describe("normalizeError", () => {
  it("preserves an application error", () => {
    const error = new AppError(418, "teapot", "Short and stout");
    expect(normalizeError(error)).toBe(error);
  });

  it("turns a Zod error into a safe bad request", () => {
    const parsed = speechRequestSchema.safeParse({ text: "", voice: "marin" });
    expect(parsed.success).toBe(false);
    if (parsed.success) return;

    expect(normalizeError(parsed.error)).toMatchObject({
      status: 400,
      code: "invalid_request",
    });
  });

  it("maps malformed JSON", () => {
    expect(normalizeError(new SyntaxError("private parser detail"))).toMatchObject({
      status: 400,
      code: "invalid_json",
      message: "The request body is not valid JSON.",
    });
  });

  it.each([
    [429, 429, "upstream_rate_limit"],
    [401, 503, "upstream_authentication_error"],
    [403, 503, "upstream_authentication_error"],
    [500, 502, "upstream_error"],
  ])("maps OpenAI status %i without exposing the provider message", (upstream, status, code) => {
    const providerError = new OpenAI.APIError(
      upstream,
      { error: { message: "sensitive provider detail" } },
      "sensitive provider detail",
      new Headers(),
    );

    expect(normalizeError(providerError)).toMatchObject({ status, code });
    expect(normalizeError(providerError).message).not.toContain("sensitive");
  });

  it("maps a cancelled request", () => {
    const error = new Error("cancelled");
    error.name = "AbortError";
    expect(normalizeError(error)).toMatchObject({ status: 499, code: "request_cancelled" });
  });

  it("uses a generic fallback for unknown failures", () => {
    expect(normalizeError({ unexpected: true })).toMatchObject({
      status: 500,
      code: "internal_error",
    });
  });
});

describe("errorResponse", () => {
  it("returns the stable no-store envelope and custom headers", async () => {
    const response = errorResponse(
      new AppError(400, "invalid", "Invalid input"),
      "request-123",
      { "RateLimit-Remaining": "9" },
    );

    expect(response.status).toBe(400);
    expect(response.headers.get("cache-control")).toBe("no-store");
    expect(response.headers.get("x-request-id")).toBe("request-123");
    expect(response.headers.get("ratelimit-remaining")).toBe("9");
    await expect(response.json()).resolves.toEqual({
      error: { code: "invalid", message: "Invalid input", requestId: "request-123" },
    });
  });
});

import { afterEach, describe, expect, it, vi } from "vitest";

import { logVoiceRequest } from "../src/lib/observability";

afterEach(() => vi.restoreAllMocks());

describe("logVoiceRequest", () => {
  const event = {
    event: "speech.stream_started",
    requestId: "request-1",
    route: "speech" as const,
    durationMs: 42,
    status: 200,
    model: "gpt-4o-mini-tts",
    inputSize: 24,
  };

  it("writes structured informational metadata", () => {
    const info = vi.spyOn(console, "info").mockImplementation(() => undefined);
    logVoiceRequest("info", event);

    expect(info).toHaveBeenCalledOnce();
    const parsed = JSON.parse(String(info.mock.calls[0]?.[0])) as Record<string, unknown>;
    expect(parsed).toMatchObject(event);
    expect(parsed.timestamp).toEqual(expect.any(String));
  });

  it("writes failures to stderr", () => {
    const error = vi.spyOn(console, "error").mockImplementation(() => undefined);
    logVoiceRequest("error", { ...event, event: "speech.failed", status: 500 });
    expect(error).toHaveBeenCalledOnce();
  });
});

import { afterEach, describe, expect, it } from "vitest";

import {
  checkRateLimit,
  rateLimitHeaders,
  resetRateLimitsForTests,
} from "../src/lib/rate-limit";

afterEach(() => {
  delete process.env.UPSTASH_REDIS_REST_URL;
  delete process.env.UPSTASH_REDIS_REST_TOKEN;
  resetRateLimitsForTests();
});

describe("checkRateLimit", () => {
  it("allows requests inside the fixed window", async () => {
    const first = await checkRateLimit("speech:client", { limit: 2, windowMs: 1_000, now: 100 });
    const second = await checkRateLimit("speech:client", { limit: 2, windowMs: 1_000, now: 200 });

    expect(first).toMatchObject({ allowed: true, remaining: 1, resetAt: 1_100 });
    expect(second).toMatchObject({ allowed: true, remaining: 0, resetAt: 1_100 });
  });

  it("blocks a request after the limit", async () => {
    await checkRateLimit("speech:client", { limit: 1, windowMs: 1_000, now: 100 });
    const blocked = await checkRateLimit("speech:client", { limit: 1, windowMs: 1_000, now: 200 });

    expect(blocked).toEqual({ allowed: false, limit: 1, remaining: 0, resetAt: 1_100 });
    expect(rateLimitHeaders(blocked)).toMatchObject({ "Retry-After": "1" });
  });

  it("opens a fresh window after reset", async () => {
    await checkRateLimit("speech:client", { limit: 1, windowMs: 1_000, now: 100 });
    const nextWindow = await checkRateLimit("speech:client", {
      limit: 1,
      windowMs: 1_000,
      now: 1_101,
    });

    expect(nextWindow).toMatchObject({ allowed: true, remaining: 0, resetAt: 2_101 });
  });

  it("serializes standard rate-limit headers", () => {
    expect(
      rateLimitHeaders({ allowed: true, limit: 10, remaining: 9, resetAt: 12_345 }),
    ).toEqual({
      "RateLimit-Limit": "10",
      "RateLimit-Remaining": "9",
      "RateLimit-Reset": "13",
    });
  });

  it("periodically removes expired keys", async () => {
    for (let index = 0; index < 1_000; index += 1) {
      await checkRateLimit(`expired:${index}`, { limit: 1, windowMs: 1, now: 0 });
    }

    const result = await checkRateLimit("fresh", { limit: 1, windowMs: 1_000, now: 2 });
    expect(result.allowed).toBe(true);
  });
});

import { describe, expect, it } from "vitest";

import { readJsonBody } from "../src/lib/request-body";

describe("readJsonBody", () => {
  it("parses a bounded JSON request", async () => {
    const request = new Request("https://voice.example.com/api/speech", {
      method: "POST",
      headers: { "content-type": "application/json; charset=utf-8" },
      body: JSON.stringify({ text: "hello" }),
    });

    await expect(readJsonBody(request, 1_024, "Too large")).resolves.toEqual({ text: "hello" });
  });

  it("rejects an unsupported content type", async () => {
    const request = new Request("https://voice.example.com/api/speech", {
      method: "POST",
      body: "hello",
    });

    await expect(readJsonBody(request, 1_024, "Too large")).rejects.toMatchObject({
      status: 415,
      code: "unsupported_media_type",
    });
  });

  it("rejects an advertised body that is too large", async () => {
    const request = new Request("https://voice.example.com/api/speech", {
      method: "POST",
      headers: { "content-type": "application/json", "content-length": "2048" },
      body: "{}",
    });

    await expect(readJsonBody(request, 10, "Too large")).rejects.toMatchObject({
      status: 413,
      code: "request_too_large",
    });
  });

  it("counts streamed bytes even without Content-Length", async () => {
    const request = new Request("https://voice.example.com/api/speech", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: new ReadableStream({
        start(controller) {
          controller.enqueue(new TextEncoder().encode('{"text":"'));
          controller.enqueue(new TextEncoder().encode('payload"}'));
          controller.close();
        },
      }),
      duplex: "half",
    } as RequestInit & { duplex: "half" });

    await expect(readJsonBody(request, 12, "Too large")).rejects.toMatchObject({ status: 413 });
  });

  it("maps malformed or empty JSON to a safe error", async () => {
    const malformed = new Request("https://voice.example.com/api/speech", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: "not-json",
    });
    const empty = new Request("https://voice.example.com/api/speech", {
      method: "POST",
      headers: { "content-type": "application/json" },
    });

    await expect(readJsonBody(malformed, 1_024, "Too large")).rejects.toMatchObject({
      status: 400,
      code: "invalid_json",
    });
    await expect(readJsonBody(empty, 1_024, "Too large")).rejects.toMatchObject({
      status: 400,
      code: "invalid_json",
    });
  });
});

import { afterEach, describe, expect, it, vi } from "vitest";

import { resetRateLimitsForTests } from "../src/lib/rate-limit";
import { guardApiRequest } from "../src/lib/request-guard";

afterEach(() => {
  vi.unstubAllEnvs();
  delete process.env.PLAYGROUND_ACCESS_TOKEN;
  delete process.env.APP_ORIGIN;
  delete process.env.CLIENT_IP_HEADER;
  delete process.env.UPSTASH_REDIS_REST_URL;
  delete process.env.UPSTASH_REDIS_REST_TOKEN;
  resetRateLimitsForTests();
});

describe("guardApiRequest", () => {
  it("accepts a same-origin request and returns a quota", async () => {
    const request = new Request("https://voice.example.com/api/speech", {
      headers: { origin: "https://voice.example.com", "x-forwarded-for": "203.0.113.10" },
    });

    await expect(guardApiRequest(request, "speech")).resolves.toMatchObject({
      allowed: true,
      remaining: 9,
    });
  });

  it("fails closed when production safeguards are missing", async () => {
    vi.stubEnv("NODE_ENV", "production");

    await expect(
      guardApiRequest(new Request("https://voice.example.com/api/speech"), "speech"),
    ).rejects.toMatchObject({
      status: 503,
      code: "security_configuration_incomplete",
    });
  });

  it("blocks explicit cross-site browser requests", async () => {
    const request = new Request("https://voice.example.com/api/speech", {
      headers: { origin: "https://attacker.example", "sec-fetch-site": "cross-site" },
    });

    await expect(guardApiRequest(request, "speech")).rejects.toMatchObject({
      status: 403,
      code: "cross_origin_request",
    });
  });

  it("requires the configured deployment access token", async () => {
    process.env.PLAYGROUND_ACCESS_TOKEN = "a-long-shared-token";

    const unauthorized = new Request("https://voice.example.com/api/speech");
    await expect(guardApiRequest(unauthorized, "speech")).rejects.toMatchObject({
      status: 401,
      code: "unauthorized",
    });

    const authorized = new Request("https://voice.example.com/api/speech", {
      headers: { authorization: "Bearer a-long-shared-token" },
    });
    await expect(guardApiRequest(authorized, "speech")).resolves.toMatchObject({ allowed: true });
  });

  it("rate-limits invalid token attempts before authentication", async () => {
    process.env.PLAYGROUND_ACCESS_TOKEN = "a-long-shared-token";
    const request = () =>
      new Request("https://voice.example.com/api/speech", {
        headers: { authorization: "Bearer wrong", "x-forwarded-for": "203.0.113.20" },
      });

    for (let index = 0; index < 30; index += 1) {
      await expect(guardApiRequest(request(), "speech")).rejects.toMatchObject({ status: 401 });
    }
    await expect(guardApiRequest(request(), "speech")).rejects.toMatchObject({
      status: 429,
      code: "rate_limit_exceeded",
      headers: expect.objectContaining({ "Retry-After": expect.any(String) }),
    });
  });

  it("honors a configured canonical origin", async () => {
    process.env.APP_ORIGIN = "https://voice.example.com";
    const request = new Request("https://preview.example.com/api/speech", {
      headers: { origin: "https://preview.example.com" },
    });

    await expect(guardApiRequest(request, "speech")).rejects.toMatchObject({ status: 403 });
  });

  it("rejects an invalid origin header", async () => {
    const request = new Request("https://voice.example.com/api/speech", {
      headers: { origin: "not a URL" },
    });
    await expect(guardApiRequest(request, "speech")).rejects.toMatchObject({
      status: 403,
      code: "invalid_origin",
    });
  });

  it("enforces the local operation quota", async () => {
    for (let index = 0; index < 10; index += 1) {
      await guardApiRequest(new Request("https://voice.example.com/api/speech"), "speech");
    }

    await expect(
      guardApiRequest(new Request("https://voice.example.com/api/speech"), "speech"),
    ).rejects.toMatchObject({ status: 429, code: "rate_limit_exceeded" });
  });
});