@floegence/flowersec-core 2.4.0 → 2.4.2

package/README.md

@@ -33,6 +33,65 @@ Retry ownership belongs to `ConnectionController`; applications do not classify
 
 When connector options omit a connection timeout, browser and Node.js connectors use the shared ten-second default.
 
+### One-shot Node client
+
+```ts
+import { RPCHandlers, connect } from "@floegence/flowersec-core/node";
+
+const rpcHandlers = new RPCHandlers();
+rpcHandlers.handleRPC(7, async (payload) => ({ payload }));
+rpcHandlers.handleNotification(8, (payload) => onNotice(payload));
+const session = await connect(lease, {
+  origin: "https://app.example",
+  rpcHandlers,
+});
+```
+
+### Long-lived Node client
+
+```ts
+import { RPCHandlers, createConnectionController } from "@floegence/flowersec-core/node";
+
+const rpcHandlers = new RPCHandlers();
+rpcHandlers.handleRPC(7, async (payload) => ({ payload }));
+const controller = createConnectionController(source, {
+  origin: "https://app.example",
+  rpcHandlers,
+});
+controller.start();
+const session = await controller.waitForSession();
+```
+
+The immutable callback definition applies to every generation, while each
+Session gets a fresh router. Terminated Session work is never replayed.
+
+For the complete durable `ArtifactLease` spend workflow, see the
+[TypeScript cookbook](../examples/ts/README.md). Node raw-QUIC-only artifacts
+may omit `origin`; providing an absolute HTTP(S) origin enables WebSocket
+candidates. Secure raw QUIC still requires an explicit `tls.ca` trust root.
+
+### Accepted Node server Session
+
+```ts
+import { SessionHandlers, createAcceptor } from "@floegence/flowersec-core/node";
+
+const handlers = new SessionHandlers({ maxConcurrentStreams: 32 });
+handlers.handleRPC(7, async (payload) => ({ payload }));
+handlers.handleNotification(8, (payload) => onNotice(payload));
+handlers.handleStream("files/read", async (incoming) => serveFile(incoming));
+const acceptor = await createAcceptor({
+  listeners,
+  maxInboundStreams: 32,
+  authorize,
+  resolveHandlers: () => handlers,
+});
+const accepted = await acceptor.accept();
+await accepted.serve();
+```
+
+`RPCHandlers` is available only from the Node entrypoint and cannot register
+application streams. `SessionHandlers` is accepted-server-only.
+
 ## Connection Lifecycle
 
 The Browser and Node `connect(...)` operations are one-shot and never reconnect. Long-lived applications can create the runtime-specific `ConnectionController` with a refreshable `ArtifactSource`. Every attempt must return a fresh `ArtifactLease`; a one-time artifact or lease is not a controller source.
@@ -91,9 +150,10 @@ Cold-connection diagnostics require every independent carrier to meet the declar
 
 Node.js applications receive the same `Session` contract from `connect(...)`.
 The Node connector supports WSS, restricted plaintext loopback WebSocket
-direct connections, and raw QUIC through the optional native package. It
-requires an absolute HTTP(S) `origin`; custom certificate authorities can be
-supplied through `tls.ca`, and raw QUIC requires explicit trust roots.
+direct connections, and raw QUIC through the optional native package. WebSocket
+candidates require an absolute HTTP(S) `origin`; raw-QUIC-only artifacts may
+omit it. Custom certificate authorities can be supplied through `tls.ca`, and
+secure raw QUIC requires an explicit trust root.
 
 The connectors choose an eligible connection path from the invitation. They do
 not expose transport selectors, candidate lists, or native carrier objects to application code.

package/dist/framing/jsonframe.js

@@ -2,7 +2,7 @@ import { readU32be, u32be } from "../utils/bin.js";
 import { SDK_DEFAULTS } from "../defaults.js";
 export const DEFAULT_MAX_JSON_FRAME_BYTES = SDK_DEFAULTS.rpc.maxJsonFrameBytes;
 const te = new TextEncoder();
-const td = new TextDecoder();
+const td = new TextDecoder("utf-8", { fatal: true });
 // JsonFramingError marks malformed or oversized frames.
 export class JsonFramingError extends Error {
 }
@@ -29,5 +29,12 @@ export async function readJsonFrame(readExactly, maxBytes) {
     if (maxBytes > 0 && n > maxBytes)
         throw new JsonFramingError("frame too large");
     const payload = await read(n);
-    return JSON.parse(td.decode(payload));
+    let text;
+    try {
+        text = td.decode(payload);
+    }
+    catch {
+        throw new JsonFramingError("invalid UTF-8");
+    }
+    return JSON.parse(text);
 }

package/dist/interop/serverParityPeer.js

@@ -1,6 +1,6 @@
 import { createInterface } from "node:readline";
 import { createPrivateKey, createPublicKey, X509Certificate } from "node:crypto";
-import { createAcceptor, createArtifactLease, createEndpointSet, createStreamMetadata, createTunnelRuntime, connect, Issuer, parseArtifact, SessionError, SessionHandlers, } from "../node/index.js";
+import { createAcceptor, createArtifactLease, createEndpointSet, createStreamMetadata, createTunnelRuntime, connect, Issuer, parseArtifact, RPCHandlers, SessionError, SessionHandlers, } from "../node/index.js";
 const RUNTIME = "node-typescript";
 const ORIGIN = process.env.FLOWERSEC_PARITY_ORIGIN ?? "https://client.example";
 const ECHO_RPC = 7001;
@@ -56,38 +56,43 @@ class ExecutedCases {
     }
 }
 function createHandlers(path) {
-    const handlers = new SessionHandlers({ maxConcurrentStreams: 16 });
+    const rpcHandlers = new RPCHandlers();
+    const sessionHandlers = new SessionHandlers({ maxConcurrentStreams: 16 });
     const notifications = new SignalQueue();
     const activeStreams = { value: 0 };
     const executed = new ExecutedCases();
-    handlers.handleRPC(ECHO_RPC, async (payload) => {
-        if (!validValuePayload(payload, "ping"))
-            return { error: { code: 400, message: "invalid echo payload" } };
-        executed.record("rpc");
-        return { payload };
-    });
-    handlers.handleRPC(COMPLETE_RPC, async (payload) => {
-        if (!validValuePayload(payload, "complete"))
-            return { error: { code: 400, message: "invalid completion payload" } };
-        executed.record("rekey", "liveness");
-        notifications.push();
-        return { payload };
-    });
-    handlers.handleRPC(DATAGRAM_READY_RPC, async (payload) => {
-        if (!validValuePayload(payload, "datagram-ready"))
-            return {
-                error: { code: 400, message: "invalid datagram barrier payload" },
-            };
-        notifications.push();
-        return { payload };
-    });
-    handlers.handleNotification(NOTIFY_RPC, (payload) => {
-        if (!validValuePayload(payload, "notify"))
-            throw new Error("invalid notification payload");
-        executed.record("notification");
-        notifications.push();
-    });
-    handlers.handleStream(ECHO_KIND, async (incoming) => {
+    const registerRPC = (handlers) => {
+        handlers.handleRPC(ECHO_RPC, async (payload) => {
+            if (!validValuePayload(payload, "ping"))
+                return { error: { code: 400, message: "invalid echo payload" } };
+            executed.record("rpc");
+            return { payload };
+        });
+        handlers.handleRPC(COMPLETE_RPC, async (payload) => {
+            if (!validValuePayload(payload, "complete"))
+                return { error: { code: 400, message: "invalid completion payload" } };
+            executed.record("rekey", "liveness");
+            notifications.push();
+            return { payload };
+        });
+        handlers.handleRPC(DATAGRAM_READY_RPC, async (payload) => {
+            if (!validValuePayload(payload, "datagram-ready"))
+                return {
+                    error: { code: 400, message: "invalid datagram barrier payload" },
+                };
+            notifications.push();
+            return { payload };
+        });
+        handlers.handleNotification(NOTIFY_RPC, (payload) => {
+            if (!validValuePayload(payload, "notify"))
+                throw new Error("invalid notification payload");
+            executed.record("notification");
+            notifications.push();
+        });
+    };
+    registerRPC(rpcHandlers);
+    registerRPC(sessionHandlers);
+    sessionHandlers.handleStream(ECHO_KIND, async (incoming) => {
         activeStreams.value++;
         try {
             if (incoming.metadata.values.cell !== path)
@@ -102,13 +107,13 @@ function createHandlers(path) {
             activeStreams.value--;
         }
     });
-    handlers.handleStream(RESET_KIND, async (incoming) => {
+    sessionHandlers.handleStream(RESET_KIND, async (incoming) => {
         if (decoder.decode(await readAll(incoming.stream)) !== "reset")
             throw new Error("invalid reset stream payload");
         executed.record("stream-reset");
         throw new Error("intentional parity reset");
     });
-    return { handlers, notifications, activeStreams, executed };
+    return { rpcHandlers, sessionHandlers, notifications, activeStreams, executed };
 }
 function validValuePayload(payload, expected) {
     if (payload === null || typeof payload !== "object" || Array.isArray(payload))
@@ -315,11 +320,11 @@ function pem(label, encoded) {
         throw new Error("invalid embedded TLS fixture");
     return `-----BEGIN ${label}-----\n${lines.join("\n")}\n-----END ${label}-----\n`;
 }
-async function connectArtifact(artifactJSON, relay, handlers) {
+async function connectArtifact(artifactJSON, relay, rpcHandlers) {
     return await connect(createArtifactLease(parseArtifact(artifactJSON), async () => undefined), {
         origin: relay.origin,
         tls: { ca: relay.trust_pem },
-        handlers,
+        rpcHandlers,
     });
 }
 async function runServer(tls, carrier) {
@@ -334,7 +339,7 @@ async function runServer(tls, carrier) {
                 ? { decision: "reject", reason: "invalid_credential" }
                 : { decision: "allow", artifact };
         },
-        resolveHandlers: () => state.handlers,
+        resolveHandlers: () => state.sessionHandlers,
     });
     try {
         const address = acceptor.addresses()[0];
@@ -387,7 +392,7 @@ async function runClient(input, carrier) {
         ready.artifact_json === "")
         throw new Error("invalid direct ready message");
     const state = createHandlers("direct");
-    const session = await connectArtifact(ready.artifact_json, ready, state.handlers);
+    const session = await connectArtifact(ready.artifact_json, ready, state.rpcHandlers);
     state.executed.record("admission");
     await exerciseClient(session, state, "direct", carrier);
     await session.close().catch((error) => {
@@ -512,7 +517,7 @@ async function runTunnelEndpointB(input, carrier) {
     if (command.type !== "connect")
         throw new Error("endpoint B did not receive connect command");
     const state = createHandlers("tunnel");
-    const session = await connectArtifact(secondJSON, relay, state.handlers);
+    const session = await connectArtifact(secondJSON, relay, state.rpcHandlers);
     state.executed.record("admission");
     if (process.env.FLOWERSEC_PARITY_CLIENT_PROFILE !== undefined) {
         await externalServer(session, state);
@@ -541,7 +546,7 @@ async function runTunnelEndpointA(input, carrier) {
         ready.endpoint_a_artifact_json === "")
         throw new Error("invalid endpoint B ready message");
     const state = createHandlers("tunnel");
-    const session = await connectArtifact(ready.endpoint_a_artifact_json, ready.relay, state.handlers);
+    const session = await connectArtifact(ready.endpoint_a_artifact_json, ready.relay, state.rpcHandlers);
     state.executed.record("admission");
     await exerciseClient(session, state, "tunnel", carrier);
     await session.close().catch(() => undefined);

package/dist/node/acceptor.d.ts

@@ -20,16 +20,25 @@ export type StreamHandler = (incoming: IncomingStream, options: OperationOptions
 export type SessionHandlerOptions = Readonly<{
     maxConcurrentStreams?: number;
 }>;
-export declare class SessionHandlersError extends Error {
+export declare class HandlerRegistrationError extends Error {
     readonly code: "invalid_handler" | "already_registered" | "frozen";
     constructor(code: "invalid_handler" | "already_registered" | "frozen");
 }
+export declare class RPCHandlers {
+    constructor();
+    handleRPC(typeId: number, handler: RPCHandler): void;
+    handleNotification(typeId: number, handler: NotificationHandler): void;
+}
 export declare class SessionHandlers {
     constructor(options?: SessionHandlerOptions);
     handleRPC(typeId: number, handler: RPCHandler): void;
     handleNotification(typeId: number, handler: NotificationHandler): void;
     handleStream(kind: string, handler: StreamHandler): void;
 }
+export type FrozenRPCHandlers = Readonly<{
+    requests: ReadonlyMap<number, RPCHandler>;
+    notifications: ReadonlyMap<number, NotificationHandler>;
+}>;
 export type AcceptorListener = Readonly<{
     carrier: "websocket";
     path: "direct";

package/dist/node/acceptor.js

@@ -1,4 +1,5 @@
 import { RpcRouter } from "../rpc/server.js";
+import { assertRpcError } from "../rpc/validate.js";
 import { acceptReceivedSessionV2, receiveSessionAdmissionV2, rejectSessionAdmissionV2, } from "../connector/sessionAcceptor.js";
 import { nodeSessionRuntimeV2 } from "./sessionRuntime.js";
 import { startNodeWebSocketServer, } from "./webSocketServer.js";
@@ -12,12 +13,23 @@ const DEFAULT_MAX_CONCURRENT_STREAMS = 64;
 const MAX_CONCURRENT_STREAMS = 128;
 const DEFAULT_CLEANUP_TIMEOUT_MS = 2_000;
 const encoder = new TextEncoder();
-export class SessionHandlersError extends Error {
+export class HandlerRegistrationError extends Error {
     code;
     constructor(code) {
-        super(`Flowersec session handler registration failed (code=${code})`);
+        super(`Flowersec handler registration failed (code=${code})`);
         this.code = code;
-        this.name = "SessionHandlersError";
+        this.name = "HandlerRegistrationError";
+    }
+}
+export class RPCHandlers {
+    constructor() {
+        rpcHandlerStates.set(this, createRPCHandlerState());
+    }
+    handleRPC(typeId, handler) {
+        registerRPC(mutableRPCHandlerState(this), typeId, handler);
+    }
+    handleNotification(typeId, handler) {
+        registerNotification(mutableRPCHandlerState(this), typeId, handler);
     }
 }
 export class SessionHandlers {
@@ -26,68 +38,107 @@ export class SessionHandlers {
         if (!Number.isSafeInteger(maximum) ||
             maximum < 1 ||
             maximum > MAX_CONCURRENT_STREAMS) {
-            throw new SessionHandlersError("invalid_handler");
+            throw new HandlerRegistrationError("invalid_handler");
         }
         sessionHandlerStates.set(this, {
             maxConcurrentStreams: maximum,
-            rpc: new Map(),
-            notifications: new Map(),
+            rpc: createRPCHandlerState(),
             streams: new Map(),
             frozen: false,
         });
     }
     handleRPC(typeId, handler) {
-        const state = mutableHandlerState(this);
-        if (!Number.isSafeInteger(typeId) ||
-            typeId < 1 ||
-            typeId > 0xffff_ffff ||
-            typeof handler !== "function") {
-            throw new SessionHandlersError("invalid_handler");
-        }
-        if (state.rpc.has(typeId))
-            throw new SessionHandlersError("already_registered");
-        if (state.notifications.has(typeId))
-            throw new SessionHandlersError("already_registered");
-        state.rpc.set(typeId, handler);
+        const state = mutableSessionHandlerState(this);
+        registerRPC(state.rpc, typeId, handler);
     }
     handleNotification(typeId, handler) {
-        const state = mutableHandlerState(this);
-        if (!Number.isSafeInteger(typeId) ||
-            typeId < 1 ||
-            typeId > 0xffff_ffff ||
-            typeof handler !== "function") {
-            throw new SessionHandlersError("invalid_handler");
-        }
-        if (state.rpc.has(typeId) || state.notifications.has(typeId))
-            throw new SessionHandlersError("already_registered");
-        state.notifications.set(typeId, handler);
+        const state = mutableSessionHandlerState(this);
+        registerNotification(state.rpc, typeId, handler);
     }
     handleStream(kind, handler) {
-        const state = mutableHandlerState(this);
+        const state = mutableSessionHandlerState(this);
         if (kind.length < 1 ||
             encoder.encode(kind).length > 255 ||
             kind === "flowersec.rpc.v2" ||
             typeof handler !== "function") {
-            throw new SessionHandlersError("invalid_handler");
+            throw new HandlerRegistrationError("invalid_handler");
         }
         if (state.streams.has(kind))
-            throw new SessionHandlersError("already_registered");
+            throw new HandlerRegistrationError("already_registered");
         state.streams.set(kind, handler);
     }
 }
+const rpcHandlerStates = new WeakMap();
 const sessionHandlerStates = new WeakMap();
-function mutableHandlerState(handlers) {
+function createRPCHandlerState() {
+    return { requests: new Map(), notifications: new Map(), frozen: false };
+}
+function mutableRPCHandlerState(handlers) {
+    const state = rpcHandlerStates.get(handlers);
+    if (state === undefined)
+        throw new HandlerRegistrationError("invalid_handler");
+    if (state.frozen)
+        throw new HandlerRegistrationError("frozen");
+    return state;
+}
+function mutableSessionHandlerState(handlers) {
     const state = sessionHandlerStates.get(handlers);
     if (state === undefined)
-        throw new SessionHandlersError("invalid_handler");
+        throw new HandlerRegistrationError("invalid_handler");
     if (state.frozen)
-        throw new SessionHandlersError("frozen");
+        throw new HandlerRegistrationError("frozen");
     return state;
 }
-function freezeHandlers(handlers, router) {
-    const state = mutableHandlerState(handlers);
+function registerRPC(state, typeId, handler) {
+    validateRPCRegistration(typeId, handler);
+    if (state.requests.has(typeId) || state.notifications.has(typeId)) {
+        throw new HandlerRegistrationError("already_registered");
+    }
+    state.requests.set(typeId, handler);
+}
+function registerNotification(state, typeId, handler) {
+    validateRPCRegistration(typeId, handler);
+    if (state.requests.has(typeId) || state.notifications.has(typeId)) {
+        throw new HandlerRegistrationError("already_registered");
+    }
+    state.notifications.set(typeId, handler);
+}
+function validateRPCRegistration(typeId, handler) {
+    if (!Number.isSafeInteger(typeId)
+        || typeId < 1
+        || typeId > 0xffff_ffff
+        || typeof handler !== "function") {
+        throw new HandlerRegistrationError("invalid_handler");
+    }
+}
+/** @internal */
+export function freezeRPCHandlers(handlers) {
+    const state = rpcHandlerStates.get(handlers);
+    if (state === undefined)
+        throw new HandlerRegistrationError("invalid_handler");
+    if (state.snapshot !== undefined)
+        return state.snapshot;
+    state.frozen = true;
+    state.snapshot = Object.freeze({
+        requests: new Map(state.requests),
+        notifications: new Map(state.notifications),
+    });
+    return state.snapshot;
+}
+function freezeRPCHandlerState(state) {
+    if (state.snapshot !== undefined)
+        return state.snapshot;
     state.frozen = true;
-    for (const [typeId, handler] of state.rpc) {
+    state.snapshot = Object.freeze({
+        requests: new Map(state.requests),
+        notifications: new Map(state.notifications),
+    });
+    return state.snapshot;
+}
+/** @internal */
+export function createRPCRouter(snapshot) {
+    const router = new RpcRouter();
+    for (const [typeId, handler] of snapshot.requests) {
         router.register(typeId, async (payload) => {
             const result = await handler(payload, Object.freeze({ typeId }));
             if ("error" in result)
@@ -95,34 +146,39 @@ function freezeHandlers(handlers, router) {
             return { payload: result.payload };
         });
     }
-    for (const [typeId, handler] of state.notifications) {
+    for (const [typeId, handler] of snapshot.notifications) {
         router.onNotify(typeId, (payload) => {
             void Promise.resolve(handler(payload, Object.freeze({ typeId }))).catch(() => undefined);
         });
     }
-    return Object.freeze({
+    return router;
+}
+function freezeSessionHandlers(handlers) {
+    const state = sessionHandlerStates.get(handlers);
+    if (state === undefined)
+        throw new HandlerRegistrationError("invalid_handler");
+    if (state.snapshot !== undefined)
+        return state.snapshot;
+    state.frozen = true;
+    state.snapshot = Object.freeze({
+        rpc: freezeRPCHandlerState(state.rpc),
         maxConcurrentStreams: state.maxConcurrentStreams,
         streams: new Map(state.streams),
     });
-}
-/** @internal */
-export function freezeSessionHandlersForConnector(handlers) {
-    const router = new RpcRouter();
-    freezeHandlers(handlers, router);
-    return router;
+    return state.snapshot;
 }
 /** @internal */
 export function registerSessionStreamsAtomically(handlers, entries) {
-    const state = mutableHandlerState(handlers);
+    const state = mutableSessionHandlerState(handlers);
     const pending = new Set();
     for (const [kind, handler] of entries) {
         if (kind.length < 1 ||
             encoder.encode(kind).length > 255 ||
             kind === "flowersec.rpc.v2" ||
             typeof handler !== "function")
-            throw new SessionHandlersError("invalid_handler");
+            throw new HandlerRegistrationError("invalid_handler");
         if (state.streams.has(kind) || pending.has(kind))
-            throw new SessionHandlersError("already_registered");
+            throw new HandlerRegistrationError("already_registered");
         pending.add(kind);
     }
     for (const [kind, handler] of entries)
@@ -209,11 +265,27 @@ export class Acceptor {
     }
     async close() {
         const state = acceptorState(this);
-        state.abort.abort();
-        state.accepted.close();
-        await Promise.all(state.listeners.map(async (listener) => await listener.close()));
-        await boundedCleanup(state.tasks, state.cleanupTimeoutMs);
-        state.tasks.clear();
+        if (state.lifecycle.completion === undefined) {
+            state.lifecycle.completion = closeAcceptor(state);
+        }
+        await withCleanupTimeout(state.lifecycle.completion, state.cleanupTimeoutMs);
+    }
+}
+const MAX_CONCURRENT_ADMISSIONS = 64;
+const MAX_PENDING_ACCEPTED_SESSIONS = 64;
+async function closeAcceptor(state) {
+    state.abort.abort();
+    const queued = state.accepted.close();
+    const cleanup = await Promise.allSettled([
+        ...state.listeners.map(async (listener) => await listener.close()),
+        ...queued.map(async (accepted) => await accepted.close()),
+    ]);
+    while (state.tasks.size > 0) {
+        await Promise.allSettled([...state.tasks]);
+    }
+    if (cleanup.some((result) => result.status === "rejected") ||
+        state.lifecycle.cleanupFailed) {
+        throw new SessionError("operation_failed");
     }
 }
 async function releaseLease(state, leaseId) {
@@ -225,7 +297,7 @@ async function authorizeCarrier(state, carrier) {
     const received = await receiveSessionAdmissionV2(carrier, state.abort.signal);
     const decoded = received.decoded;
     const request = runtimeAuthorizationRequestFromDecoded(decoded);
-    const decision = await abortableCallback(state.options.authorize(request, { signal: state.abort.signal }), state.abort.signal);
+    const decision = await state.options.authorize(request, { signal: state.abort.signal });
     if (decision.decision !== "allow") {
         return await rejectSessionAdmissionV2(received, {
             accepted: false,
@@ -237,17 +309,15 @@ async function authorizeCarrier(state, carrier) {
         ? decision.leaseId
         : undefined;
     try {
-        const router = new RpcRouter();
         const registry = state.options.resolveHandlers === undefined
             ? new SessionHandlers()
-            : await abortableCallback(Promise.resolve(state.options.resolveHandlers(request, {
-                signal: state.abort.signal,
-            })), state.abort.signal);
+            : await state.options.resolveHandlers(request, { signal: state.abort.signal });
+        const handlers = freezeSessionHandlers(registry);
         const leg = {
             received,
             artifact: unwrapArtifact(decision.artifact),
-            handlers: freezeHandlers(registry, router),
-            router,
+            handlers,
+            router: createRPCRouter(handlers.rpc),
         };
         if (leaseId !== undefined)
             leg.leaseId = leaseId;
@@ -271,28 +341,50 @@ async function processCarrier(state, carrier) {
     const leg = await authorizeCarrier(state, carrier);
     if (leg === undefined)
         return;
+    let releaseOwnedByAcceptedSession = false;
     try {
         if (leg.received.decoded.request.pathKind !== "direct" ||
             leg.artifact.path.kind !== "direct") {
             await leg.received.carrier.close().catch(() => undefined);
             throw new SessionError("operation_failed");
         }
-        state.accepted.push(await establishDirect(leg, state.abort.signal, leg.leaseId === undefined ? undefined : () => releaseLease(state, leg.leaseId)));
+        const accepted = await establishDirect(leg, state.abort.signal, leg.leaseId === undefined ? undefined : () => releaseLease(state, leg.leaseId));
+        releaseOwnedByAcceptedSession = true;
+        if (state.accepted.push(accepted) === "rejected") {
+            try {
+                await accepted.close();
+            }
+            catch {
+                state.lifecycle.cleanupFailed = true;
+                throw new SessionError("operation_failed");
+            }
+        }
     }
     catch (error) {
-        await releaseLease(state, leg.leaseId).catch(() => undefined);
+        if (!releaseOwnedByAcceptedSession) {
+            await releaseLease(state, leg.leaseId).catch(() => undefined);
+        }
         throw error;
     }
 }
 async function runAcceptLoop(state) {
     while (!state.abort.signal.aborted) {
         try {
+            while (state.admissions.size >= MAX_CONCURRENT_ADMISSIONS) {
+                await Promise.race(state.admissions);
+                if (state.abort.signal.aborted)
+                    return;
+            }
             const carrier = await state.accept({ signal: state.abort.signal });
             const task = processCarrier(state, carrier)
                 .catch(async () => {
                 await carrier.close().catch(() => undefined);
             })
-                .finally(() => state.tasks.delete(task));
+                .finally(() => {
+                state.admissions.delete(task);
+                state.tasks.delete(task);
+            });
+            state.admissions.add(task);
             state.tasks.add(task);
         }
         catch (error) {
@@ -307,16 +399,19 @@ class AcceptedQueue {
     waiters = new Set();
     failure;
     push(value) {
-        if (this.failure !== undefined) {
-            void value.close();
-            return;
-        }
+        if (this.failure !== undefined)
+            return "rejected";
         const waiter = this.waiters.values().next().value;
-        if (waiter === undefined)
+        if (waiter === undefined) {
+            if (this.values.length >= MAX_PENDING_ACCEPTED_SESSIONS)
+                return "rejected";
             this.values.push(value);
+            return "queued";
+        }
         else {
             this.waiters.delete(waiter);
             waiter.resolve(value);
+            return "delivered";
         }
     }
     async shift(signal) {
@@ -357,6 +452,7 @@ class AcceptedQueue {
     }
     close() {
         this.fail(new SessionError("closed"));
+        return this.values.splice(0);
     }
 }
 const acceptorStates = new WeakMap();
@@ -427,6 +523,7 @@ export async function createAcceptor(options) {
     const accepted = new AcceptedQueue();
     const abort = new AbortController();
     const tasks = new Set();
+    const admissions = new Set();
     let started = false;
     const state = {
         listeners,
@@ -435,7 +532,9 @@ export async function createAcceptor(options) {
         accepted,
         abort,
         tasks,
+        admissions,
         cleanupTimeoutMs,
+        lifecycle: { cleanupFailed: false },
         start() {
             if (started)
                 return;
@@ -447,52 +546,26 @@ export async function createAcceptor(options) {
     acceptorStates.set(acceptor, state);
     return Object.freeze(acceptor);
 }
-async function boundedCleanup(tasks, timeoutMs) {
-    await Promise.race([
-        Promise.allSettled([...tasks]).then(() => undefined),
-        new Promise((resolve) => setTimeout(resolve, timeoutMs)),
-    ]);
-}
-async function abortableCallback(promise, signal) {
-    if (signal.aborted)
-        throw signal.reason instanceof Error ? signal.reason : new SessionError("closed");
-    return await new Promise((resolve, reject) => {
-        let settled = false;
-        const cleanup = () => signal.removeEventListener("abort", abort);
-        const abort = () => {
-            if (settled)
-                return;
-            settled = true;
-            cleanup();
-            reject(signal.reason instanceof Error ? signal.reason : new SessionError("closed"));
-        };
-        signal.addEventListener("abort", abort, { once: true });
-        void promise.then((value) => {
-            if (settled)
-                return;
-            settled = true;
-            cleanup();
-            resolve(value);
-        }, (error) => {
-            if (settled)
-                return;
-            settled = true;
-            cleanup();
-            reject(error);
-        });
-    });
+async function withCleanupTimeout(completion, timeoutMs) {
+    let timer;
+    try {
+        await Promise.race([
+            completion,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new SessionError("timeout")), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
 }
 function validRPCError(error) {
-    if (!Number.isSafeInteger(error.code) ||
-        error.code < 1 ||
-        error.code > 0xffff_ffff) {
-        return { code: 500, message: "handler failed" };
+    try {
+        return assertRpcError(error);
     }
-    if (error.message !== undefined &&
-        encoder.encode(error.message).length > 1024) {
+    catch {
         return { code: 500, message: "handler failed" };
     }
-    return error.message === undefined
-        ? { code: error.code }
-        : { code: error.code, message: error.message };
 }

package/dist/node/connectSession.d.ts

@@ -1,22 +1,23 @@
 import type { ArtifactLease } from "../public/artifactLease.js";
 import type { Session } from "../public/contract.js";
 import { type ArtifactSource, type ConnectionController } from "../connectionController.js";
-import { type SessionHandlers } from "./acceptor.js";
+import { type RPCHandlers } from "./acceptor.js";
 export type SessionTLSOptions = Readonly<{
     ca?: string | Uint8Array;
 }>;
 export type SessionOptions = Readonly<{
-    origin: string;
+    origin?: string;
     signal?: AbortSignal;
     connectTimeoutMs?: number;
     tls?: SessionTLSOptions;
-    handlers?: SessionHandlers;
+    rpcHandlers?: RPCHandlers;
 }>;
 export type ConnectionControllerOptions = Readonly<{
-    origin: string;
+    origin?: string;
     connectTimeoutMs?: number;
     tls?: SessionTLSOptions;
     maximumAttempts?: number;
+    rpcHandlers?: RPCHandlers;
 }>;
 export declare function createConnectionController(source: ArtifactSource, options: ConnectionControllerOptions): ConnectionController;
 export declare function connect(lease: ArtifactLease, options: SessionOptions): Promise<Session>;

package/dist/node/connectSession.js

@@ -7,33 +7,24 @@ import { projectSessionV2 } from "../v2/publicSession.js";
 import { ConnectError } from "../public/connectError.js";
 import { nodeSessionRuntimeV2 } from "./sessionRuntime.js";
 import { createConnectionControllerV2, } from "../connectionController.js";
-import { freezeSessionHandlersForConnector, } from "./acceptor.js";
+import { createRPCRouter, freezeRPCHandlers, } from "./acceptor.js";
 import { createNativeRawQuicDriver, NativeTransportUnavailableError, tryLoadNativeTransportAddon, } from "./nativeTransportAddon.js";
-import { createNodeRawQuicClientV2 } from "./rawQuicAdapter.js";
+import { createNodeRawQuicClientV2, normalizeCertificateChain } from "./rawQuicAdapter.js";
 export function createConnectionController(source, options) {
+    const normalized = normalizeNodeOptions(options);
     const controllerOptions = options.maximumAttempts === undefined
         ? {}
         : { maximumAttempts: options.maximumAttempts };
-    return createConnectionControllerV2(source, async (lease, signal) => await connect(lease, {
-        origin: options.origin,
-        signal,
-        ...(options.connectTimeoutMs === undefined ? {} : { connectTimeoutMs: options.connectTimeoutMs }),
-        ...(options.tls === undefined ? {} : { tls: options.tls }),
-    }), controllerOptions);
+    return createConnectionControllerV2(source, async (lease, signal) => await connectWithRPCSnapshot(lease, normalized, signal), controllerOptions);
 }
 export async function connect(lease, options) {
-    let origin;
-    let wsFactory;
-    try {
-        origin = normalizeOrigin(options.origin);
-        wsFactory = createNodeWsFactory(options.tls);
-    }
-    catch {
-        throw new ConnectError("invalid_options");
-    }
-    const rpcRouter = options.handlers === undefined
+    const normalized = normalizeNodeOptions(options);
+    return await connectWithRPCSnapshot(lease, normalized, options.signal);
+}
+async function connectWithRPCSnapshot(lease, options, signal) {
+    const rpcRouter = options.rpcSnapshot === undefined
         ? undefined
-        : freezeSessionHandlersForConnector(options.handlers);
+        : createRPCRouter(options.rpcSnapshot);
     // WebSocket sessions do not require the optional native raw QUIC addon. Load
     // it only when a raw QUIC candidate is actually selected by the connector.
     const nativeAddon = tryLoadNativeTransportAddon();
@@ -45,8 +36,14 @@ export async function connect(lease, options) {
         }
         return await createNodeRawQuicClientV2(createNativeRawQuicDriver(nativeAddon), candidate, artifact, { ca: options.tls.ca }, signal, options.connectTimeoutMs);
     });
+    const origin = options.origin;
+    let websocketFactory;
+    if (origin !== undefined) {
+        const wsFactory = createNodeWsFactory(options.tls);
+        websocketFactory = createWebSocketCandidateFactoryV2((url, subprotocol) => wsFactory(url, origin, subprotocol));
+    }
     const connector = new SessionConnectorV2(lease, composeCandidateAttemptFactoryV2({
-        websocket: createWebSocketCandidateFactoryV2((url, subprotocol) => wsFactory(url, origin, subprotocol)),
+        ...(websocketFactory === undefined ? {} : { websocket: websocketFactory }),
         raw_quic: rawQuicFactory,
     }), {
         capability: detectNodeRuntimeCapabilityV2(nativeAddon !== undefined),
@@ -54,10 +51,34 @@ export async function connect(lease, options) {
         ...(rpcRouter === undefined ? {} : { rpcRouter }),
         ...(options.connectTimeoutMs === undefined ? {} : { connectTimeoutMs: options.connectTimeoutMs }),
     });
-    const result = await connector.connect(options.signal === undefined ? {} : { signal: options.signal });
+    const result = await connector.connect(signal === undefined ? {} : { signal });
     return projectSessionV2(result.session);
 }
+function normalizeNodeOptions(options) {
+    try {
+        const origin = normalizeOrigin(options.origin);
+        if (options.connectTimeoutMs !== undefined &&
+            (!Number.isSafeInteger(options.connectTimeoutMs) || options.connectTimeoutMs < 1)) {
+            throw new RangeError("connectTimeoutMs must be a positive safe integer");
+        }
+        if (origin !== undefined)
+            createNodeWsFactory(options.tls);
+        if (options.tls?.ca !== undefined)
+            normalizeCertificateChain(options.tls.ca);
+        return Object.freeze({
+            ...(origin === undefined ? {} : { origin }),
+            ...(options.connectTimeoutMs === undefined ? {} : { connectTimeoutMs: options.connectTimeoutMs }),
+            ...(options.tls === undefined ? {} : { tls: options.tls }),
+            ...(options.rpcHandlers === undefined ? {} : { rpcSnapshot: freezeRPCHandlers(options.rpcHandlers) }),
+        });
+    }
+    catch {
+        throw new ConnectError("invalid_options");
+    }
+}
 function normalizeOrigin(input) {
+    if (input === undefined)
+        return undefined;
     let parsed;
     try {
         parsed = new URL(input);

package/dist/node/controlplane.js

@@ -1,4 +1,4 @@
-import { randomBytes as nodeRandomBytes } from "node:crypto";
+import { randomBytes as nodeRandomBytes, timingSafeEqual } from "node:crypto";
 import { buildFSB2RequestV2, canonicalizeCandidatesV2, computeSessionContractHashV2, decodeArtifactV2JSON, decodeFSB2RequestV2, encodeArtifactV2JSON, encodeFSB2RequestV2, } from "../v2/artifact.js";
 import { wrapArtifact } from "../public/artifact.js";
 import { base64urlDecode, base64urlEncode } from "../utils/base64url.js";
@@ -413,7 +413,11 @@ function validTCPAddress(value) {
     return port >= 1 && port <= 65_535;
 }
 function validObservedText(value) { return value.length > 0 && value.length <= 512 && !/[\u0000-\u001f\u007f]/u.test(value); }
-function bytesEqual(a, b) { return a.length === b.length && a.every((value, index) => value === b[index]); }
+function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
 function strictObject(bytes) {
     let value;
     try {

package/dist/node/index.d.ts

@@ -1,5 +1,5 @@
 export { connect, createConnectionController } from "./connectSession.js";
-export { AcceptedSession, Acceptor, SessionHandlers, SessionHandlersError, createAcceptor, } from "./acceptor.js";
+export { AcceptedSession, Acceptor, HandlerRegistrationError, RPCHandlers, SessionHandlers, createAcceptor, } from "./acceptor.js";
 export type { AcceptorListener, AcceptorOptions, AuthorizationDecision, RPCHandler, RPCHandlerResult, NotificationHandler, SessionHandlerOptions, StreamHandler, } from "./acceptor.js";
 export { TunnelRuntime, createTunnelRuntime } from "./tunnelRuntime.js";
 export type { TunnelAuthorizationDecision, TunnelRuntimeListener, TunnelRuntimeOptions, } from "./tunnelRuntime.js";

package/dist/node/index.js

@@ -1,5 +1,5 @@
 export { connect, createConnectionController } from "./connectSession.js";
-export { AcceptedSession, Acceptor, SessionHandlers, SessionHandlersError, createAcceptor, } from "./acceptor.js";
+export { AcceptedSession, Acceptor, HandlerRegistrationError, RPCHandlers, SessionHandlers, createAcceptor, } from "./acceptor.js";
 export { TunnelRuntime, createTunnelRuntime } from "./tunnelRuntime.js";
 export { AuthorizationRecord, AuthorizationResponse, TunnelAuthorizationResponse, ControlPlaneError, EndpointSet, IssuedArtifact, Issuer, RuntimeAuthorizationRequest, authorizeRuntime, authorizeTunnelRuntime, createEndpointSet, parseAuthorizationRecord, parseRuntimeAuthorizationRequest, rejectRuntime, rejectTunnelRuntime, } from "./controlplane.js";
 export { ProxyServer, ProxyServerError } from "./proxyServer.js";

package/dist/public/artifactLease.js

@@ -36,13 +36,6 @@ export async function commitArtifactLeaseSpend(lease, signal) {
     const leaseState = artifactLeaseStates.get(lease);
     if (leaseState === undefined || leaseState.state !== "idle")
         throw new ArtifactLeaseError();
-    leaseState.state = "spending";
-    try {
-        await leaseState.commitSpend(signal);
-        leaseState.state = "consumed";
-    }
-    catch (error) {
-        leaseState.state = "idle";
-        throw error;
-    }
+    leaseState.state = "consumed";
+    await leaseState.commitSpend(signal);
 }

package/dist/rpc/server.js

@@ -1,5 +1,5 @@
 import { DEFAULT_MAX_JSON_FRAME_BYTES, readJsonFrame, writeJsonFrame } from "../framing/jsonframe.js";
-import { assertRpcEnvelope } from "./validate.js";
+import { assertRpcEnvelope, assertRpcError } from "./validate.js";
 import { SDK_DEFAULTS } from "../defaults.js";
 const DEFAULT_RPC_SERVER_OPTIONS = Object.freeze({
     maxConcurrentRequests: SDK_DEFAULTS.rpc.maxConcurrentRequests,
@@ -217,12 +217,21 @@ export class RpcServer {
         waiters.shift()?.();
     }
     async writeResponse(request, out) {
+        let error;
+        if (out.error != null) {
+            try {
+                error = assertRpcError(out.error);
+            }
+            catch {
+                error = { code: 500, message: "internal error" };
+            }
+        }
         const resp = {
             type_id: request.type_id,
             request_id: 0,
             response_to: request.request_id,
             payload: out.payload,
-            ...(out.error != null ? { error: out.error } : {}),
+            ...(error != null ? { error } : {}),
         };
         await this.writeEnvelope(resp);
     }

package/dist/rpc/validate.d.ts

@@ -1,2 +1,3 @@
-import type { RpcEnvelope } from "./wire.js";
+import type { RpcEnvelope, RpcError } from "./wire.js";
 export declare function assertRpcEnvelope(v: unknown): RpcEnvelope;
+export declare function assertRpcError(value: unknown): RpcError;

package/dist/rpc/validate.js

@@ -1,4 +1,6 @@
 import { isSafeU32Number, isSafeU64Number } from "../utils/number.js";
+const encoder = new TextEncoder();
+const strictDecoder = new TextDecoder("utf-8", { fatal: true });
 // assertRpcEnvelope validates numeric fields that are u32/u64 in the IDL.
 //
 // The wire format is JSON, so JS numbers are used. For u64 we enforce the safe integer range
@@ -15,13 +17,29 @@ export function assertRpcEnvelope(v) {
         throw new Error("bad rpc envelope: response_to");
     // payload: unknown (JSON)
     if (o.error != null) {
-        if (typeof o.error !== "object" || o.error == null)
-            throw new Error("bad rpc envelope: error");
-        if (!isSafeU32Number(o.error.code))
-            throw new Error("bad rpc envelope: error.code");
-        const msg = o.error.message;
-        if (msg !== undefined && typeof msg !== "string")
-            throw new Error("bad rpc envelope: error.message");
+        assertRpcError(o.error);
     }
     return o;
 }
+export function assertRpcError(value) {
+    if (typeof value !== "object" || value == null)
+        throw new Error("bad rpc envelope: error");
+    const error = value;
+    if (Object.keys(error).some((key) => key !== "code" && key !== "message")) {
+        throw new Error("bad rpc envelope: error shape");
+    }
+    if (!isSafeU32Number(error.code) || error.code === 0) {
+        throw new Error("bad rpc envelope: error.code");
+    }
+    const message = error.message;
+    if (message !== undefined && typeof message !== "string") {
+        throw new Error("bad rpc envelope: error.message");
+    }
+    if (typeof message === "string") {
+        const encoded = encoder.encode(message);
+        if (encoded.byteLength > 1_024 || strictDecoder.decode(encoded) !== message) {
+            throw new Error("bad rpc envelope: error.message");
+        }
+    }
+    return message === undefined ? { code: error.code } : { code: error.code, message };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floegence/flowersec-core",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "description": "Flowersec core TypeScript library for carrier-neutral encrypted sessions and multiplexed streams.",
   "license": "MIT",
   "repository": {
@@ -77,7 +77,7 @@
     "ws": "^8.21.2"
   },
   "optionalDependencies": {
-    "@floegence/flowersec-node-native": "2.4.0"
+    "@floegence/flowersec-node-native": "2.4.2"
   },
   "devDependencies": {
     "@playwright/test": "1.62.1",
@@ -95,5 +95,5 @@
     "vite": "^8.2.1",
     "vitest": "4.1.10"
   },
-  "flowersecSourceCommit": "0849589d3516564cc2f32ce51f15a1bba4aa3aa6"
+  "flowersecSourceCommit": "1393acdb891a6c935a435bee9068f65b68268795"
 }

package/sbom/cyclonedx.json

@@ -1,20 +1,20 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:c502284d-2e30-5f97-8204-2cdd20d4483a",
+  "serialNumber": "urn:uuid:a7cb7385-1123-5452-8424-bbcb7904bbbb",
   "version": 1,
   "metadata": {
     "component": {
       "type": "library",
       "name": "@floegence/flowersec-core",
-      "version": "2.4.0",
-      "purl": "pkg:npm/%40floegence/flowersec-core@2.4.0",
-      "bom-ref": "pkg:npm/%40floegence/flowersec-core@2.4.0"
+      "version": "2.4.2",
+      "purl": "pkg:npm/%40floegence/flowersec-core@2.4.2",
+      "bom-ref": "pkg:npm/%40floegence/flowersec-core@2.4.2"
     },
     "properties": [
       {
         "name": "flowersec:source-inventory-sha256",
-        "value": "1c377fd1fb5ea77eadd418a3990b5ae9585edf1a740a95901287df743cc2ec9c"
+        "value": "59d233df0e12f2c371ab542c83edf97a2968a75c7d17c057e453b97f530a90e4"
       }
     ]
   },
@@ -190,7 +190,7 @@
   ],
   "dependencies": [
     {
-      "ref": "pkg:npm/%40floegence/flowersec-core@2.4.0",
+      "ref": "pkg:npm/%40floegence/flowersec-core@2.4.2",
       "dependsOn": [
         "pkg:npm/%40noble/ciphers@2.3.0",
         "pkg:npm/%40noble/curves@2.3.0",

package/sbom/spdx.json

@@ -3,7 +3,7 @@
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
   "name": "flowersec-ts",
-  "documentNamespace": "https://github.com/floegence/flowersec/sbom/flowersec-ts/1c377fd1fb5ea77eadd418a3990b5ae9585edf1a740a95901287df743cc2ec9c",
+  "documentNamespace": "https://github.com/floegence/flowersec/sbom/flowersec-ts/59d233df0e12f2c371ab542c83edf97a2968a75c7d17c057e453b97f530a90e4",
   "creationInfo": {
     "created": "1970-01-01T00:00:00Z",
     "creators": [
@@ -13,19 +13,19 @@
   "packages": [
     {
       "name": "@floegence/flowersec-core",
-      "SPDXID": "SPDXRef-Package-d5c0c7bb3c27968de167",
-      "versionInfo": "2.4.0",
+      "SPDXID": "SPDXRef-Package-9eec732cc29715c69e1e",
+      "versionInfo": "2.4.2",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
       "licenseDeclared": "NOASSERTION",
       "copyrightText": "NOASSERTION",
-      "comment": "Flowersec source inventory SHA-256: 1c377fd1fb5ea77eadd418a3990b5ae9585edf1a740a95901287df743cc2ec9c",
+      "comment": "Flowersec source inventory SHA-256: 59d233df0e12f2c371ab542c83edf97a2968a75c7d17c057e453b97f530a90e4",
       "externalRefs": [
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40floegence/flowersec-core@2.4.0"
+          "referenceLocator": "pkg:npm/%40floegence/flowersec-core@2.4.2"
         }
       ]
     },
@@ -136,30 +136,30 @@
     {
       "spdxElementId": "SPDXRef-DOCUMENT",
       "relationshipType": "DESCRIBES",
-      "relatedSpdxElement": "SPDXRef-Package-d5c0c7bb3c27968de167"
+      "relatedSpdxElement": "SPDXRef-Package-9eec732cc29715c69e1e"
     },
     {
-      "spdxElementId": "SPDXRef-Package-d5c0c7bb3c27968de167",
+      "spdxElementId": "SPDXRef-Package-9eec732cc29715c69e1e",
       "relationshipType": "DEPENDS_ON",
       "relatedSpdxElement": "SPDXRef-Package-5ce913a03239b02770fb"
     },
     {
-      "spdxElementId": "SPDXRef-Package-d5c0c7bb3c27968de167",
+      "spdxElementId": "SPDXRef-Package-9eec732cc29715c69e1e",
       "relationshipType": "DEPENDS_ON",
       "relatedSpdxElement": "SPDXRef-Package-01009adf60db02c13634"
     },
     {
-      "spdxElementId": "SPDXRef-Package-d5c0c7bb3c27968de167",
+      "spdxElementId": "SPDXRef-Package-9eec732cc29715c69e1e",
       "relationshipType": "DEPENDS_ON",
       "relatedSpdxElement": "SPDXRef-Package-8815b117c8a1d5f7eeb0"
     },
     {
-      "spdxElementId": "SPDXRef-Package-d5c0c7bb3c27968de167",
+      "spdxElementId": "SPDXRef-Package-9eec732cc29715c69e1e",
       "relationshipType": "DEPENDS_ON",
       "relatedSpdxElement": "SPDXRef-Package-f8b45a289df643042b94"
     },
     {
-      "spdxElementId": "SPDXRef-Package-d5c0c7bb3c27968de167",
+      "spdxElementId": "SPDXRef-Package-9eec732cc29715c69e1e",
       "relationshipType": "DEPENDS_ON",
       "relatedSpdxElement": "SPDXRef-Package-b779412f685822663496"
     },