libre-webui 0.26.0 → 0.27.0

package/backend/dist/services/recoveryDrillService.js

@@ -0,0 +1,363 @@
+/*
+ * Libre WebUI
+ * Copyright (C) 2025 Kroonen AI, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at:
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Scheduled verified recovery drills (RECOVERY-01).
+ *
+ * A drill proves the instance is actually recoverable, end to end, with the
+ * same signed/encrypted pipeline operators use for real backups:
+ *
+ *   1. Stage a quiescent copy of the data directory (SQLite through the
+ *      online backup API, blobs and files by physical copy).
+ *   2. Create a signed, encrypted archive from the staged copy with
+ *      ephemeral drill keys, running the full recovery inventory.
+ *   3. Verify the archive, restore it into an isolated temporary target,
+ *      and verify the restored environment again.
+ *   4. Record measured timings — restore duration is the demonstrated RTO,
+ *      and the spacing between successful drills bounds the achievable RPO
+ *      of the current schedule — then delete every artifact.
+ *
+ * Drills are verification, not backups: nothing is retained. They run only
+ * on the solo (SQLite) profile, under a coordinator lease so replicas and
+ * overlapping ticks cannot double-run, and only while no other durable job
+ * is mid-flight — the same quiescence rule the recovery inventory enforces.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { getPersistence, getSQLiteAdapterDatabase, } from '../persistence/index.js';
+import { encryptionService } from './encryptionService.js';
+import { getCoordinator } from '../platform/coordination/service.js';
+import { resolveDataDirectory } from '../utils/dataDirectory.js';
+import { createBackupArchive, generateBackupKeys, restoreBackupArchive, verifyBackupArchive, verifyRestoredBackup, } from '../platform/recovery/index.js';
+import { createLogger } from '../utils/logger.js';
+const logger = createLogger('services:recovery-drill');
+const LEASE_KEY = 'recovery-drill';
+const LEASE_TTL_MS = 30 * 60 * 1000;
+/** A running drill older than this was interrupted (crash/restart). */
+const STALE_RUNNING_MS = 60 * 60 * 1000;
+const DEFAULT_HISTORY_LIMIT = 60;
+const LIST_LIMIT = 50;
+const repositories = () => getPersistence(encryptionService).repositories.resources;
+export class RecoveryDrillError extends Error {
+    constructor(message, statusCode = 400) {
+        super(message);
+        this.statusCode = statusCode;
+    }
+}
+const historyLimit = () => {
+    const parsed = Number.parseInt(process.env.RECOVERY_DRILL_HISTORY || '', 10);
+    return Number.isInteger(parsed) && parsed >= 5 && parsed <= 1000
+        ? parsed
+        : DEFAULT_HISTORY_LIMIT;
+};
+export const drillIntervalHours = () => {
+    const parsed = Number.parseFloat(process.env.RECOVERY_DRILL_INTERVAL_HOURS || '');
+    return Number.isFinite(parsed) && parsed >= 1 ? parsed : null;
+};
+/** Drills stage a filesystem snapshot; the team profile has its own CLI. */
+export const drillsSupported = () => {
+    const env = process.env;
+    return !(env.LIBRE_PLATFORM_MODE?.trim().toLowerCase() === 'team' ||
+        env.DATABASE_BACKEND?.trim().toLowerCase() === 'postgres' ||
+        env.BLOB_STORE_BACKEND?.trim().toLowerCase() === 's3' ||
+        env.VECTOR_STORE_BACKEND?.trim().toLowerCase() === 'pgvector');
+};
+const decryptReport = (value) => {
+    if (!value)
+        return null;
+    try {
+        return JSON.parse(encryptionService.decryptAuthenticated(value));
+    }
+    catch {
+        return null;
+    }
+};
+const toPublic = (record) => ({
+    id: record.id,
+    status: record.status,
+    origin: record.origin,
+    startedAt: record.started_at,
+    finishedAt: record.finished_at,
+    snapshotBytes: record.snapshot_bytes,
+    rpoSeconds: record.rpo_seconds,
+    restoreMs: record.restore_ms,
+    error: record.error,
+    report: decryptReport(record.report),
+});
+export const listDrills = async () => (await repositories().recoveryDrills.list(LIST_LIMIT)).map(toPublic);
+const notifyAdminsOfFailure = async (drillId, message) => {
+    try {
+        const [{ userModel }, { notificationService }] = await Promise.all([
+            import('../models/userModel.js'),
+            import('./notificationService.js'),
+        ]);
+        const admins = (await userModel.getAllUsers()).filter(user => user.role === 'admin' && user.status === 'active');
+        for (const admin of admins) {
+            await notificationService.publish({
+                userId: admin.id,
+                type: 'system',
+                title: 'Recovery drill failed',
+                body: message,
+                href: '/system',
+                sourceKey: `recovery-drill-failed:${drillId}`,
+            });
+        }
+    }
+    catch (error) {
+        logger.warn('Recovery drill failure notification did not send', { error });
+    }
+};
+/** Copy the data directory, leaving the live SQLite files for the backup API. */
+const stageDataDirectory = async (dataDir, staging) => {
+    fs.mkdirSync(staging, { recursive: true, mode: 0o700 });
+    const skip = new Set(['data.sqlite', 'data.sqlite-wal', 'data.sqlite-shm']);
+    for (const entry of fs.readdirSync(dataDir)) {
+        if (skip.has(entry))
+            continue;
+        fs.cpSync(path.join(dataDir, entry), path.join(staging, entry), {
+            recursive: true,
+            errorOnExist: true,
+            force: false,
+        });
+    }
+    // The online backup API yields a consistent snapshot of a live database
+    // without stopping writers — the reason drills need no downtime.
+    await getSQLiteAdapterDatabase().backup(path.join(staging, 'data.sqlite'));
+};
+const runningDurableJobs = () => {
+    // The drill runs outside the durable-job system precisely so its own
+    // execution never appears here: any running row is real in-flight work
+    // that would land mid-write in the snapshot. The archive's recovery
+    // inventory re-checks this on the staged copy and remains authoritative.
+    try {
+        const row = getSQLiteAdapterDatabase()
+            .prepare("SELECT COUNT(*) AS count FROM platform_jobs WHERE state = 'running'")
+            .get();
+        return row.count;
+    }
+    catch {
+        return 0;
+    }
+};
+/**
+ * Run one full drill. Returns the recorded drill, or null when it was
+ * skipped without recording (lease held elsewhere, or busy on a scheduled
+ * run).
+ */
+export const runDrill = async (options) => {
+    if (!drillsSupported()) {
+        throw new RecoveryDrillError('Recovery drills run on the solo (SQLite) profile; the team profile uses the coordinated backup CLI', 501);
+    }
+    const lease = await getCoordinator().acquireLease(LEASE_KEY, LEASE_TTL_MS);
+    if (!lease) {
+        if (options.origin === 'manual') {
+            throw new RecoveryDrillError('A recovery drill is already running', 409);
+        }
+        return null;
+    }
+    const now = Date.now();
+    const drills = repositories().recoveryDrills;
+    try {
+        const running = await drills.findRunning();
+        if (running) {
+            if (now - running.started_at > STALE_RUNNING_MS) {
+                await drills.update(running.id, {
+                    status: 'failed',
+                    finished_at: now,
+                    error: 'The drill was interrupted by a restart',
+                });
+            }
+            else if (options.origin === 'manual') {
+                throw new RecoveryDrillError('A recovery drill is already running', 409);
+            }
+            else {
+                return null;
+            }
+        }
+        const previous = await drills.findLatestFinished();
+        const record = {
+            id: randomUUID(),
+            status: 'running',
+            origin: options.origin,
+            started_at: now,
+            finished_at: null,
+            snapshot_bytes: null,
+            rpo_seconds: null,
+            restore_ms: null,
+            error: null,
+            report: null,
+            created_by: options.createdBy ?? null,
+            created_at: now,
+        };
+        await drills.insert(record);
+        const workDir = fs.mkdtempSync(path.join(os.tmpdir(), 'libre-drill-'));
+        try {
+            const busy = runningDurableJobs();
+            if (busy > 0) {
+                const message = `${busy} durable job(s) were running; the drill needs a quiet moment and will retry`;
+                if (options.origin === 'scheduled' && !options.recordBusyAsFailure) {
+                    await drills.update(record.id, {
+                        status: 'failed',
+                        finished_at: Date.now(),
+                        error: message,
+                    });
+                    // Scheduled busy-skips are unremarkable: no admin alert, and the
+                    // interval clock restarts so the next tick can try again.
+                    return toPublic({
+                        ...record,
+                        status: 'failed',
+                        finished_at: Date.now(),
+                        error: message,
+                    });
+                }
+                throw new RecoveryDrillError(message, 409);
+            }
+            const dataDir = resolveDataDirectory();
+            const staging = path.join(workDir, 'staging');
+            const snapshotStarted = Date.now();
+            await stageDataDirectory(dataDir, staging);
+            const keys = generateBackupKeys(path.join(workDir, 'keys'));
+            const archivePath = path.join(workDir, 'drill.lwbackup');
+            await createBackupArchive({
+                dataDir: staging,
+                outputPath: archivePath,
+                encryptionKeyPath: keys.encryptionKeyPath,
+                signingPrivateKeyPath: keys.signingPrivateKeyPath,
+                offline: true,
+            });
+            const snapshotMs = Date.now() - snapshotStarted;
+            const archiveBytes = fs.statSync(archivePath).size;
+            const verifyStarted = Date.now();
+            const verification = verifyBackupArchive({
+                archivePath,
+                signingPublicKeyPath: keys.signingPublicKeyPath,
+                encryptionKeyPath: keys.encryptionKeyPath,
+            });
+            if (!verification.signatureVerified || !verification.payloadVerified) {
+                throw new Error('The drill archive failed verification');
+            }
+            const verifyMs = Date.now() - verifyStarted;
+            const restoreStarted = Date.now();
+            const restoreTarget = path.join(workDir, 'restore');
+            await restoreBackupArchive({
+                archivePath,
+                signingPublicKeyPath: keys.signingPublicKeyPath,
+                encryptionKeyPath: keys.encryptionKeyPath,
+                targetDirectory: restoreTarget,
+                apply: true,
+            });
+            const restoreMs = Date.now() - restoreStarted;
+            const restoreVerifyStarted = Date.now();
+            await verifyRestoredBackup(restoreTarget);
+            const restoreVerifyMs = Date.now() - restoreVerifyStarted;
+            const report = {
+                snapshotMs,
+                archiveBytes,
+                verifyMs,
+                restoreMs,
+                restoreVerifyMs,
+            };
+            const finishedAt = Date.now();
+            const rpoSeconds = previous?.status === 'passed'
+                ? Math.round((now - previous.started_at) / 1000)
+                : null;
+            await drills.update(record.id, {
+                status: 'passed',
+                finished_at: finishedAt,
+                snapshot_bytes: archiveBytes,
+                rpo_seconds: rpoSeconds,
+                restore_ms: restoreMs,
+                report: encryptionService.encrypt(JSON.stringify(report)),
+            });
+            await drills.pruneToLimit(historyLimit());
+            logger.info('Recovery drill passed', {
+                drillId: record.id,
+                restoreMs,
+                archiveBytes,
+            });
+            return toPublic({
+                ...record,
+                status: 'passed',
+                finished_at: finishedAt,
+                snapshot_bytes: archiveBytes,
+                rpo_seconds: rpoSeconds,
+                restore_ms: restoreMs,
+                report: encryptionService.encrypt(JSON.stringify(report)),
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Recovery drill failed';
+            await drills.update(record.id, {
+                status: 'failed',
+                finished_at: Date.now(),
+                error: message.slice(0, 500),
+            });
+            // Interactive refusals (busy, already running) answered the caller
+            // directly; the bell alert is for drills failing unattended.
+            if (!(error instanceof RecoveryDrillError)) {
+                await notifyAdminsOfFailure(record.id, message.slice(0, 500));
+            }
+            logger.warn('Recovery drill failed', { drillId: record.id, message });
+            if (error instanceof RecoveryDrillError)
+                throw error;
+            return toPublic({
+                ...(await drills.findById(record.id)),
+            });
+        }
+        finally {
+            fs.rmSync(workDir, { recursive: true, force: true });
+        }
+    }
+    finally {
+        await lease.release().catch(() => false);
+    }
+};
+let sweepInFlight = false;
+/**
+ * Scheduler-lease sweep: start a drill when the configured interval has
+ * elapsed since the last one (any outcome, so a failing instance does not
+ * hammer itself). Fire-and-forget; the drill lease serializes execution.
+ */
+export const sweepDrills = async (now) => {
+    const interval = drillIntervalHours();
+    if (!interval || !drillsSupported() || sweepInFlight)
+        return false;
+    const drills = repositories().recoveryDrills;
+    const latest = await drills.list(1);
+    const last = latest[0];
+    if (last && now - last.started_at < interval * 60 * 60 * 1000) {
+        return false;
+    }
+    sweepInFlight = true;
+    void runDrill({ origin: 'scheduled' })
+        .catch(error => {
+        logger.warn('Scheduled recovery drill errored', { error });
+    })
+        .finally(() => {
+        sweepInFlight = false;
+    });
+    return true;
+};
+export default {
+    runDrill,
+    sweepDrills,
+    listDrills,
+    drillsSupported,
+    drillIntervalHours,
+};
+//# sourceMappingURL=recoveryDrillService.js.map

package/backend/dist/services/recoveryDrillService.js.map

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

package/backend/dist/services/webPushService.d.ts

@@ -0,0 +1,71 @@
+import type { StoredPushSubscriptionRecord } from '../persistence/resourceTypes.js';
+export declare class WebPushError extends Error {
+    readonly statusCode: number;
+    constructor(message: string, statusCode?: number);
+}
+/** The endpoint acknowledged but the subscription no longer exists. */
+export declare class PushSubscriptionGoneError extends Error {
+}
+export interface PushSubscriptionKeys {
+    endpoint: string;
+    keys: {
+        p256dh: string;
+        auth: string;
+    };
+}
+interface VapidKeys {
+    /** base64url uncompressed P-256 point (65 bytes). */
+    publicKey: string;
+    /** base64url raw private scalar (32 bytes). */
+    privateKey: string;
+}
+export declare const getVapidKeys: () => Promise<VapidKeys>;
+export declare const getVapidPublicKey: () => Promise<string>;
+/** RFC 8292 VAPID JWT for one push-service origin. */
+export declare const buildVapidAuthorization: (endpointOrigin: string) => Promise<string>;
+export interface EncryptParams {
+    /** Test hook: fixed ephemeral private key (32-byte scalar). */
+    ephemeralPrivateKey?: Buffer;
+    /** Test hook: fixed 16-byte salt. */
+    salt?: Buffer;
+}
+/**
+ * Encrypt one push message with aes128gcm content encoding. Returns the
+ * complete request body (header block + single record).
+ */
+export declare const encryptPushPayload: (userAgentPublicKey: Buffer, authSecret: Buffer, plaintext: Buffer, params?: EncryptParams) => Buffer;
+export interface PublicPushSubscription {
+    id: string;
+    createdAt: number;
+    lastUsedAt: number | null;
+    current: boolean;
+}
+export declare const subscribe: (userId: string, sessionId: string | null, input: {
+    endpoint?: unknown;
+    keys?: {
+        p256dh?: unknown;
+        auth?: unknown;
+    };
+}, userAgent: string | null) => Promise<{
+    id: string;
+}>;
+export declare const unsubscribe: (userId: string, endpoint: string) => Promise<boolean>;
+export declare const listSubscriptionsForUser: (userId: string) => Promise<StoredPushSubscriptionRecord[]>;
+export interface PushMessage {
+    title: string;
+    body?: string;
+    href?: string;
+    type?: string;
+}
+/**
+ * Deliver one message to one stored subscription. Returns false (and
+ * removes the row) when the push service reports the subscription gone.
+ */
+export declare const deliverToSubscription: (subscriptionId: string, message: PushMessage, signal?: AbortSignal) => Promise<{
+    delivered: boolean;
+    status?: number;
+}>;
+/** Remove device subscriptions when their auth session is revoked. */
+export declare const registerPushSessionCleanup: () => void;
+export {};
+//# sourceMappingURL=webPushService.d.ts.map

package/backend/dist/services/webPushService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webPushService.d.ts","sourceRoot":"","sources":["../../src/services/webPushService.ts"],"names":[],"mappings":"AAuDA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,iCAAiC,CAAC;AAYpF,qBAAa,YAAa,SAAQ,KAAK;aAGnB,UAAU;IAF5B,YACE,OAAO,EAAE,MAAM,EACC,UAAU,SAAM,EAGjC;CACF;AAED,uEAAuE;AACvE,qBAAa,yBAA0B,SAAQ,KAAK;CAAG;AAEvD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACxC;AAID,UAAU,SAAS;IACjB,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;CACpB;AA2BD,eAAO,MAAM,YAAY,QAAa,OAAO,CAAC,SAAS,CAqCtD,CAAC;AAEF,eAAO,MAAM,iBAAiB,QAAa,OAAO,CAAC,MAAM,CACvB,CAAC;AAoBnC,sDAAsD;AACtD,eAAO,MAAM,uBAAuB,mBAClB,MAAM,KACrB,OAAO,CAAC,MAAM,CAchB,CAAC;AAIF,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,qCAAqC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB,uBACT,MAAM,cACd,MAAM,aACP,MAAM,WACT,aAAa,KACpB,MAkEF,CAAC;AA6CF,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,eAAO,MAAM,SAAS,WACZ,MAAM,aACH,MAAM,GAAG,IAAI,SACjB;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;CAAE,aAC/D,MAAM,GAAG,IAAI,KACvB,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAqCxB,CAAC;AAEF,eAAO,MAAM,WAAW,WACd,MAAM,YACJ,MAAM,KACf,OAAO,CAAC,OAAO,CAIf,CAAC;AAEJ,eAAO,MAAM,wBAAwB,WAC3B,MAAM,KACb,OAAO,CAAC,4BAA4B,EAAE,CACY,CAAC;AAwBtD,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,mBAChB,MAAM,WACb,WAAW,WACX,WAAW,KACnB,OAAO,CAAC;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CA6CjD,CAAC;AAMF,sEAAsE;AACtE,eAAO,MAAM,0BAA0B,QAAO,IAgB7C,CAAC"}