@polyengine/wasi 0.1.0-pre.g633468a → 0.2.0-pre.g2125a06

package/esm/http.js

@@ -66,7 +66,12 @@
 // Fetch failures are TypeErrors with prose; a small sniff table maps the
 // recognizable ones and everything else is `internal-error(message)`.
 import { ComponentException } from "@polyengine/runtime/embedder";
-/** The compatibility track the fragment registers on by default. */
+/**
+ * The compatibility track the fragment registers on by default.
+ *
+ * @internal — test-only export; wasi/tests/http_test.ts pins the default
+ * track literally, but the public entry point is `http()`.
+ */
 export const HTTP_TRACK = "0.3";
 const OK = { kind: "ok" };
 function httpError(payload, detail) {
@@ -75,7 +80,12 @@ function httpError(payload, detail) {
 function headerError(kind, detail) {
     return new ComponentException({ kind }, `wasi:http/types: ${detail}`);
 }
-/** Map a fetch failure onto `error-code` (sniff table + honest catch-all). */
+/**
+ * Map a fetch failure onto `error-code` (sniff table + honest catch-all).
+ *
+ * @internal — used only inside this module's `send` implementation; no
+ * importer outside wasi/src/http.ts. The public entry point is `http()`.
+ */
 export function mapFetchError(e) {
     // Deno/undici wrap the transport detail in the `cause` chain; sniff the
     // whole chain, report the top-level message.
@@ -133,6 +143,7 @@ const decoder = new TextDecoder();
 export function http(options = {}) {
     const onCall = options.onCall ?? (() => { });
     const v = options.version ?? HTTP_TRACK;
+    const allowRequest = options.allowRequest;
     // --- fields -----------------------------------------------------------------
     class Fields {
         /** Entries in original casing and insertion order. */
@@ -608,6 +619,42 @@ export function http(options = {}) {
                 throw httpError({ kind: "internal-error", value: `header '${name}' refused by the platform` }, `client.send: ${e}`);
             }
         }
+        // Name-level egress policy (allowRequest). Only parse `url` when a
+        // policy is actually configured — with no policy or `allowRequest:
+        // true`, this path is byte-for-byte today's behavior (same string
+        // handed to fetch below, `URL.href` never substituted in). Placed
+        // after headers, before collectBody: refusing must not drain the
+        // guest's body stream.
+        if (allowRequest !== undefined && allowRequest !== true) {
+            if (allowRequest === false) {
+                request.settleTransmission({ kind: "err", value: { kind: "HTTP-request-denied" } });
+                throw httpError({ kind: "HTTP-request-denied" }, "client.send: request denied (allowRequest: false)");
+            }
+            let parsed;
+            try {
+                parsed = new URL(url);
+            }
+            catch {
+                // A malformed authority is not a policy decision — the existing
+                // HTTP-request-URI-invalid case at line ~858 covers this.
+                throw httpError({ kind: "HTTP-request-URI-invalid" }, "client.send: url could not be parsed for policy check");
+            }
+            let allowed;
+            try {
+                allowed = await allowRequest({ url: parsed, method, headers });
+            }
+            catch (e) {
+                // Fail closed: a throwing/rejecting predicate denies. The thrown
+                // message goes into the ComponentException's DETAIL string only,
+                // never the WIT payload.
+                request.settleTransmission({ kind: "err", value: { kind: "HTTP-request-denied" } });
+                throw httpError({ kind: "HTTP-request-denied" }, `client.send: allowRequest threw: ${e instanceof Error ? e.message : String(e)}`);
+            }
+            if (!allowed) {
+                request.settleTransmission({ kind: "err", value: { kind: "HTTP-request-denied" } });
+                throw httpError({ kind: "HTTP-request-denied" }, "client.send: request denied by allowRequest");
+            }
+        }
         // Buffered request body (module header divergence), then the trailers
         // future decides whether the request may be transmitted at all.
         let body;

package/esm/internal/sockets_shared.js

@@ -19,7 +19,12 @@ export function componentError(payload, detail) {
     return new ComponentException(payload, `wasi:sockets/types@0.3: ${detail}`);
 }
 // --- address codec ------------------------------------------------------------
-/** Render the address part of `addr` as a Deno hostname string. */
+/**
+ * Render the address part of `addr` as a Deno hostname string.
+ *
+ * @internal — shared by the node/Deno socket backends; the public entry
+ * point is `sockets()`.
+ */
 export function ipHostname(addr) {
     if (addr.kind === "ipv4")
         return addr.value.address.join(".");
@@ -35,6 +40,9 @@ export function ipHostname(addr) {
  * when it is numeric and drops to 0 otherwise (interface names are not
  * representable in the WIT shape); flow-info is not observable and is
  * always 0.
+ *
+ * @internal — shared by the node/Deno socket backends; the public entry
+ * point is `sockets()`.
  */
 export function parseNetAddr(addr) {
     const host = addr.hostname;
@@ -131,6 +139,9 @@ function isDeprecatedV4CompatibleV6(groups) {
 /**
  * Whether `addr` may cross this socket's family boundary: same family, and
  * never an IPv4-mapped or deprecated IPv4-compatible IPv6 address.
+ *
+ * @internal — shared by the node/Deno socket backends; the public entry
+ * point is `sockets()`.
  */
 export function isValidAddressFamily(family, addr) {
     if (family === "ipv4")
@@ -139,12 +150,21 @@ export function isValidAddressFamily(family, addr) {
         !isV4MappedV6(addr.value.address) &&
         !isDeprecatedV4CompatibleV6(addr.value.address);
 }
+/**
+ * @internal — shared by the node/Deno socket backends; the public entry
+ * point is `sockets()`.
+ */
 export function isUnspecified(addr) {
     if (addr.kind === "ipv4")
         return addr.value.address.every((o) => o === 0);
     return addr.value.address.every((g) => g === 0);
 }
-/** Same endpoint: family, address, and port (udp connected-mode filter). */
+/**
+ * Same endpoint: family, address, and port (udp connected-mode filter).
+ *
+ * @internal — shared by the node/Deno socket backends; the public entry
+ * point is `sockets()`.
+ */
 export function sameSocketAddress(a, b) {
     if (a.kind !== b.kind || a.value.port !== b.value.port)
         return false;
@@ -203,6 +223,9 @@ const CODE_ERRORS = {
  * capability re-detection throw branded errors from inside the same try
  * blocks that guard the platform calls, and re-wrapping one would demote
  * its payload to `other`.
+ *
+ * @internal — shared by the node/Deno socket backends; the public entry
+ * point is `sockets()`.
  */
 export function mapPlatformError(e, what) {
     if (e instanceof ComponentException)
@@ -257,7 +280,12 @@ export const RESULT_INVALID_STATE = {
 export function resultErrOf(e, what) {
     return { kind: "err", value: mapPlatformError(e, what).payload };
 }
-/** The family's wildcard address, port 0 (tcp listen's implicit bind). */
+/**
+ * The family's wildcard address, port 0 (tcp listen's implicit bind).
+ *
+ * @internal — shared by the node/Deno socket backends; the public entry
+ * point is `sockets()`.
+ */
 export function wildcardAddress(family) {
     return family === "ipv4"
         ? { kind: "ipv4", value: { port: 0, address: [0, 0, 0, 0] } }

package/esm/io.js

@@ -366,7 +366,10 @@ let OutputStream = (() => {
 export { OutputStream };
 /** Default high-water mark for the async-backed streams below: how many
  * buffered bytes pause a `FedInputStream`'s feed, and the byte budget a
- * `SinkOutputStream`'s `check-write` reports. */
+ * `SinkOutputStream`'s `check-write` reports.
+ *
+ * @internal — a tuning constant for this module's stream implementations;
+ * not part of any consumer-facing option surface. */
 export const STREAM_HIGH_WATER = 65536;
 /**
  * The p2 `input-stream` surface over an asynchronously-fed buffer: the
@@ -377,6 +380,11 @@ export const STREAM_HIGH_WATER = 65536;
  * registered `InputStream`, the marks relay from that prototype), and
  * EOF-with-drained-buffer is the `closed` stream-error. The feed pauses
  * past the high-water mark (no unbounded buffering).
+ *
+ * @internal — an implementation detail wired internally by `cli_stdio.ts`,
+ * `filesystem_node.ts`/`filesystem_web.ts`, and the sockets fragments; never
+ * surfaced as a public field/return type (`CliStdio.imports` and
+ * `FilesystemFragment.imports` are opaque `Record<string, unknown>`).
  */
 let FedInputStream = (() => {
     let _instanceExtraInitializers = [];
@@ -508,6 +516,10 @@ export { FedInputStream };
  * drained everything (A14/A2 mark relay), `subscribe` wakes when budget
  * frees. A sink failure surfaces as the `last-operation-failed`
  * stream-error carrying an `IoError`.
+ *
+ * @internal — an implementation detail wired internally by `cli_stdio.ts`,
+ * `filesystem_node.ts`/`filesystem_web.ts`, and the sockets fragments; never
+ * surfaced as a public field/return type.
  */
 let SinkOutputStream = (() => {
     let _instanceExtraInitializers = [];

package/esm/sockets.js

@@ -148,6 +148,10 @@ export { ipHostname, isUnspecified, isValidAddressFamily, mapPlatformError, MAX_
 // The 0.2 track's public pieces: the enum error vocabulary, the io-error
 // resource `network-error-code` downcasts, and the opaque network.
 export { Network, SocketIoError, } from "./internal/sockets_02.js";
+/**
+ * @internal — test-only export; wasi/tests/sockets_test.ts pins the
+ * literal track key. The public entry point is `sockets()`.
+ */
 export const SOCKETS_TYPES_INTERFACE = "wasi:sockets/types@0.3";
 /**
  * The `wasi:sockets` provider fragment, BOTH tracks (module header):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polyengine/wasi",
-  "version": "0.1.0-pre.g633468a",
+  "version": "0.2.0-pre.g2125a06",
   "description": "WASI providers for polyengine hosts: the p2 baseline and p3 clocks, one module per semver track.",
   "homepage": "https://github.com/polymorph-components/polyengine#readme",
   "repository": {
@@ -91,8 +91,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@polyengine/protocol": "0.1.0-pre.g633468a",
-    "@polyengine/runtime": "0.1.0-pre.g633468a"
+    "@polyengine/protocol": "0.2.0-pre.g2125a06",
+    "@polyengine/runtime": "0.2.0-pre.g2125a06"
   },
   "_generatedBy": "dnt@0.43.2"
 }

package/types/http.d.ts

@@ -1,5 +1,10 @@
 import { Stream } from "@polyengine/runtime/embedder";
-/** The compatibility track the fragment registers on by default. */
+/**
+ * The compatibility track the fragment registers on by default.
+ *
+ * @internal — test-only export; wasi/tests/http_test.ts pins the default
+ * track literally, but the public entry point is `http()`.
+ */
 export declare const HTTP_TRACK = "0.3";
 /** `method` — case names verbatim (A10). */
 export type Method = {
@@ -77,7 +82,12 @@ export type HttpResult = {
     kind: "err";
     value: ErrorCode;
 };
-/** Map a fetch failure onto `error-code` (sniff table + honest catch-all). */
+/**
+ * Map a fetch failure onto `error-code` (sniff table + honest catch-all).
+ *
+ * @internal — used only inside this module's `send` implementation; no
+ * importer outside wasi/src/http.ts. The public entry point is `http()`.
+ */
 export declare function mapFetchError(e: unknown): ErrorCode;
 /** What body params accept: the lifted handle, or any natural byte producer. */
 export type BodySource = Stream<number> | AsyncIterable<Uint8Array | number[]> | Iterable<Uint8Array | number[]>;
@@ -93,6 +103,34 @@ export interface HttpOptions {
     version?: string;
     /** Observe every entry point the guest reaches (see sockets' onCall). */
     onCall?: (call: string) => void;
+    /**
+     * Name-level egress policy, evaluated in `client.send` after the outgoing
+     * request is assembled (method, headers) but before its body is
+     * collected — so a refused request never drains the guest's body
+     * stream. `true`/default preserves today's behavior exactly (unscoped
+     * egress); `false` denies every request without dispatching `fetch`; a
+     * callback decides per request from the parsed `url`, `method`, and
+     * `headers`.
+     *
+     * This is the name-level half only: it sees the URL a guest asked for,
+     * matching what a `fetch`-based host can express (no resolved address
+     * is ever observed here, unlike a native socket layer). The
+     * address-level half (`socket_addr_check`-shaped, e.g. blocking a
+     * name that resolves to a loopback/link-local address) is issue #200
+     * and is out of scope for this fragment; `sockets()` is unaffected.
+     *
+     * A callback that throws, or whose returned promise rejects, DENIES
+     * (fail closed) — a security predicate must never fail open. Denials
+     * refuse with the WIT `HTTP-request-denied` error-code case
+     * (examples/guests/http-fetch/wit/deps/wasi-http/types.wit); this is
+     * distinct from `destination-IP-prohibited`, which names an address
+     * judgement this fragment cannot make.
+     */
+    allowRequest?: boolean | ((request: {
+        url: URL;
+        method: string;
+        headers: Headers;
+    }) => boolean | Promise<boolean>);
 }
 /** What `http()` returns: the imports fragment plus the fragment's classes. */
 export interface HttpFragment {

package/types/internal/fs_provider.d.ts

@@ -50,6 +50,12 @@ export interface Opened<H> {
     handle: H;
     type: DescriptorType;
 }
+/**
+ * @internal — used only in the (unexported) `FsBackend` seam interface;
+ * re-exported from `filesystem_node.ts`/`filesystem_web.ts` but never part
+ * of `FilesystemFragment`'s public shape (`{ imports: Record<string,
+ * unknown> }`), so no importer outside wasi/src references it.
+ */
 export type MaybeAsync<T> = T | Promise<T>;
 /**
  * The backend seam. `isSync: true` promises every op returns a plain

package/types/internal/sockets_platform.d.ts

@@ -1,4 +1,10 @@
-/** The address shape the socket backends speak. */
+/**
+ * The address shape the socket backends speak.
+ *
+ * @internal — a Deno/node platform backend type; its only non-backend
+ * reference was `parseNetAddr`'s parameter, itself internal. The public
+ * entry point is `sockets()`.
+ */
 export interface NetAddr {
     transport?: string;
     hostname: string;

package/types/internal/sockets_shared.d.ts

@@ -106,7 +106,12 @@ export declare const MAX_UDP_DATAGRAM_SIZE = 65535;
  * guest-visible err.
  */
 export declare function componentError(payload: SocketErrorCode, detail: string): ComponentException<SocketErrorCode>;
-/** Render the address part of `addr` as a Deno hostname string. */
+/**
+ * Render the address part of `addr` as a Deno hostname string.
+ *
+ * @internal — shared by the node/Deno socket backends; the public entry
+ * point is `sockets()`.
+ */
 export declare function ipHostname(addr: IpSocketAddress): string;
 /**
  * Parse a Deno `NetAddr` back into a WIT `ip-socket-address`.
@@ -117,15 +122,30 @@ export declare function ipHostname(addr: IpSocketAddress): string;
  * when it is numeric and drops to 0 otherwise (interface names are not
  * representable in the WIT shape); flow-info is not observable and is
  * always 0.
+ *
+ * @internal — shared by the node/Deno socket backends; the public entry
+ * point is `sockets()`.
  */
 export declare function parseNetAddr(addr: NetAddr): IpSocketAddress;
 /**
  * Whether `addr` may cross this socket's family boundary: same family, and
  * never an IPv4-mapped or deprecated IPv4-compatible IPv6 address.
+ *
+ * @internal — shared by the node/Deno socket backends; the public entry
+ * point is `sockets()`.
  */
 export declare function isValidAddressFamily(family: IpAddressFamily, addr: IpSocketAddress): boolean;
+/**
+ * @internal — shared by the node/Deno socket backends; the public entry
+ * point is `sockets()`.
+ */
 export declare function isUnspecified(addr: IpSocketAddress): boolean;
-/** Same endpoint: family, address, and port (udp connected-mode filter). */
+/**
+ * Same endpoint: family, address, and port (udp connected-mode filter).
+ *
+ * @internal — shared by the node/Deno socket backends; the public entry
+ * point is `sockets()`.
+ */
 export declare function sameSocketAddress(a: IpSocketAddress, b: IpSocketAddress): boolean;
 /** `e instanceof Deno.errors[name]`, tolerating hosts/versions lacking the class. */
 export declare function isDenoError(e: unknown, name: string): boolean;
@@ -138,6 +158,9 @@ export declare function isDenoError(e: unknown, name: string): boolean;
  * capability re-detection throw branded errors from inside the same try
  * blocks that guard the platform calls, and re-wrapping one would demote
  * its payload to `other`.
+ *
+ * @internal — shared by the node/Deno socket backends; the public entry
+ * point is `sockets()`.
  */
 export declare function mapPlatformError(e: unknown, what: string): ComponentException<SocketErrorCode>;
 /** `result<_, error-code>` as a value (the payload of tcp send/receive futures). */
@@ -252,5 +275,10 @@ export interface TcpSocket {
 export interface TcpSocketClass {
     create(addressFamily: IpAddressFamily): TcpSocket;
 }
-/** The family's wildcard address, port 0 (tcp listen's implicit bind). */
+/**
+ * The family's wildcard address, port 0 (tcp listen's implicit bind).
+ *
+ * @internal — shared by the node/Deno socket backends; the public entry
+ * point is `sockets()`.
+ */
 export declare function wildcardAddress(family: IpAddressFamily): IpSocketAddress;

package/types/io.d.ts

@@ -1,4 +1,9 @@
-/** A p2 `stream-error` value (variant): `closed` or `last-operation-failed`. */
+/**
+ * A p2 `stream-error` value (variant): `closed` or `last-operation-failed`.
+ *
+ * @internal — only used as `closedError()`'s local payload type; not part
+ * of any exported class's public signature (`IoError` never surfaces it).
+ */
 export type StreamErrorValue = {
     kind: "closed";
 } | {
@@ -116,7 +121,10 @@ export declare class OutputStream {
 }
 /** Default high-water mark for the async-backed streams below: how many
  * buffered bytes pause a `FedInputStream`'s feed, and the byte budget a
- * `SinkOutputStream`'s `check-write` reports. */
+ * `SinkOutputStream`'s `check-write` reports.
+ *
+ * @internal — a tuning constant for this module's stream implementations;
+ * not part of any consumer-facing option surface. */
 export declare const STREAM_HIGH_WATER = 65536;
 /** An async byte sink; the returned promise settling = the chunk drained. */
 export type ByteSink = (chunk: Uint8Array) => void | Promise<void>;
@@ -129,6 +137,11 @@ export type ByteSink = (chunk: Uint8Array) => void | Promise<void>;
  * registered `InputStream`, the marks relay from that prototype), and
  * EOF-with-drained-buffer is the `closed` stream-error. The feed pauses
  * past the high-water mark (no unbounded buffering).
+ *
+ * @internal — an implementation detail wired internally by `cli_stdio.ts`,
+ * `filesystem_node.ts`/`filesystem_web.ts`, and the sockets fragments; never
+ * surfaced as a public field/return type (`CliStdio.imports` and
+ * `FilesystemFragment.imports` are opaque `Record<string, unknown>`).
  */
 export declare class FedInputStream {
     #private;
@@ -149,6 +162,10 @@ export declare class FedInputStream {
  * drained everything (A14/A2 mark relay), `subscribe` wakes when budget
  * frees. A sink failure surfaces as the `last-operation-failed`
  * stream-error carrying an `IoError`.
+ *
+ * @internal — an implementation detail wired internally by `cli_stdio.ts`,
+ * `filesystem_node.ts`/`filesystem_web.ts`, and the sockets fragments; never
+ * surfaced as a public field/return type.
  */
 export declare class SinkOutputStream {
     #private;

package/types/sockets.d.ts

@@ -1,6 +1,10 @@
 import type { IpAddress, SocketsOptions, TcpSocketClass, UdpSocketClass } from "./internal/sockets_shared.js";
 export { type IpAddress, type IpAddressFamily, ipHostname, type IpSocketAddress, type Ipv4Address, type Ipv4SocketAddress, type Ipv6Address, type Ipv6SocketAddress, isUnspecified, isValidAddressFamily, mapPlatformError, MAX_UDP_DATAGRAM_SIZE, type NameLookupErrorCode, type NetAddr, parseNetAddr, sameSocketAddress, type SocketErrorCode, type SocketResult, type SocketsOptions, type TcpAcceptStream, type TcpByteStream, type TcpSendSource, type TcpSocket, type TcpSocketClass, type UdpSocket, type UdpSocketClass, wildcardAddress, } from "./internal/sockets_shared.js";
 export { Network, type SocketErrorCode02, SocketIoError, } from "./internal/sockets_02.js";
+/**
+ * @internal — test-only export; wasi/tests/sockets_test.ts pins the
+ * literal track key. The public entry point is `sockets()`.
+ */
 export declare const SOCKETS_TYPES_INTERFACE = "wasi:sockets/types@0.3";
 /** What `sockets()` returns: the imports fragment plus the fragment's classes. */
 export interface SocketsShim {