@floegence/flowersec-core 0.1.1

package/dist/e2ee/secureChannel.js

@@ -0,0 +1,265 @@
+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";
+// 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;
+    // Upper bound for buffered plaintext in memory.
+    maxBufferedBytes;
+    // 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;
+    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;
+        this.maxBufferedBytes = Math.max(0, args.maxBufferedBytes ?? 4 * (1 << 20));
+        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) {
+        const maxPlain = Math.max(1, maxPlaintextBytes(this.maxRecordBytes) || plaintext.length);
+        let off = 0;
+        while (off < plaintext.length) {
+            const chunk = plaintext.slice(off, Math.min(plaintext.length, off + maxPlain));
+            await this.enqueueSend("app", chunk);
+            off += chunk.length;
+        }
+    }
+    // read resolves with the next plaintext chunk or throws on errors/close.
+    async read() {
+        while (true) {
+            if (this.readErr != null)
+                throw this.readErr;
+            if (this.recvQueueHead < this.recvQueue.length) {
+                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;
+                }
+                this.recvQueueBytes -= b.length;
+                return b;
+            }
+            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();
+        this.recvQueue.length = 0;
+        this.recvQueueHead = 0;
+        this.recvQueueBytes = 0;
+        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"));
+        return new Promise((resolve, reject) => {
+            if (this.sendErr != null) {
+                reject(this.sendErr);
+                return;
+            }
+            if (this.closed || this.sendClosed) {
+                reject(new Error("closed"));
+                return;
+            }
+            const req = payload === undefined ? { kind, resolve, reject } : { kind, payload, resolve, reject };
+            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 > 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 > 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++)
+            queued[i].reject(err);
+    }
+    failSend(err) {
+        if (this.sendErr != null)
+            return;
+        this.sendErr = err;
+        this.rejectQueuedSenders(err);
+        this.wakeSendWaiters();
+    }
+    async sendLoop() {
+        while (true) {
+            const req = await this.nextSend();
+            if (req == null)
+                return;
+            if (this.sendErr != null) {
+                req.reject(this.sendErr);
+                continue;
+            }
+            if (this.closed || this.sendClosed) {
+                req.reject(new Error("closed"));
+                continue;
+            }
+            try {
+                let frame;
+                if (req.kind === "app") {
+                    const seq = this.sendSeq++;
+                    frame = encryptRecord(this.sendKey, this.sendNoncePrefix, RECORD_FLAG_APP, seq, req.payload ?? new Uint8Array(), this.maxRecordBytes);
+                }
+                else if (req.kind === "ping") {
+                    const seq = this.sendSeq++;
+                    frame = encryptRecord(this.sendKey, this.sendNoncePrefix, RECORD_FLAG_PING, seq, new Uint8Array(), this.maxRecordBytes);
+                }
+                else {
+                    const seq = this.sendSeq++;
+                    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;
+            }
+        }
+    }
+    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);
+                this.recvSeq = seq + 1n;
+                if (flags === RECORD_FLAG_APP) {
+                    if (this.maxBufferedBytes > 0 && this.recvQueueBytes + plaintext.length > this.maxBufferedBytes) {
+                        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

@@ -0,0 +1,23 @@
+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

@@ -0,0 +1,31 @@
+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/facade.d.ts

@@ -0,0 +1,21 @@
+import type { Client } from "./client.js";
+import type { DirectConnectOptions } from "./direct-client/connect.js";
+import type { TunnelConnectOptions } from "./tunnel-client/connect.js";
+import type { ChannelInitGrant } from "./gen/flowersec/controlplane/v1.gen.js";
+import type { DirectConnectInfo } from "./gen/flowersec/direct/v1.gen.js";
+export type { ChannelInitGrant } from "./gen/flowersec/controlplane/v1.gen.js";
+export { assertChannelInitGrant } from "./gen/flowersec/controlplane/v1.gen.js";
+export type { DirectConnectInfo } from "./gen/flowersec/direct/v1.gen.js";
+export { assertDirectConnectInfo } from "./gen/flowersec/direct/v1.gen.js";
+export type { ClientObserverLike } from "./observability/observer.js";
+export type { Client, ClientPath } from "./client.js";
+export type { FlowersecErrorCode, FlowersecPath, FlowersecStage } from "./utils/errors.js";
+export { FlowersecError } from "./utils/errors.js";
+export type { TunnelConnectOptions } from "./tunnel-client/connect.js";
+export type { DirectConnectOptions } from "./direct-client/connect.js";
+export type ConnectOptions = TunnelConnectOptions | DirectConnectOptions;
+export declare function connectTunnel(grant: ChannelInitGrant, opts: TunnelConnectOptions): Promise<Client>;
+export declare function connectDirect(info: DirectConnectInfo, opts: DirectConnectOptions): Promise<Client>;
+export declare function connect(input: DirectConnectInfo, opts: DirectConnectOptions): Promise<Client>;
+export declare function connect(input: ChannelInitGrant, opts: TunnelConnectOptions): Promise<Client>;
+export declare function connect(input: unknown, opts: ConnectOptions): Promise<Client>;

package/dist/facade.js

@@ -0,0 +1,61 @@
+import { connectDirect as connectDirectInternal } from "./direct-client/connect.js";
+import { connectTunnel as connectTunnelInternal } from "./tunnel-client/connect.js";
+import { FlowersecError } from "./utils/errors.js";
+export { assertChannelInitGrant } from "./gen/flowersec/controlplane/v1.gen.js";
+export { assertDirectConnectInfo } from "./gen/flowersec/direct/v1.gen.js";
+export { FlowersecError } from "./utils/errors.js";
+export async function connectTunnel(grant, opts) {
+    return await connectTunnelInternal(grant, opts);
+}
+export async function connectDirect(info, opts) {
+    return await connectDirectInternal(info, opts);
+}
+function maybeParseJSON(input) {
+    if (typeof input !== "string")
+        return input;
+    const s = input.trim();
+    if (s === "")
+        return input;
+    if (s[0] !== "{" && s[0] !== "[")
+        return input;
+    try {
+        return JSON.parse(s);
+    }
+    catch (e) {
+        throw new FlowersecError({
+            path: "auto",
+            stage: "validate",
+            code: "invalid_input",
+            message: "invalid JSON string",
+            cause: e,
+        });
+    }
+}
+export async function connect(input, opts) {
+    const v = maybeParseJSON(input);
+    if (v != null && typeof v === "object") {
+        const o = v;
+        if (o["ws_url"] !== undefined)
+            return await connectDirectInternal(v, opts);
+        if (o["grant_client"] !== undefined)
+            return await connectTunnelInternal(v, opts);
+        if (o["grant_server"] !== undefined)
+            return await connectTunnelInternal(v, opts);
+        if (o["tunnel_url"] !== undefined)
+            return await connectTunnelInternal(v, opts);
+        if (o["token"] !== undefined || o["role"] !== undefined)
+            return await connectTunnelInternal(v, opts);
+        throw new FlowersecError({
+            path: "auto",
+            stage: "validate",
+            code: "invalid_input",
+            message: "invalid input: expected DirectConnectInfo (ws_url) or ChannelInitGrant (tunnel_url, grant_client, or grant_server)",
+        });
+    }
+    throw new FlowersecError({
+        path: "auto",
+        stage: "validate",
+        code: "invalid_input",
+        message: "invalid input: expected an object or a JSON string",
+    });
+}

package/dist/gen/flowersec/controlplane/v1.gen.d.ts

@@ -0,0 +1,36 @@
+/** Endpoint role for tunnel attach. */
+export declare enum Role {
+    /** Client endpoint. */
+    Role_client = 1,
+    /** Server endpoint. */
+    Role_server = 2
+}
+/** E2EE cipher suite identifier. */
+export declare enum Suite {
+    /** P-256 + HKDF-SHA256 + AES-256-GCM. */
+    Suite_P256_HKDF_SHA256_AES_256_GCM = 2,
+    /** X25519 + HKDF-SHA256 + AES-256-GCM. */
+    Suite_X25519_HKDF_SHA256_AES_256_GCM = 1
+}
+/** Grant issued by controlplane to attach and start E2EE. */
+export interface ChannelInitGrant {
+    /** WebSocket URL of the tunnel server. */
+    tunnel_url: string;
+    /** Channel identifier shared by both endpoints. */
+    channel_id: string;
+    /** Unix timestamp when the grant expires. */
+    channel_init_expire_at_unix_s: number;
+    /** Server idle timeout hint in seconds. */
+    idle_timeout_seconds: number;
+    /** Role for this grant (client or server). */
+    role: Role;
+    /** Signed tunnel attach token. */
+    token: string;
+    /** Base64url-encoded 32-byte PSK. */
+    e2ee_psk_b64u: string;
+    /** Allowed E2EE cipher suites. */
+    allowed_suites: Suite[];
+    /** Default E2EE cipher suite. */
+    default_suite: Suite;
+}
+export declare function assertChannelInitGrant(v: unknown): ChannelInitGrant;

package/dist/gen/flowersec/controlplane/v1.gen.js

@@ -0,0 +1,135 @@
+// Code generated by idlgen. DO NOT EDIT.
+/** Endpoint role for tunnel attach. */
+export var Role;
+(function (Role) {
+    /** Client endpoint. */
+    Role[Role["Role_client"] = 1] = "Role_client";
+    /** Server endpoint. */
+    Role[Role["Role_server"] = 2] = "Role_server";
+})(Role || (Role = {}));
+/** E2EE cipher suite identifier. */
+export var Suite;
+(function (Suite) {
+    /** P-256 + HKDF-SHA256 + AES-256-GCM. */
+    Suite[Suite["Suite_P256_HKDF_SHA256_AES_256_GCM"] = 2] = "Suite_P256_HKDF_SHA256_AES_256_GCM";
+    /** X25519 + HKDF-SHA256 + AES-256-GCM. */
+    Suite[Suite["Suite_X25519_HKDF_SHA256_AES_256_GCM"] = 1] = "Suite_X25519_HKDF_SHA256_AES_256_GCM";
+})(Suite || (Suite = {}));
+function isRecord(v) {
+    return typeof v === "object" && v != null && !Array.isArray(v);
+}
+function assertString(name, v) {
+    if (typeof v !== "string")
+        throw new Error(`bad ${name}`);
+    return v;
+}
+function assertBoolean(name, v) {
+    if (typeof v !== "boolean")
+        throw new Error(`bad ${name}`);
+    return v;
+}
+function assertSafeInt(name, v) {
+    if (typeof v !== "number" || !Number.isSafeInteger(v))
+        throw new Error(`bad ${name}`);
+    return v;
+}
+function assertU32(name, v) {
+    const n = assertSafeInt(name, v);
+    if (n < 0 || n > 0xffffffff)
+        throw new Error(`bad ${name}`);
+    return n;
+}
+function assertU16(name, v) {
+    const n = assertU32(name, v);
+    if (n > 0xffff)
+        throw new Error(`bad ${name}`);
+    return n;
+}
+function assertU8(name, v) {
+    const n = assertU32(name, v);
+    if (n > 0xff)
+        throw new Error(`bad ${name}`);
+    return n;
+}
+function assertU64(name, v) {
+    const n = assertSafeInt(name, v);
+    if (n < 0)
+        throw new Error(`bad ${name}`);
+    return n;
+}
+function assertI32(name, v) {
+    const n = assertSafeInt(name, v);
+    if (n < -2147483648 || n > 2147483647)
+        throw new Error(`bad ${name}`);
+    return n;
+}
+function assertI64(name, v) {
+    return assertSafeInt(name, v);
+}
+function assertStringMap(name, v) {
+    if (!isRecord(v))
+        throw new Error(`bad ${name}`);
+    for (const [k, vv] of Object.entries(v)) {
+        void k;
+        if (typeof vv !== "string")
+            throw new Error(`bad ${name}`);
+    }
+    return v;
+}
+const _RoleValues = new Set([
+    1,
+    2,
+]);
+function assertRole(name, v) {
+    const n = assertSafeInt(name, v);
+    if (!_RoleValues.has(n))
+        throw new Error(`bad ${name}`);
+    return n;
+}
+const _SuiteValues = new Set([
+    2,
+    1,
+]);
+function assertSuite(name, v) {
+    const n = assertSafeInt(name, v);
+    if (!_SuiteValues.has(n))
+        throw new Error(`bad ${name}`);
+    return n;
+}
+export function assertChannelInitGrant(v) {
+    if (!isRecord(v))
+        throw new Error("bad ChannelInitGrant");
+    const o = v;
+    if (o["tunnel_url"] === undefined)
+        throw new Error("bad ChannelInitGrant.tunnel_url");
+    assertString("ChannelInitGrant.tunnel_url", o["tunnel_url"]);
+    if (o["channel_id"] === undefined)
+        throw new Error("bad ChannelInitGrant.channel_id");
+    assertString("ChannelInitGrant.channel_id", o["channel_id"]);
+    if (o["channel_init_expire_at_unix_s"] === undefined)
+        throw new Error("bad ChannelInitGrant.channel_init_expire_at_unix_s");
+    assertI64("ChannelInitGrant.channel_init_expire_at_unix_s", o["channel_init_expire_at_unix_s"]);
+    if (o["idle_timeout_seconds"] === undefined)
+        throw new Error("bad ChannelInitGrant.idle_timeout_seconds");
+    assertI32("ChannelInitGrant.idle_timeout_seconds", o["idle_timeout_seconds"]);
+    if (o["role"] === undefined)
+        throw new Error("bad ChannelInitGrant.role");
+    assertRole("ChannelInitGrant.role", o["role"]);
+    if (o["token"] === undefined)
+        throw new Error("bad ChannelInitGrant.token");
+    assertString("ChannelInitGrant.token", o["token"]);
+    if (o["e2ee_psk_b64u"] === undefined)
+        throw new Error("bad ChannelInitGrant.e2ee_psk_b64u");
+    assertString("ChannelInitGrant.e2ee_psk_b64u", o["e2ee_psk_b64u"]);
+    if (o["allowed_suites"] === undefined)
+        throw new Error("bad ChannelInitGrant.allowed_suites");
+    if (!Array.isArray(o["allowed_suites"]))
+        throw new Error("bad ChannelInitGrant.allowed_suites");
+    for (let i = 0; i < o["allowed_suites"].length; i++) {
+        assertSuite("ChannelInitGrant.allowed_suites[]", o["allowed_suites"][i]);
+    }
+    if (o["default_suite"] === undefined)
+        throw new Error("bad ChannelInitGrant.default_suite");
+    assertSuite("ChannelInitGrant.default_suite", o["default_suite"]);
+    return o;
+}

package/dist/gen/flowersec/direct/v1.gen.d.ts

@@ -0,0 +1,21 @@
+/** E2EE cipher suite identifier. */
+export declare enum Suite {
+    /** P-256 + HKDF-SHA256 + AES-256-GCM. */
+    Suite_P256_HKDF_SHA256_AES_256_GCM = 2,
+    /** X25519 + HKDF-SHA256 + AES-256-GCM. */
+    Suite_X25519_HKDF_SHA256_AES_256_GCM = 1
+}
+/** Connection info for direct (no tunnel) WebSocket + E2EE sessions. */
+export interface DirectConnectInfo {
+    /** WebSocket URL of the direct server. */
+    ws_url: string;
+    /** Channel identifier. */
+    channel_id: string;
+    /** Base64url-encoded 32-byte PSK. */
+    e2ee_psk_b64u: string;
+    /** Unix timestamp when the handshake init window expires. */
+    channel_init_expire_at_unix_s: number;
+    /** Default E2EE suite identifier. */
+    default_suite: Suite;
+}
+export declare function assertDirectConnectInfo(v: unknown): DirectConnectInfo;