openrtc 1.0.27 → 2.0.0-rc.1

package/README.md

@@ -1,228 +1,166 @@
-# OpenRTC TypeScript Package
+# OpenRTC
 
-The TypeScript package is the host-facing layer for `openrtc`.
+OpenRTC is a provider-neutral peer coordination and transport SDK for browsers,
+desktop applications, and mobile applications. The 2.0 API is capability based:
+constructing a client is local and side-effect free, and network work starts only
+when the application activates a device, space, room, or ticket handle.
 
-It does not implement a second realtime engine. It exposes the Rust runtime to:
-- browser apps through WASM plus the scoped browser Firebase signaling layer
-- native apps through a generic IPC contract, with first-party Tauri wiring in `openrtc-tauri`
+The core is message-agnostic. Named channels are the application protocol
+extension boundary; they do not replace the incoming router or authorize a
+parallel lifecycle owner.
 
-## Recommended Usage
+## Install
 
-Use the OpenRTC client entry points for new integrations, and choose the
-avenue that matches your product:
+```bash
+pnpm add openrtc
+```
+
+## Fast prototype
 
-- `user-scoped` for a signed-in user's durable device mesh
-- `space` for a small live shared namespace
-- rooms for intentional group membership
-- tickets/share grants for explicit one-off pairing without a roster
+Only a public API key is required for a bounded ephemeral space:
 
 ```ts
 import { OpenRTC } from 'openrtc';
 
-const client = OpenRTC({
-  apiKey: 'pk_live_...',
-  discoveryMode: 'user-scoped',
-  authMode: 'external',
+const rtc = OpenRTC({ apiKey: import.meta.env.VITE_OPENRTC_API_KEY });
+const cursors = await rtc.spaces.join('portfolio-cursors', {
+  access: 'capability',
+  identity: 'ephemeral',
+  payload: 'latest-state',
+});
+
+const stop = cursors.peers.watch((peers) => console.log(peers));
+
+// Later
+stop();
+await cursors.leave();
+await rtc.close();
+```
+
+The constructor performs no network request, storage access, authentication,
+attestation, timer creation, WASM load, or transport startup.
+
+## Authenticated devices
+
+Your application owns login and supplies a short-lived assertion from its
+registered OIDC/JWKS provider. OpenRTC validates it, binds the installation's
+device key, and issues scoped gateway grants.
+
+```ts
+const auth = {
+  getAssertion: ({ forceRefresh }: { forceRefresh: boolean }) =>
+    fetch('/api/openrtc/assertion', {
+      method: 'POST',
+      headers: { 'X-Force-Refresh': String(forceRefresh) },
+    }).then((response) => response.text()),
+};
+
+const rtc = OpenRTC({
+  apiKey: import.meta.env.VITE_OPENRTC_API_KEY,
+  auth,
+});
+
+const devices = await rtc.devices.start({
+  auth,
+  autoConnect: 'online',
+});
+```
+
+Consumer apps own login UX, product authorization, IdP registration, and
+platform-attestation setup. OpenRTC owns assertion validation, device binding,
+grant issuance and refresh, revocation, budgets, metering, and abuse controls.
+
+## Rooms
+
+Rooms default to ephemeral membership:
+
+```ts
+const room = await rtc.rooms.join('match-123', {
+  access: 'capability',
+  membership: 'ephemeral',
+  maxPeers: 8,
 });
+```
+
+Durable membership is an advanced capability and must be enabled in the
+developer portal and requested by the application:
 
-await client.connect();
-await client.devices.startSession({
-  deviceName: 'Work Laptop',
+```ts
+const team = await rtc.rooms.join('team', {
+  access: 'authenticated',
+  membership: 'durable',
+  auth,
 });
 ```
 
-For normal app code, the default flow is:
+Every long-lived capability has `close()`; spaces and rooms also have
+`leave()`. One handle activates exactly one avenue.
+
+## Optional trust adapters
 
-1. discover or select a device
-2. open a named logical app channel with `client.channels.connect({ device, channelId })`
-3. send and receive app payloads on that channel
+Attestation is evaluated at device enrollment, key rotation, recovery, or risk
+escalation—not as a connection heartbeat.
 
-`channels.connect(...)` owns the peer dial, readiness wait, channel selection,
-roster-ticket reuse, and default `session` lifecycle scope. Use `client.peers.connect(...)`,
-`client.channels.openBi(...)`, `connectScoped(...)`, `openPeerBi(...)`, or
-`openPeerUni(...)` only when you need explicit lifecycle, stream, or transport
-control.
+```ts
+import { FirebaseAppCheckAttestationProvider } from '@openrtc/trust-firebase-app-check';
+
+const rtc = OpenRTC({
+  apiKey,
+  auth,
+  trust: {
+    attestation: new FirebaseAppCheckAttestationProvider({ appCheck }),
+  },
+});
+```
 
-## Naming Guide
+Managed Firebase App Check, Apple App Attest, and Play Integrity are optional
+packages. A consumer backend may instead validate platform evidence and issue
+the registered OIDC assertion; that is the canonical production integration.
 
-Prefer the short app-facing names in new code:
+## Usage controls
 
 ```ts
-import { OpenRTC, spaceToken } from 'openrtc';
-
-const client = OpenRTC({
-  apiKey: 'pk_live_...',
-  discoveryMode: 'space',
-  authMode: 'anonymous',
-  space: 'team-canvas',
-  spaceTokenProvider: spaceToken({
-    apiKey: 'pk_live_...',
-    space: 'team-canvas',
-  }),
+const rtc = OpenRTC({
+  apiKey,
+  usage: {
+    warnAtSessionCreditsUsd: 0.25,
+    maxSessionCreditsUsd: 0.50,
+    onUsage: console.log,
+    onWarning: console.warn,
+  },
 });
+
+rtc.usage.estimate({ operation: 'coordination.connection.open', units: 3 });
 ```
 
-- Use `space` instead of `spaceKey` in app code.
-- Use `spaceTokenProvider` and `spaceToken(...)` for scoped shared-space auth.
-- Use `client.devices.*`, `client.rooms.*`, `client.tickets.*`,
-  `client.channels.*`, and `client.peers.*` before reaching for lower-level
-  runtime names.
-
-## Discovery Avenues
-
-OpenRTC discovery is not one generic live device list:
-
-- User-scope/user-device is the persistent owned-device avenue. Devices remain
-  visible while `presenceStatus` degrades `online` -> `idle` -> `offline`, and
-  are removed only by explicit deletion or offline retention expiry.
-- Spaces and rooms are ephemeral collaboration avenues. Active rosters may
-  filter or clean up stale entries.
-- Ticket-only/share flows do not use a hosted discovery roster; the ticket or
-  grant is the bootstrap avenue.
-
-Status-aware device APIs should preserve presence-only changes and merge
-authoritative roster refreshes with live watch state so no avenue-specific
-device disappears just because one read model missed it.
-
-## What This Package Owns
-- runtime factories and adapters
-- auth context injection
-- Pluto hosted auth helpers
-- browser Firebase signaling/rooms wiring
-- host wiring for WASM and generic IPC
-
-## What This Package Does Not Own
-- native Tauri API bindings
-- peer discovery or lifecycle policy beyond the browser Firebase host layer
-- iroh connection lifecycle
-
-Those responsibilities belong to the Rust runtime and the host platform adapter.
-
-## Message Model
-- `openrtc` is message-agnostic above the runtime layer.
-- The runtime only defines internal control messages such as handshake and heartbeat.
-- Application payload protocols, including file transfer, should be implemented on top of generic runtime connections and streams.
-- If an app needs richer payload ergonomics, add generic stream/connection primitives to the runtime instead of adding app-specific message types to `pluto-rtc`.
-
-## Protocol Extension Model
-
-The recommended TypeScript extension path is:
-
-1. choose the public avenue (`user-scoped`, `space`, room, or ticket/share)
-2. open a named logical channel with `client.channels.connect(...)`
-3. implement your own framing and message semantics in app code
-
-This keeps the runtime responsible for peer/session establishment while leaving
-full control of channel/message specifics to the developer.
-
-Register a `RuntimeChannelDescriptor` with `client.channels.register(...)` and
-install one process-level `client.channels.onIncomingChannel(...)` handler when
-the protocol needs explicit readiness, routing, or framing metadata. This is an
-application protocol extension. It does not replace the incoming router or
-grant authority over admission, peer scopes, dialing, retry, transport
-promotion, recovery, or settlement.
-
-`OpenRTCClient` still inherits `RuntimeClient` compatibility methods, and
-`openrtc/runtime`, `client.peers.addScope()` / `releaseScope()`, and
-`client.advanced` expose authority-capable manual surfaces. They are not the
-recommended extension model and must not be used to build a parallel lifecycle.
-Their narrowing is future-version work.
-
-Advanced custom ALPN protocol plugins are a Rust-first/native-first feature.
-Browser parity is guaranteed at the connected-peer stream layer, not at the
-full ALPN plugin layer.
-
-For applications that want a reusable file protocol without making it part of
-the core runtime, install `openrtc-file-transfer`. It implements versioned,
-bounded file framing, acknowledgement, progress, cancellation, optional
-integrity verification, and streaming receive sinks. Modern clients send
-receiver-acknowledged segments through OpenRTC's current application route;
-the named-channel stream carrier remains compatibility fallback.
-Filesystem destinations, persistent queues, history, acceptance prompts, and
-product policy remain consumer-owned.
-
-## Main Surfaces
-
-### Root Package
-- `OpenRTC()`
-- `OpenRTC.native()`
-
-### Native-only Entrypoint
-- `openrtc/native`
-- `createNativeOpenRTC(options, bridge)`
-- excludes the browser WASM adapter and binary from Tauri webview bundles
-
-### Runtime Secondary Entrypoint
-- `openrtc/runtime`
-- `RuntimeClient`
-- `createWasmClient()` and `createIpcClient(..., bridge)` (legacy compatibility)
-- `IpcRuntimeAdapter`
-- `WasmRuntimeAdapter`
-- `PlutoIpcBridge` types for advanced host integrations
-
-### Tauri Package
-- `openrtc-tauri`
-- `createTauriIpcBridge()`
-- `TauriRuntimeAdapter`
-- Rust plugin crate: `openrtc-tauri-plugin`
-- `openrtc/runtime/tauri` remains as a deprecated compatibility shim for one release cycle
-
-For Tauri desktop/mobile apps, use `createNativeOpenRTC(options, bridge)` from
-`openrtc/native` with the `openrtc-tauri` bridge and register
-`openrtc-tauri-plugin` in the Rust Tauri
-builder. Do not copy product-owned RTC command files into new apps. The plugin
-owns the native IPC command set and delegates lifecycle, discovery, presence,
-auto-connect, and connection state to one `openrtc::client::Client`. Do not use
-`OpenRTC(options)` or the compatibility `OpenRTC.native(options)` entry inside a
-Tauri shell unless you intentionally want the
-browser/WASM runtime for a prototype; that path bypasses the native Rust runtime
-or retains browser-runtime bundle reachability and can hide native
-lifecycle/presence issues from tests.
-
-Mobile hosts should forward connectivity-restored callbacks through
-`client.advanced.notifyNetworkChange(reason)`. The Tauri plugin passes this hint
-to the existing Iroh endpoint so it can reconsider relay and direct paths; it
-does not create a second OpenRTC dial or retry loop.
-
-## Auth Model
-- `anonymous`: no Pluto auth required
-- `required`: Pluto auth required; the SDK may initiate Pluto SSO
-- `external`: Pluto auth still required, but the host app acquires it and injects it into the runtime
-
-## Security Boundary
-
-Iroh authenticates endpoint keys and encrypts transport traffic. OpenRTC's
-managed avenues add scoped session-token admission and application payload
-encryption. These protections are cumulative: transport connectivity alone is
-not permission to invoke a product action.
-
-- Prefer `client.devices`, `client.rooms`, `client.tickets`, and
-  `client.channels` managed flows; they retain admission and protected-route
-  checks across transport replacement.
-- Treat raw endpoint tickets and low-level manual peer APIs as transport
-  primitives. A consumer using them must define its own authorization boundary.
-- Authorize every privileged message against the accepted OpenRTC scope and the
-  consumer application's current ACL. Never trust a payload's self-declared
-  sender, role, or scope.
-- Keep compound tickets and session tokens out of logs, telemetry, query
-  strings, crash reports, and UI diagnostics. Use URL fragments for intentional
-  browser handoff and scrub them immediately after capture.
-- Revocation must invalidate the matching scope and product ACL; reconnecting a
-  transport must not restore revoked access.
-
-The full owner and release contract is in
-[`docs/architecture/application-security-and-delivery-contract.md`](../../docs/architecture/application-security-and-delivery-contract.md).
-
-## Design Rule
-If a feature requires discovery, signaling, presence, or lifecycle state, the TypeScript package should delegate to Rust rather than reimplement it locally, except for the scoped browser Firebase host layer where the official browser SDK is the source of truth. In both cases, keep the avenue semantics intact: persistent user-device rosters are not space/room live rosters.
-
-## Allowed vs. Not Allowed
-
-- Allowed:
-  - host/runtime adapter selection
-  - auth injection and hosted Pluto auth helpers
-  - thin, typed wrappers over Rust-owned state
-- Not allowed:
-  - TypeScript-owned discovery or lifecycle engines
-  - TypeScript-owned peer identity policy
-  - app-specific protocol messages embedded into the runtime
+The client ceiling is an additional local guard. Server budgets and developer
+manifest limits remain authoritative.
+
+## Native and WASM
+
+```ts
+import { createNativeOpenRTC } from 'openrtc/native';
+import { createTauriIpcBridge } from 'openrtc-tauri/ipc';
+
+const rtc = createNativeOpenRTC({ apiKey, auth }, createTauriIpcBridge());
+```
+
+Native hosts keep one Ed25519 installation key in host secure storage. Browsers
+use a non-extractable WebCrypto key in IndexedDB when supported. The Rust and
+WASM clients use the same provider-neutral avenue-grant contract as TypeScript.
+
+Low-level runtime access is intentionally isolated in `openrtc/runtime` for
+transport authors, migration harnesses, and diagnostics. Test endpoint
+overrides live only in `openrtc/testing`.
+
+## Extensions
+
+- `y-openrtc` adapts one activated room to Yjs.
+- `openrtc-netcode` owns matches, replicated state, latest-state transforms,
+  chat/control, and optional voice helpers.
+- `openrtc-file-transfer` owns bounded, acknowledged, resumable file transfer.
+
+Relay, durable membership, managed attestation, MoQ, and BLE require both
+portal enablement and explicit runtime opt-in. During the public RC, avenues
+default to 8 peers; 9-12 peers additionally require runtime `advancedFanout`
+and an operator-reviewed app allowlist.