@floegence/flowersec-core 0.26.0 → 2.0.0

package/dist/proxy/controllerGuard.js

@@ -1,210 +1,116 @@
-function dedupeStrings(values) {
-    const out = [];
-    const seen = new Set();
-    for (const value of values) {
-        const normalized = String(value ?? "").trim();
-        if (normalized === "" || seen.has(normalized))
-            continue;
-        seen.add(normalized);
-        out.push(normalized);
-    }
-    return out;
-}
-function resolveWindow(raw, label) {
-    const candidate = (raw ?? globalThis.window);
-    if (candidate == null) {
-        throw new Error(`${label} is not available in this environment`);
-    }
-    return candidate;
-}
-function getServiceWorker(targetWindow) {
-    return targetWindow.navigator?.serviceWorker ?? null;
-}
-function parseRepairAttemptFromHref(href, queryKey) {
+function serviceWorkerContainer(target) {
     try {
-        const url = new URL(href);
-        const raw = String(url.searchParams.get(queryKey) ?? "").trim();
-        const n = raw === "" ? 0 : Number(raw);
-        if (!Number.isFinite(n) || n < 0)
-            return 0;
-        return Math.min(9, Math.floor(n));
+        return target.navigator?.serviceWorker;
     }
     catch {
-        return 0;
+        return undefined;
     }
 }
-function buildHrefWithRepairAttempt(href, queryKey, attempt) {
-    const url = new URL(href);
-    url.searchParams.set(queryKey, String(Math.max(0, Math.floor(attempt))));
-    return url.toString();
-}
-function isServiceWorkerScriptPathSuffix(raw, suffix) {
-    const script = String(raw ?? "").trim();
-    const wanted = String(suffix ?? "").trim();
-    if (script === "" || wanted === "")
+function scriptMatches(scriptURL, suffix) {
+    if (scriptURL === undefined || scriptURL === "")
         return false;
     try {
-        return new URL(script).pathname.endsWith(wanted);
+        return new URL(scriptURL).pathname.endsWith(suffix);
     }
     catch {
-        return script.endsWith(wanted);
+        return scriptURL.endsWith(suffix);
     }
 }
-async function waitForControllerSuffix(targetWindow, suffix, timeoutMs) {
-    const sw = getServiceWorker(targetWindow);
-    if (sw == null)
-        return false;
-    const isMatch = () => isServiceWorkerScriptPathSuffix(String(sw.controller?.scriptURL ?? ""), suffix);
-    if (isMatch())
-        return true;
-    const ms = Math.max(0, Math.floor(timeoutMs));
-    return await new Promise((resolve) => {
-        let done = false;
-        let timer = null;
-        const finish = (ok) => {
-            if (done)
-                return;
-            done = true;
-            if (timer != null)
-                targetWindow.clearTimeout(timer);
-            sw.removeEventListener?.("controllerchange", onChange);
-            resolve(ok);
-        };
-        const onChange = () => {
-            if (isMatch())
-                finish(true);
-        };
-        sw.addEventListener?.("controllerchange", onChange);
-        if (isMatch()) {
-            finish(true);
-            return;
-        }
-        if (ms > 0) {
-            timer = targetWindow.setTimeout(() => finish(isMatch()), ms);
-        }
-        else {
-            finish(isMatch());
-        }
-    });
-}
-async function uninstallConflictingServiceWorkers(targetWindow, conflicts) {
-    if (conflicts?.uninstallOnMismatch === false)
-        return;
-    const sw = getServiceWorker(targetWindow);
-    if (sw == null || typeof sw.getRegistrations !== "function")
+async function removeConflicts(container, expected, policy) {
+    if (policy?.uninstallOnMismatch === false || typeof container.getRegistrations !== "function")
         return;
-    const keepSuffixes = dedupeStrings(conflicts?.keepScriptPathSuffixes ?? []);
-    const regs = await sw.getRegistrations();
-    for (const reg of regs) {
-        const script = String(reg?.active?.scriptURL ?? reg?.waiting?.scriptURL ?? reg?.installing?.scriptURL ?? "").trim();
-        if (script === "")
-            continue;
-        let shouldKeep = false;
-        for (const suffix of keepSuffixes) {
-            if (isServiceWorkerScriptPathSuffix(script, suffix)) {
-                shouldKeep = true;
-                break;
-            }
-        }
-        if (shouldKeep)
-            continue;
-        try {
-            await reg.unregister?.();
-        }
-        catch {
-            // Best effort cleanup.
+    const keep = [expected, ...(policy?.keepScriptPathSuffixes ?? [])];
+    for (const registration of await container.getRegistrations()) {
+        const script = registration.active?.scriptURL ?? registration.waiting?.scriptURL ?? registration.installing?.scriptURL;
+        if (script !== undefined && !keep.some((suffix) => scriptMatches(script, suffix))) {
+            await registration.unregister().catch(() => false);
         }
     }
 }
-function triggerRepairNavigation(navigationWindow, repair, attempt) {
-    const queryKey = String(repair?.queryKey ?? "_flowersec_sw_repair").trim() || "_flowersec_sw_repair";
-    const maxAttempts = Math.max(0, Math.floor(repair?.maxAttempts ?? 2));
-    const strategy = repair?.strategy ?? "replace";
-    const hrefAttempt = parseRepairAttemptFromHref(navigationWindow.location.href, queryKey);
-    const effectiveAttempt = Math.max(attempt, hrefAttempt);
-    if (effectiveAttempt >= maxAttempts)
-        return false;
-    if (strategy === "reload") {
-        navigationWindow.location.reload();
-        return true;
+function repair(target, options) {
+    const key = options?.queryKey?.trim() || "_flowersec_sw_repair";
+    const maxAttempts = options?.maxAttempts ?? 2;
+    let url;
+    try {
+        url = new URL(target.location.href);
     }
-    const next = buildHrefWithRepairAttempt(navigationWindow.location.href, queryKey, effectiveAttempt + 1);
-    navigationWindow.location.replace(next);
-    return true;
-}
-export function createServiceWorkerControllerGuard(opts) {
-    const targetWindow = resolveWindow(opts.targetWindow, "targetWindow");
-    const navigationWindow = resolveWindow(opts.navigationWindow ?? opts.targetWindow, "navigationWindow");
-    const expectedScriptPathSuffix = String(opts.expectedScriptPathSuffix ?? "").trim();
-    if (expectedScriptPathSuffix === "") {
-        throw new Error("expectedScriptPathSuffix must be non-empty");
+    catch {
+        throw new Error("service worker controller repair URL is unavailable");
+    }
+    const current = Number(url.searchParams.get(key) ?? "0");
+    const attempt = Number.isSafeInteger(current) && current >= 0 ? current : 0;
+    if (attempt >= maxAttempts)
+        throw new Error("service worker controller mismatch persists");
+    if (options?.strategy === "reload") {
+        target.location.reload();
     }
-    const controllerTimeoutMs = Math.max(0, Math.floor(opts.repair?.controllerTimeoutMs ?? 8_000));
-    const monitorEnabled = opts.monitor?.enabled ?? true;
-    const monitorThrottleMs = Math.max(0, Math.floor(opts.monitor?.throttleMs ?? 10_000));
+    else {
+        url.searchParams.set(key, String(attempt + 1));
+        target.location.replace(url.toString());
+    }
+    throw new Error("service worker controller repair navigation started");
+}
+export function createServiceWorkerControllerGuard(options) {
+    const target = options.targetWindow ?? globalThis.window;
+    const navigation = options.navigationWindow ?? target;
+    const expected = options.expectedScriptPathSuffix.trim();
+    if (expected === "")
+        throw new TypeError("expected service worker script suffix is required");
+    const container = serviceWorkerContainer(target);
     let disposed = false;
-    let monitorHandler = null;
-    let lastMonitorRepairAt = 0;
-    let repairAttempts = 0;
+    let lastRepairAt = 0;
     const handleMismatch = async (stage) => {
-        const actualScriptURL = String(getServiceWorker(targetWindow)?.controller?.scriptURL ?? "").trim();
-        const ctx = {
-            expectedScriptPathSuffix,
-            actualScriptURL,
-            stage,
-        };
-        const action = opts.onControllerMismatch?.(ctx);
-        if (action === "ignore")
-            return "ignored";
-        await uninstallConflictingServiceWorkers(targetWindow, opts.conflicts);
-        const repaired = triggerRepairNavigation(navigationWindow, opts.repair, repairAttempts);
-        if (repaired)
-            repairAttempts += 1;
-        return repaired ? "repaired" : "skipped";
+        if (disposed || container === undefined)
+            throw new Error("service worker controller is unavailable");
+        const actual = container.controller?.scriptURL ?? "";
+        const context = { expectedScriptPathSuffix: expected, actualScriptURL: actual, stage };
+        if (options.onControllerMismatch?.(context) === "ignore")
+            return;
+        await removeConflicts(container, expected, options.conflicts);
+        repair(navigation, options.repair);
     };
-    const attachMonitor = () => {
-        if (!monitorEnabled || monitorHandler != null)
+    const onControllerChange = () => {
+        if (disposed || options.monitor?.enabled === false || scriptMatches(container?.controller?.scriptURL, expected))
             return;
-        const currentSW = getServiceWorker(targetWindow);
-        if (currentSW == null)
+        const now = Date.now();
+        const throttle = options.monitor?.throttleMs ?? 10_000;
+        if (now - lastRepairAt < throttle)
             return;
-        monitorHandler = () => {
-            const actualScriptURL = String(currentSW.controller?.scriptURL ?? "").trim();
-            if (isServiceWorkerScriptPathSuffix(actualScriptURL, expectedScriptPathSuffix))
-                return;
-            const now = Date.now();
-            if (monitorThrottleMs > 0 && now - lastMonitorRepairAt <= monitorThrottleMs)
-                return;
-            lastMonitorRepairAt = now;
-            void handleMismatch("monitor");
-        };
-        currentSW.addEventListener?.("controllerchange", monitorHandler);
+        lastRepairAt = now;
+        void handleMismatch("monitor").catch(() => undefined);
     };
-    return {
+    container?.addEventListener("controllerchange", onControllerChange);
+    return Object.freeze({
         ensure: async () => {
             if (disposed)
-                throw new Error("controller guard is already disposed");
-            if (getServiceWorker(targetWindow) == null) {
-                throw new Error("service worker is not available in the target window");
-            }
-            const ok = await waitForControllerSuffix(targetWindow, expectedScriptPathSuffix, controllerTimeoutMs);
-            if (!ok) {
-                const outcome = await handleMismatch("ensure");
-                if (outcome !== "ignored") {
-                    throw new Error("Proxy Service Worker is installed but not controlling the target window");
-                }
+                throw new Error("service worker controller guard is disposed");
+            if (container === undefined)
+                throw new Error("service worker controller is unavailable");
+            if (scriptMatches(container.controller?.scriptURL, expected))
                 return;
-            }
-            attachMonitor();
+            const timeoutMs = options.repair?.controllerTimeoutMs ?? 8_000;
+            const matched = await new Promise((resolve) => {
+                const onChange = () => {
+                    if (!scriptMatches(container.controller?.scriptURL, expected))
+                        return;
+                    cleanup();
+                    resolve(true);
+                };
+                const cleanup = () => {
+                    clearTimeout(timer);
+                    container.removeEventListener("controllerchange", onChange);
+                };
+                container.addEventListener("controllerchange", onChange);
+                const timer = setTimeout(() => { cleanup(); resolve(scriptMatches(container.controller?.scriptURL, expected)); }, timeoutMs);
+            });
+            if (!matched)
+                await handleMismatch("ensure");
         },
         dispose: () => {
             if (disposed)
                 return;
             disposed = true;
-            if (monitorHandler != null) {
-                getServiceWorker(targetWindow)?.removeEventListener?.("controllerchange", monitorHandler);
-            }
-            monitorHandler = null;
+            container?.removeEventListener("controllerchange", onControllerChange);
         },
-    };
+    });
 }

package/dist/proxy/disableUpstreamServiceWorkerRegister.d.ts

@@ -1 +1,3 @@
-export declare function disableUpstreamServiceWorkerRegister(): void;
+export declare function disableUpstreamServiceWorkerRegister(): Readonly<{
+    restore(): void;
+}>;

package/dist/proxy/disableUpstreamServiceWorkerRegister.js

@@ -1,23 +1,25 @@
-// 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() {
+    const serviceWorker = globalThis.navigator?.serviceWorker;
+    if (serviceWorker === undefined || typeof serviceWorker.register !== "function")
+        return Object.freeze({ restore: () => undefined });
+    const original = serviceWorker.register.bind(serviceWorker);
+    const replacement = async () => {
+        throw new Error("upstream service worker registration is disabled by the Flowersec proxy runtime");
+    };
     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.
-        }
+        Object.defineProperty(serviceWorker, "register", { configurable: true, value: replacement });
     }
     catch {
-        // Ignore.
+        return Object.freeze({ restore: () => undefined });
     }
+    return Object.freeze({
+        restore: () => {
+            try {
+                Object.defineProperty(serviceWorker, "register", { configurable: true, value: original });
+            }
+            catch {
+                // Best effort restoration during page teardown.
+            }
+        },
+    });
 }

package/dist/proxy/index.d.ts

@@ -1,16 +1,17 @@
-export * from "./constants.js";
-export * from "./types.js";
-export * from "./cookieJar.js";
-export type { ProxyPresetInput, ProxyPresetLimits, ProxyPresetManifest, ResolvedProxyPreset } from "./preset.js";
-export { DEFAULT_PROXY_PRESET_MANIFEST, assertProxyPresetManifest, resolveProxyPreset } from "./preset.js";
-export * from "./runtime.js";
-export * from "./serviceWorker.js";
+export { PROXY_RUNTIME_SCOPE, assertProxyRuntimeScope } from "./scope.js";
+export { createProxyRuntime, ensureServiceWorkerRuntimeRegistered } from "./runtime.js";
+export type { EnsureServiceWorkerRuntimeRegisteredOptions } from "./runtime.js";
+export { createProxyServiceWorkerScript } from "./serviceWorker.js";
+export type { ProxyServiceWorkerInjectHTMLOptions, ProxyServiceWorkerPassthroughOptions, ProxyServiceWorkerScriptOptions, } from "./serviceWorker.js";
 export { registerServiceWorkerAndEnsureControl } from "./registerServiceWorker.js";
-export * from "./integration.js";
-export * from "./controllerGuard.js";
-export * from "./bootstrap.js";
-export * from "./runtimeScope.js";
-export * from "./controllerWindow.js";
-export * from "./appWindow.js";
-export * from "./wsPatch.js";
-export * from "./disableUpstreamServiceWorkerRegister.js";
+export type { RegisterServiceWorkerOptions } from "./registerServiceWorker.js";
+export { createServiceWorkerControllerGuard } from "./controllerGuard.js";
+export type { ServiceWorkerControllerGuardConflictPolicy, ServiceWorkerControllerGuardHandle, ServiceWorkerControllerGuardMismatchContext, ServiceWorkerControllerGuardMonitorOptions, ServiceWorkerControllerGuardOptions, ServiceWorkerControllerGuardRepairOptions, } from "./controllerGuard.js";
+export { registerProxyAppWindow, registerProxyAppWindowWithServiceWorkerControl, registerProxyControllerWindow, } from "./windowBridge.js";
+export type { ProxyAppServiceWorkerControlOptions, ProxyAppWindowHandle, ProxyControllerWindowHandle, RegisterProxyAppWindowOptions, RegisterProxyAppWindowWithServiceWorkerControlOptions, RegisterProxyControllerWindowOptions, } from "./windowBridge.js";
+export { installWebSocketPatch } from "./wsPatch.js";
+export type { WebSocketPatchOptions } from "./wsPatch.js";
+export { disableUpstreamServiceWorkerRegister } from "./disableUpstreamServiceWorkerRegister.js";
+export { connectProxyBrowser, connectProxyControllerBrowser, } from "./integration.js";
+export type { ProxyBrowserConnectOptions, ProxyBrowserHandle, ProxyControllerBrowserConnectOptions, ProxyControllerBrowserHandle, } from "./integration.js";
+export type { ProxyFetchRequest, ProxyHeader, ProxyRuntime, ProxyRuntimeControllerBridgeScope, ProxyRuntimeLimits, ProxyRuntimeOptions, ProxyRuntimePathPolicy, ProxyRuntimeScopeLimits, ProxyRuntimeScope, ProxyRuntimeServiceWorkerScope, } from "./types.js";

package/dist/proxy/index.js

@@ -1,15 +1,9 @@
-export * from "./constants.js";
-export * from "./types.js";
-export * from "./cookieJar.js";
-export { DEFAULT_PROXY_PRESET_MANIFEST, assertProxyPresetManifest, resolveProxyPreset } from "./preset.js";
-export * from "./runtime.js";
-export * from "./serviceWorker.js";
+export { PROXY_RUNTIME_SCOPE, assertProxyRuntimeScope } from "./scope.js";
+export { createProxyRuntime, ensureServiceWorkerRuntimeRegistered } from "./runtime.js";
+export { createProxyServiceWorkerScript } from "./serviceWorker.js";
 export { registerServiceWorkerAndEnsureControl } from "./registerServiceWorker.js";
-export * from "./integration.js";
-export * from "./controllerGuard.js";
-export * from "./bootstrap.js";
-export * from "./runtimeScope.js";
-export * from "./controllerWindow.js";
-export * from "./appWindow.js";
-export * from "./wsPatch.js";
-export * from "./disableUpstreamServiceWorkerRegister.js";
+export { createServiceWorkerControllerGuard } from "./controllerGuard.js";
+export { registerProxyAppWindow, registerProxyAppWindowWithServiceWorkerControl, registerProxyControllerWindow, } from "./windowBridge.js";
+export { installWebSocketPatch } from "./wsPatch.js";
+export { disableUpstreamServiceWorkerRegister } from "./disableUpstreamServiceWorkerRegister.js";
+export { connectProxyBrowser, connectProxyControllerBrowser, } from "./integration.js";

package/dist/proxy/integration.d.ts

@@ -1,77 +1,29 @@
-import type { Client } from "../client.js";
-import { type ProxyPresetInput, type ResolvedProxyPreset } from "./preset.js";
-import { type ProxyRuntime, type ProxyRuntimePathPolicy } from "./runtime.js";
-import { type ProxyServiceWorkerScriptOptions } from "./serviceWorker.js";
-export type ProxyIntegrationMonitorOptions = Readonly<{
-    enabled?: boolean;
-    throttleMs?: number;
-}>;
-export type ProxyIntegrationRepairOptions = Readonly<{
-    queryKey?: string;
-    maxAttempts?: number;
-    controllerTimeoutMs?: number;
-    strategy?: "replace" | "reload";
-}>;
-export type ProxyServiceWorkerConflictPolicy = Readonly<{
-    keepScriptPathSuffixes?: readonly string[];
-    uninstallOnMismatch?: boolean;
-}>;
-export type ProxyIntegrationServiceWorkerOptions = Readonly<{
-    scriptUrl: string;
-    scope?: string;
-    expectedScriptPathSuffix?: string;
-    repair?: ProxyIntegrationRepairOptions;
-    monitor?: ProxyIntegrationMonitorOptions;
-    conflicts?: ProxyServiceWorkerConflictPolicy;
-}>;
-export type RegisterProxyIntegrationOptions = Readonly<{
-    client: Client;
-    preset?: ProxyPresetInput;
-    runtimeGlobalKey?: string;
-    runtime?: Readonly<{
-        maxJsonFrameBytes?: number;
-        maxChunkBytes?: number;
-        maxBodyBytes?: number;
-        maxWsFrameBytes?: number;
-        maxWsBufferedAmountBytes?: number;
-        maxConcurrentHttpStreams?: number;
-        maxQueuedHttpRequests?: number;
-        maxQueuedHttpBodyBytes?: number;
-        timeoutMs?: number;
-        pathPolicy?: ProxyRuntimePathPolicy;
-        externalOrigin?: string;
-        runtimeRegistrationToken?: string;
+import { type SessionOptions } from "../browser/connectSession.js";
+import type { ArtifactLease } from "../public/artifactLease.js";
+import type { Session } from "../public/contract.js";
+import type { ProxyRuntime, ProxyRuntimeOptions } from "./types.js";
+import { type ProxyControllerWindowHandle, type RegisterProxyControllerWindowOptions } from "./windowBridge.js";
+export type ProxyBrowserConnectOptions = Readonly<{
+    connect?: SessionOptions;
+    runtime?: Omit<ProxyRuntimeOptions, "session">;
+    serviceWorker?: Readonly<{
+        scriptUrl: string;
+        scope?: string;
+        repairQueryKey?: string;
+        maxRepairAttempts?: number;
+        controllerTimeoutMs?: number;
     }>;
-    serviceWorker: ProxyIntegrationServiceWorkerOptions;
-    plugins?: readonly ProxyIntegrationPlugin[];
 }>;
-export type ProxyIntegrationContext = Readonly<{
+export type ProxyBrowserHandle = Readonly<{
+    session: Session;
     runtime: ProxyRuntime;
-    options: RegisterProxyIntegrationOptions;
-    preset: ResolvedProxyPreset;
+    dispose(): Promise<void>;
 }>;
-export type ControllerMismatchContext = Readonly<{
-    expectedScriptPathSuffix: string;
-    actualScriptURL: string;
-    stage: "register" | "monitor";
-}>;
-export type ProxyIntegrationPlugin = Readonly<{
-    name: string;
-    mutateOptions?: (opts: RegisterProxyIntegrationOptions) => RegisterProxyIntegrationOptions;
-    extendServiceWorkerScriptOptions?: (opts: ProxyServiceWorkerScriptOptions) => ProxyServiceWorkerScriptOptions;
-    serviceWorkerConflictPolicy?: ProxyServiceWorkerConflictPolicy;
-    forwardFetchMessageTypes?: readonly string[];
-    onRegistered?: (ctx: ProxyIntegrationContext) => void | Promise<void>;
-    onControllerMismatch?: (ctx: ControllerMismatchContext) => "repair" | "ignore" | void;
-    onDisposed?: () => void | Promise<void>;
-}>;
-export type ProxyIntegrationHandle = Readonly<{
-    runtime: ProxyRuntime;
-    dispose: () => Promise<void>;
+export declare function connectProxyBrowser(lease: ArtifactLease, options?: ProxyBrowserConnectOptions): Promise<ProxyBrowserHandle>;
+export type ProxyControllerBrowserConnectOptions = ProxyBrowserConnectOptions & Readonly<{
+    controller: Omit<RegisterProxyControllerWindowOptions, "runtime">;
 }>;
-export type CreateProxyIntegrationServiceWorkerScriptOptions = Readonly<{
-    baseOptions?: ProxyServiceWorkerScriptOptions;
-    plugins?: readonly ProxyIntegrationPlugin[];
+export type ProxyControllerBrowserHandle = ProxyBrowserHandle & Readonly<{
+    controller: ProxyControllerWindowHandle;
 }>;
-export declare function createProxyIntegrationServiceWorkerScript(opts?: CreateProxyIntegrationServiceWorkerScriptOptions): string;
-export declare function registerProxyIntegration(input: RegisterProxyIntegrationOptions): Promise<ProxyIntegrationHandle>;
+export declare function connectProxyControllerBrowser(lease: ArtifactLease, options: ProxyControllerBrowserConnectOptions): Promise<ProxyControllerBrowserHandle>;