@matthesketh/fleet 1.8.1 → 1.11.1

package/dist/core/backup/schedule.js

@@ -0,0 +1,90 @@
+import { writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { FleetError } from '../errors.js';
+import { execSafe } from '../exec.js';
+export const SYSTEMD_UNIT_DIR = process.env.FLEET_SYSTEMD_UNIT_DIR ?? '/etc/systemd/system';
+function onCalendarFor(schedule) {
+    if (schedule === 'hourly')
+        return 'hourly';
+    if (schedule === 'daily')
+        return 'daily';
+    if (schedule === 'weekly')
+        return 'weekly';
+    return schedule;
+}
+export function timerUnitName(app) {
+    return `fleet-backup@${app}.timer`;
+}
+export function serviceUnitName(app) {
+    return `fleet-backup@${app}.service`;
+}
+/** plans the timer + service units. returns the unit file contents so callers
+ *  can show a dry-run. set apply=true to actually write+enable. */
+export function installScheduleUnits(app, schedule, opts = {}) {
+    const sharedServicePath = join(SYSTEMD_UNIT_DIR, 'fleet-backup@.service');
+    const sharedServiceContent = sharedServiceUnit();
+    const timerPath = join(SYSTEMD_UNIT_DIR, timerUnitName(app));
+    const timerContent = perAppTimerUnit(app, schedule);
+    const sharedServiceWrote = !existsSync(sharedServicePath);
+    if (!opts.apply) {
+        return { timerPath, timerContent, sharedServicePath, sharedServiceContent, sharedServiceWrote };
+    }
+    if (!existsSync(SYSTEMD_UNIT_DIR)) {
+        mkdirSync(SYSTEMD_UNIT_DIR, { recursive: true });
+    }
+    if (sharedServiceWrote) {
+        writeFileSync(sharedServicePath, sharedServiceContent, { mode: 0o644 });
+    }
+    writeFileSync(timerPath, timerContent, { mode: 0o644 });
+    const reload = execSafe('systemctl', ['daemon-reload'], { timeout: 5_000 });
+    if (!reload.ok)
+        throw new FleetError(`systemctl daemon-reload failed: ${reload.stderr}`);
+    const enable = execSafe('systemctl', ['enable', '--now', timerUnitName(app)], { timeout: 5_000 });
+    if (!enable.ok)
+        throw new FleetError(`enable timer failed: ${enable.stderr}`);
+    return { timerPath, timerContent, sharedServicePath, sharedServiceContent, sharedServiceWrote };
+}
+export function disableSchedule(app) {
+    execSafe('systemctl', ['disable', '--now', timerUnitName(app)], { timeout: 5_000 });
+}
+function sharedServiceUnit() {
+    // the wrapper loads the rest backend url (with embedded user:pass) from
+    // systemd-creds (host-key sealed at rest) and exports it as
+    // FLEET_BACKUP_BASE_URL. fleet writes via the append-only rest backend.
+    // legacy sftp backend still works if the wrapper / credstore entry are
+    // absent.
+    return `[Unit]
+Description=fleet backup for %i
+Documentation=fleet backup --help
+After=network-online.target docker.service wg-quick@wg0.service
+Wants=network-online.target wg-quick@wg0.service
+
+[Service]
+Type=oneshot
+LoadCredentialEncrypted=mx-url:/etc/credstore.encrypted/mx-url
+ExecStart=/usr/local/sbin/fleet-backup-wrapper %i
+# big snapshots (multi-gb dumps) need headroom; default 90s would kill them.
+TimeoutStartSec=4h
+TimeoutStopSec=5min
+Nice=10
+IOSchedulingClass=best-effort
+IOSchedulingPriority=7
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+function perAppTimerUnit(app, schedule) {
+    return `[Unit]
+Description=fleet backup timer for ${app}
+
+[Timer]
+OnCalendar=${onCalendarFor(schedule)}
+Persistent=true
+RandomizedDelaySec=10m
+Unit=${serviceUnitName(app)}
+
+[Install]
+WantedBy=timers.target
+`;
+}

package/dist/core/backup/sensitive.d.ts

@@ -0,0 +1,5 @@
+/** classifies a snapshot-relative path as holding secret material or not.
+ *  used by the backup explorer to refuse view/download of sensitive files
+ *  while still allowing them to be restored to a staging dir. */
+export type Sensitivity = 'sensitive' | 'normal';
+export declare function classify(path: string): Sensitivity;

package/dist/core/backup/sensitive.js

@@ -0,0 +1,37 @@
+/** classifies a snapshot-relative path as holding secret material or not.
+ *  used by the backup explorer to refuse view/download of sensitive files
+ *  while still allowing them to be restored to a staging dir. */
+// matched case-insensitively against the full path.
+const SENSITIVE_PATTERNS = [
+    // key material
+    /\/\.ssh\//,
+    /\/\.gnupg\//,
+    /^\/etc\/ssh\//,
+    /^\/etc\/letsencrypt\//,
+    /\.pem$/,
+    /\.key$/,
+    // cloud + credential stores
+    /\/\.aws\//,
+    /\/\.gcloud\//,
+    /\/\.azure\//,
+    /\/\.kube\//,
+    /\/\.docker\//,
+    /\/\.secrets\//,
+    /\/credentials/,
+    /\/\.token/,
+    /\/\.npmrc$/,
+    /\/\.git-credentials$/,
+    // fleet + agent secrets
+    /\/\.claude/,
+    /^\/var\/lib\/fleet\//,
+    // database dumps
+    /\.pg\.sql$/,
+    /\.mysql\.sql$/,
+    /\.mongo\.archive$/,
+    /\.rdb$/,
+    /\.sql$/,
+];
+export function classify(path) {
+    const p = path.toLowerCase();
+    return SENSITIVE_PATTERNS.some(re => re.test(p)) ? 'sensitive' : 'normal';
+}

package/dist/core/backup/status.d.ts

@@ -0,0 +1,3 @@
+import { StatusReport } from './statuspage.js';
+/** gathers per-app snapshot counts, last-snapshot time and repo size. */
+export declare function buildStatusReport(): StatusReport;

package/dist/core/backup/status.js

@@ -0,0 +1,29 @@
+import { listConfiguredApps, loadConfig } from './config.js';
+import { listSnapshots, stats, isAppendOnly } from './repo.js';
+/** gathers per-app snapshot counts, last-snapshot time and repo size. */
+export function buildStatusReport() {
+    const apps = listConfiguredApps();
+    const entries = [];
+    for (const app of apps) {
+        const cfg = loadConfig(app);
+        if (!cfg)
+            continue;
+        const snaps = listSnapshots(app);
+        const last = snaps[snaps.length - 1];
+        const st = stats(app);
+        entries.push({
+            app,
+            schedule: cfg.schedule,
+            disabled: !!cfg.disabled,
+            snapshotCount: snaps.length,
+            lastSnapshotAt: last?.time ?? null,
+            totalSize: st?.totalSize ?? null,
+        });
+    }
+    return {
+        generatedAt: new Date().toISOString(),
+        backend: (process.env.FLEET_BACKUP_BASE_URL ?? '').startsWith('rest:') ? 'rest' : 'sftp',
+        appendOnly: isAppendOnly(),
+        apps: entries,
+    };
+}

package/dist/core/backup/statuspage.d.ts

@@ -0,0 +1,23 @@
+/** read-only backup status dashboard. rendered to static html by a systemd
+ *  timer and served at the /backups route (ip-restricted in nginx). */
+export interface StatusEntry {
+    app: string;
+    schedule: string;
+    disabled: boolean;
+    snapshotCount: number;
+    lastSnapshotAt: string | null;
+    totalSize: number | null;
+}
+export interface StatusReport {
+    generatedAt: string;
+    backend: 'rest' | 'sftp';
+    appendOnly: boolean;
+    apps: StatusEntry[];
+}
+export type Health = 'ok' | 'stale' | 'missing' | 'disabled';
+export declare function healthOf(entry: StatusEntry, now?: number): Health;
+export declare function humanBytes(n: number | null): string;
+export declare function relativeTime(iso: string | null, now?: number): string;
+/** renders the full standalone html page. no external assets — inline css so
+ *  it works as a flat file behind nginx. */
+export declare function renderStatusHtml(report: StatusReport, now?: number): string;

package/dist/core/backup/statuspage.js

@@ -0,0 +1,145 @@
+/** read-only backup status dashboard. rendered to static html by a systemd
+ *  timer and served at the /backups route (ip-restricted in nginx). */
+/** how long after the expected cadence a backup is considered stale.
+ *  generous — covers the timer's randomised delay plus a missed run. */
+function stalenessThresholdMs(schedule) {
+    const hour = 3_600_000;
+    if (schedule === 'hourly')
+        return 3 * hour;
+    if (schedule === 'weekly')
+        return 8.5 * 24 * hour;
+    if (schedule.includes('00/3'))
+        return 7 * hour;
+    if (schedule.includes('00/6'))
+        return 13 * hour;
+    if (schedule.includes('00/12'))
+        return 25 * hour;
+    // daily and anything unrecognised
+    return 28 * hour;
+}
+export function healthOf(entry, now = Date.now()) {
+    if (entry.disabled)
+        return 'disabled';
+    if (!entry.lastSnapshotAt || entry.snapshotCount === 0)
+        return 'missing';
+    const age = now - new Date(entry.lastSnapshotAt).getTime();
+    return age > stalenessThresholdMs(entry.schedule) ? 'stale' : 'ok';
+}
+export function humanBytes(n) {
+    if (n === null)
+        return '—';
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 ** 2)
+        return `${(n / 1024).toFixed(1)} KB`;
+    if (n < 1024 ** 3)
+        return `${(n / 1024 ** 2).toFixed(1)} MB`;
+    return `${(n / 1024 ** 3).toFixed(2)} GB`;
+}
+export function relativeTime(iso, now = Date.now()) {
+    if (!iso)
+        return 'never';
+    const diff = now - new Date(iso).getTime();
+    const min = Math.floor(diff / 60_000);
+    if (min < 1)
+        return 'just now';
+    if (min < 60)
+        return `${min}m ago`;
+    const hr = Math.floor(min / 60);
+    if (hr < 48)
+        return `${hr}h ago`;
+    return `${Math.floor(hr / 24)}d ago`;
+}
+function esc(s) {
+    return s.replace(/[&<>"]/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
+}
+/** renders the full standalone html page. no external assets — inline css so
+ *  it works as a flat file behind nginx. */
+export function renderStatusHtml(report, now = Date.now()) {
+    const apps = [...report.apps].sort((a, b) => a.app.localeCompare(b.app));
+    const counts = { ok: 0, stale: 0, missing: 0, disabled: 0 };
+    for (const a of apps)
+        counts[healthOf(a, now)]++;
+    const totalBytes = apps.reduce((s, a) => s + (a.totalSize ?? 0), 0);
+    const rows = apps.map(a => {
+        const h = healthOf(a, now);
+        return `      <tr class="h-${h}">
+        <td class="dot"><span class="d d-${h}" title="${h}"></span></td>
+        <td class="app">${esc(a.app)}</td>
+        <td>${esc(a.schedule)}</td>
+        <td class="num">${a.snapshotCount}</td>
+        <td>${esc(relativeTime(a.lastSnapshotAt, now))}</td>
+        <td class="num">${humanBytes(a.totalSize)}</td>
+      </tr>`;
+    }).join('\n');
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta http-equiv="refresh" content="300">
+<title>fleet backups</title>
+<style>
+  :root { color-scheme: dark; }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; padding: 2rem;
+    background: #0d1117; color: #c9d1d9;
+    font: 14px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace;
+  }
+  h1 { font-size: 1.1rem; margin: 0 0 0.25rem; color: #e6edf3; }
+  .meta { color: #8b949e; margin-bottom: 1.25rem; font-size: 0.8rem; }
+  .badges { display: flex; gap: 0.5rem; flex-wrap: wrap; margin-bottom: 1.25rem; }
+  .badge {
+    padding: 0.3rem 0.7rem; border-radius: 6px; font-size: 0.8rem;
+    background: #161b22; border: 1px solid #30363d;
+  }
+  .badge b { color: #e6edf3; }
+  .badge.ok b { color: #3fb950; }
+  .badge.stale b { color: #d29922; }
+  .badge.missing b { color: #f85149; }
+  table { border-collapse: collapse; width: 100%; max-width: 880px; }
+  th, td { text-align: left; padding: 0.45rem 0.8rem; border-bottom: 1px solid #21262d; }
+  th { color: #8b949e; font-weight: 600; font-size: 0.78rem; text-transform: uppercase; letter-spacing: 0.04em; }
+  td.num { text-align: right; font-variant-numeric: tabular-nums; }
+  td.app { color: #e6edf3; }
+  td.dot { width: 1.5rem; }
+  .d { display: inline-block; width: 9px; height: 9px; border-radius: 50%; }
+  .d-ok { background: #3fb950; }
+  .d-stale { background: #d29922; }
+  .d-missing { background: #f85149; }
+  .d-disabled { background: #484f58; }
+  tr.h-stale td.app { color: #d29922; }
+  tr.h-missing td.app { color: #f85149; }
+  tr.h-disabled { opacity: 0.5; }
+  tfoot td { border-top: 2px solid #30363d; border-bottom: none; color: #8b949e; padding-top: 0.7rem; }
+</style>
+</head>
+<body>
+  <h1>fleet backups</h1>
+  <div class="meta">
+    generated ${esc(report.generatedAt)} ·
+    backend <b>${esc(report.backend)}</b> ·
+    ${report.appendOnly ? 'append-only enforced' : 'append-only OFF'}
+  </div>
+  <div class="badges">
+    <span class="badge ok"><b>${counts.ok}</b> ok</span>
+    <span class="badge stale"><b>${counts.stale}</b> stale</span>
+    <span class="badge missing"><b>${counts.missing}</b> missing</span>
+    <span class="badge"><b>${counts.disabled}</b> disabled</span>
+  </div>
+  <table>
+    <thead>
+      <tr><th></th><th>app</th><th>schedule</th><th>snaps</th><th>last</th><th>size</th></tr>
+    </thead>
+    <tbody>
+${rows}
+    </tbody>
+    <tfoot>
+      <tr><td colspan="3">${apps.length} apps</td><td class="num"></td><td></td><td class="num">${humanBytes(totalBytes)}</td></tr>
+    </tfoot>
+  </table>
+</body>
+</html>
+`;
+}

package/dist/core/backup/system.d.ts

@@ -0,0 +1,24 @@
+import { AppBackupConfig } from './types.js';
+/** the `system` pseudo-app: os, infra config, all the things needed to rebuild
+ * this host from a fresh ubuntu install + the data on the backup vps. */
+export declare const SYSTEM_PATHS: string[];
+export declare const ROOT_HOME_PATHS: string[];
+/** excludes for root-home and user-home: claude code regeneratable state
+ *  (sessions, plugin caches, telemetry) and tool caches that take GBs but
+ *  contain nothing the user authored. credentials.json, settings, hooks,
+ *  skills, plans, mcp.json all stay. */
+export declare const HOME_EXCLUDES: string[];
+/** the operator's home-dir paths worth backing up — dotfiles and agent
+ *  state, never app working directories. derived from the configured home. */
+export declare function userHomePaths(homeDir: string): string[];
+export declare const USER_HOME_EXCLUDES: string[];
+export declare function systemConfig(): AppBackupConfig;
+export declare function rootHomeConfig(): AppBackupConfig;
+/** shared-cluster dumps. these are safety nets — they capture every database
+ *  in the shared container as one big stream. per-app preDump entries are
+ *  preferred for routine restore granularity (run hourly), but these run
+ *  daily and catch DBs the per-app list doesn't enumerate. */
+export declare function sharedPostgresConfig(): AppBackupConfig;
+export declare function sharedMysqlConfig(): AppBackupConfig;
+export declare function sharedMongoConfig(): AppBackupConfig;
+export declare function userHomeConfig(): AppBackupConfig;

package/dist/core/backup/system.js

@@ -0,0 +1,209 @@
+import { loadOperator } from '../operator.js';
+import { DEFAULT_RETENTION } from './config.js';
+/** the `system` pseudo-app: os, infra config, all the things needed to rebuild
+ * this host from a fresh ubuntu install + the data on the backup vps. */
+export const SYSTEM_PATHS = [
+    '/etc/nginx',
+    '/etc/letsencrypt',
+    '/etc/systemd/system',
+    '/etc/systemd/resolved.conf.d',
+    '/etc/fleet',
+    '/etc/iptables',
+    '/etc/truewaf',
+    '/etc/modsecurity',
+    '/etc/ssh',
+    '/etc/sudoers',
+    '/etc/sudoers.d',
+    '/etc/fail2ban',
+    '/etc/cron.d',
+    '/etc/crontab',
+    '/etc/netplan',
+    '/etc/hosts',
+    '/etc/hostname',
+    '/etc/timezone',
+    '/etc/apt/sources.list',
+    '/etc/apt/sources.list.d',
+    '/etc/apt/keyrings',
+    '/etc/sysctl.conf',
+    '/etc/sysctl.d',
+    '/etc/security',
+    '/etc/php',
+    '/etc/guardian',
+    '/etc/cloud',
+    '/etc/default',
+    '/etc/ntpsec',
+    '/etc/logrotate.d',
+    '/etc/docker/daemon.json',
+    '/etc/nftables.conf',
+    '/var/lib/fleet',
+    '/var/lib/letsencrypt',
+    '/var/lib/fail2ban',
+    '/usr/local/bin',
+    '/usr/local/sbin',
+    '/opt/coreruleset',
+    '/root/firewall',
+];
+export const ROOT_HOME_PATHS = [
+    '/root/.ssh',
+    '/root/.docker/config.json',
+    '/root/.docker/.token_seed',
+    '/root/.secrets',
+    '/root/.gnupg',
+    '/root/.aws',
+    '/root/.gcloud',
+    '/root/.azure',
+    '/root/.kube',
+    '/root/.gitconfig',
+    '/root/.npmrc',
+    '/root/.bashrc',
+    '/root/.bash_profile',
+    '/root/.bash_history',
+    '/root/.claude',
+    '/root/.claude.json',
+    '/root/.mcp.json',
+    '/root/.gmail-mcp/tokens',
+    '/root/.cargo/credentials.toml',
+    '/root/.cargo/config.toml',
+    '/root/.pm2/dump.pm2',
+    '/root/.pm2/module_conf.json',
+];
+/** excludes for root-home and user-home: claude code regeneratable state
+ *  (sessions, plugin caches, telemetry) and tool caches that take GBs but
+ *  contain nothing the user authored. credentials.json, settings, hooks,
+ *  skills, plans, mcp.json all stay. */
+export const HOME_EXCLUDES = [
+    '**/.claude/projects',
+    '**/.claude/plugins/data',
+    '**/.claude/plugins/cache',
+    '**/.claude/plugins/marketplaces',
+    '**/.claude/plugins/install-counts-cache.json',
+    '**/.claude/file-history',
+    '**/.claude/paste-cache',
+    '**/.claude/telemetry',
+    '**/.claude/todos',
+    '**/.claude/tasks',
+    '**/.claude/backups',
+    '**/.claude/session-env',
+    '**/.claude/sessions',
+    '**/.claude/cache',
+    '**/.claude/debug',
+    '**/.claude/shell-snapshots',
+    '**/.claude/usage-data',
+    '**/.claude/cc-counter',
+    '**/.claude/statsig',
+    '**/.claude/stats-cache.json',
+    '**/.claude/history.jsonl',
+    '**/.claude/ide',
+    '**/.claude/downloads',
+    '**/.claude/mcp-needs-auth-cache.json',
+    '**/.claude/.last-cleanup',
+    '**/.claude/hooks/.last_test_run_*',
+    '*.log',
+];
+/** the operator's home-dir paths worth backing up — dotfiles and agent
+ *  state, never app working directories. derived from the configured home. */
+export function userHomePaths(homeDir) {
+    return [
+        `${homeDir}/.ssh`,
+        `${homeDir}/.gitconfig`,
+        `${homeDir}/.docker/config.json`,
+        `${homeDir}/.config/gh`,
+        `${homeDir}/.config/op`,
+        `${homeDir}/.aws`,
+        `${homeDir}/.gnupg`,
+        `${homeDir}/.terraform.d`,
+        `${homeDir}/.claude`,
+        `${homeDir}/.claude.json`,
+        `${homeDir}/.mcp.json`,
+        `${homeDir}/.bashrc`,
+        `${homeDir}/.bash_history`,
+        `${homeDir}/.profile`,
+        `${homeDir}/.local/bin`,
+    ];
+}
+export const USER_HOME_EXCLUDES = [
+    ...HOME_EXCLUDES,
+    '*.cache',
+    '.npm',
+    '.yarn',
+    '.cargo/registry',
+    '.cargo/git',
+    '.gradle/caches',
+    '.local/share',
+    'node_modules',
+];
+export function systemConfig() {
+    return {
+        app: 'system',
+        schedule: 'daily',
+        paths: SYSTEM_PATHS,
+        exclude: ['*.log', '*.pid', '.cache'],
+        retention: DEFAULT_RETENTION,
+    };
+}
+export function rootHomeConfig() {
+    return {
+        app: 'root-home',
+        schedule: 'daily',
+        paths: ROOT_HOME_PATHS,
+        exclude: HOME_EXCLUDES,
+        retention: DEFAULT_RETENTION,
+    };
+}
+/** shared-cluster dumps. these are safety nets — they capture every database
+ *  in the shared container as one big stream. per-app preDump entries are
+ *  preferred for routine restore granularity (run hourly), but these run
+ *  daily and catch DBs the per-app list doesn't enumerate. */
+export function sharedPostgresConfig() {
+    return {
+        app: 'shared-postgres',
+        schedule: 'daily',
+        paths: [],
+        exclude: [],
+        // postgres_user=postgres is set in compose env; pg_dumpall uses unix-socket
+        // peer auth so no password needed inside the container.
+        preDump: { type: 'postgres', container: 'shared-postgres', user: 'postgres' },
+        retention: { daily: 14, weekly: 8, monthly: 12 },
+    };
+}
+export function sharedMysqlConfig() {
+    return {
+        app: 'shared-mysql',
+        schedule: 'daily',
+        paths: [],
+        exclude: [],
+        // shared-mysql uses docker secrets — password lives at the file path below,
+        // not in an env var.
+        preDump: {
+            type: 'mysql',
+            container: 'shared-mysql',
+            user: 'root',
+            passwordFile: '/run/secrets/mysql_root_password',
+        },
+        retention: { daily: 14, weekly: 8, monthly: 12 },
+    };
+}
+export function sharedMongoConfig() {
+    return {
+        app: 'shared-mongodb',
+        schedule: 'daily',
+        paths: [],
+        exclude: [],
+        preDump: {
+            type: 'mongo',
+            container: 'shared-mongodb',
+            user: 'root',
+            passwordFile: '/run/secrets/mongo_root_password',
+        },
+        retention: { daily: 14, weekly: 8, monthly: 12 },
+    };
+}
+export function userHomeConfig() {
+    return {
+        app: 'user-home',
+        schedule: 'daily',
+        paths: userHomePaths(loadOperator().homeDir),
+        exclude: USER_HOME_EXCLUDES,
+        retention: DEFAULT_RETENTION,
+    };
+}

package/dist/core/backup/totp.d.ts

@@ -0,0 +1,16 @@
+/** new random 20-byte secret, base32-encoded for authenticator apps. */
+export declare function generateSecret(): string;
+/** the 6-digit TOTP code for a base32 secret at a given epoch-ms time. */
+export declare function totpCode(secretB32: string, atMs?: number): string;
+/** true if `code` is valid for the secret within a +/-1 step window. */
+export declare function verifyTotp(secretB32: string, code: string, atMs?: number): boolean;
+/** otpauth:// enrolment URI — paste into 1Password or an authenticator app. */
+export declare function totpUri(secretB32: string, label: string, issuer: string): string;
+export interface SessionPayload {
+    /** epoch-ms expiry. */
+    exp: number;
+}
+/** signs a session payload as `<body>.<hmac>` (hmac-sha256). */
+export declare function signSession(payload: SessionPayload, secret: string): string;
+/** verifies a session cookie; returns the payload or null if invalid/expired. */
+export declare function verifySession(cookie: string, secret: string, nowMs?: number): SessionPayload | null;