@floegence/flowersec-core 0.26.0 → 2.0.0

package/dist/e2ee/secureChannel.d.ts

@@ -1,92 +0,0 @@
-export type ReadBinaryOptions = Readonly<{
-    /** Optional AbortSignal to cancel the pending operation. */
-    signal?: AbortSignal;
-    /** Optional timeout (milliseconds) for the pending operation. */
-    timeoutMs?: number;
-}>;
-export type WriteBinaryOptions = Readonly<{
-    /** Optional AbortSignal to cancel the pending operation. */
-    signal?: AbortSignal;
-}>;
-export type BinaryTransport = {
-    /** Reads the next binary frame from the underlying transport. */
-    readBinary(opts?: ReadBinaryOptions): Promise<Uint8Array>;
-    /** Writes a binary frame to the underlying transport. */
-    writeBinary(frame: Uint8Array, opts?: WriteBinaryOptions): Promise<void>;
-    /** Closes the transport and unblocks pending readers/writers. */
-    close(): void;
-};
-export type SecureChannelOptions = Readonly<{
-    /** Maximum encoded record size (header + ciphertext). */
-    maxRecordBytes: number;
-    /** Preferred plaintext bytes per outbound record. */
-    outboundRecordChunkBytes?: number;
-    /** Maximum queued inbound plaintext bytes before the channel is closed. */
-    maxBufferedBytes?: number;
-    /** Maximum queued outbound plaintext bytes (default 4 MiB; 0 uses default). */
-    maxOutboundBufferedBytes?: number;
-}>;
-type Direction = 1 | 2;
-export declare class SecureChannel {
-    private readonly transport;
-    private readonly maxRecordBytes;
-    private readonly outboundRecordChunkBytes;
-    private readonly maxInboundBufferedBytes;
-    private readonly maxOutboundBufferedBytes;
-    private sendKey;
-    private recvKey;
-    private sendNoncePrefix;
-    private recvNoncePrefix;
-    private readonly rekeyBase;
-    private readonly transcriptHash;
-    private readonly sendDir;
-    private readonly recvDir;
-    private sendSeq;
-    private recvSeq;
-    private sendQueue;
-    private sendQueueHead;
-    private sendWaiters;
-    private sendWaitersHead;
-    private sendQueueBytes;
-    private sendClosed;
-    private sendErr;
-    private recvQueue;
-    private recvQueueHead;
-    private recvQueueBytes;
-    private recvWaiters;
-    private readErr;
-    private closed;
-    constructor(args: {
-        transport: BinaryTransport;
-        maxRecordBytes: number;
-        outboundRecordChunkBytes?: number;
-        maxBufferedBytes?: number;
-        maxOutboundBufferedBytes?: number;
-        sendKey: Uint8Array;
-        recvKey: Uint8Array;
-        sendNoncePrefix: Uint8Array;
-        recvNoncePrefix: Uint8Array;
-        rekeyBase: Uint8Array;
-        transcriptHash: Uint8Array;
-        sendDir: Direction;
-        recvDir: Direction;
-        sendSeq?: bigint;
-        recvSeq?: bigint;
-    });
-    write(plaintext: Uint8Array): Promise<void>;
-    read(): Promise<Uint8Array>;
-    close(): void;
-    sendPing(): Promise<void>;
-    rekeyNow(): Promise<void>;
-    private enqueueSend;
-    private nextSend;
-    private dequeueSend;
-    private shiftSendWaiter;
-    private wakeSendWaiters;
-    private rejectQueuedSenders;
-    private failSend;
-    private reserveSendSeq;
-    private sendLoop;
-    private readLoop;
-}
-export {};

package/dist/e2ee/secureChannel.js

@@ -1,328 +0,0 @@
-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() {
-        super("record seq exhausted");
-        this.name = "RecordSeqExhaustedError";
-    }
-}
-// SecureChannel encrypts/decrypts records and buffers application payloads.
-export class SecureChannel {
-    // Underlying transport for encrypted record frames.
-    transport;
-    // Maximum allowed bytes per record frame.
-    maxRecordBytes;
-    outboundRecordChunkBytes;
-    maxInboundBufferedBytes;
-    maxOutboundBufferedBytes;
-    // Active encryption keys and nonce prefixes for the current epoch.
-    sendKey;
-    recvKey;
-    sendNoncePrefix;
-    recvNoncePrefix;
-    // Rekey base secret derived from the handshake.
-    rekeyBase;
-    // Transcript hash binding rekeys to the handshake.
-    transcriptHash;
-    // Rekey direction identifiers for send/recv.
-    sendDir;
-    recvDir;
-    // Monotonic record sequence numbers per direction.
-    sendSeq;
-    recvSeq;
-    // Send queue and waiters for backpressure.
-    sendQueue = [];
-    sendQueueHead = 0;
-    sendWaiters = [];
-    sendWaitersHead = 0;
-    sendQueueBytes = 0;
-    sendClosed = false;
-    sendErr = null;
-    // Receive queue and waiters for plaintext delivery.
-    recvQueue = [];
-    recvQueueHead = 0;
-    recvQueueBytes = 0;
-    recvWaiters = [];
-    readErr = null;
-    closed = false;
-    constructor(args) {
-        this.transport = args.transport;
-        this.maxRecordBytes = args.maxRecordBytes;
-        const maxPlain = Math.max(1, maxPlaintextBytes(this.maxRecordBytes));
-        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.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 ? SDK_DEFAULTS.e2ee.maxOutboundBufferedBytes : maxOutboundBufferedBytes;
-        this.sendKey = args.sendKey;
-        this.recvKey = args.recvKey;
-        this.sendNoncePrefix = args.sendNoncePrefix;
-        this.recvNoncePrefix = args.recvNoncePrefix;
-        this.rekeyBase = args.rekeyBase;
-        this.transcriptHash = args.transcriptHash;
-        this.sendDir = args.sendDir;
-        this.recvDir = args.recvDir;
-        this.sendSeq = args.sendSeq ?? 1n;
-        this.recvSeq = args.recvSeq ?? 1n;
-        void this.readLoop();
-        void this.sendLoop();
-    }
-    // write splits payloads into record-sized chunks and queues them for send.
-    async write(plaintext) {
-        if (plaintext.length === 0)
-            return;
-        await this.enqueueSend("app", plaintext);
-    }
-    // read resolves with the next plaintext chunk or throws on errors/close.
-    async read() {
-        while (true) {
-            if (this.recvQueueHead < this.recvQueue.length) {
-                const b = this.recvQueue[this.recvQueueHead];
-                this.recvQueueHead++;
-                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;
-                }
-                this.recvQueueBytes -= b.length;
-                return b;
-            }
-            if (this.readErr != null)
-                throw this.readErr;
-            if (this.closed)
-                throw new Error("closed");
-            await new Promise((resolve) => this.recvWaiters.push(resolve));
-        }
-    }
-    // close shuts down the transport and rejects any pending senders.
-    close() {
-        if (this.closed)
-            return;
-        this.closed = true;
-        this.sendClosed = true;
-        this.rejectQueuedSenders(this.sendErr ?? new Error("closed"));
-        this.wakeSendWaiters();
-        this.transport.close();
-        const ws = this.recvWaiters;
-        this.recvWaiters = [];
-        for (const w of ws)
-            w();
-    }
-    // sendPing emits a keepalive record.
-    async sendPing() {
-        await this.enqueueSend("ping");
-    }
-    // rekeyNow emits a rekey record and advances the send key.
-    async rekeyNow() {
-        await this.enqueueSend("rekey");
-    }
-    enqueueSend(kind, payload) {
-        if (this.sendErr != null)
-            return Promise.reject(this.sendErr);
-        if (this.closed || this.sendClosed)
-            return Promise.reject(new Error("closed"));
-        const bufferedBytes = payload?.byteLength ?? 0;
-        if (this.sendQueueBytes + bufferedBytes > this.maxOutboundBufferedBytes) {
-            return Promise.reject(new Error("secure channel outbound buffer exceeded"));
-        }
-        return new Promise((resolve, reject) => {
-            if (this.sendErr != null) {
-                reject(this.sendErr);
-                return;
-            }
-            if (this.closed || this.sendClosed) {
-                reject(new Error("closed"));
-                return;
-            }
-            if (this.sendQueueBytes + bufferedBytes > this.maxOutboundBufferedBytes) {
-                reject(new Error("secure channel outbound buffer exceeded"));
-                return;
-            }
-            const retainedPayload = payload?.slice();
-            const req = retainedPayload === undefined
-                ? { kind, bufferedBytes, resolve, reject }
-                : { kind, payload: retainedPayload, bufferedBytes, resolve, reject };
-            this.sendQueueBytes += bufferedBytes;
-            this.sendQueue.push(req);
-            const w = this.shiftSendWaiter();
-            if (w != null)
-                w();
-        });
-    }
-    async nextSend() {
-        const immediate = this.dequeueSend();
-        if (immediate != null)
-            return immediate;
-        if (this.closed || this.sendClosed)
-            return null;
-        return await new Promise((resolve) => {
-            this.sendWaiters.push(() => resolve(this.dequeueSend()));
-        });
-    }
-    dequeueSend() {
-        if (this.sendQueueHead >= this.sendQueue.length)
-            return null;
-        const req = this.sendQueue[this.sendQueueHead];
-        this.sendQueueHead++;
-        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;
-        }
-        return req;
-    }
-    shiftSendWaiter() {
-        if (this.sendWaitersHead >= this.sendWaiters.length)
-            return undefined;
-        const w = this.sendWaiters[this.sendWaitersHead];
-        this.sendWaitersHead++;
-        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;
-        }
-        return w;
-    }
-    wakeSendWaiters() {
-        const ws = this.sendWaiters;
-        const start = this.sendWaitersHead;
-        this.sendWaiters = [];
-        this.sendWaitersHead = 0;
-        for (let i = start; i < ws.length; i++)
-            ws[i]();
-    }
-    rejectQueuedSenders(err) {
-        const queued = this.sendQueue;
-        const start = this.sendQueueHead;
-        this.sendQueue = [];
-        this.sendQueueHead = 0;
-        for (let i = start; i < queued.length; i++) {
-            const req = queued[i];
-            this.sendQueueBytes = Math.max(0, this.sendQueueBytes - req.bufferedBytes);
-            req.reject(err);
-        }
-    }
-    failSend(err) {
-        if (this.sendErr != null)
-            return;
-        this.sendErr = err;
-        this.rejectQueuedSenders(err);
-        this.wakeSendWaiters();
-    }
-    reserveSendSeq() {
-        if (this.sendSeq >= maxRecordSeq) {
-            const err = new RecordSeqExhaustedError();
-            this.failSend(err);
-            throw err;
-        }
-        const seq = this.sendSeq;
-        this.sendSeq++;
-        return seq;
-    }
-    async sendLoop() {
-        while (true) {
-            const req = await this.nextSend();
-            if (req == null)
-                return;
-            try {
-                if (this.sendErr != null) {
-                    req.reject(this.sendErr);
-                    continue;
-                }
-                if (this.closed || this.sendClosed) {
-                    req.reject(new Error("closed"));
-                    continue;
-                }
-                let frame;
-                if (req.kind === "app") {
-                    const payload = req.payload ?? new Uint8Array();
-                    for (let offset = 0; offset < payload.length; offset += this.outboundRecordChunkBytes) {
-                        const chunk = payload.subarray(offset, Math.min(payload.length, offset + this.outboundRecordChunkBytes));
-                        const seq = this.reserveSendSeq();
-                        frame = encryptRecord(this.sendKey, this.sendNoncePrefix, RECORD_FLAG_APP, seq, chunk, this.maxRecordBytes);
-                        await this.transport.writeBinary(frame);
-                    }
-                    req.resolve();
-                    continue;
-                }
-                else if (req.kind === "ping") {
-                    const seq = this.reserveSendSeq();
-                    frame = encryptRecord(this.sendKey, this.sendNoncePrefix, RECORD_FLAG_PING, seq, new Uint8Array(), this.maxRecordBytes);
-                }
-                else {
-                    const seq = this.reserveSendSeq();
-                    frame = encryptRecord(this.sendKey, this.sendNoncePrefix, RECORD_FLAG_REKEY, seq, new Uint8Array(), this.maxRecordBytes);
-                    // Update the send key after enqueuing the rekey frame.
-                    this.sendKey = deriveRekeyKey(this.rekeyBase, this.transcriptHash, seq, this.sendDir);
-                }
-                await this.transport.writeBinary(frame);
-                req.resolve();
-            }
-            catch (e) {
-                req.reject(e);
-                this.failSend(e);
-                this.close();
-                return;
-            }
-            finally {
-                this.sendQueueBytes = Math.max(0, this.sendQueueBytes - req.bufferedBytes);
-            }
-        }
-    }
-    async readLoop() {
-        try {
-            while (!this.closed) {
-                const frame = await this.transport.readBinary();
-                const { flags, seq, plaintext } = decryptRecord(this.recvKey, this.recvNoncePrefix, frame, this.recvSeq, this.maxRecordBytes);
-                if (seq >= maxRecordSeq) {
-                    throw new RecordSeqExhaustedError();
-                }
-                this.recvSeq = seq + 1n;
-                if (flags === RECORD_FLAG_APP) {
-                    if (this.maxInboundBufferedBytes > 0 && this.recvQueueBytes + plaintext.length > this.maxInboundBufferedBytes) {
-                        throw new Error("recv buffer exceeded");
-                    }
-                    this.recvQueue.push(plaintext);
-                    this.recvQueueBytes += plaintext.length;
-                    const ws = this.recvWaiters;
-                    this.recvWaiters = [];
-                    for (const w of ws)
-                        w();
-                    continue;
-                }
-                if (flags === RECORD_FLAG_PING)
-                    continue;
-                if (flags === RECORD_FLAG_REKEY) {
-                    this.recvKey = deriveRekeyKey(this.rekeyBase, this.transcriptHash, seq, this.recvDir);
-                    continue;
-                }
-                throw new Error(`unknown record flag ${flags}`);
-            }
-        }
-        catch (e) {
-            this.readErr = e;
-            const ws = this.recvWaiters;
-            this.recvWaiters = [];
-            for (const w of ws)
-                w();
-            this.close();
-        }
-    }
-}

package/dist/e2ee/transcript.d.ts

@@ -1,23 +0,0 @@
-export type TranscriptInputs = Readonly<{
-    /** Protocol version byte used in the transcript. */
-    version: number;
-    /** Numeric suite identifier (see e2ee suite). */
-    suite: number;
-    /** Role byte (client=1, server=2). */
-    role: number;
-    /** Client feature bitset. */
-    clientFeatures: number;
-    /** Server feature bitset. */
-    serverFeatures: number;
-    /** Channel identifier shared by both endpoints. */
-    channelId: string;
-    /** Client nonce (32 bytes). */
-    nonceC: Uint8Array;
-    /** Server nonce (32 bytes). */
-    nonceS: Uint8Array;
-    /** Client ephemeral public key bytes. */
-    clientEphPub: Uint8Array;
-    /** Server ephemeral public key bytes. */
-    serverEphPub: Uint8Array;
-}>;
-export declare function transcriptHash(inputs: TranscriptInputs): Uint8Array;

package/dist/e2ee/transcript.js

@@ -1,31 +0,0 @@
-import { sha256 } from "@noble/hashes/sha256";
-import { concatBytes, u16be, u32be } from "../utils/bin.js";
-const te = new TextEncoder();
-// transcriptHash computes the SHA-256 hash of the handshake transcript.
-export function transcriptHash(inputs) {
-    if (inputs.nonceC.length !== 32 || inputs.nonceS.length !== 32)
-        throw new Error("nonce must be 32 bytes");
-    const channelIdBytes = te.encode(inputs.channelId);
-    if (channelIdBytes.length > 0xffff)
-        throw new Error("channel_id too long");
-    if (inputs.clientEphPub.length > 0xffff || inputs.serverEphPub.length > 0xffff)
-        throw new Error("pub too long");
-    const prefix = te.encode("flowersec-e2ee-v1");
-    const body = concatBytes([
-        prefix,
-        new Uint8Array([inputs.version & 0xff]),
-        u16be(inputs.suite),
-        new Uint8Array([inputs.role & 0xff]),
-        u32be(inputs.clientFeatures >>> 0),
-        u32be(inputs.serverFeatures >>> 0),
-        u16be(channelIdBytes.length),
-        channelIdBytes,
-        inputs.nonceC,
-        inputs.nonceS,
-        u16be(inputs.clientEphPub.length),
-        inputs.clientEphPub,
-        u16be(inputs.serverEphPub.length),
-        inputs.serverEphPub
-    ]);
-    return sha256(body);
-}

package/dist/endpoint/index.d.ts

@@ -1,84 +0,0 @@
-import { type TransportSecurityPolicy } from "../client-connect/transportSecurity.js";
-import { serverHandshake, ServerHandshakeCache, type Suite } from "../e2ee/handshake.js";
-import { type YamuxLimits } from "../yamux/session.js";
-import type { YamuxStream } from "../yamux/stream.js";
-import { type RpcRouter, type RpcServerOptions } from "../rpc/server.js";
-import { type WebSocketLike, type WebSocketLimits } from "../ws-client/binaryTransport.js";
-export type { Suite } from "../e2ee/handshake.js";
-export type EndpointPath = "direct" | "tunnel";
-export type DirectHandshakeInit = Readonly<{
-    channelId: string;
-    version: number;
-    suite: Suite;
-    clientFeatures: number;
-}>;
-export type DirectHandshakeCredential = Readonly<{
-    psk: Uint8Array | string;
-    initExpireAtUnixS: number;
-    commitAuthenticated?: () => void | Promise<void>;
-}>;
-export type DirectCredentialResolver = (init: DirectHandshakeInit) => DirectHandshakeCredential | Promise<DirectHandshakeCredential>;
-export type EndpointOptions = Readonly<{
-    signal?: AbortSignal;
-    handshakeTimeoutMs?: number;
-    handshakeClockSkewMs?: number;
-    serverFeatures?: number;
-    maxHandshakePayload?: number;
-    maxRecordBytes?: number;
-    maxBufferedBytes?: number;
-    maxOutboundBufferedBytes?: number;
-    outboundRecordChunkBytes?: number;
-    webSocketLimits?: Partial<WebSocketLimits>;
-    yamuxLimits?: Partial<YamuxLimits>;
-    handshakeCache?: ServerHandshakeCache;
-}>;
-export type DirectAcceptOptions = EndpointOptions & Readonly<{
-    secureTransport?: boolean;
-    transportSecurityPolicy?: TransportSecurityPolicy;
-}>;
-export type TunnelEndpointOptions = EndpointOptions & Readonly<{
-    origin: string;
-    connectTimeoutMs?: number;
-    endpointInstanceId?: string;
-    wsFactory: (url: string, origin: string) => WebSocketLike;
-    transportSecurityPolicy?: TransportSecurityPolicy;
-}>;
-export type EndpointStream = Readonly<{
-    kind: string;
-    stream: YamuxStream;
-}>;
-export declare class Session {
-    private readonly secure;
-    private readonly mux;
-    readonly path: EndpointPath;
-    readonly endpointInstanceId: string | undefined;
-    private readonly streams;
-    private readonly waiters;
-    private terminalError;
-    private constructor();
-    static create(path: EndpointPath, secure: Awaited<ReturnType<typeof serverHandshake>>, options?: Readonly<{
-        yamuxLimits?: Partial<YamuxLimits>;
-        endpointInstanceId?: string;
-    }>): Session;
-    openStream(kind: string, options?: Readonly<{
-        signal?: AbortSignal;
-    }>): Promise<YamuxStream>;
-    acceptStream(options?: Readonly<{
-        signal?: AbortSignal;
-    }>): Promise<EndpointStream>;
-    serveRPC(router: RpcRouter, options?: RpcServerOptions & Readonly<{
-        signal?: AbortSignal;
-    }>): Promise<void>;
-    probeLiveness(timeoutMs?: 10000): Promise<number>;
-    rekey(): Promise<void>;
-    close(): void;
-    private pushStream;
-    private acceptRawStream;
-    private fail;
-}
-export declare function acceptDirect(websocket: WebSocketLike, handshake: Readonly<{
-    channelId: string;
-    suite: Suite;
-}> & DirectHandshakeCredential, options?: DirectAcceptOptions): Promise<Session>;
-export declare function acceptDirectResolved(websocket: WebSocketLike, resolver: DirectCredentialResolver, options?: DirectAcceptOptions): Promise<Session>;
-export declare function connectTunnel(grantInput: unknown, options: TunnelEndpointOptions): Promise<Session>;