@floegence/flowersec-core 0.17.2 → 0.19.0

package/dist/proxy/preset.js

@@ -0,0 +1,133 @@
+import { DEFAULT_MAX_JSON_FRAME_BYTES } from "../framing/jsonframe.js";
+import { DEFAULT_MAX_BODY_BYTES, DEFAULT_MAX_CHUNK_BYTES, DEFAULT_MAX_WS_FRAME_BYTES } from "./constants.js";
+const PRESET_ID_RE = /^[a-z][a-z0-9._-]{0,63}$/;
+const DEFAULT_LIMITS = Object.freeze({
+    max_json_frame_bytes: DEFAULT_MAX_JSON_FRAME_BYTES,
+    max_chunk_bytes: DEFAULT_MAX_CHUNK_BYTES,
+    max_body_bytes: DEFAULT_MAX_BODY_BYTES,
+    max_ws_frame_bytes: DEFAULT_MAX_WS_FRAME_BYTES,
+});
+export const DEFAULT_PROXY_PRESET_MANIFEST = Object.freeze({
+    v: 1,
+    preset_id: "default",
+    limits: {
+        max_json_frame_bytes: DEFAULT_MAX_JSON_FRAME_BYTES,
+        max_chunk_bytes: DEFAULT_MAX_CHUNK_BYTES,
+        max_body_bytes: DEFAULT_MAX_BODY_BYTES,
+        max_ws_frame_bytes: DEFAULT_MAX_WS_FRAME_BYTES,
+    },
+});
+export const CODESERVER_PROXY_PRESET_MANIFEST = Object.freeze({
+    v: 1,
+    preset_id: "codeserver",
+    deprecated: true,
+    limits: {
+        max_json_frame_bytes: DEFAULT_MAX_JSON_FRAME_BYTES,
+        max_chunk_bytes: DEFAULT_MAX_CHUNK_BYTES,
+        max_body_bytes: DEFAULT_MAX_BODY_BYTES,
+        max_ws_frame_bytes: 32 * 1024 * 1024,
+    },
+});
+function isRecord(v) {
+    return typeof v === "object" && v != null && !Array.isArray(v);
+}
+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(`${name} must be a positive safe integer`);
+    }
+    return value;
+}
+function assertLimits(value) {
+    if (!isRecord(value))
+        throw new Error("bad ProxyPresetManifest.limits");
+    assertNoUnknownFields("ProxyPresetManifest.limits", value, [
+        "max_json_frame_bytes",
+        "max_chunk_bytes",
+        "max_body_bytes",
+        "max_ws_frame_bytes",
+        "timeout_ms",
+    ]);
+    const out = {};
+    if (value.max_json_frame_bytes !== undefined)
+        out.max_json_frame_bytes = assertPositiveInt("max_json_frame_bytes", value.max_json_frame_bytes);
+    if (value.max_chunk_bytes !== undefined)
+        out.max_chunk_bytes = assertPositiveInt("max_chunk_bytes", value.max_chunk_bytes);
+    if (value.max_body_bytes !== undefined)
+        out.max_body_bytes = assertPositiveInt("max_body_bytes", value.max_body_bytes);
+    if (value.max_ws_frame_bytes !== undefined)
+        out.max_ws_frame_bytes = assertPositiveInt("max_ws_frame_bytes", value.max_ws_frame_bytes);
+    if (value.timeout_ms !== undefined)
+        out.timeout_ms = assertPositiveInt("timeout_ms", value.timeout_ms);
+    return Object.freeze(out);
+}
+export function assertProxyPresetManifest(value) {
+    if (!isRecord(value))
+        throw new Error("bad ProxyPresetManifest");
+    assertNoUnknownFields("ProxyPresetManifest", value, ["v", "preset_id", "deprecated", "limits"]);
+    if (value.v !== 1)
+        throw new Error("bad ProxyPresetManifest.v");
+    if (typeof value.preset_id !== "string" || !PRESET_ID_RE.test(value.preset_id)) {
+        throw new Error("bad ProxyPresetManifest.preset_id");
+    }
+    if (value.deprecated !== undefined && typeof value.deprecated !== "boolean") {
+        throw new Error("bad ProxyPresetManifest.deprecated");
+    }
+    return Object.freeze({
+        v: 1,
+        preset_id: value.preset_id,
+        ...(value.deprecated === undefined ? {} : { deprecated: value.deprecated }),
+        limits: assertLimits(value.limits),
+    });
+}
+export function resolveNamedProxyPreset(name) {
+    switch (String(name ?? "").trim()) {
+        case "":
+        case "default":
+            return DEFAULT_PROXY_PRESET_MANIFEST;
+        case "codeserver":
+            return CODESERVER_PROXY_PRESET_MANIFEST;
+        default:
+            throw new Error(`unknown proxy preset: ${name}`);
+    }
+}
+function toResolved(manifest) {
+    return Object.freeze({
+        v: 1,
+        preset_id: manifest.preset_id,
+        deprecated: manifest.deprecated === true,
+        limits: Object.freeze({
+            max_json_frame_bytes: manifest.limits.max_json_frame_bytes ?? DEFAULT_LIMITS.max_json_frame_bytes,
+            max_chunk_bytes: manifest.limits.max_chunk_bytes ?? DEFAULT_LIMITS.max_chunk_bytes,
+            max_body_bytes: manifest.limits.max_body_bytes ?? DEFAULT_LIMITS.max_body_bytes,
+            max_ws_frame_bytes: manifest.limits.max_ws_frame_bytes ?? DEFAULT_LIMITS.max_ws_frame_bytes,
+            ...(manifest.limits.timeout_ms === undefined ? {} : { timeout_ms: manifest.limits.timeout_ms }),
+        }),
+    });
+}
+export function resolveProxyPreset(input) {
+    if (input == null)
+        return toResolved(DEFAULT_PROXY_PRESET_MANIFEST);
+    if (isRecord(input) && ("v" in input || "presetId" in input || "limits" in input)) {
+        return toResolved(assertProxyPresetManifest(input));
+    }
+    const limits = assertLimits(input);
+    return Object.freeze({
+        v: 1,
+        preset_id: "custom",
+        deprecated: false,
+        limits: Object.freeze({
+            max_json_frame_bytes: limits.max_json_frame_bytes ?? DEFAULT_LIMITS.max_json_frame_bytes,
+            max_chunk_bytes: limits.max_chunk_bytes ?? DEFAULT_LIMITS.max_chunk_bytes,
+            max_body_bytes: limits.max_body_bytes ?? DEFAULT_LIMITS.max_body_bytes,
+            max_ws_frame_bytes: limits.max_ws_frame_bytes ?? DEFAULT_LIMITS.max_ws_frame_bytes,
+            ...(limits.timeout_ms === undefined ? {} : { timeout_ms: limits.timeout_ms }),
+        }),
+    });
+}

package/dist/proxy/profiles.d.ts

@@ -1,3 +1,4 @@
+import { type ProxyPresetManifest } from "./preset.js";
 export type ProxyProfile = Readonly<{
     maxJsonFrameBytes: number;
     maxChunkBytes: number;
@@ -21,3 +22,4 @@ export declare const PROXY_PROFILE_CODESERVER: Readonly<{
     timeoutMs: number;
 }>;
 export declare function resolveProxyProfile(profile?: ProxyProfileName | Partial<ProxyProfile>): ProxyProfile;
+export declare function profileToPresetManifest(profile?: ProxyProfileName | Partial<ProxyProfile>): ProxyPresetManifest;

package/dist/proxy/profiles.js

@@ -1,20 +1,16 @@
-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,
-});
+import { CODESERVER_PROXY_PRESET_MANIFEST, DEFAULT_PROXY_PRESET_MANIFEST, resolveProxyPreset, } from "./preset.js";
+function toLegacyProfile(manifest) {
+    const resolved = resolveProxyPreset(manifest);
+    return Object.freeze({
+        maxJsonFrameBytes: resolved.limits.max_json_frame_bytes,
+        maxChunkBytes: resolved.limits.max_chunk_bytes,
+        maxBodyBytes: resolved.limits.max_body_bytes,
+        maxWsFrameBytes: resolved.limits.max_ws_frame_bytes,
+        timeoutMs: resolved.limits.timeout_ms ?? 0,
+    });
+}
+const DEFAULT_PROFILE = toLegacyProfile(DEFAULT_PROXY_PRESET_MANIFEST);
+const CODESERVER_PROFILE = toLegacyProfile(CODESERVER_PROXY_PRESET_MANIFEST);
 export const PROXY_PROFILE_DEFAULT = DEFAULT_PROFILE;
 export const PROXY_PROFILE_CODESERVER = CODESERVER_PROFILE;
 function normalizeSafeInt(name, value) {
@@ -52,3 +48,30 @@ export function resolveProxyProfile(profile) {
         timeoutMs: normalizeSafeInt("timeoutMs", profile.timeoutMs ?? base.timeoutMs),
     });
 }
+export function profileToPresetManifest(profile) {
+    if (profile == null)
+        return DEFAULT_PROXY_PRESET_MANIFEST;
+    if (typeof profile === "string") {
+        switch (profile) {
+            case "default":
+                return DEFAULT_PROXY_PRESET_MANIFEST;
+            case "codeserver":
+                return CODESERVER_PROXY_PRESET_MANIFEST;
+            default:
+                throw new Error(`unknown proxy profile: ${profile}`);
+        }
+    }
+    const resolved = resolveProxyProfile(profile);
+    return Object.freeze({
+        v: 1,
+        preset_id: "legacy-profile",
+        deprecated: true,
+        limits: {
+            ...(resolved.maxJsonFrameBytes > 0 ? { max_json_frame_bytes: resolved.maxJsonFrameBytes } : {}),
+            ...(resolved.maxChunkBytes > 0 ? { max_chunk_bytes: resolved.maxChunkBytes } : {}),
+            ...(resolved.maxBodyBytes > 0 ? { max_body_bytes: resolved.maxBodyBytes } : {}),
+            ...(resolved.maxWsFrameBytes > 0 ? { max_ws_frame_bytes: resolved.maxWsFrameBytes } : {}),
+            ...(resolved.timeoutMs > 0 ? { timeout_ms: resolved.timeoutMs } : {}),
+        },
+    });
+}

package/dist/proxy/runtimeScope.d.ts

@@ -0,0 +1,49 @@
+import type { ConnectArtifact, ScopePayload } from "../connect/artifact.js";
+import { assertProxyPresetManifest, type ProxyPresetInput, type ProxyPresetLimits } from "./preset.js";
+export type ProxyPresetSnapshotV1 = ReturnType<typeof assertProxyPresetManifest>;
+type ProxyRuntimeScopeBaseV1 = Readonly<{
+    appBasePath?: string;
+    preset: Readonly<{
+        presetId: string;
+        snapshot?: ProxyPresetSnapshotV1;
+    }>;
+    limits?: Readonly<{
+        timeoutMs?: number;
+        maxJsonFrameBytes?: number;
+        maxChunkBytes?: number;
+        maxBodyBytes?: number;
+        maxWsFrameBytes?: number;
+    }>;
+}>;
+export type ProxyRuntimeServiceWorkerScopeV1 = ProxyRuntimeScopeBaseV1 & Readonly<{
+    mode: "service_worker";
+    serviceWorker: Readonly<{
+        scriptUrl: string;
+        scope: string;
+    }>;
+}>;
+export type ProxyRuntimeControllerBridgeScopeV1 = ProxyRuntimeScopeBaseV1 & Readonly<{
+    mode: "controller_bridge";
+    controllerBridge: Readonly<{
+        allowedOrigins: readonly string[];
+    }>;
+}>;
+export type ProxyRuntimeScopeV1 = ProxyRuntimeServiceWorkerScopeV1 | ProxyRuntimeControllerBridgeScopeV1;
+export declare function assertProxyRuntimeScopeV1(payload: ScopePayload): ProxyRuntimeScopeV1;
+export declare function extractProxyRuntimeScopeV1(artifact: ConnectArtifact, mode: ProxyRuntimeScopeV1["mode"]): ProxyRuntimeScopeV1;
+export declare function resolveRuntimeLimitsFromScope(scope: ProxyRuntimeScopeV1, overrides: Readonly<{
+    maxJsonFrameBytes?: number;
+    maxChunkBytes?: number;
+    maxBodyBytes?: number;
+    maxWsFrameBytes?: number;
+    timeoutMs?: number;
+}> | undefined): Readonly<{
+    maxJsonFrameBytes?: number;
+    maxChunkBytes?: number;
+    maxBodyBytes?: number;
+    maxWsFrameBytes?: number;
+    timeoutMs?: number;
+}> | undefined;
+export declare function resolvePresetInputFromScope(scope: ProxyRuntimeScopeV1, presetOverride: ProxyPresetInput | undefined): ProxyPresetInput | undefined;
+export declare function resolveRuntimePresetLimits(scope: ProxyRuntimeScopeV1): ProxyPresetLimits | undefined;
+export {};

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/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/reconnect/index.d.ts

@@ -1,5 +1,5 @@
 import type { Client } from "../client.js";
-import type { ClientObserverLike } from "../observability/observer.js";
+import { type ClientObserverLike } from "../observability/observer.js";
 export type ConnectionStatus = "disconnected" | "connecting" | "connected" | "error";
 export type AutoReconnectConfig = Readonly<{
     enabled?: boolean;

package/dist/reconnect/index.js

@@ -1,3 +1,4 @@
+import { withObserverContext } from "../observability/observer.js";
 function normalizeAutoReconnect(cfg) {
     if (!cfg?.enabled) {
         return {
@@ -59,6 +60,7 @@ export function createReconnectManager() {
     let retryTimer = null;
     let retryResolve = null;
     let attemptAbort = null;
+    let attemptSeq = 0;
     const cancelRetrySleep = () => {
         if (retryTimer) {
             clearTimeout(retryTimer);
@@ -90,6 +92,7 @@ export function createReconnectManager() {
         active = null;
         activeConnectPromise = null;
         token += 1;
+        attemptSeq = 0;
         if (s.client) {
             try {
                 s.client.close();
@@ -138,9 +141,9 @@ export function createReconnectManager() {
             // connectWithRetry updates state; keep errors observable via state().
         });
     };
-    const createObserver = (t, cfg) => {
+    const createObserver = (t, cfg, currentAttemptSeq) => {
         const user = cfg.observer;
-        return {
+        return withObserverContext({
             onConnect: (...args) => user?.onConnect?.(...args),
             onAttach: (...args) => user?.onAttach?.(...args),
             onHandshake: (...args) => user?.onHandshake?.(...args),
@@ -156,12 +159,14 @@ export function createReconnectManager() {
             },
             onRpcCall: (...args) => user?.onRpcCall?.(...args),
             onRpcNotify: (...args) => user?.onRpcNotify?.(...args),
-        };
+        }, {
+            attemptSeq: currentAttemptSeq,
+        });
     };
-    const connectOnce = async (t, cfg) => {
+    const connectOnce = async (t, cfg, currentAttemptSeq) => {
         abortActiveAttempt();
         attemptAbort = new AbortController();
-        return await cfg.connectOnce({ signal: attemptAbort.signal, observer: createObserver(t, cfg) ?? {} });
+        return await cfg.connectOnce({ signal: attemptAbort.signal, observer: createObserver(t, cfg, currentAttemptSeq) ?? {} });
     };
     const connectWithRetry = async (t, cfg) => {
         const ar = normalizeAutoReconnect(cfg.autoReconnect);
@@ -172,8 +177,9 @@ export function createReconnectManager() {
             if (active !== cfg)
                 return;
             attempts += 1;
+            attemptSeq += 1;
             try {
-                const client = await connectOnce(t, cfg);
+                const client = await connectOnce(t, cfg, attemptSeq);
                 if (t !== token) {
                     try {
                         client.close();
@@ -218,6 +224,7 @@ export function createReconnectManager() {
         token += 1;
         const t = token;
         active = cfg;
+        attemptSeq = 0;
         if (s.client) {
             try {
                 s.client.close();

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.17.2",
+  "version": "0.19.0",
   "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",