@markii/host 0.0.1 → 0.17.0-next.2

package/dist/run/ip-address.js

@@ -0,0 +1,255 @@
+/**
+ * Address classification for the run path's network jail (GitHub issue #10).
+ *
+ * A network grant is a hostname string, so the host the user consented to and
+ * the address the request actually reaches are two different things. This
+ * module answers the second half: given an address, is it somewhere a note's
+ * script has any business reaching?
+ *
+ * Pure and dependency-free (the address validators are local), so it
+ * is exhaustively testable without a socket, a resolver, or a worker.
+ */
+/**
+ * True for a dotted-quad IPv4 literal: four decimal octets, 0 to 255, with
+ * no leading zeros (`010.0.0.1` is refused, since some SSRF filters
+ * mis-parse it as decimal) and no extra characters.
+ */
+export function isIPv4(value) {
+    const parts = value.split('.');
+    if (parts.length !== 4)
+        return false;
+    return parts.every((part) => /^(0|[1-9][0-9]{0,2})$/.test(part) && Number.parseInt(part, 10) <= 255);
+}
+/**
+ * True for an IPv6 literal without a zone index: up to eight groups of one
+ * to four hex digits, at most one `::` run, and an optional trailing
+ * dotted-quad standing for the last two groups.
+ */
+export function isIPv6(value) {
+    if (value === '' || value.includes('%') || !value.includes(':'))
+        return false;
+    const doubleColon = value.indexOf('::');
+    if (doubleColon !== -1 && value.indexOf('::', doubleColon + 1) !== -1) {
+        return false;
+    }
+    // ':::' is two overlapping '::' runs.
+    if (value.includes(':::'))
+        return false;
+    const head = doubleColon === -1 ? value : value.slice(0, doubleColon);
+    const tail = doubleColon === -1 ? '' : value.slice(doubleColon + 2);
+    const headGroups = head === '' ? [] : head.split(':');
+    const tailGroups = tail === '' ? [] : tail.split(':');
+    const groups = [...headGroups, ...tailGroups];
+    let count = 0;
+    for (let i = 0; i < groups.length; i += 1) {
+        const group = groups[i] ?? '';
+        const isLast = i === groups.length - 1;
+        if (group.includes('.')) {
+            // Only the final group may be a dotted-quad, and it counts as two.
+            if (!isLast || !isIPv4(group))
+                return false;
+            count += 2;
+        }
+        else {
+            if (!/^[0-9a-fA-F]{1,4}$/.test(group))
+                return false;
+            count += 1;
+        }
+    }
+    return doubleColon === -1 ? count === 8 : count <= 7;
+}
+/** Every scope except `'public'`: not reachable by default from a note's script. */
+export function isRestrictedScope(scope) {
+    return scope !== 'public';
+}
+/** Human wording for a denial or a grant prompt. Kept here so one vocabulary describes a scope everywhere. */
+export function describeScope(scope) {
+    switch (scope) {
+        case 'public':
+            return 'a public address';
+        case 'loopback':
+            return 'an address on this machine';
+        case 'private':
+            return 'an address on this private network';
+        case 'link-local':
+            return 'a link-local address';
+        case 'unspecified':
+            return 'the unspecified address';
+        case 'multicast':
+            return 'a multicast address';
+        case 'reserved':
+            return 'a reserved address';
+    }
+}
+/**
+ * Classifies `address`, or returns `undefined` when it is not an IP literal
+ * at all (a hostname, or anything malformed). The local `isIPv4`/`isIPv6`
+ * validators decide what counts as an IP; they reject the leading-zero octet forms
+ * (`010.0.0.1`) that some SSRF filters mis-parse as decimal.
+ */
+export function classifyIpAddress(address) {
+    const trimmed = address.trim();
+    // A bracketed literal is how an IPv6 address appears in a URL authority;
+    // `URL.hostname` hands it back still bracketed.
+    const bare = trimmed.startsWith('[') && trimmed.endsWith(']')
+        ? trimmed.slice(1, -1)
+        : trimmed;
+    if (isIPv4(bare))
+        return classifyIpv4(bare);
+    if (isIPv6(bare))
+        return classifyIpv6(bare);
+    // An IPv6 literal may carry a zone index (`fe80::1%eth0`), which the
+    // validator rejects; the address before the `%` is what matters.
+    const zoneSplit = bare.indexOf('%');
+    if (zoneSplit > 0) {
+        const withoutZone = bare.slice(0, zoneSplit);
+        if (isIPv6(withoutZone))
+            return classifyIpv6(withoutZone);
+    }
+    return undefined;
+}
+function classifyIpv4(address) {
+    const octets = address.split('.').map((part) => Number(part));
+    return classifyIpv4Octets(octets[0], octets[1], octets[2], octets[3]);
+}
+/**
+ * The IPv4 special-purpose ranges, in the order a classifier must read them
+ * (narrower ranges before the wider ones they sit inside). Every range that
+ * is not globally routable is restricted, not only the three RFC 1918
+ * blocks: a filter that stops at 10/8, 172.16/12 and 192.168/16 is the
+ * classic incomplete SSRF filter, walked around with 169.254.169.254 (the
+ * cloud metadata address) or a CGNAT address.
+ */
+function classifyIpv4Octets(a = 0, b = 0, c = 0, d = 0) {
+    if (a === 0)
+        return b === 0 && c === 0 && d === 0 ? 'unspecified' : 'reserved';
+    if (a === 127)
+        return 'loopback';
+    if (a === 10)
+        return 'private';
+    if (a === 172 && b >= 16 && b <= 31)
+        return 'private';
+    if (a === 192 && b === 168)
+        return 'private';
+    // Carrier-grade NAT (RFC 6598): a real LAN range on many networks.
+    if (a === 100 && b >= 64 && b <= 127)
+        return 'private';
+    // Link-local, which contains the cloud metadata address 169.254.169.254.
+    if (a === 169 && b === 254)
+        return 'link-local';
+    // IETF protocol assignments, and the benchmarking range.
+    if (a === 192 && b === 0 && c === 0)
+        return 'reserved';
+    if (a === 198 && (b === 18 || b === 19))
+        return 'reserved';
+    // Documentation ranges (RFC 5737).
+    if (a === 192 && b === 0 && c === 2)
+        return 'reserved';
+    if (a === 198 && b === 51 && c === 100)
+        return 'reserved';
+    if (a === 203 && b === 0 && c === 113)
+        return 'reserved';
+    if (a >= 224 && a <= 239)
+        return 'multicast';
+    if (a >= 240)
+        return 'reserved';
+    return 'public';
+}
+/**
+ * Expands `address` to its sixteen bytes. The validator has already accepted
+ * it, so this handles the two shapes that survive: groups of hex separated by
+ * `:` with at most one `::` run, and a trailing dotted-quad.
+ */
+function ipv6Bytes(address) {
+    let head = address;
+    let tail = '';
+    const doubleColon = address.indexOf('::');
+    if (doubleColon !== -1) {
+        head = address.slice(0, doubleColon);
+        tail = address.slice(doubleColon + 2);
+    }
+    const bytes = [];
+    const pushGroup = (group) => {
+        // A trailing dotted-quad stands for the last four bytes.
+        if (group.includes('.')) {
+            if (!isIPv4(group))
+                return false;
+            for (const part of group.split('.'))
+                bytes.push(Number(part));
+            return true;
+        }
+        const value = Number.parseInt(group, 16);
+        if (!Number.isFinite(value))
+            return false;
+        bytes.push((value >> 8) & 0xff, value & 0xff);
+        return true;
+    };
+    const headGroups = head === '' ? [] : head.split(':');
+    const tailGroups = tail === '' ? [] : tail.split(':');
+    for (const group of headGroups)
+        if (!pushGroup(group))
+            return undefined;
+    const tailBytes = [];
+    const savedLength = bytes.length;
+    for (const group of tailGroups)
+        if (!pushGroup(group))
+            return undefined;
+    tailBytes.push(...bytes.splice(savedLength));
+    if (doubleColon === -1) {
+        return bytes.length === 16 ? bytes : undefined;
+    }
+    const gap = 16 - bytes.length - tailBytes.length;
+    if (gap < 0)
+        return undefined;
+    return [...bytes, ...new Array(gap).fill(0), ...tailBytes];
+}
+function classifyIpv6(address) {
+    const bytes = ipv6Bytes(address.toLowerCase());
+    // Unparseable after the validator accepted it should be impossible; treat
+    // it as restricted anyway rather than letting an unknown shape through.
+    if (!bytes)
+        return 'reserved';
+    /** Byte `index`, or 0 past the end. `bytes` is always sixteen long here; this keeps the reads total under `noUncheckedIndexedAccess`. */
+    const at = (index) => bytes[index] ?? 0;
+    const allZero = (from, to) => bytes.slice(from, to).every((byte) => byte === 0);
+    if (allZero(0, 16))
+        return 'unspecified';
+    if (allZero(0, 15) && at(15) === 1)
+        return 'loopback';
+    // The three shapes that carry an IPv4 address inside an IPv6 one. Each is a
+    // documented SSRF bypass when a filter classifies the wrapper instead of
+    // the address it actually reaches, so each is classified by its payload.
+    // IPv4-mapped (::ffff:a.b.c.d) and IPv4-compatible (::a.b.c.d).
+    if (allZero(0, 10) && at(10) === 0xff && at(11) === 0xff) {
+        return classifyIpv4Octets(at(12), at(13), at(14), at(15));
+    }
+    if (allZero(0, 12)) {
+        return classifyIpv4Octets(at(12), at(13), at(14), at(15));
+    }
+    // 6to4 (2002::/16) embeds the IPv4 address in the next four bytes.
+    if (at(0) === 0x20 && at(1) === 0x02) {
+        return classifyIpv4Octets(at(2), at(3), at(4), at(5));
+    }
+    // NAT64 well-known prefix (64:ff9b::/96) embeds it in the last four.
+    if (at(0) === 0x00 &&
+        at(1) === 0x64 &&
+        at(2) === 0xff &&
+        at(3) === 0x9b &&
+        allZero(4, 12)) {
+        return classifyIpv4Octets(at(12), at(13), at(14), at(15));
+    }
+    // Unique-local (fc00::/7).
+    if ((at(0) & 0xfe) === 0xfc)
+        return 'private';
+    // Link-local (fe80::/10).
+    if (at(0) === 0xfe && (at(1) & 0xc0) === 0x80)
+        return 'link-local';
+    // Multicast (ff00::/8).
+    if (at(0) === 0xff)
+        return 'multicast';
+    // Documentation (2001:db8::/32) and the IETF protocol block (2001::/23).
+    if (at(0) === 0x20 && at(1) === 0x01 && at(2) === 0x0d && at(3) === 0xb8) {
+        return 'reserved';
+    }
+    return 'public';
+}

package/dist/run/isolate.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The seam between `spawnRun`'s watchdog logic and the KIND of isolate a
+ * host can actually create.
+ *
+ * `./run-host.ts` owns the part that must never differ between hosts: the
+ * external wall-clock watchdog, exactly-once settlement, and the
+ * never-rejects contract. What differs is what the runtime can spawn at
+ * all. A Node host (the VS Code extension's extension host) uses
+ * `node:worker_threads`. An Electron RENDERER, which is what an Obsidian
+ * plugin runs in, supports neither: `new Worker()` from `worker_threads`
+ * throws "The V8 platform used by this instance of Node does not support
+ * creating Workers", and forking a Node child via `ELECTRON_RUN_AS_NODE`
+ * was measured failing there too (no IPC round-trip; the child exited on
+ * SIGTRAP). A Web Worker is what remains, and it works.
+ *
+ * Both satisfy the normative requirement in docs/security.md: a dedicated
+ * isolate that an external watchdog can terminate from outside. They do
+ * NOT have equal capabilities, and the difference is documented rather than
+ * papered over: `maxOldGenerationSizeMb` bounds a worker thread's V8 heap,
+ * and a Web Worker accepts no such cap.
+ */
+/**
+ * One spawned isolate, reduced to what the watchdog needs. Deliberately
+ * event-callback shaped rather than promise-shaped: `spawnRun` settles on
+ * whichever of message/error/exit/watchdog fires FIRST, which a promise
+ * per event would make harder to express, not easier.
+ *
+ * Every implementation must guarantee: `kill()` is idempotent and safe on
+ * an isolate that already exited, and no callback fires after `kill()`
+ * resolves the run (late events are harmless anyway, since `spawnRun`
+ * guards settlement, but an implementation should not rely on that).
+ */
+export interface RunIsolate {
+    /**
+     * Hands the job to the isolate. MAY THROW synchronously — a structured
+     * clone of an uncloneable payload does exactly that — and `spawnRun`
+     * catches it, so an implementation must not swallow it into a silent
+     * no-op that would leave the run hanging until the watchdog.
+     */
+    send(job: unknown): void;
+    /** Terminates the isolate. Called by the watchdog and again on settle; must tolerate both. */
+    kill(): void;
+    onMessage(listener: (message: unknown) => void): void;
+    onError(listener: (error: unknown) => void): void;
+    /** `code` is `null` where the runtime does not report one (a Web Worker never does). */
+    onExit(listener: (code: number | null) => void): void;
+}
+export interface SpawnIsolateOptions {
+    /** The entry the isolate loads — resolved by the host, never guessed here (see `./run-host.ts`'s `defaultWorkerPath`). */
+    entryPath: string;
+    /** Node `execArgv` for a worker-thread isolate; meaningless to a Web Worker, which ignores it. */
+    execArgv?: string[];
+    /** V8 old-space cap in MB. A worker thread honors it; a Web Worker cannot, and says so in its own doc comment. */
+    maxOldGenerationSizeMb: number;
+}
+/** Creates one isolate per run. Injected via `SpawnRunOptions.spawnIsolate`; defaults to the worker-thread implementation. */
+export type IsolateSpawner = (options: SpawnIsolateOptions) => RunIsolate;

package/dist/run/isolate.js

@@ -0,0 +1,22 @@
+/**
+ * The seam between `spawnRun`'s watchdog logic and the KIND of isolate a
+ * host can actually create.
+ *
+ * `./run-host.ts` owns the part that must never differ between hosts: the
+ * external wall-clock watchdog, exactly-once settlement, and the
+ * never-rejects contract. What differs is what the runtime can spawn at
+ * all. A Node host (the VS Code extension's extension host) uses
+ * `node:worker_threads`. An Electron RENDERER, which is what an Obsidian
+ * plugin runs in, supports neither: `new Worker()` from `worker_threads`
+ * throws "The V8 platform used by this instance of Node does not support
+ * creating Workers", and forking a Node child via `ELECTRON_RUN_AS_NODE`
+ * was measured failing there too (no IPC round-trip; the child exited on
+ * SIGTRAP). A Web Worker is what remains, and it works.
+ *
+ * Both satisfy the normative requirement in docs/security.md: a dedicated
+ * isolate that an external watchdog can terminate from outside. They do
+ * NOT have equal capabilities, and the difference is documented rather than
+ * papered over: `maxOldGenerationSizeMb` bounds a worker thread's V8 heap,
+ * and a Web Worker accepts no such cap.
+ */
+export {};

package/dist/run/lua-resolver.d.ts

@@ -0,0 +1,21 @@
+import type { PackModuleResolver } from '@markii/lua';
+/**
+ * Pack namespace -> (bundle-jail-normalized module path, always ending in
+ * `.lua`) -> Lua source text. Produced by `./pack-scripts.ts` on the
+ * extension host and carried into the worker as `RunJob.packModules`.
+ */
+export type PackModulesMap = Readonly<Record<string, Readonly<Record<string, string>>>>;
+/**
+ * Builds a `PackModuleResolver` (`@markii/lua`) backed by a pre-loaded
+ * `PackModulesMap`. Every lookup is read with `Object.hasOwn` only (never
+ * bare indexing) so a pack namespace or module path shaped like
+ * `__proto__`/`constructor` can never resolve through the prototype chain,
+ * matching this codebase's hostile-map discipline throughout
+ * `@markii/pack`/`@markii/bundle`.
+ *
+ * Returns `undefined` (a clean "no such module", per `PackModuleResolver`'s
+ * own contract) for: an unconfigured pack namespace, a module path the
+ * bundle-jail rejects (traversal, absolute path, null byte, backslash), or
+ * a module path not present in the map. Never throws.
+ */
+export declare function createPackModuleResolver(modules: PackModulesMap): PackModuleResolver;

package/dist/run/lua-resolver.js

@@ -0,0 +1,63 @@
+/**
+ * The pure half of the Run path's `PackModuleResolver` (`@markii/lua`'s
+ * `require.ts`): a synchronous, in-memory lookup over a pre-loaded map of
+ * pack Lua source text. `vscode`-free and dependency-free beyond
+ * `@markii/bundle`'s path jail, so it is unit-testable directly.
+ *
+ * WHY pre-loaded rather than reading files live: the resolver runs on the
+ * `worker_thread` the Run path spawns per run (`run/worker-entry.ts`),
+ * which has no filesystem access of its own — by design, the worker's only
+ * inputs are the serializable `RunJob` message the extension host posts to
+ * it (docs/security.md's isolate model treats the worker as running
+ * untrusted script content). So the extension host reads every pack's
+ * `scripts/*.lua` files ahead of time (`./pack-scripts.ts`), and this
+ * module's map is exactly that pre-read content, structurally cloned into
+ * the job. `require "packName/modulePath"` then resolves with no I/O at
+ * all inside the worker.
+ */
+import { normalizeBundlePath } from '@markii/bundle';
+/**
+ * Normalizes a `require "packName/modulePath"` module path the same way
+ * `./pack-scripts.ts` normalized it while building the map: reject any
+ * path-jail violation (`..`, an absolute path, a null byte, a backslash —
+ * see `@markii/bundle`'s `normalizeBundlePath`) and append `.lua` when the
+ * caller didn't already write one, matching `@markii/lua`'s own bundle-local
+ * `require` convention. Returns `undefined` for anything the jail rejects —
+ * never throws, so a hostile or malformed module path degrades to the same
+ * "no such module" outcome an ordinary miss gets.
+ */
+function normalizeModulePath(modulePath) {
+    const withExtension = modulePath.endsWith('.lua')
+        ? modulePath
+        : `${modulePath}.lua`;
+    const result = normalizeBundlePath(withExtension);
+    return result.ok ? result.path : undefined;
+}
+/**
+ * Builds a `PackModuleResolver` (`@markii/lua`) backed by a pre-loaded
+ * `PackModulesMap`. Every lookup is read with `Object.hasOwn` only (never
+ * bare indexing) so a pack namespace or module path shaped like
+ * `__proto__`/`constructor` can never resolve through the prototype chain,
+ * matching this codebase's hostile-map discipline throughout
+ * `@markii/pack`/`@markii/bundle`.
+ *
+ * Returns `undefined` (a clean "no such module", per `PackModuleResolver`'s
+ * own contract) for: an unconfigured pack namespace, a module path the
+ * bundle-jail rejects (traversal, absolute path, null byte, backslash), or
+ * a module path not present in the map. Never throws.
+ */
+export function createPackModuleResolver(modules) {
+    return (packName, modulePath) => {
+        if (!Object.hasOwn(modules, packName))
+            return undefined;
+        const packModules = modules[packName];
+        if (packModules == null)
+            return undefined;
+        const normalized = normalizeModulePath(modulePath);
+        if (normalized === undefined)
+            return undefined;
+        if (!Object.hasOwn(packModules, normalized))
+            return undefined;
+        return packModules[normalized];
+    };
+}

package/dist/run/net-bridge-worker.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The WORKER half of the net bridge (see `./net-bridge.ts` for the
+ * protocol and the host half).
+ *
+ * Separate from its other half for one reason: it needs
+ * `@markii/lua`'s `netProviderDenial` to rebrand a host-side refusal, and
+ * that import pulls the whole WebAssembly Lua engine in behind it. The
+ * worker bundle contains that engine anyway; a host bundle must not.
+ */
+import { type NetProvider } from '@markii/lua';
+import { type NetBridgeRequest } from './net-bridge.js';
+/**
+ * The worker-side `NetProvider`: every call becomes one request message and
+ * resolves when its reply arrives. `post` on the returned object is what
+ * the worker uses to send; the caller routes incoming replies through
+ * `handleMessage`.
+ *
+ * There is deliberately NO timeout here. The run's wall-clock budget is
+ * already enforced from outside the isolate by `run-host.ts`'s watchdog,
+ * which terminates the whole worker; a second, inner timeout would only
+ * add a way for the two to disagree about whether a run is still alive.
+ */
+export declare function createNetBridge(post: (message: NetBridgeRequest) => void): {
+    provider: NetProvider;
+    handleMessage: (message: unknown) => void;
+};

package/dist/run/net-bridge-worker.js

@@ -0,0 +1,66 @@
+/**
+ * The WORKER half of the net bridge (see `./net-bridge.ts` for the
+ * protocol and the host half).
+ *
+ * Separate from its other half for one reason: it needs
+ * `@markii/lua`'s `netProviderDenial` to rebrand a host-side refusal, and
+ * that import pulls the whole WebAssembly Lua engine in behind it. The
+ * worker bundle contains that engine anyway; a host bundle must not.
+ */
+import { netProviderDenial } from '@markii/lua';
+import { isNetBridgeReply } from './net-bridge.js';
+/**
+ * The worker-side `NetProvider`: every call becomes one request message and
+ * resolves when its reply arrives. `post` on the returned object is what
+ * the worker uses to send; the caller routes incoming replies through
+ * `handleMessage`.
+ *
+ * There is deliberately NO timeout here. The run's wall-clock budget is
+ * already enforced from outside the isolate by `run-host.ts`'s watchdog,
+ * which terminates the whole worker; a second, inner timeout would only
+ * add a way for the two to disagree about whether a run is still alive.
+ */
+export function createNetBridge(post) {
+    let nextId = 1;
+    const pending = new Map();
+    const request = (method, url, body) => new Promise((resolve, reject) => {
+        const id = nextId++;
+        pending.set(id, { resolve, reject });
+        try {
+            post({
+                kind: 'markii:net-request',
+                id,
+                method,
+                url,
+                ...(body !== undefined ? { body } : {}),
+            });
+        }
+        catch (error) {
+            pending.delete(id);
+            reject(error);
+        }
+    });
+    return {
+        provider: {
+            get: (url) => request('get', url),
+            post: (url, body) => request('post', url, body),
+            patch: (url, body) => request('patch', url, body),
+        },
+        handleMessage: (message) => {
+            if (!isNetBridgeReply(message))
+                return;
+            const waiter = pending.get(message.id);
+            if (!waiter)
+                return;
+            pending.delete(message.id);
+            if (message.ok && message.response) {
+                waiter.resolve(message.response);
+                return;
+            }
+            const text = message.error ?? 'network request failed';
+            // Rebrand a host-side policy refusal so `@markii/lua` classifies it
+            // exactly as it would have inside a Node worker.
+            waiter.reject(message.denied ? netProviderDenial(text) : new Error(text));
+        },
+    };
+}

package/dist/run/net-bridge.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The network half of a Web Worker isolate.
+ *
+ * A Web Worker has no `node:https` and no `node:dns`, so the pinned
+ * request that closes the DNS-rebinding gap (issue #10, docs/security.md)
+ * cannot run inside one. Rather than drop pinning for hosts that only have
+ * Web Workers, the request moves OUT of the isolate: the worker asks its
+ * host to perform it, and the host, which still has Node, runs exactly the
+ * same `createNetProvider` the worker-thread isolate always used.
+ *
+ * This is a security improvement, not a compromise. The allowlist and the
+ * pinning policy now live somewhere the sandboxed code cannot reach at
+ * all: an isolate with no network stack has nothing to bypass them with.
+ * What the worker can do is ask, and every ask is answered by the host's
+ * own provider, against the host's own allowlist.
+ *
+ * This file is the protocol and the HOST half. The worker half lives in
+ * `./net-bridge-worker.ts` because it needs `@markii/lua`'s denial brand,
+ * and a host bundle must not drag a WebAssembly Lua engine in behind a
+ * message type — see `./net-provider.ts` for the same reasoning applied to
+ * the pinned request itself.
+ */
+import type { NetProvider, NetResponse } from '@markii/lua';
+/** Worker -> host. `id` correlates the reply; `method` selects the provider call. */
+export interface NetBridgeRequest {
+    kind: 'markii:net-request';
+    id: number;
+    method: 'get' | 'post' | 'patch';
+    url: string;
+    body?: string;
+}
+/**
+ * Host -> worker. A failure crosses as a MESSAGE plus a `denied` flag, never
+ * as a structured-cloned `Error`: the branded denial `@markii/lua` checks
+ * for is a JS `Symbol` on an Error object, and a `Symbol` does not survive
+ * structured cloning. The flag is what lets the worker side rebuild a
+ * properly branded denial, so a host-side policy refusal still classifies
+ * as `'capability-denied'` rather than degrading to a generic script error.
+ */
+export interface NetBridgeReply {
+    kind: 'markii:net-reply';
+    id: number;
+    ok: boolean;
+    response?: NetResponse;
+    error?: string;
+    denied?: boolean;
+}
+export declare function isNetBridgeRequest(value: unknown): value is NetBridgeRequest;
+export declare function isNetBridgeReply(value: unknown): value is NetBridgeReply;
+/**
+ * The host-side half: answers one request message using `provider`, and
+ * hands the reply to `post`. Never throws — a failure becomes a reply
+ * carrying the message, because a worker waiting on a reply that never
+ * comes would hang until the watchdog kills it.
+ */
+export declare function serveNetRequest(request: NetBridgeRequest, provider: NetProvider, post: (reply: NetBridgeReply) => void): Promise<void>;

package/dist/run/net-bridge.js

@@ -0,0 +1,59 @@
+export function isNetBridgeRequest(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    return (v.kind === 'markii:net-request' &&
+        typeof v.id === 'number' &&
+        typeof v.url === 'string' &&
+        (v.method === 'get' || v.method === 'post' || v.method === 'patch'));
+}
+export function isNetBridgeReply(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    return v.kind === 'markii:net-reply' && typeof v.id === 'number';
+}
+/**
+ * The host-side half: answers one request message using `provider`, and
+ * hands the reply to `post`. Never throws — a failure becomes a reply
+ * carrying the message, because a worker waiting on a reply that never
+ * comes would hang until the watchdog kills it.
+ */
+export async function serveNetRequest(request, provider, post) {
+    try {
+        const call = request.method === 'get'
+            ? provider.get(request.url)
+            : request.method === 'post'
+                ? provider.post?.(request.url, request.body ?? '')
+                : provider.patch?.(request.url, request.body ?? '');
+        if (!call) {
+            post({
+                kind: 'markii:net-reply',
+                id: request.id,
+                ok: false,
+                error: `${request.method} is not available`,
+                denied: true,
+            });
+            return;
+        }
+        post({
+            kind: 'markii:net-reply',
+            id: request.id,
+            ok: true,
+            response: await call,
+        });
+    }
+    catch (error) {
+        post({
+            kind: 'markii:net-reply',
+            id: request.id,
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+            // Everything the host's provider refuses IS a policy denial: the
+            // provider's own failures are allowlist, redirect, size, and pinning
+            // refusals. Marking them so keeps the worker's classification
+            // identical to the in-worker case.
+            denied: true,
+        });
+    }
+}