ldrouter 1.18.2 → 1.19.1

package/dist/server/db/schema.js

@@ -1,7 +1,7 @@
 // Drizzle ORM schema for LateDev Router SQLite database.
 // Source of truth: docs/02-DATA-MODEL.md
 import { sql } from 'drizzle-orm';
-import { sqliteTable, text, integer, index, uniqueIndex } from 'drizzle-orm/sqlite-core';
+import { sqliteTable, text, integer, index, uniqueIndex, primaryKey } from 'drizzle-orm/sqlite-core';
 // ============================================================================
 // Application settings (singleton)
 // ============================================================================
@@ -381,6 +381,23 @@ export const requestAttempts = sqliteTable('request_attempts', {
     qoderAccountIdx: index('idx_attempt_qoder_account').on(t.qoderAccountId, t.startedAt),
 }));
 // ============================================================================
+export const dailyModelStats = sqliteTable('daily_model_stats', {
+    day: text('day').notNull(), modelId: text('model_id').notNull().default(''), requests: integer('requests').notNull().default(0),
+    successfulRequests: integer('successful_requests').notNull().default(0), failedRequests: integer('failed_requests').notNull().default(0),
+    inputTokens: integer('input_tokens').notNull().default(0), outputTokens: integer('output_tokens').notNull().default(0), cacheReadTokens: integer('cache_read_tokens').notNull().default(0),
+    cacheWriteTokens: integer('cache_write_tokens').notNull().default(0), reasoningTokens: integer('reasoning_tokens').notNull().default(0), gatewayCacheHits: integer('gateway_cache_hits').notNull().default(0),
+    fallbackRequests: integer('fallback_requests').notNull().default(0), latencySuccessSumMs: integer('latency_success_sum_ms').notNull().default(0), latencySuccessCount: integer('latency_success_count').notNull().default(0),
+    ttftSumMs: integer('ttft_sum_ms').notNull().default(0), ttftCount: integer('ttft_count').notNull().default(0),
+}, (t) => ({ pk: primaryKey({ columns: [t.day, t.modelId] }) }));
+export const dailyProviderStats = sqliteTable('daily_provider_stats', {
+    day: text('day').notNull(), providerId: text('provider_id').notNull(), attempts: integer('attempts').notNull().default(0), successfulAttempts: integer('successful_attempts').notNull().default(0),
+    failedAttempts: integer('failed_attempts').notNull().default(0), inputTokens: integer('input_tokens').notNull().default(0), outputTokens: integer('output_tokens').notNull().default(0), cacheReadTokens: integer('cache_read_tokens').notNull().default(0),
+    cacheWriteTokens: integer('cache_write_tokens').notNull().default(0), reasoningTokens: integer('reasoning_tokens').notNull().default(0), latencySuccessSumMs: integer('latency_success_sum_ms').notNull().default(0), latencySuccessCount: integer('latency_success_count').notNull().default(0),
+}, (t) => ({ pk: primaryKey({ columns: [t.day, t.providerId] }) }));
+export const dailyApiKeyStats = sqliteTable('daily_api_key_stats', {
+    day: text('day').notNull(), apiKeyId: text('api_key_id').notNull().default(''), requests: integer('requests').notNull().default(0), successfulRequests: integer('successful_requests').notNull().default(0), failedRequests: integer('failed_requests').notNull().default(0),
+    inputTokens: integer('input_tokens').notNull().default(0), outputTokens: integer('output_tokens').notNull().default(0), totalTokens: integer('total_tokens').notNull().default(0),
+}, (t) => ({ pk: primaryKey({ columns: [t.day, t.apiKeyId] }) }));
 // Audit logs (immutable, excluded from request retention)
 // ============================================================================
 export const auditLogs = sqliteTable('audit_logs', {

package/dist/server/gateway/runner.js

@@ -1,5 +1,5 @@
 // Gateway execution pipeline: auth -> resolve -> ACL -> limits -> route -> attempt -> persist.
-import { getDb, schema } from '../db/index.js';
+import { getDb, getRawDb, schema } from '../db/index.js';
 import { eq } from 'drizzle-orm';
 import { GatewayError } from '../errors.js';
 import { resolveRequestedModel, unwrapAlias } from '../routing/resolver.js';
@@ -23,6 +23,7 @@ import { uuid } from '../auth/ids.js';
 import { redactString, redactValue } from '../security/redact.js';
 import { getSettings } from '../db/repositories/settings.js';
 import { buildCacheKey, lookupCache, storeCache, cacheAllowed } from '../caching/store.js';
+import { upsertDailyAggregates } from '../backup/stats.js';
 import { metrics } from '../metrics/registry.js';
 import { emitRequestLogged, emitRequestStarted } from './events.js';
 import { debugHttp, debugBody, debugUpstream, debugStream, errorLine, formatError, getDebugFlags, truncate } from '../logging/debug.js';
@@ -945,65 +946,78 @@ export class GatewayRunner {
         if (settings.contentLogMode === 'prompt_and_response') {
             responsePayload = JSON.stringify(redactValue({ text: outcome.text, toolCalls: outcome.toolCalls, finishReason: outcome.finishReason }));
         }
-        db.insert(schema.requests).values({
-            id: requestId,
-            createdAt: now,
-            completedAt: now,
-            apiKeyId: ctx.key?.id ?? null,
-            keyPrefixSnapshot: ctx.key?.keyPrefix ?? null,
-            clientIp: ctx.clientIp,
-            protocol: ctx.protocol,
-            endpoint: req.endpoint,
-            requestedModel: req.canonical.model,
-            resolvedTargetKind: outcome.resolvedTargetKind,
-            resolvedTargetId: outcome.resolvedTargetId,
-            finalModelId: outcome.finalModelId,
-            streaming: req.canonical.stream,
-            httpStatus: outcome.httpStatus,
-            success: outcome.success ? 1 : 0,
-            totalLatencyMs: outcome.latencyMs,
-            ttftMs: outcome.ttftMs,
-            inputTokens: usage.input,
-            outputTokens: usage.output,
-            cacheReadTokens: usage.cacheRead,
-            cacheWriteTokens: usage.cacheWrite,
-            reasoningTokens: usage.reasoning,
-            totalTokens: usage.total,
-            attemptsCount: attempts.length,
-            errorType: outcome.errorType,
-            errorMessage: outcome.errorMessage ? redactString(outcome.errorMessage) : null,
-            requestPayloadJson: requestPayload,
-            responsePayloadJson: responsePayload,
-            gatewayCacheHit: cacheHit ? true : false,
-        }).run();
-        for (const a of attempts) {
-            db.insert(schema.requestAttempts).values({
-                id: uuid(),
-                requestId,
-                attemptNumber: a.attemptNumber,
-                providerId: a.providerId,
-                modelId: a.modelId,
-                codexAccountId: a.codexAccountId ?? null,
-                qoderAccountId: a.qoderAccountId ?? null,
-                startedAt: a.startedAt,
-                completedAt: a.completedAt,
-                statusCode: a.statusCode,
-                success: a.success,
-                latencyMs: a.latencyMs,
-                ttftMs: a.ttftMs,
-                inputTokens: a.usage.input,
-                outputTokens: a.usage.output,
-                cacheReadTokens: a.usage.cacheRead,
-                cacheWriteTokens: a.usage.cacheWrite,
-                reasoningTokens: a.usage.reasoning,
-                streamStarted: a.streamStarted ? 1 : 0,
-                partialResponse: a.partialResponse ? 1 : 0,
-                selectionReason: a.selectionReason,
-                failureReason: a.failureReason,
-                errorMessage: a.sanitizedError ? redactString(a.sanitizedError) : null,
-                upstreamRequestId: a.upstreamRequestId,
+        const persistedAttempts = attempts.map((a) => ({
+            id: uuid(),
+            requestId,
+            attemptNumber: a.attemptNumber,
+            providerId: a.providerId,
+            modelId: a.modelId,
+            codexAccountId: a.codexAccountId ?? null,
+            qoderAccountId: a.qoderAccountId ?? null,
+            startedAt: a.startedAt,
+            completedAt: a.completedAt,
+            statusCode: a.statusCode,
+            success: a.success,
+            latencyMs: a.latencyMs,
+            ttftMs: a.ttftMs,
+            inputTokens: a.usage.input,
+            outputTokens: a.usage.output,
+            cacheReadTokens: a.usage.cacheRead,
+            cacheWriteTokens: a.usage.cacheWrite,
+            reasoningTokens: a.usage.reasoning,
+            streamStarted: a.streamStarted ? 1 : 0,
+            partialResponse: a.partialResponse ? 1 : 0,
+            selectionReason: a.selectionReason,
+            failureReason: a.failureReason,
+            errorMessage: a.sanitizedError ? redactString(a.sanitizedError) : null,
+            upstreamRequestId: a.upstreamRequestId,
+        }));
+        const tx = getRawDb().transaction(() => {
+            db.insert(schema.requests).values({
+                id: requestId,
+                createdAt: now,
+                completedAt: now,
+                apiKeyId: ctx.key?.id ?? null,
+                keyPrefixSnapshot: ctx.key?.keyPrefix ?? null,
+                clientIp: ctx.clientIp,
+                protocol: ctx.protocol,
+                endpoint: req.endpoint,
+                requestedModel: req.canonical.model,
+                resolvedTargetKind: outcome.resolvedTargetKind,
+                resolvedTargetId: outcome.resolvedTargetId,
+                finalModelId: outcome.finalModelId,
+                streaming: req.canonical.stream,
+                httpStatus: outcome.httpStatus,
+                success: outcome.success ? 1 : 0,
+                totalLatencyMs: outcome.latencyMs,
+                ttftMs: outcome.ttftMs,
+                inputTokens: usage.input,
+                outputTokens: usage.output,
+                cacheReadTokens: usage.cacheRead,
+                cacheWriteTokens: usage.cacheWrite,
+                reasoningTokens: usage.reasoning,
+                totalTokens: usage.total,
+                attemptsCount: attempts.length,
+                errorType: outcome.errorType,
+                errorMessage: outcome.errorMessage ? redactString(outcome.errorMessage) : null,
+                requestPayloadJson: requestPayload,
+                responsePayloadJson: responsePayload,
+                gatewayCacheHit: cacheHit ? true : false,
             }).run();
-        }
+            for (const attempt of persistedAttempts)
+                db.insert(schema.requestAttempts).values(attempt).run();
+            upsertDailyAggregates(getRawDb(), {
+                day: now.slice(0, 10), modelId: outcome.finalModelId, apiKeyId: ctx.key?.id ?? null,
+                success: outcome.success, inputTokens: usage.input, outputTokens: usage.output,
+                cacheReadTokens: usage.cacheRead, cacheWriteTokens: usage.cacheWrite, reasoningTokens: usage.reasoning,
+                cacheHit, attemptsCount: attempts.length, latencyMs: outcome.latencyMs, ttftMs: outcome.ttftMs,
+            }, attempts.map((a) => ({
+                day: a.startedAt.slice(0, 10), providerId: a.providerId, success: a.success,
+                inputTokens: a.usage.input, outputTokens: a.usage.output, cacheReadTokens: a.usage.cacheRead,
+                cacheWriteTokens: a.usage.cacheWrite, reasoningTokens: a.usage.reasoning, latencyMs: a.latencyMs,
+            })));
+        });
+        tx();
         emitRequestLogged(requestId);
     }
 }

package/dist/server/protocols/canonical.js

@@ -78,6 +78,7 @@ export function openAIToCanonical(req) {
         maxOutputTokens: req.max_tokens,
         stop: Array.isArray(req.stop) ? req.stop : req.stop ? [req.stop] : undefined,
         stream: Boolean(req.stream),
+        streamIncludeUsage: Boolean(req.stream_options?.include_usage),
         responseFormat,
         reasoning: req.reasoning_effort ? { effort: req.reasoning_effort } : undefined,
     };
@@ -88,6 +89,11 @@ export function canonicalToOpenAIRequest(req, targetModel) {
         stream: req.stream,
         messages: [],
     };
+    // OpenAI-compatible upstreams omit `usage` from a streamed answer unless the
+    // request opts in. Without this the gateway persisted 0 tokens for every
+    // streamed request to such a provider (live: "Tokens 0" on the Requests page).
+    if (req.stream)
+        out.stream_options = { include_usage: true };
     if (req.system)
         out.messages.push({ role: 'system', content: req.system });
     for (const m of req.messages) {

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

@@ -1,7 +1,6 @@
 // Admin API: database backup / restore.
 import fs from 'node:fs';
 import path from 'node:path';
-import zlib from 'node:zlib';
 import crypto from 'node:crypto';
 import { getDb, closeDb, openDb, schema } from '../../db/index.js';
 import { requireAdminAuth, requireAdminCsrf } from '../../auth/middleware.js';
@@ -10,11 +9,10 @@ import { recordAudit } from '../../db/repositories/audit.js';
 import { loadConfig, setConfigMasterKey } from '../../config/index.js';
 import { getSettings } from '../../db/repositories/settings.js';
 import { GatewayError } from '../../errors.js';
-import { getAppVersion } from '../../version.js';
 import { eq, sql } from 'drizzle-orm';
-import { decryptBackupMasterKey, encryptBackupMasterKey } from '../../auth/backup-crypto.js';
-import { parseMasterKey, resetMasterKeyCache } from '../../auth/crypto.js';
-const BACKUP_VERSION = 1;
+import { resetMasterKeyCache } from '../../auth/crypto.js';
+import { createBackupExport } from '../../backup/export.js';
+import { receiveBackupUpload, validateUploadedBackup, writeLegacyEnvelopeUpload } from '../../backup/restore-upload.js';
 /** Reopen the in-process SQLite connection on the (possibly just-replaced)
  *  database file. The old connection must already be closed: a hot restore
  *  swaps the file on disk, then the gateway keeps serving from the new data
@@ -53,6 +51,144 @@ function assertDatabaseUsable(expectedSchemaVersion) {
         throw new Error(`restored database schema version mismatch: expected ${expectedSchemaVersion}, got ${row.schemaVersion}`);
     }
 }
+/** Raw filesystem/multipart failures become safe fixed-message errors; validated
+ *  failures keep their own safe GatewayError. Internal paths never reach the browser. */
+function safeRestoreError(error) {
+    if (error instanceof GatewayError)
+        return error;
+    return new GatewayError('gateway_error', 'Restore failed', { status: 500 });
+}
+function auditRestoreFailure(req, error) {
+    const reason = error instanceof GatewayError ? (error.code ?? error.type) : 'restore_error';
+    recordAudit({ action: 'db.restore', success: false, ip: req.ip, metadata: { reason } });
+}
+/** Accept both the wrapped `{ backup, passphrase }` legacy body and the bare envelope. */
+function legacyRequestBody(body) {
+    const incoming = body;
+    const wrapped = Boolean(incoming && typeof incoming === 'object' && 'backup' in incoming);
+    const wrappedBody = incoming;
+    return { envelope: (wrapped ? wrappedBody.backup : incoming), passphrase: wrapped ? wrappedBody.passphrase : undefined };
+}
+/**
+ * Atomic swap of an already-validated restore payload. Both the v2 multipart path and the legacy
+ * v1 JSON path feed this, so the snapshot/rollback, hot reopen, session/CSRF re-seed, and audit
+ * behaviour stay identical regardless of container format.
+ */
+export async function restoreValidatedDatabase(validated, req) {
+    const cfg = loadConfig();
+    const liveDb = cfg.dbFile;
+    const previousMasterKey = cfg.masterKey;
+    const restoreKeyPath = path.join(cfg.dataDir, 'master.key.restore');
+    const previousRestoreKey = fs.existsSync(restoreKeyPath) ? fs.readFileSync(restoreKeyPath) : null;
+    const restoredKey = validated.masterKey?.toString('base64');
+    // Snapshot current DB before restore (kept for manual rollback).
+    const snapshot = path.join(cfg.dataDir, `pre-restore-${Date.now()}.sqlite`);
+    const Database = (await import('better-sqlite3')).default;
+    const live = new Database(liveDb);
+    try {
+        await live.backup(snapshot);
+    }
+    catch {
+        live.close();
+        recordAudit({ action: 'db.restore', success: false, ip: req.ip, metadata: { reason: 'snapshot_failed' } });
+        throw new GatewayError('gateway_error', 'Could not snapshot current database', { status: 500 });
+    }
+    live.close();
+    // Close the in-process connection before swapping the file. The gateway
+    // keeps serving (no restart) but the file must be free: on Windows a
+    // rename fails while a handle is open. Reopening runs migrations + the
+    // app_settings bootstrap automatically.
+    getDb();
+    closeDb();
+    // Atomic replace.
+    const tempDb = `${liveDb}.restore-${Date.now()}`;
+    fs.copyFileSync(validated.sqlitePath, tempDb);
+    try {
+        fs.renameSync(tempDb, liveDb);
+    }
+    catch {
+        fs.rmSync(tempDb, { force: true });
+        recordAudit({ action: 'db.restore', success: false, ip: req.ip, metadata: { reason: 'rename_failed' } });
+        throw new GatewayError('gateway_error', 'Restore atomic replace failed', { status: 500 });
+    }
+    // The backup key is authoritative. Apply it before reopening the restored
+    // database so every post-restore read uses the key that encrypted it.
+    if (restoredKey) {
+        fs.writeFileSync(restoreKeyPath, restoredKey, { mode: 0o600, encoding: 'utf8' });
+        setConfigMasterKey(restoredKey);
+        resetMasterKeyCache();
+    }
+    // Hot-reload the database in-process: reopen the replaced file, validate
+    // it, and keep serving. No gateway restart needed.
+    try {
+        reopenDatabase(liveDb);
+        assertDatabaseUsable(validated.schemaVersion);
+    }
+    catch (e) {
+        // Roll back to the snapshot taken before the restore so the gateway
+        // never stays on a broken database.
+        try {
+            closeDb();
+        }
+        catch { /* ignore */ }
+        try {
+            for (const suffix of ['-wal', '-shm']) {
+                const stale = path.join(path.dirname(liveDb), `${path.basename(liveDb)}${suffix}`);
+                if (fs.existsSync(stale))
+                    fs.unlinkSync(stale);
+            }
+            fs.copyFileSync(snapshot, liveDb);
+            openDb(liveDb);
+            try {
+                if (previousRestoreKey)
+                    fs.writeFileSync(restoreKeyPath, previousRestoreKey, { mode: 0o600 });
+                else
+                    fs.unlinkSync(restoreKeyPath);
+            }
+            catch { /* no prior override */ }
+            if (previousMasterKey)
+                setConfigMasterKey(previousMasterKey);
+            resetMasterKeyCache();
+        }
+        catch (rollbackErr) {
+            const err = e.message;
+            const rerr = rollbackErr.message;
+            recordAudit({ action: 'db.restore', success: false, ip: req.ip, metadata: { reason: 'rollback_failed', err, rollbackErr: rerr } });
+            throw new GatewayError('gateway_error', `Restore failed (${err}) and automatic rollback also failed (${rerr}). Please restart the gateway.`, { status: 500 });
+        }
+        recordAudit({ action: 'db.restore', success: false, ip: req.ip, metadata: { reason: 'validation_failed', err: e.message } });
+        throw new GatewayError('gateway_error', `Restore failed: ${e.message}`, { status: 500 });
+    }
+    // The swap invalidates the previous admin session (its row lived in the
+    // old database). Re-create the current session in the restored database so
+    // the admin stays logged in across the hot restore.
+    const sessionToken = req.cookies['ld_session'];
+    const sessionId = req.adminSessionId;
+    if (sessionId && sessionToken) {
+        const db = getDb();
+        const expiresAt = new Date(Date.now() + 12 * 3600 * 1000).toISOString();
+        db.delete(schema.adminSessions).where(sql `id = ${sessionId}`).run();
+        db.insert(schema.adminSessions).values({
+            id: sessionId,
+            tokenDigest: sha256Hex(sessionToken),
+            expiresAt,
+            lastSeenAt: new Date().toISOString(),
+            ip: req.ip,
+        }).run();
+        // Re-seed the CSRF token that was bound to the old session.
+        const csrfRow = db.select().from(schema.csrfTokens).where(eq(schema.csrfTokens.sessionId, sessionId)).get();
+        if (!csrfRow) {
+            db.insert(schema.csrfTokens).values({
+                id: crypto.randomUUID(),
+                sessionId,
+                token: crypto.randomBytes(32).toString('base64url'),
+                expiresAt,
+            }).run();
+        }
+    }
+    recordAudit({ action: 'db.restore', success: true, ip: req.ip, metadata: { profile: validated.profile, schemaVersion: validated.schemaVersion } });
+    return { profile: validated.profile, message: 'Database restored. The gateway continues running with the restored data — no restart needed.' };
+}
 export async function registerBackupRoutes(app) {
     // This module is registered in its own scope (routes/admin.ts) precisely so this is the only
     // auth hook on the backup routes. A preHandler cannot cancel a later one, so the first-run
@@ -64,208 +200,58 @@ export async function registerBackupRoutes(app) {
         if (['POST', 'PUT', 'PATCH', 'DELETE'].includes(req.method))
             await requireAdminCsrf(req);
     });
+    /** UI preflight: the effective server-side maximum upload size. */
+    app.get('/api/admin/backup/capabilities', async () => ({ maxUploadBytes: loadConfig().maxBackupUploadBytes }));
     app.post('/api/admin/backup/create', async (req, reply) => {
-        const passphrase = req.body?.passphrase ?? '';
+        const body = req.body ?? {};
+        const passphrase = body.passphrase ?? '';
         if (!/^\d{6}$/.test(passphrase)) {
             throw new GatewayError('invalid_request_error', 'Backup passphrase must contain exactly six digits', { status: 400 });
         }
-        const cfg = loadConfig();
-        const temp = path.join(cfg.dataDir, `.backup-${Date.now()}.sqlite`);
-        const Database = (await import('better-sqlite3')).default;
-        const source = new Database(cfg.dbFile, { readonly: true });
-        try {
-            await source.backup(temp);
-        }
-        finally {
-            source.close();
-        }
-        const buf = fs.readFileSync(temp);
-        fs.unlinkSync(temp);
-        const compressed = zlib.gzipSync(buf, { level: 6 });
-        const checksum = crypto.createHash('sha256').update(compressed).digest('hex');
-        const settings = getSettings();
-        const masterKey = parseMasterKey(cfg.masterKey ?? fs.readFileSync(path.join(cfg.dataDir, 'master.key'), 'utf8').trim());
-        const envelope = {
-            format: 'latedev-backup',
-            version: BACKUP_VERSION,
-            appVersion: getAppVersion(),
-            schemaVersion: settings.schemaVersion,
-            masterKeyConfigured: settings.masterKeyConfigured,
-            createdAt: new Date().toISOString(),
-            payload: compressed.toString('base64'),
-            checksum,
-            keyEnvelope: encryptBackupMasterKey(masterKey, passphrase),
-        };
-        const envBuf = Buffer.from(JSON.stringify(envelope), 'utf8');
-        const fileName = `latedev-backup-${new Date().toISOString().replace(/[:.]/g, '-')}.ldb.json`;
-        reply.header('content-type', 'application/json');
+        const profile = body.profile === 'full' ? 'full' : 'compact';
+        const { manifest, body: payload } = await createBackupExport({ profile, passphrase, cfg: loadConfig() });
+        const fileName = `latedev-backup-${new Date().toISOString().replace(/[:.]/g, '-')}.ldb`;
+        reply.header('content-type', 'application/octet-stream');
         reply.header('content-disposition', `attachment; filename="${fileName}"`);
-        recordAudit({ action: 'db.backup_download', success: true, ip: req.ip, metadata: { sizeBytes: envBuf.length, checksum } });
-        return reply.send(envBuf);
+        recordAudit({
+            action: 'db.backup_download',
+            success: true,
+            ip: req.ip,
+            metadata: { profile, sizeBytes: manifest.compressedBytes, checksum: manifest.checksum, excludedTables: manifest.excludedTables },
+        });
+        return reply.send(payload);
     });
     app.post('/api/admin/backup/restore', async (req, reply) => {
         const cfg = loadConfig();
-        const incoming = req.body;
-        const wrapped = Boolean(incoming && 'backup' in incoming);
-        const wrappedBody = incoming;
-        const passphrase = wrapped ? wrappedBody.passphrase : undefined;
-        let envelope;
-        try {
-            envelope = (wrapped ? wrappedBody.backup : incoming);
-            if (!envelope || envelope.format !== 'latedev-backup')
-                throw new Error('not a backup envelope');
-            if (envelope.keyEnvelope && !/^\d{6}$/.test(passphrase ?? ''))
-                throw new Error('backup passphrase required');
-        }
-        catch {
-            recordAudit({ action: 'db.restore', success: false, ip: req.ip, metadata: { reason: 'invalid_envelope' } });
-            throw new GatewayError('invalid_request_error', 'Invalid backup file format', { status: 400 });
-        }
-        if (envelope.version > BACKUP_VERSION) {
-            recordAudit({ action: 'db.restore', success: false, ip: req.ip, metadata: { reason: 'future_version', version: envelope.version } });
-            throw new GatewayError('invalid_request_error', `Backup version ${envelope.version} is not supported (max ${BACKUP_VERSION})`, { status: 400 });
-        }
-        const compressed = Buffer.from(envelope.payload, 'base64');
-        const checksum = crypto.createHash('sha256').update(compressed).digest('hex');
-        if (checksum !== envelope.checksum) {
-            recordAudit({ action: 'db.restore', success: false, ip: req.ip, metadata: { reason: 'checksum_mismatch' } });
-            throw new GatewayError('invalid_request_error', 'Backup checksum mismatch', { status: 400 });
-        }
-        let buf;
+        const contentType = String(req.headers['content-type'] ?? '');
+        let upload;
         try {
-            buf = zlib.gunzipSync(compressed);
-        }
-        catch {
-            recordAudit({ action: 'db.restore', success: false, ip: req.ip, metadata: { reason: 'decompress_failed' } });
-            throw new GatewayError('invalid_request_error', 'Backup decompression failed', { status: 400 });
-        }
-        // Validate SQLite header
-        if (!(buf[0] === 0x53 && buf[1] === 0x51 && buf[2] === 0x4c && buf[3] === 0x69 && buf[4] === 0x74 && buf[5] === 0x65)) {
-            recordAudit({ action: 'db.restore', success: false, ip: req.ip, metadata: { reason: 'not_sqlite' } });
-            throw new GatewayError('invalid_request_error', 'Backup does not contain a valid SQLite database', { status: 400 });
-        }
-        let restoredMasterKey;
-        if (envelope.keyEnvelope) {
-            try {
-                restoredMasterKey = decryptBackupMasterKey(envelope.keyEnvelope, passphrase);
-                parseMasterKey(restoredMasterKey.toString('base64'));
+            if (contentType.includes('multipart/form-data')) {
+                upload = await receiveBackupUpload(req, { cfg, maxBytes: cfg.maxBackupUploadBytes });
             }
-            catch {
-                recordAudit({ action: 'db.restore', success: false, ip: req.ip, metadata: { reason: 'invalid_backup_passphrase' } });
-                throw new GatewayError('invalid_request_error', 'Invalid backup passphrase', { status: 400 });
+            else {
+                const { envelope, passphrase } = legacyRequestBody(req.body);
+                upload = await writeLegacyEnvelopeUpload(envelope, cfg, passphrase);
             }
         }
-        const liveDb = cfg.dbFile;
-        const previousMasterKey = cfg.masterKey;
-        const restoreKeyPath = path.join(cfg.dataDir, 'master.key.restore');
-        const previousRestoreKey = fs.existsSync(restoreKeyPath) ? fs.readFileSync(restoreKeyPath) : null;
-        const restoredKey = restoredMasterKey?.toString('base64');
-        // Snapshot current DB before restore (kept for manual rollback).
-        const snapshot = path.join(cfg.dataDir, `pre-restore-${Date.now()}.sqlite`);
-        const Database = (await import('better-sqlite3')).default;
-        const live = new Database(liveDb);
-        try {
-            await live.backup(snapshot);
-        }
-        catch (e) {
-            live.close();
-            recordAudit({ action: 'db.restore', success: false, ip: req.ip, metadata: { reason: 'snapshot_failed', err: String(e) } });
-            throw new GatewayError('gateway_error', 'Could not snapshot current database', { status: 500 });
+        catch (error) {
+            auditRestoreFailure(req, error);
+            throw safeRestoreError(error);
         }
-        live.close();
-        // Close the in-process connection before swapping the file. The gateway
-        // keeps serving (no restart) but the file must be free: on Windows a
-        // rename fails while a handle is open. Reopening runs migrations + the
-        // app_settings bootstrap automatically.
-        getDb();
-        closeDb();
-        // Atomic replace.
-        const tempDb = `${liveDb}.restore-${Date.now()}`;
-        fs.writeFileSync(tempDb, buf);
+        let validated;
         try {
-            fs.renameSync(tempDb, liveDb);
+            validated = await validateUploadedBackup(upload, upload.passphrase);
+            const result = await restoreValidatedDatabase(validated, req);
+            return reply.code(200).send({ ok: true, profile: result.profile, message: result.message });
         }
-        catch (e) {
-            fs.unlinkSync(tempDb);
-            recordAudit({ action: 'db.restore', success: false, ip: req.ip, metadata: { reason: 'rename_failed', err: String(e) } });
-            throw new GatewayError('gateway_error', 'Restore atomic replace failed', { status: 500 });
+        catch (error) {
+            auditRestoreFailure(req, error);
+            throw safeRestoreError(error);
         }
-        // The backup key is authoritative. Apply it before reopening the restored
-        // database so every post-restore read uses the key that encrypted it.
-        if (restoredKey) {
-            fs.writeFileSync(restoreKeyPath, restoredKey, { mode: 0o600, encoding: 'utf8' });
-            setConfigMasterKey(restoredKey);
-            resetMasterKeyCache();
-        }
-        // Hot-reload the database in-process: reopen the replaced file, validate
-        // it, and keep serving. No gateway restart needed.
-        try {
-            reopenDatabase(liveDb);
-            assertDatabaseUsable(envelope.schemaVersion);
-        }
-        catch (e) {
-            // Roll back to the snapshot taken before the restore so the gateway
-            // never stays on a broken database.
-            try {
-                closeDb();
-            }
-            catch { /* ignore */ }
-            try {
-                for (const suffix of ['-wal', '-shm']) {
-                    const stale = path.join(path.dirname(liveDb), `${path.basename(liveDb)}${suffix}`);
-                    if (fs.existsSync(stale))
-                        fs.unlinkSync(stale);
-                }
-                fs.copyFileSync(snapshot, liveDb);
-                openDb(liveDb);
-                try {
-                    if (previousRestoreKey)
-                        fs.writeFileSync(restoreKeyPath, previousRestoreKey, { mode: 0o600 });
-                    else
-                        fs.unlinkSync(restoreKeyPath);
-                }
-                catch { /* no prior override */ }
-                if (previousMasterKey)
-                    setConfigMasterKey(previousMasterKey);
-                resetMasterKeyCache();
-            }
-            catch (rollbackErr) {
-                const err = e.message;
-                const rerr = rollbackErr.message;
-                recordAudit({ action: 'db.restore', success: false, ip: req.ip, metadata: { reason: 'rollback_failed', err, rollbackErr: rerr } });
-                throw new GatewayError('gateway_error', `Restore failed (${err}) and automatic rollback also failed (${rerr}). Please restart the gateway.`, { status: 500 });
-            }
-            recordAudit({ action: 'db.restore', success: false, ip: req.ip, metadata: { reason: 'validation_failed', err: e.message } });
-            throw new GatewayError('gateway_error', `Restore failed: ${e.message}`, { status: 500 });
-        }
-        // The swap invalidates the previous admin session (its row lived in the
-        // old database). Re-create the current session in the restored database so
-        // the admin stays logged in across the hot restore.
-        const sessionToken = req.cookies['ld_session'];
-        const sessionId = req.adminSessionId;
-        if (sessionId && sessionToken) {
-            const db = getDb();
-            const expiresAt = new Date(Date.now() + 12 * 3600 * 1000).toISOString();
-            db.delete(schema.adminSessions).where(sql `id = ${sessionId}`).run();
-            db.insert(schema.adminSessions).values({
-                id: sessionId,
-                tokenDigest: sha256Hex(sessionToken),
-                expiresAt,
-                lastSeenAt: new Date().toISOString(),
-                ip: req.ip,
-            }).run();
-            // Re-seed the CSRF token that was bound to the old session.
-            const csrfRow = db.select().from(schema.csrfTokens).where(eq(schema.csrfTokens.sessionId, sessionId)).get();
-            if (!csrfRow) {
-                db.insert(schema.csrfTokens).values({
-                    id: crypto.randomUUID(),
-                    sessionId,
-                    token: crypto.randomBytes(32).toString('base64url'),
-                    expiresAt,
-                }).run();
-            }
+        finally {
+            // Temp upload + decompressed payload are removed on success, failure, and abort.
+            await validated?.cleanup();
+            await upload.cleanup();
         }
-        recordAudit({ action: 'db.restore', success: true, ip: req.ip, metadata: { schemaVersion: envelope.schemaVersion } });
-        return reply.code(200).send({ ok: true, message: 'Database restored. The gateway continues running with the restored data — no restart needed.' });
     });
 }