@floegence/flowersec-core 0.1.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Floegence, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,42 @@
+# @floegence/flowersec-core
+
+Flowersec core TypeScript library for building an end-to-end encrypted, multiplexed connection over WebSocket (browser-friendly).
+
+Status: experimental; not audited.
+
+## Install
+
+```bash
+npm install @floegence/flowersec-core
+```
+
+## Usage
+
+Browser (recommended):
+
+```ts
+import { connectBrowser } from "@floegence/flowersec-core/browser";
+
+const grant = await fetch("/api/flowersec/channel/init", { method: "POST" }).then((r) => r.json());
+const client = await connectBrowser(grant);
+await client.ping();
+client.close();
+```
+
+Node.js (recommended):
+
+```ts
+import { connectNode } from "@floegence/flowersec-core/node";
+
+const grant = await fetch("https://your-app.example/api/flowersec/channel/init", { method: "POST" }).then((r) => r.json());
+const client = await connectNode(grant, { origin: "https://your-app.example" });
+await client.ping();
+client.close();
+```
+
+## Docs
+
+- Frontend quickstart: `docs/FRONTEND_QUICKSTART.md`
+- Integration guide: `docs/INTEGRATION_GUIDE.md`
+- API surface contract: `docs/API_SURFACE.md`
+- Error model: `docs/ERROR_MODEL.md`

package/YAMUX_ALIGNMENT.md

@@ -0,0 +1,127 @@
+# TS Yamux Alignment Status
+
+This repository contains a TypeScript implementation of the Yamux protocol in `flowersec-ts/src/yamux/`.
+It is designed to be interoperable with HashiCorp's Yamux (protocol version `0`) for the subset of
+features required by Flowersec: multiplexing multiple logical byte streams over a single encrypted
+transport.
+
+## What “aligned” means here
+
+“Aligned” in this document means:
+
+- **Wire compatibility**: our frames can be understood by `github.com/hashicorp/yamux` and vice versa.
+- **Behavioral compatibility (subset)**: stream open/accept, data transfer, and basic flow control work
+  correctly when interoperating with HashiCorp Yamux.
+- **Not a full spec clone**: some Yamux behaviors are intentionally simplified or currently unimplemented.
+
+## Implemented protocol surface (TS)
+
+Source: `flowersec-ts/src/yamux/constants.ts`, `flowersec-ts/src/yamux/header.ts`, `flowersec-ts/src/yamux/session.ts`, `flowersec-ts/src/yamux/stream.ts`.
+
+### Header & framing
+
+- 12-byte header (`HEADER_LEN=12`) with:
+  - `version: u8`
+  - `type: u8`
+  - `flags: u16` (big-endian)
+  - `stream_id: u32` (big-endian)
+  - `length: u32` (big-endian)
+- Supported `version`: `0` (`YAMUX_VERSION=0`).
+- Unknown `type` or invalid `version` causes session close (strict).
+
+### Frame types & flags
+
+- Types: `DATA(0)`, `WINDOW_UPDATE(1)`, `PING(2)`, `GO_AWAY(3)` (`flowersec-ts/src/yamux/constants.ts`).
+- Flags: `SYN(1)`, `ACK(2)`, `FIN(4)`, `RST(8)`.
+
+### Stream IDs
+
+- Client opens **odd** stream IDs, server opens **even** stream IDs:
+  - `opts.client=true` starts at `1`, step `+2`
+  - `opts.client=false` starts at `2`, step `+2`
+  - (`flowersec-ts/src/yamux/session.ts`)
+
+### Stream open handshake
+
+- Opening a stream starts by sending a `WINDOW_UPDATE` with `SYN` (length may be `0`).
+- Peer creates the stream when it receives `SYN` on either `DATA` or `WINDOW_UPDATE`.
+- The peer responds with a `WINDOW_UPDATE` carrying `ACK`, moving both sides into “established”.
+
+### Flow control (per-stream windows)
+
+- Default per-stream max window: `256 KiB` (`DEFAULT_MAX_STREAM_WINDOW=256*1024`).
+- Each stream maintains:
+  - `recvWindow`: decremented by received `DATA` length; receiving beyond window triggers `RST`.
+  - `sendWindow`: incremented by `WINDOW_UPDATE` deltas; writing waits if `sendWindow<=0`.
+- `WINDOW_UPDATE` generation strategy:
+  - Always send for SYN/ACK transitions.
+  - Otherwise, send when replenishment delta reaches at least half the max window.
+
+### FIN/RST semantics
+
+- Local close sends a `WINDOW_UPDATE` with `FIN`.
+- Receiving `FIN` transitions the stream to a closed-ish state and unblocks pending reads.
+- `RST` is sent as `WINDOW_UPDATE` with `RST` (and length `0`) and terminates the stream.
+- If a frame references an unknown stream **without** `SYN`, TS sends `RST`.
+
+### PING / GO_AWAY behavior
+
+- PING:
+  - If `SYN` is set, TS replies with `ACK` and the same opaque `length`.
+  - TS does not currently initiate pings or track RTT.
+- GO_AWAY:
+  - Any `GO_AWAY` immediately closes the session (no reason code handling).
+
+## Interop evidence (what is actually tested today)
+
+The TS Yamux implementation is exercised in real interop scenarios:
+
+- **TS client ↔ Go server (minimal Yamux over TCP)**:
+  - Test: `flowersec-ts/src/e2e/yamux_interop.test.ts` (minimal tcp mode)
+  - Go harness: `flowersec-go/internal/cmd/flowersec-yamux-harness/main.go`
+  - Covers: window update race, RST handling, concurrent open/close, session close.
+  - Notes: opt-in via `YAMUX_INTEROP=1` (runs Go harnesses).
+  - Notes: sizes scale via `YAMUX_INTEROP_SCALE` (e.g. `2` => 20 streams / 1 MiB per stream).
+  - Notes: client-initiated RST scenarios run when `YAMUX_INTEROP_CLIENT_RST=1`.
+  - Notes: window-update and concurrent-open/close stress runs when `YAMUX_INTEROP_STRESS=1`.
+- **TS client ↔ Go server (full chain: E2EE + tunnel + Yamux)**:
+  - Test: `flowersec-ts/src/e2e/yamux_interop.test.ts` (full chain mode)
+  - Go harness: `flowersec-go/internal/cmd/flowersec-e2e-harness/main.go` with `-scenario`
+  - Notes: reduced stream counts/payload sizes to keep end-to-end runtime bounded.
+- **Layered close/reset probes (memory + WS + full chain)**:
+  - Test: `flowersec-ts/src/e2e/yamux_interop_layers.test.ts`
+  - Covers: session-close wakeup, FIN/RST delivery across SecureChannel + WebSocketBinaryTransport,
+    and a full-chain FIN/RST probe on `rst_mid_write_go`.
+  - Notes: gated by `YAMUX_INTEROP=1`; the full-chain probe additionally requires
+    `YAMUX_INTEROP_DEBUG=1`.
+- **TS client ↔ Go server (RPC happy path)**:
+  - Test: `flowersec-ts/src/e2e/go_integration.test.ts`
+  - Go harness: `flowersec-go/internal/cmd/flowersec-e2e-harness/main.go`
+  - Covers: single-stream RPC framing and basic window updates.
+
+These confirm wire-level interop and the correctness of the happy-path subset under real IO.
+
+## Current gaps (not yet proven or intentionally simplified)
+
+These items are either untested or simplified compared to HashiCorp Yamux behavior:
+
+- **Multi-stream concurrency**: covered by interop tests, but fairness/priority under heavy contention
+  is not proven.
+- **Large payload / fragmentation**: covered up to ~1 MiB per stream; larger payloads and pathological
+  fragmentation are still untested.
+- **Stress & fuzz robustness**: no fuzz tests for invalid headers/flags/lengths and adversarial streams.
+- **Session-level behaviors**: GO_AWAY reason handling, keepalive/heartbeats, and more nuanced shutdown.
+- **Strictness differences**: unknown frame types trigger session close, which may be stricter than some
+  implementations.
+- **Server-initiated streams**: Go-initiated streams are not covered by interop tests yet.
+- **Bidirectional window-update stress**: current window update tests run TS -> Go only.
+
+## Practical alignment summary
+
+- **Aligned (high confidence)**:
+  - Version 0 framing, stream ID parity, open handshake via SYN/ACK, basic DATA transfer, basic window
+    updates, and interop with HashiCorp Yamux server for the Flowersec RPC use-case.
+- **Aligned but under-tested**:
+  - FIN/RST edges, ping handling, and window boundary conditions.
+- **Not aligned / out of scope today**:
+  - Full Yamux feature parity (advanced GO_AWAY semantics, keepalive, exhaustive error handling).

package/dist/_examples/flowersec/demo/v1.facade.gen.d.ts

@@ -0,0 +1,12 @@
+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";
+import { createDemoClient } from "./v1.rpc.gen.js";
+export type DemoSession = Client & Readonly<{
+    demo: ReturnType<typeof createDemoClient>;
+}>;
+export declare function createDemoSession(client: Client): DemoSession;
+export declare function connectDemoTunnel(grant: ChannelInitGrant, opts: TunnelConnectOptions): Promise<DemoSession>;
+export declare function connectDemoDirect(info: DirectConnectInfo, opts: DirectConnectOptions): Promise<DemoSession>;

package/dist/_examples/flowersec/demo/v1.facade.gen.js

@@ -0,0 +1,15 @@
+// Code generated by idlgen. DO NOT EDIT.
+import { connectDirect } from "../../../direct-client/connect.js";
+import { connectTunnel } from "../../../tunnel-client/connect.js";
+import { createDemoClient, } from "./v1.rpc.gen.js";
+export function createDemoSession(client) {
+    return { ...client, demo: createDemoClient(client.rpc) };
+}
+export async function connectDemoTunnel(grant, opts) {
+    const client = await connectTunnel(grant, opts);
+    return createDemoSession(client);
+}
+export async function connectDemoDirect(info, opts) {
+    const client = await connectDirect(info, opts);
+    return createDemoSession(client);
+}

package/dist/_examples/flowersec/demo/v1.gen.d.ts

@@ -0,0 +1,16 @@
+/** Demo hello notification. */
+export interface HelloNotify {
+    /** Hello message. */
+    hello: string;
+}
+/** Demo ping request. */
+export interface PingRequest {
+}
+/** Demo ping response. */
+export interface PingResponse {
+    /** Whether the request succeeded. */
+    ok: boolean;
+}
+export declare function assertHelloNotify(v: unknown): HelloNotify;
+export declare function assertPingRequest(v: unknown): PingRequest;
+export declare function assertPingResponse(v: unknown): PingResponse;

package/dist/_examples/flowersec/demo/v1.gen.js

@@ -0,0 +1,86 @@
+// Code generated by idlgen. DO NOT EDIT.
+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;
+}
+export function assertHelloNotify(v) {
+    if (!isRecord(v))
+        throw new Error("bad HelloNotify");
+    const o = v;
+    if (o["hello"] === undefined)
+        throw new Error("bad HelloNotify.hello");
+    assertString("HelloNotify.hello", o["hello"]);
+    return o;
+}
+export function assertPingRequest(v) {
+    if (!isRecord(v))
+        throw new Error("bad PingRequest");
+    const o = v;
+    return o;
+}
+export function assertPingResponse(v) {
+    if (!isRecord(v))
+        throw new Error("bad PingResponse");
+    const o = v;
+    if (o["ok"] === undefined)
+        throw new Error("bad PingResponse.ok");
+    assertBoolean("PingResponse.ok", o["ok"]);
+    return o;
+}

package/dist/_examples/flowersec/demo/v1.rpc.gen.d.ts

@@ -0,0 +1,11 @@
+import type { RpcCaller } from "../../../rpc/caller.js";
+import { HelloNotify, PingRequest, PingResponse } from "./v1.gen.js";
+/** Demo service used by examples and integration tests. */
+export declare function createDemoClient(rpc: RpcCaller): {
+    /** Hello notification. */
+    onHello: (handler: (v: HelloNotify) => void) => () => void;
+    /** Ping request/response. */
+    ping: (req: PingRequest, opts?: Readonly<{
+        signal?: AbortSignal;
+    }>) => Promise<PingResponse>;
+};

package/dist/_examples/flowersec/demo/v1.rpc.gen.js

@@ -0,0 +1,22 @@
+// Code generated by idlgen. DO NOT EDIT.
+import { RpcCallError } from "../../../rpc/callError.js";
+import { assertHelloNotify, assertPingRequest, assertPingResponse, } from "./v1.gen.js";
+/** Demo service used by examples and integration tests. */
+export function createDemoClient(rpc) {
+    return {
+        /** Hello notification. */
+        onHello: (handler) => {
+            return rpc.onNotify(2, (payload) => {
+                handler(assertHelloNotify(payload));
+            });
+        },
+        /** Ping request/response. */
+        ping: async (req, opts = {}) => {
+            const checkedReq = assertPingRequest(req);
+            const resp = await rpc.call(1, checkedReq, opts.signal);
+            if (resp.error != null)
+                throw new RpcCallError(resp.error.code, resp.error.message, 1);
+            return assertPingResponse(resp.payload);
+        },
+    };
+}

package/dist/browser/connect.d.ts

@@ -0,0 +1,12 @@
+import type { Client } from "../client.js";
+import type { DirectConnectOptions } from "../direct-client/connect.js";
+import type { TunnelConnectOptions } from "../tunnel-client/connect.js";
+import { type ConnectOptions } from "../facade.js";
+import type { ChannelInitGrant } from "../gen/flowersec/controlplane/v1.gen.js";
+import type { DirectConnectInfo } from "../gen/flowersec/direct/v1.gen.js";
+export type TunnelConnectBrowserOptions = Omit<TunnelConnectOptions, "origin" | "wsFactory">;
+export type DirectConnectBrowserOptions = Omit<DirectConnectOptions, "origin" | "wsFactory">;
+export type ConnectBrowserOptions = Omit<ConnectOptions, "origin" | "wsFactory">;
+export declare function connectBrowser(input: unknown, opts?: ConnectBrowserOptions): Promise<Client>;
+export declare function connectTunnelBrowser(grant: ChannelInitGrant, opts?: TunnelConnectBrowserOptions): Promise<Client>;
+export declare function connectDirectBrowser(info: DirectConnectInfo, opts?: DirectConnectBrowserOptions): Promise<Client>;

package/dist/browser/connect.js

@@ -0,0 +1,31 @@
+import { connectDirect } from "../direct-client/connect.js";
+import { connectTunnel } from "../tunnel-client/connect.js";
+import { connect } from "../facade.js";
+import { FlowersecError } from "../utils/errors.js";
+function getBrowserOrigin() {
+    if (typeof window === "undefined")
+        return "";
+    const o = window?.location?.origin;
+    return typeof o === "string" ? o : "";
+}
+export async function connectBrowser(input, opts = {}) {
+    const origin = getBrowserOrigin();
+    if (origin === "") {
+        throw new FlowersecError({ stage: "validate", code: "missing_origin", path: "auto", message: "missing browser origin" });
+    }
+    return await connect(input, { ...opts, origin });
+}
+export async function connectTunnelBrowser(grant, opts = {}) {
+    const origin = getBrowserOrigin();
+    if (origin === "") {
+        throw new FlowersecError({ stage: "validate", code: "missing_origin", path: "tunnel", message: "missing browser origin" });
+    }
+    return await connectTunnel(grant, { ...opts, origin });
+}
+export async function connectDirectBrowser(info, opts = {}) {
+    const origin = getBrowserOrigin();
+    if (origin === "") {
+        throw new FlowersecError({ stage: "validate", code: "missing_origin", path: "direct", message: "missing browser origin" });
+    }
+    return await connectDirect(info, { ...opts, origin });
+}

package/dist/browser/index.d.ts

@@ -0,0 +1,2 @@
+export type { ConnectBrowserOptions, DirectConnectBrowserOptions, TunnelConnectBrowserOptions } from "./connect.js";
+export { connectBrowser, connectDirectBrowser, connectTunnelBrowser } from "./connect.js";

package/dist/browser/index.js

@@ -0,0 +1 @@
+export { connectBrowser, connectDirectBrowser, connectTunnelBrowser } from "./connect.js";

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

@@ -0,0 +1,26 @@
+import type { WebSocketLike } from "../ws-client/binaryTransport.js";
+export declare class OriginMismatchError extends Error {
+    readonly expected: string;
+    readonly got: string;
+    constructor(expected: string, got: string);
+}
+export declare class WsFactoryRequiredError extends Error {
+    constructor();
+}
+export declare function createWebSocket(url: string, origin: string, wsFactory: ((url: string, origin: string) => WebSocketLike) | undefined): WebSocketLike;
+export declare function classifyConnectError(err: unknown): "websocket_error" | "websocket_closed" | "timeout" | "canceled";
+export declare function classifyHandshakeError(err: unknown): "auth_tag_mismatch" | "handshake_failed" | "invalid_version" | "timestamp_after_init_exp" | "timestamp_out_of_skew" | "timeout" | "canceled";
+export declare function withAbortAndTimeout<T>(p: Promise<T>, opts: Readonly<{
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    onCancel?: () => void;
+}>): Promise<T>;
+export declare function waitOpen(ws: WebSocketLike, opts?: Readonly<{
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}>): Promise<void>;
+export declare function randomBytes(n: number): Uint8Array;
+export declare function ioReadOpts(signal: AbortSignal | undefined, timeoutMs: number | undefined): {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+};

package/dist/client-connect/common.js

@@ -0,0 +1,167 @@
+import { AbortError, TimeoutError, isAbortError, isTimeoutError, throwIfAborted } from "../utils/errors.js";
+import { E2EEHandshakeError } from "../e2ee/errors.js";
+class WebSocketClosedError extends Error {
+    constructor() {
+        super("websocket closed");
+        this.name = "WebSocketClosedError";
+    }
+}
+class WebSocketOpenError extends Error {
+    constructor() {
+        super("websocket error");
+        this.name = "WebSocketOpenError";
+    }
+}
+export class OriginMismatchError extends Error {
+    expected;
+    got;
+    constructor(expected, got) {
+        super(`origin mismatch: expected ${expected}, got ${got}`);
+        this.name = "OriginMismatchError";
+        this.expected = expected;
+        this.got = got;
+    }
+}
+export class WsFactoryRequiredError extends Error {
+    constructor() {
+        super("wsFactory is required outside the browser to set the Origin header (use connectTunnelNode/connectDirectNode or createNodeWsFactory from @floegence/flowersec-core/node)");
+        this.name = "WsFactoryRequiredError";
+    }
+}
+function defaultWebSocketFactory(url) {
+    return new WebSocket(url);
+}
+function isBrowserEnv() {
+    return typeof window !== "undefined" && typeof window.location !== "undefined" && typeof window.location.origin === "string";
+}
+export function createWebSocket(url, origin, wsFactory) {
+    if (wsFactory != null)
+        return wsFactory(url, origin);
+    if (isBrowserEnv()) {
+        if (window.location.origin !== origin)
+            throw new OriginMismatchError(origin, window.location.origin);
+        return defaultWebSocketFactory(url);
+    }
+    throw new WsFactoryRequiredError();
+}
+export function classifyConnectError(err) {
+    if (isTimeoutError(err))
+        return "timeout";
+    if (isAbortError(err))
+        return "canceled";
+    if (err instanceof WebSocketClosedError)
+        return "websocket_closed";
+    return "websocket_error";
+}
+export function classifyHandshakeError(err) {
+    if (isTimeoutError(err))
+        return "timeout";
+    if (isAbortError(err))
+        return "canceled";
+    if (err instanceof E2EEHandshakeError)
+        return err.code;
+    return "handshake_failed";
+}
+export async function withAbortAndTimeout(p, opts) {
+    if (opts.signal?.aborted) {
+        opts.onCancel?.();
+        throw new AbortError("canceled");
+    }
+    const timeoutMs = Math.max(0, opts.timeoutMs ?? 0);
+    if (timeoutMs <= 0 && opts.signal == null)
+        return await p;
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        const cleanup = () => {
+            settled = true;
+            if (timer != null)
+                clearTimeout(timer);
+            opts.signal?.removeEventListener("abort", onAbort);
+        };
+        const finish = (fn) => {
+            if (settled)
+                return;
+            cleanup();
+            fn();
+        };
+        const onAbort = () => {
+            opts.onCancel?.();
+            finish(() => reject(new AbortError("canceled")));
+        };
+        const timer = timeoutMs > 0
+            ? setTimeout(() => {
+                opts.onCancel?.();
+                finish(() => reject(new TimeoutError("timeout")));
+            }, timeoutMs)
+            : undefined;
+        opts.signal?.addEventListener("abort", onAbort);
+        p.then((v) => finish(() => resolve(v)), (e) => finish(() => reject(e)));
+    });
+}
+// waitOpen resolves when the websocket opens or rejects on error/close.
+export function waitOpen(ws, opts = {}) {
+    return new Promise((resolve, reject) => {
+        if (opts.signal?.aborted) {
+            reject(new AbortError("connect aborted"));
+            return;
+        }
+        const onOpen = () => {
+            cleanup();
+            resolve();
+        };
+        const onErr = () => {
+            cleanup();
+            reject(new WebSocketOpenError());
+        };
+        const onClose = () => {
+            cleanup();
+            reject(new WebSocketClosedError());
+        };
+        const onAbort = () => {
+            cleanup();
+            try {
+                ws.close();
+            }
+            catch {
+                // ignore
+            }
+            reject(new AbortError("connect aborted"));
+        };
+        const timeoutMs = Math.max(0, opts.timeoutMs ?? 0);
+        const timer = timeoutMs > 0
+            ? setTimeout(() => {
+                cleanup();
+                try {
+                    ws.close();
+                }
+                catch {
+                    // ignore
+                }
+                reject(new TimeoutError("connect timeout"));
+            }, timeoutMs)
+            : undefined;
+        const cleanup = () => {
+            if (timer != null)
+                clearTimeout(timer);
+            ws.removeEventListener("open", onOpen);
+            ws.removeEventListener("error", onErr);
+            ws.removeEventListener("close", onClose);
+            opts.signal?.removeEventListener("abort", onAbort);
+        };
+        ws.addEventListener("open", onOpen);
+        ws.addEventListener("error", onErr);
+        ws.addEventListener("close", onClose);
+        opts.signal?.addEventListener("abort", onAbort);
+    });
+}
+// randomBytes uses the Web Crypto API for nonces and IDs.
+export function randomBytes(n) {
+    const out = new Uint8Array(n);
+    crypto.getRandomValues(out);
+    return out;
+}
+export function ioReadOpts(signal, timeoutMs) {
+    throwIfAborted(signal, "operation aborted");
+    const ms = timeoutMs == null ? undefined : Math.max(0, timeoutMs);
+    return signal != null ? { signal, ...(ms !== undefined ? { timeoutMs: ms } : {}) } : ms !== undefined ? { timeoutMs: ms } : {};
+}

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

@@ -0,0 +1,42 @@
+import { type ClientObserverLike } from "../observability/observer.js";
+import { type WebSocketLike } from "../ws-client/binaryTransport.js";
+import type { ClientInternal } from "../client.js";
+export type ConnectOptionsBase = Readonly<{
+    /** Explicit Origin value (required). In browsers this must match window.location.origin. */
+    origin: string;
+    /** Optional AbortSignal to cancel connect/handshake. */
+    signal?: AbortSignal;
+    /** Optional websocket connect timeout in milliseconds (0 disables). */
+    connectTimeoutMs?: number;
+    /** Optional total E2EE handshake timeout in milliseconds (0 disables). */
+    handshakeTimeoutMs?: number;
+    /** Feature bitset advertised during the E2EE handshake. */
+    clientFeatures?: number;
+    /** Maximum allowed bytes for handshake payloads (0 uses default). */
+    maxHandshakePayload?: number;
+    /** Maximum encrypted record size on the wire (0 uses default). */
+    maxRecordBytes?: number;
+    /** Maximum buffered plaintext bytes in the secure channel (0 uses default). */
+    maxBufferedBytes?: number;
+    /** Maximum queued websocket bytes before backpressure (0 uses default). */
+    maxWsQueuedBytes?: number;
+    /** Optional factory for creating the WebSocket instance. */
+    wsFactory?: (url: string, origin: string) => WebSocketLike;
+    /** Optional observer for client metrics. */
+    observer?: ClientObserverLike;
+    /** Encrypted keepalive ping interval in milliseconds (0 disables). */
+    keepaliveIntervalMs?: number;
+}>;
+export type ConnectCoreArgs = Readonly<{
+    path: "tunnel" | "direct";
+    wsUrl: string;
+    channelId: string;
+    e2eePskB64u: string;
+    defaultSuite: number;
+    opts: ConnectOptionsBase;
+    attach?: Readonly<{
+        attachJson: string;
+        endpointInstanceId: string;
+    }>;
+}>;
+export declare function connectCore(args: ConnectCoreArgs): Promise<ClientInternal>;