@inkbox/sdk 0.2.16 → 0.3.0

package/dist/tunnels/client/_url_forward.d.ts

@@ -0,0 +1,92 @@
+/**
+ * inkbox-tunnels/client/_url_forward.ts
+ *
+ * URL-forward HTTP proxy. Mirrors Python `_url_forward.py`.
+ *
+ * The discriminated-union return type is the type-system forcing
+ * function against materialize-then-check: a plain `{body: Buffer}`
+ * shape would push implementations toward buffering full responses
+ * before checking the cap, defeating the streaming guarantee. Both
+ * over-cap and upstream-error paths are values the runtime maps onto
+ * fixed on-wire response shapes — no exception-driven control flow.
+ */
+import type { Envelope } from "./_envelope.js";
+export type ForwardResult = {
+    kind: "ok";
+    status: number;
+    headers: Array<[string, string]>;
+    body: Buffer;
+} | {
+    kind: "too-large";
+    status: 502;
+    inkboxReason: "response-too-large";
+} | {
+    kind: "upstream-unreachable";
+    status: 502;
+    inkboxReason: "upstream-unreachable";
+};
+export interface ForwardOpts {
+    envelope: Envelope;
+    forwardTo: string;
+    publicHost: string;
+    /** Injectable for tests; defaults to global `fetch`. */
+    fetcher?: typeof fetch;
+    /** Cap on materialized outbound bodies. */
+    maxResponseBytes: number;
+    /** Optional abort signal — runtime ties this to its deadline. */
+    signal?: AbortSignal;
+    /**
+     * Verify the upstream's TLS certificate when ``forwardTo`` is
+     * ``https://``. Default ``true``. Has no effect for ``http://``.
+     */
+    verifyTls?: boolean;
+    /** Extra PEM CA bundle to trust for the upstream TLS connection. */
+    caBundle?: Buffer | string | null;
+    /**
+     * Per-runtime cache of undici Agent dispatchers used when TLS
+     * overrides are configured. Reuses connection pools across requests
+     * with the same (verifyTls, caBundle) tuple instead of allocating a
+     * fresh Agent — and timer — per request.
+     */
+    agentCache?: UndiciAgentCache;
+}
+/**
+ * Cache of undici ``Agent`` instances keyed by (verifyTls, caBundle).
+ * Returned dispatcher is opaque (`unknown`) so undici stays a
+ * type-only dependency at this surface — the runtime imports lazily.
+ */
+export interface UndiciAgentCache {
+    /**
+     * Return a cached Agent for these TLS settings, or create + cache one.
+     * Returns `null` if no override is needed (default trust + verify on).
+     */
+    get(verifyTls: boolean | undefined, caBundle: Buffer | string | null | undefined): Promise<unknown>;
+    /** Close every cached Agent. Idempotent. */
+    close(): Promise<void>;
+}
+/**
+ * Build a per-runtime undici Agent cache. Each unique
+ * (verifyTls, caBundle) combination gets one shared Agent. Closed in
+ * `TunnelRuntime.aclose()`.
+ */
+export declare function createUndiciAgentCache(): UndiciAgentCache;
+/**
+ * Prefix-join the envelope's path onto `forwardTo`'s base path.
+ * Mirrors Python `join_forward_path`.
+ */
+export declare function joinForwardPath(forwardTo: string, envelopePath: string): string;
+/**
+ * Build the headers we send to `forwardTo`. Strips hop-by-hop and
+ * inbound forwarded-for headers; injects Host, X-Forwarded-Host,
+ * X-Forwarded-Proto, X-Forwarded-For, Forwarded.
+ */
+export declare function buildForwardHeaders(envelope: Envelope, publicHost: string, targetHost: string): Array<[string, string]>;
+/**
+ * Forward an envelope to `forwardTo`. Streams the upstream response;
+ * bails as soon as the accumulated body exceeds `maxResponseBytes`.
+ *
+ * Caller is expected to have already validated the forward target and
+ * the envelope path, and materialized the inbound body.
+ */
+export declare function forwardEnvelopeToUrl(opts: ForwardOpts): Promise<ForwardResult>;
+//# sourceMappingURL=_url_forward.d.ts.map

package/dist/tunnels/client/_url_forward.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_url_forward.d.ts","sourceRoot":"","sources":["../../../src/tunnels/client/_url_forward.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAG/C,MAAM,MAAM,aAAa,GACrB;IACE,IAAI,EAAE,IAAI,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;CACd,GACD;IACE,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,EAAE,GAAG,CAAC;IACZ,YAAY,EAAE,oBAAoB,CAAC;CACpC,GACD;IACE,IAAI,EAAE,sBAAsB,CAAC;IAC7B,MAAM,EAAE,GAAG,CAAC;IACZ,YAAY,EAAE,sBAAsB,CAAC;CACtC,CAAC;AAEN,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,QAAQ,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,2CAA2C;IAC3C,gBAAgB,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAClC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,GAAG,CACD,SAAS,EAAE,OAAO,GAAG,SAAS,EAC9B,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAC3C,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,4CAA4C;IAC5C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,gBAAgB,CAmEzD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAU/E;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,QAAQ,EAClB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAuBzB;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,aAAa,CAAC,CAoHxB"}

package/dist/tunnels/client/_url_forward.js

@@ -0,0 +1,255 @@
+/**
+ * inkbox-tunnels/client/_url_forward.ts
+ *
+ * URL-forward HTTP proxy. Mirrors Python `_url_forward.py`.
+ *
+ * The discriminated-union return type is the type-system forcing
+ * function against materialize-then-check: a plain `{body: Buffer}`
+ * shape would push implementations toward buffering full responses
+ * before checking the cap, defeating the streaming guarantee. Both
+ * over-cap and upstream-error paths are values the runtime maps onto
+ * fixed on-wire response shapes — no exception-driven control flow.
+ */
+import { HOP_BY_HOP_REQUEST } from "./_protocol.js";
+/**
+ * Build a per-runtime undici Agent cache. Each unique
+ * (verifyTls, caBundle) combination gets one shared Agent. Closed in
+ * `TunnelRuntime.aclose()`.
+ */
+export function createUndiciAgentCache() {
+    const agents = new Map();
+    let closed = false;
+    const keyFor = (verifyTls, caBundle) => {
+        const v = verifyTls === false ? "off" : "on";
+        let cb = "none";
+        if (caBundle !== null && caBundle !== undefined) {
+            const buf = typeof caBundle === "string"
+                ? Buffer.from(caBundle, "utf-8")
+                : caBundle;
+            // crypto import is lazy below; do a coarse digest via length
+            // initially, then refine with real hash inside `get` after we've
+            // imported `node:crypto`.
+            cb = `len:${buf.length}`;
+        }
+        return `${v}|${cb}`;
+    };
+    return {
+        async get(verifyTls, caBundle) {
+            if (closed)
+                return undefined;
+            const noOverride = verifyTls !== false &&
+                (caBundle === null || caBundle === undefined);
+            if (noOverride)
+                return undefined;
+            // Stable hash of caBundle so two distinct CAs of the same length
+            // don't alias.
+            const { createHash } = await import("node:crypto");
+            let cbHash = "none";
+            if (caBundle !== null && caBundle !== undefined) {
+                const buf = typeof caBundle === "string"
+                    ? Buffer.from(caBundle, "utf-8")
+                    : caBundle;
+                cbHash = createHash("sha256").update(buf).digest("hex").slice(0, 16);
+            }
+            const key = `${verifyTls === false ? "off" : "on"}|${cbHash}`;
+            void keyFor;
+            const existing = agents.get(key);
+            if (existing !== undefined)
+                return existing;
+            const undici = await import("undici");
+            const { buildUpstreamTlsConnectOpts } = await import("./_upstream_tls.js");
+            const connect = buildUpstreamTlsConnectOpts({
+                verify: verifyTls,
+                caBundle: caBundle ?? null,
+            });
+            const agent = new undici.Agent({ connect });
+            agents.set(key, agent);
+            return agent;
+        },
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            const ps = [];
+            for (const a of agents.values()) {
+                const ag = a;
+                if (ag && typeof ag.close === "function") {
+                    try {
+                        ps.push(ag.close());
+                    }
+                    catch { /* swallow */ }
+                }
+            }
+            agents.clear();
+            await Promise.allSettled(ps);
+        },
+    };
+}
+/**
+ * Prefix-join the envelope's path onto `forwardTo`'s base path.
+ * Mirrors Python `join_forward_path`.
+ */
+export function joinForwardPath(forwardTo, envelopePath) {
+    const parsed = new URL(forwardTo);
+    let basePath = parsed.pathname;
+    if (basePath.endsWith("/"))
+        basePath = basePath.slice(0, -1);
+    const queryIdx = envelopePath.indexOf("?");
+    let rawPath = queryIdx >= 0 ? envelopePath.slice(0, queryIdx) : envelopePath;
+    const query = queryIdx >= 0 ? envelopePath.slice(queryIdx) : "";
+    if (!rawPath.startsWith("/"))
+        rawPath = "/" + rawPath;
+    const fullPath = basePath ? `${basePath}${rawPath}` : rawPath;
+    return `${parsed.protocol}//${parsed.host}${fullPath}${query}`;
+}
+/**
+ * Build the headers we send to `forwardTo`. Strips hop-by-hop and
+ * inbound forwarded-for headers; injects Host, X-Forwarded-Host,
+ * X-Forwarded-Proto, X-Forwarded-For, Forwarded.
+ */
+export function buildForwardHeaders(envelope, publicHost, targetHost) {
+    const out = [];
+    out.push(["host", targetHost]);
+    out.push(["x-forwarded-host", publicHost]);
+    out.push(["x-forwarded-proto", "https"]);
+    if (envelope.forwardedForIp) {
+        out.push(["x-forwarded-for", envelope.forwardedForIp]);
+        out.push(["forwarded", `for=${envelope.forwardedForIp}`]);
+    }
+    const seenSpecial = new Set([
+        "host",
+        "x-forwarded-host",
+        "x-forwarded-proto",
+        "x-forwarded-for",
+        "forwarded",
+    ]);
+    for (const [k, v] of envelope.forwardedHeaders) {
+        const kl = k.toLowerCase();
+        if (HOP_BY_HOP_REQUEST.has(kl))
+            continue;
+        if (seenSpecial.has(kl))
+            continue;
+        out.push([k, v]);
+    }
+    return out;
+}
+/**
+ * Forward an envelope to `forwardTo`. Streams the upstream response;
+ * bails as soon as the accumulated body exceeds `maxResponseBytes`.
+ *
+ * Caller is expected to have already validated the forward target and
+ * the envelope path, and materialized the inbound body.
+ */
+export async function forwardEnvelopeToUrl(opts) {
+    const targetUrl = joinForwardPath(opts.forwardTo, opts.envelope.path);
+    const parsedTarget = new URL(opts.forwardTo);
+    const targetHost = parsedTarget.host;
+    const headers = buildForwardHeaders(opts.envelope, opts.publicHost, targetHost);
+    // For https:// upstreams with TLS overrides, get a cached undici
+    // dispatcher (or build one ad-hoc if the runtime didn't supply a
+    // cache, e.g. legacy callers / direct unit tests). Lazy-loaded so
+    // the default http:// path stays out of undici and edge bundles
+    // don't pull undici in unconditionally.
+    const isHttps = parsedTarget.protocol === "https:";
+    const wantsTlsOverride = isHttps &&
+        (opts.verifyTls === false ||
+            (opts.caBundle !== null && opts.caBundle !== undefined));
+    let dispatcher = undefined;
+    if (wantsTlsOverride && opts.fetcher === undefined) {
+        if (opts.agentCache !== undefined) {
+            dispatcher = await opts.agentCache.get(opts.verifyTls, opts.caBundle ?? null);
+        }
+        else {
+            // No cache supplied — fall back to per-request Agent. Caller is
+            // responsible for closing if it cares; the runtime always passes
+            // a cache, so this branch is only hit by direct callers.
+            const undici = await import("undici");
+            const { buildUpstreamTlsConnectOpts } = await import("./_upstream_tls.js");
+            const connect = buildUpstreamTlsConnectOpts({
+                verify: opts.verifyTls,
+                caBundle: opts.caBundle ?? null,
+            });
+            dispatcher = new undici.Agent({ connect });
+        }
+    }
+    const fetcher = opts.fetcher ?? ((url, init) => {
+        // Node's fetch (undici-backed) honors `dispatcher` on the init.
+        const initWithDispatcher = dispatcher === undefined ? init ?? {} : { ...(init ?? {}), dispatcher };
+        return globalThis.fetch(url, initWithDispatcher);
+    });
+    const reqInit = {
+        method: opts.envelope.method,
+        headers,
+        // Empty bodies must not be passed for GET/HEAD.
+        body: opts.envelope.method === "GET" || opts.envelope.method === "HEAD"
+            ? undefined
+            : opts.envelope.body.length > 0
+                ? new Uint8Array(opts.envelope.body)
+                : undefined,
+        signal: opts.signal,
+        // Don't follow redirects automatically — let the user app's
+        // upstream decide. Matches the Python httpx behavior under stream().
+        redirect: "manual",
+    };
+    let response;
+    try {
+        response = await fetcher(targetUrl, reqInit);
+    }
+    catch {
+        return { kind: "upstream-unreachable", status: 502, inkboxReason: "upstream-unreachable" };
+    }
+    const reader = response.body?.getReader();
+    if (!reader) {
+        // No body — emit empty response.
+        return {
+            kind: "ok",
+            status: response.status,
+            headers: collectResponseHeaders(response.headers),
+            body: Buffer.alloc(0),
+        };
+    }
+    const chunks = [];
+    let total = 0;
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            const chunk = Buffer.from(value);
+            if (total + chunk.length > opts.maxResponseBytes) {
+                // Cap exceeded — cancel the upstream reader before any more
+                // bytes land in our buffer, matching Python's
+                // `oversize=True; break` shape.
+                await reader.cancel().catch(() => undefined);
+                return {
+                    kind: "too-large",
+                    status: 502,
+                    inkboxReason: "response-too-large",
+                };
+            }
+            chunks.push(chunk);
+            total += chunk.length;
+        }
+    }
+    catch {
+        return {
+            kind: "upstream-unreachable",
+            status: 502,
+            inkboxReason: "upstream-unreachable",
+        };
+    }
+    return {
+        kind: "ok",
+        status: response.status,
+        headers: collectResponseHeaders(response.headers),
+        body: chunks.length === 0 ? Buffer.alloc(0) : Buffer.concat(chunks, total),
+    };
+}
+function collectResponseHeaders(h) {
+    const out = [];
+    h.forEach((value, key) => {
+        out.push([key, value]);
+    });
+    return out;
+}
+//# sourceMappingURL=_url_forward.js.map

package/dist/tunnels/client/_url_forward.js.map

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

package/dist/tunnels/client/_validation.d.ts

@@ -0,0 +1,27 @@
+/**
+ * inkbox-tunnels/client/_validation.ts
+ *
+ * Path-traversal + forward-target validation for the data-plane runtime.
+ * Mirrors the Python ``_url_forward.py`` algorithms so the two SDKs
+ * accept and reject the same set of inputs.
+ */
+export declare class ForwardTargetRefused extends Error {
+    constructor(message: string);
+}
+/**
+ * Validate `forward_to` against the loopback-only allowlist.
+ *
+ * Default refuses any host that isn't a literal loopback form. Hostnames
+ * that *would* resolve to loopback are also refused (no DNS resolution
+ * happens here — that lets a rebinding-prone hostname slip a sensitive
+ * target past the check).
+ */
+export declare function validateForwardTarget(forwardTo: string, options?: {
+    allowRemoteForwarding?: boolean;
+}): void;
+/**
+ * Reject path-traversal evasion attempts. Returns `null` on success or
+ * the `inkbox-reason` string for the rejection.
+ */
+export declare function validateEnvelopePath(path: string): string | null;
+//# sourceMappingURL=_validation.d.ts.map

package/dist/tunnels/client/_validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_validation.d.ts","sourceRoot":"","sources":["../../../src/tunnels/client/_validation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;IAAE,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAAO,GAChD,IAAI,CAiCN;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA6BhE"}

package/dist/tunnels/client/_validation.js

@@ -0,0 +1,96 @@
+/**
+ * inkbox-tunnels/client/_validation.ts
+ *
+ * Path-traversal + forward-target validation for the data-plane runtime.
+ * Mirrors the Python ``_url_forward.py`` algorithms so the two SDKs
+ * accept and reject the same set of inputs.
+ */
+const LOOPBACK_LITERALS = new Set(["localhost", "127.0.0.1", "::1"]);
+export class ForwardTargetRefused extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ForwardTargetRefused";
+    }
+}
+/**
+ * Validate `forward_to` against the loopback-only allowlist.
+ *
+ * Default refuses any host that isn't a literal loopback form. Hostnames
+ * that *would* resolve to loopback are also refused (no DNS resolution
+ * happens here — that lets a rebinding-prone hostname slip a sensitive
+ * target past the check).
+ */
+export function validateForwardTarget(forwardTo, options = {}) {
+    if (options.allowRemoteForwarding === true)
+        return;
+    let parsed;
+    try {
+        parsed = new URL(forwardTo);
+    }
+    catch {
+        throw new ForwardTargetRefused(`forward_to is not a valid URL: ${forwardTo}`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new ForwardTargetRefused(`forward_to scheme must be http or https; got ${parsed.protocol}`);
+    }
+    const host = parsed.hostname.toLowerCase().replace(/^\[/, "").replace(/\]$/, "");
+    if (!host) {
+        throw new ForwardTargetRefused(`forward_to has no host: ${forwardTo}`);
+    }
+    if (LOOPBACK_LITERALS.has(host))
+        return;
+    // IPv4 in 127.0.0.0/8?
+    const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+    if (m) {
+        const a = Number(m[1]);
+        if (a === 127)
+            return;
+        throw new ForwardTargetRefused(`forward_to address ${host} is not loopback; pass ` +
+            "allowRemoteForwarding: true to bypass (review the SSRF tradeoff first)");
+    }
+    // ::1 already covered by the literals set; otherwise fall through.
+    throw new ForwardTargetRefused(`forward_to host ${host} is not a literal loopback address; pass ` +
+        "allowRemoteForwarding: true to bypass (review the SSRF tradeoff first)");
+}
+/**
+ * Reject path-traversal evasion attempts. Returns `null` on success or
+ * the `inkbox-reason` string for the rejection.
+ */
+export function validateEnvelopePath(path) {
+    const queryIdx = path.indexOf("?");
+    const rawPath = queryIdx >= 0 ? path.slice(0, queryIdx) : path;
+    const lowered = rawPath.toLowerCase();
+    if (lowered.includes("%2f") || lowered.includes("%5c"))
+        return "invalid-path";
+    let decoded;
+    try {
+        const pass1 = decodeURIComponent(rawPath);
+        if (pass1 !== rawPath) {
+            const pass2 = decodeURIComponent(pass1);
+            if (pass2 !== pass1)
+                return "invalid-path";
+            decoded = pass2;
+        }
+        else {
+            decoded = pass1;
+        }
+    }
+    catch {
+        return "invalid-path";
+    }
+    for (const segment of decoded.split("/")) {
+        if (segment === "." || segment === "..")
+            return "invalid-path";
+        // Some upstream frameworks treat raw backslash as a path separator.
+        // Reject it so `/static\..\secret` can't slip past split-on-/.
+        if (segment.includes("\\"))
+            return "invalid-path";
+        for (const ch of segment) {
+            const o = ch.charCodeAt(0);
+            if (o < 0x20 || o === 0x7f)
+                return "invalid-path";
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=_validation.js.map

package/dist/tunnels/client/_validation.js.map

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

package/dist/tunnels/client/_ws.d.ts

@@ -0,0 +1,149 @@
+/**
+ * inkbox-tunnels/client/_ws.ts
+ *
+ * In-process WebSocket session driver.
+ *
+ * Public types: {@link InkboxWebSocket}, {@link InkboxWsHandler},
+ * {@link WsAcceptDeadlineExceeded}, {@link WsProtocolMismatch},
+ * {@link WsClosed}.
+ *
+ * Internal types: {@link buildAcceptReply}, the lifecycle driver
+ * {@link dispatchWsUpgradeInProcess}.
+ *
+ */
+import type { Envelope } from "./_envelope.js";
+export declare class WsAcceptDeadlineExceeded extends Error {
+    constructor(message?: string);
+}
+export declare class WsProtocolMismatch extends Error {
+    constructor(requested: string, offered: ReadonlyArray<string>);
+}
+export declare class WsClosed extends Error {
+    constructor(message?: string);
+}
+export interface InkboxWebSocketAcceptOpts {
+    /** Optional subprotocol; must be one of `offeredProtocols`. */
+    protocol?: string;
+    /** Additional response headers (excluding hop-by-hop). */
+    headers?: Array<[string, string]>;
+}
+export interface InkboxWebSocket {
+    readonly url: string;
+    readonly headers: ReadonlyMap<string, string>;
+    readonly offeredProtocols: ReadonlyArray<string>;
+    /**
+     * Complete the upgrade handshake. If `protocol` is given, it MUST be
+     * one of `offeredProtocols` — otherwise rejects with
+     * `WsProtocolMismatch`. Resolves once the accept reply has been
+     * posted on the wire.
+     */
+    accept(opts?: InkboxWebSocketAcceptOpts): Promise<void>;
+    /**
+     * Send a message. Resolves when the outbound buffer drains. Rejects
+     * with `WsClosed` if `close()` has already been called.
+     */
+    send(data: string | Buffer): Promise<void>;
+    /**
+     * Send a CLOSE frame and tear down the bridge stream. Resolves once
+     * the CLOSE frame is on the wire. Subsequent `send()` calls reject
+     * with `WsClosed`.
+     */
+    close(code?: number, reason?: string): Promise<void>;
+    /**
+     * Inbound message stream. Completes cleanly (`done: true`) on a
+     * normal CLOSE frame from the peer. Throws on abnormal close.
+     */
+    [Symbol.asyncIterator](): AsyncIterator<string | Buffer>;
+}
+export type InkboxWsHandler = (ws: InkboxWebSocket) => Promise<void>;
+/**
+ * Parse a `Sec-WebSocket-Protocol` header into an ordered list of
+ * offered subprotocols. Comma-split, trimmed, empties dropped.
+ */
+export declare function parseOfferedSubprotocols(forwardedHeaders: ReadonlyArray<readonly [string, string]>): string[];
+/**
+ * Build the upgrade-reply headers the runtime posts back to
+ * `/_system/response/{requestId}` once the user's handler has called
+ * `accept()`.
+ *
+ * Hop-by-hop headers are stripped; an explicit `subprotocol` is added
+ * as `sec-websocket-protocol`.
+ */
+export declare function buildAcceptReply(acceptOpts: InkboxWebSocketAcceptOpts | undefined): Array<[string, string]>;
+/**
+ * Build the inbound headers map exposed to the user's handler. Strips
+ * hop-by-hop request headers; preserves the rest verbatim.
+ */
+export declare function buildInboundHeaders(envelope: Envelope): Map<string, string>;
+/**
+ * Bridge primitives — supplied by the runtime so this module stays
+ * unit-testable in isolation.
+ */
+export interface WsBridgeIO {
+    /**
+     * Send a chunk of WS-frame bytes on the bridge stream. Resolves when
+     * the chunk is on the wire (post-flow-control).
+     */
+    sendFrame(frame: Buffer): Promise<void>;
+    /**
+     * Async-iterate inbound h2 DATA chunks from the bridge stream.
+     * Completes when the bridge stream's `end` event fires; throws on a
+     * `reset` event.
+     */
+    recv(): AsyncIterableIterator<Buffer>;
+    /** Tear down the bridge stream cleanly. */
+    closeStream(): Promise<void>;
+    /** Post the upgrade reply (status + headers) to `/_system/response/{id}`. */
+    postUpgradeReply(headers: Array<[string, string]>): Promise<void>;
+    /** Reject the upgrade with a 4xx/5xx response. */
+    rejectUpgrade(status: number, reason: string): Promise<void>;
+}
+export interface DispatchWsOpts {
+    envelope: Envelope;
+    handler: InkboxWsHandler;
+    publicHost: string;
+    acceptDeadlineMs: number;
+    bridge: WsBridgeIO;
+}
+/**
+ * The full WS-upgrade lifecycle from envelope → handler → message
+ * pump → CLOSE. The runtime calls this from its dispatch loop after
+ * confirming the envelope is a `ws-upgrade` route kind.
+ */
+export declare function dispatchWsUpgradeInProcess(opts: DispatchWsOpts): Promise<void>;
+interface WsSessionOpts {
+    url: string;
+    headers: ReadonlyMap<string, string>;
+    offeredProtocols: ReadonlyArray<string>;
+    acceptDeadlineMs: number;
+    bridge: WsBridgeIO;
+}
+declare class WsSession implements InkboxWebSocket {
+    readonly url: string;
+    readonly headers: ReadonlyMap<string, string>;
+    readonly offeredProtocols: ReadonlyArray<string>;
+    private readonly bridge;
+    private readonly acceptDeadlineMs;
+    private acceptCalled;
+    private acceptResolved;
+    private acceptReply;
+    private closeRequested;
+    private closeResolved;
+    private inboundQueue;
+    private inboundWaiter;
+    private envelopeDecoder;
+    private frameDecoder;
+    constructor(opts: WsSessionOpts);
+    accept(opts?: InkboxWebSocketAcceptOpts): Promise<void>;
+    send(data: string | Buffer): Promise<void>;
+    close(code?: number, reason?: string): Promise<void>;
+    [Symbol.asyncIterator](): AsyncIterator<string | Buffer>;
+    run(handler: InkboxWsHandler): Promise<void>;
+    private runInboundPump;
+    private pushInbound;
+}
+export declare const __testing: {
+    WsSession: typeof WsSession;
+};
+export {};
+//# sourceMappingURL=_ws.d.ts.map

package/dist/tunnels/client/_ws.d.ts.map

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