@floegence/flowersec-core 0.6.0 → 0.7.0

package/dist/proxy/constants.d.ts

@@ -0,0 +1,8 @@
+export declare const PROXY_PROTOCOL_VERSION: 1;
+export declare const PROXY_KIND_HTTP1: "flowersec-proxy/http1";
+export declare const PROXY_KIND_WS: "flowersec-proxy/ws";
+export declare const DEFAULT_MAX_CHUNK_BYTES: number;
+export declare const DEFAULT_MAX_BODY_BYTES: number;
+export declare const DEFAULT_MAX_WS_FRAME_BYTES: number;
+export declare const DEFAULT_DEFAULT_TIMEOUT_MS = 30000;
+export declare const DEFAULT_MAX_TIMEOUT_MS: number;

package/dist/proxy/constants.js

@@ -0,0 +1,8 @@
+export const PROXY_PROTOCOL_VERSION = 1;
+export const PROXY_KIND_HTTP1 = "flowersec-proxy/http1";
+export const PROXY_KIND_WS = "flowersec-proxy/ws";
+export const DEFAULT_MAX_CHUNK_BYTES = 256 * 1024;
+export const DEFAULT_MAX_BODY_BYTES = 64 * 1024 * 1024;
+export const DEFAULT_MAX_WS_FRAME_BYTES = 1024 * 1024;
+export const DEFAULT_DEFAULT_TIMEOUT_MS = 30_000;
+export const DEFAULT_MAX_TIMEOUT_MS = 5 * 60_000;

package/dist/proxy/cookieJar.d.ts

@@ -0,0 +1,6 @@
+export declare class CookieJar {
+    private readonly cookies;
+    setCookie(setCookieHeader: string): void;
+    updateFromSetCookieHeaders(headers: readonly string[]): void;
+    getCookieHeader(path: string): string;
+}

package/dist/proxy/cookieJar.js

@@ -0,0 +1,88 @@
+function nowMs() {
+    return Date.now();
+}
+function parseCookieNameValue(s) {
+    const idx = s.indexOf("=");
+    if (idx <= 0)
+        return null;
+    const name = s.slice(0, idx).trim();
+    const value = s.slice(idx + 1).trim();
+    if (name === "")
+        return null;
+    return { name, value };
+}
+export class CookieJar {
+    cookies = new Map();
+    setCookie(setCookieHeader) {
+        const raw = setCookieHeader.trim();
+        if (raw === "")
+            return;
+        const parts = raw.split(";").map((p) => p.trim()).filter((p) => p !== "");
+        if (parts.length === 0)
+            return;
+        const nv = parseCookieNameValue(parts[0] ?? "");
+        if (nv == null)
+            return;
+        let path = "/";
+        let expiresAtMs;
+        for (let i = 1; i < parts.length; i++) {
+            const p = parts[i];
+            const lower = p.toLowerCase();
+            if (lower.startsWith("path=")) {
+                const v = p.slice("path=".length).trim();
+                if (v !== "")
+                    path = v;
+                continue;
+            }
+            if (lower.startsWith("max-age=")) {
+                const v = p.slice("max-age=".length).trim();
+                const n = Number.parseInt(v, 10);
+                if (!Number.isFinite(n))
+                    continue;
+                if (n <= 0) {
+                    this.cookies.delete(nv.name);
+                    return;
+                }
+                expiresAtMs = nowMs() + n * 1000;
+                continue;
+            }
+            if (lower.startsWith("expires=")) {
+                const v = p.slice("expires=".length).trim();
+                const t = Date.parse(v);
+                if (!Number.isFinite(t))
+                    continue;
+                expiresAtMs = t;
+                continue;
+            }
+        }
+        // Expired via Expires.
+        if (expiresAtMs != null && expiresAtMs <= nowMs()) {
+            this.cookies.delete(nv.name);
+            return;
+        }
+        if (expiresAtMs == null) {
+            this.cookies.set(nv.name, { name: nv.name, value: nv.value, path });
+        }
+        else {
+            this.cookies.set(nv.name, { name: nv.name, value: nv.value, path, expiresAtMs });
+        }
+    }
+    updateFromSetCookieHeaders(headers) {
+        for (const h of headers)
+            this.setCookie(h);
+    }
+    getCookieHeader(path) {
+        const now = nowMs();
+        const pairs = [];
+        for (const c of this.cookies.values()) {
+            if (c.expiresAtMs != null && c.expiresAtMs <= now) {
+                this.cookies.delete(c.name);
+                continue;
+            }
+            if (c.path !== "/" && !path.startsWith(c.path))
+                continue;
+            pairs.push(`${c.name}=${c.value}`);
+        }
+        return pairs.join("; ");
+    }
+}

package/dist/proxy/disableUpstreamServiceWorkerRegister.d.ts

@@ -0,0 +1 @@
+export declare function disableUpstreamServiceWorkerRegister(): void;

package/dist/proxy/disableUpstreamServiceWorkerRegister.js

@@ -0,0 +1,23 @@
+// disableUpstreamServiceWorkerRegister blocks upstream apps from registering their own Service Worker.
+//
+// This is required for runtime-mode proxying where a proxy SW must control the app scope.
+export function disableUpstreamServiceWorkerRegister() {
+    try {
+        const sw = globalThis.navigator?.serviceWorker;
+        if (!sw || typeof sw.register !== "function")
+            return;
+        const blocked = () => {
+            throw new Error("service worker register is disabled by flowersec-proxy runtime");
+        };
+        // Best-effort. Some environments may not allow overriding the property.
+        try {
+            sw.register = blocked;
+        }
+        catch {
+            // Ignore.
+        }
+    }
+    catch {
+        // Ignore.
+    }
+}

package/dist/proxy/headerPolicy.d.ts

@@ -0,0 +1,14 @@
+import type { Header } from "./types.js";
+export declare function normalizeHeaderName(name: string): string;
+export declare function isValidHeaderName(name: string): boolean;
+export declare function isSafeHeaderValue(value: string): boolean;
+export type FilterHeadersOptions = Readonly<{
+    extraAllowed?: readonly string[];
+}>;
+export declare function filterRequestHeaders(input: readonly Header[], opts?: FilterHeadersOptions): Header[];
+export type FilterResponseResult = Readonly<{
+    passthrough: Header[];
+    setCookie: string[];
+}>;
+export declare function filterResponseHeaders(input: readonly Header[], opts?: FilterHeadersOptions): FilterResponseResult;
+export declare function filterWsOpenHeaders(input: readonly Header[], opts?: FilterHeadersOptions): Header[];

package/dist/proxy/headerPolicy.js

@@ -0,0 +1,124 @@
+const DEFAULT_REQUEST_HEADER_ALLOWLIST = new Set([
+    "accept",
+    "accept-language",
+    "cache-control",
+    "content-type",
+    "if-match",
+    "if-modified-since",
+    "if-none-match",
+    "if-unmodified-since",
+    "pragma",
+    "range",
+    "x-requested-with"
+]);
+const DEFAULT_RESPONSE_HEADER_ALLOWLIST = new Set([
+    "cache-control",
+    "content-disposition",
+    "content-encoding",
+    "content-language",
+    "content-type",
+    "etag",
+    "expires",
+    "last-modified",
+    "location",
+    "pragma",
+    "vary",
+    "www-authenticate",
+    "set-cookie"
+]);
+const DEFAULT_WS_HEADER_ALLOWLIST = new Set(["sec-websocket-protocol", "cookie"]);
+export function normalizeHeaderName(name) {
+    return name.trim().toLowerCase();
+}
+export function isValidHeaderName(name) {
+    // Minimal RFC 7230 token validation; keep strict to avoid smuggling bugs.
+    for (let i = 0; i < name.length; i++) {
+        const c = name.charCodeAt(i);
+        const isAlpha = c >= 0x61 && c <= 0x7a;
+        const isDigit = c >= 0x30 && c <= 0x39;
+        if (isAlpha || isDigit)
+            continue;
+        // ! # $ % & ' * + - . ^ _ ` | ~
+        if (c === 0x21 || c === 0x23 || c === 0x24 || c === 0x25 || c === 0x26 || c === 0x27)
+            continue;
+        if (c === 0x2a || c === 0x2b || c === 0x2d || c === 0x2e)
+            continue;
+        if (c === 0x5e || c === 0x5f || c === 0x60 || c === 0x7c || c === 0x7e)
+            continue;
+        return false;
+    }
+    return name.length > 0;
+}
+export function isSafeHeaderValue(value) {
+    return !value.includes("\r") && !value.includes("\n");
+}
+function buildExtraAllowedSet(extraAllowed) {
+    if (extraAllowed == null || extraAllowed.length === 0)
+        return null;
+    const s = new Set();
+    for (const n of extraAllowed) {
+        const nn = normalizeHeaderName(n);
+        if (nn !== "" && isValidHeaderName(nn))
+            s.add(nn);
+    }
+    return s;
+}
+function isAllowed(allow, extra, name) {
+    return allow.has(name) || (extra != null && extra.has(name));
+}
+export function filterRequestHeaders(input, opts = {}) {
+    const extra = buildExtraAllowedSet(opts.extraAllowed);
+    const out = [];
+    for (const h of input) {
+        const name = normalizeHeaderName(h.name);
+        if (name === "" || !isValidHeaderName(name))
+            continue;
+        if (!isSafeHeaderValue(h.value))
+            continue;
+        // Never forward these from the client runtime.
+        if (name === "host" || name === "authorization")
+            continue;
+        // Cookie is injected by the runtime CookieJar (not copied from browser cookie store).
+        if (name === "cookie")
+            continue;
+        if (!isAllowed(DEFAULT_REQUEST_HEADER_ALLOWLIST, extra, name))
+            continue;
+        out.push({ name, value: h.value });
+    }
+    return out;
+}
+export function filterResponseHeaders(input, opts = {}) {
+    const extra = buildExtraAllowedSet(opts.extraAllowed);
+    const passthrough = [];
+    const setCookie = [];
+    for (const h of input) {
+        const name = normalizeHeaderName(h.name);
+        if (name === "" || !isValidHeaderName(name))
+            continue;
+        if (!isSafeHeaderValue(h.value))
+            continue;
+        if (!isAllowed(DEFAULT_RESPONSE_HEADER_ALLOWLIST, extra, name))
+            continue;
+        if (name === "set-cookie") {
+            setCookie.push(h.value);
+            continue;
+        }
+        passthrough.push({ name, value: h.value });
+    }
+    return { passthrough, setCookie };
+}
+export function filterWsOpenHeaders(input, opts = {}) {
+    const extra = buildExtraAllowedSet(opts.extraAllowed);
+    const out = [];
+    for (const h of input) {
+        const name = normalizeHeaderName(h.name);
+        if (name === "" || !isValidHeaderName(name))
+            continue;
+        if (!isSafeHeaderValue(h.value))
+            continue;
+        if (!isAllowed(DEFAULT_WS_HEADER_ALLOWLIST, extra, name))
+            continue;
+        out.push({ name, value: h.value });
+    }
+    return out;
+}

package/dist/proxy/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./constants.js";
+export * from "./types.js";
+export * from "./cookieJar.js";
+export * from "./runtime.js";
+export * from "./serviceWorker.js";
+export * from "./wsPatch.js";
+export * from "./disableUpstreamServiceWorkerRegister.js";

package/dist/proxy/index.js

@@ -0,0 +1,7 @@
+export * from "./constants.js";
+export * from "./types.js";
+export * from "./cookieJar.js";
+export * from "./runtime.js";
+export * from "./serviceWorker.js";
+export * from "./wsPatch.js";
+export * from "./disableUpstreamServiceWorkerRegister.js";

package/dist/proxy/runtime.d.ts

@@ -0,0 +1,33 @@
+import type { Client } from "../client.js";
+import type { YamuxStream } from "../yamux/stream.js";
+import { CookieJar } from "./cookieJar.js";
+export type ProxyRuntimeLimits = Readonly<{
+    maxJsonFrameBytes: number;
+    maxChunkBytes: number;
+    maxBodyBytes: number;
+    maxWsFrameBytes: number;
+}>;
+export type ProxyRuntime = Readonly<{
+    cookieJar: CookieJar;
+    limits: ProxyRuntimeLimits;
+    dispose: () => void;
+    openWebSocketStream: (path: string, opts?: Readonly<{
+        protocols?: readonly string[];
+        signal?: AbortSignal;
+    }>) => Promise<Readonly<{
+        stream: YamuxStream;
+        protocol: string;
+    }>>;
+}>;
+export type ProxyRuntimeOptions = Readonly<{
+    client: Client;
+    maxJsonFrameBytes?: number;
+    maxChunkBytes?: number;
+    maxBodyBytes?: number;
+    maxWsFrameBytes?: number;
+    timeoutMs?: number;
+    extraRequestHeaders?: readonly string[];
+    extraResponseHeaders?: readonly string[];
+    extraWsHeaders?: readonly string[];
+}>;
+export declare function createProxyRuntime(opts: ProxyRuntimeOptions): ProxyRuntime;

package/dist/proxy/runtime.js

@@ -0,0 +1,237 @@
+import { DEFAULT_MAX_JSON_FRAME_BYTES, readJsonFrame, writeJsonFrame } from "../framing/jsonframe.js";
+import { createByteReader } from "../streamio/index.js";
+import { base64urlEncode } from "../utils/base64url.js";
+import { readU32be, u32be } from "../utils/bin.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";
+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;
+}
+function cookiePathFromRequestPath(path) {
+    const q = path.indexOf("?");
+    return q >= 0 ? path.slice(0, q) : path;
+}
+function normalizeTimeoutMs(timeoutMs) {
+    const v = Math.floor(timeoutMs ?? 0);
+    if (v < 0)
+        throw new Error("timeout_ms must be >= 0");
+    return v;
+}
+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;
+}
+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;
+    }
+    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;
+        }
+    }
+    return gen();
+}
+export function createProxyRuntime(opts) {
+    const client = opts.client;
+    const 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 timeoutMs = normalizeTimeoutMs(opts.timeoutMs);
+    const extraRequestHeaders = opts.extraRequestHeaders ?? [];
+    const extraResponseHeaders = opts.extraResponseHeaders ?? [];
+    const extraWsHeaders = opts.extraWsHeaders ?? [];
+    const registerRuntime = () => {
+        try {
+            const ctl = globalThis.navigator?.serviceWorker?.controller;
+            ctl?.postMessage({ type: "flowersec-proxy:register-runtime" });
+        }
+        catch {
+            // Best-effort: runtime can still work if SW picks it via matchAll().
+        }
+    };
+    const onMessage = (ev) => {
+        const data = ev.data;
+        if (data == null || typeof data !== "object")
+            return;
+        if (data.type !== "flowersec-proxy:fetch")
+            return;
+        const msg = data;
+        const port = ev.ports?.[0];
+        if (!port)
+            return;
+        void handleFetch(msg.req, port);
+    };
+    const sw = globalThis.navigator?.serviceWorker;
+    sw?.addEventListener("message", onMessage);
+    sw?.addEventListener("controllerchange", registerRuntime);
+    registerRuntime();
+    async function handleFetch(req, port) {
+        const ac = new AbortController();
+        let stream = null;
+        port.onmessage = (ev) => {
+            const m = ev.data;
+            if (m && typeof m === "object" && m.type === "flowersec-proxy:abort") {
+                ac.abort("aborted");
+            }
+        };
+        try {
+            const path = pathOnly(req.path);
+            const requestID = req.id.trim() !== "" ? req.id : randomB64u(18);
+            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,
+                request_id: requestID,
+                method: req.method,
+                path,
+                headers: reqHeaders,
+                timeout_ms: timeoutMs
+            });
+            const body = req.body != null ? new Uint8Array(req.body) : new Uint8Array();
+            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, message: msg });
+                try {
+                    stream.reset(new Error(msg));
+                }
+                catch {
+                    // Best-effort.
+                }
+                stream = null;
+                return;
+            }
+            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);
+            port.postMessage({ type: "flowersec-proxy:response_meta", status, headers: passthrough });
+            const chunks = await readChunkFrames(reader, maxChunkBytes, maxBodyBytes);
+            for await (const chunk of chunks) {
+                // Always transfer an ArrayBuffer (SharedArrayBuffer is not transferable).
+                const ab = chunk.slice().buffer;
+                port.postMessage({ type: "flowersec-proxy:response_chunk", data: ab }, [ab]);
+            }
+            port.postMessage({ type: "flowersec-proxy:response_end" });
+            await stream.close();
+            stream = null;
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            port.postMessage({ type: "flowersec-proxy:response_error", status: 502, message: msg });
+            try {
+                stream?.reset(new Error(msg));
+            }
+            catch {
+                // Best-effort.
+            }
+        }
+        finally {
+            try {
+                port.close();
+            }
+            catch {
+                // Best-effort.
+            }
+        }
+    }
+    async function openWebSocketStream(pathRaw, wsOpts = {}) {
+        const path = pathOnly(pathRaw);
+        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";
+            try {
+                stream.reset(new Error(msg));
+            }
+            catch {
+                // Best-effort.
+            }
+            throw new Error(msg);
+        }
+        return { stream, protocol: resp.protocol ?? "" };
+    }
+    return {
+        cookieJar,
+        limits: { maxJsonFrameBytes, maxChunkBytes, maxBodyBytes, maxWsFrameBytes },
+        openWebSocketStream,
+        dispose: () => {
+            sw?.removeEventListener("message", onMessage);
+            sw?.removeEventListener("controllerchange", registerRuntime);
+        }
+    };
+}

package/dist/proxy/serviceWorker.d.ts

@@ -0,0 +1,9 @@
+export type ProxyServiceWorkerScriptOptions = Readonly<{
+    proxyPathPrefix?: string;
+    stripProxyPathPrefix?: boolean;
+    injectHTML?: Readonly<{
+        proxyModuleUrl: string;
+        runtimeGlobal?: string;
+    }>;
+}>;
+export declare function createProxyServiceWorkerScript(opts?: ProxyServiceWorkerScriptOptions): string;

package/dist/proxy/serviceWorker.js

@@ -0,0 +1,197 @@
+// createProxyServiceWorkerScript returns a Service Worker script that forwards fetches to a runtime
+// in a controlled window via postMessage + MessageChannel.
+//
+// The runtime side is implemented by createProxyRuntime(...) in this package.
+export function createProxyServiceWorkerScript(opts = {}) {
+    const proxyPathPrefix = opts.proxyPathPrefix ?? "";
+    const stripProxyPathPrefix = opts.stripProxyPathPrefix ?? false;
+    const injectHTML = opts.injectHTML ?? null;
+    const proxyModuleUrl = injectHTML?.proxyModuleUrl?.trim() ?? "";
+    const runtimeGlobal = injectHTML?.runtimeGlobal?.trim() ?? "__flowersecProxyRuntime";
+    if (injectHTML != null && proxyModuleUrl === "") {
+        throw new Error("injectHTML.proxyModuleUrl must be non-empty");
+    }
+    if (injectHTML != null && runtimeGlobal === "") {
+        throw new Error("injectHTML.runtimeGlobal must be non-empty");
+    }
+    return `// Generated by @floegence/flowersec-core/proxy
+const PROXY_PATH_PREFIX = ${JSON.stringify(proxyPathPrefix)};
+const STRIP_PROXY_PATH_PREFIX = ${JSON.stringify(stripProxyPathPrefix)};
+const INJECT_HTML = ${JSON.stringify(injectHTML != null)};
+const PROXY_MODULE_URL = ${JSON.stringify(proxyModuleUrl)};
+const RUNTIME_GLOBAL = ${JSON.stringify(runtimeGlobal)};
+let runtimeClientId = null;
+
+self.addEventListener("install", () => {
+  // Take over as soon as possible.
+  void self.skipWaiting();
+});
+
+self.addEventListener("activate", (event) => {
+  event.waitUntil(self.clients.claim());
+});
+
+self.addEventListener("message", (event) => {
+  const data = event.data;
+  if (!data || typeof data !== "object") return;
+  if (data.type !== "flowersec-proxy:register-runtime") return;
+  if (event.source && typeof event.source.id === "string") runtimeClientId = event.source.id;
+});
+
+async function getRuntimeClient() {
+  if (runtimeClientId) {
+    const c = await self.clients.get(runtimeClientId);
+    if (c) return c;
+    runtimeClientId = null;
+  }
+  const cs = await self.clients.matchAll({ type: "window", includeUncontrolled: true });
+  if (cs.length > 0) {
+    runtimeClientId = cs[0].id;
+    return cs[0];
+  }
+  return null;
+}
+
+function headersToPairs(headers) {
+  const out = [];
+  headers.forEach((value, name) => out.push({ name, value }));
+  return out;
+}
+
+function concatChunks(chunks) {
+  let total = 0;
+  for (const c of chunks) total += c.length;
+  const out = new Uint8Array(total);
+  let off = 0;
+  for (const c of chunks) {
+    out.set(c, off);
+    off += c.length;
+  }
+  return out;
+}
+
+function injectBootstrap(html) {
+  const snippet =
+    '<script type="module">' +
+    'import { installWebSocketPatch, disableUpstreamServiceWorkerRegister } from ' + JSON.stringify(PROXY_MODULE_URL) + ';' +
+    'const rt = window.top && window.top[' + JSON.stringify(RUNTIME_GLOBAL) + '];' +
+    'if (rt) { disableUpstreamServiceWorkerRegister(); installWebSocketPatch({ runtime: rt }); }' +
+    '</script>';
+  const lower = html.toLowerCase();
+  const idx = lower.indexOf("<head");
+  if (idx >= 0) {
+    const end = html.indexOf(">", idx);
+    if (end >= 0) return html.slice(0, end + 1) + snippet + html.slice(end + 1);
+  }
+  return snippet + html;
+}
+
+self.addEventListener("fetch", (event) => {
+  const url = new URL(event.request.url);
+  if (PROXY_PATH_PREFIX && !url.pathname.startsWith(PROXY_PATH_PREFIX)) return;
+  event.respondWith(handleFetch(event));
+});
+
+async function handleFetch(event) {
+  const runtime = await getRuntimeClient();
+  if (!runtime) return new Response("flowersec-proxy runtime not available", { status: 503 });
+
+  const req = event.request;
+  const url = new URL(req.url);
+  const id = Math.random().toString(16).slice(2) + Date.now().toString(16);
+  const body = (req.method === "GET" || req.method === "HEAD") ? undefined : await req.arrayBuffer();
+
+  const ch = new MessageChannel();
+  const port = ch.port1;
+  const port2 = ch.port2;
+
+  let metaResolve;
+  let metaReject;
+  const metaPromise = new Promise((resolve, reject) => { metaResolve = resolve; metaReject = reject; });
+
+  const queued = [];
+  const htmlChunks = [];
+  let shouldInjectHTML = false;
+
+  let doneResolve;
+  let doneReject;
+  const donePromise = new Promise((resolve, reject) => { doneResolve = resolve; doneReject = reject; });
+
+  let controller = null;
+
+  const stream = new ReadableStream({
+    start(c) { controller = c; },
+    cancel() {
+      try { port.postMessage({ type: "flowersec-proxy:abort" }); } catch {}
+      try { port.close(); } catch {}
+    }
+  });
+
+  port.onmessage = (ev) => {
+    const m = ev.data;
+    if (!m || typeof m.type !== "string") return;
+    if (m.type === "flowersec-proxy:response_meta") {
+      if (INJECT_HTML) {
+        const ct = String((m.headers || []).find((h) => (h.name || "").toLowerCase() === "content-type")?.value || "");
+        shouldInjectHTML = ct.toLowerCase().includes("text/html");
+      }
+      metaResolve(m);
+      if (controller && !shouldInjectHTML) for (const q of queued) controller.enqueue(q);
+      if (shouldInjectHTML) for (const q of queued) htmlChunks.push(q);
+      queued.length = 0;
+      return;
+    }
+    if (m.type === "flowersec-proxy:response_chunk") {
+      const b = new Uint8Array(m.data);
+      if (shouldInjectHTML) {
+        htmlChunks.push(b);
+        return;
+      }
+      if (controller) controller.enqueue(b); else queued.push(b);
+      return;
+    }
+    if (m.type === "flowersec-proxy:response_end") {
+      if (shouldInjectHTML) {
+        doneResolve(htmlChunks);
+        return;
+      }
+      controller?.close();
+      return;
+    }
+    if (m.type === "flowersec-proxy:response_error") {
+      const err = new Error(m.message || "proxy error");
+      metaReject(err);
+      doneReject(err);
+      controller?.error(err);
+      try { port.close(); } catch {}
+      return;
+    }
+  };
+
+  let path = url.pathname + url.search;
+  if (PROXY_PATH_PREFIX && STRIP_PROXY_PATH_PREFIX) {
+    let rest = url.pathname.slice(PROXY_PATH_PREFIX.length);
+    if (rest.startsWith("/")) rest = rest.slice(1);
+    path = "/" + rest + url.search;
+  }
+
+  runtime.postMessage({
+    type: "flowersec-proxy:fetch",
+    req: { id, method: req.method, path, headers: headersToPairs(req.headers), body }
+  }, [port2]);
+
+  const meta = await metaPromise;
+  const headers = new Headers();
+  for (const h of (meta.headers || [])) headers.append(h.name, h.value);
+  if (shouldInjectHTML) {
+    const chunks = await donePromise;
+    const raw = concatChunks(chunks);
+    const html = new TextDecoder().decode(raw);
+    const injected = injectBootstrap(html);
+    return new Response(new TextEncoder().encode(injected), { status: meta.status || 502, headers });
+  }
+
+  return new Response(stream, { status: meta.status || 502, headers });
+}
+`;
+}

package/dist/proxy/types.d.ts

@@ -0,0 +1,37 @@
+export type Header = Readonly<{
+    name: string;
+    value: string;
+}>;
+export type ProxyError = Readonly<{
+    code: string;
+    message: string;
+}>;
+export type HttpRequestMetaV1 = Readonly<{
+    v: 1;
+    request_id: string;
+    method: string;
+    path: string;
+    headers: Header[];
+    timeout_ms?: number;
+}>;
+export type HttpResponseMetaV1 = Readonly<{
+    v: 1;
+    request_id: string;
+    ok: boolean;
+    status?: number;
+    headers?: Header[];
+    error?: ProxyError;
+}>;
+export type WsOpenMetaV1 = Readonly<{
+    v: 1;
+    conn_id: string;
+    path: string;
+    headers: Header[];
+}>;
+export type WsOpenRespV1 = Readonly<{
+    v: 1;
+    conn_id: string;
+    ok: boolean;
+    protocol?: string;
+    error?: ProxyError;
+}>;

package/dist/proxy/types.js

@@ -0,0 +1 @@
+export {};

package/dist/proxy/wsPatch.d.ts

@@ -0,0 +1,9 @@
+import type { ProxyRuntime } from "./runtime.js";
+export type WebSocketPatchOptions = Readonly<{
+    runtime: ProxyRuntime;
+    shouldProxy?: (url: URL) => boolean;
+    maxWsFrameBytes?: number;
+}>;
+export declare function installWebSocketPatch(opts: WebSocketPatchOptions): Readonly<{
+    uninstall: () => void;
+}>;

package/dist/proxy/wsPatch.js

@@ -0,0 +1,272 @@
+import { createByteReader } from "../streamio/index.js";
+import { readU32be, u16be, u32be } from "../utils/bin.js";
+import { DEFAULT_MAX_WS_FRAME_BYTES } from "./constants.js";
+function readU16be(buf, off) {
+    return ((buf[off] << 8) | buf[off + 1]) >>> 0;
+}
+const te = new TextEncoder();
+const td = new TextDecoder();
+function defaultPortForProtocol(protocol) {
+    // Protocol strings include the trailing ':' in URL (e.g. 'http:', 'ws:').
+    if (protocol === "http:" || protocol === "ws:")
+        return "80";
+    if (protocol === "https:" || protocol === "wss:")
+        return "443";
+    return "";
+}
+class ListenerMap {
+    map = new Map();
+    on(type, cb) {
+        let s = this.map.get(type);
+        if (!s) {
+            s = new Set();
+            this.map.set(type, s);
+        }
+        s.add(cb);
+    }
+    off(type, cb) {
+        this.map.get(type)?.delete(cb);
+    }
+    emit(type, ev) {
+        for (const cb of this.map.get(type) ?? []) {
+            try {
+                cb.call(null, ev);
+            }
+            catch {
+                // Best-effort event fanout.
+            }
+        }
+    }
+}
+async function writeWSFrame(stream, op, payload, maxPayload) {
+    if (maxPayload > 0 && payload.length > maxPayload)
+        throw new Error("ws payload too large");
+    const hdr = new Uint8Array(5);
+    hdr[0] = op & 0xff;
+    hdr.set(u32be(payload.length), 1);
+    await stream.write(hdr);
+    if (payload.length > 0)
+        await stream.write(payload);
+}
+async function readWSFrame(reader, maxPayload) {
+    const hdr = await reader.readExactly(5);
+    const op = hdr[0];
+    const n = readU32be(hdr, 1);
+    if (maxPayload > 0 && n > maxPayload)
+        throw new Error("ws payload too large");
+    const payload = n === 0 ? new Uint8Array() : await reader.readExactly(n);
+    return { op, payload };
+}
+export function installWebSocketPatch(opts) {
+    const Original = globalThis.WebSocket;
+    if (Original == null) {
+        return { uninstall: () => { } };
+    }
+    const shouldProxy = opts.shouldProxy ??
+        ((u) => {
+            const loc = globalThis.location;
+            const hostname = typeof loc?.hostname === "string" ? loc.hostname : "";
+            if (hostname === "")
+                return false;
+            const locProto = typeof loc?.protocol === "string" ? loc.protocol : "";
+            const locPortRaw = typeof loc?.port === "string" ? loc.port : "";
+            const locPort = locPortRaw !== "" ? locPortRaw : defaultPortForProtocol(locProto);
+            const uPort = u.port !== "" ? u.port : defaultPortForProtocol(u.protocol);
+            return u.hostname === hostname && uPort === locPort;
+        });
+    const runtime = opts.runtime;
+    const runtimeMaxWsFrameBytes = typeof runtime.limits?.maxWsFrameBytes === "number" && Number.isFinite(runtime.limits.maxWsFrameBytes)
+        ? runtime.limits.maxWsFrameBytes
+        : DEFAULT_MAX_WS_FRAME_BYTES;
+    const maxWsFrameBytesRaw = opts.maxWsFrameBytes ?? runtimeMaxWsFrameBytes;
+    if (!Number.isFinite(maxWsFrameBytesRaw))
+        throw new Error("maxWsFrameBytes must be a finite number");
+    const maxWsFrameBytesFloor = Math.floor(maxWsFrameBytesRaw);
+    if (maxWsFrameBytesFloor < 0)
+        throw new Error("maxWsFrameBytes must be >= 0");
+    const maxWsFrameBytes = maxWsFrameBytesFloor === 0 ? runtimeMaxWsFrameBytes : maxWsFrameBytesFloor;
+    class PatchedWebSocket {
+        static CONNECTING = 0;
+        static OPEN = 1;
+        static CLOSING = 2;
+        static CLOSED = 3;
+        url = "";
+        readyState = PatchedWebSocket.CONNECTING;
+        bufferedAmount = 0;
+        extensions = "";
+        protocol = "";
+        binaryType = "blob";
+        onopen = null;
+        onmessage = null;
+        onerror = null;
+        onclose = null;
+        listeners = new ListenerMap();
+        ac = new AbortController();
+        stream = null;
+        readLoopPromise = null;
+        writeChain = Promise.resolve();
+        constructor(url, protocols) {
+            const u = new URL(String(url), globalThis.location?.href);
+            if (!shouldProxy(u)) {
+                return new Original(String(url), protocols);
+            }
+            this.url = u.toString();
+            void this.init(u, protocols);
+        }
+        addEventListener(type, listener) {
+            this.listeners.on(type, listener);
+        }
+        removeEventListener(type, listener) {
+            this.listeners.off(type, listener);
+        }
+        send(data) {
+            if (this.readyState !== PatchedWebSocket.OPEN || this.stream == null) {
+                throw new Error("WebSocket is not open");
+            }
+            const sendBytes = (op, payload) => {
+                this.writeChain = this.writeChain
+                    .then(() => writeWSFrame(this.stream, op, payload, maxWsFrameBytes))
+                    .catch((e) => this.fail(e));
+            };
+            if (typeof data === "string") {
+                sendBytes(1, te.encode(data));
+                return;
+            }
+            if (data instanceof ArrayBuffer) {
+                sendBytes(2, new Uint8Array(data));
+                return;
+            }
+            if (ArrayBuffer.isView(data)) {
+                sendBytes(2, new Uint8Array(data.buffer, data.byteOffset, data.byteLength));
+                return;
+            }
+            if (typeof Blob !== "undefined" && data instanceof Blob) {
+                void data
+                    .arrayBuffer()
+                    .then((ab) => sendBytes(2, new Uint8Array(ab)))
+                    .catch((e) => this.fail(e));
+                return;
+            }
+            throw new Error("unsupported WebSocket send payload");
+        }
+        close(code, reason) {
+            if (this.readyState === PatchedWebSocket.CLOSED)
+                return;
+            this.readyState = PatchedWebSocket.CLOSING;
+            const payloadParts = [];
+            if (code != null)
+                payloadParts.push(u16be(code));
+            if (reason != null && reason !== "")
+                payloadParts.push(te.encode(reason));
+            const payload = payloadParts.length === 0 ? new Uint8Array() : payloadParts.reduce((a, b) => {
+                const out = new Uint8Array(a.length + b.length);
+                out.set(a, 0);
+                out.set(b, a.length);
+                return out;
+            });
+            this.writeChain = this.writeChain
+                .then(() => (this.stream ? writeWSFrame(this.stream, 8, payload, maxWsFrameBytes) : undefined))
+                .catch(() => undefined)
+                .finally(() => {
+                try {
+                    this.ac.abort("closed");
+                }
+                catch {
+                    // Best-effort abort.
+                }
+            });
+        }
+        emit(type, ev) {
+            const prop = this["on" + type];
+            if (typeof prop === "function") {
+                try {
+                    prop.call(this, ev);
+                }
+                catch {
+                    // Best-effort.
+                }
+            }
+            this.listeners.emit(type, ev);
+        }
+        async init(u, protocols) {
+            try {
+                const list = typeof protocols === "string"
+                    ? [protocols]
+                    : Array.isArray(protocols)
+                        ? protocols
+                        : [];
+                const { stream, protocol } = await runtime.openWebSocketStream(u.pathname + u.search, {
+                    protocols: list,
+                    signal: this.ac.signal
+                });
+                this.stream = stream;
+                this.protocol = protocol;
+                this.readyState = PatchedWebSocket.OPEN;
+                this.emit("open", { type: "open" });
+                this.readLoopPromise = this.readLoop(stream, this.ac.signal);
+            }
+            catch (e) {
+                this.fail(e);
+            }
+        }
+        async readLoop(stream, signal) {
+            const reader = createByteReader(stream, { signal });
+            try {
+                while (true) {
+                    const { op, payload } = await readWSFrame(reader, maxWsFrameBytes);
+                    if (op === 9) {
+                        // Ping -> Pong (not exposed to WebSocket JS API).
+                        await writeWSFrame(stream, 10, payload, maxWsFrameBytes);
+                        continue;
+                    }
+                    if (op === 10)
+                        continue;
+                    if (op === 8) {
+                        this.readyState = PatchedWebSocket.CLOSED;
+                        const code = payload.length >= 2 ? readU16be(payload, 0) : 1000;
+                        const reason = payload.length > 2 ? td.decode(payload.subarray(2)) : "";
+                        this.emit("close", { type: "close", code, reason, wasClean: true });
+                        return;
+                    }
+                    if (op === 1) {
+                        this.emit("message", { type: "message", data: td.decode(payload) });
+                        continue;
+                    }
+                    if (op === 2) {
+                        if (this.binaryType === "arraybuffer") {
+                            const ab = payload.buffer.slice(payload.byteOffset, payload.byteOffset + payload.byteLength);
+                            this.emit("message", { type: "message", data: ab });
+                            continue;
+                        }
+                        if (typeof Blob !== "undefined") {
+                            this.emit("message", { type: "message", data: new Blob([new Uint8Array(payload)]) });
+                            continue;
+                        }
+                        // Fallback for non-browser contexts.
+                        const ab = payload.buffer.slice(payload.byteOffset, payload.byteOffset + payload.byteLength);
+                        this.emit("message", { type: "message", data: ab });
+                        continue;
+                    }
+                }
+            }
+            catch (e) {
+                if (this.readyState !== PatchedWebSocket.CLOSED)
+                    this.fail(e);
+            }
+        }
+        fail(e) {
+            this.readyState = PatchedWebSocket.CLOSED;
+            const msg = e instanceof Error ? e.message : String(e);
+            this.emit("error", { type: "error", message: msg });
+            this.emit("close", { type: "close", code: 1006, reason: msg, wasClean: false });
+            try {
+                this.ac.abort(msg);
+            }
+            catch {
+                // Best-effort.
+            }
+        }
+    }
+    globalThis.WebSocket = PatchedWebSocket;
+    return { uninstall: () => (globalThis.WebSocket = Original) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floegence/flowersec-core",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Flowersec core TypeScript library (browser-friendly E2EE + multiplexing over WebSocket).",
   "license": "MIT",
   "repository": {
@@ -44,6 +44,10 @@
       "types": "./dist/streamio/index.d.ts",
       "default": "./dist/streamio/index.js"
     },
+    "./proxy": {
+      "types": "./dist/proxy/index.d.ts",
+      "default": "./dist/proxy/index.js"
+    },
     "./rpc": {
       "types": "./dist/rpc/index.d.ts",
       "default": "./dist/rpc/index.js"