@celilo/cli 0.23.0 → 0.24.0

package/src/services/audit/backups.test.ts

@@ -1,19 +1,19 @@
 import { describe, expect, test } from 'bun:test';
 import type { ModuleManifest } from '../../manifest/schema';
-import { type InstalledModuleBackupInfo, auditBackups } from './backups';
+import { parseCadence } from '../cadence';
+import { type InstalledModuleBackupInfo, auditBackups, backupStaleThresholdMs } from './backups';
 
 const NOW = new Date('2026-04-25T00:00:00Z').getTime();
 const HOUR = 60 * 60 * 1000;
 const ONE_DAY = 24 * HOUR;
 
-type Schedule = 'hourly' | 'daily' | 'weekly' | 'monthly' | 'manual';
-
 function makeModule(
   id: string,
   opts: {
     hasBackupHook: boolean;
     lastSuccessfulBackupAt: number | null;
-    schedule?: Schedule;
+    schedule?: string;
+    scheduleOverride?: string;
   },
 ): InstalledModuleBackupInfo {
   const manifest = {
@@ -27,9 +27,42 @@ function makeModule(
   // Default to INSTALLED — existing tests assert backup findings
   // fire, which is the deployed-module behavior. Tests for the
   // non-deployed-skip behavior override this explicitly.
-  return { id, state: 'INSTALLED', manifest, lastSuccessfulBackupAt: opts.lastSuccessfulBackupAt };
+  return {
+    id,
+    state: 'INSTALLED',
+    manifest,
+    scheduleOverride: opts.scheduleOverride,
+    lastSuccessfulBackupAt: opts.lastSuccessfulBackupAt,
+  };
 }
 
+describe('backupStaleThresholdMs', () => {
+  function cadence(value: string) {
+    const parsed = parseCadence(value);
+    if (parsed === null) throw new Error(`test fixture is not a cadence: ${value}`);
+    return parsed;
+  }
+
+  // The four values the change's release note promises. A table could not
+  // answer for `6h`, so these come out of `cadence + max(1h, cadence × 0.1)`;
+  // `weekly` is the only one that now alerts EARLIER than it used to (8d).
+  test('the four documented thresholds', () => {
+    expect(backupStaleThresholdMs(cadence('hourly'))).toBe(2 * HOUR);
+    expect(backupStaleThresholdMs(cadence('daily'))).toBe(26.4 * HOUR);
+    expect(backupStaleThresholdMs(cadence('weekly'))).toBe(7.7 * ONE_DAY);
+    expect(backupStaleThresholdMs(cadence('monthly'))).toBe(33 * ONE_DAY);
+  });
+
+  test('a custom duration has a defined threshold', () => {
+    expect(backupStaleThresholdMs(cadence('6h'))).toBe(7 * HOUR);
+    expect(backupStaleThresholdMs(cadence('90m'))).toBe(90 * 60_000 + HOUR);
+  });
+
+  test('manual has none — an opted-out module is never stale', () => {
+    expect(backupStaleThresholdMs('manual')).toBeNull();
+  });
+});
+
 describe('auditBackups', () => {
   test('skips modules without an on_backup hook', async () => {
     const result = await auditBackups({
@@ -39,7 +72,10 @@ describe('auditBackups', () => {
     expect(result).toEqual([]);
   });
 
-  test('reports missing backup regardless of schedule (still want at least one)', async () => {
+  // A module opted out of scheduled backups used to be reported as missing one
+  // forever: the never-backed-up check fired BEFORE the manual check, and the
+  // only remediation offered was the very thing the operator declined.
+  test('a module opted out is not reported as missing a backup', async () => {
     const result = await auditBackups({
       modules: [
         makeModule('lunacycle', {
@@ -51,14 +87,63 @@ describe('auditBackups', () => {
       now: () => NOW,
     });
 
+    expect(result).toEqual([]);
+  });
+
+  test('a module that has NOT opted out is still reported as missing a backup', async () => {
+    const result = await auditBackups({
+      modules: [
+        makeModule('authentik', {
+          hasBackupHook: true,
+          lastSuccessfulBackupAt: null,
+          schedule: 'daily',
+        }),
+      ],
+      now: () => NOW,
+    });
+
     expect(result).toHaveLength(1);
     expect(result[0]).toMatchObject({
       category: 'backups',
       severity: 'drift',
       code: 'backup_missing',
-      subject: 'lunacycle',
+      subject: 'authentik',
+    });
+  });
+
+  test("an operator's manual override silences a module the manifest wanted backed up", async () => {
+    const result = await auditBackups({
+      modules: [
+        makeModule('authentik', {
+          hasBackupHook: true,
+          lastSuccessfulBackupAt: null,
+          schedule: 'daily',
+          scheduleOverride: 'manual',
+        }),
+      ],
+      now: () => NOW,
+    });
+
+    expect(result).toEqual([]);
+  });
+
+  test('staleness is judged against the override, not the suggestion', async () => {
+    // Manifest says weekly (fresh at 2 days); the operator asked for hourly.
+    const result = await auditBackups({
+      modules: [
+        makeModule('caddy', {
+          hasBackupHook: true,
+          lastSuccessfulBackupAt: NOW - 2 * ONE_DAY,
+          schedule: 'weekly',
+          scheduleOverride: 'hourly',
+        }),
+      ],
+      now: () => NOW,
     });
-    expect(result[0].message).toContain('manual');
+
+    expect(result).toHaveLength(1);
+    expect(result[0].code).toBe('backup_stale');
+    expect(result[0].message).toContain('hourly');
   });
 
   test('manual schedule: never flags stale (user-driven cadence)', async () => {
@@ -93,12 +178,12 @@ describe('auditBackups', () => {
     expect(result[0].message).toContain('daily');
   });
 
-  test('daily schedule: 26h-old is stale', async () => {
+  test('daily schedule: 27h-old is stale', async () => {
     const result = await auditBackups({
       modules: [
         makeModule('authentik', {
           hasBackupHook: true,
-          lastSuccessfulBackupAt: NOW - 26 * HOUR,
+          lastSuccessfulBackupAt: NOW - 27 * HOUR,
           schedule: 'daily',
         }),
       ],

package/src/services/audit/backups.ts

@@ -1,24 +1,25 @@
 /**
  * Backup freshness drift check.
  *
- * For each installed module that declares an `on_backup` hook,
- * decides whether the most recent successful backup is too old based
- * on the module's declared `manifest.backup.schedule`. Each schedule
- * tier has a threshold with a small grace window so a slightly-late
- * scheduled run doesn't flag drift on every audit.
+ * For each installed module that declares an `on_backup` hook, decides whether
+ * the most recent successful backup is too old, against the module's EFFECTIVE
+ * cadence — the operator's override if they set one, else the manifest's
+ * suggestion. The threshold is that cadence plus a grace allowance, so a
+ * slightly-late scheduled run doesn't flag drift on every audit.
  *
- * Modules without an `on_backup` hook are skipped — there's nothing
- * to back up. Modules whose schedule is explicitly `manual` skip the
- * staleness check (the operator decides cadence) but still get a
- * `backup_missing` finding if no backup has ever been recorded. An
- * unset schedule is `daily`, not `manual` — see
- * [[services/backup-schedule.ts]] for why that default matters.
+ * Modules without an `on_backup` hook are skipped — there's nothing to back up.
+ * A module whose effective cadence is `manual` is skipped entirely: it has
+ * opted out, and a finding asking it to back up is one no operator action can
+ * clear, because the action it asks for is the one they declined. An unset
+ * cadence is `daily`, not `manual` — see [[services/backup-schedule.ts]] for
+ * why that default matters.
  *
  * Time is injected so tests can pin "now" deterministically.
  */
 
 import type { ModuleManifest } from '../../manifest/schema';
 import { effectiveBackupSchedule } from '../backup-schedule';
+import { type Cadence, cadenceMs, formatCadence } from '../cadence';
 import type { DriftFinding } from './types';
 
 export interface InstalledModuleBackupInfo {
@@ -26,6 +27,8 @@ export interface InstalledModuleBackupInfo {
   /** Lifecycle state — non-deployed modules have nothing to back up. */
   state: string;
   manifest: ModuleManifest;
+  /** The operator's `backup_schedule` override, or undefined when unset. */
+  scheduleOverride: string | undefined;
   /** Most recent successful backup timestamp (ms since epoch), or null. */
   lastSuccessfulBackupAt: number | null;
 }
@@ -33,9 +36,9 @@ export interface InstalledModuleBackupInfo {
 export interface BackupsAuditDeps {
   modules: InstalledModuleBackupInfo[];
   /**
-   * Test-only override: forces this threshold for every module,
-   * ignoring `manifest.backup.schedule`. Production code never sets
-   * this — schedule-based thresholds are the right behavior.
+   * Test-only override: forces this threshold for every module whose
+   * effective cadence is not `manual`. Production code never sets this —
+   * cadence-derived thresholds are the right behavior.
    */
   staleAfterMs?: number;
   /** Defaults to `Date.now()`. */
@@ -46,32 +49,26 @@ const HOUR = 60 * 60 * 1000;
 const DAY = 24 * HOUR;
 
 /**
- * Schedule → stale threshold. Each tier gets a grace window so a
- * legitimately-just-late run doesn't trip the audit:
+ * How old a backup may get before it is drift: the cadence itself plus a grace
+ * allowance, so a legitimately-just-late run doesn't trip the audit.
  *
- * - hourly  → 2h   (1h cadence + 1h grace)
- * - daily   → 25h  (24h + 1h grace)
- * - weekly  → 8d   (7d + 1d grace)
- * - monthly → 32d  (~30d + 2d grace)
- * - manual  → null (no staleness check; operator-driven cadence)
+ * A formula rather than a table because a table cannot answer for `6h`, and an
+ * operator who sets a custom cadence would get either no staleness reporting or
+ * an arbitrary threshold. The four previous values were not a formula in
+ * disguise — hourly had 100% grace, daily 4%, weekly 14%, monthly 7% — so this
+ * moves them: daily 25h → 26.4h, weekly 8d → 7.7d (the only one that alerts
+ * EARLIER), monthly 32d → 33d, hourly unchanged at 2h. See design.md D7.
  */
-const SCHEDULE_THRESHOLDS = {
-  hourly: 2 * HOUR,
-  daily: 25 * HOUR,
-  weekly: 8 * DAY,
-  monthly: 32 * DAY,
-  manual: null,
-} as const;
+export function backupStaleThresholdMs(cadence: Cadence): number | null {
+  if (cadence === 'manual') return null;
+  const interval = cadenceMs(cadence);
+  return interval + Math.max(HOUR, interval * 0.1);
+}
 
 function moduleHasBackupHook(manifest: ModuleManifest): boolean {
   return Boolean(manifest.hooks?.on_backup);
 }
 
-function thresholdFor(manifest: ModuleManifest, override: number | undefined): number | null {
-  if (override !== undefined) return override;
-  return SCHEDULE_THRESHOLDS[effectiveBackupSchedule(manifest)];
-}
-
 function formatAge(ms: number): string {
   const days = Math.floor(ms / DAY);
   if (days >= 1) return `${days}d`;
@@ -96,12 +93,18 @@ export async function auditBackups(deps: BackupsAuditDeps): Promise<DriftFinding
     // audit.
     if (!DEPLOYED_STATES.has(m.state)) continue;
 
+    const cadence = effectiveBackupSchedule(m.manifest, m.scheduleOverride);
+    // BEFORE the never-backed-up check, not after. A module opted out of
+    // scheduled backups was reported as missing one forever, and the only
+    // remediation offered was the very thing the operator declined.
+    if (cadence === 'manual') continue;
+
     if (m.lastSuccessfulBackupAt === null) {
       findings.push({
         category: 'backups',
         severity: 'drift',
         code: 'backup_missing',
-        message: `${m.id}: no successful backup recorded (schedule: ${effectiveBackupSchedule(m.manifest)})`,
+        message: `${m.id}: no successful backup recorded (schedule: ${formatCadence(cadence)})`,
         remediation: `celilo backup create ${m.id} --force`,
         actionable: true,
         subject: m.id,
@@ -109,8 +112,8 @@ export async function auditBackups(deps: BackupsAuditDeps): Promise<DriftFinding
       continue;
     }
 
-    const threshold = thresholdFor(m.manifest, deps.staleAfterMs);
-    if (threshold === null) continue; // manual cadence — staleness is user-defined
+    const threshold = deps.staleAfterMs ?? backupStaleThresholdMs(cadence);
+    if (threshold === null) continue;
 
     const age = now - m.lastSuccessfulBackupAt;
     if (age > threshold) {
@@ -118,7 +121,7 @@ export async function auditBackups(deps: BackupsAuditDeps): Promise<DriftFinding
         category: 'backups',
         severity: 'drift',
         code: 'backup_stale',
-        message: `${m.id}: last successful backup is ${formatAge(age)} old (schedule: ${effectiveBackupSchedule(m.manifest)}, threshold: ${formatAge(threshold)})`,
+        message: `${m.id}: last successful backup is ${formatAge(age)} old (schedule: ${formatCadence(cadence)}, threshold: ${formatAge(threshold)})`,
         remediation: `celilo backup create ${m.id} --force`,
         actionable: true,
         subject: m.id,

package/src/services/audit/interface-classification.test.ts

@@ -0,0 +1,220 @@
+/**
+ * §10 — what the audit says about a firewall's interfaces.
+ *
+ * The condition that produced `fw-keeper.sh` was not that celilo lacked
+ * information; it was that celilo said nothing. So the load-bearing assertions
+ * here are about what gets NAMED — an alien interface by name AND address, a
+ * carrier leg, an ambiguous edge — and about §10.2's converse: a fully declared
+ * firewall must produce no findings at all, or the report trains the operator to
+ * ignore it.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import {
+  type FirewallInterfaceView,
+  auditFirewallInterfaces,
+  auditInterfaceClassification,
+  describeClassification,
+} from './interface-classification';
+
+const DECLARED = [
+  { zone: 'internal', subnet: '192.168.0.0/24' },
+  { zone: 'dmz', subnet: '10.0.10.0/24' },
+  { zone: 'app', subnet: '10.0.20.0/24' },
+  { zone: 'secure', subnet: '10.0.30.0/24' },
+];
+
+/** celilo's own firewall: five RFC1918 legs, four declared, wg0 not. */
+function liveFleetShape(overrides: Partial<FirewallInterfaceView> = {}): FirewallInterfaceView {
+  return {
+    hostname: 'fw-main',
+    interfaces: [
+      { name: 'eth0', ip: '192.168.0.254' },
+      { name: 'eth1', ip: '10.0.10.1' },
+      { name: 'eth2', ip: '10.0.20.1' },
+      { name: 'eth3', ip: '10.0.30.1' },
+      { name: 'wg0', ip: '10.255.255.1' },
+    ],
+    zones: DECLARED,
+    defaultRouteInterface: 'eth0',
+    ...overrides,
+  };
+}
+
+function codes(findings: { code: string }[]): string[] {
+  return findings.map((f) => f.code);
+}
+
+describe('§10.2 — a fully declared firewall produces NO interface findings', () => {
+  test('every leg declared, default route on internal, no findings', () => {
+    // The positive control, and not a formality: a check that cries wolf on a
+    // healthy fleet is worse than no check, because it teaches an operator to
+    // ignore the one signal that matters.
+    const view = liveFleetShape({
+      zones: [...DECLARED, { zone: 'control-plane-vpn', subnet: '10.255.255.0/24' }],
+    });
+    expect(auditFirewallInterfaces(view)).toEqual([]);
+  });
+
+  test('a firewall that owns its WAN, fully declared, produces no findings', () => {
+    const view: FirewallInterfaceView = {
+      hostname: 'vps-fw',
+      interfaces: [
+        { name: 'eth0', ip: '10.0.10.1' },
+        { name: 'eth1', ip: '203.0.113.100' },
+      ],
+      zones: [{ zone: 'dmz', subnet: '10.0.10.0/24' }],
+      defaultRouteInterface: 'eth1',
+    };
+    expect(auditFirewallInterfaces(view)).toEqual([]);
+  });
+
+  test('loopback does not produce a finding', () => {
+    const view = liveFleetShape({
+      interfaces: [{ name: 'lo', ip: '127.0.0.1' }, ...liveFleetShape().interfaces.slice(0, 4)],
+      defaultRouteInterface: 'eth0',
+    });
+    expect(auditFirewallInterfaces(view)).toEqual([]);
+  });
+});
+
+describe('§10.1 — alien interfaces are named, by name AND address', () => {
+  const findings = auditFirewallInterfaces(liveFleetShape());
+
+  test('the undeclared VPN leg is reported', () => {
+    expect(codes(findings)).toContain('alien_interfaces');
+  });
+
+  test('the message carries both the interface name and its address', () => {
+    // "one alien interface" is useless at 3am. The operator needs to know
+    // which, and where.
+    const alien = findings.find((f) => f.code === 'alien_interfaces');
+    expect(alien?.message).toContain('wg0');
+    expect(alien?.message).toContain('10.255.255.1');
+  });
+
+  test('it is drift, not blocked — the converge decides, the audit reports', () => {
+    expect(findings.find((f) => f.code === 'alien_interfaces')?.severity).toBe('drift');
+  });
+
+  test('it is subjected on the hostname, never a UUID', () => {
+    // Suppression resolves a machine's ancestor key from its hostname; a
+    // finding subjected on a UUID produces an alert key nothing can match
+    // (#596). Users never see UUIDs either.
+    expect(findings.find((f) => f.code === 'alien_interfaces')?.subject).toBe('fw-main');
+  });
+
+  test('several alien legs are all named, not just the first', () => {
+    const view = liveFleetShape({ zones: [{ zone: 'internal', subnet: '192.168.0.0/24' }] });
+    const alien = auditFirewallInterfaces(view).find((f) => f.code === 'alien_interfaces');
+    for (const ip of ['10.0.10.1', '10.0.20.1', '10.0.30.1', '10.255.255.1']) {
+      expect(alien?.message).toContain(ip);
+    }
+  });
+});
+
+describe('§10.1 — the blocking findings match what the converge does', () => {
+  test('a carrier-grade NAT leg blocks, naming the interface and address', () => {
+    const view = liveFleetShape({
+      interfaces: [...liveFleetShape().interfaces, { name: 'eth9', ip: '100.83.4.17' }],
+      zones: [...DECLARED, { zone: 'control-plane-vpn', subnet: '10.255.255.0/24' }],
+    });
+    const finding = auditFirewallInterfaces(view).find(
+      (f) => f.code === 'carrier_grade_nat_interface',
+    );
+    expect(finding?.severity).toBe('blocked');
+    expect(finding?.message).toContain('eth9');
+    expect(finding?.message).toContain('100.83.4.17');
+  });
+
+  test('two public legs with no designation block, naming both candidates', () => {
+    const view: FirewallInterfaceView = {
+      hostname: 'fw-two-wans',
+      interfaces: [
+        { name: 'eth0', ip: '203.0.113.100' },
+        { name: 'eth1', ip: '198.51.100.7' },
+      ],
+      zones: [],
+      defaultRouteInterface: 'eth0',
+    };
+    const finding = auditFirewallInterfaces(view).find((f) => f.code === 'ambiguous_external_edge');
+    expect(finding?.severity).toBe('blocked');
+    expect(finding?.message).toContain('203.0.113.100');
+    expect(finding?.message).toContain('198.51.100.7');
+    expect(finding?.remediation).toContain('zone.external.ip');
+  });
+
+  test('a designated edge resolves the ambiguity, producing no finding', () => {
+    const view: FirewallInterfaceView = {
+      hostname: 'fw-two-wans',
+      interfaces: [
+        { name: 'eth0', ip: '203.0.113.100' },
+        { name: 'eth1', ip: '198.51.100.7' },
+      ],
+      zones: [],
+      defaultRouteInterface: 'eth0',
+      designatedExternalIp: '198.51.100.7',
+    };
+    expect(codes(auditFirewallInterfaces(view))).not.toContain('ambiguous_external_edge');
+  });
+
+  test('a default route on a segmented zone blocks', () => {
+    const view = liveFleetShape({
+      zones: [...DECLARED, { zone: 'control-plane-vpn', subnet: '10.255.255.0/24' }],
+      defaultRouteInterface: 'eth1', // the dmz leg
+    });
+    const finding = auditFirewallInterfaces(view).find((f) => f.code === 'default_route_off_edge');
+    expect(finding?.severity).toBe('blocked');
+    expect(finding?.message).toContain('eth1');
+  });
+
+  test('an unknown default route is not checked rather than guessed', () => {
+    // `undefined` means celilo did not read the routing table. Reporting a
+    // finding from an absent measurement would be inventing evidence.
+    const view = liveFleetShape({
+      zones: [...DECLARED, { zone: 'control-plane-vpn', subnet: '10.255.255.0/24' }],
+      defaultRouteInterface: undefined,
+    });
+    expect(codes(auditFirewallInterfaces(view))).not.toContain('default_route_off_edge');
+  });
+
+  test('blocking findings come before drift, so the report reads top-down', () => {
+    const view = liveFleetShape({
+      interfaces: [...liveFleetShape().interfaces, { name: 'eth9', ip: '100.83.4.17' }],
+    });
+    const severities = auditFirewallInterfaces(view).map((f) => f.severity);
+    expect(severities[0]).toBe('blocked');
+    expect(severities.at(-1)).toBe('drift');
+  });
+});
+
+describe('describeClassification — the picture, not a finding', () => {
+  test('names the role of every interface, and why an alien one is alien', () => {
+    const lines = describeClassification(liveFleetShape());
+    expect(lines).toContain('eth0: 192.168.0.254 → zone:internal');
+    expect(lines).toContain('wg0: 10.255.255.1 → alien (no declared subnet contains it)');
+  });
+
+  test('a publicly routable but unclaimed leg is described as external', () => {
+    const lines = describeClassification({
+      hostname: 'vps-fw',
+      interfaces: [{ name: 'eth1', ip: '203.0.113.100' }],
+      zones: [],
+    });
+    expect(lines[0]).toBe('eth1: 203.0.113.100 → external (the WAN edge)');
+  });
+});
+
+describe('auditInterfaceClassification — every firewall, flattened', () => {
+  test('reports across several firewalls, each subjected on its own hostname', () => {
+    const findings = auditInterfaceClassification([
+      liveFleetShape(),
+      liveFleetShape({ hostname: 'fw-branch' }),
+    ]);
+    expect(findings.map((f) => f.subject).sort()).toEqual(['fw-branch', 'fw-main']);
+  });
+
+  test('no firewalls means no findings', () => {
+    expect(auditInterfaceClassification([])).toEqual([]);
+  });
+});