@floegence/flowersec-core 3.0.2 → 3.1.0

package/README.md

@@ -15,19 +15,26 @@ 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 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/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.
 
 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`, and `UnreliableMessageSendResult`.
+- 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`, `ConnectionControllerFailure`, `ConnectionControllerError`, and `RetryDisposition`.
+- Connection lifecycle: `ArtifactSource`, `ArtifactSourceResult`, `ConnectionController`, `ConnectionState`, `ConnectionSnapshot`, `ConnectionDiagnostic`, `ConnectionControllerFailure`, `ConnectionControllerError`, and `RetryDisposition`.
 
-Retry ownership belongs to `ConnectionController`; applications do not classify error text or run a parallel retry scheduler. Public failures remain redacted and reveal no carrier, candidate, URL, credential, stage, key, or diagnostic details.
+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.
 
@@ -50,7 +57,11 @@ const session = await connect(lease, {
 ### Long-lived Node client
 
 ```ts
-import { RPCHandlers, createConnectionController } from "@floegence/flowersec-core/node";
+import {
+  RPCHandlers,
+  connectionDiagnostic,
+  createConnectionController,
+} from "@floegence/flowersec-core/node";
 
 const rpcHandlers = new RPCHandlers();
 rpcHandlers.handleRPC(7, async (payload) => ({ payload }));
@@ -60,10 +71,15 @@ const controller = createConnectionController(source, {
 });
 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. Terminated Session work is never replayed.
+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
 
@@ -151,7 +167,8 @@ 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 control plane and `ProxyServer` behind `node.v2`; the
+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.

package/THIRD_PARTY_NOTICES.md

@@ -3,11 +3,11 @@
 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.0.2 (Declared: MIT; selected: MIT; source: https://github.com/floegence/flowersec.git)
-- @floegence/flowersec-node-native-darwin-arm64 3.0.2 (Declared: MIT; selected: MIT; source: https://github.com/floegence/flowersec.git)
-- @floegence/flowersec-node-native-darwin-x64 3.0.2 (Declared: MIT; selected: MIT; source: https://github.com/floegence/flowersec.git)
-- @floegence/flowersec-node-native-linux-arm64-gnu 3.0.2 (Declared: MIT; selected: MIT; source: https://github.com/floegence/flowersec.git)
-- @floegence/flowersec-node-native-linux-x64-gnu 3.0.2 (Declared: MIT; selected: MIT; source: https://github.com/floegence/flowersec.git)
+- @floegence/flowersec-node-native 3.1.0 (Declared: MIT; selected: MIT; source: https://github.com/floegence/flowersec.git)
+- @floegence/flowersec-node-native-darwin-arm64 3.1.0 (Declared: MIT; selected: MIT; source: https://github.com/floegence/flowersec.git)
+- @floegence/flowersec-node-native-darwin-x64 3.1.0 (Declared: MIT; selected: MIT; source: https://github.com/floegence/flowersec.git)
+- @floegence/flowersec-node-native-linux-arm64-gnu 3.1.0 (Declared: MIT; selected: MIT; source: https://github.com/floegence/flowersec.git)
+- @floegence/flowersec-node-native-linux-x64-gnu 3.1.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)

package/dist/browser/index.d.ts

@@ -1,4 +1,8 @@
 export * from "../facade.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";
+export { connectV3 as connect, createConnectionControllerV3 as createConnectionController, } from "./connectSessionV3.js";
+/** @deprecated Use connect and createConnectionController. */
+export { connectV3, createConnectionControllerV3 } from "./connectSessionV3.js";
+export type { ConnectionControllerOptionsV3 as ConnectionControllerOptions, SessionOptionsV3 as SessionOptions, } from "./connectSessionV3.js";
+/** @deprecated Use ConnectionControllerOptions and SessionOptions. */
+export type { ConnectionControllerOptionsV3, SessionOptionsV3 } from "./connectSessionV3.js";

package/dist/browser/index.js

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

package/dist/facade.d.ts

@@ -1,21 +1,38 @@
 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 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";
 export type { StreamMetadata } from "./public/streamMetadata.js";
 export { HandlerRegistrationError, StreamHandlers, } from "./public/streamHandlers.js";
 export type { StreamHandler, StreamHandlerOptions, } from "./public/streamHandlers.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 { 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, 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";
+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";

package/dist/facade.js

@@ -2,7 +2,18 @@ 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 { 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";
+export { ArtifactHandleV3 as Artifact, ArtifactParseErrorV3 as ArtifactError, createArtifactLeaseV3 as createArtifactLease, parseArtifactV3 as parseArtifact, } from "./v3/publicApi.js";
+/** @deprecated Use Artifact, ArtifactError, createArtifactLease, and parseArtifact. */
+export { ArtifactHandleV3, ArtifactParseErrorV3, createArtifactLeaseV3, parseArtifactV3, } 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 { connectionDiagnosticV3 as connectionDiagnostic } from "./v3/connectionController.js";
+/** @deprecated Use connectionDiagnostic. */
+export { connectionDiagnosticV3 } from "./v3/connectionController.js";
+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";

package/dist/interop/serverParityPeer.js

@@ -1,5 +1,7 @@
 import { createInterface } from "node:readline";
 import { createPrivateKey, createPublicKey, X509Certificate } from "node:crypto";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
 import { createStreamMetadata, } from "../public/streamMetadata.js";
 import { createAcceptor, RPCHandlers, SessionHandlers } from "../node/acceptor.js";
 import { createTunnelRuntime } from "../node/tunnelRuntime.js";
@@ -8,7 +10,14 @@ 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";
+import { createAcceptorV3 } from "../node/acceptorV3.js";
+import { createTunnelRuntimeV3 } from "../node/tunnelRuntimeV3.js";
+import { verifyTunnelAuthorizationGrantV3 } from "../node/runtimeAuthorizationV3.js";
+import { connectV3 } from "../node/connectSessionV3.js";
+import { createArtifactLeaseV3, parseArtifactV3 } from "../v3/publicApi.js";
+import { SessionHandlersV3 } from "../node/acceptor.js";
 const RUNTIME = "node-typescript";
+const PROTOCOL = process.env.FLOWERSEC_PARITY_PROTOCOL ?? "v2";
 const ORIGIN = process.env.FLOWERSEC_PARITY_ORIGIN ?? "https://client.example";
 const ECHO_RPC = 7001;
 const NOTIFY_RPC = 7002;
@@ -64,7 +73,9 @@ class ExecutedCases {
 }
 function createHandlers(path) {
     const rpcHandlers = new RPCHandlers();
-    const sessionHandlers = new SessionHandlers({ maxConcurrentStreams: 16 });
+    const sessionHandlers = PROTOCOL === "v3"
+        ? new SessionHandlersV3({ maxConcurrentStreams: 16 })
+        : new SessionHandlers({ maxConcurrentStreams: 16 });
     const notifications = new SignalQueue();
     const activeStreams = { value: 0 };
     const executed = new ExecutedCases();
@@ -334,7 +345,29 @@ async function connectArtifact(artifactJSON, relay, rpcHandlers) {
         rpcHandlers,
     });
 }
+async function connectArtifactV3(artifactJSON, relay, rpcHandlers) {
+    return await connectV3(createArtifactLeaseV3(parseArtifactV3(artifactJSON), async () => undefined), { origin: relay.origin, roots: relay.trust_pem, rpcHandlers });
+}
+async function issueV3(input) {
+    const goRoot = fileURLToPath(new URL("../../../flowersec-go", import.meta.url));
+    const child = spawn("go", ["run", "./internal/cmd/parity-artifact-issuer"], {
+        cwd: goRoot,
+        env: { ...process.env, FLOWERSEC_SERVER_PARITY_PEER: "1" },
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    child.stdin.end(`${JSON.stringify(input)}\n`);
+    const stdout = [];
+    const stderr = [];
+    child.stdout.on("data", (chunk) => stdout.push(chunk));
+    child.stderr.on("data", (chunk) => stderr.push(chunk));
+    const code = await new Promise((resolve) => child.once("exit", resolve));
+    if (code !== 0)
+        throw new Error(`v3 parity issuer failed: ${Buffer.concat(stderr).toString("utf8").trim()}`);
+    return JSON.parse(Buffer.concat(stdout).toString("utf8"));
+}
 async function runServer(tls, carrier) {
+    if (PROTOCOL === "v3")
+        return await runServerV3(tls, carrier);
     const issuedByLookup = new Map();
     const state = createHandlers("direct");
     const acceptor = await createAcceptor({
@@ -391,6 +424,50 @@ async function runServer(tls, carrier) {
         await acceptor.close();
     }
 }
+async function runServerV3(tls, carrier) {
+    const state = createHandlers("direct");
+    let trustedArtifact;
+    const acceptor = await createAcceptorV3({
+        listeners: [directListenerOptionsV3(carrier, tls)],
+        maxInboundStreams: 16,
+        authorize: async () => trustedArtifact === undefined
+            ? { accepted: false, retryable: false, reason: "invalid_credential" }
+            : { accepted: true, artifact: trustedArtifact },
+        resolveHandlers: () => state.sessionHandlers,
+    });
+    try {
+        const address = acceptor.addresses()[0];
+        if (address === undefined)
+            throw new Error(`direct ${carrier} listener did not bind`);
+        const issued = await issueV3({ mode: "direct", endpoint: endpointURLV3(carrier, "direct", address.port) });
+        if (issued.artifact_json === undefined)
+            throw new Error("v3 parity issuer omitted direct artifact");
+        trustedArtifact = parseArtifactV3(issued.artifact_json);
+        const accepting = acceptor.accept();
+        writeJSON({
+            type: "ready", runtime: RUNTIME, carrier, path: "direct",
+            artifact_json: issued.artifact_json, trust_pem: tls.tls.root_certificate_pem, origin: ORIGIN,
+        });
+        const accepted = await accepting;
+        state.executed.record("admission");
+        const serving = accepted.serve().catch((error) => error);
+        if (process.env.FLOWERSEC_PARITY_CLIENT_PROFILE !== undefined) {
+            await externalServer(accepted.session, state);
+        }
+        else {
+            await exerciseServer(accepted.session, state, "direct", true, carrier);
+        }
+        await serving;
+        await accepted.close().catch(() => undefined);
+        if (state.activeStreams.value !== 0)
+            throw new Error(`direct server cleanup left ${state.activeStreams.value} streams`);
+        state.executed.record("cleanup");
+        writeJSON(result("server-result", "direct", state.executed.snapshot(), carrier));
+    }
+    finally {
+        await acceptor.close();
+    }
+}
 async function runClient(input, carrier) {
     const ready = await input.next();
     if (ready.type !== "ready" ||
@@ -399,7 +476,9 @@ async function runClient(input, carrier) {
         ready.artifact_json === "")
         throw new Error("invalid direct ready message");
     const state = createHandlers("direct");
-    const session = await connectArtifact(ready.artifact_json, ready, state.rpcHandlers);
+    const session = PROTOCOL === "v3"
+        ? await connectArtifactV3(ready.artifact_json, ready, state.rpcHandlers)
+        : await connectArtifact(ready.artifact_json, ready, state.rpcHandlers);
     state.executed.record("admission");
     await exerciseClient(session, state, "direct", carrier);
     await session.close().catch((error) => {
@@ -413,6 +492,8 @@ async function runClient(input, carrier) {
     writeJSON(result("client-result", "direct", state.executed.snapshot(), carrier));
 }
 async function runRelay(tls, input, carrier) {
+    if (PROTOCOL === "v3")
+        return await runRelayV3(tls, input, carrier);
     const decisions = new Map();
     const released = new Set();
     const executed = new ExecutedCases();
@@ -492,7 +573,77 @@ async function runRelay(tls, input, carrier) {
         released_leases: released.size,
     });
 }
+async function runRelayV3(tls, input, carrier) {
+    const authorizations = new Map();
+    const verificationRecords = new Map();
+    const released = new Set();
+    const executed = new ExecutedCases();
+    const runtime = createTunnelRuntimeV3({
+        listeners: [tunnelListenerOptionsV3(carrier, tls)],
+        maxInboundStreams: 16,
+        maxPendingLegs: 16,
+        maxActivePairs: 8,
+        authorize: async (request) => {
+            const item = authorizations.get(request.lookupKey());
+            const artifactJSON = verificationRecords.get(request.lookupKey());
+            if (item === undefined || artifactJSON === undefined)
+                return { decision: "reject", reason: "invalid_credential" };
+            return {
+                decision: "allow",
+                grant: verifyTunnelAuthorizationGrantV3(request, parseArtifactV3(artifactJSON), {
+                    leaseId: item.leaseId,
+                    allowReplacement: item.allowReplacement,
+                }),
+            };
+        },
+        release: (leaseId) => { released.add(leaseId); },
+    });
+    try {
+        await runtime.start();
+        const address = runtime.addresses()[0];
+        if (address === undefined)
+            throw new Error(`tunnel ${carrier} listener did not bind`);
+        writeJSON({
+            type: "relay-ready", runtime: RUNTIME, carrier, path: "tunnel",
+            endpoint_url: endpointURLV3(carrier, "tunnel", address.port),
+            trust_pem: tls.tls.root_certificate_pem,
+            trust_roots_der: [tls.tls.root_certificate_der_base64],
+            server_certificate_der: tls.tls.leaf_certificate_der_base64,
+            origin: ORIGIN,
+        });
+        const configure = await input.next();
+        if (configure.type !== "configure" || !Array.isArray(configure.authorizations) ||
+            configure.authorizations.length === 0 || configure.verification_records === undefined) {
+            throw new Error("invalid v3 tunnel relay configuration");
+        }
+        for (const item of configure.authorizations)
+            authorizations.set(item.credentialId, item);
+        for (const [credentialID, artifactJSON] of Object.entries(configure.verification_records)) {
+            verificationRecords.set(credentialID, artifactJSON);
+        }
+        const close = await input.next();
+        if (close.type !== "close")
+            throw new Error("invalid tunnel relay close command");
+        executed.record("close");
+    }
+    finally {
+        await runtime.close();
+        executed.record("cancel");
+    }
+    if (released.size !== authorizations.size)
+        throw new Error(`relay cleanup released ${released.size} of ${authorizations.size} leases`);
+    executed.record("admission", "pairing", "opaque-forwarding");
+    if (carrier === "raw-quic")
+        executed.record("datagram-forwarding");
+    executed.record("cleanup");
+    writeJSON({
+        type: "relay-result", runtime: RUNTIME, carrier, path: "tunnel", cases: executed.snapshot(),
+        observed_plaintext: false, released_leases: released.size,
+    });
+}
 async function runTunnelEndpointB(input, carrier) {
+    if (PROTOCOL === "v3")
+        return await runTunnelEndpointBV3(input, carrier);
     const envelope = await input.next();
     const { topology, relay } = envelope;
     validateTunnelDimensions(topology, relay, "endpoint_b", carrier);
@@ -539,7 +690,53 @@ async function runTunnelEndpointB(input, carrier) {
     state.executed.record("cleanup");
     writeJSON(result("endpoint-b-result", "tunnel", state.executed.snapshot(), carrier));
 }
+async function runTunnelEndpointBV3(input, carrier) {
+    const envelope = await input.next();
+    const { topology, relay } = envelope;
+    validateTunnelDimensions(topology, relay, "endpoint_b", carrier);
+    const issued = await issueV3({ mode: "tunnel", endpoint: relay.endpoint_url, topology_id: topology.id });
+    if (issued.endpoint_a_artifact_json === undefined || issued.endpoint_b_artifact_json === undefined ||
+        issued.authorizations === undefined || issued.verification_records === undefined) {
+        throw new Error("v3 parity issuer omitted tunnel material");
+    }
+    const ready = {
+        type: "endpoint-b-ready", runtime: RUNTIME, carrier, path: "tunnel",
+        endpoint_a_artifact_json: issued.endpoint_a_artifact_json,
+        endpoint_b_artifact_json: issued.endpoint_b_artifact_json,
+        relay, authorizations: issued.authorizations, verification_records: issued.verification_records,
+    };
+    writeJSON(ready);
+    const command = await input.next();
+    if (command.type !== "connect")
+        throw new Error("endpoint B did not receive connect command");
+    const state = createHandlers("tunnel");
+    const session = await connectArtifactV3(ready.endpoint_b_artifact_json, relay, state.rpcHandlers);
+    state.executed.record("admission");
+    if (process.env.FLOWERSEC_PARITY_CLIENT_PROFILE !== undefined) {
+        await externalServer(session, state);
+    }
+    else {
+        await exerciseServer(session, state, "tunnel", false, carrier);
+    }
+    await session.close().catch(() => undefined);
+    state.executed.record("close");
+    if (state.activeStreams.value !== 0)
+        throw new Error(`endpoint B cleanup left ${state.activeStreams.value} streams`);
+    state.executed.record("cleanup");
+    writeJSON(result("endpoint-b-result", "tunnel", state.executed.snapshot(), carrier));
+}
 async function externalServer(session, state) {
+    const cancellation = new AbortController();
+    cancellation.abort();
+    try {
+        await session.waitTermination({ signal: cancellation.signal });
+    }
+    catch (error) {
+        if (!(error instanceof SessionError) || error.code !== "canceled")
+            throw error;
+    }
+    state.executed.record("cancel");
+    await session.probeLiveness();
     await session.waitTermination();
     state.executed.record("close");
 }
@@ -553,7 +750,9 @@ async function runTunnelEndpointA(input, carrier) {
         ready.endpoint_a_artifact_json === "")
         throw new Error("invalid endpoint B ready message");
     const state = createHandlers("tunnel");
-    const session = await connectArtifact(ready.endpoint_a_artifact_json, ready.relay, state.rpcHandlers);
+    const session = PROTOCOL === "v3"
+        ? await connectArtifactV3(ready.endpoint_a_artifact_json, ready.relay, state.rpcHandlers)
+        : await connectArtifact(ready.endpoint_a_artifact_json, ready.relay, state.rpcHandlers);
     state.executed.record("admission");
     await exerciseClient(session, state, "tunnel", carrier);
     await session.close().catch(() => undefined);
@@ -624,6 +823,11 @@ function endpointURL(carrier, path, port) {
         ? `wss://localhost:${port}/flowersec/v2/${path}`
         : `quic://127.0.0.1:${port}`;
 }
+function endpointURLV3(carrier, path, port) {
+    return carrier === "websocket"
+        ? `wss://localhost:${port}/flowersec/v3/${path}`
+        : `quic://127.0.0.1:${port}`;
+}
 function directListenerOptions(carrier, tls) {
     const material = { certificate: tls.tls.certificate_chain_pem, privateKey: tls.tls.private_key_pem };
     return carrier === "websocket"
@@ -636,6 +840,18 @@ function tunnelListenerOptions(carrier, tls) {
         ? { carrier, host: "127.0.0.1", port: 0, tls: material, allowedOrigins: [ORIGIN] }
         : { carrier: "raw_quic", host: "127.0.0.1", port: 0, tls: material };
 }
+function directListenerOptionsV3(carrier, tls) {
+    const material = { certificate: tls.tls.certificate_chain_pem, privateKey: tls.tls.private_key_pem };
+    return carrier === "websocket"
+        ? { carrier, path: "direct", host: "127.0.0.1", port: 0, tls: material, allowedOrigins: [ORIGIN] }
+        : { carrier: "raw_quic", path: "direct", host: "127.0.0.1", port: 0, tls: material };
+}
+function tunnelListenerOptionsV3(carrier, tls) {
+    const material = { certificate: tls.tls.certificate_chain_pem, privateKey: tls.tls.private_key_pem };
+    return carrier === "websocket"
+        ? { carrier, host: "127.0.0.1", port: 0, tls: material, allowedOrigins: [ORIGIN] }
+        : { carrier: "raw_quic", host: "127.0.0.1", port: 0, tls: material };
+}
 async function main() {
     const { role, carrier } = parseArguments(process.argv.slice(2));
     switch (role) {

package/dist/node/index.d.ts

@@ -1,16 +1,32 @@
-export { AcceptedSessionV3 as AcceptedSession, AcceptedSessionV3, AcceptorV3 as Acceptor, AcceptorV3, createAcceptorV3 as createAcceptor, createAcceptorV3, } from "./acceptorV3.js";
-export type { AcceptorListenerV3 as AcceptorListener, AcceptorListenerV3, AcceptorAuthorizationDecisionV3 as AcceptorAuthorizationDecision, AcceptorAuthorizationDecisionV3, AcceptorAuthorizerV3 as AcceptorAuthorizer, AcceptorAuthorizerV3, AcceptorOptionsV3 as AcceptorOptions, AcceptorOptionsV3, } from "./acceptorV3.js";
-export { TunnelRuntimeV3 as TunnelRuntime, TunnelRuntimeV3, createTunnelRuntimeV3 as createTunnelRuntime, createTunnelRuntimeV3, } from "./tunnelRuntimeV3.js";
-export type { TunnelAuthorizationDecisionV3 as TunnelAuthorizationDecision, TunnelAuthorizationDecisionV3, TunnelRuntimeListenerV3 as TunnelRuntimeListener, TunnelRuntimeListenerV3, TunnelRuntimeOptionsV3 as TunnelRuntimeOptions, TunnelRuntimeOptionsV3, } from "./tunnelRuntimeV3.js";
-export { RuntimeAuthorizationRequestV3 as RuntimeAuthorizationRequest, RuntimeAuthorizationRequestV3, TunnelAuthorizationGrantV3 as TunnelAuthorizationGrant, TunnelAuthorizationGrantV3, verifyTunnelAuthorizationGrantV3 as verifyTunnelAuthorizationGrant, verifyTunnelAuthorizationGrantV3, } from "./runtimeAuthorizationV3.js";
-export type { TunnelAuthorizationGrantOptionsV3 as TunnelAuthorizationGrantOptions, TunnelAuthorizationGrantOptionsV3, } from "./runtimeAuthorizationV3.js";
+export { AcceptedSessionV3 as AcceptedSession, AcceptorV3 as Acceptor, createAcceptorV3 as createAcceptor, } from "./acceptorV3.js";
+export type { AcceptorListenerV3 as AcceptorListener, AcceptorAuthorizationDecisionV3 as AcceptorAuthorizationDecision, AcceptorAuthorizerV3 as AcceptorAuthorizer, AcceptorOptionsV3 as AcceptorOptions, } from "./acceptorV3.js";
+/** @deprecated Use the corresponding unversioned acceptor exports. */
+export { AcceptedSessionV3, AcceptorV3, createAcceptorV3 } from "./acceptorV3.js";
+/** @deprecated Use the corresponding unversioned acceptor types. */
+export type { AcceptorListenerV3, AcceptorAuthorizationDecisionV3, AcceptorAuthorizerV3, AcceptorOptionsV3, } from "./acceptorV3.js";
+export { TunnelRuntimeV3 as TunnelRuntime, createTunnelRuntimeV3 as createTunnelRuntime, } from "./tunnelRuntimeV3.js";
+export type { TunnelAuthorizationDecisionV3 as TunnelAuthorizationDecision, TunnelRuntimeListenerV3 as TunnelRuntimeListener, TunnelRuntimeOptionsV3 as TunnelRuntimeOptions, } from "./tunnelRuntimeV3.js";
+/** @deprecated Use TunnelRuntime and createTunnelRuntime. */
+export { TunnelRuntimeV3, createTunnelRuntimeV3 } from "./tunnelRuntimeV3.js";
+/** @deprecated Use the corresponding unversioned tunnel runtime types. */
+export type { TunnelAuthorizationDecisionV3, TunnelRuntimeListenerV3, TunnelRuntimeOptionsV3, } from "./tunnelRuntimeV3.js";
+export { RuntimeAuthorizationRequestV3 as RuntimeAuthorizationRequest, TunnelAuthorizationGrantV3 as TunnelAuthorizationGrant, verifyTunnelAuthorizationGrantV3 as verifyTunnelAuthorizationGrant, } from "./runtimeAuthorizationV3.js";
+export type { TunnelAuthorizationGrantOptionsV3 as TunnelAuthorizationGrantOptions, } from "./runtimeAuthorizationV3.js";
+/** @deprecated Use the corresponding unversioned runtime-authorization exports. */
+export { RuntimeAuthorizationRequestV3, TunnelAuthorizationGrantV3, verifyTunnelAuthorizationGrantV3, } from "./runtimeAuthorizationV3.js";
+/** @deprecated Use TunnelAuthorizationGrantOptions. */
+export type { TunnelAuthorizationGrantOptionsV3 } from "./runtimeAuthorizationV3.js";
 export * from "../facade.js";
 export * as v2 from "./v2.js";
-import type { NodeTLSRootsV3 } from "./connectSessionV3.js";
-export { connectV3 as connect, connectV3, createConnectionControllerV3 as createConnectionController, createConnectionControllerV3, } from "./connectSessionV3.js";
-export type { ConnectionControllerOptionsV3 as ConnectionControllerOptions, ConnectionControllerOptionsV3, NodeTLSRootsV3, SessionOptionsV3 as SessionOptions, SessionOptionsV3, } from "./connectSessionV3.js";
+import type { NodeTLSRootsV3 as NodeTLSRoots } from "./connectSessionV3.js";
+export { connectV3 as connect, createConnectionControllerV3 as createConnectionController, } from "./connectSessionV3.js";
+/** @deprecated Use connect and createConnectionController. */
+export { connectV3, createConnectionControllerV3 } from "./connectSessionV3.js";
+export type { ConnectionControllerOptionsV3 as ConnectionControllerOptions, NodeTLSRootsV3 as NodeTLSRoots, SessionOptionsV3 as SessionOptions, } from "./connectSessionV3.js";
+/** @deprecated Use ConnectionControllerOptions, SessionTLSOptions, and SessionOptions. */
+export type { ConnectionControllerOptionsV3, NodeTLSRootsV3, SessionOptionsV3, } from "./connectSessionV3.js";
 export type SessionTLSOptions = Readonly<{
-    ca?: NodeTLSRootsV3;
+    ca?: NodeTLSRoots;
 }>;
 export { HandlerRegistrationError, RPCHandlers, SessionHandlersV3 as SessionHandlers, } from "./acceptor.js";
 export type { NotificationHandler, RPCHandler, RPCHandlerResult, SessionHandlerOptions, } from "./acceptor.js";

package/dist/node/index.js

@@ -1,7 +1,15 @@
-export { AcceptedSessionV3 as AcceptedSession, AcceptedSessionV3, AcceptorV3 as Acceptor, AcceptorV3, createAcceptorV3 as createAcceptor, createAcceptorV3, } from "./acceptorV3.js";
-export { TunnelRuntimeV3 as TunnelRuntime, TunnelRuntimeV3, createTunnelRuntimeV3 as createTunnelRuntime, createTunnelRuntimeV3, } from "./tunnelRuntimeV3.js";
-export { RuntimeAuthorizationRequestV3 as RuntimeAuthorizationRequest, RuntimeAuthorizationRequestV3, TunnelAuthorizationGrantV3 as TunnelAuthorizationGrant, TunnelAuthorizationGrantV3, verifyTunnelAuthorizationGrantV3 as verifyTunnelAuthorizationGrant, verifyTunnelAuthorizationGrantV3, } from "./runtimeAuthorizationV3.js";
+export { AcceptedSessionV3 as AcceptedSession, AcceptorV3 as Acceptor, createAcceptorV3 as createAcceptor, } from "./acceptorV3.js";
+/** @deprecated Use the corresponding unversioned acceptor exports. */
+export { AcceptedSessionV3, AcceptorV3, createAcceptorV3 } from "./acceptorV3.js";
+export { TunnelRuntimeV3 as TunnelRuntime, createTunnelRuntimeV3 as createTunnelRuntime, } from "./tunnelRuntimeV3.js";
+/** @deprecated Use TunnelRuntime and createTunnelRuntime. */
+export { TunnelRuntimeV3, createTunnelRuntimeV3 } from "./tunnelRuntimeV3.js";
+export { RuntimeAuthorizationRequestV3 as RuntimeAuthorizationRequest, TunnelAuthorizationGrantV3 as TunnelAuthorizationGrant, verifyTunnelAuthorizationGrantV3 as verifyTunnelAuthorizationGrant, } from "./runtimeAuthorizationV3.js";
+/** @deprecated Use the corresponding unversioned runtime-authorization exports. */
+export { RuntimeAuthorizationRequestV3, TunnelAuthorizationGrantV3, verifyTunnelAuthorizationGrantV3, } from "./runtimeAuthorizationV3.js";
 export * from "../facade.js";
 export * as v2 from "./v2.js";
-export { connectV3 as connect, connectV3, createConnectionControllerV3 as createConnectionController, createConnectionControllerV3, } from "./connectSessionV3.js";
+export { connectV3 as connect, createConnectionControllerV3 as createConnectionController, } from "./connectSessionV3.js";
+/** @deprecated Use connect and createConnectionController. */
+export { connectV3, createConnectionControllerV3 } from "./connectSessionV3.js";
 export { HandlerRegistrationError, RPCHandlers, SessionHandlersV3 as SessionHandlers, } from "./acceptor.js";

package/dist/public/contract.d.ts

@@ -18,14 +18,17 @@ export interface UnreliableMessageChannel {
     send(message: Uint8Array, options: UnreliableMessageSendOptions): Promise<UnreliableMessageSendResult>;
     receive(options?: OperationOptions): Promise<Uint8Array>;
 }
+export type UnreliableMessageErrorCode = "unavailable" | "invalid_message" | "too_large" | "canceled" | "closed" | "operation_failed";
 export declare class UnreliableMessageError extends Error {
-    readonly code: "invalid_message" | "closed" | "operation_failed";
-    constructor(code: "invalid_message" | "closed" | "operation_failed");
+    readonly code: UnreliableMessageErrorCode;
+    constructor(code: UnreliableMessageErrorCode);
 }
 export type StreamOpenOptions = OperationOptions & Readonly<{
     metadata?: StreamMetadata;
 }>;
-export type SessionErrorCode = "canceled" | "timeout" | "closed" | "going_away" | "resource_exhausted" | "stream_rejected" | "stream_reset" | "rekey_failed" | "liveness_failed" | "unreliable_unavailable" | "unreliable_too_large" | "unreliable_dropped" | "operation_failed";
+/** @deprecated Unreliable-message operations use UnreliableMessageErrorCode. */
+export type LegacyUnreliableSessionErrorCode = "unreliable_unavailable" | "unreliable_too_large" | "unreliable_dropped";
+export type SessionErrorCode = "canceled" | "timeout" | "closed" | "going_away" | "resource_exhausted" | "stream_rejected" | "stream_reset" | "rekey_failed" | "liveness_failed" | LegacyUnreliableSessionErrorCode | "operation_failed";
 /** A closed, carrier-neutral session failure with no internal cause or peer detail. */
 export declare class SessionError extends Error {
     readonly code: SessionErrorCode;

package/dist/v2/protocol.js

@@ -385,6 +385,8 @@ export function decodeStreamKeyUpdateACKV2(raw) {
     assertLogicalStreamID(value.logicalStreamID);
     if (value.transition === 0n)
         throw new ProtocolV2Error("stream rekey transition must be non-zero");
+    if (value.epoch === 0)
+        throw new ProtocolV2Error("stream rekey epoch must be non-zero");
     return value;
 }
 export function buildRecordAAD(h3, logicalStreamID, direction, rawHeader) {

package/dist/v2/session.d.ts

@@ -135,6 +135,7 @@ export declare class SessionV2 implements SessionV2Contract {
     private idleWatchdogStarted;
     private idleTimerCancel;
     private readonly terminationState;
+    private readonly terminationController;
     private readonly rpcRouter;
     constructor(carrier: CarrierSessionV2, control: CarrierStreamV2, controlReader: ExactReader, config: SessionConfigV2, material: HandshakeMaterial);
     openStream(kind: string, options?: InternalStreamOpenOptionsV2): Promise<ByteStreamV2>;
@@ -149,6 +150,7 @@ export declare class SessionV2 implements SessionV2Contract {
     installReceiveRoots(epoch: number, roots: EpochRootsV2): void;
     transcriptHash(): Uint8Array;
     receiveDirectionValue(): DirectionV2;
+    terminationSignal(): AbortSignal;
     sendStreamRecord(stream: EncryptedStreamV2, type: InnerTypeV2, payload: Uint8Array, signal?: AbortSignal): Promise<void>;
     readStreamRecord(stream: EncryptedStreamV2): Promise<Readonly<{
         type: InnerTypeV2;
@@ -238,6 +240,7 @@ declare class EncryptedStreamV2 implements ByteStreamV2 {
     private pendingSendRekey;
     private lastSendRekeyACK;
     private receiveRekey;
+    private receiveRekeyChanged;
     constructor(session: SessionV2, carrier: CarrierStreamV2, id: bigint, kind: string, sendEpoch: number, receiveEpoch: number, permitRelease: () => void, reader?: ExactReader);
     read(options?: OperationOptionsV2): Promise<Uint8Array | null>;
     write(payload: Uint8Array, options?: OperationOptionsV2): Promise<number>;
@@ -253,6 +256,7 @@ declare class EncryptedStreamV2 implements ByteStreamV2 {
     }>;
     waitReceiveRekey(transition: bigint, epoch: number, signal?: AbortSignal): Promise<void>;
     publishReceiveRekey(transition: bigint, epoch: number): void;
+    private notifyReceiveRekeyChanged;
     startPump(): void;
     markOpen(): void;
     markTerminal(error: Error): boolean;