@floegence/flowersec-core 0.23.0 → 0.24.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,27 @@ 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";
-
-const artifact = await requestConnectArtifact({
-  endpointId: "env_demo",
-});
-
-const client = await connectBrowser(artifact);
-await client.ping();
-client.close();
-```
-
-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",
-  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",
-  },
-});
-```
+The package is ESM-only and exposes environment-specific entrypoints for browser and Node.js applications.
 
-Browser `requestConnectArtifact(...)`, `requestEntryConnectArtifact(...)`, and `ControlplaneRequestError` remain available from `@floegence/flowersec-core/browser` as stable aliases.
+## Cookbook
 
-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.
+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.
 
-## Node endpoint and controlplane
+## Entrypoints
 
-`@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.
+- 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`
 
-## Proxy
+High-level WebSocket connections require TLS by default. Use `AllowPlaintextForLoopback` only for literal local development targets.
 
-`@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/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);

package/dist/endpoint/index.js

@@ -8,6 +8,7 @@ import { decodeHandshakeFrame } from "../e2ee/framing.js";
 import { HANDSHAKE_TYPE_INIT, PROTOCOL_VERSION } from "../e2ee/constants.js";
 import { readStreamHello, writeStreamHello } from "../streamhello/streamHello.js";
 import { ByteReader } from "../yamux/byteReader.js";
+import { isYamuxPingTimeoutError } from "../yamux/errors.js";
 import { YamuxSession } from "../yamux/session.js";
 import { RpcServer } from "../rpc/server.js";
 import { base64urlDecode, base64urlEncode } from "../utils/base64url.js";
@@ -43,9 +44,10 @@ export class Session {
         return session;
     }
     async openStream(kind, options = {}) {
+        const streamKind = normalizeStreamKind(kind, this.path);
         const stream = await this.mux.openStream(options);
         try {
-            await writeStreamHello((bytes) => stream.write(bytes), normalizeStreamKind(kind, this.path));
+            await writeStreamHello((bytes) => stream.write(bytes), streamKind);
             return stream;
         }
         catch (error) {
@@ -82,8 +84,19 @@ export class Session {
             return;
         }
     }
-    probeLiveness(timeoutMs = SDK_DEFAULTS.transport.handshakeTimeoutMs) {
-        return this.mux.probeLiveness(timeoutMs);
+    async probeLiveness(timeoutMs = SDK_DEFAULTS.transport.handshakeTimeoutMs) {
+        try {
+            return await this.mux.probeLiveness(timeoutMs);
+        }
+        catch (error) {
+            throw new FlowersecError({
+                path: this.path,
+                stage: "yamux",
+                code: isYamuxPingTimeoutError(error) ? "timeout" : "ping_failed",
+                message: "endpoint liveness probe failed",
+                cause: error,
+            });
+        }
     }
     async rekey() {
         try {
@@ -247,7 +260,7 @@ async function establishSession(path, transport, handshake, options, endpointIns
             maxHandshakePayload: options.maxHandshakePayload ?? SDK_DEFAULTS.e2ee.maxHandshakePayloadBytes,
             maxRecordBytes: options.maxRecordBytes ?? SDK_DEFAULTS.e2ee.maxRecordBytes,
             outboundRecordChunkBytes: options.outboundRecordChunkBytes ?? SDK_DEFAULTS.e2ee.outboundRecordChunkBytes,
-            maxBufferedBytes: options.maxBufferedBytes ?? SDK_DEFAULTS.e2ee.maxOutboundBufferedBytes,
+            maxBufferedBytes: options.maxBufferedBytes ?? SDK_DEFAULTS.e2ee.maxInboundBufferedBytes,
             maxOutboundBufferedBytes: options.maxOutboundBufferedBytes ?? SDK_DEFAULTS.e2ee.maxOutboundBufferedBytes,
             timeoutMs: options.handshakeTimeoutMs ?? SDK_DEFAULTS.transport.handshakeTimeoutMs,
             ...(options.signal === undefined ? {} : { signal: options.signal }),
@@ -327,7 +340,7 @@ function randomEndpointInstanceId() {
 function normalizeStreamKind(kind, path) {
     const value = kind.trim();
     if (value === "")
-        throw new FlowersecError({ path, stage: "validate", code: "missing_stream_kind", message: "missing stream kind" });
+        throw new FlowersecError({ path, stage: "rpc", code: "missing_stream_kind", message: "missing stream kind" });
     return value;
 }
 function unwrapServerGrant(input) {

package/dist/reconnect/index.js

@@ -1,6 +1,7 @@
 import { getClientTermination } from "../client-connect/termination.js";
 import { emitObserverDiagnostic, withObserverContext } from "../observability/observer.js";
 import { SDK_DEFAULTS } from "../defaults.js";
+import { AbortError, FlowersecError } from "../utils/errors.js";
 export { createArtifactResolver, createControlplaneArtifactSource } from "./artifactControlplane.js";
 function normalizeAutoReconnect(cfg) {
     const settings = {
@@ -33,6 +34,26 @@ function backoffDelayMs(attemptIndex, cfg) {
     const jitter = cfg.jitterRatio <= 0 ? 0 : base * cfg.jitterRatio * (Math.random() * 2 - 1);
     return Math.max(0, Math.round(base + jitter));
 }
+const TERMINAL_RECONNECT_CODES = new Set([
+    "invalid_input",
+    "invalid_option",
+    "role_mismatch",
+    "transport_policy_denied",
+    "invalid_psk",
+    "invalid_suite",
+    "missing_grant",
+    "missing_connect_info",
+    "missing_tunnel_url",
+    "missing_ws_url",
+    "missing_channel_id",
+    "missing_token",
+    "missing_init_exp",
+]);
+function isTerminalConnectError(error) {
+    if (error instanceof AbortError || error.name === "AbortError")
+        return true;
+    return error instanceof FlowersecError && (error.code === "canceled" || TERMINAL_RECONNECT_CODES.has(error.code));
+}
 function isSameConfig(a, b) {
     if (a == null)
         return false;
@@ -101,6 +122,30 @@ export function createReconnectManager() {
             resolve();
         }, ms);
     });
+    const finishWithError = (cfg, error, currentAttemptSeq) => {
+        setState({ status: "error", error, client: null });
+        emitObserverDiagnostic(withObserverContext(cfg.observer, { attemptSeq: currentAttemptSeq }), {
+            path: "auto",
+            stage: "reconnect",
+            code_domain: "event",
+            code: "reconnect_exhausted",
+            result: "fail",
+        });
+    };
+    const scheduleRetry = async (t, cfg, error, settings, failedAttemptIndex, currentAttemptSeq) => {
+        if (t !== token || active !== cfg)
+            return false;
+        setState({ status: "connecting", error, client: null });
+        emitObserverDiagnostic(withObserverContext(cfg.observer, { attemptSeq: currentAttemptSeq }), {
+            path: "auto",
+            stage: "reconnect",
+            code_domain: "event",
+            code: "reconnect_scheduled",
+            result: "retry",
+        });
+        await sleep(backoffDelayMs(failedAttemptIndex, settings));
+        return t === token && active === cfg;
+    };
     const disconnectInternal = () => {
         cancelRetrySleep();
         abortActiveAttempt();
@@ -145,8 +190,7 @@ export function createReconnectManager() {
         }
         token += 1;
         const nextToken = token;
-        const reconnectPromise = startConnectLoop(nextToken, cfg);
-        setState({ status: "connecting", error, client: null });
+        const reconnectPromise = startConnectLoop(nextToken, cfg, error);
         void reconnectPromise.catch(() => {
             // connectWithRetry updates state; keep errors observable via state().
         });
@@ -184,9 +228,17 @@ export function createReconnectManager() {
         attemptAbort = new AbortController();
         return await cfg.connectOnce({ signal: attemptAbort.signal, observer: createObserver(t, cfg, currentAttemptSeq) ?? {} });
     };
-    const connectWithRetry = async (t, cfg) => {
+    const connectWithRetry = async (t, cfg, initialFailure) => {
         const ar = normalizeAutoReconnect(cfg.autoReconnect);
         let attempts = 0;
+        if (initialFailure != null) {
+            if (isTerminalConnectError(initialFailure)) {
+                finishWithError(cfg, initialFailure, attemptSeq);
+                throw initialFailure;
+            }
+            if (!await scheduleRetry(t, cfg, initialFailure, ar, 0, attemptSeq))
+                return;
+        }
         for (;;) {
             if (t !== token)
                 return;
@@ -245,32 +297,17 @@ export function createReconnectManager() {
                     return;
                 if (active !== cfg)
                     return;
-                const canRetry = ar.enabled && attempts < ar.maxAttempts;
+                const canRetry = ar.enabled && attempts < ar.maxAttempts && !isTerminalConnectError(e);
                 if (!canRetry) {
-                    setState({ status: "error", error: e, client: null });
-                    emitObserverDiagnostic(withObserverContext(cfg.observer, { attemptSeq }), {
-                        path: "auto",
-                        stage: "reconnect",
-                        code_domain: "event",
-                        code: "reconnect_exhausted",
-                        result: "fail",
-                    });
+                    finishWithError(cfg, e, attemptSeq);
                     throw e;
                 }
-                setState({ status: "connecting", error: e, client: null });
-                const delay = backoffDelayMs(attempts - 1, ar);
-                emitObserverDiagnostic(withObserverContext(cfg.observer, { attemptSeq }), {
-                    path: "auto",
-                    stage: "reconnect",
-                    code_domain: "event",
-                    code: "reconnect_scheduled",
-                    result: "retry",
-                });
-                await sleep(delay);
+                if (!await scheduleRetry(t, cfg, e, ar, attempts - 1, attemptSeq))
+                    return;
             }
         }
     };
-    const startConnectLoop = (t, cfg) => {
+    const startConnectLoop = (t, cfg, initialFailure) => {
         let resolveLoop;
         let rejectLoop;
         const loop = new Promise((resolve, reject) => {
@@ -283,7 +320,7 @@ export function createReconnectManager() {
                 activeConnectPromise = null;
         });
         activeConnectPromise = promise;
-        void connectWithRetry(t, cfg).then(resolveLoop, rejectLoop);
+        void connectWithRetry(t, cfg, initialFailure).then(resolveLoop, rejectLoop);
         return promise;
     };
     const connect = async (cfg) => {
@@ -300,7 +337,7 @@ export function createReconnectManager() {
             setState({ status: "error", error: closeError, client: null });
             throw closeError;
         }
-        const connectPromise = startConnectLoop(t, cfg);
+        const connectPromise = startConnectLoop(t, cfg, null);
         setState({ status: "connecting", error: null, client: null });
         await connectPromise;
     };

package/dist/yamux/byteReader.d.ts

@@ -8,4 +8,6 @@ export declare class ByteReader {
     readExactly(n: number): Promise<Uint8Array>;
     discardExactly(n: number): Promise<void>;
     bufferedBytes(): number;
+    private consumeAvailable;
+    private compactConsumedChunks;
 }

package/dist/yamux/byteReader.js

@@ -23,25 +23,7 @@ export class ByteReader {
             this.buffered += chunk.length;
         }
         const out = new Uint8Array(n);
-        let outOff = 0;
-        while (outOff < n) {
-            const head = this.chunks[this.chunkHead];
-            const avail = head.length - this.headOff;
-            const need = n - outOff;
-            const take = Math.min(avail, need);
-            out.set(head.subarray(this.headOff, this.headOff + take), outOff);
-            outOff += take;
-            this.headOff += take;
-            this.buffered -= take;
-            if (this.headOff === head.length) {
-                this.chunkHead++;
-                this.headOff = 0;
-                if (this.chunkHead > 1024 && this.chunkHead * 2 > this.chunks.length) {
-                    this.chunks.splice(0, this.chunkHead);
-                    this.chunkHead = 0;
-                }
-            }
-        }
+        this.consumeAvailable(n, out);
         return out;
     }
     // discardExactly consumes bytes without allocating a contiguous output buffer.
@@ -59,19 +41,41 @@ export class ByteReader {
                 this.chunks.push(chunk);
                 this.buffered += chunk.length;
             }
+            remaining -= this.consumeAvailable(remaining);
+        }
+    }
+    // bufferedBytes returns the number of bytes currently buffered.
+    bufferedBytes() {
+        return this.buffered;
+    }
+    consumeAvailable(maxBytes, output) {
+        let consumed = 0;
+        while (consumed < maxBytes && this.buffered > 0) {
             const head = this.chunks[this.chunkHead];
-            const take = Math.min(remaining, head.length - this.headOff);
+            const take = Math.min(maxBytes - consumed, head.length - this.headOff);
+            if (output != null)
+                output.set(head.subarray(this.headOff, this.headOff + take), consumed);
             this.headOff += take;
             this.buffered -= take;
-            remaining -= take;
+            consumed += take;
             if (this.headOff === head.length) {
                 this.chunkHead++;
                 this.headOff = 0;
             }
         }
+        this.compactConsumedChunks();
+        return consumed;
     }
-    // bufferedBytes returns the number of bytes currently buffered.
-    bufferedBytes() {
-        return this.buffered;
+    compactConsumedChunks() {
+        if (this.buffered === 0) {
+            this.chunks.length = 0;
+            this.chunkHead = 0;
+            this.headOff = 0;
+            return;
+        }
+        if (this.chunkHead > 1024 && this.chunkHead * 2 > this.chunks.length) {
+            this.chunks.splice(0, this.chunkHead);
+            this.chunkHead = 0;
+        }
     }
 }

package/dist/yamux/session.js

@@ -11,7 +11,7 @@ export const DEFAULT_YAMUX_LIMITS = Object.freeze({
     preferredOutboundFrameBytes: SDK_DEFAULTS.yamux.preferredOutboundFrameBytes,
     maxStreamReceiveBytes: SDK_DEFAULTS.yamux.maxStreamReceiveBytes,
     maxSessionReceiveBytes: SDK_DEFAULTS.yamux.maxSessionReceiveBytes,
-    maxStreamWriteQueueBytes: SDK_DEFAULTS.e2ee.maxOutboundBufferedBytes,
+    maxStreamWriteQueueBytes: SDK_DEFAULTS.yamux.maxStreamWriteQueueBytes,
 });
 // YamuxSession multiplexes multiple streams over a single byte stream.
 export class YamuxSession {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floegence/flowersec-core",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Flowersec core TypeScript library (browser-friendly E2EE + multiplexing over WebSocket).",
   "license": "MIT",
   "repository": {
@@ -121,6 +121,8 @@
     "build": "tsc -p tsconfig.build.json",
     "bench": "vitest bench --run",
     "test": "npm run build && vitest run",
+    "test:browser": "npm run build && playwright test",
+    "ensure:browser": "node ./scripts/ensure-playwright-chromium.mjs",
     "test:coverage": "npm run build && vitest run --coverage",
     "lint": "eslint .",
     "verify:package": "node ./scripts/verify-package-exports.mjs",
@@ -136,6 +138,7 @@
   "devDependencies": {
     "@types/node": "^24.0.0",
     "@types/ws": "^8.5.12",
+    "@playwright/test": "1.58.2",
     "@typescript-eslint/eslint-plugin": "^8.18.0",
     "@typescript-eslint/parser": "^8.18.0",
     "@vitest/coverage-v8": "4.1.0",