@floegence/flowersec-core 0.10.1 → 0.11.0

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

@@ -1,4 +1,9 @@
 import { type ConnectOptionsBase } from "../client-connect/connectCore.js";
 import type { ClientInternal } from "../client.js";
-export type DirectConnectOptions = ConnectOptionsBase;
+export type DirectConnectOptions = ConnectOptionsBase & Readonly<{
+    /** Type-only marker to prevent mixing direct and tunnel option types. */
+    __mode?: "direct";
+    /** Reserved for tunnel connects; forbidden for direct connects. */
+    endpointInstanceId?: never;
+}>;
 export declare function connectDirect(info: unknown, opts: DirectConnectOptions): Promise<ClientInternal>;

package/dist/proxy/index.d.ts

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

package/dist/proxy/index.js

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

package/dist/proxy/integration.d.ts

@@ -0,0 +1,69 @@
+import type { Client } from "../client.js";
+import { type ProxyProfile, type ProxyProfileName } from "./profiles.js";
+import { type ProxyRuntime } 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;
+    profile?: ProxyProfileName | Partial<ProxyProfile>;
+    runtime?: Readonly<{
+        maxJsonFrameBytes?: number;
+        maxChunkBytes?: number;
+        maxBodyBytes?: number;
+        maxWsFrameBytes?: number;
+        timeoutMs?: number;
+    }>;
+    serviceWorker: ProxyIntegrationServiceWorkerOptions;
+    plugins?: readonly ProxyIntegrationPlugin[];
+}>;
+export type ProxyIntegrationContext = Readonly<{
+    runtime: ProxyRuntime;
+    options: RegisterProxyIntegrationOptions;
+    profile: ProxyProfile;
+}>;
+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 type CreateProxyIntegrationServiceWorkerScriptOptions = Readonly<{
+    baseOptions?: ProxyServiceWorkerScriptOptions;
+    plugins?: readonly ProxyIntegrationPlugin[];
+}>;
+export declare function createProxyIntegrationServiceWorkerScript(opts?: CreateProxyIntegrationServiceWorkerScriptOptions): string;
+export declare function registerProxyIntegration(input: RegisterProxyIntegrationOptions): Promise<ProxyIntegrationHandle>;

package/dist/proxy/integration.js

@@ -0,0 +1,292 @@
+import { resolveProxyProfile } from "./profiles.js";
+import { registerServiceWorkerAndEnsureControl } from "./registerServiceWorker.js";
+import { createProxyRuntime } from "./runtime.js";
+import { createProxyServiceWorkerScript } from "./serviceWorker.js";
+function dedupeStrings(values) {
+    const out = [];
+    const seen = new Set();
+    for (const v of values) {
+        const n = String(v ?? "").trim();
+        if (n === "" || seen.has(n))
+            continue;
+        seen.add(n);
+        out.push(n);
+    }
+    return out;
+}
+function parseRepairAttemptFromHref(href, queryKey) {
+    try {
+        const u = new URL(href);
+        const raw = String(u.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 u = new URL(href);
+    u.searchParams.set(queryKey, String(Math.max(0, Math.floor(attempt))));
+    return u.toString();
+}
+function isServiceWorkerScriptPathSuffix(raw, suffix) {
+    const script = String(raw ?? "").trim();
+    if (script === "")
+        return false;
+    const wanted = String(suffix ?? "").trim();
+    if (wanted === "")
+        return false;
+    try {
+        const u = new URL(script);
+        return u.pathname.endsWith(wanted);
+    }
+    catch {
+        return script.endsWith(wanted);
+    }
+}
+async function waitForControllerSuffix(suffix, timeoutMs) {
+    const sw = globalThis.navigator?.serviceWorker;
+    if (!sw)
+        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)
+                window.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 = window.setTimeout(() => finish(isMatch()), ms);
+    });
+}
+async function uninstallConflictingServiceWorkers(conflicts) {
+    if (conflicts?.uninstallOnMismatch === false)
+        return;
+    const sw = globalThis.navigator?.serviceWorker;
+    if (!sw || typeof sw.getRegistrations !== "function")
+        return;
+    const keep = 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 keep) {
+            if (isServiceWorkerScriptPathSuffix(script, suffix)) {
+                shouldKeep = true;
+                break;
+            }
+        }
+        if (shouldKeep)
+            continue;
+        try {
+            await reg.unregister();
+        }
+        catch {
+            // Best effort cleanup.
+        }
+    }
+}
+async function maybeRepairNavigation(opts) {
+    const attempt = parseRepairAttemptFromHref(window.location.href, opts.queryKey);
+    if (attempt >= opts.maxAttempts)
+        return;
+    if (opts.strategy === "reload") {
+        window.location.reload();
+        await new Promise(() => {
+            // keep pending on navigation
+        });
+        return;
+    }
+    const next = buildHrefWithRepairAttempt(window.location.href, opts.queryKey, attempt + 1);
+    window.location.replace(next);
+    await new Promise(() => {
+        // keep pending on navigation
+    });
+}
+function applyPluginMutations(opts, plugins) {
+    let out = opts;
+    for (const plugin of plugins) {
+        if (!plugin.mutateOptions)
+            continue;
+        out = plugin.mutateOptions(out);
+    }
+    return out;
+}
+function mergeConflictPolicy(base, plugins) {
+    const keep = dedupeStrings([
+        ...(base?.keepScriptPathSuffixes ?? []),
+        ...plugins.flatMap((p) => p.serviceWorkerConflictPolicy?.keepScriptPathSuffixes ?? []),
+    ]);
+    let uninstallOnMismatch = base?.uninstallOnMismatch;
+    for (const p of plugins) {
+        if (p.serviceWorkerConflictPolicy?.uninstallOnMismatch != null) {
+            uninstallOnMismatch = p.serviceWorkerConflictPolicy.uninstallOnMismatch;
+        }
+    }
+    if (keep.length === 0 && uninstallOnMismatch == null)
+        return base;
+    const out = {};
+    if (keep.length > 0)
+        out.keepScriptPathSuffixes = keep;
+    if (uninstallOnMismatch != null)
+        out.uninstallOnMismatch = uninstallOnMismatch;
+    return out;
+}
+function shouldIgnoreMismatch(plugins, ctx) {
+    for (const plugin of plugins) {
+        const action = plugin.onControllerMismatch?.(ctx);
+        if (action === "ignore")
+            return true;
+    }
+    return false;
+}
+function buildRuntimeOptions(profile, runtime) {
+    return {
+        maxJsonFrameBytes: runtime?.maxJsonFrameBytes ?? profile.maxJsonFrameBytes,
+        maxChunkBytes: runtime?.maxChunkBytes ?? profile.maxChunkBytes,
+        maxBodyBytes: runtime?.maxBodyBytes ?? profile.maxBodyBytes,
+        maxWsFrameBytes: runtime?.maxWsFrameBytes ?? profile.maxWsFrameBytes,
+        timeoutMs: runtime?.timeoutMs ?? profile.timeoutMs,
+    };
+}
+export function createProxyIntegrationServiceWorkerScript(opts = {}) {
+    const plugins = opts.plugins ?? [];
+    let scriptOpts = opts.baseOptions ?? {};
+    for (const plugin of plugins) {
+        if (!plugin.extendServiceWorkerScriptOptions)
+            continue;
+        scriptOpts = plugin.extendServiceWorkerScriptOptions(scriptOpts);
+    }
+    const forwarded = dedupeStrings([
+        ...(scriptOpts.forwardFetchMessageTypes ?? []),
+        ...plugins.flatMap((p) => p.forwardFetchMessageTypes ?? []),
+    ]);
+    const keepSuffixes = dedupeStrings([
+        ...(scriptOpts.conflictHints?.keepScriptPathSuffixes ?? []),
+        ...plugins.flatMap((p) => p.serviceWorkerConflictPolicy?.keepScriptPathSuffixes ?? []),
+    ]);
+    const finalOpts = {
+        ...scriptOpts,
+        forwardFetchMessageTypes: forwarded,
+    };
+    if (keepSuffixes.length > 0) {
+        return createProxyServiceWorkerScript({
+            ...finalOpts,
+            conflictHints: { keepScriptPathSuffixes: keepSuffixes },
+        });
+    }
+    if (scriptOpts.conflictHints != null) {
+        return createProxyServiceWorkerScript({
+            ...finalOpts,
+            conflictHints: scriptOpts.conflictHints,
+        });
+    }
+    return createProxyServiceWorkerScript(finalOpts);
+}
+export async function registerProxyIntegration(input) {
+    const plugins = input.plugins ?? [];
+    const opts = applyPluginMutations(input, plugins);
+    const profile = resolveProxyProfile(opts.profile);
+    const runtimeOpts = buildRuntimeOptions(profile, opts.runtime);
+    const runtime = createProxyRuntime({ ...runtimeOpts, client: opts.client });
+    const swCfg = opts.serviceWorker;
+    const repairQueryKey = String(swCfg.repair?.queryKey ?? "_flowersec_sw_repair").trim() || "_flowersec_sw_repair";
+    const maxRepairAttempts = Math.max(0, Math.floor(swCfg.repair?.maxAttempts ?? 2));
+    const controllerTimeoutMs = Math.max(0, Math.floor(swCfg.repair?.controllerTimeoutMs ?? 8_000));
+    const strategy = swCfg.repair?.strategy ?? "replace";
+    const conflicts = mergeConflictPolicy(swCfg.conflicts, plugins);
+    const finalScope = String(swCfg.scope ?? "/").trim() || "/";
+    const expectedScriptPathSuffix = String(swCfg.expectedScriptPathSuffix ?? "").trim();
+    await uninstallConflictingServiceWorkers(conflicts);
+    await registerServiceWorkerAndEnsureControl({
+        scriptUrl: swCfg.scriptUrl,
+        scope: finalScope,
+        repairQueryKey,
+        maxRepairAttempts,
+        controllerTimeoutMs,
+    });
+    if (expectedScriptPathSuffix !== "") {
+        const ok = await waitForControllerSuffix(expectedScriptPathSuffix, controllerTimeoutMs);
+        if (!ok) {
+            const actual = String(globalThis.navigator?.serviceWorker?.controller?.scriptURL ?? "").trim();
+            const ctx = {
+                expectedScriptPathSuffix,
+                actualScriptURL: actual,
+                stage: "register",
+            };
+            if (!shouldIgnoreMismatch(plugins, ctx)) {
+                await uninstallConflictingServiceWorkers(conflicts);
+                await maybeRepairNavigation({ queryKey: repairQueryKey, maxAttempts: maxRepairAttempts, strategy });
+                throw new Error("Proxy Service Worker is installed but not controlling this page");
+            }
+        }
+    }
+    const monitorEnabled = swCfg.monitor?.enabled ?? true;
+    const monitorThrottleMs = Math.max(0, Math.floor(swCfg.monitor?.throttleMs ?? 10_000));
+    const sw = globalThis.navigator?.serviceWorker;
+    let monitorHandler = null;
+    let lastMonitorRepairAt = 0;
+    if (monitorEnabled && sw && expectedScriptPathSuffix !== "") {
+        monitorHandler = () => {
+            const actual = String(sw.controller?.scriptURL ?? "").trim();
+            if (isServiceWorkerScriptPathSuffix(actual, expectedScriptPathSuffix))
+                return;
+            const ctx = {
+                expectedScriptPathSuffix,
+                actualScriptURL: actual,
+                stage: "monitor",
+            };
+            if (shouldIgnoreMismatch(plugins, ctx))
+                return;
+            const now = Date.now();
+            if (monitorThrottleMs > 0 && now - lastMonitorRepairAt <= monitorThrottleMs)
+                return;
+            lastMonitorRepairAt = now;
+            void maybeRepairNavigation({ queryKey: repairQueryKey, maxAttempts: maxRepairAttempts, strategy });
+        };
+        sw.addEventListener("controllerchange", monitorHandler);
+    }
+    const ctx = {
+        runtime,
+        options: opts,
+        profile,
+    };
+    for (const plugin of plugins) {
+        await plugin.onRegistered?.(ctx);
+    }
+    return {
+        runtime,
+        dispose: async () => {
+            if (monitorHandler && sw) {
+                sw.removeEventListener("controllerchange", monitorHandler);
+            }
+            runtime.dispose();
+            for (const plugin of plugins) {
+                await plugin.onDisposed?.();
+            }
+        },
+    };
+}

package/dist/proxy/profiles.d.ts

@@ -0,0 +1,23 @@
+export type ProxyProfile = Readonly<{
+    maxJsonFrameBytes: number;
+    maxChunkBytes: number;
+    maxBodyBytes: number;
+    maxWsFrameBytes: number;
+    timeoutMs: number;
+}>;
+export type ProxyProfileName = "default" | "codeserver";
+export declare const PROXY_PROFILE_DEFAULT: Readonly<{
+    maxJsonFrameBytes: number;
+    maxChunkBytes: number;
+    maxBodyBytes: number;
+    maxWsFrameBytes: number;
+    timeoutMs: number;
+}>;
+export declare const PROXY_PROFILE_CODESERVER: Readonly<{
+    maxJsonFrameBytes: number;
+    maxChunkBytes: number;
+    maxBodyBytes: number;
+    maxWsFrameBytes: number;
+    timeoutMs: number;
+}>;
+export declare function resolveProxyProfile(profile?: ProxyProfileName | Partial<ProxyProfile>): ProxyProfile;

package/dist/proxy/profiles.js

@@ -0,0 +1,54 @@
+import { DEFAULT_MAX_BODY_BYTES, DEFAULT_MAX_CHUNK_BYTES, DEFAULT_MAX_WS_FRAME_BYTES } from "./constants.js";
+const DEFAULT_PROFILE = Object.freeze({
+    // Keep aligned with runtime defaults.
+    maxJsonFrameBytes: 0,
+    maxChunkBytes: DEFAULT_MAX_CHUNK_BYTES,
+    maxBodyBytes: DEFAULT_MAX_BODY_BYTES,
+    maxWsFrameBytes: DEFAULT_MAX_WS_FRAME_BYTES,
+    timeoutMs: 0,
+});
+const CODESERVER_PROFILE = Object.freeze({
+    maxJsonFrameBytes: 0,
+    maxChunkBytes: DEFAULT_MAX_CHUNK_BYTES,
+    maxBodyBytes: DEFAULT_MAX_BODY_BYTES,
+    // Keep aligned with redeven/redeven-agent production profile.
+    maxWsFrameBytes: 32 * 1024 * 1024,
+    timeoutMs: 0,
+});
+export const PROXY_PROFILE_DEFAULT = DEFAULT_PROFILE;
+export const PROXY_PROFILE_CODESERVER = CODESERVER_PROFILE;
+function normalizeSafeInt(name, value) {
+    if (!Number.isFinite(value))
+        throw new Error(`${name} must be a finite number`);
+    const n = Math.floor(value);
+    if (!Number.isSafeInteger(n))
+        throw new Error(`${name} must be a safe integer`);
+    if (n < 0)
+        throw new Error(`${name} must be >= 0`);
+    return n;
+}
+function resolveNamedProfile(name) {
+    switch (name) {
+        case "default":
+            return DEFAULT_PROFILE;
+        case "codeserver":
+            return CODESERVER_PROFILE;
+        default:
+            throw new Error(`unknown proxy profile: ${name}`);
+    }
+}
+export function resolveProxyProfile(profile) {
+    if (profile == null)
+        return DEFAULT_PROFILE;
+    if (typeof profile === "string") {
+        return resolveNamedProfile(profile);
+    }
+    const base = DEFAULT_PROFILE;
+    return Object.freeze({
+        maxJsonFrameBytes: normalizeSafeInt("maxJsonFrameBytes", profile.maxJsonFrameBytes ?? base.maxJsonFrameBytes),
+        maxChunkBytes: normalizeSafeInt("maxChunkBytes", profile.maxChunkBytes ?? base.maxChunkBytes),
+        maxBodyBytes: normalizeSafeInt("maxBodyBytes", profile.maxBodyBytes ?? base.maxBodyBytes),
+        maxWsFrameBytes: normalizeSafeInt("maxWsFrameBytes", profile.maxWsFrameBytes ?? base.maxWsFrameBytes),
+        timeoutMs: normalizeSafeInt("timeoutMs", profile.timeoutMs ?? base.timeoutMs),
+    });
+}

package/dist/proxy/serviceWorker.d.ts

@@ -30,5 +30,9 @@ export type ProxyServiceWorkerScriptOptions = Readonly<{
     proxyPathPrefix?: string;
     stripProxyPathPrefix?: boolean;
     injectHTML?: ProxyServiceWorkerInjectHTMLOptions;
+    forwardFetchMessageTypes?: readonly string[];
+    conflictHints?: Readonly<{
+        keepScriptPathSuffixes?: readonly string[];
+    }>;
 }>;
 export declare function createProxyServiceWorkerScript(opts?: ProxyServiceWorkerScriptOptions): string;

package/dist/proxy/serviceWorker.js

@@ -25,6 +25,20 @@ function normalizePathList(name, input) {
     }
     return Array.from(new Set(out));
 }
+function normalizeMessageTypeList(name, input) {
+    const out = [];
+    if (input == null || input.length === 0)
+        return out;
+    for (const raw of input) {
+        const s = typeof raw === "string" ? raw.trim() : "";
+        if (s === "")
+            continue;
+        if (/[\r\n]/.test(s))
+            throw new Error(`${name} must not contain newline`);
+        out.push(s);
+    }
+    return Array.from(new Set(out));
+}
 const defaultMaxInjectHTMLBytes = 2 * 1024 * 1024;
 function normalizeMaxBytes(name, v, defaultValue) {
     if (v == null)
@@ -58,6 +72,8 @@ export function createProxyServiceWorkerScript(opts = {}) {
     }
     const passthroughPaths = normalizePathList("passthrough.paths", opts.passthrough?.paths);
     const passthroughPrefixes = normalizePathList("passthrough.prefixes", opts.passthrough?.prefixes);
+    const forwardFetchMessageTypes = normalizeMessageTypeList("forwardFetchMessageTypes", opts.forwardFetchMessageTypes);
+    const keepScriptPathSuffixes = normalizePathList("conflictHints.keepScriptPathSuffixes", opts.conflictHints?.keepScriptPathSuffixes);
     const injectHTML = opts.injectHTML ?? null;
     // Injection mode defaults to inline_module when injectHTML is provided.
     const injectMode = injectHTML?.mode ?? "inline_module";
@@ -116,6 +132,8 @@ const INJECT_SET_NO_STORE = ${JSON.stringify(setNoStore)};
 
 const MAX_REQUEST_BODY_BYTES = ${JSON.stringify(maxRequestBodyBytes)};
 const MAX_INJECT_HTML_BYTES = ${JSON.stringify(maxInjectHTMLBytes)};
+const FORWARD_FETCH_MESSAGE_TYPES = new Set(${JSON.stringify(forwardFetchMessageTypes)});
+const CONFLICT_HINT_KEEP_SCRIPT_SUFFIXES = ${JSON.stringify(keepScriptPathSuffixes)};
 
 const INJECT_STRIP_HEADER_NAMES = new Set(["content-length", "etag", "last-modified", "content-md5"]);
 
@@ -133,8 +151,32 @@ self.addEventListener("activate", (event) => {
 self.addEventListener("message", (event) => {
   const data = event.data;
   if (!data || typeof data !== "object") return;
-  if (data.type !== "flowersec-proxy:register-runtime") return;
-  if (event.source && typeof event.source.id === "string") runtimeClientId = event.source.id;
+  const msgType = typeof data.type === "string" ? data.type : "";
+  if (msgType === "flowersec-proxy:register-runtime") {
+    if (event.source && typeof event.source.id === "string") runtimeClientId = event.source.id;
+    return;
+  }
+  if (!FORWARD_FETCH_MESSAGE_TYPES.has(msgType)) return;
+
+  const port = event.ports && event.ports[0];
+  if (!port) return;
+
+  event.waitUntil((async () => {
+    const runtime = await getRuntimeClient();
+    if (!runtime) {
+      try { port.postMessage({ type: "flowersec-proxy:response_error", status: 503, message: "flowersec-proxy runtime not available" }); } catch {}
+      try { port.close(); } catch {}
+      return;
+    }
+
+    try {
+      runtime.postMessage({ type: "flowersec-proxy:fetch", req: data.req }, [port]);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      try { port.postMessage({ type: "flowersec-proxy:response_error", status: 502, message: msg }); } catch {}
+      try { port.close(); } catch {}
+    }
+  })());
 });
 
 async function getRuntimeClient() {

package/dist/reconnect/index.d.ts

@@ -28,6 +28,7 @@ export type ReconnectManager = Readonly<{
     state: () => ReconnectState;
     subscribe: (listener: ReconnectListener) => () => void;
     connect: (config: ConnectConfig) => Promise<void>;
+    connectIfNeeded: (config: ConnectConfig) => Promise<void>;
     disconnect: () => void;
 }>;
 export declare function createReconnectManager(): ReconnectManager;

package/dist/reconnect/index.js

@@ -23,6 +23,22 @@ function backoffDelayMs(attemptIndex, cfg) {
     const jitter = cfg.jitterRatio <= 0 ? 0 : base * cfg.jitterRatio * (Math.random() * 2 - 1);
     return Math.max(0, Math.round(base + jitter));
 }
+function isSameConfig(a, b) {
+    if (a == null)
+        return false;
+    if (a.connectOnce !== b.connectOnce)
+        return false;
+    if (a.observer !== b.observer)
+        return false;
+    const aa = normalizeAutoReconnect(a.autoReconnect);
+    const bb = normalizeAutoReconnect(b.autoReconnect);
+    return (aa.enabled === bb.enabled &&
+        aa.maxAttempts === bb.maxAttempts &&
+        aa.initialDelayMs === bb.initialDelayMs &&
+        aa.maxDelayMs === bb.maxDelayMs &&
+        aa.factor === bb.factor &&
+        aa.jitterRatio === bb.jitterRatio);
+}
 export function createReconnectManager() {
     let s = { status: "disconnected", error: null, client: null };
     const listeners = new Set();
@@ -39,6 +55,7 @@ export function createReconnectManager() {
     };
     let token = 0;
     let active = null;
+    let activeConnectPromise = null;
     let retryTimer = null;
     let retryResolve = null;
     let attemptAbort = null;
@@ -71,6 +88,7 @@ export function createReconnectManager() {
         cancelRetrySleep();
         abortActiveAttempt();
         active = null;
+        activeConnectPromise = null;
         token += 1;
         if (s.client) {
             try {
@@ -209,7 +227,26 @@ export function createReconnectManager() {
             }
         }
         setState({ status: "connecting", error: null, client: null });
-        await connectWithRetry(t, cfg);
+        const p = connectWithRetry(t, cfg);
+        activeConnectPromise = p;
+        try {
+            await p;
+        }
+        finally {
+            if (activeConnectPromise === p)
+                activeConnectPromise = null;
+        }
+    };
+    const connectIfNeeded = async (cfg) => {
+        if (isSameConfig(active, cfg)) {
+            if (s.status === "connected" && s.client)
+                return;
+            if (s.status === "connecting" && activeConnectPromise) {
+                await activeConnectPromise;
+                return;
+            }
+        }
+        await connect(cfg);
     };
     const disconnect = () => {
         disconnectInternal();
@@ -230,6 +267,7 @@ export function createReconnectManager() {
             };
         },
         connect,
+        connectIfNeeded,
         disconnect,
     };
 }

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

@@ -1,6 +1,8 @@
 import { type ConnectOptionsBase } from "../client-connect/connectCore.js";
 import type { ClientInternal } from "../client.js";
 export type TunnelConnectOptions = ConnectOptionsBase & Readonly<{
+    /** Type-only marker to prevent mixing direct and tunnel option types. */
+    __mode?: "tunnel";
     /** Optional caller-provided endpoint instance ID (base64url). */
     endpointInstanceId?: string;
 }>;

package/package.json

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