@celilo/e2e 0.7.14 → 0.7.15

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

package/src/zone-classifier.ts

@@ -0,0 +1,92 @@
+/**
+ * Zone classification for e2e network assertions (ISS-0117, §D5).
+ *
+ * Pure functions: given a resolved IPv4, say which celilo zone it belongs to (by
+ * matching the topology's `ZONE_SUBNETS`), or whether it is a reserved/special-use
+ * range, or a globally-routable "public" address. The vantage-assertion verbs
+ * (`resolveFrom` / `assertResolvesInZone`, ISS-0117 §D3) build on this to enforce
+ * e.g. "www.<domain> resolved from internalDevice must NOT be a segmented-zone
+ * container IP" — the ISS-0101 / ISS-0111 bug class.
+ *
+ * Classification uses `ZONE_SUBNETS` (exact) + a reserved-range check — deliberately
+ * NOT a blanket RFC-1918/CGNAT ban: the sim's "public" IP is a CGNAT stand-in
+ * (100.100.0.100), so in this topology 10.x / 192.168.x are *zones* and 100.x is
+ * *public*. (A real deployment would additionally treat RFC-1918 + RFC-6598 as
+ * non-public; that's the caller's policy, layered on top of this primitive.)
+ */
+
+import { type Zone, ZONE_SUBNETS } from './types';
+
+export type ZoneClass =
+  | { kind: 'zone'; zone: Zone }
+  | { kind: 'reserved'; label: string }
+  | { kind: 'public' }
+  | { kind: 'invalid' };
+
+/**
+ * Segmented zones a device on the operator's LAN (`internal`) cannot route into —
+ * traffic to them must go via the firewall natIp. `internal` IS the LAN, so it is
+ * NOT segmented (a record at an internal-zone IP is reachable).
+ */
+export const SEGMENTED_ZONES: readonly Zone[] = ['dmz', 'app', 'secure'];
+
+/**
+ * Special-use IPv4 ranges that must never be a real service address (nor appear in
+ * any DNS answer). RFC-1918 and RFC-6598 (CGNAT) are intentionally absent — in this
+ * topology the former are the managed zones and the latter is the public stand-in.
+ */
+const RESERVED: ReadonlyArray<{ cidr: string; label: string }> = [
+  { cidr: '0.0.0.0/8', label: 'unspecified/this-host (incl. the 0.0.0.0 sentinel)' },
+  { cidr: '127.0.0.0/8', label: 'loopback' },
+  { cidr: '169.254.0.0/16', label: 'link-local (RFC 3927)' },
+  { cidr: '224.0.0.0/4', label: 'multicast' },
+  { cidr: '240.0.0.0/4', label: 'reserved (RFC 1112)' },
+];
+
+/** Parse a dotted-quad IPv4 to an unsigned 32-bit int, or null if malformed. */
+export function parseIpv4(ip: string): number | null {
+  const m = ip.trim().match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  if (!m) return null;
+  const octets = m.slice(1, 5).map(Number);
+  if (octets.some((o) => o > 255)) return null;
+  return ((octets[0] << 24) | (octets[1] << 16) | (octets[2] << 8) | octets[3]) >>> 0;
+}
+
+/** True if `ip` falls within `cidr` (e.g. "10.0.10.0/24"). */
+export function inCidr(ip: string, cidr: string): boolean {
+  const [base, bitsStr] = cidr.split('/');
+  const bits = Number(bitsStr);
+  const ipN = parseIpv4(ip);
+  const baseN = parseIpv4(base);
+  if (ipN === null || baseN === null || Number.isNaN(bits) || bits < 0 || bits > 32) return false;
+  if (bits === 0) return true;
+  const mask = (0xffffffff << (32 - bits)) >>> 0;
+  return (ipN & mask) >>> 0 === ((baseN & mask) >>> 0);
+}
+
+/** Classify a resolved IPv4 against the e2e topology. */
+export function classifyIp(ip: string): ZoneClass {
+  if (parseIpv4(ip) === null) return { kind: 'invalid' };
+  for (const r of RESERVED) {
+    if (inCidr(ip, r.cidr)) return { kind: 'reserved', label: r.label };
+  }
+  for (const zone of Object.keys(ZONE_SUBNETS) as Zone[]) {
+    if (inCidr(ip, ZONE_SUBNETS[zone])) return { kind: 'zone', zone };
+  }
+  return { kind: 'public' };
+}
+
+/** True if `ip` is inside a segmented zone (dmz/app/secure) — unroutable from the LAN. */
+export function isSegmentedZoneIp(ip: string): boolean {
+  const c = classifyIp(ip);
+  return c.kind === 'zone' && SEGMENTED_ZONES.includes(c.zone);
+}
+
+/**
+ * The "no leak past the public boundary" rule (ISS-0117 §D5; CLAUDE.md inviolable
+ * rule #1): a public DNS answer must be a routable public address — never a managed
+ * zone (incl. `internal`/RFC-1918) nor a reserved range.
+ */
+export function isPublicLeakSafe(ip: string): boolean {
+  return classifyIp(ip).kind === 'public';
+}

package/config/dns/iamtheinternet.org.zone

@@ -1,16 +0,0 @@
-$ORIGIN iamtheinternet.org.
-$TTL 300
-
-@ IN SOA ns1.iamtheinternet.org. admin.iamtheinternet.org. (
-    2024020247 300 60 604800 300
-)
-
-; Public DNS — RFC 1918 addresses NEVER appear here. The whole point of
-; the e2e simulation is to model real internet connectivity, where
-; private IPs are unreachable from outside. All public-facing names
-; resolve to the firewall's external IP (100.100.0.100), which DNATs
-; inbound to the right internal host.
-@       IN NS   ns1.iamtheinternet.org.
-ns1     IN A    100.64.0.55
-@       IN A    0.0.0.0
-www     IN A    100.100.0.100

package/config/dns/templates/lunacycle.net.zone

@@ -1,16 +0,0 @@
-$ORIGIN lunacycle.net.
-$TTL 300
-
-@ IN SOA ns1.lunacycle.net. admin.lunacycle.net. (
-    2024020108 300 60 604800 300
-)
-
-; Public DNS — RFC 1918 addresses NEVER appear here. The whole point of
-; the e2e simulation is to model real internet connectivity, where
-; private IPs are unreachable from outside. All public-facing names
-; resolve to the firewall's external IP (100.100.0.100), which DNATs
-; inbound to the right internal host.
-@       IN NS   ns1.lunacycle.net.
-ns1     IN A    100.64.0.55
-@       IN A    100.100.0.100
-www     IN A    100.100.0.100