@namzu/sandbox 1.1.0 → 2.0.1

package/src/backends/firecracker/__tests__/fixtures/ipc-path.ts

@@ -0,0 +1,31 @@
+import { randomUUID } from 'node:crypto'
+import { join } from 'node:path'
+
+/**
+ * A local IPC address Node can actually `listen()` on, for the current OS.
+ *
+ * These suites bind a loopback agent over a Unix domain socket in a temp
+ * directory. Windows supports `AF_UNIX` at the OS level, but Node's `net`
+ * server does not bind filesystem sockets there — it wants a **named
+ * pipe**, so every one of these tests failed with
+ * `listen EACCES: permission denied …\agent.sock` and the whole
+ * `@namzu/sandbox` suite has been red for Windows contributors.
+ *
+ * The transport under test is address-agnostic: it is handed a path and
+ * connects to it. So the fix belongs in the fixture, not the driver.
+ */
+export function localIpcPath(workDir: string, name = 'agent'): string {
+	if (process.platform === 'win32') {
+		// Named pipes are not filesystem entries, so the temp dir cannot
+		// namespace them — a uuid keeps concurrent test files apart.
+		return `\\\\.\\pipe\\namzu-${name}-${randomUUID()}`
+	}
+	return join(workDir, `${name}.sock`)
+}
+
+/**
+ * True when the socket address lives on disk and can be cleaned up with
+ * the temp directory. Named pipes disappear with the process that owns
+ * them, so there is nothing to unlink.
+ */
+export const IPC_IS_FILESYSTEM_PATH = process.platform !== 'win32'

package/src/backends/firecracker/__tests__/protocol.test.ts

@@ -50,9 +50,6 @@ describe('pickBackend — microvm:self-hosted', () => {
 			backend: {
 				tier: 'microvm',
 				service: 'self-hosted',
-				firecrackerBinary: '/usr/bin/firecracker',
-				kernelImage: '/golden/vmlinux',
-				rootfsImage: '/golden/rootfs.ext4',
 				orchestratorEndpoint: 'https://orchestrator.test',
 				getToken: async () => 'tok',
 				template: 'golden-rev-1',
@@ -63,28 +60,16 @@ describe('pickBackend — microvm:self-hosted', () => {
 		expect(provider.name).toContain('microvm:self-hosted')
 	})
 
-	it('still throws for the legacy local-containerd self-hosted shape (no orchestrator)', () => {
+	it('refuses the shape that reaches no orchestrator', () => {
+		// The control-plane endpoint and its bearer are required now. They
+		// used to be optional beside three REQUIRED fields belonging to a
+		// local-daemon path that was never written, so the only working
+		// configuration had to supply three values nothing reads — and
+		// omitting these two type-checked its way to a runtime throw.
 		expect(() =>
 			createSandboxProvider({
-				backend: {
-					tier: 'microvm',
-					service: 'self-hosted',
-					firecrackerBinary: '/usr/bin/firecracker',
-					kernelImage: '/k',
-					rootfsImage: '/r',
-				},
-			}),
-		).toThrow(SandboxBackendNotImplementedError)
-	})
-
-	it('still throws for microvm:e2b and microvm:fly-machines', () => {
-		expect(() =>
-			createSandboxProvider({ backend: { tier: 'microvm', service: 'e2b', apiKey: 'k' } }),
-		).toThrow(SandboxBackendNotImplementedError)
-		expect(() =>
-			createSandboxProvider({
-				backend: { tier: 'microvm', service: 'fly-machines', apiToken: 't', app: 'a', image: 'i' },
-			}),
+				backend: { tier: 'microvm', service: 'self-hosted' },
+			} as never),
 		).toThrow(SandboxBackendNotImplementedError)
 	})
 })

package/src/backends/firecracker/__tests__/transport.test.ts

@@ -31,6 +31,14 @@ import { VsockAgentTransport } from '../transport.js'
 // require-time. Set the env, then require it through createRequire so
 // each test file gets a fresh module bound to its own workspace dir.
 import { createRequire } from 'node:module'
+import { localIpcPath } from './fixtures/ipc-path.js'
+// The loopback agent under test is the guest-side agent for a Linux microVM:
+// it spawns `/bin/sh` to run commands, and that binary does not exist on
+// Windows. These cases assert behavior the platform cannot produce, so they
+// skip there rather than leaving the suite permanently red for Windows
+// contributors. The socket-address fixture IS platform-correct, so the
+// transport is still exercised wherever it can be.
+const IS_WINDOWS = process.platform === 'win32'
 
 const require_ = createRequire(import.meta.url)
 
@@ -53,7 +61,7 @@ function startAgentServer(connHandler: (s: Socket) => void): Promise<Server> {
 
 beforeEach(() => {
 	workDir = mkdtempSync(join(tmpdir(), 'fc-agent-test-'))
-	sockPath = join(workDir, 'agent.sock')
+	sockPath = localIpcPath(workDir)
 	// Bind the agent's workspace jail to the temp dir BEFORE requiring it.
 	process.env.NAMZU_SANDBOX_WORKSPACE = workDir
 	// The agent's root-normalization filters env on PRESENCE; `= undefined`
@@ -76,7 +84,7 @@ afterEach(async () => {
 	rmSync(workDir, { recursive: true, force: true })
 })
 
-describe('VsockAgentTransport over a unix-socket loopback agent', () => {
+describe.skipIf(IS_WINDOWS)('VsockAgentTransport over a unix-socket loopback agent', () => {
 	it('streams stdout/stderr/result NDJSON from an exec', async () => {
 		server = await startAgentServer(agent.handleConnection)
 		const transport = new VsockAgentTransport({ kind: 'unix', path: sockPath })
@@ -367,7 +375,7 @@ function startMtlsRelayOnPort(agentSockPath: string, port: number): Promise<Rela
 	return startMtlsRelay(agentSockPath, port)
 }
 
-describe('VsockAgentTransport mtls arm over a TLS loopback relay', () => {
+describe.skipIf(IS_WINDOWS)('VsockAgentTransport mtls arm over a TLS loopback relay', () => {
 	let agentServer: Server | undefined
 	let relay: RelayHandle | undefined
 

package/src/backends/firecracker/index.ts

@@ -65,6 +65,21 @@ import type {
 } from './transport.js'
 import { VsockAgentTransport } from './transport.js'
 
+/**
+ * Trim trailing slashes without a regex.
+ *
+ * `/\/+$/` backtracks quadratically on a long run of slashes, and this
+ * value crosses a trust boundary — a host-supplied endpoint on a shared
+ * event loop. The scan is linear and says the same thing.
+ */
+function stripTrailingSlashes(value: string): string {
+	let end = value.length
+	while (end > 0 && value[end - 1] === '/') {
+		end--
+	}
+	return value.slice(0, end)
+}
+
 /**
  * Async callback returning a fresh bearer token for
  * {@link FirecrackerBackendInternalConfig.orchestratorEndpoint}.
@@ -195,7 +210,7 @@ async function orchestratorCall<T>(
 	mtls?: MtlsClientMaterial,
 ): Promise<T | undefined> {
 	const token = await getToken()
-	const url = `${endpoint.replace(/\/+$/, '')}${pathSuffix}`
+	const url = `${stripTrailingSlashes(endpoint)}${pathSuffix}`
 	const payload = body !== undefined ? JSON.stringify(body) : undefined
 	const headers: Record<string, string> = {
 		Authorization: `Bearer ${token}`,
@@ -308,15 +323,17 @@ async function spawnFirecrackerSandbox(
 	options: SandboxBackendOptions,
 ): Promise<Sandbox> {
 	const endpoint = config.orchestratorEndpoint
+	const egressAllowlist = await resolveEgressAllowlist(options)
 	const createBody: OrchestratorCreateRequest = {
 		...(config.template !== undefined ? { template: config.template } : {}),
 		...(config.agentSnapshot !== undefined ? { agentSnapshot: config.agentSnapshot } : {}),
 		...(options.memoryLimitMb !== undefined ? { memoryLimitMb: options.memoryLimitMb } : {}),
 		...(options.maxProcesses !== undefined ? { maxProcesses: options.maxProcesses } : {}),
 		...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
-		...(resolveEgressAllowlist(options) !== undefined
-			? { egressAllowlist: resolveEgressAllowlist(options) }
-			: {}),
+		// Resolved once. It used to be called twice — harmless for the pure
+		// kinds, and once the resolver variant actually runs its callback,
+		// twice means two round-trips and two chances to disagree.
+		...(egressAllowlist !== undefined ? { egressAllowlist } : {}),
 	}
 
 	let created: OrchestratorCreateResponse | undefined
@@ -404,6 +421,16 @@ async function spawnFirecrackerSandbox(
 			argv?: string[],
 			opts?: SandboxExecOptions,
 		): Promise<SandboxExecResult> {
+			// `opts.signal` is deliberately not forwarded, and the reason is
+			// worth writing down because the obvious "fix" is worse than the
+			// gap. There is no cancel op on this wire — the guest agent takes
+			// an execute frame and answers when the command is done. Aborting
+			// the socket here would abandon the WAIT while the process keeps
+			// running inside the microVM, which is verbatim the failure
+			// `SandboxExecOptions.signal` exists to prevent, except it would
+			// then look honoured. Honouring it means a cancel op in the guest
+			// protocol; until then, ignoring it is the truthful behaviour the
+			// option's own contract allows.
 			status = 'busy'
 			try {
 				return await transport.execute({
@@ -463,17 +490,53 @@ async function spawnFirecrackerSandbox(
 // Helpers
 // ---------------------------------------------------------------------------
 
-function resolveEgressAllowlist(options: SandboxBackendOptions): readonly string[] | undefined {
+/**
+ * Materialise an egress policy into the allowlist the orchestrator turns
+ * into firewall rules.
+ *
+ * Omitting the field means "no allowlist to apply", which the orchestrator
+ * reads as unrestricted. That makes omission the encoding for `allow-all`
+ * and ONLY for `allow-all`.
+ *
+ * `resolver` used to be omitted too, so two opposite intentions shared one
+ * encoding and the tenant-scoped allowlist the variant exists for was
+ * silently absent — with the callback that would have produced it never
+ * called anywhere in the repo. Whichever way the orchestrator reads an
+ * omitted field, one of the two variants was always mis-enforced, and the
+ * one that failed open was the one whose entire purpose is restriction.
+ *
+ * The switch is exhaustive on purpose: a new variant should fail to
+ * compile here rather than fall through to "unrestricted".
+ */
+export async function resolveEgressAllowlist(
+	options: SandboxBackendOptions,
+): Promise<readonly string[] | undefined> {
 	const egress = options.egress
 	if (!egress) return undefined
-	if (egress.kind === 'static') return egress.allowedHosts
-	// `deny-all` → empty allowlist (explicit). `allow-all` / `resolver`
-	// are resolved by the host before create when they apply; the
-	// backend forwards only the static, already-resolved shape. A
-	// resolver-shaped policy is the Vandal lifecycle's job to resolve
-	// upstream and pass as `static`.
-	if (egress.kind === 'deny-all') return []
-	return undefined
+
+	switch (egress.kind) {
+		case 'allow-all':
+			// The one intent omission is allowed to mean.
+			return undefined
+		case 'deny-all':
+			// Explicitly empty, not absent.
+			return []
+		case 'static':
+			return egress.allowedHosts
+		case 'resolver': {
+			// The callback exists to produce this list. Calling it is the
+			// whole feature; an empty result is a real deny-all and travels
+			// as one rather than collapsing back to omission.
+			const resolved = await egress.resolve()
+			return resolved
+		}
+		default: {
+			const exhaustive: never = egress
+			throw new Error(
+				`Unhandled egress policy kind: ${JSON.stringify(exhaustive)}. Refusing rather than defaulting to unrestricted network access.`,
+			)
+		}
+	}
 }
 
 /**

package/src/egress/__tests__/allowlist.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'vitest'
+
+import { isHostAllowed, splitAuthority } from '../allowlist.js'
+
+/**
+ * The part that decides whether untrusted code reaches the network.
+ *
+ * Substring matching is the obvious implementation and it is a hole: an
+ * entry of `example.com` would admit `example.com.attacker.net`, a domain
+ * the attacker owns. Plain suffix matching has the same hole without a
+ * leading dot — `notexample.com` ends with `example.com`.
+ */
+
+describe('an exact host entry', () => {
+	it('matches only that host', () => {
+		expect(isHostAllowed('api.example.com', ['api.example.com'])).toBe(true)
+		expect(isHostAllowed('other.example.com', ['api.example.com'])).toBe(false)
+	})
+
+	it('does not match a host that merely contains it', () => {
+		// The whole reason this is not `includes`.
+		expect(isHostAllowed('api.example.com.attacker.net', ['api.example.com'])).toBe(false)
+	})
+
+	it('does not match a prefix of itself', () => {
+		expect(isHostAllowed('example.com', ['api.example.com'])).toBe(false)
+	})
+})
+
+describe('a wildcard entry', () => {
+	it('matches subdomains', () => {
+		expect(isHostAllowed('api.example.com', ['.example.com'])).toBe(true)
+		expect(isHostAllowed('deep.api.example.com', ['.example.com'])).toBe(true)
+	})
+
+	it('matches the apex too', () => {
+		// An author writing the wildcard form means the site; admitting
+		// `www.example.com` but not `example.com` reads as a bug.
+		expect(isHostAllowed('example.com', ['.example.com'])).toBe(true)
+	})
+
+	it('does not match a domain that merely ends with the same letters', () => {
+		// This is why the leading dot is required rather than optional.
+		expect(isHostAllowed('notexample.com', ['.example.com'])).toBe(false)
+		expect(isHostAllowed('evilexample.com', ['.example.com'])).toBe(false)
+	})
+
+	it('does not match a domain that only contains it', () => {
+		expect(isHostAllowed('example.com.attacker.net', ['.example.com'])).toBe(false)
+	})
+})
+
+describe('normalisation', () => {
+	it('ignores case, because DNS does', () => {
+		expect(isHostAllowed('API.Example.COM', ['api.example.com'])).toBe(true)
+	})
+
+	it('ignores a trailing dot, which is the same name', () => {
+		// An allowlist that treats `example.com.` as different is bypassable
+		// by typing the host differently.
+		expect(isHostAllowed('example.com.', ['example.com'])).toBe(true)
+	})
+
+	it('ignores surrounding whitespace in an entry', () => {
+		expect(isHostAllowed('example.com', ['  example.com  '])).toBe(true)
+	})
+})
+
+describe('an empty allowlist', () => {
+	it('denies everything', () => {
+		expect(isHostAllowed('example.com', [])).toBe(false)
+	})
+
+	it('is not satisfied by an empty entry', () => {
+		// `''` must not become a wildcard through some string coincidence.
+		expect(isHostAllowed('example.com', ['', '   '])).toBe(false)
+	})
+
+	it('denies an empty host', () => {
+		expect(isHostAllowed('', ['example.com'])).toBe(false)
+	})
+})
+
+describe('splitting an authority', () => {
+	it('separates host from port', () => {
+		expect(splitAuthority('example.com:8443')).toEqual({ host: 'example.com', port: 8443 })
+	})
+
+	it('leaves a bare host alone', () => {
+		expect(splitAuthority('example.com')).toEqual({ host: 'example.com' })
+	})
+
+	it('handles a bracketed IPv6 literal', () => {
+		// A `split(':')` would shred this, and the allowlist would then be
+		// matching against a fragment.
+		expect(splitAuthority('[::1]:9000')).toEqual({ host: '::1', port: 9000 })
+		expect(splitAuthority('[2001:db8::1]')).toEqual({ host: '2001:db8::1' })
+	})
+
+	it('keeps the whole value when the port is not a number', () => {
+		expect(splitAuthority('example.com:notaport')).toEqual({ host: 'example.com:notaport' })
+	})
+})

package/src/egress/__tests__/proxy.test.ts

@@ -0,0 +1,212 @@
+import { createServer, request as nodeRequest } from 'node:http'
+import type { IncomingMessage, Server, ServerResponse } from 'node:http'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import { EgressProxy } from '../proxy.js'
+import type { RunningEgressProxy } from '../proxy.js'
+
+/**
+ * Until this existed, an egress policy could be declared and only two of
+ * its four shapes could be honoured anywhere: the container backend
+ * refused a host allowlist outright because it had no proxy to filter
+ * through. `deny-all` and `allow-all` were the whole spectrum — all or
+ * nothing.
+ *
+ * It also settles where credentials live. Any token the agent needed to
+ * reach an allowed host had to be INSIDE the sandbox, in the environment,
+ * readable by the untrusted code it is meant to be isolated from — via
+ * `/proc/self/environ`, or via a prompt injection that exfiltrates it over
+ * the very egress the policy permits.
+ */
+
+/** A stand-in upstream that reports what it was sent. */
+function upstream(): Promise<{ server: Server; port: number; seen: IncomingMessage[] }> {
+	const seen: IncomingMessage[] = []
+	const server = createServer((req: IncomingMessage, res: ServerResponse) => {
+		seen.push(req)
+		res.writeHead(200, { 'content-type': 'text/plain' })
+		res.end('upstream ok')
+	})
+	return new Promise((resolve) => {
+		server.listen(0, '127.0.0.1', () => {
+			const address = server.address()
+			const port = typeof address === 'object' && address !== null ? address.port : 0
+			resolve({ server, port, seen })
+		})
+	})
+}
+
+/**
+ * Issue a request THROUGH the proxy, the way a proxied client does: the
+ * absolute URL goes in the request line.
+ *
+ * `fetch` cannot express this — it owns the `Host` header and refuses an
+ * override, so a request built with it names the proxy as its own target.
+ * The first version of this helper did exactly that, and the proxy
+ * forwarded to itself and hung. That hang is now a 400, and this helper
+ * speaks the protocol properly.
+ */
+function viaProxy(
+	proxy: RunningEgressProxy,
+	target: string,
+	init: { headers?: Record<string, string> } = {},
+): Promise<{ status: number; body: string }> {
+	const proxyUrl = new URL(proxy.url)
+	return new Promise((resolve, reject) => {
+		const req = nodeRequest(
+			{
+				host: proxyUrl.hostname,
+				port: Number(proxyUrl.port),
+				method: 'GET',
+				// Absolute-URI form: what distinguishes a proxied request.
+				path: target,
+				headers: init.headers ?? {},
+			},
+			(res) => {
+				let body = ''
+				res.setEncoding('utf-8')
+				res.on('data', (chunk: string) => {
+					body += chunk
+				})
+				res.on('end', () => resolve({ status: res.statusCode ?? 0, body }))
+			},
+		)
+		req.on('error', reject)
+		req.end()
+	})
+}
+
+describe('the boundary', () => {
+	let proxy: RunningEgressProxy
+	let allowed: string[]
+	let denied: Array<{ host: string; reason: string }>
+	let target: Awaited<ReturnType<typeof upstream>>
+
+	beforeEach(async () => {
+		target = await upstream()
+		allowed = ['127.0.0.1']
+		denied = []
+		proxy = await new EgressProxy({
+			allowedHosts: async () => allowed,
+			// The stand-in upstream speaks plain HTTP.
+			upgradeToHttps: false,
+			onDenied: (host, reason) => denied.push({ host, reason }),
+		}).listen()
+	})
+
+	afterEach(async () => {
+		await proxy.close()
+		await new Promise<void>((resolve) => target.server.close(() => resolve()))
+	})
+
+	it('lets an allowed host through', async () => {
+		const res = await viaProxy(proxy, `http://127.0.0.1:${target.port}/thing`)
+		expect(res.status).toBe(200)
+		expect(res.body).toBe('upstream ok')
+	})
+
+	it('refuses a host that is not on the list', async () => {
+		allowed = ['example.com']
+		const res = await viaProxy(proxy, `http://127.0.0.1:${target.port}/thing`)
+
+		expect(res.status).toBe(403)
+		// Never reached the upstream at all — the refusal is the point, not
+		// the response code.
+		expect(target.seen).toHaveLength(0)
+	})
+
+	it('names the host it refused', async () => {
+		allowed = []
+		const res = await viaProxy(proxy, `http://127.0.0.1:${target.port}/thing`)
+
+		// An agent that cannot tell "not permitted" from "network down"
+		// retries forever, and a human debugging it has nothing to go on.
+		expect(res.body).toContain('127.0.0.1')
+		expect(denied[0]?.host).toBe('127.0.0.1')
+	})
+
+	it('denies when the policy cannot be read', async () => {
+		// An allowlist that fails open is not an allowlist.
+		const failing = await new EgressProxy({
+			allowedHosts: async () => {
+				throw new Error('policy service unavailable')
+			},
+			upgradeToHttps: false,
+		}).listen()
+
+		try {
+			const res = await viaProxy(failing, `http://127.0.0.1:${target.port}/thing`)
+			expect(res.status).toBe(403)
+		} finally {
+			await failing.close()
+		}
+	})
+
+	it('re-reads the policy per request, so a rotating allowlist is honoured', async () => {
+		allowed = []
+		expect((await viaProxy(proxy, `http://127.0.0.1:${target.port}/a`)).status).toBe(403)
+
+		allowed = ['127.0.0.1']
+		expect((await viaProxy(proxy, `http://127.0.0.1:${target.port}/b`)).status).toBe(200)
+	})
+
+	it('can be narrowed on a live proxy', async () => {
+		// "Clone with a token, then drop to deny-all before running
+		// untrusted build scripts" was not expressible at all: the policy
+		// was frozen at provider construction.
+		expect((await viaProxy(proxy, `http://127.0.0.1:${target.port}/a`)).status).toBe(200)
+
+		proxy.setAllowedHosts(async () => [])
+		expect((await viaProxy(proxy, `http://127.0.0.1:${target.port}/b`)).status).toBe(403)
+	})
+})
+
+describe('brokering a credential', () => {
+	let proxy: RunningEgressProxy
+	let target: Awaited<ReturnType<typeof upstream>>
+
+	beforeEach(async () => {
+		target = await upstream()
+	})
+
+	afterEach(async () => {
+		await proxy.close()
+		await new Promise<void>((resolve) => target.server.close(() => resolve()))
+	})
+
+	const withCredentials = async (host: string) => {
+		proxy = await new EgressProxy({
+			allowedHosts: async () => ['127.0.0.1'],
+			upgradeToHttps: false,
+			credentials: [{ host, header: 'authorization', value: 'Bearer real-secret' }],
+		}).listen()
+		return proxy
+	}
+
+	it('stamps the real value on at the boundary', async () => {
+		const p = await withCredentials('127.0.0.1')
+		await viaProxy(p, `http://127.0.0.1:${target.port}/thing`)
+
+		// The token never entered the sandbox — a placeholder did, and the
+		// value was applied here.
+		expect(target.seen[0]?.headers.authorization).toBe('Bearer real-secret')
+	})
+
+	it('sends it only to the host it belongs to', async () => {
+		// A credential attached to every request is a credential handed to
+		// whichever host the agent was talked into contacting.
+		const p = await withCredentials('other.example.com')
+		await viaProxy(p, `http://127.0.0.1:${target.port}/thing`)
+
+		expect(target.seen[0]?.headers.authorization).toBeUndefined()
+	})
+
+	it('does not forward the hop-by-hop proxy header onward', async () => {
+		const p = await withCredentials('127.0.0.1')
+		await viaProxy(p, `http://127.0.0.1:${target.port}/thing`, {
+			headers: { 'proxy-authorization': 'Basic should-not-travel' },
+		})
+
+		expect(target.seen[0]?.headers['proxy-authorization']).toBeUndefined()
+	})
+})

package/src/egress/allowlist.ts

@@ -0,0 +1,82 @@
+/**
+ * Host matching for an egress allowlist.
+ *
+ * Kept apart from the proxy because this is the part that decides whether
+ * untrusted code reaches the network, and it has to be readable on its own
+ * and testable without opening a socket.
+ */
+
+/**
+ * Whether `host` is covered by `allowed`.
+ *
+ * Two forms, and only two:
+ *
+ *  - `api.example.com` — that exact host.
+ *  - `.example.com` — that domain and any subdomain of it.
+ *
+ * Substring matching is deliberately NOT one of them. `host.includes(entry)`
+ * is the obvious implementation and it is a hole: an allowlist entry of
+ * `example.com` would admit `example.com.attacker.net`, which is a domain
+ * the attacker owns. Suffix matching has the same hole without the leading
+ * dot — `notexample.com` ends with `example.com` — which is why the
+ * wildcard form requires it.
+ *
+ * Comparison is case-insensitive and ignores a trailing dot, because DNS
+ * treats `Example.COM.` and `example.com` as the same name and an allowlist
+ * that does not would be bypassable by typing the host differently.
+ */
+export function isHostAllowed(host: string, allowed: readonly string[]): boolean {
+	const target = normalizeHost(host)
+	if (target.length === 0) return false
+
+	for (const raw of allowed) {
+		const entry = normalizeHost(raw)
+		if (entry.length === 0) continue
+
+		if (entry.startsWith('.')) {
+			// `.example.com` covers `example.com` itself and any subdomain.
+			// Covering the apex matters: an allowlist author writing the
+			// wildcard form means the site, and a policy that admits
+			// `www.example.com` but not `example.com` reads as a bug.
+			const domain = entry.slice(1)
+			if (target === domain || target.endsWith(entry)) return true
+			continue
+		}
+
+		if (target === entry) return true
+	}
+
+	return false
+}
+
+/** Lowercase, trailing-dot-free, whitespace-free. */
+function normalizeHost(host: string): string {
+	return host.trim().toLowerCase().replace(/\.$/, '')
+}
+
+/**
+ * Split an authority into host and port.
+ *
+ * A CONNECT target and a `Host` header both carry `host:port`, and the
+ * allowlist is about the HOST — matching the whole authority would make an
+ * entry admit one port and silently refuse the same site on another.
+ * IPv6 literals are bracketed, which is why this is not a `split(':')`.
+ */
+export function splitAuthority(authority: string): { host: string; port?: number } {
+	const value = authority.trim()
+
+	if (value.startsWith('[')) {
+		const close = value.indexOf(']')
+		if (close < 0) return { host: value }
+		const host = value.slice(1, close)
+		const rest = value.slice(close + 1)
+		const port = rest.startsWith(':') ? Number(rest.slice(1)) : undefined
+		return port !== undefined && Number.isInteger(port) ? { host, port } : { host }
+	}
+
+	const colon = value.lastIndexOf(':')
+	if (colon < 0) return { host: value }
+	const port = Number(value.slice(colon + 1))
+	if (!Number.isInteger(port)) return { host: value }
+	return { host: value.slice(0, colon), port }
+}

package/src/egress/index.ts

@@ -0,0 +1,7 @@
+export { isHostAllowed, splitAuthority } from './allowlist.js'
+export { EgressProxy } from './proxy.js'
+export type {
+	BrokeredCredential,
+	EgressProxyOptions,
+	RunningEgressProxy,
+} from './proxy.js'