@floegence/flowersec-core 0.13.0 → 0.14.1

package/dist/client-connect/connectCore.js

@@ -14,6 +14,19 @@ export async function connectCore(args) {
     const observer = normalizeObserver(args.opts.observer);
     const signal = args.opts.signal;
     const connectStart = nowSeconds();
+    let attachState = args.path === "tunnel" ? "not_started" : "accepted";
+    const reportAttachSuccess = () => {
+        if (args.path !== "tunnel" || attachState !== "sent")
+            return;
+        observer.onAttach("ok", undefined);
+        attachState = "accepted";
+    };
+    const reportAttachFailure = (reason) => {
+        if (args.path !== "tunnel" || attachState !== "sent")
+            return;
+        observer.onAttach("fail", reason);
+        attachState = "failed";
+    };
     const origin = typeof args.opts.origin === "string" ? args.opts.origin.trim() : "";
     if (origin === "") {
         throw new FlowersecError({ path: args.path, stage: "validate", code: "missing_origin", message: "missing origin" });
@@ -131,9 +144,11 @@ export async function connectCore(args) {
         if (args.path === "tunnel") {
             try {
                 ws.send(args.attach.attachJson);
+                attachState = "sent";
             }
             catch (err) {
                 observer.onAttach("fail", "send_failed");
+                attachState = "failed";
                 try {
                     transport.close();
                 }
@@ -161,9 +176,7 @@ export async function connectCore(args) {
                 ...(signal !== undefined ? { signal } : {}),
                 onCancel: () => transport.close(),
             });
-            if (args.path === "tunnel") {
-                observer.onAttach("ok", undefined);
-            }
+            reportAttachSuccess();
             observer.onHandshake(args.path, "ok", undefined, nowSeconds() - handshakeStart);
         }
         catch (err) {
@@ -173,12 +186,12 @@ export async function connectCore(args) {
             if (args.path === "tunnel" && err instanceof WsCloseError) {
                 const reason = err.reason;
                 if (isTunnelAttachCloseReason(reason)) {
-                    observer.onAttach("fail", reason);
+                    reportAttachFailure(reason);
                     throw new FlowersecError({ path: args.path, stage: "attach", code: reason, message: "tunnel rejected attach", cause: err });
                 }
             }
             if (args.path === "tunnel") {
-                observer.onAttach("ok", undefined);
+                reportAttachFailure(handshakeCode === "timeout" ? "timeout" : handshakeCode === "canceled" ? "canceled" : "attach_failed");
             }
             observer.onHandshake(args.path, "fail", handshakeCode, handshakeElapsedSeconds);
             throw new FlowersecError({

package/dist/proxy/bootstrap.d.ts

@@ -0,0 +1,19 @@
+import type { Client } from "../client.js";
+import type { TunnelConnectBrowserOptions } from "../browser/connect.js";
+import type { ChannelInitGrant } from "../gen/flowersec/controlplane/v1.gen.js";
+import { type ProxyIntegrationPlugin, type ProxyIntegrationServiceWorkerOptions, type RegisterProxyIntegrationOptions } from "./integration.js";
+import type { ProxyProfile, ProxyProfileName } from "./profiles.js";
+import type { ProxyRuntime } from "./runtime.js";
+export type ConnectTunnelProxyBrowserOptions = Readonly<{
+    connect?: TunnelConnectBrowserOptions;
+    profile?: ProxyProfileName | Partial<ProxyProfile>;
+    runtime?: RegisterProxyIntegrationOptions["runtime"];
+    serviceWorker: ProxyIntegrationServiceWorkerOptions;
+    plugins?: readonly ProxyIntegrationPlugin[];
+}>;
+export type ConnectTunnelProxyBrowserHandle = Readonly<{
+    client: Client;
+    runtime: ProxyRuntime;
+    dispose: () => Promise<void>;
+}>;
+export declare function connectTunnelProxyBrowser(grant: ChannelInitGrant, opts: ConnectTunnelProxyBrowserOptions): Promise<ConnectTunnelProxyBrowserHandle>;

package/dist/proxy/bootstrap.js

@@ -0,0 +1,45 @@
+import { connectTunnelBrowser } from "../browser/connect.js";
+import { registerProxyIntegration, } from "./integration.js";
+export async function connectTunnelProxyBrowser(grant, opts) {
+    const client = await connectTunnelBrowser(grant, opts.connect ?? {});
+    const integrationInput = {
+        client,
+        serviceWorker: opts.serviceWorker,
+        ...(opts.profile === undefined ? {} : { profile: opts.profile }),
+        ...(opts.runtime === undefined ? {} : { runtime: opts.runtime }),
+        ...(opts.plugins === undefined ? {} : { plugins: opts.plugins }),
+    };
+    let registered = false;
+    let integration = null;
+    try {
+        integration = await registerProxyIntegration(integrationInput);
+        registered = true;
+    }
+    finally {
+        if (!registered) {
+            client.close();
+        }
+    }
+    return {
+        client,
+        runtime: integration.runtime,
+        dispose: async () => {
+            let firstError = null;
+            try {
+                await integration.dispose();
+            }
+            catch (error) {
+                firstError = error;
+            }
+            try {
+                client.close();
+            }
+            catch (error) {
+                if (firstError == null)
+                    firstError = error;
+            }
+            if (firstError != null)
+                throw firstError;
+        },
+    };
+}

package/dist/proxy/controllerGuard.d.ts

@@ -0,0 +1,33 @@
+export type ServiceWorkerControllerGuardMonitorOptions = Readonly<{
+    enabled?: boolean;
+    throttleMs?: number;
+}>;
+export type ServiceWorkerControllerGuardRepairOptions = Readonly<{
+    queryKey?: string;
+    maxAttempts?: number;
+    controllerTimeoutMs?: number;
+    strategy?: "replace" | "reload";
+}>;
+export type ServiceWorkerControllerGuardConflictPolicy = Readonly<{
+    keepScriptPathSuffixes?: readonly string[];
+    uninstallOnMismatch?: boolean;
+}>;
+export type ServiceWorkerControllerGuardMismatchContext = Readonly<{
+    expectedScriptPathSuffix: string;
+    actualScriptURL: string;
+    stage: "ensure" | "monitor";
+}>;
+export type ServiceWorkerControllerGuardOptions = Readonly<{
+    targetWindow?: Window;
+    navigationWindow?: Window;
+    expectedScriptPathSuffix: string;
+    repair?: ServiceWorkerControllerGuardRepairOptions;
+    monitor?: ServiceWorkerControllerGuardMonitorOptions;
+    conflicts?: ServiceWorkerControllerGuardConflictPolicy;
+    onControllerMismatch?: (ctx: ServiceWorkerControllerGuardMismatchContext) => "repair" | "ignore" | void;
+}>;
+export type ServiceWorkerControllerGuardHandle = Readonly<{
+    ensure: () => Promise<void>;
+    dispose: () => void;
+}>;
+export declare function createServiceWorkerControllerGuard(opts: ServiceWorkerControllerGuardOptions): ServiceWorkerControllerGuardHandle;

package/dist/proxy/controllerGuard.js

@@ -0,0 +1,205 @@
+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) {
+    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));
+    }
+    catch {
+        return 0;
+    }
+}
+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 === "")
+        return false;
+    try {
+        return new URL(script).pathname.endsWith(wanted);
+    }
+    catch {
+        return script.endsWith(wanted);
+    }
+}
+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")
+        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.
+        }
+    }
+}
+function triggerRepairNavigation(navigationWindow, repair) {
+    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 attempt = parseRepairAttemptFromHref(navigationWindow.location.href, queryKey);
+    if (attempt >= maxAttempts)
+        return false;
+    if (strategy === "reload") {
+        navigationWindow.location.reload();
+        return true;
+    }
+    const next = buildHrefWithRepairAttempt(navigationWindow.location.href, queryKey, attempt + 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");
+    }
+    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));
+    let disposed = false;
+    let monitorHandler = null;
+    let lastMonitorRepairAt = 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);
+        return triggerRepairNavigation(navigationWindow, opts.repair) ? "repaired" : "skipped";
+    };
+    const attachMonitor = () => {
+        if (!monitorEnabled || monitorHandler != null)
+            return;
+        const currentSW = getServiceWorker(targetWindow);
+        if (currentSW == null)
+            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);
+    };
+    return {
+        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");
+                }
+                return;
+            }
+            attachMonitor();
+        },
+        dispose: () => {
+            if (disposed)
+                return;
+            disposed = true;
+            if (monitorHandler != null) {
+                getServiceWorker(targetWindow)?.removeEventListener?.("controllerchange", monitorHandler);
+            }
+            monitorHandler = null;
+        },
+    };
+}

package/dist/proxy/index.d.ts

@@ -6,5 +6,7 @@ export * from "./runtime.js";
 export * from "./serviceWorker.js";
 export { registerServiceWorkerAndEnsureControl } from "./registerServiceWorker.js";
 export * from "./integration.js";
+export * from "./controllerGuard.js";
+export * from "./bootstrap.js";
 export * from "./wsPatch.js";
 export * from "./disableUpstreamServiceWorkerRegister.js";

package/dist/proxy/index.js

@@ -6,5 +6,7 @@ export * from "./runtime.js";
 export * from "./serviceWorker.js";
 export { registerServiceWorkerAndEnsureControl } from "./registerServiceWorker.js";
 export * from "./integration.js";
+export * from "./controllerGuard.js";
+export * from "./bootstrap.js";
 export * from "./wsPatch.js";
 export * from "./disableUpstreamServiceWorkerRegister.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floegence/flowersec-core",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "Flowersec core TypeScript library (browser-friendly E2EE + multiplexing over WebSocket).",
   "license": "MIT",
   "repository": {
@@ -108,7 +108,10 @@
     "build": "tsc -p tsconfig.build.json",
     "bench": "vitest bench --run",
     "test": "vitest run",
-    "lint": "eslint ."
+    "lint": "eslint .",
+    "verify:package": "node ./scripts/verify-package-exports.mjs",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run build && npm run verify:package"
   },
   "dependencies": {
     "@noble/ciphers": "^0.6.0",