ldrouter 1.6.7 → 1.10.0

package/CHANGELOG.md

@@ -4,6 +4,66 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/) and the project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [1.10.0] - 2026-09-01
+
+### Added
+
+- **Real streaming model test**: clicking Test on a model now streams the upstream response token-by-token into the test dialog (`POST /api/admin/models/:id/test-stream` SSE endpoint, newline-delimited). Previously the dialog waited ~1s with no feedback before showing a static result; now content appears live as the model generates, with a blinking cursor, live TTFT/elapsed counter, and a final `test_meta` event with full latency/token/attempt stats. The old non-streaming `POST .../test` endpoint remains for backwards compatibility.
+
+### Fixed
+
+- **Test dialog no loading state**: the model test modal previously opened instantly but showed nothing for the ~1s the request took, looking like a hang. It now shows an immediate streaming view with progress as soon as the modal opens.
+
+## [1.9.1] - 2026-09-01
+
+### Fixed
+
+- **Request-content logging now visible**: Settings → Logging "Request-content logging" was saving payloads to the database (`prompt` / `prompt_and_response` modes) but the admin UI never displayed them, making the setting appear broken. The request detail dialog on `/requests` now shows "Request content" and "Response content" sections (sanitized, scrollable) whenever payloads were logged. Added integration test covering all four `contentLogMode` values end-to-end.
+
+## [1.9.0] - 2026-09-01
+
+### Added
+
+- **Realtime monitoring dashboard (/statistics)**: redesigned into a production-grade overview — summary cards now show icons, animated count-up, % delta vs previous period, and mini sparklines; a live **request routing flow** diagram (Incoming Traffic → AI Gateway → Providers with curved paths and animated pulse dots on each active route); a **Recent Requests** table with green/red status dots and time-ago labels; bottom metrics with circular Success Rate progress and Average Latency sparkline. All driven by the existing SSE stream (no new dependencies, CSS/SVG-native animations).
+- **Stats API extensions**: `GET /api/admin/stats` now returns `previous` (same-window comparison for deltas), `recent` (last 10 requests with provider info), `providers` (traffic/error-rate/latency/health per provider), and per-bucket `avgLatency`/`cacheRead` in `series`; `RequestLogSummary` gained `providerId`/`providerName`.
+
+
+
+### Added
+
+- **Notification toggles in Settings**: request notification cards and the notification sound can each be turned on/off in Settings → System ("Notifications" card); preferences persist server-side (`app_settings`) and apply immediately across the whole admin UI.
+- **Real-time /requests page**: the Requests log now subscribes to the SSE stream — new requests appear in the table live (page 1, honoring active filters) plus a "N new requests — refresh" badge, no manual page refresh needed.
+
+### Fixed
+
+- **Setup redirect (permanent fix)**: after creating the admin account the app now hard-reloads to `/login` instead of soft-navigating. Root cause: `SetupGate` cached `setupComplete=false` on mount and re-bounced every post-setup route back to `/setup`; a full reload clears the stale state.
+
+## [1.7.0] - 2026-08-31
+
+### Added
+
+- **Real-time request notifications**: every gateway request completion shows a notification card in the admin UI (stacked, all visible simultaneously). Cards show model/request, in/out tokens, cache tokens, success/failure, duration + TTFT; auto-dismiss after 5s with manual close button; red on failure, amber when slow (>15s), default surface otherwise. Plays `notification.mp3` per notification.
+- **SSE stream endpoint** (`GET /api/admin/requests/stream`): server-push of request log rows behind admin auth, with `since`-based history replay so clients never miss events across reconnects.
+
+## [1.6.8] - 2026-08-31
+
+### Added
+
+- **Model test endpoint** (`POST /api/admin/models/:id/test`): Run a non-streaming request against a model with prompt "Bạn là model gì?", returns TTFT, total latency, token usage, and provider attempts.
+- **Model delete action**: Replace enable/disable toggle with explicit Delete button + confirmation modal and Test button showing results.
+- **Combo edit functionality**: New edit dialog (via `/api/admin/combos/:id`) and PATCH handler for modifying combo metadata/members.
+- **Searchable member picker**: Dropdown in create/edit combo dialogs now filters models by public ID or display name.
+- **API key actions**: Split Revoke into Disable/Enable toggle + Delete button; persist secret visibility for each key row.
+- **Dynamic sidebar version**: Footer displays real app version fetched from server instead of hardcoded `v0.1.0`.
+
+### Fixed
+
+- **TOTP speakeasy v2 compatibility**: Fixed API migration — removed deprecated `authenticator` namespace, replaced with direct v2 exports (`generateSecret`, `totp.verify({encoding:'base32'})`, `otpauthURL`). Eliminates "Gateway error" when enabling TOTP. Also fixed login flow verification to use same pattern.
+
+### Changed
+
+- **Language**: UI labels updated to Vietnamese where appropriate ("Xoá", "Sửa").
+
 ## [1.6.7] - 2026-08-30
 
 ### Fixed

package/dist/server/db/migrate.js

@@ -87,6 +87,8 @@ function buildInitialSchemaSql() {
       gateway_cache_max_size_mb INTEGER NOT NULL DEFAULT 256,
       master_key_version INTEGER NOT NULL DEFAULT 1,
       master_key_configured INTEGER NOT NULL DEFAULT 0,
+      notifications_enabled INTEGER NOT NULL DEFAULT 1,
+      notification_sound_enabled INTEGER NOT NULL DEFAULT 1,
       updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
     );
 

package/dist/server/db/repositories/settings.js

@@ -17,6 +17,8 @@ function rowToSettings(row) {
         gatewayCacheMaxSizeMb: row.gatewayCacheMaxSizeMb,
         masterKeyConfigured: row.masterKeyConfigured,
         masterKeyVersion: row.masterKeyVersion,
+        notificationsEnabled: row.notificationsEnabled,
+        notificationSoundEnabled: row.notificationSoundEnabled,
     };
 }
 export function getSettings() {
@@ -55,6 +57,10 @@ export function updateSettings(patch) {
         update.gatewayCacheMaxSizeMb = patch.gatewayCacheMaxSizeMb;
     if (patch.masterKeyConfigured !== undefined)
         update.masterKeyConfigured = patch.masterKeyConfigured;
+    if (patch.notificationsEnabled !== undefined)
+        update.notificationsEnabled = patch.notificationsEnabled;
+    if (patch.notificationSoundEnabled !== undefined)
+        update.notificationSoundEnabled = patch.notificationSoundEnabled;
     db.update(schema.appSettings).set(update).where(eq(schema.appSettings.id, 1)).run();
     return getSettings();
 }

package/dist/server/db/schema.js

@@ -19,6 +19,9 @@ export const appSettings = sqliteTable('app_settings', {
     gatewayCacheMaxSizeMb: integer('gateway_cache_max_size_mb').notNull().default(256),
     masterKeyVersion: integer('master_key_version').notNull().default(1),
     masterKeyConfigured: integer('master_key_configured', { mode: 'boolean' }).notNull().notNull().default(false),
+    // Admin UI notification preferences (v1.8.0). Default true: notifications on, sound on.
+    notificationsEnabled: integer('notifications_enabled', { mode: 'boolean' }).notNull().default(true),
+    notificationSoundEnabled: integer('notification_sound_enabled', { mode: 'boolean' }).notNull().default(true),
     updatedAt: text('updated_at').notNull().default(sql `(strftime('%Y-%m-%dT%H:%M:%fZ','now'))`),
 });
 // ============================================================================

package/dist/server/gateway/events.js

@@ -0,0 +1,20 @@
+// Internal event bus: notifies subscribers when a gateway request row is persisted.
+// Fire-and-forget: listeners must never affect the request path.
+import { EventEmitter } from 'node:events';
+const bus = new EventEmitter();
+bus.setMaxListeners(50);
+const REQUEST_LOGGED = 'request_logged';
+export function emitRequestLogged(requestId) {
+    try {
+        bus.emit(REQUEST_LOGGED, requestId);
+    }
+    catch {
+        // Never let listener failures affect the request path.
+    }
+}
+export function onRequestLogged(cb) {
+    bus.on(REQUEST_LOGGED, cb);
+}
+export function offRequestLogged(cb) {
+    bus.off(REQUEST_LOGGED, cb);
+}

package/dist/server/gateway/runner.js

@@ -17,6 +17,7 @@ import { redactString, redactValue } from '../security/redact.js';
 import { getSettings } from '../db/repositories/settings.js';
 import { buildCacheKey, lookupCache, storeCache, cacheAllowed } from '../caching/store.js';
 import { metrics } from '../metrics/registry.js';
+import { emitRequestLogged } from './events.js';
 export class GatewayRunner {
     async execute(req, ctx) {
         const start = Date.now();
@@ -683,6 +684,7 @@ export class GatewayRunner {
                 upstreamRequestId: a.upstreamRequestId,
             }).run();
         }
+        emitRequestLogged(requestId);
     }
 }
 function classifyFailure(err) {

package/dist/server/routes/admin/auth.js

@@ -109,16 +109,20 @@ export async function registerAuthRoutes(app) {
 async function verifyTotp(account, code) {
     if (!account.totpSecretEncrypted || !account.totpSecretNonce)
         return false;
-    // Lazy-load to avoid breaking things if crypto module not yet ready
+    // speakeasy v2 exports at top level (no `authenticator` namespace). Normalize once here.
     const { decryptSecret } = await import('../../auth/crypto.js');
-    const speakeasy = await import('speakeasy');
-    const payload = { ciphertext: account.totpSecretEncrypted, nonce: account.totpSecretNonce, version: 1 };
+    const sp = await loadSpeakeasy();
     try {
-        const secret = decryptSecret({ ciphertext: payload.ciphertext, nonce: payload.nonce, version: 1 });
-        return speakeasy.authenticator.verify({ token: code, secret, window: 1 });
+        const secret = decryptSecret({ ciphertext: account.totpSecretEncrypted, nonce: account.totpSecretNonce, version: 1 });
+        return sp.totp.verify({ token: code, secret, encoding: 'base32', window: 1 });
     }
     catch {
         return false;
     }
 }
+// Same helper as settings.ts to normalize speakeasy v2 imports
+async function loadSpeakeasy() {
+    const m = await import('speakeasy');
+    return m.default ?? m;
+}
 import { sql } from 'drizzle-orm';

package/dist/server/routes/admin/models.js

@@ -167,6 +167,151 @@ export async function registerModelRoutes(app) {
         recordAudit({ action: 'model.delete', success: true, targetType: 'model', targetId: id, targetName: m.publicModelId, ip: req.ip });
         return { ok: true };
     });
+    // Streaming test endpoint: streams SSE tokens to the client in real time.
+    app.post('/api/admin/models/:id/test-stream', async (req, reply) => {
+        const { id } = req.params;
+        const db = getDb();
+        const m = db.select().from(schema.models).where(eq(schema.models.id, id)).get();
+        if (!m)
+            throw new GatewayError('invalid_request_error', 'Model not found', { status: 404 });
+        if (!m.enabled)
+            throw new GatewayError('invalid_request_error', 'Model is disabled', { status: 400 });
+        if (!m.upstreamAvailable)
+            throw new GatewayError('invalid_request_error', 'Model is not available upstream', { status: 400 });
+        const provider = db.select().from(schema.providers).where(eq(schema.providers.id, m.providerId)).get();
+        if (!provider || !provider.enabled)
+            throw new GatewayError('invalid_request_error', 'Provider is disabled', { status: 400 });
+        // Hijack reply so runner streams SSE directly to the client.
+        reply.hijack();
+        const res = reply.raw;
+        const SSE_HEADERS = {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            Connection: 'keep-alive',
+        };
+        let headWritten = false;
+        const writeHeadOnce = () => {
+            if (headWritten)
+                return;
+            headWritten = true;
+            res.writeHead(200, SSE_HEADERS);
+        };
+        const send = (event, data) => {
+            writeHeadOnce();
+            res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+        };
+        // The runner calls reply.raw.end() as soon as the upstream completes.
+        // Defer that so we can append our own test_meta event before the
+        // real end(). Writes are forwarded live, so tokens still stream.
+        const fakeRaw = {
+            writeHead: () => writeHeadOnce(),
+            write: (chunk) => res.write(chunk),
+            end: () => { },
+        };
+        const { GatewayRunner } = await import('../../gateway/runner.js');
+        const runner = new GatewayRunner();
+        const canonicalReq = {
+            model: m.publicModelId,
+            messages: [{ role: 'user', content: [{ type: 'text', text: 'Bạn là model gì?' }] }],
+            stream: true,
+            maxOutputTokens: 256,
+            temperature: 0.7,
+        };
+        const requestId = `test-${uuid()}`;
+        const ctx = {
+            requestId,
+            clientIp: req.ip,
+            protocol: 'openai',
+            endpoint: 'chat/completions',
+            requestedModel: m.publicModelId,
+            key: null,
+            reply: { raw: fakeRaw },
+        };
+        const gatewayReq = {
+            canonical: canonicalReq,
+            protocol: 'openai',
+            endpoint: 'chat/completions',
+        };
+        try {
+            const outcome = await runner.execute(gatewayReq, ctx);
+            // Runner already wrote [DONE]. Append our own test_meta event so the
+            // client knows the test finished with full stats.
+            send('test_meta', {
+                success: outcome.success,
+                latencyMs: outcome.latencyMs,
+                ttftMs: outcome.ttftMs ?? null,
+                usage: outcome.usage,
+                attempts: outcome.attempts.map((a) => ({
+                    providerName: a.providerName,
+                    modelId: a.modelId,
+                    latencyMs: a.latencyMs,
+                    success: a.success,
+                    failureReason: a.failureReason,
+                })),
+            });
+        }
+        catch (e) {
+            send('test_error', { message: e.message });
+        }
+        finally {
+            res.end();
+        }
+    });
+    // Non-streaming test endpoint (kept for backwards compatibility)
+    app.post('/api/admin/models/:id/test', async (req) => {
+        const { id } = req.params;
+        const db = getDb();
+        const m = db.select().from(schema.models).where(eq(schema.models.id, id)).get();
+        if (!m)
+            throw new GatewayError('invalid_request_error', 'Model not found', { status: 404 });
+        if (!m.enabled)
+            throw new GatewayError('invalid_request_error', 'Model is disabled', { status: 400 });
+        if (!m.upstreamAvailable)
+            throw new GatewayError('invalid_request_error', 'Model is not available upstream', { status: 400 });
+        const provider = db.select().from(schema.providers).where(eq(schema.providers.id, m.providerId)).get();
+        if (!provider || !provider.enabled)
+            throw new GatewayError('invalid_request_error', 'Provider is disabled', { status: 400 });
+        const { GatewayRunner } = await import('../../gateway/runner.js');
+        const runner = new GatewayRunner();
+        const canonicalReq = {
+            model: m.publicModelId,
+            messages: [{ role: 'user', content: [{ type: 'text', text: 'Bạn là model gì?' }] }],
+            stream: false,
+            maxOutputTokens: 256,
+            temperature: 0.7,
+        };
+        const ctx = {
+            requestId: `test-${uuid()}`,
+            clientIp: req.ip,
+            protocol: 'openai',
+            endpoint: 'chat/completions',
+            requestedModel: m.publicModelId,
+            key: null,
+            reply: { raw: {} }, // Fake reply object; non-streaming won't use it
+        };
+        const gatewayReq = {
+            canonical: canonicalReq,
+            protocol: 'openai',
+            endpoint: 'chat/completions',
+        };
+        const outcome = await runner.execute(gatewayReq, ctx);
+        recordAudit({ action: 'model.test', success: outcome.success, targetType: 'model', targetId: id, targetName: m.publicModelId, ip: req.ip });
+        return {
+            success: outcome.success,
+            text: outcome.text ?? '',
+            latencyMs: outcome.latencyMs,
+            ttftMs: outcome.ttftMs ?? null,
+            usage: outcome.usage,
+            attempts: outcome.attempts.map((a) => ({
+                providerName: a.providerName,
+                modelId: a.modelId,
+                latencyMs: a.latencyMs,
+                ttftMs: a.ttftMs,
+                success: a.success,
+                failureReason: a.failureReason,
+            })),
+        };
+    });
 }
 function safeJson(s) {
     try {

package/dist/server/routes/admin/requests.js

@@ -3,6 +3,55 @@ import { and, desc, eq, gte, like, lte, sql } from 'drizzle-orm';
 import { getDb, schema } from '../../db/index.js';
 import { requireAdminAuth } from '../../auth/middleware.js';
 import { redactJsonString } from '../../security/redact.js';
+import { onRequestLogged, offRequestLogged } from '../../gateway/events.js';
+export function loadSummaryMaps() {
+    const db = getDb();
+    const keys = db.select().from(schema.apiKeys).all();
+    const models = db.select().from(schema.models).all();
+    const providers = db.select().from(schema.providers).all();
+    return {
+        keyMap: new Map(keys.map((k) => [k.id, k])),
+        modelMap: new Map(models.map((m) => [m.id, m])),
+        providerMap: new Map(providers.map((p) => [p.id, p])),
+    };
+}
+// Shared row → API summary mapping (used by the list endpoint, the SSE stream, and stats).
+export function toSummary(r, maps) {
+    const { keyMap, modelMap, providerMap } = maps;
+    const key = r.apiKeyId ? keyMap.get(r.apiKeyId) : null;
+    const finalModel = r.finalModelId ? modelMap.get(r.finalModelId) : null;
+    const provider = finalModel?.providerId ? providerMap.get(finalModel.providerId) : null;
+    return {
+        id: r.id,
+        createdAt: r.createdAt,
+        completedAt: r.completedAt,
+        apiKeyName: key?.name ?? null,
+        keyPrefix: r.keyPrefixSnapshot,
+        clientIp: r.clientIp,
+        protocol: r.protocol,
+        endpoint: r.endpoint,
+        requestedModel: r.requestedModel,
+        resolvedTargetKind: r.resolvedTargetKind,
+        finalModelPublicId: finalModel?.publicModelId ?? null,
+        providerId: provider ? finalModel.providerId : null,
+        providerName: provider?.name ?? null,
+        streaming: Boolean(r.streaming),
+        httpStatus: r.httpStatus,
+        success: Boolean(r.success),
+        totalLatencyMs: r.totalLatencyMs,
+        ttftMs: r.ttftMs,
+        inputTokens: r.inputTokens,
+        outputTokens: r.outputTokens,
+        cacheReadTokens: r.cacheReadTokens,
+        cacheWriteTokens: r.cacheWriteTokens,
+        reasoningTokens: r.reasoningTokens,
+        totalTokens: r.totalTokens,
+        attemptsCount: r.attemptsCount,
+        errorType: r.errorType,
+        errorMessage: r.errorMessage ?? null,
+        gatewayCacheHit: Boolean(r.gatewayCacheHit),
+    };
+}
 export async function registerRequestRoutes(app) {
     app.addHook('preHandler', requireAdminAuth);
     app.get('/api/admin/requests', async (req) => {
@@ -38,45 +87,82 @@ export async function registerRequestRoutes(app) {
         const whereExpr = conds.length ? and(...conds) : undefined;
         const rows = db.select().from(schema.requests).where(whereExpr).orderBy(desc(schema.requests.createdAt)).limit(limit).offset(offset).all();
         const totalRow = db.select({ c: sql `COUNT(*)` }).from(schema.requests).where(whereExpr).get();
-        const keys = db.select().from(schema.apiKeys).all();
-        const keyMap = new Map(keys.map((k) => [k.id, k]));
-        const models = db.select().from(schema.models).all();
-        const modelMap = new Map(models.map((m) => [m.id, m]));
+        const maps = loadSummaryMaps();
         return {
             total: totalRow?.c ?? 0,
-            requests: rows.map((r) => {
-                const key = r.apiKeyId ? keyMap.get(r.apiKeyId) : null;
-                const finalModel = r.finalModelId ? modelMap.get(r.finalModelId) : null;
-                return {
-                    id: r.id,
-                    createdAt: r.createdAt,
-                    completedAt: r.completedAt,
-                    apiKeyName: key?.name ?? null,
-                    keyPrefix: r.keyPrefixSnapshot,
-                    clientIp: r.clientIp,
-                    protocol: r.protocol,
-                    endpoint: r.endpoint,
-                    requestedModel: r.requestedModel,
-                    resolvedTargetKind: r.resolvedTargetKind,
-                    finalModelPublicId: finalModel?.publicModelId ?? null,
-                    streaming: Boolean(r.streaming),
-                    httpStatus: r.httpStatus,
-                    success: Boolean(r.success),
-                    totalLatencyMs: r.totalLatencyMs,
-                    ttftMs: r.ttftMs,
-                    inputTokens: r.inputTokens,
-                    outputTokens: r.outputTokens,
-                    cacheReadTokens: r.cacheReadTokens,
-                    cacheWriteTokens: r.cacheWriteTokens,
-                    reasoningTokens: r.reasoningTokens,
-                    totalTokens: r.totalTokens,
-                    attemptsCount: r.attemptsCount,
-                    errorType: r.errorType,
-                    errorMessage: r.errorMessage ?? null,
-                    gatewayCacheHit: Boolean(r.gatewayCacheHit),
-                };
-            }),
+            requests: rows.map((r) => toSummary(r, maps)),
+        };
+    });
+    // SSE stream of request completions (client reconnects with `since` of its last seen event).
+    app.get('/api/admin/requests/stream', async (req, reply) => {
+        reply.hijack();
+        const q = req.query;
+        const parsedSince = Number(q.since);
+        const since = Number.isFinite(parsedSince) && parsedSince > 0 ? parsedSince : Date.now() - 5_000;
+        const response = reply.raw;
+        // Standard SSE headers
+        response.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            Connection: 'keep-alive',
+        });
+        response.flushHeaders(); // ensure the client sees the stream immediately, even with an empty replay
+        let closed = false;
+        const send = (data) => {
+            if (closed)
+                return;
+            try {
+                response.write(data);
+            }
+            catch {
+                closed = true;
+            }
+        };
+        const db = getDb();
+        const maps = loadSummaryMaps();
+        // History replay: up to 20 most recent rows after `since` (oldest first so the client renders in order).
+        const historyRows = db
+            .select()
+            .from(schema.requests)
+            .where(gte(schema.requests.createdAt, new Date(since).toISOString()))
+            .orderBy(desc(schema.requests.createdAt))
+            .limit(20)
+            .all()
+            .reverse();
+        const replayIds = new Set();
+        for (const r of historyRows) {
+            replayIds.add(r.id);
+            send(`event: request\ndata: ${JSON.stringify(toSummary(r, maps))}\n\n`);
+        }
+        // Live: subscribe to the event bus.
+        const handleRequestLogged = (requestId) => {
+            if (closed || replayIds.has(requestId))
+                return;
+            const row = db.select().from(schema.requests).where(eq(schema.requests.id, requestId)).get();
+            if (!row)
+                return;
+            send(`event: request\ndata: ${JSON.stringify(toSummary(row, maps))}\n\n`);
+        };
+        onRequestLogged(handleRequestLogged);
+        // Keepalive ping every 25s.
+        const keepAlive = setInterval(() => send(': ping\n\n'), 25_000);
+        // Auto-close after 5 min; the client reconnects with its last seen timestamp.
+        const autoClose = setTimeout(() => {
+            response.end();
+            response.destroy();
+        }, 5 * 60_000);
+        const cleanup = () => {
+            closed = true;
+            clearInterval(keepAlive);
+            clearTimeout(autoClose);
+            offRequestLogged(handleRequestLogged);
         };
+        // Listen on the *response*: req.raw (IncomingMessage) emits 'close' as soon as the
+        // request message is consumed (immediately for a GET), which would tear down the
+        // stream before any live event. reply.raw (ServerResponse) 'close' fires when the
+        // response completes or the connection terminates — the canonical SSE signal.
+        reply.raw.on('close', cleanup);
+        reply.raw.on('error', cleanup);
     });
     app.get('/api/admin/requests/:id', async (req, reply) => {
         const { id } = req.params;

package/dist/server/routes/admin/settings.js

@@ -18,6 +18,8 @@ const UpdateBody = z.object({
     gatewayCacheEnabled: z.boolean().optional(),
     gatewayCacheDefaultTtlSeconds: z.number().int().min(1).max(86400).optional(),
     gatewayCacheMaxSizeMb: z.number().int().min(1).max(10240).optional(),
+    notificationsEnabled: z.boolean().optional(),
+    notificationSoundEnabled: z.boolean().optional(),
 });
 const PasswordChange = z.object({
     currentPassword: z.string().min(1),
@@ -28,6 +30,14 @@ const PasswordChange = z.object({
 const TotpEnableBegin = z.object({});
 void TotpEnableBegin;
 const TotpEnableVerify = z.object({ code: z.string().regex(/^\d{6}$/) });
+// speakeasy v2 exports at top level (no `authenticator` namespace). Under ESM
+// interop the module may arrive as { default: {...} }. Normalize once here so
+// every TOTP site uses the v2 API: generateSecret(), totp.verify({secret,
+// encoding:'base32', token, window}), otpauthURL({secret, label, issuer}).
+async function loadSpeakeasy() {
+    const m = await import('speakeasy');
+    return m.default ?? m;
+}
 export async function registerSettingsRoutes(app) {
     app.addHook('preHandler', requireAdminAuth);
     app.get('/api/admin/settings', async () => {
@@ -66,8 +76,8 @@ export async function registerSettingsRoutes(app) {
         }
         if (account.totpEnabled && body.totp) {
             const secret = decryptSecret({ ciphertext: account.totpSecretEncrypted, nonce: account.totpSecretNonce, version: 1 });
-            const speakeasy = await import('speakeasy');
-            if (!speakeasy.authenticator.verify({ token: body.totp, secret, window: 1 })) {
+            const sp = await loadSpeakeasy();
+            if (!sp.totp.verify({ token: body.totp, secret, encoding: 'base32', window: 1 })) {
                 recordAudit({ action: 'admin.password_change', success: false, ip: req.ip, metadata: { reason: 'bad_totp' } });
                 throw new GatewayError('authentication_error', 'Invalid TOTP', { status: 401 });
             }
@@ -83,14 +93,13 @@ export async function registerSettingsRoutes(app) {
     app.post('/api/admin/account/totp/begin', async (req) => {
         if (!isMasterKeyConfigured())
             throw new GatewayError('gateway_error', 'Master key required to enable TOTP', { status: 503 });
-        const speakeasy = await import('speakeasy');
+        const sp = await loadSpeakeasy();
         const qrcode = (await import('qrcode'));
-        const auth = speakeasy.authenticator;
-        const secret = auth.generateSecret({ name: 'LateDev Router', length: 20 });
+        const secret = sp.generateSecret({ name: 'LateDev Router', length: 20 });
         const enc = encryptSecret(secret.base32);
         const db = getDb();
         db.update(schema.adminAccount).set({ totpSecretEncrypted: enc.ciphertext, totpSecretNonce: enc.nonce, updatedAt: new Date().toISOString() }).where(eq(schema.adminAccount.id, req.adminAccount.id)).run();
-        const otpauth = auth.keyuri('admin', 'LateDev Router', secret.base32);
+        const otpauth = sp.otpauthURL({ secret: secret.ascii, label: 'admin', issuer: 'LateDev Router' });
         const qr = await qrcode.toDataURL(otpauth);
         recordAudit({ action: 'totp.begin', success: true, ip: req.ip });
         return { secret: secret.base32, otpauth, qr };
@@ -100,10 +109,9 @@ export async function registerSettingsRoutes(app) {
         const account = req.adminAccount;
         if (!account.totpSecretEncrypted)
             throw new GatewayError('invalid_request_error', 'Begin TOTP setup first', { status: 400 });
-        const speakeasy = await import('speakeasy');
-        const auth = speakeasy.authenticator;
+        const sp = await loadSpeakeasy();
         const secret = decryptSecret({ ciphertext: account.totpSecretEncrypted, nonce: account.totpSecretNonce, version: 1 });
-        if (!auth.verify({ token: body.code, secret, window: 1 })) {
+        if (!sp.totp.verify({ token: body.code, secret, encoding: 'base32', window: 1 })) {
             recordAudit({ action: 'totp.verify', success: false, ip: req.ip });
             throw new GatewayError('invalid_request_error', 'Invalid code', { status: 400 });
         }
@@ -133,9 +141,8 @@ export async function registerSettingsRoutes(app) {
         }
         if (account.totpEnabled && body.totp) {
             const secret = decryptSecret({ ciphertext: account.totpSecretEncrypted, nonce: account.totpSecretNonce, version: 1 });
-            const speakeasy = await import('speakeasy');
-            const auth = speakeasy.authenticator;
-            if (!auth.verify({ token: body.totp, secret, window: 1 })) {
+            const sp = await loadSpeakeasy();
+            if (!sp.totp.verify({ token: body.totp, secret, encoding: 'base32', window: 1 })) {
                 recordAudit({ action: 'totp.disable', success: false, ip: req.ip, metadata: { reason: 'bad_totp' } });
                 throw new GatewayError('authentication_error', 'Invalid TOTP', { status: 401 });
             }
@@ -154,10 +161,9 @@ export async function registerSettingsRoutes(app) {
         const ok = await argon2.verify(account.passwordHash, body.password);
         if (!ok)
             throw new GatewayError('authentication_error', 'Invalid password', { status: 401 });
-        const speakeasy = await import('speakeasy');
-        const auth = speakeasy.authenticator;
+        const sp = await loadSpeakeasy();
         const secret = decryptSecret({ ciphertext: account.totpSecretEncrypted, nonce: account.totpSecretNonce, version: 1 });
-        if (!auth.verify({ token: body.totp, secret, window: 1 }))
+        if (!sp.totp.verify({ token: body.totp, secret, encoding: 'base32', window: 1 }))
             throw new GatewayError('authentication_error', 'Invalid TOTP', { status: 401 });
         const { generateRecoveryCodes } = await import('../../auth/recovery.js');
         const db = getDb();