@moxxy/plugin-stt-whisper 0.27.0

package/src/audio.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest';
+import { MOXXY_PCM16_24KHZ_MIME, normalizeWhisperUpload, pcm16MonoToWav } from './audio.js';
+
+function ascii(bytes: Uint8Array, offset: number, len: number): string {
+  return String.fromCharCode(...bytes.slice(offset, offset + len));
+}
+
+describe('pcm16MonoToWav', () => {
+  it('writes a 44-byte canonical mono/16-bit WAV header for 24kHz', () => {
+    const pcm = new Uint8Array(8); // 8 bytes of samples
+    const wav = pcm16MonoToWav(pcm, 24_000);
+    expect(wav.byteLength).toBe(44 + 8);
+
+    const view = new DataView(wav.buffer, wav.byteOffset, wav.byteLength);
+    expect(ascii(wav, 0, 4)).toBe('RIFF');
+    expect(view.getUint32(4, true)).toBe(36 + 8); // chunk size = 36 + data
+    expect(ascii(wav, 8, 4)).toBe('WAVE');
+    expect(ascii(wav, 12, 4)).toBe('fmt ');
+    expect(view.getUint32(16, true)).toBe(16); // PCM fmt chunk size
+    expect(view.getUint16(20, true)).toBe(1); // audio format = PCM
+    expect(view.getUint16(22, true)).toBe(1); // channels = mono
+    expect(view.getUint32(24, true)).toBe(24_000); // sample rate
+    expect(view.getUint32(28, true)).toBe(24_000 * 2); // byte rate = rate * blockAlign
+    expect(view.getUint16(32, true)).toBe(2); // block align = channels * bytesPerSample
+    expect(view.getUint16(34, true)).toBe(16); // bits per sample
+    expect(ascii(wav, 36, 4)).toBe('data');
+    expect(view.getUint32(40, true)).toBe(8); // data chunk size
+  });
+
+  it('copies the PCM samples verbatim after the header', () => {
+    const pcm = new Uint8Array([1, 2, 3, 4]);
+    const wav = pcm16MonoToWav(pcm, 24_000);
+    expect([...wav.slice(44)]).toEqual([1, 2, 3, 4]);
+  });
+});
+
+describe('normalizeWhisperUpload', () => {
+  it('wraps raw PCM16 bytes in a WAV and reports audio/wav', () => {
+    const pcm = new Uint8Array(4);
+    const out = normalizeWhisperUpload(pcm, MOXXY_PCM16_24KHZ_MIME);
+    expect(out.mimeType).toBe('audio/wav');
+    expect(out.filename).toBe('audio.wav');
+    expect(out.bytes.byteLength).toBe(44 + 4);
+    expect(ascii(out.bytes, 0, 4)).toBe('RIFF');
+  });
+
+  it('brands the PCM16 WAV filename with a prefix when supplied', () => {
+    const out = normalizeWhisperUpload(new Uint8Array(2), MOXXY_PCM16_24KHZ_MIME, 'moxxy');
+    expect(out.filename).toBe('moxxy.wav');
+    expect(out.mimeType).toBe('audio/wav');
+  });
+
+  it('passes non-PCM bytes through and infers the filename from the MIME table', () => {
+    const bytes = new Uint8Array([9, 9]);
+    const out = normalizeWhisperUpload(bytes, 'audio/ogg');
+    expect(out.mimeType).toBe('audio/ogg');
+    expect(out.filename).toBe('audio.ogg');
+    expect(out.bytes).toBe(bytes); // no copy on passthrough
+  });
+
+  it('falls back to audio.bin for an unknown MIME', () => {
+    const out = normalizeWhisperUpload(new Uint8Array(1), 'audio/weird');
+    expect(out.filename).toBe('audio.bin');
+    expect(out.mimeType).toBe('audio/weird');
+  });
+
+  it('keeps the inferred extension when branding the passthrough filename', () => {
+    const out = normalizeWhisperUpload(new Uint8Array(1), 'audio/mpeg', 'moxxy');
+    // audio/mpeg maps to audio.mp3 → branded as moxxy.mp3.
+    expect(out.filename).toBe('moxxy.mp3');
+  });
+
+  it('defaults a missing MIME to audio/wav', () => {
+    const out = normalizeWhisperUpload(new Uint8Array(1), undefined);
+    expect(out.mimeType).toBe('audio/wav');
+    expect(out.filename).toBe('audio.wav');
+  });
+
+  it('accepts an ArrayBuffer input', () => {
+    const buf = new Uint8Array([5, 6, 7]).buffer;
+    const out = normalizeWhisperUpload(buf, 'audio/ogg');
+    expect([...out.bytes]).toEqual([5, 6, 7]);
+  });
+
+  it('degrades to the default when a non-string mimeType slips past the type', () => {
+    // The Telegram path forwards `media.mime_type` from raw update JSON, which a
+    // crafted message could make a number/object/array. `.toLowerCase()` would
+    // throw on these; the runtime guard must fall back to audio/wav instead.
+    for (const bad of [123, {}, [], true, Symbol('x')] as unknown[]) {
+      const out = normalizeWhisperUpload(new Uint8Array([1]), bad as string | undefined);
+      expect(out.mimeType).toBe('audio/wav');
+      expect(out.filename).toBe('audio.wav');
+    }
+  });
+
+  it('treats null mimeType like a missing one', () => {
+    const out = normalizeWhisperUpload(new Uint8Array([1]), null as unknown as undefined);
+    expect(out.mimeType).toBe('audio/wav');
+    expect(out.filename).toBe('audio.wav');
+  });
+});

package/src/audio.ts

@@ -0,0 +1,150 @@
+/**
+ * Audio helpers shared across STT plugins. Whisper-family backends — the
+ * generic OpenAI Whisper endpoint, the Codex OAuth `/transcribe` proxy,
+ * any future Whisper-compatible vendor — all want the same preprocessing
+ * (filename inference from MIME, raw PCM16 → WAV wrapping). Centralizing
+ * them here keeps the wrapper plugins thin.
+ */
+
+import { MOXXY_PCM16_24KHZ_MIME } from '@moxxy/sdk';
+
+/** A custom MIME tag used by the TUI voice recorder to flag raw PCM16
+ *  mono @ 24kHz bytes (ffmpeg's `-f s16le` output) so the transcriber
+ *  knows to wrap them in a WAV header before upload. Public so other
+ *  recorders / channels can mark their captures identically. Sourced from
+ *  the SDK's zero-dep cross-package source of truth; re-exported here so the
+ *  existing `@moxxy/plugin-stt-whisper` surface stays stable. */
+export { MOXXY_PCM16_24KHZ_MIME };
+
+/** Default filename per MIME type, used to set the upload `filename` so
+ *  the vendor's content sniffer routes to the right decoder. Defaults to
+ *  `audio.bin` for anything unmapped.
+ *
+ *  The MIME string is caller-supplied and can be fully untrusted (the
+ *  Telegram voice path forwards `media.mime_type` verbatim). A plain object
+ *  literal would let a crafted MIME equal to an inherited member name
+ *  ('constructor', 'toString', '__proto__', …) resolve to a function/object
+ *  instead of `undefined`, defeating the `?? 'audio.bin'` fallback. Using a
+ *  null-prototype map closes that hole; lookups can only hit own keys. */
+export const WHISPER_FILENAME_BY_MIME: Readonly<Record<string, string>> =
+  /* null-prototype: see comment above */ Object.assign(Object.create(null) as Record<string, string>, {
+    'audio/ogg': 'audio.ogg',
+    'audio/opus': 'audio.opus',
+    'audio/mpeg': 'audio.mp3',
+    'audio/mp3': 'audio.mp3',
+    'audio/wav': 'audio.wav',
+    'audio/x-wav': 'audio.wav',
+    'audio/webm': 'audio.webm',
+    'audio/m4a': 'audio.m4a',
+    'audio/mp4': 'audio.mp4',
+    'audio/flac': 'audio.flac',
+  });
+
+export interface NormalizedAudioUpload {
+  readonly bytes: Uint8Array;
+  readonly mimeType: string;
+  readonly filename: string;
+}
+
+/**
+ * Normalize a raw audio buffer for upload to a Whisper-family endpoint.
+ *
+ * - If the input is `MOXXY_PCM16_24KHZ_MIME`, wraps the raw samples in a
+ *   WAV header (samples are mono, 24kHz, 16-bit little-endian) and
+ *   reports the upload as `audio/wav`.
+ * - Otherwise passes the bytes through and picks a filename from the
+ *   MIME table (or `audio.bin` for unknown types).
+ *
+ * The optional `filenamePrefix` lets callers brand the upload filename
+ * (e.g. Codex uses `moxxy.wav`); when omitted the default `audio.<ext>`
+ * shape is used.
+ */
+export function normalizeWhisperUpload(
+  audio: Uint8Array | ArrayBuffer,
+  mimeType: string | undefined,
+  filenamePrefix?: string,
+): NormalizedAudioUpload {
+  const bytes = audio instanceof Uint8Array ? audio : new Uint8Array(audio);
+  // MIME types are case-insensitive (RFC 2045) and may carry a `; codecs=…`
+  // parameter; some callers (Telegram) forward the header verbatim without
+  // normalizing. Canonicalize once so casing/params don't miss the table.
+  //
+  // `mimeType` is *typed* `string | undefined`, but the value crosses a trust
+  // boundary unvalidated: the Telegram path forwards `media.mime_type` from raw
+  // update JSON, which a crafted message could make a number/object/array.
+  // Guard the runtime type so `.toLowerCase()` can't throw on hostile input —
+  // anything non-string degrades to the default rather than crashing the path.
+  const rawMime = typeof mimeType === 'string' ? mimeType : '';
+  const mt = (rawMime || 'audio/wav').toLowerCase().split(';')[0]!.trim();
+  if (mt === MOXXY_PCM16_24KHZ_MIME) {
+    return {
+      bytes: pcm16MonoToWav(bytes, 24_000),
+      mimeType: 'audio/wav',
+      filename: rename(filenamePrefix, 'wav') ?? 'audio.wav',
+    };
+  }
+  // Null-prototype map + string guard: an untrusted MIME can't surface an
+  // inherited member (function/object), so the upload filename is always a
+  // real string and `extOf` never receives a non-string.
+  const mapped = WHISPER_FILENAME_BY_MIME[mt];
+  const defaultName = typeof mapped === 'string' ? mapped : 'audio.bin';
+  return {
+    bytes,
+    mimeType: mt,
+    filename: rename(filenamePrefix, extOf(defaultName)) ?? defaultName,
+  };
+}
+
+function rename(prefix: string | undefined, ext: string): string | undefined {
+  return prefix ? `${prefix}.${ext}` : undefined;
+}
+
+function extOf(filename: string): string {
+  const dot = filename.lastIndexOf('.');
+  return dot >= 0 ? filename.slice(dot + 1) : 'bin';
+}
+
+/**
+ * Wrap raw PCM16 mono samples in a WAV container. Used by recorders that
+ * stream `s16le` (ffmpeg's default raw output) so the bytes can be sent
+ * to endpoints that only accept container formats.
+ */
+export function pcm16MonoToWav(pcm: Uint8Array | ArrayBuffer, sampleRate = 24_000): Uint8Array {
+  const raw = pcm instanceof Uint8Array ? pcm : new Uint8Array(pcm);
+  // 16-bit samples are 2 bytes; a trailing odd byte is half a sample and
+  // breaks RIFF even-alignment, so drop it. `subarray` is a view, no copy.
+  const data = raw.byteLength & 1 ? raw.subarray(0, raw.byteLength & ~1) : raw;
+  // The RIFF/data chunk sizes are unsigned 32-bit; >~4GiB would silently
+  // wrap to a tiny size and emit a structurally corrupt WAV. Reject loudly.
+  if (data.byteLength > 0xffffffff - 36) {
+    throw new RangeError(
+      `PCM payload too large for a WAV container (${data.byteLength} bytes; max ${0xffffffff - 36}).`,
+    );
+  }
+  const headerBytes = 44;
+  const wav = new Uint8Array(headerBytes + data.byteLength);
+  const view = new DataView(wav.buffer);
+
+  writeAscii(wav, 0, 'RIFF');
+  view.setUint32(4, 36 + data.byteLength, true);
+  writeAscii(wav, 8, 'WAVE');
+  writeAscii(wav, 12, 'fmt ');
+  view.setUint32(16, 16, true);
+  view.setUint16(20, 1, true);
+  view.setUint16(22, 1, true);
+  view.setUint32(24, sampleRate, true);
+  view.setUint32(28, sampleRate * 2, true);
+  view.setUint16(32, 2, true);
+  view.setUint16(34, 16, true);
+  writeAscii(wav, 36, 'data');
+  view.setUint32(40, data.byteLength, true);
+  wav.set(data, headerBytes);
+
+  return wav;
+}
+
+function writeAscii(target: Uint8Array, offset: number, value: string): void {
+  for (let i = 0; i < value.length; i += 1) {
+    target[offset + i] = value.charCodeAt(i);
+  }
+}

package/src/index.ts

@@ -0,0 +1,73 @@
+import { definePlugin, defineTranscriber, type Plugin } from '@moxxy/sdk';
+import { WhisperTranscriber, type WhisperModel, type WhisperTranscriberOptions } from './whisper.js';
+
+export {
+  WhisperTranscriber,
+  createWhisperTranscriber,
+  type WhisperModel,
+  type WhisperTranscriberOptions,
+} from './whisper.js';
+export {
+  MOXXY_PCM16_24KHZ_MIME,
+  WHISPER_FILENAME_BY_MIME,
+  normalizeWhisperUpload,
+  pcm16MonoToWav,
+  type NormalizedAudioUpload,
+} from './audio.js';
+
+export interface BuildWhisperPluginOptions {
+  /**
+   * Default model used when the host calls `session.transcribers.setActive(name)`
+   * without an explicit config. Defaults to `whisper-1`.
+   */
+  readonly model?: WhisperModel;
+  /**
+   * Optional default config baked into the transcriber def. Callers can
+   * still override per-`setActive(name, config)`.
+   */
+  readonly defaults?: Omit<WhisperTranscriberOptions, 'client'>;
+}
+
+/**
+ * Build the @moxxy/plugin-stt-whisper plugin. Each instance registers
+ * exactly one transcriber, named `openai-<model>`.
+ *
+ * To run several Whisper-family models at once, build the plugin once per
+ * model — the transcriber names won't collide (`openai-whisper-1` vs
+ * `openai-gpt-4o-transcribe`), but each registration carries the SAME
+ * plugin name, so the host must register them under DISTINCT plugin names
+ * (the name-keyed plugin registry would otherwise clobber the first).
+ *
+ * Activation:
+ *   session.transcribers.setActive('openai-whisper-1', { apiKey: ... });
+ *
+ * The plugin is intentionally side-effect free — registering it does
+ * NOT activate the transcriber. The host (CLI / config loader) chooses
+ * activation explicitly so users on local providers aren't surprised by
+ * outbound calls to OpenAI.
+ */
+export function buildWhisperPlugin(opts: BuildWhisperPluginOptions = {}): Plugin {
+  const model = opts.model ?? 'whisper-1';
+  const name = `openai-${model}`;
+  return definePlugin({
+    name: '@moxxy/plugin-stt-whisper',
+    version: '0.0.0',
+    transcribers: [
+      defineTranscriber({
+        name,
+        displayName: `OpenAI ${model}`,
+        createClient: (config) => {
+          const merged: WhisperTranscriberOptions = {
+            ...(opts.defaults ?? {}),
+            ...(config as WhisperTranscriberOptions),
+            model,
+          };
+          return new WhisperTranscriber(merged);
+        },
+      }),
+    ],
+  });
+}
+
+// Discovery entry: `createPluginLoader` requires a default Plugin export.
+export default buildWhisperPlugin();

package/src/whisper.test.ts

@@ -0,0 +1,281 @@
+import { describe, expect, it, vi } from 'vitest';
+import type OpenAI from 'openai';
+import { APIError, APIConnectionError, APIUserAbortError } from 'openai';
+import { WhisperTranscriber } from './whisper.js';
+import { buildWhisperPlugin } from './index.js';
+import { MOXXY_PCM16_24KHZ_MIME, normalizeWhisperUpload, pcm16MonoToWav } from './audio.js';
+
+const fakeOpenAI = (impl: (req: unknown) => unknown): OpenAI =>
+  ({
+    audio: {
+      transcriptions: {
+        create: vi.fn(async (req: unknown) => impl(req)),
+      },
+    },
+  }) as unknown as OpenAI;
+
+/** A client whose `create` always rejects with the supplied error — exercises
+ *  the `run()` failure-translation surface without touching the network. */
+const throwingOpenAI = (err: unknown): OpenAI =>
+  ({
+    audio: {
+      transcriptions: {
+        create: vi.fn(async () => {
+          throw err;
+        }),
+      },
+    },
+    // `run()` reads client.baseURL for error context.
+    baseURL: 'https://api.openai.com/v1',
+  }) as unknown as OpenAI;
+
+describe('WhisperTranscriber', () => {
+  it('returns text, language, duration, and segments from verbose_json', async () => {
+    const client = fakeOpenAI(() => ({
+      text: 'hello world',
+      language: 'en',
+      duration: 1.5,
+      segments: [
+        { start: 0, end: 1.5, text: 'hello world' },
+      ],
+    }));
+    const t = new WhisperTranscriber({ client });
+    const result = await t.transcribe(new Uint8Array([1, 2, 3]), { mimeType: 'audio/ogg' });
+    expect(result.text).toBe('hello world');
+    expect(result.language).toBe('en');
+    expect(result.durationSec).toBe(1.5);
+    expect(result.segments).toEqual([{ start: 0, end: 1.5, text: 'hello world' }]);
+  });
+
+  it('passes language hint + prompt to the OpenAI client', async () => {
+    const create = vi.fn(async () => ({ text: 'cześć', language: 'pl', segments: [] }));
+    const client = { audio: { transcriptions: { create } } } as unknown as OpenAI;
+    const t = new WhisperTranscriber({ client, language: 'pl' });
+    await t.transcribe(new Uint8Array(), { mimeType: 'audio/ogg', prompt: 'jargon-list' });
+    const req = create.mock.calls[0]![0] as { language: string; prompt: string; response_format: string };
+    expect(req.language).toBe('pl');
+    expect(req.prompt).toBe('jargon-list');
+    expect(req.response_format).toBe('verbose_json');
+  });
+
+  it('uses the per-call language over the default', async () => {
+    const create = vi.fn(async () => ({ text: '' }));
+    const client = { audio: { transcriptions: { create } } } as unknown as OpenAI;
+    const t = new WhisperTranscriber({ client, language: 'pl' });
+    await t.transcribe(new Uint8Array(), { language: 'en' });
+    const req = create.mock.calls[0]![0] as { language: string };
+    expect(req.language).toBe('en');
+  });
+
+  it('falls back to plain text on gpt-4o-transcribe (no verbose_json branch)', async () => {
+    const create = vi.fn(async () => ({ text: 'plain' }));
+    const client = { audio: { transcriptions: { create } } } as unknown as OpenAI;
+    const t = new WhisperTranscriber({ client, model: 'gpt-4o-transcribe' });
+    const out = await t.transcribe(new Uint8Array(), { mimeType: 'audio/wav' });
+    expect(out.text).toBe('plain');
+    const req = create.mock.calls[0]![0] as { response_format?: string };
+    expect(req.response_format).toBeUndefined();
+  });
+
+  it('plugin registers a transcriber whose createClient yields the right name', () => {
+    const plugin = buildWhisperPlugin({});
+    expect(plugin.transcribers).toHaveLength(1);
+    const def = plugin.transcribers![0]!;
+    expect(def.name).toBe('openai-whisper-1');
+    expect(def.displayName).toBe('OpenAI whisper-1');
+    const inst = def.createClient({ apiKey: 'sk-test' });
+    expect(inst.name).toBe('openai-whisper-1');
+  });
+
+  it('WAV-wraps the project raw-PCM16 MIME before upload', async () => {
+    const create = vi.fn(async () => ({ text: '' }));
+    const client = { audio: { transcriptions: { create } } } as unknown as OpenAI;
+    const t = new WhisperTranscriber({ client });
+    // 4 raw s16le samples of silence.
+    const raw = new Uint8Array([0, 0, 0, 0, 0, 0, 0, 0]);
+    await t.transcribe(raw, { mimeType: MOXXY_PCM16_24KHZ_MIME });
+
+    const req = create.mock.calls[0]![0] as { file: File };
+    expect(req.file.type).toBe('audio/wav');
+    const header = new Uint8Array(await req.file.arrayBuffer());
+    const ascii = (s: number, e: number): string =>
+      String.fromCharCode(...header.slice(s, e));
+    expect(ascii(0, 4)).toBe('RIFF');
+    expect(ascii(8, 12)).toBe('WAVE');
+    // Header (44 bytes) + the 8 raw sample bytes.
+    expect(header.byteLength).toBe(44 + raw.byteLength);
+  });
+
+  it('plugin honors a non-default model name', () => {
+    const plugin = buildWhisperPlugin({ model: 'gpt-4o-mini-transcribe' });
+    expect(plugin.transcribers![0]!.name).toBe('openai-gpt-4o-mini-transcribe');
+  });
+
+  it('throws PROVIDER_UNKNOWN_RESPONSE when verbose_json lacks a string text', async () => {
+    const client = fakeOpenAI(() => ({ language: 'en', segments: [] }));
+    const t = new WhisperTranscriber({ client });
+    await expect(
+      t.transcribe(new Uint8Array([1, 2, 3]), { mimeType: 'audio/ogg' }),
+    ).rejects.toMatchObject({ code: 'PROVIDER_UNKNOWN_RESPONSE' });
+  });
+
+  it('throws PROVIDER_UNKNOWN_RESPONSE when the gpt-4o response lacks text', async () => {
+    const client = fakeOpenAI(() => ({ foo: 'bar' }));
+    const t = new WhisperTranscriber({ client, model: 'gpt-4o-transcribe' });
+    await expect(
+      t.transcribe(new Uint8Array([1, 2, 3]), { mimeType: 'audio/wav' }),
+    ).rejects.toMatchObject({ code: 'PROVIDER_UNKNOWN_RESPONSE' });
+  });
+
+  it('ignores a non-string language/duration in verbose_json', async () => {
+    const client = fakeOpenAI(() => ({ text: 'ok', language: 123, duration: 'nope' }));
+    const t = new WhisperTranscriber({ client });
+    const result = await t.transcribe(new Uint8Array([1]), { mimeType: 'audio/ogg' });
+    expect(result.text).toBe('ok');
+    expect(result.language).toBeUndefined();
+    expect(result.durationSec).toBeUndefined();
+  });
+
+  it('drops malformed segments from a hostile verbose_json response without crashing', async () => {
+    // A vendor (or man-in-the-middle) response whose segments array is full of
+    // junk: null, a primitive, missing fields, wrong types, and non-finite
+    // bounds. A blind `.start` read on `null` would throw; an unchecked map
+    // would leak `{ text: 123 }`. Each bad entry must be dropped; only the one
+    // well-formed segment survives.
+    const client = fakeOpenAI(() => ({
+      text: 'ok',
+      segments: [
+        null,
+        42,
+        'not-an-object',
+        { start: 0, end: 1 }, // missing text
+        { start: 0, text: 'no end' }, // missing end
+        { start: 'x', end: 1, text: 'bad start' }, // non-number start
+        { start: 0, end: 1, text: 99 }, // non-string text
+        { start: Number.NaN, end: 1, text: 'nan start' }, // non-finite
+        { start: 0, end: Infinity, text: 'inf end' }, // non-finite
+        { start: 1, end: 2, text: 'good' }, // the only valid one
+      ],
+    }));
+    const t = new WhisperTranscriber({ client });
+    const result = await t.transcribe(new Uint8Array([1]), { mimeType: 'audio/ogg' });
+    expect(result.text).toBe('ok');
+    expect(result.segments).toEqual([{ start: 1, end: 2, text: 'good' }]);
+  });
+
+  it('returns an empty segments array when every segment is malformed', async () => {
+    const client = fakeOpenAI(() => ({ text: 'ok', segments: [null, undefined, {}] }));
+    const t = new WhisperTranscriber({ client });
+    const result = await t.transcribe(new Uint8Array([1]), { mimeType: 'audio/ogg' });
+    expect(result.segments).toEqual([]);
+  });
+
+  it('does not crash when mimeType is a non-string at runtime (untrusted Telegram path)', async () => {
+    const create = vi.fn(async () => ({ text: 'ok' }));
+    const client = { audio: { transcriptions: { create } } } as unknown as OpenAI;
+    const t = new WhisperTranscriber({ client });
+    // A crafted Telegram update could deliver a non-string mime_type; the type
+    // says `string` but the runtime value is hostile. Must degrade, not throw.
+    const result = await t.transcribe(new Uint8Array([1]), {
+      mimeType: 123 as unknown as string,
+    });
+    expect(result.text).toBe('ok');
+    const req = create.mock.calls[0]![0] as { file: File };
+    // Defaults to the audio/wav fallback filename rather than crashing.
+    expect(req.file.name).toBe('audio.wav');
+  });
+});
+
+describe('WhisperTranscriber.run() error translation', () => {
+  const audio = new Uint8Array([1, 2, 3]);
+
+  it('re-throws a user abort unchanged (not masked as a provider error)', async () => {
+    const abort = new APIUserAbortError();
+    const t = new WhisperTranscriber({ client: throwingOpenAI(abort) });
+    await expect(t.transcribe(audio, { mimeType: 'audio/ogg' })).rejects.toBe(abort);
+  });
+
+  it('maps a refused connection to NETWORK_UNREACHABLE', async () => {
+    const cause = Object.assign(new Error('connect ECONNREFUSED'), { code: 'ECONNREFUSED' });
+    const conn = new APIConnectionError({ cause });
+    const t = new WhisperTranscriber({ client: throwingOpenAI(conn) });
+    await expect(t.transcribe(audio, { mimeType: 'audio/ogg' })).rejects.toMatchObject({
+      code: 'NETWORK_UNREACHABLE',
+    });
+  });
+
+  it('maps HTTP 401 to AUTH_INVALID', async () => {
+    const err = new APIError(401, { error: { message: 'bad key' } }, 'Unauthorized', {});
+    const t = new WhisperTranscriber({ client: throwingOpenAI(err) });
+    await expect(t.transcribe(audio, { mimeType: 'audio/ogg' })).rejects.toMatchObject({
+      code: 'AUTH_INVALID',
+    });
+  });
+
+  it('maps HTTP 500 to PROVIDER_SERVER_ERROR', async () => {
+    const err = new APIError(500, undefined, 'boom', {});
+    const t = new WhisperTranscriber({ client: throwingOpenAI(err) });
+    await expect(t.transcribe(audio, { mimeType: 'audio/ogg' })).rejects.toMatchObject({
+      code: 'PROVIDER_SERVER_ERROR',
+    });
+  });
+
+  it('falls back to PROVIDER_BAD_REQUEST for an unmapped status', async () => {
+    const err = new APIError(418, undefined, 'teapot', {});
+    const t = new WhisperTranscriber({ client: throwingOpenAI(err) });
+    await expect(t.transcribe(audio, { mimeType: 'audio/ogg' })).rejects.toMatchObject({
+      code: 'PROVIDER_BAD_REQUEST',
+      context: { status: 418 },
+    });
+  });
+
+  it('re-throws an unclassifiable non-network error rather than swallowing it', async () => {
+    const odd = new Error('totally unexpected');
+    const t = new WhisperTranscriber({ client: throwingOpenAI(odd) });
+    await expect(t.transcribe(audio, { mimeType: 'audio/ogg' })).rejects.toBe(odd);
+  });
+});
+
+describe('normalizeWhisperUpload hardening', () => {
+  it('does not resolve inherited prototype members for a crafted MIME', () => {
+    // 'constructor' / 'toString' / '__proto__' must NOT surface a function/object.
+    for (const mt of ['constructor', 'toString', 'valueOf', 'hasOwnProperty', '__proto__']) {
+      const out = normalizeWhisperUpload(new Uint8Array([1]), mt);
+      expect(out.filename).toBe('audio.bin');
+      expect(typeof out.filename).toBe('string');
+    }
+  });
+
+  it('does not throw inside the prefix path for a crafted MIME', () => {
+    // extOf() would have thrown if the lookup returned a function.
+    const out = normalizeWhisperUpload(new Uint8Array([1]), 'constructor', 'moxxy');
+    expect(out.filename).toBe('moxxy.bin');
+  });
+
+  it('matches MIME case-insensitively and strips codec params', () => {
+    expect(normalizeWhisperUpload(new Uint8Array([1]), 'AUDIO/OGG').filename).toBe('audio.ogg');
+    expect(
+      normalizeWhisperUpload(new Uint8Array([1]), 'audio/webm; codecs=opus').filename,
+    ).toBe('audio.webm');
+    expect(normalizeWhisperUpload(new Uint8Array([1]), '  Audio/Wav ').filename).toBe('audio.wav');
+  });
+});
+
+describe('pcm16MonoToWav hardening', () => {
+  it('drops a trailing odd byte so the data chunk stays even-aligned', () => {
+    const wav = pcm16MonoToWav(new Uint8Array([1, 2, 3]));
+    const view = new DataView(wav.buffer);
+    // 3 input bytes → 2 retained (one whole 16-bit sample).
+    expect(view.getUint32(40, true)).toBe(2);
+    expect(wav.byteLength).toBe(44 + 2);
+  });
+
+  it('rejects a payload too large for the 32-bit WAV size fields', () => {
+    // Fake a (real) Uint8Array reporting an oversized, even byteLength without
+    // allocating 4GiB. Even length skips the odd-byte subarray branch, so the
+    // size guard is what must fire. 0xfffffffe > 0xffffffff - 36.
+    const huge = new Uint8Array(2);
+    Object.defineProperty(huge, 'byteLength', { value: 0xfffffffe });
+    expect(() => pcm16MonoToWav(huge)).toThrow(RangeError);
+  });
+});