@celilo/e2e 0.7.14 → 0.7.15

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/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 });
+  }
+}

package/src/vantage.test.ts

@@ -0,0 +1,200 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  type CertInfo,
+  type ProbeTransport,
+  type Vantage,
+  VantageAssertionError,
+  VantageProbe,
+} from './vantage';
+
+/**
+ * A scriptable fake transport: the verbs are pure orchestration over this boundary,
+ * so we can drive every assertion path without Docker (Rule 2.3).
+ */
+function fakeTransport(overrides: Partial<ProbeTransport> = {}): ProbeTransport {
+  return {
+    resolve: async () => ({ ips: [] }),
+    tcpConnect: async () => ({ connected: false }),
+    ping: async () => ({ alive: false }),
+    httpsRequest: async () => ({ status: 200, body: '', cert: realCert() }),
+    inspectResolution: async () => ({ resolvConf: '', hostsLines: [] }),
+    ...overrides,
+  };
+}
+
+function realCert(over: Partial<CertInfo> = {}): CertInfo {
+  return {
+    cn: 'www.example.com',
+    issuer: 'Pebble Intermediate CA',
+    subjectAltNames: ['www.example.com'],
+    selfSigned: false,
+    ...over,
+  };
+}
+
+const LAN: Vantage = 'internalDevice';
+
+describe('resolveFrom', () => {
+  test('defaults method to system, passes through ips', async () => {
+    const probe = new VantageProbe(fakeTransport({ resolve: async () => ({ ips: ['192.168.0.253'] }) }));
+    const r = await probe.resolveFrom({ from: LAN, name: 'www.example.com' });
+    expect(r.method).toBe('system');
+    expect(r.ips).toEqual(['192.168.0.253']);
+  });
+});
+
+describe('assertResolves / assertNxdomain', () => {
+  test('assertResolves throws on empty answer', async () => {
+    const probe = new VantageProbe(fakeTransport({ resolve: async () => ({ ips: [] }) }));
+    await expect(probe.assertResolves({ from: LAN, name: 'gone.example.com' })).rejects.toThrow(
+      VantageAssertionError,
+    );
+  });
+  test('assertNxdomain throws when a public vantage CAN see an internal-only name', async () => {
+    const probe = new VantageProbe(fakeTransport({ resolve: async () => ({ ips: ['10.0.20.5'] }) }));
+    await expect(
+      probe.assertNxdomain({ from: 'publicInternet', name: 'authentik.internal' }),
+    ).rejects.toThrow(/expected NXDOMAIN/);
+  });
+});
+
+describe('assertResolvesInZone — the killer verb', () => {
+  test('ISS-0101: www at caddy DMZ container IP FAILS from internalDevice', async () => {
+    const probe = new VantageProbe(fakeTransport({ resolve: async () => ({ ips: ['10.0.10.10'] }) }));
+    await expect(
+      probe.assertResolvesInZone({ from: LAN, name: 'www.example.com', zone: 'internal' }),
+    ).rejects.toThrow(/ISS-0101/);
+  });
+
+  test('www at the firewall natIp PASSES from internalDevice (the right answer)', async () => {
+    const probe = new VantageProbe(fakeTransport({ resolve: async () => ({ ips: ['192.168.0.253'] }) }));
+    const r = await probe.assertResolvesInZone({ from: LAN, name: 'www.example.com', zone: 'internal' });
+    expect(r.ips).toEqual(['192.168.0.253']);
+  });
+
+  test('public vantage expecting a public answer passes; a leaked zone IP fails', async () => {
+    const ok = new VantageProbe(fakeTransport({ resolve: async () => ({ ips: ['100.100.0.100'] }) }));
+    await ok.assertResolvesInZone({ from: 'publicInternet', name: 'www.example.com', zone: 'public' });
+
+    const leaked = new VantageProbe(fakeTransport({ resolve: async () => ({ ips: ['192.168.0.253'] }) }));
+    await expect(
+      leaked.assertResolvesInZone({ from: 'publicInternet', name: 'www.example.com', zone: 'public' }),
+    ).rejects.toThrow(VantageAssertionError);
+  });
+
+  test('any one leaked IP among several fails the whole answer', async () => {
+    const probe = new VantageProbe(
+      fakeTransport({ resolve: async () => ({ ips: ['192.168.0.253', '10.0.30.9'] }) }),
+    );
+    await expect(
+      probe.assertResolvesInZone({ from: LAN, name: 'www.example.com', zone: 'internal' }),
+    ).rejects.toThrow(/10\.0\.30\.9/);
+  });
+});
+
+describe('assertResolvesTo — exact-IP DNS correctness', () => {
+  test('passes when the resolver returns the expected IP (via a specific server)', async () => {
+    const probe = new VantageProbe(fakeTransport({ resolve: async () => ({ ips: ['192.168.0.53'] }) }));
+    const r = await probe.assertResolvesTo({
+      from: 'internalDevice',
+      name: 'host.infra.example.com',
+      method: 'dns',
+      server: '192.168.0.10',
+      expected: '192.168.0.53',
+    });
+    expect(r.ips).toEqual(['192.168.0.53']);
+  });
+
+  test('fails (naming the server) when the expected IP is absent', async () => {
+    const probe = new VantageProbe(fakeTransport({ resolve: async () => ({ ips: ['10.0.10.99'] }) }));
+    await expect(
+      probe.assertResolvesTo({
+        from: 'internalDevice',
+        name: 'host.infra.example.com',
+        method: 'dns',
+        server: '192.168.0.10',
+        expected: '192.168.0.53',
+      }),
+    ).rejects.toThrow(/via 192\.168\.0\.10.*expected to include \[192\.168\.0\.53\]/);
+  });
+
+  test('accepts an array of expected IPs (all must be present)', async () => {
+    const probe = new VantageProbe(fakeTransport({ resolve: async () => ({ ips: ['1.2.3.4', '5.6.7.8'] }) }));
+    await probe.assertResolvesTo({ from: 'publicInternet', name: 'x', expected: ['1.2.3.4', '5.6.7.8'] });
+    await expect(
+      probe.assertResolvesTo({ from: 'publicInternet', name: 'x', expected: ['1.2.3.4', '9.9.9.9'] }),
+    ).rejects.toThrow(/9\.9\.9\.9/);
+  });
+});
+
+describe('reachability + isolation (§D6)', () => {
+  test('assertReachable throws when the connection fails (ISS-0111 git-ssh:2222)', async () => {
+    const probe = new VantageProbe(fakeTransport({ tcpConnect: async () => ({ connected: false, detail: 'timeout' }) }));
+    await expect(probe.assertReachable({ from: LAN, host: 'git-ssh.example.com', port: 2222 })).rejects.toThrow(
+      /timeout/,
+    );
+  });
+  test('assertUnreachable throws when isolation is violated', async () => {
+    const probe = new VantageProbe(fakeTransport({ tcpConnect: async () => ({ connected: true }) }));
+    await expect(probe.assertUnreachable({ from: 'appSystem', host: '10.0.30.5', port: 443 })).rejects.toThrow(
+      /zone isolation/,
+    );
+  });
+  test('the reachable/unreachable happy paths do not throw', async () => {
+    const reachable = new VantageProbe(fakeTransport({ tcpConnect: async () => ({ connected: true }) }));
+    await reachable.assertReachable({ from: LAN, host: '192.168.0.253', port: 443 });
+    const blocked = new VantageProbe(fakeTransport({ tcpConnect: async () => ({ connected: false }) }));
+    await blocked.assertUnreachable({ from: 'appSystem', host: '10.0.30.5', port: 443 });
+  });
+});
+
+describe('assertHttps — cert provenance', () => {
+  test('self-signed cert is rejected (catches --insecure / skip-cert cheats)', async () => {
+    const probe = new VantageProbe(
+      fakeTransport({ httpsRequest: async () => ({ status: 200, body: 'ok', cert: realCert({ selfSigned: true }) }) }),
+    );
+    await expect(probe.assertHttps({ from: LAN, url: 'https://www.example.com' })).rejects.toThrow(/self-signed/);
+  });
+  test('wrong CA issuer is rejected', async () => {
+    const probe = new VantageProbe(fakeTransport());
+    await expect(
+      probe.assertHttps({ from: LAN, url: 'https://www.example.com', expectCA: "Let's Encrypt" }),
+    ).rejects.toThrow(/issuer/);
+  });
+  test('matching CN + CA + status passes', async () => {
+    const probe = new VantageProbe(fakeTransport());
+    const r = await probe.assertHttps({
+      from: LAN,
+      url: 'https://www.example.com',
+      expectStatus: 200,
+      expectCN: 'www.example.com',
+      expectCA: 'Pebble',
+    });
+    expect(r.status).toBe(200);
+    expect(r.cert.cn).toBe('www.example.com');
+  });
+  test('unexpected status is rejected', async () => {
+    const probe = new VantageProbe(
+      fakeTransport({ httpsRequest: async () => ({ status: 502, body: '', cert: realCert() }) }),
+    );
+    await expect(
+      probe.assertHttps({ from: LAN, url: 'https://www.example.com', expectStatus: 200 }),
+    ).rejects.toThrow(/status 502/);
+  });
+});
+
+describe('inspectResolution', () => {
+  test('returns the vantage resolv.conf + matching hosts lines (host-pin check, ISS-0095)', async () => {
+    const probe = new VantageProbe(
+      fakeTransport({
+        inspectResolution: async () => ({
+          resolvConf: 'nameserver 192.168.0.253',
+          hostsLines: ['10.0.10.10 auth.example.com'],
+        }),
+      }),
+    );
+    const r = await probe.inspectResolution({ from: 'dmzSystem', name: 'auth.example.com' });
+    expect(r.hostsLines).toContain('10.0.10.10 auth.example.com');
+    expect(r.resolvConf).toContain('192.168.0.253');
+  });
+});