sandboxedjs 0.1.93 → 0.1.94

package/dist/agent.d.cts

@@ -1,5 +1,5 @@
-import { C as Container } from './container-BGmhPbSD.cjs';
-import './contracts-BkWBTH8E.cjs';
+import { C as Container } from './container-C3cgcnXZ.cjs';
+import './contracts-B6SHFjma.cjs';
 
 /**
  * Structural copies of the LangChain Deep Agents backend contract.

package/dist/agent.d.ts

@@ -1,5 +1,5 @@
-import { C as Container } from './container-DCwYX_Cx.js';
-import './contracts-BkWBTH8E.js';
+import { C as Container } from './container-WEYRUg6Q.js';
+import './contracts-B6SHFjma.js';
 
 /**
  * Structural copies of the LangChain Deep Agents backend contract.

package/dist/{container-BGmhPbSD.d.cts → container-C3cgcnXZ.d.cts}

@@ -1,4 +1,4 @@
-import { V as Vfs, C as Cred, f as RuntimePod, O as OutboundPolicy, D as DirEntry, p as Stats } from './contracts-BkWBTH8E.cjs';
+import { V as Vfs, C as Cred, f as RuntimePod, O as OutboundPolicy, D as DirEntry, p as Stats } from './contracts-B6SHFjma.cjs';
 
 /**
  * Byte streams for stdin/stdout/stderr, pipelines and redirections.

package/dist/{container-DCwYX_Cx.d.ts → container-WEYRUg6Q.d.ts}

@@ -1,4 +1,4 @@
-import { V as Vfs, C as Cred, f as RuntimePod, O as OutboundPolicy, D as DirEntry, p as Stats } from './contracts-BkWBTH8E.js';
+import { V as Vfs, C as Cred, f as RuntimePod, O as OutboundPolicy, D as DirEntry, p as Stats } from './contracts-B6SHFjma.js';
 
 /**
  * Byte streams for stdin/stdout/stderr, pipelines and redirections.

package/dist/{contracts-BkWBTH8E.d.cts → contracts-B6SHFjma.d.cts}

@@ -95,6 +95,101 @@ declare function createChildProcessModule(spawnChild: SpawnChild, defaultCwd: ()
     ipc?: IpcTransport;
 }): Record<string, unknown>;
 
+/**
+ * The outbound network policy, as plain functions every client consults.
+ *
+ * The container has several ways out — `curl` and `wget` in the shell, `http`,
+ * `https`, `fetch` and `WebSocket` in a Node program, sockets in Python — and
+ * they used to decide separately. Only the shell asked: a Node program's
+ * `fetch("https://…")` reached the internet from a container booted with
+ * outbound access off. One policy, applied at each exit, is what makes
+ * `network: { allowOutbound: false }` mean what it says.
+ *
+ * Loopback is not "outbound" at all. `127.0.0.1` inside the container is the
+ * container, so those requests are routed to its own servers and never handed
+ * to the host's network stack, whatever the policy allows.
+ */
+interface OutboundPolicy {
+    /** Whether requests may leave the container at all. */
+    allowOutbound: boolean;
+    /** When outbound is on, the hosts it may reach (subdomains included). `null` means any. */
+    allowedHosts: string[] | null;
+}
+
+/**
+ * Outbound TCP: names resolved by the host, connections dialled by the host.
+ *
+ * Until now a guest socket could reach only loopback. Everything that speaks a
+ * protocol other than HTTP -- Postgres, Redis, SMTP, an LLM gateway over a raw
+ * stream -- was therefore unreachable, and so was every HTTP client that opens
+ * its own socket rather than going through the egress. Extensions do not help:
+ * no wheel can create a connection the container cannot make.
+ *
+ * Two things are needed, and both belong to the host.
+ *
+ * **Names.** Emscripten's own `getaddrinfo` invents an address per hostname and
+ * keeps the table inside the guest's JavaScript module, where the kernel cannot
+ * see it -- so a later `connect` arrived as an address nobody could map back to
+ * a name. Resolution is therefore a host operation: the host allocates the
+ * address, remembers which name it stands for, and recognises it on connect. A
+ * guest still sees ordinary addresses, `getaddrinfo` still returns tuples, and
+ * reverse lookup answers.
+ *
+ * **The connection.** Only the host can open a socket. In Node that is
+ * `node:net`; in a browser there is no such thing, and a page cannot be given
+ * one, so a browser host supplies no dialer and outbound connects fail with a
+ * message that says to use the HTTP egress instead.
+ *
+ * The outbound policy applies here as it does at every other exit, and it is
+ * applied to the *name* the guest asked for, not to the address it was handed.
+ */
+
+/** A real connection the host owns, as this module needs to use it. */
+interface HostTcpConnection {
+    write(bytes: Uint8Array): void;
+    /** Half-close: the guest has finished writing. */
+    end(): void;
+    close(): void;
+    onData(handler: (bytes: Uint8Array) => void): void;
+    onClose(handler: () => void): void;
+    /** The address the host actually connected to, for `getpeername`. */
+    readonly remoteAddress: string;
+    readonly remotePort: number;
+    readonly localPort: number;
+}
+/** What a host must provide for a guest to reach the network. */
+interface TcpDialer {
+    (host: string, port: number): Promise<HostTcpConnection>;
+}
+declare class OutboundTcp {
+    private readonly policy;
+    private readonly dialer;
+    private readonly byName;
+    private readonly byAddress;
+    private next;
+    constructor(policy: () => OutboundPolicy, dialer: TcpDialer | null);
+    /** Whether this address was handed out by `resolve`. */
+    knows(address: string): boolean;
+    hostnameFor(address: string): string | undefined;
+    /**
+     * The address for `hostname`, allocating one on first use.
+     *
+     * Refusal happens here as well as at connect, because a name that cannot be
+     * reached should fail as a resolution failure -- which is what every client
+     * reports as "unknown host" rather than as a mid-connection error.
+     */
+    resolve(hostname: string): string;
+    /** Open a connection to a resolved address, or to a literal one. */
+    connect(address: string, port: number, local: {
+        address: string;
+        port: number;
+    }): Promise<{
+        connection: VirtualTcpConnection;
+        host: HostTcpConnection;
+    }>;
+    private allowed;
+}
+
 type FileKind = "file" | "directory" | "symlink" | "chardev" | "blockdev" | "fifo" | "socket";
 /** Render as `drwxr-xr-x`, honouring setuid/setgid/sticky. */
 declare function formatMode(mode: number): string;
@@ -368,36 +463,29 @@ declare class VirtualTcpListener {
 declare class VirtualTcpNetwork {
     private readonly occupied?;
     private readonly listeners;
+    /** The host's outbound stack, when this host can open sockets at all. */
+    outbound: OutboundTcp | null;
+    /**
+     * Ports held by in-container servers that are not sockets.
+     *
+     * A JavaScript HTTP server in the container is registered with the request
+     * router and never binds one of these sockets, so a guest connecting to its
+     * port found nothing listening. Before sockets could leave the container
+     * this did not arise -- every guest client went out through the egress --
+     * and afterwards `urllib` dialling a container server got ECONNREFUSED.
+     */
+    loopbackHttp: ((port: number, connection: VirtualTcpConnection) => boolean) | null;
     constructor(occupied?: ((port: number) => boolean) | undefined);
     listen(port: number, address?: string, backlog?: number): VirtualTcpListener;
     close(listener: VirtualTcpListener): void;
     connect(port: number, localPort?: number, localAddress?: string): VirtualTcpConnection;
+    /** A connection to a port an in-container server holds without a socket. */
+    private connectToNonSocketServer;
     hasListener(port: number): boolean;
     ports(): number[];
     closeAll(): void;
 }
 
-/**
- * The outbound network policy, as plain functions every client consults.
- *
- * The container has several ways out — `curl` and `wget` in the shell, `http`,
- * `https`, `fetch` and `WebSocket` in a Node program, sockets in Python — and
- * they used to decide separately. Only the shell asked: a Node program's
- * `fetch("https://…")` reached the internet from a container booted with
- * outbound access off. One policy, applied at each exit, is what makes
- * `network: { allowOutbound: false }` mean what it says.
- *
- * Loopback is not "outbound" at all. `127.0.0.1` inside the container is the
- * container, so those requests are routed to its own servers and never handed
- * to the host's network stack, whatever the policy allows.
- */
-interface OutboundPolicy {
-    /** Whether requests may leave the container at all. */
-    allowOutbound: boolean;
-    /** When outbound is on, the hosts it may reach (subdomains included). `null` means any. */
-    allowedHosts: string[] | null;
-}
-
 /**
  * Clean-room contracts between SandboxedJS and its JavaScript runtime.
  *

package/dist/{contracts-BkWBTH8E.d.ts → contracts-B6SHFjma.d.ts}

@@ -95,6 +95,101 @@ declare function createChildProcessModule(spawnChild: SpawnChild, defaultCwd: ()
     ipc?: IpcTransport;
 }): Record<string, unknown>;
 
+/**
+ * The outbound network policy, as plain functions every client consults.
+ *
+ * The container has several ways out — `curl` and `wget` in the shell, `http`,
+ * `https`, `fetch` and `WebSocket` in a Node program, sockets in Python — and
+ * they used to decide separately. Only the shell asked: a Node program's
+ * `fetch("https://…")` reached the internet from a container booted with
+ * outbound access off. One policy, applied at each exit, is what makes
+ * `network: { allowOutbound: false }` mean what it says.
+ *
+ * Loopback is not "outbound" at all. `127.0.0.1` inside the container is the
+ * container, so those requests are routed to its own servers and never handed
+ * to the host's network stack, whatever the policy allows.
+ */
+interface OutboundPolicy {
+    /** Whether requests may leave the container at all. */
+    allowOutbound: boolean;
+    /** When outbound is on, the hosts it may reach (subdomains included). `null` means any. */
+    allowedHosts: string[] | null;
+}
+
+/**
+ * Outbound TCP: names resolved by the host, connections dialled by the host.
+ *
+ * Until now a guest socket could reach only loopback. Everything that speaks a
+ * protocol other than HTTP -- Postgres, Redis, SMTP, an LLM gateway over a raw
+ * stream -- was therefore unreachable, and so was every HTTP client that opens
+ * its own socket rather than going through the egress. Extensions do not help:
+ * no wheel can create a connection the container cannot make.
+ *
+ * Two things are needed, and both belong to the host.
+ *
+ * **Names.** Emscripten's own `getaddrinfo` invents an address per hostname and
+ * keeps the table inside the guest's JavaScript module, where the kernel cannot
+ * see it -- so a later `connect` arrived as an address nobody could map back to
+ * a name. Resolution is therefore a host operation: the host allocates the
+ * address, remembers which name it stands for, and recognises it on connect. A
+ * guest still sees ordinary addresses, `getaddrinfo` still returns tuples, and
+ * reverse lookup answers.
+ *
+ * **The connection.** Only the host can open a socket. In Node that is
+ * `node:net`; in a browser there is no such thing, and a page cannot be given
+ * one, so a browser host supplies no dialer and outbound connects fail with a
+ * message that says to use the HTTP egress instead.
+ *
+ * The outbound policy applies here as it does at every other exit, and it is
+ * applied to the *name* the guest asked for, not to the address it was handed.
+ */
+
+/** A real connection the host owns, as this module needs to use it. */
+interface HostTcpConnection {
+    write(bytes: Uint8Array): void;
+    /** Half-close: the guest has finished writing. */
+    end(): void;
+    close(): void;
+    onData(handler: (bytes: Uint8Array) => void): void;
+    onClose(handler: () => void): void;
+    /** The address the host actually connected to, for `getpeername`. */
+    readonly remoteAddress: string;
+    readonly remotePort: number;
+    readonly localPort: number;
+}
+/** What a host must provide for a guest to reach the network. */
+interface TcpDialer {
+    (host: string, port: number): Promise<HostTcpConnection>;
+}
+declare class OutboundTcp {
+    private readonly policy;
+    private readonly dialer;
+    private readonly byName;
+    private readonly byAddress;
+    private next;
+    constructor(policy: () => OutboundPolicy, dialer: TcpDialer | null);
+    /** Whether this address was handed out by `resolve`. */
+    knows(address: string): boolean;
+    hostnameFor(address: string): string | undefined;
+    /**
+     * The address for `hostname`, allocating one on first use.
+     *
+     * Refusal happens here as well as at connect, because a name that cannot be
+     * reached should fail as a resolution failure -- which is what every client
+     * reports as "unknown host" rather than as a mid-connection error.
+     */
+    resolve(hostname: string): string;
+    /** Open a connection to a resolved address, or to a literal one. */
+    connect(address: string, port: number, local: {
+        address: string;
+        port: number;
+    }): Promise<{
+        connection: VirtualTcpConnection;
+        host: HostTcpConnection;
+    }>;
+    private allowed;
+}
+
 type FileKind = "file" | "directory" | "symlink" | "chardev" | "blockdev" | "fifo" | "socket";
 /** Render as `drwxr-xr-x`, honouring setuid/setgid/sticky. */
 declare function formatMode(mode: number): string;
@@ -368,36 +463,29 @@ declare class VirtualTcpListener {
 declare class VirtualTcpNetwork {
     private readonly occupied?;
     private readonly listeners;
+    /** The host's outbound stack, when this host can open sockets at all. */
+    outbound: OutboundTcp | null;
+    /**
+     * Ports held by in-container servers that are not sockets.
+     *
+     * A JavaScript HTTP server in the container is registered with the request
+     * router and never binds one of these sockets, so a guest connecting to its
+     * port found nothing listening. Before sockets could leave the container
+     * this did not arise -- every guest client went out through the egress --
+     * and afterwards `urllib` dialling a container server got ECONNREFUSED.
+     */
+    loopbackHttp: ((port: number, connection: VirtualTcpConnection) => boolean) | null;
     constructor(occupied?: ((port: number) => boolean) | undefined);
     listen(port: number, address?: string, backlog?: number): VirtualTcpListener;
     close(listener: VirtualTcpListener): void;
     connect(port: number, localPort?: number, localAddress?: string): VirtualTcpConnection;
+    /** A connection to a port an in-container server holds without a socket. */
+    private connectToNonSocketServer;
     hasListener(port: number): boolean;
     ports(): number[];
     closeAll(): void;
 }
 
-/**
- * The outbound network policy, as plain functions every client consults.
- *
- * The container has several ways out — `curl` and `wget` in the shell, `http`,
- * `https`, `fetch` and `WebSocket` in a Node program, sockets in Python — and
- * they used to decide separately. Only the shell asked: a Node program's
- * `fetch("https://…")` reached the internet from a container booted with
- * outbound access off. One policy, applied at each exit, is what makes
- * `network: { allowOutbound: false }` mean what it says.
- *
- * Loopback is not "outbound" at all. `127.0.0.1` inside the container is the
- * container, so those requests are routed to its own servers and never handed
- * to the host's network stack, whatever the policy allows.
- */
-interface OutboundPolicy {
-    /** Whether requests may leave the container at all. */
-    allowOutbound: boolean;
-    /** When outbound is on, the hosts it may reach (subdomains included). `null` means any. */
-    allowedHosts: string[] | null;
-}
-
 /**
  * Clean-room contracts between SandboxedJS and its JavaScript runtime.
  *