@floegence/flowersec-core 0.19.11 → 0.20.0

package/dist/yamux/session.js

@@ -1,7 +1,16 @@
 import { ByteReader } from "./byteReader.js";
 import { decodeHeader, encodeHeader, HEADER_LEN } from "./header.js";
-import { DEFAULT_MAX_STREAM_WINDOW, FLAG_ACK, FLAG_RST, FLAG_SYN, TYPE_DATA, TYPE_GO_AWAY, TYPE_PING, TYPE_WINDOW_UPDATE, YAMUX_VERSION } from "./constants.js";
+import { FLAG_ACK, FLAG_RST, FLAG_SYN, TYPE_DATA, TYPE_GO_AWAY, TYPE_PING, TYPE_WINDOW_UPDATE, YAMUX_VERSION } from "./constants.js";
 import { YamuxStream } from "./stream.js";
+import { YamuxResourceExhaustedError } from "./errors.js";
+export const DEFAULT_YAMUX_LIMITS = Object.freeze({
+    maxActiveStreams: 64,
+    maxInboundStreams: 32,
+    maxFrameBytes: 256 * 1024,
+    preferredOutboundFrameBytes: 64 * 1024,
+    maxStreamReceiveBytes: 256 * 1024,
+    maxSessionReceiveBytes: 16 * (1 << 20),
+});
 // YamuxSession multiplexes multiple streams over a single byte stream.
 export class YamuxSession {
     // Underlying byte stream for yamux frames.
@@ -13,7 +22,8 @@ export class YamuxSession {
     // Callback for inbound streams created from SYN frames.
     onIncomingStream;
     // Maximum allowed DATA frame length.
-    maxFrameBytes;
+    limits;
+    onDiagnostic;
     // True when this side is the yamux client (odd local stream IDs).
     client;
     // Next stream ID to allocate (odd/even based on role).
@@ -22,6 +32,11 @@ export class YamuxSession {
     closed = false;
     // Writers waiting for send window credits per stream.
     sendWindowWaiters = new Map();
+    inboundStreams = new Set();
+    sessionReceiveBytes = 0;
+    nextPingId = 1;
+    pingWaiters = new Map();
+    activeProbe;
     constructor(conn, opts) {
         this.conn = conn;
         this.reader = new ByteReader(async () => {
@@ -33,19 +48,33 @@ export class YamuxSession {
             }
         });
         this.onIncomingStream = opts.onIncomingStream;
-        this.maxFrameBytes = Math.max(0, opts.maxFrameBytes ?? DEFAULT_MAX_STREAM_WINDOW);
+        this.limits = normalizeYamuxLimits({ ...opts.limits, ...(opts.maxFrameBytes === undefined ? {} : { maxFrameBytes: opts.maxFrameBytes }) });
+        this.onDiagnostic = opts.onDiagnostic;
         this.client = opts.client;
         this.nextStreamId = opts.client ? 1 : 2;
         void this.readLoop();
     }
     // openStream allocates a new stream and performs the SYN handshake.
     async openStream() {
+        if (this.closed)
+            throw new Error("session closed");
+        if (this.streams.size >= this.limits.maxActiveStreams) {
+            const error = new YamuxResourceExhaustedError("active_streams", this.streams.size, this.limits.maxActiveStreams);
+            this.diagnostic({ code: "resource_limit_reached", resource: error.resource, current: error.current, limit: error.limit });
+            throw error;
+        }
         const id = this.nextStreamId;
         this.nextStreamId += 2;
         const s = new YamuxStream(this, id, "init");
         this.streams.set(id, s);
-        await s.open();
-        return s;
+        try {
+            await s.open();
+            return s;
+        }
+        catch (error) {
+            this.onStreamClosed(id);
+            throw error;
+        }
     }
     // getStream returns the stream for an ID, if any.
     getStream(id) {
@@ -55,6 +84,57 @@ export class YamuxSession {
     async writeRaw(chunk) {
         await this.conn.write(chunk);
     }
+    outboundFrameBytes() {
+        return this.limits.preferredOutboundFrameBytes;
+    }
+    releaseReceiveBytes(bytes) {
+        this.sessionReceiveBytes = Math.max(0, this.sessionReceiveBytes - Math.max(0, bytes));
+    }
+    // probeLiveness performs a correlated yamux PING SYN/ACK round trip.
+    async probeLiveness(timeoutMs = 10_000) {
+        if (this.activeProbe != null)
+            return await this.activeProbe;
+        const probe = this.startLivenessProbe(timeoutMs);
+        this.activeProbe = probe;
+        try {
+            return await probe;
+        }
+        finally {
+            if (this.activeProbe === probe)
+                this.activeProbe = undefined;
+        }
+    }
+    async startLivenessProbe(timeoutMs) {
+        if (this.closed)
+            throw new Error("session closed");
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+            throw new RangeError("timeoutMs must be positive");
+        let opaque = this.nextPingId >>> 0;
+        do {
+            opaque = this.nextPingId++ >>> 0;
+            if (this.nextPingId > 0xffffffff)
+                this.nextPingId = 1;
+        } while (opaque === 0 || this.pingWaiters.has(opaque));
+        const startedAt = monotonicMilliseconds();
+        return await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pingWaiters.delete(opaque);
+                reject(new Error("yamux ping timeout"));
+                this.close();
+            }, timeoutMs);
+            timer?.unref?.();
+            this.pingWaiters.set(opaque, { startedAt, resolve, reject, timer });
+            const hdr = encodeHeader({ type: TYPE_PING, flags: FLAG_SYN, streamId: 0, length: opaque });
+            void this.writeRaw(hdr).catch((err) => {
+                const waiter = this.pingWaiters.get(opaque);
+                if (waiter == null)
+                    return;
+                this.pingWaiters.delete(opaque);
+                clearTimeout(waiter.timer);
+                reject(err);
+            });
+        });
+    }
     // sendRst sends a reset frame and removes the stream.
     async sendRst(id) {
         const hdr = encodeHeader({ type: TYPE_WINDOW_UPDATE, flags: FLAG_RST, streamId: id, length: 0 });
@@ -102,7 +182,11 @@ export class YamuxSession {
     onStreamEstablished(_streamId) { }
     // onStreamClosed removes the stream and wakes any per-stream waiters.
     onStreamClosed(streamId) {
+        const stream = this.streams.get(streamId);
+        if (stream != null)
+            this.releaseReceiveBytes(stream.releaseBufferedReceiveBytes());
         this.streams.delete(streamId);
+        this.inboundStreams.delete(streamId);
         this.notifySendWindow(streamId);
     }
     // close terminates the session and resets all streams.
@@ -112,6 +196,11 @@ export class YamuxSession {
         this.closed = true;
         this.conn.close();
         this.wakeSendWindowWaiters();
+        for (const waiter of this.pingWaiters.values()) {
+            clearTimeout(waiter.timer);
+            waiter.reject(new Error("session closed"));
+        }
+        this.pingWaiters.clear();
         const streams = Array.from(this.streams.values());
         this.streams.clear();
         for (const s of streams)
@@ -134,12 +223,47 @@ export class YamuxSession {
                     return;
                 }
                 if (h.type === TYPE_DATA) {
-                    if (this.maxFrameBytes > 0 && h.length > this.maxFrameBytes) {
+                    if (h.length > this.limits.maxFrameBytes) {
+                        this.close();
+                        return;
+                    }
+                    if (h.streamId === 0) {
+                        this.close();
+                        return;
+                    }
+                    const existing = this.streams.get(h.streamId);
+                    if (existing == null) {
+                        const inboundAllowed = (h.flags & FLAG_SYN) !== 0 && this.isInboundStreamIdValid(h.streamId);
+                        const resourceAllowed = this.streams.size < this.limits.maxActiveStreams && this.inboundStreams.size < this.limits.maxInboundStreams;
+                        if (!inboundAllowed || !resourceAllowed || h.length > this.limits.maxStreamReceiveBytes) {
+                            await this.reader.discardExactly(h.length);
+                            this.diagnostic({
+                                code: "stream_rejected",
+                                resource: !resourceAllowed ? "inbound_streams" : "stream_receive_bytes",
+                                current: !resourceAllowed ? this.inboundStreams.size : h.length,
+                                limit: !resourceAllowed ? this.limits.maxInboundStreams : this.limits.maxStreamReceiveBytes,
+                            });
+                            await this.sendRst(h.streamId);
+                            continue;
+                        }
+                    }
+                    if (existing != null && existing.bufferedReceiveBytes() + h.length > this.limits.maxStreamReceiveBytes) {
+                        await this.reader.discardExactly(h.length);
+                        this.diagnostic({ code: "resource_limit_reached", resource: "stream_receive_bytes", current: existing.bufferedReceiveBytes() + h.length, limit: this.limits.maxStreamReceiveBytes });
+                        await this.sendRst(h.streamId);
+                        continue;
+                    }
+                    if (this.sessionReceiveBytes + h.length > this.limits.maxSessionReceiveBytes) {
+                        this.diagnostic({ code: "resource_limit_reached", resource: "session_receive_bytes", current: this.sessionReceiveBytes + h.length, limit: this.limits.maxSessionReceiveBytes });
                         this.close();
                         return;
                     }
                     const data = h.length > 0 ? await this.reader.readExactly(h.length) : new Uint8Array();
-                    await this.handleDataFrame(h.streamId, h.flags, data);
+                    if (data.length > 0)
+                        this.sessionReceiveBytes += data.length;
+                    const accepted = await this.handleDataFrame(h.streamId, h.flags, data);
+                    if (!accepted)
+                        this.releaseReceiveBytes(data.length);
                     continue;
                 }
                 if (h.type === TYPE_WINDOW_UPDATE) {
@@ -168,30 +292,43 @@ export class YamuxSession {
             await this.writeRaw(hdr);
             return;
         }
+        if ((flags & FLAG_ACK) !== 0) {
+            const waiter = this.pingWaiters.get(opaque >>> 0);
+            if (waiter == null)
+                return;
+            this.pingWaiters.delete(opaque >>> 0);
+            clearTimeout(waiter.timer);
+            waiter.resolve(Math.max(0, monotonicMilliseconds() - waiter.startedAt));
+        }
     }
     async handleDataFrame(streamId, flags, data) {
         if (streamId === 0) {
             this.close();
-            return;
+            return false;
         }
         let s = this.streams.get(streamId);
         if (s == null) {
             if ((flags & FLAG_SYN) !== 0) {
                 if (!this.isInboundStreamIdValid(streamId)) {
                     await this.sendRst(streamId);
-                    return;
+                    return false;
+                }
+                if (this.streams.size >= this.limits.maxActiveStreams || this.inboundStreams.size >= this.limits.maxInboundStreams || data.length > this.limits.maxStreamReceiveBytes) {
+                    await this.sendRst(streamId);
+                    return false;
                 }
                 s = new YamuxStream(this, streamId, "synReceived");
                 this.streams.set(streamId, s);
+                this.inboundStreams.add(streamId);
                 await s.open();
                 this.onIncomingStream?.(s);
             }
             else {
                 await this.sendRst(streamId);
-                return;
+                return false;
             }
         }
-        s.onData(data, flags);
+        return s.onData(data, flags);
     }
     async handleWindowUpdateFrame(streamId, flags, delta) {
         if (streamId === 0) {
@@ -205,8 +342,13 @@ export class YamuxSession {
                     await this.sendRst(streamId);
                     return;
                 }
+                if (this.streams.size >= this.limits.maxActiveStreams || this.inboundStreams.size >= this.limits.maxInboundStreams) {
+                    await this.sendRst(streamId);
+                    return;
+                }
                 s = new YamuxStream(this, streamId, "synReceived");
                 this.streams.set(streamId, s);
+                this.inboundStreams.add(streamId);
                 await s.open();
                 this.onIncomingStream?.(s);
             }
@@ -215,7 +357,9 @@ export class YamuxSession {
                 return;
             }
         }
-        s.onWindowUpdate(delta, flags);
+        if (!s.onWindowUpdate(delta, flags)) {
+            this.close();
+        }
     }
     isInboundStreamIdValid(streamId) {
         // yamux uses stream ID parity to identify the initiator:
@@ -225,4 +369,39 @@ export class YamuxSession {
         // When we are the server, the peer is the client and must initiate odd IDs.
         return (streamId & 1) === (this.client ? 0 : 1);
     }
+    diagnostic(event) {
+        try {
+            this.onDiagnostic?.(event);
+        }
+        catch { /* Diagnostics cannot affect transport behavior. */ }
+    }
+}
+function normalizeYamuxLimits(input) {
+    const maxFrameBytes = input?.maxFrameBytes ?? DEFAULT_YAMUX_LIMITS.maxFrameBytes;
+    const limits = {
+        maxActiveStreams: input?.maxActiveStreams ?? DEFAULT_YAMUX_LIMITS.maxActiveStreams,
+        maxInboundStreams: input?.maxInboundStreams ?? DEFAULT_YAMUX_LIMITS.maxInboundStreams,
+        maxFrameBytes,
+        preferredOutboundFrameBytes: input?.preferredOutboundFrameBytes ?? Math.min(DEFAULT_YAMUX_LIMITS.preferredOutboundFrameBytes, maxFrameBytes),
+        maxStreamReceiveBytes: input?.maxStreamReceiveBytes ?? DEFAULT_YAMUX_LIMITS.maxStreamReceiveBytes,
+        maxSessionReceiveBytes: input?.maxSessionReceiveBytes ?? DEFAULT_YAMUX_LIMITS.maxSessionReceiveBytes,
+    };
+    for (const [name, value] of Object.entries(limits)) {
+        if (!Number.isSafeInteger(value) || value <= 0)
+            throw new RangeError(`${name} must be a positive integer`);
+    }
+    if (limits.maxInboundStreams > limits.maxActiveStreams)
+        throw new RangeError("maxInboundStreams must not exceed maxActiveStreams");
+    if (limits.preferredOutboundFrameBytes > limits.maxFrameBytes)
+        throw new RangeError("preferredOutboundFrameBytes must not exceed maxFrameBytes");
+    if (limits.maxFrameBytes > limits.maxStreamReceiveBytes)
+        throw new RangeError("maxFrameBytes must not exceed maxStreamReceiveBytes");
+    if (limits.maxStreamReceiveBytes < DEFAULT_YAMUX_LIMITS.maxStreamReceiveBytes)
+        throw new RangeError("maxStreamReceiveBytes must cover the 256 KiB initial stream window");
+    if (limits.maxStreamReceiveBytes > limits.maxSessionReceiveBytes)
+        throw new RangeError("maxStreamReceiveBytes must not exceed maxSessionReceiveBytes");
+    return Object.freeze(limits);
+}
+function monotonicMilliseconds() {
+    return typeof performance !== "undefined" ? performance.now() : Date.now();
 }

package/dist/yamux/stream.d.ts

@@ -11,14 +11,21 @@ export declare class YamuxStream {
     private recvQueueBytes;
     private readWaiters;
     private error;
+    private resetTask;
+    private writeChain;
+    private finalized;
     constructor(session: YamuxSession, id: number, state: StreamState);
     open(): Promise<void>;
-    onData(data: Uint8Array, flags: number): void;
-    onWindowUpdate(delta: number, flags: number): void;
+    onData(data: Uint8Array, flags: number): boolean;
+    onWindowUpdate(delta: number, flags: number): boolean;
     read(): Promise<Uint8Array | null>;
     write(data: Uint8Array): Promise<void>;
+    private writeSerial;
     close(): Promise<void>;
-    reset(err: Error): void;
+    reset(err: Error): Promise<void>;
+    private fail;
+    bufferedReceiveBytes(): number;
+    releaseBufferedReceiveBytes(): number;
     private processFlags;
     private finalizeClosed;
     private shiftRecv;

package/dist/yamux/stream.js

@@ -22,6 +22,9 @@ export class YamuxStream {
     readWaiters = [];
     // Terminal error (reset/overflow) for the stream.
     error = null;
+    resetTask;
+    writeChain = Promise.resolve();
+    finalized = false;
     constructor(session, id, state) {
         this.session = session;
         this.id = id;
@@ -33,26 +36,35 @@ export class YamuxStream {
     }
     // onData handles inbound DATA frames and updates receive window.
     onData(data, flags) {
-        this.processFlags(flags);
-        if (data.length === 0)
-            return;
-        if (data.length > this.recvWindow) {
-            this.reset(new Error("recv window exceeded"));
-            return;
+        this.processFlags(flags & ~FLAG_FIN);
+        if (this.state === "reset" || this.state === "closed")
+            return false;
+        if (data.length > 0) {
+            if (data.length > this.recvWindow) {
+                void this.reset(new Error("recv window exceeded"));
+                return false;
+            }
+            this.recvWindow -= data.length;
+            this.recvQueue.push(data);
+            this.recvQueueBytes += data.length;
         }
-        this.recvWindow -= data.length;
-        this.recvQueue.push(data);
-        this.recvQueueBytes += data.length;
+        this.processFlags(flags & FLAG_FIN);
         const ws = this.readWaiters;
         this.readWaiters = [];
         for (const w of ws)
             w();
+        return true;
     }
     // onWindowUpdate applies flow-control credits from peer.
     onWindowUpdate(delta, flags) {
         this.processFlags(flags);
-        this.sendWindow += delta >>> 0;
+        const credit = delta >>> 0;
+        if (credit > DEFAULT_MAX_STREAM_WINDOW - this.sendWindow) {
+            return false;
+        }
+        this.sendWindow += credit;
         this.session.notifySendWindow(this.id);
+        return true;
     }
     // read resolves with the next data chunk, null on EOF, or throws on reset/errors.
     async read() {
@@ -62,7 +74,10 @@ export class YamuxStream {
             const b = this.shiftRecv();
             if (b != null) {
                 this.recvQueueBytes -= b.length;
+                this.session.releaseReceiveBytes(b.length);
                 await this.sendWindowUpdate();
+                if (this.recvQueueBytes === 0 && this.state === "closed")
+                    this.finalizeClosed();
                 return b;
             }
             if (this.state === "closed" || this.state === "remoteClose")
@@ -72,11 +87,17 @@ export class YamuxStream {
     }
     // write sends DATA frames, respecting the send window.
     async write(data) {
+        const payload = data.slice();
+        const write = this.writeChain.then(() => this.writeSerial(payload));
+        this.writeChain = write.catch(() => { });
+        await write;
+    }
+    async writeSerial(data) {
         this.ensureWritable();
         let off = 0;
         while (off < data.length) {
             this.ensureWritable();
-            const chunk = data.subarray(off);
+            const chunk = data.subarray(off, off + this.session.outboundFrameBytes());
             const allowed = await this.waitForSendWindow(chunk.length);
             this.ensureWritable();
             const sendChunk = chunk.subarray(0, allowed);
@@ -111,26 +132,42 @@ export class YamuxStream {
             await this.session.writeRaw(hdr);
         }
         finally {
-            if (wasRemoteClose)
+            if (wasRemoteClose && this.recvQueueBytes === 0)
                 this.finalizeClosed();
         }
     }
     // reset tears down the stream and notifies the peer.
     reset(err) {
+        if (this.resetTask != null)
+            return this.resetTask;
+        if (!this.fail(err))
+            return Promise.resolve();
+        this.resetTask = this.session.sendRst(this.id);
+        return this.resetTask;
+    }
+    fail(err) {
         if (this.state === "reset")
-            return;
+            return false;
         this.state = "reset";
         this.error = err;
         // Drop any buffered data to free memory on terminal errors.
-        this.recvQueue.length = 0;
-        this.recvQueueHead = 0;
-        this.recvQueueBytes = 0;
+        this.session.releaseReceiveBytes(this.releaseBufferedReceiveBytes());
         const ws = this.readWaiters;
         this.readWaiters = [];
         for (const w of ws)
             w();
         this.session.notifySendWindow(this.id);
-        void this.session.sendRst(this.id);
+        return true;
+    }
+    bufferedReceiveBytes() {
+        return this.recvQueueBytes;
+    }
+    releaseBufferedReceiveBytes() {
+        const bytes = this.recvQueueBytes;
+        this.recvQueue.length = 0;
+        this.recvQueueHead = 0;
+        this.recvQueueBytes = 0;
+        return bytes;
     }
     // processFlags updates the state machine for ACK/FIN/RST.
     processFlags(flags) {
@@ -142,7 +179,8 @@ export class YamuxStream {
         if ((flags & FLAG_FIN) !== 0) {
             if (this.state === "localClose") {
                 this.state = "closed";
-                this.finalizeClosed();
+                if (this.recvQueueBytes === 0)
+                    this.finalizeClosed();
             }
             else if (this.state === "established" || this.state === "synSent" || this.state === "synReceived") {
                 this.state = "remoteClose";
@@ -153,10 +191,14 @@ export class YamuxStream {
                 w();
         }
         if ((flags & FLAG_RST) !== 0) {
-            this.reset(new Error("rst"));
+            if (this.fail(new Error("rst")))
+                this.session.onStreamClosed(this.id);
         }
     }
     finalizeClosed() {
+        if (this.finalized)
+            return;
+        this.finalized = true;
         const ws = this.readWaiters;
         this.readWaiters = [];
         for (const w of ws)

package/package.json

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