@floegence/flowersec-core 0.19.11 → 0.20.1

package/README.md

@@ -30,8 +30,9 @@ client.close();
 Node.js:
 
 ```ts
-import { connectNode, createNodeReconnectConfig, RequireTLS } from "@floegence/flowersec-core/node";
+import { connectNode, createNodeReconnectConfig } from "@floegence/flowersec-core/node";
 import { requestConnectArtifact } from "@floegence/flowersec-core/controlplane";
+import { createControlplaneArtifactSource } from "@floegence/flowersec-core/reconnect";
 
 const artifact = await requestConnectArtifact({
   baseUrl: "https://your-app.example/api/flowersec",
@@ -40,26 +41,25 @@ const artifact = await requestConnectArtifact({
 
 const client = await connectNode(artifact, {
   origin: "https://your-app.example",
-  transportSecurityPolicy: RequireTLS,
 });
 await client.ping();
+const rttMs = await client.probeLiveness();
 client.close();
 
 const reconnectConfig = createNodeReconnectConfig({
-  artifactControlplane: {
+  source: createControlplaneArtifactSource({
     baseUrl: "https://your-app.example/api/flowersec",
     endpointId: "env_demo",
-  },
+  }),
   connect: {
     origin: "https://your-app.example",
-    transportSecurityPolicy: RequireTLS,
   },
 });
 ```
 
 Browser `requestConnectArtifact(...)`, `requestEntryConnectArtifact(...)`, and `ControlplaneRequestError` remain available from `@floegence/flowersec-core/browser` as stable aliases.
 
-Use `RequireTLS` for remote deployments. `AllowPlaintextForLoopback` permits only literal loopback
+High-level connects use `RequireTLS` by default. `AllowPlaintextForLoopback` permits only literal loopback
 targets without DNS resolution; `AllowPlaintext` is an explicit acceptance of pre-E2EE metadata exposure.
 
 ## Docs
@@ -69,4 +69,4 @@ targets without DNS resolution; `AllowPlaintext` is an explicit acceptance of pr
 - API surface contract: `docs/API_SURFACE.md`
 - Controlplane artifact fetch: `docs/CONTROLPLANE_ARTIFACT_FETCH.md`
 - Error model: `docs/ERROR_MODEL.md`
-- Migration guide: `docs/V0_19_MIGRATION.md`
+- Migration guide: `docs/V0_20_MIGRATION.md`

package/dist/browser/reconnectConfig.d.ts

@@ -1,43 +1,15 @@
-import type { ConnectArtifact } from "../connect/artifact.js";
-import type { ChannelInitGrant } from "../gen/flowersec/controlplane/v1.gen.js";
-import type { DirectConnectInfo } from "../gen/flowersec/direct/v1.gen.js";
 import type { ClientObserverLike } from "../observability/observer.js";
 import type { AutoReconnectConfig, ConnectConfig as ReconnectConnectConfig } from "../reconnect/index.js";
-import { type ArtifactAwareReconnectConfig, type ArtifactFactoryArgs } from "../reconnect/artifactControlplane.js";
-import type { RequestConnectArtifactInput, RequestEntryConnectArtifactInput } from "../controlplane/index.js";
+import { type ArtifactSource } from "../reconnect/artifactControlplane.js";
 import type { DirectConnectBrowserOptions, TunnelConnectBrowserOptions } from "./connect.js";
-import { type ControlplaneConfig } from "./controlplane.js";
-type SharedReconnectOptions = Readonly<{
+export type BrowserReconnectConfig = Readonly<{
+    source: ArtifactSource;
+    connect?: Omit<TunnelConnectBrowserOptions, "observer" | "signal"> | Omit<DirectConnectBrowserOptions, "observer" | "signal">;
     observer?: ClientObserverLike;
     autoReconnect?: AutoReconnectConfig;
 }>;
-type TunnelReconnectConnectOptions = Omit<TunnelConnectBrowserOptions, "observer" | "signal">;
-type DirectReconnectConnectOptions = Omit<DirectConnectBrowserOptions, "observer" | "signal">;
-type ArtifactAwareTunnelReconnectConfig = ArtifactAwareReconnectConfig & Readonly<{
-    artifact?: ConnectArtifact;
-    getArtifact?: (args: ArtifactFactoryArgs) => Promise<ConnectArtifact>;
-    artifactControlplane?: RequestConnectArtifactInput | RequestEntryConnectArtifactInput;
-}>;
-type ArtifactAwareDirectReconnectConfig = ArtifactAwareReconnectConfig & Readonly<{
-    artifact?: ConnectArtifact;
-    getArtifact?: (args: ArtifactFactoryArgs) => Promise<ConnectArtifact>;
-    artifactControlplane?: RequestConnectArtifactInput | RequestEntryConnectArtifactInput;
-}>;
-export type TunnelBrowserReconnectConfig = SharedReconnectOptions & ArtifactAwareTunnelReconnectConfig & Readonly<{
-    mode?: "tunnel";
-    connect?: TunnelReconnectConnectOptions;
-    grant?: ChannelInitGrant;
-    getGrant?: () => Promise<ChannelInitGrant>;
-    controlplane?: ControlplaneConfig;
-}>;
-export type DirectBrowserReconnectConfig = SharedReconnectOptions & ArtifactAwareDirectReconnectConfig & Readonly<{
-    mode: "direct";
-    connect?: DirectReconnectConnectOptions;
-    directInfo?: DirectConnectInfo;
-    getDirectInfo?: () => Promise<DirectConnectInfo>;
-}>;
-export type BrowserReconnectConfig = TunnelBrowserReconnectConfig | DirectBrowserReconnectConfig;
-export declare function createTunnelBrowserReconnectConfig(config: TunnelBrowserReconnectConfig): ReconnectConnectConfig;
-export declare function createDirectBrowserReconnectConfig(config: DirectBrowserReconnectConfig): ReconnectConnectConfig;
+export type TunnelBrowserReconnectConfig = BrowserReconnectConfig;
+export type DirectBrowserReconnectConfig = BrowserReconnectConfig;
 export declare function createBrowserReconnectConfig(config: BrowserReconnectConfig): ReconnectConnectConfig;
-export {};
+export declare const createTunnelBrowserReconnectConfig: typeof createBrowserReconnectConfig;
+export declare const createDirectBrowserReconnectConfig: typeof createBrowserReconnectConfig;

package/dist/browser/reconnectConfig.js

@@ -1,77 +1,20 @@
-import { resolveConnectArtifact, updateTraceId, } from "../reconnect/artifactControlplane.js";
-import { connectBrowser, connectDirectBrowser, connectTunnelBrowser } from "./connect.js";
-import { requestChannelGrant, } from "./controlplane.js";
-async function resolveTunnelGrant(config) {
-    if (config.getGrant)
-        return await config.getGrant();
-    if (config.grant)
-        return config.grant;
-    if (config.controlplane)
-        return await requestChannelGrant(config.controlplane);
-    throw new Error("Tunnel reconnect config requires `getGrant`, `grant`, or `controlplane`");
-}
-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 createTunnelBrowserReconnectConfig(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);
-                return await connectBrowser(artifact, {
-                    ...(config.connect ?? {}),
-                    signal,
-                    observer,
-                });
-            }
-            return await connectTunnelBrowser(await resolveTunnelGrant(config), {
-                ...(config.connect ?? {}),
-                signal,
-                observer,
-            });
-        },
-    };
-}
-export function createDirectBrowserReconnectConfig(config) {
-    let traceId = config.artifact?.correlation?.trace_id;
+import { createArtifactResolver, updateTraceId } from "../reconnect/artifactControlplane.js";
+import { connectBrowser } from "./connect.js";
+export function createBrowserReconnectConfig(config) {
+    if (config.source.kind === "once" && config.autoReconnect?.enabled) {
+        throw new Error("automatic reconnect requires a refreshable artifact source");
+    }
+    let traceId = config.source.kind === "once" ? config.source.artifact.correlation?.trace_id : undefined;
+    const acquire = createArtifactResolver(config.source);
     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);
-                return await connectBrowser(artifact, {
-                    ...(config.connect ?? {}),
-                    signal,
-                    observer,
-                });
-            }
-            return await connectDirectBrowser(await resolveDirectInfo(config), {
-                ...(config.connect ?? {}),
-                signal,
-                observer,
-            });
+            const artifact = await acquire({ ...(traceId === undefined ? {} : { traceId }), signal });
+            traceId = updateTraceId(traceId, artifact);
+            return await connectBrowser(artifact, { ...(config.connect ?? {}), signal, observer });
         },
     };
 }
-export function createBrowserReconnectConfig(config) {
-    if (config.mode === "direct") {
-        return createDirectBrowserReconnectConfig(config);
-    }
-    return createTunnelBrowserReconnectConfig(config);
-}
+export const createTunnelBrowserReconnectConfig = createBrowserReconnectConfig;
+export const createDirectBrowserReconnectConfig = createBrowserReconnectConfig;

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

@@ -1,8 +1,13 @@
+import { type YamuxLimits } from "../yamux/session.js";
 import { type ClientObserverLike } from "../observability/observer.js";
-import { type WebSocketLike } from "../ws-client/binaryTransport.js";
+import { type WebSocketLike, type WebSocketLimits } from "../ws-client/binaryTransport.js";
 import type { ClientInternal } from "../client.js";
 import type { ConnectScopeResolverMap } from "../connect/internalNormalize.js";
 import { type TransportSecurityPolicy } from "./transportSecurity.js";
+export type LivenessOptions = Readonly<{
+    intervalMs?: number;
+    timeoutMs?: number;
+}>;
 export type ConnectOptionsBase = Readonly<{
     /** Explicit Origin value (required). In browsers this must match window.location.origin. */
     origin: string;
@@ -20,8 +25,12 @@ export type ConnectOptionsBase = Readonly<{
     maxRecordBytes?: number;
     /** Maximum buffered plaintext bytes in the secure channel (0 uses default). */
     maxBufferedBytes?: number;
-    /** Maximum queued websocket bytes before backpressure (0 uses default). */
-    maxWsQueuedBytes?: number;
+    /** Preferred plaintext bytes per outbound encrypted record (default 64 KiB). */
+    outboundRecordChunkBytes?: number;
+    /** WebSocket inbound and outbound queue limits. */
+    webSocketLimits?: Partial<WebSocketLimits>;
+    /** Yamux stream, frame, and receive-memory limits. */
+    yamuxLimits?: Partial<YamuxLimits>;
     /** Optional factory for creating the WebSocket instance. */
     wsFactory?: (url: string, origin: string) => WebSocketLike;
     /** Optional observer for client metrics. */
@@ -32,8 +41,8 @@ export type ConnectOptionsBase = Readonly<{
     scopeResolvers?: ConnectScopeResolverMap;
     /** Experimental migration switch for optional scope failures. */
     relaxedOptionalScopeValidation?: boolean;
-    /** Encrypted keepalive ping interval in milliseconds (0 disables). */
-    keepaliveIntervalMs?: number;
+    /** Acknowledged Yamux liveness checks, or false to disable automatic checks. */
+    liveness?: false | LivenessOptions;
 }>;
 export type ConnectCoreArgs = Readonly<{
     path: "tunnel" | "direct";

package/dist/client-connect/connectCore.js

@@ -1,16 +1,19 @@
 import { clientHandshake } from "../e2ee/handshake.js";
 import { ByteReader } from "../yamux/byteReader.js";
 import { YamuxSession } from "../yamux/session.js";
+import { DEFAULT_YAMUX_LIMITS } from "../yamux/session.js";
 import { RpcClient } from "../rpc/client.js";
 import { writeStreamHello } from "../streamhello/streamHello.js";
-import { normalizeObserver, nowSeconds } from "../observability/observer.js";
+import { emitObserverDiagnostic, normalizeObserver, nowSeconds } from "../observability/observer.js";
 import { base64urlDecode } from "../utils/base64url.js";
 import { AbortError, FlowersecError, throwIfAborted } from "../utils/errors.js";
-import { WebSocketBinaryTransport, WsCloseError } from "../ws-client/binaryTransport.js";
+import { DEFAULT_WEB_SOCKET_LIMITS, WebSocketBinaryTransport, WsCloseError } from "../ws-client/binaryTransport.js";
 import { OriginMismatchError, WsFactoryRequiredError, classifyConnectError, classifyHandshakeError, createWebSocket, waitOpen, withAbortAndTimeout, } from "./common.js";
 import { prepareChannelId } from "./contract.js";
 import { isTunnelAttachCloseReason } from "./tunnelAttachCloseReason.js";
 import { enforceTransportSecurity } from "./transportSecurity.js";
+import { maxPlaintextBytes } from "../e2ee/record.js";
+import { isYamuxResourceExhaustedError } from "../yamux/errors.js";
 export async function connectCore(args) {
     const observer = normalizeObserver(args.opts.observer, { path: args.path });
     const signal = args.opts.signal;
@@ -32,6 +35,9 @@ export async function connectCore(args) {
     if (origin === "") {
         throw new FlowersecError({ path: args.path, stage: "validate", code: "missing_origin", message: "missing origin" });
     }
+    const invalidOption = (message) => {
+        throw new FlowersecError({ path: args.path, stage: "validate", code: "invalid_option", message });
+    };
     if (args.path === "tunnel" && args.attach == null) {
         throw new FlowersecError({
             path: args.path,
@@ -45,15 +51,6 @@ export async function connectCore(args) {
         const code = args.path === "tunnel" ? "missing_tunnel_url" : "missing_ws_url";
         throw new FlowersecError({ path: args.path, stage: "validate", code, message: "missing websocket url" });
     }
-    await enforceTransportSecurity({
-        rawUrl: wsUrl,
-        path: args.path,
-        ...(args.opts.transportSecurityPolicy === undefined ? {} : { policy: args.opts.transportSecurityPolicy }),
-        ...(args.opts.observer === undefined ? {} : { observer: args.opts.observer }),
-    });
-    const invalidOption = (message) => {
-        throw new FlowersecError({ path: args.path, stage: "validate", code: "invalid_option", message });
-    };
     const connectTimeoutMs = args.opts.connectTimeoutMs ?? 10_000;
     if (!Number.isFinite(connectTimeoutMs) || connectTimeoutMs < 0) {
         invalidOption("connectTimeoutMs must be a non-negative number");
@@ -62,10 +59,6 @@ export async function connectCore(args) {
     if (!Number.isFinite(handshakeTimeoutMs) || handshakeTimeoutMs < 0) {
         invalidOption("handshakeTimeoutMs must be a non-negative number");
     }
-    const keepaliveIntervalMs = args.opts.keepaliveIntervalMs ?? 0;
-    if (!Number.isFinite(keepaliveIntervalMs) || keepaliveIntervalMs < 0) {
-        invalidOption("keepaliveIntervalMs must be a non-negative number");
-    }
     const clientFeatures = args.opts.clientFeatures ?? 0;
     if (!Number.isSafeInteger(clientFeatures) || clientFeatures < 0 || clientFeatures > 0xffffffff) {
         invalidOption("clientFeatures must be a uint32");
@@ -82,10 +75,22 @@ export async function connectCore(args) {
     if (!Number.isSafeInteger(maxBufferedBytes) || maxBufferedBytes < 0) {
         invalidOption("maxBufferedBytes must be a non-negative integer");
     }
-    const maxWsQueuedBytes = args.opts.maxWsQueuedBytes ?? 0;
-    if (!Number.isSafeInteger(maxWsQueuedBytes) || maxWsQueuedBytes < 0) {
-        invalidOption("maxWsQueuedBytes must be a non-negative integer");
+    const effectiveMaxRecordBytes = maxRecordBytes > 0 ? maxRecordBytes : (1 << 20);
+    const outboundRecordChunkBytes = args.opts.outboundRecordChunkBytes ?? 64 * 1024;
+    if (!Number.isSafeInteger(outboundRecordChunkBytes) || outboundRecordChunkBytes <= 0 || outboundRecordChunkBytes > maxPlaintextBytes(effectiveMaxRecordBytes)) {
+        invalidOption("outboundRecordChunkBytes must be a positive integer within maxRecordBytes");
     }
+    validateLimitObject(args.opts.webSocketLimits, "webSocketLimits", invalidOption);
+    validateLimitObject(args.opts.yamuxLimits, "yamuxLimits", invalidOption);
+    validateWebSocketLimitRelationships(args.opts.webSocketLimits, invalidOption);
+    validateYamuxLimitRelationships(args.opts.yamuxLimits, invalidOption);
+    const liveness = normalizeLiveness(args.opts.liveness, invalidOption);
+    await enforceTransportSecurity({
+        rawUrl: wsUrl,
+        path: args.path,
+        ...(args.opts.transportSecurityPolicy === undefined ? {} : { policy: args.opts.transportSecurityPolicy }),
+        ...(args.opts.observer === undefined ? {} : { observer: args.opts.observer }),
+    });
     const channelId = prepareChannelId(args.channelId, args.path);
     let psk;
     try {
@@ -118,7 +123,7 @@ export async function connectCore(args) {
     // Install close/error/message listeners before waiting for "open" to avoid a gap where a peer close
     // (for example a tunnel attach rejection with a reason token) can be missed and misclassified as a handshake timeout.
     const transport = new WebSocketBinaryTransport(ws, {
-        ...(maxWsQueuedBytes > 0 ? { maxQueuedBytes: maxWsQueuedBytes } : {}),
+        ...(args.opts.webSocketLimits === undefined ? {} : { webSocketLimits: args.opts.webSocketLimits }),
         observer,
     });
     try {
@@ -174,7 +179,8 @@ export async function connectCore(args) {
                 psk,
                 clientFeatures,
                 maxHandshakePayload: maxHandshakePayload > 0 ? maxHandshakePayload : 8 * 1024,
-                maxRecordBytes: maxRecordBytes > 0 ? maxRecordBytes : (1 << 20),
+                maxRecordBytes: effectiveMaxRecordBytes,
+                outboundRecordChunkBytes,
                 ...(maxBufferedBytes > 0 ? { maxBufferedBytes } : {}),
                 timeoutMs: handshakeTimeoutMs,
                 ...(signal !== undefined ? { signal } : {}),
@@ -214,7 +220,20 @@ export async function connectCore(args) {
             write: (b) => secure.write(b),
             close: () => secure.close(),
         };
-        const mux = new YamuxSession(conn, { client: true });
+        const mux = new YamuxSession(conn, {
+            client: true,
+            ...(args.opts.yamuxLimits === undefined ? {} : { limits: args.opts.yamuxLimits }),
+            onDiagnostic: (event) => emitObserverDiagnostic(args.opts.observer, {
+                path: args.path,
+                stage: "yamux",
+                code_domain: "event",
+                code: event.code,
+                result: "fail",
+                resource: event.resource,
+                current: event.current,
+                limit: event.limit,
+            }),
+        });
         let rpcStream;
         try {
             rpcStream = await mux.openStream();
@@ -256,16 +275,39 @@ export async function connectCore(args) {
                 throw new FlowersecError({ path: args.path, stage: "secure", code: "ping_failed", message: "ping failed", cause: e });
             }
         };
-        let keepaliveTimer;
-        let keepaliveInFlight = false;
-        const stopKeepalive = () => {
-            if (keepaliveTimer === undefined)
+        const probeLiveness = async () => {
+            try {
+                return await mux.probeLiveness(liveness.timeoutMs);
+            }
+            catch (e) {
+                if (String(e?.message).includes("ping timeout")) {
+                    emitObserverDiagnostic(args.opts.observer, { path: args.path, stage: "yamux", code_domain: "event", code: "liveness_timeout", result: "fail" });
+                }
+                try {
+                    rpc.close();
+                }
+                catch { /* ignore */ }
+                try {
+                    mux.close();
+                }
+                catch { /* ignore */ }
+                try {
+                    secure.close();
+                }
+                catch { /* ignore */ }
+                throw new FlowersecError({ path: args.path, stage: "yamux", code: "ping_failed", message: "liveness probe failed", cause: e });
+            }
+        };
+        let livenessTimer;
+        let livenessInFlight = false;
+        const stopLiveness = () => {
+            if (livenessTimer === undefined)
                 return;
-            clearInterval(keepaliveTimer);
-            keepaliveTimer = undefined;
+            clearInterval(livenessTimer);
+            livenessTimer = undefined;
         };
         const closeAll = () => {
-            stopKeepalive();
+            stopLiveness();
             try {
                 rpc.close();
             }
@@ -285,20 +327,20 @@ export async function connectCore(args) {
                 // ignore
             }
         };
-        if (keepaliveIntervalMs > 0) {
-            keepaliveTimer = setInterval(() => {
-                if (keepaliveInFlight)
+        if (liveness.intervalMs > 0) {
+            livenessTimer = setInterval(() => {
+                if (livenessInFlight)
                     return;
-                keepaliveInFlight = true;
-                ping()
+                livenessInFlight = true;
+                probeLiveness()
                     .catch(() => {
-                    closeAll();
+                    stopLiveness();
                 })
                     .finally(() => {
-                    keepaliveInFlight = false;
+                    livenessInFlight = false;
                 });
-            }, keepaliveIntervalMs);
-            keepaliveTimer?.unref?.();
+            }, liveness.intervalMs);
+            livenessTimer?.unref?.();
         }
         return {
             path: args.path,
@@ -307,6 +349,7 @@ export async function connectCore(args) {
             mux,
             rpc,
             ping,
+            probeLiveness,
             openStream: async (kind, opts = {}) => {
                 if (kind == null || kind === "")
                     throw new FlowersecError({ path: args.path, stage: "validate", code: "missing_stream_kind", message: "missing stream kind" });
@@ -334,7 +377,8 @@ export async function connectCore(args) {
                     s = await mux.openStream();
                 }
                 catch (e) {
-                    throw new FlowersecError({ path: args.path, stage: "yamux", code: "open_stream_failed", message: "open stream failed", cause: e });
+                    const exhausted = isYamuxResourceExhaustedError(e);
+                    throw new FlowersecError({ path: args.path, stage: "yamux", code: exhausted ? "resource_exhausted" : "open_stream_failed", message: exhausted ? "yamux stream limit reached" : "open stream failed", cause: e });
                 }
                 if (signal != null) {
                     abortListener = () => {
@@ -423,3 +467,51 @@ export async function connectCore(args) {
         throw e;
     }
 }
+function validateLimitObject(input, name, invalid) {
+    if (input === undefined)
+        return;
+    for (const [key, value] of Object.entries(input)) {
+        if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0))
+            invalid(`${name}.${key} must be a positive integer`);
+    }
+}
+function normalizeLiveness(input, invalid) {
+    if (input === false || input === undefined)
+        return { intervalMs: 0, timeoutMs: 10_000 };
+    const intervalMs = input.intervalMs ?? 0;
+    const timeoutMs = input.timeoutMs ?? (intervalMs > 0 ? Math.min(10_000, intervalMs) : 10_000);
+    if (!Number.isFinite(intervalMs) || intervalMs < 0)
+        invalid("liveness.intervalMs must be a non-negative number");
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        invalid("liveness.timeoutMs must be a positive number");
+    return { intervalMs, timeoutMs };
+}
+function validateWebSocketLimitRelationships(input, invalid) {
+    if (input === undefined)
+        return;
+    const low = input.outboundLowWatermarkBytes ?? DEFAULT_WEB_SOCKET_LIMITS.outboundLowWatermarkBytes;
+    const high = input.outboundHighWatermarkBytes ?? DEFAULT_WEB_SOCKET_LIMITS.outboundHighWatermarkBytes;
+    const hard = input.outboundHardLimitBytes ?? DEFAULT_WEB_SOCKET_LIMITS.outboundHardLimitBytes;
+    if (low > high || high > hard)
+        invalid("webSocketLimits outbound watermarks must satisfy low <= high <= hard");
+}
+function validateYamuxLimitRelationships(input, invalid) {
+    if (input === undefined)
+        return;
+    const active = input.maxActiveStreams ?? DEFAULT_YAMUX_LIMITS.maxActiveStreams;
+    const inbound = input.maxInboundStreams ?? DEFAULT_YAMUX_LIMITS.maxInboundStreams;
+    const frame = input.maxFrameBytes ?? DEFAULT_YAMUX_LIMITS.maxFrameBytes;
+    const outbound = input.preferredOutboundFrameBytes ?? Math.min(DEFAULT_YAMUX_LIMITS.preferredOutboundFrameBytes, frame);
+    const streamReceive = input.maxStreamReceiveBytes ?? DEFAULT_YAMUX_LIMITS.maxStreamReceiveBytes;
+    const sessionReceive = input.maxSessionReceiveBytes ?? DEFAULT_YAMUX_LIMITS.maxSessionReceiveBytes;
+    if (inbound > active)
+        invalid("yamuxLimits.maxInboundStreams must not exceed maxActiveStreams");
+    if (outbound > frame)
+        invalid("yamuxLimits.preferredOutboundFrameBytes must not exceed maxFrameBytes");
+    if (frame > streamReceive)
+        invalid("yamuxLimits.maxFrameBytes must not exceed maxStreamReceiveBytes");
+    if (streamReceive < DEFAULT_YAMUX_LIMITS.maxStreamReceiveBytes)
+        invalid("yamuxLimits.maxStreamReceiveBytes must cover the 256 KiB initial stream window");
+    if (streamReceive > sessionReceive)
+        invalid("yamuxLimits.maxStreamReceiveBytes must not exceed maxSessionReceiveBytes");
+}

package/dist/client-connect/transportSecurity.js

@@ -17,25 +17,14 @@ export async function enforceTransportSecurity(args) {
         host: target.host,
         runtime: detectRuntime(),
     };
-    if (args.policy === undefined) {
-        if (target.scheme === "ws") {
-            emitObserverDiagnostic(args.observer, {
-                path: args.path,
-                stage: "validate",
-                code_domain: "event",
-                code: "plaintext_transport",
-                result: "skip",
-            });
-        }
-        return;
-    }
     let allowed = false;
+    const policy = args.policy ?? RequireTLS;
     try {
-        if (typeof args.policy === "function") {
-            allowed = await args.policy(input);
+        if (typeof policy === "function") {
+            allowed = await policy(input);
         }
         else {
-            allowed = evaluatePreset(args.policy, target);
+            allowed = evaluatePreset(policy, target);
         }
     }
     catch (cause) {
@@ -43,6 +32,15 @@ export async function enforceTransportSecurity(args) {
     }
     if (!allowed)
         throw denied(args.path);
+    if (target.scheme === "ws") {
+        emitObserverDiagnostic(args.observer, {
+            path: args.path,
+            stage: "transport",
+            code_domain: "event",
+            code: "plaintext_transport",
+            result: "skip",
+        });
+    }
 }
 function denied(path, cause) {
     return new FlowersecError({

package/dist/client.d.ts

@@ -11,6 +11,8 @@ export type Client = Readonly<{
         signal?: AbortSignal;
     }>) => Promise<YamuxStream>;
     ping: () => Promise<void>;
+    /** Performs an acknowledged Yamux round trip and returns RTT in milliseconds. */
+    probeLiveness: () => Promise<number>;
     close: () => void;
 }>;
 export type ClientInternal = Client & Readonly<{

package/dist/e2ee/handshake.d.ts

@@ -14,6 +14,8 @@ export type HandshakeClientOptions = Readonly<{
     maxHandshakePayload: number;
     /** Maximum record size for encrypted frames after handshake. */
     maxRecordBytes: number;
+    /** Preferred plaintext bytes per outbound record. */
+    outboundRecordChunkBytes?: number;
     /** Maximum buffered plaintext bytes for the secure channel. */
     maxBufferedBytes?: number;
     /** Optional AbortSignal to cancel the handshake. */
@@ -38,6 +40,8 @@ export type HandshakeServerOptions = Readonly<{
     maxHandshakePayload: number;
     /** Maximum record size for encrypted frames after handshake. */
     maxRecordBytes: number;
+    /** Preferred plaintext bytes per outbound record. */
+    outboundRecordChunkBytes?: number;
     /** Maximum buffered plaintext bytes for the secure channel. */
     maxBufferedBytes?: number;
     /** Optional AbortSignal to cancel the handshake. */

package/dist/e2ee/handshake.js

@@ -159,6 +159,7 @@ export async function clientHandshake(transport, opts) {
     return new SecureChannel({
         transport,
         maxRecordBytes: opts.maxRecordBytes,
+        ...(opts.outboundRecordChunkBytes !== undefined ? { outboundRecordChunkBytes: opts.outboundRecordChunkBytes } : {}),
         ...(opts.maxBufferedBytes !== undefined ? { maxBufferedBytes: opts.maxBufferedBytes } : {}),
         sendKey: keys.c2sKey,
         recvKey: keys.s2cKey,
@@ -316,6 +317,7 @@ export async function serverHandshake(transport, cache, opts) {
     return new SecureChannel({
         transport,
         maxRecordBytes: opts.maxRecordBytes,
+        ...(opts.outboundRecordChunkBytes !== undefined ? { outboundRecordChunkBytes: opts.outboundRecordChunkBytes } : {}),
         ...(opts.maxBufferedBytes !== undefined ? { maxBufferedBytes: opts.maxBufferedBytes } : {}),
         sendKey: keys.s2cKey,
         recvKey: keys.c2sKey,

package/dist/e2ee/secureChannel.d.ts

@@ -19,6 +19,8 @@ export type BinaryTransport = {
 export type SecureChannelOptions = Readonly<{
     /** Maximum encoded record size (header + ciphertext). */
     maxRecordBytes: number;
+    /** Preferred plaintext bytes per outbound record. */
+    outboundRecordChunkBytes?: number;
     /** Maximum queued plaintext bytes before backpressure/errors. */
     maxBufferedBytes?: number;
 }>;
@@ -26,6 +28,7 @@ type Direction = 1 | 2;
 export declare class SecureChannel {
     private readonly transport;
     private readonly maxRecordBytes;
+    private readonly outboundRecordChunkBytes;
     private readonly maxBufferedBytes;
     private sendKey;
     private recvKey;
@@ -52,6 +55,7 @@ export declare class SecureChannel {
     constructor(args: {
         transport: BinaryTransport;
         maxRecordBytes: number;
+        outboundRecordChunkBytes?: number;
         maxBufferedBytes?: number;
         sendKey: Uint8Array;
         recvKey: Uint8Array;