@floegence/flowersec-core 0.19.10 → 0.20.0

package/README.md

@@ -32,6 +32,7 @@ Node.js:
 ```ts
 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",
@@ -42,13 +43,14 @@ const client = await connectNode(artifact, {
   origin: "https://your-app.example",
 });
 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",
   },
@@ -57,6 +59,9 @@ const reconnectConfig = createNodeReconnectConfig({
 
 Browser `requestConnectArtifact(...)`, `requestEntryConnectArtifact(...)`, and `ControlplaneRequestError` remain available from `@floegence/flowersec-core/browser` as stable aliases.
 
+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
 
 - Frontend quickstart: `docs/FRONTEND_QUICKSTART.md`
@@ -64,4 +69,4 @@ Browser `requestConnectArtifact(...)`, `requestEntryConnectArtifact(...)`, and `
 - 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/index.d.ts

@@ -1,5 +1,7 @@
 export type { ConnectBrowserOptions, DirectConnectBrowserOptions, TunnelConnectBrowserOptions } from "./connect.js";
 export { connectBrowser, connectDirectBrowser, connectTunnelBrowser } from "./connect.js";
+export { AllowPlaintext, AllowPlaintextForLoopback, RequireTLS, } from "../client-connect/transportSecurity.js";
+export type { TransportSecurityPolicy, TransportSecurityPolicyInput, TransportSecurityPolicyPreset, } from "../client-connect/transportSecurity.js";
 export type { ConnectArtifact, CorrelationContext, CorrelationKV, DirectClientConnectArtifact, ScopeMetadataEntry, TunnelClientConnectArtifact, } from "../connect/artifact.js";
 export { assertConnectArtifact } from "../connect/artifact.js";
 export type { ConnectArtifactRequestConfig, ControlplaneConfig, EntryConnectArtifactRequestConfig, EntryControlplaneConfig, } from "./controlplane.js";

package/dist/browser/index.js

@@ -1,4 +1,5 @@
 export { connectBrowser, connectDirectBrowser, connectTunnelBrowser } from "./connect.js";
+export { AllowPlaintext, AllowPlaintextForLoopback, RequireTLS, } from "../client-connect/transportSecurity.js";
 export { assertConnectArtifact } from "../connect/artifact.js";
 export { ControlplaneRequestError, requestChannelGrant, requestConnectArtifact, requestEntryChannelGrant, requestEntryConnectArtifact, } from "./controlplane.js";
 export { createBrowserReconnectConfig, createDirectBrowserReconnectConfig, createTunnelBrowserReconnectConfig, } from "./reconnectConfig.js";

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,7 +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;
@@ -19,18 +25,24 @@ 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. */
     observer?: ClientObserverLike;
+    /** Policy evaluated before any WebSocket network activity. */
+    transportSecurityPolicy?: TransportSecurityPolicy;
     /** Experimental scope validators keyed by scope name. */
     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,15 +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;
@@ -31,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,
@@ -44,9 +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" });
     }
-    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");
@@ -55,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");
@@ -75,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 {
@@ -111,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 {
@@ -167,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 } : {}),
@@ -207,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();
@@ -249,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();
             }
@@ -278,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,
@@ -300,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" });
@@ -327,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 = () => {
@@ -416,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.d.ts

@@ -0,0 +1,19 @@
+import type { ClientPath } from "../client.js";
+import { type ClientObserverLike } from "../observability/observer.js";
+export declare const RequireTLS: "require_tls";
+export declare const AllowPlaintextForLoopback: "allow_plaintext_for_loopback";
+export declare const AllowPlaintext: "allow_plaintext";
+export type TransportSecurityPolicyInput = Readonly<{
+    path: ClientPath;
+    scheme: "ws" | "wss";
+    host: string;
+    runtime: "browser" | "node" | "other";
+}>;
+export type TransportSecurityPolicyPreset = typeof RequireTLS | typeof AllowPlaintextForLoopback | typeof AllowPlaintext;
+export type TransportSecurityPolicy = TransportSecurityPolicyPreset | ((input: TransportSecurityPolicyInput) => boolean | Promise<boolean>);
+export declare function enforceTransportSecurity(args: Readonly<{
+    rawUrl: string;
+    path: ClientPath;
+    policy?: TransportSecurityPolicy;
+    observer?: ClientObserverLike;
+}>): Promise<void>;

package/dist/client-connect/transportSecurity.js

@@ -0,0 +1,114 @@
+import { FlowersecError } from "../utils/errors.js";
+import { emitObserverDiagnostic } from "../observability/observer.js";
+export const RequireTLS = "require_tls";
+export const AllowPlaintextForLoopback = "allow_plaintext_for_loopback";
+export const AllowPlaintext = "allow_plaintext";
+export async function enforceTransportSecurity(args) {
+    let target;
+    try {
+        target = parseWebSocketTarget(args.rawUrl);
+    }
+    catch (cause) {
+        throw denied(args.path, cause);
+    }
+    const input = {
+        path: args.path,
+        scheme: target.scheme,
+        host: target.host,
+        runtime: detectRuntime(),
+    };
+    let allowed = false;
+    const policy = args.policy ?? RequireTLS;
+    try {
+        if (typeof policy === "function") {
+            allowed = await policy(input);
+        }
+        else {
+            allowed = evaluatePreset(policy, target);
+        }
+    }
+    catch (cause) {
+        throw denied(args.path, cause);
+    }
+    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({
+        path,
+        stage: "validate",
+        code: "transport_policy_denied",
+        message: "transport security policy denied websocket URL",
+        ...(cause === undefined ? {} : { cause }),
+    });
+}
+function evaluatePreset(policy, target) {
+    switch (policy) {
+        case RequireTLS:
+            return target.scheme === "wss";
+        case AllowPlaintextForLoopback:
+            return target.scheme === "wss" || isLiteralLoopbackHost(target.host);
+        case AllowPlaintext:
+            return true;
+    }
+}
+function parseWebSocketTarget(rawUrl) {
+    const raw = rawUrl.trim();
+    const match = /^([A-Za-z][A-Za-z0-9+.-]*):\/\/([^/?#]*)(?:[/?#]|$)/.exec(raw);
+    const scheme = match?.[1]?.toLowerCase();
+    const authority = match?.[2] ?? "";
+    if ((scheme !== "ws" && scheme !== "wss") || authority === "" || authority.includes("@")) {
+        throw new Error("invalid websocket URL");
+    }
+    let host;
+    if (authority.startsWith("[")) {
+        const end = authority.indexOf("]");
+        if (end <= 1 || (authority.slice(end + 1) !== "" && !/^:\d+$/.test(authority.slice(end + 1)))) {
+            throw new Error("invalid websocket URL");
+        }
+        host = authority.slice(1, end).toLowerCase();
+    }
+    else {
+        const pieces = authority.split(":");
+        if (pieces.length > 2 || (pieces.length === 2 && !/^\d+$/.test(pieces[1] ?? ""))) {
+            throw new Error("invalid websocket URL");
+        }
+        host = (pieces[0] ?? "").toLowerCase();
+    }
+    if (host === "")
+        throw new Error("invalid websocket URL");
+    return { scheme, host };
+}
+function isLiteralLoopbackHost(host) {
+    if (host === "localhost" || host === "::1")
+        return true;
+    const parts = host.split(".");
+    if (parts.length !== 4)
+        return false;
+    const octets = [];
+    for (const part of parts) {
+        if (!/^(0|[1-9]\d{0,2})$/.test(part))
+            return false;
+        const value = Number(part);
+        if (value > 255)
+            return false;
+        octets.push(value);
+    }
+    return octets[0] === 127;
+}
+function detectRuntime() {
+    if (typeof window !== "undefined" && typeof window.document !== "undefined")
+        return "browser";
+    if (typeof process !== "undefined" && process.versions?.node != null)
+        return "node";
+    return "other";
+}

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<{