@floegence/flowersec-core 2.5.4 → 3.0.0

package/dist/v3/transportConstants.d.ts

@@ -0,0 +1,56 @@
+/** Version-bound transport identifiers shared by the v3 production paths. */
+export declare const FLOWERSEC_V3_PROFILE: "flowersec/3";
+export declare const FLOWERSEC_V3_WIRE_PROFILES: Readonly<{
+    readonly direct: "flowersec-direct/3";
+    readonly tunnel: "flowersec-tunnel/3";
+}>;
+export declare const FLOWERSEC_V3_PATHS: Readonly<{
+    readonly websocket: Readonly<{
+        direct: "/flowersec/v3/direct";
+        tunnel: "/flowersec/v3/tunnel";
+    }>;
+    readonly webtransport: Readonly<{
+        direct: "/flowersec/webtransport/v3/direct";
+        tunnel: "/flowersec/webtransport/v3/tunnel";
+    }>;
+}>;
+export declare const FLOWERSEC_V3_WEBSOCKET_SUBPROTOCOLS: Readonly<{
+    readonly direct: "flowersec.direct.v3";
+    readonly tunnel: "flowersec.tunnel.v3";
+}>;
+export declare const FLOWERSEC_V3_ALPN: Readonly<{
+    readonly direct: "flowersec-direct/3";
+    readonly tunnel: "flowersec-tunnel/3";
+}>;
+/** The strings below are the exact v3 inputs to the protocol KDF/MAC helpers. */
+export declare const FLOWERSEC_V3_CRYPTO_LABELS: Readonly<{
+    readonly "session-contract": "flowersec-v3-session-contract\0";
+    readonly candidates: "flowersec-v3-candidates\0";
+    readonly admission: "flowersec-v3-admission\0";
+    readonly "runtime-capability": "flowersec-v3-runtime-capability\0";
+    readonly handshake: "flowersec-v3-handshake\0";
+    readonly "server-finished": "flowersec v3 server finished";
+    readonly "client-finished": "flowersec v3 client finished";
+    readonly "epoch-zero": "flowersec v3 epoch zero";
+    readonly "control-root": "flowersec v3 control root";
+    readonly "stream-root": "flowersec v3 stream root";
+    readonly "setup-root": "flowersec v3 setup root";
+    readonly "rekey-root": "flowersec v3 rekey root";
+    readonly "next-epoch": "flowersec v3 next epoch";
+    readonly stream: "flowersec v3 stream";
+    readonly control: "flowersec v3 control";
+    readonly "record-key": "flowersec v3 record key";
+    readonly nonce: "flowersec v3 nonce";
+    readonly "unreliable-root": "flowersec v3 unreliable root";
+    readonly unreliable: "flowersec v3 unreliable";
+    readonly "unreliable-key": "flowersec v3 unreliable key";
+    readonly "unreliable-nonce": "flowersec v3 unreliable nonce";
+    readonly "unreliable-aad": "flowersec-v3-unreliable";
+    readonly "setup-mac": "flowersec-v3-setup\0";
+    readonly "record-aad": "flowersec-v3-record\0";
+    readonly open: "flowersec-v3-open\0";
+    readonly "acceptor-admissions": "flowersec-v3-acceptor-admissions\0";
+}>;
+export declare function wireProfileForPathV3(path: "direct" | "tunnel"): string;
+export declare function websocketSubprotocolForPathV3(path: "direct" | "tunnel"): string;
+export declare function alpnForPathV3(path: "direct" | "tunnel"): string;

package/dist/v3/transportConstants.js

@@ -0,0 +1,59 @@
+/** Version-bound transport identifiers shared by the v3 production paths. */
+export const FLOWERSEC_V3_PROFILE = "flowersec/3";
+export const FLOWERSEC_V3_WIRE_PROFILES = Object.freeze({
+    direct: "flowersec-direct/3",
+    tunnel: "flowersec-tunnel/3",
+});
+export const FLOWERSEC_V3_PATHS = Object.freeze({
+    websocket: Object.freeze({
+        direct: "/flowersec/v3/direct",
+        tunnel: "/flowersec/v3/tunnel",
+    }),
+    webtransport: Object.freeze({
+        direct: "/flowersec/webtransport/v3/direct",
+        tunnel: "/flowersec/webtransport/v3/tunnel",
+    }),
+});
+export const FLOWERSEC_V3_WEBSOCKET_SUBPROTOCOLS = Object.freeze({
+    direct: "flowersec.direct.v3",
+    tunnel: "flowersec.tunnel.v3",
+});
+export const FLOWERSEC_V3_ALPN = FLOWERSEC_V3_WIRE_PROFILES;
+/** The strings below are the exact v3 inputs to the protocol KDF/MAC helpers. */
+export const FLOWERSEC_V3_CRYPTO_LABELS = Object.freeze({
+    "session-contract": "flowersec-v3-session-contract\0",
+    candidates: "flowersec-v3-candidates\0",
+    admission: "flowersec-v3-admission\0",
+    "runtime-capability": "flowersec-v3-runtime-capability\0",
+    handshake: "flowersec-v3-handshake\0",
+    "server-finished": "flowersec v3 server finished",
+    "client-finished": "flowersec v3 client finished",
+    "epoch-zero": "flowersec v3 epoch zero",
+    "control-root": "flowersec v3 control root",
+    "stream-root": "flowersec v3 stream root",
+    "setup-root": "flowersec v3 setup root",
+    "rekey-root": "flowersec v3 rekey root",
+    "next-epoch": "flowersec v3 next epoch",
+    stream: "flowersec v3 stream",
+    control: "flowersec v3 control",
+    "record-key": "flowersec v3 record key",
+    nonce: "flowersec v3 nonce",
+    "unreliable-root": "flowersec v3 unreliable root",
+    unreliable: "flowersec v3 unreliable",
+    "unreliable-key": "flowersec v3 unreliable key",
+    "unreliable-nonce": "flowersec v3 unreliable nonce",
+    "unreliable-aad": "flowersec-v3-unreliable",
+    "setup-mac": "flowersec-v3-setup\0",
+    "record-aad": "flowersec-v3-record\0",
+    open: "flowersec-v3-open\0",
+    "acceptor-admissions": "flowersec-v3-acceptor-admissions\0",
+});
+export function wireProfileForPathV3(path) {
+    return FLOWERSEC_V3_WIRE_PROFILES[path];
+}
+export function websocketSubprotocolForPathV3(path) {
+    return FLOWERSEC_V3_WEBSOCKET_SUBPROTOCOLS[path];
+}
+export function alpnForPathV3(path) {
+    return FLOWERSEC_V3_ALPN[path];
+}

package/dist/v3/unreliableMessage.d.ts

@@ -0,0 +1,44 @@
+import type { CarrierUnreliableDatagramsV3 } from "./carrier.js";
+import { CipherSuiteV3 } from "./protocol.js";
+import type { DirectionV3 } from "./protocol.js";
+export declare const UNRELIABLE_MESSAGES_FEATURE_V3 = 1;
+export declare const UNRELIABLE_MESSAGE_MAX_PLAINTEXT_BYTES_V3: 976;
+export declare const UNRELIABLE_MESSAGE_WIRE_BYTES_V3: 1024;
+export type InternalUnreliableMessageChannelV3Options = Readonly<{
+    transport: CarrierUnreliableDatagramsV3;
+    suite: CipherSuiteV3;
+    h3: Uint8Array;
+    sendDirection: DirectionV3;
+    receiveDirection: DirectionV3;
+    currentSendEpoch(): Readonly<{
+        epoch: number;
+        epochSecret: Uint8Array;
+    }>;
+    receiveEpochSecret(epoch: number): Uint8Array | undefined;
+    onProtocolFailure(): void;
+    now?: () => number;
+}>;
+export type UnreliableMessageMaterialV3 = Readonly<{
+    unreliableRoot: Uint8Array;
+    materialSecret: Uint8Array;
+    recordKey: Uint8Array;
+    noncePrefix: Uint8Array;
+}>;
+export type SealUnreliableMessageDatagramV3Options = Readonly<{
+    suite: CipherSuiteV3;
+    epochSecret: Uint8Array;
+    h3: Uint8Array;
+    direction: DirectionV3;
+    epoch: number;
+    sequence: bigint;
+    expiresAtUnixMs: bigint;
+    plaintext: Uint8Array;
+}>;
+export type SealedUnreliableMessageDatagramV3 = Readonly<{
+    material: UnreliableMessageMaterialV3;
+    nonce: Uint8Array;
+    header: Uint8Array;
+    aad: Uint8Array;
+    ciphertext: Uint8Array;
+    wire: Uint8Array;
+}>;

package/dist/v3/unreliableMessage.js

@@ -0,0 +1,284 @@
+import { gcm } from "@noble/ciphers/aes.js";
+import { chacha20poly1305 } from "@noble/ciphers/chacha.js";
+import { expand } from "@noble/hashes/hkdf.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { CipherSuiteV3 } from "./protocol.js";
+import { UnreliableMessageError } from "../public/contract.js";
+import { FLOWERSEC_V3_CRYPTO_LABELS } from "./transportConstants.js";
+export const UNRELIABLE_MESSAGES_FEATURE_V3 = 0x00000001;
+export const UNRELIABLE_MESSAGE_MAX_PLAINTEXT_BYTES_V3 = 976;
+export const UNRELIABLE_MESSAGE_WIRE_BYTES_V3 = 1_024;
+const HEADER_BYTES = 32;
+const TAG_BYTES = 16;
+const MIN_CIPHERTEXT_BYTES = TAG_BYTES + 1;
+const MAX_CIPHERTEXT_BYTES = UNRELIABLE_MESSAGE_MAX_PLAINTEXT_BYTES_V3 + TAG_BYTES;
+const MAX_PENDING_SENDS = 64;
+const MAX_UINT32 = 0xffffffff;
+const MAX_UINT64 = (1n << 64n) - 1n;
+const encoder = new TextEncoder();
+/** @internal */ export { UnreliableMessageError } from "../public/contract.js";
+/** @internal */
+export function createInternalUnreliableMessageChannelV3(options) {
+    return new InternalUnreliableMessageChannelV3(options);
+}
+class InternalUnreliableMessageChannelV3 {
+    options;
+    maxMessageSize = UNRELIABLE_MESSAGE_MAX_PLAINTEXT_BYTES_V3;
+    replay = new Map();
+    now;
+    nextSequence = 0n;
+    sendEpoch = -1;
+    pendingSends = 0;
+    constructor(options) {
+        this.options = options;
+        if (options.transport.maxDatagramSize < UNRELIABLE_MESSAGE_WIRE_BYTES_V3 || options.h3.byteLength !== 32) {
+            throw new UnreliableMessageError("operation_failed");
+        }
+        this.now = options.now ?? Date.now;
+    }
+    async send(message, options) {
+        throwIfAborted(options.signal);
+        if (!(message instanceof Uint8Array) || message.byteLength < 1 ||
+            message.byteLength > UNRELIABLE_MESSAGE_MAX_PLAINTEXT_BYTES_V3) {
+            throw new UnreliableMessageError("invalid_message");
+        }
+        const payload = message.slice();
+        const expiresAt = requireFutureExpiry(options.expiresAtUnixMs, this.now());
+        if (expiresAt === undefined)
+            return "dropped_expired";
+        if (this.pendingSends >= MAX_PENDING_SENDS)
+            return "dropped_budget";
+        const roots = this.options.currentSendEpoch();
+        if (roots.epoch !== this.sendEpoch) {
+            this.sendEpoch = roots.epoch;
+            this.nextSequence = 0n;
+        }
+        if (this.nextSequence > MAX_UINT64)
+            throw new UnreliableMessageError("closed");
+        const sequence = this.nextSequence++;
+        const sealed = sealUnreliableMessageDatagramV3({
+            suite: this.options.suite,
+            epochSecret: roots.epochSecret,
+            h3: this.options.h3,
+            direction: this.options.sendDirection,
+            epoch: roots.epoch,
+            sequence,
+            expiresAtUnixMs: BigInt(expiresAt),
+            plaintext: payload,
+        });
+        this.pendingSends++;
+        try {
+            return await this.options.transport.send(sealed.wire, {
+                ...(options.signal === undefined ? {} : { signal: options.signal }),
+                expiresAt,
+            });
+        }
+        catch (error) {
+            if (error instanceof DOMException && error.name === "AbortError")
+                throw error;
+            throw new UnreliableMessageError("operation_failed");
+        }
+        finally {
+            this.pendingSends--;
+        }
+    }
+    async receive(options = {}) {
+        for (;;) {
+            throwIfAborted(options.signal);
+            let wire;
+            try {
+                wire = await this.options.transport.receive(options);
+            }
+            catch (error) {
+                if (isAbortError(error))
+                    throw error;
+                throw new UnreliableMessageError("closed");
+            }
+            if (isPreviousVersionDatagram(wire)) {
+                this.options.onProtocolFailure();
+                throw new UnreliableMessageError("closed");
+            }
+            const decoded = decodeHeader(wire);
+            if (decoded === undefined || decoded.expiresAtUnixMs <= BigInt(Math.floor(this.now())))
+                continue;
+            const epochSecret = this.options.receiveEpochSecret(decoded.epoch);
+            if (epochSecret === undefined)
+                continue;
+            const window = this.replay.get(decoded.epoch) ?? new ReplayWindow();
+            if (window.seen(decoded.sequence))
+                continue;
+            const material = deriveUnreliableMessageMaterialV3(epochSecret, this.options.h3, this.options.receiveDirection, decoded.epoch);
+            const nonce = concat(material.noncePrefix, u64be(decoded.sequence));
+            const aad = labelWith(FLOWERSEC_V3_CRYPTO_LABELS["unreliable-aad"], this.options.h3, byte(this.options.receiveDirection), wire.subarray(0, HEADER_BYTES));
+            let plaintext;
+            try {
+                plaintext = cipher(this.options.suite, material.recordKey, nonce, aad).decrypt(wire.subarray(HEADER_BYTES));
+            }
+            catch {
+                continue;
+            }
+            if (plaintext.byteLength < 1 || plaintext.byteLength > UNRELIABLE_MESSAGE_MAX_PLAINTEXT_BYTES_V3)
+                continue;
+            window.mark(decoded.sequence);
+            this.replay.set(decoded.epoch, window);
+            pruneReplayEpochs(this.replay, decoded.epoch);
+            return plaintext.slice();
+        }
+    }
+}
+function isPreviousVersionDatagram(wire) {
+    if (!(wire instanceof Uint8Array) || wire.byteLength < 5 ||
+        wire[0] !== 0x46 || wire[1] !== 0x53 || wire[2] !== 0x44)
+        return false;
+    return wire[3] === 0x32 || (wire[3] === 0x33 && wire[4] === 2);
+}
+/** @internal */
+export function encodeUnreliableMessageHeaderV3(epoch, sequence, expiresAtUnixMs, ciphertextLength) {
+    if (!isUint32(epoch) || !isUint64(sequence) || !isUint64(expiresAtUnixMs) ||
+        expiresAtUnixMs === 0n || !Number.isInteger(ciphertextLength) ||
+        ciphertextLength < MIN_CIPHERTEXT_BYTES || ciphertextLength > MAX_CIPHERTEXT_BYTES) {
+        throw new Error("invalid FSD3 header");
+    }
+    const header = new Uint8Array(HEADER_BYTES);
+    header.set(encoder.encode("FSD3"));
+    header[4] = 3;
+    header[5] = 0;
+    const view = new DataView(header.buffer);
+    view.setUint16(6, HEADER_BYTES, false);
+    view.setUint32(8, epoch, false);
+    view.setBigUint64(12, sequence, false);
+    view.setBigUint64(20, expiresAtUnixMs, false);
+    view.setUint32(28, ciphertextLength, false);
+    return header;
+}
+function decodeHeader(wire) {
+    if (!(wire instanceof Uint8Array) || wire.byteLength < HEADER_BYTES + TAG_BYTES ||
+        wire.byteLength > UNRELIABLE_MESSAGE_WIRE_BYTES_V3 ||
+        wire[0] !== 0x46 || wire[1] !== 0x53 || wire[2] !== 0x44 || wire[3] !== 0x33 ||
+        wire[4] !== 3 || wire[5] !== 0)
+        return undefined;
+    const view = new DataView(wire.buffer, wire.byteOffset, HEADER_BYTES);
+    if (view.getUint16(6, false) !== HEADER_BYTES || view.getUint32(28, false) !== wire.byteLength - HEADER_BYTES) {
+        return undefined;
+    }
+    const expiresAtUnixMs = view.getBigUint64(20, false);
+    if (expiresAtUnixMs === 0n)
+        return undefined;
+    return {
+        epoch: view.getUint32(8, false),
+        sequence: view.getBigUint64(12, false),
+        expiresAtUnixMs,
+    };
+}
+/** @internal */
+export function deriveUnreliableMessageMaterialV3(epochSecret, h3, direction, epoch) {
+    const unreliableRoot = expand(sha256, epochSecret, labelWith(FLOWERSEC_V3_CRYPTO_LABELS["unreliable-root"]), 32);
+    const materialSecret = expand(sha256, unreliableRoot, labelWith(FLOWERSEC_V3_CRYPTO_LABELS.unreliable, h3, byte(direction), u32be(epoch)), 32);
+    return {
+        unreliableRoot,
+        materialSecret,
+        recordKey: expand(sha256, materialSecret, labelWith(FLOWERSEC_V3_CRYPTO_LABELS["unreliable-key"]), 32),
+        noncePrefix: expand(sha256, materialSecret, labelWith(FLOWERSEC_V3_CRYPTO_LABELS["unreliable-nonce"]), 4),
+    };
+}
+/** @internal */
+export function sealUnreliableMessageDatagramV3(options) {
+    const header = encodeUnreliableMessageHeaderV3(options.epoch, options.sequence, options.expiresAtUnixMs, options.plaintext.byteLength + TAG_BYTES);
+    const material = deriveUnreliableMessageMaterialV3(options.epochSecret, options.h3, options.direction, options.epoch);
+    const nonce = concat(material.noncePrefix, u64be(options.sequence));
+    const aad = labelWith(FLOWERSEC_V3_CRYPTO_LABELS["unreliable-aad"], options.h3, byte(options.direction), header);
+    const ciphertext = cipher(options.suite, material.recordKey, nonce, aad).encrypt(options.plaintext);
+    return {
+        material,
+        nonce,
+        header,
+        aad,
+        ciphertext,
+        wire: concat(header, ciphertext),
+    };
+}
+function cipher(suite, key, nonce, aad) {
+    if (suite === CipherSuiteV3.ChaCha20Poly1305)
+        return chacha20poly1305(key, nonce, aad);
+    if (suite === CipherSuiteV3.AES256GCM)
+        return gcm(key, nonce, aad);
+    throw new UnreliableMessageError("operation_failed");
+}
+class ReplayWindow {
+    highest = -1n;
+    bitmap = 0n;
+    seen(sequence) {
+        if (this.highest < 0n || sequence > this.highest)
+            return false;
+        const distance = this.highest - sequence;
+        return distance >= 64n || (this.bitmap & (1n << distance)) !== 0n;
+    }
+    mark(sequence) {
+        if (this.highest < 0n) {
+            this.highest = sequence;
+            this.bitmap = 1n;
+            return;
+        }
+        if (sequence > this.highest) {
+            const shift = sequence - this.highest;
+            this.bitmap = shift >= 64n ? 1n : ((this.bitmap << shift) | 1n) & ((1n << 64n) - 1n);
+            this.highest = sequence;
+            return;
+        }
+        this.bitmap |= 1n << (this.highest - sequence);
+    }
+}
+function pruneReplayEpochs(windows, current) {
+    for (const epoch of windows.keys()) {
+        if (epoch + 1 < current || epoch > current + 1)
+            windows.delete(epoch);
+    }
+}
+function requireFutureExpiry(value, now) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new UnreliableMessageError("invalid_message");
+    return value <= now ? undefined : value;
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted === true)
+        throw new DOMException("operation aborted", "AbortError");
+}
+function isAbortError(error) {
+    return error instanceof DOMException && error.name === "AbortError" ||
+        error instanceof Error && error.name === "AbortError";
+}
+function labelWith(label, ...parts) {
+    return concat(encoder.encode(label), byte(0), ...parts);
+}
+function concat(...parts) {
+    const out = new Uint8Array(parts.reduce((size, part) => size + part.byteLength, 0));
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.byteLength;
+    }
+    return out;
+}
+function byte(value) {
+    return Uint8Array.of(value);
+}
+function u32be(value) {
+    if (!isUint32(value))
+        throw new Error("invalid FSD3 uint32");
+    const out = new Uint8Array(4);
+    new DataView(out.buffer).setUint32(0, value, false);
+    return out;
+}
+function u64be(value) {
+    if (!isUint64(value))
+        throw new Error("invalid FSD3 uint64");
+    const out = new Uint8Array(8);
+    new DataView(out.buffer).setBigUint64(0, value, false);
+    return out;
+}
+function isUint32(value) {
+    return Number.isInteger(value) && value >= 0 && value <= MAX_UINT32;
+}
+function isUint64(value) {
+    return typeof value === "bigint" && value >= 0n && value <= MAX_UINT64;
+}

package/dist/v3/webSocketCarrier.d.ts

@@ -0,0 +1,31 @@
+import { type CarrierSessionV3 } from "./carrier.js";
+import type { OperationOptionsV3, PathKind } from "./contract.js";
+export type WebSocketBinaryTransportV3 = Readonly<{
+    readBinary(options?: Readonly<{
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }>): Promise<Uint8Array>;
+    writeBinary(data: Uint8Array, options?: OperationOptionsV3): Promise<void>;
+    flush(options?: OperationOptionsV3): Promise<void>;
+    close(): void;
+}>;
+export type WebSocketResourcePolicyV3 = Readonly<{
+    maxConcurrentStreams?: number;
+    maxFrameBytes?: number;
+    preferredWriteBytes?: number;
+    maxStreamWriteQueueBytes?: number;
+    maxStreamReceiveBytes?: number;
+    maxSessionReceiveBytes?: number;
+}>;
+export declare function createWebSocketCarrierSessionV3(transport: WebSocketBinaryTransportV3, options: Readonly<{
+    path: PathKind;
+    client: boolean;
+    inboundBidirectionalStreamCapacity: number;
+    resourcePolicy?: WebSocketResourcePolicyV3;
+}>): CarrierSessionV3;
+export declare function createServerWebSocketCarrierSessionV3(transport: WebSocketBinaryTransportV3, options: Readonly<{
+    path: PathKind;
+    inboundBidirectionalStreamCapacity: number;
+    resourcePolicy?: WebSocketResourcePolicyV3;
+}>): CarrierSessionV3;
+export declare function configureServerWebSocketCarrierRoleV3(carrier: CarrierSessionV3, client: boolean): void;