@matthesketh/fleet 1.8.0 → 1.11.0

package/dist/core/backup/browser-api.js

@@ -0,0 +1,197 @@
+import { verifyTotp, signSession, verifySession } from './totp.js';
+import { renderLoginPage, renderExplorerPage } from './browser-ui.js';
+import { renderStatusHtml } from './statuspage.js';
+import { classify } from './sensitive.js';
+const SESSION_COOKIE = 'fleet_backup_session';
+function json(status, body, setCookie) {
+    return { kind: 'json', status, body, setCookie };
+}
+function hasSession(req, ctx) {
+    const cookie = req.cookies[SESSION_COOKIE];
+    if (!cookie)
+        return false;
+    return verifySession(cookie, ctx.sessionSecret, ctx.now()) !== null;
+}
+/** /api/* must carry the csrf header, and write methods must carry an
+ *  Origin header whose host matches our domain exactly.
+ *
+ *  the custom `x-fleet-backup: 1` header is the primary barrier — modern
+ *  browsers can't set it cross-origin without preflight, which a same-
+ *  origin policy denies for any host that isn't our own. the Origin check
+ *  is belt-and-braces, and matters specifically for POST / DELETE so the
+ *  endsWith bug (where `evil-${domain}` would have been accepted) is
+ *  closed and a missing Origin on a mutating request is rejected. read
+ *  methods accept a missing Origin so health checks / curl probes keep
+ *  working without the operator having to set an Origin manually. */
+const READ_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+function csrfOk(req, domain) {
+    if (req.headers['x-fleet-backup'] !== '1')
+        return false;
+    const origin = req.headers['origin'];
+    const isWrite = !READ_METHODS.has(req.method.toUpperCase());
+    if (!origin)
+        return !isWrite;
+    let host;
+    try {
+        host = new URL(origin).host;
+    }
+    catch {
+        return false;
+    }
+    return host === domain;
+}
+export function handle(req, ctx) {
+    // public: the login page
+    if (req.path === '/login' && req.method === 'GET') {
+        return { kind: 'html', status: 200, body: renderLoginPage() };
+    }
+    // /api/* — the CSRF + same-origin check runs before auth so a cross-site
+    // probe is rejected (403) without ever reaching the session layer.
+    if (req.path.startsWith('/api/')) {
+        if (!csrfOk(req, ctx.domain))
+            return json(403, { error: 'csrf check failed' });
+        if (req.path === '/api/login' && req.method === 'POST') {
+            const code = req.body?.code ?? '';
+            if (!verifyTotp(ctx.totpSecret, code, ctx.now())) {
+                return json(401, { error: 'invalid code' });
+            }
+            const cookie = signSession({ exp: ctx.now() + ctx.sessionTtlMs }, ctx.sessionSecret);
+            const attrs = `Path=/backups; HttpOnly; Secure; SameSite=Strict; Max-Age=${Math.floor(ctx.sessionTtlMs / 1000)}`;
+            return json(200, { ok: true }, `${SESSION_COOKIE}=${cookie}; ${attrs}`);
+        }
+        if (!hasSession(req, ctx))
+            return json(401, { error: 'not authenticated' });
+        return handleApi(req, ctx);
+    }
+    // every non-api route requires a session
+    if (!hasSession(req, ctx)) {
+        return { kind: 'redirect', status: 302, location: '/backups/login' };
+    }
+    if (req.path === '/' && req.method === 'GET') {
+        return { kind: 'html', status: 200, body: renderStatusHtml(ctx.statusReport()) };
+    }
+    if (req.path === '/explore' && req.method === 'GET') {
+        return { kind: 'html', status: 200, body: renderExplorerPage() };
+    }
+    return json(404, { error: 'not found' });
+}
+const SNAP_RE = /^[0-9a-f]{8,64}$/;
+const INLINE_TYPES = ['text/', 'image/', 'application/pdf', 'application/json'];
+function validPath(p) {
+    if (!p || !p.startsWith('/'))
+        return false;
+    // reject any traversal segment in the raw path — checking a normalised
+    // path is useless here because normalisation collapses `..` away first.
+    return !p.split('/').includes('..');
+}
+/** maps a restic error to 503 when the backend is unreachable, else 500. */
+function resticErrorStatus(message) {
+    return /unreach|connection refused|dial |timeout|no route to host/i.test(message)
+        ? 503
+        : 500;
+}
+function contentTypeFor(path) {
+    const ext = path.slice(path.lastIndexOf('.') + 1).toLowerCase();
+    const map = {
+        txt: 'text/plain', md: 'text/plain', log: 'text/plain', json: 'application/json',
+        js: 'text/plain', ts: 'text/plain', css: 'text/plain', html: 'text/plain',
+        png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif',
+        svg: 'image/svg+xml', pdf: 'application/pdf',
+    };
+    return map[ext] ?? 'application/octet-stream';
+}
+function handleApi(req, ctx) {
+    const { path: route, query } = req;
+    if (route === '/api/apps' && req.method === 'GET') {
+        return json(200, ctx.statusReport());
+    }
+    if (route === '/api/snapshots' && req.method === 'GET') {
+        const app = query.app ?? '';
+        if (!ctx.listApps().includes(app))
+            return json(404, { error: 'unknown app' });
+        return json(200, { snapshots: ctx.snapshots(app) });
+    }
+    if (route === '/api/ls' && req.method === 'GET') {
+        const { app = '', snap = '', path = '/' } = query;
+        if (!ctx.listApps().includes(app))
+            return json(404, { error: 'unknown app' });
+        if (!SNAP_RE.test(snap))
+            return json(400, { error: 'bad snapshot id' });
+        if (!validPath(path))
+            return json(400, { error: 'bad path' });
+        try {
+            // sensitivity is derived from the path itself — no per-entry restic call.
+            const entries = ctx.lsTree(app, snap, path).map(e => ({
+                ...e,
+                sensitive: classify(e.path) === 'sensitive',
+            }));
+            return json(200, { path, entries });
+        }
+        catch (e) {
+            const msg = e.message;
+            return json(resticErrorStatus(msg), { error: msg });
+        }
+    }
+    if (route === '/api/staging' && req.method === 'GET') {
+        return json(200, { staging: ctx.listStaging() });
+    }
+    if (route === '/api/restore' && req.method === 'POST') {
+        const b = (req.body ?? {});
+        const app = b.app ?? '';
+        const snap = b.snap ?? '';
+        const path = b.path ?? '';
+        if (!ctx.listApps().includes(app))
+            return json(404, { error: 'unknown app' });
+        if (!SNAP_RE.test(snap))
+            return json(400, { error: 'bad snapshot id' });
+        if (!validPath(path))
+            return json(400, { error: 'bad path' });
+        try {
+            return json(200, ctx.restore(app, snap, path));
+        }
+        catch (e) {
+            const msg = e.message;
+            // doRestore throws a code-507 error when staging space is short
+            const status = e.code === 507 ? 507 : 500;
+            return json(status, { error: msg });
+        }
+    }
+    if (route === '/api/staging' && req.method === 'DELETE') {
+        const p = query.path ?? '';
+        if (!p.startsWith('/var/restore/') || p.includes('..')) {
+            return json(400, { error: 'bad staging path' });
+        }
+        try {
+            ctx.deleteStaging(p);
+            return json(200, { ok: true });
+        }
+        catch (e) {
+            return json(500, { error: e.message });
+        }
+    }
+    if (route === '/api/file' && req.method === 'GET') {
+        const { app = '', snap = '', path = '', dl } = query;
+        if (!ctx.listApps().includes(app))
+            return json(404, { error: 'unknown app' });
+        if (!SNAP_RE.test(snap))
+            return json(400, { error: 'bad snapshot id' });
+        if (!validPath(path))
+            return json(400, { error: 'bad path' });
+        const meta = ctx.fileMeta(app, snap, path);
+        if (!meta)
+            return json(404, { error: 'file not found' });
+        if (meta.sensitive)
+            return json(403, { error: 'sensitive path — view/download blocked' });
+        const filename = path.slice(path.lastIndexOf('/') + 1);
+        const ct = contentTypeFor(path);
+        const inlineable = INLINE_TYPES.some(t => ct.startsWith(t)) && meta.size <= 5 * 1024 * 1024;
+        return {
+            kind: 'stream',
+            status: 200,
+            app, snap, path, filename,
+            contentType: ct,
+            disposition: dl === '1' || !inlineable ? 'attachment' : 'inline',
+        };
+    }
+    return json(404, { error: 'not found' });
+}

package/dist/core/backup/browser-server.d.ts

@@ -0,0 +1,11 @@
+import { Server } from 'node:http';
+export interface ServeOptions {
+    port: number;
+    totpSecret: string;
+    sessionSecret: string;
+    sessionTtlMs?: number;
+    stagingRoot?: string;
+}
+/** starts the explorer http service, resolving once it is bound. the socket
+ *  is localhost-only (nginx fronts it). */
+export declare function startServer(opts: ServeOptions): Promise<Server>;

package/dist/core/backup/browser-server.js

@@ -0,0 +1,241 @@
+import { existsSync, mkdirSync, statfsSync, readdirSync, statSync, rmSync, appendFileSync, } from 'node:fs';
+import { createServer } from 'node:http';
+import { loadOperator } from '../operator.js';
+import { handle } from './browser-api.js';
+import { listConfiguredApps } from './config.js';
+import { listSnapshots, lsTree, dumpFileSpawn, restore } from './repo.js';
+import { classify } from './sensitive.js';
+import { buildStatusReport } from './status.js';
+const MAX_INFLIGHT = 4;
+let inFlight = 0;
+const AUDIT_LOG = '/var/log/fleet-backup/audit.log';
+/** appends a structured audit line to journald (via stdout) and a log file. */
+function audit(action, detail) {
+    const line = JSON.stringify({ ts: new Date().toISOString(), action, ...detail });
+    // stdout is captured by journald when run as a systemd unit
+    process.stdout.write(`[audit] ${line}\n`);
+    try {
+        appendFileSync(AUDIT_LOG, line + '\n');
+    }
+    catch {
+        /* best effort — never fail a request because the audit file is unwritable */
+    }
+}
+/** recursive byte size of a directory tree. */
+function dirSize(dir) {
+    let total = 0;
+    for (const name of readdirSync(dir)) {
+        const full = `${dir}/${name}`;
+        const st = statSync(full);
+        total += st.isDirectory() ? dirSize(full) : st.size;
+    }
+    return total;
+}
+function humanAge(mtimeMs) {
+    const h = Math.floor((Date.now() - mtimeMs) / 3600_000);
+    return h < 24 ? `${h}h` : `${Math.floor(h / 24)}d`;
+}
+const STAGING_ROOT_DEFAULT = '/var/restore';
+function parseCookies(header) {
+    const out = {};
+    for (const part of (header ?? '').split(';')) {
+        const i = part.indexOf('=');
+        if (i > 0)
+            out[part.slice(0, i).trim()] = part.slice(i + 1).trim();
+    }
+    return out;
+}
+const MAX_BODY_BYTES = 1_000_000;
+function readBody(req) {
+    return new Promise(resolve => {
+        const chunks = [];
+        let size = 0;
+        let aborted = false;
+        req.on('data', c => {
+            if (aborted)
+                return;
+            size += c.length;
+            if (size > MAX_BODY_BYTES) {
+                // cut the slow-loris off at the wire — keeping `req.on('data')`
+                // running for gigabytes just to drop chunks past the cap pins
+                // the handler open and gives the attacker a free socket.
+                aborted = true;
+                req.destroy();
+                resolve(undefined);
+                return;
+            }
+            chunks.push(c);
+        });
+        req.on('end', () => {
+            if (aborted)
+                return;
+            if (chunks.length === 0) {
+                resolve(undefined);
+                return;
+            }
+            try {
+                resolve(JSON.parse(Buffer.concat(chunks).toString('utf-8')));
+            }
+            catch {
+                resolve(undefined);
+            }
+        });
+        req.on('error', () => { if (!aborted)
+            resolve(undefined); });
+    });
+}
+/** restores a single path into a fresh timestamped staging dir. */
+function doRestore(app, snap, path, stagingRoot) {
+    const ts = new Date().toISOString().replace(/[:.]/g, '').slice(0, 15);
+    const target = `${stagingRoot}/${app}-${snap.slice(0, 8)}-${ts}`;
+    // pre-flight: refuse if the filesystem is nearly full
+    const fs = statfsSync(stagingRoot);
+    if (fs.bavail * fs.bsize < 64 * 1024 * 1024) {
+        const e = new Error('insufficient staging space');
+        e.code = 507;
+        throw e;
+    }
+    mkdirSync(target, { recursive: true, mode: 0o700 });
+    const started = Date.now();
+    restore(app, { snapshotId: snap, target, include: [path] });
+    return { target, fileCount: 1, bytes: 0, durationMs: Date.now() - started };
+}
+function buildContext(opts) {
+    const stagingRoot = opts.stagingRoot ?? STAGING_ROOT_DEFAULT;
+    return {
+        now: () => Date.now(),
+        totpSecret: opts.totpSecret,
+        sessionSecret: opts.sessionSecret,
+        sessionTtlMs: opts.sessionTtlMs ?? 12 * 3600_000,
+        domain: loadOperator().domain,
+        listApps: () => listConfiguredApps(),
+        statusReport: () => buildStatusReport(),
+        snapshots: app => listSnapshots(app),
+        lsTree: (app, snap, path) => lsTree(app, snap, path),
+        fileMeta: (app, snap, path) => {
+            // size comes from the parent dir listing; sensitivity from the classifier.
+            const parent = path.slice(0, path.lastIndexOf('/')) || '/';
+            const entry = lsTree(app, snap, parent).find(e => e.path === path);
+            if (!entry)
+                return null;
+            return { size: entry.size, sensitive: classify(path) === 'sensitive' };
+        },
+        restore: (app, snap, path) => doRestore(app, snap, path, stagingRoot),
+        listStaging: () => {
+            if (!existsSync(stagingRoot))
+                return [];
+            return readdirSync(stagingRoot)
+                .map(name => `${stagingRoot}/${name}`)
+                .filter(p => statSync(p).isDirectory())
+                .map(p => ({ path: p, bytes: dirSize(p), age: humanAge(statSync(p).mtimeMs) }));
+        },
+        deleteStaging: (path) => {
+            if (!path.startsWith(stagingRoot + '/')) {
+                throw new Error('refusing to delete outside the staging root');
+            }
+            rmSync(path, { recursive: true, force: true });
+        },
+    };
+}
+function sendResponse(httpRes, apiRes) {
+    if (apiRes.kind === 'json') {
+        const headers = { 'Content-Type': 'application/json' };
+        if (apiRes.setCookie)
+            headers['Set-Cookie'] = apiRes.setCookie;
+        httpRes.writeHead(apiRes.status, headers);
+        httpRes.end(JSON.stringify(apiRes.body));
+        return;
+    }
+    if (apiRes.kind === 'html') {
+        httpRes.writeHead(apiRes.status, { 'Content-Type': 'text/html; charset=utf-8' });
+        httpRes.end(apiRes.body);
+        return;
+    }
+    if (apiRes.kind === 'redirect') {
+        httpRes.writeHead(apiRes.status, { Location: apiRes.location });
+        httpRes.end();
+        return;
+    }
+    // stream: pipe `restic dump` straight to the response
+    const child = dumpFileSpawn(apiRes.app, apiRes.snap, apiRes.path);
+    // strip CR / LF / NUL / other control chars in addition to quotes —
+    // filenames live inside restic-tracked content, so the operator can
+    // restore a path whose basename contains \r\n and inject arbitrary
+    // response headers if we only quote-strip.
+    // eslint-disable-next-line no-control-regex
+    const safeFilename = apiRes.filename.replace(/[\r\n\x00-\x1F"\\]/g, '');
+    httpRes.writeHead(apiRes.status, {
+        'Content-Type': apiRes.contentType,
+        'Content-Disposition': `${apiRes.disposition}; filename="${safeFilename}"`,
+    });
+    child.stdout.pipe(httpRes);
+    child.stderr.on('data', () => { });
+    child.on('error', () => { if (!httpRes.headersSent)
+        httpRes.writeHead(500); httpRes.end(); });
+    child.on('close', code => { if (code !== 0)
+        httpRes.end(); });
+}
+/** starts the explorer http service, resolving once it is bound. the socket
+ *  is localhost-only (nginx fronts it). */
+export function startServer(opts) {
+    const ctx = buildContext(opts);
+    const stagingRoot = opts.stagingRoot ?? STAGING_ROOT_DEFAULT;
+    if (!existsSync(stagingRoot))
+        mkdirSync(stagingRoot, { recursive: true, mode: 0o700 });
+    const server = createServer(async (httpReq, httpRes) => {
+        try {
+            const url = new URL(httpReq.url ?? '/', 'http://localhost');
+            // soft concurrency cap on the heavy routes (streaming a file, running a
+            // restore) — refuse rather than fork unbounded restic processes.
+            const heavy = url.pathname === '/api/file' || url.pathname === '/api/restore';
+            if (heavy) {
+                if (inFlight >= MAX_INFLIGHT) {
+                    httpRes.writeHead(429, { 'Content-Type': 'application/json' });
+                    httpRes.end(JSON.stringify({ error: 'too many concurrent operations' }));
+                    return;
+                }
+                inFlight++;
+                httpRes.on('close', () => { inFlight--; });
+            }
+            const query = {};
+            url.searchParams.forEach((v, k) => { query[k] = v; });
+            const headers = {};
+            for (const [k, v] of Object.entries(httpReq.headers)) {
+                if (typeof v === 'string')
+                    headers[k.toLowerCase()] = v;
+            }
+            const apiReq = {
+                method: httpReq.method ?? 'GET',
+                path: url.pathname,
+                query,
+                headers,
+                cookies: parseCookies(httpReq.headers['cookie']),
+                body: httpReq.method === 'POST' ? await readBody(httpReq) : undefined,
+            };
+            const apiRes = handle(apiReq, ctx);
+            // audit the security-relevant actions (view/download, restore, delete).
+            if (apiRes.status < 400) {
+                if (url.pathname === '/api/file') {
+                    audit('view', { app: query.app, snap: query.snap, path: query.path, dl: query.dl === '1' });
+                }
+                else if (url.pathname === '/api/restore') {
+                    const b = (apiReq.body ?? {});
+                    audit('restore', { app: b.app, snap: b.snap, path: b.path });
+                }
+                else if (url.pathname === '/api/staging' && apiReq.method === 'DELETE') {
+                    audit('staging-delete', { path: query.path });
+                }
+            }
+            sendResponse(httpRes, apiRes);
+        }
+        catch (e) {
+            if (!httpRes.headersSent)
+                httpRes.writeHead(500, { 'Content-Type': 'application/json' });
+            httpRes.end(JSON.stringify({ error: e.message }));
+        }
+    });
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(opts.port, '127.0.0.1', () => resolve(server));
+    });
+}

package/dist/core/backup/browser-ui.d.ts

@@ -0,0 +1,5 @@
+/** server-rendered html for the backup explorer. self-contained — inline
+ *  css + vanilla js, no build step, no external assets. all routes are
+ *  served under the /backups/ prefix by nginx. */
+export declare function renderLoginPage(): string;
+export declare function renderExplorerPage(): string;