ldrouter 1.18.1 → 1.19.0

package/CHANGELOG.md

@@ -4,6 +4,34 @@ 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.19.0] - 2026-10-12
+
+### Added
+
+- Compact and full database backup profiles, exported as a v2 `.ldb` binary container (manifest + gzip payload + encrypted key envelope).
+- Compact backups keep all gateway configuration and daily statistics (by model, provider and API key) while excluding request/attempt/audit logs, the gateway response cache, admin sessions, CSRF tokens and previous backups.
+- Streamed multipart restore: the upload is written to disk, then validated (checksum, gzip, SQLite integrity, schema, key envelope) before an atomic swap with rollback, with real upload progress and cancel in the admin UI.
+- `LATEDEV_MAX_BACKUP_UPLOAD_BYTES` (default 256 MiB) and a `GET /api/admin/backup/capabilities` preflight.
+- Daily aggregate statistics tables (`daily_model_stats`, `daily_provider_stats`, `daily_api_key_stats`) written in the same transaction as request persistence.
+
+### Changed
+
+- Backup download extension is now `.ldb` (previously `.json`); legacy v1 JSON backups remain restorable.
+- Statistics over a range that includes a compacted day report p95 latency and TTFT as unavailable instead of a misleading zero.
+
+### Notes
+
+- A compact restore cannot recover individual request, attempt or audit history, and the response cache is empty after a compact restore even when caching is enabled.
+- Uploads are not resumable.
+
+## [1.18.2] - 2026-10-02
+
+### Fixed
+
+- Restore now adopts the backup's master key, including across restarts.
+- Admin deletion now permanently removes API keys, models, and providers with dependent routing configuration cleaned up first.
+- `/setup` always exposes the master-key input and reports runtime key availability.
+
 ## [1.17.9] - 2026-09-22
 
 ### Fixed

package/README.md

@@ -16,7 +16,7 @@ Lightweight self-hosted LLM gateway with a polished admin UI. Presents stable Op
 - Request + attempt logs, statistics (Today / 7d / 30d), retention cleanup
 - Admin TOTP 2FA, Argon2id passwords, recovery codes
 - Immutable audit logs
-- Consistent backup / restore (SQLite snapshot + checksum + schema validation)
+- Consistent backup / restore: compact `.ldb` default + full forensic profile, streamed upload with progress/cancel
 - Prometheus `/metrics`, structured logs, graceful shutdown
 - One distributable npm package, multi-stage Dockerfile, Docker Compose
 
@@ -52,6 +52,20 @@ The data directory defaults to `~/.latedev-router/` and can be overridden via `L
 | `LATEDEV_MASTER_KEY` | 32-byte base64 key for encrypting provider credentials | _required once providers exist_ |
 | `LATEDEV_TRUST_PROXY` | Number of reverse-proxy hops to trust for X-Forwarded-For | `0` |
 | `LATEDEV_LOG_LEVEL` | trace / debug / info / warn / error / fatal | `info` |
+| `LATEDEV_MAX_BACKUP_UPLOAD_BYTES` | Maximum accepted backup restore upload size (bytes) | `268435456` (256 MiB) |
+
+## Backup & restore
+
+Backups download from Settings > Backup (or first-run Setup). New backups use the binary `.ldb` container; legacy `.ldb.json` files remain restoreable.
+
+- **Compact (default)** — retains all gateway configuration, encrypted provider credentials, API-key configuration, quota usage, and daily statistics by model/provider/API key. It excludes requests, attempts, audit logs, and the gateway response cache, so it is much smaller and is the right choice for routine backups.
+- **Full (forensic)** — retains every raw row, including request/attempt/audit and cached response content. It can be much larger and contains sensitive data; treat the file as confidential.
+
+To restore, upload the `.ldb` file (or legacy `.ldb.json`) and enter the **same six-digit passphrase** used to create it — it decrypts the encrypted master key inside the backup. Without it, restored provider credentials cannot be decrypted. The upload streams to disk with real progress and a Cancel button; **uploads are not resumable**, so an interrupted upload must be restarted. The default upload size limit is 256 MiB (`LATEDEV_MAX_BACKUP_UPLOAD_BYTES`); over-limit uploads are rejected with HTTP 413.
+
+Restore validates the container, checksum, gzip, SQLite integrity, schema version, and key envelope before an atomic swap, and keeps a pre-restore snapshot so a failure rolls back to the previous database.
+
+**Limitation:** a compact backup cannot restore individual request/attempt/audit history or cached responses, and after a compact restore historical p95 latency and p95 TTFT percentiles are unavailable for aggregate-only days (average latency/TTFT and top rankings are retained). Use a full backup if you need that row-level detail or percentile history.
 
 ## Public API examples
 

package/dist/server/backup/container.js

@@ -0,0 +1,99 @@
+import fs from 'node:fs';
+import { open as openFile } from 'node:fs/promises';
+import { Readable } from 'node:stream';
+export const BACKUP_MAGIC = Buffer.from('LDRB');
+export const BACKUP_VERSION = 2;
+export const MAX_BACKUP_MANIFEST_BYTES = 1024 * 1024;
+const PREFIX_BYTES = BACKUP_MAGIC.length + 1 + 4;
+export async function writeBackupContainer(input) {
+    const manifest = Buffer.from(JSON.stringify(input.manifest), 'utf8');
+    if (manifest.length > MAX_BACKUP_MANIFEST_BYTES)
+        throw new Error('Backup manifest exceeds maximum size');
+    const header = Buffer.alloc(PREFIX_BYTES + manifest.length);
+    BACKUP_MAGIC.copy(header);
+    header.writeUInt8(BACKUP_VERSION, BACKUP_MAGIC.length);
+    header.writeUInt32BE(manifest.length, BACKUP_MAGIC.length + 1);
+    manifest.copy(header, PREFIX_BYTES);
+    return Readable.from((async function* () {
+        yield header;
+        yield* input.payload;
+    })());
+}
+export async function readBackupContainerHeader(file, open = (path) => openFile(path, 'r')) {
+    const handle = await open(file);
+    try {
+        const prefix = Buffer.alloc(PREFIX_BYTES);
+        const prefixRead = await handle.read(prefix, 0, PREFIX_BYTES, 0);
+        if (prefixRead.bytesRead !== PREFIX_BYTES)
+            throw new Error('Truncated backup header');
+        if (!prefix.subarray(0, BACKUP_MAGIC.length).equals(BACKUP_MAGIC))
+            throw new Error('Invalid backup magic');
+        if (prefix.readUInt8(BACKUP_MAGIC.length) !== BACKUP_VERSION)
+            throw new Error('Unsupported backup version');
+        const manifestLength = prefix.readUInt32BE(BACKUP_MAGIC.length + 1);
+        if (manifestLength > MAX_BACKUP_MANIFEST_BYTES)
+            throw new Error('Backup manifest exceeds maximum size');
+        const manifestBytes = Buffer.alloc(manifestLength);
+        const manifestRead = await handle.read(manifestBytes, 0, manifestLength, PREFIX_BYTES);
+        if (manifestRead.bytesRead !== manifestLength)
+            throw new Error('Truncated backup header');
+        let manifest;
+        try {
+            manifest = JSON.parse(manifestBytes.toString('utf8'));
+        }
+        catch {
+            throw new Error('Invalid backup manifest');
+        }
+        if (!isBackupManifestV2(manifest))
+            throw new Error('Invalid backup manifest');
+        return { manifest, payloadOffset: PREFIX_BYTES + manifestLength };
+    }
+    finally {
+        await handle.close();
+    }
+}
+export function streamBackupPayload(file, payloadOffset) {
+    return fs.createReadStream(file, { start: payloadOffset });
+}
+function isBackupManifestV2(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const manifest = value;
+    return manifest.format === 'latedev-backup'
+        && manifest.version === BACKUP_VERSION
+        && (manifest.profile === 'compact' || manifest.profile === 'full')
+        && typeof manifest.appVersion === 'string'
+        && isNonNegativeInteger(manifest.schemaVersion)
+        && isIsoTimestamp(manifest.createdAt)
+        && isNonNegativeInteger(manifest.compressedBytes)
+        && isNonNegativeInteger(manifest.uncompressedBytes)
+        && typeof manifest.checksum === 'string'
+        && /^[a-f\d]{64}$/i.test(manifest.checksum)
+        && (!('keyEnvelope' in manifest) || isBackupMasterKeyEnvelope(manifest.keyEnvelope))
+        && Array.isArray(manifest.excludedTables)
+        && manifest.excludedTables.every((table) => typeof table === 'string')
+        && !!manifest.statistics
+        && manifest.statistics.granularity === 'daily'
+        && manifest.statistics.p95Available === false
+        && Array.isArray(manifest.statistics.dimensions)
+        && manifest.statistics.dimensions.every((dimension) => dimension === 'model' || dimension === 'provider' || dimension === 'api_key');
+}
+function isNonNegativeInteger(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+function isIsoTimestamp(value) {
+    if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value))
+        return false;
+    const timestamp = new Date(value);
+    return !Number.isNaN(timestamp.valueOf()) && timestamp.toISOString() === value;
+}
+function isBackupMasterKeyEnvelope(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const envelope = value;
+    return envelope.algorithm === 'scrypt-aes-256-gcm'
+        && typeof envelope.salt === 'string'
+        && typeof envelope.nonce === 'string'
+        && typeof envelope.ciphertext === 'string'
+        && typeof envelope.tag === 'string';
+}

package/dist/server/backup/export.js

@@ -0,0 +1,99 @@
+// Compact/full backup export: consistent snapshot → profile pruning → streamed gzip → v2 container.
+// The SQLite payload is never read into memory: only per-chunk byte counters and the SHA-256
+// digest state are kept while the snapshot is piped through gzip to disk.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { encryptBackupMasterKey } from '../auth/backup-crypto.js';
+import { parseMasterKey } from '../auth/crypto.js';
+import { getSettings } from '../db/repositories/settings.js';
+import { getAppVersion } from '../version.js';
+import { writeBackupContainer } from './container.js';
+/** Forensic/volatile tables removed by a compact export; retained by a full export. */
+export const COMPACT_EXCLUDED_TABLES = [
+    'requests',
+    'request_attempts',
+    'audit_logs',
+    'response_cache',
+    'admin_sessions',
+    'csrf_tokens',
+    'backups',
+];
+export async function createBackupExport(input) {
+    const { profile, passphrase, cfg } = input;
+    const snapshotFile = path.join(cfg.dataDir, `.export-snapshot-${crypto.randomUUID()}.sqlite`);
+    const gzFile = path.join(cfg.dataDir, `.export-payload-${crypto.randomUUID()}.gz`);
+    let body;
+    try {
+        const Database = (await import('better-sqlite3')).default;
+        // 1. Consistent snapshot of the live DB while the gateway keeps serving.
+        const source = new Database(cfg.dbFile, { readonly: true });
+        try {
+            await source.backup(snapshotFile);
+        }
+        finally {
+            source.close();
+        }
+        // 2. Compact prunes the snapshot in place, then reclaims its pages. Full keeps every row.
+        if (profile === 'compact') {
+            const staging = new Database(snapshotFile);
+            try {
+                const present = new Set(staging.prepare("SELECT name FROM sqlite_master WHERE type='table'").all().map((row) => row.name));
+                for (const table of COMPACT_EXCLUDED_TABLES) {
+                    if (present.has(table))
+                        staging.prepare(`DELETE FROM "${table}"`).run();
+                }
+                staging.exec('VACUUM');
+            }
+            finally {
+                staging.close();
+            }
+        }
+        // 3. Stream the snapshot through gzip to disk, hashing exactly the compressed bytes.
+        const checksum = crypto.createHash('sha256');
+        let uncompressedBytes = 0;
+        let compressedBytes = 0;
+        const meter = (onChunk) => new Transform({
+            transform(chunk, _encoding, callback) {
+                onChunk(chunk.length, chunk);
+                callback(null, chunk);
+            },
+        });
+        await pipeline(fs.createReadStream(snapshotFile), meter((length) => { uncompressedBytes += length; }), zlib.createGzip({ level: 6 }), meter((length, chunk) => { compressedBytes += length; checksum.update(chunk); }), fs.createWriteStream(gzFile));
+        // 4. v2 manifest.
+        const masterKey = parseMasterKey(cfg.masterKey ?? fs.readFileSync(path.join(cfg.dataDir, 'master.key'), 'utf8').trim());
+        const manifest = {
+            format: 'latedev-backup',
+            version: 2,
+            profile,
+            appVersion: getAppVersion(),
+            schemaVersion: getSettings().schemaVersion,
+            createdAt: new Date().toISOString(),
+            compressedBytes,
+            uncompressedBytes,
+            checksum: checksum.digest('hex'),
+            keyEnvelope: encryptBackupMasterKey(masterKey, passphrase),
+            excludedTables: profile === 'compact' ? [...COMPACT_EXCLUDED_TABLES] : [],
+            statistics: { granularity: 'daily', dimensions: ['model', 'provider', 'api_key'], p95Available: false },
+        };
+        // 5. Container. The payload stream is lazy, so the gz file must outlive this
+        // function: it is deleted when that stream closes or errors, never before.
+        body = await writeBackupContainer({ manifest, payload: fs.createReadStream(gzFile) });
+        return { manifest, body };
+    }
+    finally {
+        for (const suffix of ['', '-wal', '-shm'])
+            fs.rmSync(`${snapshotFile}${suffix}`, { force: true });
+        if (body) {
+            const removePayload = () => fs.rmSync(gzFile, { force: true });
+            body.once('close', removePayload);
+            body.once('error', removePayload);
+        }
+        else {
+            fs.rmSync(gzFile, { force: true });
+        }
+    }
+}

package/dist/server/backup/restore-upload.js

@@ -0,0 +1,333 @@
+// Streamed, disk-based backup restore support.
+//
+// The upload is written straight to a private temp file (never buffered in memory), the v2 header
+// is read from disk, and the payload is stream-decompressed into a second temp SQLite file that is
+// validated (magic, integrity_check, manifest checksum, key envelope, schema version) BEFORE the
+// caller swaps it in. Every failure path removes its temp files.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { loadConfig } from '../config/index.js';
+import { GatewayError } from '../errors.js';
+import { decryptBackupMasterKey } from '../auth/backup-crypto.js';
+import { parseMasterKey } from '../auth/crypto.js';
+import { getSettings } from '../db/repositories/settings.js';
+import { readBackupContainerHeader, streamBackupPayload, } from './container.js';
+/** Tables a compact export must have left in place; a restore of one without them is not usable. */
+const COMPACT_AGGREGATE_TABLES = ['daily_model_stats', 'daily_provider_stats', 'daily_api_key_stats'];
+/** Ceiling on decompressed bytes, as a multiple of the configured upload limit. A SQLite snapshot
+ *  compresses ~3-10x, so 20x is generous while still bounding a decompression bomb. */
+const MAX_UNCOMPRESSED_MULTIPLE = 20;
+const LEGACY_VERSION = 1;
+function backupError(code, message, status = 400) {
+    return new GatewayError('invalid_request_error', message, { status, code });
+}
+const tooLarge = () => backupError('backup_too_large', 'Backup upload exceeds maximum size', 413);
+const malformed = () => backupError('multipart_malformed', 'Malformed multipart restore body');
+const invalidFormat = () => backupError('invalid_backup_format', 'Invalid backup file format');
+const checksumMismatch = () => backupError('checksum_mismatch', 'Backup checksum mismatch');
+const decompressFailed = () => backupError('decompress_failed', 'Backup decompression failed');
+const notSqlite = () => backupError('not_sqlite', 'Backup does not contain a valid SQLite database');
+const integrityFailed = () => backupError('integrity_failed', 'Backup database failed the integrity check');
+const invalidPassphrase = () => backupError('invalid_backup_passphrase', 'Invalid backup passphrase');
+async function restoreTmpDir(cfg) {
+    const dir = path.join(cfg.dataDir, 'restore-tmp');
+    await fs.promises.mkdir(dir, { recursive: true, mode: 0o700 });
+    return dir;
+}
+function removeQuietly(...files) {
+    for (const file of files)
+        fs.rmSync(file, { force: true });
+}
+async function drain(stream) {
+    for await (const chunk of stream)
+        void chunk;
+}
+/**
+ * Collect the single `backup` file part into `<dataDir>/restore-tmp/<uuid>.part` (dir 0700, file
+ * 0600), counting bytes as they arrive so the configured maximum is enforced mid-stream rather
+ * than trusted from Content-Length alone.
+ */
+export async function receiveBackupUpload(request, options) {
+    const maxBytes = options.maxBytes;
+    const declared = Number(request.headers['content-length']);
+    if (Number.isFinite(declared) && declared > maxBytes)
+        throw tooLarge();
+    const tmpDir = await restoreTmpDir(options.cfg);
+    let target;
+    let out;
+    let bytes = 0;
+    let fileDone = false;
+    let settled = false;
+    let passphrase;
+    let filename;
+    // Abort/cancel cleanup: the request may die while the body is still streaming. Node also emits
+    // 'close' when a request completes normally, so only an incomplete message counts as a cancel.
+    const cleanupFile = () => {
+        try {
+            out?.destroy();
+        }
+        catch { /* already gone */ }
+        if (target)
+            removeQuietly(target);
+    };
+    const onAbort = () => {
+        if (settled || fileDone || request.raw.complete)
+            return;
+        settled = true;
+        cleanupFile();
+    };
+    request.raw.once('aborted', onAbort);
+    request.raw.once('close', onAbort);
+    try {
+        let seenFiles = 0;
+        // The global multipart fileSize cap (2 MB, sized for JSON imports) is too small for a backup,
+        // so the limit is raised per request here; the byte counter below is the real enforcement.
+        for await (const part of request.parts({ limits: { fileSize: maxBytes + 1 } })) {
+            if (part.type === 'field') {
+                if (part.fieldname === 'passphrase')
+                    passphrase = String(part.value);
+                continue;
+            }
+            if (part.fieldname !== 'backup') {
+                await drain(part.file);
+                throw malformed();
+            }
+            seenFiles += 1;
+            if (seenFiles > 1) {
+                await drain(part.file);
+                throw malformed();
+            }
+            const name = part.filename ?? '';
+            if (!name) {
+                await drain(part.file);
+                throw malformed();
+            }
+            if (!name.endsWith('.ldb') && !name.endsWith('.ldb.json')) {
+                await drain(part.file);
+                throw malformed();
+            }
+            filename = name;
+            target = path.join(tmpDir, `${crypto.randomUUID()}.part`);
+            out = fs.createWriteStream(target, { mode: 0o600, flags: 'wx' });
+            const counter = new Transform({
+                transform(chunk, _encoding, callback) {
+                    bytes += chunk.length;
+                    if (bytes > maxBytes) {
+                        callback(tooLarge());
+                        return;
+                    }
+                    callback(null, chunk);
+                },
+            });
+            await pipeline(part.file, counter, out);
+            fileDone = true;
+        }
+        if (!target || !filename)
+            throw malformed();
+        settled = true;
+        request.raw.off('aborted', onAbort);
+        request.raw.off('close', onAbort);
+        const filePath = target;
+        return {
+            path: filePath,
+            bytes,
+            filename,
+            ...(passphrase === undefined ? {} : { passphrase }),
+            cleanup: async () => { removeQuietly(filePath); },
+        };
+    }
+    catch (error) {
+        settled = true;
+        cleanupFile();
+        if (error instanceof GatewayError)
+            throw error;
+        throw malformed();
+    }
+}
+/** Write a legacy v1 JSON envelope to a private temp file so both restore paths share one reader. */
+export async function writeLegacyEnvelopeUpload(envelope, cfg, passphrase) {
+    const tmpDir = await restoreTmpDir(cfg);
+    const target = path.join(tmpDir, `${crypto.randomUUID()}.ldb.json`);
+    const body = Buffer.from(JSON.stringify(envelope ?? {}), 'utf8');
+    if (body.length > cfg.maxBackupUploadBytes)
+        throw tooLarge();
+    await fs.promises.writeFile(target, body, { mode: 0o600 });
+    return {
+        path: target,
+        bytes: body.length,
+        filename: 'restore.ldb.json',
+        ...(passphrase === undefined ? {} : { passphrase }),
+        cleanup: async () => { removeQuietly(target); },
+    };
+}
+/**
+ * Validate an uploaded backup from disk and return a SQLite file ready for the atomic swap.
+ * Reads only the v2 header into memory; the payload is streamed through gunzip into a second
+ * private temp file. Nothing is swapped until checksum, decompression, SQLite integrity, schema
+ * version, and the passphrase-protected key envelope have all passed.
+ */
+export async function validateUploadedBackup(upload, passphrase) {
+    const cfg = loadConfig();
+    const isLegacy = upload.filename.endsWith('.ldb.json');
+    const sqlitePath = path.join(path.dirname(upload.path), `${crypto.randomUUID()}.sqlite`);
+    const cleanup = async () => {
+        removeQuietly(sqlitePath, `${sqlitePath}-wal`, `${sqlitePath}-shm`, upload.path);
+    };
+    try {
+        const result = isLegacy
+            ? await validateLegacyJson(upload.path, sqlitePath, cfg, passphrase)
+            : await validateV2(upload.path, sqlitePath, cfg, passphrase);
+        return { ...result, cleanup };
+    }
+    catch (error) {
+        await cleanup();
+        throw error;
+    }
+}
+async function validateV2(file, sqlitePath, cfg, passphrase) {
+    let manifest;
+    let payloadOffset;
+    try {
+        ({ manifest, payloadOffset } = await readBackupContainerHeader(file));
+    }
+    catch {
+        throw invalidFormat();
+    }
+    if (manifest.schemaVersion > getSettings().schemaVersion) {
+        throw backupError('future_schema', 'Backup was created by a newer schema version than this gateway supports');
+    }
+    const checksum = crypto.createHash('sha256');
+    let compressedBytes = 0;
+    let uncompressedBytes = 0;
+    const ceiling = cfg.maxBackupUploadBytes * MAX_UNCOMPRESSED_MULTIPLE;
+    try {
+        await pipeline(streamBackupPayload(file, payloadOffset), new Transform({
+            transform(chunk, _encoding, callback) {
+                compressedBytes += chunk.length;
+                checksum.update(chunk);
+                callback(null, chunk);
+            },
+        }), zlib.createGunzip(), new Transform({
+            transform(chunk, _encoding, callback) {
+                uncompressedBytes += chunk.length;
+                if (uncompressedBytes > ceiling) {
+                    callback(tooLarge());
+                    return;
+                }
+                callback(null, chunk);
+            },
+        }), fs.createWriteStream(sqlitePath, { mode: 0o600, flags: 'wx' }));
+    }
+    catch (error) {
+        if (error instanceof GatewayError)
+            throw error;
+        throw decompressFailed();
+    }
+    if (compressedBytes !== manifest.compressedBytes || checksum.digest('hex') !== manifest.checksum) {
+        throw checksumMismatch();
+    }
+    await assertUsableSqlite(sqlitePath, manifest.profile);
+    return {
+        sqlitePath,
+        schemaVersion: manifest.schemaVersion,
+        profile: manifest.profile,
+        ...(manifest.keyEnvelope ? { masterKey: decryptMasterKey(manifest.keyEnvelope, passphrase) } : {}),
+    };
+}
+async function validateLegacyJson(file, sqlitePath, cfg, passphrase) {
+    // Bounded read: the file was already capped at the configured maximum by the receiver.
+    let envelope;
+    try {
+        envelope = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        throw invalidFormat();
+    }
+    if (!envelope || envelope.format !== 'latedev-backup')
+        throw invalidFormat();
+    if (typeof envelope.version === 'number' && envelope.version > LEGACY_VERSION) {
+        throw backupError('unsupported_version', 'Backup version is not supported');
+    }
+    const compressed = Buffer.from(String(envelope.payload ?? ''), 'base64');
+    if (compressed.length > cfg.maxBackupUploadBytes)
+        throw tooLarge();
+    if (crypto.createHash('sha256').update(compressed).digest('hex') !== envelope.checksum)
+        throw checksumMismatch();
+    let uncompressedBytes = 0;
+    const ceiling = cfg.maxBackupUploadBytes * MAX_UNCOMPRESSED_MULTIPLE;
+    try {
+        await pipeline(Readable.from(compressed), zlib.createGunzip(), new Transform({
+            transform(chunk, _encoding, callback) {
+                uncompressedBytes += chunk.length;
+                if (uncompressedBytes > ceiling) {
+                    callback(tooLarge());
+                    return;
+                }
+                callback(null, chunk);
+            },
+        }), fs.createWriteStream(sqlitePath, { mode: 0o600, flags: 'wx' }));
+    }
+    catch (error) {
+        if (error instanceof GatewayError)
+            throw error;
+        throw decompressFailed();
+    }
+    await assertUsableSqlite(sqlitePath, 'full');
+    return {
+        sqlitePath,
+        schemaVersion: typeof envelope.schemaVersion === 'number' ? envelope.schemaVersion : getSettings().schemaVersion,
+        profile: 'full',
+        ...(envelope.keyEnvelope ? { masterKey: decryptMasterKey(envelope.keyEnvelope, passphrase) } : {}),
+    };
+}
+function decryptMasterKey(envelope, passphrase) {
+    if (!/^\d{6}$/.test(passphrase ?? ''))
+        throw invalidPassphrase();
+    let key;
+    try {
+        key = decryptBackupMasterKey(envelope, passphrase);
+        parseMasterKey(key.toString('base64'));
+    }
+    catch {
+        throw invalidPassphrase();
+    }
+    return key;
+}
+/** Verify the SQLite header, run a read-only integrity check, and confirm the tables the profile
+ *  promises are actually present. */
+async function assertUsableSqlite(file, profile) {
+    const head = Buffer.alloc(16);
+    const fd = fs.openSync(file, 'r');
+    try {
+        if (fs.readSync(fd, head, 0, 16, 0) !== 16 || head.toString('utf8') !== 'SQLite format 3\u0000')
+            throw notSqlite();
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    const Database = (await import('better-sqlite3')).default;
+    let db;
+    try {
+        db = new Database(file, { readonly: true, fileMustExist: true });
+        const result = db.prepare('PRAGMA integrity_check').get();
+        if (result?.integrity_check !== 'ok')
+            throw integrityFailed();
+        const tables = new Set(db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all().map((row) => row.name));
+        if (!tables.has('app_settings'))
+            throw invalidFormat();
+        if (profile === 'compact' && !COMPACT_AGGREGATE_TABLES.every((table) => tables.has(table)))
+            throw invalidFormat();
+    }
+    catch (error) {
+        if (error instanceof GatewayError)
+            throw error;
+        throw notSqlite();
+    }
+    finally {
+        db?.close();
+    }
+}

package/dist/server/backup/stats.js

@@ -0,0 +1,15 @@
+/** Call within the raw request-log transaction; empty IDs represent missing dimensions. */
+export function upsertDailyAggregates(db, request, attempts) {
+    const model = db.prepare(`INSERT INTO daily_model_stats (day,model_id,requests,successful_requests,failed_requests,input_tokens,output_tokens,cache_read_tokens,cache_write_tokens,reasoning_tokens,gateway_cache_hits,fallback_requests,latency_success_sum_ms,latency_success_count,ttft_sum_ms,ttft_count)
+    VALUES (@day,@modelId,1,@success,1-@success,@inputTokens,@outputTokens,@cacheReadTokens,@cacheWriteTokens,@reasoningTokens,@cacheHit,@fallback,@latencySum,@latencyCount,@ttftSum,@ttftCount)
+    ON CONFLICT(day,model_id) DO UPDATE SET requests=requests+1,successful_requests=successful_requests+excluded.successful_requests,failed_requests=failed_requests+excluded.failed_requests,input_tokens=input_tokens+excluded.input_tokens,output_tokens=output_tokens+excluded.output_tokens,cache_read_tokens=cache_read_tokens+excluded.cache_read_tokens,cache_write_tokens=cache_write_tokens+excluded.cache_write_tokens,reasoning_tokens=reasoning_tokens+excluded.reasoning_tokens,gateway_cache_hits=gateway_cache_hits+excluded.gateway_cache_hits,fallback_requests=fallback_requests+excluded.fallback_requests,latency_success_sum_ms=latency_success_sum_ms+excluded.latency_success_sum_ms,latency_success_count=latency_success_count+excluded.latency_success_count,ttft_sum_ms=ttft_sum_ms+excluded.ttft_sum_ms,ttft_count=ttft_count+excluded.ttft_count`);
+    model.run({ day: request.day, modelId: request.modelId ?? '', success: Number(request.success), inputTokens: request.inputTokens, outputTokens: request.outputTokens, cacheReadTokens: request.cacheReadTokens, cacheWriteTokens: request.cacheWriteTokens, reasoningTokens: request.reasoningTokens, cacheHit: Number(request.cacheHit), fallback: Number(request.attemptsCount > 1), latencySum: request.success ? request.latencyMs : 0, latencyCount: Number(request.success), ttftSum: request.success ? request.ttftMs ?? 0 : 0, ttftCount: Number(request.success && request.ttftMs !== null) });
+    db.prepare(`INSERT INTO daily_api_key_stats (day,api_key_id,requests,successful_requests,failed_requests,input_tokens,output_tokens,total_tokens) VALUES (@day,@apiKeyId,1,@success,1-@success,@inputTokens,@outputTokens,@totalTokens)
+    ON CONFLICT(day,api_key_id) DO UPDATE SET requests=requests+1,successful_requests=successful_requests+excluded.successful_requests,failed_requests=failed_requests+excluded.failed_requests,input_tokens=input_tokens+excluded.input_tokens,output_tokens=output_tokens+excluded.output_tokens,total_tokens=total_tokens+excluded.total_tokens`)
+        .run({ day: request.day, apiKeyId: request.apiKeyId ?? '', success: Number(request.success), inputTokens: request.inputTokens, outputTokens: request.outputTokens, totalTokens: request.inputTokens + request.outputTokens });
+    const provider = db.prepare(`INSERT INTO daily_provider_stats (day,provider_id,attempts,successful_attempts,failed_attempts,input_tokens,output_tokens,cache_read_tokens,cache_write_tokens,reasoning_tokens,latency_success_sum_ms,latency_success_count)
+    VALUES (@day,@providerId,1,@success,1-@success,@inputTokens,@outputTokens,@cacheReadTokens,@cacheWriteTokens,@reasoningTokens,@latencySum,@latencyCount)
+    ON CONFLICT(day,provider_id) DO UPDATE SET attempts=attempts+1,successful_attempts=successful_attempts+excluded.successful_attempts,failed_attempts=failed_attempts+excluded.failed_attempts,input_tokens=input_tokens+excluded.input_tokens,output_tokens=output_tokens+excluded.output_tokens,cache_read_tokens=cache_read_tokens+excluded.cache_read_tokens,cache_write_tokens=cache_write_tokens+excluded.cache_write_tokens,reasoning_tokens=reasoning_tokens+excluded.reasoning_tokens,latency_success_sum_ms=latency_success_sum_ms+excluded.latency_success_sum_ms,latency_success_count=latency_success_count+excluded.latency_success_count`);
+    for (const attempt of attempts)
+        provider.run({ day: attempt.day, providerId: attempt.providerId, success: Number(attempt.success), inputTokens: attempt.inputTokens, outputTokens: attempt.outputTokens, cacheReadTokens: attempt.cacheReadTokens, cacheWriteTokens: attempt.cacheWriteTokens, reasoningTokens: attempt.reasoningTokens, latencySum: attempt.success ? attempt.latencyMs : 0, latencyCount: Number(attempt.success) });
+}

package/dist/server/config/index.js

@@ -14,6 +14,9 @@ const EnvSchema = z.object({
     // Alias used by docs/13 debug tooling: LOG_LEVEL=debug enables lifecycle lines.
     LOG_LEVEL: z.enum(['trace', 'debug', 'info', 'warn', 'error', 'fatal']).optional(),
     LATEDEV_DB_URL: z.string().optional(),
+    // Maximum accepted database-restore upload. Default 256 MiB, matching the operator expectation
+    // that a full forensic backup of a heavily-logged instance still restores.
+    LATEDEV_MAX_BACKUP_UPLOAD_BYTES: z.coerce.number().int().positive().default(256 * 1024 * 1024),
     NODE_ENV: z.enum(['development', 'production', 'test']).default('production'),
 });
 let cached = null;
@@ -49,17 +52,27 @@ export function loadConfig(env = process.env, argv = process.argv) {
         (parsed.NODE_ENV === 'test' ? path.resolve('../.tmp/test-data') : path.resolve(os.homedir(), '.latedev-router'));
     const isContainer = Boolean(env.LATEDEV_DATA_DIR?.startsWith('/data') || process.env.CONTAINER === '1');
     const dbFile = parsed.LATEDEV_DB_URL ?? path.join(dataDir, 'data.sqlite');
+    const restoredMasterKeyPath = path.join(dataDir, 'master.key.restore');
+    let restoredMasterKey = null;
+    try {
+        if (fs.existsSync(restoredMasterKeyPath))
+            restoredMasterKey = fs.readFileSync(restoredMasterKeyPath, 'utf8').trim() || null;
+    }
+    catch {
+        /* ignore unreadable override — use the configured key */
+    }
     cached = {
         host: cliArgs.host ?? parsed.LATEDEV_HOST,
         port: cliArgs.port ?? parsed.LATEDEV_PORT,
         dataDir,
         dbFile,
-        masterKey: parsed.LATEDEV_MASTER_KEY ?? readMasterKeyFile(dataDir),
+        masterKey: restoredMasterKey ?? parsed.LATEDEV_MASTER_KEY ?? readMasterKeyFile(dataDir),
         trustProxyHops: parsed.LATEDEV_TRUST_PROXY,
         logLevel: parsed.LOG_LEVEL ?? parsed.LATEDEV_LOG_LEVEL,
         env: parsed.NODE_ENV,
         isContainer,
         appVersion: getAppVersion(),
+        maxBackupUploadBytes: parsed.LATEDEV_MAX_BACKUP_UPLOAD_BYTES,
     };
     return cached;
 }