@celilo/e2e 0.7.13 → 0.7.15

package/src/observer.test.ts

@@ -0,0 +1,155 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  createObserverTransport,
+  normalizeObservers,
+  OBSERVER_PLACEMENTS,
+  observerEnv,
+  vantageContainer,
+} from './observer';
+import type { ExecResult, NetworkHandle } from './types';
+import { ZONE_GATEWAYS } from './types';
+
+/** A NetworkHandle whose `exec` records calls and returns scripted results. */
+function fakeHandle(script: (container: string, cmd: string) => Partial<ExecResult>) {
+  const calls: { container: string; cmd: string }[] = [];
+  const exec = (container: string, cmd: string): Promise<ExecResult> => {
+    calls.push({ container, cmd });
+    return Promise.resolve({ stdout: '', stderr: '', exitCode: 0, ...script(container, cmd) });
+  };
+  return { handle: { exec } as unknown as NetworkHandle, calls };
+}
+
+describe('placement faithfulness (the load-bearing invariants)', () => {
+  test('internalDevice routes via the home router, NOT fw-main, and has no inter-zone routes', () => {
+    const p = OBSERVER_PLACEMENTS.internalDevice;
+    expect(p.network).toBe('internal');
+    expect(p.interZoneRoutes).toBe(false);
+    // The whole point: default route is the LAN's home router, never ZONE_GATEWAYS.internal
+    // (fw-main), which would hand it a path into the segmented zones.
+    expect(p.gateway).not.toBe(ZONE_GATEWAYS.internal);
+  });
+
+  test('no injectable observer carries inter-zone routes (only the management trap would)', () => {
+    for (const p of Object.values(OBSERVER_PLACEMENTS)) {
+      expect(p.interZoneRoutes).toBe(false);
+    }
+  });
+
+  test('segmented-zone observer IPs derive from their zone gateway (no pinned subnets)', () => {
+    expect(OBSERVER_PLACEMENTS.dmzSystem.gateway).toBe(ZONE_GATEWAYS.dmz);
+    expect(OBSERVER_PLACEMENTS.dmzSystem.ip).toBe(ZONE_GATEWAYS.dmz.replace(/\.\d+$/, '.240'));
+    expect(OBSERVER_PLACEMENTS.secureSystem.ip).toBe(ZONE_GATEWAYS.secure.replace(/\.\d+$/, '.240'));
+  });
+
+  test('publicInternet uses only the public resolver (never the internal split-horizon view)', () => {
+    expect(OBSERVER_PLACEMENTS.publicInternet.resolvers).toEqual(['100.100.0.1']);
+  });
+
+  test('observerEnv serializes the routing profile for the setup script', () => {
+    const env = observerEnv(OBSERVER_PLACEMENTS.internalDevice);
+    expect(env.OBSERVER_INTERZONE).toBe('0');
+    expect(env.OBSERVER_GATEWAY).toBe(OBSERVER_PLACEMENTS.internalDevice.gateway);
+    expect(env.OBSERVER_RESOLVERS).toContain('100.100.0.1');
+  });
+});
+
+describe('normalizeObservers + vantageContainer', () => {
+  test('dedupes and rejects management as an injectable observer', () => {
+    expect(normalizeObservers([{ vantage: 'internalDevice' }, { vantage: 'internalDevice' }])).toHaveLength(1);
+    expect(() => normalizeObservers([{ vantage: 'management' }])).toThrow(/management/);
+  });
+  test('management vantage maps to the real management container; others to observers', () => {
+    expect(vantageContainer('management')).toBe('management');
+    expect(vantageContainer('internalDevice')).toBe(OBSERVER_PLACEMENTS.internalDevice.service);
+  });
+});
+
+describe('observer transport — parsing + container targeting', () => {
+  test('resolve(system) parses getent first column and targets the right observer', async () => {
+    const { handle, calls } = fakeHandle((_c, cmd) =>
+      cmd.startsWith('getent') ? { stdout: '192.168.0.253  www.iamtheinternet.org' } : {},
+    );
+    const t = createObserverTransport(handle);
+    const r = await t.resolve({ from: 'internalDevice', name: 'www.iamtheinternet.org', method: 'system' });
+    expect(r.ips).toEqual(['192.168.0.253']);
+    expect(calls[0].container).toBe('observer-internal');
+  });
+
+  test('resolve(dns) with explicit server', async () => {
+    const { handle, calls } = fakeHandle((_c, cmd) => (cmd.includes('dig') ? { stdout: '10.0.10.10\n' } : {}));
+    const t = createObserverTransport(handle);
+    const r = await t.resolve({ from: 'dmzSystem', name: 'auth.x', method: 'dns', server: '192.168.0.10' });
+    expect(r.ips).toEqual(['10.0.10.10']);
+    expect(calls[0].cmd).toContain('@192.168.0.10');
+  });
+
+  test('resolve(hostfiles) parses /etc/hosts first column', async () => {
+    const { handle } = fakeHandle((_c, cmd) =>
+      cmd.startsWith('grep -F') ? { stdout: '10.0.10.10 auth.iamtheinternet.org' } : {},
+    );
+    const t = createObserverTransport(handle);
+    const r = await t.resolve({ from: 'dmzSystem', name: 'auth.iamtheinternet.org', method: 'hostfiles' });
+    expect(r.ips).toEqual(['10.0.10.10']);
+  });
+
+  test('tcpConnect maps the container exit code', async () => {
+    const { handle } = fakeHandle((_c, cmd) => ({ exitCode: cmd.includes('443') ? 0 : 1 }));
+    const t = createObserverTransport(handle);
+    expect((await t.tcpConnect({ from: 'internalDevice', host: '192.168.0.253', port: 443 })).connected).toBe(true);
+    expect((await t.tcpConnect({ from: 'internalDevice', host: '10.0.10.10', port: 22 })).connected).toBe(false);
+  });
+
+  test('httpsRequest parses cert (CN/issuer/SAN/selfSigned) + status', async () => {
+    const { handle } = fakeHandle((_c, cmd) => {
+      if (cmd.includes('openssl s_client')) {
+        return {
+          stdout:
+            'subject=CN = deathstar.iamtheinternet.org\n' +
+            'issuer=CN = Pebble Intermediate CA 1a2b3c\n' +
+            'X509v3 Subject Alternative Name:\n    DNS:deathstar.iamtheinternet.org\n',
+        };
+      }
+      if (cmd.includes('%{http_code}')) return { stdout: '200' };
+      return { stdout: 'Caddy reverse proxy is running' };
+    });
+    const t = createObserverTransport(handle);
+    const r = await t.httpsRequest({ from: 'publicInternet', url: 'https://deathstar.iamtheinternet.org' });
+    expect(r.status).toBe(200);
+    expect(r.cert.cn).toBe('deathstar.iamtheinternet.org');
+    expect(r.cert.issuer).toContain('Pebble');
+    expect(r.cert.subjectAltNames).toContain('deathstar.iamtheinternet.org');
+    expect(r.cert.selfSigned).toBe(false);
+  });
+
+  test('httpsRequest flags a self-signed cert (subject == issuer)', async () => {
+    const { handle } = fakeHandle((_c, cmd) =>
+      cmd.includes('openssl s_client')
+        ? { stdout: 'subject=CN = sketchy.local\nissuer=CN = sketchy.local\n' }
+        : cmd.includes('%{http_code}')
+          ? { stdout: '200' }
+          : {},
+    );
+    const t = createObserverTransport(handle);
+    const r = await t.httpsRequest({ from: 'internalDevice', url: 'https://sketchy.local' });
+    expect(r.cert.selfSigned).toBe(true);
+  });
+});
+
+describe('host-shell footgun guard', () => {
+  test('no command contains $(...) or backticks (would be host-evaluated through the wrap)', async () => {
+    const { handle, calls } = fakeHandle(() => ({ stdout: '200', exitCode: 0 }));
+    const t = createObserverTransport(handle);
+    await t.resolve({ from: 'internalDevice', name: 'www.x', method: 'system' });
+    await t.resolve({ from: 'internalDevice', name: 'www.x', method: 'dns', server: '192.168.0.10' });
+    await t.resolve({ from: 'internalDevice', name: 'www.x', method: 'hostfiles' });
+    await t.tcpConnect({ from: 'internalDevice', host: '10.0.10.10', port: 443 });
+    await t.ping({ from: 'internalDevice', target: '192.168.0.253' });
+    await t.httpsRequest({ from: 'internalDevice', url: 'https://www.x' });
+    await t.inspectResolution({ from: 'internalDevice', name: 'www.x' });
+    expect(calls.length).toBeGreaterThan(0);
+    for (const { cmd } of calls) {
+      expect(cmd).not.toContain('$(');
+      expect(cmd).not.toContain('`');
+    }
+  });
+});

package/src/observer.ts

@@ -0,0 +1,270 @@
+/**
+ * Observer vantages (ISS-0117 §D2/§D4) — the topology side of the vantage framework.
+ *
+ * An *observer* is a passive spy: a purpose-built container carrying all the probe
+ * tooling, injected at a named vantage's network location with a routing profile that
+ * mirrors a REAL device there. The point is faithfulness — a vantage's correctness is
+ * its routing table, not just which network it attaches to. The management box reaches
+ * a DMZ container IP directly only because management-routes.sh adds an explicit
+ * inter-zone route; a real LAN device has no such route, so it must go via the firewall
+ * natIp. An `internalDevice` observer reproduces the LAN device's routing exactly, which
+ * is how it catches the ISS-0101 / ISS-0111 "e2e-green/prod-broke" class.
+ *
+ * This file holds the single source of truth for each vantage's placement + routing
+ * profile (consumed by the compose generator), the vantage->container mapping, and the
+ * dockerExec-based ProbeTransport (the developer escape hatch the design retains; the
+ * typed probe-agent will wrap this same surface later).
+ *
+ * Commands sent through dockerExec deliberately avoid `$(...)`, backticks and unescaped
+ * `$` — those are evaluated by the HOST shell before reaching the container (the wrapping
+ * footgun CLAUDE.md documents). We rely on the container command's exit code (propagated
+ * by `docker compose exec`) instead of `echo $?`.
+ */
+
+import { type NetworkHandle, type ObserverSpec, type Vantage, ZONE_GATEWAYS } from './types';
+import type { CertInfo, ProbeTransport, ResolveMethod } from './vantage';
+
+export interface ObserverPlacement {
+  /** docker compose service name for this observer */
+  service: string;
+  /** docker network to attach to */
+  network: string;
+  /** the observer's own IP in that network */
+  ip: string;
+  /** default route (gateway) — the load-bearing faithfulness knob */
+  gateway: string;
+  /** add the management-style explicit inter-zone routes (only the `management` trap) */
+  interZoneRoutes: boolean;
+  /** nameservers written to /etc/resolv.conf, in order */
+  resolvers: string[];
+}
+
+// The internal LAN's home router (hands out DHCP option:router) and split-horizon
+// resolver. Literals here match the values the compose generator + dnsmasq already use;
+// they are roles, not pins repeated into tests. ZONE_GATEWAYS.internal (.254) is fw-main
+// — the firewall to the segmented zones — NOT the LAN's default route, which is the home
+// router below. A faithful internalDevice routes its default via the home router and has
+// NO route to the segmented zones, so a dmz/app/secure container IP is unreachable.
+const HOME_ROUTER = '192.168.0.1';
+const INTERNAL_RESOLVER = '192.168.0.10';
+const PUBLIC_RESOLVER = '100.100.0.1';
+const INTERNET_GATEWAY = '100.64.0.1'; // fw-ext, on internet-external
+
+/** Derive an observer host IP in a zone from its gateway (no new literal subnets). */
+function observerIpInZone(zone: 'dmz' | 'app' | 'secure'): string {
+  return ZONE_GATEWAYS[zone].replace(/\.\d+$/, '.240');
+}
+
+/**
+ * Placement + routing profile per injectable vantage. `management` is intentionally
+ * absent — that vantage reuses the real `management` container (see vantageContainer),
+ * so the trap is demonstrated with the actual all-VLAN box, not a copy.
+ */
+export const OBSERVER_PLACEMENTS: Record<Exclude<Vantage, 'management'>, ObserverPlacement> = {
+  internalDevice: {
+    service: 'observer-internal',
+    network: 'internal',
+    ip: '192.168.0.211', // a LAN host (dhcp range is .200-.220; dhcp-client is .210)
+    gateway: HOME_ROUTER,
+    interZoneRoutes: false,
+    // Identical DNS to the management box on purpose: the only difference vs management
+    // is the routing profile, so any reachability gap is provably routing — the bug.
+    resolvers: [INTERNAL_RESOLVER, PUBLIC_RESOLVER],
+  },
+  dmzSystem: {
+    service: 'observer-dmz',
+    network: 'dmz',
+    ip: observerIpInZone('dmz'),
+    gateway: ZONE_GATEWAYS.dmz,
+    interZoneRoutes: false,
+    resolvers: [INTERNAL_RESOLVER, PUBLIC_RESOLVER],
+  },
+  appSystem: {
+    service: 'observer-app',
+    network: 'app',
+    ip: observerIpInZone('app'),
+    gateway: ZONE_GATEWAYS.app,
+    interZoneRoutes: false,
+    resolvers: [INTERNAL_RESOLVER, PUBLIC_RESOLVER],
+  },
+  secureSystem: {
+    service: 'observer-secure',
+    network: 'secure',
+    ip: observerIpInZone('secure'),
+    gateway: ZONE_GATEWAYS.secure,
+    interZoneRoutes: false,
+    resolvers: [INTERNAL_RESOLVER, PUBLIC_RESOLVER],
+  },
+  publicInternet: {
+    service: 'observer-public',
+    network: 'internet-external',
+    ip: '100.64.0.240',
+    gateway: INTERNET_GATEWAY,
+    interZoneRoutes: false,
+    // Outside the firewall: only the public resolver, never the internal split-horizon view.
+    resolvers: [PUBLIC_RESOLVER],
+  },
+};
+
+/** The placement for an injectable vantage; throws for `management` (not injectable). */
+export function observerPlacement(vantage: Vantage): ObserverPlacement {
+  if (vantage === 'management') {
+    throw new Error('management has no observer placement — it reuses the real management container.');
+  }
+  return OBSERVER_PLACEMENTS[vantage];
+}
+
+/** The container a vantage probes from. `management` reuses the real management box. */
+export function vantageContainer(vantage: Vantage): string {
+  if (vantage === 'management') return 'management';
+  return OBSERVER_PLACEMENTS[vantage].service;
+}
+
+/** Environment a generated observer service needs for its routing-profile setup script. */
+export function observerEnv(placement: ObserverPlacement): Record<string, string> {
+  return {
+    OBSERVER_GATEWAY: placement.gateway,
+    OBSERVER_INTERZONE: placement.interZoneRoutes ? '1' : '0',
+    OBSERVER_RESOLVERS: placement.resolvers.join(' '),
+  };
+}
+
+/** Dedupe + validate a list of observer specs (a vantage can't be injected twice). */
+export function normalizeObservers(observers: ObserverSpec[]): ObserverSpec[] {
+  const seen = new Set<Vantage>();
+  const out: ObserverSpec[] = [];
+  for (const spec of observers) {
+    if (spec.vantage === 'management') {
+      throw new Error(
+        'management is not an injectable observer — that vantage reuses the real management container.',
+      );
+    }
+    if (seen.has(spec.vantage)) continue;
+    seen.add(spec.vantage);
+    out.push(spec);
+  }
+  return out;
+}
+
+// --- dockerExec-based ProbeTransport (escape hatch; substitution-free commands) ---
+
+const IPV4 = /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/;
+
+/**
+ * The first whitespace token of each line, kept if it's an IPv4. Works for all three
+ * resolve methods without shell-side column extraction (which would need `$1`/awk — a
+ * host-shell-expansion footgun): `dig +short` lines ARE the IP; `getent hosts` and
+ * `/etc/hosts` lines are "IP  name…", so token[0] is the IP either way.
+ */
+function firstColumnIps(stdout: string): string[] {
+  return stdout
+    .split('\n')
+    .map((l) => l.trim().split(/\s+/)[0] ?? '')
+    .filter((tok) => IPV4.test(tok));
+}
+
+function hostPort(url: string): { host: string; port: number } {
+  const u = new URL(url);
+  return { host: u.hostname, port: u.port ? Number(u.port) : u.protocol === 'https:' ? 443 : 80 };
+}
+
+function parseCert(opensslOut: string): CertInfo {
+  const subjectLine = opensslOut.match(/^subject=(.*)$/m)?.[1]?.trim() ?? '';
+  const issuerLine = opensslOut.match(/^issuer=(.*)$/m)?.[1]?.trim() ?? '';
+  const cn = subjectLine.match(/CN\s*=\s*([^,/]+)/)?.[1]?.trim() ?? '';
+  const issuerCn = issuerLine.match(/CN\s*=\s*([^,/]+)/)?.[1]?.trim() ?? issuerLine;
+  const sanLine = opensslOut.match(/DNS:[^\n]*/)?.[0] ?? '';
+  const subjectAltNames = sanLine
+    .split(',')
+    .map((s) => s.replace(/.*DNS:/, '').trim())
+    .filter(Boolean);
+  return {
+    cn,
+    issuer: issuerCn,
+    subjectAltNames,
+    // Pebble's leaf issuer differs from the leaf subject; equal subject==issuer ⇒ self-signed.
+    selfSigned: subjectLine !== '' && subjectLine === issuerLine,
+  };
+}
+
+/**
+ * A ProbeTransport that runs each verb's probe inside the vantage's observer container
+ * via `handle.exec`. Returns typed results; raw dockerExec stays available on `handle`.
+ */
+export function createObserverTransport(handle: NetworkHandle): ProbeTransport {
+  return {
+    async resolve(opts) {
+      const c = vantageContainer(opts.from);
+      const cmd = resolveCommand(opts.name, opts.method, opts.server);
+      const res = await handle.exec(c, cmd, 15_000);
+      return { ips: firstColumnIps(res.stdout) };
+    },
+
+    async tcpConnect(opts) {
+      const c = vantageContainer(opts.from);
+      // bash's /dev/tcp builtin, not `nc`: the management box (a valid vantage) ships no
+      // netcat, whereas /dev/tcp works on every vantage. `timeout` bounds a hung connect.
+      const res = await handle.exec(
+        c,
+        `timeout 4 bash -c 'exec 3<>/dev/tcp/${opts.host}/${opts.port}'`,
+        8_000,
+      );
+      return { connected: res.exitCode === 0, detail: res.exitCode === 0 ? undefined : 'connect failed/timed out' };
+    },
+
+    async ping(opts) {
+      const c = vantageContainer(opts.from);
+      const res = await handle.exec(c, `ping -c 1 -W 2 ${opts.target}`, 6_000);
+      return { alive: res.exitCode === 0 };
+    },
+
+    async httpsRequest(opts) {
+      const c = vantageContainer(opts.from);
+      const { host, port } = hostPort(opts.url);
+      const certRes = await handle.exec(
+        c,
+        `echo | openssl s_client -connect ${host}:${port} -servername ${host} 2>/dev/null | ` +
+          'openssl x509 -noout -subject -issuer -ext subjectAltName',
+        10_000,
+      );
+      // -k gathers the status even for an untrusted chain; the cert is reported truthfully
+      // above so the verb layer asserts provenance separately (this is fact-gathering, not
+      // validation-skipping — the no-insecure rule is enforced by the verb, not relaxed here).
+      const statusRes = await handle.exec(
+        c,
+        `curl -sk -o /dev/null -w '%{http_code}' --max-time 8 ${opts.url}`,
+        10_000,
+      );
+      const bodyRes = await handle.exec(c, `curl -sk --max-time 8 ${opts.url}`, 10_000);
+      return {
+        status: Number.parseInt(statusRes.stdout.trim(), 10) || 0,
+        body: bodyRes.stdout,
+        cert: parseCert(certRes.stdout),
+      };
+    },
+
+    async inspectResolution(opts) {
+      const c = vantageContainer(opts.from);
+      const resolv = await handle.exec(c, 'cat /etc/resolv.conf', 5_000);
+      const hosts = await handle.exec(c, `grep -F ${opts.name} /etc/hosts`, 5_000);
+      return {
+        resolvConf: resolv.stdout.trim(),
+        hostsLines: hosts.stdout.split('\n').map((l) => l.trim()).filter(Boolean),
+      };
+    },
+  };
+}
+
+function resolveCommand(name: string, method: ResolveMethod, server?: string): string {
+  switch (method) {
+    case 'dns':
+      // DNS only (ignores /etc/hosts); optionally a specific resolver.
+      return `dig +short A ${name}${server ? ` @${server}` : ''}`;
+    case 'hostfiles':
+      // The /etc/hosts layer only (the host-pin path — ISS-0095). Raw; parsed host-side.
+      return `grep -F ${name} /etc/hosts`;
+    default:
+      // system: the real stack — nsswitch consults files AND dns. getent prints "IP name...".
+      return `getent hosts ${name}`;
+  }
+}

package/src/runner.ts

@@ -58,6 +58,8 @@ function resolveModuleTestsDir(dir: string): string {
 const testsPath = moduleDir
   ? resolveModuleTestsDir(moduleDir)
   : (process.env.E2E_TESTS_PATH ?? join(testDir, 'tests'));
+/** Set by `cele2e run --all` so a module-dirs run ALSO picks up the repo's top-level e2e/tests/. */
+const topLevelTestsPath = process.env.E2E_TOP_LEVEL_TESTS;
 const timingFile = join(testDir, '.e2e-timing.json');
 const persistentFile = join(testDir, '.e2e-persistent.json');
 
@@ -427,6 +429,22 @@ async function main() {
         .map((f) => resolve(tp, f));
       testFiles.push(...files);
     }
+    // `cele2e run --all` sets E2E_MODULE_DIRS (every module) AND
+    // E2E_TOP_LEVEL_TESTS (the repo's top-level e2e/tests/), so one invocation
+    // covers BOTH the module suites and the top-level tests. Without this, the
+    // module branch and the testsPath branch below are mutually exclusive and
+    // no single run can cover everything (ISS-0013).
+    if (topLevelTestsPath) {
+      if (!existsSync(topLevelTestsPath)) {
+        console.error(`${red}No top-level tests directory found at ${topLevelTestsPath}${reset}`);
+        process.exit(1);
+      }
+      const files = readdirSync(topLevelTestsPath)
+        .filter((f) => f.endsWith('.test.ts'))
+        .sort()
+        .map((f) => resolve(topLevelTestsPath, f));
+      testFiles.push(...files);
+    }
   } else {
     if (!existsSync(testsPath)) {
       console.error(`${red}No tests/ directory found at ${testsPath}${reset}`);

package/src/types.ts

@@ -1,5 +1,25 @@
 export type Zone = 'dmz' | 'app' | 'secure' | 'internal';
 
+/**
+ * Where a network assertion is made FROM — named by the box's network location
+ * (ISS-0117 §D4). A vantage is realized in the topology by an `observer` container
+ * (passive spy with all probe tooling) placed at that location with a routing profile
+ * that mirrors a real device there. `from` is always explicit — there is no default
+ * vantage, so adding one can't silently change an existing test.
+ */
+export type Vantage =
+  | 'internalDevice' // unmanaged device on the internal/Home LAN; NO route into dmz/app/secure (the real end-user)
+  | 'dmzSystem'
+  | 'appSystem'
+  | 'secureSystem'
+  | 'publicInternet' // outside the firewall — what the real internet sees
+  | 'management'; // celilo-mgmt box; all-VLAN routes (the trap — explicit, rare)
+
+/** A request to inject an observer at a vantage (passive spy with controlled routing). */
+export interface ObserverSpec {
+  vantage: Vantage;
+}
+
 export interface MachineSpec {
   name: string;
   ip: string;
@@ -25,6 +45,13 @@ export interface NetworkConfig {
   managementVolumes: string[];
   /** Include a DHCP client container on the internal network */
   dhcpClient: boolean;
+  /**
+   * Observer vantages to inject into the topology. Each becomes an `observer-*`
+   * container — a passive spy carrying the probe tooling, placed at the named
+   * vantage's network location with a routing profile that mirrors a real device
+   * there (ISS-0117). Drive them via the VantageProbe transport.
+   */
+  observers?: ObserverSpec[];
   /**
    * Absolute path to the Celilo project root (the directory containing apps/celilo/).
    * Mounted into the management container at /celilo so the CLI is available.
@@ -330,3 +357,34 @@ export const ZONE_SUBNETS: Record<Zone, string> = {
   secure: '10.0.30.0/24',
   internal: '192.168.0.0/24',
 };
+
+/**
+ * The firewall's internal-side DNAT ingress (the natIp) in the e2e topology — the role by
+ * which an internal device reaches a service that lives in a segmented zone. Single source
+ * of truth: `deployFirewall` uses it as its default and tests assert against it, so the
+ * asserted natIp is by construction the one that was deployed. Reference this instead of
+ * hardcoding the address in a test.
+ */
+export function internalNatIp(): string {
+  return '192.168.0.253';
+}
+
+/**
+ * The internal network's internet-facing gateway router (the greenwave / fw-isp sim) — the
+ * default route for internal devices toward the internet. Distinct from
+ * `ZONE_GATEWAYS.internal` (fw-main), which is the firewall to the segmented zones. Reference
+ * this instead of hardcoding the address in a test.
+ */
+export function greenwaveRouterIp(): string {
+  return '192.168.0.1';
+}
+
+/** The internal split-horizon DNS resolver (dns-int) in the e2e topology. */
+export function internalResolverIp(): string {
+  return '192.168.0.10';
+}
+
+/** The public upstream recursive resolver (the comcast-resolver sim). */
+export function publicResolverIp(): string {
+  return '100.100.0.1';
+}

package/src/vantage-helpers.ts

@@ -0,0 +1,78 @@
+/**
+ * Reusable positive vantage assertions (ISS-0117).
+ *
+ * Module e2e suites call these after deploying a service to assert the positive network
+ * facts the right consumer should see — TLS works from the internet, the name resolves to
+ * a public address, an internal device reaches the service via the firewall natIp. The
+ * negative/isolation gates (a system that SHOULDN'T reach another) are intentionally not
+ * here — they wait on real firewall isolation (ISS-0118).
+ *
+ * Topology prerequisite: inject the observers the assertion needs, e.g.
+ *   network().dmz({ caddy: '10.0.10.10' }).observe('internalDevice', 'publicInternet')
+ */
+
+import { createObserverTransport } from './observer';
+import type { NetworkHandle } from './types';
+import { VantageProbe } from './vantage';
+
+export interface FrontedServiceExpectation {
+  /** The public hostname the service is fronted at. */
+  fqdn: string;
+  /**
+   * The firewall natIp, when the topology deploys a firewall. Enables the internalDevice
+   * reachability check (an internal device reaches the service via the controlled DNAT).
+   * Omit for topologies without a firewall (e.g. direct-internet).
+   */
+  natIp?: string;
+  /** Service port (default 443). */
+  port?: number;
+  /** Expected HTTPS status (default 200). Override for roots that redirect (e.g. 302). */
+  expectStatus?: number;
+  /** Optional path appended to the URL for the HTTPS check (e.g. '/-/ping'). */
+  path?: string;
+  /** Optional expected cert issuer substring (e.g. 'Pebble') — a CA-provenance assertion. */
+  expectCA?: string;
+}
+
+/**
+ * Assert the positive facts a web-fronted service should present from the right vantages:
+ *  - `publicInternet` resolves the FQDN to a public IP (not a private/segmented-zone IP),
+ *  - `publicInternet` gets a valid HTTPS response with a real, non-self-signed cert,
+ *  - `internalDevice` reaches the service via the firewall natIp (when `natIp` is given).
+ *
+ * Requires the topology to have injected the `publicInternet` (and, for the natIp check,
+ * `internalDevice`) observers.
+ */
+export async function assertFrontedServicePositives(
+  net: NetworkHandle,
+  expectation: FrontedServiceExpectation,
+): Promise<void> {
+  const probe = new VantageProbe(createObserverTransport(net));
+  const port = expectation.port ?? 443;
+  const url = `https://${expectation.fqdn}${expectation.path ?? ''}`;
+
+  // The internet sees the service at a public IP and a valid HTTPS endpoint.
+  await probe.assertResolvesInZone({ from: 'publicInternet', name: expectation.fqdn, zone: 'public' });
+  await probe.assertHttps({
+    from: 'publicInternet',
+    url,
+    expectStatus: expectation.expectStatus ?? 200,
+    expectCA: expectation.expectCA,
+  });
+
+  // An internal device reaches the service via the controlled natIp DNAT (when firewalled).
+  if (expectation.natIp) {
+    await probe.assertReachable({ from: 'internalDevice', host: expectation.natIp, port });
+  }
+}
+
+/** Assert several fronted hostnames at once (multi-hostname caddy, etc.). */
+export async function assertFrontedHostnames(
+  net: NetworkHandle,
+  fqdns: string[],
+  shared: Omit<FrontedServiceExpectation, 'fqdn'>,
+): Promise<void> {
+  for (const fqdn of fqdns) {
+    await assertFrontedServicePositives(net, { ...shared, fqdn });
+  }
+}