@floegence/flowersec-core 0.18.0 → 0.19.1

package/dist/proxy/runtimeScope.js

@@ -0,0 +1,223 @@
+import { assertProxyPresetManifest, resolveNamedProxyPreset, } from "./preset.js";
+const RUNTIME_SCOPE_NAME = "proxy.runtime";
+const PRESET_ID_RE = /^[a-z][a-z0-9._-]{0,63}$/;
+const MAX_RUNTIME_PAYLOAD_BYTES = 8 * 1024;
+const MAX_RUNTIME_DEPTH = 8;
+const MAX_RUNTIME_FIELDS = 64;
+const MAX_RUNTIME_SNAPSHOT_BYTES = 4 * 1024;
+function isRecord(value) {
+    return typeof value === "object" && value != null && !Array.isArray(value);
+}
+function assertNoUnknownFields(kind, value, allowed) {
+    const allowedSet = new Set(allowed);
+    for (const key of Object.keys(value)) {
+        if (!allowedSet.has(key))
+            throw new Error(`bad ${kind}.${key}`);
+    }
+}
+function assertPositiveInt(name, value) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+        throw new Error(`bad ${name}`);
+    }
+    return value;
+}
+function utf8Len(value) {
+    return new TextEncoder().encode(value).length;
+}
+function maxContainerDepth(value) {
+    if (Array.isArray(value)) {
+        let best = 1;
+        for (const entry of value)
+            best = Math.max(best, 1 + maxContainerDepth(entry));
+        return best;
+    }
+    if (isRecord(value)) {
+        let best = 1;
+        for (const entry of Object.values(value))
+            best = Math.max(best, 1 + maxContainerDepth(entry));
+        return best;
+    }
+    return 0;
+}
+function countFields(value) {
+    if (Array.isArray(value))
+        return value.reduce((total, entry) => total + countFields(entry), 0);
+    if (isRecord(value)) {
+        return Object.entries(value).reduce((total, [, entry]) => total + 1 + countFields(entry), 0);
+    }
+    return 0;
+}
+function assertRuntimePayloadEnvelope(payload) {
+    if (!isRecord(payload))
+        throw new Error("bad proxy.runtime.payload");
+    if (utf8Len(JSON.stringify(payload)) > MAX_RUNTIME_PAYLOAD_BYTES)
+        throw new Error("bad proxy.runtime.payload");
+    if (maxContainerDepth(payload) > MAX_RUNTIME_DEPTH)
+        throw new Error("bad proxy.runtime.payload");
+    if (countFields(payload) > MAX_RUNTIME_FIELDS)
+        throw new Error("bad proxy.runtime.payload");
+    return payload;
+}
+function assertServiceWorkerConfig(value) {
+    if (!isRecord(value))
+        throw new Error("bad proxy.runtime.serviceWorker");
+    assertNoUnknownFields("proxy.runtime.serviceWorker", value, ["scriptUrl", "scope"]);
+    const scriptUrl = String(value.scriptUrl ?? "").trim();
+    const scope = String(value.scope ?? "").trim();
+    if (scriptUrl === "")
+        throw new Error("bad proxy.runtime.serviceWorker.scriptUrl");
+    if (scope === "")
+        throw new Error("bad proxy.runtime.serviceWorker.scope");
+    return Object.freeze({ scriptUrl, scope });
+}
+function assertAllowedOrigins(value) {
+    if (!Array.isArray(value))
+        throw new Error("bad proxy.runtime.controllerBridge.allowedOrigins");
+    const out = [];
+    const seen = new Set();
+    for (const entry of value) {
+        const normalized = String(entry ?? "").trim();
+        if (normalized === "" || seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        out.push(normalized);
+    }
+    if (out.length === 0)
+        throw new Error("bad proxy.runtime.controllerBridge.allowedOrigins");
+    return Object.freeze(out);
+}
+function assertControllerBridgeConfig(value) {
+    if (!isRecord(value))
+        throw new Error("bad proxy.runtime.controllerBridge");
+    assertNoUnknownFields("proxy.runtime.controllerBridge", value, ["allowedOrigins"]);
+    return Object.freeze({
+        allowedOrigins: assertAllowedOrigins(value.allowedOrigins),
+    });
+}
+function assertLimits(value) {
+    if (!isRecord(value))
+        throw new Error("bad proxy.runtime.limits");
+    assertNoUnknownFields("proxy.runtime.limits", value, [
+        "timeoutMs",
+        "maxJsonFrameBytes",
+        "maxChunkBytes",
+        "maxBodyBytes",
+        "maxWsFrameBytes",
+    ]);
+    const out = {};
+    if (value.timeoutMs !== undefined)
+        out.timeoutMs = assertPositiveInt("proxy.runtime.limits.timeoutMs", value.timeoutMs);
+    if (value.maxJsonFrameBytes !== undefined) {
+        out.maxJsonFrameBytes = assertPositiveInt("proxy.runtime.limits.maxJsonFrameBytes", value.maxJsonFrameBytes);
+    }
+    if (value.maxChunkBytes !== undefined)
+        out.maxChunkBytes = assertPositiveInt("proxy.runtime.limits.maxChunkBytes", value.maxChunkBytes);
+    if (value.maxBodyBytes !== undefined)
+        out.maxBodyBytes = assertPositiveInt("proxy.runtime.limits.maxBodyBytes", value.maxBodyBytes);
+    if (value.maxWsFrameBytes !== undefined)
+        out.maxWsFrameBytes = assertPositiveInt("proxy.runtime.limits.maxWsFrameBytes", value.maxWsFrameBytes);
+    return Object.freeze(out);
+}
+function assertPreset(value) {
+    if (!isRecord(value))
+        throw new Error("bad proxy.runtime.preset");
+    assertNoUnknownFields("proxy.runtime.preset", value, ["presetId", "snapshot"]);
+    const presetId = String(value.presetId ?? "").trim();
+    if (!PRESET_ID_RE.test(presetId))
+        throw new Error("bad proxy.runtime.preset.presetId");
+    if (value.snapshot === undefined) {
+        return Object.freeze({ presetId });
+    }
+    const snapshot = assertProxyPresetManifest(value.snapshot);
+    if (utf8Len(JSON.stringify(snapshot)) > MAX_RUNTIME_SNAPSHOT_BYTES)
+        throw new Error("bad proxy.runtime.preset.snapshot");
+    return Object.freeze({ presetId, snapshot });
+}
+export function assertProxyRuntimeScopeV1(payload) {
+    const value = assertRuntimePayloadEnvelope(payload);
+    assertNoUnknownFields("proxy.runtime", value, [
+        "mode",
+        "appBasePath",
+        "serviceWorker",
+        "controllerBridge",
+        "preset",
+        "limits",
+    ]);
+    const mode = value.mode;
+    if (mode !== "service_worker" && mode !== "controller_bridge") {
+        throw new Error("bad proxy.runtime.mode");
+    }
+    const appBasePath = value.appBasePath === undefined ? undefined : String(value.appBasePath ?? "").trim();
+    if (value.appBasePath !== undefined && appBasePath === "") {
+        throw new Error("bad proxy.runtime.appBasePath");
+    }
+    const preset = assertPreset(value.preset);
+    const limits = value.limits === undefined ? undefined : assertLimits(value.limits);
+    if (mode === "service_worker") {
+        if (value.controllerBridge !== undefined)
+            throw new Error("bad proxy.runtime.controllerBridge");
+        const serviceWorker = assertServiceWorkerConfig(value.serviceWorker);
+        return Object.freeze({
+            mode,
+            ...(appBasePath === undefined ? {} : { appBasePath }),
+            serviceWorker,
+            preset,
+            ...(limits === undefined ? {} : { limits }),
+        });
+    }
+    if (value.serviceWorker !== undefined)
+        throw new Error("bad proxy.runtime.serviceWorker");
+    const controllerBridge = assertControllerBridgeConfig(value.controllerBridge);
+    return Object.freeze({
+        mode,
+        ...(appBasePath === undefined ? {} : { appBasePath }),
+        controllerBridge,
+        preset,
+        ...(limits === undefined ? {} : { limits }),
+    });
+}
+export function extractProxyRuntimeScopeV1(artifact, mode) {
+    const scoped = artifact.scoped ?? [];
+    const entry = scoped.find((item) => item.scope === RUNTIME_SCOPE_NAME);
+    if (!entry) {
+        throw new Error("missing proxy.runtime@1 scope");
+    }
+    if (entry.scope_version !== 1) {
+        throw new Error(`unsupported proxy.runtime scope_version: ${entry.scope_version}`);
+    }
+    const scope = assertProxyRuntimeScopeV1(entry.payload);
+    if (scope.mode !== mode) {
+        throw new Error(`proxy.runtime mode mismatch: expected ${mode}`);
+    }
+    return scope;
+}
+export function resolveRuntimeLimitsFromScope(scope, overrides) {
+    const merged = {
+        ...(scope.limits ?? {}),
+        ...(overrides ?? {}),
+    };
+    return Object.keys(merged).length === 0 ? undefined : merged;
+}
+export function resolvePresetInputFromScope(scope, presetOverride) {
+    if (presetOverride !== undefined)
+        return presetOverride;
+    if (scope.preset.snapshot)
+        return scope.preset.snapshot;
+    try {
+        return resolveNamedProxyPreset(scope.preset.presetId);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function resolveRuntimePresetLimits(scope) {
+    if (scope.limits === undefined)
+        return undefined;
+    return Object.freeze({
+        ...(scope.limits.maxJsonFrameBytes === undefined ? {} : { max_json_frame_bytes: scope.limits.maxJsonFrameBytes }),
+        ...(scope.limits.maxChunkBytes === undefined ? {} : { max_chunk_bytes: scope.limits.maxChunkBytes }),
+        ...(scope.limits.maxBodyBytes === undefined ? {} : { max_body_bytes: scope.limits.maxBodyBytes }),
+        ...(scope.limits.maxWsFrameBytes === undefined ? {} : { max_ws_frame_bytes: scope.limits.maxWsFrameBytes }),
+        ...(scope.limits.timeoutMs === undefined ? {} : { timeout_ms: scope.limits.timeoutMs }),
+    });
+}

package/dist/proxy/serviceWorker.js

@@ -159,6 +159,7 @@ self.addEventListener("install", (event) => {
 });
 
 self.addEventListener("activate", (event) => {
+  runtimeClientId = null;
   event.waitUntil(self.clients.claim());
 });
 
@@ -207,16 +208,10 @@ async function getWindowClient(preferredClientId) {
     return cs.length > 0 ? cs[0] : null;
   }
 
-  if (runtimeClientId) {
-    const c = await self.clients.get(runtimeClientId);
-    if (c) return c;
-    runtimeClientId = null;
-  }
-  const cs = await self.clients.matchAll({ type: "window", includeUncontrolled: true });
-  if (cs.length > 0) {
-    runtimeClientId = cs[0].id;
-    return cs[0];
-  }
+  if (!runtimeClientId) return null;
+  const c = await self.clients.get(runtimeClientId);
+  if (c) return c;
+  runtimeClientId = null;
   return null;
 }
 

package/dist/reconnect/artifactControlplane.d.ts

@@ -0,0 +1,13 @@
+import type { ConnectArtifact } from "../connect/artifact.js";
+import { type RequestConnectArtifactInput, type RequestEntryConnectArtifactInput } from "../controlplane/index.js";
+export type ArtifactFactoryArgs = Readonly<{
+    traceId?: string;
+    signal?: AbortSignal;
+}>;
+export type ArtifactAwareReconnectConfig = Readonly<{
+    artifact?: ConnectArtifact;
+    getArtifact?: (args: ArtifactFactoryArgs) => Promise<ConnectArtifact>;
+    artifactControlplane?: RequestConnectArtifactInput | RequestEntryConnectArtifactInput;
+}>;
+export declare function resolveConnectArtifact(config: ArtifactAwareReconnectConfig, traceId?: string, signal?: AbortSignal): Promise<ConnectArtifact>;
+export declare function updateTraceId(current: string | undefined, artifact: ConnectArtifact): string | undefined;

package/dist/reconnect/artifactControlplane.js

@@ -0,0 +1,34 @@
+import { requestConnectArtifact, requestEntryConnectArtifact, } from "../controlplane/index.js";
+export async function resolveConnectArtifact(config, traceId, signal) {
+    if (config.getArtifact) {
+        return await config.getArtifact({
+            ...(traceId === undefined ? {} : { traceId }),
+            ...(signal === undefined ? {} : { signal }),
+        });
+    }
+    if (config.artifact)
+        return config.artifact;
+    if (config.artifactControlplane) {
+        const correlation = traceId === undefined
+            ? config.artifactControlplane.correlation
+            : { traceId };
+        if ("entryTicket" in config.artifactControlplane) {
+            const input = {
+                ...config.artifactControlplane,
+                ...(correlation === undefined ? {} : { correlation }),
+                ...(signal === undefined ? {} : { signal }),
+            };
+            return await requestEntryConnectArtifact(input);
+        }
+        const input = {
+            ...config.artifactControlplane,
+            ...(correlation === undefined ? {} : { correlation }),
+            ...(signal === undefined ? {} : { signal }),
+        };
+        return await requestConnectArtifact(input);
+    }
+    throw new Error("Artifact reconnect config requires `getArtifact`, `artifact`, or `artifactControlplane`");
+}
+export function updateTraceId(current, artifact) {
+    return artifact.correlation?.trace_id ?? current;
+}

package/dist/utils/errors.d.ts

@@ -6,7 +6,7 @@ export declare class AbortError extends Error {
 }
 export type FlowersecPath = "auto" | "tunnel" | "direct";
 export type FlowersecStage = "validate" | "connect" | "attach" | "handshake" | "secure" | "yamux" | "rpc" | "close";
-export type FlowersecErrorCode = "timeout" | "canceled" | "invalid_version" | "invalid_input" | "invalid_option" | "invalid_endpoint_instance_id" | "invalid_psk" | "invalid_suite" | "missing_grant" | "missing_connect_info" | "missing_conn" | "missing_handler" | "missing_stream_kind" | "role_mismatch" | "missing_tunnel_url" | "missing_ws_url" | "missing_origin" | "missing_channel_id" | "missing_token" | "missing_init_exp" | "timestamp_after_init_exp" | "timestamp_out_of_skew" | "auth_tag_mismatch" | "resolve_failed" | "random_failed" | "upgrade_failed" | "dial_failed" | "attach_failed" | "too_many_connections" | "expected_attach" | "invalid_attach" | "invalid_token" | "channel_mismatch" | "init_exp_mismatch" | "idle_timeout_mismatch" | "token_replay" | "replace_rate_limited" | "handshake_failed" | "ping_failed" | "mux_failed" | "accept_stream_failed" | "open_stream_failed" | "stream_hello_failed" | "rpc_failed" | "not_connected";
+export type FlowersecErrorCode = "timeout" | "canceled" | "invalid_version" | "invalid_input" | "invalid_option" | "invalid_endpoint_instance_id" | "invalid_psk" | "invalid_suite" | "missing_grant" | "missing_connect_info" | "missing_conn" | "missing_handler" | "missing_stream_kind" | "role_mismatch" | "missing_tunnel_url" | "missing_ws_url" | "missing_origin" | "missing_channel_id" | "missing_token" | "missing_init_exp" | "timestamp_after_init_exp" | "timestamp_out_of_skew" | "auth_tag_mismatch" | "resolve_failed" | "random_failed" | "upgrade_failed" | "dial_failed" | "attach_failed" | "too_many_connections" | "expected_attach" | "invalid_attach" | "invalid_token" | "channel_mismatch" | "init_exp_mismatch" | "idle_timeout_mismatch" | "token_replay" | "tenant_mismatch" | "policy_denied" | "policy_error" | "replace_rate_limited" | "handshake_failed" | "ping_failed" | "mux_failed" | "accept_stream_failed" | "open_stream_failed" | "stream_hello_failed" | "rpc_failed" | "not_connected";
 export declare class FlowersecError extends Error {
     readonly code: FlowersecErrorCode;
     readonly stage: FlowersecStage;

package/dist/utils/errors.js

@@ -17,7 +17,9 @@ export class FlowersecError extends Error {
     cause;
     constructor(args) {
         const prefix = `${args.path} ${args.stage} (${args.code})`;
-        const message = args.message != null && args.message !== "" ? `${prefix}: ${args.message}` : prefix;
+        const message = args.message != null && args.message !== ""
+            ? `${prefix}: ${args.message}`
+            : prefix;
         super(message, args.cause !== undefined ? { cause: args.cause } : undefined);
         this.name = "FlowersecError";
         this.code = args.code;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floegence/flowersec-core",
-  "version": "0.18.0",
+  "version": "0.19.1",
   "description": "Flowersec core TypeScript library (browser-friendly E2EE + multiplexing over WebSocket).",
   "license": "MIT",
   "repository": {
@@ -36,6 +36,10 @@
       "types": "./dist/browser/index.d.ts",
       "default": "./dist/browser/index.js"
     },
+    "./controlplane": {
+      "types": "./dist/controlplane/index.d.ts",
+      "default": "./dist/controlplane/index.js"
+    },
     "./framing": {
       "types": "./dist/framing/index.d.ts",
       "default": "./dist/framing/index.js"
@@ -102,7 +106,7 @@
     }
   },
   "engines": {
-    "node": "^20.0.0 || ^22.0.0 || >=24.0.0"
+    "node": ">=24.0.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
@@ -121,7 +125,7 @@
     "ws": "^8.18.0"
   },
   "devDependencies": {
-    "@types/node": "^22.10.0",
+    "@types/node": "^24.0.0",
     "@types/ws": "^8.5.12",
     "@typescript-eslint/eslint-plugin": "^8.18.0",
     "@typescript-eslint/parser": "^8.18.0",