@torkbot/sandbox 0.3.0 → 0.4.0

package/README.md

@@ -17,7 +17,7 @@ const workspaceFs = fs.memory({
 });
 
 const sandbox = defineSandbox({
-  rootfs: rootfs.builtIn("alpine:3.20"),
+  rootfs: rootfs.builtIn("alpine:3.23"),
   resources: {
     cpus: 2,
     memoryMiB: 2048,
@@ -53,7 +53,7 @@ import {
 const workspaceFs = fs.memory();
 
 const sandbox = defineSandbox({
-  rootfs: rootfs.builtIn("alpine:3.20"),
+  rootfs: rootfs.builtIn("alpine:3.23"),
 });
 
 await using lane = await sandbox.boot({
@@ -79,10 +79,68 @@ The public API is split into three layers:
 - `lane.exec(...)` runs buffered work inside the booted instance.
 
 Expensive artifact preparation is intentionally outside `boot()`.
-`rootfs.builtIn("alpine:3.20")` selects a built-in rootfs artifact that must
+`rootfs.builtIn("alpine:3.23")` selects a built-in rootfs artifact that must
 already be installed with Sandbox. It does not pull an image or build a rootfs
 at runtime.
 
+## Durable, Policy-Controlled Instances
+
+Sandbox composes durable rootfs mutation with explicit network policy. In this
+example, dirty COW blocks are synchronized to blob storage, public HTTP(S)
+egress is allowed, and only GitHub API requests receive an installation token:
+
+```ts
+import {
+  defineSandbox,
+  network,
+  rootfs,
+  type SandboxBlockStore,
+} from "@torkbot/sandbox";
+
+const writableRootfs: SandboxBlockStore = new BlobSynchronizedCowBlockStore({
+  bucket: "sandbox-rootfs-overlays",
+  keyPrefix: "lanes/github-worker",
+});
+
+const githubTokens = new GitHubInstallationTokenService({
+  installationId: 123456,
+});
+
+const sandbox = defineSandbox({
+  rootfs: rootfs.cow({
+    base: rootfs.builtIn("alpine:3.23"),
+    writable: writableRootfs,
+  }),
+  resources: {
+    cpus: 4,
+    memoryMiB: 4096,
+  },
+  network: network.policy(async (conn) => {
+    if (conn.transport === "udp" && conn.dst.port === 53) {
+      conn.accept();
+      return;
+    }
+    if (conn.transport === "tcp" && conn.dst.port === 443) {
+      conn.acceptHttp(async (request) => {
+        if (request.destination.hostname !== "api.github.com") return;
+        request.headers.set(
+          "authorization",
+          `Bearer ${await githubTokens.tokenForRequest(request)}`,
+        );
+      });
+      return;
+    }
+  }),
+});
+
+await using lane = await sandbox.boot({ cwd: "/workspace" });
+
+await lane.exec("sh", [
+  "-lc",
+  "apk add --no-cache git curl && curl -fsSL https://api.github.com/user",
+]);
+```
+
 ## API Overview
 
 ### Configuration
@@ -102,7 +160,7 @@ type SandboxDefinition = {
 the read-only built-in catalog:
 
 ```ts
-rootfs.builtIn("alpine:3.20");
+rootfs.builtIn("alpine:3.23");
 ```
 
 `resources` controls the VM shape used by every instance booted from the
@@ -110,7 +168,7 @@ definition. Omitted values use Sandbox defaults.
 
 ```ts
 defineSandbox({
-  rootfs: rootfs.builtIn("alpine:3.20"),
+  rootfs: rootfs.builtIn("alpine:3.23"),
   resources: {
     cpus: 4,
     memoryMiB: 4096,
@@ -120,14 +178,15 @@ defineSandbox({
 
 Use `rootfs.cow(...)` when rootfs mutations should persist. The sandbox library
 owns the COW block-device contract; user-space owns the block store's
-durability, compression, migration, and checkpoint policy. Built-in rootfs
-packages include a read-only EROFS image for normal boots and a writable ext4
-image used as the COW base.
+durability, migration, and checkpoint policy. Built-in rootfs packages include
+one compressed QCOW2 image with an ext4 guest filesystem. `rootfs.builtIn(...)`
+mounts that image read-only in the guest; `rootfs.cow(...)` mounts the same base
+read-write through the host COW block store.
 
 ```ts
 defineSandbox({
   rootfs: rootfs.cow({
-    base: rootfs.builtIn("alpine:3.20"),
+    base: rootfs.builtIn("alpine:3.23"),
     writable: laneBlockStore,
   }),
 });
@@ -169,33 +228,65 @@ connection requests and grants only the traffic it explicitly allows:
 
 ```ts
 const policy = network.policy(async (conn) => {
-  if (conn.host === "registry.npmjs.org") {
-    conn.allowHttp();
+  if (conn.transport === "tcp" && conn.dst.isPublicInternet() && conn.dst.port === 443) {
+    conn.accept();
   }
 });
 ```
 
-`conn.allow()` grants HTTP(S)-classified traffic without request middleware.
-`conn.allowHttp(...)` grants HTTP(S)-classified traffic and can apply request
-middleware:
+`conn.accept()` grants the observed connection or flow at the transport layer.
+It does not classify the application protocol, does not enter HTTP middleware,
+and does not MITM TLS. `conn.acceptHttp(...)` is TCP-only and explicitly opts
+the flow into Sandbox's HTTP-family enforcement path. If the accepted flow is
+not actually HTTP or HTTPS, it fails closed.
 
 ```ts
 const policy = network.policy(async (conn) => {
-  if (conn.host !== "api.example.com") return;
-
-  conn.allowHttp(async (request) => {
-    request.headers.set(
-      "authorization",
-      `Bearer ${await credentialBroker.authorizationFor(request)}`,
-    );
-  });
+  if (
+    conn.transport === "tcp" &&
+    conn.dst.isPublicInternet() &&
+    conn.dst.port === 443
+  ) {
+    conn.acceptHttp(async (request) => {
+      if (request.destination.hostname !== "api.example.com") return;
+      request.headers.set(
+        "authorization",
+        `Bearer ${await credentialBroker.authorizationFor(request)}`,
+      );
+    });
+  }
 });
 ```
 
+Every TCP and UDP policy request carries source and destination IP-layer
+endpoints:
+
+```ts
+conn.src.ip;
+conn.src.port;
+conn.dst.ip;
+conn.dst.port;
+```
+
+Endpoint helpers classify logical address ranges without relying on hostnames:
+`isLoopback()`, `isPrivate()`, `isLinkLocal()`, `isMulticast()`,
+`isBroadcast()`, `isDocumentation()`, `isReserved()`, and
+`isPublicInternet()`. `transport` is the TCP/UDP discriminator. TCP callbacks
+may also include `conn.signals` metadata such as TLS SNI or ALPN when the
+runtime has explicitly observed it, but Sandbox does not expose a best-effort
+`conn.protocol` classifier.
+
+HTTP middleware receives trusted destination metadata separately from the
+request URL. `request.destination.hostname` is populated only when Sandbox can
+pin the destination IP to trusted connection metadata, such as its own DNS
+answer cache. IP-addressed requests still work under `acceptHttp(...)`, but they
+do not advertise a hostname. Do not use the HTTP `Host` header as authority for
+policy decisions.
+
 Deny remains the default. If the policy callback does not create a grant, the
-connection is blocked. The `NetworkGrant` returned by `allow()` and
-`allowHttp()` is reserved as the future extension point for instance-local
-state, such as remembering a grant for a time window.
+connection is blocked. The grants returned by `accept()` and `acceptHttp()` are
+reserved as future extension points for instance-local state, such as
+remembering a grant for a time window.
 
 The runtime uses this policy shape to keep the JavaScript boundary explicit.
 Native rules can be added under the same model later without changing the
@@ -262,7 +353,7 @@ Sandbox hides the kernel, init, transport, and host helper behind a small
 TypeScript API:
 
 - The runtime boots a libkrun-backed guest from a prebuilt rootfs artifact:
-  read-only EROFS by default, or writable ext4 when a COW rootfs is used.
+  a compressed QCOW2 image that contains an ext4 guest filesystem.
 - Kernel and init artifacts are implementation details owned by Sandbox.
 - A signed `sandbox-host` helper owns the Node/Rust/libkrun boundary.
 - Guest control traffic uses an implicit fd-backed transport between the host
@@ -274,6 +365,14 @@ TypeScript API:
   decisions and delegate to JavaScript only when a policy callback is required.
 - HTTP request middleware is caller-provided JavaScript, but Sandbox owns the
   interception machinery and certificate plumbing.
+- When HTTP interception is enabled, the host generates the CA material and
+  passes only the public CA certificate to Sandbox init. Init does not generate
+  or manage certificates; the host exposes the supplied CA through an internal
+  read-only virtiofs mount, then init installs it using the selected rootfs'
+  native trust-store mechanism. Built-in rootfs launches use an ephemeral
+  writable COW view for HTTP interception so init can update the guest trust
+  store deterministically. If a rootfs does not provide a supported native
+  trust-store installer, init fails closed.
 
 The intended boundary is that Sandbox knows how to launch, isolate, mount,
 intercept, and enforce. User-space owns artifact selection, filesystem

package/dist/artifacts.d.ts

@@ -1,16 +1,15 @@
 type SandboxTarget = {
     readonly packageName: string;
     readonly hostBinaryName: string;
-    readonly rootfsNames: Record<BuiltInRootfsFormat, string>;
+    readonly rootfsName: string;
     readonly platform: NodeJS.Platform;
     readonly arch: NodeJS.Architecture;
     readonly libc?: "glibc";
 };
-type BuiltInRootfsFormat = "erofs" | "ext4";
 export declare function currentSandboxTarget(): SandboxTarget;
 export declare function hostBinaryPath(): string;
-export declare function builtInRootfsPath(name: "alpine:3.20", format?: BuiltInRootfsFormat): string;
-export declare function builtInRootfsIdentity(name: "alpine:3.20", format: BuiltInRootfsFormat): string;
+export declare function builtInRootfsPath(name: "alpine:3.23"): string;
+export declare function builtInRootfsIdentity(name: "alpine:3.23"): string;
 export declare function rawHostBinaryPath(): string;
 export declare function assertMacosHostIsSigned(path: string): void;
 export declare function macosHostSigningError(path: string): Error | null;

package/dist/artifacts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"AAKA,KAAK,aAAa,GAAG;IACnB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC;IAC1D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,YAAY,CAAC;IACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,KAAK,mBAAmB,GAAG,OAAO,GAAG,MAAM,CAAC;AA0B5C,wBAAgB,oBAAoB,IAAI,aAAa,CAYpD;AAED,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,GAAE,mBAA6B,GAAG,MAAM,CAMpG;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAiB9F;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAG1C;AA2BD,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAuB1D;AAcD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI,CAWhE"}
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"AAKA,KAAK,aAAa,GAAG;IACnB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,YAAY,CAAC;IACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAoBF,wBAAgB,oBAAoB,IAAI,aAAa,CAYpD;AAED,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAM7D;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAiBjE;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAG1C;AA2BD,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAuB1D;AAcD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI,CAWhE"}

package/dist/artifacts.js

@@ -5,20 +5,14 @@ const targets = [
     {
         packageName: "@torkbot/sandbox-darwin-arm64",
         hostBinaryName: "sandbox-host",
-        rootfsNames: {
-            erofs: "rootfs/alpine-3.20.erofs",
-            ext4: "rootfs/alpine-3.20.ext4",
-        },
+        rootfsName: "rootfs/alpine-3.23.qcow2",
         platform: "darwin",
         arch: "arm64",
     },
     {
         packageName: "@torkbot/sandbox-linux-x64-gnu",
         hostBinaryName: "sandbox-host",
-        rootfsNames: {
-            erofs: "rootfs/alpine-3.20.erofs",
-            ext4: "rootfs/alpine-3.20.ext4",
-        },
+        rootfsName: "rootfs/alpine-3.23.qcow2",
         platform: "linux",
         arch: "x64",
         libc: "glibc",
@@ -36,27 +30,27 @@ export function currentSandboxTarget() {
 export function hostBinaryPath() {
     return rawHostBinaryPath();
 }
-export function builtInRootfsPath(name, format = "erofs") {
-    if (name === "alpine:3.20") {
+export function builtInRootfsPath(name) {
+    if (name === "alpine:3.23") {
         const target = currentSandboxTarget();
-        return resolveArtifactPath(target, target.rootfsNames[format]);
+        return resolveArtifactPath(target, target.rootfsName);
     }
     throw new Error(`unsupported built-in rootfs: ${name}`);
 }
-export function builtInRootfsIdentity(name, format) {
-    if (name === "alpine:3.20") {
+export function builtInRootfsIdentity(name) {
+    if (name === "alpine:3.23") {
         const target = currentSandboxTarget();
         const packageVersion = platformPackageVersion(target);
         return [
             "built-in",
             name,
-            format,
+            "qcow2",
             target.platform,
             target.arch,
             target.libc ?? "none",
             target.packageName,
             packageVersion,
-            target.rootfsNames[format],
+            target.rootfsName,
         ].join(":");
     }
     throw new Error(`unsupported built-in rootfs: ${name}`);

package/dist/artifacts.js.map

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

package/dist/host-process.d.ts

@@ -1,13 +1,13 @@
 import { hostBinaryPath } from "./artifacts.ts";
 import type { HostControlChannel } from "./control.ts";
 import type { HostSpawnSandboxOptions } from "./spawn-options.ts";
-import type { InternalSandboxOptions, RegisteredHttpRequestHeadersHook } from "./launch-options.ts";
+import type { InternalSandboxOptions, RegisteredHttpRequestHeadersHook, RegisteredNetworkConnectionHook } from "./launch-options.ts";
 export declare class HostProcessSandboxVm implements HostControlChannel {
     #private;
     readonly hasControlSocket = true;
     readonly packets: AsyncIterable<Uint8Array>;
     private constructor();
-    static spawn(options: InternalSandboxOptions, hostOptions: HostSpawnSandboxOptions, requestHeaderHooks?: Map<string, RegisteredHttpRequestHeadersHook>): Promise<HostProcessSandboxVm>;
+    static spawn(options: InternalSandboxOptions, hostOptions: HostSpawnSandboxOptions, requestHeaderHooks?: Map<string, RegisteredHttpRequestHeadersHook>, networkConnectionHook?: RegisteredNetworkConnectionHook): Promise<HostProcessSandboxVm>;
     writeControlPacket(packet: Uint8Array): void;
     close(): Promise<void>;
     terminateHostForTest(): Promise<void>;

package/dist/host-process.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host-process.d.ts","sourceRoot":"","sources":["../src/host-process.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAAyB,MAAM,gBAAgB,CAAC;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAQlE,OAAO,KAAK,EACV,sBAAsB,EACtB,gCAAgC,EACjC,MAAM,qBAAqB,CAAC;AAI7B,qBAAa,oBAAqB,YAAW,kBAAkB;;IAC7D,QAAQ,CAAC,gBAAgB,QAAQ;IACjC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAiB5C,OAAO,eA6CN;IAED,OAAa,KAAK,CAChB,OAAO,EAAE,sBAAsB,EAC/B,WAAW,EAAE,uBAAuB,EACpC,kBAAkB,GAAE,GAAG,CAAC,MAAM,EAAE,gCAAgC,CAAa,GAC5E,OAAO,CAAC,oBAAoB,CAAC,CAyB/B;IAED,kBAAkB,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAG3C;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CA4B3B;IAEK,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAiB1C;CAqhBF;AA2BD,OAAO,EAAE,cAAc,EAAE,CAAC"}
+{"version":3,"file":"host-process.d.ts","sourceRoot":"","sources":["../src/host-process.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAAyB,MAAM,gBAAgB,CAAC;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAQlE,OAAO,KAAK,EACV,sBAAsB,EACtB,gCAAgC,EAChC,+BAA+B,EAChC,MAAM,qBAAqB,CAAC;AAU7B,qBAAa,oBAAqB,YAAW,kBAAkB;;IAC7D,QAAQ,CAAC,gBAAgB,QAAQ;IACjC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAmB5C,OAAO,eAkDN;IAED,OAAa,KAAK,CAChB,OAAO,EAAE,sBAAsB,EAC/B,WAAW,EAAE,uBAAuB,EACpC,kBAAkB,GAAE,GAAG,CAAC,MAAM,EAAE,gCAAgC,CAAa,EAC7E,qBAAqB,CAAC,EAAE,+BAA+B,GACtD,OAAO,CAAC,oBAAoB,CAAC,CAyB/B;IAED,kBAAkB,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAG3C;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CA4B3B;IAEK,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAiB1C;CAqnBF;AA2BD,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/host-process.js

@@ -16,16 +16,19 @@ export class HostProcessSandboxVm {
     #rootBlockStore;
     #rootBlockStoreContext;
     #requestHeaderHooks;
+    #networkConnectionHook;
+    #httpMiddlewareByFlow = new Map();
     #buffer = new Uint8Array();
     #stderr = "";
     #closed = false;
     #exitError = null;
     #stdinError = null;
-    constructor(child, options, requestHeaderHooks) {
+    constructor(child, options, requestHeaderHooks, networkConnectionHook) {
         this.#child = child;
         this.#options = options;
         this.packets = this.#packets;
         this.#requestHeaderHooks = requestHeaderHooks;
+        this.#networkConnectionHook = networkConnectionHook;
         this.#rootBlockStore = options.rootfs.storage?.blockStore;
         this.#rootBlockStoreContext = options.rootfs.storage?.context;
         for (const mount of options.mounts ?? []) {
@@ -38,6 +41,9 @@ export class HostProcessSandboxVm {
             const text = chunk.toString("utf8").trim();
             if (text.length > 0) {
                 this.#stderr = this.#stderr.length === 0 ? text : `${this.#stderr}\n${text}`;
+                if (process.env.SANDBOX_HOST_STDERR === "1") {
+                    process.stderr.write(chunk);
+                }
             }
         });
         child.stdin.on("error", (error) => {
@@ -59,14 +65,14 @@ export class HostProcessSandboxVm {
             this.#launchReady.close(this.#exitError);
         });
     }
-    static async spawn(options, hostOptions, requestHeaderHooks = new Map()) {
+    static async spawn(options, hostOptions, requestHeaderHooks = new Map(), networkConnectionHook) {
         let vm;
         const hostPath = hostBinaryPath();
         try {
             const child = spawn(hostPath, ["--stdio"], {
                 stdio: ["pipe", "pipe", "pipe"],
             });
-            vm = new HostProcessSandboxVm(child, options, requestHeaderHooks);
+            vm = new HostProcessSandboxVm(child, options, requestHeaderHooks, networkConnectionHook);
             await Promise.race([
                 once(child, "spawn"),
                 once(child, "error").then(([error]) => {
@@ -222,6 +228,8 @@ export class HostProcessSandboxVm {
             && type !== "host.vfs.removexattr"
             && type !== "host.http.requestHeaders"
             && type !== "host.http.activeRequestHeaderHooks"
+            && type !== "host.network.connection"
+            && type !== "host.network.closed"
             && type !== "host.block.list"
             && type !== "host.block.read"
             && type !== "host.block.write"
@@ -234,6 +242,12 @@ export class HostProcessSandboxVm {
         else if (type === "host.http.activeRequestHeaderHooks") {
             void this.#handleActiveRequestHeaderHooks(document);
         }
+        else if (type === "host.network.connection") {
+            void this.#handleNetworkConnection(document);
+        }
+        else if (type === "host.network.closed") {
+            this.#handleNetworkClosed(document);
+        }
         else if (type === "host.block.list"
             || type === "host.block.read"
             || type === "host.block.write"
@@ -245,6 +259,85 @@ export class HostProcessSandboxVm {
         }
         return true;
     }
+    async #handleNetworkConnection(document) {
+        const id = typeof document.id === "string" ? document.id : "";
+        try {
+            const transport = assertNetworkTransport(document.transport);
+            const srcIp = assertString(document.srcIp, "srcIp");
+            const srcPort = assertNumber(document.srcPort, "srcPort");
+            const dstIp = assertString(document.dstIp, "dstIp");
+            const dstPort = assertNumber(document.dstPort, "dstPort");
+            const src = createNetworkEndpoint(srcIp, srcPort);
+            const dst = createNetworkEndpoint(dstIp, dstPort);
+            const decision = { action: "deny" };
+            let httpMiddleware;
+            const accept = () => {
+                decision.action = "accept";
+                return {};
+            };
+            const connection = {
+                transport,
+                src,
+                dst,
+                accept,
+                ...(transport === "tcp"
+                    ? {
+                        acceptHttp(middleware) {
+                            decision.action = "acceptHttp";
+                            httpMiddleware = middleware;
+                            return {};
+                        },
+                    }
+                    : {}),
+            };
+            if (this.#networkConnectionHook?.active === true) {
+                await this.#networkConnectionHook.hook(connection);
+            }
+            if (decision.action === "acceptHttp") {
+                this.#httpMiddlewareByFlow.set(networkFlowKey(src, dst), httpMiddleware);
+            }
+            this.#tryWriteToHost(encodePacket({
+                type: "host.network.response",
+                id,
+                ok: true,
+                action: decision.action,
+            }));
+        }
+        catch (error) {
+            this.#tryWriteToHost(encodePacket({
+                type: "host.network.response",
+                id,
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        }
+    }
+    #handleNetworkClosed(document) {
+        const id = typeof document.id === "string" ? document.id : "";
+        try {
+            const transport = assertNetworkTransport(document.transport);
+            const srcIp = assertString(document.srcIp, "srcIp");
+            const srcPort = assertNumber(document.srcPort, "srcPort");
+            const dstIp = assertString(document.dstIp, "dstIp");
+            const dstPort = assertNumber(document.dstPort, "dstPort");
+            if (transport === "tcp") {
+                this.#httpMiddlewareByFlow.delete(networkFlowKey(createNetworkEndpoint(srcIp, srcPort), createNetworkEndpoint(dstIp, dstPort)));
+            }
+            this.#tryWriteToHost(encodePacket({
+                type: "host.network.response",
+                id,
+                ok: true,
+            }));
+        }
+        catch (error) {
+            this.#tryWriteToHost(encodePacket({
+                type: "host.network.response",
+                id,
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        }
+    }
     async #handleHttpRequestHeaders(document) {
         const id = typeof document.id === "string" ? document.id : "";
         try {
@@ -258,13 +351,15 @@ export class HostProcessSandboxVm {
                 method: assertString(document.method, "method"),
                 headers,
                 destination: {
+                    sourceIp: assertString(document.sourceIp, "sourceIp"),
+                    sourcePort: assertNumber(document.sourcePort, "sourcePort"),
                     originalIp: assertString(document.originalDestinationIp, "originalDestinationIp"),
                     originalPort: assertNumber(document.originalDestinationPort, "originalDestinationPort"),
-                    upstreamIp: assertString(document.upstreamDialIp, "upstreamDialIp"),
-                    upstreamPort: assertNumber(document.upstreamDialPort, "upstreamDialPort"),
+                    hostname: optionalString(document.originalDestinationHostname, "originalDestinationHostname"),
                 },
                 tls: optionalTlsMetadata(document.tls),
             };
+            await this.#httpMiddlewareByFlow.get(networkFlowKey(createNetworkEndpoint(request.destination.sourceIp, request.destination.sourcePort), createNetworkEndpoint(request.destination.originalIp, request.destination.originalPort)))?.(request);
             for (const hookId of hookIds) {
                 const registration = this.#requestHeaderHooks.get(hookId);
                 if (registration?.active === true) {
@@ -743,6 +838,108 @@ function assertProtocol(value) {
     }
     throw new Error("host request protocol must be http/1.1 or h2");
 }
+function assertNetworkTransport(value) {
+    if (value === "tcp" || value === "udp") {
+        return value;
+    }
+    throw new Error("host network request transport must be tcp or udp");
+}
+function createNetworkEndpoint(ip, port) {
+    return {
+        ip,
+        port,
+        isLoopback: () => isLoopbackIp(ip),
+        isPrivate: () => isPrivateIp(ip),
+        isLinkLocal: () => isLinkLocalIp(ip),
+        isMulticast: () => isMulticastIp(ip),
+        isBroadcast: () => ip === "255.255.255.255",
+        isDocumentation: () => isDocumentationIp(ip),
+        isReserved: () => isReservedIp(ip),
+        isPublicInternet: () => isPublicInternetIp(ip),
+    };
+}
+function networkFlowKey(src, dst) {
+    return `${src.ip}:${src.port}->${dst.ip}:${dst.port}`;
+}
+function isLoopbackIp(ip) {
+    const ipv4 = parseIpv4(ip);
+    if (ipv4 !== undefined) {
+        return ipv4[0] === 127;
+    }
+    return ip.toLowerCase() === "::1";
+}
+function isPrivateIp(ip) {
+    const ipv4 = parseIpv4(ip);
+    if (ipv4 !== undefined) {
+        return ipv4[0] === 10
+            || (ipv4[0] === 172 && ipv4[1] >= 16 && ipv4[1] <= 31)
+            || (ipv4[0] === 192 && ipv4[1] === 168);
+    }
+    const lower = ip.toLowerCase();
+    return lower.startsWith("fc") || lower.startsWith("fd");
+}
+function isLinkLocalIp(ip) {
+    const ipv4 = parseIpv4(ip);
+    if (ipv4 !== undefined) {
+        return ipv4[0] === 169 && ipv4[1] === 254;
+    }
+    return /^fe[89ab]/i.test(ip);
+}
+function isMulticastIp(ip) {
+    const ipv4 = parseIpv4(ip);
+    if (ipv4 !== undefined) {
+        return ipv4[0] >= 224 && ipv4[0] <= 239;
+    }
+    return ip.toLowerCase().startsWith("ff");
+}
+function isDocumentationIp(ip) {
+    const ipv4 = parseIpv4(ip);
+    if (ipv4 !== undefined) {
+        return (ipv4[0] === 192 && ipv4[1] === 0 && ipv4[2] === 2)
+            || (ipv4[0] === 198 && ipv4[1] === 51 && ipv4[2] === 100)
+            || (ipv4[0] === 203 && ipv4[1] === 0 && ipv4[2] === 113);
+    }
+    return ip.toLowerCase().startsWith("2001:db8:");
+}
+function isReservedIp(ip) {
+    const ipv4 = parseIpv4(ip);
+    if (ipv4 !== undefined) {
+        return ipv4[0] === 0
+            || (ipv4[0] === 100 && ipv4[1] >= 64 && ipv4[1] <= 127)
+            || (ipv4[0] === 192 && ipv4[1] === 0 && ipv4[2] === 0)
+            || (ipv4[0] === 192 && ipv4[1] === 88 && ipv4[2] === 99)
+            || (ipv4[0] === 198 && (ipv4[1] === 18 || ipv4[1] === 19))
+            || ipv4[0] >= 240
+            || isDocumentationIp(ip);
+    }
+    return ip.toLowerCase().startsWith("2001:db8:");
+}
+function isPublicInternetIp(ip) {
+    return parseIpv4(ip) !== undefined
+        && !isLoopbackIp(ip)
+        && !isPrivateIp(ip)
+        && !isLinkLocalIp(ip)
+        && !isMulticastIp(ip)
+        && !isReservedIp(ip)
+        && !isDocumentationIp(ip)
+        && ip !== "255.255.255.255";
+}
+function parseIpv4(ip) {
+    const parts = ip.split(".");
+    if (parts.length !== 4) {
+        return undefined;
+    }
+    const octets = parts.map((part) => {
+        if (!/^(0|[1-9][0-9]{0,2})$/.test(part)) {
+            return undefined;
+        }
+        const value = Number(part);
+        return value <= 255 ? value : undefined;
+    });
+    return octets.every((part) => part !== undefined)
+        ? octets
+        : undefined;
+}
 function optionalTlsMetadata(value) {
     if (value === undefined || value === null) {
         return undefined;
@@ -760,6 +957,9 @@ function optionalTlsMetadata(value) {
             : assertString(document.alpn, "tls.alpn"),
     };
 }
+function optionalString(value, field) {
+    return value === undefined || value === null ? undefined : assertString(value, field);
+}
 function binaryField(value, field) {
     if (value instanceof Uint8Array) {
         return value;
@@ -922,6 +1122,7 @@ function encodeHostSpawn(options) {
         mounts: options.mounts ?? [],
         networkOutbound: options.network?.outbound,
         networkHttp: options.network?.http === undefined ? undefined : options.network.http,
+        networkPolicy: options.network?.policy === undefined ? undefined : options.network.policy,
     });
 }
 function encodePacket(document) {