@celilo/cli 0.11.0-alpha.0 → 0.12.0

package/src/cli/index.ts

@@ -77,11 +77,11 @@ import { handleModuleUpdate } from './commands/module-update';
 import { handleModuleUpgrade } from './commands/module-upgrade';
 import { moduleVerify } from './commands/module-verify';
 import { handleModuleVersion } from './commands/module-version';
+import { handleModuleWhere } from './commands/module-where';
 import { handlePackage } from './commands/package';
 import { handleProxmoxInstanceList } from './commands/proxmox-instance-list';
 import { handleProxmoxInstanceResize } from './commands/proxmox-instance-resize';
 import { handleProxmoxNodeList } from './commands/proxmox-node-list';
-import { main as runPublish } from './commands/publish';
 import { handleSecretList } from './commands/secret-list';
 import { handleSecretSet } from './commands/secret-set';
 import { handleServiceAddDigitalOcean } from './commands/service-add-digitalocean';
@@ -193,6 +193,8 @@ Commands:
   ipam                     Manage IP address and VMID allocations and reservations
   proxmox                  Proxmox cluster introspection (proxmox node list)
   publish                  Publish workspace packages to npm and modules to celilo.computer
+  registry                 Administer the module registry (append-safe publish-token management)
+  token                    Manage contributor identity tokens (idp-issued per-user publish tokens)
   subscribers              Manage build-bus subscribers (cross-machine publish-event delivery)
   api                      Manage remote-API access (principals, grants, authorized_keys)
   completion               Generate shell completion scripts (bash/zsh)
@@ -301,7 +303,7 @@ Description:
   Modules declare \`subscriptions:\` in their manifests; \`celilo module deploy\`
   emits lifecycle events that subscribers react to.
 
-  See infra/design/SQLITE_EVENT_BUS.md for the full design.
+  See infra/openspec/specs/event-bus/spec.md for the full design.
 
 Examples:
   celilo events run                                      # foreground dispatcher
@@ -340,7 +342,7 @@ Description:
   package name glob). The publisher signs every event with the
   subscriber's secret; the receiver verifies before reacting.
 
-  This is the static-config first cut of v2/BUILD_BUS.md — operators
+  This is the static-config first cut of openspec/changes/build-bus-poll-cd/proposal.md — operators
   manage subscribers explicitly. Auto-discovery via the celilo
   registry switchboard is a follow-on.
 
@@ -433,6 +435,79 @@ Examples:
   return { success: true, message: helpText };
 }
 
+function displayRegistryHelp(): CommandResult {
+  const helpText = `
+Celilo - Module Registry Administration
+
+Usage:
+  celilo registry <subcommand> [args...]
+
+Subcommands:
+  token add <token>            Append a publish token (append-safe; never clobbers others)
+  token rm <token>             Remove one publish token, leaving the rest intact
+  owner list                   List the module-owner table (who may publish what)
+  owner show <module>          Show the owner of one module name
+  owner set <module> <sub>     Reassign a module name to a new owner (admin)
+
+Description:
+  The celilo-registry module's publish_tokens secret is a newline-separated list
+  of bootstrap/admin publish tokens. Editing it with 'module secret set' OVERWRITES
+  the whole list, clobbering every other holder. These commands read-modify-write
+  the list instead.
+
+  The module-owner table (owner *) gates which module NAMES a verified publisher
+  may publish: the first verified publisher of an unclaimed name owns it
+  (first-publish-claims); thereafter only that owner or an admin may publish it.
+  'owner set' is the admin reassignment. These read the admin token from the local
+  publish_tokens list; pass --registry to target a non-default registry.
+
+  Run on the host where celilo-registry is deployed (where the master key lives).
+
+Examples:
+  celilo registry token add ci-token-abc123
+  celilo registry owner list
+  celilo registry owner show homebridge
+  celilo registry owner set homebridge alice
+`;
+
+  return { success: true, message: helpText.trim() };
+}
+
+function displayTokenHelp(): CommandResult {
+  const helpText = `
+Celilo - Contributor Identity Tokens (idp-issued, per-user)
+
+Usage:
+  celilo token <subcommand> [args...]
+
+Subcommands:
+  obtain --user <username>    Mint (or return) a per-user API token for publishing
+  list   --user <username>    List a user's API tokens (metadata only, no secret)
+  revoke <identifier>         Revoke a token by identifier; next publish denied
+
+Options:
+  --user <username>           The idp user the token is bound to
+  --identifier <id>           Token identifier (default: celilo-publish-<user>)
+  --description <text>        Human-readable description (obtain only)
+
+Description:
+  Issues per-user API tokens from the idp (authentik) so a module contributor
+  authenticates publishes AS THEMSELVES — no admin/shared token on their machine.
+  The token is consumed by 'celilo author init'. Shown once at mint; the idp
+  stores it hashed and celilo persists nothing.
+
+  Distinct from 'celilo registry token add/rm', which manages the raw bootstrap
+  publish_tokens list. Run on the host where the idp is deployed (celilo-mgr).
+
+Examples:
+  celilo token obtain --user alice
+  celilo token list --user alice
+  celilo token revoke celilo-publish-alice
+`;
+
+  return { success: true, message: helpText.trim() };
+}
+
 function displayCapabilityHelp(): CommandResult {
   const helpText = `
 Celilo - Capability Management
@@ -1206,6 +1281,71 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
     };
   }
 
+  if (parsed.command === 'registry') {
+    if (parsed.flags.help || parsed.flags.h || !parsed.subcommand) {
+      return displayRegistryHelp();
+    }
+
+    const registryFlagError = checkFlags('registry', parsed.subcommand, parsed.flags, parsed.args);
+    if (registryFlagError) return registryFlagError;
+
+    if (parsed.subcommand === 'token') {
+      const action = parsed.args[0];
+      const tokenArgs = parsed.args.slice(1);
+      const { handleRegistryTokenAdd, handleRegistryTokenRm } = await import(
+        './commands/registry-token'
+      );
+      if (action === 'add') return handleRegistryTokenAdd(tokenArgs);
+      if (action === 'rm') return handleRegistryTokenRm(tokenArgs);
+      return {
+        success: false,
+        error:
+          'Token action required (add or rm)\n\nUsage:\n  celilo registry token add <token>\n  celilo registry token rm <token>',
+      };
+    }
+
+    if (parsed.subcommand === 'owner') {
+      const action = parsed.args[0];
+      const ownerArgs = parsed.args.slice(1);
+      const { handleRegistryOwnerList, handleRegistryOwnerShow, handleRegistryOwnerSet } =
+        await import('./commands/registry-owner');
+      if (action === 'list') return handleRegistryOwnerList(parsed.flags);
+      if (action === 'show') return handleRegistryOwnerShow(ownerArgs, parsed.flags);
+      if (action === 'set') return handleRegistryOwnerSet(ownerArgs, parsed.flags);
+      return {
+        success: false,
+        error:
+          'Owner action required (list, show, or set)\n\nUsage:\n  celilo registry owner list\n  celilo registry owner show <module>\n  celilo registry owner set <module> <owner-sub>',
+      };
+    }
+
+    return {
+      success: false,
+      error: `Unknown registry subcommand: ${parsed.subcommand}\n\nRun "celilo registry --help" for usage`,
+    };
+  }
+
+  if (parsed.command === 'token') {
+    if (parsed.flags.help || parsed.flags.h || !parsed.subcommand) {
+      return displayTokenHelp();
+    }
+
+    const tokenFlagError = checkFlags('token', parsed.subcommand, parsed.flags, parsed.args);
+    if (tokenFlagError) return tokenFlagError;
+
+    const { handleTokenObtain, handleTokenList, handleTokenRevoke } = await import(
+      './commands/token'
+    );
+    if (parsed.subcommand === 'obtain') return handleTokenObtain(parsed.args, parsed.flags);
+    if (parsed.subcommand === 'list') return handleTokenList(parsed.args, parsed.flags);
+    if (parsed.subcommand === 'revoke') return handleTokenRevoke(parsed.args, parsed.flags);
+
+    return {
+      success: false,
+      error: `Unknown token subcommand: ${parsed.subcommand}\n\nRun "celilo token --help" for usage`,
+    };
+  }
+
   if (parsed.command === 'publish') {
     if (parsed.flags.help || parsed.flags.h) {
       return displayPublishHelp();
@@ -1218,6 +1358,15 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
     // flag identity since the parser canonicalises those.
     const publishIdx = process.argv.indexOf('publish');
     const publishArgv = publishIdx >= 0 ? process.argv.slice(publishIdx + 1) : [...parsed.args];
+    // Lazy-load the publish command: it's monorepo-only release tooling whose
+    // transitive import chain reaches scripts/workspace-graph.ts, which does NOT
+    // ship in @celilo/cli's files[]. A static top-level import pulled that into
+    // EVERY command's load graph, so `celilo --version` in a consumer install
+    // crashed on the unresolvable module (WORKSPACE_PACKAGE_GRAPH.md — the D3
+    // failure, deeper than the module-load throw). Loading it only when the
+    // operator actually runs `celilo publish` (which only happens in the
+    // monorepo) keeps every other command free of the dependency.
+    const { main: runPublish } = await import('./commands/publish');
     await runPublish(publishArgv);
     // runPublish handles its own console output (multi-phase, multi-line);
     // returning an empty success message tells the outer CLI loop to skip
@@ -1306,6 +1455,8 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
         return handleModuleList(parsed.flags);
       case 'status':
         return handleModuleStatus(parsed.args);
+      case 'where':
+        return handleModuleWhere(parsed.args, parsed.flags);
       case 'logs':
         return handleModuleLogs(parsed.args, parsed.flags);
       case 'health':
@@ -1697,7 +1848,7 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
   }
 
   if (parsed.command === 'restore') {
-    // Phase 4 of v2/SYSTEM_BACKUP_TERRAFORM_STATE.md — top-level
+    // Phase 4 of openspec/specs/management-server-backup/spec.md — top-level
     // fresh-bootstrap restore. Distinct from `celilo backup restore
     // <id>` (which restores from a configured storage destination
     // using an existing backup record); this one takes a local file

package/src/cli/restore-command.test.ts

@@ -1,6 +1,6 @@
 /**
  * Tests for the `celilo restore` top-level command (Phase 4 of
- * v2/SYSTEM_BACKUP_TERRAFORM_STATE.md).
+ * openspec/specs/management-server-backup/spec.md).
  *
  * Covers the CLI surface: routing, argument parsing, pre-flight
  * gating, error propagation. The actual file-direct restore +

package/src/db/client.ts

@@ -92,7 +92,7 @@ export function createDbClient(config?: Partial<DatabaseConfig>) {
   }
 
   // One-time upgrade backfill for the target_ip → module_systems refactor
-  // (v2/MODULE_SYSTEMS_ADDRESSING.md). migrate() above has ensured the
+  // (openspec/specs/module-systems-addressing/spec.md). migrate() above has ensured the
   // module_systems table exists (migration 0007). A deployment created before
   // the refactor has its host data only in module_configs /
   // ip_allocations / module_infrastructure and an EMPTY module_systems, so its

package/src/db/schema.ts

@@ -318,7 +318,7 @@ export const machines = sqliteTable('machines', {
    * Appliance machines (e.g., greenwave = ISP modem) where celilo
    * has no shell-level access — only API calls. Base-module aspects
    * cannot Ansible to these systems, so the aspect runner skips
-   * them. See v2/CELILO_BASE.md D8.
+   * them. See openspec/specs/base-module-aspects/spec.md D8.
    */
   apiOnly: integer('api_only', { mode: 'boolean' }).notNull().default(false),
   createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
@@ -345,7 +345,7 @@ export const moduleInfrastructure = sqliteTable('module_infrastructure', {
    * driver registers an entry that has no SSH surface (rare today,
    * but exists for future API-only providers). Aspect runner reads
    * this to decide whether the system is reachable via Ansible.
-   * See v2/CELILO_BASE.md D8.
+   * See openspec/specs/base-module-aspects/spec.md D8.
    */
   apiOnly: integer('api_only', { mode: 'boolean' }).notNull().default(false),
   createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
@@ -358,7 +358,7 @@ export const moduleInfrastructure = sqliteTable('module_infrastructure', {
  * deployment-STATE counterpart to module_configs (declared inputs): it records,
  * per deployed system, the hostname + IPv4 + zone + where it lives. Replaces the
  * old scalar `target_ip`/`vmid` rows in module_configs, which baked in the
- * one-module-one-host assumption. See v2/MODULE_SYSTEMS_ADDRESSING.md.
+ * one-module-one-host assumption. See openspec/specs/module-systems-addressing/spec.md.
  *
  *   - 0 rows: API-only modules (e.g. namecheap — no host).
  *   - 1 row:  the common case (technitium, homebridge, …).
@@ -368,7 +368,7 @@ export const moduleInfrastructure = sqliteTable('module_infrastructure', {
  * the manifest's `requires.systems[].name` — what templates reference via
  * `$infra:<name>.…`. `hostname` is the runtime DNS hostname (often == name, but
  * user/well-known-assignable), used by DNS and events. See
- * v2/MODULE_SYSTEMS_ADDRESSING.md.
+ * openspec/specs/module-systems-addressing/spec.md.
  */
 export const moduleSystems = sqliteTable(
   'module_systems',
@@ -443,6 +443,49 @@ export const webRoutes = sqliteTable(
   }),
 );
 
+/**
+ * Port-forward registry — the desired-state store for the `firewall` capability
+ * (openspec/changes/unified-management-no-ssh/proposal.md). One row per exposed forward. `exposeService`
+ * upserts, `unexposeService` deletes, and the firewall provider's converge
+ * renders the COMPLETE ruleset for a firewall from these rows and applies it
+ * atomically via `iptables-restore` — replacing the old per-rule `iptables -A`
+ * (non-idempotent) + the "read the box back with iptables -L" source of truth.
+ *
+ * Keyed by `firewall_ip` (the converge target) so multiple firewalls each render
+ * their own set. Shared-core (not a per-module JSON file) so any firewall
+ * provider reconciles against the one canonical store.
+ */
+export const portForwards = sqliteTable(
+  'port_forwards',
+  {
+    id: integer('id').primaryKey({ autoIncrement: true }),
+    /** The firewall host this forward is installed on (config.firewallIp). */
+    firewallIp: text('firewall_ip').notNull(),
+    /** Backend IP the forward targets. */
+    internalIp: text('internal_ip').notNull(),
+    /** Port — external == internal (no translation today). */
+    port: integer('port').notNull(),
+    protocol: text('protocol').$type<'TCP' | 'UDP'>().notNull(),
+    /** Dedicated INTERNAL ingress IP (ISS-0156); NULL for the normal public path. */
+    ingressIp: text('ingress_ip'),
+    description: text('description').notNull().default(''),
+    createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+  },
+  (table) => ({
+    // One row per (firewall, backend, port, protocol, ingress). The store also
+    // delete-then-inserts on this tuple so a re-expose is an idempotent upsert
+    // (NULL ingress_ip is compared with `is null` there, since SQLite treats
+    // NULLs as distinct in a unique index).
+    forwardUnique: uniqueIndex('port_forwards_unique_idx').on(
+      table.firewallIp,
+      table.internalIp,
+      table.port,
+      table.protocol,
+      table.ingressIp,
+    ),
+  }),
+);
+
 /**
  * DNS registration ledger — one row per (provider, fqdn) the framework
  * has successfully registered via dns_registrar.registerHost. Written
@@ -509,7 +552,7 @@ export const dnsInternalRecords = sqliteTable(
     /**
      * In-zone split-horizon answer (caddy's zone-routable IP), when this is a
      * caddy-fronted hostname that needs source-based views (ISS-0156,
-     * v2/INTERNAL_DNS_ZONE_VIEWS.md). NULL for records with no zone override
+     * openspec/specs/internal-dns-zone-views/spec.md). NULL for records with no zone override
      * (per-system identity, plain A records). This column is the durable
      * desired-state the resolver's view config is reconciled from.
      */
@@ -621,7 +664,7 @@ export const moduleOperations = sqliteTable('module_operations', {
  * per module version. Cascade delete on module removal so stale
  * approvals don't linger.
  *
- * See v2/CELILO_BASE.md D2 + D7.
+ * See openspec/specs/base-module-aspects/spec.md D2 + D7.
  */
 export const aspectApprovals = sqliteTable(
   'aspect_approvals',
@@ -655,7 +698,7 @@ export const aspectApprovals = sqliteTable(
 );
 
 /**
- * Remote API principals (see v2/API_COMMUNICATION.md).
+ * Remote API principals (see openspec/changes/replace-ssh-cli-api/proposal.md).
  *
  * Each row is one API identity: a name, one SSH public key, and the set of
  * operations it may run. celilo renders these into the API account's

package/src/hooks/capability-loader-firewall.test.ts

@@ -47,12 +47,13 @@ export default defineCapabilityFunction({
 `;
 
 // Mock iptables firewall factory — kept on the legacy
-// `createFirewall(config, upstreamFirewall)` shape because its
+// `createFirewall(config, store, upstreamFirewall, logger)` shape because its
 // upstream-injection signature doesn't fit the
 // defineCapabilityFunction `{ config, secrets, logger }` context.
-// buildFirewallChain detects this and wires the upstream manually.
+// buildFirewallChain injects the port-forward store (2nd arg) and wires the
+// upstream (3rd arg) manually. The mock ignores store (no converge here).
 const MOCK_IPTABLES_MODULE = `
-export function createFirewall(config, upstreamFirewall) {
+export function createFirewall(config, store, upstreamFirewall, logger) {
   return {
     exposeService: async (opts) => {
       if (!upstreamFirewall) {

package/src/hooks/capability-loader.ts

@@ -21,18 +21,20 @@ import type {
   DnsInternalCapability,
   DnsRegistrarCapability,
   HookLogger,
+  PortForwardStore,
   RouteOps,
   RouteReadView,
 } from '@celilo/capabilities';
 import { and, eq } from 'drizzle-orm';
 import type { DbClient } from '../db/client';
-import { capabilities, modules, secrets, webRoutes } from '../db/schema';
+import { capabilities, modules, secrets, systemConfig, webRoutes } from '../db/schema';
 import { decryptSecret } from '../secrets/encryption';
 import { getOrCreateMasterKey } from '../secrets/master-key';
 import { emitWebRoutesChangedAndWait } from '../services/celilo-events';
 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 { resolveComputedFields } from '../variables/computed/evaluate';
 import { containsComputedMarker } from '../variables/computed/marker';
 import { buildProviderLookup } from '../variables/computed/provider-lookup';
@@ -288,6 +290,10 @@ export async function loadCapabilityFunctions(
         exported,
         providerConfig,
         providerSecrets,
+        // Single firewall provider (no upstream chain) still needs the injected
+        // port-forward store — the chain path isn't taken when there's one provider.
+        capName === 'firewall' ? buildPortForwardStore(db) : undefined,
+        capName === 'firewall' ? loadFirewallZones(db) : undefined,
       );
 
       if (capabilityInterface) {
@@ -326,6 +332,17 @@ export async function loadCapabilityFunctions(
       debugLog(`public_web: using firewall natIp ${firewallNatIp} for internal DNS`);
     }
 
+    // Caddy's external (WAN) IP for the D1 public A record (M1 / #328). Caddy
+    // learns it from its own firewall.exposeService at install and persists it
+    // as the `public_ip` hook output (stored as a caddy secret). register_route
+    // points a new hostname's PUBLIC record here, so it's reachable from one
+    // deploy — no per-hostname DNAT (shared :443 ingress).
+    const caddyExternalIp =
+      typeof providerSecrets.public_ip === 'string' ? providerSecrets.public_ip : undefined;
+    if (caddyExternalIp) {
+      debugLog(`public_web: using caddy externalIp ${caddyExternalIp} for public DNS`);
+    }
+
     // Caddy's configured hostnames — public_web rejects routes for any
     // hostname not in this list, throwing a structured error that runs
     // caddy's `managed_hostname` ensure interview. Empty list means
@@ -437,6 +454,8 @@ export async function loadCapabilityFunctions(
         routeOps,
         dnsInternal: result.dns_internal as DnsInternalCapability | undefined,
         firewallNatIp,
+        dnsRegistrar: result.dns_registrar as DnsRegistrarCapability | undefined,
+        externalIp: caddyExternalIp,
         hostnames: caddyHostnames,
         caddyModuleId: provider.moduleId,
         dnsManagedDomains,
@@ -525,16 +544,28 @@ function buildCapabilityInterface(
   factory: (...args: unknown[]) => unknown,
   config: Record<string, unknown>,
   _secrets: Record<string, string>,
+  store?: PortForwardStore,
+  zones?: FirewallZones,
 ): unknown {
   if (capabilityName === 'firewall') {
-    // iptables firewall factory: SSH access + NAT config (upstream is
-    // injected by buildFirewallChain when this module is downstream of
-    // another firewall provider).
+    // iptables firewall factory: NAT config + the injected port-forward store
+    // (createFirewall(config, store, upstream?, logger?)). Upstream is injected
+    // by buildFirewallChain when this module is downstream of another provider.
+    // The firewall is only built through buildFirewallChain, which always passes
+    // a store — guard so a mis-route surfaces loudly rather than as store=undefined.
     if (config.firewall_ip && config.nat_ip) {
-      return factory({
-        firewallIp: config.firewall_ip as string,
-        natIp: config.nat_ip as string,
-      });
+      if (!store) {
+        throw new Error('firewall capability requires an injected port-forward store');
+      }
+      return factory(
+        {
+          firewallIp: config.firewall_ip as string,
+          natIp: config.nat_ip as string,
+          zoneTiers: zones?.zoneTiers ?? [],
+          trustedSubnets: zones?.trustedSubnets ?? [],
+        },
+        store,
+      );
     }
     return null;
   }
@@ -624,6 +655,40 @@ async function resolveRegistrarDomainList(
  * on the legacy `createFirewall(config, upstream)` path because its
  * upstream-injection signature doesn't fit the new shape.
  */
+/** Most-exposed → most-protected SEGMENTED tiers for the firewall default-DROP matrix. */
+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 }>;
+  /** Trusted LAN subnets (internal) that reach every tier — celilo's control plane. */
+  trustedSubnets: string[];
+}
+
+function readZoneSubnet(db: DbClient, zone: string): string | undefined {
+  const row = db
+    .select()
+    .from(systemConfig)
+    .where(eq(systemConfig.key, `network.${zone}.subnet`))
+    .get();
+  return row?.value ?? undefined;
+}
+
+/**
+ * Read the firewall zone matrix inputs from system config (network.<zone>.subnet):
+ * the segmented tiers [dmz, app, secure] and the trusted internal LAN. Zones with
+ * no configured subnet are omitted — their traffic stays denied (fail-closed).
+ */
+function loadFirewallZones(db: DbClient): FirewallZones {
+  const zoneTiers: Array<{ name: string; subnet: string }> = [];
+  for (const zone of ZONE_TIER_ORDER) {
+    const subnet = readZoneSubnet(db, zone);
+    if (subnet) zoneTiers.push({ name: zone, subnet });
+  }
+  const internal = readZoneSubnet(db, 'internal');
+  return { zoneTiers, trustedSubnets: internal ? [internal] : [] };
+}
+
 async function buildFirewallChain(
   allProviders: Array<{
     id: number;
@@ -638,6 +703,13 @@ async function buildFirewallChain(
   logger: HookLogger,
   debugLog: (msg: string) => void,
 ): 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);
+
   // Find the provider with has_external (the leaf — has direct internet access)
   const hasExternal = allProviders.find((p) => {
     const data = (typeof p.data === 'string' ? JSON.parse(p.data) : p.data) as Record<
@@ -686,7 +758,14 @@ async function buildFirewallChain(
     );
   } else {
     // Legacy factory path
-    leafFirewall = buildCapabilityInterface('firewall', leafExported, leafConfig, leafSecrets);
+    leafFirewall = buildCapabilityInterface(
+      'firewall',
+      leafExported,
+      leafConfig,
+      leafSecrets,
+      store,
+      zones,
+    );
     if (leafFirewall) {
       leafFirewall = wrapWithLogging(leafFirewall as object, logger, 'firewall');
     }
@@ -741,7 +820,18 @@ async function buildFirewallChain(
     // celilo's ProgressDisplay instead of dumping to stderr. Older
     // iptables modules ignore it — the factory's signature is
     // backward-compatible.
-    const downstreamFirewall = provFactory({ firewallIp, natIp, dryRun }, currentUpstream, logger);
+    const downstreamFirewall = provFactory(
+      {
+        firewallIp,
+        natIp,
+        dryRun,
+        zoneTiers: zones.zoneTiers,
+        trustedSubnets: zones.trustedSubnets,
+      },
+      store,
+      currentUpstream,
+      logger,
+    );
 
     debugLog(`firewall chain: wired ${provider.moduleId} → ${hasExternal.moduleId}`);
     // Wrap each downstream layer with auto-logging.

package/src/hooks/define-hook.test.ts

@@ -95,6 +95,12 @@ const fakeIdp: IdpCapability = {
   async create_token() {
     return { token: 'fake-token', created: true };
   },
+  async list_tokens() {
+    return [];
+  },
+  async revoke_token() {
+    return { revoked: true };
+  },
 };
 
 describe('defineHook', () => {
@@ -260,6 +266,12 @@ describe('defineCapabilityFunction', () => {
         async create_token() {
           return { token: 'fake-token', created: true };
         },
+        async list_tokens() {
+          return [];
+        },
+        async revoke_token() {
+          return { revoked: true };
+        },
       }),
     });
 
@@ -323,6 +335,12 @@ describe('defineCapabilityFunction', () => {
           async create_token(): Promise<{ token: string; created: boolean }> {
             return { token: 'tok', created: true };
           },
+          async list_tokens() {
+            return [];
+          },
+          async revoke_token(): Promise<{ revoked: boolean }> {
+            return { revoked: true };
+          },
         };
       },
     });
@@ -459,6 +477,12 @@ void defineCapabilityFunction({
     async create_token() {
       return { token: 'x', created: true };
     },
+    async list_tokens() {
+      return [];
+    },
+    async revoke_token() {
+      return { revoked: true };
+    },
   }),
 });
 

package/src/hooks/executor.test.ts

@@ -469,7 +469,7 @@ describe('Hook Executor', () => {
       // cross_module_read is a privilege granted by the framework to the
       // hooks that use it (backup/restore), not a provider-loaded
       // capability. It must not block other hooks like on_install
-      // (regression: celilo-mgmt deploy, v2/NETWORK_CONFIG_TO_FIREWALL.md).
+      // (regression: celilo-mgmt deploy, openspec/specs/progressive-zone-disclosure/spec.md).
       expect(checkRequiredCapabilities('on_install', ['cross_module_read'], {})).toBeNull();
       // Real missing providers still flagged alongside a privilege.
       const mixed = checkRequiredCapabilities('on_install', ['cross_module_read', 'idp'], {});

package/src/hooks/executor.ts

@@ -202,7 +202,7 @@ async function runScript(
 
   if (!isCompiledHook(module.default)) {
     throw new Error(
-      `Hook script ${scriptPath} does not use defineHook(). As of HOOK_API_V2 Phase 8, all hook scripts must wrap their handler with defineHook from @celilo/capabilities so the executor can verify the brand and apply pre-flight checks. See design/MODULE_DEVELOPMENT_GUIDE.md "Hooks" section for the migration pattern.`,
+      `Hook script ${scriptPath} does not use defineHook(). As of HOOK_API_V2 Phase 8, all hook scripts must wrap their handler with defineHook from @celilo/capabilities so the executor can verify the brand and apply pre-flight checks. See reference/MODULE_DEVELOPMENT_GUIDE.md "Hooks" section for the migration pattern.`,
     );
   }
 
@@ -263,7 +263,7 @@ export interface InvokeHookOptions {
   capabilities?: Record<string, unknown>;
   /**
    * The module's 0..N deployed systems, injected as `ctx.systems`
-   * (v2/MODULE_SYSTEMS_ADDRESSING.md). Callers load these from the DB via
+   * (openspec/specs/module-systems-addressing/spec.md). Callers load these from the DB via
    * `getModuleSystems` — the executor stays decoupled from the database, the
    * same way `capabilities` is loaded by the caller. Defaults to `[]`.
    */

package/src/hooks/types.ts

@@ -55,7 +55,7 @@ export interface HookContext {
   /** Module secret values (decrypted) */
   secrets: Record<string, string>;
   /**
-   * The 0..N systems this module has deployed onto (v2/MODULE_SYSTEMS_ADDRESSING.md).
+   * The 0..N systems this module has deployed onto (openspec/specs/module-systems-addressing/spec.md).
    * Always an array — no singular convenience, so the 0/1/N reality stays visible.
    */
   systems: DeployedSystem[];

package/src/manifest/contracts/v1.ts

@@ -145,7 +145,7 @@ export const V1_HOOKS: ContractHooks = {
     },
   },
   /**
-   * Per-system DNS lifecycle hook (v2/INTERNAL_DNS_DHCP_AND_SPLIT_HORIZON.md D5).
+   * Per-system DNS lifecycle hook (openspec/specs/internal-dns-split-horizon/spec.md D5).
    *
    * A dns_internal provider declares this hook; celilo's internal-dns bridge
    * invokes it once per host when a system.created/destroyed event fires,
@@ -198,7 +198,7 @@ export const V1_HOOKS: ContractHooks = {
    * Build-bus upstream publish hook. The executor passes the
    * PublishEvent fields as env vars (CELILO_EVENT_PAYLOAD,
    * CELILO_EVENT_PACKAGE_NAME, etc.) rather than as named inputs
-   * here — see v2/BUILD_BUS.md Phase 4 + the hook-dispatch executor.
+   * here — see openspec/changes/build-bus-poll-cd/proposal.md Phase 4 + the hook-dispatch executor.
    * No structured outputs; hook reports success via exit code.
    */
   on_upstream_publish: {