@chatpanel/gateway 0.6.50 → 0.6.52

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/gateway",
-  "version": "0.6.50",
+  "version": "0.6.52",
   "description": "Local privacy gateway — redacts PII out of OpenAI/Anthropic API traffic before it reaches a model, then restores it in the reply. Point opencode, codex, aider, Claude Code, etc. at it.",
   "type": "module",
   "bin": {

package/src/config.js

@@ -111,9 +111,23 @@ const DEFAULTS = {
   // as stt: the model downloads on FIRST synthesis, never on gateway boot.
   tts: {
     enabled: true,
+    // 'local' = Kokoro in this process, nothing leaves the machine (the default).
+    // 'openai' | 'elevenlabs' = a remote voice. Auth is passed through from the
+    // client as everywhere else here; no key is stored. See src/tts-remote.js for
+    // why remote synthesis redacts by default and what that costs.
+    provider: 'local',
     model: 'onnx-community/Kokoro-82M-v1.0-ONNX',
     voice: 'af_heart',
     allowDownload: true,
+    remote: {
+      baseUrl: '',   // '' = the provider's own default endpoint
+      model: '',
+      voice: '',
+      // Redact before the text leaves this machine. Audio cannot be un-redacted,
+      // so this genuinely means the voice says "PERSON_1" — set false only if you
+      // accept sending real values to the vendor.
+      redact: true,
+    },
   },
 
   // Log one line per request (method, tokens redacted) without any raw values.

package/src/server.js

@@ -41,6 +41,7 @@ import { MODEL_CATALOG, isKnownModel, isValidCustomModelId } from './models.js';
 import { STT_MODEL_CATALOG, isKnownSttModel, isValidCustomSttId, DEFAULT_STT_MODEL, STT_DTYPES, isValidDtype } from './stt-models.js';
 import * as ttsEngine from './tts-engine.js';
 import { TTS_MODEL_CATALOG, TTS_VOICES, isKnownTtsModel, isValidCustomTtsId, isKnownVoice, isValidVoiceId, DEFAULT_TTS_MODEL, DEFAULT_TTS_VOICE, TTS_DTYPES, isValidTtsDtype, MAX_TTS_CHARS } from './tts-models.js';
+import { ttsDestination, synthesizeRemote, isValidRemoteVoice } from './tts-remote.js';
 import { resolvePro, checkQuota, consume, usage } from './freegate.js';
 import { publicConfig, applyConfigPatch, applyNerModelSelection, persistConfig, configPath } from './configstore.js';
 import { resolveDestination, aggregateModelsAsync, listDestinations } from './router.js';
@@ -51,7 +52,7 @@ import * as openai from './openai.js';
 import * as responses from './responses.js';
 import * as anthropic from './anthropic.js';
 
-export const VERSION = '0.6.50';
+export const VERSION = '0.6.52';
 
 // WARM search tier — SQLite + FTS5 record store (falls back to an encrypted-JSON
 // store if SQLite can't load), fed by the extension's ingest sync + backup-ingest.
@@ -980,8 +981,13 @@ export function createGateway(cfg = loadConfig()) {
           progress: ttsEngine.progress(),
           available,
           voice: cfg.tts?.voice || DEFAULT_TTS_VOICE,
-          // Each voice is a separate ~500 KB style bank, so `installed` is per-voice.
-          voices: TTS_VOICES.map((v) => ({ ...v, installed: ttsEngine.voiceOnDisk(v.id, active) })),
+          // Architecture decides whether voices mean anything: Kokoro picks one from
+          // a style bank, VITS/MMS is single-speaker. An empty list tells the UI to
+          // hide the picker rather than offer choices that cannot take effect.
+          arch: ttsEngine.arch(),
+          supportsVoices: ttsEngine.supportsVoices(),
+          sampleRate: ttsEngine.sampleRate(),
+          voices: ttsEngine.arch() === 'vits' ? [] : TTS_VOICES.map((v) => ({ ...v, installed: ttsEngine.voiceOnDisk(v.id, active) })),
           dtype: cfg.tts?.dtype || 'auto',
           loadedDtype: ttsEngine.health().dtype,
           runtime: ttsEngine.health().runtime,
@@ -1025,14 +1031,41 @@ export function createGateway(cfg = loadConfig()) {
       const text = body && typeof (body.input ?? body.text) === 'string' ? String(body.input ?? body.text).trim() : '';
       if (!text) return sendJson(res, 400, { error: { message: 'text is required', type: 'bad_request' } });
       if (text.length > MAX_TTS_CHARS) return sendJson(res, 413, { error: { message: `text too long (max ${MAX_TTS_CHARS} chars)`, type: 'too_long' } });
-      const voice = body && typeof body.voice === 'string' && body.voice.trim() ? body.voice.trim() : (cfg.tts?.voice || DEFAULT_TTS_VOICE);
-      if (!(isKnownVoice(voice) && isValidVoiceId(voice))) return sendJson(res, 400, { error: { message: 'unknown or invalid voice', type: 'bad_voice' } });
       const speed = Number.isFinite(body.speed) ? Math.min(2, Math.max(0.5, body.speed)) : 1;
+      const dest = ttsDestination(cfg);
+      // A remote destination has its own voice namespace (an ElevenLabs voice id is
+      // not a Kokoro one), so the local catalog check would reject every valid id.
+      const rawVoice = body && typeof body.voice === 'string' && body.voice.trim() ? body.voice.trim() : null;
+      const voice = rawVoice || (dest ? dest.voice : (cfg.tts?.voice || DEFAULT_TTS_VOICE));
+      const voiceOk = dest ? isValidRemoteVoice(voice) : (isKnownVoice(voice) && isValidVoiceId(voice));
+      if (!voiceOk) return sendJson(res, 400, { error: { message: 'unknown or invalid voice', type: 'bad_voice' } });
       // We synthesize WAV only. Say so rather than returning WAV bytes under an mp3
       // content-type — a client that trusts the header would play noise.
       const fmt = body && typeof body.response_format === 'string' ? body.response_format.toLowerCase() : 'wav';
       if (fmt !== 'wav' && fmt !== 'pcm') return sendJson(res, 400, { error: { message: `unsupported response_format "${fmt}" — this gateway synthesizes wav`, type: 'bad_format' } });
       try {
+        // Remote destination: the caller's own auth goes upstream, the text is
+        // redacted first unless this destination explicitly opted out, and the
+        // vendor's own audio format is passed straight through rather than
+        // re-wrapped — we did not synthesize it and must not claim its container.
+        if (dest) {
+          const { audio, contentType, redacted } = await synthesizeRemote({
+            dest, text, voice, speed,
+            auth: req.headers.authorization || req.headers['xi-api-key'] || '',
+            redaction: cfg.redaction,
+            isPro: await resolvePro(cfg.pro?.entitlementToken),
+          });
+          res.writeHead(200, {
+            'Content-Type': contentType,
+            'Content-Length': String(audio.length),
+            'Cache-Control': 'no-store',
+            // Say what actually left. A caller that asked for privacy can verify it,
+            // and one that turned it off can see that it is off.
+            'X-Tts-Provider': dest.kind,
+            'X-Tts-Redacted': String(redacted),
+          });
+          return res.end(audio);
+        }
         const ok = await ttsEngine.ready({
           onLog: (m) => console.log(m),
           allowDownload: cfg.tts?.allowDownload !== false,
@@ -1041,12 +1074,15 @@ export function createGateway(cfg = loadConfig()) {
         });
         if (!ok) return sendJson(res, 503, { error: { message: ttsEngine.health().error || 'tts model not ready', type: 'tts_unavailable' } });
         const pcm = await ttsEngine.synth(text, { voice, speed });
-        const out = fmt === 'pcm' ? Buffer.from(new Float32Array(pcm).buffer) : ttsEngine.toWav(pcm);
+        // The ACTIVE model's rate, not the constant: a VITS/MMS model emits 16 kHz
+        // and writing it into a 24 kHz header plays it fast and chipmunked.
+        const rate = ttsEngine.sampleRate();
+        const out = fmt === 'pcm' ? Buffer.from(new Float32Array(pcm).buffer) : ttsEngine.toWav(pcm, rate);
         res.writeHead(200, {
           'Content-Type': fmt === 'pcm' ? 'application/octet-stream' : 'audio/wav',
           'Content-Length': String(out.length),
           'Cache-Control': 'no-store',
-          'X-Tts-Sample-Rate': String(ttsEngine.SAMPLE_RATE),
+          'X-Tts-Sample-Rate': String(rate),
         });
         return res.end(out);
       } catch (e) {

package/src/tts-engine.js

@@ -27,7 +27,11 @@ import {
   ttsModelDtype, isKnownTtsModel, isValidVoiceId, voiceLang,
 } from './tts-models.js';
 
-export const SAMPLE_RATE = 24000; // Kokoro's output rate — fixed by the model
+// Kokoro's rate. Kept as a named export because it is the default and several
+// callers want a number before anything is loaded — but it is NOT universal: a
+// VITS/MMS model outputs 16 kHz, and writing its samples into a 24 kHz WAV header
+// plays it back fast and chipmunked. Use sampleRate() once a model is active.
+export const SAMPLE_RATE = 24000;
 
 let _state = 'off';       // 'off' | 'loading' | 'downloading' | 'ready' | 'error'
 let _model = null;
@@ -37,14 +41,27 @@ let _dtype = null;
 let _err = null;
 let _progress = null;
 let _initPromise = null;
+let _arch = null;         // 'style-tts2' (Kokoro) | 'vits' (MMS et al)
+let _rate = SAMPLE_RATE;  // the ACTIVE model's output rate
 const _voices = new Map(); // voice id → Float32Array style bank
 
+// The architectures this engine can actually drive. Anything else is refused at
+// load with a message naming what it is, rather than failing later inside a
+// forward pass with a shape error nobody can act on.
+export const SUPPORTED_ARCH = { style_text_to_speech_2: 'style-tts2', vits: 'vits' };
+
+export function arch() { return _arch; }
+export function sampleRate() { return _rate; }
+// Kokoro picks a voice from a style bank; VITS is single-speaker and has none, so
+// the UI must not offer a voice list that cannot do anything.
+export function supportsVoices() { return _arch === 'style-tts2'; }
+
 export function state() { return _state; }
 export function isReady() { return _state === 'ready' && !!_net; }
 export function progress() { return _progress; }
 
 export function health() {
-  return { configured: _state !== 'off', ok: isReady(), state: _state, model: _model, dtype: _dtype, runtime: runtimeName(), error: _err };
+  return { configured: _state !== 'off', ok: isReady(), state: _state, model: _model, dtype: _dtype, runtime: runtimeName(), error: _err, arch: _arch, sampleRate: _rate, voices: supportsVoices() };
 }
 
 export function modelDir(modelId) {
@@ -119,18 +136,32 @@ async function loadModel(modelId, { log = () => {}, allowDownload = true, dtype:
     // this is the SAME transformers instance ensureLib already configured (env,
     // cacheDir, wasm paths) — importing it here keeps ner-engine free of TTS.
     const tf = await import('@huggingface/transformers');
+
+    // Which architecture is this? Read the config BEFORE choosing a class, so an
+    // unsupported model is refused by name instead of exploding inside a forward
+    // pass with a tensor-shape error.
+    let modelType = '';
+    try {
+      const conf = await tf.AutoConfig.from_pretrained(modelId);
+      modelType = String(conf?.model_type || '').toLowerCase();
+    } catch { /* no config we can read — fall through to the Kokoro default */ }
+    const kind = SUPPORTED_ARCH[modelType] || (modelType ? null : 'style-tts2');
+    if (!kind) throw new Error(`unsupported TTS architecture "${modelType}" — this engine drives Kokoro (style_text_to_speech_2) and VITS/MMS`);
+
+    const onProgress = (p) => {
+      if (p?.status === 'progress' && p.file) _progress = { model: modelId, file: p.file, pct: Math.round(p.progress || 0) };
+    };
+    const Klass = kind === 'vits' ? tf.VitsModel : tf.StyleTextToSpeech2Model;
     const [net, tok] = await Promise.all([
-      tf.StyleTextToSpeech2Model.from_pretrained(modelId, {
-        dtype,
-        progress_callback: (p) => {
-          if (p?.status === 'progress' && p.file) _progress = { model: modelId, file: p.file, pct: Math.round(p.progress || 0) };
-        },
-      }),
+      Klass.from_pretrained(modelId, { dtype, progress_callback: onProgress }),
       tf.AutoTokenizer.from_pretrained(modelId),
     ]);
-    _net = net; _tok = tok; _model = modelId; _dtype = dtype;
+    _net = net; _tok = tok; _model = modelId; _dtype = dtype; _arch = kind;
+    // VITS/MMS emit 16 kHz; Kokoro 24 kHz. Take it from the model's own config
+    // where it says so, because guessing wrong plays the voice at the wrong pitch.
+    _rate = Number(net?.config?.sampling_rate) || (kind === 'vits' ? 16000 : SAMPLE_RATE);
     _state = 'ready'; _err = null; _progress = null;
-    log(`[tts] ready — model ${modelId} @ ${dtype} (${runtimeName()}, offline) — local speech active`);
+    log(`[tts] ready — model ${modelId} @ ${dtype} (${kind}, ${_rate} Hz, ${runtimeName()}, offline) — local speech active`);
     return true;
   } catch (e) {
     // A failed SWITCH keeps the previous working model, same as ner/stt.
@@ -231,9 +262,19 @@ export function splitSentences(text, maxChars = 300) {
  */
 export async function synthChunk(text, { voice = DEFAULT_TTS_VOICE, speed = 1 } = {}) {
   if (!isReady()) throw new Error('tts model not ready');
-  const { phonemize } = await import('phonemizer');
   const tf = await import('@huggingface/transformers');
 
+  // VITS/MMS: single-speaker, tokenizes GRAPHEMES directly — no phonemizer, no
+  // style bank, no speed input. One language per model, which is the trade for
+  // ~40 MB and a thousand of them.
+  if (_arch === 'vits') {
+    const inputs = _tok(String(text));
+    const out = await _net(inputs);
+    return out.waveform.data;
+  }
+
+  const { phonemize } = await import('phonemizer');
+
   // G2P follows the VOICE, not the request — an American voice reading British
   // phonemes is audibly wrong.
   const phonemes = (await phonemize(String(text), voiceLang(voice))).join(' ');
@@ -296,5 +337,6 @@ export function toWav(pcm, sampleRate = SAMPLE_RATE) {
 
 export function _reset() {
   _state = 'off'; _model = null; _net = null; _tok = null; _dtype = null;
-  _err = null; _progress = null; _initPromise = null; _voices.clear();
+  _err = null; _progress = null; _initPromise = null; _arch = null; _rate = SAMPLE_RATE;
+  _voices.clear();
 }

package/src/tts-models.js

@@ -40,8 +40,37 @@ export const TTS_MODEL_CATALOG = [
     approxMB: 330,  // fp32 on WASM; ~90 on native q8
     ramMB: 600,
     sampleRate: 24000,
+    voices: true,
     note: 'Apache-2.0, 82M params. Natural voices at ~5× realtime on CPU. The default.',
   },
+  {
+    id: 'onnx-community/Kokoro-82M-v1.1-zh-ONNX',
+    label: 'Kokoro 82M (v1.1, Chinese)',
+    lang: 'Chinese + English',
+    tier: 'balanced',
+    arch: 'style-tts2',
+    approxMB: 330,
+    ramMB: 600,
+    sampleRate: 24000,
+    voices: true,
+    note: 'The Mandarin-tuned Kokoro. Same engine and voice mechanism as v1.0.',
+  },
+  {
+    // One MMS entry so the second architecture is DISCOVERABLE from the list rather
+    // than only findable by search. The rest of the family (~1000 languages) is
+    // exactly what the search box is for — listing them all here would be a menu,
+    // not a catalog.
+    id: 'Xenova/mms-tts-hin',
+    label: 'MMS TTS — Hindi',
+    lang: 'Hindi (हिन्दी)',
+    tier: 'light',
+    arch: 'vits',
+    approxMB: 40,
+    ramMB: 200,
+    sampleRate: 16000,
+    voices: false,
+    note: 'Tiny single-speaker VITS. Meta\u2019s MMS covers ~1000 languages — search "mms-tts" for yours.',
+  },
 ];
 
 // Voice prefix → the language phonemizer must use for G2P. First letter = language,
@@ -84,7 +113,14 @@ export const TTS_VOICES = [
 // THIRD-PARTY re-export of a gated checkpoint. That is a parakeet-engine-sized
 // piece of work, not a catalog entry — so the seam is here and the engine is not.
 export function ttsModelEngine(id) {
-  return ttsModel(id)?.engine || 'style-tts2';
+  return ttsModel(id)?.arch || 'style-tts2';
+}
+
+// Does this catalog entry have selectable voices? Kokoro picks one from a style
+// bank; VITS/MMS is single-speaker. Unknown (a searched model) resolves at load.
+export function ttsModelHasVoices(id) {
+  const m = ttsModel(id);
+  return m ? m.voices !== false : true;
 }
 
 export function ttsModel(id) {

package/src/tts-remote.js

@@ -0,0 +1,109 @@
+// Remote text-to-speech destinations — ElevenLabs, OpenAI, or anything that speaks
+// the OpenAI /audio/speech shape (Groq, a local server, an OpenAI-compatible proxy).
+//
+// TWO RULES, and they are the whole reason this is a separate module from
+// tts-engine.js rather than a branch inside it.
+//
+// 1. NO KEY LIVES HERE. config.js says it outright — "the gateway forwards the
+//    CLIENT's own auth header upstream (it stores no provider keys)" — and a TTS
+//    destination is not the place to break that. The caller sends its own
+//    Authorization (or xi-api-key) and we pass it through. Config holds the ROUTE.
+//
+// 2. THE PRIVACY DECISION INVERTS. Local synthesis speaks restored text because the
+//    words never leave the machine; there is nothing to protect them from. The
+//    moment the destination is remote, the text IS leaving, to a vendor, and every
+//    other egress in this gateway is redacted first. So remote synthesis redacts by
+//    default.
+//
+//    That trade is real and cannot be papered over: audio cannot be un-redacted the
+//    way a text completion can, so a redacted remote voice literally says
+//    "PERSON_1". The honest options are (a) placeholders spoken aloud, or (b) real
+//    PII sent to a vendor — and the user picks, per destination, with `redact`. The
+//    default is the safe one and the choice is logged via onEgress, so sending real
+//    names to ElevenLabs is something someone DID, not something that happened.
+
+import { secureFetch } from './secure-fetch.js';
+import { redactSegments, segment } from './redact.js';
+
+export const TTS_PROVIDERS = ['local', 'openai', 'elevenlabs'];
+
+export function isValidTtsProvider(p) {
+  return TTS_PROVIDERS.includes(String(p || ''));
+}
+
+/** The configured destination, or null when synthesis is local (the default). */
+export function ttsDestination(cfg = {}) {
+  const t = cfg.tts || {};
+  const kind = t.provider || 'local';
+  if (kind === 'local' || !isValidTtsProvider(kind)) return null;
+  const r = t.remote || {};
+  return {
+    kind,
+    baseUrl: String(r.baseUrl || (kind === 'elevenlabs' ? 'https://api.elevenlabs.io/v1' : 'https://api.openai.com/v1')).replace(/\/+$/, ''),
+    model: r.model || (kind === 'elevenlabs' ? 'eleven_multilingual_v2' : 'tts-1'),
+    voice: r.voice || (kind === 'elevenlabs' ? '21m00Tcm4TlvDq8ikWAM' : 'alloy'),
+    // Undefined means "not set", which must read as ON — an absent flag is never
+    // permission to send someone's name to a vendor.
+    redact: r.redact !== false,
+  };
+}
+
+// A remote voice id lands in a URL PATH for ElevenLabs, so it is shape-checked
+// rather than trusted: no slashes, no traversal, no query smuggling.
+export function isValidRemoteVoice(v) {
+  return /^[A-Za-z0-9_-]{1,64}$/.test(String(v || ''));
+}
+
+/**
+ * Synthesize remotely. Returns { audio: Buffer, contentType, redacted } — `redacted`
+ * is the count of values replaced, so the caller can report what actually left.
+ *
+ * @param {{dest: any, text: string, voice?: string, speed?: number, auth?: string,
+ *          redaction?: any, isPro?: boolean, onEgress?: Function, fetchImpl?: Function}} opts
+ */
+export async function synthesizeRemote({ dest, text, voice, speed = 1, auth, redaction, isPro = true, onEgress = null, fetchImpl = null } = {}) {
+  if (!dest) throw new Error('no remote TTS destination configured');
+  const pick = voice || dest.voice;
+  if (!isValidRemoteVoice(pick)) throw new Error(`invalid remote voice id: ${pick}`);
+
+  // Redact BEFORE anything is built, so there is no path where the raw string
+  // reaches a request body by accident.
+  let out = String(text);
+  let redacted = 0;
+  if (dest.redact && redaction) {
+    const box = { text: out };
+    const r = await redactSegments([segment(() => box.text, (v) => { box.text = v; })], redaction, { isPro, onEgress });
+    out = box.text;
+    redacted = r?.count || 0;
+  }
+
+  const fetcher = fetchImpl || secureFetch;
+  const headers = { 'Content-Type': 'application/json' };
+  let url, body;
+  if (dest.kind === 'elevenlabs') {
+    url = `${dest.baseUrl}/text-to-speech/${encodeURIComponent(pick)}`;
+    body = { text: out, model_id: dest.model };
+    // ElevenLabs uses its own header. Accept either form from the caller so a
+    // generic OpenAI client can drive it too.
+    const key = stripBearer(auth);
+    if (key) headers['xi-api-key'] = key;
+  } else {
+    url = `${dest.baseUrl}/audio/speech`;
+    body = { model: dest.model, input: out, voice: pick, response_format: 'wav', speed };
+    if (auth) headers.Authorization = auth.startsWith('Bearer ') ? auth : `Bearer ${auth}`;
+  }
+
+  const res = await fetcher(url, { method: 'POST', headers, body: JSON.stringify(body) });
+  if (!res.ok) {
+    let detail = `HTTP ${res.status}`;
+    try { detail = (await res.text()).slice(0, 300) || detail; } catch { /* no body */ }
+    throw new Error(`remote tts failed: ${detail}`);
+  }
+  const audio = Buffer.from(await res.arrayBuffer());
+  return { audio, contentType: res.headers.get('content-type') || 'audio/mpeg', redacted };
+}
+
+function stripBearer(a) {
+  const s = String(a || '').trim();
+  return s.toLowerCase().startsWith('bearer ') ? s.slice(7).trim() : s;
+}