@floegence/flowersec-core 0.18.0 → 0.19.0

package/dist/node/reconnectConfig.js

@@ -0,0 +1,78 @@
+import { resolveConnectArtifact, updateTraceId, } from "../reconnect/artifactControlplane.js";
+import { connectDirectNode, connectNode, connectTunnelNode } from "./connect.js";
+async function resolveTunnelGrant(config) {
+    if (config.getGrant)
+        return await config.getGrant();
+    if (config.grant)
+        return config.grant;
+    throw new Error("Tunnel reconnect config requires `getGrant` or `grant`");
+}
+async function resolveDirectInfo(config) {
+    if (config.getDirectInfo)
+        return await config.getDirectInfo();
+    if (config.directInfo)
+        return config.directInfo;
+    throw new Error("Direct reconnect config requires `getDirectInfo` or `directInfo`");
+}
+export function createTunnelNodeReconnectConfig(config) {
+    let traceId = config.artifact?.correlation?.trace_id;
+    return {
+        ...(config.observer === undefined ? {} : { observer: config.observer }),
+        ...(config.autoReconnect === undefined ? {} : { autoReconnect: config.autoReconnect }),
+        connectOnce: async ({ signal, observer }) => {
+            if (config.getArtifact || config.artifact || config.artifactControlplane) {
+                const artifact = await resolveConnectArtifact(config, traceId, signal);
+                if (artifact.transport !== "tunnel") {
+                    throw new Error("Tunnel reconnect config requires a tunnel ConnectArtifact");
+                }
+                traceId = updateTraceId(traceId, artifact);
+                const connectOptions = {
+                    ...(config.connect === undefined ? {} : config.connect),
+                    signal,
+                    observer,
+                };
+                return await connectNode(artifact, connectOptions);
+            }
+            const connectOptions = {
+                ...(config.connect === undefined ? {} : config.connect),
+                signal,
+                observer,
+            };
+            return await connectTunnelNode(await resolveTunnelGrant(config), connectOptions);
+        },
+    };
+}
+export function createDirectNodeReconnectConfig(config) {
+    let traceId = config.artifact?.correlation?.trace_id;
+    return {
+        ...(config.observer === undefined ? {} : { observer: config.observer }),
+        ...(config.autoReconnect === undefined ? {} : { autoReconnect: config.autoReconnect }),
+        connectOnce: async ({ signal, observer }) => {
+            if (config.getArtifact || config.artifact || config.artifactControlplane) {
+                const artifact = await resolveConnectArtifact(config, traceId, signal);
+                if (artifact.transport !== "direct") {
+                    throw new Error("Direct reconnect config requires a direct ConnectArtifact");
+                }
+                traceId = updateTraceId(traceId, artifact);
+                const connectOptions = {
+                    ...(config.connect === undefined ? {} : config.connect),
+                    signal,
+                    observer,
+                };
+                return await connectNode(artifact, connectOptions);
+            }
+            const connectOptions = {
+                ...(config.connect === undefined ? {} : config.connect),
+                signal,
+                observer,
+            };
+            return await connectDirectNode(await resolveDirectInfo(config), connectOptions);
+        },
+    };
+}
+export function createNodeReconnectConfig(config) {
+    if (config.mode === "direct") {
+        return createDirectNodeReconnectConfig(config);
+    }
+    return createTunnelNodeReconnectConfig(config);
+}

package/dist/observability/observer.d.ts

@@ -2,7 +2,7 @@ import type { ClientPath } from "../client.js";
 export type ConnectResult = "ok" | "fail";
 export type ConnectReason = "websocket_error" | "websocket_closed" | "timeout" | "canceled";
 export type AttachResult = "ok" | "fail";
-export type AttachReason = "send_failed" | "too_many_connections" | "expected_attach" | "invalid_attach" | "invalid_token" | "channel_mismatch" | "role_mismatch" | "init_exp_mismatch" | "idle_timeout_mismatch" | "token_replay" | "replace_rate_limited" | "attach_failed" | "timeout" | "canceled";
+export type AttachReason = "send_failed" | "too_many_connections" | "expected_attach" | "invalid_attach" | "invalid_token" | "channel_mismatch" | "role_mismatch" | "init_exp_mismatch" | "idle_timeout_mismatch" | "token_replay" | "tenant_mismatch" | "policy_denied" | "policy_error" | "replace_rate_limited" | "attach_failed" | "timeout" | "canceled";
 export type HandshakeResult = "ok" | "fail";
 export type HandshakeReason = "auth_tag_mismatch" | "handshake_failed" | "invalid_suite" | "invalid_version" | "timestamp_after_init_exp" | "timestamp_out_of_skew" | "timeout" | "canceled";
 export type WsCloseKind = "local" | "peer_or_error";

package/dist/observability/observer.js

@@ -51,12 +51,20 @@ function buildDiagnosticEvent(context, event) {
         elapsed_ms: Math.max(0, Math.floor(nowMilliseconds() - (context.attemptStartMs ?? nowMilliseconds()))),
         attempt_seq: Math.max(1, Math.floor(context.attemptSeq ?? 1)),
         ...(context.traceId === undefined ? {} : { trace_id: context.traceId }),
-        ...(context.sessionId === undefined ? {} : { session_id: context.sessionId }),
+        ...(context.sessionId === undefined
+            ? {}
+            : { session_id: context.sessionId }),
     });
 }
 function mapConnectDiagnostic(path, result, reason) {
     if (result === "ok") {
-        return { path, stage: "connect", code_domain: "event", code: "connect_ok", result: "ok" };
+        return {
+            path,
+            stage: "connect",
+            code_domain: "event",
+            code: "connect_ok",
+            result: "ok",
+        };
     }
     return {
         path,
@@ -68,7 +76,13 @@ function mapConnectDiagnostic(path, result, reason) {
 }
 function mapAttachDiagnostic(result, reason, path) {
     if (result === "ok") {
-        return { path, stage: "attach", code_domain: "event", code: "attach_ok", result: "ok" };
+        return {
+            path,
+            stage: "attach",
+            code_domain: "event",
+            code: "attach_ok",
+            result: "ok",
+        };
     }
     return {
         path,
@@ -80,7 +94,13 @@ function mapAttachDiagnostic(result, reason, path) {
 }
 function mapHandshakeDiagnostic(path, result, reason) {
     if (result === "ok") {
-        return { path, stage: "handshake", code_domain: "event", code: "handshake_ok", result: "ok" };
+        return {
+            path,
+            stage: "handshake",
+            code_domain: "event",
+            code: "handshake_ok",
+            result: "ok",
+        };
     }
     return {
         path,
@@ -153,14 +173,20 @@ class ObserverDispatcher {
     emitDiagnosticEvent(event) {
         const diagnostic = buildDiagnosticEvent(this[OBSERVER_CONTEXT], event);
         this.enqueue({
-            kind: event.code === "diagnostics_overflow" ? "overflow" : event.result === "fail" ? "terminal" : "normal",
+            kind: event.code === "diagnostics_overflow"
+                ? "overflow"
+                : event.result === "fail"
+                    ? "terminal"
+                    : "normal",
             deliver: () => this.observer.onDiagnosticEvent?.(diagnostic),
         });
     }
     enqueueCombined(callback, diagnostic, terminal) {
         if (callback == null && diagnostic == null)
             return;
-        const event = diagnostic == null ? undefined : buildDiagnosticEvent(this[OBSERVER_CONTEXT], diagnostic);
+        const event = diagnostic == null
+            ? undefined
+            : buildDiagnosticEvent(this[OBSERVER_CONTEXT], diagnostic);
         this.enqueue({
             kind: terminal ? "terminal" : "normal",
             deliver: () => {
@@ -277,7 +303,8 @@ export function nowSeconds() {
     return nowMilliseconds() / 1000;
 }
 function nowMilliseconds() {
-    if (typeof performance !== "undefined" && typeof performance.now === "function") {
+    if (typeof performance !== "undefined" &&
+        typeof performance.now === "function") {
         return performance.now();
     }
     return Date.now();

package/dist/proxy/bootstrap.d.ts

@@ -1,5 +1,6 @@
 import type { Client } from "../client.js";
-import type { TunnelConnectBrowserOptions } from "../browser/connect.js";
+import type { ConnectArtifact } from "../connect/artifact.js";
+import type { ConnectBrowserOptions, TunnelConnectBrowserOptions } from "../browser/connect.js";
 import type { ChannelInitGrant } from "../gen/flowersec/controlplane/v1.gen.js";
 import { type ProxyIntegrationPlugin, type RegisterProxyIntegrationOptions, type ProxyIntegrationServiceWorkerOptions } from "./integration.js";
 import { type RegisterProxyControllerWindowOptions } from "./controllerWindow.js";
@@ -18,6 +19,14 @@ export type ConnectTunnelProxyBrowserHandle = Readonly<{
     runtime: ProxyRuntime;
     dispose: () => Promise<void>;
 }>;
+export type ConnectArtifactProxyBrowserOptions = Readonly<{
+    connect?: ConnectBrowserOptions;
+    preset?: ProxyPresetInput;
+    runtimeGlobalKey?: string;
+    runtime?: RegisterProxyIntegrationOptions["runtime"];
+    serviceWorker?: ProxyIntegrationServiceWorkerOptions;
+    plugins?: readonly ProxyIntegrationPlugin[];
+}>;
 export type ConnectTunnelProxyControllerBrowserOptions = Readonly<{
     connect?: TunnelConnectBrowserOptions;
     runtime?: RegisterProxyIntegrationOptions["runtime"];
@@ -30,5 +39,14 @@ export type ConnectTunnelProxyControllerBrowserHandle = Readonly<{
     runtime: ProxyRuntime;
     dispose: () => void;
 }>;
+export type ConnectArtifactProxyControllerBrowserOptions = Readonly<{
+    connect?: ConnectBrowserOptions;
+    runtime?: RegisterProxyIntegrationOptions["runtime"];
+    allowedOrigins?: RegisterProxyControllerWindowOptions["allowedOrigins"];
+    targetWindow?: RegisterProxyControllerWindowOptions["targetWindow"];
+    expectedSource?: RegisterProxyControllerWindowOptions["expectedSource"];
+}>;
 export declare function connectTunnelProxyBrowser(grant: ChannelInitGrant, opts: ConnectTunnelProxyBrowserOptions): Promise<ConnectTunnelProxyBrowserHandle>;
+export declare function connectArtifactProxyBrowser(artifact: ConnectArtifact, opts?: ConnectArtifactProxyBrowserOptions): Promise<ConnectTunnelProxyBrowserHandle>;
 export declare function connectTunnelProxyControllerBrowser(grant: ChannelInitGrant, opts: ConnectTunnelProxyControllerBrowserOptions): Promise<ConnectTunnelProxyControllerBrowserHandle>;
+export declare function connectArtifactProxyControllerBrowser(artifact: ConnectArtifact, opts?: ConnectArtifactProxyControllerBrowserOptions): Promise<ConnectTunnelProxyControllerBrowserHandle>;

package/dist/proxy/bootstrap.js

@@ -1,9 +1,28 @@
-import { connectTunnelBrowser } from "../browser/connect.js";
+import { connectBrowser, connectTunnelBrowser } from "../browser/connect.js";
 import { registerProxyIntegration, } from "./integration.js";
 import { registerProxyControllerWindow } from "./controllerWindow.js";
+import { extractProxyRuntimeScopeV1, resolvePresetInputFromScope, resolveRuntimeLimitsFromScope, resolveRuntimePresetLimits, } from "./runtimeScope.js";
 import { createProxyRuntime } from "./runtime.js";
-export async function connectTunnelProxyBrowser(grant, opts) {
-    const client = await connectTunnelBrowser(grant, opts.connect ?? {});
+function scopeRuntimeToIntegrationOptions(scope, opts) {
+    const runtimeLimits = resolveRuntimeLimitsFromScope(scope, opts.runtime);
+    const presetFromScope = resolvePresetInputFromScope(scope, opts.preset);
+    const presetFromLimits = presetFromScope ?? resolveRuntimePresetLimits(scope);
+    const serviceWorker = opts.serviceWorker ?? (scope.mode === "service_worker" ? {
+        scriptUrl: scope.serviceWorker.scriptUrl,
+        scope: scope.serviceWorker.scope,
+    } : undefined);
+    if (!serviceWorker) {
+        throw new Error("service worker config is required for proxy runtime mode");
+    }
+    return {
+        ...(presetFromLimits === undefined ? {} : { preset: presetFromLimits }),
+        ...(opts.runtimeGlobalKey === undefined ? {} : { runtimeGlobalKey: opts.runtimeGlobalKey }),
+        ...(runtimeLimits === undefined ? {} : { runtime: runtimeLimits }),
+        serviceWorker,
+        ...(opts.plugins === undefined ? {} : { plugins: opts.plugins }),
+    };
+}
+async function connectProxyBrowserClient(client, opts) {
     const compat = opts;
     const integrationInput = {
         client,
@@ -48,8 +67,7 @@ export async function connectTunnelProxyBrowser(grant, opts) {
         },
     };
 }
-export async function connectTunnelProxyControllerBrowser(grant, opts) {
-    const client = await connectTunnelBrowser(grant, opts.connect ?? {});
+function connectProxyControllerClient(client, opts) {
     let runtime = null;
     let controller = null;
     try {
@@ -82,3 +100,28 @@ export async function connectTunnelProxyControllerBrowser(grant, opts) {
         },
     };
 }
+export async function connectTunnelProxyBrowser(grant, opts) {
+    const client = await connectTunnelBrowser(grant, opts.connect ?? {});
+    return await connectProxyBrowserClient(client, opts);
+}
+export async function connectArtifactProxyBrowser(artifact, opts = {}) {
+    const scope = extractProxyRuntimeScopeV1(artifact, "service_worker");
+    const client = await connectBrowser(artifact, opts.connect ?? {});
+    const nextOpts = scopeRuntimeToIntegrationOptions(scope, opts);
+    return await connectProxyBrowserClient(client, nextOpts);
+}
+export async function connectTunnelProxyControllerBrowser(grant, opts) {
+    const client = await connectTunnelBrowser(grant, opts.connect ?? {});
+    return connectProxyControllerClient(client, opts);
+}
+export async function connectArtifactProxyControllerBrowser(artifact, opts = {}) {
+    const scope = extractProxyRuntimeScopeV1(artifact, "controller_bridge");
+    const client = await connectBrowser(artifact, opts.connect ?? {});
+    const runtime = resolveRuntimeLimitsFromScope(scope, opts.runtime);
+    return connectProxyControllerClient(client, {
+        ...(runtime === undefined ? {} : { runtime }),
+        allowedOrigins: opts.allowedOrigins ?? scope.controllerBridge.allowedOrigins,
+        ...(opts.targetWindow === undefined ? {} : { targetWindow: opts.targetWindow }),
+        ...(opts.expectedSource === undefined ? {} : { expectedSource: opts.expectedSource }),
+    });
+}

package/dist/proxy/index.d.ts

@@ -9,6 +9,7 @@ export { registerServiceWorkerAndEnsureControl } from "./registerServiceWorker.j
 export * from "./integration.js";
 export * from "./controllerGuard.js";
 export * from "./bootstrap.js";
+export * from "./runtimeScope.js";
 export * from "./controllerWindow.js";
 export * from "./appWindow.js";
 export * from "./wsPatch.js";

package/dist/proxy/index.js

@@ -8,6 +8,7 @@ export { registerServiceWorkerAndEnsureControl } from "./registerServiceWorker.j
 export * from "./integration.js";
 export * from "./controllerGuard.js";
 export * from "./bootstrap.js";
+export * from "./runtimeScope.js";
 export * from "./controllerWindow.js";
 export * from "./appWindow.js";
 export * from "./wsPatch.js";

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/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;