@floegence/flowersec-core 0.23.0 → 0.25.0

package/README.md

@@ -1,8 +1,6 @@
 # @floegence/flowersec-core
 
-Flowersec core TypeScript library for the complete portable Flowersec client/server contract in Node.js, plus the browser and Service Worker runtime owned by TypeScript.
-
-Status: experimental; not audited.
+The TypeScript SDK for Flowersec end-to-end encrypted direct and tunneled sessions. It implements the portable Node.js client and endpoint contract plus the browser and Service Worker runtime owned by TypeScript.
 
 ## Install
 
@@ -10,73 +8,33 @@ Status: experimental; not audited.
 npm install @floegence/flowersec-core
 ```
 
-## Recommended usage
-
-Browser:
-
-```ts
-import { connectBrowser } from "@floegence/flowersec-core/browser";
-import { requestConnectArtifact } from "@floegence/flowersec-core/controlplane";
+The package is ESM-only and exposes environment-specific entrypoints for browser and Node.js applications.
 
-const artifact = await requestConnectArtifact({
-  endpointId: "env_demo",
-});
-
-const client = await connectBrowser(artifact);
-await client.ping();
-client.close();
-```
+## Cookbook
 
-Node.js:
+Start with the [TypeScript cookbook](https://github.com/floegence/flowersec/tree/main/examples/ts). It contains runnable browser direct/tunnel pages, Node.js clients, the shared demo server, the Service Worker proxy runtime, and manual protocol-stack references.
 
-```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",
-  endpointId: "env_demo",
-});
-
-const client = await connectNode(artifact, {
-  origin: "https://your-app.example",
-});
-await client.ping();
-const rttMs = await client.probeLiveness();
-client.close();
-
-const reconnectConfig = createNodeReconnectConfig({
-  source: createControlplaneArtifactSource({
-    baseUrl: "https://your-app.example/api/flowersec",
-    endpointId: "env_demo",
-  }),
-  connect: {
-    origin: "https://your-app.example",
-  },
-});
-```
+## Entrypoints
 
-Browser `requestConnectArtifact(...)`, `requestEntryConnectArtifact(...)`, and `ControlplaneRequestError` remain available from `@floegence/flowersec-core/browser` as stable aliases.
+- Browser client: `@floegence/flowersec-core/browser`
+- Node.js client and endpoint transport: `@floegence/flowersec-core/node`
+- Controlplane artifact helpers: `@floegence/flowersec-core/controlplane`
+- Endpoint session serving: `@floegence/flowersec-core/endpoint`
+- RPC: `@floegence/flowersec-core/rpc`
+- Reconnect: `@floegence/flowersec-core/reconnect`
+- HTTP/WebSocket proxy and browser runtime: `@floegence/flowersec-core/proxy`
+- Observability: `@floegence/flowersec-core/observability`
 
-High-level connects use `RequireTLS` by default. `AllowPlaintextForLoopback` permits only literal loopback
-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.
+High-level WebSocket connections require TLS by default. Use `AllowPlaintextForLoopback` only for literal local development targets.
 
-## Node endpoint and controlplane
+## Node Proxy Server
 
-`@floegence/flowersec-core/node` exports the high-level endpoint APIs for accepted direct WebSockets and server-role tunnel grants. `@floegence/flowersec-core/endpoint` provides portable session and RPC serving, while `@floegence/flowersec-core/controlplane` provides bounded artifact envelopes, FST2 tokens, issuer rotation, and channel initialization.
+The Node entrypoint exports `serveProxySession(...)`, `serveProxyStream(...)`, and `ProxyServerOptions`. Request bodies remain bounded per request by `maxBodyBytes`; `maxBufferedRequestBodyBytes` additionally caps the total buffered request-body bytes owned by one proxy session. WebSocket frames remain bounded by `maxWsFrameBytes`; `maxWsQueuedBytes` additionally caps upstream-to-Yamux queued bytes per connection, while the reverse direction waits for each Node `ws` send callback.
 
-## Proxy
+The defaults keep one session request-body budget equal to `maxBodyBytes` and one queued WebSocket frame plus its proxy header. Raise either limit only when the deployment has a matching memory budget.
 
-`@floegence/flowersec-core/proxy` contains both portable HTTP/1 and WebSocket proxy protocols and the TypeScript-owned browser runtime. Node endpoint servers use `serveProxySession(...)`; browser applications use the Service Worker or controller bridge helpers without changing the portable stream contract.
+## Runtime Boundaries
 
-## Docs
+TypeScript owns browser and Service Worker integration. Shared tunnel, proxy gateway, and helper binaries remain Go-owned.
 
-- Frontend quickstart: `docs/FRONTEND_QUICKSTART.md`
-- Integration guide: `docs/INTEGRATION_GUIDE.md`
-- 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_20_MIGRATION.md`
+Review the shared [API contract](../docs/API_CONTRACT.md), [protocol](../docs/PROTOCOL.md), [threat model](../docs/THREAT_MODEL.md), and [error model](../docs/ERROR_MODEL.md).

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

@@ -23,7 +23,7 @@ export type ConnectOptionsBase = Readonly<{
     maxHandshakePayload?: number;
     /** Maximum encrypted record size on the wire (0 uses default). */
     maxRecordBytes?: number;
-    /** Maximum buffered plaintext bytes in the secure channel (0 uses default). */
+    /** Maximum queued inbound plaintext bytes in the secure channel (0 uses default). */
     maxBufferedBytes?: number;
     /** Maximum queued outbound plaintext bytes in the secure channel (default 4 MiB; 0 uses default). */
     maxOutboundBufferedBytes?: number;
@@ -39,9 +39,9 @@ export type ConnectOptionsBase = Readonly<{
     observer?: ClientObserverLike;
     /** Policy evaluated before any WebSocket network activity. */
     transportSecurityPolicy?: TransportSecurityPolicy;
-    /** Experimental scope validators keyed by scope name. */
+    /** Scope validators keyed by scope name. */
     scopeResolvers?: ConnectScopeResolverMap;
-    /** Experimental migration switch for optional scope failures. */
+    /** Explicit compatibility switch for optional scope failures. */
     relaxedOptionalScopeValidation?: boolean;
     /** Acknowledged Yamux liveness checks, or false to disable automatic checks. */
     liveness?: false | LivenessOptions;

package/dist/client-connect/connectCore.js

@@ -303,10 +303,11 @@ export async function connectCore(args) {
                 return await mux.probeLiveness(liveness.timeoutMs);
             }
             catch (e) {
-                if (isYamuxPingTimeoutError(e)) {
+                const timedOut = isYamuxPingTimeoutError(e);
+                if (timedOut) {
                     emitObserverDiagnostic(args.opts.observer, { path: args.path, stage: "yamux", code_domain: "event", code: "liveness_timeout", result: "fail" });
                 }
-                const error = new FlowersecError({ path: args.path, stage: "yamux", code: "ping_failed", message: "liveness probe failed", cause: e });
+                const error = new FlowersecError({ path: args.path, stage: "yamux", code: timedOut ? "timeout" : "ping_failed", message: "liveness probe failed", cause: e });
                 reportTermination(error);
                 throw error;
             }
@@ -355,8 +356,9 @@ export async function connectCore(args) {
             },
             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" });
+                const streamKind = kind?.trim() ?? "";
+                if (streamKind === "")
+                    throw new FlowersecError({ path: args.path, stage: "rpc", code: "missing_stream_kind", message: "missing stream kind" });
                 if (opts.signal?.aborted) {
                     throw new FlowersecError({
                         path: args.path,
@@ -415,7 +417,7 @@ export async function connectCore(args) {
                     });
                 }
                 try {
-                    await writeStreamHello((b) => s.write(b), kind);
+                    await writeStreamHello((b) => s.write(b), streamKind);
                 }
                 catch (err) {
                     if (signal?.aborted) {

package/dist/client-connect/transportSecurity.js

@@ -35,7 +35,7 @@ export async function enforceTransportSecurity(args) {
     const policy = args.policy ?? RequireTLS;
     try {
         if (typeof policy === "function") {
-            allowed = await policy(input);
+            allowed = await policy(input) === true;
         }
         else {
             allowed = evaluatePreset(policy, target);

package/dist/controlplane/issuer.d.ts

@@ -1,7 +1,7 @@
 import { type TokenPayload } from "./token.js";
 export declare class IssuerKeyset {
-    private kid;
-    private signingSeed;
+    private active;
+    private readonly verificationKeys;
     constructor(kid: string, signingSeed: Uint8Array);
     static random(kid: string): IssuerKeyset;
     currentKID(): string;
@@ -9,7 +9,10 @@ export declare class IssuerKeyset {
     sign(payload: Omit<TokenPayload, "kid"> & Readonly<{
         kid?: string;
     }>): string;
+    addVerificationKey(kid: string, publicKey: Uint8Array): void;
     rotate(kid: string, signingSeed: Uint8Array): void;
+    retireVerificationKey(kid: string): void;
     exportTunnelKeyset(): Uint8Array;
     dispose(): void;
+    private requireActive;
 }

package/dist/controlplane/issuer.js

@@ -2,13 +2,13 @@ import { ed25519 } from "@noble/curves/ed25519";
 import { base64urlEncode } from "../utils/base64url.js";
 import { signToken } from "./token.js";
 export class IssuerKeyset {
-    kid;
-    signingSeed;
+    active;
+    verificationKeys = new Map();
     constructor(kid, signingSeed) {
-        this.kid = normalizeKid(kid);
-        if (signingSeed.length !== 32)
-            throw new TypeError("Ed25519 signing seed must be 32 bytes");
-        this.signingSeed = signingSeed.slice();
+        const normalizedKID = normalizeKid(kid);
+        const retainedSeed = copySigningSeed(signingSeed);
+        this.active = { kid: normalizedKID, signingSeed: retainedSeed };
+        this.verificationKeys.set(normalizedKID, ed25519.getPublicKey(retainedSeed));
     }
     static random(kid) {
         const seed = crypto.getRandomValues(new Uint8Array(32));
@@ -20,30 +20,90 @@ export class IssuerKeyset {
         }
     }
     currentKID() {
-        return this.kid;
+        return this.requireActive().kid;
     }
     publicKeys() {
-        return new Map([[this.kid, ed25519.getPublicKey(this.signingSeed)]]);
+        this.requireActive();
+        return new Map([...this.verificationKeys.entries()]
+            .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+            .map(([kid, publicKey]) => [kid, publicKey.slice()]));
     }
     sign(payload) {
-        return signToken(this.signingSeed, { ...payload, kid: this.kid });
+        const active = this.requireActive();
+        return signToken(active.signingSeed, { ...payload, kid: active.kid });
+    }
+    addVerificationKey(kid, publicKey) {
+        this.requireActive();
+        const normalizedKID = normalizeKid(kid);
+        const retainedKey = copyPublicKey(publicKey);
+        const existing = this.verificationKeys.get(normalizedKID);
+        if (existing != null) {
+            if (!equalBytes(existing, retainedKey))
+                throw new Error(`key ID ${normalizedKID} is already bound to a different public key`);
+            return;
+        }
+        this.verificationKeys.set(normalizedKID, retainedKey);
     }
     rotate(kid, signingSeed) {
+        const active = this.requireActive();
         const nextKID = normalizeKid(kid);
-        if (signingSeed.length !== 32)
-            throw new TypeError("Ed25519 signing seed must be 32 bytes");
-        const nextSeed = signingSeed.slice();
-        this.signingSeed.fill(0);
-        this.kid = nextKID;
-        this.signingSeed = nextSeed;
+        const nextSeed = copySigningSeed(signingSeed);
+        const nextPublicKey = ed25519.getPublicKey(nextSeed);
+        const prepublishedKey = this.verificationKeys.get(nextKID);
+        if (prepublishedKey == null) {
+            nextSeed.fill(0);
+            throw new Error(`key ID ${nextKID} must be prepublished before rotation`);
+        }
+        if (!equalBytes(prepublishedKey, nextPublicKey)) {
+            nextSeed.fill(0);
+            throw new Error(`key ID ${nextKID} is bound to a different public key`);
+        }
+        this.active = { kid: nextKID, signingSeed: nextSeed };
+        active.signingSeed.fill(0);
+    }
+    retireVerificationKey(kid) {
+        const active = this.requireActive();
+        const normalizedKID = normalizeKid(kid);
+        if (normalizedKID === active.kid)
+            throw new Error("the active signing key cannot be retired");
+        if (!this.verificationKeys.delete(normalizedKID))
+            throw new Error(`key ID ${normalizedKID} is not published`);
     }
     exportTunnelKeyset() {
         const keys = [...this.publicKeys()].map(([kid, publicKey]) => ({ kid, pubkey_b64u: base64urlEncode(publicKey) }));
         return new TextEncoder().encode(JSON.stringify({ keys }, null, 2));
     }
     dispose() {
-        this.signingSeed.fill(0);
+        const active = this.active;
+        if (active == null)
+            return;
+        active.signingSeed.fill(0);
+        this.active = undefined;
+        this.verificationKeys.clear();
     }
+    requireActive() {
+        if (this.active == null)
+            throw new Error("issuer keyset is disposed");
+        return this.active;
+    }
+}
+function copySigningSeed(signingSeed) {
+    if (signingSeed.length !== 32)
+        throw new TypeError("Ed25519 signing seed must be 32 bytes");
+    return signingSeed.slice();
+}
+function copyPublicKey(publicKey) {
+    if (publicKey.length !== 32)
+        throw new TypeError("Ed25519 public key must be 32 bytes");
+    return publicKey.slice();
+}
+function equalBytes(left, right) {
+    if (left.length !== right.length)
+        return false;
+    let diff = 0;
+    for (let index = 0; index < left.length; index++)
+        diff |= left[index] ^ right[index];
+    return diff === 0;
 }
 function normalizeKid(kid) {
     const value = kid.trim();

package/dist/defaults.d.ts

@@ -8,6 +8,7 @@ export declare const SDK_DEFAULTS: Readonly<{
         maxHandshakePayloadBytes: number;
         maxRecordBytes: number;
         outboundRecordChunkBytes: number;
+        maxInboundBufferedBytes: number;
         maxOutboundBufferedBytes: number;
     }>;
     yamux: Readonly<{
@@ -15,6 +16,7 @@ export declare const SDK_DEFAULTS: Readonly<{
         maxInboundStreams: 32;
         maxFrameBytes: number;
         preferredOutboundFrameBytes: number;
+        maxStreamWriteQueueBytes: number;
         maxStreamReceiveBytes: number;
         maxSessionReceiveBytes: number;
     }>;

package/dist/defaults.js

@@ -8,6 +8,7 @@ export const SDK_DEFAULTS = Object.freeze({
         maxHandshakePayloadBytes: 8 * 1024,
         maxRecordBytes: 1024 * 1024,
         outboundRecordChunkBytes: 64 * 1024,
+        maxInboundBufferedBytes: 4 * 1024 * 1024,
         maxOutboundBufferedBytes: 4 * 1024 * 1024,
     }),
     yamux: Object.freeze({
@@ -15,6 +16,7 @@ export const SDK_DEFAULTS = Object.freeze({
         maxInboundStreams: 32,
         maxFrameBytes: 256 * 1024,
         preferredOutboundFrameBytes: 64 * 1024,
+        maxStreamWriteQueueBytes: 4 * 1024 * 1024,
         maxStreamReceiveBytes: 256 * 1024,
         maxSessionReceiveBytes: 16 * 1024 * 1024,
     }),

package/dist/e2ee/handshake.d.ts

@@ -16,7 +16,7 @@ export type HandshakeClientOptions = Readonly<{
     maxRecordBytes: number;
     /** Preferred plaintext bytes per outbound record. */
     outboundRecordChunkBytes?: number;
-    /** Maximum buffered plaintext bytes for the secure channel. */
+    /** Maximum queued inbound plaintext bytes for the secure channel. */
     maxBufferedBytes?: number;
     /** Maximum queued outbound plaintext bytes for the secure channel. */
     maxOutboundBufferedBytes?: number;
@@ -44,7 +44,7 @@ export type HandshakeServerOptions = Readonly<{
     maxRecordBytes: number;
     /** Preferred plaintext bytes per outbound record. */
     outboundRecordChunkBytes?: number;
-    /** Maximum buffered plaintext bytes for the secure channel. */
+    /** Maximum queued inbound plaintext bytes for the secure channel. */
     maxBufferedBytes?: number;
     /** Maximum queued outbound plaintext bytes for the secure channel. */
     maxOutboundBufferedBytes?: number;

package/dist/e2ee/secureChannel.d.ts

@@ -31,7 +31,7 @@ export declare class SecureChannel {
     private readonly transport;
     private readonly maxRecordBytes;
     private readonly outboundRecordChunkBytes;
-    private readonly maxBufferedBytes;
+    private readonly maxInboundBufferedBytes;
     private readonly maxOutboundBufferedBytes;
     private sendKey;
     private recvKey;
@@ -50,7 +50,7 @@ export declare class SecureChannel {
     private sendQueueBytes;
     private sendClosed;
     private sendErr;
-    private readonly recvQueue;
+    private recvQueue;
     private recvQueueHead;
     private recvQueueBytes;
     private recvWaiters;

package/dist/e2ee/secureChannel.js

@@ -1,6 +1,7 @@
 import { RECORD_FLAG_APP, RECORD_FLAG_PING, RECORD_FLAG_REKEY } from "./constants.js";
 import { decryptRecord, encryptRecord, maxPlaintextBytes } from "./record.js";
 import { deriveRekeyKey } from "./kdf.js";
+import { SDK_DEFAULTS } from "../defaults.js";
 const maxRecordSeq = (1n << 64n) - 1n;
 class RecordSeqExhaustedError extends Error {
     constructor() {
@@ -15,8 +16,7 @@ export class SecureChannel {
     // Maximum allowed bytes per record frame.
     maxRecordBytes;
     outboundRecordChunkBytes;
-    // Upper bound for buffered plaintext in memory.
-    maxBufferedBytes;
+    maxInboundBufferedBytes;
     maxOutboundBufferedBytes;
     // Active encryption keys and nonce prefixes for the current epoch.
     sendKey;
@@ -52,16 +52,16 @@ export class SecureChannel {
         this.transport = args.transport;
         this.maxRecordBytes = args.maxRecordBytes;
         const maxPlain = Math.max(1, maxPlaintextBytes(this.maxRecordBytes));
-        this.outboundRecordChunkBytes = args.outboundRecordChunkBytes ?? Math.min(64 * 1024, maxPlain);
+        this.outboundRecordChunkBytes = args.outboundRecordChunkBytes ?? Math.min(SDK_DEFAULTS.e2ee.outboundRecordChunkBytes, maxPlain);
         if (!Number.isSafeInteger(this.outboundRecordChunkBytes) || this.outboundRecordChunkBytes <= 0 || this.outboundRecordChunkBytes > maxPlain) {
             throw new RangeError("outboundRecordChunkBytes must be a positive integer within the record plaintext limit");
         }
-        this.maxBufferedBytes = Math.max(0, args.maxBufferedBytes ?? 4 * (1 << 20));
-        const maxOutboundBufferedBytes = args.maxOutboundBufferedBytes ?? 4 * (1 << 20);
+        this.maxInboundBufferedBytes = Math.max(0, args.maxBufferedBytes ?? SDK_DEFAULTS.e2ee.maxInboundBufferedBytes);
+        const maxOutboundBufferedBytes = args.maxOutboundBufferedBytes ?? SDK_DEFAULTS.e2ee.maxOutboundBufferedBytes;
         if (!Number.isSafeInteger(maxOutboundBufferedBytes) || maxOutboundBufferedBytes < 0) {
             throw new RangeError("maxOutboundBufferedBytes must be a non-negative safe integer");
         }
-        this.maxOutboundBufferedBytes = maxOutboundBufferedBytes === 0 ? 4 * (1 << 20) : maxOutboundBufferedBytes;
+        this.maxOutboundBufferedBytes = maxOutboundBufferedBytes === 0 ? SDK_DEFAULTS.e2ee.maxOutboundBufferedBytes : maxOutboundBufferedBytes;
         this.sendKey = args.sendKey;
         this.recvKey = args.recvKey;
         this.sendNoncePrefix = args.sendNoncePrefix;
@@ -87,7 +87,11 @@ export class SecureChannel {
             if (this.recvQueueHead < this.recvQueue.length) {
                 const b = this.recvQueue[this.recvQueueHead];
                 this.recvQueueHead++;
-                if (this.recvQueueHead > 1024 && this.recvQueueHead * 2 > this.recvQueue.length) {
+                if (this.recvQueueHead === this.recvQueue.length) {
+                    this.recvQueue = [];
+                    this.recvQueueHead = 0;
+                }
+                else if (this.recvQueueHead > 1024 && this.recvQueueHead * 2 > this.recvQueue.length) {
                     this.recvQueue.splice(0, this.recvQueueHead);
                     this.recvQueueHead = 0;
                 }
@@ -171,7 +175,11 @@ export class SecureChannel {
             return null;
         const req = this.sendQueue[this.sendQueueHead];
         this.sendQueueHead++;
-        if (this.sendQueueHead > 1024 && this.sendQueueHead * 2 > this.sendQueue.length) {
+        if (this.sendQueueHead === this.sendQueue.length) {
+            this.sendQueue = [];
+            this.sendQueueHead = 0;
+        }
+        else if (this.sendQueueHead > 1024 && this.sendQueueHead * 2 > this.sendQueue.length) {
             this.sendQueue.splice(0, this.sendQueueHead);
             this.sendQueueHead = 0;
         }
@@ -182,7 +190,11 @@ export class SecureChannel {
             return undefined;
         const w = this.sendWaiters[this.sendWaitersHead];
         this.sendWaitersHead++;
-        if (this.sendWaitersHead > 1024 && this.sendWaitersHead * 2 > this.sendWaiters.length) {
+        if (this.sendWaitersHead === this.sendWaiters.length) {
+            this.sendWaiters = [];
+            this.sendWaitersHead = 0;
+        }
+        else if (this.sendWaitersHead > 1024 && this.sendWaitersHead * 2 > this.sendWaiters.length) {
             this.sendWaiters.splice(0, this.sendWaitersHead);
             this.sendWaitersHead = 0;
         }
@@ -284,7 +296,7 @@ export class SecureChannel {
                 }
                 this.recvSeq = seq + 1n;
                 if (flags === RECORD_FLAG_APP) {
-                    if (this.maxBufferedBytes > 0 && this.recvQueueBytes + plaintext.length > this.maxBufferedBytes) {
+                    if (this.maxInboundBufferedBytes > 0 && this.recvQueueBytes + plaintext.length > this.maxInboundBufferedBytes) {
                         throw new Error("recv buffer exceeded");
                     }
                     this.recvQueue.push(plaintext);