@floegence/flowersec-core 0.12.0 → 0.14.0

package/dist/client-connect/connectCore.js

@@ -8,6 +8,7 @@ import { base64urlDecode } from "../utils/base64url.js";
 import { AbortError, FlowersecError, throwIfAborted } from "../utils/errors.js";
 import { WebSocketBinaryTransport, WsCloseError } from "../ws-client/binaryTransport.js";
 import { OriginMismatchError, WsFactoryRequiredError, classifyConnectError, classifyHandshakeError, createWebSocket, waitOpen, withAbortAndTimeout, } from "./common.js";
+import { prepareChannelId } from "./contract.js";
 import { isTunnelAttachCloseReason } from "./tunnelAttachCloseReason.js";
 export async function connectCore(args) {
     const observer = normalizeObserver(args.opts.observer);
@@ -65,10 +66,7 @@ export async function connectCore(args) {
     if (!Number.isSafeInteger(maxWsQueuedBytes) || maxWsQueuedBytes < 0) {
         invalidOption("maxWsQueuedBytes must be a non-negative integer");
     }
-    const channelId = typeof args.channelId === "string" ? args.channelId.trim() : "";
-    if (channelId === "") {
-        throw new FlowersecError({ path: args.path, stage: "validate", code: "missing_channel_id", message: "missing channel_id" });
-    }
+    const channelId = prepareChannelId(args.channelId, args.path);
     let psk;
     try {
         const pskB64u = typeof args.e2eePskB64u === "string" ? args.e2eePskB64u.trim() : "";

package/dist/client-connect/contract.d.ts

@@ -0,0 +1,8 @@
+import type { ChannelInitGrant, Role as ControlRole } from "../gen/flowersec/controlplane/v1.gen.js";
+import type { DirectConnectInfo } from "../gen/flowersec/direct/v1.gen.js";
+import { type FlowersecPath } from "../utils/errors.js";
+export declare const CHANNEL_ID_MAX_BYTES = 256;
+export declare function prepareChannelId(raw: string, path: Exclude<FlowersecPath, "auto">): string;
+export declare function assertTunnelGrantContract(grant: ChannelInitGrant, expectedRole: ControlRole): void;
+export declare function assertDirectConnectContract(info: DirectConnectInfo): void;
+export declare function assertValidPSK(raw: string, path: Exclude<FlowersecPath, "auto">): string;

package/dist/client-connect/contract.js

@@ -0,0 +1,51 @@
+import { base64urlDecode } from "../utils/base64url.js";
+import { FlowersecError } from "../utils/errors.js";
+const textEncoder = new TextEncoder();
+export const CHANNEL_ID_MAX_BYTES = 256;
+export function prepareChannelId(raw, path) {
+    const channelId = typeof raw === "string" ? raw.trim() : "";
+    if (channelId === "") {
+        throw new FlowersecError({ path, stage: "validate", code: "missing_channel_id", message: "missing channel_id" });
+    }
+    if (textEncoder.encode(channelId).length > CHANNEL_ID_MAX_BYTES) {
+        throw new FlowersecError({ path, stage: "validate", code: "invalid_input", message: "channel_id too long" });
+    }
+    return channelId;
+}
+export function assertTunnelGrantContract(grant, expectedRole) {
+    if (grant.role !== expectedRole) {
+        throw new FlowersecError({ stage: "validate", code: "role_mismatch", path: "tunnel", message: `expected role=${expectedRole === 1 ? "client" : "server"}` });
+    }
+    const allowedSuites = Array.isArray(grant.allowed_suites) ? grant.allowed_suites : [];
+    if (allowedSuites.length === 0) {
+        throw new FlowersecError({ stage: "validate", code: "invalid_suite", path: "tunnel", message: "allowed_suites must be non-empty" });
+    }
+    for (const suite of allowedSuites) {
+        assertSupportedSuite(suite, "tunnel");
+    }
+    assertSupportedSuite(grant.default_suite, "tunnel");
+    if (!allowedSuites.includes(grant.default_suite)) {
+        throw new FlowersecError({ stage: "validate", code: "invalid_suite", path: "tunnel", message: "default_suite must be included in allowed_suites" });
+    }
+}
+export function assertDirectConnectContract(info) {
+    assertSupportedSuite(info.default_suite, "direct");
+}
+export function assertValidPSK(raw, path) {
+    const pskB64u = typeof raw === "string" ? raw.trim() : "";
+    try {
+        const psk = base64urlDecode(pskB64u);
+        if (psk.length !== 32) {
+            throw new Error("psk must be 32 bytes");
+        }
+    }
+    catch (e) {
+        throw new FlowersecError({ stage: "validate", code: "invalid_psk", path, message: "invalid e2ee_psk_b64u", cause: e });
+    }
+    return pskB64u;
+}
+function assertSupportedSuite(suite, path) {
+    if (suite !== 1 && suite !== 2) {
+        throw new FlowersecError({ stage: "validate", code: "invalid_suite", path, message: "invalid suite" });
+    }
+}

package/dist/direct-client/connect.js

@@ -1,7 +1,7 @@
 import { assertDirectConnectInfo } from "../gen/flowersec/direct/v1.gen.js";
-import { base64urlDecode } from "../utils/base64url.js";
 import { FlowersecError } from "../utils/errors.js";
 import { connectCore } from "../client-connect/connectCore.js";
+import { assertDirectConnectContract, assertValidPSK, prepareChannelId } from "../client-connect/contract.js";
 function isRecord(v) {
     return typeof v === "object" && v != null && !Array.isArray(v);
 }
@@ -68,9 +68,7 @@ export async function connectDirect(info, opts) {
     if (ready.ws_url === "") {
         throw new FlowersecError({ stage: "validate", code: "missing_ws_url", path: "direct", message: "missing ws_url" });
     }
-    if (ready.channel_id === "") {
-        throw new FlowersecError({ stage: "validate", code: "missing_channel_id", path: "direct", message: "missing channel_id" });
-    }
+    const channelId = prepareChannelId(ready.channel_id, "direct");
     if (ready.channel_init_expire_at_unix_s <= 0) {
         throw new FlowersecError({
             stage: "validate",
@@ -79,19 +77,12 @@ export async function connectDirect(info, opts) {
             message: "missing channel_init_expire_at_unix_s",
         });
     }
-    try {
-        const psk = base64urlDecode(ready.e2ee_psk_b64u);
-        if (psk.length !== 32) {
-            throw new Error("psk must be 32 bytes");
-        }
-    }
-    catch (e) {
-        throw new FlowersecError({ stage: "validate", code: "invalid_psk", path: "direct", message: "invalid e2ee_psk_b64u", cause: e });
-    }
+    assertDirectConnectContract(ready);
+    assertValidPSK(ready.e2ee_psk_b64u, "direct");
     return await connectCore({
         path: "direct",
         wsUrl: ready.ws_url,
-        channelId: ready.channel_id,
+        channelId,
         e2eePskB64u: ready.e2ee_psk_b64u,
         defaultSuite: ready.default_suite,
         opts,

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/dist/tunnel-client/connect.js

@@ -4,6 +4,7 @@ import { base64urlDecode, base64urlEncode } from "../utils/base64url.js";
 import { FlowersecError } from "../utils/errors.js";
 import { randomBytes } from "../client-connect/common.js";
 import { connectCore } from "../client-connect/connectCore.js";
+import { assertTunnelGrantContract, assertValidPSK, prepareChannelId } from "../client-connect/contract.js";
 function isRecord(v) {
     return typeof v === "object" && v != null && !Array.isArray(v);
 }
@@ -84,10 +85,7 @@ export async function connectTunnel(grant, opts) {
     if (tunnelUrl === "") {
         throw new FlowersecError({ stage: "validate", code: "missing_tunnel_url", path: "tunnel", message: "missing tunnel_url" });
     }
-    const channelId = checkedGrant.channel_id.trim();
-    if (channelId === "") {
-        throw new FlowersecError({ stage: "validate", code: "missing_channel_id", path: "tunnel", message: "missing channel_id" });
-    }
+    const channelId = prepareChannelId(checkedGrant.channel_id, "tunnel");
     const token = checkedGrant.token.trim();
     if (token === "") {
         throw new FlowersecError({ stage: "validate", code: "missing_token", path: "tunnel", message: "missing token" });
@@ -100,20 +98,9 @@ export async function connectTunnel(grant, opts) {
             message: "missing channel_init_expire_at_unix_s",
         });
     }
-    const e2eePskB64u = checkedGrant.e2ee_psk_b64u.trim();
-    try {
-        const psk = base64urlDecode(e2eePskB64u);
-        if (psk.length !== 32) {
-            throw new Error("psk must be 32 bytes");
-        }
-    }
-    catch (e) {
-        throw new FlowersecError({ stage: "validate", code: "invalid_psk", path: "tunnel", message: "invalid e2ee_psk_b64u", cause: e });
-    }
+    assertTunnelGrantContract(checkedGrant, ControlRole.Role_client);
+    const e2eePskB64u = assertValidPSK(checkedGrant.e2ee_psk_b64u, "tunnel");
     const idleTimeoutSeconds = checkedGrant.idle_timeout_seconds;
-    if (checkedGrant.role !== ControlRole.Role_client) {
-        throw new FlowersecError({ stage: "validate", code: "role_mismatch", path: "tunnel", message: "expected role=client" });
-    }
     const endpointInstanceId = opts.endpointInstanceId ?? base64urlEncode(randomBytes(24));
     let eidBytes;
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floegence/flowersec-core",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Flowersec core TypeScript library (browser-friendly E2EE + multiplexing over WebSocket).",
   "license": "MIT",
   "repository": {