lastlight 0.1.8 → 0.2.0

package/dist/sandbox/egress-allowlist.js

@@ -0,0 +1,164 @@
+import { isIP } from "node:net";
+/**
+ * Single source of truth for sandbox HTTP egress allowlists.
+ *
+ * Both sandbox backends consume this list:
+ *   - gondolin: passed verbatim to `agenticRun({ allowedHttpHosts })` so the
+ *     QEMU-layer HTTP interceptor 502s anything off-list.
+ *   - docker: nginx-egress + coredns configs are generated from these hosts
+ *     at harness boot. Sandbox containers spawn with `--dns <coredns-ip>`;
+ *     coredns sinkholes allowlisted hostnames to the nginx firewall IP,
+ *     which peeks SNI and tunnels to the real upstream. See
+ *     `src/sandbox/egress-firewall-config.ts` for the full architecture.
+ *
+ * The lists are intentionally split so callers can compose tighter policies
+ * (e.g. a read-only profile that doesn't need package registries). The
+ * everyday default is `DEFAULT_ALLOWLIST`.
+ *
+ * ## Convention: every entry matches the apex AND all subdomains
+ *
+ * `openai.com`  → matches openai.com, api.openai.com, platform.openai.com, …
+ * `npmjs.org`   → matches npmjs.org, registry.npmjs.org, auth.npmjs.org, …
+ *
+ * Bare hostnames only — no leading dot, no `*.` prefix. The config
+ * generator emits the right syntax for each backend (nginx's
+ * `.example.com` map form, CoreDNS regex `(^|\.)example\.com\.$`).
+ *
+ * Exact-only matching isn't currently supported because we haven't
+ * needed it — every host in the list is one we want apex+subdomain
+ * access to. If we ever do, we'd add an explicit type (e.g. an `exact:`
+ * prefix) so the loose-by-default convention stays unambiguous.
+ *
+ * A workflow phase can declare `unrestricted_egress: true` to bypass the
+ * allowlist entirely — see `src/workflows` for the phase schema.
+ */
+/** GitHub HTTPS endpoints used by `git`, `gh`, and agentic-pi's github tools. */
+export const GITHUB_HOSTS = [
+    // Covers github.com plus api.github.com, codeload.github.com, raw.…, gist.…
+    "github.com",
+    // *.githubusercontent.com — release artifacts, raw blobs, avatars.
+    "githubusercontent.com",
+];
+/**
+ * LLM provider hosts.
+ *
+ * Required for the docker backend because `agentic-pi run` executes inside
+ * the sandbox container there (`src/sandbox/docker.ts` runs `agentic-pi run
+ * --sandbox none`), so the LLM HTTP call originates from inside the
+ * container. The gondolin backend runs agentic-pi in the harness process,
+ * so the call originates from the host and these hosts aren't strictly
+ * required inside the VM — they're kept here so a single allowlist can
+ * cover both paths without surprises.
+ */
+export const PROVIDER_HOSTS = [
+    "anthropic.com",
+    "openai.com",
+    "openrouter.ai",
+    // Fireworks — api.fireworks.ai is the inference endpoint.
+    "fireworks.ai",
+];
+/**
+ * Public package registries the executor may hit during `npm install`,
+ * etc. Apex-plus-subdomain matching covers auth / CDN / mirror
+ * subdomains without needing separate entries.
+ */
+export const PACKAGE_REGISTRY_HOSTS = [
+    // npm / yarn / pnpm
+    "npmjs.org",
+    "yarnpkg.com",
+    // Python — pypi.org + files.pythonhosted.org are the two big ones.
+    "pypi.org",
+    "pythonhosted.org",
+    // Rust — static.crates.io, index.crates.io, crates.io itself.
+    "crates.io",
+    // Go modules — covers proxy.golang.org, sum.golang.org, plus golang.org.
+    "golang.org",
+    // Ruby
+    "rubygems.org",
+    // Alpine apk + Debian apt — apex covers the regional mirror subdomains.
+    "alpinelinux.org",
+    "debian.org",
+];
+/**
+ * Combined allowlist used by both backends when a phase has not opted into
+ * unrestricted egress. Order is preserved across imports so generated
+ * configs are stable.
+ */
+export const DEFAULT_ALLOWLIST = [
+    ...GITHUB_HOSTS,
+    ...PROVIDER_HOSTS,
+    ...PACKAGE_REGISTRY_HOSTS,
+];
+/**
+ * Sentinel value recognized by agentic-pi/gondolin (post the `"*"` patch)
+ * meaning "allow every host". Used when a phase sets `unrestricted_egress`.
+ *
+ * On the docker backend, unrestricted egress routes through the open
+ * nginx-egress + coredns-open pair — this sentinel is for gondolin only.
+ */
+export const ALLOW_ALL_SENTINEL = "*";
+const INTERNAL_HOSTNAMES = new Set(["localhost", "metadata.google.internal"]);
+function isPrivateOrInternalIp(host) {
+    const ip = host.replace(/^\[|\]$/g, "");
+    const family = isIP(ip);
+    if (family === 4) {
+        const octets = ip.split(".").map((part) => Number(part));
+        if (octets.length !== 4 || octets.some((part) => !Number.isInteger(part) || part < 0 || part > 255))
+            return true;
+        const [a, b] = octets;
+        return a === 0
+            || a === 10
+            || a === 127
+            || (a === 169 && b === 254)
+            || (a === 172 && b >= 16 && b <= 31)
+            || (a === 192 && b === 168);
+    }
+    if (family === 6) {
+        const lower = ip.toLowerCase();
+        const mappedIpv4 = lower.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/)?.[1];
+        if (mappedIpv4)
+            return isPrivateOrInternalIp(mappedIpv4);
+        if (lower.startsWith("::ffff:"))
+            return true;
+        return lower === "::"
+            || lower === "::1"
+            || lower.startsWith("fe8")
+            || lower.startsWith("fe9")
+            || lower.startsWith("fea")
+            || lower.startsWith("feb")
+            || lower.startsWith("fc")
+            || lower.startsWith("fd");
+    }
+    return false;
+}
+export function normalizeAllowlistHost(host) {
+    const trimmed = host.trim().toLowerCase();
+    if (!trimmed)
+        return null;
+    let parsed = trimmed;
+    try {
+        parsed = new URL(trimmed.includes("://") ? trimmed : `https://${trimmed}`).hostname.toLowerCase();
+    }
+    catch {
+        parsed = trimmed.split("/")[0] || "";
+        if (!parsed.startsWith("["))
+            parsed = parsed.split(":")[0] || "";
+    }
+    parsed = parsed.replace(/^\.+|\.+$/g, "").replace(/^\[|\]$/g, "");
+    if (!parsed || parsed.includes("*") || INTERNAL_HOSTNAMES.has(parsed) || isPrivateOrInternalIp(parsed))
+        return null;
+    return parsed;
+}
+export function mergeAllowlist(base, extra = []) {
+    const out = [];
+    const seen = new Set();
+    for (const candidate of [...base, ...extra]) {
+        const host = normalizeAllowlistHost(candidate);
+        if (host && !seen.has(host)) {
+            seen.add(host);
+            out.push(host);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=egress-allowlist.js.map

package/dist/sandbox/egress-allowlist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"egress-allowlist.js","sourceRoot":"","sources":["../../src/sandbox/egress-allowlist.ts"],"names":[],"mappings":"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"}

package/dist/sandbox/egress-allowlist.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sandbox/egress-allowlist.test.js

@@ -0,0 +1,65 @@
+import { describe, it, expect } from "vitest";
+import { ALLOW_ALL_SENTINEL, DEFAULT_ALLOWLIST, GITHUB_HOSTS, PACKAGE_REGISTRY_HOSTS, PROVIDER_HOSTS, mergeAllowlist, normalizeAllowlistHost, } from "./egress-allowlist.js";
+describe("egress-allowlist source of truth", () => {
+    it("groups are non-empty and disjoint", () => {
+        for (const group of [GITHUB_HOSTS, PROVIDER_HOSTS, PACKAGE_REGISTRY_HOSTS]) {
+            expect(group.length).toBeGreaterThan(0);
+        }
+        const all = [...GITHUB_HOSTS, ...PROVIDER_HOSTS, ...PACKAGE_REGISTRY_HOSTS];
+        expect(new Set(all).size).toBe(all.length);
+    });
+    it("DEFAULT_ALLOWLIST is the union of the three groups in declaration order", () => {
+        const expected = [...GITHUB_HOSTS, ...PROVIDER_HOSTS, ...PACKAGE_REGISTRY_HOSTS];
+        expect([...DEFAULT_ALLOWLIST]).toEqual(expected);
+    });
+    it("covers the critical host categories the runtime depends on", () => {
+        // GitHub apex covers api.github.com, codeload.github.com, raw.…
+        expect(GITHUB_HOSTS).toContain("github.com");
+        // Provider hosts — the docker backend dials these from inside the
+        // sandbox container.
+        expect(PROVIDER_HOSTS).toContain("openai.com");
+        expect(PROVIDER_HOSTS).toContain("anthropic.com");
+        // npm — covers registry.npmjs.org, auth.npmjs.org, www.npmjs.org.
+        expect(PACKAGE_REGISTRY_HOSTS).toContain("npmjs.org");
+    });
+    it("entries are bare hostnames (no leading dot, no wildcard prefix)", () => {
+        // Convention is "every entry matches apex+subdomains" — see file
+        // docstring. The config generator emits the right syntax for each
+        // backend. If someone tries to write `.github.com` or `*.github.com`
+        // here, fail fast.
+        for (const host of DEFAULT_ALLOWLIST) {
+            expect(host).toMatch(/^[A-Za-z0-9][A-Za-z0-9.-]*[A-Za-z0-9]$/);
+            expect(host.startsWith(".")).toBe(false);
+            expect(host.includes("*")).toBe(false);
+        }
+    });
+    it("ALLOW_ALL_SENTINEL is the wildcard string the gondolin matcher honours", () => {
+        expect(ALLOW_ALL_SENTINEL).toBe("*");
+    });
+    it("normalizes and merges extra allowlist hosts", () => {
+        expect(normalizeAllowlistHost("https://Collector.Example.com:4318/v1/traces")).toBe("collector.example.com");
+        expect(normalizeAllowlistHost("169.254.169.254")).toBeNull();
+        expect(mergeAllowlist(["github.com"], ["GitHub.com", "otel.example.com"])).toEqual([
+            "github.com",
+            "otel.example.com",
+        ]);
+    });
+    it("rejects private and internal collector endpoints", () => {
+        for (const host of [
+            "0.0.0.0",
+            "127.0.0.1",
+            "10.0.0.4",
+            "172.16.0.1",
+            "192.168.1.10",
+            "http://[::1]:4318",
+            "http://[fe80::1]:4318",
+            "http://[fd00::1]:4318",
+            "http://[::ffff:127.0.0.1]:4318",
+            "metadata.google.internal",
+            "localhost",
+        ]) {
+            expect(normalizeAllowlistHost(host), host).toBeNull();
+        }
+    });
+});
+//# sourceMappingURL=egress-allowlist.test.js.map

package/dist/sandbox/egress-allowlist.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"egress-allowlist.test.js","sourceRoot":"","sources":["../../src/sandbox/egress-allowlist.test.ts"],"names":[],"mappings":"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"}

package/dist/sandbox/egress-firewall-config.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Egress firewall config generation for the docker sandbox backend.
+ *
+ * Architecture (replaces the earlier tinyproxy CONNECT-proxy):
+ *
+ *   sandbox-egress (internal: true, subnet 172.30.0.0/24)
+ *     ├─ sandbox containers              (docker run --dns <coredns-ip>)
+ *     ├─ coredns-strict   172.30.0.10    → returns nginx-strict IP for allowlist hosts, NXDOMAIN otherwise
+ *     ├─ coredns-open     172.30.0.11    → returns nginx-open IP for ANY hostname (except hard-deny SSRF magnets)
+ *     ├─ nginx-egress-strict 172.30.0.20 → ssl_preread, SNI must match allowlist; tunnel upstream via proxy-egress
+ *     └─ nginx-egress-open   172.30.0.21 → tunnel any SNI; client DNS already gated through coredns-open
+ *
+ * Why this instead of a forward proxy (tinyproxy/smokescreen): clients
+ * inside the sandbox (especially the OpenAI/Anthropic SDKs that build
+ * their own undici dispatchers) don't honour HTTP_PROXY / HTTPS_PROXY.
+ * Forcing them to cooperate is a losing battle. By spoofing DNS and
+ * peeking SNI at the network layer, the sandbox sees no proxy at all —
+ * it dials `api.openai.com:443` directly. The firewall intercepts the
+ * connection by virtue of being the only thing the spoofed DNS pointed
+ * at.
+ *
+ * Inspired by Vercel Sandbox's egress firewall (SNI peeking, no env
+ * vars). Their implementation also handles TLS termination for
+ * credentials brokering and Postgres STARTTLS — we don't (yet).
+ *
+ * ## Wildcards
+ *
+ * Entries in egress-allowlist.ts with a leading dot (`".github.com"`)
+ * match the apex plus every subdomain. nginx's `map` directive supports
+ * this syntax natively. CoreDNS uses the `template` plugin with an
+ * anchored regex to do the same.
+ */
+/** Fixed IPs assigned in docker-compose.yml so `--dns` and nginx upstreams can reference them. */
+export declare const COREDNS_STRICT_IP = "172.30.0.10";
+export declare const COREDNS_OPEN_IP = "172.30.0.11";
+export declare const NGINX_STRICT_IP = "172.30.0.20";
+export declare const NGINX_OPEN_IP = "172.30.0.21";
+/**
+ * Static IP of the in-network OTEL collector (docker backend). Sandboxes
+ * dial it directly by IP — it lives on `sandbox-egress` alongside the
+ * firewalls, so no DNS lookup (and therefore no coredns allowlist entry)
+ * is involved. The collector is the ONLY OTLP endpoint a sandbox ever
+ * sees: it terminates the sandbox's telemetry and re-exports to the real
+ * backend over `proxy-egress` using credentials that stay host-side. This
+ * is why the strict SNI firewall no longer needs to know about collector
+ * hosts or non-443 ports — that hop happens on the trusted outbound leg,
+ * not through `ssl_preread`.
+ */
+export declare const OTEL_COLLECTOR_IP = "172.30.0.30";
+/** OTLP/HTTP + OTLP/gRPC receiver ports the in-network collector listens on. */
+export declare const OTEL_COLLECTOR_OTLP_HTTP_PORT = 4318;
+export declare const OTEL_COLLECTOR_OTLP_GRPC_PORT = 4317;
+/** Endpoint a docker sandbox is told to export OTLP to (HTTP/protobuf). */
+export declare const OTEL_COLLECTOR_SANDBOX_ENDPOINT = "http://172.30.0.30:4318";
+/**
+ * UID the `otel/opentelemetry-collector` image runs as (its Dockerfile
+ * `USER`). The collector reads the OTLP config (which can hold backend auth
+ * headers) as this non-root user. To let it read a mode-0600 file from the
+ * shared volume WITHOUT running as root or making the secret world-readable,
+ * the harness's own `lastlight` user is pinned to this same UID (see the
+ * Dockerfile `useradd -u`), so the collector reads files it wrote as their
+ * owner. The Dockerfile and the collector image tag in docker-compose.yml
+ * must move together if a future image bumps the UID — enforced by a test in
+ * docker-compose.test.ts.
+ */
+export declare const OTEL_COLLECTOR_UID = 10001;
+/** Subnet for sandbox-egress. Compose declares this CIDR so the IPs above are valid. */
+export declare const SANDBOX_EGRESS_SUBNET = "172.30.0.0/24";
+/** Build the strict nginx.conf — ssl_preread + map on SNI allowlist. */
+export declare function renderNginxStrictConf(): string;
+/** Build the open nginx.conf — no SNI allowlist, just tunnel whatever DNS pointed at. */
+export declare function renderNginxOpenConf(): string;
+/** Build the Corefile that returns the strict nginx IP for allowlist hosts. */
+export declare function renderCorefileStrict(): string;
+/** Build the Corefile that returns the open nginx IP for ANY hostname (except hard-denies). */
+export declare function renderCorefileOpen(): string;
+/**
+ * Write the four config files under $STATE_DIR/proxy/. Idempotent.
+ * Returns the directory path. Compose bind-mounts this dir into the
+ * coredns + nginx containers read-only.
+ */
+export declare function writeEgressFirewallConfigs(stateDir: string): string;
+/**
+ * Render the in-network OTEL collector config (docker backend).
+ *
+ * `opts.active` gates whether the collector forwards anywhere. It MUST track
+ * the harness's effective `otel.enabled && otel.forwardToSandbox` — when
+ * false, every pipeline is wired to a `debug` exporter (drops data) and NO
+ * backend endpoint or credential is emitted, even if `OTEL_EXPORTER_OTLP_*`
+ * env vars are present. This is the security floor: the collector listens on
+ * a static IP that sandboxes can reach, so if forwarding weren't gated, a
+ * sandbox could POST directly to it and exfil to the real backend regardless
+ * of the documented `LASTLIGHT_OTEL_ENABLED` / `FORWARD_TO_SANDBOX` opt-outs.
+ *
+ * When active, the collector re-exports to the REAL backend — the standard
+ * `OTEL_EXPORTER_OTLP_ENDPOINT` / `OTEL_EXPORTER_OTLP_HEADERS` plus their
+ * per-signal `OTEL_EXPORTER_OTLP_<SIGNAL>_ENDPOINT` / `_HEADERS` overrides,
+ * resolved with the spec's precedence. Each signal gets its own exporter so
+ * a split traces/metrics/logs setup is routed correctly rather than all
+ * collapsing onto whichever endpoint won a fallback chain. Those credentials
+ * live here, in a file on the host mounted read-only into the collector, and
+ * are NEVER forwarded into an untrusted sandbox. The sandbox can only
+ * influence span *content* sent to the harness's own fixed backend — it
+ * cannot redirect where the collector exports, so this adds no SSRF/exfil
+ * surface.
+ *
+ * A signal with no configured endpoint (neither specific nor generic) is
+ * likewise wired to `debug` so the collector still boots cleanly and accepts
+ * connections — sandboxes simply never send what isn't routed.
+ */
+export declare function renderOtelCollectorConfig(opts: {
+    active: boolean;
+    env?: NodeJS.ProcessEnv;
+}): string;
+/**
+ * Write the in-network collector config to $STATE_DIR/proxy/otel-collector.yaml.
+ * Mode 0600 — it can contain backend auth headers. Called at harness boot
+ * (and by the compose `egress-init` one-shot) so the file exists before the
+ * `otel-collector` service reads it. `opts.active` gates forwarding — see
+ * `renderOtelCollectorConfig`. The harness passes its parsed
+ * `otel.enabled && otel.forwardToSandbox`; the env-only callers compute it
+ * via `otelForwardActiveFromEnv`.
+ */
+export declare function writeOtelCollectorConfig(stateDir: string, opts: {
+    active: boolean;
+    env?: NodeJS.ProcessEnv;
+}): string;