@celilo/cli 1.0.0 → 1.1.0

package/CELILO_CORE_MODULES.md

@@ -19,6 +19,19 @@ Each entry: `module id` — what it is — **provides** / **requires** capabilit
 > (**knot-unbound-internal** / **technitium**). Identity comes from **authentik** (`idp`). That's
 > the whole edge: DNS + firewall + ingress + identity, each a swappable provider module.
 
+> How the graph OPENS again: when a consumer is removed, celilo dispatches
+> `on_consumer_removed` to every provider of every capability that consumer
+> declared, and each withdraws what it minted on its behalf
+> (openspec/changes/consumer-removal-cleanup). Providers implementing it:
+> **caddy** and **caddy-internal** (drop the routes, reclaim `/srv/www/<slug>`),
+> **iptables** / **greenwave** / **axon** (drop the forwards and trusted
+> sources), **authentik** (delete the OIDC application), **forgejo**
+> (deregister the CI runner), **generic-cpanel-hosting-provider** (remove the
+> published docroot). Consumers do NOT withdraw their own state any more — a
+> module gives a port or a subnet back by narrowing its own declaration, and
+> departing entirely is the provider's job. A provider that fails to withdraw
+> is marked ERROR; the removal still completes.
+
 ## Network fabric (DNS / firewall / DHCP)
 
 - **axon** — Axon Networks Q1000K ISP router driver (Brightspeed-branded); port-forwarding + public-IP discovery + DHCP DNS + DHCP address-pool bounds via the TR-181 CGI API. **provides:** `firewall`, `dhcp_server`. Fork of **greenwave** — identical protocol, differing only in the vendor extension prefix (`X_AXON_` vs `X_GWS_`/`X_LANTIQ_COM_`). Pick by device: Q1000K → **axon**, C4000XG → **greenwave**. Two device behaviours shape this driver and are not shared by **greenwave** (celilo#739): the router **regenerates** `Pool.1.DNSServers` from its own upstream resolver list every ~15 min and on any config commit, so `setDhcpDns` also writes `Device.DNS.X_AXON_CustomServer` — the *input* to that computation, which survives — and **technitium re-asserts** the pool value on `timer.tick.1m`. Optional `dhcp_pool_start`/`dhcp_pool_end` bound the leased range; set them below the addresses IPAM allocates, because **IPAM has no knowledge of the router's DHCP pool** and nothing otherwise stops the router leasing an address celilo already assigned.
@@ -28,12 +41,12 @@ Each entry: `module id` — what it is — **provides** / **requires** capabilit
 - **technitium** — internal split-horizon DNS resolver + authoritative server (web UI + HTTP API); heavier alternative to knot-unbound. **provides:** `dns_internal`. Ships a base-module-aspect (`modules/technitium/base-module-aspect/`).
 - **namecheap** — public DNS A-record management via Namecheap Dynamic DNS API (HTTP, no browser automation). A caller supplies a NAME and nothing else: the address is the source IP of celilo's own update, re-derived on every assert. Registering `<domain>` also claims `www.<domain>` and vice versa (best effort, reported back as `outputs.companion_fqdn` so the framework's `public_dns` check watches it — Namecheap answers `ErrCount 0` for `www` updates it does not apply). DDNS passwords are keyed by the **registrable domain**, never the FQDN. **provides:** `dns_registrar`.
 - **wireguard** — owns the admin WireGuard tunnel on the firewall host: interface, listen port, peers (as records), and client subnet are module config rather than hand-maintained state. Exposes the listen port and **registers the client subnet as a trusted source**, so VPN reach into the managed zones is in the firewall registry and every converge re-emits it. **REQUIRES the `control-plane-vpn` network and READS its range** (`requires.networks`; `client_subnet` is a `source: system` derive of `network.control-plane-vpn.subnet`). It does not write that network and has no way to — celilo owns the namespace, and the deploy will not reach any hook until the network is defined, asking for a range if one is missing. So `wg0` is attributable the moment it exists. This replaces a declare-before-you-create ordering inside `on_install`, which could only narrow the window and not close it: a consumer that captured config before the hook started could not see a value the hook wrote, whatever order it wrote it in, and that is exactly what left `wg0` unattributable (celilo#759). `health_check` still asserts the declaration matches what the tunnel serves — what it catches now is divergence, celilo's network having changed since the module resolved its config. That same key is what the internal resolver's split-horizon view consumes. Adopts a running tunnel in place (existing key retained; `wg syncconf`, never `wg-quick down`) because that tunnel is the operator's recovery path. **Adoption is a one-time IMPORT and it ENDS.** The marker is `registered_peers` — celilo's own config key, separate from the operator's `peers` so a machine can never rewrite what an operator typed. While that key has never been written the tunnel is not yet celilo's; the deploy that writes it (even as `[]`) CLAIMS the tunnel, importing whatever `[Peer]` blocks are running, and from then on the render is closed-world (`peers` ∪ `registered_peers`) with a `[Peer]` on the box in neither reported as drift by `on_install` and by `health_check`'s `unknown_peers`. An ABSENT `peers` declaration and a declared-EMPTY one are deliberately different (no `default: []` on either variable): they used to be the same value, so the module read every empty list as "adopt what is running", the last peer could not be revoked, and a hand-added peer rode along on every deploy unreported (celilo#765). On a tunnel celilo has not yet claimed, a declared-empty `peers` is REFUSED rather than obeyed — celilo's own variable-default seeding wrote a real `peers = []` row for every install of the previous version that never set one, so on the installed base an empty list cannot be told from a stored default, and obeying it would `wg syncconf` the admin tunnel down to zero peers. **PROVIDES `control_plane_vpn`** so another module can enrol clients without an operator editing YAML: `registerClient` / `revokeClient` write to `registered_peers` — the same key the adoption claim uses — and `getEndpoint` reads the server's public key LIVE off the host rather than storing a copy that could be republished after the key changed. `client_pool` is the range a consumer may allocate from, a strict subset of the client subnet, and `validate_config` REFUSES any operator-declared peer inside it: the two allocators cannot see each other, so the range is divided rather than negotiated, and that check is the only place a bad division is caught. ⚠️ Granting this capability grants fleet-wide reach — the tunnel's client subnet is a registered trusted source, so every client enrolled through it reaches every managed zone. **requires:** `firewall` (and the provider must support trusted-source registration — `iptables` does; the ISP-router drivers `greenwave` and `axon` do not).
-- **wireguard-manager** — self-service enrolment for the control-plane VPN, so adding an administrator's laptop is a web page rather than an operator editing `peers` by hand. A browser generates the WireGuard keypair with WebCrypto and **the private key never leaves it** — celilo never sees it and the app never stores it. The app allocates an address from `client_pool` (the range `wireguard` reserved for a consumer; celilo's IPAM deliberately does not cover VPN clients) and enrols the peer through **`control_plane_vpn`**, so it never edits wireguard's config and cannot reach a peer the operator declared by hand. Its own device list is the app's SQLite, reconciled onto the tunnel by the `reconcile_clients` hook on a `timer.tick.1m` subscription. Two guards make a failed poll harmless and both are structural rather than a check: `planReconcile` accepts only the `read` variant of a discriminated union, so an unreadable poll cannot reach it, and revocation is TOMBSTONE-driven — a device is revoked because the app says it was, never because it is missing from a list — so a short or empty read can only fail to add someone, never cut anyone off. A peer on the tunnel the app does not know and has not tombstoned is reported as an orphan and LEFT ALONE (usually an app restored from an older backup). **REQUIRES `private_web`, never `public_web`**: there is no public record, no ACME certificate and no port forward, and the internal CA's certificate is bundled with each downloaded config so a freshly enrolled device trusts the manager it just connected to. ⚠️ **Everyone enrolled becomes a fleet administrator** — the tunnel's client subnet is a registered trusted source, so the `admin_group` gate on the idp application is the entire access-control story; per-peer narrowing is not possible, because server-side `AllowedIPs` is crypto-key routing rather than access control. Enrolment works from the `internal` zone ONLY (a device not yet on the VPN cannot reach a manager reachable only over it), and a revocation takes effect at the next reconcile — that interval IS the window in which a revoked device still has reach, which is why the UI shows it pending and why `celilo module run-hook wireguard-manager reconcile_clients` exists. **requires:** `control_plane_vpn` (wireguard), `idp` (authentik), `private_web` (caddy-internal).
+- **wireguard-manager** — self-service enrolment for the control-plane VPN, so adding an administrator's laptop is a web page rather than an operator editing `peers` by hand. A browser generates the WireGuard keypair with WebCrypto and **the private key never leaves it** — celilo never sees it and the app never stores it. The app allocates an address from `client_pool` (the range `wireguard` reserved for a consumer; celilo's IPAM deliberately does not cover VPN clients) and enrols the peer through **`control_plane_vpn`**, so it never edits wireguard's config and cannot reach a peer the operator declared by hand. Its own device list is the app's SQLite, reconciled onto the tunnel by the `reconcile_clients` hook on a `timer.tick.1m` subscription. Two guards make a failed poll harmless and both are structural rather than a check: `planReconcile` accepts only the `read` variant of a discriminated union, so an unreadable poll cannot reach it, and revocation is TOMBSTONE-driven — a device is revoked because the app says it was, never because it is missing from a list — so a short or empty read can only fail to add someone, never cut anyone off. A peer on the tunnel the app does not know and has not tombstoned is reported as an orphan and LEFT ALONE (usually an app restored from an older backup). **REQUIRES `private_web`, never `public_web`**: there is no public record, no ACME certificate and no port forward, and the internal CA's certificate is bundled with each downloaded config so a freshly enrolled device trusts the manager it just connected to. ⚠️ **Everyone enrolled becomes a fleet administrator** — the tunnel's client subnet is a registered trusted source, so the `admin_group` gate on the idp application is the entire access-control story; per-peer narrowing is not possible, because server-side `AllowedIPs` is crypto-key routing rather than access control. Lives in **`app`**, one tier behind `caddy-internal` in `dmz`, and is never reached directly (celilo#879). Enrolment works from INSIDE the fleet only (a device not yet on the VPN cannot reach a manager reachable only over it) — from the LAN through the ingress IP, from a segmented zone at the ingress's dmz address, or over an existing VPN session, and a revocation takes effect at the next reconcile — that interval IS the window in which a revoked device still has reach, which is why the UI shows it pending and why `celilo module run-hook wireguard-manager reconcile_clients` exists. **requires:** `control_plane_vpn` (wireguard), `idp` (authentik), `private_web` (caddy-internal).
 
 ## Public edge (ingress / identity)
 
 - **caddy** — reverse proxy with automatic HTTPS (HTTP-01 ACME); the standard HTTPS ingress. Emits a 301 redirect block for each served name's `www`/apex companion (kept out of the served-hostname set, so a companion never blocks the ACME wait). Its `health_check`'s DNS item is `internal_dns_resolution` — it digs from the management host behind the split-horizon resolver and is evidence about the in-fleet view only; public reachability is the framework's `public_dns` check. **provides:** `public_web`. **requires:** `dns_registrar`, `firewall`.
-- **caddy-internal** — a SECOND Caddy that serves the fleet and nothing else, and is a sibling of **caddy** rather than a mode of it. It never calls `firewall.exposeService`, never publishes a public record, and takes its certificates from Caddy's own local CA (`tls internal`) — those three absences ARE the capability, and `public_web` cannot express them because it treats an unreachable route as a deploy failure and publishes a public A record to prevent one (design D10). Lives in the **`internal`** zone, with the LAN devices it serves: a dmz placement would need the firewall DNAT ingress to be reachable at all, which is the one thing it must not install. **`getCaCertificate()` is why the contract has a method `public_web` does not** — an internally-issued cert means clients must trust a CA celilo runs, and here that is nearly free because the people who must trust it are the ones who just downloaded a bundle from the service behind it, so the anchor ships with it. **The route table is this module's OWN config (`routes`), never celilo's `web_routes`** (celilo#846): caddy derives its served hostnames from every row of that table, so a private route stored there would be picked up and served PUBLICLY — storage is the privacy boundary, not policy. Route changes reconcile synchronously in the capability call (there is no `routes_changed` event for private routes, and inventing one would only add delay). A consumer cannot register a route on a hostname the ingress is not already configured for: a capability factory gets no capabilities of its own, so it cannot add the internal DNS record a new name would need, and it refuses rather than serving an unresolvable site block. **provides:** `private_web`. **requires:** `dns_internal` — declared under `optional.capabilities` ONLY to route around celilo#854 (the import-time secret gate refuses a consumer over a secret it never reads); `on_install` throws without it.
+- **caddy-internal** — a SECOND Caddy that serves the fleet and nothing else, and is a sibling of **caddy** rather than a mode of it. It never exposes a port on the firewall's EXTERNAL interface, never publishes a public record, and takes its certificates from Caddy's own local CA (`tls internal`) — those absences ARE the capability, and `public_web` cannot express them because it treats an unreachable route as a deploy failure and publishes a public A record to prevent one (design D10). Lives in the **`dmz`** zone, in front of the things it fronts, mirroring the public `caddy` (celilo#879). LAN devices reach it through an IPAM-allocated `internal`-subnet `ingress_ip` that `on_install` passes to `firewall.exposeService({ ingressIp })` — one DNAT on the firewall's INTERNAL side and nothing external, the same mechanism the dmz-resident `dns_internal` resolver has used for `:53` since ISS-0156. Systems already inside `dmz`/`app`/`secure` use its dmz address instead (carried as `zoneRoutableValue` on the internal record), and VPN clients arrive as a registered trusted source. It previously lived in `internal` on the claim that a dmz ingress could not be reached from a LAN without a public port-forward; that conflated a public forward with an internal-side ingress IP, and cost it the ability to serve a browser inside a segmented zone at all. **`getCaCertificate()` is why the contract has a method `public_web` does not** — an internally-issued cert means clients must trust a CA celilo runs, and here that is nearly free because the people who must trust it are the ones who just downloaded a bundle from the service behind it, so the anchor ships with it. **The route table is this module's OWN config (`routes`), never celilo's `web_routes`** (celilo#846): caddy derives its served hostnames from every row of that table, so a private route stored there would be picked up and served PUBLICLY — storage is the privacy boundary, not policy. Route changes reconcile synchronously in the capability call (there is no `routes_changed` event for private routes, and inventing one would only add delay). A consumer cannot register a route on a hostname the ingress is not already configured for: a capability factory gets no capabilities of its own, so it cannot add the internal DNS record a new name would need, and it refuses rather than serving an unresolvable site block. **provides:** `private_web`. **requires:** `dns_internal` — declared under `optional.capabilities` ONLY to route around celilo#854 (the import-time secret gate refuses a consumer over a secret it never reads); `on_install` throws without it.
 - **generic-cpanel-hosting-provider** — publishes static sites into a subfolder of a domain on a cPanel/SSH web host celilo does **not** govern (the host owns the domain, DNS, TLS and web server). Systemless like **namecheap** — no `requires.system`, no zone, no IPAM; it holds credentials for an external party. One provider serves many accounts, resolved by hostname; onboarding takes the account password once, `ssh-copy-id`s celilo's key, then discards it. **provides:** `external_web`.
 - **authentik** — Authentik identity provider with OIDC (Docker Compose: server, worker, Postgres, Redis). **provides:** `idp`. **requires:** `public_web`, `dns_registrar`, `firewall`.
 

package/CELILO_SUBSYSTEMS.md

@@ -24,6 +24,7 @@ see `openspec/specs/`. Companion doc: [CELILO_CORE_MODULES.md](./CELILO_CORE_MOD
 ## Allocation & infrastructure selection
 
 - **IPAM (IP/VMID allocation)** — `apps/celilo/src/ipam/allocator.ts` — `allocateIPFromSubnet`, `allocateVMID`, `reserveIP`/`unreserveIP`, `inferZoneFromIP`, `getAllocation`. Auto-wrapper: `apps/celilo/src/ipam/auto-allocator.ts` — `allocateForModule` / `deallocateForModule`.
+- **Ingress IPs (how the LAN reaches a service in a segmented zone)** — `ensureIngressIps` in `apps/celilo/src/templates/generator.ts`, called from `generateTemplates`. A module opts in by declaring an infrastructure variable whose name ENDS IN `ingress_ip` (`dns_ingress_ip` on the resolver, `ingress_ip` on `caddy-internal`); generate allocates and RESERVES a free `internal`-subnet address once and reuses it forever after, and the module's `on_install` passes it to `firewall.exposeService({ ingressIp })`. That renders ONE DNAT on the firewall's internal side and nothing on the external interface — it is not a public port-forward, and conflating the two is what pinned `caddy-internal` into the `internal` zone until celilo#879. Idempotence is load-bearing: re-allocating on a later generate silently moves the address clients use, with every command still reporting success (`apps/celilo/src/templates/ingress-ip.test.ts`).
 - **Infrastructure selection (container-service vs machine pool)** — `apps/celilo/src/services/machine-pool.ts` (`getMachineByHostname`, `addMachine`, `assignModuleToMachine`) and `apps/celilo/src/services/container-service.ts` (`getContainerServiceByName`, `addContainerService`, `verifyContainerService`). Provider API clients: `apps/celilo/src/api-clients/proxmox.ts`, `apps/celilo/src/api-clients/digitalocean.ts`.
 - **Zone detection / system config** — `apps/celilo/src/services/zone-detector.ts` — `detectZoneFromIp` reads `network.<zone>.subnet` from the `systemConfig` table and returns `NetworkZone | 'unknown'`. It answers CONTAINMENT ONLY. It used to return `'external'` on no-match, which conflated "no declared subnet contains this" with "the internet can route to this" — on a firewall with five RFC1918 legs that reported four of them as facing the internet. `'unknown'` is the honest answer; the caller resolves it (see `machine add`: publicly routable → `external`, otherwise fail asking for `--zone`). The subnet-backed zone list is derived from `NETWORK_ZONES` minus `external`, which has no subnet and must never be given one.
 - **Interface classification** — `packages/capabilities/src/interface-classification.ts` — THE shared classifier, used by the backend and every firewall provider module so the two cannot drift apart again. `isPubliclyRoutable(ip)` is a property of the address alone (false for RFC 1918, RFC 6598 carrier-grade NAT, loopback, link-local, multicast, reserved). `classifyInterfaces(interfaces, zones)` assigns each interface `zone → external → alien`, first match winning, where `external` is the RESIDUAL — routable and claimed by no declared zone — and is never subnet-matched. `externalEdge()` returns none/single/**ambiguous** rather than silently picking the first public address. `defaultRouteFinding()` enforces the invariant that the default route leaves through `internal` or `external`. **`subnetContains(cidr, ip)` lives here and is the ONLY implementation** — three existed and disagreed (the backend's mishandled `/0`); the other two are deleted, not aliased. Design: `openspec/changes/firewall-interface-classification/design.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {

package/src/templates/generator.ts

@@ -654,38 +654,58 @@ celilo module import modules/${moduleId}
  * @returns Generation result
  */
 /** Narrower than `GenerateResult`: this step produces no files, only an outcome. */
-export type DnsIngressResult = { success: true } | { success: false; error: string };
+export type IngressIpResult = { success: true } | { success: false; error: string };
 
 /**
- * Allocate-and-reserve the module's dedicated DNS-ingress IP, ONCE (ISS-0156).
+ * Allocate-and-reserve a module's dedicated `internal`-subnet ingress IPs, ONCE
+ * (ISS-0156, celilo#879).
  *
- * A `dns_internal` provider deploys into a PROTECTED zone (dmz) so it can see
- * protected-zone query sources for split-horizon views. `internal` devices have
- * no route into the 10-net, so they reach the resolver through a firewall DNAT
- * on a dedicated `internal`-subnet address. A module opts in by declaring a
- * `dns_ingress_ip` infrastructure variable.
+ * A service can need to live in a PROTECTED zone — the `dns_internal` resolver
+ * sits in `dmz` so it can see protected-zone query sources for split-horizon,
+ * and `caddy-internal` sits there so systems in the segmented zones can reach
+ * it. `internal` devices have no route into the 10-net, so they reach such a
+ * service through a firewall DNAT on a dedicated `internal`-subnet address.
+ * That DNAT is internal-side only: it is NOT a public port-forward, and the two
+ * are routinely confused.
+ *
+ * A module opts in by declaring an infrastructure variable whose name ends in
+ * `ingress_ip` — `dns_ingress_ip` for the resolver's `:53`, `ingress_ip` for a
+ * private web ingress's `:80/:443`. The hook then passes the stored value to
+ * `firewall.exposeService({ ingressIp })`.
  *
  * **Idempotence is the whole point, and it is load-bearing.** `module generate`
  * runs repeatedly over a module's life. Re-allocating here on the second run
- * would move the address internal clients use to reach DNS, every time — while
- * every command still reports success. That is why the stored value is reused
- * rather than re-derived, and why this is a named function instead of a branch
- * buried in `generateTemplates`: an invariant nothing can call is an invariant
- * nothing can test, and this one had no test at all.
+ * would move the address internal clients use to reach the service, every time
+ * — while every command still reports success. That is why the stored value is
+ * reused rather than re-derived, and why this is a named function instead of a
+ * branch buried in `generateTemplates`: an invariant nothing can call is an
+ * invariant nothing can test, and this one had no test at all.
  */
-export async function ensureDnsIngressIp(
+export async function ensureIngressIps(
   moduleId: string,
   manifest: ModuleManifest,
   db: DbClient,
-): Promise<DnsIngressResult> {
-  const wantsDnsIngress = manifest.variables?.owns?.some(
-    (v) => v.name === 'dns_ingress_ip' && v.source === 'infrastructure',
+): Promise<IngressIpResult> {
+  const wanted = (manifest.variables?.owns ?? []).filter(
+    (v) => v.name.endsWith('ingress_ip') && v.source === 'infrastructure',
   );
-  if (!wantsDnsIngress) return { success: true };
+  if (wanted.length === 0) return { success: true };
+
+  for (const variable of wanted) {
+    const result = await allocateIngressIp(moduleId, variable.name, db);
+    if (!result.success) return result;
+  }
+  return { success: true };
+}
 
-  const existing = getModuleConfigValue(moduleId, 'dns_ingress_ip', db)?.value;
+async function allocateIngressIp(
+  moduleId: string,
+  variableName: string,
+  db: DbClient,
+): Promise<IngressIpResult> {
+  const existing = getModuleConfigValue(moduleId, variableName, db)?.value;
   if (typeof existing === 'string' && existing.length > 0) {
-    log.success(`Using existing DNS-ingress IP ${existing} for ${moduleId}`);
+    log.success(`Using existing ingress IP ${existing} (${variableName}) for ${moduleId}`);
     return { success: true };
   }
 
@@ -695,9 +715,7 @@ export async function ensureDnsIngressIp(
   if (!subnetRow?.value) {
     return {
       success: false,
-      error:
-        'network.internal.subnet is not configured — required to allocate the ' +
-        'dns_internal DNS-ingress IP (ISS-0156). Ensure the internal network is set up first.',
+      error: `network.internal.subnet is not configured — required to allocate the ${variableName} ingress IP (ISS-0156). Ensure the internal network is set up first.`,
     };
   }
 
@@ -705,14 +723,14 @@ export async function ensureDnsIngressIp(
   const { stripCIDR } = await import('../ipam/subnet-parser');
   try {
     const ip = stripCIDR(await allocateIPFromSubnet(subnetRow.value, 'internal', db));
-    await reserveIP(ip, 'internal', `dns-ingress:${moduleId}`, null, db);
-    upsertModuleConfig(db, moduleId, 'dns_ingress_ip', ip);
-    log.success(`Allocated DNS-ingress IP ${ip} (internal subnet) for ${moduleId}`);
+    await reserveIP(ip, 'internal', `ingress:${moduleId}:${variableName}`, null, db);
+    upsertModuleConfig(db, moduleId, variableName, ip);
+    log.success(`Allocated ingress IP ${ip} (internal subnet, ${variableName}) for ${moduleId}`);
     return { success: true };
   } catch (error) {
     return {
       success: false,
-      error: `DNS-ingress IP allocation failed: ${error instanceof Error ? error.message : String(error)}`,
+      error: `Ingress IP allocation failed for ${variableName}: ${error instanceof Error ? error.message : String(error)}`,
     };
   }
 }
@@ -879,8 +897,8 @@ export async function generateTemplates(options: GenerateOptions): Promise<Gener
     }
   }
 
-  const dnsIngress = await ensureDnsIngressIp(moduleId, manifest, db);
-  if (!dnsIngress.success) return dnsIngress;
+  const ingress = await ensureIngressIps(moduleId, manifest, db);
+  if (!ingress.success) return ingress;
 
   // Infrastructure Properties Resolution (Proxmox provider config)
   // For Proxmox services, extract provider config and store as temporary values

package/src/templates/{dns-ingress-ip.test.ts → ingress-ip.test.ts}

@@ -1,11 +1,11 @@
 /**
- * The DNS-ingress allocate-and-reserve guard (ISS-0156).
+ * The ingress-IP allocate-and-reserve guard (ISS-0156, celilo#879).
  *
  * This invariant had NO test. Losing it is not a crash: `module generate`
  * re-allocates a different address on every run, silently moving the address
- * internal clients use to reach DNS, while every command still reports success.
- * `module generate` runs repeatedly over a module's life, so "on the second
- * run" is the normal case, not an edge one.
+ * internal clients use to reach the service, while every command still reports
+ * success. `module generate` runs repeatedly over a module's life, so "on the
+ * second run" is the normal case, not an edge one.
  */
 
 import { beforeEach, describe, expect, test } from 'bun:test';
@@ -13,7 +13,7 @@ import type { DbClient } from '../db/client';
 import type { ModuleManifest } from '../manifest/schema';
 import { getModuleConfigValue } from '../services/module-config';
 import { setupTestDatabase } from '../test-utils/database';
-import { ensureDnsIngressIp } from './generator';
+import { ensureIngressIps } from './generator';
 
 let db: DbClient;
 
@@ -27,12 +27,17 @@ const operatorSupplied = {
   variables: { owns: [{ name: 'dns_ingress_ip', source: 'user_input' }] },
 } as unknown as ModuleManifest;
 
+/** How `caddy-internal` opts in — a web ingress rather than a DNS one. */
+const wantsWebIngress = {
+  variables: { owns: [{ name: 'ingress_ip', source: 'infrastructure' }] },
+} as unknown as ModuleManifest;
+
 /**
  * Typed as `string | undefined` rather than `unknown`: every assertion here is
  * about an address, and an untyped read pushes a cast onto each one.
  */
-const storedIp = (moduleId: string): string | undefined => {
-  const value = getModuleConfigValue(moduleId, 'dns_ingress_ip', db)?.value;
+const storedIp = (moduleId: string, variable = 'dns_ingress_ip'): string | undefined => {
+  const value = getModuleConfigValue(moduleId, variable, db)?.value;
   return typeof value === 'string' ? value : undefined;
 };
 
@@ -43,9 +48,9 @@ beforeEach(async () => {
     .run('network.internal.subnet', '10.226.1.0/24');
 });
 
-describe('ensureDnsIngressIp', () => {
+describe('ensureIngressIps', () => {
   test('allocates an address from the internal subnet on first generate', async () => {
-    const result = await ensureDnsIngressIp('technitium', wantsIngress, db);
+    const result = await ensureIngressIps('technitium', wantsIngress, db);
 
     expect(result.success).toBe(true);
     expect(storedIp('technitium')).toMatch(/^10\.226\.1\.\d+$/);
@@ -54,21 +59,21 @@ describe('ensureDnsIngressIp', () => {
   test('REUSES the same address on a second generate', async () => {
     // The guard itself. Re-allocating here moves the resolver's DNAT ingress
     // every time the module is regenerated, and nothing reports a problem.
-    await ensureDnsIngressIp('technitium', wantsIngress, db);
+    await ensureIngressIps('technitium', wantsIngress, db);
     const first = storedIp('technitium');
 
-    await ensureDnsIngressIp('technitium', wantsIngress, db);
+    await ensureIngressIps('technitium', wantsIngress, db);
     const second = storedIp('technitium');
 
     expect(second).toBe(first);
   });
 
   test('stays stable across many generates, not just two', async () => {
-    await ensureDnsIngressIp('technitium', wantsIngress, db);
+    await ensureIngressIps('technitium', wantsIngress, db);
     const first = storedIp('technitium');
 
     for (let i = 0; i < 5; i++) {
-      await ensureDnsIngressIp('technitium', wantsIngress, db);
+      await ensureIngressIps('technitium', wantsIngress, db);
     }
 
     expect(storedIp('technitium')).toBe(first);
@@ -77,7 +82,7 @@ describe('ensureDnsIngressIp', () => {
   test('RESERVES the address, so it is never handed out to something else', async () => {
     // Allocation without reservation is the same bug one step later: a
     // container gets the resolver's ingress address and DNS goes dark.
-    await ensureDnsIngressIp('technitium', wantsIngress, db);
+    await ensureIngressIps('technitium', wantsIngress, db);
     const ip = storedIp('technitium');
 
     const reserved = db.$client
@@ -85,20 +90,20 @@ describe('ensureDnsIngressIp', () => {
       .get(ip ?? '') as { ip_start: string; reason: string } | undefined;
 
     expect(reserved?.ip_start).toBe(ip);
-    // The reason names the owner, so an operator reading the table can tell
-    // what an otherwise anonymous held address is for.
-    expect(reserved?.reason).toBe('dns-ingress:technitium');
+    // The reason names the owner AND the variable, so an operator reading the
+    // table can tell what an otherwise anonymous held address is for.
+    expect(reserved?.reason).toBe('ingress:technitium:dns_ingress_ip');
   });
 
   test('two modules get two different addresses', async () => {
-    await ensureDnsIngressIp('technitium', wantsIngress, db);
-    await ensureDnsIngressIp('knot-unbound-internal', wantsIngress, db);
+    await ensureIngressIps('technitium', wantsIngress, db);
+    await ensureIngressIps('knot-unbound-internal', wantsIngress, db);
 
     expect(storedIp('knot-unbound-internal')).not.toBe(storedIp('technitium'));
   });
 
   test('does nothing for a module that never asked for one', async () => {
-    const result = await ensureDnsIngressIp('caddy', {} as ModuleManifest, db);
+    const result = await ensureIngressIps('caddy', {} as ModuleManifest, db);
 
     expect(result.success).toBe(true);
     expect(storedIp('caddy')).toBeUndefined();
@@ -107,7 +112,7 @@ describe('ensureDnsIngressIp', () => {
   test('only `source: infrastructure` opts in', async () => {
     // A same-named variable the operator supplies is theirs to set; allocating
     // over it would overwrite an operator's deliberate choice.
-    await ensureDnsIngressIp('technitium', operatorSupplied, db);
+    await ensureIngressIps('technitium', operatorSupplied, db);
 
     expect(storedIp('technitium')).toBeUndefined();
   });
@@ -115,9 +120,20 @@ describe('ensureDnsIngressIp', () => {
   test('fails with an actionable message when the internal subnet is unset', async () => {
     db.$client.prepare('DELETE FROM system_config WHERE key = ?').run('network.internal.subnet');
 
-    const result = await ensureDnsIngressIp('technitium', wantsIngress, db);
+    const result = await ensureIngressIps('technitium', wantsIngress, db);
 
     expect(result.success).toBe(false);
     expect(result.success === false && result.error).toContain('network.internal.subnet');
   });
+
+  // celilo#879. The opt-in used to be the literal name `dns_ingress_ip`, so a
+  // dmz-resident WEB ingress had no way to ask for the same treatment — which
+  // is how `caddy-internal` came to be pinned into the `internal` zone with a
+  // manifest comment claiming a dmz ingress could not be reached from a LAN.
+  test('a `ingress_ip` variable opts in the same way, for a non-DNS ingress', async () => {
+    const result = await ensureIngressIps('caddy-internal', wantsWebIngress, db);
+
+    expect(result.success).toBe(true);
+    expect(storedIp('caddy-internal', 'ingress_ip')).toMatch(/^10\.226\.1\.\d+$/);
+  });
 });