@floegence/flowersec-core 0.1.1

package/dist/yamux/session.js

@@ -0,0 +1,228 @@
+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 { YamuxStream } from "./stream.js";
+// YamuxSession multiplexes multiple streams over a single byte stream.
+export class YamuxSession {
+    // Underlying byte stream for yamux frames.
+    conn;
+    // Reader for fixed-length header/body reads.
+    reader;
+    // Active streams keyed by stream ID.
+    streams = new Map();
+    // Callback for inbound streams created from SYN frames.
+    onIncomingStream;
+    // Maximum allowed DATA frame length.
+    maxFrameBytes;
+    // True when this side is the yamux client (odd local stream IDs).
+    client;
+    // Next stream ID to allocate (odd/even based on role).
+    nextStreamId;
+    // Closed flag for terminating read loops and streams.
+    closed = false;
+    // Writers waiting for send window credits per stream.
+    sendWindowWaiters = new Map();
+    constructor(conn, opts) {
+        this.conn = conn;
+        this.reader = new ByteReader(async () => {
+            try {
+                return await this.conn.read();
+            }
+            catch {
+                return null;
+            }
+        });
+        this.onIncomingStream = opts.onIncomingStream;
+        this.maxFrameBytes = Math.max(0, opts.maxFrameBytes ?? DEFAULT_MAX_STREAM_WINDOW);
+        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() {
+        const id = this.nextStreamId;
+        this.nextStreamId += 2;
+        const s = new YamuxStream(this, id, "init");
+        this.streams.set(id, s);
+        await s.open();
+        return s;
+    }
+    // getStream returns the stream for an ID, if any.
+    getStream(id) {
+        return this.streams.get(id);
+    }
+    // writeRaw writes a raw yamux frame to the underlying connection.
+    async writeRaw(chunk) {
+        await this.conn.write(chunk);
+    }
+    // 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 });
+        if (this.closed) {
+            this.onStreamClosed(id);
+            return;
+        }
+        try {
+            await this.writeRaw(hdr);
+        }
+        catch {
+            // Best-effort reset; ignore errors when the session is closing.
+        }
+        this.onStreamClosed(id);
+    }
+    // notifySendWindow wakes any writers waiting on window credit.
+    notifySendWindow(streamId) {
+        const ws = this.sendWindowWaiters.get(streamId);
+        if (ws == null)
+            return;
+        this.sendWindowWaiters.delete(streamId);
+        for (const w of ws)
+            w();
+    }
+    // waitForSendWindow blocks until send window credits are available.
+    waitForSendWindow(streamId) {
+        if (this.closed)
+            return Promise.reject(new Error("session closed"));
+        return new Promise((resolve, reject) => {
+            if (this.closed) {
+                reject(new Error("session closed"));
+                return;
+            }
+            const ws = this.sendWindowWaiters.get(streamId) ?? [];
+            ws.push(() => {
+                if (this.closed) {
+                    reject(new Error("session closed"));
+                    return;
+                }
+                resolve();
+            });
+            this.sendWindowWaiters.set(streamId, ws);
+        });
+    }
+    onStreamEstablished(_streamId) { }
+    // onStreamClosed removes the stream and wakes any per-stream waiters.
+    onStreamClosed(streamId) {
+        this.streams.delete(streamId);
+        this.notifySendWindow(streamId);
+    }
+    // close terminates the session and resets all streams.
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.conn.close();
+        this.wakeSendWindowWaiters();
+        const streams = Array.from(this.streams.values());
+        this.streams.clear();
+        for (const s of streams)
+            s.reset(new Error("session closed"));
+    }
+    wakeSendWindowWaiters() {
+        for (const [streamId, ws] of this.sendWindowWaiters) {
+            this.sendWindowWaiters.delete(streamId);
+            for (const w of ws)
+                w();
+        }
+    }
+    async readLoop() {
+        try {
+            while (!this.closed) {
+                const hdrBytes = await this.reader.readExactly(HEADER_LEN);
+                const h = decodeHeader(hdrBytes, 0);
+                if (h.version !== YAMUX_VERSION) {
+                    this.close();
+                    return;
+                }
+                if (h.type === TYPE_DATA) {
+                    if (this.maxFrameBytes > 0 && h.length > this.maxFrameBytes) {
+                        this.close();
+                        return;
+                    }
+                    const data = h.length > 0 ? await this.reader.readExactly(h.length) : new Uint8Array();
+                    await this.handleDataFrame(h.streamId, h.flags, data);
+                    continue;
+                }
+                if (h.type === TYPE_WINDOW_UPDATE) {
+                    await this.handleWindowUpdateFrame(h.streamId, h.flags, h.length);
+                    continue;
+                }
+                if (h.type === TYPE_PING) {
+                    await this.handlePing(h.flags, h.length);
+                    continue;
+                }
+                if (h.type === TYPE_GO_AWAY) {
+                    this.close();
+                    return;
+                }
+                this.close();
+                return;
+            }
+        }
+        catch {
+            this.close();
+        }
+    }
+    async handlePing(flags, opaque) {
+        if ((flags & FLAG_SYN) !== 0) {
+            const hdr = encodeHeader({ type: TYPE_PING, flags: FLAG_ACK, streamId: 0, length: opaque >>> 0 });
+            await this.writeRaw(hdr);
+            return;
+        }
+    }
+    async handleDataFrame(streamId, flags, data) {
+        if (streamId === 0) {
+            this.close();
+            return;
+        }
+        let s = this.streams.get(streamId);
+        if (s == null) {
+            if ((flags & FLAG_SYN) !== 0) {
+                if (!this.isInboundStreamIdValid(streamId)) {
+                    await this.sendRst(streamId);
+                    return;
+                }
+                s = new YamuxStream(this, streamId, "synReceived");
+                this.streams.set(streamId, s);
+                await s.open();
+                this.onIncomingStream?.(s);
+            }
+            else {
+                await this.sendRst(streamId);
+                return;
+            }
+        }
+        s.onData(data, flags);
+    }
+    async handleWindowUpdateFrame(streamId, flags, delta) {
+        if (streamId === 0) {
+            this.close();
+            return;
+        }
+        let s = this.streams.get(streamId);
+        if (s == null) {
+            if ((flags & FLAG_SYN) !== 0) {
+                if (!this.isInboundStreamIdValid(streamId)) {
+                    await this.sendRst(streamId);
+                    return;
+                }
+                s = new YamuxStream(this, streamId, "synReceived");
+                this.streams.set(streamId, s);
+                await s.open();
+                this.onIncomingStream?.(s);
+            }
+            else {
+                await this.sendRst(streamId);
+                return;
+            }
+        }
+        s.onWindowUpdate(delta, flags);
+    }
+    isInboundStreamIdValid(streamId) {
+        // yamux uses stream ID parity to identify the initiator:
+        // client-initiated streams are odd, server-initiated streams are even.
+        //
+        // When we are the client, the peer is the server and must initiate even IDs.
+        // When we are the server, the peer is the client and must initiate odd IDs.
+        return (streamId & 1) === (this.client ? 0 : 1);
+    }
+}

package/dist/yamux/stream.d.ts

@@ -0,0 +1,30 @@
+import type { YamuxSession } from "./session.js";
+type StreamState = "init" | "synSent" | "synReceived" | "established" | "localClose" | "remoteClose" | "closed" | "reset";
+export declare class YamuxStream {
+    readonly id: number;
+    private state;
+    private readonly session;
+    private recvWindow;
+    private sendWindow;
+    private readonly recvQueue;
+    private recvQueueHead;
+    private recvQueueBytes;
+    private readWaiters;
+    private error;
+    constructor(session: YamuxSession, id: number, state: StreamState);
+    open(): Promise<void>;
+    onData(data: Uint8Array, flags: number): void;
+    onWindowUpdate(delta: number, flags: number): void;
+    read(): Promise<Uint8Array>;
+    write(data: Uint8Array): Promise<void>;
+    close(): Promise<void>;
+    reset(err: Error): void;
+    private processFlags;
+    private finalizeClosed;
+    private shiftRecv;
+    private sendFlags;
+    private sendWindowUpdate;
+    private waitForSendWindow;
+    private ensureWritable;
+}
+export {};

package/dist/yamux/stream.js

@@ -0,0 +1,222 @@
+import { concatBytes } from "../utils/bin.js";
+import { encodeHeader } from "./header.js";
+import { DEFAULT_MAX_STREAM_WINDOW, FLAG_ACK, FLAG_FIN, FLAG_RST, FLAG_SYN, TYPE_DATA, TYPE_WINDOW_UPDATE } from "./constants.js";
+// YamuxStream manages per-stream flow control and state transitions.
+export class YamuxStream {
+    // Stream identifier within the session.
+    id;
+    // Current stream state in the yamux state machine.
+    state;
+    // Parent session used for frame IO and window coordination.
+    session;
+    // Remaining receive window advertised to the peer.
+    recvWindow = DEFAULT_MAX_STREAM_WINDOW;
+    // Remaining send window credit granted by the peer.
+    sendWindow = DEFAULT_MAX_STREAM_WINDOW;
+    // Buffered inbound data chunks.
+    recvQueue = [];
+    recvQueueHead = 0;
+    // Total buffered bytes in recvQueue.
+    recvQueueBytes = 0;
+    // Readers waiting for incoming data or EOF/reset.
+    readWaiters = [];
+    // Terminal error (reset/overflow) for the stream.
+    error = null;
+    constructor(session, id, state) {
+        this.session = session;
+        this.id = id;
+        this.state = state;
+    }
+    // open sends the initial window update to establish the stream.
+    async open() {
+        await this.sendWindowUpdate();
+    }
+    // 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.recvWindow -= data.length;
+        this.recvQueue.push(data);
+        this.recvQueueBytes += data.length;
+        const ws = this.readWaiters;
+        this.readWaiters = [];
+        for (const w of ws)
+            w();
+    }
+    // onWindowUpdate applies flow-control credits from peer.
+    onWindowUpdate(delta, flags) {
+        this.processFlags(flags);
+        this.sendWindow += delta >>> 0;
+        this.session.notifySendWindow(this.id);
+    }
+    // read resolves with the next data chunk or throws on EOF/reset.
+    async read() {
+        while (true) {
+            if (this.error != null)
+                throw this.error;
+            const b = this.shiftRecv();
+            if (b != null) {
+                this.recvQueueBytes -= b.length;
+                await this.sendWindowUpdate();
+                return b;
+            }
+            if (this.state === "closed" || this.state === "remoteClose")
+                throw new Error("eof");
+            await new Promise((resolve) => this.readWaiters.push(resolve));
+        }
+    }
+    // write sends DATA frames, respecting the send window.
+    async write(data) {
+        this.ensureWritable();
+        let off = 0;
+        while (off < data.length) {
+            this.ensureWritable();
+            const chunk = data.subarray(off);
+            const allowed = await this.waitForSendWindow(chunk.length);
+            this.ensureWritable();
+            const sendChunk = chunk.subarray(0, allowed);
+            const flags = this.sendFlags();
+            this.sendWindow -= sendChunk.length;
+            const hdr = encodeHeader({
+                type: TYPE_DATA,
+                flags,
+                streamId: this.id,
+                length: sendChunk.length
+            });
+            await this.session.writeRaw(concatBytes([hdr, sendChunk]));
+            off += sendChunk.length;
+        }
+    }
+    // close sends FIN and transitions to local close.
+    async close() {
+        if (this.state === "closed")
+            return;
+        if (this.state === "reset")
+            return;
+        const wasRemoteClose = this.state === "remoteClose";
+        const flags = this.sendFlags() | FLAG_FIN;
+        this.state = wasRemoteClose ? "closed" : "localClose";
+        const hdr = encodeHeader({
+            type: TYPE_WINDOW_UPDATE,
+            flags,
+            streamId: this.id,
+            length: 0
+        });
+        try {
+            await this.session.writeRaw(hdr);
+        }
+        finally {
+            if (wasRemoteClose)
+                this.finalizeClosed();
+        }
+    }
+    // reset tears down the stream and notifies the peer.
+    reset(err) {
+        if (this.state === "reset")
+            return;
+        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;
+        const ws = this.readWaiters;
+        this.readWaiters = [];
+        for (const w of ws)
+            w();
+        this.session.notifySendWindow(this.id);
+        void this.session.sendRst(this.id);
+    }
+    // processFlags updates the state machine for ACK/FIN/RST.
+    processFlags(flags) {
+        if ((flags & FLAG_ACK) !== 0) {
+            if (this.state === "synSent")
+                this.state = "established";
+            this.session.onStreamEstablished(this.id);
+        }
+        if ((flags & FLAG_FIN) !== 0) {
+            if (this.state === "localClose") {
+                this.state = "closed";
+                this.finalizeClosed();
+            }
+            else if (this.state === "established" || this.state === "synSent" || this.state === "synReceived") {
+                this.state = "remoteClose";
+            }
+            const ws = this.readWaiters;
+            this.readWaiters = [];
+            for (const w of ws)
+                w();
+        }
+        if ((flags & FLAG_RST) !== 0) {
+            this.reset(new Error("rst"));
+        }
+    }
+    finalizeClosed() {
+        const ws = this.readWaiters;
+        this.readWaiters = [];
+        for (const w of ws)
+            w();
+        this.session.onStreamClosed(this.id);
+    }
+    shiftRecv() {
+        if (this.recvQueueHead >= this.recvQueue.length)
+            return undefined;
+        const b = this.recvQueue[this.recvQueueHead];
+        this.recvQueueHead++;
+        if (this.recvQueueHead > 1024 && this.recvQueueHead * 2 > this.recvQueue.length) {
+            this.recvQueue.splice(0, this.recvQueueHead);
+            this.recvQueueHead = 0;
+        }
+        return b;
+    }
+    // sendFlags returns any SYN/ACK flags needed for the current state.
+    sendFlags() {
+        if (this.state === "init") {
+            this.state = "synSent";
+            return FLAG_SYN;
+        }
+        if (this.state === "synReceived") {
+            this.state = "established";
+            return FLAG_ACK;
+        }
+        return 0;
+    }
+    // sendWindowUpdate advertises the current receive window to the peer.
+    async sendWindowUpdate() {
+        const max = DEFAULT_MAX_STREAM_WINDOW;
+        const bufLen = this.recvQueueBytes >>> 0;
+        const delta = (max - bufLen) - this.recvWindow;
+        const flags = this.sendFlags();
+        if (delta < max / 2 && flags === 0)
+            return;
+        this.recvWindow += delta;
+        const hdr = encodeHeader({
+            type: TYPE_WINDOW_UPDATE,
+            flags,
+            streamId: this.id,
+            length: delta >>> 0
+        });
+        await this.session.writeRaw(hdr);
+    }
+    // waitForSendWindow blocks until credits are available.
+    async waitForSendWindow(want) {
+        if (want <= 0)
+            return 0;
+        while (this.sendWindow <= 0) {
+            this.ensureWritable();
+            await this.session.waitForSendWindow(this.id);
+        }
+        return Math.min(want, this.sendWindow);
+    }
+    ensureWritable() {
+        if (this.state === "reset")
+            throw new Error("stream reset");
+        if (this.state === "closed" || this.state === "localClose")
+            throw new Error("stream closed");
+    }
+}

package/package.json

@@ -0,0 +1,112 @@
+{
+  "name": "@floegence/flowersec-core",
+  "version": "0.1.1",
+  "description": "Flowersec core TypeScript library (browser-friendly E2EE + multiplexing over WebSocket).",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/floegence/flowersec.git"
+  },
+  "bugs": {
+    "url": "https://github.com/floegence/flowersec/issues"
+  },
+  "homepage": "https://github.com/floegence/flowersec#readme",
+  "type": "module",
+  "main": "./dist/facade.js",
+  "types": "./dist/facade.d.ts",
+  "files": [
+    "dist/**",
+    "README.md",
+    "LICENSE",
+    "YAMUX_ALIGNMENT.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/facade.d.ts",
+      "default": "./dist/facade.js"
+    },
+    "./node": {
+      "types": "./dist/node/index.d.ts",
+      "default": "./dist/node/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser/index.d.ts",
+      "default": "./dist/browser/index.js"
+    },
+    "./rpc": {
+      "types": "./dist/rpc/index.d.ts",
+      "default": "./dist/rpc/index.js"
+    },
+    "./yamux": {
+      "types": "./dist/yamux/index.d.ts",
+      "default": "./dist/yamux/index.js"
+    },
+    "./e2ee": {
+      "types": "./dist/e2ee/index.d.ts",
+      "default": "./dist/e2ee/index.js"
+    },
+    "./ws": {
+      "types": "./dist/ws/index.d.ts",
+      "default": "./dist/ws/index.js"
+    },
+    "./observability": {
+      "types": "./dist/observability/index.d.ts",
+      "default": "./dist/observability/index.js"
+    },
+    "./streamhello": {
+      "types": "./dist/streamhello/index.d.ts",
+      "default": "./dist/streamhello/index.js"
+    },
+    "./gen/flowersec/controlplane/*": {
+      "types": "./dist/gen/flowersec/controlplane/*.d.ts",
+      "default": "./dist/gen/flowersec/controlplane/*.js"
+    },
+    "./gen/flowersec/direct/*": {
+      "types": "./dist/gen/flowersec/direct/*.d.ts",
+      "default": "./dist/gen/flowersec/direct/*.js"
+    },
+    "./gen/flowersec/e2ee/*": {
+      "types": "./dist/gen/flowersec/e2ee/*.d.ts",
+      "default": "./dist/gen/flowersec/e2ee/*.js"
+    },
+    "./gen/flowersec/rpc/*": {
+      "types": "./dist/gen/flowersec/rpc/*.d.ts",
+      "default": "./dist/gen/flowersec/rpc/*.js"
+    },
+    "./gen/flowersec/tunnel/*": {
+      "types": "./dist/gen/flowersec/tunnel/*.d.ts",
+      "default": "./dist/gen/flowersec/tunnel/*.js"
+    },
+    "./internal": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": "^20.0.0 || ^22.0.0 || >=24.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "bench": "vitest bench --run",
+    "test": "vitest run",
+    "lint": "eslint ."
+  },
+  "dependencies": {
+    "@noble/ciphers": "^0.6.0",
+    "@noble/curves": "^1.9.0",
+    "@noble/hashes": "^1.8.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/ws": "^8.5.12",
+    "@typescript-eslint/eslint-plugin": "^8.18.0",
+    "@typescript-eslint/parser": "^8.18.0",
+    "eslint": "^9.17.0",
+    "typescript": "^5.7.2",
+    "vitest": "^4.0.17"
+  }
+}