@celilo/e2e 0.9.3 → 0.10.0

package/simulators/signal-cli/server.ts

@@ -0,0 +1,272 @@
+/**
+ * signal-cli JSON-RPC daemon simulator.
+ *
+ * Mimics `signal-cli daemon --http <addr>`: JSON-RPC 2.0 over POST, with the
+ * behaviours that make the real thing awkward, because those are the ones
+ * celilo has to survive:
+ *
+ *   - errors arrive as a JSON-RPC `error` member with HTTP **200**, so code
+ *     that checks `response.ok` believes a rejected send succeeded;
+ *   - an unlinked/revoked account answers HTTP perfectly and can send nothing;
+ *   - `receive` returns receipts and typing indicators alongside real
+ *     messages, and those are not replies.
+ *
+ * It pushes back rather than saying yes. Sending to a number that has not been
+ * registered with the simulator fails the way Signal fails.
+ *
+ * ── FIDELITY ───────────────────────────────────────────────────────────────
+ * Every shape below is verified against signal-cli 0.14.6 running in a
+ * container, plus its published JSON schemas — not against recollection. The
+ * contract test in e2e re-checks the real daemon so this file cannot silently
+ * drift from it. See design.md D16 for the verified table.
+ *
+ * Still true: this cannot prove that a LINKED account delivers to a phone.
+ * That needs Signal's real network, and CDSI/SVR2 attestation makes a local
+ * substitute impossible. Everything short of delivery is verified.
+ * ───────────────────────────────────────────────────────────────────────────
+ *
+ * Control surface (simulator-only, not part of signal-cli):
+ *   POST /_control/inbound   {from, body}  queue a reply as if a human sent it
+ *   POST /_control/soft-fail {recipient}   make a recipient fail INSIDE a success
+ *   POST /_control/unlink                  revoke the device link
+ *   POST /_control/relink                  restore it
+ *   GET  /_control/sent                    every message sent, for assertions
+ */
+
+const ACCOUNT = process.env.SIGNAL_ACCOUNT ?? '+15551234567';
+const PORT = Number(process.env.SIGNAL_RPC_PORT ?? 8080);
+
+/** Numbers the simulator will accept as recipients. Anything else is rejected. */
+const KNOWN_RECIPIENTS = new Set(
+  (process.env.SIGNAL_KNOWN_RECIPIENTS ?? '')
+    .split(',')
+    .map((n) => n.trim())
+    .filter(Boolean),
+);
+
+interface SentMessage {
+  recipient: string;
+  message: string;
+  timestamp: number;
+}
+
+interface QueuedInbound {
+  from: string;
+  body: string;
+  timestamp: number;
+}
+
+const sent: SentMessage[] = [];
+/**
+ * Recipients that fail INSIDE a successful response, with a non-SUCCESS
+ * `type`. signal-cli only raises a JSON-RPC error when nothing succeeded, so
+ * this is how a partial failure looks — and how a client that checks only
+ * `error` ends up recording an undelivered page as sent.
+ */
+const unregisteredRecipients = new Set<string>();
+const inboundQueue: QueuedInbound[] = [];
+let linked = true;
+let clock = 1_722_200_000_000;
+
+const nextTimestamp = () => ++clock;
+
+function rpcResult(id: unknown, result: unknown): Response {
+  return Response.json({ jsonrpc: '2.0', id, result });
+}
+
+/**
+ * A JSON-RPC error, returned with HTTP 200 exactly as signal-cli does. This is
+ * the single most important fidelity detail in the simulator.
+ */
+function rpcError(id: unknown, code: number, message: string): Response {
+  return Response.json({ jsonrpc: '2.0', id, error: { code, message } }, { status: 200 });
+}
+
+function handleSend(id: unknown, params: Record<string, unknown>): Response {
+  if (!linked) {
+    return rpcError(id, -32000, 'Account is not registered or the device link was removed');
+  }
+
+  const recipients = Array.isArray(params.recipient) ? (params.recipient as string[]) : [];
+  const message = typeof params.message === 'string' ? params.message : '';
+
+  if (recipients.length === 0) return rpcError(id, -32602, 'No recipient given');
+
+  for (const recipient of recipients) {
+    // Push back like Signal: an unregistered number is a hard failure, not a
+    // silent no-op.
+    if (KNOWN_RECIPIENTS.size > 0 && !KNOWN_RECIPIENTS.has(recipient)) {
+      return rpcError(id, -32000, `Unregistered user: ${recipient}`);
+    }
+  }
+
+  const timestamp = nextTimestamp();
+  for (const recipient of recipients) {
+    sent.push({ recipient, message, timestamp });
+    console.log(`[signal-sim] -> ${recipient}: ${message.split('\n')[0]}`);
+  }
+
+  // Verified shape: { timestamp, results: [ { type, recipientAddress } ] }.
+  // The per-recipient `type` is the THIRD failure mode — a call can succeed
+  // at the JSON-RPC level and still not have delivered.
+  return rpcResult(id, {
+    timestamp,
+    results: recipients.map((recipient) => ({
+      type: unregisteredRecipients.has(recipient) ? 'UNREGISTERED_FAILURE' : 'SUCCESS',
+      recipientAddress: { number: recipient },
+    })),
+  });
+}
+
+/**
+ * Drain the inbound queue.
+ *
+ * Interleaves a delivery receipt and a typing indicator with real messages —
+ * the real daemon does, and a consumer that treats every envelope as a reply
+ * will misbehave on them.
+ */
+function handleReceive(id: unknown): Response {
+  if (!linked) {
+    return rpcError(id, -32000, 'Account is not registered or the device link was removed');
+  }
+
+  const envelopes: unknown[] = [
+    {
+      envelope: {
+        sourceNumber: ACCOUNT,
+        timestamp: nextTimestamp(),
+        receiptMessage: { isDelivery: true },
+      },
+    },
+  ];
+
+  while (inboundQueue.length > 0) {
+    const item = inboundQueue.shift() as QueuedInbound;
+    envelopes.push({
+      envelope: {
+        sourceNumber: item.from,
+        timestamp: item.timestamp,
+        dataMessage: { message: item.body },
+      },
+    });
+    console.log(`[signal-sim] <- ${item.from}: ${item.body}`);
+  }
+
+  envelopes.push({
+    envelope: {
+      sourceNumber: ACCOUNT,
+      timestamp: nextTimestamp(),
+      typingMessage: { action: 'STARTED' },
+    },
+  });
+
+  return rpcResult(id, envelopes);
+}
+
+function handleListAccounts(id: unknown): Response {
+  // A revoked link answers happily with an empty account list — reachability
+  // is not health.
+  return rpcResult(id, linked ? [{ number: ACCOUNT }] : []);
+}
+
+async function handleControl(url: URL, req: Request): Promise<Response> {
+  switch (url.pathname) {
+    case '/_control/inbound': {
+      const body = (await req.json()) as { from?: string; body?: string };
+      if (!body.from || !body.body) {
+        return Response.json({ error: 'from and body required' }, { status: 400 });
+      }
+      inboundQueue.push({ from: body.from, body: body.body, timestamp: nextTimestamp() });
+      return Response.json({ queued: inboundQueue.length });
+    }
+    case '/_control/soft-fail': {
+      const body = (await req.json()) as { recipient?: string };
+      if (!body.recipient) {
+        return Response.json({ error: 'recipient required' }, { status: 400 });
+      }
+      unregisteredRecipients.add(body.recipient);
+      return Response.json({ softFailing: [...unregisteredRecipients] });
+    }
+    case '/_control/unlink':
+      linked = false;
+      console.log('[signal-sim] device link revoked');
+      return Response.json({ linked });
+    case '/_control/relink':
+      linked = true;
+      console.log('[signal-sim] device link restored');
+      return Response.json({ linked });
+    case '/_control/sent':
+      return Response.json({ sent });
+    case '/_control/reset':
+      sent.length = 0;
+      inboundQueue.length = 0;
+      unregisteredRecipients.clear();
+      linked = true;
+      return Response.json({ ok: true });
+    default:
+      return new Response('Not found', { status: 404 });
+  }
+}
+
+Bun.serve({
+  port: PORT,
+  hostname: '0.0.0.0',
+  async fetch(req) {
+    const url = new URL(req.url);
+
+    if (url.pathname.startsWith('/_control/')) return handleControl(url, req);
+
+    // Verified endpoints on the real daemon.
+    if (url.pathname === '/api/v1/check') {
+      return req.method === 'GET' ? new Response(null, { status: 200 }) : new Response(null, { status: 405 });
+    }
+    if (url.pathname === '/api/v1/events') {
+      return new Response('', { status: 200, headers: { 'content-type': 'text/event-stream' } });
+    }
+    if (url.pathname !== '/api/v1/rpc') return new Response('Not found', { status: 404 });
+
+    // Verified: the real daemon returns 415 when Content-Type is not JSON.
+    const contentType = req.headers.get('content-type');
+    if (!contentType?.startsWith('application/json')) {
+      return new Response(null, { status: 415 });
+    }
+
+    if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+
+    let payload: { id?: unknown; method?: string; params?: Record<string, unknown> };
+    try {
+      payload = (await req.json()) as typeof payload;
+    } catch {
+      return Response.json(
+        { jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } },
+        { status: 200 },
+      );
+    }
+
+    const { id = null, method, params = {} } = payload;
+
+    switch (method) {
+      case 'send':
+        return handleSend(id, params);
+      case 'receive':
+        return handleReceive(id);
+      case 'listAccounts':
+        return handleListAccounts(id);
+      case 'version':
+        // Verified: { "version": "0.14.6" }
+        return rpcResult(id, { version: '0.14.6' });
+      default:
+        return rpcError(id, -32601, `Method not found: ${method}`);
+    }
+  },
+});
+
+console.log(`[signal-sim] signal-cli JSON-RPC simulator on :${PORT} as ${ACCOUNT}`);
+if (KNOWN_RECIPIENTS.size > 0) {
+  console.log(`[signal-sim] known recipients: ${[...KNOWN_RECIPIENTS].join(', ')}`);
+}
+
+// Marks this file a module so its top-level constants get their own scope.
+// Without it, `PORT` here collides with the same name in the isitup simulator,
+// which shares a tsconfig.
+export {};

package/src/cli/build.ts

@@ -23,6 +23,7 @@ import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } fro
 import { basename, join, resolve } from 'node:path';
 import { gunzipSync } from 'node:zlib';
 import { stageAptRepo } from '../../scripts/stage-apt-repo';
+import { stageLibsignal } from '../../scripts/stage-libsignal';
 import { ensureRegistryServerBundle } from '../registry-bundle';
 
 /**
@@ -176,6 +177,12 @@ async function stageSimulatorInputs(pkgDir: string): Promise<void> {
   // time, so this must run before buildDockerImages().
   stageAptRepo(repoRoot, pkgDir);
 
+  // (d) Build + stage the libsignal aarch64 native as a .deb, into the SAME
+  // pool stageAptRepo just populated (so it must run after it — that function
+  // recreates the pool empty). Compiled here on the host's own network rather
+  // than inside the sealed e2e network; see stage-libsignal.ts.
+  stageLibsignal(repoRoot, pkgDir);
+
   console.log('');
 }
 

package/src/cli/index.ts

@@ -61,6 +61,12 @@ function detectTestDir(): { stateDir: string; testsPath: string } {
     }
   }
   if (existsSync(join(cwd, 'tests'))) return { stateDir: cwd, testsPath: join(cwd, 'tests') };
+  // The repo's own top-level suite lives at e2e/tests/, which is what `list`
+  // enumerates. Without this, `cele2e list` shows a test that `cele2e run
+  // <name>` then cannot find — the run/list disagreement in #412.
+  if (existsSync(join(cwd, 'e2e', 'tests'))) {
+    return { stateDir: join(cwd, 'e2e'), testsPath: join(cwd, 'e2e', 'tests') };
+  }
   return { stateDir: cwd, testsPath: join(cwd, 'tests') };
 }
 

package/src/container-manager.ts

@@ -935,7 +935,11 @@ export async function startNetwork(config: NetworkConfig): Promise<NetworkHandle
       `celilo system init --accept-defaults \
         network.internal.subnet=${ZONE_SUBNETS.internal} \
         network.internal.gateway=${ZONE_GATEWAYS.internal} \
-        dns.primary=100.100.0.1 \
+        ${
+          config.managementZone === 'secure-mgmt'
+            ? 'network.secure-mgmt.subnet=10.0.120.0/24 network.secure-mgmt.gateway=10.0.120.1 '
+            : ''
+        }dns.primary=100.100.0.1 \
         dns.fallback=1.0.0.1,8.8.8.8`,
     );
     if (initResult.exitCode !== 0) {

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,17 @@ 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';
   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.
+    ...(mgmtOnOwnNetwork
+      ? { '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 +434,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 +462,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 +502,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 (mgmtOnOwnNetwork) {
+    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' },
@@ -518,6 +580,44 @@ 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',
+      },
+    });
+  }
+
   // --- 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 +628,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 +763,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',
     ],
   });
 

package/src/network-builder.ts

@@ -39,6 +39,9 @@ export class NetworkBuilder {
     secureMachines: [],
     internalMachines: [],
     dhcpClient: false,
+    signalCli: false,
+    signalSim: false,
+    signalRelease: false,
     observers: [],
     domain: 'iamtheinternet.org',
     ddnsPassword: 'test123',
@@ -51,6 +54,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[],
@@ -97,6 +111,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/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

@@ -45,6 +45,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