@floegence/flowersec-core 2.3.10 → 2.4.1

package/README.md

@@ -29,10 +29,69 @@ The root type exports are:
 
 Retry ownership belongs to `ConnectionController`; applications do not classify error text or run a parallel retry scheduler. Public failures remain redacted and reveal no carrier, candidate, URL, credential, stage, key, or diagnostic details.
 
-`RpcResult<Response>` is a discriminated union. `RpcPeer.call(...)` requires a decoder for successful payloads, so the typed success value has passed application validation before it is returned. Check `result.ok` before reading either the typed success `payload` or bounded application `error`; a result cannot contain both. RPC call and notify are portable across SDKs. TypeScript `RpcPeer.onNotify(...)` receives peer outbound notifications through the local Session's inbound reserved RPC stream.
+`RpcResult<Response>` is a discriminated union. `RpcPeer.call(...)` requires a decoder for successful payloads, so the typed success value has passed application validation before it is returned. Check `result.ok` before reading either the typed success `payload` or bounded application `error`; a result cannot contain both. RPC call and notify accept only `JsonValue` payloads and reject values that cannot be represented on the wire before sending. TypeScript `RpcPeer.onNotify(typeId, decoder, handler)` receives peer outbound notifications through the local Session's inbound reserved RPC stream. A notification reaches the handler only after its decoder succeeds; decoder and handler failures are isolated from RPC serving.
 
 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/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

@@ -12,12 +12,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 +37,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 +145,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)
@@ -237,17 +292,17 @@ 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);
+        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;

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/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/contract.d.ts

@@ -42,9 +42,9 @@ export type RpcResult<Response = unknown> = Readonly<{
     }>;
 }>;
 export interface RpcPeer {
-    call<Request = unknown, Response = unknown>(typeId: number, payload: Request, decodeResponse: (payload: JsonValue) => Response, options?: OperationOptions): Promise<RpcResult<Response>>;
-    notify<Payload = unknown>(typeId: number, payload: Payload, options?: OperationOptions): Promise<void>;
-    onNotify<Payload = unknown>(typeId: number, handler: (payload: Payload) => void): () => void;
+    call<Request extends JsonValue = JsonValue, Response = unknown>(typeId: number, payload: Request, decodeResponse: (payload: JsonValue) => Response, options?: OperationOptions): Promise<RpcResult<Response>>;
+    notify<Payload extends JsonValue = JsonValue>(typeId: number, payload: Payload, options?: OperationOptions): Promise<void>;
+    onNotify<Payload>(typeId: number, decodePayload: (payload: JsonValue) => Payload, handler: (payload: Payload) => void | Promise<void>): () => void;
 }
 export interface ByteStream {
     readonly kind: string;

package/dist/v2/publicSession.js

@@ -2,8 +2,18 @@ import { SessionError } from "./contract.js";
 import { createStreamMetadataV2, streamMetadataValuesV2 } from "./streamMetadata.js";
 /** @internal */
 export function projectSessionV2(session) {
-    const rpc = projectRpcPeerV2(session.rpc);
+    const notificationOwner = {
+        subscriptions: new Set(),
+        closed: false,
+    };
+    const clearNotificationSubscriptions = () => {
+        notificationOwner.closed = true;
+        for (const unsubscribe of [...notificationOwner.subscriptions])
+            unsubscribe();
+    };
+    const rpc = projectRpcPeerV2(session.rpc, notificationOwner);
     const unreliable = session.unreliableMessages;
+    void session.termination.then(clearNotificationSubscriptions, clearNotificationSubscriptions);
     return Object.freeze({
         rpc,
         ...(unreliable === undefined ? {} : { unreliableMessages: unreliable }),
@@ -64,6 +74,9 @@ export function projectSessionV2(session) {
             catch (error) {
                 throw redactSessionError(error);
             }
+            finally {
+                clearNotificationSubscriptions();
+            }
         },
     });
 }
@@ -115,14 +128,16 @@ function projectByteStreamV2(stream) {
         },
     });
 }
-function projectRpcPeerV2(peer) {
+function projectRpcPeerV2(peer, notificationOwner) {
     return Object.freeze({
         async call(typeId, payload, decodeResponse, options) {
             try {
+                assertJsonValue(payload);
                 const result = await peer.call(typeId, payload, options?.signal);
                 if (result.error !== undefined) {
                     return Object.freeze({ ok: false, error: Object.freeze({ ...result.error }) });
                 }
+                assertJsonValue(result.payload);
                 return Object.freeze({ ok: true, payload: decodeResponse(result.payload) });
             }
             catch (error) {
@@ -131,6 +146,7 @@ function projectRpcPeerV2(peer) {
         },
         async notify(typeId, payload, options) {
             try {
+                assertJsonValue(payload);
                 if (options?.signal?.aborted)
                     throw options.signal.reason ?? new DOMException("The operation was aborted", "AbortError");
                 await raceWithSignal(peer.notify(typeId, payload), options?.signal);
@@ -139,11 +155,75 @@ function projectRpcPeerV2(peer) {
                 throw redactSessionError(error);
             }
         },
-        onNotify(typeId, handler) {
-            return peer.onNotify(typeId, (payload) => handler(payload));
+        onNotify(typeId, decodePayload, handler) {
+            if (notificationOwner.closed)
+                return () => undefined;
+            const unsubscribe = peer.onNotify(typeId, (payload) => {
+                let decoded;
+                try {
+                    assertJsonValue(payload);
+                    decoded = decodePayload(payload);
+                }
+                catch {
+                    return;
+                }
+                try {
+                    void Promise.resolve(handler(decoded)).catch(() => undefined);
+                }
+                catch {
+                    // Notification handlers are isolated from RPC serving.
+                }
+            });
+            let subscribed = true;
+            const cancel = () => {
+                if (!subscribed)
+                    return;
+                subscribed = false;
+                notificationOwner.subscriptions.delete(cancel);
+                unsubscribe();
+            };
+            notificationOwner.subscriptions.add(cancel);
+            return cancel;
         },
     });
 }
+function assertJsonValue(value) {
+    validateJsonValue(value, new Set());
+}
+function validateJsonValue(value, ancestors) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return;
+    if (typeof value === "number") {
+        if (Number.isFinite(value))
+            return;
+        throw new TypeError("RPC payload contains a non-finite number");
+    }
+    if (typeof value !== "object")
+        throw new TypeError("RPC payload is not a JSON value");
+    if (ancestors.has(value))
+        throw new TypeError("RPC payload contains a cycle");
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            for (let index = 0; index < value.length; index += 1) {
+                if (!(index in value))
+                    throw new TypeError("RPC payload contains a sparse array");
+                validateJsonValue(value[index], ancestors);
+            }
+            return;
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError("RPC payload contains a non-JSON object");
+        }
+        for (const key of Object.keys(value)) {
+            validateJsonValue(value[key], ancestors);
+        }
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
 async function raceWithSignal(operation, signal) {
     if (signal === undefined)
         return await operation;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floegence/flowersec-core",
-  "version": "2.3.10",
+  "version": "2.4.1",
   "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.3.10"
+    "@floegence/flowersec-node-native": "2.4.1"
   },
   "devDependencies": {
     "@playwright/test": "1.62.1",
@@ -95,5 +95,5 @@
     "vite": "^8.2.1",
     "vitest": "4.1.10"
   },
-  "flowersecSourceCommit": "67e5ff521e77982e4f57e8ba5eb858df3e48c886"
+  "flowersecSourceCommit": "3605cb0c32551ec5bc2f799cd2e086c5c3102177"
 }

package/sbom/cyclonedx.json

@@ -1,20 +1,20 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:2ff806a3-4e32-5ae7-867b-3dc94826ed55",
+  "serialNumber": "urn:uuid:1b2d0f50-da64-544b-8761-aaf9dd5a7c79",
   "version": 1,
   "metadata": {
     "component": {
       "type": "library",
       "name": "@floegence/flowersec-core",
-      "version": "2.3.10",
-      "purl": "pkg:npm/%40floegence/flowersec-core@2.3.10",
-      "bom-ref": "pkg:npm/%40floegence/flowersec-core@2.3.10"
+      "version": "2.4.1",
+      "purl": "pkg:npm/%40floegence/flowersec-core@2.4.1",
+      "bom-ref": "pkg:npm/%40floegence/flowersec-core@2.4.1"
     },
     "properties": [
       {
         "name": "flowersec:source-inventory-sha256",
-        "value": "36475d4f06355a764285462713f086777546ed34fe2ea5911961d9bb9a3037f1"
+        "value": "661d332941b82dbf168619a507636c87c3d13befebe1b70ddec45674655e1941"
       }
     ]
   },
@@ -190,7 +190,7 @@
   ],
   "dependencies": [
     {
-      "ref": "pkg:npm/%40floegence/flowersec-core@2.3.10",
+      "ref": "pkg:npm/%40floegence/flowersec-core@2.4.1",
       "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/36475d4f06355a764285462713f086777546ed34fe2ea5911961d9bb9a3037f1",
+  "documentNamespace": "https://github.com/floegence/flowersec/sbom/flowersec-ts/661d332941b82dbf168619a507636c87c3d13befebe1b70ddec45674655e1941",
   "creationInfo": {
     "created": "1970-01-01T00:00:00Z",
     "creators": [
@@ -13,19 +13,19 @@
   "packages": [
     {
       "name": "@floegence/flowersec-core",
-      "SPDXID": "SPDXRef-Package-bd5ff7d2005890830d32",
-      "versionInfo": "2.3.10",
+      "SPDXID": "SPDXRef-Package-4eeba6fa52c374d21b02",
+      "versionInfo": "2.4.1",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
       "licenseDeclared": "NOASSERTION",
       "copyrightText": "NOASSERTION",
-      "comment": "Flowersec source inventory SHA-256: 36475d4f06355a764285462713f086777546ed34fe2ea5911961d9bb9a3037f1",
+      "comment": "Flowersec source inventory SHA-256: 661d332941b82dbf168619a507636c87c3d13befebe1b70ddec45674655e1941",
       "externalRefs": [
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40floegence/flowersec-core@2.3.10"
+          "referenceLocator": "pkg:npm/%40floegence/flowersec-core@2.4.1"
         }
       ]
     },
@@ -136,30 +136,30 @@
     {
       "spdxElementId": "SPDXRef-DOCUMENT",
       "relationshipType": "DESCRIBES",
-      "relatedSpdxElement": "SPDXRef-Package-bd5ff7d2005890830d32"
+      "relatedSpdxElement": "SPDXRef-Package-4eeba6fa52c374d21b02"
     },
     {
-      "spdxElementId": "SPDXRef-Package-bd5ff7d2005890830d32",
+      "spdxElementId": "SPDXRef-Package-4eeba6fa52c374d21b02",
       "relationshipType": "DEPENDS_ON",
       "relatedSpdxElement": "SPDXRef-Package-5ce913a03239b02770fb"
     },
     {
-      "spdxElementId": "SPDXRef-Package-bd5ff7d2005890830d32",
+      "spdxElementId": "SPDXRef-Package-4eeba6fa52c374d21b02",
       "relationshipType": "DEPENDS_ON",
       "relatedSpdxElement": "SPDXRef-Package-01009adf60db02c13634"
     },
     {
-      "spdxElementId": "SPDXRef-Package-bd5ff7d2005890830d32",
+      "spdxElementId": "SPDXRef-Package-4eeba6fa52c374d21b02",
       "relationshipType": "DEPENDS_ON",
       "relatedSpdxElement": "SPDXRef-Package-8815b117c8a1d5f7eeb0"
     },
     {
-      "spdxElementId": "SPDXRef-Package-bd5ff7d2005890830d32",
+      "spdxElementId": "SPDXRef-Package-4eeba6fa52c374d21b02",
       "relationshipType": "DEPENDS_ON",
       "relatedSpdxElement": "SPDXRef-Package-f8b45a289df643042b94"
     },
     {
-      "spdxElementId": "SPDXRef-Package-bd5ff7d2005890830d32",
+      "spdxElementId": "SPDXRef-Package-4eeba6fa52c374d21b02",
       "relationshipType": "DEPENDS_ON",
       "relatedSpdxElement": "SPDXRef-Package-b779412f685822663496"
     },