@floegence/flowersec-core 2.4.1 → 2.5.0

package/README.md

@@ -65,6 +65,20 @@ 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.
 
+### Application streams on any Session
+
+```ts
+import { StreamHandlers } from "@floegence/flowersec-core";
+
+const streamHandlers = new StreamHandlers({ maxConcurrentStreams: 32 });
+streamHandlers.handleStream("files/read", async (incoming) => serveFile(incoming));
+await streamHandlers.serve(session);
+```
+
+The portable root, browser, and Node entrypoints share this dispatcher. The
+sealed registrar used by Node `ProxyServer.register(...)` is exported only from
+the Node entrypoint.
+
 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
@@ -98,7 +112,7 @@ The Browser and Node `connect(...)` operations are one-shot and never reconnect.
 
 The controller has one scheduler and one in-flight attempt. Its states are `idle`, `connecting`, `connected`, `waiting`, `failed`, and `closed`; immutable snapshots expose `ConnectionSnapshot.retryDisposition` while the corresponding retry decision applies and clear it before a new attempt, after connection, and on close. Call `start()` once, observe snapshots with `subscribe(...)`, await an established session with `waitForSession(...)`, and use `retryNow()` only to wake a `waiting` controller. `close()` cancels acquisition, connection, and waiting before closing the current session.
 
-Node `SessionHandlers` accept application stream kinds whose UTF-8 encoding is 1 through 255 bytes and reserve `flowersec.rpc.v2` for Flowersec RPC. `AcceptedSession.serve(...)` half-closes successfully handled streams. A rejected handler Promise resets only that stream; the accept loop and unrelated streams continue.
+`StreamHandlers` and Node `SessionHandlers` accept application stream kinds containing 1 through 128 canonical UTF-8 bytes, reject leading or trailing Unicode whitespace, controls, and unassigned scalars, and reserve `flowersec.rpc.v2` for Flowersec RPC. Successful handlers half-close their stream. A rejected handler Promise resets only that stream; the accept loop and unrelated streams continue.
 
 Reliable streams apply bounded per-stream receive backpressure instead of buffering application data without limit. A slow consumer pauses carrier progress until reads release capacity; records retain carrier order, so a rekey behind backpressured DATA completes after the consumer resumes. `closeWrite()` sends the graceful FIN and keeps reads available. `reset()` and `close()` abort both directions. If a write is canceled or fails after its wire commit may have started, only that stream becomes terminal and cannot be reused.
 

package/dist/facade.d.ts

@@ -2,6 +2,8 @@ export type { ByteStream, IncomingStream, JsonObject, JsonPrimitive, JsonValue,
 export { SessionError, UnreliableMessageError } from "./public/contract.js";
 export { createStreamMetadata, StreamMetadataError } from "./public/streamMetadata.js";
 export type { StreamMetadata } from "./public/streamMetadata.js";
+export { HandlerRegistrationError, StreamHandlers, } from "./public/streamHandlers.js";
+export type { StreamHandler, StreamHandlerOptions, } from "./public/streamHandlers.js";
 export { ArtifactLeaseError, createArtifactLease, } from "./public/artifactLease.js";
 export type { ArtifactLease } from "./public/artifactLease.js";
 export { Artifact, ArtifactError, parseArtifact } from "./public/artifact.js";

package/dist/facade.js

@@ -1,5 +1,6 @@
 export { SessionError, UnreliableMessageError } from "./public/contract.js";
 export { createStreamMetadata, StreamMetadataError } from "./public/streamMetadata.js";
+export { HandlerRegistrationError, StreamHandlers, } from "./public/streamHandlers.js";
 export { ArtifactLeaseError, createArtifactLease, } from "./public/artifactLease.js";
 export { Artifact, ArtifactError, parseArtifact } from "./public/artifact.js";
 export { ConnectError } from "./public/connectError.js";

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

@@ -1,6 +1,9 @@
-import { type IncomingStream, type JsonValue, type OperationOptions, type Session } from "../public/contract.js";
+import { type JsonValue, type OperationOptions, type Session } from "../public/contract.js";
 import { type DirectAuthorizationDecision, type RuntimeAuthorizationRequest } from "./controlplane.js";
+import { type StreamHandler, type StreamHandlerOptions } from "../public/streamHandlers.js";
 export type { RuntimeAuthorizationRequest } from "./controlplane.js";
+export { HandlerRegistrationError } from "../public/streamHandlers.js";
+export type { StreamHandler } from "../public/streamHandlers.js";
 export type AuthorizationDecision = DirectAuthorizationDecision;
 export type RPCHandlerResult = Readonly<{
     payload: JsonValue;
@@ -16,20 +19,14 @@ export type RPCHandler = (payload: JsonValue, request: Readonly<{
 export type NotificationHandler = (payload: JsonValue, request: Readonly<{
     typeId: number;
 }>) => Promise<void> | void;
-export type StreamHandler = (incoming: IncomingStream, options: OperationOptions) => Promise<void>;
-export type SessionHandlerOptions = Readonly<{
-    maxConcurrentStreams?: number;
-}>;
-export declare class HandlerRegistrationError extends Error {
-    readonly code: "invalid_handler" | "already_registered" | "frozen";
-    constructor(code: "invalid_handler" | "already_registered" | "frozen");
-}
+export type SessionHandlerOptions = StreamHandlerOptions;
 export declare class RPCHandlers {
     constructor();
     handleRPC(typeId: number, handler: RPCHandler): void;
     handleNotification(typeId: number, handler: NotificationHandler): void;
 }
 export declare class SessionHandlers {
+    private readonly streamHandlerRegistrarBrand;
     constructor(options?: SessionHandlerOptions);
     handleRPC(typeId: number, handler: RPCHandler): void;
     handleNotification(typeId: number, handler: NotificationHandler): void;

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";
@@ -8,18 +9,9 @@ import { unwrapArtifact } from "../public/artifact.js";
 import { SessionError, } from "../public/contract.js";
 import { projectSessionV2 } from "../v2/publicSession.js";
 import { runtimeAuthorizationRequestFromDecoded, } from "./controlplane.js";
-const DEFAULT_MAX_CONCURRENT_STREAMS = 64;
-const MAX_CONCURRENT_STREAMS = 128;
+import { HandlerRegistrationError, StreamHandlers, freezeStreamHandlers, registerStreamHandlersAtomically, serveFrozenStreamHandlers, } from "../public/streamHandlers.js";
+export { HandlerRegistrationError } from "../public/streamHandlers.js";
 const DEFAULT_CLEANUP_TIMEOUT_MS = 2_000;
-const encoder = new TextEncoder();
-export class HandlerRegistrationError extends Error {
-    code;
-    constructor(code) {
-        super(`Flowersec handler registration failed (code=${code})`);
-        this.code = code;
-        this.name = "HandlerRegistrationError";
-    }
-}
 export class RPCHandlers {
     constructor() {
         rpcHandlerStates.set(this, createRPCHandlerState());
@@ -33,16 +25,9 @@ export class RPCHandlers {
 }
 export class SessionHandlers {
     constructor(options = {}) {
-        const maximum = options.maxConcurrentStreams ?? DEFAULT_MAX_CONCURRENT_STREAMS;
-        if (!Number.isSafeInteger(maximum) ||
-            maximum < 1 ||
-            maximum > MAX_CONCURRENT_STREAMS) {
-            throw new HandlerRegistrationError("invalid_handler");
-        }
         sessionHandlerStates.set(this, {
-            maxConcurrentStreams: maximum,
             rpc: createRPCHandlerState(),
-            streams: new Map(),
+            streams: new StreamHandlers(options),
             frozen: false,
         });
     }
@@ -56,15 +41,7 @@ export class SessionHandlers {
     }
     handleStream(kind, handler) {
         const state = mutableSessionHandlerState(this);
-        if (kind.length < 1 ||
-            encoder.encode(kind).length > 255 ||
-            kind === "flowersec.rpc.v2" ||
-            typeof handler !== "function") {
-            throw new HandlerRegistrationError("invalid_handler");
-        }
-        if (state.streams.has(kind))
-            throw new HandlerRegistrationError("already_registered");
-        state.streams.set(kind, handler);
+        state.streams.handleStream(kind, handler);
     }
 }
 const rpcHandlerStates = new WeakMap();
@@ -88,6 +65,11 @@ function mutableSessionHandlerState(handlers) {
         throw new HandlerRegistrationError("frozen");
     return state;
 }
+/** @internal */
+export function registerSessionStreamHandlersAtomically(handlers, entries) {
+    const state = mutableSessionHandlerState(handlers);
+    registerStreamHandlersAtomically(state.streams, entries);
+}
 function registerRPC(state, typeId, handler) {
     validateRPCRegistration(typeId, handler);
     if (state.requests.has(typeId) || state.notifications.has(typeId)) {
@@ -161,63 +143,18 @@ function freezeSessionHandlers(handlers) {
     state.frozen = true;
     state.snapshot = Object.freeze({
         rpc: freezeRPCHandlerState(state.rpc),
-        maxConcurrentStreams: state.maxConcurrentStreams,
-        streams: new Map(state.streams),
+        streams: freezeStreamHandlers(state.streams),
     });
     return state.snapshot;
 }
-/** @internal */
-export function registerSessionStreamsAtomically(handlers, entries) {
-    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 HandlerRegistrationError("invalid_handler");
-        if (state.streams.has(kind) || pending.has(kind))
-            throw new HandlerRegistrationError("already_registered");
-        pending.add(kind);
-    }
-    for (const [kind, handler] of entries)
-        state.streams.set(kind, handler);
-}
 export class AcceptedSession {
     constructor() { }
     get session() {
         return acceptedSessionState(this).session;
     }
     async serve(options = {}) {
-        const active = new Set();
         const state = acceptedSessionState(this);
-        try {
-            while (true) {
-                if (options.signal?.aborted)
-                    throw new SessionError("canceled");
-                const incoming = await this.session.acceptStream(options);
-                const handler = state.handlers.streams.get(incoming.kind);
-                if (handler === undefined ||
-                    active.size >= state.handlers.maxConcurrentStreams) {
-                    await incoming.stream.reset();
-                    continue;
-                }
-                const task = (async () => {
-                    try {
-                        await handler(incoming, options);
-                        await incoming.stream.closeWrite();
-                    }
-                    catch {
-                        await incoming.stream.reset().catch(() => undefined);
-                    }
-                })().finally(() => active.delete(task));
-                active.add(task);
-            }
-        }
-        finally {
-            await this.close().catch(() => undefined);
-            await Promise.allSettled(active);
-        }
+        await serveFrozenStreamHandlers(state.handlers.streams, this.session, options, async () => await this.close());
     }
     async close() {
         const state = acceptedSessionState(this);
@@ -264,11 +201,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) {
@@ -280,7 +233,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,
@@ -294,9 +247,7 @@ async function authorizeCarrier(state, carrier) {
     try {
         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,
@@ -326,28 +277,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) {
@@ -362,16 +335,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) {
@@ -412,6 +388,7 @@ class AcceptedQueue {
     }
     close() {
         this.fail(new SessionError("closed"));
+        return this.values.splice(0);
     }
 }
 const acceptorStates = new WeakMap();
@@ -482,6 +459,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,
@@ -490,7 +468,9 @@ export async function createAcceptor(options) {
         accepted,
         abort,
         tasks,
+        admissions,
         cleanupTimeoutMs,
+        lifecycle: { cleanupFailed: false },
         start() {
             if (started)
                 return;
@@ -502,52 +482,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/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,11 +1,11 @@
 export { connect, createConnectionController } from "./connectSession.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 type { AcceptorListener, AcceptorOptions, AuthorizationDecision, RPCHandler, RPCHandlerResult, NotificationHandler, SessionHandlerOptions, } from "./acceptor.js";
 export { TunnelRuntime, createTunnelRuntime } from "./tunnelRuntime.js";
 export type { TunnelAuthorizationDecision, TunnelRuntimeListener, TunnelRuntimeOptions, } from "./tunnelRuntime.js";
 export type { ConnectionControllerOptions, SessionOptions, SessionTLSOptions, } from "./connectSession.js";
 export { AuthorizationRecord, AuthorizationResponse, TunnelAuthorizationResponse, ControlPlaneError, EndpointSet, IssuedArtifact, Issuer, RuntimeAuthorizationRequest, authorizeRuntime, authorizeTunnelRuntime, createEndpointSet, parseAuthorizationRecord, parseRuntimeAuthorizationRequest, rejectRuntime, rejectTunnelRuntime, } from "./controlplane.js";
 export type { ArtifactMetadata, ControlPlaneErrorCode, DirectIssueOptions, IssuedTunnelPair, Scope, SessionOptions as ControlPlaneSessionOptions, TunnelIssueOptions, } from "./controlplane.js";
 export { ProxyServer, ProxyServerError } from "./proxyServer.js";
-export type { ProxyServerOptions } from "./proxyServer.js";
+export type { ProxyServerOptions, StreamHandlerRegistrar } from "./proxyServer.js";
 export * from "../facade.js";

package/dist/node/proxyServer.d.ts

@@ -1,4 +1,6 @@
+import { StreamHandlers } from "../public/streamHandlers.js";
 import { SessionHandlers } from "./acceptor.js";
+export type StreamHandlerRegistrar = StreamHandlers | SessionHandlers;
 export type ProxyServerOptions = Readonly<{
     upstream: string;
     upstreamOrigin: string;
@@ -26,6 +28,6 @@ export declare class ProxyServerError extends Error {
 export declare class ProxyServer {
     #private;
     constructor(options: ProxyServerOptions);
-    register(handlers: SessionHandlers): void;
+    register(handlers: StreamHandlerRegistrar): void;
     close(): Promise<void>;
 }

package/dist/node/proxyServer.js

@@ -2,7 +2,8 @@ import { createRequire } from "node:module";
 import { SessionError } from "../public/contract.js";
 import { writeJsonFrame } from "../framing/jsonframe.js";
 import { ProxyByteReader, writeAll } from "../proxy/stream.js";
-import { registerSessionStreamsAtomically, SessionHandlers, } from "./acceptor.js";
+import { StreamHandlers, registerStreamHandlersAtomically, } from "../public/streamHandlers.js";
+import { SessionHandlers, registerSessionStreamHandlersAtomically, } from "./acceptor.js";
 const HTTP_KIND = "flowersec-proxy/http1";
 const WS_KIND = "flowersec-proxy/ws";
 const WIRE_VERSION = 1;
@@ -38,13 +39,20 @@ export class ProxyServer {
     register(handlers) {
         if (this.#closed)
             throw new ProxyServerError("closed");
-        if (!(handlers instanceof SessionHandlers))
-            throw new ProxyServerError("handler_registration");
         try {
-            registerSessionStreamsAtomically(handlers, [
+            const registrations = [
                 [HTTP_KIND, this.#httpHandler()],
                 [WS_KIND, this.#webSocketHandler()],
-            ]);
+            ];
+            if (handlers instanceof StreamHandlers) {
+                registerStreamHandlersAtomically(handlers, registrations);
+            }
+            else if (handlers instanceof SessionHandlers) {
+                registerSessionStreamHandlersAtomically(handlers, registrations);
+            }
+            else {
+                throw new TypeError("invalid Flowersec stream handler registrar");
+            }
         }
         catch (error) {
             this.#report(error);

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

@@ -0,0 +1,20 @@
+import { type IncomingStream, type OperationOptions, type Session } from "./contract.js";
+export type StreamHandler = (incoming: IncomingStream, options: OperationOptions) => Promise<void>;
+export type StreamHandlerOptions = Readonly<{
+    maxConcurrentStreams?: number;
+}>;
+export declare class HandlerRegistrationError extends Error {
+    readonly code: "invalid_handler" | "already_registered" | "frozen";
+    constructor(code: "invalid_handler" | "already_registered" | "frozen");
+}
+export type FrozenStreamHandlers = Readonly<{
+    maxConcurrentStreams: number;
+    streams: ReadonlyMap<string, StreamHandler>;
+}>;
+/** Carrier-neutral application-stream handlers for any established Session. */
+export declare class StreamHandlers {
+    private readonly streamHandlerRegistrarBrand;
+    constructor(options?: StreamHandlerOptions);
+    handleStream(kind: string, handler: StreamHandler): void;
+    serve(session: Session, options?: OperationOptions): Promise<void>;
+}

package/dist/public/streamHandlers.js

@@ -0,0 +1,124 @@
+import { SessionError, } from "./contract.js";
+import { validApplicationStreamKind } from "../v2/protocol.js";
+const DEFAULT_MAX_CONCURRENT_STREAMS = 64;
+const MAX_CONCURRENT_STREAMS = 128;
+export class HandlerRegistrationError extends Error {
+    code;
+    constructor(code) {
+        super(`Flowersec handler registration failed (code=${code})`);
+        this.code = code;
+        this.name = "HandlerRegistrationError";
+    }
+}
+const streamHandlerStates = new WeakMap();
+/** Carrier-neutral application-stream handlers for any established Session. */
+export class StreamHandlers {
+    constructor(options = {}) {
+        const maximum = options.maxConcurrentStreams ?? DEFAULT_MAX_CONCURRENT_STREAMS;
+        if (!Number.isSafeInteger(maximum) ||
+            maximum < 1 ||
+            maximum > MAX_CONCURRENT_STREAMS) {
+            throw new HandlerRegistrationError("invalid_handler");
+        }
+        streamHandlerStates.set(this, {
+            maxConcurrentStreams: maximum,
+            streams: new Map(),
+            frozen: false,
+        });
+    }
+    handleStream(kind, handler) {
+        registerStreamHandlersAtomically(this, [[kind, handler]]);
+    }
+    async serve(session, options = {}) {
+        if (session === null || typeof session !== "object") {
+            throw new HandlerRegistrationError("invalid_handler");
+        }
+        await serveFrozenStreamHandlers(freezeStreamHandlers(this), session, options, async () => await session.close());
+    }
+}
+function mutableStreamHandlerState(handlers) {
+    const state = streamHandlerStates.get(handlers);
+    if (state === undefined)
+        throw new HandlerRegistrationError("invalid_handler");
+    if (state.frozen)
+        throw new HandlerRegistrationError("frozen");
+    return state;
+}
+function registerIntoState(state, entries) {
+    if (entries.length === 0)
+        throw new HandlerRegistrationError("invalid_handler");
+    const pending = new Set();
+    for (const [kind, handler] of entries) {
+        if (!validApplicationStreamKind(kind) ||
+            kind === "flowersec.rpc.v2" ||
+            typeof handler !== "function") {
+            throw new HandlerRegistrationError("invalid_handler");
+        }
+        if (state.streams.has(kind) || pending.has(kind)) {
+            throw new HandlerRegistrationError("already_registered");
+        }
+        pending.add(kind);
+    }
+    for (const [kind, handler] of entries)
+        state.streams.set(kind, handler);
+}
+/** @internal */
+export function registerStreamHandlersAtomically(handlers, entries) {
+    registerIntoState(mutableStreamHandlerState(handlers), entries);
+}
+/** @internal */
+export function freezeStreamHandlers(handlers) {
+    const state = streamHandlerStates.get(handlers);
+    if (state === undefined)
+        throw new HandlerRegistrationError("invalid_handler");
+    if (state.snapshot !== undefined)
+        return state.snapshot;
+    state.frozen = true;
+    state.snapshot = Object.freeze({
+        maxConcurrentStreams: state.maxConcurrentStreams,
+        streams: new Map(state.streams),
+    });
+    return state.snapshot;
+}
+/** @internal */
+export async function serveFrozenStreamHandlers(snapshot, session, options, close) {
+    const active = new Set();
+    const controller = new AbortController();
+    const abortFromCaller = () => controller.abort(options.signal?.reason);
+    if (options.signal?.aborted === true)
+        abortFromCaller();
+    else
+        options.signal?.addEventListener("abort", abortFromCaller, { once: true });
+    const handlerOptions = Object.freeze({
+        signal: controller.signal,
+    });
+    try {
+        while (true) {
+            if (controller.signal.aborted)
+                throw new SessionError("canceled");
+            const incoming = await session.acceptStream(handlerOptions);
+            const handler = snapshot.streams.get(incoming.kind);
+            if (handler === undefined ||
+                active.size >= snapshot.maxConcurrentStreams) {
+                await incoming.stream.reset();
+                continue;
+            }
+            const task = (async () => {
+                try {
+                    await handler(incoming, handlerOptions);
+                    await incoming.stream.closeWrite();
+                }
+                catch {
+                    await incoming.stream.reset().catch(() => undefined);
+                }
+            })().finally(() => active.delete(task));
+            active.add(task);
+        }
+    }
+    finally {
+        options.signal?.removeEventListener("abort", abortFromCaller);
+        controller.abort(new SessionError("closed"));
+        await close().catch(() => undefined);
+        await Promise.allSettled(active);
+    }
+}

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/dist/v2/protocol.js

@@ -567,16 +567,21 @@ function bytesEqual(left, right) {
 }
 function validateOpenKind(value) {
     const encoded = encoder.encode(value);
-    if (!validOpenUnicodeString(value, MAX_OPEN_KIND_BYTES, false)) {
+    if (!validApplicationStreamKind(value)) {
         throw new ProtocolV2Error("invalid OPEN kind");
     }
-    const scalars = Array.from(value);
-    if (isUnicodeWhitespace(scalars[0].codePointAt(0)) ||
-        isUnicodeWhitespace(scalars.at(-1).codePointAt(0))) {
-        throw new ProtocolV2Error("OPEN kind has leading or trailing Unicode whitespace");
-    }
     return encoded;
 }
+/** @internal */
+export function validApplicationStreamKind(value) {
+    if (typeof value !== "string" ||
+        !validOpenUnicodeString(value, MAX_OPEN_KIND_BYTES, false)) {
+        return false;
+    }
+    const scalars = Array.from(value);
+    return !(isUnicodeWhitespace(scalars[0].codePointAt(0)) ||
+        isUnicodeWhitespace(scalars.at(-1).codePointAt(0)));
+}
 function canonicalMetadata(raw, allowEmpty) {
     if (raw.length === 0 && allowEmpty)
         return encoder.encode("{}");

package/package.json

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

package/sbom/cyclonedx.json

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