@floegence/flowersec-core 0.27.0 → 2.0.0

package/dist/proxy/runtime.js

@@ -1,502 +1,408 @@
-import { DEFAULT_MAX_JSON_FRAME_BYTES, readJsonFrame, writeJsonFrame } from "../framing/jsonframe.js";
-import { createByteReader } from "../streamio/index.js";
+import { SDK_DEFAULTS } from "../defaults.js";
+import { readJsonFrame, writeJsonFrame } from "../framing/jsonframe.js";
 import { base64urlEncode } from "../utils/base64url.js";
 import { readU32be, u32be } from "../utils/bin.js";
-import { AbortError, FlowersecError, isFlowersecError } from "../utils/errors.js";
-import { CookieJar } from "./cookieJar.js";
-import { DEFAULT_MAX_BODY_BYTES, DEFAULT_MAX_CHUNK_BYTES, DEFAULT_MAX_WS_FRAME_BYTES, PROXY_KIND_HTTP1, PROXY_KIND_WS, PROXY_PROTOCOL_VERSION } from "./constants.js";
-import { filterRequestHeaders, filterResponseHeaders, filterWsOpenHeaders } from "./headerPolicy.js";
-class ProxyRuntimePolicyError extends Error {
-    status = 403;
-}
-function randomB64u(bytes) {
-    const b = new Uint8Array(bytes);
-    if (globalThis.crypto?.getRandomValues) {
-        globalThis.crypto.getRandomValues(b);
-    }
-    else {
-        for (let i = 0; i < b.length; i++)
-            b[i] = Math.floor(Math.random() * 256);
-    }
-    return base64urlEncode(b);
-}
-function pathOnly(path) {
-    const p = path.trim();
-    if (!p.startsWith("/"))
-        throw new Error("path must start with /");
-    if (p.startsWith("//"))
-        throw new Error("path must not start with //");
-    if (/[ \t\r\n]/.test(p))
-        throw new Error("path contains whitespace");
-    if (p.includes("://"))
-        throw new Error("path must not include scheme/host");
-    return p;
+import { SessionError } from "../public/contract.js";
+import { createStreamMetadata } from "../public/streamMetadata.js";
+import { ProxyByteReader, writeAll } from "./stream.js";
+const PROXY_HTTP_STREAM_KIND = "flowersec-proxy/http1";
+const PROXY_WEBSOCKET_STREAM_KIND = "flowersec-proxy/ws";
+const PROXY_WIRE_VERSION = 1;
+const DEFAULT_MAX_WS_BUFFERED_AMOUNT_BYTES = 4 * 1024 * 1024;
+const DEFAULT_MAX_CONCURRENT_HTTP_STREAMS = 24;
+const DEFAULT_MAX_QUEUED_HTTP_REQUESTS = 128;
+const DEFAULT_MAX_QUEUED_HTTP_BODY_BYTES = 64 * 1024 * 1024;
+class ProxyPolicyError extends Error {
 }
-function requestPathname(path) {
-    const q = path.indexOf("?");
-    return q >= 0 ? path.slice(0, q) : path;
+function randomID() {
+    const bytes = new Uint8Array(18);
+    if (globalThis.crypto?.getRandomValues !== undefined)
+        globalThis.crypto.getRandomValues(bytes);
+    else
+        for (let index = 0; index < bytes.length; index++)
+            bytes[index] = Math.floor(Math.random() * 256);
+    return base64urlEncode(bytes);
 }
-function cookiePathFromRequestPath(path) {
-    return requestPathname(path);
+function positiveLimit(name, input, fallback) {
+    if (input === undefined || input === 0)
+        return fallback;
+    if (!Number.isSafeInteger(input) || input < 0)
+        throw new TypeError(`${name} must be a non-negative safe integer`);
+    return input;
 }
-function normalizeTimeoutMs(timeoutMs) {
-    const v = Math.floor(timeoutMs ?? 0);
-    if (v < 0)
-        throw new Error("timeout_ms must be >= 0");
-    return v;
+function strictlyPositiveLimit(name, input, fallback) {
+    if (input === undefined)
+        return fallback;
+    if (!Number.isSafeInteger(input) || input <= 0)
+        throw new TypeError(`${name} must be a positive safe integer`);
+    return input;
 }
-function normalizeExternalOrigin(externalOriginRaw) {
-    if (typeof externalOriginRaw !== "string")
-        return undefined;
-    const externalOrigin = externalOriginRaw.trim();
-    if (externalOrigin === "")
-        return undefined;
-    let parsed;
-    try {
-        parsed = new URL(externalOrigin);
-    }
-    catch {
-        throw new Error("external_origin must be an http(s) origin");
+function normalizeTimeout(input) {
+    if (input === undefined)
+        return 0;
+    if (!Number.isSafeInteger(input) || input < 0 || input > SDK_DEFAULTS.proxy.maxTimeoutMs) {
+        throw new TypeError("timeoutMs must be within the proxy timeout contract");
     }
-    if ((parsed.protocol !== "http:" && parsed.protocol !== "https:") || parsed.host === "") {
-        throw new Error("external_origin must be an http(s) origin");
-    }
-    if (parsed.username !== "" || parsed.password !== "" || (parsed.pathname !== "" && parsed.pathname !== "/") || parsed.search !== "" || parsed.hash !== "") {
-        throw new Error("external_origin must be an origin without credentials, path, query, or fragment");
-    }
-    return parsed.origin;
+    return input;
 }
-function normalizeOptionalToken(name, input) {
-    if (input == null)
-        return undefined;
-    const s = String(input);
-    if (s === "")
-        return undefined;
-    if (s.trim() !== s || /[\s\u0000-\u001f\u007f]/.test(s)) {
-        throw new Error(`${name} must not contain whitespace or control characters`);
+function normalizePath(input) {
+    if (input !== input.trim() || !input.startsWith("/") || input.startsWith("//") || /[\u0000-\u0020]/u.test(input) || input.includes("://")) {
+        throw new TypeError("proxy path must be an origin-relative path");
     }
-    return s;
+    return input;
+}
+function pathName(path) {
+    const query = path.indexOf("?");
+    return query < 0 ? path : path.slice(0, query);
 }
-function normalizePathPolicyPrefixes(name, input) {
-    const out = [];
-    if (input == null || input.length === 0)
-        return out;
-    for (const raw of input) {
-        const s = pathOnly(String(raw ?? ""));
-        if (s.includes("?"))
-            throw new Error(`${name} must not include query`);
-        if (!out.includes(s))
-            out.push(s);
+function normalizePrefixes(name, values) {
+    const result = [];
+    for (const raw of values ?? []) {
+        const value = normalizePath(raw);
+        if (value.includes("?"))
+            throw new TypeError(`${name} must not include a query`);
+        if (!result.includes(value))
+            result.push(value);
     }
-    return out;
+    return Object.freeze(result);
 }
 function normalizePathPolicy(policy) {
     return {
-        allowedPathPrefixes: normalizePathPolicyPrefixes("pathPolicy.allowedPathPrefixes", policy?.allowedPathPrefixes),
-        deniedPathPrefixes: normalizePathPolicyPrefixes("pathPolicy.deniedPathPrefixes", policy?.deniedPathPrefixes),
-        allowedWebSocketPathPrefixes: normalizePathPolicyPrefixes("pathPolicy.allowedWebSocketPathPrefixes", policy?.allowedWebSocketPathPrefixes),
-        deniedWebSocketPathPrefixes: normalizePathPolicyPrefixes("pathPolicy.deniedWebSocketPathPrefixes", policy?.deniedWebSocketPathPrefixes),
+        allowedPathPrefixes: normalizePrefixes("allowedPathPrefixes", policy?.allowedPathPrefixes),
+        deniedPathPrefixes: normalizePrefixes("deniedPathPrefixes", policy?.deniedPathPrefixes),
+        allowedWebSocketPathPrefixes: normalizePrefixes("allowedWebSocketPathPrefixes", policy?.allowedWebSocketPathPrefixes),
+        deniedWebSocketPathPrefixes: normalizePrefixes("deniedWebSocketPathPrefixes", policy?.deniedWebSocketPathPrefixes),
     };
 }
-function assertPathPolicyAllows(kind, path, policy) {
-    const pathname = requestPathname(path);
-    const denied = kind === "websocket" ? [...policy.deniedPathPrefixes, ...policy.deniedWebSocketPathPrefixes] : policy.deniedPathPrefixes;
-    for (const prefix of denied) {
-        if (pathname.startsWith(prefix))
-            throw new ProxyRuntimePolicyError(`${kind} path is denied by proxy runtime policy`);
-    }
+function enforcePathPolicy(kind, path, policy) {
+    const candidate = pathName(path);
+    const denied = kind === "websocket"
+        ? [...policy.deniedPathPrefixes, ...policy.deniedWebSocketPathPrefixes]
+        : policy.deniedPathPrefixes;
+    if (denied.some((prefix) => candidate.startsWith(prefix)))
+        throw new ProxyPolicyError("proxy path denied");
     const allowed = kind === "websocket" && policy.allowedWebSocketPathPrefixes.length > 0
         ? policy.allowedWebSocketPathPrefixes
         : policy.allowedPathPrefixes;
-    if (allowed.length === 0)
-        return;
-    for (const prefix of allowed) {
-        if (pathname.startsWith(prefix))
-            return;
+    if (allowed.length > 0 && !allowed.some((prefix) => candidate.startsWith(prefix))) {
+        throw new ProxyPolicyError("proxy path not allowed");
+    }
+}
+function normalizeOrigin(input) {
+    if (input === undefined || input === "")
+        return undefined;
+    let parsed;
+    try {
+        parsed = new URL(input);
+    }
+    catch {
+        throw new TypeError("externalOrigin must be an HTTP origin");
+    }
+    if ((parsed.protocol !== "http:" && parsed.protocol !== "https:") || parsed.origin !== input || parsed.username !== "" || parsed.password !== "") {
+        throw new TypeError("externalOrigin must be an HTTP origin");
     }
-    throw new ProxyRuntimePolicyError(`${kind} path is not allowed by proxy runtime policy`);
+    return input;
 }
-function normalizeMaxBytes(name, v, defaultValue) {
-    if (v == null)
-        return defaultValue;
-    if (!Number.isFinite(v))
-        throw new Error(`${name} must be a finite number`);
-    const n = Math.floor(v);
-    if (!Number.isSafeInteger(n))
-        throw new Error(`${name} must be a safe integer`);
-    if (n < 0)
-        throw new Error(`${name} must be >= 0`);
-    if (n === 0)
-        return defaultValue;
-    return n;
+function normalizeToken(input) {
+    if (input === undefined || input === "")
+        return undefined;
+    if (input !== input.trim() || /[\u0000-\u0020\u007f]/u.test(input) || input.length > 256) {
+        throw new TypeError("runtimeRegistrationToken is invalid");
+    }
+    return input;
 }
-const DEFAULT_MAX_CONCURRENT_HTTP_STREAMS = 24;
-const DEFAULT_MAX_QUEUED_HTTP_REQUESTS = 128;
-const DEFAULT_MAX_QUEUED_HTTP_BODY_BYTES = 64 * (1 << 20);
-const DEFAULT_MAX_WS_BUFFERED_AMOUNT_BYTES = 4 * (1 << 20);
-function normalizePositiveLimit(name, value, defaultValue) {
-    if (value == null)
-        return defaultValue;
-    if (!Number.isFinite(value) || !Number.isSafeInteger(value) || value <= 0) {
-        throw new Error(`${name} must be a positive safe integer`);
+const BASE_REQUEST_HEADERS = new Set(["accept", "accept-language", "content-type", "if-match", "if-none-match", "range"]);
+const BASE_RESPONSE_HEADERS = new Set(["accept-ranges", "cache-control", "content-disposition", "content-language", "content-range", "content-type", "etag", "expires", "last-modified", "location"]);
+const FORBIDDEN_HEADERS = new Set(["authorization", "connection", "cookie", "host", "keep-alive", "proxy-authorization", "set-cookie", "transfer-encoding", "upgrade"]);
+function normalizeHeaderNames(values) {
+    const result = new Set();
+    for (const raw of values ?? []) {
+        const value = raw.toLowerCase().trim();
+        if (!/^[!#$%&'*+\-.^_`|~0-9a-z]+$/u.test(value) || FORBIDDEN_HEADERS.has(value)) {
+            throw new TypeError("proxy header allowlist contains a forbidden name");
+        }
+        result.add(value);
     }
-    return value;
+    return result;
 }
-function normalizeNonNegativeLimit(name, value, defaultValue) {
-    if (value == null)
-        return defaultValue;
-    if (!Number.isFinite(value) || !Number.isSafeInteger(value) || value < 0) {
-        throw new Error(`${name} must be a non-negative safe integer`);
+function filterHeaders(input, base, extra) {
+    const result = [];
+    for (const entry of input) {
+        if (typeof entry?.name !== "string" || typeof entry?.value !== "string")
+            continue;
+        const name = entry.name.toLowerCase().trim();
+        if ((!base.has(name) && !extra.has(name)) || FORBIDDEN_HEADERS.has(name) || /[\r\n]/u.test(entry.value))
+            continue;
+        result.push(Object.freeze({ name, value: entry.value }));
     }
-    return value;
+    return result;
 }
-class HttpStreamAdmission {
-    path;
-    maxConcurrent;
-    maxQueued;
-    maxQueuedBodyBytes;
+function parseRuntimeRequest(raw) {
+    const headers = Array.isArray(raw.headers) ? raw.headers.filter((entry) => typeof entry === "object" && entry !== null && typeof entry.name === "string" && typeof entry.value === "string") : [];
+    const body = raw.body instanceof ArrayBuffer ? raw.body : undefined;
+    return {
+        id: typeof raw.id === "string" ? raw.id : "",
+        method: typeof raw.method === "string" ? raw.method : "GET",
+        path: typeof raw.path === "string" ? raw.path : "",
+        headers,
+        ...(typeof raw.external_origin === "string" ? { externalOrigin: raw.external_origin } : {}),
+        ...(raw.response_flow_control === "chunk_credit_v2" ? { responseFlowControl: "chunk_credit_v2" } : {}),
+        ...(body === undefined ? {} : { body }),
+    };
+}
+class StreamAdmission {
+    concurrent;
+    queued;
+    queuedBodyBytes;
     active = 0;
-    pending = [];
-    pendingBodyBytes = 0;
+    queuedBytes = 0;
     closed = false;
-    constructor(path, maxConcurrent, maxQueued, maxQueuedBodyBytes) {
-        this.path = path;
-        this.maxConcurrent = maxConcurrent;
-        this.maxQueued = maxQueued;
-        this.maxQueuedBodyBytes = maxQueuedBodyBytes;
+    queue = [];
+    constructor(concurrent, queued, queuedBodyBytes) {
+        this.concurrent = concurrent;
+        this.queued = queued;
+        this.queuedBodyBytes = queuedBodyBytes;
     }
-    acquire(bodyBytes, signal) {
+    acquire(bytes, signal) {
         if (this.closed)
-            return Promise.reject(this.closedError());
-        if (signal?.aborted)
-            return Promise.reject(this.abortedError());
-        if (this.active < this.maxConcurrent && this.pending.length === 0) {
+            return Promise.reject(new SessionError("closed"));
+        if (signal?.aborted === true)
+            return Promise.reject(new SessionError("canceled"));
+        if (this.active < this.concurrent && this.queue.length === 0) {
             this.active++;
-            return Promise.resolve(this.createRelease());
-        }
-        if (this.pending.length >= this.maxQueued) {
-            return Promise.reject(new FlowersecError({
-                path: this.path,
-                stage: "yamux",
-                code: "resource_exhausted",
-                message: "proxy runtime HTTP request queue is full",
-            }));
+            return Promise.resolve(this.releaseFunction());
         }
-        if (this.pendingBodyBytes + bodyBytes > this.maxQueuedBodyBytes) {
-            return Promise.reject(new FlowersecError({
-                path: this.path,
-                stage: "yamux",
-                code: "resource_exhausted",
-                message: "proxy runtime HTTP request body queue is full",
-            }));
+        if (this.queue.length >= this.queued || this.queuedBytes + bytes > this.queuedBodyBytes) {
+            return Promise.reject(new SessionError("resource_exhausted"));
         }
         return new Promise((resolve, reject) => {
-            const waiter = {
-                bodyBytes,
-                resolve,
-                reject,
+            const entry = {
+                bytes,
                 ...(signal === undefined ? {} : { signal }),
+                resolve,
+                reject: (error) => reject(error),
             };
-            waiter.onAbort = () => {
-                const index = this.pending.indexOf(waiter);
+            const onAbort = () => {
+                const index = this.queue.indexOf(entry);
                 if (index < 0)
                     return;
-                this.pending.splice(index, 1);
-                this.pendingBodyBytes = Math.max(0, this.pendingBodyBytes - waiter.bodyBytes);
-                this.cleanupWaiter(waiter);
-                reject(this.abortedError());
+                this.queue.splice(index, 1);
+                this.queuedBytes -= bytes;
+                reject(new SessionError("canceled"));
             };
-            signal?.addEventListener("abort", waiter.onAbort, { once: true });
-            this.pending.push(waiter);
-            this.pendingBodyBytes += bodyBytes;
+            signal?.addEventListener("abort", onAbort, { once: true });
+            this.queue.push(entry);
+            this.queuedBytes += bytes;
         });
     }
     close() {
         if (this.closed)
             return;
         this.closed = true;
-        for (const waiter of this.pending.splice(0)) {
-            this.pendingBodyBytes = Math.max(0, this.pendingBodyBytes - waiter.bodyBytes);
-            this.cleanupWaiter(waiter);
-            waiter.reject(this.closedError());
-        }
+        for (const entry of this.queue.splice(0))
+            entry.reject(new SessionError("closed"));
+        this.queuedBytes = 0;
     }
-    assertOpen() {
-        if (this.closed)
-            throw this.closedError();
-    }
-    createRelease() {
+    releaseFunction() {
         let released = false;
         return () => {
             if (released)
                 return;
             released = true;
-            this.active = Math.max(0, this.active - 1);
+            this.active--;
             this.drain();
         };
     }
     drain() {
-        while (!this.closed && this.active < this.maxConcurrent && this.pending.length > 0) {
-            const waiter = this.pending.shift();
-            this.pendingBodyBytes = Math.max(0, this.pendingBodyBytes - waiter.bodyBytes);
-            this.cleanupWaiter(waiter);
-            if (waiter.signal?.aborted) {
-                waiter.reject(this.abortedError());
+        while (!this.closed && this.active < this.concurrent && this.queue.length > 0) {
+            const entry = this.queue.shift();
+            this.queuedBytes -= entry.bytes;
+            if (entry.signal?.aborted === true) {
+                entry.reject(new SessionError("canceled"));
                 continue;
             }
             this.active++;
-            waiter.resolve(this.createRelease());
-        }
-    }
-    cleanupWaiter(waiter) {
-        if (waiter.onAbort != null) {
-            waiter.signal?.removeEventListener("abort", waiter.onAbort);
+            entry.resolve(this.releaseFunction());
         }
     }
-    abortedError() {
-        return new AbortError("proxy HTTP request canceled while waiting for stream admission");
-    }
-    closedError() {
-        return new FlowersecError({
-            path: this.path,
-            stage: "close",
-            code: "not_connected",
-            message: "proxy runtime is disposed",
-        });
+}
+async function writeChunks(stream, body, chunkBytes, maxBodyBytes, signal) {
+    if (body.length > maxBodyBytes)
+        throw new SessionError("resource_exhausted");
+    for (let offset = 0; offset < body.length; offset += chunkBytes) {
+        const chunk = body.subarray(offset, Math.min(body.length, offset + chunkBytes));
+        await writeAll(stream, u32be(chunk.length), { signal });
+        await writeAll(stream, chunk, { signal });
     }
+    await writeAll(stream, u32be(0), { signal });
 }
-async function writeChunkFrames(stream, body, chunkSize, maxBodyBytes) {
-    if (maxBodyBytes > 0 && body.length > maxBodyBytes)
-        throw new Error("request body too large");
-    const n = Math.max(1, Math.floor(chunkSize));
-    let off = 0;
-    while (off < body.length) {
-        const end = Math.min(body.length, off + n);
-        const chunk = body.subarray(off, end);
-        await stream.write(u32be(chunk.length));
-        await stream.write(chunk);
-        off = end;
+async function* readChunks(reader, maxChunkBytes, maxBodyBytes) {
+    let total = 0;
+    while (true) {
+        const length = readU32be(await reader.readExactly(4), 0);
+        if (length === 0)
+            return;
+        if (length > maxChunkBytes || total + length > maxBodyBytes)
+            throw new SessionError("resource_exhausted");
+        total += length;
+        yield await reader.readExactly(length);
     }
-    await stream.write(u32be(0));
 }
-async function readChunkFrames(reader, maxChunkBytes, maxBodyBytes) {
-    async function* gen() {
-        let total = 0;
-        while (true) {
-            const lenBuf = await reader.readExactly(4);
-            const n = readU32be(lenBuf, 0);
-            if (n === 0)
-                return;
-            if (maxChunkBytes > 0 && n > maxChunkBytes)
-                throw new Error("response chunk too large");
-            total += n;
-            if (maxBodyBytes > 0 && total > maxBodyBytes)
-                throw new Error("response body too large");
-            const payload = await reader.readExactly(n);
-            yield payload;
-        }
+function publicFailure(error) {
+    if (error instanceof ProxyPolicyError)
+        return { status: 403, code: "policy_denied", message: "proxy request denied" };
+    if (error instanceof SessionError && (error.code === "resource_exhausted" || error.code === "closed" || error.code === "going_away")) {
+        return { status: 503, code: error.code, message: "proxy service unavailable" };
     }
-    return gen();
+    if (error instanceof SessionError && error.code === "canceled")
+        return { status: 499, code: "canceled", message: "proxy request canceled" };
+    return { status: 502, code: "operation_failed", message: "proxy request failed" };
 }
-export function createProxyRuntime(opts) {
-    const client = opts.client;
-    const cookieJar = opts.cookieJar ?? new CookieJar();
-    const maxJsonFrameBytes = normalizeMaxBytes("maxJsonFrameBytes", opts.maxJsonFrameBytes, DEFAULT_MAX_JSON_FRAME_BYTES);
-    const maxChunkBytes = normalizeMaxBytes("maxChunkBytes", opts.maxChunkBytes, DEFAULT_MAX_CHUNK_BYTES);
-    const maxBodyBytes = normalizeMaxBytes("maxBodyBytes", opts.maxBodyBytes, DEFAULT_MAX_BODY_BYTES);
-    const maxWsFrameBytes = normalizeMaxBytes("maxWsFrameBytes", opts.maxWsFrameBytes, DEFAULT_MAX_WS_FRAME_BYTES);
-    const maxWsBufferedAmountBytes = normalizeMaxBytes("maxWsBufferedAmountBytes", opts.maxWsBufferedAmountBytes, DEFAULT_MAX_WS_BUFFERED_AMOUNT_BYTES);
-    const maxConcurrentHttpStreams = normalizePositiveLimit("maxConcurrentHttpStreams", opts.maxConcurrentHttpStreams, DEFAULT_MAX_CONCURRENT_HTTP_STREAMS);
-    const maxQueuedHttpRequests = normalizeNonNegativeLimit("maxQueuedHttpRequests", opts.maxQueuedHttpRequests, DEFAULT_MAX_QUEUED_HTTP_REQUESTS);
-    const maxQueuedHttpBodyBytes = normalizeNonNegativeLimit("maxQueuedHttpBodyBytes", opts.maxQueuedHttpBodyBytes, DEFAULT_MAX_QUEUED_HTTP_BODY_BYTES);
-    const httpStreamAdmission = new HttpStreamAdmission(client.path, maxConcurrentHttpStreams, maxQueuedHttpRequests, maxQueuedHttpBodyBytes);
-    const timeoutMs = normalizeTimeoutMs(opts.timeoutMs);
-    const extraRequestHeaders = opts.extraRequestHeaders ?? [];
-    const extraResponseHeaders = opts.extraResponseHeaders ?? [];
-    const extraWsHeaders = opts.extraWsHeaders ?? [];
-    const pathPolicy = normalizePathPolicy(opts.pathPolicy);
-    const externalOriginOverride = normalizeExternalOrigin(opts.externalOrigin);
-    const runtimeRegistrationToken = normalizeOptionalToken("runtimeRegistrationToken", opts.runtimeRegistrationToken);
-    const registerRuntime = () => {
-        void ensureServiceWorkerRuntimeRegistered({
-            timeoutMs: 2_000,
-            ...(runtimeRegistrationToken === undefined ? {} : { runtimeRegistrationToken }),
-        }).catch(() => {
-            // Best-effort: controllerchange will retry once the active Service Worker is ready.
-        });
-    };
-    const onMessage = (ev) => {
-        const data = ev.data;
-        if (data == null || typeof data !== "object")
-            return;
-        if (data.type !== "flowersec-proxy:fetch")
+export function createProxyRuntime(options) {
+    if (options.session === null || typeof options.session !== "object" || typeof options.session.openStream !== "function") {
+        throw new TypeError("proxy runtime requires a Session");
+    }
+    const maxJsonFrameBytes = positiveLimit("maxJsonFrameBytes", options.maxJsonFrameBytes, SDK_DEFAULTS.proxy.maxJsonFrameBytes);
+    const maxChunkBytes = positiveLimit("maxChunkBytes", options.maxChunkBytes, SDK_DEFAULTS.proxy.maxChunkBytes);
+    const maxBodyBytes = positiveLimit("maxBodyBytes", options.maxBodyBytes, SDK_DEFAULTS.proxy.maxBodyBytes);
+    const maxWsFrameBytes = positiveLimit("maxWsFrameBytes", options.maxWsFrameBytes, SDK_DEFAULTS.proxy.maxWsFrameBytes);
+    const maxWsBufferedAmountBytes = positiveLimit("maxWsBufferedAmountBytes", options.maxWsBufferedAmountBytes, DEFAULT_MAX_WS_BUFFERED_AMOUNT_BYTES);
+    const maxConcurrentHttpStreams = strictlyPositiveLimit("maxConcurrentHttpStreams", options.maxConcurrentHttpStreams, DEFAULT_MAX_CONCURRENT_HTTP_STREAMS);
+    const maxQueuedHttpRequests = positiveLimit("maxQueuedHttpRequests", options.maxQueuedHttpRequests, DEFAULT_MAX_QUEUED_HTTP_REQUESTS);
+    const maxQueuedHttpBodyBytes = positiveLimit("maxQueuedHttpBodyBytes", options.maxQueuedHttpBodyBytes, DEFAULT_MAX_QUEUED_HTTP_BODY_BYTES);
+    const timeoutMs = normalizeTimeout(options.timeoutMs);
+    const pathPolicy = normalizePathPolicy(options.pathPolicy);
+    const externalOrigin = normalizeOrigin(options.externalOrigin);
+    const runtimeRegistrationToken = normalizeToken(options.runtimeRegistrationToken);
+    const requestExtra = normalizeHeaderNames(options.extraRequestHeaders);
+    const responseExtra = normalizeHeaderNames(options.extraResponseHeaders);
+    const webSocketExtra = normalizeHeaderNames(options.extraWebSocketHeaders);
+    const admission = new StreamAdmission(maxConcurrentHttpStreams, maxQueuedHttpRequests, maxQueuedHttpBodyBytes);
+    let disposed = false;
+    const register = () => void ensureServiceWorkerRuntimeRegistered({
+        timeoutMs: 2_000,
+        ...(runtimeRegistrationToken === undefined ? {} : { runtimeRegistrationToken }),
+    }).catch(() => undefined);
+    const serviceWorker = globalThis.navigator?.serviceWorker;
+    const onMessage = (event) => {
+        if (event.data === null || typeof event.data !== "object" || event.data.type !== "flowersec-proxy:fetch")
             return;
-        const msg = data;
-        const port = ev.ports?.[0];
-        if (!port)
+        const port = event.ports?.[0];
+        if (port === undefined)
             return;
-        dispatchFetch(msg.req, port);
+        dispatchFetch(parseRuntimeRequest(event.data.req), port);
     };
-    const sw = globalThis.navigator?.serviceWorker;
-    sw?.addEventListener("message", onMessage);
-    sw?.addEventListener("controllerchange", registerRuntime);
-    registerRuntime();
-    const dispatchFetch = (req, port) => {
-        const ac = new AbortController();
-        let stream = null;
-        let releaseAdmission = null;
-        const usesResponseCredits = req.response_flow_control === "chunk_credit_v1";
-        let responseCreditAvailable = false;
-        let responseCreditResolve = null;
-        const wakeResponseCreditWaiter = () => {
-            const resolve = responseCreditResolve;
-            responseCreditResolve = null;
-            resolve?.();
-        };
-        port.onmessage = (ev) => {
-            const m = ev.data;
-            if (!m || typeof m !== "object")
-                return;
-            if (m.type === "flowersec-proxy:abort") {
-                responseCreditAvailable = false;
-                ac.abort("aborted");
-                wakeResponseCreditWaiter();
-                return;
+    serviceWorker?.addEventListener("message", onMessage);
+    serviceWorker?.addEventListener("controllerchange", register);
+    register();
+    function dispatchFetch(request, port) {
+        const controller = new AbortController();
+        let stream;
+        let release;
+        let credit = request.responseFlowControl !== "chunk_credit_v2";
+        let creditWake;
+        port.onmessage = (event) => {
+            if (event.data?.type === "flowersec-proxy:abort") {
+                controller.abort();
+                creditWake?.();
             }
-            if (usesResponseCredits && m.type === "flowersec-proxy:response_credit") {
-                responseCreditAvailable = true;
-                wakeResponseCreditWaiter();
+            else if (event.data?.type === "flowersec-proxy:response_credit") {
+                credit = true;
+                creditWake?.();
             }
         };
-        const waitForResponseCredit = async () => {
-            if (!usesResponseCredits)
-                return;
-            if (ac.signal.aborted)
-                throw new AbortError("aborted");
-            while (!responseCreditAvailable) {
-                if (ac.signal.aborted)
-                    throw new AbortError("aborted");
-                await new Promise((resolve) => {
-                    responseCreditResolve = resolve;
-                });
+        const waitForCredit = async () => {
+            while (!credit) {
+                if (controller.signal.aborted)
+                    throw new SessionError("canceled");
+                await new Promise((resolve) => { creditWake = resolve; });
+                creditWake = undefined;
             }
-            if (ac.signal.aborted)
-                throw new AbortError("aborted");
-            responseCreditAvailable = false;
+            credit = request.responseFlowControl !== "chunk_credit_v2";
         };
         void (async () => {
             try {
-                const path = pathOnly(req.path);
-                assertPathPolicyAllows("http", path, pathPolicy);
-                const requestID = req.id.trim() !== "" ? req.id : randomB64u(18);
-                const externalOrigin = externalOriginOverride ?? normalizeExternalOrigin(req.external_origin);
-                const body = req.body != null ? new Uint8Array(req.body) : new Uint8Array();
-                if (maxBodyBytes > 0 && body.length > maxBodyBytes)
-                    throw new Error("request body too large");
-                releaseAdmission = await httpStreamAdmission.acquire(body.byteLength, ac.signal);
-                httpStreamAdmission.assertOpen();
-                stream = await client.openStream(PROXY_KIND_HTTP1, { signal: ac.signal });
-                const reader = createByteReader(stream, { signal: ac.signal });
-                const filteredReqHeaders = filterRequestHeaders(req.headers, { extraAllowed: extraRequestHeaders });
-                const cookieHeader = cookieJar.getCookieHeader(cookiePathFromRequestPath(path));
-                const reqHeaders = cookieHeader === "" ? filteredReqHeaders : [...filteredReqHeaders, { name: "cookie", value: cookieHeader }];
-                await writeJsonFrame(stream, {
-                    v: PROXY_PROTOCOL_VERSION,
+                if (disposed)
+                    throw new SessionError("closed");
+                const path = normalizePath(request.path);
+                enforcePathPolicy("http", path, pathPolicy);
+                const body = request.body === undefined ? new Uint8Array() : new Uint8Array(request.body);
+                release = await admission.acquire(body.length, controller.signal);
+                stream = await options.session.openStream(PROXY_HTTP_STREAM_KIND, {
+                    signal: controller.signal,
+                    metadata: createStreamMetadata({ protocol: "flowersec.proxy.http", version: 2 }),
+                });
+                const reader = new ProxyByteReader(stream, { signal: controller.signal });
+                const requestID = request.id.trim() === "" ? randomID() : request.id;
+                const headers = filterHeaders(request.headers, BASE_REQUEST_HEADERS, requestExtra);
+                const requestOrigin = externalOrigin ?? normalizeOrigin(request.externalOrigin);
+                await writeJsonFrame({ write: async (data) => await writeAll(stream, data, { signal: controller.signal }) }, {
+                    v: PROXY_WIRE_VERSION,
                     request_id: requestID,
-                    method: req.method,
+                    method: request.method.toUpperCase(),
                     path,
-                    headers: reqHeaders,
-                    ...(externalOrigin === undefined ? {} : { external_origin: externalOrigin }),
-                    timeout_ms: timeoutMs
+                    headers,
+                    ...(requestOrigin === undefined ? {} : { external_origin: requestOrigin }),
+                    ...(timeoutMs === 0 ? {} : { timeout_ms: timeoutMs }),
                 });
-                await writeChunkFrames(stream, body, Math.min(64 * 1024, maxChunkBytes), maxBodyBytes);
-                const respMeta = (await readJsonFrame(reader, maxJsonFrameBytes));
-                if (respMeta.v !== PROXY_PROTOCOL_VERSION || respMeta.request_id !== requestID) {
-                    throw new Error("invalid upstream response meta");
-                }
-                if (!respMeta.ok) {
-                    const msg = respMeta.error?.message ?? "upstream error";
-                    port.postMessage({
-                        type: "flowersec-proxy:response_error",
-                        status: 502,
-                        ...(respMeta.error?.code === undefined ? {} : { code: respMeta.error.code }),
-                        message: msg,
-                    });
-                    await stream.reset(new Error(msg));
-                    stream = null;
-                    return;
+                await writeChunks(stream, body, maxChunkBytes, maxBodyBytes, controller.signal);
+                const response = await readJsonFrame(reader, maxJsonFrameBytes);
+                if (response.v !== PROXY_WIRE_VERSION || response.request_id !== requestID || response.ok !== true || !Number.isInteger(response.status)) {
+                    throw new Error("invalid proxy response");
                 }
-                const status = Math.max(0, Math.floor(respMeta.status ?? 502));
-                const rawHeaders = Array.isArray(respMeta.headers) ? respMeta.headers : [];
-                const { passthrough, setCookie } = filterResponseHeaders(rawHeaders, { extraAllowed: extraResponseHeaders });
-                cookieJar.updateFromSetCookieHeaders(setCookie, path);
-                port.postMessage({ type: "flowersec-proxy:response_meta", status, headers: passthrough });
-                const chunks = await readChunkFrames(reader, maxChunkBytes, maxBodyBytes);
-                for await (const chunk of chunks) {
-                    await waitForResponseCredit();
-                    if (ac.signal.aborted)
-                        throw new AbortError("aborted");
-                    // Always transfer an ArrayBuffer (SharedArrayBuffer is not transferable).
-                    const ab = chunk.slice().buffer;
-                    port.postMessage({ type: "flowersec-proxy:response_chunk", data: ab }, [ab]);
+                const headersOut = filterHeaders(response.headers ?? [], BASE_RESPONSE_HEADERS, responseExtra);
+                port.postMessage({ type: "flowersec-proxy:response_meta", status: response.status, headers: headersOut });
+                for await (const chunk of readChunks(reader, maxChunkBytes, maxBodyBytes)) {
+                    await waitForCredit();
+                    const data = chunk.slice().buffer;
+                    port.postMessage({ type: "flowersec-proxy:response_chunk", data }, [data]);
                 }
                 port.postMessage({ type: "flowersec-proxy:response_end" });
                 await stream.close();
-                stream = null;
+                stream = undefined;
             }
-            catch (e) {
-                const msg = e instanceof Error ? e.message : String(e);
-                const code = isFlowersecError(e) ? e.code : undefined;
-                const status = e instanceof ProxyRuntimePolicyError
-                    ? e.status
-                    : code === "resource_exhausted" || code === "not_connected"
-                        ? 503
-                        : 502;
-                port.postMessage({
-                    type: "flowersec-proxy:response_error",
-                    status,
-                    ...(code === undefined ? {} : { code }),
-                    message: msg,
-                });
-                await stream?.reset(new Error(msg));
+            catch (error) {
+                const failure = publicFailure(error);
+                port.postMessage({ type: "flowersec-proxy:response_error", ...failure });
+                await stream?.reset().catch(() => undefined);
             }
             finally {
-                wakeResponseCreditWaiter();
-                releaseAdmission?.();
-                try {
-                    port.close();
-                }
-                catch {
-                    // Best-effort.
-                }
+                release?.();
+                port.close();
             }
         })();
-    };
-    async function openWebSocketStream(pathRaw, wsOpts = {}) {
-        const path = pathOnly(pathRaw);
-        assertPathPolicyAllows("websocket", path, pathPolicy);
-        const openOpts = wsOpts.signal ? { signal: wsOpts.signal } : undefined;
-        const stream = await client.openStream(PROXY_KIND_WS, openOpts);
-        const reader = createByteReader(stream, openOpts);
-        const cookie = cookieJar.getCookieHeader(cookiePathFromRequestPath(path));
-        const headers = [];
-        const protos = wsOpts.protocols?.filter((p) => p.trim() !== "") ?? [];
-        if (protos.length > 0)
-            headers.push({ name: "sec-websocket-protocol", value: protos.join(", ") });
-        if (cookie !== "")
-            headers.push({ name: "cookie", value: cookie });
-        const filtered = filterWsOpenHeaders(headers, { extraAllowed: extraWsHeaders });
-        await writeJsonFrame(stream, { v: PROXY_PROTOCOL_VERSION, conn_id: randomB64u(18), path, headers: filtered });
-        const resp = (await readJsonFrame(reader, maxJsonFrameBytes));
-        if (resp.v !== PROXY_PROTOCOL_VERSION || resp.ok !== true) {
-            const msg = resp.error?.message ?? "upstream ws open failed";
-            await stream.reset(new Error(msg));
-            throw new Error(msg);
+    }
+    async function openWebSocketStream(input, openOptions = {}) {
+        if (disposed)
+            throw new SessionError("closed");
+        const path = normalizePath(input);
+        enforcePathPolicy("websocket", path, pathPolicy);
+        const stream = await options.session.openStream(PROXY_WEBSOCKET_STREAM_KIND, {
+            ...(openOptions.signal === undefined ? {} : { signal: openOptions.signal }),
+            metadata: createStreamMetadata({ protocol: "flowersec.proxy.websocket", version: 2 }),
+        });
+        try {
+            const protocols = (openOptions.protocols ?? []).filter((value) => value.trim() !== "" && value === value.trim());
+            const headers = filterHeaders(protocols.length === 0 ? [] : [{ name: "sec-websocket-protocol", value: protocols.join(", ") }], new Set(["sec-websocket-protocol"]), webSocketExtra);
+            await writeJsonFrame({ write: async (data) => await writeAll(stream, data, openOptions.signal === undefined ? {} : { signal: openOptions.signal }) }, {
+                v: PROXY_WIRE_VERSION,
+                conn_id: randomID(),
+                path,
+                headers,
+            });
+            const response = await readJsonFrame(new ProxyByteReader(stream, openOptions.signal === undefined ? {} : { signal: openOptions.signal }), maxJsonFrameBytes);
+            if (response.v !== PROXY_WIRE_VERSION || response.ok !== true || (response.protocol !== undefined && typeof response.protocol !== "string")) {
+                throw new Error("proxy WebSocket open failed");
+            }
+            return Object.freeze({ stream, protocol: response.protocol ?? "" });
+        }
+        catch (error) {
+            await stream.reset().catch(() => undefined);
+            throw error instanceof SessionError ? error : new SessionError("operation_failed");
         }
-        return { stream, protocol: resp.protocol ?? "" };
     }
-    return {
-        limits: {
+    return Object.freeze({
+        limits: Object.freeze({
             maxJsonFrameBytes,
             maxChunkBytes,
             maxBodyBytes,
@@ -505,74 +411,55 @@ export function createProxyRuntime(opts) {
             maxConcurrentHttpStreams,
             maxQueuedHttpRequests,
             maxQueuedHttpBodyBytes,
-        },
+        }),
         dispatchFetch,
         openWebSocketStream,
         dispose: () => {
-            httpStreamAdmission.close();
-            sw?.removeEventListener("message", onMessage);
-            sw?.removeEventListener("controllerchange", registerRuntime);
-        }
-    };
+            if (disposed)
+                return;
+            disposed = true;
+            admission.close();
+            serviceWorker?.removeEventListener("message", onMessage);
+            serviceWorker?.removeEventListener("controllerchange", register);
+        },
+    });
 }
-export async function ensureServiceWorkerRuntimeRegistered(opts = {}) {
-    const ctl = globalThis.navigator?.serviceWorker?.controller;
-    if (!ctl || typeof ctl.postMessage !== "function")
+export async function ensureServiceWorkerRuntimeRegistered(options = {}) {
+    const controller = globalThis.navigator?.serviceWorker?.controller;
+    if (controller === null || controller === undefined || typeof controller.postMessage !== "function")
         return;
-    const timeoutMs = Math.max(0, Math.floor(opts.timeoutMs ?? 2_000));
-    const runtimeRegistrationToken = normalizeOptionalToken("runtimeRegistrationToken", opts.runtimeRegistrationToken);
-    const ch = new MessageChannel();
+    const timeoutMs = options.timeoutMs ?? 2_000;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 0 || timeoutMs > 60_000)
+        throw new TypeError("invalid runtime registration timeout");
+    const token = normalizeToken(options.runtimeRegistrationToken);
+    const channel = new MessageChannel();
     await new Promise((resolve, reject) => {
-        let done = false;
-        let timer = null;
+        let settled = false;
         const finish = (error) => {
-            if (done)
+            if (settled)
                 return;
-            done = true;
-            if (timer != null)
+            settled = true;
+            if (timer !== undefined)
                 clearTimeout(timer);
-            ch.port1.onmessage = null;
-            ch.port1.onmessageerror = null;
-            try {
-                ch.port1.close();
-            }
-            catch {
-                // Best-effort.
-            }
-            if (error == null) {
-                resolve();
-                return;
-            }
-            reject(error instanceof Error ? error : new Error(String(error)));
+            channel.port1.close();
+            error === undefined ? resolve() : reject(error);
         };
-        ch.port1.onmessage = (ev) => {
-            const data = ev.data;
-            if (data == null || typeof data !== "object")
+        channel.port1.onmessage = (event) => {
+            if (event.data?.type !== "flowersec-proxy:register-runtime-ack")
                 return;
-            if (data.type !== "flowersec-proxy:register-runtime-ack")
-                return;
-            if (data.ok !== true) {
-                finish(new Error("service worker runtime registration was rejected"));
-                return;
-            }
-            finish();
+            finish(event.data.ok === true ? undefined : new Error("service worker runtime registration rejected"));
         };
-        ch.port1.onmessageerror = () => {
-            finish(new Error("service worker runtime registration failed"));
-        };
-        if (timeoutMs > 0) {
-            timer = setTimeout(() => {
-                finish(new Error("service worker runtime registration timed out"));
-            }, timeoutMs);
-        }
+        channel.port1.onmessageerror = () => finish(new Error("service worker runtime registration failed"));
+        const timer = timeoutMs === 0 ? undefined : setTimeout(() => finish(new Error("service worker runtime registration timed out")), timeoutMs);
         try {
-            ctl.postMessage({
+            controller.postMessage({
                 type: "flowersec-proxy:register-runtime",
-                ...(runtimeRegistrationToken === undefined ? {} : { token: runtimeRegistrationToken }),
-            }, [ch.port2]);
+                version: 2,
+                ...(token === undefined ? {} : { token }),
+            }, [channel.port2]);
         }
-        catch (error) {
-            finish(error);
+        catch {
+            finish(new Error("service worker runtime registration failed"));
         }
     });
 }