@floegence/flowersec-core 2.5.3 → 3.0.0

package/README.md

@@ -15,7 +15,7 @@ npm install @floegence/flowersec-core
 
 - `@floegence/flowersec-core` exports the portable artifact, lease, session, stream, RPC, stream-metadata, and connection-controller API, plus profile-owned unreliable messages when negotiated.
 - `@floegence/flowersec-core/browser` adds `connect(...)`, `createConnectionController(...)`, and their options.
-- `@floegence/flowersec-core/node` adds `connect(...)`, `createConnectionController(...)`, direct-only `createAcceptor(...)`, opaque `createTunnelRuntime(...)`, `SessionHandlers`, `AcceptedSession`, `Issuer`, authorization record/request/response types, `authorizeRuntime(...)`, `authorizeTunnelRuntime(...)`, and `ProxyServer`.
+- `@floegence/flowersec-core/node` adds the V3 `connect(...)`, `createConnectionController(...)`, direct-only `createAcceptor(...)`, opaque `createTunnelRuntime(...)`, `AcceptedSession`, `SessionHandlers`, and `RPCHandlers` APIs. Legacy V2 server, control-plane, and `ProxyServer` APIs are available only under the explicit `node.v2` namespace.
 - `@floegence/flowersec-core/proxy` adds the `Session`-based HTTP/WebSocket runtime, Service Worker and controller/app-window bridges, strict `proxy.runtime@2` validation, and `connectProxyBrowser(...)` composition.
 
 The root type exports are:
@@ -31,7 +31,7 @@ Retry ownership belongs to `ConnectionController`; applications do not classify
 
 `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.
+Browser and Node.js connector options accept `connectTimeoutMs`; omitting it uses the shared ten-second default.
 
 ### One-shot Node client
 
@@ -82,7 +82,10 @@ 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
-candidates. Secure raw QUIC still requires an explicit `tls.ca` trust root.
+candidates. CA candidates use platform or deployment-provided trust roots;
+pin candidates use only the complete active leaf-certificate SHA-256 pin set
+embedded in the opaque artifact. The connector never fetches pins or falls
+back between CA and pin modes.
 
 ### Accepted Node server Session
 
@@ -96,15 +99,30 @@ handlers.handleStream("files/read", async (incoming) => serveFile(incoming));
 const acceptor = await createAcceptor({
   listeners,
   maxInboundStreams: 32,
-  authorize,
+  admissionTimeoutMs: 10_000,
+  authorize: async (request, options) => ({
+    accepted: true,
+    artifact: await loadAuthorizedArtifact(request, options),
+  }),
   resolveHandlers: () => handlers,
 });
 const accepted = await acceptor.accept();
 await accepted.serve();
 ```
 
+`loadAuthorizedArtifact(...)` returns the opaque `Artifact` produced by
+`parseArtifact(...)`; authorization code never reconstructs or receives
+package-private PSK, candidate, or pin fields. Tunnel authorization verifies
+that artifact with `verifyTunnelAuthorizationGrant(...)` and returns only the
+request-bound, secret-free grant consumed by the relay.
+The admission deadline covers FSB3 receive, authorization, handler resolution,
+FSA3 completion, and Session establishment. Tunnel allow decisions return the
+secret-free grant; the trusted verifier performs the full FSB3 projection while
+the relay remains unable to inspect the artifact or its E2EE session fields.
+
 `RPCHandlers` is available only from the Node entrypoint and cannot register
-application streams. `SessionHandlers` is accepted-server-only.
+application streams. The default `SessionHandlers` is strict v3 and
+accepted-server-only; the v2 registry remains under `node.v2.SessionHandlers`.
 
 ## Connection Lifecycle
 
@@ -112,7 +130,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.
 
-`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.
+`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 the package-owned `flowersec.rpc.v2` and `flowersec.rpc.v3` names 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.
 
@@ -132,9 +150,10 @@ server sessions, and opaque `TunnelRuntime` relay legs. Raw QUIC uses the
 Flowersec-owned optional native addon wrapper and one of its supported
 prebuilt platform packages; it never loads from the browser entrypoint. The
 wrapper selects the matching optional package for macOS arm64/x64 or Linux
-arm64/x64 glibc. Windows and musl packages are not published. The same Node entrypoint provides the
-control plane and `ProxyServer`, and the relay never terminates an E2EE
-Session. WebTransport is an optional adapter profile and the Node.js runtime
+arm64/x64 glibc. Windows and musl packages are not published. The V3 Node
+entrypoint keeps the control plane and `ProxyServer` behind `node.v2`; the
+relay never terminates an E2EE Session. WebTransport is an optional adapter
+profile and the Node.js runtime
 does not currently expose a production adapter.
 The `/proxy` entrypoint adds browser bridges for applications that need to keep
 the session behind a Service Worker or another window.
@@ -143,6 +162,14 @@ the session behind a Service Worker or another window.
 
 `Artifact` is an opaque handle. Applications cannot inspect its connection data or serialize it back to protocol JSON. `ArtifactLease` exposes no spend operation; only the connector may invoke the durable callback. `Session` exposes RPC, stream operations, liveness, rekeying, `waitTermination()`, and closure without revealing the selected transport or peer endpoint identity. Public streams expose their kind and terminal state, but no protocol stream identifier.
 
+A Node tunnel authorizer returns an allow decision only after calling
+`verifyTunnelAuthorizationGrant(request, artifact, { leaseId, allowReplacement })`.
+The verifier compares the complete observed FSB3 with the opaque authorization
+artifact and mints a request-bound, secret-free `TunnelAuthorizationGrant`.
+The relay runtime retains only that grant; a structurally similar ordinary
+object is not an authorization and the relay never unwraps or retains the
+artifact's E2EE key material.
+
 `ConnectError` and `SessionError` expose only a closed `code`. They do not retain raw causes, credentials, URLs, candidate diagnostics, transport objects, peer details, or internal routing and handshake state.
 
 Connection negotiation and cryptographic state are not package exports.
@@ -154,20 +181,21 @@ The proxy entrypoint accepts an opaque `ArtifactLease` or an already connected `
 ## Connection Notes
 
 Browser applications receive a ready `Session` from `connect(...)`. The browser
-connector supports WSS, restricted plaintext loopback WebSocket direct
-connections, and WebTransport when the browser exposes that API. WebTransport
-uses browser-owned HTTP/3 streams and is not available in the Node entrypoint.
+connector supports CA-authenticated WSS and pinned WebTransport when the
+browser exposes that API. WebTransport uses browser-owned HTTP/3 streams and
+is not available in the Node entrypoint. Production v3 accepts no plaintext
+carrier.
 
 Chromium does not support a WebTransport pooling option; each carrier creates an independent native WebTransport connection.
 
 Cold-connection diagnostics require every independent carrier to meet the declared deadline. A `dial_failed` result remains a test failure and is not hidden by pooling, retry, or timeout relaxation.
 
 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. 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 Node connector supports WSS and raw QUIC through the optional native
+package. WebSocket candidates require an absolute HTTP(S) `origin`;
+raw-QUIC-only artifacts may omit it. CA candidates use platform or configured
+private roots. Pin candidates use their artifact-bound pin set and never
+downgrade to CA after a verification failure.
 
 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.
@@ -180,4 +208,4 @@ npm test
 npm run verify:package
 ```
 
-See the [API contract](../docs/API_CONTRACT.md), [Transport v2 architecture](../docs/TRANSPORT_V2_ARCHITECTURE.md), [threat model](../docs/THREAT_MODEL.md), and [error model](../docs/ERROR_MODEL.md).
+See the [API contract](../docs/API_CONTRACT.md), [Transport v3 architecture](../docs/TRANSPORT_V3_ARCHITECTURE.md), [v3 wire contract](../docs/TRANSPORT_V3_WIRE.md), [threat model](../docs/THREAT_MODEL.md), and [error model](../docs/ERROR_MODEL.md).

package/dist/browser/connectSessionV3.d.ts

@@ -0,0 +1,13 @@
+import type { Session } from "../public/contract.js";
+import type { ArtifactLeaseV3 } from "../v3/artifactLease.js";
+import { type ArtifactSourceV3, type ConnectionControllerV3 } from "../v3/connectionController.js";
+export type SessionOptionsV3 = Readonly<{
+    signal?: AbortSignal;
+    connectTimeoutMs?: number;
+}>;
+export type ConnectionControllerOptionsV3 = Readonly<{
+    maximumAttempts?: number;
+    connectTimeoutMs?: number;
+}>;
+export declare function connectV3(lease: ArtifactLeaseV3, options?: SessionOptionsV3): Promise<Session>;
+export declare function createConnectionControllerV3(source: ArtifactSourceV3, options?: ConnectionControllerOptionsV3): Promise<ConnectionControllerV3<Session>>;

package/dist/browser/connectSessionV3.js

@@ -0,0 +1,75 @@
+import { SDK_DEFAULTS } from "../defaults.js";
+import { createConnectionControllerV3 as createCoreControllerV3, } from "../v3/connectionController.js";
+import { BrowserRuntimeCapabilityRegistryV3, createBrowserWebTransportCarrierV3, } from "../v3/browserRuntime.js";
+import { attemptClaimedArtifactLeaseV3, connectArtifactLeaseV3 } from "../v3/sessionConnector.js";
+import { readyNativeAdmissionV3, readyWebSocketAdmissionV3 } from "../v3/runtimeAdapters.js";
+import { TransportFailureV3, ConnectErrorV3 } from "../v3/security.js";
+import { browserSessionRuntimeV3 } from "../v3/browserSessionRuntime.js";
+export async function connectV3(lease, options = {}) {
+    const registry = await BrowserRuntimeCapabilityRegistryV3.create();
+    return await connectArtifactLeaseV3(lease, browserRuntime(registry, options.connectTimeoutMs), options.signal);
+}
+export async function createConnectionControllerV3(source, options = {}) {
+    const registry = await BrowserRuntimeCapabilityRegistryV3.create();
+    const runtime = browserRuntime(registry, options.connectTimeoutMs);
+    const coreOptions = {
+        capabilitySnapshot: runtime.capabilitySnapshot,
+        projectSessionFailure,
+        ...(options.maximumAttempts === undefined ? {} : { maximumAttempts: options.maximumAttempts }),
+    };
+    return createCoreControllerV3(source, async (context) => await attemptClaimedArtifactLeaseV3(context, runtime), coreOptions);
+}
+function browserRuntime(registry, connectTimeoutMs) {
+    const connectTimeoutMilliseconds = connectTimeoutMs ?? SDK_DEFAULTS.transport.connectTimeoutMs;
+    if (!Number.isSafeInteger(connectTimeoutMilliseconds) || connectTimeoutMilliseconds < 1) {
+        throw new ConnectErrorV3("artifact_invalid", { kind: "terminal" });
+    }
+    return {
+        capabilitySnapshot: () => registry.snapshot(),
+        connectTimeoutMilliseconds,
+        protocolRuntime: browserSessionRuntimeV3,
+        dial: async (candidate, artifact, attemptNow, capability, signal) => {
+            if (candidate.carrier === "webtransport") {
+                const carrier = await createBrowserWebTransportCarrierV3(candidate, attemptNow, capability, registry, artifact.session.max_inbound_streams + 2, signal);
+                return readyNativeAdmissionV3(candidate, carrier);
+            }
+            if (candidate.carrier !== "websocket" || candidate.tls.mode !== "ca") {
+                throw new TransportFailureV3("tls_unsupported");
+            }
+            validateBrowserWebSocketURL(candidate.normalized_url, artifact.path.kind);
+            const Constructor = globalThis.WebSocket;
+            if (Constructor === undefined)
+                throw new TransportFailureV3("tls_unsupported");
+            const protocol = artifact.path.kind === "direct" ? "flowersec.direct.v3" : "flowersec.tunnel.v3";
+            let socket;
+            try {
+                socket = new Constructor(candidate.normalized_url, protocol);
+            }
+            catch (error) {
+                throw new TransportFailureV3("connection_failed", undefined, error);
+            }
+            return await readyWebSocketAdmissionV3(candidate, artifact, socket, signal);
+        },
+    };
+}
+function validateBrowserWebSocketURL(raw, path) {
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        throw new TransportFailureV3("invalid_artifact");
+    }
+    const expectedPath = path === "direct" ? "/flowersec/v3/direct" : "/flowersec/v3/tunnel";
+    if (parsed.href !== raw || parsed.protocol !== "wss:" || parsed.username !== "" || parsed.password !== "" ||
+        parsed.pathname !== expectedPath || parsed.search !== "" || parsed.hash !== "") {
+        throw new TransportFailureV3("invalid_artifact");
+    }
+}
+function projectSessionFailure(error) {
+    const code = error.code;
+    const retryable = new Set([
+        "closed", "going_away", "timeout", "resource_exhausted", "stream_reset", "rekey_failed", "liveness_failed",
+    ]).has(String(code));
+    return new ConnectErrorV3("connection_failed", { kind: retryable ? "retryable" : "terminal" });
+}

package/dist/browser/index.d.ts

@@ -1,3 +1,4 @@
 export * from "../facade.js";
-export { connect, createConnectionController } from "./connectSession.js";
-export type { ConnectionControllerOptions, SessionOptions, } from "./connectSession.js";
+export * as v2 from "./v2.js";
+export { connectV3 as connect, connectV3, createConnectionControllerV3 as createConnectionController, createConnectionControllerV3, } from "./connectSessionV3.js";
+export type { ConnectionControllerOptionsV3 as ConnectionControllerOptions, ConnectionControllerOptionsV3, SessionOptionsV3 as SessionOptions, SessionOptionsV3, } from "./connectSessionV3.js";

package/dist/browser/index.js

@@ -1,2 +1,3 @@
 export * from "../facade.js";
-export { connect, createConnectionController } from "./connectSession.js";
+export * as v2 from "./v2.js";
+export { connectV3 as connect, connectV3, createConnectionControllerV3 as createConnectionController, createConnectionControllerV3, } from "./connectSessionV3.js";

package/dist/browser/v2.d.ts

@@ -0,0 +1,3 @@
+export * from "../v2/index.js";
+export { connect, createConnectionController } from "./connectSession.js";
+export type { ConnectionControllerOptions, SessionOptions, } from "./connectSession.js";

package/dist/browser/v2.js

@@ -0,0 +1,2 @@
+export * from "../v2/index.js";
+export { connect, createConnectionController } from "./connectSession.js";

package/dist/facade.d.ts

@@ -1,14 +1,21 @@
+import type { Session as PublicSession } from "./public/contract.js";
+import type { ConnectionControllerSnapshotV3 as CoreConnectionControllerSnapshotV3, ConnectionControllerV3 as CoreConnectionControllerV3 } from "./v3/connectionController.js";
+export * as v2 from "./v2/index.js";
 export type { ByteStream, IncomingStream, JsonObject, JsonPrimitive, JsonValue, OperationOptions, RpcPeer, RpcResult, SessionErrorCode, StreamOpenOptions, UnreliableMessageChannel, UnreliableMessageSendOptions, UnreliableMessageSendResult, SessionTermination, Session, } from "./public/contract.js";
 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";
-export type { ArtifactErrorCode } from "./public/artifact.js";
-export type { ConnectErrorCode } from "./public/connectError.js";
-export { ConnectError } from "./public/connectError.js";
-export { ConnectionControllerError } from "./connectionController.js";
-export type { ArtifactSource, ArtifactSourceResult, ConnectionController, ConnectionControllerFailure, ConnectionControllerOptions, ConnectionSnapshot, ConnectionState, RetryDisposition, } from "./connectionController.js";
+export { ArtifactHandleV3 as Artifact, ArtifactHandleV3, ArtifactParseErrorV3 as ArtifactError, ArtifactParseErrorV3, createArtifactLeaseV3 as createArtifactLease, createArtifactLeaseV3, parseArtifactV3 as parseArtifact, parseArtifactV3, } from "./v3/publicApi.js";
+export type { ArtifactParseErrorCodeV3 as ArtifactErrorCode, ArtifactParseErrorCodeV3, } from "./v3/publicApi.js";
+export { ArtifactLeaseV3 as ArtifactLease, ArtifactLeaseV3, ArtifactLeaseV3Error as ArtifactLeaseError, ArtifactLeaseV3Error, } from "./v3/artifactLease.js";
+export type { ArtifactSourceResultV3 as ArtifactSourceResult, ArtifactSourceResultV3, ArtifactSourceV3 as ArtifactSource, ArtifactSourceV3, ConnectionControllerFailureV3 as ConnectionControllerFailure, ConnectionControllerFailureV3, ConnectionControllerSnapshotV3, ConnectionControllerStateV3 as ConnectionState, ConnectionControllerStateV3, ConnectionControllerV3, } from "./v3/connectionController.js";
+export type ConnectionController = CoreConnectionControllerV3<PublicSession>;
+export type ConnectionSnapshot = CoreConnectionControllerSnapshotV3<PublicSession>;
+export type ConnectionControllerOptions = Readonly<{
+    maximumAttempts?: number;
+}>;
+export { ConnectionControllerV3Error as ConnectionControllerError, ConnectionControllerV3Error, } from "./v3/connectionController.js";
+export { ConnectErrorV3 as ConnectError, ConnectErrorV3 } from "./v3/security.js";
+export type { PublicConnectErrorCodeV3 as ConnectErrorCode, PublicConnectErrorCodeV3, RetryDispositionV3 as RetryDisposition, RetryDispositionV3, } from "./v3/security.js";

package/dist/facade.js

@@ -1,7 +1,8 @@
+export * as v2 from "./v2/index.js";
 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";
-export { ConnectionControllerError } from "./connectionController.js";
+export { ArtifactHandleV3 as Artifact, ArtifactHandleV3, ArtifactParseErrorV3 as ArtifactError, ArtifactParseErrorV3, createArtifactLeaseV3 as createArtifactLease, createArtifactLeaseV3, parseArtifactV3 as parseArtifact, parseArtifactV3, } from "./v3/publicApi.js";
+export { ArtifactLeaseV3 as ArtifactLease, ArtifactLeaseV3, ArtifactLeaseV3Error as ArtifactLeaseError, ArtifactLeaseV3Error, } from "./v3/artifactLease.js";
+export { ConnectionControllerV3Error as ConnectionControllerError, ConnectionControllerV3Error, } from "./v3/connectionController.js";
+export { ConnectErrorV3 as ConnectError, ConnectErrorV3 } from "./v3/security.js";

package/dist/framing/jsonframe.d.ts

@@ -9,6 +9,6 @@ type ReadExactlyFn = (n: number) => Promise<Uint8Array>;
 type ReadExactlyLike = Readonly<{
     readExactly: (n: number) => Promise<Uint8Array>;
 }>;
-export declare function writeJsonFrame(write: WriteFn | WriteLike, v: unknown): Promise<void>;
+export declare function writeJsonFrame(write: WriteFn | WriteLike, v: unknown, maxBytes?: number): Promise<void>;
 export declare function readJsonFrame(readExactly: ReadExactlyFn | ReadExactlyLike, maxBytes: number): Promise<unknown>;
 export {};

package/dist/framing/jsonframe.js

@@ -13,8 +13,10 @@ function normalizeReadExactly(readExactly) {
     return typeof readExactly === "function" ? readExactly : (n) => readExactly.readExactly(n);
 }
 // writeJsonFrame encodes a JSON payload with a 4-byte length prefix.
-export async function writeJsonFrame(write, v) {
+export async function writeJsonFrame(write, v, maxBytes = 0) {
     const json = te.encode(JSON.stringify(v));
+    if (maxBytes > 0 && json.length > maxBytes)
+        throw new JsonFramingError("frame too large");
     const hdr = u32be(json.length);
     const out = new Uint8Array(4 + json.length);
     out.set(hdr, 0);

package/dist/interop/proxyServerPeer.js

@@ -1,4 +1,4 @@
-import { authorizeRuntime, createAcceptor, createEndpointSet, Issuer, parseArtifact, ProxyServer, SessionHandlers, } from "../node/index.js";
+import { authorizeRuntime, createAcceptor, createEndpointSet, Issuer, parseArtifact, ProxyServer, SessionHandlers, } from "../node/v2.js";
 const ORIGIN = "https://app.example";
 const args = process.argv.slice(2);
 if (args.length !== 2 || args[0] !== "--upstream" || args[1] === undefined) {

package/dist/interop/serverParityPeer.js

@@ -1,6 +1,13 @@
 import { createInterface } from "node:readline";
 import { createPrivateKey, createPublicKey, X509Certificate } from "node:crypto";
-import { createAcceptor, createArtifactLease, createEndpointSet, createStreamMetadata, createTunnelRuntime, connect, Issuer, parseArtifact, RPCHandlers, SessionError, SessionHandlers, } from "../node/index.js";
+import { createStreamMetadata, } from "../public/streamMetadata.js";
+import { createAcceptor, RPCHandlers, SessionHandlers } from "../node/acceptor.js";
+import { createTunnelRuntime } from "../node/tunnelRuntime.js";
+import { createArtifactLease } from "../public/artifactLease.js";
+import { parseArtifact } from "../public/artifact.js";
+import { connect } from "../node/connectSession.js";
+import { Issuer, createEndpointSet } from "../node/controlplane.js";
+import { SessionError } from "../public/contract.js";
 const RUNTIME = "node-typescript";
 const ORIGIN = process.env.FLOWERSEC_PARITY_ORIGIN ?? "https://client.example";
 const ECHO_RPC = 7001;

package/dist/node/acceptor.d.ts

@@ -27,6 +27,16 @@ export declare class RPCHandlers {
 }
 export declare class SessionHandlers {
     private readonly streamHandlerRegistrarBrand;
+    private readonly sessionHandlersV2Brand;
+    constructor(options?: SessionHandlerOptions);
+    handleRPC(typeId: number, handler: RPCHandler): void;
+    handleNotification(typeId: number, handler: NotificationHandler): void;
+    handleStream(kind: string, handler: StreamHandler): void;
+}
+/** Strict-v3 accepted-session handlers. */
+export declare class SessionHandlersV3 {
+    private readonly streamHandlerRegistrarBrand;
+    private readonly sessionHandlersV3Brand;
     constructor(options?: SessionHandlerOptions);
     handleRPC(typeId: number, handler: RPCHandler): void;
     handleNotification(typeId: number, handler: NotificationHandler): void;

package/dist/node/acceptor.js

@@ -1,5 +1,5 @@
 import { RpcRouter } from "../rpc/server.js";
-import { assertRpcError } from "../rpc/validate.js";
+import { assertRpcError, assertRpcTypeId } from "../rpc/validate.js";
 import { acceptReceivedSessionV2, receiveSessionAdmissionV2, rejectSessionAdmissionV2, } from "../connector/sessionAcceptor.js";
 import { nodeSessionRuntimeV2 } from "./sessionRuntime.js";
 import { startNodeWebSocketServer, } from "./webSocketServer.js";
@@ -9,7 +9,7 @@ import { unwrapArtifact } from "../public/artifact.js";
 import { SessionError, } from "../public/contract.js";
 import { projectSessionV2 } from "../v2/publicSession.js";
 import { runtimeAuthorizationRequestFromDecoded, } from "./controlplane.js";
-import { HandlerRegistrationError, StreamHandlers, freezeStreamHandlers, registerStreamHandlersAtomically, serveFrozenStreamHandlers, } from "../public/streamHandlers.js";
+import { HandlerRegistrationError, StreamHandlers, LegacyStreamHandlers, freezeStreamHandlers, registerStreamHandlersAtomically, serveFrozenStreamHandlers, } from "../public/streamHandlers.js";
 export { HandlerRegistrationError } from "../public/streamHandlers.js";
 const DEFAULT_CLEANUP_TIMEOUT_MS = 2_000;
 export class RPCHandlers {
@@ -24,6 +24,28 @@ export class RPCHandlers {
     }
 }
 export class SessionHandlers {
+    constructor(options = {}) {
+        sessionHandlerStates.set(this, {
+            rpc: createRPCHandlerState(),
+            streams: new LegacyStreamHandlers(options),
+            frozen: false,
+        });
+    }
+    handleRPC(typeId, handler) {
+        const state = mutableSessionHandlerState(this);
+        registerRPC(state.rpc, typeId, handler);
+    }
+    handleNotification(typeId, handler) {
+        const state = mutableSessionHandlerState(this);
+        registerNotification(state.rpc, typeId, handler);
+    }
+    handleStream(kind, handler) {
+        const state = mutableSessionHandlerState(this);
+        state.streams.handleStream(kind, handler);
+    }
+}
+/** Strict-v3 accepted-session handlers. */
+export class SessionHandlersV3 {
     constructor(options = {}) {
         sessionHandlerStates.set(this, {
             rpc: createRPCHandlerState(),
@@ -85,10 +107,13 @@ function registerNotification(state, typeId, handler) {
     state.notifications.set(typeId, handler);
 }
 function validateRPCRegistration(typeId, handler) {
-    if (!Number.isSafeInteger(typeId)
-        || typeId < 1
-        || typeId > 0xffff_ffff
-        || typeof handler !== "function") {
+    try {
+        assertRpcTypeId(typeId);
+    }
+    catch {
+        throw new HandlerRegistrationError("invalid_handler");
+    }
+    if (typeof handler !== "function") {
         throw new HandlerRegistrationError("invalid_handler");
     }
 }
@@ -134,7 +159,28 @@ export function createRPCRouter(snapshot) {
     }
     return router;
 }
-function freezeSessionHandlers(handlers) {
+/** @internal */
+export function freezeSessionHandlers(handlers) {
+    if (!(handlers instanceof SessionHandlers)) {
+        throw new HandlerRegistrationError("invalid_handler");
+    }
+    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),
+        streams: freezeStreamHandlers(state.streams),
+    });
+    return state.snapshot;
+}
+/** @internal */
+export function freezeSessionHandlersV3(handlers) {
+    if (!(handlers instanceof SessionHandlersV3)) {
+        throw new HandlerRegistrationError("invalid_handler");
+    }
     const state = sessionHandlerStates.get(handlers);
     if (state === undefined)
         throw new HandlerRegistrationError("invalid_handler");

package/dist/node/acceptorV3.d.ts

@@ -0,0 +1,57 @@
+import type { OperationOptions, Session } from "../public/contract.js";
+import { type ArtifactHandleV3 } from "../v3/publicApi.js";
+import { SessionHandlersV3 } from "./acceptor.js";
+import { type RuntimeAuthorizationRequestV3 } from "./runtimeAuthorizationV3.js";
+export type AcceptorListenerV3 = Readonly<{
+    carrier: "websocket";
+    path: "direct";
+    host: string;
+    port: number;
+    tls: Readonly<{
+        certificate: string;
+        privateKey: string;
+    }>;
+    allowedOrigins: readonly string[];
+}> | Readonly<{
+    carrier: "raw_quic";
+    path: "direct";
+    host: string;
+    port: number;
+    tls: Readonly<{
+        certificate: string | Uint8Array;
+        privateKey: string | Uint8Array;
+    }>;
+}>;
+export type AcceptorOptionsV3 = Readonly<{
+    listeners: readonly AcceptorListenerV3[];
+    maxInboundStreams: number;
+    admissionTimeoutMs?: number;
+    admissionReasons?: readonly string[];
+    authorize: AcceptorAuthorizerV3;
+    resolveHandlers?(request: RuntimeAuthorizationRequestV3, options: OperationOptions): Promise<SessionHandlersV3> | SessionHandlersV3;
+}>;
+export type AcceptorAuthorizationDecisionV3 = Readonly<{
+    accepted: true;
+    artifact: ArtifactHandleV3;
+}> | Readonly<{
+    accepted: false;
+    retryable: boolean;
+    reason: string;
+}>;
+export type AcceptorAuthorizerV3 = (request: RuntimeAuthorizationRequestV3, options: OperationOptions) => Promise<AcceptorAuthorizationDecisionV3> | AcceptorAuthorizationDecisionV3;
+export declare class AcceptedSessionV3 {
+    private constructor();
+    get session(): Session;
+    serve(options?: OperationOptions): Promise<void>;
+    close(): Promise<void>;
+}
+export declare class AcceptorV3 {
+    private constructor();
+    addresses(): readonly Readonly<{
+        host: string;
+        port: number;
+    }>[];
+    accept(options?: OperationOptions): Promise<AcceptedSessionV3>;
+    close(): Promise<void>;
+}
+export declare function createAcceptorV3(options: AcceptorOptionsV3): Promise<AcceptorV3>;