@celilo/cli 0.13.3 → 0.14.1

package/src/hooks/capability-loader.ts

@@ -24,6 +24,7 @@ import type {
   PortForwardStore,
   RouteOps,
   RouteReadView,
+  TrustedSourceStore,
 } from '@celilo/capabilities';
 import { and, eq } from 'drizzle-orm';
 import type { DbClient } from '../db/client';
@@ -35,6 +36,14 @@ import { getModuleSystems } from '../services/deployed-systems';
 import { withDnsInternalLedger } from '../services/dns-internal-records';
 import { withDnsRegistrationLedger } from '../services/dns-registrations';
 import { buildPortForwardStore } from '../services/port-forwards';
+import {
+  TRUSTED_SUBNETS_CONFIG_KEY,
+  type TrustedSubnetEntry,
+  buildTrustedSourceStore,
+  composeTrustedSubnets,
+  listTrustedSourcesFor,
+  parseOperatorTrustedSubnets,
+} from '../services/trusted-sources';
 import { resolveComputedFields } from '../variables/computed/evaluate';
 import { containsComputedMarker } from '../variables/computed/marker';
 import { buildProviderLookup } from '../variables/computed/provider-lookup';
@@ -54,37 +63,46 @@ import { loadHookConfigMap } from './load-hook-config';
  * upstream-chain wiring takes a second factory argument (`upstreamFirewall`)
  * that doesn't fit the `defineCapabilityFunction` shape.
  */
-const CAPABILITY_MODULE_MAP: Record<string, { script: string; legacyFactoryName: string }> = {
-  dns_registrar: {
-    script: 'scripts/register-host.ts',
-    legacyFactoryName: 'default',
-  },
-  firewall: {
-    script: 'scripts/firewall-functions.ts',
-    legacyFactoryName: 'createFirewall',
-  },
-  // public_web: handled via framework implementation (createPublicWeb from @celilo/capabilities)
-  idp: {
-    script: 'scripts/idp-functions.ts',
-    legacyFactoryName: 'createIdp',
-  },
-  source_forge: {
-    script: 'scripts/source-forge-functions.ts',
-    legacyFactoryName: 'createForgejoSourceForge',
-  },
-  registry_publish: {
-    script: 'scripts/registry-publish-functions.ts',
-    legacyFactoryName: 'default',
-  },
-  dhcp_server: {
-    script: 'scripts/dhcp-server-functions.ts',
-    legacyFactoryName: 'default',
-  },
-  dns_internal: {
-    script: 'scripts/dns-internal-functions.ts',
-    legacyFactoryName: 'default',
-  },
-};
+export const CAPABILITY_MODULE_MAP: Record<string, { script: string; legacyFactoryName: string }> =
+  {
+    dns_registrar: {
+      script: 'scripts/register-host.ts',
+      legacyFactoryName: 'default',
+    },
+    firewall: {
+      script: 'scripts/firewall-functions.ts',
+      legacyFactoryName: 'createFirewall',
+    },
+    // public_web: handled via framework implementation (createPublicWeb from @celilo/capabilities)
+    idp: {
+      script: 'scripts/idp-functions.ts',
+      legacyFactoryName: 'createIdp',
+    },
+    source_forge: {
+      script: 'scripts/source-forge-functions.ts',
+      legacyFactoryName: 'createForgejoSourceForge',
+    },
+    registry_publish: {
+      script: 'scripts/registry-publish-functions.ts',
+      legacyFactoryName: 'default',
+    },
+    dhcp_server: {
+      script: 'scripts/dhcp-server-functions.ts',
+      legacyFactoryName: 'default',
+    },
+    dns_internal: {
+      script: 'scripts/dns-internal-functions.ts',
+      legacyFactoryName: 'default',
+    },
+    notification: {
+      script: 'scripts/notification.ts',
+      legacyFactoryName: 'default',
+    },
+    external_web: {
+      script: 'scripts/publish-functions.ts',
+      legacyFactoryName: 'default',
+    },
+  };
 
 /**
  * Load capability function interfaces for a consuming module
@@ -199,6 +217,7 @@ export async function loadCapabilityFunctions(
         db,
         logger,
         debugLog,
+        consumingModuleId,
       );
       if (firewallInterface) {
         result[capName] = firewallInterface;
@@ -277,7 +296,13 @@ export async function loadCapabilityFunctions(
           systems: getModuleSystems(capability.moduleId, db),
           logger,
         });
-        result[capName] = withLedger(capabilityInterface);
+        // Stamp here too, not only on the legacy path: a consumer that cannot
+        // get what it needs must be able to name WHICH provider could not give
+        // it. Missing this made the wireguard module report "Firewall provider
+        // 'unknown' does not support trusted-source registration" against
+        // greenwave — true, useless, and a violation of the contract's
+        // requirement to name the provider.
+        result[capName] = withLedger(stampProvider(capabilityInterface, capability.moduleId));
         debugLog(`${capName}: loaded via defineCapabilityFunction`);
         continue;
       }
@@ -294,6 +319,10 @@ export async function loadCapabilityFunctions(
         // port-forward store — the chain path isn't taken when there's one provider.
         capName === 'firewall' ? buildPortForwardStore(db) : undefined,
         capName === 'firewall' ? loadFirewallZones(db) : undefined,
+        // Bound to the CONSUMING module so a trusted-source registration is
+        // attributable — reach into every tier must never be anonymous.
+        capName === 'firewall' ? buildTrustedSourceStore(db, consumingModuleId) : undefined,
+        capability.moduleId,
       );
 
       if (capabilityInterface) {
@@ -539,6 +568,16 @@ export async function loadCapabilityFunctions(
  * factories are now branded `defineCapabilityFunction` outputs that the
  * caller invokes directly with the new context.
  */
+/**
+ * Stamp the provider module id onto a capability interface, so a consumer that
+ * cannot get what it needs can name WHICH provider could not supply it (see
+ * `requireTrustedSources`). Non-function properties survive `wrapWithLogging`.
+ */
+function stampProvider(iface: unknown, providerModuleId?: string): unknown {
+  if (!iface || typeof iface !== 'object' || !providerModuleId) return iface;
+  return Object.assign(iface, { providerModuleId });
+}
+
 function buildCapabilityInterface(
   capabilityName: string,
   factory: (...args: unknown[]) => unknown,
@@ -546,6 +585,8 @@ function buildCapabilityInterface(
   _secrets: Record<string, string>,
   store?: PortForwardStore,
   zones?: FirewallZones,
+  trustedSourceStore?: TrustedSourceStore,
+  providerModuleId?: string,
 ): unknown {
   if (capabilityName === 'firewall') {
     // iptables firewall factory: NAT config + the injected port-forward store
@@ -557,15 +598,20 @@ function buildCapabilityInterface(
       if (!store) {
         throw new Error('firewall capability requires an injected port-forward store');
       }
-      return factory(
+      const iface = factory(
         {
           firewallIp: config.firewall_ip as string,
           natIp: config.nat_ip as string,
           zoneTiers: zones?.zoneTiers ?? [],
           trustedSubnets: zones?.trustedSubnets ?? [],
+          controlPlaneSubnet: zones?.controlPlaneSubnet,
         },
         store,
+        undefined, // no upstream — the chain path handles that
+        undefined, // logger is applied by wrapWithLogging at the loader site
+        trustedSourceStore,
       );
+      return stampProvider(iface, providerModuleId);
     }
     return null;
   }
@@ -661,8 +707,10 @@ const ZONE_TIER_ORDER = ['dmz', 'app', 'secure'] as const;
 interface FirewallZones {
   /** Ordered segmented tiers (dmz→app→secure adjacency) for the data-plane matrix. */
   zoneTiers: Array<{ name: string; subnet: string }>;
-  /** Subnets that reach EVERY tier — celilo's control plane (see loadControlPlaneSubnet). */
+  /** Subnets that reach EVERY tier — the composed set (see loadTrustedSubnets). */
   trustedSubnets: string[];
+  /** celilo's control-plane network, as a DESTINATION for trusted sources. */
+  controlPlaneSubnet?: string;
 }
 
 /** The module that IS celilo's control plane; its network is what we trust. */
@@ -699,10 +747,51 @@ export function loadControlPlaneSubnet(db: DbClient): string | undefined {
   return undefined;
 }
 
+/**
+ * The composed trusted-subnet set for one firewall, with each subnet's ORIGIN —
+ * celilo's derived control plane, the sources modules registered, and any
+ * explicit operator override.
+ *
+ * This used to be the derived control-plane subnet and nothing else, with no
+ * contribution point: infrastructure whose need was zone-wide REACH rather than
+ * port exposure had no way into the registry, so a converge — correctly
+ * rebuilding the ruleset from what it knew — removed rules nothing had claimed.
+ *
+ * With nothing registered and no override the result is the derived subnet
+ * alone, so a fleet without such infrastructure renders exactly as before.
+ *
+ * `firewallIp` includes that firewall's REGISTRATIONS — the full composed view,
+ * for REPORTING (which networks hold zone-wide reach, and who claimed each).
+ * Omit it for the render input: there the provider unions the live registry at
+ * converge time, and folding a snapshot in here as well would give one value two
+ * sources of truth, one of which cannot shrink.
+ */
+export function loadTrustedSubnets(db: DbClient, firewallIp?: string): TrustedSubnetEntry[] {
+  // Fall back to the internal subnet when celilo-mgmt's location can't be
+  // determined (e.g. installs predating celilo-mgmt-as-a-module). Losing control-
+  // plane trust outright would brick celilo's own fleet management, so absent
+  // information preserves today's behaviour; the gap is REPORTED separately.
+  const controlPlaneSubnet = loadControlPlaneSubnet(db) ?? readZoneSubnet(db, 'internal');
+  // Registrations are keyed by firewall. With no firewall named, contribute
+  // NONE rather than unioning every firewall's registrations — trust registered
+  // against one firewall is not trust granted by another.
+  const registered = firewallIp ? listTrustedSourcesFor(db, firewallIp) : [];
+  const overrideRow = db
+    .select()
+    .from(systemConfig)
+    .where(eq(systemConfig.key, TRUSTED_SUBNETS_CONFIG_KEY))
+    .get();
+  return composeTrustedSubnets({
+    controlPlaneSubnet,
+    registered,
+    operatorOverride: parseOperatorTrustedSubnets(overrideRow?.value ?? undefined),
+  });
+}
+
 /**
  * Read the firewall zone matrix inputs from system config (network.<zone>.subnet):
- * the segmented tiers [dmz, app, secure] and the control-plane subnet that reaches
- * all of them. Zones with no configured subnet are omitted — their traffic stays
+ * the segmented tiers [dmz, app, secure] and the trusted subnets that reach all
+ * of them. Zones with no configured subnet are omitted — their traffic stays
  * denied (fail-closed).
  */
 function loadFirewallZones(db: DbClient): FirewallZones {
@@ -711,12 +800,21 @@ function loadFirewallZones(db: DbClient): FirewallZones {
     const subnet = readZoneSubnet(db, zone);
     if (subnet) zoneTiers.push({ name: zone, subnet });
   }
-  // Fall back to the internal subnet when celilo-mgmt's location can't be
-  // determined (e.g. installs predating celilo-mgmt-as-a-module). Losing control-
-  // plane trust outright would brick celilo's own fleet management, so absent
-  // information preserves today's behaviour; the gap is REPORTED separately.
-  const controlPlane = loadControlPlaneSubnet(db) ?? readZoneSubnet(db, 'internal');
-  return { zoneTiers, trustedSubnets: controlPlane ? [controlPlane] : [] };
+  // The BASE set only — derived control plane + operator override. Module
+  // registrations are DELIBERATELY excluded: the provider unions them at
+  // converge time from the live store.
+  //
+  // Injecting them here too would give one value two sources of truth, and the
+  // snapshot is taken when the capability is built — before any hook runs. A
+  // hook that WITHDRAWS a registration then converges would have the stale
+  // snapshot put the subnet straight back, so the set could grow but never
+  // shrink. That is exactly what happened: `on_uninstall` withdrew the VPN's
+  // trusted source, logged success, and the reach rules were re-rendered anyway.
+  return {
+    zoneTiers,
+    trustedSubnets: loadTrustedSubnets(db).map((e) => e.subnet),
+    controlPlaneSubnet: loadControlPlaneSubnet(db) ?? readZoneSubnet(db, 'internal'),
+  };
 }
 
 async function buildFirewallChain(
@@ -732,13 +830,15 @@ async function buildFirewallChain(
   db: DbClient,
   logger: HookLogger,
   debugLog: (msg: string) => void,
+  consumingModuleId: string,
 ): Promise<unknown> {
   // The shared-core port-forward registry, injected into every firewall provider
   // in the chain so exposeService/converge reconcile against the one canonical
   // store (openspec/changes/unified-management-no-ssh/proposal.md).
   const store = buildPortForwardStore(db);
-  // Zone matrix for the default-DROP posture — same set for every layer in the chain.
-  const zones = loadFirewallZones(db);
+  // Trusted-source registry, bound to the CONSUMING module so a registration is
+  // attributable. Only the layers that render their own ruleset receive it.
+  const trustedSourceStore = buildTrustedSourceStore(db, consumingModuleId);
 
   // Find the provider with has_external (the leaf — has direct internet access)
   const hasExternal = allProviders.find((p) => {
@@ -783,6 +883,7 @@ async function buildFirewallChain(
       systems: getModuleSystems(hasExternal.moduleId, db),
       logger,
     });
+    leafFirewall = stampProvider(leafFirewall, hasExternal.moduleId);
     debugLog(
       `firewall chain: built leaf via defineCapabilityFunction from ${hasExternal.moduleId}`,
     );
@@ -794,7 +895,9 @@ async function buildFirewallChain(
       leafConfig,
       leafSecrets,
       store,
-      zones,
+      loadFirewallZones(db),
+      trustedSourceStore,
+      hasExternal.moduleId,
     );
     if (leafFirewall) {
       leafFirewall = wrapWithLogging(leafFirewall as object, logger, 'firewall');
@@ -850,6 +953,10 @@ async function buildFirewallChain(
     // celilo's ProgressDisplay instead of dumping to stderr. Older
     // iptables modules ignore it — the factory's signature is
     // backward-compatible.
+    // Zone matrix for the default-DROP posture. The same BASE set for every
+    // layer; each layer's own registrations are unioned in by its provider at
+    // converge time, from the live store.
+    const zones = loadFirewallZones(db);
     const downstreamFirewall = provFactory(
       {
         firewallIp,
@@ -857,15 +964,20 @@ async function buildFirewallChain(
         dryRun,
         zoneTiers: zones.zoneTiers,
         trustedSubnets: zones.trustedSubnets,
+        controlPlaneSubnet: zones.controlPlaneSubnet,
       },
       store,
       currentUpstream,
       logger,
+      trustedSourceStore,
     );
 
     debugLog(`firewall chain: wired ${provider.moduleId} → ${hasExternal.moduleId}`);
     // Wrap each downstream layer with auto-logging.
-    currentUpstream = wrapWithLogging(downstreamFirewall as object, logger, 'firewall');
+    currentUpstream = stampProvider(
+      wrapWithLogging(downstreamFirewall as object, logger, 'firewall'),
+      provider.moduleId,
+    );
   }
 
   return currentUpstream;

package/src/hooks/capability-map-coverage.test.ts

@@ -0,0 +1,101 @@
+/**
+ * Recurrence gate: every capability with a FUNCTION implementation is loadable.
+ *
+ * `CAPABILITY_MODULE_MAP` in capability-loader.ts is a hand-maintained table of
+ * capability name → the script that implements it. A module can ship a perfectly
+ * good `defineCapabilityFunction`, register the capability on deploy — and still
+ * be unreachable, because the loader skips anything absent from that table.
+ *
+ * The failure is silent and inverted: consumers get "does not provide the
+ * notification capability" for a module that demonstrably provides it. It cost
+ * the notification transport a full round-trip to find, so it gets a gate.
+ *
+ * Scoped to FUNCTION capabilities on purpose. A capability that provides only
+ * `data:` (`apt_publish`, `celilo_event_bus`) is read through `$capability:`
+ * variables and has nothing to load — the map would be the wrong place for it.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse } from 'yaml';
+import { CAPABILITY_MODULE_MAP } from './capability-loader';
+
+/** Capabilities the framework implements itself, with no provider script. */
+const FRAMEWORK_OWNED = new Set(['public_web']);
+
+/** Capability names a module implements as callable functions. */
+function functionCapabilitiesIn(moduleDir: string): Set<string> {
+  const found = new Set<string>();
+  const scriptsDir = join(MODULES_DIR, moduleDir, 'scripts');
+
+  let entries: string[];
+  try {
+    entries = readdirSync(scriptsDir).filter((f) => f.endsWith('.ts') && !f.endsWith('.test.ts'));
+  } catch {
+    return found;
+  }
+
+  for (const file of entries) {
+    const src = readFileSync(join(scriptsDir, file), 'utf-8');
+    // The declaration form is `capability: '<name>'` inside
+    // defineCapabilityFunction — matching it directly avoids inferring
+    // implementation from a filename.
+    if (!src.includes('defineCapabilityFunction')) continue;
+    for (const match of src.matchAll(/capability:\s*'([a-z_]+)'/g)) found.add(match[1]);
+  }
+
+  return found;
+}
+
+const MODULES_DIR = join(import.meta.dir, '../../../../modules');
+
+interface ManifestShape {
+  provides?: { capabilities?: { name?: string }[] };
+}
+
+function providedCapabilities(): Map<string, string[]> {
+  const byCapability = new Map<string, string[]>();
+
+  for (const entry of readdirSync(MODULES_DIR, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    let manifest: ManifestShape;
+    try {
+      manifest = parse(readFileSync(join(MODULES_DIR, entry.name, 'manifest.yml'), 'utf-8'));
+    } catch {
+      continue; // Not a module directory.
+    }
+
+    const implemented = functionCapabilitiesIn(entry.name);
+    for (const capability of manifest.provides?.capabilities ?? []) {
+      if (!capability.name || !implemented.has(capability.name)) continue;
+      const providers = byCapability.get(capability.name) ?? [];
+      providers.push(entry.name);
+      byCapability.set(capability.name, providers);
+    }
+  }
+
+  return byCapability;
+}
+
+describe('recurrence gate: function capabilities are loadable', () => {
+  const provided = providedCapabilities();
+
+  test('scans a non-trivial set of modules (sanity — the scan actually ran)', () => {
+    expect(provided.size).toBeGreaterThan(2);
+  });
+
+  test('every function capability a module implements is in CAPABILITY_MODULE_MAP', () => {
+    const missing: string[] = [];
+    for (const [capability, providers] of provided) {
+      if (FRAMEWORK_OWNED.has(capability)) continue;
+      if (capability in CAPABILITY_MODULE_MAP) continue;
+      missing.push(`${capability} (provided by ${providers.join(', ')})`);
+    }
+
+    expect(
+      missing,
+      `These capabilities ship a defineCapabilityFunction but are absent from CAPABILITY_MODULE_MAP, so loadCapabilityFunctions will never return them:\n  ${missing.join('\n  ')}`,
+    ).toEqual([]);
+  });
+});

package/src/manifest/schema.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { NETWORK_ZONES } from '../db/schema';
 import { SUPPORTED_CONTRACT_VERSIONS } from './contracts';
 
 /**
@@ -272,6 +273,75 @@ export const LifecycleHookSchema = z.object({
   timeout: z.number().positive().optional(),
 });
 
+/**
+ * Floor for a module's suggested `health_check` interval.
+ *
+ * The monitor sweep rides the event bus's fixed `timer.tick.5m`
+ * (packages/event-bus/src/timer.ts), so an interval below five minutes
+ * cannot be honoured — it would silently round up. Rejecting it at manifest
+ * validation is better than accepting a promise celilo can't keep.
+ */
+export const MONITOR_INTERVAL_FLOOR_MINUTES = 5;
+
+const DURATION_PATTERN = /^(\d+)(m|h|d)$/;
+
+/**
+ * Parse a duration string (`15m`, `1h`, `1d`) to whole minutes.
+ * Returns null when the string is not a well-formed duration.
+ */
+export function parseIntervalMinutes(value: string): number | null {
+  const match = DURATION_PATTERN.exec(value);
+  if (!match) return null;
+  const amount = Number.parseInt(match[1], 10);
+  if (!Number.isFinite(amount) || amount <= 0) return null;
+  const unit = match[2];
+  if (unit === 'm') return amount;
+  if (unit === 'h') return amount * 60;
+  return amount * 60 * 24;
+}
+
+/**
+ * `health_check` accepts everything a lifecycle hook does, plus an optional
+ * `interval` — the module author's SUGGESTED monitoring cadence.
+ *
+ * It is only a suggestion: the operator's `monitors` row is the effective
+ * schedule and survives module upgrades (openspec/changes/add-alerting
+ * design D3). A module that omits it is simply not monitored until an
+ * operator creates a monitor by hand.
+ */
+export const HealthCheckHookSchema = LifecycleHookSchema.extend({
+  // `.regex` duplicates the well-formedness half of the `superRefine` below on
+  // purpose: only `.regex` survives the export to JSON Schema, and that export is
+  // what validates `modules/*/manifest.yml` in the editor. The 5-minute floor
+  // cannot be expressed in JSON Schema at all, so it stays a refinement — which
+  // is why both exist rather than one. Keeping them in sync is the point of
+  // sharing DURATION_PATTERN.
+  interval: z
+    .string()
+    .regex(DURATION_PATTERN)
+    .optional()
+    .describe(
+      'Suggested monitoring cadence, e.g. "15m", "1h", "1d". Must be 5m or longer — the monitor sweep runs on a 5-minute grid.',
+    )
+    .superRefine((value, ctx) => {
+      if (value === undefined) return;
+      const minutes = parseIntervalMinutes(value);
+      if (minutes === null) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `Invalid health_check interval "${value}". Use a duration like "15m", "1h", or "1d".`,
+        });
+        return;
+      }
+      if (minutes < MONITOR_INTERVAL_FLOOR_MINUTES) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `health_check interval "${value}" is below the ${MONITOR_INTERVAL_FLOOR_MINUTES}m floor — the monitor sweep runs on a ${MONITOR_INTERVAL_FLOOR_MINUTES}-minute grid and cannot run it more often. Use "${MONITOR_INTERVAL_FLOOR_MINUTES}m" or longer.`,
+        });
+      }
+    }),
+});
+
 /**
  * Build-bus upstream-publish hook. Fires when a publish event lands
  * on the local event bus from the receiver daemon
@@ -320,9 +390,10 @@ export const SystemResourceSchema = z.object({
       'Proxmox provisioning type: lxc (default) or vm (qemu, for Docker / kernel-module workloads). ' +
         'Modules declare this explicitly; celilo never infers it. Moot for machine-pool / external infra.',
     ),
-  zone: z
-    .enum(['internal', 'dmz', 'app', 'secure', 'secure-mgmt', 'external'])
-    .describe('Required security zone for this module'),
+  // Derived from NETWORK_ZONES, not re-listed: a hand-written copy here would be
+  // a fourth place a new zone has to be remembered, and the copies in
+  // module-show and machine-pool had both already drifted.
+  zone: z.enum(NETWORK_ZONES).describe('Required security zone for this module'),
 });
 
 /**
@@ -535,7 +606,9 @@ export const ModuleManifestSchema = z
         container_created: LifecycleHookSchema.optional(),
         on_install: LifecycleHookSchema.optional(),
         on_uninstall: LifecycleHookSchema.optional(),
-        health_check: LifecycleHookSchema.optional(),
+        health_check: HealthCheckHookSchema.optional().describe(
+          "Health check hook. `interval` is the module's SUGGESTED monitoring cadence; the operator's monitor row is the effective schedule and always wins.",
+        ),
         validate_config: LifecycleHookSchema.optional(),
         on_backup: LifecycleHookSchema.optional(),
         on_backup_analyze: LifecycleHookSchema.optional(),