@floegence/flowersec-core 0.27.0 → 2.0.0

package/README.md

@@ -1,40 +1,109 @@
-# @floegence/flowersec-core
+# Flowersec for TypeScript
 
-The TypeScript SDK for Flowersec end-to-end encrypted direct and tunneled sessions. It implements the portable Node.js client and endpoint contract plus the browser and Service Worker runtime owned by TypeScript.
+`@floegence/flowersec-core` is the ESM-only Flowersec v2 SDK for browsers and Node.js. Its public package surface is limited to the root, `/browser`, `/node`, and `/proxy` entrypoints.
+
+Flowersec 2.0.0 is the published coordinated TypeScript SDK release.
 
 ## Install
 
 ```bash
-npm install @floegence/flowersec-core
+npm install @floegence/flowersec-core@2.0.0
 ```
 
-The package is ESM-only and exposes environment-specific entrypoints for browser and Node.js applications.
+## Public API
+
+- `@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(...)`, and their options.
+- `@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`.
+- JSON values: `JsonPrimitive`, `JsonValue`, and `JsonObject`.
+- Errors: `ConnectErrorCode`, `SessionErrorCode`, and structured `RetryDisposition`.
+- Connection lifecycle: `ArtifactSource`, `ArtifactSourceResult`, `ConnectionController`, `ConnectionState`, `ConnectionSnapshot`, `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.
+
+`RpcResult<Response>` is a discriminated union. `RpcPeer.call(...)` requires a decoder for successful payloads, so the typed success value has passed application validation before it is returned. Check `result.ok` before reading either the typed success `payload` or bounded application `error`; a result cannot contain both. RPC call and notify are portable across SDKs, while `RpcPeer.onNotify(...)` is a TypeScript-specific subscription convenience.
+
+When connector options omit a connection timeout, browser and Node.js connectors use the shared ten-second default.
+
+## 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`; snapshots expose the current structured `retryDisposition` while waiting. Call `start()` once, observe immutable 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.
+
+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.
+
+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.
+
+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.
+
+## Capability Layers
+
+The portable core is the same application model used by every Flowersec SDK:
+opaque artifact parsing, a durable single-use lease, one-shot connection,
+carrier-neutral sessions, RPC, reliable streams, redacted public errors, and
+the optional single-owner `ConnectionController`. Callers should not compare
+raw TypeScript error-code strings with other SDKs.
 
-## Cookbook
+Only this portable core is required to align across languages. Complete SDK
+profiles and language conveniences intentionally differ by runtime.
 
-Start with the [TypeScript cookbook](https://github.com/floegence/flowersec/tree/main/examples/ts). It contains runnable browser direct/tunnel pages, Node.js clients, the shared demo server, the Service Worker proxy runtime, and manual protocol-stack references.
+The TypeScript SDK profile is split by entrypoint: browsers own WebSocket and
+WebTransport dialing, while Node.js owns WebSocket and WebTransport dialing through
+the native `@fails-components/webtransport` adapter. Its language convenience
+includes static generic RPC result typing, notification subscriptions, and
+proxy composition. These conveniences do not expand the
+portable core required from Go, Swift, or Rust.
 
-## Entrypoints
+## Opaque Boundaries
 
-- Browser client: `@floegence/flowersec-core/browser`
-- Node.js client and endpoint transport: `@floegence/flowersec-core/node`
-- Controlplane artifact helpers: `@floegence/flowersec-core/controlplane`
-- Endpoint session serving: `@floegence/flowersec-core/endpoint`
-- RPC: `@floegence/flowersec-core/rpc`
-- Reconnect: `@floegence/flowersec-core/reconnect`
-- HTTP/WebSocket proxy and browser runtime: `@floegence/flowersec-core/proxy`
-- Observability: `@floegence/flowersec-core/observability`
+`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.
 
-High-level WebSocket connections require TLS by default. Use `AllowPlaintextForLoopback` only for literal local development targets.
+`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.
 
-## Node Proxy Server
+Candidate lists, runtime capability descriptors, transport factories, admission state, Yamux, wire messages, cryptographic state, keys, and spend-ledger internals are not package exports.
 
-The Node entrypoint exports `serveProxySession(...)`, `serveProxyStream(...)`, and `ProxyServerOptions`. HTTP request and response bodies stream between Flowersec chunk frames and the upstream fetch while remaining bounded per request by `maxBodyBytes`. Proxy sessions admit at most `maxConcurrentStreams` HTTP/WebSocket streams, with a shared default of 64; RPC serving has its own concurrency controls. WebSocket frames remain bounded by `maxWsFrameBytes`; `maxWsQueuedBytes` additionally caps upstream-to-Yamux queued bytes per connection, while the reverse direction waits for each Node `ws` send callback.
+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 defaults keep one queued WebSocket frame plus its proxy header. Raise body, concurrency, or queue limits only when the deployment has matching upstream and memory capacity.
+The proxy entrypoint accepts an opaque `ArtifactLease` or an already connected `Session`. Its public runtime never exposes the selected carrier, a Yamux stream, raw artifact fields, or proxy wire frames. 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.
 
-## Runtime Boundaries
+## Transport v2 Support
 
-TypeScript owns browser and Service Worker integration. Shared tunnel, proxy gateway, and helper binaries remain Go-owned.
+WebSocket, raw QUIC, and WebTransport are equal carrier candidates. Browser and Node.js support below describes this SDK's profiles, not the portable API.
+
+Raw QUIC and WebTransport preserve native FIN, RESET_STREAM, STOP_SENDING, flow control, and migration behavior. The TypeScript SDK support below is narrower than the protocol carrier set.
+
+WebSocket uses Yamux only inside its carrier adapter. Yamux has no independent STOP_SENDING primitive, so that operation is explicitly unavailable rather than emulated with a full stream reset.
+
+Browser applications receive a ready `Session` from `connect(...)`. The browser connector supports WSS and WebTransport production connections. WebTransport uses native HTTP/3 bidirectional streams and does not use Yamux.
+
+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.js connector supports WSS and WebTransport production connections for direct and tunnel artifacts. It requires an absolute HTTP(S) `origin`; a custom certificate authority can be supplied through `tls.ca`. Invalid origin and TLS options fail as `ConnectError` with `invalid_options` and are terminal to the optional connection controller.
+
+The Node WebTransport direct listener/server is owned by the Node runtime and the `flowersec-ts-cli` server path. It uses the same native carrier acceptor and session engine as the client connector; it is not a second protocol implementation.
+
+The connectors select an eligible transport from the opaque artifact internally. They do not accept a public transport selector, capability manifest, candidate factory, or admission-reason override. Unsupported artifacts fail closed. The TypeScript package does not expose raw QUIC dialing.
+
+Transport v2 production carrier support: browsers support WebSocket and WebTransport; Node.js supports WebSocket and WebTransport dialing for direct clients and both tunnel roles. Node WebTransport uses the pinned native quiche adapter and is covered by a real admission/session integration test without Playwright.
+
+Flowersec disables application 0-RTT. Reliable streams never use QUIC DATAGRAM; runtimes with negotiated native DATAGRAM expose it only through carrier-neutral unreliable messages.
+
+## Verify
+
+```bash
+npm run build
+npm test
+npm run verify:package
+```
 
-Review the shared [API contract](../docs/API_CONTRACT.md), [protocol](../docs/PROTOCOL.md), [threat model](../docs/THREAT_MODEL.md), and [error model](../docs/ERROR_MODEL.md).
+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).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,141 @@
+# Third Party Notices
+
+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.
+
+- @fails-components/webtransport 1.6.7 (Declared: BSD-3-Clause; selected: BSD-3-Clause; source: https://registry.npmjs.org/@fails-components/webtransport/-/webtransport-1.6.7.tgz)
+- @fails-components/webtransport-transport-http3-quiche 1.6.7 (Declared: BSD-3-Clause; selected: BSD-3-Clause; source: https://registry.npmjs.org/@fails-components/webtransport-transport-http3-quiche/-/webtransport-transport-http3-quiche-1.6.7.tgz)
+- @isaacs/fs-minipass 4.0.1 (Declared: ISC; selected: ISC; source: https://registry.npmjs.org/@isaacs/fs-minipass/-/fs-minipass-4.0.1.tgz)
+- @noble/ciphers 0.6.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/@noble/ciphers/-/ciphers-0.6.0.tgz)
+- @noble/curves 1.9.7 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/@noble/curves/-/curves-1.9.7.tgz)
+- @noble/hashes 1.8.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/@noble/hashes/-/hashes-1.8.0.tgz)
+- @types/debug 4.1.13 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/@types/debug/-/debug-4.1.13.tgz)
+- @types/ms 2.1.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/@types/ms/-/ms-2.1.0.tgz)
+- ansi-regex 5.0.1 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz)
+- ansi-styles 4.3.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz)
+- base64-js 1.5.1 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz)
+- bindings 1.5.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/bindings/-/bindings-1.5.0.tgz)
+- bl 4.1.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/bl/-/bl-4.1.0.tgz)
+- buffer 5.7.1 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/buffer/-/buffer-5.7.1.tgz)
+- chownr 1.1.4 (Declared: ISC; selected: ISC; source: https://registry.npmjs.org/chownr/-/chownr-1.1.4.tgz)
+- chownr 3.0.0 (Declared: BlueOak-1.0.0; selected: BlueOak-1.0.0; source: https://registry.npmjs.org/chownr/-/chownr-3.0.0.tgz)
+- cliui 8.0.1 (Declared: ISC; selected: ISC; source: https://registry.npmjs.org/cliui/-/cliui-8.0.1.tgz)
+- cmake-js 8.0.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/cmake-js/-/cmake-js-8.0.0.tgz)
+- color-convert 2.0.1 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz)
+- color-name 1.1.4 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz)
+- debug 4.4.3 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/debug/-/debug-4.4.3.tgz)
+- decompress-response 6.0.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/decompress-response/-/decompress-response-6.0.0.tgz)
+- deep-extend 0.6.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/deep-extend/-/deep-extend-0.6.0.tgz)
+- detect-libc 2.1.2 (Declared: Apache-2.0; selected: Apache-2.0; source: https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz)
+- emoji-regex 8.0.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz)
+- end-of-stream 1.4.5 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/end-of-stream/-/end-of-stream-1.4.5.tgz)
+- escalade 3.2.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz)
+- expand-template 2.0.3 (Declared: MIT OR WTFPL; selected: MIT; source: https://registry.npmjs.org/expand-template/-/expand-template-2.0.3.tgz)
+- file-uri-to-path 1.0.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/file-uri-to-path/-/file-uri-to-path-1.0.0.tgz)
+- fs-constants 1.0.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/fs-constants/-/fs-constants-1.0.0.tgz)
+- fs-extra 11.4.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/fs-extra/-/fs-extra-11.4.0.tgz)
+- get-caller-file 2.0.5 (Declared: ISC; selected: ISC; source: https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz)
+- github-from-package 0.0.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/github-from-package/-/github-from-package-0.0.0.tgz)
+- graceful-fs 4.2.11 (Declared: ISC; selected: ISC; source: https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz)
+- ieee754 1.2.1 (Declared: BSD-3-Clause; selected: BSD-3-Clause; source: https://registry.npmjs.org/ieee754/-/ieee754-1.2.1.tgz)
+- inherits 2.0.4 (Declared: ISC; selected: ISC; source: https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz)
+- ini 1.3.8 (Declared: ISC; selected: ISC; source: https://registry.npmjs.org/ini/-/ini-1.3.8.tgz)
+- is-fullwidth-code-point 3.0.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz)
+- isexe 4.0.0 (Declared: BlueOak-1.0.0; selected: BlueOak-1.0.0; source: https://registry.npmjs.org/isexe/-/isexe-4.0.0.tgz)
+- jsonfile 6.2.1 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/jsonfile/-/jsonfile-6.2.1.tgz)
+- mimic-response 3.1.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/mimic-response/-/mimic-response-3.1.0.tgz)
+- minimist 1.2.8 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/minimist/-/minimist-1.2.8.tgz)
+- minipass 7.1.3 (Declared: BlueOak-1.0.0; selected: BlueOak-1.0.0; source: https://registry.npmjs.org/minipass/-/minipass-7.1.3.tgz)
+- minizlib 3.1.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/minizlib/-/minizlib-3.1.0.tgz)
+- mkdirp-classic 0.5.3 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/mkdirp-classic/-/mkdirp-classic-0.5.3.tgz)
+- ms 2.1.3 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/ms/-/ms-2.1.3.tgz)
+- napi-build-utils 2.0.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/napi-build-utils/-/napi-build-utils-2.0.0.tgz)
+- node-abi 3.94.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/node-abi/-/node-abi-3.94.0.tgz)
+- node-addon-api 7.1.1 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/node-addon-api/-/node-addon-api-7.1.1.tgz)
+- node-api-headers 1.9.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/node-api-headers/-/node-api-headers-1.9.0.tgz)
+- once 1.4.0 (Declared: ISC; selected: ISC; source: https://registry.npmjs.org/once/-/once-1.4.0.tgz)
+- prebuild-install 7.1.3 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/prebuild-install/-/prebuild-install-7.1.3.tgz)
+- pump 3.0.4 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/pump/-/pump-3.0.4.tgz)
+- punycode 2.3.1 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/punycode/-/punycode-2.3.1.tgz)
+- rc 1.2.8 (Declared: BSD-2-Clause OR MIT OR Apache-2.0; selected: MIT; source: https://registry.npmjs.org/rc/-/rc-1.2.8.tgz)
+- readable-stream 3.6.2 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/readable-stream/-/readable-stream-3.6.2.tgz)
+- require-directory 2.1.1 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz)
+- safe-buffer 5.2.1 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz)
+- semver 7.7.3 (Declared: ISC; selected: ISC; source: https://registry.npmjs.org/semver/-/semver-7.7.3.tgz)
+- simple-concat 1.0.1 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/simple-concat/-/simple-concat-1.0.1.tgz)
+- simple-get 4.0.1 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/simple-get/-/simple-get-4.0.1.tgz)
+- string_decoder 1.3.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/string_decoder/-/string_decoder-1.3.0.tgz)
+- string-width 4.2.3 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz)
+- strip-ansi 6.0.1 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz)
+- strip-json-comments 2.0.1 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-2.0.1.tgz)
+- tar 7.5.22 (Declared: BlueOak-1.0.0; selected: BlueOak-1.0.0; source: https://registry.npmjs.org/tar/-/tar-7.5.22.tgz)
+- tar-fs 2.1.5 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/tar-fs/-/tar-fs-2.1.5.tgz)
+- tar-stream 2.2.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/tar-stream/-/tar-stream-2.2.0.tgz)
+- tr46 5.0.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/tr46/-/tr46-5.0.0.tgz)
+- tunnel-agent 0.6.0 (Declared: Apache-2.0; selected: Apache-2.0; source: https://registry.npmjs.org/tunnel-agent/-/tunnel-agent-0.6.0.tgz)
+- universalify 2.0.1 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/universalify/-/universalify-2.0.1.tgz)
+- url-join 4.0.1 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/url-join/-/url-join-4.0.1.tgz)
+- util-deprecate 1.0.2 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz)
+- which 6.0.1 (Declared: ISC; selected: ISC; source: https://registry.npmjs.org/which/-/which-6.0.1.tgz)
+- wrap-ansi 7.0.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz)
+- wrappy 1.0.2 (Declared: ISC; selected: ISC; source: https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz)
+- ws 8.21.0 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/ws/-/ws-8.21.0.tgz)
+- y18n 5.0.8 (Declared: ISC; selected: ISC; source: https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz)
+- yallist 5.0.0 (Declared: BlueOak-1.0.0; selected: BlueOak-1.0.0; source: https://registry.npmjs.org/yallist/-/yallist-5.0.0.tgz)
+- yargs 17.7.3 (Declared: MIT; selected: MIT; source: https://registry.npmjs.org/yargs/-/yargs-17.7.3.tgz)
+- yargs-parser 21.1.1 (Declared: ISC; selected: ISC; source: https://registry.npmjs.org/yargs-parser/-/yargs-parser-21.1.1.tgz)
+## Distributed Dependency License Materials
+
+The following dependencies are incorporated into distributed Flowersec files or binaries.
+Their reviewed upstream license, notice, copyright, and patent materials are reproduced below.
+
+### punycode 2.3.1
+
+#### Reviewed bundled license text
+
+Copyright Mathias Bynens <https://mathiasbynens.be/>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+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
+
+#### Reviewed bundled license text
+
+The MIT License (MIT)
+
+Copyright (c) Sebastian Mayr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE 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.

package/dist/browser/connectSession.d.ts

@@ -0,0 +1,13 @@
+import type { ArtifactLease } from "../public/artifactLease.js";
+import type { Session } from "../public/contract.js";
+import { type ArtifactSource, type ConnectionController } from "../connectionController.js";
+export type SessionOptions = Readonly<{
+    signal?: AbortSignal;
+    connectTimeoutMs?: number;
+}>;
+export type ConnectionControllerOptions = Readonly<{
+    connectTimeoutMs?: number;
+    maximumAttempts?: number;
+}>;
+export declare function createConnectionController(source: ArtifactSource, options?: ConnectionControllerOptions): ConnectionController;
+export declare function connect(lease: ArtifactLease, options?: SessionOptions): Promise<Session>;

package/dist/browser/connectSession.js

@@ -0,0 +1,40 @@
+import { composeCandidateAttemptFactoryV2, SessionConnectorV2, } from "../connector/sessionConnector.js";
+import { createWebSocketCandidateFactoryV2 } from "../connector/adapters/webSocketCandidate.js";
+import { createWebTransportCandidateFactoryV2 } from "../connector/adapters/webTransportCandidate.js";
+import { detectBrowserRuntimeCapabilityV2 } from "./runtimeCapability.js";
+import { projectSessionV2 } from "../v2/publicSession.js";
+import { createBrowserWebTransportClientV2 } from "./webTransportClient.js";
+import { browserSessionRuntimeV2 } from "./sessionRuntime.js";
+import { createConnectionControllerV2, } from "../connectionController.js";
+export function createConnectionController(source, options = {}) {
+    const controllerOptions = options.maximumAttempts === undefined
+        ? {}
+        : { maximumAttempts: options.maximumAttempts };
+    return createConnectionControllerV2(source, async (lease, signal) => await connect(lease, {
+        signal,
+        ...(options.connectTimeoutMs === undefined ? {} : { connectTimeoutMs: options.connectTimeoutMs }),
+    }), controllerOptions);
+}
+export async function connect(lease, options = {}) {
+    const { signal, ...connectorOptions } = options;
+    const connector = new SessionConnectorV2(lease, composeCandidateAttemptFactoryV2({
+        websocket: createWebSocketCandidateFactoryV2(defaultWebSocketFactory),
+        webtransport: createWebTransportCandidateFactoryV2(async (candidate, artifact, signal) => await createBrowserWebTransportClientV2(candidate.normalized_url, {
+            path: artifact.path.kind,
+            inboundBidirectionalStreamCapacity: artifact.session.max_inbound_streams + 2,
+            signal,
+        })),
+    }), {
+        ...connectorOptions,
+        capability: detectBrowserRuntimeCapabilityV2(),
+        runtime: browserSessionRuntimeV2,
+    });
+    const result = await connector.connect(signal === undefined ? {} : { signal });
+    return projectSessionV2(result.session);
+}
+function defaultWebSocketFactory(url, subprotocol) {
+    const Constructor = globalThis.WebSocket;
+    if (Constructor === undefined)
+        throw new Error("WebSocket is unavailable in this browser runtime");
+    return new Constructor(url, subprotocol);
+}

package/dist/browser/index.d.ts

@@ -1,10 +1,3 @@
-export type { ConnectBrowserOptions, DirectConnectBrowserOptions, TunnelConnectBrowserOptions } from "./connect.js";
-export { connectBrowser, connectDirectBrowser, connectTunnelBrowser } from "./connect.js";
-export { AllowPlaintextForLoopback, createNetworkPlaintextPolicy, PlaintextRiskAcceptance, RequireTLS, } from "../client-connect/transportSecurity.js";
-export type { TransportSecurityPolicy, TransportSecurityPolicyInput, TransportSecurityPolicyPreset, NetworkPlaintextPolicyOptions, } from "../client-connect/transportSecurity.js";
-export type { ConnectArtifact, CorrelationContext, CorrelationKV, DirectClientConnectArtifact, ScopeMetadataEntry, TunnelClientConnectArtifact, } from "../connect/artifact.js";
-export { assertConnectArtifact } from "../connect/artifact.js";
-export type { RequestConnectArtifactInput, RequestEntryConnectArtifactInput } from "../controlplane/request.js";
-export { requestConnectArtifact, requestEntryConnectArtifact, } from "../controlplane/request.js";
-export type { BrowserReconnectConfig, DirectBrowserReconnectConfig, TunnelBrowserReconnectConfig, } from "./reconnectConfig.js";
-export { createBrowserReconnectConfig, createDirectBrowserReconnectConfig, createTunnelBrowserReconnectConfig, } from "./reconnectConfig.js";
+export * from "../facade.js";
+export { connect, createConnectionController } from "./connectSession.js";
+export type { ConnectionControllerOptions, SessionOptions, } from "./connectSession.js";

package/dist/browser/index.js

@@ -1,5 +1,2 @@
-export { connectBrowser, connectDirectBrowser, connectTunnelBrowser } from "./connect.js";
-export { AllowPlaintextForLoopback, createNetworkPlaintextPolicy, PlaintextRiskAcceptance, RequireTLS, } from "../client-connect/transportSecurity.js";
-export { assertConnectArtifact } from "../connect/artifact.js";
-export { requestConnectArtifact, requestEntryConnectArtifact, } from "../controlplane/request.js";
-export { createBrowserReconnectConfig, createDirectBrowserReconnectConfig, createTunnelBrowserReconnectConfig, } from "./reconnectConfig.js";
+export * from "../facade.js";
+export { connect, createConnectionController } from "./connectSession.js";

package/dist/browser/runtimeCapability.d.ts

@@ -0,0 +1,13 @@
+import { type RuntimeCapabilityDescriptorV2, type UnsupportedRuntimeCarrierV2 } from "../v2/capability.js";
+export type BrowserRuntimeFeaturesV2 = Readonly<{
+    WebSocket?: unknown;
+    WebTransport?: unknown;
+}>;
+export declare const BROWSER_RUNTIME_CAPABILITY_V2: Readonly<{
+    language: string;
+    runtime: string;
+    schemaVersion: 2;
+    tuples: readonly import("../v2/capability.js").RuntimeCapabilityTupleV2[];
+    unsupported: readonly UnsupportedRuntimeCarrierV2[];
+}>;
+export declare function detectBrowserRuntimeCapabilityV2(runtime?: BrowserRuntimeFeaturesV2): RuntimeCapabilityDescriptorV2;

package/dist/browser/runtimeCapability.js

@@ -0,0 +1,27 @@
+import { defineRuntimeCapabilityDescriptorV2, } from "../v2/capability.js";
+import { hasWebTransportConstructorSurfaceV2 } from "../transport/webTransportAdapter.js";
+const tuples = Object.freeze([
+    { carrier: "websocket", datagrams: false, migration: false, networkMode: "dial", path: "direct", reliableStreams: true, sessionRole: "client" },
+    { carrier: "websocket", datagrams: false, migration: false, networkMode: "dial", path: "tunnel", reliableStreams: true, sessionRole: "client" },
+    { carrier: "websocket", datagrams: false, migration: false, networkMode: "dial", path: "tunnel", reliableStreams: true, sessionRole: "server" },
+    { carrier: "webtransport", datagrams: true, migration: false, networkMode: "dial", path: "direct", reliableStreams: true, sessionRole: "client" },
+    { carrier: "webtransport", datagrams: true, migration: false, networkMode: "dial", path: "tunnel", reliableStreams: true, sessionRole: "client" },
+    { carrier: "webtransport", datagrams: true, migration: false, networkMode: "dial", path: "tunnel", reliableStreams: true, sessionRole: "server" },
+]);
+export const BROWSER_RUNTIME_CAPABILITY_V2 = defineRuntimeCapabilityDescriptorV2("browser", tuples, [{ carrier: "raw_quic", reason: "browser_no_raw_udp" }]);
+export function detectBrowserRuntimeCapabilityV2(runtime = globalThis) {
+    const available = new Set();
+    if (typeof runtime.WebSocket === "function")
+        available.add("websocket");
+    if (hasWebTransportConstructorSurfaceV2(runtime.WebTransport))
+        available.add("webtransport");
+    const unsupported = [{ carrier: "raw_quic", reason: "browser_no_raw_udp" }];
+    if (!available.has("websocket")) {
+        unsupported.push({ carrier: "websocket", reason: "browser_websocket_api_unavailable" });
+    }
+    if (!available.has("webtransport")) {
+        unsupported.push({ carrier: "webtransport", reason: "browser_webtransport_api_unavailable" });
+    }
+    unsupported.sort((left, right) => left.carrier.localeCompare(right.carrier));
+    return defineRuntimeCapabilityDescriptorV2("browser", tuples.filter(({ carrier }) => available.has(carrier)), unsupported);
+}

package/dist/browser/sessionRuntime.d.ts

@@ -0,0 +1,2 @@
+import type { SessionProtocolRuntimeV2 } from "../v2/session.js";
+export declare const browserSessionRuntimeV2: SessionProtocolRuntimeV2;

package/dist/browser/sessionRuntime.js

@@ -0,0 +1,21 @@
+import { RuntimeError } from "../runtime/errors.js";
+export const browserSessionRuntimeV2 = Object.freeze({
+    entropy(length) {
+        requireLength(length);
+        const runtime = globalThis.crypto;
+        if (runtime === undefined || typeof runtime.getRandomValues !== "function") {
+            throw new RuntimeError("runtime_unsupported", "browser cryptographic entropy is unavailable");
+        }
+        const output = new Uint8Array(length);
+        runtime.getRandomValues(output);
+        return output;
+    },
+    monotonicMilliseconds() {
+        return performance.now();
+    },
+});
+function requireLength(length) {
+    if (!Number.isSafeInteger(length) || length < 1 || length > 65_536) {
+        throw new RangeError("entropy length must be an integer from 1 to 65536");
+    }
+}

package/dist/browser/webTransportClient.d.ts

@@ -0,0 +1,8 @@
+import type { NativeCarrierSessionV2 } from "../v2/carrier.js";
+import type { PathKind } from "../v2/contract.js";
+export type BrowserWebTransportClientOptionsV2 = Readonly<{
+    path: PathKind;
+    inboundBidirectionalStreamCapacity: number;
+    signal?: AbortSignal;
+}>;
+export declare function createBrowserWebTransportClientV2(url: string, options: BrowserWebTransportClientOptionsV2): Promise<NativeCarrierSessionV2>;

package/dist/browser/webTransportClient.js

@@ -0,0 +1,55 @@
+import { adaptWebTransportCarrierSessionV2, } from "../transport/webTransportAdapter.js";
+import { RuntimeError } from "../runtime/errors.js";
+export async function createBrowserWebTransportClientV2(url, options) {
+    const parsed = validateWebTransportURL(url, options.path);
+    const Constructor = globalThis.WebTransport;
+    if (Constructor === undefined) {
+        throw new RuntimeError("runtime_unsupported", "WebTransport is unavailable in this browser runtime");
+    }
+    if (options.signal?.aborted === true)
+        throw options.signal.reason;
+    // Chromium does not implement a WebTransport pooling constructor option.
+    // Every carrier is one independent native WebTransport created from its URL.
+    const transport = new Constructor(parsed.href);
+    try {
+        await raceAbort(transport.ready, options.signal);
+        return adaptWebTransportCarrierSessionV2(transport, options);
+    }
+    catch (error) {
+        transport.close({ closeCode: 6, reason: "WebTransport start failed" });
+        const detail = error instanceof Error && error.message !== "" ? `: ${error.message}` : "";
+        throw new RuntimeError("runtime_start_failed", `browser WebTransport failed to start${detail}`, error);
+    }
+}
+function validateWebTransportURL(raw, path) {
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch (error) {
+        throw new RuntimeError("runtime_start_failed", "invalid WebTransport URL", error);
+    }
+    const expectedPath = path === "direct"
+        ? "/flowersec/webtransport/v2/direct"
+        : "/flowersec/webtransport/v2/tunnel";
+    if (parsed.protocol !== "https:" ||
+        parsed.username !== "" ||
+        parsed.password !== "" ||
+        parsed.pathname !== expectedPath ||
+        parsed.search !== "" ||
+        parsed.hash !== "") {
+        throw new RuntimeError("runtime_start_failed", `WebTransport URL must use ${expectedPath}`);
+    }
+    return parsed;
+}
+async function raceAbort(promise, signal) {
+    if (signal === undefined)
+        return await promise;
+    if (signal.aborted)
+        throw signal.reason;
+    return await new Promise((resolve, reject) => {
+        const abort = () => reject(signal.reason);
+        signal.addEventListener("abort", abort, { once: true });
+        void promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+    });
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};