@floegence/flowersec-core 0.27.0 → 2.0.0

package/dist/controlplane/token.d.ts

@@ -1,33 +0,0 @@
-export declare const TOKEN_PREFIX = "FST2";
-export type TokenPayload = Readonly<{
-    kid: string;
-    aud: string;
-    iss?: string;
-    channel_id: string;
-    role: 1 | 2;
-    token_id: string;
-    init_exp: number;
-    idle_timeout_seconds: number;
-    iat: number;
-    exp: number;
-}>;
-export type ParsedToken = Readonly<{
-    payload: TokenPayload;
-    signed: Uint8Array;
-    signature: Uint8Array;
-}>;
-export type TokenVerifyOptions = Readonly<{
-    nowUnixS?: number;
-    audience?: string;
-    issuer?: string;
-    clockSkewMs?: number;
-}>;
-export type TokenKeyLookup = ReadonlyMap<string, Uint8Array> | ((kid: string) => Uint8Array | undefined);
-export declare class TokenError extends Error {
-    readonly code: string;
-    constructor(code: string, message?: string);
-}
-export declare function signToken(signingSeed: Uint8Array, payload: TokenPayload): string;
-export declare function parseToken(token: string): ParsedToken;
-export declare function verifyToken(token: string, keys: TokenKeyLookup, options?: TokenVerifyOptions): TokenPayload;
-export declare function equalSignedTokenPart(left: string, right: string): boolean;

package/dist/controlplane/token.js

@@ -1,119 +0,0 @@
-import { ed25519 } from "@noble/curves/ed25519";
-import { base64urlDecode, base64urlEncode } from "../utils/base64url.js";
-export const TOKEN_PREFIX = "FST2";
-export class TokenError extends Error {
-    code;
-    constructor(code, message = code) {
-        super(message);
-        this.code = code;
-        this.name = "TokenError";
-    }
-}
-export function signToken(signingSeed, payload) {
-    if (signingSeed.length !== 32)
-        throw new TokenError("invalid_signing_key");
-    const normalized = normalizePayload(payload, true);
-    const payloadJSON = new TextEncoder().encode(JSON.stringify(normalized));
-    const signedText = `${TOKEN_PREFIX}.${base64urlEncode(payloadJSON)}`;
-    const signature = ed25519.sign(new TextEncoder().encode(signedText), signingSeed);
-    return `${signedText}.${base64urlEncode(signature)}`;
-}
-export function parseToken(token) {
-    const parts = token.split(".");
-    if (parts.length !== 3 || parts[0] !== TOKEN_PREFIX)
-        throw new TokenError("invalid_format");
-    try {
-        const payload = JSON.parse(new TextDecoder().decode(base64urlDecode(parts[1])));
-        return {
-            payload,
-            signed: new TextEncoder().encode(`${TOKEN_PREFIX}.${parts[1]}`),
-            signature: base64urlDecode(parts[2]),
-        };
-    }
-    catch (error) {
-        if (error instanceof SyntaxError)
-            throw new TokenError("invalid_json");
-        throw new TokenError("invalid_base64url");
-    }
-}
-export function verifyToken(token, keys, options = {}) {
-    const parsed = parseToken(token);
-    const payload = normalizePayload(parsed.payload, false);
-    const publicKey = typeof keys === "function" ? keys(payload.kid) : keys.get(payload.kid);
-    if (publicKey == null)
-        throw new TokenError("unknown_kid");
-    if (publicKey.length !== 32 || parsed.signature.length !== 64 || !ed25519.verify(parsed.signature, parsed.signed, publicKey)) {
-        throw new TokenError("invalid_signature");
-    }
-    if (options.audience !== undefined && !constantTimeTextEqual(payload.aud, options.audience))
-        throw new TokenError("invalid_audience");
-    if (options.issuer !== undefined && !constantTimeTextEqual(payload.iss ?? "", options.issuer))
-        throw new TokenError("invalid_issuer");
-    const skewMs = options.clockSkewMs ?? 0;
-    if (!Number.isFinite(skewMs) || skewMs < 0)
-        throw new TokenError("invalid_clock_skew");
-    const skewSeconds = Math.ceil(skewMs / 1000);
-    const now = options.nowUnixS ?? Math.floor(Date.now() / 1000);
-    if (!Number.isSafeInteger(now))
-        throw new TokenError("invalid_time");
-    if (payload.iat > now + skewSeconds)
-        throw new TokenError("iat_in_future");
-    if (payload.init_exp < now - skewSeconds)
-        throw new TokenError("init_expired");
-    if (payload.exp < now - skewSeconds)
-        throw new TokenError("expired");
-    return payload;
-}
-export function equalSignedTokenPart(left, right) {
-    const leftPart = left.lastIndexOf(".");
-    const rightPart = right.lastIndexOf(".");
-    if (leftPart <= 0 || rightPart <= 0)
-        return false;
-    return constantTimeTextEqual(left.slice(0, leftPart), right.slice(0, rightPart));
-}
-function normalizePayload(input, signing) {
-    const kid = String(input?.kid ?? "").trim();
-    const aud = String(input?.aud ?? "").trim();
-    const iss = String(input?.iss ?? "").trim();
-    const channelId = String(input?.channel_id ?? "").trim();
-    const tokenId = String(input?.token_id ?? "").trim();
-    if (kid === "" || tokenId === "" || (signing && aud === ""))
-        throw new TokenError("invalid_format");
-    if (channelId === "" || new TextEncoder().encode(channelId).length > 256)
-        throw new TokenError("invalid_format");
-    if (input.role !== 1 && input.role !== 2)
-        throw new TokenError("invalid_format");
-    for (const [name, value] of [["init_exp", input.init_exp], ["iat", input.iat], ["exp", input.exp], ["idle_timeout_seconds", input.idle_timeout_seconds]]) {
-        if (!Number.isSafeInteger(value))
-            throw new TokenError("invalid_format", `invalid ${name}`);
-    }
-    if (input.idle_timeout_seconds <= 0)
-        throw new TokenError("invalid_idle_timeout");
-    if (signing && (input.init_exp <= 0 || input.iat <= 0 || input.exp <= 0))
-        throw new TokenError("invalid_format");
-    if (input.exp > input.init_exp)
-        throw new TokenError("exp_after_init");
-    if (input.iat > input.exp)
-        throw new TokenError("invalid_format");
-    return {
-        kid,
-        aud,
-        ...(iss === "" ? {} : { iss }),
-        channel_id: channelId,
-        role: input.role,
-        token_id: tokenId,
-        init_exp: input.init_exp,
-        idle_timeout_seconds: input.idle_timeout_seconds,
-        iat: input.iat,
-        exp: input.exp,
-    };
-}
-function constantTimeTextEqual(left, right) {
-    const a = new TextEncoder().encode(left);
-    const b = new TextEncoder().encode(right);
-    let diff = a.length ^ b.length;
-    const length = Math.max(a.length, b.length);
-    for (let index = 0; index < length; index++)
-        diff |= (a[index] ?? 0) ^ (b[index] ?? 0);
-    return diff === 0;
-}

package/dist/direct-client/connect.d.ts

@@ -1,9 +0,0 @@
-import { type ConnectOptionsBase } from "../client-connect/connectCore.js";
-import type { ClientInternal } from "../client.js";
-export type DirectConnectOptions = ConnectOptionsBase & Readonly<{
-    /** Type-only marker to prevent mixing direct and tunnel option types. */
-    __mode?: "direct";
-    /** Reserved for tunnel connects; forbidden for direct connects. */
-    endpointInstanceId?: never;
-}>;
-export declare function connectDirect(info: unknown, opts: DirectConnectOptions): Promise<ClientInternal>;

package/dist/direct-client/connect.js

@@ -1,90 +0,0 @@
-import { assertDirectConnectInfo } from "../gen/flowersec/direct/v1.gen.js";
-import { FlowersecError } from "../utils/errors.js";
-import { connectCore } from "../client-connect/connectCore.js";
-import { assertDirectConnectContract, assertValidPSK, prepareChannelId } from "../client-connect/contract.js";
-function isRecord(v) {
-    return typeof v === "object" && v != null && !Array.isArray(v);
-}
-function hasOwn(o, key) {
-    return Object.prototype.hasOwnProperty.call(o, key);
-}
-// connectDirect connects to a direct websocket endpoint and returns an RPC-ready session.
-export async function connectDirect(info, opts) {
-    const endpointInstanceId = opts?.endpointInstanceId;
-    if (endpointInstanceId != null) {
-        throw new FlowersecError({
-            stage: "validate",
-            code: "invalid_option",
-            path: "direct",
-            message: "endpointInstanceId is only valid for tunnel connects",
-        });
-    }
-    if (info == null) {
-        throw new FlowersecError({ stage: "validate", code: "missing_connect_info", path: "direct", message: "missing connect info" });
-    }
-    if (isRecord(info)) {
-        // Align missing/invalid field codes with Go: missing fields map to specific stable codes.
-        const okTypes = (!hasOwn(info, "ws_url") || typeof info["ws_url"] === "string") &&
-            (!hasOwn(info, "channel_id") || typeof info["channel_id"] === "string") &&
-            (!hasOwn(info, "channel_init_expire_at_unix_s") ||
-                (typeof info["channel_init_expire_at_unix_s"] === "number" && Number.isSafeInteger(info["channel_init_expire_at_unix_s"]))) &&
-            (!hasOwn(info, "e2ee_psk_b64u") || typeof info["e2ee_psk_b64u"] === "string") &&
-            (!hasOwn(info, "default_suite") || (typeof info["default_suite"] === "number" && Number.isSafeInteger(info["default_suite"])));
-        if (okTypes) {
-            if (!hasOwn(info, "ws_url")) {
-                throw new FlowersecError({ stage: "validate", code: "missing_ws_url", path: "direct", message: "missing ws_url" });
-            }
-            if (!hasOwn(info, "channel_id")) {
-                throw new FlowersecError({ stage: "validate", code: "missing_channel_id", path: "direct", message: "missing channel_id" });
-            }
-            if (!hasOwn(info, "channel_init_expire_at_unix_s")) {
-                throw new FlowersecError({
-                    stage: "validate",
-                    code: "missing_init_exp",
-                    path: "direct",
-                    message: "missing channel_init_expire_at_unix_s",
-                });
-            }
-            if (!hasOwn(info, "e2ee_psk_b64u")) {
-                throw new FlowersecError({ stage: "validate", code: "invalid_psk", path: "direct", message: "missing e2ee_psk_b64u" });
-            }
-            if (!hasOwn(info, "default_suite")) {
-                throw new FlowersecError({ stage: "validate", code: "invalid_suite", path: "direct", message: "missing default_suite" });
-            }
-        }
-        const suite = info["default_suite"];
-        // Keep "invalid_suite" as the stable error code even when the IDL validator rejects the enum value.
-        if (typeof suite === "number" && Number.isSafeInteger(suite) && suite !== 1 && suite !== 2) {
-            throw new FlowersecError({ stage: "validate", code: "invalid_suite", path: "direct", message: "invalid suite" });
-        }
-    }
-    let ready;
-    try {
-        ready = assertDirectConnectInfo(info);
-    }
-    catch (e) {
-        throw new FlowersecError({ stage: "validate", code: "invalid_input", path: "direct", message: "invalid DirectConnectInfo", cause: e });
-    }
-    if (ready.ws_url === "") {
-        throw new FlowersecError({ stage: "validate", code: "missing_ws_url", path: "direct", message: "missing ws_url" });
-    }
-    const channelId = prepareChannelId(ready.channel_id, "direct");
-    if (ready.channel_init_expire_at_unix_s <= 0) {
-        throw new FlowersecError({
-            stage: "validate",
-            code: "missing_init_exp",
-            path: "direct",
-            message: "missing channel_init_expire_at_unix_s",
-        });
-    }
-    assertDirectConnectContract(ready);
-    assertValidPSK(ready.e2ee_psk_b64u, "direct");
-    return await connectCore({
-        path: "direct",
-        wsUrl: ready.ws_url,
-        channelId,
-        e2eePskB64u: ready.e2ee_psk_b64u,
-        defaultSuite: ready.default_suite,
-        opts,
-    });
-}

package/dist/direct-client/index.d.ts

@@ -1 +0,0 @@
-export * from "./connect.js";

package/dist/direct-client/index.js

@@ -1 +0,0 @@
-export * from "./connect.js";

package/dist/e2ee/constants.d.ts

@@ -1,9 +0,0 @@
-export declare const HANDSHAKE_MAGIC = "FSEH";
-export declare const RECORD_MAGIC = "FSEC";
-export declare const PROTOCOL_VERSION: 1;
-export declare const HANDSHAKE_TYPE_INIT: 1;
-export declare const HANDSHAKE_TYPE_RESP: 2;
-export declare const HANDSHAKE_TYPE_ACK: 3;
-export declare const RECORD_FLAG_APP: 0;
-export declare const RECORD_FLAG_PING: 1;
-export declare const RECORD_FLAG_REKEY: 2;

package/dist/e2ee/constants.js

@@ -1,18 +0,0 @@
-// Handshake header prefix.
-export const HANDSHAKE_MAGIC = "FSEH";
-// Record header prefix.
-export const RECORD_MAGIC = "FSEC";
-// Wire-format version for E2EE framing.
-export const PROTOCOL_VERSION = 1;
-// Client->server init.
-export const HANDSHAKE_TYPE_INIT = 1;
-// Server response with ephemeral key and nonce.
-export const HANDSHAKE_TYPE_RESP = 2;
-// Client ack with auth tag.
-export const HANDSHAKE_TYPE_ACK = 3;
-// Application payload record.
-export const RECORD_FLAG_APP = 0;
-// Keepalive record.
-export const RECORD_FLAG_PING = 1;
-// Rekey record.
-export const RECORD_FLAG_REKEY = 2;

package/dist/e2ee/errors.d.ts

@@ -1,5 +0,0 @@
-export type E2EEHandshakeErrorCode = "auth_tag_mismatch" | "invalid_suite" | "invalid_version" | "timestamp_after_init_exp" | "timestamp_out_of_skew";
-export declare class E2EEHandshakeError extends Error {
-    readonly code: E2EEHandshakeErrorCode;
-    constructor(code: E2EEHandshakeErrorCode, message: string);
-}

package/dist/e2ee/errors.js

@@ -1,8 +0,0 @@
-export class E2EEHandshakeError extends Error {
-    code;
-    constructor(code, message) {
-        super(message);
-        this.name = "E2EEHandshakeError";
-        this.code = code;
-    }
-}

package/dist/e2ee/framing.d.ts

@@ -1,12 +0,0 @@
-export declare const HANDSHAKE_HEADER_LEN: number;
-export declare const RECORD_HEADER_LEN: number;
-export declare class FramingError extends Error {
-}
-export declare function encodeHandshakeFrame(handshakeType: number, payloadJsonUtf8: Uint8Array): Uint8Array;
-export declare function decodeHandshakeFrame(frame: Uint8Array, maxPayloadBytes: number): {
-    handshakeType: number;
-    payloadJsonUtf8: Uint8Array;
-};
-export declare function looksLikeRecordFrame(frame: Uint8Array, maxCiphertextBytes: number): boolean;
-export declare function encodeU64beBigint(n: bigint): Uint8Array;
-export declare function decodeU64beBigint(buf: Uint8Array, off: number): bigint;

package/dist/e2ee/framing.js

@@ -1,57 +0,0 @@
-import { concatBytes, readU32be, readU64be, u32be, u64be } from "../utils/bin.js";
-import { HANDSHAKE_MAGIC, PROTOCOL_VERSION, RECORD_MAGIC } from "./constants.js";
-const te = new TextEncoder();
-const td = new TextDecoder();
-// Handshake header byte size: magic + version + type + length.
-export const HANDSHAKE_HEADER_LEN = 4 + 1 + 1 + 4;
-// Record header byte size: magic + version + flags + seq + length.
-export const RECORD_HEADER_LEN = 4 + 1 + 1 + 8 + 4;
-// FramingError marks malformed or truncated frames.
-export class FramingError extends Error {
-}
-// encodeHandshakeFrame builds the handshake header plus JSON payload.
-export function encodeHandshakeFrame(handshakeType, payloadJsonUtf8) {
-    const header = new Uint8Array(HANDSHAKE_HEADER_LEN);
-    header.set(te.encode(HANDSHAKE_MAGIC), 0);
-    header[4] = PROTOCOL_VERSION;
-    header[5] = handshakeType & 0xff;
-    header.set(u32be(payloadJsonUtf8.length), 6);
-    return concatBytes([header, payloadJsonUtf8]);
-}
-// decodeHandshakeFrame validates the handshake header and extracts the payload.
-export function decodeHandshakeFrame(frame, maxPayloadBytes) {
-    if (frame.length < HANDSHAKE_HEADER_LEN)
-        throw new FramingError("handshake frame too short");
-    if (td.decode(frame.slice(0, 4)) !== HANDSHAKE_MAGIC)
-        throw new FramingError("bad handshake magic");
-    if (frame[4] !== PROTOCOL_VERSION)
-        throw new FramingError("bad handshake version");
-    const handshakeType = frame[5];
-    const n = readU32be(frame, 6);
-    if (maxPayloadBytes > 0 && n > maxPayloadBytes)
-        throw new FramingError("handshake payload too large");
-    if (HANDSHAKE_HEADER_LEN + n !== frame.length)
-        throw new FramingError("handshake length mismatch");
-    return { handshakeType, payloadJsonUtf8: frame.slice(HANDSHAKE_HEADER_LEN) };
-}
-// looksLikeRecordFrame checks whether a frame matches the record header shape.
-export function looksLikeRecordFrame(frame, maxCiphertextBytes) {
-    if (frame.length < RECORD_HEADER_LEN)
-        return false;
-    if (td.decode(frame.slice(0, 4)) !== RECORD_MAGIC)
-        return false;
-    if (frame[4] !== PROTOCOL_VERSION)
-        return false;
-    const n = readU32be(frame, 14);
-    if (maxCiphertextBytes > 0 && n > maxCiphertextBytes)
-        return false;
-    return RECORD_HEADER_LEN + n === frame.length;
-}
-// encodeU64beBigint converts a bigint into an 8-byte big-endian buffer.
-export function encodeU64beBigint(n) {
-    return u64be(n);
-}
-// decodeU64beBigint reads a bigint from an 8-byte big-endian buffer.
-export function decodeU64beBigint(buf, off) {
-    return readU64be(buf, off);
-}

package/dist/e2ee/handshake.d.ts

@@ -1,88 +0,0 @@
-import type { E2EE_Init } from "../gen/flowersec/e2ee/v1.gen.js";
-import { SecureChannel, type BinaryTransport } from "./secureChannel.js";
-export type Suite = 1 | 2;
-export type HandshakeClientOptions = Readonly<{
-    /** Channel identifier shared with the server. */
-    channelId: string;
-    /** Cipher suite selection (see Suite). */
-    suite: Suite;
-    /** 32-byte pre-shared key for authenticating the handshake. */
-    psk: Uint8Array;
-    /** Client feature bitset advertised during handshake. */
-    clientFeatures: number;
-    /** Maximum allowed bytes for a handshake JSON payload. */
-    maxHandshakePayload: number;
-    /** Maximum record size for encrypted frames after handshake. */
-    maxRecordBytes: number;
-    /** Preferred plaintext bytes per outbound record. */
-    outboundRecordChunkBytes?: number;
-    /** Maximum queued inbound plaintext bytes for the secure channel. */
-    maxBufferedBytes?: number;
-    /** Maximum queued outbound plaintext bytes for the secure channel. */
-    maxOutboundBufferedBytes?: number;
-    /** Optional AbortSignal to cancel the handshake. */
-    signal?: AbortSignal;
-    /** Optional total handshake timeout in milliseconds (>= 0; 0 disables). */
-    timeoutMs?: number;
-}>;
-export type HandshakeServerOptions = Readonly<{
-    /** Channel identifier expected from the client. */
-    channelId: string;
-    /** Cipher suite selection (see Suite). */
-    suite: Suite;
-    /** 32-byte pre-shared key for authenticating the handshake. */
-    psk: Uint8Array;
-    /** Server feature bitset advertised during handshake. */
-    serverFeatures: number;
-    /** Absolute expiry (Unix seconds) for the init message. */
-    initExpireAtUnixS: number;
-    /** Allowed clock skew (seconds) for timestamp validation. */
-    clockSkewSeconds: number;
-    /** Maximum allowed bytes for a handshake JSON payload. */
-    maxHandshakePayload: number;
-    /** Maximum record size for encrypted frames after handshake. */
-    maxRecordBytes: number;
-    /** Preferred plaintext bytes per outbound record. */
-    outboundRecordChunkBytes?: number;
-    /** Maximum queued inbound plaintext bytes for the secure channel. */
-    maxBufferedBytes?: number;
-    /** Maximum queued outbound plaintext bytes for the secure channel. */
-    maxOutboundBufferedBytes?: number;
-    /** Optional AbortSignal to cancel the handshake. */
-    signal?: AbortSignal;
-    /** Optional total handshake timeout in milliseconds (>= 0; 0 disables). */
-    timeoutMs?: number;
-}>;
-export declare function clientHandshake(transport: BinaryTransport, opts: HandshakeClientOptions): Promise<SecureChannel>;
-type ServerCacheEntry = {
-    /** Stable fingerprint of the init message for retries. */
-    initKey: string;
-    /** Suite used for this cached handshake. */
-    suite: Suite;
-    /** Server ephemeral private key for ECDH. */
-    serverPriv: Uint8Array;
-    /** Server ephemeral public key bytes. */
-    serverPub: Uint8Array;
-    /** Server nonce (32 bytes). */
-    nonceS: Uint8Array;
-    /** Handshake identifier returned to the client. */
-    handshakeId: string;
-    /** Server feature bitset from this handshake. */
-    serverFeatures: number;
-    /** Cache insert time (ms since epoch) for TTL eviction. */
-    createdAtMs: number;
-};
-export declare class ServerHandshakeCache {
-    private readonly m;
-    private readonly ttlMs;
-    private readonly maxEntries;
-    constructor(opts?: Readonly<{
-        ttlMs?: number;
-        maxEntries?: number;
-    }>);
-    private cleanup;
-    getOrCreate(init: E2EE_Init, suite: Suite, serverFeatures: number): ServerCacheEntry;
-    delete(init: E2EE_Init): void;
-}
-export declare function serverHandshake(transport: BinaryTransport, cache: ServerHandshakeCache, opts: HandshakeServerOptions): Promise<SecureChannel>;
-export {};