@celilo/e2e 0.9.3 → 0.10.2

package/src/docker-compose-generator.ts

@@ -79,6 +79,8 @@ function baseService(opts: {
   tmpfs?: string[];
   privileged?: boolean;
   dns?: string[];
+  /** Host devices to expose, e.g. `/dev/net/tun` for a userspace WireGuard tunnel. */
+  devices?: string[];
 }) {
   // Auto-assign an image tag from the Dockerfile name so Docker can
   // skip builds when pre-built images exist.
@@ -109,6 +111,16 @@ export const SHARED_NETWORKS = {
  * Default topology: fw-isp (greenwave) + fw-main (iptables)
  * Two-layer NAT: internet → fw-isp → fw-main → target
  */
+/**
+ * celilo's own control-plane network, used only when `managementZone` is
+ * 'secure-mgmt'. Deliberately NOT one of the segmented data-plane tiers: it is
+ * where celilo-mgr itself lives, mirroring the production topology the suite
+ * previously could not express.
+ */
+const SECURE_MGMT_SUBNET = '10.0.120.0/24';
+const SECURE_MGMT_GATEWAY = '10.0.120.1';
+const SECURE_MGMT_MANAGEMENT_IP = '10.0.120.100';
+
 function defaultTopologyServices(): Record<string, unknown> {
   return {
     'fw-main': baseService({
@@ -120,6 +132,10 @@ function defaultTopologyServices(): Record<string, unknown> {
         secure: { ipv4_address: '10.0.30.1' },
       },
       cap_add: ['NET_ADMIN', 'SYS_ADMIN'],
+      // A firewall may also terminate a VPN (the admin tunnel the `wireguard`
+      // module owns). wireguard-go needs the tun device; the kernel module is
+      // deliberately not relied on — see Dockerfile.firewall.
+      devices: ['/dev/net/tun'],
       sysctls: ROUTER_SYSCTLS,
       volumes: ['ssh-keys:/ssh-keys:ro'],
     }),
@@ -130,6 +146,10 @@ function defaultTopologyServices(): Record<string, unknown> {
         'isp-external': { ipv4_address: '100.100.0.100' },
       },
       cap_add: ['NET_ADMIN', 'SYS_ADMIN'],
+      // A firewall may also terminate a VPN (the admin tunnel the `wireguard`
+      // module owns). wireguard-go needs the tun device; the kernel module is
+      // deliberately not relied on — see Dockerfile.firewall.
+      devices: ['/dev/net/tun'],
       sysctls: ROUTER_SYSCTLS,
       volumes: ['ssh-keys:/ssh-keys:ro'],
     }),
@@ -153,6 +173,10 @@ function directInternetTopologyServices(): Record<string, unknown> {
         'isp-external': { ipv4_address: '100.100.0.100' },
       },
       cap_add: ['NET_ADMIN', 'SYS_ADMIN'],
+      // A firewall may also terminate a VPN (the admin tunnel the `wireguard`
+      // module owns). wireguard-go needs the tun device; the kernel module is
+      // deliberately not relied on — see Dockerfile.firewall.
+      devices: ['/dev/net/tun'],
       sysctls: ROUTER_SYSCTLS,
       volumes: ['ssh-keys:/ssh-keys:ro'],
     }),
@@ -232,6 +256,7 @@ export function generateSharedInfraYaml(): string {
       './config/dns/celilo.computer.zone:/seed/celilo.computer.zone:ro',
       './config/dns/example.net.zone:/seed/example.net.zone:ro',
       './config/dns/park-your-domain.com.zone:/seed/park-your-domain.com.zone:ro',
+      './config/dns/tangohost.com.zone:/seed/tangohost.com.zone:ro',
     ],
   });
 
@@ -292,6 +317,17 @@ export function generateSharedInfraYaml(): string {
   // packages/e2e/scripts/pack-celilo-packages.ts (cli, capabilities,
   // cli-display, e2e, event-bus). Reachable at http://npm-registry.lab from
   // any container that uses the internal resolver.
+  // OFF-FLEET web host (external_web). A PUBLIC PEER on internet-external, not
+  // a fleet member and not behind the customer firewall: celilo reaches it by
+  // SSH egress the way it would reach any host on the real internet, and public
+  // DNS resolves tangohost.com straight to this address. It runs its own Apache
+  // and its own pre-installed TLS — celilo governs none of it.
+  services['cpanel-host'] = baseService({
+    build: { context: '.', dockerfile: 'docker/Dockerfile.cpanel-host-sim' },
+    networks: { 'internet-external': { ipv4_address: SIMULATOR_IPS.CPANEL_HOST } },
+    cap_add: ['NET_ADMIN'],
+  });
+
   services['npm-registry'] = baseService({
     build: { context: '.', dockerfile: 'docker/Dockerfile.npm-registry-sim' },
     networks: { 'internet-external': { ipv4_address: SIMULATOR_IPS.NPM_REGISTRY } },
@@ -337,11 +373,21 @@ export function generateSharedInfraYaml(): string {
  * Creates its own internal, dmz, app, secure networks.
  */
 export function generateTestComposeYaml(config: NetworkConfig, celiloRoot?: string): string {
+  const mgmtOnOwnNetwork = config.managementZone === 'secure-mgmt';
+  // The control-plane network exists if celilo-mgr lives there OR if any
+  // machine does — a module declaring `zone: secure-mgmt` needs somewhere to
+  // land whether or not the management box shares the network (#436).
+  const needsSecureMgmt = mgmtOnOwnNetwork || (config.secureMgmtMachines ?? []).length > 0;
   const networks: Record<string, unknown> = {
     internal: networkDef('192.168.0.0/24', '192.168.0.250'),
     dmz: networkDef('10.0.10.0/24', '10.0.10.250'),
     app: networkDef('10.0.20.0/24', '10.0.20.250'),
     secure: networkDef('10.0.30.0/24', '10.0.30.250'),
+    // Only when celilo-mgr lives off the internal LAN — keeps the default
+    // topology's generated compose byte-identical for every existing test.
+    ...(needsSecureMgmt
+      ? { 'secure-mgmt': networkDef(SECURE_MGMT_SUBNET, '10.0.120.250') }
+      : {}),
     'isp-external': networkDef('100.100.0.0/24', '100.100.0.250'),
     // internet-external is owned by shared infra; real-internet is per-test
     // (it just bridges fw-ext ↔ comcast-resolver, no shared service uses it).
@@ -392,11 +438,15 @@ export function generateTestComposeYaml(config: NetworkConfig, celiloRoot?: stri
   // first. container-manager's celilo-init + routing-verify target the
   // `management` container by name, so `celilo-mgr-2` comes up fresh and
   // un-init'd — the empty target restore needs.
-  const emitManagement = (variant: 'default' | 'vanilla' | undefined, ip: string) =>
+  const emitManagement = (
+    variant: 'default' | 'vanilla' | undefined,
+    ip: string,
+    zone: 'internal' | 'secure-mgmt' = 'internal',
+  ) =>
     baseService({
       image:
         variant === 'vanilla' ? 'celilo-e2e/management:vanilla' : 'celilo-e2e/management:latest',
-      networks: { internal: { ipv4_address: ip } },
+      networks: { [zone]: { ipv4_address: ip } },
       cap_add: ['NET_ADMIN'],
       // ISS-0157: `module import`'s `bun install` hard-links packages from the
       // bun cache into node_modules, which on overlayfs forces a copy-up + fsync
@@ -416,12 +466,17 @@ export function generateTestComposeYaml(config: NetworkConfig, celiloRoot?: stri
       ],
       environment: {
         DDNS_ENDPOINT: `http://${SIMULATOR_IPS.NAMECHEAP_DNS}:8080/update`,
-        DEFAULT_GATEWAY: managementDefaultGw,
+        // On its own control-plane network the only router in reach is fw-main's
+        // leg there — both for the default route and for the segmented zones.
+        DEFAULT_GATEWAY: zone === 'secure-mgmt' ? SECURE_MGMT_GATEWAY : managementDefaultGw,
+        ...(zone === 'secure-mgmt' ? { FW_MAIN_HOP: SECURE_MGMT_GATEWAY } : {}),
         CELILO_REGISTRY_URL: 'http://e2e-registry.lab',
       },
     });
 
-  services.management = emitManagement(config.managementVariant, '192.168.0.100');
+  services.management = mgmtOnOwnNetwork
+    ? emitManagement(config.managementVariant, SECURE_MGMT_MANAGEMENT_IP, 'secure-mgmt')
+    : emitManagement(config.managementVariant, '192.168.0.100');
 
   if (config.secondaryManagementVariant) {
     services['celilo-mgr-2'] = emitManagement(config.secondaryManagementVariant, '192.168.0.101');
@@ -451,6 +506,17 @@ export function generateTestComposeYaml(config: NetworkConfig, celiloRoot?: stri
   const topologyFn = TOPOLOGY_SERVICES[config.topology] || TOPOLOGY_SERVICES.default;
   Object.assign(services, topologyFn());
 
+  // Give fw-main a leg on the control-plane network when celilo-mgr lives there,
+  // so the management box is routed like any other segmented network rather than
+  // being stranded. Applied as a post-step so the default topology's generated
+  // compose is untouched.
+  if (needsSecureMgmt) {
+    const fwMain = services['fw-main'] as { networks?: Record<string, unknown> } | undefined;
+    if (fwMain?.networks) {
+      fwMain.networks['secure-mgmt'] = { ipv4_address: SECURE_MGMT_GATEWAY };
+    }
+  }
+
   // --- Routing infrastructure (bridges per-test to shared infra) ---
   services['fw-ext'] = baseService({
     build: { context: '.', dockerfile: 'docker/Dockerfile.router' },
@@ -473,12 +539,7 @@ export function generateTestComposeYaml(config: NetworkConfig, celiloRoot?: stri
   });
 
   // --- Dynamic test machines ---
-  const allMachines = [
-    ...config.dmzMachines,
-    ...config.appMachines,
-    ...config.secureMachines,
-    ...config.internalMachines,
-  ];
+  const allMachines = getAllMachines(config);
 
   for (const machine of allMachines) {
     const zoneNetwork = machine.zone;
@@ -518,6 +579,49 @@ export function generateTestComposeYaml(config: NetworkConfig, celiloRoot?: stri
     });
   }
 
+  // --- Optional real signal-cli daemon ---
+  // On `internal`, matching the signal module's declared zone — it is a local
+  // service celilo talks to, not an internet-facing one, so it does not belong
+  // on internet-external. Unlinked: the JSON-RPC surface needs no account.
+  if (config.signalCli) {
+    services['signal-cli'] = baseService({
+      build: { context: '.', dockerfile: 'docker/Dockerfile.signal-cli' },
+      networks: { internal: { ipv4_address: '192.168.0.90' } },
+      cap_add: ['NET_ADMIN'],
+    });
+  }
+
+  // --- Optional signal-cli release host ---
+  // On internet-external because that is what it models: an artifact the
+  // module downloads FROM the internet at deploy time.
+  if (config.signalRelease) {
+    services['signal-release'] = baseService({
+      build: { context: '.', dockerfile: 'docker/Dockerfile.signal-release' },
+      networks: { 'internet-external': { ipv4_address: SIMULATOR_IPS.SIGNAL_RELEASE } },
+      cap_add: ['NET_ADMIN'],
+    });
+  }
+
+  // --- Optional signal-cli simulator ---
+  // Same network placement as the real daemon so a test can swap one for the
+  // other without touching the module's configured endpoint.
+  if (config.signalSim) {
+    services['signal-sim'] = baseService({
+      build: { context: '.', dockerfile: 'docker/Dockerfile.signal-sim' },
+      networks: { internal: { ipv4_address: '192.168.0.91' } },
+      cap_add: ['NET_ADMIN'],
+      environment: {
+        SIGNAL_ACCOUNT: '+15551234567',
+        SIGNAL_KNOWN_RECIPIENTS: '+15550001,+15550002',
+        // Mirrors the flag the module's systemd unit must pass. Without it the
+        // simulator refuses `receive`, exactly as the real daemon does — which
+        // is the point: a test may only read replies from a daemon started the
+        // way celilo has to deploy it.
+        SIGNAL_RECEIVE_MODE: 'manual',
+      },
+    });
+  }
+
   // --- Observer vantages (passive spies; ISS-0117) ---
   // Each is the SAME image at a different network location with a routing profile that
   // mirrors a real device there — that routing profile is what makes it a faithful seat
@@ -528,6 +632,9 @@ export function generateTestComposeYaml(config: NetworkConfig, celiloRoot?: stri
       build: { context: '.', dockerfile: 'docker/Dockerfile.observer' },
       networks: { [p.network]: { ipv4_address: p.ip } },
       cap_add: ['NET_ADMIN'],
+      // A vantage may dial a VPN and probe from INSIDE the tunnel — the only way
+      // to assert VPN reach by real signal instead of by reading a rule string.
+      devices: ['/dev/net/tun'],
       environment: observerEnv(p),
     });
   }
@@ -660,6 +767,7 @@ export function generateComposeYaml(config: NetworkConfig, celiloRoot = '..'): s
       './config/dns/celilo.computer.zone:/seed/celilo.computer.zone:ro',
       './config/dns/example.net.zone:/seed/example.net.zone:ro',
       './config/dns/park-your-domain.com.zone:/seed/park-your-domain.com.zone:ro',
+      './config/dns/tangohost.com.zone:/seed/tangohost.com.zone:ro',
     ],
   });
 
@@ -691,12 +799,7 @@ export function generateComposeYaml(config: NetworkConfig, celiloRoot = '..'): s
     volumes: getRegistryVolumes(),
   });
 
-  const allMachines = [
-    ...config.dmzMachines,
-    ...config.appMachines,
-    ...config.secureMachines,
-    ...config.internalMachines,
-  ];
+  const allMachines = getAllMachines(config);
 
   for (const machine of allMachines) {
     const zoneNetwork = machine.zone;
@@ -743,5 +846,6 @@ export function getAllMachines(config: NetworkConfig): MachineSpec[] {
     ...config.appMachines,
     ...config.secureMachines,
     ...config.internalMachines,
+    ...(config.secureMgmtMachines ?? []),
   ];
 }

package/src/exit-cleanup.test.ts

@@ -0,0 +1,56 @@
+/**
+ * Recurrence gate for #508: a failed e2e run must not leak its Docker networks.
+ *
+ * The sim's networks use the same subnets as a real celilo fleet, so on a host
+ * that lives in those subnets (celilo's forgejo-builder does) a stranded bridge
+ * leaves a duplicate route for a production prefix and blackholes later
+ * containers' traffic to the real address. Three consecutive release runs died
+ * that way — in `git fetch`, ~132s connect timeout — well after the e2e run
+ * that stranded the network had finished.
+ *
+ * The leak's mechanism was a wiring bug, so the gate is on the wiring.
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { expect, test } from 'bun:test';
+
+const SRC = readFileSync(
+  join(dirname(fileURLToPath(import.meta.url)), 'container-manager.ts'),
+  'utf-8',
+);
+
+test("teardown is wired to 'exit', which is the event an explicit process.exit() fires", () => {
+  // `beforeExit` alone was the bug: the runner ends with
+  // `process.exit(failed > 0 ? 1 : 0)`, so on the failure path — where the test
+  // never reaches handle.stop() — nothing ever tore the network down.
+  expect(SRC).toContain("process.on('exit'");
+});
+
+test('cleanup honors --keep / --reuse so a failed run stays debuggable', () => {
+  // Without this guard, adding the `exit` hook would destroy exactly the stack
+  // an operator asked to keep, since --keep matters most after a failure.
+  const body = SRC.slice(
+    SRC.indexOf('function cleanupOnExit'),
+    SRC.indexOf('process.on(\'SIGTERM\''),
+  );
+  expect(body).toContain('CELILO_E2E_KEEP');
+  expect(body).toContain('CELILO_E2E_REUSE');
+});
+
+test("the premise holds: process.exit() fires 'exit' but NOT 'beforeExit'", async () => {
+  // The whole fix rests on this runtime behavior. If it ever changes, the
+  // reasoning above is void and this should fail loudly rather than silently
+  // leaving the leak unfixed.
+  const proc = Bun.spawn([
+    'bun',
+    '-e',
+    "process.on('beforeExit', () => console.log('BEFORE_EXIT')); process.on('exit', () => console.log('EXIT')); process.exit(0);",
+  ]);
+  const out = await new Response(proc.stdout).text();
+  await proc.exited;
+
+  expect(out).toContain('EXIT');
+  expect(out).not.toContain('BEFORE_EXIT');
+});

package/src/index.ts

@@ -48,6 +48,8 @@ export type {
 } from './types';
 export {
   CeliloCommandError,
+  externalWanIp,
+  externalWanSubnet,
   greenwaveRouterIp,
   internalNatIp,
   internalResolverIp,
@@ -84,6 +86,11 @@ export {
   TECHNITIUM_DHCP_STACK,
 } from './fixtures';
 
+// Simulator addresses on `internet-external` — canonical for code, so a test
+// asserting against the authoritative DNS server never hardcodes its IP.
+export { SIMULATOR_IPS, SIMULATOR_IP_ENTRIES } from './simulator-ips';
+export type { SimulatorIpName } from './simulator-ips';
+
 // Shared infrastructure management (for test runners)
 export { ensureSharedInfra, stopSharedInfra, isSharedInfraRunning } from './shared-infra';
 

package/src/network-builder.ts

@@ -38,7 +38,11 @@ export class NetworkBuilder {
     appMachines: [],
     secureMachines: [],
     internalMachines: [],
+    secureMgmtMachines: [],
     dhcpClient: false,
+    signalCli: false,
+    signalSim: false,
+    signalRelease: false,
     observers: [],
     domain: 'iamtheinternet.org',
     ddnsPassword: 'test123',
@@ -51,6 +55,17 @@ export class NetworkBuilder {
     return this;
   }
 
+  /**
+   * Place the celilo management container in a given zone. Defaults to
+   * `internal`; `secure-mgmt` gives celilo-mgr its own control-plane network
+   * (the production topology), so a test can exercise celilo reaching and
+   * resolving for a fleet from OFF the internal LAN.
+   */
+  managementZone(zone: 'internal' | 'secure-mgmt'): this {
+    this.config.managementZone = zone;
+    return this;
+  }
+
   /** Append `{name, ip, zone, ...extra}` for each entry to a zone's machine list. */
   private addMachines(
     target: MachineSpec[],
@@ -80,6 +95,19 @@ export class NetworkBuilder {
     return this.addMachines(this.config.internalMachines, 'internal', machines);
   }
 
+  /**
+   * Add machines on celilo's control plane (`secure-mgmt`).
+   *
+   * For a module whose manifest declares `zone: secure-mgmt` — the signal
+   * transport does, because it holds the operator's Signal identity and must
+   * depend on nothing it reports about. Without this the module deploys onto
+   * whatever zone a test happened to add a machine in, which is the placement
+   * defect #435 is about, or fails selection outright.
+   */
+  secureMgmt(machines: Record<string, string>): this {
+    return this.addMachines(this.config.secureMgmtMachines, 'secure-mgmt', machines);
+  }
+
   /** Add internal-zone machines that need the Docker-capable image (e.g., Technitium) */
   internalDocker(machines: Record<string, string>): this {
     return this.addMachines(this.config.internalMachines, 'internal', machines, { docker: true });
@@ -97,6 +125,44 @@ export class NetworkBuilder {
     return this;
   }
 
+  /**
+   * Add a real, UNLINKED signal-cli daemon on the internal network.
+   *
+   * For verifying the JSON-RPC contract against the actual binary. It cannot
+   * send to a phone (no account, and CDSI/SVR2 attestation makes a local
+   * Signal substitute impossible), but every endpoint, envelope and error
+   * shape celilo's client relies on is checkable without one.
+   */
+  withSignalCli(): this {
+    this.config.signalCli = true;
+    return this;
+  }
+
+  /**
+   * Add the signal-cli SIMULATOR on the internal network.
+   *
+   * Use this for anything that drives the delivery or ack loop: unlike the
+   * real daemon it exposes a control surface (`/_control/inbound`,
+   * `/_control/sent`, `/_control/unlink`) so a test can make a human "reply"
+   * and then assert on what celilo did about it.
+   */
+  withSignalSim(): this {
+    this.config.signalSim = true;
+    return this;
+  }
+
+  /**
+   * Serve the signal-cli release tarball from the simulated internet.
+   *
+   * Needed to DEPLOY the signal module: its ansible role downloads signal-cli
+   * at deploy time, and the e2e network is sealed. Point the module at it with
+   * `module config set signal release_base_url http://signal-release.lab`.
+   */
+  withSignalRelease(): this {
+    this.config.signalRelease = true;
+    return this;
+  }
+
   /**
    * Inject one or more observer vantages (ISS-0117) — passive spies carrying the probe
    * toolbox, each placed at its vantage's network location with a routing profile that

package/src/public-sim-routes.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Recurrence gate: every simulator on `internet-external` must route the
+ * customer's public prefix via the ISP edge.
+ *
+ * `internet-external` models the public internet. A host there replies to a
+ * customer's public address through its ISP — modelled by defaulting via
+ * fw-ext (100.64.0.1). Docker's bridge gateway has no path across networks, so
+ * a simulator without that route silently blackholes every reply.
+ *
+ * This was invisible for as long as fw-ext MASQUERADEd the customer to its own
+ * on-link 100.64.0.1: nothing needed routing, so five simulators shipped
+ * without it. Removing that second NAT (an ISP routes a subscriber's public
+ * prefix, it does not NAT it) turned the omission into a hang — first in
+ * `bun add -g` against the sim npm registry, then in the signal module's
+ * release download. Both cost a full build-and-run cycle to find.
+ *
+ * A static check because the honest runtime one is impossible here: fw-ext is
+ * per-test, so at shared-infra readiness the route's next hop does not exist
+ * yet. Reading the compose the generator actually emits (rather than a
+ * hand-kept list) means a NEW simulator is covered the day it is added.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse } from 'yaml';
+import { generateSharedInfraYaml, generateTestComposeYaml } from './docker-compose-generator';
+import type { NetworkConfig } from './types';
+
+/** fw-ext's address on internet-external — the ISP edge every public host exits by. */
+const ISP_EDGE = '100.64.0.1';
+
+/** The one container that IS the edge, so it cannot route through itself. */
+const EDGE_SERVICE = 'fw-ext';
+
+interface ComposeService {
+  build?: { dockerfile?: string };
+  networks?: Record<string, unknown>;
+}
+
+/** Every optional simulator switched on, so none escapes the sweep. */
+const EVERYTHING: NetworkConfig = {
+  topology: 'default',
+  dmzMachines: [],
+  appMachines: [],
+  secureMachines: [],
+  internalMachines: [],
+  secureMgmtMachines: [],
+  domain: 'iamtheinternet.org',
+  ddnsPassword: 'test123',
+  verifyRouting: false,
+  managementVolumes: [],
+  dhcpClient: true,
+  signalCli: true,
+  signalSim: true,
+  signalRelease: true,
+};
+
+function publicSimulators(yaml: string): Array<{ name: string; dockerfile: string }> {
+  const compose = parse(yaml) as { services?: Record<string, ComposeService> };
+  return Object.entries(compose.services ?? {})
+    .filter(([name, svc]) => name !== EDGE_SERVICE && svc.networks?.['internet-external'])
+    .map(([name, svc]) => ({ name, dockerfile: svc.build?.dockerfile ?? '' }));
+}
+
+/**
+ * True if the image establishes the route — either through the shared
+ * entrypoint or by naming the ISP edge itself (a few sims predate the shared
+ * script and do it inline in their own entrypoint).
+ */
+function establishesIspRoute(dockerfile: string): boolean {
+  const e2eDir = join(import.meta.dir, '..');
+  const text = readFileSync(join(e2eDir, dockerfile), 'utf-8');
+  if (text.includes('public-sim-entrypoint.sh') || text.includes(ISP_EDGE)) return true;
+
+  // Otherwise the route may live in a script the image copies in. Follow every
+  // COPY source that looks like a script and check those too.
+  for (const match of text.matchAll(/^COPY\s+(?:--from=\S+\s+)?(\S+\.sh)\s/gm)) {
+    try {
+      if (readFileSync(join(e2eDir, match[1]), 'utf-8').includes(ISP_EDGE)) return true;
+    } catch {
+      // A COPY source outside the build context is not a route carrier.
+    }
+  }
+
+  // Some sims ship their entrypoint in a simulators/<name>/ directory copied
+  // wholesale; check the obvious sibling.
+  for (const match of text.matchAll(/^COPY\s+(?:--from=\S+\s+)?(simulators\/\S+)\s/gm)) {
+    try {
+      if (readFileSync(join(e2eDir, match[1], 'entrypoint.sh'), 'utf-8').includes(ISP_EDGE)) {
+        return true;
+      }
+    } catch {
+      // Not an entrypoint-bearing directory.
+    }
+  }
+  return false;
+}
+
+describe('public simulators route back through the ISP edge', () => {
+  const simulators = [
+    ...publicSimulators(generateSharedInfraYaml()),
+    ...publicSimulators(generateTestComposeYaml(EVERYTHING)),
+  ];
+
+  test('the sweep actually found simulators', () => {
+    // Guard against the check silently passing because the filter broke.
+    expect(simulators.length).toBeGreaterThan(5);
+  });
+
+  for (const { name, dockerfile } of simulators) {
+    test(`${name} routes the customer prefix via ${ISP_EDGE}`, () => {
+      expect(dockerfile).not.toBe('');
+      expect(establishesIspRoute(dockerfile)).toBe(true);
+    });
+  }
+});

package/src/simulator-ips.ts

@@ -35,6 +35,15 @@ export const SIMULATOR_IPS = {
   APT_REPO: '100.64.0.60',
   /** MinIO S3-compatible object storage — backup/restore target (replaces AWS S3 in tests). Reachable at http://minio.lab. */
   MINIO: '100.64.0.61',
+  /**
+   * OFF-FLEET cPanel/SSH web host simulator (`tangohost.com`) — a third-party
+   * host celilo publishes to via `external_web` but does NOT govern. A public
+   * peer of namecheap-dns/pebble, NOT behind the customer firewall, so public
+   * DNS pointing the domain here is a genuine public endpoint.
+   */
+  CPANEL_HOST: '100.64.0.63',
+  /** signal-cli release host — serves the tarball the signal module downloads at deploy time. */
+  SIGNAL_RELEASE: '100.64.0.62',
   /** Pebble ACME server (replaces production Let's Encrypt). */
   PEBBLE: '100.64.0.100',
 } as const;

package/src/types.ts

@@ -1,4 +1,13 @@
-export type Zone = 'dmz' | 'app' | 'secure' | 'internal';
+/**
+ * A placement zone a machine can be brought up in.
+ *
+ * `secure-mgmt` is celilo's own control plane, not a data-plane tier. It was
+ * expressible for the management box alone until a module declared
+ * `zone: secure-mgmt` (#436, the signal transport) and infrastructure
+ * selection had nowhere to put it — so a module that named the zone correctly
+ * could not be deployed by any test.
+ */
+export type Zone = 'dmz' | 'app' | 'secure' | 'internal' | 'secure-mgmt';
 
 /**
  * Where a network assertion is made FROM — named by the box's network location
@@ -38,6 +47,11 @@ export interface NetworkConfig {
   appMachines: MachineSpec[];
   secureMachines: MachineSpec[];
   internalMachines: MachineSpec[];
+  /**
+   * Machines on celilo's control-plane network. Bringing one up implies the
+   * `secure-mgmt` network exists, whether or not celilo-mgr itself sits there.
+   */
+  secureMgmtMachines: MachineSpec[];
   domain: string;
   ddnsPassword: string;
   verifyRouting: boolean;
@@ -45,6 +59,40 @@ export interface NetworkConfig {
   managementVolumes: string[];
   /** Include a DHCP client container on the internal network */
   dhcpClient: boolean;
+  /**
+   * Include a REAL signal-cli daemon on the internal network.
+   *
+   * Never linked to a Signal account — the JSON-RPC interface is served
+   * locally and needs none. It exists so the contract celilo's client depends
+   * on is verified against the actual binary rather than against a simulator
+   * that encodes the same assumptions. See design.md D16.
+   */
+  signalCli: boolean;
+  /**
+   * Include the signal-cli SIMULATOR on the internal network.
+   *
+   * The drivable counterpart to `signalCli`: it can queue an inbound reply,
+   * fail a recipient inside a JSON-RPC success, and revoke the device link on
+   * command, which is what a test of the delivery/ack loop needs and what an
+   * unlinked real daemon cannot be made to do.
+   */
+  signalSim: boolean;
+  /**
+   * Serve the signal-cli release tarball from the simulated internet, so the
+   * signal module's deploy-time download resolves inside the sealed network.
+   */
+  signalRelease: boolean;
+  /**
+   * Which zone the celilo management container sits in. Defaults to `internal`
+   * — the single-network topology every existing test uses.
+   *
+   * `secure-mgmt` places celilo-mgr on its OWN control-plane network, which is
+   * the production topology and the one the suite could not express before. That
+   * gap is why the control-plane-network bug reached production: with management
+   * always on `internal`, the hardcoded "trusted subnet == network.internal.subnet"
+   * assumption was accidentally true in every test.
+   */
+  managementZone?: 'internal' | 'secure-mgmt';
   /**
    * Observer vantages to inject into the topology. Each becomes an `observer-*`
    * container — a passive spy carrying the probe tooling, placed at the named
@@ -364,6 +412,7 @@ export const ZONE_GATEWAYS: Record<Zone, string> = {
   app: '10.0.20.1',
   secure: '10.0.30.1',
   internal: '192.168.0.254',
+  'secure-mgmt': '10.0.120.1',
 };
 
 export const ZONE_SUBNETS: Record<Zone, string> = {
@@ -371,6 +420,7 @@ export const ZONE_SUBNETS: Record<Zone, string> = {
   app: '10.0.20.0/24',
   secure: '10.0.30.0/24',
   internal: '192.168.0.0/24',
+  'secure-mgmt': '10.0.120.0/24',
 };
 
 /**
@@ -394,6 +444,26 @@ export function greenwaveRouterIp(): string {
   return '192.168.0.1';
 }
 
+/**
+ * The customer firewall's EXTERNAL (WAN) address — what the public internet
+ * sees, and the only address a public A record for a fronted service may hold
+ * (CLAUDE.md inviolable rule #1). Also the source address a DDNS update
+ * acquires on its way out, which is what makes source-IP registration correct
+ * by construction. Reference this instead of hardcoding it.
+ */
+export function externalWanIp(): string {
+  return '100.100.0.100';
+}
+
+/**
+ * The customer's public /24 on `isp-external`. The ISP ROUTES this prefix; it
+ * never re-NATs it, so a packet leaving the fleet still carries the firewall's
+ * WAN address when it reaches a public service.
+ */
+export function externalWanSubnet(): string {
+  return '100.100.0.0/24';
+}
+
 /** The internal split-horizon DNS resolver (dns-int) in the e2e topology. */
 export function internalResolverIp(): string {
   return '192.168.0.10';