@floegence/flowersec-core 0.22.0 → 0.22.1

package/README.md

@@ -60,7 +60,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.
+targets without DNS resolution. Deliberate non-loopback `ws://` connections must use
+`createNetworkPlaintextPolicy(...)` with exact canonical IP literals and
+`PlaintextRiskAcceptance.acceptPreE2ECredentialExposure`. The unrestricted `AllowPlaintext` preset is deprecated.
 
 ## Node endpoint and controlplane
 

package/dist/browser/index.d.ts

@@ -1,7 +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 { AllowPlaintext, AllowPlaintextForLoopback, createNetworkPlaintextPolicy, PlaintextRiskAcceptance, RequireTLS, } from "../client-connect/transportSecurity.js";
+export type { TransportSecurityPolicy, TransportSecurityPolicyInput, TransportSecurityPolicyPreset, NetworkPlaintextPolicyOptions, } 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,5 +1,5 @@
 export { connectBrowser, connectDirectBrowser, connectTunnelBrowser } from "./connect.js";
-export { AllowPlaintext, AllowPlaintextForLoopback, RequireTLS, } from "../client-connect/transportSecurity.js";
+export { AllowPlaintext, AllowPlaintextForLoopback, createNetworkPlaintextPolicy, PlaintextRiskAcceptance, 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/transportSecurity.d.ts

@@ -2,7 +2,16 @@ 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";
+/** @deprecated Use RequireTLS, AllowPlaintextForLoopback, or createNetworkPlaintextPolicy. */
 export declare const AllowPlaintext: "allow_plaintext";
+export declare const PlaintextRiskAcceptance: {
+    readonly acceptPreE2ECredentialExposure: "accept_pre_e2ee_credential_exposure";
+};
+export type PlaintextRiskAcceptance = typeof PlaintextRiskAcceptance[keyof typeof PlaintextRiskAcceptance];
+export type NetworkPlaintextPolicyOptions = Readonly<{
+    allowedHosts: readonly string[];
+    riskAcceptance: PlaintextRiskAcceptance;
+}>;
 export type TransportSecurityPolicyInput = Readonly<{
     path: ClientPath;
     scheme: "ws" | "wss";
@@ -11,6 +20,7 @@ export type TransportSecurityPolicyInput = Readonly<{
 }>;
 export type TransportSecurityPolicyPreset = typeof RequireTLS | typeof AllowPlaintextForLoopback | typeof AllowPlaintext;
 export type TransportSecurityPolicy = TransportSecurityPolicyPreset | ((input: TransportSecurityPolicyInput) => boolean | Promise<boolean>);
+export declare function createNetworkPlaintextPolicy(options: NetworkPlaintextPolicyOptions): TransportSecurityPolicy;
 export declare function enforceTransportSecurity(args: Readonly<{
     rawUrl: string;
     path: ClientPath;

package/dist/client-connect/transportSecurity.js

@@ -2,7 +2,21 @@ import { FlowersecError } from "../utils/errors.js";
 import { emitObserverDiagnostic } from "../observability/observer.js";
 export const RequireTLS = "require_tls";
 export const AllowPlaintextForLoopback = "allow_plaintext_for_loopback";
+/** @deprecated Use RequireTLS, AllowPlaintextForLoopback, or createNetworkPlaintextPolicy. */
 export const AllowPlaintext = "allow_plaintext";
+export const PlaintextRiskAcceptance = {
+    acceptPreE2ECredentialExposure: "accept_pre_e2ee_credential_exposure",
+};
+export function createNetworkPlaintextPolicy(options) {
+    if (options?.riskAcceptance !== PlaintextRiskAcceptance.acceptPreE2ECredentialExposure) {
+        throw new Error("network plaintext policy requires explicit pre-E2EE credential exposure acceptance");
+    }
+    if (!Array.isArray(options.allowedHosts) || options.allowedHosts.length === 0) {
+        throw new Error("network plaintext policy requires at least one allowed host");
+    }
+    const allowedHosts = new Set(options.allowedHosts.map(canonicalNetworkPlaintextHost));
+    return (input) => input.scheme === "wss" || (input.scheme === "ws" && allowedHosts.has(input.host));
+}
 export async function enforceTransportSecurity(args) {
     let target;
     try {
@@ -105,6 +119,81 @@ function isLiteralLoopbackHost(host) {
     }
     return octets[0] === 127;
 }
+function canonicalNetworkPlaintextHost(rawHost) {
+    const host = String(rawHost ?? "").trim();
+    if (host === "" || host !== host.toLowerCase() || /[@/?#%\[\]]/.test(host)) {
+        throw new Error(`invalid network plaintext allowed host ${JSON.stringify(rawHost)}`);
+    }
+    if (host.includes(":")) {
+        return canonicalNetworkIPv6Host(host);
+    }
+    const octets = canonicalIPv4Octets(host);
+    const firstOctet = octets[0];
+    const secondOctet = octets[1];
+    if (firstOctet == null || secondOctet == null) {
+        throw new Error(`network plaintext allowed host must be a canonical IP literal: ${JSON.stringify(rawHost)}`);
+    }
+    if (firstOctet === 127 || (firstOctet === 169 && secondOctet === 254) || firstOctet >= 224 || octets.every((value) => value === 0)) {
+        throw new Error(`network plaintext allowed host must be a non-loopback unicast IP literal: ${JSON.stringify(rawHost)}`);
+    }
+    return host;
+}
+function canonicalIPv4Octets(host) {
+    const parts = host.split(".");
+    if (parts.length !== 4) {
+        throw new Error(`network plaintext allowed host must be a canonical IP literal: ${JSON.stringify(host)}`);
+    }
+    const octets = parts.map((part) => {
+        if (!/^(0|[1-9]\d{0,2})$/.test(part)) {
+            throw new Error(`network plaintext allowed host must be a canonical IP literal: ${JSON.stringify(host)}`);
+        }
+        const value = Number(part);
+        if (value > 255) {
+            throw new Error(`network plaintext allowed host must be a canonical IP literal: ${JSON.stringify(host)}`);
+        }
+        return value;
+    });
+    return octets;
+}
+function canonicalNetworkIPv6Host(host) {
+    let parsed;
+    try {
+        parsed = new URL(`http://[${host}]/`);
+    }
+    catch {
+        throw new Error(`network plaintext allowed host must be a canonical IP literal: ${JSON.stringify(host)}`);
+    }
+    const canonical = parsed.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    if (canonical !== host) {
+        throw new Error(`network plaintext allowed host must be a canonical IP literal: ${JSON.stringify(host)}`);
+    }
+    const words = expandIPv6Words(canonical);
+    const unspecified = words.every((word) => word === 0);
+    const loopback = words.slice(0, 7).every((word) => word === 0) && words[7] === 1;
+    const mappedIPv4 = words.slice(0, 5).every((word) => word === 0) && words[5] === 0xffff;
+    const multicast = (words[0] & 0xff00) === 0xff00;
+    const linkLocal = (words[0] & 0xffc0) === 0xfe80;
+    if (unspecified || loopback || mappedIPv4 || multicast || linkLocal) {
+        throw new Error(`network plaintext allowed host must be a non-loopback unicast IP literal: ${JSON.stringify(host)}`);
+    }
+    return canonical;
+}
+function expandIPv6Words(host) {
+    const halves = host.split("::");
+    if (halves.length > 2)
+        throw new Error("invalid IPv6 host");
+    const left = halves[0] === "" ? [] : halves[0].split(":");
+    const right = halves.length === 1 || halves[1] === "" ? [] : halves[1].split(":");
+    const missing = 8 - left.length - right.length;
+    if ((halves.length === 1 && missing !== 0) || (halves.length === 2 && missing < 1)) {
+        throw new Error("invalid IPv6 host");
+    }
+    const words = [...left, ...Array.from({ length: missing }, () => "0"), ...right].map((part) => Number.parseInt(part, 16));
+    if (words.length !== 8 || words.some((word) => !Number.isInteger(word) || word < 0 || word > 0xffff)) {
+        throw new Error("invalid IPv6 host");
+    }
+    return words;
+}
 function detectRuntime() {
     if (typeof window !== "undefined" && typeof window.document !== "undefined")
         return "browser";

package/dist/facade.d.ts

@@ -17,8 +17,8 @@ export type { WebSocketLimits } from "./ws-client/binaryTransport.js";
 export type { YamuxLimits } from "./yamux/session.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 { AllowPlaintext, AllowPlaintextForLoopback, createNetworkPlaintextPolicy, PlaintextRiskAcceptance, RequireTLS, } from "./client-connect/transportSecurity.js";
+export type { NetworkPlaintextPolicyOptions, 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,7 +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 { AllowPlaintext, AllowPlaintextForLoopback, createNetworkPlaintextPolicy, PlaintextRiskAcceptance, RequireTLS, } from "./client-connect/transportSecurity.js";
 export async function connectTunnel(grant, opts) {
     return await connectTunnelInternal(grant, opts);
 }

package/dist/node/index.d.ts

@@ -1,6 +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 { AllowPlaintext, AllowPlaintextForLoopback, createNetworkPlaintextPolicy, PlaintextRiskAcceptance, RequireTLS, } from "../client-connect/transportSecurity.js";
+export type { TransportSecurityPolicy, TransportSecurityPolicyInput, TransportSecurityPolicyPreset, NetworkPlaintextPolicyOptions, } 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,5 +1,5 @@
 export { createNodeWsFactory } from "./wsFactory.js";
-export { AllowPlaintext, AllowPlaintextForLoopback, RequireTLS, } from "../client-connect/transportSecurity.js";
+export { AllowPlaintext, AllowPlaintextForLoopback, createNetworkPlaintextPolicy, PlaintextRiskAcceptance, RequireTLS, } from "../client-connect/transportSecurity.js";
 export { connectDirectNode, connectNode, connectTunnelNode } from "./connect.js";
 export { createDirectNodeReconnectConfig, createNodeReconnectConfig, createTunnelNodeReconnectConfig, } from "./reconnectConfig.js";
 export * from "../endpoint/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floegence/flowersec-core",
-  "version": "0.22.0",
+  "version": "0.22.1",
   "description": "Flowersec core TypeScript library (browser-friendly E2EE + multiplexing over WebSocket).",
   "license": "MIT",
   "repository": {
@@ -120,8 +120,8 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "bench": "vitest bench --run",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage",
+    "test": "npm run build && vitest run",
+    "test:coverage": "npm run build && vitest run --coverage",
     "lint": "eslint .",
     "verify:package": "node ./scripts/verify-package-exports.mjs",
     "prepack": "npm run build",