@floegence/flowersec-core 0.6.0 → 0.8.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,8 @@
+export * from "./constants.js";
+export * from "./types.js";
+export * from "./cookieJar.js";
+export * from "./runtime.js";
+export * from "./serviceWorker.js";
+export { registerServiceWorkerAndEnsureControl } from "./registerServiceWorker.js";
+export * from "./wsPatch.js";
+export * from "./disableUpstreamServiceWorkerRegister.js";

package/dist/proxy/index.js

@@ -0,0 +1,8 @@
+export * from "./constants.js";
+export * from "./types.js";
+export * from "./cookieJar.js";
+export * from "./runtime.js";
+export * from "./serviceWorker.js";
+export { registerServiceWorkerAndEnsureControl } from "./registerServiceWorker.js";
+export * from "./wsPatch.js";
+export * from "./disableUpstreamServiceWorkerRegister.js";

package/dist/proxy/registerServiceWorker.d.ts

@@ -0,0 +1,17 @@
+export type RegisterServiceWorkerOptions = Readonly<{
+    scriptUrl: string;
+    scope?: string;
+    repairQueryKey?: string;
+    maxRepairAttempts?: number;
+    controllerTimeoutMs?: number;
+}>;
+declare function parseRepairAttemptFromHref(href: string, queryKey: string): number;
+declare function buildHrefWithRepairAttempt(href: string, queryKey: string, attempt: number): string;
+declare function buildHrefWithoutRepairQueryParam(href: string, queryKey: string): string;
+export declare function registerServiceWorkerAndEnsureControl(opts: RegisterServiceWorkerOptions): Promise<void>;
+export declare const __testOnly: {
+    parseRepairAttemptFromHref: typeof parseRepairAttemptFromHref;
+    buildHrefWithRepairAttempt: typeof buildHrefWithRepairAttempt;
+    buildHrefWithoutRepairQueryParam: typeof buildHrefWithoutRepairQueryParam;
+};
+export {};

package/dist/proxy/registerServiceWorker.js

@@ -0,0 +1,116 @@
+function parseRepairAttemptFromHref(href, queryKey) {
+    try {
+        const u = new URL(href);
+        const raw = String(u.searchParams.get(queryKey) ?? "").trim();
+        const n = raw ? Number(raw) : 0;
+        if (!Number.isFinite(n) || n < 0)
+            return 0;
+        return Math.min(9, Math.floor(n));
+    }
+    catch {
+        return 0;
+    }
+}
+function buildHrefWithRepairAttempt(href, queryKey, attempt) {
+    const u = new URL(href);
+    u.searchParams.set(queryKey, String(Math.max(0, Math.floor(attempt))));
+    return u.toString();
+}
+function buildHrefWithoutRepairQueryParam(href, queryKey) {
+    const u = new URL(href);
+    u.searchParams.delete(queryKey);
+    const search = u.searchParams.toString();
+    return u.pathname + (search ? `?${search}` : "") + u.hash;
+}
+function waitForController(timeoutMs) {
+    if (navigator.serviceWorker.controller)
+        return Promise.resolve(true);
+    const ms = Math.max(0, Math.floor(timeoutMs));
+    return new Promise((resolve) => {
+        let done = false;
+        let t = null;
+        function finish(ok) {
+            if (done)
+                return;
+            done = true;
+            if (t != null)
+                window.clearTimeout(t);
+            navigator.serviceWorker.removeEventListener("controllerchange", onChange);
+            resolve(ok);
+        }
+        function onChange() {
+            finish(true);
+        }
+        navigator.serviceWorker.addEventListener("controllerchange", onChange);
+        // Avoid race: controller can become available before/after the listener registration.
+        if (navigator.serviceWorker.controller) {
+            finish(true);
+            return;
+        }
+        if (ms > 0) {
+            t = window.setTimeout(() => finish(Boolean(navigator.serviceWorker.controller)), ms);
+        }
+    });
+}
+// registerServiceWorkerAndEnsureControl registers a Service Worker and ensures the current page load is controlled.
+//
+// In DevTools hard reload flows, the SW may be installed but not control the current page load.
+// When this happens, we perform a limited "soft navigation" repair to recover control.
+export async function registerServiceWorkerAndEnsureControl(opts) {
+    const scriptUrl = String(opts.scriptUrl ?? "").trim();
+    if (!scriptUrl)
+        throw new Error("scriptUrl is required");
+    if (globalThis.navigator?.serviceWorker == null) {
+        throw new Error("service worker is not available in this environment");
+    }
+    const scope = String(opts.scope ?? "/").trim() || "/";
+    const queryKey = String(opts.repairQueryKey ?? "_flowersec_sw_repair").trim() || "_flowersec_sw_repair";
+    const maxRepairAttempts = Math.max(0, Math.floor(opts.maxRepairAttempts ?? 2));
+    const controllerTimeoutMs = Math.max(0, Math.floor(opts.controllerTimeoutMs ?? 2_000));
+    await navigator.serviceWorker.register(scriptUrl, { scope });
+    await navigator.serviceWorker.ready;
+    const attempt = parseRepairAttemptFromHref(window.location.href, queryKey);
+    if (navigator.serviceWorker.controller) {
+        if (attempt > 0) {
+            try {
+                const next = buildHrefWithoutRepairQueryParam(window.location.href, queryKey);
+                history.replaceState(null, document.title, next);
+            }
+            catch {
+                // ignore
+            }
+        }
+        return;
+    }
+    const controlled = await waitForController(controllerTimeoutMs);
+    if (controlled) {
+        if (attempt > 0) {
+            try {
+                const next = buildHrefWithoutRepairQueryParam(window.location.href, queryKey);
+                history.replaceState(null, document.title, next);
+            }
+            catch {
+                // ignore
+            }
+        }
+        return;
+    }
+    if (attempt < maxRepairAttempts) {
+        try {
+            const next = buildHrefWithRepairAttempt(window.location.href, queryKey, attempt + 1);
+            window.location.replace(next);
+        }
+        catch {
+            window.location.reload();
+        }
+        // Navigation will interrupt JS; keep pending so callers don't proceed with dependent work.
+        await new Promise(() => { });
+    }
+    throw new Error("Service Worker is installed but not controlling this page");
+}
+// Test-only exports (not re-exported from the public proxy entrypoint).
+export const __testOnly = {
+    parseRepairAttemptFromHref,
+    buildHrefWithRepairAttempt,
+    buildHrefWithoutRepairQueryParam,
+};

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;