@floegence/flowersec-core 0.21.1 → 0.22.1

package/dist/controlplane/token.js

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

@@ -0,0 +1,46 @@
+export declare const SDK_DEFAULTS: Readonly<{
+    transport: Readonly<{
+        connectTimeoutMs: 10000;
+        handshakeTimeoutMs: 10000;
+        handshakeClockSkewMs: 30000;
+    }>;
+    e2ee: Readonly<{
+        maxHandshakePayloadBytes: number;
+        maxRecordBytes: number;
+        outboundRecordChunkBytes: number;
+        maxOutboundBufferedBytes: number;
+    }>;
+    yamux: Readonly<{
+        maxActiveStreams: 64;
+        maxInboundStreams: 32;
+        maxFrameBytes: number;
+        preferredOutboundFrameBytes: number;
+        maxStreamReceiveBytes: number;
+        maxSessionReceiveBytes: number;
+    }>;
+    rpc: Readonly<{
+        maxJsonFrameBytes: number;
+        maxConcurrentRequests: 32;
+        maxQueuedRequests: 128;
+        maxQueuedNotifications: 128;
+    }>;
+    controlplane: Readonly<{
+        maxRequestBodyBytes: number;
+        maxResponseBodyBytes: number;
+    }>;
+    proxy: Readonly<{
+        maxJsonFrameBytes: number;
+        maxChunkBytes: number;
+        maxBodyBytes: number;
+        maxWsFrameBytes: number;
+        defaultTimeoutMs: 30000;
+        maxTimeoutMs: 300000;
+    }>;
+    reconnect: Readonly<{
+        maxAttempts: 5;
+        initialDelayMs: 500;
+        maxDelayMs: 10000;
+        factor: 1.8;
+        jitterRatio: 0.2;
+    }>;
+}>;

package/dist/defaults.js

@@ -0,0 +1,46 @@
+export const SDK_DEFAULTS = Object.freeze({
+    transport: Object.freeze({
+        connectTimeoutMs: 10_000,
+        handshakeTimeoutMs: 10_000,
+        handshakeClockSkewMs: 30_000,
+    }),
+    e2ee: Object.freeze({
+        maxHandshakePayloadBytes: 8 * 1024,
+        maxRecordBytes: 1024 * 1024,
+        outboundRecordChunkBytes: 64 * 1024,
+        maxOutboundBufferedBytes: 4 * 1024 * 1024,
+    }),
+    yamux: Object.freeze({
+        maxActiveStreams: 64,
+        maxInboundStreams: 32,
+        maxFrameBytes: 256 * 1024,
+        preferredOutboundFrameBytes: 64 * 1024,
+        maxStreamReceiveBytes: 256 * 1024,
+        maxSessionReceiveBytes: 16 * 1024 * 1024,
+    }),
+    rpc: Object.freeze({
+        maxJsonFrameBytes: 1024 * 1024,
+        maxConcurrentRequests: 32,
+        maxQueuedRequests: 128,
+        maxQueuedNotifications: 128,
+    }),
+    controlplane: Object.freeze({
+        maxRequestBodyBytes: 32 * 1024,
+        maxResponseBodyBytes: 1024 * 1024,
+    }),
+    proxy: Object.freeze({
+        maxJsonFrameBytes: 1024 * 1024,
+        maxChunkBytes: 256 * 1024,
+        maxBodyBytes: 64 * 1024 * 1024,
+        maxWsFrameBytes: 1024 * 1024,
+        defaultTimeoutMs: 30_000,
+        maxTimeoutMs: 300_000,
+    }),
+    reconnect: Object.freeze({
+        maxAttempts: 5,
+        initialDelayMs: 500,
+        maxDelayMs: 10_000,
+        factor: 1.8,
+        jitterRatio: 0.2,
+    }),
+});

package/dist/endpoint/index.d.ts

@@ -0,0 +1,83 @@
+import { type TransportSecurityPolicy } from "../client-connect/transportSecurity.js";
+import { serverHandshake, ServerHandshakeCache, type Suite } from "../e2ee/handshake.js";
+import { type YamuxLimits } from "../yamux/session.js";
+import type { YamuxStream } from "../yamux/stream.js";
+import { type RpcRouter, type RpcServerOptions } from "../rpc/server.js";
+import { type WebSocketLike, type WebSocketLimits } from "../ws-client/binaryTransport.js";
+export type { Suite } from "../e2ee/handshake.js";
+export type EndpointPath = "direct" | "tunnel";
+export type DirectHandshakeInit = Readonly<{
+    channelId: string;
+    version: number;
+    suite: Suite;
+    clientFeatures: number;
+}>;
+export type DirectHandshakeCredential = Readonly<{
+    psk: Uint8Array | string;
+    initExpireAtUnixS: number;
+    commitAuthenticated?: () => void | Promise<void>;
+}>;
+export type DirectCredentialResolver = (init: DirectHandshakeInit) => DirectHandshakeCredential | Promise<DirectHandshakeCredential>;
+export type EndpointOptions = Readonly<{
+    signal?: AbortSignal;
+    handshakeTimeoutMs?: number;
+    handshakeClockSkewMs?: number;
+    serverFeatures?: number;
+    maxHandshakePayload?: number;
+    maxRecordBytes?: number;
+    maxBufferedBytes?: number;
+    maxOutboundBufferedBytes?: number;
+    outboundRecordChunkBytes?: number;
+    webSocketLimits?: Partial<WebSocketLimits>;
+    yamuxLimits?: Partial<YamuxLimits>;
+    handshakeCache?: ServerHandshakeCache;
+}>;
+export type DirectAcceptOptions = EndpointOptions & Readonly<{
+    secureTransport?: boolean;
+    transportSecurityPolicy?: TransportSecurityPolicy;
+}>;
+export type TunnelEndpointOptions = EndpointOptions & Readonly<{
+    origin: string;
+    connectTimeoutMs?: number;
+    endpointInstanceId?: string;
+    wsFactory: (url: string, origin: string) => WebSocketLike;
+    transportSecurityPolicy?: TransportSecurityPolicy;
+}>;
+export type EndpointStream = Readonly<{
+    kind: string;
+    stream: YamuxStream;
+}>;
+export declare class Session {
+    private readonly secure;
+    private readonly mux;
+    readonly path: EndpointPath;
+    readonly endpointInstanceId: string | undefined;
+    private readonly streams;
+    private readonly waiters;
+    private terminalError;
+    private constructor();
+    static create(path: EndpointPath, secure: Awaited<ReturnType<typeof serverHandshake>>, options?: Readonly<{
+        yamuxLimits?: Partial<YamuxLimits>;
+        endpointInstanceId?: string;
+    }>): Session;
+    openStream(kind: string, options?: Readonly<{
+        signal?: AbortSignal;
+    }>): Promise<YamuxStream>;
+    acceptStream(options?: Readonly<{
+        signal?: AbortSignal;
+    }>): Promise<EndpointStream>;
+    serveRPC(router: RpcRouter, options?: RpcServerOptions & Readonly<{
+        signal?: AbortSignal;
+    }>): Promise<void>;
+    probeLiveness(timeoutMs?: 10000): Promise<number>;
+    close(): void;
+    private pushStream;
+    private acceptRawStream;
+    private fail;
+}
+export declare function acceptDirect(websocket: WebSocketLike, handshake: Readonly<{
+    channelId: string;
+    suite: Suite;
+}> & DirectHandshakeCredential, options?: DirectAcceptOptions): Promise<Session>;
+export declare function acceptDirectResolved(websocket: WebSocketLike, resolver: DirectCredentialResolver, options?: DirectAcceptOptions): Promise<Session>;
+export declare function connectTunnel(grantInput: unknown, options: TunnelEndpointOptions): Promise<Session>;

package/dist/endpoint/index.js

@@ -0,0 +1,384 @@
+import { Role as ControlRole, assertChannelInitGrant } from "../gen/flowersec/controlplane/v1.gen.js";
+import { Role as TunnelRole } from "../gen/flowersec/tunnel/v1.gen.js";
+import { assertTunnelGrantContract, assertValidPSK, prepareChannelId } from "../client-connect/contract.js";
+import { enforceTransportSecurity } from "../client-connect/transportSecurity.js";
+import { SDK_DEFAULTS } from "../defaults.js";
+import { serverHandshake, ServerHandshakeCache } from "../e2ee/handshake.js";
+import { decodeHandshakeFrame } from "../e2ee/framing.js";
+import { HANDSHAKE_TYPE_INIT, PROTOCOL_VERSION } from "../e2ee/constants.js";
+import { readStreamHello, writeStreamHello } from "../streamhello/streamHello.js";
+import { ByteReader } from "../yamux/byteReader.js";
+import { YamuxSession } from "../yamux/session.js";
+import { RpcServer } from "../rpc/server.js";
+import { base64urlDecode, base64urlEncode } from "../utils/base64url.js";
+import { AbortError, FlowersecError } from "../utils/errors.js";
+import { WebSocketBinaryTransport } from "../ws-client/binaryTransport.js";
+export class Session {
+    secure;
+    mux;
+    path;
+    endpointInstanceId;
+    streams = [];
+    waiters = [];
+    terminalError;
+    constructor(path, secure, mux, endpointInstanceId) {
+        this.secure = secure;
+        this.mux = mux;
+        this.path = path;
+        this.endpointInstanceId = endpointInstanceId;
+    }
+    static create(path, secure, options = {}) {
+        let session;
+        const mux = new YamuxSession({
+            read: () => secure.read(),
+            write: (bytes) => secure.write(bytes),
+            close: () => secure.close(),
+        }, {
+            client: false,
+            ...(options.yamuxLimits === undefined ? {} : { limits: options.yamuxLimits }),
+            onIncomingStream: (stream) => session.pushStream(stream),
+            onTerminal: (error) => session.fail(error),
+        });
+        session = new Session(path, secure, mux, options.endpointInstanceId);
+        return session;
+    }
+    async openStream(kind, options = {}) {
+        const stream = await this.mux.openStream(options);
+        try {
+            await writeStreamHello((bytes) => stream.write(bytes), normalizeStreamKind(kind, this.path));
+            return stream;
+        }
+        catch (error) {
+            await stream.reset(asError(error));
+            throw new FlowersecError({ path: this.path, stage: "rpc", code: "stream_hello_failed", message: "failed to write stream hello", cause: error });
+        }
+    }
+    async acceptStream(options = {}) {
+        const stream = await this.acceptRawStream(options.signal);
+        try {
+            const reader = new ByteReader(() => stream.read());
+            const hello = await readStreamHello((length) => reader.readExactly(length));
+            return { kind: hello.kind, stream };
+        }
+        catch (error) {
+            await stream.reset(asError(error));
+            throw new FlowersecError({ path: this.path, stage: "rpc", code: "stream_hello_failed", message: "failed to read stream hello", cause: error });
+        }
+    }
+    async serveRPC(router, options = {}) {
+        while (true) {
+            const accepted = await this.acceptStream(options.signal === undefined ? {} : { signal: options.signal });
+            if (accepted.kind !== "rpc") {
+                await accepted.stream.reset(new Error(`unexpected stream kind ${accepted.kind}`));
+                continue;
+            }
+            const reader = new ByteReader(() => accepted.stream.read());
+            const server = new RpcServer({
+                readExactly: (length) => reader.readExactly(length),
+                write: (bytes) => accepted.stream.write(bytes),
+                close: (error) => { void accepted.stream.reset(asError(error)); },
+            }, options, router);
+            await server.serve(options.signal);
+            return;
+        }
+    }
+    probeLiveness(timeoutMs = SDK_DEFAULTS.transport.handshakeTimeoutMs) {
+        return this.mux.probeLiveness(timeoutMs);
+    }
+    close() {
+        this.fail(new Error("endpoint session closed"));
+        this.mux.close();
+        this.secure.close();
+    }
+    pushStream(stream) {
+        const waiter = this.waiters.shift();
+        if (waiter == null) {
+            this.streams.push(stream);
+            return;
+        }
+        cleanupWaiter(waiter);
+        waiter.resolve(stream);
+    }
+    acceptRawStream(signal) {
+        if (signal?.aborted)
+            return Promise.reject(new AbortError("accept stream aborted"));
+        if (this.terminalError != null)
+            return Promise.reject(this.terminalError);
+        const stream = this.streams.shift();
+        if (stream != null)
+            return Promise.resolve(stream);
+        return new Promise((resolve, reject) => {
+            const waiter = { resolve, reject, ...(signal === undefined ? {} : { signal }) };
+            waiter.onAbort = () => {
+                const index = this.waiters.indexOf(waiter);
+                if (index >= 0)
+                    this.waiters.splice(index, 1);
+                cleanupWaiter(waiter);
+                reject(new AbortError("accept stream aborted"));
+            };
+            signal?.addEventListener("abort", waiter.onAbort, { once: true });
+            this.waiters.push(waiter);
+        });
+    }
+    fail(error) {
+        if (this.terminalError != null)
+            return;
+        this.terminalError = error;
+        for (const waiter of this.waiters.splice(0)) {
+            cleanupWaiter(waiter);
+            waiter.reject(error);
+        }
+    }
+}
+export async function acceptDirect(websocket, handshake, options = {}) {
+    await enforceIncomingDirectTransport(options);
+    const transport = new WebSocketBinaryTransport(websocket, webSocketTransportOptions(options));
+    return await establishSession("direct", transport, handshake, options);
+}
+export async function acceptDirectResolved(websocket, resolver, options = {}) {
+    await enforceIncomingDirectTransport(options);
+    const transport = new WebSocketBinaryTransport(websocket, webSocketTransportOptions(options));
+    const first = await transport.readBinary(readOptions(options));
+    let init;
+    try {
+        const decoded = decodeHandshakeFrame(first, options.maxHandshakePayload ?? SDK_DEFAULTS.e2ee.maxHandshakePayloadBytes);
+        if (decoded.handshakeType !== HANDSHAKE_TYPE_INIT)
+            throw new Error("expected handshake init");
+        init = JSON.parse(new TextDecoder().decode(decoded.payloadJsonUtf8));
+        if (init.version !== PROTOCOL_VERSION || init.role !== 1 || (init.suite !== 1 && init.suite !== 2))
+            throw new Error("invalid handshake init");
+    }
+    catch (error) {
+        transport.close();
+        throw new FlowersecError({ path: "direct", stage: "handshake", code: "handshake_failed", message: "invalid handshake init", cause: error });
+    }
+    let credential;
+    try {
+        credential = await resolver({
+            channelId: prepareChannelId(init.channel_id, "direct"),
+            version: init.version,
+            suite: init.suite,
+            clientFeatures: init.client_features >>> 0,
+        });
+    }
+    catch (error) {
+        transport.close();
+        throw new FlowersecError({ path: "direct", stage: "validate", code: "resolve_failed", message: "credential resolution failed", cause: error });
+    }
+    const replay = new PrefetchedTransport(transport, first);
+    return await establishSession("direct", replay, {
+        channelId: init.channel_id,
+        suite: init.suite,
+        ...credential,
+    }, options);
+}
+export async function connectTunnel(grantInput, options) {
+    let grant;
+    try {
+        grant = assertChannelInitGrant(unwrapServerGrant(grantInput));
+    }
+    catch (error) {
+        throw new FlowersecError({ path: "tunnel", stage: "validate", code: "invalid_input", message: "invalid ChannelInitGrant", cause: error });
+    }
+    assertTunnelGrantContract(grant, ControlRole.Role_server);
+    const tunnelUrl = grant.tunnel_url.trim();
+    if (tunnelUrl === "")
+        throw new FlowersecError({ path: "tunnel", stage: "validate", code: "missing_tunnel_url", message: "missing tunnel_url" });
+    if (grant.token.trim() === "")
+        throw new FlowersecError({ path: "tunnel", stage: "validate", code: "missing_token", message: "missing token" });
+    if (grant.channel_init_expire_at_unix_s <= 0)
+        throw new FlowersecError({ path: "tunnel", stage: "validate", code: "missing_init_exp", message: "missing channel init expiry" });
+    const origin = options.origin.trim();
+    if (origin === "")
+        throw new FlowersecError({ path: "tunnel", stage: "validate", code: "missing_origin", message: "missing origin" });
+    await enforceTransportSecurity({ rawUrl: tunnelUrl, path: "tunnel", ...(options.transportSecurityPolicy === undefined ? {} : { policy: options.transportSecurityPolicy }) });
+    const endpointInstanceId = normalizeEndpointInstanceId(options.endpointInstanceId);
+    const websocket = options.wsFactory(tunnelUrl, origin);
+    const transport = new WebSocketBinaryTransport(websocket, webSocketTransportOptions(options));
+    try {
+        await waitForOpen(websocket, options.connectTimeoutMs ?? SDK_DEFAULTS.transport.connectTimeoutMs, options.signal);
+        const attach = {
+            v: 1,
+            channel_id: prepareChannelId(grant.channel_id, "tunnel"),
+            role: TunnelRole.Role_server,
+            token: grant.token.trim(),
+            endpoint_instance_id: endpointInstanceId,
+        };
+        websocket.send(JSON.stringify(attach));
+        return await establishSession("tunnel", transport, {
+            channelId: grant.channel_id,
+            suite: grant.default_suite,
+            psk: assertValidPSK(grant.e2ee_psk_b64u, "tunnel"),
+            initExpireAtUnixS: grant.channel_init_expire_at_unix_s,
+        }, options, endpointInstanceId);
+    }
+    catch (error) {
+        transport.close();
+        if (error instanceof FlowersecError)
+            throw error;
+        throw new FlowersecError({ path: "tunnel", stage: "connect", code: "dial_failed", message: "endpoint tunnel connect failed", cause: error });
+    }
+}
+async function establishSession(path, transport, handshake, options, endpointInstanceId) {
+    let psk;
+    try {
+        psk = normalizePSK(handshake.psk, path);
+    }
+    catch (error) {
+        transport.close();
+        throw error;
+    }
+    try {
+        const secure = await serverHandshake(transport, options.handshakeCache ?? new ServerHandshakeCache(), {
+            channelId: prepareChannelId(handshake.channelId, path),
+            suite: handshake.suite,
+            psk,
+            serverFeatures: options.serverFeatures ?? 0,
+            initExpireAtUnixS: handshake.initExpireAtUnixS,
+            clockSkewSeconds: Math.ceil((options.handshakeClockSkewMs ?? SDK_DEFAULTS.transport.handshakeClockSkewMs) / 1000),
+            maxHandshakePayload: options.maxHandshakePayload ?? SDK_DEFAULTS.e2ee.maxHandshakePayloadBytes,
+            maxRecordBytes: options.maxRecordBytes ?? SDK_DEFAULTS.e2ee.maxRecordBytes,
+            outboundRecordChunkBytes: options.outboundRecordChunkBytes ?? SDK_DEFAULTS.e2ee.outboundRecordChunkBytes,
+            maxBufferedBytes: options.maxBufferedBytes ?? SDK_DEFAULTS.e2ee.maxOutboundBufferedBytes,
+            maxOutboundBufferedBytes: options.maxOutboundBufferedBytes ?? SDK_DEFAULTS.e2ee.maxOutboundBufferedBytes,
+            timeoutMs: options.handshakeTimeoutMs ?? SDK_DEFAULTS.transport.handshakeTimeoutMs,
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+        });
+        try {
+            await handshake.commitAuthenticated?.();
+        }
+        catch (error) {
+            secure.close();
+            throw new FlowersecError({ path, stage: "handshake", code: "credential_commit_failed", message: "credential commit failed", cause: error });
+        }
+        return Session.create(path, secure, {
+            ...(options.yamuxLimits === undefined ? {} : { yamuxLimits: options.yamuxLimits }),
+            ...(endpointInstanceId === undefined ? {} : { endpointInstanceId }),
+        });
+    }
+    catch (error) {
+        transport.close();
+        if (error instanceof FlowersecError)
+            throw error;
+        throw new FlowersecError({ path, stage: "handshake", code: "handshake_failed", message: "endpoint handshake failed", cause: error });
+    }
+    finally {
+        psk.fill(0);
+    }
+}
+class PrefetchedTransport {
+    inner;
+    first;
+    constructor(inner, first) {
+        this.inner = inner;
+        this.first = first;
+    }
+    readBinary(options) {
+        if (this.first != null) {
+            const first = this.first;
+            this.first = undefined;
+            return Promise.resolve(first);
+        }
+        return this.inner.readBinary(options);
+    }
+    writeBinary(frame, options) {
+        return this.inner.writeBinary(frame, options);
+    }
+    close() {
+        this.inner.close();
+    }
+}
+function normalizePSK(input, path) {
+    try {
+        const psk = typeof input === "string" ? base64urlDecode(input.trim()) : input.slice();
+        if (psk.length !== 32)
+            throw new Error("psk must be 32 bytes");
+        return psk;
+    }
+    catch (error) {
+        throw new FlowersecError({ path, stage: "validate", code: "invalid_psk", message: "invalid psk", cause: error });
+    }
+}
+function normalizeEndpointInstanceId(input) {
+    const value = input ?? randomEndpointInstanceId();
+    try {
+        const bytes = base64urlDecode(value);
+        if (bytes.length < 16 || bytes.length > 32)
+            throw new Error("endpoint instance ID must decode to 16..32 bytes");
+    }
+    catch (error) {
+        throw new FlowersecError({ path: "tunnel", stage: "validate", code: "invalid_endpoint_instance_id", message: "invalid endpoint instance ID", cause: error });
+    }
+    return value;
+}
+function randomEndpointInstanceId() {
+    const bytes = new Uint8Array(24);
+    crypto.getRandomValues(bytes);
+    return base64urlEncode(bytes);
+}
+function normalizeStreamKind(kind, path) {
+    const value = kind.trim();
+    if (value === "")
+        throw new FlowersecError({ path, stage: "validate", code: "missing_stream_kind", message: "missing stream kind" });
+    return value;
+}
+function unwrapServerGrant(input) {
+    if (typeof input !== "object" || input == null || Array.isArray(input))
+        return input;
+    const record = input;
+    return record["grant_server"] ?? input;
+}
+function webSocketTransportOptions(options) {
+    return options.webSocketLimits === undefined ? {} : { webSocketLimits: options.webSocketLimits };
+}
+function readOptions(options) {
+    return {
+        timeoutMs: options.handshakeTimeoutMs ?? SDK_DEFAULTS.transport.handshakeTimeoutMs,
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+    };
+}
+async function enforceIncomingDirectTransport(options) {
+    const rawUrl = options.secureTransport === false ? "ws://127.0.0.1/" : "wss://127.0.0.1/";
+    await enforceTransportSecurity({ rawUrl, path: "direct", ...(options.transportSecurityPolicy === undefined ? {} : { policy: options.transportSecurityPolicy }) });
+}
+function waitForOpen(websocket, timeoutMs, signal) {
+    if (websocket.readyState === 1)
+        return Promise.resolve();
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0)
+        return Promise.reject(new RangeError("connectTimeoutMs must be non-negative"));
+    return new Promise((resolve, reject) => {
+        let timer;
+        const cleanup = () => {
+            if (timer != null)
+                clearTimeout(timer);
+            websocket.removeEventListener("open", onOpen);
+            websocket.removeEventListener("error", onError);
+            websocket.removeEventListener("close", onClose);
+            signal?.removeEventListener("abort", onAbort);
+        };
+        const finish = (error) => {
+            cleanup();
+            if (error == null)
+                resolve();
+            else
+                reject(error);
+        };
+        const onOpen = () => finish();
+        const onError = () => finish(new Error("websocket open failed"));
+        const onClose = () => finish(new Error("websocket closed before open"));
+        const onAbort = () => finish(new AbortError("connect aborted"));
+        websocket.addEventListener("open", onOpen);
+        websocket.addEventListener("error", onError);
+        websocket.addEventListener("close", onClose);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        if (timeoutMs > 0)
+            timer = setTimeout(() => finish(new Error("websocket open timeout")), timeoutMs);
+    });
+}
+function cleanupWaiter(waiter) {
+    if (waiter.onAbort != null)
+        waiter.signal?.removeEventListener("abort", waiter.onAbort);
+}
+function asError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}