@floegence/flowersec-core 0.1.1

package/dist/streamhello/streamHello.js

@@ -0,0 +1,13 @@
+import { readJsonFrame, writeJsonFrame } from "../rpc/framing.js";
+// writeStreamHello sends the initial stream greeting.
+export async function writeStreamHello(write, kind) {
+    const h = { kind, v: 1 };
+    await writeJsonFrame(write, h);
+}
+// readStreamHello reads and validates the stream greeting.
+export async function readStreamHello(readExactly) {
+    const h = (await readJsonFrame(readExactly, 8 * 1024));
+    if (h.v !== 1 || typeof h.kind !== "string" || h.kind.length === 0)
+        throw new Error("bad StreamHello");
+    return h;
+}

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

@@ -0,0 +1,7 @@
+import { type ConnectOptionsBase } from "../client-connect/connectCore.js";
+import type { ClientInternal } from "../client.js";
+export type TunnelConnectOptions = ConnectOptionsBase & Readonly<{
+    /** Optional caller-provided endpoint instance ID (base64url). */
+    endpointInstanceId?: string;
+}>;
+export declare function connectTunnel(grant: unknown, opts: TunnelConnectOptions): Promise<ClientInternal>;

package/dist/tunnel-client/connect.js

@@ -0,0 +1,125 @@
+import { Role as TunnelRole } from "../gen/flowersec/tunnel/v1.gen.js";
+import { assertChannelInitGrant, Role as ControlRole } from "../gen/flowersec/controlplane/v1.gen.js";
+import { base64urlDecode, base64urlEncode } from "../utils/base64url.js";
+import { FlowersecError } from "../utils/errors.js";
+import { randomBytes } from "../client-connect/common.js";
+import { connectCore } from "../client-connect/connectCore.js";
+function isRecord(v) {
+    return typeof v === "object" && v != null && !Array.isArray(v);
+}
+function unwrapGrant(v) {
+    if (v == null || typeof v !== "object")
+        return v;
+    const o = v;
+    if (o["grant_client"] != null)
+        return o["grant_client"];
+    if (o["grant_server"] != null)
+        return o["grant_server"];
+    return v;
+}
+// connectTunnel attaches to a tunnel and returns an RPC-ready session.
+export async function connectTunnel(grant, opts) {
+    const input = unwrapGrant(grant);
+    if (input == null) {
+        throw new FlowersecError({ stage: "validate", code: "missing_grant", path: "tunnel", message: "missing grant" });
+    }
+    if (isRecord(input)) {
+        const suite = input["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: "tunnel", message: "invalid suite" });
+        }
+        const allowed = input["allowed_suites"];
+        if (Array.isArray(allowed)) {
+            for (const v of allowed) {
+                if (typeof v === "number" && Number.isSafeInteger(v) && v !== 1 && v !== 2) {
+                    throw new FlowersecError({ stage: "validate", code: "invalid_suite", path: "tunnel", message: "invalid suite" });
+                }
+            }
+        }
+    }
+    let checkedGrant;
+    try {
+        checkedGrant = assertChannelInitGrant(input);
+    }
+    catch (e) {
+        throw new FlowersecError({ stage: "validate", code: "invalid_input", path: "tunnel", message: "invalid ChannelInitGrant", cause: e });
+    }
+    if (checkedGrant.tunnel_url === "") {
+        throw new FlowersecError({ stage: "validate", code: "missing_tunnel_url", path: "tunnel", message: "missing tunnel_url" });
+    }
+    if (checkedGrant.channel_id === "") {
+        throw new FlowersecError({ stage: "validate", code: "missing_channel_id", path: "tunnel", message: "missing channel_id" });
+    }
+    if (checkedGrant.token === "") {
+        throw new FlowersecError({ stage: "validate", code: "missing_token", path: "tunnel", message: "missing token" });
+    }
+    if (checkedGrant.channel_init_expire_at_unix_s <= 0) {
+        throw new FlowersecError({
+            stage: "validate",
+            code: "missing_init_exp",
+            path: "tunnel",
+            message: "missing channel_init_expire_at_unix_s",
+        });
+    }
+    try {
+        const psk = base64urlDecode(checkedGrant.e2ee_psk_b64u);
+        if (psk.length !== 32) {
+            throw new Error("psk must be 32 bytes");
+        }
+    }
+    catch (e) {
+        throw new FlowersecError({ stage: "validate", code: "invalid_psk", path: "tunnel", message: "invalid e2ee_psk_b64u", cause: e });
+    }
+    const idleTimeoutSeconds = checkedGrant.idle_timeout_seconds;
+    if (checkedGrant.role !== ControlRole.Role_client) {
+        throw new FlowersecError({ stage: "validate", code: "role_mismatch", path: "tunnel", message: "expected role=client" });
+    }
+    const endpointInstanceId = opts.endpointInstanceId ?? base64urlEncode(randomBytes(24));
+    let eidBytes;
+    try {
+        eidBytes = base64urlDecode(endpointInstanceId);
+    }
+    catch (e) {
+        throw new FlowersecError({
+            stage: "validate",
+            code: "invalid_endpoint_instance_id",
+            path: "tunnel",
+            message: "invalid endpointInstanceId",
+            cause: e
+        });
+    }
+    if (eidBytes.length < 16 || eidBytes.length > 32) {
+        throw new FlowersecError({
+            stage: "validate",
+            code: "invalid_endpoint_instance_id",
+            path: "tunnel",
+            message: "endpointInstanceId must decode to 16..32 bytes"
+        });
+    }
+    const attach = {
+        v: 1,
+        channel_id: checkedGrant.channel_id,
+        role: TunnelRole.Role_client,
+        token: checkedGrant.token,
+        endpoint_instance_id: endpointInstanceId
+    };
+    const attachJson = JSON.stringify(attach);
+    const keepaliveIntervalMs = opts.keepaliveIntervalMs !== undefined ? Math.max(0, opts.keepaliveIntervalMs) : defaultKeepaliveIntervalMs(idleTimeoutSeconds);
+    return await connectCore({
+        path: "tunnel",
+        wsUrl: checkedGrant.tunnel_url,
+        channelId: checkedGrant.channel_id,
+        e2eePskB64u: checkedGrant.e2ee_psk_b64u,
+        defaultSuite: checkedGrant.default_suite,
+        opts: { ...opts, keepaliveIntervalMs },
+        attach: { attachJson, endpointInstanceId }
+    });
+}
+function defaultKeepaliveIntervalMs(idleTimeoutSeconds) {
+    if (!Number.isFinite(idleTimeoutSeconds) || idleTimeoutSeconds <= 0)
+        return 0;
+    const idleMs = idleTimeoutSeconds * 1000;
+    const half = Math.floor(idleMs / 2);
+    return Math.max(500, half);
+}

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

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

package/dist/tunnel-client/index.js

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

package/dist/utils/base64url.d.ts

@@ -0,0 +1,2 @@
+export declare function base64urlEncode(bytes: Uint8Array): string;
+export declare function base64urlDecode(s: string): Uint8Array;

package/dist/utils/base64url.js

@@ -0,0 +1,40 @@
+// base64urlEncode encodes bytes without padding.
+export function base64urlEncode(bytes) {
+    let b64;
+    if (typeof Buffer !== "undefined") {
+        b64 = Buffer.from(bytes).toString("base64");
+    }
+    else {
+        let binary = "";
+        for (let i = 0; i < bytes.length; i++)
+            binary += String.fromCharCode(bytes[i]);
+        b64 = btoa(binary);
+    }
+    return b64.replace(/=/g, "").replace(/\+/g, "-").replace(/\//g, "_");
+}
+// base64urlDecode decodes base64url without padding.
+export function base64urlDecode(s) {
+    // Be strict: Node's Buffer base64 decoder is permissive (it may ignore invalid characters).
+    if (!/^[A-Za-z0-9_-]*$/.test(s))
+        throw new Error("invalid base64url");
+    // base64/base64url length cannot be 1 mod 4.
+    if (s.length % 4 === 1)
+        throw new Error("invalid base64url length");
+    const normalized = s.replace(/-/g, "+").replace(/_/g, "/");
+    const padLen = (4 - (normalized.length % 4)) % 4;
+    const padded = normalized + "=".repeat(padLen);
+    if (typeof Buffer !== "undefined") {
+        const out = new Uint8Array(Buffer.from(padded, "base64"));
+        // Roundtrip validation makes invalid inputs fail fast and deterministically.
+        if (base64urlEncode(out) !== s)
+            throw new Error("invalid base64url");
+        return out;
+    }
+    const binary = atob(padded);
+    const out = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        out[i] = binary.charCodeAt(i);
+    if (base64urlEncode(out) !== s)
+        throw new Error("invalid base64url");
+    return out;
+}

package/dist/utils/bin.d.ts

@@ -0,0 +1,6 @@
+export declare function u16be(n: number): Uint8Array;
+export declare function u32be(n: number): Uint8Array;
+export declare function u64be(n: bigint): Uint8Array;
+export declare function readU32be(buf: Uint8Array, off: number): number;
+export declare function readU64be(buf: Uint8Array, off: number): bigint;
+export declare function concatBytes(chunks: readonly Uint8Array[]): Uint8Array;

package/dist/utils/bin.js

@@ -0,0 +1,55 @@
+// u16be encodes a number into 2 bytes big-endian.
+export function u16be(n) {
+    const b = new Uint8Array(2);
+    const v = n >>> 0;
+    b[0] = (v >>> 8) & 0xff;
+    b[1] = v & 0xff;
+    return b;
+}
+// u32be encodes a number into 4 bytes big-endian.
+export function u32be(n) {
+    const b = new Uint8Array(4);
+    const v = n >>> 0;
+    b[0] = (v >>> 24) & 0xff;
+    b[1] = (v >>> 16) & 0xff;
+    b[2] = (v >>> 8) & 0xff;
+    b[3] = v & 0xff;
+    return b;
+}
+// u64be encodes a bigint into 8 bytes big-endian.
+export function u64be(n) {
+    const b = new Uint8Array(8);
+    let v = n;
+    for (let i = 7; i >= 0; i--) {
+        b[i] = Number(v & 0xffn);
+        v >>= 8n;
+    }
+    return b;
+}
+// readU32be reads a 4-byte big-endian number.
+export function readU32be(buf, off) {
+    return ((buf[off] << 24) |
+        (buf[off + 1] << 16) |
+        (buf[off + 2] << 8) |
+        buf[off + 3]) >>> 0;
+}
+// readU64be reads an 8-byte big-endian bigint.
+export function readU64be(buf, off) {
+    let v = 0n;
+    for (let i = 0; i < 8; i++)
+        v = (v << 8n) | BigInt(buf[off + i]);
+    return v;
+}
+// concatBytes concatenates buffers into a single Uint8Array.
+export function concatBytes(chunks) {
+    let total = 0;
+    for (const c of chunks)
+        total += c.length;
+    const out = new Uint8Array(total);
+    let off = 0;
+    for (const c of chunks) {
+        out.set(c, off);
+        off += c.length;
+    }
+    return out;
+}

package/dist/utils/errors.d.ts

@@ -0,0 +1,26 @@
+export declare class TimeoutError extends Error {
+    constructor(message?: string);
+}
+export declare class AbortError extends Error {
+    constructor(message?: string);
+}
+export type FlowersecPath = "auto" | "tunnel" | "direct";
+export type FlowersecStage = "validate" | "connect" | "attach" | "handshake" | "secure" | "yamux" | "rpc" | "close";
+export type FlowersecErrorCode = "timeout" | "canceled" | "invalid_version" | "invalid_input" | "invalid_option" | "invalid_endpoint_instance_id" | "invalid_psk" | "invalid_suite" | "missing_grant" | "missing_connect_info" | "missing_conn" | "missing_handler" | "missing_stream_kind" | "role_mismatch" | "missing_tunnel_url" | "missing_ws_url" | "missing_origin" | "missing_channel_id" | "missing_token" | "missing_init_exp" | "timestamp_after_init_exp" | "timestamp_out_of_skew" | "auth_tag_mismatch" | "resolve_failed" | "random_failed" | "upgrade_failed" | "dial_failed" | "attach_failed" | "too_many_connections" | "expected_attach" | "invalid_attach" | "invalid_token" | "channel_mismatch" | "token_replay" | "replace_rate_limited" | "handshake_failed" | "ping_failed" | "mux_failed" | "accept_stream_failed" | "open_stream_failed" | "stream_hello_failed" | "not_connected";
+export declare class FlowersecError extends Error {
+    readonly code: FlowersecErrorCode;
+    readonly stage: FlowersecStage;
+    readonly path: FlowersecPath;
+    readonly cause?: unknown;
+    constructor(args: Readonly<{
+        code: FlowersecErrorCode;
+        stage: FlowersecStage;
+        path: FlowersecPath;
+        message?: string;
+        cause?: unknown;
+    }>);
+}
+export declare function isTimeoutError(e: unknown): e is TimeoutError;
+export declare function isAbortError(e: unknown): e is AbortError;
+export declare function isFlowersecError(e: unknown): e is FlowersecError;
+export declare function throwIfAborted(signal?: AbortSignal, message?: string): void;

package/dist/utils/errors.js

@@ -0,0 +1,42 @@
+export class TimeoutError extends Error {
+    constructor(message = "timeout") {
+        super(message);
+        this.name = "TimeoutError";
+    }
+}
+export class AbortError extends Error {
+    constructor(message = "aborted") {
+        super(message);
+        this.name = "AbortError";
+    }
+}
+export class FlowersecError extends Error {
+    code;
+    stage;
+    path;
+    cause;
+    constructor(args) {
+        const prefix = `${args.path} ${args.stage} (${args.code})`;
+        const message = args.message != null && args.message !== "" ? `${prefix}: ${args.message}` : prefix;
+        super(message, args.cause !== undefined ? { cause: args.cause } : undefined);
+        this.name = "FlowersecError";
+        this.code = args.code;
+        this.stage = args.stage;
+        this.path = args.path;
+        if (args.cause !== undefined)
+            this.cause = args.cause;
+    }
+}
+export function isTimeoutError(e) {
+    return e instanceof TimeoutError;
+}
+export function isAbortError(e) {
+    return e instanceof AbortError;
+}
+export function isFlowersecError(e) {
+    return e instanceof FlowersecError;
+}
+export function throwIfAborted(signal, message) {
+    if (signal?.aborted)
+        throw new AbortError(message);
+}

package/dist/utils/number.d.ts

@@ -0,0 +1,2 @@
+export declare function isSafeU64Number(v: unknown): v is number;
+export declare function isSafeU32Number(v: unknown): v is number;

package/dist/utils/number.js

@@ -0,0 +1,9 @@
+// isSafeU64Number checks whether v is a JSON number that can safely represent a u64 in JS.
+// Values must be integers in [0, Number.MAX_SAFE_INTEGER].
+export function isSafeU64Number(v) {
+    return typeof v === "number" && Number.isSafeInteger(v) && v >= 0 && v <= Number.MAX_SAFE_INTEGER;
+}
+// isSafeU32Number checks whether v is a JSON number that can safely represent a u32 in JS.
+export function isSafeU32Number(v) {
+    return typeof v === "number" && Number.isSafeInteger(v) && v >= 0 && v <= 0xffffffff;
+}

package/dist/ws/index.d.ts

@@ -0,0 +1 @@
+export * from "../ws-client/binaryTransport.js";

package/dist/ws/index.js

@@ -0,0 +1 @@
+export * from "../ws-client/binaryTransport.js";

package/dist/ws-client/binaryTransport.d.ts

@@ -0,0 +1,49 @@
+import { type ClientObserverLike } from "../observability/observer.js";
+export declare class WsCloseError extends Error {
+    readonly code: number | undefined;
+    readonly reason: string | undefined;
+    constructor(code?: number, reason?: string);
+}
+export type WebSocketLike = {
+    binaryType: string;
+    readyState: number;
+    send(data: string | ArrayBuffer | Uint8Array): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: "open" | "message" | "error" | "close", listener: (ev: any) => void): void;
+    removeEventListener(type: "open" | "message" | "error" | "close", listener: (ev: any) => void): void;
+};
+export declare class WebSocketBinaryTransport {
+    private readonly ws;
+    private readonly observer;
+    private readonly queue;
+    private queueHead;
+    private queueBytes;
+    private readonly maxQueuedBytes;
+    private waiters;
+    private waitersHead;
+    private waitersSettled;
+    private messageChain;
+    private error;
+    private localCloseRequested;
+    constructor(ws: WebSocketLike, opts?: Readonly<{
+        maxQueuedBytes?: number;
+        observer?: ClientObserverLike;
+    }>);
+    readBinary(opts?: Readonly<{
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }>): Promise<Uint8Array>;
+    writeBinary(frame: Uint8Array, opts?: Readonly<{
+        signal?: AbortSignal;
+    }>): Promise<void>;
+    close(): void;
+    private handleMessage;
+    private readonly onMessage;
+    private readonly onError;
+    private readonly onClose;
+    private push;
+    private shiftQueue;
+    private shiftWaiter;
+    private compactWaitersMaybe;
+    private fail;
+}