@nac3/forge-cli 0.2.0-alpha.1

package/dist/voice/types.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Voice subsystem: type surface shared across STT, TTS, providers,
+ * and the router.
+ *
+ * Design principles:
+ *   - Providers are interface-based. The router instantiates a
+ *     concrete provider per request based on the active config +
+ *     credentials from the vault.
+ *   - No credential ever appears in the type surface or on the
+ *     wire from server to browser.
+ *   - Provider IDs are strings, not enums, so adding a new
+ *     provider does not break existing configs that reference
+ *     unknown providers (loud error at resolve time, not at
+ *     parse time).
+ *
+ * ASCII-only.
+ */
+/** Identifiers for the providers Forge knows about today.
+ *  Open string union so future providers slot in without
+ *  forcing a v-bump on the config schema. */
+export type SttProviderId = 'whisper' | 'google' | string;
+export type TtsProviderId = 'google' | 'elevenlabs' | string;
+/** Audio format envelopes the providers accept on input. */
+export type SttAudioFormat = 'webm' | 'ogg' | 'wav' | 'mp3' | 'flac' | 'mp4';
+/** Audio format the providers emit on output. */
+export type TtsAudioFormat = 'mp3' | 'wav' | 'ogg' | 'opus';
+export interface SttRequest {
+    /** Raw audio bytes. */
+    audio: Buffer;
+    /** Format of the audio bytes. */
+    format: SttAudioFormat;
+    /** BCP-47 language hint (e.g. "es-AR", "en-US"). When unset
+     *  the provider falls back to its own auto-detect. */
+    languageHint?: string;
+    /** Override the default model for this single request. */
+    model?: string;
+}
+export interface SttResponse {
+    /** Recognised text, trimmed. */
+    text: string;
+    /** Detected language (BCP-47), when the provider reports it. */
+    language?: string;
+    /** Provider-side confidence in [0, 1] when reported. */
+    confidence?: number;
+    /** Wall-clock latency of the provider call, milliseconds. */
+    latency_ms: number;
+    /** Provider id that handled the request. */
+    provider: SttProviderId;
+    /** Resolved model id. */
+    model: string;
+}
+export interface TtsRequest {
+    /** Plain text to synthesise. Provider must NOT execute SSML
+     *  unless the caller explicitly opts in via ssml=true. */
+    text: string;
+    /** When true, the provider may interpret SSML tags in `text`. */
+    ssml?: boolean;
+    /** Voice id (provider-specific). */
+    voice?: string;
+    /** BCP-47 language hint. */
+    language?: string;
+    /** Playback speed multiplier. 1.0 = normal. 0.5..2.0 supported
+     *  by every provider in scope. */
+    speed?: number;
+    /** Desired output format. */
+    format?: TtsAudioFormat;
+}
+export interface TtsResponse {
+    /** Raw audio bytes. */
+    audio: Buffer;
+    /** Effective output format. */
+    format: TtsAudioFormat;
+    /** Wall-clock latency, milliseconds. */
+    latency_ms: number;
+    /** Provider id that handled the request. */
+    provider: TtsProviderId;
+    /** Resolved voice id (helpful for the panel to surface what
+     *  Yujin used). */
+    voice: string;
+}
+/** STT provider abstract surface. Implementations live under
+ *  `src/voice/providers/<id>.ts`. */
+export interface SttProvider {
+    readonly id: SttProviderId;
+    /** True when the provider has everything it needs to run
+     *  (vault key present, model accessible, etc). Cheap check;
+     *  the actual provider call is `transcribe`. */
+    readyToRun(): Promise<boolean>;
+    transcribe(req: SttRequest): Promise<SttResponse>;
+}
+/** TTS provider abstract surface. */
+export interface TtsProvider {
+    readonly id: TtsProviderId;
+    readyToRun(): Promise<boolean>;
+    synthesize(req: TtsRequest): Promise<TtsResponse>;
+}
+/** User-facing voice configuration -- persisted at
+ *  ~/.yujin-forge/voice-config.json. */
+export interface VoiceConfig {
+    stt: {
+        provider: SttProviderId;
+        /** Default model id when the call does not override. */
+        model?: string;
+        /** Optional BCP-47 language hint applied to every request. */
+        language?: string;
+    };
+    tts: {
+        provider: TtsProviderId;
+        voice?: string;
+        speed?: number;
+        language?: string;
+        format?: TtsAudioFormat;
+    };
+}
+export declare const DEFAULT_VOICE_CONFIG: VoiceConfig;
+//# sourceMappingURL=types.d.ts.map

package/dist/voice/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/voice/types.ts"],"names":[],"mappings":"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"}

package/dist/voice/types.js

@@ -0,0 +1,22 @@
+/**
+ * Voice subsystem: type surface shared across STT, TTS, providers,
+ * and the router.
+ *
+ * Design principles:
+ *   - Providers are interface-based. The router instantiates a
+ *     concrete provider per request based on the active config +
+ *     credentials from the vault.
+ *   - No credential ever appears in the type surface or on the
+ *     wire from server to browser.
+ *   - Provider IDs are strings, not enums, so adding a new
+ *     provider does not break existing configs that reference
+ *     unknown providers (loud error at resolve time, not at
+ *     parse time).
+ *
+ * ASCII-only.
+ */
+export const DEFAULT_VOICE_CONFIG = {
+    stt: { provider: 'whisper' },
+    tts: { provider: 'google' },
+};
+//# sourceMappingURL=types.js.map

package/dist/voice/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/voice/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAoHH,MAAM,CAAC,MAAM,oBAAoB,GAAgB;IAC/C,GAAG,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE;IAC5B,GAAG,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE;CAC5B,CAAC"}

package/dist/voice/voiceprint/enrollment.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Voiceprint enrollment orchestrator.
+ *
+ * Takes one (or more) audio samples + a provider + a name and
+ * label, extracts the embedding(s), averages them when N > 1
+ * for robustness, and persists the result in the store.
+ *
+ * Re-enrolling with the same name overwrites silently -- the
+ * caller is expected to confirm overwrite at the UI level.
+ *
+ * Loud failures per ROADMAP sec 12.2.
+ *
+ * ASCII-only.
+ */
+import type { EnrolledIdentity, VoiceprintEmbedding, VoiceprintExtractRequest, VoiceprintProvider } from './types.js';
+import { VoiceprintStore } from './store.js';
+export interface EnrollRequest {
+    /** Stable identifier (snake_case). */
+    name: string;
+    /** Human-readable label. */
+    label: string;
+    /** One or more audio samples for the same speaker. When > 1
+     *  the embeddings are averaged + L2-renormalised. */
+    samples: VoiceprintExtractRequest[];
+    /** Optional free-form notes for the audit trail. */
+    notes?: string;
+}
+export interface EnrollResult {
+    /** The persisted identity. */
+    identity: EnrolledIdentity;
+    /** Per-sample embeddings (for debugging + tests; not
+     *  stored on disk). */
+    sampleEmbeddings: VoiceprintEmbedding[];
+}
+export declare function enroll(req: EnrollRequest, provider: VoiceprintProvider, store: VoiceprintStore): Promise<EnrollResult>;
+//# sourceMappingURL=enrollment.d.ts.map

package/dist/voice/voiceprint/enrollment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enrollment.d.ts","sourceRoot":"","sources":["../../../src/voice/voiceprint/enrollment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,mBAAmB,EACnB,wBAAwB,EACxB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,WAAW,aAAa;IAC5B,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd;yDACqD;IACrD,OAAO,EAAE,wBAAwB,EAAE,CAAC;IACpC,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,8BAA8B;IAC9B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B;2BACuB;IACvB,gBAAgB,EAAE,mBAAmB,EAAE,CAAC;CACzC;AAED,wBAAsB,MAAM,CAC1B,GAAG,EAAE,aAAa,EAClB,QAAQ,EAAE,kBAAkB,EAC5B,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,YAAY,CAAC,CA+DvB"}

package/dist/voice/voiceprint/enrollment.js

@@ -0,0 +1,71 @@
+/**
+ * Voiceprint enrollment orchestrator.
+ *
+ * Takes one (or more) audio samples + a provider + a name and
+ * label, extracts the embedding(s), averages them when N > 1
+ * for robustness, and persists the result in the store.
+ *
+ * Re-enrolling with the same name overwrites silently -- the
+ * caller is expected to confirm overwrite at the UI level.
+ *
+ * Loud failures per ROADMAP sec 12.2.
+ *
+ * ASCII-only.
+ */
+export async function enroll(req, provider, store) {
+    if (!req.samples || req.samples.length === 0) {
+        throw new Error('enroll: at least one audio sample required');
+    }
+    if (!(await provider.readyToRun())) {
+        throw new Error('enroll: voiceprint provider "' + provider.id + '" is not ready. '
+            + 'Configure its credentials in the vault before enrolling.');
+    }
+    /* Extract one embedding per sample. */
+    const embeddings = [];
+    for (const sample of req.samples) {
+        const emb = await provider.extract(sample);
+        if (emb.length !== provider.embeddingSize) {
+            throw new Error('enroll: provider "' + provider.id + '" returned ' + emb.length
+                + '-dim embedding, expected ' + provider.embeddingSize);
+        }
+        embeddings.push(emb);
+    }
+    /* Average + L2-renormalise. With N=1 this is a no-op. */
+    const dim = embeddings[0].vector.length;
+    const avg = new Array(dim).fill(0);
+    for (const emb of embeddings) {
+        const vec = emb.vector;
+        for (let i = 0; i < dim; i++) {
+            const cur = avg[i] ?? 0;
+            const add = vec[i] ?? 0;
+            avg[i] = cur + add;
+        }
+    }
+    for (let i = 0; i < dim; i++) {
+        avg[i] = (avg[i] ?? 0) / embeddings.length;
+    }
+    let norm = 0;
+    for (const v of avg)
+        norm += (v ?? 0) * (v ?? 0);
+    norm = Math.sqrt(norm);
+    if (norm > 0) {
+        for (let i = 0; i < dim; i++) {
+            avg[i] = (avg[i] ?? 0) / norm;
+        }
+    }
+    const consolidated = {
+        vector: avg,
+        length: dim,
+        source: provider.id,
+        enrolled_at: new Date().toISOString(),
+    };
+    const identity = {
+        name: req.name,
+        label: req.label,
+        embedding: consolidated,
+        ...(req.notes ? { notes: req.notes } : {}),
+    };
+    await store.set(identity);
+    return { identity, sampleEmbeddings: embeddings };
+}
+//# sourceMappingURL=enrollment.js.map

package/dist/voice/voiceprint/enrollment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enrollment.js","sourceRoot":"","sources":["../../../src/voice/voiceprint/enrollment.ts"],"names":[],"mappings":"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"}

package/dist/voice/voiceprint/identify.d.ts

@@ -0,0 +1,16 @@
+/**
+ * High-level identify(): extract an embedding from a fresh audio
+ * sample + match against the enrolled set.
+ *
+ * One call from the trust layer (V1.9). Decouples the consumer
+ * from the provider + store + matcher individually.
+ *
+ * ASCII-only.
+ */
+import type { VoiceprintExtractRequest, VoiceprintProvider } from './types.js';
+import { VoiceprintStore } from './store.js';
+import { type MatchOptions, type MatchOutput } from './match.js';
+export interface IdentifyRequest extends VoiceprintExtractRequest {
+}
+export declare function identify(req: IdentifyRequest, provider: VoiceprintProvider, store: VoiceprintStore, opts?: MatchOptions): Promise<MatchOutput>;
+//# sourceMappingURL=identify.d.ts.map

package/dist/voice/voiceprint/identify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identify.d.ts","sourceRoot":"","sources":["../../../src/voice/voiceprint/identify.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,wBAAwB,EACxB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAkB,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAEjF,MAAM,WAAW,eAAgB,SAAQ,wBAAwB;CAAG;AAEpE,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,eAAe,EACpB,QAAQ,EAAE,kBAAkB,EAC5B,KAAK,EAAE,eAAe,EACtB,IAAI,GAAE,YAAiB,GACtB,OAAO,CAAC,WAAW,CAAC,CAUtB"}

package/dist/voice/voiceprint/identify.js

@@ -0,0 +1,20 @@
+/**
+ * High-level identify(): extract an embedding from a fresh audio
+ * sample + match against the enrolled set.
+ *
+ * One call from the trust layer (V1.9). Decouples the consumer
+ * from the provider + store + matcher individually.
+ *
+ * ASCII-only.
+ */
+import { matchEmbedding } from './match.js';
+export async function identify(req, provider, store, opts = {}) {
+    if (!(await provider.readyToRun())) {
+        throw new Error('identify: voiceprint provider "' + provider.id + '" is not ready. '
+            + 'Configure credentials in the vault before running identify.');
+    }
+    const target = await provider.extract(req);
+    const enrolled = store.all();
+    return matchEmbedding(target, enrolled, opts);
+}
+//# sourceMappingURL=identify.js.map

package/dist/voice/voiceprint/identify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identify.js","sourceRoot":"","sources":["../../../src/voice/voiceprint/identify.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,EAAE,cAAc,EAAuC,MAAM,YAAY,CAAC;AAIjF,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,GAAoB,EACpB,QAA4B,EAC5B,KAAsB,EACtB,OAAqB,EAAE;IAEvB,IAAI,CAAC,CAAC,MAAM,QAAQ,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CACb,iCAAiC,GAAG,QAAQ,CAAC,EAAE,GAAG,kBAAkB;cAClE,6DAA6D,CAChE,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC3C,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC;IAC7B,OAAO,cAAc,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;AAChD,CAAC"}

package/dist/voice/voiceprint/liveness.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Liveness check.
+ *
+ * Before an irreversible operation (npm publish, force push,
+ * delete) the chat dispatcher runs a liveness challenge:
+ *
+ *   1. generateChallenge() picks a fixed phrase + a random
+ *      two-digit number. Returns the prompt text + the
+ *      expected transcript.
+ *   2. The panel TTS speaks the prompt; the user repeats it.
+ *   3. verifyChallenge() runs STT on the user's audio + does
+ *      a fuzzy match against the expected text. It also
+ *      re-runs identify to make sure the same speaker who
+ *      owned the session is still on the mic.
+ *
+ * The fuzzy match tolerates pronunciation variants + STT
+ * errors. The number-in-words component defeats trivial
+ * replay attacks: the attacker would need a recording of the
+ * user pronouncing exactly that random number.
+ *
+ * Spanish-first vocabulary; English fallback under
+ * `language: 'en'`. Adopters with other languages add a
+ * dictionary in the future.
+ *
+ * Pure -- no IO, no audio decoding. The STT + voiceprint
+ * providers are dependencies, not embedded.
+ *
+ * ASCII-only.
+ */
+import type { SttProvider, SttRequest } from '../types.js';
+import type { VoiceprintProvider } from './types.js';
+import { VoiceprintStore } from './store.js';
+export type LivenessLanguage = 'es' | 'en';
+export declare function numberToWords(n: number, lang: LivenessLanguage): string;
+export interface LivenessChallenge {
+    /** The text the panel speaks via TTS + shows on screen. */
+    prompt: string;
+    /** The exact phrase the user is expected to repeat. */
+    expected: string;
+    /** Language of the challenge. */
+    language: LivenessLanguage;
+    /** Random number used in the challenge, 10-99. */
+    number: number;
+}
+export interface LivenessOptions {
+    language?: LivenessLanguage;
+    /** Random generator for tests. Defaults to Math.random. */
+    random?: () => number;
+}
+export declare function generateChallenge(opts?: LivenessOptions): LivenessChallenge;
+/** Levenshtein distance between two strings. O(m*n) DP --
+ *  fine for the short phrases the liveness check works with. */
+export declare function levenshtein(a: string, b: string): number;
+/** Normalise a string for fuzzy comparison: lowercase, strip
+ *  punctuation, collapse whitespace. Helps STT variants
+ *  ("treinta y siete" vs "treintaisiete"). */
+export declare function normalisePhrase(s: string): string;
+/** Fuzzy match: returns true when normalised Levenshtein
+ *  distance / longer-length ratio is below 0.3 (i.e. ~70%
+ *  similarity). Tolerates STT misses + accent variants. */
+export declare function phraseMatches(transcript: string, expected: string): boolean;
+export interface VerifyChallengeRequest {
+    /** Audio bytes the user spoke in response to the challenge. */
+    audio: Buffer;
+    /** Audio format. */
+    format: SttRequest['format'];
+    /** The challenge issued by generateChallenge. */
+    challenge: LivenessChallenge;
+    /** Identity that owned the session before the challenge.
+     *  When the post-challenge identify returns a different
+     *  name, the check fails even if the phrase matched. */
+    activeIdentity: string | null;
+}
+export interface VerifyChallengeResult {
+    /** True iff both the phrase + the speaker check passed. */
+    passed: boolean;
+    /** What the STT heard. */
+    transcript: string;
+    /** True iff phrase fuzzy-matched. */
+    phrase_match: boolean;
+    /** True iff identify confirmed the active speaker.
+     *  Always true when activeIdentity is null (no enrolled
+     *  user) -- in that case the check downgrades to phrase
+     *  only, with a flag in the reason. */
+    identity_match: boolean;
+    /** Voice-readable reason for the dispatcher to surface. */
+    reason: string;
+}
+export declare function verifyChallenge(req: VerifyChallengeRequest, sttProvider: SttProvider, voiceprintProvider: VoiceprintProvider, voiceprintStore: VoiceprintStore): Promise<VerifyChallengeResult>;
+//# sourceMappingURL=liveness.d.ts.map

package/dist/voice/voiceprint/liveness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"liveness.d.ts","sourceRoot":"","sources":["../../../src/voice/voiceprint/liveness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EAAE,kBAAkB,EAA4B,MAAM,YAAY,CAAC;AAC/E,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAG7C,MAAM,MAAM,gBAAgB,GAAG,IAAI,GAAG,IAAI,CAAC;AAgD3C,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAiBvE;AAED,MAAM,WAAW,iBAAiB;IAChC,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;CACvB;AAED,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,eAAoB,GAAG,iBAAiB,CAe/E;AAED;gEACgE;AAChE,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAsBxD;AAED;;8CAE8C;AAC9C,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAQjD;AAED;;2DAE2D;AAC3D,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAQ3E;AAED,MAAM,WAAW,sBAAsB;IACrC,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd,oBAAoB;IACpB,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC7B,iDAAiD;IACjD,SAAS,EAAE,iBAAiB,CAAC;IAC7B;;4DAEwD;IACxD,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,2DAA2D;IAC3D,MAAM,EAAE,OAAO,CAAC;IAChB,0BAA0B;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,YAAY,EAAE,OAAO,CAAC;IACtB;;;2CAGuC;IACvC,cAAc,EAAE,OAAO,CAAC;IACxB,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,eAAe,CACnC,GAAG,EAAE,sBAAsB,EAC3B,WAAW,EAAE,WAAW,EACxB,kBAAkB,EAAE,kBAAkB,EACtC,eAAe,EAAE,eAAe,GAC/B,OAAO,CAAC,qBAAqB,CAAC,CA2FhC"}

package/dist/voice/voiceprint/liveness.js

@@ -0,0 +1,251 @@
+/**
+ * Liveness check.
+ *
+ * Before an irreversible operation (npm publish, force push,
+ * delete) the chat dispatcher runs a liveness challenge:
+ *
+ *   1. generateChallenge() picks a fixed phrase + a random
+ *      two-digit number. Returns the prompt text + the
+ *      expected transcript.
+ *   2. The panel TTS speaks the prompt; the user repeats it.
+ *   3. verifyChallenge() runs STT on the user's audio + does
+ *      a fuzzy match against the expected text. It also
+ *      re-runs identify to make sure the same speaker who
+ *      owned the session is still on the mic.
+ *
+ * The fuzzy match tolerates pronunciation variants + STT
+ * errors. The number-in-words component defeats trivial
+ * replay attacks: the attacker would need a recording of the
+ * user pronouncing exactly that random number.
+ *
+ * Spanish-first vocabulary; English fallback under
+ * `language: 'en'`. Adopters with other languages add a
+ * dictionary in the future.
+ *
+ * Pure -- no IO, no audio decoding. The STT + voiceprint
+ * providers are dependencies, not embedded.
+ *
+ * ASCII-only.
+ */
+import { identify } from './identify.js';
+const PHRASES_ES = [
+    'Confirmo la operacion',
+    'Adelante con esto',
+    'Soy yo y autorizo',
+    'Por favor procede',
+    'Es correcto',
+    'Doy mi consentimiento',
+    'Estoy seguro',
+    'Sigamos adelante',
+];
+const PHRASES_EN = [
+    'I confirm the operation',
+    'Go ahead with this',
+    'It is me and I authorise',
+    'Please proceed',
+    'This is correct',
+    'I give my consent',
+    'I am sure',
+    'Let us continue',
+];
+/* "treinta y siete" / "thirty seven" -- numbers 10-99 inclusive. */
+const NUMBER_WORDS_ES_ONES = [
+    'cero', 'uno', 'dos', 'tres', 'cuatro', 'cinco', 'seis', 'siete', 'ocho', 'nueve',
+];
+const NUMBER_WORDS_ES_TEENS = [
+    'diez', 'once', 'doce', 'trece', 'catorce', 'quince',
+    'dieciseis', 'diecisiete', 'dieciocho', 'diecinueve',
+];
+const NUMBER_WORDS_ES_TENS = [
+    '', '', 'veinte', 'treinta', 'cuarenta', 'cincuenta',
+    'sesenta', 'setenta', 'ochenta', 'noventa',
+];
+const NUMBER_WORDS_EN_ONES = [
+    'zero', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine',
+];
+const NUMBER_WORDS_EN_TEENS = [
+    'ten', 'eleven', 'twelve', 'thirteen', 'fourteen', 'fifteen',
+    'sixteen', 'seventeen', 'eighteen', 'nineteen',
+];
+const NUMBER_WORDS_EN_TENS = [
+    '', '', 'twenty', 'thirty', 'forty', 'fifty',
+    'sixty', 'seventy', 'eighty', 'ninety',
+];
+export function numberToWords(n, lang) {
+    if (n < 0 || n > 99 || !Number.isInteger(n)) {
+        throw new Error('numberToWords: out of range 0..99: ' + n);
+    }
+    if (lang === 'es') {
+        if (n < 10)
+            return NUMBER_WORDS_ES_ONES[n];
+        if (n < 20)
+            return NUMBER_WORDS_ES_TEENS[n - 10];
+        if (n < 30)
+            return n === 20 ? 'veinte' : 'veinti' + NUMBER_WORDS_ES_ONES[n - 20];
+        const tens = NUMBER_WORDS_ES_TENS[Math.floor(n / 10)];
+        const ones = n % 10;
+        return ones === 0 ? tens : tens + ' y ' + NUMBER_WORDS_ES_ONES[ones];
+    }
+    if (n < 10)
+        return NUMBER_WORDS_EN_ONES[n];
+    if (n < 20)
+        return NUMBER_WORDS_EN_TEENS[n - 10];
+    const tens = NUMBER_WORDS_EN_TENS[Math.floor(n / 10)];
+    const ones = n % 10;
+    return ones === 0 ? tens : tens + ' ' + NUMBER_WORDS_EN_ONES[ones];
+}
+export function generateChallenge(opts = {}) {
+    const lang = opts.language ?? 'es';
+    const rng = opts.random ?? Math.random;
+    const phrases = lang === 'es' ? PHRASES_ES : PHRASES_EN;
+    const phrase = phrases[Math.floor(rng() * phrases.length)];
+    /* Pick a number 10-99 inclusive so it always has tens-place. */
+    const n = 10 + Math.floor(rng() * 90);
+    const numberWord = numberToWords(n, lang);
+    const expected = lang === 'es'
+        ? phrase + ', el numero es ' + numberWord
+        : phrase + ', the number is ' + numberWord;
+    const prompt = lang === 'es'
+        ? 'Para confirmar, repeti: ' + expected
+        : 'To confirm, repeat: ' + expected;
+    return { prompt, expected, language: lang, number: n };
+}
+/** Levenshtein distance between two strings. O(m*n) DP --
+ *  fine for the short phrases the liveness check works with. */
+export function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    const m = a.length;
+    const n = b.length;
+    let prev = new Array(n + 1);
+    let cur = new Array(n + 1);
+    for (let j = 0; j <= n; j++)
+        prev[j] = j;
+    for (let i = 1; i <= m; i++) {
+        cur[0] = i;
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            cur[j] = Math.min(cur[j - 1] + 1, /* insert */ prev[j] + 1, /* delete */ prev[j - 1] + cost);
+        }
+        [prev, cur] = [cur, prev];
+    }
+    return prev[n];
+}
+/** Normalise a string for fuzzy comparison: lowercase, strip
+ *  punctuation, collapse whitespace. Helps STT variants
+ *  ("treinta y siete" vs "treintaisiete"). */
+export function normalisePhrase(s) {
+    return s
+        .toLowerCase()
+        .normalize('NFD')
+        .replace(/[̀-ͯ]/g, '') /* strip accents */
+        .replace(/[^a-z0-9\s]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/** Fuzzy match: returns true when normalised Levenshtein
+ *  distance / longer-length ratio is below 0.3 (i.e. ~70%
+ *  similarity). Tolerates STT misses + accent variants. */
+export function phraseMatches(transcript, expected) {
+    const a = normalisePhrase(transcript);
+    const b = normalisePhrase(expected);
+    if (a === b)
+        return true;
+    if (a.length === 0 || b.length === 0)
+        return false;
+    const dist = levenshtein(a, b);
+    const longer = Math.max(a.length, b.length);
+    return (dist / longer) <= 0.3;
+}
+export async function verifyChallenge(req, sttProvider, voiceprintProvider, voiceprintStore) {
+    if (!req.audio || req.audio.length === 0) {
+        return {
+            passed: false,
+            transcript: '',
+            phrase_match: false,
+            identity_match: false,
+            reason: 'no audio received -- repeat the prompt',
+        };
+    }
+    /* 1. STT. */
+    let transcript = '';
+    try {
+        const r = await sttProvider.transcribe({
+            audio: req.audio,
+            format: req.format,
+            languageHint: req.challenge.language === 'es' ? 'es-AR' : 'en-US',
+        });
+        transcript = r.text;
+    }
+    catch (err) {
+        return {
+            passed: false,
+            transcript: '',
+            phrase_match: false,
+            identity_match: false,
+            reason: 'could not transcribe the audio: '
+                + (err instanceof Error ? err.message : String(err)),
+        };
+    }
+    const phraseOk = phraseMatches(transcript, req.challenge.expected);
+    /* 2. Voiceprint check. Skip when there is no active
+          identity -- this is an unenrolled user. */
+    let identityOk = true;
+    if (req.activeIdentity !== null) {
+        try {
+            const matchResult = await identify({ audio: req.audio, format: req.format }, voiceprintProvider, voiceprintStore);
+            identityOk = matchResult.matched === req.activeIdentity;
+        }
+        catch (err) {
+            return {
+                passed: false,
+                transcript,
+                phrase_match: phraseOk,
+                identity_match: false,
+                reason: 'could not run identity check: '
+                    + (err instanceof Error ? err.message : String(err)),
+            };
+        }
+    }
+    if (!phraseOk && !identityOk) {
+        return {
+            passed: false,
+            transcript,
+            phrase_match: false,
+            identity_match: false,
+            reason: 'phrase did not match AND speaker did not match -- try again',
+        };
+    }
+    if (!phraseOk) {
+        return {
+            passed: false,
+            transcript,
+            phrase_match: false,
+            identity_match: identityOk,
+            reason: 'phrase did not match -- repeat exactly: ' + req.challenge.expected,
+        };
+    }
+    if (!identityOk) {
+        return {
+            passed: false,
+            transcript,
+            phrase_match: true,
+            identity_match: false,
+            reason: 'phrase ok but speaker did not match the active session identity',
+        };
+    }
+    return {
+        passed: true,
+        transcript,
+        phrase_match: true,
+        identity_match: true,
+        reason: req.activeIdentity
+            ? 'liveness check passed -- phrase + speaker confirmed'
+            : 'liveness check passed -- phrase confirmed (no enrolled identity to cross-check)',
+    };
+}
+//# sourceMappingURL=liveness.js.map