@floegence/flowersec-core 0.19.10 → 0.19.11

package/README.md

@@ -30,7 +30,7 @@ client.close();
 Node.js:
 
 ```ts
-import { connectNode, createNodeReconnectConfig } from "@floegence/flowersec-core/node";
+import { connectNode, createNodeReconnectConfig, RequireTLS } from "@floegence/flowersec-core/node";
 import { requestConnectArtifact } from "@floegence/flowersec-core/controlplane";
 
 const artifact = await requestConnectArtifact({
@@ -40,6 +40,7 @@ const artifact = await requestConnectArtifact({
 
 const client = await connectNode(artifact, {
   origin: "https://your-app.example",
+  transportSecurityPolicy: RequireTLS,
 });
 await client.ping();
 client.close();
@@ -51,12 +52,16 @@ const reconnectConfig = createNodeReconnectConfig({
   },
   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
+targets without DNS resolution; `AllowPlaintext` is an explicit acceptance of pre-E2EE metadata exposure.
+
 ## Docs
 
 - Frontend quickstart: `docs/FRONTEND_QUICKSTART.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/client-connect/connectCore.d.ts

@@ -2,6 +2,7 @@ import { type ClientObserverLike } from "../observability/observer.js";
 import { type WebSocketLike } 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 ConnectOptionsBase = Readonly<{
     /** Explicit Origin value (required). In browsers this must match window.location.origin. */
     origin: string;
@@ -25,6 +26,8 @@ export type ConnectOptionsBase = Readonly<{
     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. */

package/dist/client-connect/connectCore.js

@@ -10,6 +10,7 @@ import { WebSocketBinaryTransport, WsCloseError } from "../ws-client/binaryTrans
 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";
 export async function connectCore(args) {
     const observer = normalizeObserver(args.opts.observer, { path: args.path });
     const signal = args.opts.signal;
@@ -44,6 +45,12 @@ 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 });
     };

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,116 @@
+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(),
+    };
+    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;
+    try {
+        if (typeof args.policy === "function") {
+            allowed = await args.policy(input);
+        }
+        else {
+            allowed = evaluatePreset(args.policy, target);
+        }
+    }
+    catch (cause) {
+        throw denied(args.path, cause);
+    }
+    if (!allowed)
+        throw denied(args.path);
+}
+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/facade.d.ts

@@ -14,6 +14,8 @@ export type { ClientObserverLike } from "./observability/observer.js";
 export type { Client, ClientPath } from "./client.js";
 export type { FlowersecErrorCode, FlowersecPath, FlowersecStage } from "./utils/errors.js";
 export { FlowersecError } from "./utils/errors.js";
+export { AllowPlaintext, AllowPlaintextForLoopback, RequireTLS, } from "./client-connect/transportSecurity.js";
+export type { TransportSecurityPolicy, TransportSecurityPolicyInput, TransportSecurityPolicyPreset, } from "./client-connect/transportSecurity.js";
 export type { TunnelConnectOptions } from "./tunnel-client/connect.js";
 export type { DirectConnectOptions } from "./direct-client/connect.js";
 export type ConnectOptions = TunnelConnectOptions | DirectConnectOptions;

package/dist/facade.js

@@ -6,6 +6,7 @@ export { assertChannelInitGrant } from "./gen/flowersec/controlplane/v1.gen.js";
 export { assertDirectConnectInfo } from "./gen/flowersec/direct/v1.gen.js";
 export { assertConnectArtifact } from "./connect/artifact.js";
 export { FlowersecError } from "./utils/errors.js";
+export { AllowPlaintext, AllowPlaintextForLoopback, RequireTLS, } from "./client-connect/transportSecurity.js";
 export async function connectTunnel(grant, opts) {
     return await connectTunnelInternal(grant, opts);
 }

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export * from "./e2ee/secureChannel.js";
 export * from "./e2ee/handshake.js";
 export * from "./e2ee/errors.js";
 export * from "./client.js";
+export * from "./client-connect/transportSecurity.js";
 export * from "./observability/index.js";
 export * from "./ws-client/binaryTransport.js";
 export * from "./yamux/index.js";

package/dist/index.js

@@ -12,6 +12,7 @@ export * from "./e2ee/secureChannel.js";
 export * from "./e2ee/handshake.js";
 export * from "./e2ee/errors.js";
 export * from "./client.js";
+export * from "./client-connect/transportSecurity.js";
 export * from "./observability/index.js";
 export * from "./ws-client/binaryTransport.js";
 export * from "./yamux/index.js";

package/dist/node/index.d.ts

@@ -1,4 +1,6 @@
 export { createNodeWsFactory } from "./wsFactory.js";
+export { AllowPlaintext, AllowPlaintextForLoopback, RequireTLS, } from "../client-connect/transportSecurity.js";
+export type { TransportSecurityPolicy, TransportSecurityPolicyInput, TransportSecurityPolicyPreset, } from "../client-connect/transportSecurity.js";
 export { connectDirectNode, connectNode, connectTunnelNode } from "./connect.js";
 export type { DirectNodeReconnectConfig, NodeReconnectConfig, TunnelNodeReconnectConfig, } from "./reconnectConfig.js";
 export { createDirectNodeReconnectConfig, createNodeReconnectConfig, createTunnelNodeReconnectConfig, } from "./reconnectConfig.js";

package/dist/node/index.js

@@ -1,4 +1,5 @@
 export { createNodeWsFactory } from "./wsFactory.js";
+export { AllowPlaintext, AllowPlaintextForLoopback, RequireTLS, } from "../client-connect/transportSecurity.js";
 export { connectDirectNode, connectNode, connectTunnelNode } from "./connect.js";
 export { createDirectNodeReconnectConfig, createNodeReconnectConfig, createTunnelNodeReconnectConfig, } from "./reconnectConfig.js";
 export { assertConnectArtifact } from "../connect/artifact.js";

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" | "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 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" | "transport_policy_denied" | "credential_commit_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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floegence/flowersec-core",
-  "version": "0.19.10",
+  "version": "0.19.11",
   "description": "Flowersec core TypeScript library (browser-friendly E2EE + multiplexing over WebSocket).",
   "license": "MIT",
   "repository": {