@floegence/flowersec-core 3.2.0 → 4.0.0

package/README.md

@@ -1,9 +1,8 @@
 # Flowersec for TypeScript
 
 `@floegence/flowersec-core` is the ESM-only Flowersec SDK for browsers and
-Node.js. It gives both runtimes the same encrypted session, RPC, notification,
-and byte-stream API through the root, `/browser`, `/node`, and `/proxy`
-entrypoints.
+Node.js. It provides encrypted sessions, RPC, notifications, reliable byte
+streams, connection recovery, server runtimes, and browser proxy integration.
 
 ## Install
 
@@ -11,221 +10,75 @@ entrypoints.
 npm install @floegence/flowersec-core
 ```
 
-## Public API
+Node.js 24.20.0 or newer is required.
 
-- `@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 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; the Go control-plane remains the only v3 invitation issuer.
-- `@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.
+## Entrypoints
 
-The browser entrypoint also exposes the isolated
-`flowersec-private-loopback/1` parser, lease, one-shot connector, and
-connection controller. Only these dedicated APIs accept the profile, and they
-require the exact numeric-loopback HTTP origin. Ordinary `connect(...)`
-continues to accept only standard `flowersec/3` artifacts and WSS/WebTransport
-security capabilities.
+- `@floegence/flowersec-core` exports the portable artifact, lease, Session,
+  RPC, stream, metadata, error, and connection-controller contracts.
+- `@floegence/flowersec-core/browser` adds browser `connect(...)`,
+  `createConnectionController(...)`, WSS, optional WebTransport, and the
+  isolated private-loopback profile.
+- `@floegence/flowersec-core/node` adds Node `connect(...)`,
+  `createConnectionController(...)`, `createAcceptor(...)`,
+  `createTunnelRuntime(...)`, `ProxyServer`, `SessionHandlers`, and
+  `RPCHandlers`.
+- `@floegence/flowersec-core/proxy` provides the browser HTTP/WebSocket proxy
+  runtime, Service Worker integration, and exact-origin window bridges.
 
-The complete boundary is documented in the
-[private loopback profile](../docs/PRIVATE_LOOPBACK_V1.md).
+## Client Sessions
 
-The root type exports are:
-
-- Artifact lifecycle: `Artifact`, closed `ArtifactError` parse failures, and `ArtifactLease`.
-- Sessions: `Session`, `SessionTermination`, `RpcPeer`, `RpcResult<Response>`, `ByteStream`, `IncomingStream`, `StreamMetadata`, `OperationOptions`, and `StreamOpenOptions`. Create metadata with `createStreamMetadata(...)`; invalid values throw `StreamMetadataError` before opening a stream.
-- Unreliable messages: `UnreliableMessageChannel`, `UnreliableMessageSendOptions`, `UnreliableMessageSendResult`, and the closed `UnreliableMessageErrorCode` set.
-- JSON values: `JsonPrimitive`, `JsonValue`, and `JsonObject`.
-- Errors: `ConnectErrorCode`, `SessionErrorCode`, and structured `RetryDisposition`.
-- Connection lifecycle: `ArtifactSource`, `ArtifactSourceResult`, `ConnectionController`, `ConnectionState`, `ConnectionSnapshot`, `ConnectionDiagnostic`, `ConnectionControllerFailure`, `ConnectionControllerError`, and `RetryDisposition`.
-
-Unversioned names are the recommended strict-v3 API. Explicit `V3` exports are
-deprecated aliases. `ConnectError.retryDisposition` and
-`retry_after.notBeforeUnixMilliseconds` are canonical; deprecated
-`disposition` and `absoluteUnixMilliseconds` properties remain readable through
-their aliases. 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 implementation 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 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.
-
-Browser and Node.js connector options accept `connectTimeoutMs`; omitting it uses 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,
-  connectionDiagnostic,
-  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();
-const unsubscribe = controller.subscribe((snapshot) => {
-  monitor(connectionDiagnostic(snapshot));
-});
-```
-
-The immutable callback definition applies to every generation, while each
-Session gets a fresh router. `waitForSession()` never starts the controller.
-Diagnostics contain only state, attempt, failure phase/code, and retry
-disposition. Terminated Session work is never replayed.
-
-### Application streams on any Session
+Parse an opaque artifact, bind its durable spend callback, and connect:
 
 ```ts
-import { StreamHandlers } from "@floegence/flowersec-core";
+import { createArtifactLease, parseArtifact } from "@floegence/flowersec-core";
+import { connect } from "@floegence/flowersec-core/node";
 
-const streamHandlers = new StreamHandlers({ maxConcurrentStreams: 32 });
-streamHandlers.handleStream("files/read", async (incoming) => serveFile(incoming));
-await streamHandlers.serve(session);
+const artifact = parseArtifact(serializedArtifact);
+const lease = createArtifactLease(artifact, persistSpendExactlyOnce);
+const session = await connect(lease, { origin: "https://app.example" });
 ```
 
-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
-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
-
-```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,
-  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. The default `SessionHandlers` is strict v3 and
-accepted-server-only; the v2 registry remains under `node.v2.SessionHandlers`.
-
-## 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.
-
-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 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.
+`Artifact` hides credentials and candidate selection. `ArtifactLease` exposes no
+public spend method. `Session` exposes RPC, streams, unreliable messages when
+negotiated, liveness, rekeying, termination, and close without revealing its
+carrier.
 
-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.
+`StreamHandlers` serves bounded application handlers on any Session.
+`ConnectionController` is the only reconnect scheduler and obtains a fresh
+lease for each attempt. Work from a terminated Session is never migrated or
+replayed.
 
-Source failures return a structured `terminal`, `retryable`, or `retry_after` disposition. Thrown or malformed source failures are terminal. Retry delay is deterministic exponential backoff from 250 ms, doubling to a 30-second maximum with no jitter; `retry_after` is never attempted before its specified Unix-millisecond boundary. Attempts are unlimited unless `maximumAttempts` is explicitly set.
+## Node Servers and ProxyServer
 
-A newly established session replaces `currentSession` atomically. The controller never migrates or replays streams, RPC calls, or writes from a terminated session; callers start new application operations on the new session.
+`createAcceptor(...)` accepts direct application Sessions. `SessionHandlers`
+binds accepted RPC, notification, and stream handlers before establishment.
+`createTunnelRuntime(...)` pairs and forwards opaque relay legs without
+terminating the end-to-end Session.
 
-A negotiated `Session.unreliableMessages` channel sends defensively copied `Uint8Array` values and returns `accepted`, `dropped_expired`, `dropped_budget`, or `dropped_carrier`. `receive(...)` also returns a fresh `Uint8Array`. Invalid payloads, unavailable channels, cancellation, closure, and internal failures remain redacted public operation errors.
+`ProxyServer` registers the bounded HTTP and WebSocket application protocol on
+`StreamHandlers` or `SessionHandlers`. It enforces fixed upstream hosts,
+origins, header and cookie policy, body/frame limits, timeouts, cancellation,
+and a close barrier. The `/proxy` browser runtime uses the same application
+wire through a Service Worker or exact-origin window bridge.
 
 ## Supported Connections
 
-Browsers support WebSocket. Browser WebTransport is capability-dependent on
-the browser's WebTransport API and is an optional browser adapter, not a
-required native-server carrier. Through
-`/node`, Node.js supports WebSocket and raw QUIC client connections, direct
-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 V3 Node
-entrypoint keeps the legacy control plane and `ProxyServer` behind `node.v2`; it
-does not issue v3 invitations, which are produced by the Go control-plane. 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.
-
-## Opaque Boundaries
-
-`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.
-
-Admission rejection reasons are server-authorized bounded protocol tokens. Clients validate their wire form without carrying a deployment-specific reason registry; the public error boundary remains closed and redacted.
-
-The proxy entrypoint accepts an opaque `ArtifactLease` or an already connected `Session`. Cross-window bridges require an exact allowed origin and may require a bounded capability nonce; runtime failures are mapped to closed status/code values before reaching Service Worker or Window messages.
-
-## Connection Notes
-
-Browser applications receive a ready `Session` from `connect(...)`. The browser
-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.
+Browsers support WSS and optional browser-owned WebTransport. Node.js supports
+WSS and raw QUIC client, direct-server, and tunnel-runtime roles. Raw QUIC uses
+the optional Flowersec native package for macOS or glibc Linux on arm64/x64.
+Node.js does not expose WebTransport or an artifact issuer; use an application
+control plane such as the Go control-plane package.
 
-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.
+CA candidates use platform or configured private roots. Pin candidates verify
+only the complete artifact-bound active pin set and never fall back to CA.
+Public errors remain closed and redacted.
 
-Node.js applications receive the same `Session` contract from `connect(...)`.
-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.
+## CLI
 
-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.
+The package installs `flowersec-ts-cli`. Its client and server commands accept
+only Transport v3 artifacts. The server requires a TLS certificate and private
+key for its WebSocket listener.
 
 ## Verify
 
@@ -235,4 +88,8 @@ npm test
 npm run verify:package
 ```
 
-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).
+See the [TypeScript cookbook](../examples/ts/README.md),
+[API contract](../docs/API_CONTRACT.md),
+[Transport v3 architecture](../docs/TRANSPORT_V3_ARCHITECTURE.md),
+[wire contract](../docs/TRANSPORT_V3_WIRE.md), and
+[error model](../docs/ERROR_MODEL.md).

package/THIRD_PARTY_NOTICES.md

@@ -3,17 +3,17 @@
 This file is generated from the canonical Flowersec source dependency inventory for flowersec-ts.
 Do not edit it manually. License decisions are reviewed by the repository source license policy.
 
-- @floegence/flowersec-node-native 3.2.0 (Declared: MIT; selected: MIT; source: https://github.com/floegence/flowersec.git)
-- @floegence/flowersec-node-native-darwin-arm64 3.2.0 (Declared: MIT; selected: MIT; source: https://github.com/floegence/flowersec.git)
-- @floegence/flowersec-node-native-darwin-x64 3.2.0 (Declared: MIT; selected: MIT; source: https://github.com/floegence/flowersec.git)
-- @floegence/flowersec-node-native-linux-arm64-gnu 3.2.0 (Declared: MIT; selected: MIT; source: https://github.com/floegence/flowersec.git)
-- @floegence/flowersec-node-native-linux-x64-gnu 3.2.0 (Declared: MIT; selected: MIT; source: https://github.com/floegence/flowersec.git)
-- @noble/ciphers 2.3.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/@noble/ciphers/-/ciphers-2.3.0.tgz)
-- @noble/curves 2.3.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/@noble/curves/-/curves-2.3.0.tgz)
-- @noble/hashes 2.3.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/@noble/hashes/-/hashes-2.3.0.tgz)
+- @floegence/flowersec-node-native 4.0.0 (Declared: MIT; selected: MIT; source: https://github.com/floegence/flowersec.git)
+- @floegence/flowersec-node-native-darwin-arm64 4.0.0 (Declared: MIT; selected: MIT; source: https://github.com/floegence/flowersec.git)
+- @floegence/flowersec-node-native-darwin-x64 4.0.0 (Declared: MIT; selected: MIT; source: https://github.com/floegence/flowersec.git)
+- @floegence/flowersec-node-native-linux-arm64-gnu 4.0.0 (Declared: MIT; selected: MIT; source: https://github.com/floegence/flowersec.git)
+- @floegence/flowersec-node-native-linux-x64-gnu 4.0.0 (Declared: MIT; selected: MIT; source: https://github.com/floegence/flowersec.git)
+- @noble/ciphers 2.4.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/@noble/ciphers/-/ciphers-2.4.0.tgz)
+- @noble/curves 2.4.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/@noble/curves/-/curves-2.4.0.tgz)
+- @noble/hashes 2.4.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/@noble/hashes/-/hashes-2.4.0.tgz)
 - punycode 2.3.1 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/punycode/-/punycode-2.3.1.tgz)
-- tr46 5.0.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/tr46/-/tr46-5.0.0.tgz)
-- ws 8.21.3 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/ws/-/ws-8.21.3.tgz)
+- tr46 6.0.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/tr46/-/tr46-6.0.0.tgz)
+- ws 8.21.2 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/ws/-/ws-8.21.2.tgz)
 ## Distributed Dependency License Materials
 
 The following dependencies are incorporated into distributed Flowersec files or binaries.
@@ -44,7 +44,7 @@ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
-### tr46 5.0.0
+### tr46 6.0.0
 
 #### Reviewed bundled license text
 

package/dist/browser/index.d.ts

@@ -1,11 +1,6 @@
 export * from "../facade.js";
-export * as v2 from "./v2.js";
 export { connectV3 as connect, createConnectionControllerV3 as createConnectionController, connectPrivateLoopbackV1, createPrivateLoopbackConnectionControllerV1, } from "./connectSessionV3.js";
 export { PRIVATE_LOOPBACK_PROFILE_V1, PrivateLoopbackArtifactErrorV1, createPrivateLoopbackArtifactLeaseV1, parsePrivateLoopbackArtifactV1, } from "./privateLoopbackV1.js";
-/** @deprecated Use connect and createConnectionController. */
-export { connectV3, createConnectionControllerV3 } from "./connectSessionV3.js";
 export type { ConnectionControllerOptionsV3 as ConnectionControllerOptions, SessionOptionsV3 as SessionOptions, } from "./connectSessionV3.js";
 export type { PrivateLoopbackConnectionControllerOptionsV1, PrivateLoopbackSessionOptionsV1, } from "./connectSessionV3.js";
 export type { PrivateLoopbackArtifactLeaseV1, PrivateLoopbackArtifactSourceResultV1, PrivateLoopbackArtifactSourceV1, PrivateLoopbackArtifactV1, } from "./privateLoopbackV1.js";
-/** @deprecated Use ConnectionControllerOptions and SessionOptions. */
-export type { ConnectionControllerOptionsV3, SessionOptionsV3 } from "./connectSessionV3.js";

package/dist/browser/index.js

@@ -1,6 +1,3 @@
 export * from "../facade.js";
-export * as v2 from "./v2.js";
 export { connectV3 as connect, createConnectionControllerV3 as createConnectionController, connectPrivateLoopbackV1, createPrivateLoopbackConnectionControllerV1, } from "./connectSessionV3.js";
 export { PRIVATE_LOOPBACK_PROFILE_V1, PrivateLoopbackArtifactErrorV1, createPrivateLoopbackArtifactLeaseV1, parsePrivateLoopbackArtifactV1, } from "./privateLoopbackV1.js";
-/** @deprecated Use connect and createConnectionController. */
-export { connectV3, createConnectionControllerV3 } from "./connectSessionV3.js";

package/dist/cli.js

@@ -1,126 +1,155 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
-import { acceptNativeSessionV2 } from "./connector/sessionAcceptor.js";
 import { claimSpendMarker } from "./cliSpendMarker.js";
-import { connect } from "./node/connectSession.js";
-import { nodeSessionRuntimeV2 } from "./node/sessionRuntime.js";
-import { startNodeWebSocketServer } from "./node/webSocketServer.js";
-import { createArtifactLeaseV2 } from "./v2/artifactLease.js";
-import { buildFSB2RequestV2, encodeFSB2RequestV2 } from "./v2/artifact.js";
-import { parseArtifact, unwrapArtifact } from "./v2/opaqueArtifact.js";
-const args = parseArguments(process.argv.slice(2));
-if (args.mode === "client")
-    await runClient(args.values);
-else
-    await runServer(args.values);
+import { createArtifactLease, parseArtifact } from "./facade.js";
+import { connect, createAcceptor, } from "./node/index.js";
+await main();
+async function main() {
+    try {
+        const args = parseArguments(process.argv.slice(2));
+        if (args.mode === "client")
+            await runClient(args.values);
+        else
+            await runServer(args.values);
+    }
+    catch (error) {
+        const code = errorCode(error);
+        process.stderr.write(`${code}\n`);
+        process.exitCode = 1;
+    }
+}
 async function runClient(values) {
     requireWebSocket(values);
     const artifact = parseArtifact(readFileSync(required(values, "artifact")));
-    const lease = createArtifactLeaseV2(artifact, async () => claimSpendMarker(required(values, "spend-marker")));
+    const lease = createArtifactLease(artifact, async () => claimSpendMarker(required(values, "spend-marker")));
     let session;
     try {
         session = await connect(lease, {
             origin: required(values, "origin"),
-            ...(values.ca === undefined ? {} : { tls: { ca: readFileSync(values.ca, "utf8") } }),
+            ...(values.ca === undefined
+                ? {}
+                : { roots: readFileSync(values.ca, "utf8") }),
         });
         const stream = await session.openStream("cli");
         await stream.write(new TextEncoder().encode("flowersec-ts-cli"));
         await stream.closeWrite();
         const response = await stream.read();
         if (response === null || new TextDecoder().decode(response) !== "flowersec-ts-cli") {
-            throw new Error("CLI server returned an invalid stream response");
+            throw new Error("invalid_response");
         }
         process.stdout.write("GREEN\n");
     }
     finally {
-        await session?.close();
+        await session?.close().catch(() => undefined);
     }
 }
 async function runServer(values) {
     requireWebSocket(values);
-    const artifact = unwrapArtifact(parseArtifact(readFileSync(required(values, "artifact"))));
-    if (artifact.path.kind !== "direct")
-        throw new Error("CLI server requires a direct artifact");
-    const certificatePath = values.certificate;
-    const privateKeyPath = values["private-key"];
-    if ((certificatePath === undefined) !== (privateKeyPath === undefined)) {
-        throw new Error("--certificate and --private-key must be provided together");
-    }
-    const server = await startNodeWebSocketServer({
-        host: values.host ?? "127.0.0.1",
-        port: Number.parseInt(required(values, "port"), 10),
-        path: "direct",
-        allowedOrigins: [required(values, "origin")],
-        inboundBidirectionalStreamCapacity: artifact.session.max_inbound_streams + 2,
-        ...(certificatePath === undefined || privateKeyPath === undefined ? {} : {
-            tls: {
-                certificate: readFileSync(certificatePath, "utf8"),
-                privateKey: readFileSync(privateKeyPath, "utf8"),
-            },
-        }),
+    const artifact = parseArtifact(readFileSync(required(values, "artifact")));
+    const certificate = readFileSync(required(values, "certificate"), "utf8");
+    const privateKey = readFileSync(required(values, "private-key"), "utf8");
+    const acceptor = await createAcceptor({
+        listeners: [{
+                carrier: "websocket",
+                path: "direct",
+                host: values.host ?? "127.0.0.1",
+                port: parsePort(required(values, "port")),
+                tls: { certificate, privateKey },
+                allowedOrigins: [required(values, "origin")],
+            }],
+        maxInboundStreams: parseMaxInboundStreams(required(values, "max-inbound-streams")),
+        authorize: async () => ({ accepted: true, artifact }),
     });
-    process.stdout.write(JSON.stringify(server.address()) + "\n");
+    process.stdout.write(`${JSON.stringify(acceptor.addresses()[0])}\n`);
     const abort = new AbortController();
-    const stop = () => abort.abort(new Error("CLI server stopped"));
+    let stopping = false;
+    let accepted;
+    const stop = () => {
+        stopping = true;
+        abort.abort(new Error("canceled"));
+        void accepted?.close().catch(() => undefined);
+    };
     process.once("SIGINT", stop);
     process.once("SIGTERM", stop);
     try {
-        const session = await acceptNativeSessionV2(await server.accept({ signal: abort.signal }), async (request) => {
-            const chosen = artifact.path.candidates.find(({ id }) => id === request.request.chosen_candidate_id);
-            if (request.request.pathKind !== "direct" || chosen?.carrier !== "websocket") {
-                throw new Error("CLI server rejected an unexpected artifact candidate");
-            }
-            const expected = encodeFSB2RequestV2(buildFSB2RequestV2(artifact, request.request.chosen_candidate_id));
-            if (!bytesEqual(expected, request.raw))
-                throw new Error("CLI server rejected an unbound artifact");
-            return { accepted: true, artifact };
-        }, { runtime: nodeSessionRuntimeV2, signal: abort.signal });
-        await echoOnce(session);
-        await session.close();
+        accepted = await acceptor.accept({ signal: abort.signal });
+        await echoOnce(accepted.session);
+    }
+    catch (error) {
+        if (!stopping)
+            throw error;
     }
     finally {
         process.removeListener("SIGINT", stop);
         process.removeListener("SIGTERM", stop);
-        await server.close();
+        await accepted?.close().catch(() => undefined);
+        await acceptor.close().catch(() => undefined);
     }
 }
 async function echoOnce(session) {
     const incoming = await session.acceptStream();
+    if (incoming.kind !== "cli")
+        throw new Error("invalid_stream_kind");
     const payload = await incoming.stream.read();
     if (payload === null)
-        throw new Error("CLI stream closed before payload");
+        throw new Error("missing_payload");
     await incoming.stream.write(payload);
     await incoming.stream.closeWrite();
 }
 function parseArguments(raw) {
     const [mode, ...rest] = raw;
-    if (mode !== "client" && mode !== "server")
+    if (mode !== "client" && mode !== "server") {
         throw new Error("usage: flowersec-ts-cli <client|server> options");
+    }
     const values = {};
     for (let index = 0; index < rest.length; index++) {
         const token = rest[index];
         if (!token.startsWith("--") || index + 1 >= rest.length || rest[index + 1].startsWith("--")) {
-            throw new Error(`invalid CLI option ${token}`);
+            throw new Error(`invalid_option:${token}`);
         }
-        values[token.slice(2)] = rest[++index];
+        const name = token.slice(2);
+        if (Object.hasOwn(values, name))
+            throw new Error(`duplicate_option:${token}`);
+        values[name] = rest[++index];
     }
     return { mode, values };
 }
 function required(values, name) {
     const value = values[name];
     if (value === undefined || value === "")
-        throw new Error(`missing --${name}`);
+        throw new Error(`missing_option:${name}`);
     return value;
 }
 function requireWebSocket(values) {
     if (values.transport !== "websocket")
-        throw new Error("--transport websocket is required");
+        throw new Error("websocket_required");
+}
+function parsePort(value) {
+    if (!/^\d{1,5}$/u.test(value))
+        throw new Error("invalid_port");
+    const port = Number(value);
+    if (!Number.isSafeInteger(port) || port < 0 || port > 65_535) {
+        throw new Error("invalid_port");
+    }
+    return port;
 }
-function bytesEqual(left, right) {
-    if (left.length !== right.length)
-        return false;
-    let different = 0;
-    for (let index = 0; index < left.length; index++)
-        different |= left[index] ^ right[index];
-    return different === 0;
+function parseMaxInboundStreams(value) {
+    if (!/^\d{1,3}$/u.test(value))
+        throw new Error("invalid_max_inbound_streams");
+    const maximum = Number(value);
+    if (!Number.isSafeInteger(maximum) || maximum < 1 || maximum > 128) {
+        throw new Error("invalid_max_inbound_streams");
+    }
+    return maximum;
+}
+function errorCode(error) {
+    if (typeof error === "object" && error !== null && "code" in error) {
+        const code = error.code;
+        if (typeof code === "string" && /^[a-z][a-z0-9_]*$/u.test(code))
+            return code;
+    }
+    if (error instanceof Error && /^[a-z][a-z0-9_:<> -]*$/u.test(error.message)) {
+        return error.message;
+    }
+    return "operation_failed";
 }

package/dist/facade.d.ts

@@ -1,6 +1,5 @@
 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, UnreliableMessageErrorCode, StreamOpenOptions, UnreliableMessageChannel, UnreliableMessageSendOptions, UnreliableMessageSendResult, SessionTermination, Session, } from "./public/contract.js";
 export { SessionError, UnreliableMessageError } from "./public/contract.js";
 export { createStreamMetadata, StreamMetadataError } from "./public/streamMetadata.js";
@@ -9,30 +8,14 @@ export { HandlerRegistrationError, StreamHandlers, } from "./public/streamHandle
 export type { StreamHandler, StreamHandlerOptions, } from "./public/streamHandlers.js";
 export { ArtifactHandleV3 as Artifact, ArtifactParseErrorV3 as ArtifactError, createArtifactLeaseV3 as createArtifactLease, parseArtifactV3 as parseArtifact, } from "./v3/publicApi.js";
 export type { ArtifactParseErrorCodeV3 as ArtifactErrorCode, } from "./v3/publicApi.js";
-/** @deprecated Use Artifact, ArtifactError, createArtifactLease, and parseArtifact. */
-export { ArtifactHandleV3, ArtifactParseErrorV3, createArtifactLeaseV3, parseArtifactV3, } from "./v3/publicApi.js";
-/** @deprecated Use ArtifactErrorCode. */
-export type { ArtifactParseErrorCodeV3 } from "./v3/publicApi.js";
 export { ArtifactLeaseV3 as ArtifactLease, ArtifactLeaseV3Error as ArtifactLeaseError, } from "./v3/artifactLease.js";
-/** @deprecated Use ArtifactLease and ArtifactLeaseError. */
-export { ArtifactLeaseV3, ArtifactLeaseV3Error } from "./v3/artifactLease.js";
 export type { ArtifactSourceResultV3 as ArtifactSourceResult, ArtifactSourceV3 as ArtifactSource, ConnectionDiagnosticV3 as ConnectionDiagnostic, ConnectionControllerFailureV3 as ConnectionControllerFailure, ConnectionControllerStateV3 as ConnectionState, } from "./v3/connectionController.js";
-/** @deprecated Use the corresponding unversioned controller types. */
-export type { ArtifactSourceResultV3, ArtifactSourceV3, ConnectionDiagnosticV3, ConnectionControllerFailureV3, ConnectionControllerSnapshotV3, ConnectionControllerStateV3, ConnectionControllerV3, } from "./v3/connectionController.js";
 export { connectionDiagnosticV3 as connectionDiagnostic } from "./v3/connectionController.js";
-/** @deprecated Use connectionDiagnostic. */
-export { connectionDiagnosticV3 } from "./v3/connectionController.js";
 export type ConnectionController = CoreConnectionControllerV3<PublicSession>;
 export type ConnectionSnapshot = CoreConnectionControllerSnapshotV3<PublicSession>;
 export type ConnectionControllerOptions = Readonly<{
     maximumAttempts?: number;
 }>;
 export { ConnectionControllerV3Error as ConnectionControllerError, } from "./v3/connectionController.js";
-/** @deprecated Use ConnectionControllerError. */
-export { ConnectionControllerV3Error } from "./v3/connectionController.js";
 export { ConnectErrorV3 as ConnectError } from "./v3/security.js";
-/** @deprecated Use ConnectError. */
-export { ConnectErrorV3 } from "./v3/security.js";
 export type { PublicConnectErrorCodeV3 as ConnectErrorCode, RetryDispositionV3 as RetryDisposition, } from "./v3/security.js";
-/** @deprecated Use ConnectErrorCode and RetryDisposition. */
-export type { PublicConnectErrorCodeV3, RetryDispositionV3 } from "./v3/security.js";