@floegence/flowersec-core 0.26.0 → 2.0.0

package/dist/proxy/stream.d.ts

@@ -0,0 +1,9 @@
+import type { ByteStream, OperationOptions } from "../public/contract.js";
+export declare class ProxyByteReader {
+    private readonly stream;
+    private readonly options;
+    private buffered;
+    constructor(stream: ByteStream, options?: OperationOptions);
+    readExactly(length: number): Promise<Uint8Array>;
+}
+export declare function writeAll(stream: ByteStream, input: Uint8Array, options?: OperationOptions): Promise<void>;

package/dist/proxy/stream.js

@@ -0,0 +1,40 @@
+export class ProxyByteReader {
+    stream;
+    options;
+    buffered = new Uint8Array();
+    constructor(stream, options = {}) {
+        this.stream = stream;
+        this.options = options;
+    }
+    async readExactly(length) {
+        if (!Number.isSafeInteger(length) || length < 0)
+            throw new TypeError("invalid proxy read length");
+        const output = new Uint8Array(length);
+        let offset = 0;
+        while (offset < length) {
+            if (this.buffered.length === 0) {
+                const next = await this.stream.read(this.options);
+                if (next === null)
+                    throw new Error("proxy stream ended unexpectedly");
+                if (next.length === 0)
+                    continue;
+                this.buffered = next;
+            }
+            const take = Math.min(length - offset, this.buffered.length);
+            output.set(this.buffered.subarray(0, take), offset);
+            offset += take;
+            this.buffered = this.buffered.subarray(take);
+        }
+        return output;
+    }
+}
+export async function writeAll(stream, input, options = {}) {
+    let offset = 0;
+    while (offset < input.length) {
+        const written = await stream.write(input.subarray(offset), options);
+        if (!Number.isSafeInteger(written) || written <= 0 || written > input.length - offset) {
+            throw new Error("proxy stream write made no progress");
+        }
+        offset += written;
+    }
+}

package/dist/proxy/types.d.ts

@@ -1,38 +1,86 @@
-export type Header = Readonly<{
+import type { ByteStream, Session } from "../public/contract.js";
+export type ProxyHeader = Readonly<{
     name: string;
     value: string;
 }>;
-export type ProxyError = Readonly<{
-    code: string;
-    message: string;
+export type ProxyRuntimeLimits = Readonly<{
+    maxJsonFrameBytes: number;
+    maxChunkBytes: number;
+    maxBodyBytes: number;
+    maxWsFrameBytes: number;
+    maxWsBufferedAmountBytes: number;
+    maxConcurrentHttpStreams: number;
+    maxQueuedHttpRequests: number;
+    maxQueuedHttpBodyBytes: number;
 }>;
-export type HttpRequestMetaV1 = Readonly<{
-    v: 1;
-    request_id: string;
+export type ProxyRuntimePathPolicy = Readonly<{
+    allowedPathPrefixes?: readonly string[];
+    deniedPathPrefixes?: readonly string[];
+    allowedWebSocketPathPrefixes?: readonly string[];
+    deniedWebSocketPathPrefixes?: readonly string[];
+}>;
+export type ProxyRuntimeOptions = Readonly<{
+    session: Session;
+    maxJsonFrameBytes?: number;
+    maxChunkBytes?: number;
+    maxBodyBytes?: number;
+    maxWsFrameBytes?: number;
+    maxWsBufferedAmountBytes?: number;
+    maxConcurrentHttpStreams?: number;
+    maxQueuedHttpRequests?: number;
+    maxQueuedHttpBodyBytes?: number;
+    timeoutMs?: number;
+    extraRequestHeaders?: readonly string[];
+    extraResponseHeaders?: readonly string[];
+    extraWebSocketHeaders?: readonly string[];
+    pathPolicy?: ProxyRuntimePathPolicy;
+    externalOrigin?: string;
+    runtimeRegistrationToken?: string;
+}>;
+export type ProxyFetchRequest = Readonly<{
+    id: string;
     method: string;
     path: string;
-    headers: Header[];
-    external_origin?: string;
-    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[];
+    headers: readonly ProxyHeader[];
+    externalOrigin?: string;
+    responseFlowControl?: "chunk_credit_v2";
+    body?: ArrayBuffer;
+}>;
+export type ProxyRuntime = Readonly<{
+    limits: ProxyRuntimeLimits;
+    dispatchFetch(request: ProxyFetchRequest, port: MessagePort): void;
+    openWebSocketStream(path: string, options?: Readonly<{
+        protocols?: readonly string[];
+        signal?: AbortSignal;
+    }>): Promise<Readonly<{
+        stream: ByteStream;
+        protocol: string;
+    }>>;
+    dispose(): void;
+}>;
+export type ProxyRuntimeScopeLimits = Readonly<{
+    timeoutMs?: number;
+    maxJsonFrameBytes?: number;
+    maxChunkBytes?: number;
+    maxBodyBytes?: number;
+    maxWsFrameBytes?: number;
+}>;
+type ProxyRuntimeScopeBase = Readonly<{
+    appBasePath?: string;
+    limits?: ProxyRuntimeScopeLimits;
+}>;
+export type ProxyRuntimeServiceWorkerScope = ProxyRuntimeScopeBase & Readonly<{
+    mode: "service_worker";
+    serviceWorker: Readonly<{
+        scriptUrl: string;
+        scope: string;
+    }>;
 }>;
-export type WsOpenRespV1 = Readonly<{
-    v: 1;
-    conn_id: string;
-    ok: boolean;
-    protocol?: string;
-    error?: ProxyError;
+export type ProxyRuntimeControllerBridgeScope = ProxyRuntimeScopeBase & Readonly<{
+    mode: "controller_bridge";
+    controllerBridge: Readonly<{
+        allowedOrigins: readonly string[];
+    }>;
 }>;
+export type ProxyRuntimeScope = ProxyRuntimeServiceWorkerScope | ProxyRuntimeControllerBridgeScope;
+export {};

package/dist/proxy/windowBridge.d.ts

@@ -0,0 +1,61 @@
+import { SessionError, type ByteStream, type OperationOptions } from "../public/contract.js";
+import { type ServiceWorkerControllerGuardConflictPolicy, type ServiceWorkerControllerGuardMonitorOptions, type ServiceWorkerControllerGuardRepairOptions } from "./controllerGuard.js";
+import type { ProxyRuntime } from "./types.js";
+export declare class MessagePortByteStream implements ByteStream {
+    private readonly port;
+    readonly kind = "flowersec.proxy.window.v2";
+    terminalError: SessionError | undefined;
+    private readonly reads;
+    private readonly readWaiters;
+    private readonly writeWaiters;
+    private nextWrite;
+    private buffered;
+    private readBuffered;
+    private ended;
+    private closed;
+    constructor(port: MessagePort);
+    read(options?: OperationOptions): Promise<Uint8Array | null>;
+    write(data: Uint8Array, options?: OperationOptions): Promise<number>;
+    closeWrite(): Promise<void>;
+    reset(): Promise<void>;
+    close(): Promise<void>;
+    private handle;
+    private finish;
+    private fail;
+}
+export type RegisterProxyAppWindowOptions = Readonly<{
+    controllerOrigin: string;
+    controllerWindow?: Window | null;
+    targetWindow?: Window;
+    maxWsFrameBytes?: number;
+    maxWsBufferedAmountBytes?: number;
+    capabilityNonce?: string;
+}>;
+export type ProxyAppWindowHandle = Readonly<{
+    runtime: ProxyRuntime;
+    dispose(): void;
+}>;
+export declare function registerProxyAppWindow(options: RegisterProxyAppWindowOptions): ProxyAppWindowHandle;
+export type RegisterProxyControllerWindowOptions = Readonly<{
+    runtime: ProxyRuntime;
+    allowedOrigins: readonly string[];
+    targetWindow?: Window;
+    expectedSource?: Window | null;
+    capabilityNonce?: string;
+}>;
+export type ProxyControllerWindowHandle = Readonly<{
+    dispose(): void;
+}>;
+export declare function registerProxyControllerWindow(options: RegisterProxyControllerWindowOptions): ProxyControllerWindowHandle;
+export type ProxyAppServiceWorkerControlOptions = Readonly<{
+    scriptUrl: string;
+    scope?: string;
+    expectedScriptPathSuffix: string;
+    repair?: ServiceWorkerControllerGuardRepairOptions;
+    monitor?: ServiceWorkerControllerGuardMonitorOptions;
+    conflicts?: ServiceWorkerControllerGuardConflictPolicy;
+}>;
+export type RegisterProxyAppWindowWithServiceWorkerControlOptions = RegisterProxyAppWindowOptions & Readonly<{
+    serviceWorker: ProxyAppServiceWorkerControlOptions;
+}>;
+export declare function registerProxyAppWindowWithServiceWorkerControl(options: RegisterProxyAppWindowWithServiceWorkerControlOptions): Promise<ProxyAppWindowHandle>;

package/dist/proxy/windowBridge.js

@@ -0,0 +1,344 @@
+import { SDK_DEFAULTS } from "../defaults.js";
+import { SessionError } from "../public/contract.js";
+import { createServiceWorkerControllerGuard, } from "./controllerGuard.js";
+import { registerServiceWorkerAndEnsureControl } from "./registerServiceWorker.js";
+const FETCH_MESSAGE = "flowersec-proxy:window_fetch_v2";
+const WEBSOCKET_OPEN_MESSAGE = "flowersec-proxy:window_ws_open_v2";
+const WEBSOCKET_ACK_MESSAGE = "flowersec-proxy:window_ws_open_ack_v2";
+const MAX_BRIDGE_CHUNK_BYTES = 1024 * 1024;
+const MAX_BRIDGE_BUFFER_BYTES = 4 * 1024 * 1024;
+export class MessagePortByteStream {
+    port;
+    kind = "flowersec.proxy.window.v2";
+    terminalError;
+    reads = [];
+    readWaiters = [];
+    writeWaiters = new Map();
+    nextWrite = 1;
+    buffered = 0;
+    readBuffered = 0;
+    ended = false;
+    closed = false;
+    constructor(port) {
+        this.port = port;
+        port.onmessage = (event) => this.handle(event.data);
+        port.onmessageerror = () => this.fail(new SessionError("operation_failed"));
+        port.start();
+    }
+    async read(options = {}) {
+        if (options.signal?.aborted === true)
+            throw new SessionError("canceled");
+        const queued = this.reads.shift();
+        if (queued !== undefined) {
+            this.readBuffered -= queued.byteLength;
+            return queued;
+        }
+        if (this.ended)
+            return null;
+        if (this.terminalError !== undefined)
+            throw this.terminalError;
+        return await new Promise((resolve, reject) => {
+            const waiter = { resolve, reject };
+            const onAbort = () => {
+                const index = this.readWaiters.indexOf(waiter);
+                if (index >= 0)
+                    this.readWaiters.splice(index, 1);
+                reject(new SessionError("canceled"));
+            };
+            options.signal?.addEventListener("abort", onAbort, { once: true });
+            this.readWaiters.push(waiter);
+        });
+    }
+    async write(data, options = {}) {
+        if (this.closed || this.terminalError !== undefined)
+            throw this.terminalError ?? new SessionError("closed");
+        if (options.signal?.aborted === true)
+            throw new SessionError("canceled");
+        if (data.length === 0)
+            return 0;
+        if (data.length > MAX_BRIDGE_CHUNK_BYTES || this.buffered + data.length > MAX_BRIDGE_BUFFER_BYTES) {
+            throw new SessionError("resource_exhausted");
+        }
+        const id = this.nextWrite++;
+        const copy = data.slice();
+        this.buffered += copy.length;
+        await new Promise((resolve, reject) => {
+            this.writeWaiters.set(id, {
+                resolve: () => { this.buffered -= copy.length; resolve(); },
+                reject: (error) => { this.buffered -= copy.length; reject(error); },
+            });
+            try {
+                this.port.postMessage({ type: "chunk", id, data: copy.buffer }, [copy.buffer]);
+            }
+            catch {
+                this.writeWaiters.delete(id);
+                this.buffered -= copy.length;
+                reject(new SessionError("operation_failed"));
+            }
+        });
+        return data.length;
+    }
+    async closeWrite() {
+        if (this.closed)
+            return;
+        this.port.postMessage({ type: "end" });
+    }
+    async reset() {
+        if (this.closed)
+            return;
+        this.port.postMessage({ type: "reset" });
+        this.fail(new SessionError("stream_reset"));
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.port.postMessage({ type: "close" });
+        this.finish();
+    }
+    handle(value) {
+        if (value === null || typeof value !== "object" || !("type" in value))
+            return;
+        const message = value;
+        if (message.type === "chunk") {
+            if (!Number.isSafeInteger(message.id) || !(message.data instanceof ArrayBuffer) || message.data.byteLength > MAX_BRIDGE_CHUNK_BYTES) {
+                this.fail(new SessionError("operation_failed"));
+                return;
+            }
+            const chunk = new Uint8Array(message.data);
+            const id = message.id;
+            const waiter = this.readWaiters.shift();
+            if (waiter === undefined) {
+                if (this.readBuffered + chunk.byteLength > MAX_BRIDGE_BUFFER_BYTES) {
+                    this.fail(new SessionError("resource_exhausted"));
+                    return;
+                }
+                this.reads.push(chunk);
+                this.readBuffered += chunk.byteLength;
+            }
+            else {
+                waiter.resolve(chunk);
+            }
+            this.port.postMessage({ type: "ack", id });
+            return;
+        }
+        if (message.type === "ack" && Number.isSafeInteger(message.id)) {
+            const waiter = this.writeWaiters.get(message.id);
+            if (waiter !== undefined) {
+                this.writeWaiters.delete(message.id);
+                waiter.resolve();
+            }
+            return;
+        }
+        if (message.type === "end") {
+            this.ended = true;
+            for (const waiter of this.readWaiters.splice(0))
+                waiter.resolve(null);
+            return;
+        }
+        if (message.type === "reset")
+            this.fail(new SessionError("stream_reset"));
+        else if (message.type === "close")
+            this.finish();
+    }
+    finish() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.ended = true;
+        this.reads.length = 0;
+        this.readBuffered = 0;
+        for (const waiter of this.readWaiters.splice(0))
+            waiter.resolve(null);
+        for (const waiter of this.writeWaiters.values())
+            waiter.reject(new SessionError("closed"));
+        this.writeWaiters.clear();
+        this.port.close();
+    }
+    fail(error) {
+        if (this.terminalError !== undefined)
+            return;
+        this.terminalError = error;
+        this.closed = true;
+        this.reads.length = 0;
+        this.readBuffered = 0;
+        for (const waiter of this.readWaiters.splice(0))
+            waiter.reject(error);
+        for (const waiter of this.writeWaiters.values())
+            waiter.reject(error);
+        this.writeWaiters.clear();
+        this.port.close();
+    }
+}
+function bridgeLimits(maxWsFrameBytes, maxWsBufferedAmountBytes) {
+    const wsFrame = maxWsFrameBytes ?? SDK_DEFAULTS.proxy.maxWsFrameBytes;
+    const buffered = maxWsBufferedAmountBytes ?? MAX_BRIDGE_BUFFER_BYTES;
+    if (!Number.isSafeInteger(wsFrame) || wsFrame <= 0 || !Number.isSafeInteger(buffered) || buffered <= 0) {
+        throw new TypeError("invalid proxy window bridge limits");
+    }
+    return Object.freeze({
+        maxJsonFrameBytes: SDK_DEFAULTS.proxy.maxJsonFrameBytes,
+        maxChunkBytes: SDK_DEFAULTS.proxy.maxChunkBytes,
+        maxBodyBytes: SDK_DEFAULTS.proxy.maxBodyBytes,
+        maxWsFrameBytes: wsFrame,
+        maxWsBufferedAmountBytes: buffered,
+        maxConcurrentHttpStreams: 24,
+        maxQueuedHttpRequests: 128,
+        maxQueuedHttpBodyBytes: 64 * 1024 * 1024,
+    });
+}
+function capability(input) {
+    if (input === undefined)
+        return undefined;
+    if (input === "" || input !== input.trim() || /[\u0000-\u0020\u007f]/u.test(input) || input.length > 256) {
+        throw new TypeError("invalid proxy window capability nonce");
+    }
+    return input;
+}
+export function registerProxyAppWindow(options) {
+    const target = options.targetWindow ?? globalThis.window;
+    const controller = options.controllerWindow ?? target.opener ?? (target.parent === target ? null : target.parent);
+    if (controller === null)
+        throw new Error("proxy controller window is unavailable");
+    const origin = new URL(options.controllerOrigin).origin;
+    if (origin !== options.controllerOrigin)
+        throw new TypeError("controllerOrigin must be an origin");
+    const nonce = capability(options.capabilityNonce);
+    const limits = bridgeLimits(options.maxWsFrameBytes, options.maxWsBufferedAmountBytes);
+    let disposed = false;
+    const dispatchFetch = (request, port) => {
+        if (disposed) {
+            port.postMessage({ type: "flowersec-proxy:response_error", status: 503, code: "closed", message: "proxy service unavailable" });
+            port.close();
+            return;
+        }
+        controller.postMessage({ type: FETCH_MESSAGE, version: 2, request, ...(nonce === undefined ? {} : { capabilityNonce: nonce }) }, origin, [port]);
+    };
+    const runtime = Object.freeze({
+        limits,
+        dispatchFetch,
+        openWebSocketStream: async (path, openOptions = {}) => {
+            if (disposed)
+                throw new SessionError("closed");
+            const channel = new MessageChannel();
+            const response = new Promise((resolve, reject) => {
+                const timer = setTimeout(() => { channel.port1.close(); reject(new SessionError("timeout")); }, 10_000);
+                channel.port1.onmessage = (event) => {
+                    if (event.data?.type !== WEBSOCKET_ACK_MESSAGE)
+                        return;
+                    clearTimeout(timer);
+                    if (event.data.ok !== true) {
+                        channel.port1.close();
+                        reject(new SessionError("operation_failed"));
+                        return;
+                    }
+                    resolve(Object.freeze({ stream: new MessagePortByteStream(channel.port1), protocol: typeof event.data.protocol === "string" ? event.data.protocol : "" }));
+                };
+            });
+            controller.postMessage({
+                type: WEBSOCKET_OPEN_MESSAGE,
+                version: 2,
+                path,
+                protocols: openOptions.protocols ?? [],
+                ...(nonce === undefined ? {} : { capabilityNonce: nonce }),
+            }, origin, [channel.port2]);
+            if (openOptions.signal !== undefined) {
+                openOptions.signal.addEventListener("abort", () => channel.port1.close(), { once: true });
+            }
+            return await response;
+        },
+        dispose: () => { disposed = true; },
+    });
+    return Object.freeze({
+        runtime,
+        dispose: () => { disposed = true; },
+    });
+}
+async function bridgeStreams(runtimeStream, port) {
+    const bridge = new MessagePortByteStream(port);
+    const left = (async () => {
+        while (true) {
+            const chunk = await runtimeStream.read();
+            if (chunk === null) {
+                await bridge.closeWrite();
+                return;
+            }
+            await bridge.write(chunk);
+        }
+    })();
+    const right = (async () => {
+        while (true) {
+            const chunk = await bridge.read();
+            if (chunk === null) {
+                await runtimeStream.closeWrite();
+                return;
+            }
+            let offset = 0;
+            while (offset < chunk.length)
+                offset += await runtimeStream.write(chunk.subarray(offset));
+        }
+    })();
+    await Promise.all([left, right]);
+    await runtimeStream.close();
+    await bridge.close();
+}
+export function registerProxyControllerWindow(options) {
+    const target = options.targetWindow ?? globalThis.window;
+    const allowed = new Set(options.allowedOrigins.map((origin) => new URL(origin).origin));
+    if (allowed.size === 0 || [...allowed].some((origin) => !options.allowedOrigins.includes(origin))) {
+        throw new TypeError("allowedOrigins must contain exact origins");
+    }
+    const nonce = capability(options.capabilityNonce);
+    let disposed = false;
+    const onMessage = (event) => {
+        if (disposed || !allowed.has(event.origin) || (options.expectedSource !== undefined && event.source !== options.expectedSource))
+            return;
+        if (nonce !== undefined && event.data?.capabilityNonce !== nonce)
+            return;
+        const port = event.ports?.[0];
+        if (port === undefined)
+            return;
+        if (event.data?.type === FETCH_MESSAGE && event.data.version === 2) {
+            options.runtime.dispatchFetch(event.data.request, port);
+            return;
+        }
+        if (event.data?.type === WEBSOCKET_OPEN_MESSAGE && event.data.version === 2) {
+            void (async () => {
+                try {
+                    const opened = await options.runtime.openWebSocketStream(String(event.data.path ?? ""), {
+                        protocols: Array.isArray(event.data.protocols) ? event.data.protocols.map(String) : [],
+                    });
+                    port.postMessage({ type: WEBSOCKET_ACK_MESSAGE, ok: true, protocol: opened.protocol });
+                    await bridgeStreams(opened.stream, port);
+                }
+                catch {
+                    port.postMessage({ type: WEBSOCKET_ACK_MESSAGE, ok: false });
+                    port.close();
+                }
+            })();
+        }
+    };
+    target.addEventListener("message", onMessage);
+    return Object.freeze({ dispose: () => { disposed = true; target.removeEventListener("message", onMessage); } });
+}
+export async function registerProxyAppWindowWithServiceWorkerControl(options) {
+    await registerServiceWorkerAndEnsureControl({
+        scriptUrl: options.serviceWorker.scriptUrl,
+        ...(options.serviceWorker.scope === undefined ? {} : { scope: options.serviceWorker.scope }),
+        ...(options.serviceWorker.repair?.queryKey === undefined ? {} : { repairQueryKey: options.serviceWorker.repair.queryKey }),
+        ...(options.serviceWorker.repair?.maxAttempts === undefined ? {} : { maxRepairAttempts: options.serviceWorker.repair.maxAttempts }),
+        ...(options.serviceWorker.repair?.controllerTimeoutMs === undefined ? {} : { controllerTimeoutMs: options.serviceWorker.repair.controllerTimeoutMs }),
+    });
+    const guard = createServiceWorkerControllerGuard({
+        ...(options.targetWindow === undefined ? {} : { targetWindow: options.targetWindow, navigationWindow: options.targetWindow }),
+        expectedScriptPathSuffix: options.serviceWorker.expectedScriptPathSuffix,
+        ...(options.serviceWorker.repair === undefined ? {} : { repair: options.serviceWorker.repair }),
+        ...(options.serviceWorker.monitor === undefined ? {} : { monitor: options.serviceWorker.monitor }),
+        ...(options.serviceWorker.conflicts === undefined ? {} : { conflicts: options.serviceWorker.conflicts }),
+    });
+    await guard.ensure();
+    const app = registerProxyAppWindow(options);
+    return Object.freeze({
+        runtime: app.runtime,
+        dispose: () => { app.dispose(); guard.dispose(); },
+    });
+}

package/dist/proxy/wsPatch.d.ts

@@ -1,20 +1,10 @@
-import type { YamuxStream } from "../yamux/stream.js";
-import type { ProxyRuntimeLimits } from "./runtime.js";
+import type { ProxyRuntime } from "./types.js";
 export type WebSocketPatchOptions = Readonly<{
-    runtime: Readonly<{
-        limits: Partial<ProxyRuntimeLimits>;
-        openWebSocketStream: (path: string, opts?: Readonly<{
-            protocols?: readonly string[];
-            signal?: AbortSignal;
-        }>) => Promise<Readonly<{
-            stream: YamuxStream;
-            protocol: string;
-        }>>;
-    }>;
+    runtime: Pick<ProxyRuntime, "limits" | "openWebSocketStream">;
     shouldProxy?: (url: URL) => boolean;
     maxWsFrameBytes?: number;
     maxWsBufferedAmountBytes?: number;
 }>;
-export declare function installWebSocketPatch(opts: WebSocketPatchOptions): Readonly<{
-    uninstall: () => void;
+export declare function installWebSocketPatch(options: WebSocketPatchOptions): Readonly<{
+    uninstall(): void;
 }>;