@celilo/e2e 0.13.0 → 0.13.1

package/docker/Dockerfile.firewall

@@ -12,10 +12,21 @@ RUN apt-get update && apt-get install -y \
     dnsutils \
     procps \
     python3 \
-    wireguard-tools \
     wireguard-go \
     && rm -rf /var/lib/apt/lists/*
 
+# `wireguard-tools` is DELIBERATELY not installed here. The wireguard module's
+# job includes putting it on the host, and baking it in meant the rig proved the
+# tunnel worked on the one kind of host that could never exercise that: the
+# module only ever ran `wg --version`, found it, and moved on. On a real firewall
+# the deploy failed and told the operator to install wireguard by hand — over the
+# access the VPN was being deployed to provide.
+#
+# `wireguard-go` stays, and is a different kind of thing. A container cannot load
+# a kernel module, so wg-quick needs a userspace implementation to fall back to;
+# that is the simulator standing in for hardware it does not have, not a step
+# celilo is supposed to perform.
+
 # Containers have no wireguard kernel module to load, and a test must not depend
 # on whether the Docker host happens to have one. wg-quick falls back to this
 # userspace implementation when `ip link add type wireguard` fails, so the tunnel

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/e2e",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "E2E test infrastructure for Celilo-deployed applications. Provides a simulated internet with DNS hierarchy, ACME server, firewalls, and target machines in Docker.",
   "type": "module",
   "main": "./src/index.ts",
@@ -37,9 +37,9 @@
     "README.md"
   ],
   "dependencies": {
-    "@celilo/capabilities": "^1.1.0",
+    "@celilo/capabilities": "^1.2.0",
     "@celilo/cli-display": "^0.2.0",
-    "@celilo/event-bus": "^0.4.0",
+    "@celilo/event-bus": "^0.5.0",
     "yaml": "^2.8.0",
     "zod": "^3.24.1"
   },

package/src/container-manager.ts

@@ -535,6 +535,9 @@ function buildNetworkHandle(
   // Playwright browsers). stop() tears these down before the docker
   // network itself.
   const activeProxies: SocksProxyHandle[] = [];
+  /** Services plugged into the undeclared segment, and the subnet it uses. */
+  const attachedToAlienSegment = new Set<string>();
+  let alienSegmentSubnet = '';
   const activeBrowsers: BrowserHandle[] = [];
 
   const handle: NetworkHandle = {
@@ -612,19 +615,32 @@ function buildNetworkHandle(
       await new Promise((r) => setTimeout(r, 500));
     },
 
-    async deployFirewall(opts = {}): Promise<void> {
-      // `opts.zones` says which zones get `provided_networks` written to system
-      // config. It does NOT say which NICs the box has — the compose topology
-      // decides that, and it wires fw-main to every segmented zone regardless of
-      // what a test passed. Roughly twenty call sites passed `['dmz']` against a
-      // four-leg firewall, so every one of them under-declared the hardware.
+    async deployFirewall(opts = {}): Promise<ExecResult> {
+      // Everything the firewall declares is derived from the topology it is
+      // wired for. `opts.zones` used to select which zones got
+      // `provided_networks`, and that cannot survive interface classification:
+      // `provided_networks` IS what writes `network.<zone>.subnet`, so a leg
+      // left out of it has no declared subnet, classifies `alien`, and the
+      // converge refuses on a firewall celilo has never understood.
       //
-      // Deriving the declared list from the topology makes under-declaring
-      // structurally impossible rather than something each future test author has
-      // to remember, and removes one more hand-maintained copy of a list the
-      // compose generator already owns.
-      const providedZones = opts.zones ?? ['dmz', 'app', 'secure'];
+      // That is the real rule, not a harness quirk. A firewall holding an
+      // address on a segment celilo has no subnet for is one celilo cannot
+      // describe. So the wired legs and the declared zones are ONE list (D8),
+      // and a test wanting fewer legs changes the topology.
+      //
+      // The old `opts.zones` never said which NICs the box has — the compose
+      // topology decides that, and it wires fw-main to every segmented zone
+      // regardless of what a test passed. Roughly twenty call sites passed
+      // `['dmz']` against a four-leg firewall, so every one of them
+      // under-declared the hardware. Deriving from the topology makes that
+      // structurally impossible rather than something each test author has to
+      // remember, and removes a hand-maintained copy of a list the compose
+      // generator already owns.
+      //
+      // `external` is excluded from provided_networks: it is the residual, has
+      // no subnet, and is not a zone modules are placed in.
       const declaredZones = firewallZoneLegs(topology);
+      const providedZones = declaredZones.filter((zone) => zone !== 'external');
       const firewallIp = ZONE_GATEWAYS.internal; // fw-main on internal
       const natIp = opts.natIp ?? internalNatIp();
       const providedNetworks = providedZones.map((zone) => ({
@@ -667,7 +683,105 @@ function buildNetworkHandle(
       await handle.celilo(
         `module config set iptables provided_networks '${JSON.stringify(providedNetworks)}'`,
       );
-      await handle.celilo('module deploy iptables', 180_000);
+      // `check: false` returns the failed deploy instead of throwing, so a test
+      // can assert on WHAT the refusal said. Interface classification refuses
+      // by design (D12 onboarding), and a refusal is only useful if it names
+      // the interface — which is an assertion about output, not about an
+      // exception having been raised.
+      return opts.check === false
+        ? await handle.celilo('module deploy iptables', { check: false, timeoutMs: 180_000 })
+        : await handle.celilo('module deploy iptables', 180_000);
+    },
+
+    async attachAlienSegment(opts: {
+      subnet: string;
+      containers: string[];
+    }): Promise<Record<string, string>> {
+      // A REAL cable into a REAL port. Interface classification is about what
+      // celilo finds on the box, so a test that fakes the finding — a dummy
+      // link, a stubbed interface table — is testing its own fixture. This
+      // creates an actual docker network celilo has no subnet for and plugs
+      // real containers into it, which is what an operator hanging an
+      // unmanaged switch off a spare port produces: a new interface, a global
+      // address, and something live on the other side to prove reachability
+      // with.
+      //
+      // The subnet is the caller's, and it must not be one of ZONE_SUBNETS —
+      // the whole point is that celilo cannot attribute it.
+      const netName = `${projectName}_alien-seg`;
+      alienSegmentSubnet = opts.subnet;
+      run(`docker network create --driver bridge --subnet ${opts.subnet} ${netName}`, {
+        timeout: 20_000,
+      });
+
+      const assigned: Record<string, string> = {};
+      opts.containers.forEach((service, index) => {
+        // .2 upward: .1 is the bridge itself.
+        const ip = opts.subnet.replace(/\.0\/\d+$/, `.${index + 2}`);
+        const id = run(`docker compose -p ${projectName} -f ${COMPOSE_FILE} ps -q ${service}`, {
+          cwd: composeDir,
+          timeout: 20_000,
+        });
+        if (!id) throw new Error(`attachAlienSegment: no container for service '${service}'`);
+
+        // `docker network connect` EXITS NONZERO on a container that already has
+        // a default route — "failed to set gateway while updating gateway: file
+        // exists" — while attaching the interface perfectly well: the address
+        // lands, the veth is up, and traffic flows both ways. Every container in
+        // this topology routes through the firewall, so every attach hits it.
+        // `docker network inspect` is no help either; it lists no containers for
+        // this network whether the attach worked or not.
+        //
+        // So neither the exit code nor docker's own view can be believed, and
+        // the address on the box is the only trustworthy signal. Verified below
+        // rather than assumed — a half-completed attach really does leave an
+        // address behind with no working wire, which is precisely the state that
+        // would make a classification test pass for the wrong reason.
+        try {
+          run(`docker network connect --ip ${ip} ${netName} ${id}`, { timeout: 20_000 });
+        } catch {}
+
+        const check = dockerExec(projectName, composeDir, service, 'ip -o addr show scope global');
+        if (!check.stdout.includes(ip)) {
+          throw new Error(
+            `attachAlienSegment: '${service}' has no ${ip} after connecting to ${netName}:\n${check.stdout}`,
+          );
+        }
+        assigned[service] = ip;
+        attachedToAlienSegment.add(service);
+      });
+      return assigned;
+    },
+
+    async detachAlienSegment(): Promise<void> {
+      const netName = `${projectName}_alien-seg`;
+      for (const service of attachedToAlienSegment) {
+        const id = run(`docker compose -p ${projectName} -f ${COMPOSE_FILE} ps -q ${service}`, {
+          cwd: composeDir,
+          timeout: 20_000,
+        });
+        if (id) {
+          try {
+            run(`docker network disconnect -f ${netName} ${id}`, { timeout: 20_000 });
+          } catch {}
+        }
+      }
+      try {
+        run(`docker network rm ${netName}`, { timeout: 20_000 });
+      } catch {}
+
+      // VERIFY, for the same reason attach does. A lingering address on a dead
+      // wire is still an interface celilo cannot attribute, so a test that goes
+      // on to expect a clean converge would fail somewhere far from the cause.
+      for (const service of attachedToAlienSegment) {
+        const check = dockerExec(projectName, composeDir, service, 'ip -o addr show scope global');
+        const prefix = alienSegmentSubnet.replace(/\.\d+\/\d+$/, '').replace(/\./g, '\\.');
+        const orphan = new RegExp(`(\\S+)\\s+inet\\s+${prefix}\\.\\d+`).exec(check.stdout);
+        if (orphan) {
+          dockerExec(projectName, composeDir, service, `ip link del ${orphan[1]}`);
+        }
+      }
+      attachedToAlienSegment.clear();
     },
 
     async deployGreenwave(): Promise<void> {

package/src/types.ts

@@ -363,18 +363,16 @@ export interface NetworkHandle {
    * Targets fw-main (the customer firewall) using the standard topology
    * subnets from ZONE_SUBNETS / ZONE_GATEWAYS.
    *
-   * `opts.zones` says which zones get `provided_networks` written to system
-   * config. It does NOT declare which NICs the firewall has — the topology
-   * decides that, and `deployFirewall` derives the declared list from it, so a
-   * test cannot under-declare the box's hardware by omission.
+   * Both the declared zone list AND `provided_networks` are derived from the
+   * topology this network was built with. There is no `zones` option: a firewall
+   * holding an address on a segment celilo has no subnet for classifies `alien`
+   * and the converge refuses, so the wired legs and the declared zones must be
+   * the same list. A test that wants a firewall with fewer legs changes the
+   * topology, which is the honest way to say it (design D8).
    *
-   * @param opts.zones - zones to PROVIDE (default: dmz, app, secure)
    * @param opts.natIp - NAT IP for port-forwarded traffic (default 10.226.1.253)
    */
-  deployFirewall(opts?: {
-    zones?: Array<'dmz' | 'app' | 'secure'>;
-    natIp?: string;
-  }): Promise<void>;
+  deployFirewall(opts?: { natIp?: string; check?: boolean }): Promise<ExecResult>;
 
   /**
    * Deploy the `greenwave` module against the ISP router (`fw-isp`) — the box
@@ -390,6 +388,27 @@ export interface NetworkHandle {
    *
    * Not needed under `direct-internet`, where fw-main owns the edge itself.
    */
+  /**
+   * Plug the named containers into a NEW network celilo has no subnet for, and
+   * return the address each was given.
+   *
+   * For interface-classification tests: the firewall gains a real interface
+   * with a real global address that matches no declared zone, and a peer on the
+   * same segment gives the isolation assertion a real signal to measure — can
+   * that segment still reach a service on the firewall — rather than a rule
+   * string in `iptables-save`.
+   *
+   * `subnet` must NOT be one of `ZONE_SUBNETS`; an attributable segment defeats
+   * the purpose.
+   */
+  attachAlienSegment(opts: {
+    subnet: string;
+    containers: string[];
+  }): Promise<Record<string, string>>;
+
+  /** Unplug and remove the segment `attachAlienSegment` created. */
+  detachAlienSegment(): Promise<void>;
+
   deployGreenwave(): Promise<void>;
 
   /** Tear down the entire network */