@celilo/e2e 0.7.14 → 0.7.16

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

package/src/vantage.ts

@@ -0,0 +1,266 @@
+/**
+ * Vantage-point network assertions (ISS-0117, §D3/§D4).
+ *
+ * Every network check runs FROM a named vantage — the box a real consumer occupies —
+ * and classifies the result against the zone topology (see ./zone-classifier). A green
+ * from the wrong vantage is worse than no test: ISS-0101 (www -> DMZ container IP),
+ * ISS-0111 (git-ssh -> container IP) and the ISS-0095 risk all passed e2e because the
+ * assertion ran from the management box, which has routes into every zone.
+ *
+ * This module is the typed VERB layer. It performs no I/O itself: it orchestrates a
+ * `ProbeTransport` (the injected boundary, Rule 2.3 / Rule 10.4) and applies zone
+ * classification + assertion policy on the typed results. The real transports — a
+ * dockerExec escape hatch now, a probe-agent later (§D2) — implement `ProbeTransport`
+ * elsewhere, so the verbs stay pure and unit-testable without Docker.
+ */
+
+import { type Vantage, type Zone } from './types';
+import { classifyIp } from './zone-classifier';
+
+// `Vantage` is topology vocabulary — defined in ./types alongside Zone — and re-exported
+// here so verb-layer consumers can import it from the same module as the verbs.
+export type { Vantage };
+
+/** How a name is resolved (§D3) — lets us test the resolution layers independently. */
+export type ResolveMethod =
+  | 'system' // the vantage's real stack: resolv.conf AND /etc/hosts
+  | 'dns' // query a resolver directly (optionally a specific `server`)
+  | 'hostfiles'; // the /etc/hosts layer only (the host-pin path — ISS-0095)
+
+/** A zone the answer may legitimately land in, plus `public` for a routable internet address. */
+export type ExpectedZone = Zone | 'public';
+
+export interface ResolveResult {
+  name: string;
+  from: Vantage;
+  method: ResolveMethod;
+  ips: string[]; // resolved A records; empty == NXDOMAIN / no answer
+}
+
+export interface CertInfo {
+  cn: string;
+  issuer: string;
+  subjectAltNames: string[];
+  selfSigned: boolean;
+}
+
+export interface HttpsResult {
+  from: Vantage;
+  url: string;
+  status: number;
+  body: string;
+  cert: CertInfo;
+}
+
+export interface ResolutionInspection {
+  from: Vantage;
+  name: string;
+  resolvConf: string;
+  hostsLines: string[];
+}
+
+/**
+ * The injected I/O boundary. Implementations (dockerExec-based now, probe-agent later)
+ * are the ONLY place raw shell / network calls live; the verbs below never touch I/O.
+ */
+export interface ProbeTransport {
+  resolve(opts: { from: Vantage; name: string; method: ResolveMethod; server?: string }): Promise<{ ips: string[] }>;
+  tcpConnect(opts: { from: Vantage; host: string; port: number }): Promise<{ connected: boolean; detail?: string }>;
+  ping(opts: { from: Vantage; target: string }): Promise<{ alive: boolean }>;
+  httpsRequest(opts: { from: Vantage; url: string }): Promise<{ status: number; body: string; cert: CertInfo }>;
+  inspectResolution(opts: { from: Vantage; name: string }): Promise<{ resolvConf: string; hostsLines: string[] }>;
+}
+
+/** Thrown when a vantage assertion fails. Messages name the bug class they guard. */
+export class VantageAssertionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'VantageAssertionError';
+  }
+}
+
+interface ResolveOpts {
+  from: Vantage;
+  name: string;
+  method?: ResolveMethod;
+  server?: string;
+}
+
+interface ReachOpts {
+  from: Vantage;
+  host: string;
+  port: number;
+}
+
+interface HttpsAssertOpts {
+  from: Vantage;
+  url: string;
+  expectStatus?: number;
+  expectCN?: string;
+  expectCA?: string; // expected issuer substring (Let's Encrypt / Pebble in e2e); never self-signed
+}
+
+function describeZone(ip: string): string {
+  const c = classifyIp(ip);
+  switch (c.kind) {
+    case 'zone':
+      return `zone ${c.zone}`;
+    case 'reserved':
+      return `reserved (${c.label})`;
+    case 'public':
+      return 'public';
+    case 'invalid':
+      return 'invalid IP';
+  }
+}
+
+/**
+ * The typed probe surface. Construct with a transport; every verb takes a single
+ * options object with a required `from` (§D1 — no default vantage).
+ */
+export class VantageProbe {
+  constructor(private readonly transport: ProbeTransport) {}
+
+  async resolveFrom(opts: ResolveOpts): Promise<ResolveResult> {
+    const method = opts.method ?? 'system';
+    const { ips } = await this.transport.resolve({
+      from: opts.from,
+      name: opts.name,
+      method,
+      server: opts.server,
+    });
+    return { name: opts.name, from: opts.from, method, ips };
+  }
+
+  async assertResolves(opts: ResolveOpts): Promise<ResolveResult> {
+    const result = await this.resolveFrom(opts);
+    if (result.ips.length === 0) {
+      throw new VantageAssertionError(
+        `${opts.name} did not resolve from ${opts.from} (NXDOMAIN / no A record), expected an answer.`,
+      );
+    }
+    return result;
+  }
+
+  async assertNxdomain(opts: ResolveOpts): Promise<void> {
+    const result = await this.resolveFrom(opts);
+    if (result.ips.length > 0) {
+      throw new VantageAssertionError(
+        `${opts.name} resolved from ${opts.from} to ${result.ips.join(', ')}, expected NXDOMAIN ` +
+          `(this name must not be visible from ${opts.from}).`,
+      );
+    }
+  }
+
+  /**
+   * The killer verb: resolve, classify every answer, assert the expected zone.
+   * `www.<domain>` from `internalDevice` MUST be `internal`/`public` (natIp/public),
+   * never a managed `dmz`/`app`/`secure` container IP — the ISS-0101 / ISS-0111 class.
+   */
+  async assertResolvesInZone(opts: ResolveOpts & { zone: ExpectedZone }): Promise<ResolveResult> {
+    const result = await this.assertResolves(opts);
+    const offenders = result.ips.filter((ip) => !ipMatchesExpectedZone(ip, opts.zone));
+    if (offenders.length > 0) {
+      const detail = offenders.map((ip) => `${ip} (${describeZone(ip)})`).join(', ');
+      throw new VantageAssertionError(
+        `${opts.name} from ${opts.from} resolved to ${detail}, expected zone "${opts.zone}". ` +
+          'A managed-zone container IP is unroutable from outside that zone — this is the ' +
+          'e2e-green/prod-broke class (ISS-0101, ISS-0111). The right answer from a consumer ' +
+          'vantage is the firewall natIp (internal) or a public address.',
+      );
+    }
+    return result;
+  }
+
+  /**
+   * Resolve and assert the answer includes the EXACT expected IP(s) — the DNS-correctness
+   * verb. Pair with `method: 'dns', server` to assert what a SPECIFIC resolver returns (e.g.
+   * the internal split-horizon resolver vs the public resolver). Used by the DNS suites to
+   * check a DDNS-registered IP, an nsupdate'd A record, or a split-horizon answer.
+   */
+  async assertResolvesTo(opts: ResolveOpts & { expected: string | string[] }): Promise<ResolveResult> {
+    const result = await this.assertResolves(opts);
+    const expected = Array.isArray(opts.expected) ? opts.expected : [opts.expected];
+    const missing = expected.filter((ip) => !result.ips.includes(ip));
+    if (missing.length > 0) {
+      const via = opts.server ? ` via ${opts.server}` : '';
+      throw new VantageAssertionError(
+        `${opts.name} from ${opts.from}${via} resolved to [${result.ips.join(', ')}], ` +
+          `expected to include [${missing.join(', ')}].`,
+      );
+    }
+    return result;
+  }
+
+  async ping(opts: { from: Vantage; target: string }): Promise<boolean> {
+    const { alive } = await this.transport.ping(opts);
+    return alive;
+  }
+
+  async assertReachable(opts: ReachOpts): Promise<void> {
+    const { connected, detail } = await this.transport.tcpConnect(opts);
+    if (!connected) {
+      throw new VantageAssertionError(
+        `${opts.host}:${opts.port} was NOT reachable from ${opts.from}` +
+          (detail ? ` (${detail})` : '') +
+          ', expected a successful TCP connection.',
+      );
+    }
+  }
+
+  /** Isolation assertion (§D6): prove what shouldn't work, e.g. appSystem cannot reach a secure host. */
+  async assertUnreachable(opts: ReachOpts): Promise<void> {
+    const { connected } = await this.transport.tcpConnect(opts);
+    if (connected) {
+      throw new VantageAssertionError(
+        `${opts.host}:${opts.port} WAS reachable from ${opts.from}, expected it to be blocked ` +
+          '(zone isolation / firewall boundary violated).',
+      );
+    }
+  }
+
+  /**
+   * Connect, validate the REAL cert chain (right CN, expected issuer, never self-signed),
+   * then status. Cert provenance catches the skip-cert / 0.0.0.0-sentinel cheats.
+   */
+  async assertHttps(opts: HttpsAssertOpts): Promise<HttpsResult> {
+    const res = await this.transport.httpsRequest({ from: opts.from, url: opts.url });
+    const result: HttpsResult = { from: opts.from, url: opts.url, ...res };
+
+    if (res.cert.selfSigned) {
+      throw new VantageAssertionError(
+        `${opts.url} from ${opts.from} presented a self-signed cert (issuer "${res.cert.issuer}"). ` +
+          'A real cert from the e2e CA (Pebble / Let’s Encrypt) is required — no --insecure.',
+      );
+    }
+    if (opts.expectCN && res.cert.cn !== opts.expectCN) {
+      throw new VantageAssertionError(
+        `${opts.url} from ${opts.from} cert CN "${res.cert.cn}", expected "${opts.expectCN}".`,
+      );
+    }
+    if (opts.expectCA && !res.cert.issuer.includes(opts.expectCA)) {
+      throw new VantageAssertionError(
+        `${opts.url} from ${opts.from} cert issuer "${res.cert.issuer}", expected to contain "${opts.expectCA}".`,
+      );
+    }
+    if (opts.expectStatus !== undefined && res.status !== opts.expectStatus) {
+      throw new VantageAssertionError(
+        `${opts.url} from ${opts.from} returned status ${res.status}, expected ${opts.expectStatus}.`,
+      );
+    }
+    return result;
+  }
+
+  /** Diagnostic (§D3): the vantage's resolv.conf + matching /etc/hosts lines. Also asserts a host-pin (ISS-0095). */
+  async inspectResolution(opts: { from: Vantage; name: string }): Promise<ResolutionInspection> {
+    const res = await this.transport.inspectResolution(opts);
+    return { from: opts.from, name: opts.name, ...res };
+  }
+}
+
+/** True if `ip` satisfies the expected zone (managed zone exact, or routable `public`). */
+function ipMatchesExpectedZone(ip: string, expected: ExpectedZone): boolean {
+  const c = classifyIp(ip);
+  if (expected === 'public') return c.kind === 'public';
+  return c.kind === 'zone' && c.zone === expected;
+}

package/src/zone-classifier.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, test } from 'bun:test';
+import { classifyIp, inCidr, isPublicLeakSafe, isSegmentedZoneIp, parseIpv4 } from './zone-classifier';
+
+describe('parseIpv4', () => {
+  test('parses dotted-quad to unsigned 32-bit', () => {
+    expect(parseIpv4('0.0.0.0')).toBe(0);
+    expect(parseIpv4('255.255.255.255')).toBe(0xffffffff);
+    // High first octet must not go negative (sign-bit overflow guard).
+    expect(parseIpv4('192.168.0.253')).toBe(((192 << 24) | (168 << 16) | (0 << 8) | 253) >>> 0);
+    expect(parseIpv4('192.168.0.253')).toBeGreaterThan(0);
+  });
+  test('rejects malformed / out-of-range', () => {
+    expect(parseIpv4('not.an.ip')).toBeNull();
+    expect(parseIpv4('999.1.1.1')).toBeNull();
+    expect(parseIpv4('10.0.0')).toBeNull();
+  });
+});
+
+describe('inCidr', () => {
+  test('membership within /24', () => {
+    expect(inCidr('10.0.10.5', '10.0.10.0/24')).toBe(true);
+    expect(inCidr('10.0.10.255', '10.0.10.0/24')).toBe(true);
+    expect(inCidr('10.0.11.1', '10.0.10.0/24')).toBe(false);
+  });
+  test('high-octet subnet (192.168) — no sign-bit bug', () => {
+    expect(inCidr('192.168.0.253', '192.168.0.0/24')).toBe(true);
+    expect(inCidr('192.168.1.1', '192.168.0.0/24')).toBe(false);
+  });
+});
+
+describe('classifyIp', () => {
+  test('managed zones (the segmented ones)', () => {
+    expect(classifyIp('10.0.10.10')).toEqual({ kind: 'zone', zone: 'dmz' }); // caddy
+    expect(classifyIp('10.0.20.30')).toEqual({ kind: 'zone', zone: 'app' }); // authentik
+    expect(classifyIp('10.0.30.5')).toEqual({ kind: 'zone', zone: 'secure' });
+  });
+  test('internal zone (the LAN — natIp lives here)', () => {
+    expect(classifyIp('192.168.0.253')).toEqual({ kind: 'zone', zone: 'internal' });
+  });
+  test('public: the CGNAT stand-in and real public space', () => {
+    expect(classifyIp('100.100.0.100')).toEqual({ kind: 'public' }); // sim firewall external
+    expect(classifyIp('8.8.8.8')).toEqual({ kind: 'public' });
+    expect(classifyIp('71.36.115.155')).toEqual({ kind: 'public' }); // the prod DDNS target
+  });
+  test('reserved ranges (incl. the 0.0.0.0 sentinel cheat)', () => {
+    expect(classifyIp('0.0.0.0').kind).toBe('reserved');
+    expect(classifyIp('127.0.0.1').kind).toBe('reserved');
+    expect(classifyIp('169.254.1.1').kind).toBe('reserved');
+    expect(classifyIp('224.0.0.1').kind).toBe('reserved');
+  });
+  test('invalid input', () => {
+    expect(classifyIp('nope').kind).toBe('invalid');
+    expect(classifyIp('256.0.0.1').kind).toBe('invalid');
+  });
+});
+
+describe('isSegmentedZoneIp', () => {
+  test('dmz/app/secure are segmented; internal and public are not', () => {
+    expect(isSegmentedZoneIp('10.0.10.10')).toBe(true); // caddy DMZ — the ISS-0101/0111 bug value
+    expect(isSegmentedZoneIp('10.0.20.30')).toBe(true);
+    expect(isSegmentedZoneIp('192.168.0.253')).toBe(false); // internal IS the LAN
+    expect(isSegmentedZoneIp('100.100.0.100')).toBe(false); // public
+  });
+});
+
+describe('isPublicLeakSafe (CLAUDE.md inviolable rule #1)', () => {
+  test('only public addresses are leak-safe', () => {
+    expect(isPublicLeakSafe('100.100.0.100')).toBe(true);
+    expect(isPublicLeakSafe('8.8.8.8')).toBe(true);
+    expect(isPublicLeakSafe('10.0.10.10')).toBe(false); // managed segmented zone
+    expect(isPublicLeakSafe('192.168.0.253')).toBe(false); // internal/RFC-1918 must not leak
+    expect(isPublicLeakSafe('0.0.0.0')).toBe(false); // reserved sentinel
+  });
+
+  test('the ISS-0101 scenario: a fronted name resolving to caddy DMZ IP is NOT leak-safe', () => {
+    // www.<domain> from a LAN device must be the natIp (internal) or public, never
+    // caddy's DMZ container IP. The doctor + e2e share this judgment.
+    const wwwResolvedWrong = '10.0.10.10';
+    expect(isSegmentedZoneIp(wwwResolvedWrong)).toBe(true);
+    expect(classifyIp('192.168.0.253').kind).toBe('zone'); // the RIGHT answer (natIp, internal)
+  });
+});