openrtc 0.2.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,92 @@
+Required Notice: Copyright (c) 2026 Bryant Hargreaves and OpenRTC contributors.
+Licensor Line of Business: OpenRTC realtime collaboration runtime, SDKs, developer services, and related tools (https://openrtc.app)
+
+# PolyForm Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any product that competes with the software or any product the licensor or any of its affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality through different kinds of interfaces or for different technical platforms.  Applications can compete with services, libraries with plugins, frameworks with development tools, and so on, even if they're written in different programming languages or for different computer architectures.  Goods and services compete even when provided free of charge.  If you market a product as a practical substitute for the software or another product, it definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does not compete, but the licensor or any of its affiliates brings your product into competition by providing a new version of the software or another product using the software, you may continue using versions of the software available under these terms beforehand to provide your competing product, but not any later versions.
+
+## Discontinued Products
+
+You may begin using the software to compete with a product or service that the licensor or any of its affiliates has stopped providing, unless the licensor includes a plain-text line beginning with `Licensor Line of Business:` with the software that mentions that line of business.  For example:
+
+> Licensor Line of Business: YoyodyneCMS Content Management System (http://example.com/cms)
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of business developing the software or using the software to provide a product, the buyer can also enforce [Noncompete](#noncompete) for that product.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+A **product** can be a good or service, or a combination of them.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all its affiliates.
+
+**Affiliates** means the other organizations than an organization has control over, is under the control of, or is under common control with.
+
+**Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/README.md

@@ -8,27 +8,40 @@ It does not implement a second realtime engine. It exposes the Rust runtime to:
 
 ## Recommended Usage
 
-Use the OpenRTC client entry points for new integrations:
+Use the OpenRTC client entry points for new integrations, and choose the
+avenue that matches your product:
+
+- `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
 
 ```ts
 import { OpenRTC } from 'openrtc';
 
 const client = OpenRTC({
   apiKey: 'pk_live_...',
+  discoveryMode: 'user-scoped',
   authMode: 'external',
 });
 
 await client.connect();
+await client.devices.startSession({
+  deviceName: 'Work Laptop',
+});
 ```
 
 For normal app code, the default flow is:
 
-1. discover or select a `deviceId`
-2. call `client.peers.connect(...)` or `client.devices.connect(...)`
-3. wait for `client.peers.waitConnected(deviceId)`
-4. open app channel streams with `client.channels.openBi(...)` / `client.channels.openUni(...)`
+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
 
-Low-level peer handles returned by runtime methods, along with `openPeerBi(deviceId)` and `openPeerUni(deviceId)`, remain available for advanced runtime flows, but they are not the default integration model.
+`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.
 
 ## Naming Guide
 
@@ -51,7 +64,25 @@ const client = OpenRTC({
 
 - Use `space` instead of `spaceKey` in app code.
 - Use `spaceTokenProvider` and `spaceToken(...)` for scoped shared-space auth.
-- Use `client.devices.*`, `client.peers.*`, and `client.channels.*` before reaching for lower-level runtime names.
+- 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
@@ -77,17 +108,37 @@ Those responsibilities belong to the Rust runtime and the host platform adapter.
 
 The recommended TypeScript extension path is:
 
-1. wait for a Rust-backed connected peer session
-2. open a bidirectional or unidirectional stream
+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 over `client.channels`.
+Filesystem destinations, persistent queues, history, acceptance prompts, and
+product policy remain consumer-owned.
+
 ## Main Surfaces
 
 ### Root Package
@@ -106,15 +157,54 @@ full ALPN plugin layer.
 - `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 `OpenRTC.native(options)` 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)` inside a Tauri shell unless you intentionally want the
+browser/WASM runtime for a prototype; that path bypasses the native Rust runtime
+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.
+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
 

package/dist/{DelegatingRuntimeAdapter-CjHzBEBA.d.ts → DelegatingRuntimeAdapter-By7pziBs.d.ts}

@@ -1,4 +1,5 @@
-import { D as DiscoveryMode, A as AuthMode, S as SignalingMode, E as ExplicitFileDataSendParams, I as ISignalingBackend, R as RuntimeIdentity, a as Device, b as DeviceStatusSnapshot, P as PeerSessionSnapshot, c as ResolvedPeerIdentity, M as ManagedConnectionRecord, d as SignalingEnvelope, e as DeviceEvent, f as SignalingSession, g as SessionEvent, L as LocalDeviceInfo, N as NativeManagedSessionStartResult, G as GrantScope, B as BackendPeerBiStream, h as BackendPeerUniStream, i as NativeConnectResult, j as BackendConnectionState } from './types-DyCGvj9l.js';
+import { D as DiscoveryMode, A as AuthMode, S as SignalingMode, E as ExplicitFileDataSendParams, I as ISignalingBackend, R as RuntimeIdentity, a as Device, b as DeviceStatusSnapshot, P as PeerSessionSnapshot, c as ResolvedPeerIdentity, M as ManagedConnectionRecord, d as SignalingEnvelope, e as DeviceEvent, f as SignalingSession, g as SessionEvent, L as LocalDeviceInfo, N as NativeManagedSessionStartResult, G as GrantScope, B as BackendPeerBiStream, h as BackendPeerUniStream, i as NativeConnectParams, j as NativeConnectResult, k as BackendConnectionState } from './types-CzIpGV9x.js';
+import { A as AuthContext } from './IEngineBridge-C7OT2CRv.js';
 
 type RuntimeAdapterKind = 'browser-wasm' | 'native-ipc' | 'tauri-ipc' | 'unknown';
 interface RuntimeCapabilities {
@@ -58,28 +59,42 @@ interface RuntimeCapabilityProfile {
     };
     nativeProtocols: RuntimeCapabilities['nativeProtocols'];
 }
+interface NativeRuntimeTransportFeatureStatus {
+    compiled?: boolean;
+    enabled?: boolean;
+}
+interface NativeRuntimeStatusSnapshot {
+    ready?: boolean;
+    nodeId?: string | null;
+    node_id?: string | null;
+    transport?: {
+        irohQuic?: NativeRuntimeTransportFeatureStatus;
+        irohLan?: NativeRuntimeTransportFeatureStatus;
+        webRtc?: NativeRuntimeTransportFeatureStatus;
+        webRtcLan?: NativeRuntimeTransportFeatureStatus;
+        moq?: NativeRuntimeTransportFeatureStatus;
+        ble?: NativeRuntimeTransportFeatureStatus;
+        irohRelayOnly?: boolean;
+        irohRelayTransportPolicy?: string | null;
+    };
+}
 declare const BROWSER_WASM_RUNTIME_CAPABILITIES: RuntimeCapabilities;
 declare const NATIVE_IPC_RUNTIME_CAPABILITIES: RuntimeCapabilities;
 declare function cloneRuntimeCapabilities(capabilities: RuntimeCapabilities): RuntimeCapabilities;
+declare function runtimeCapabilitiesFromNativeStatus(status: NativeRuntimeStatusSnapshot | null | undefined, allowWasmFallback?: boolean): RuntimeCapabilities;
 declare function runtimeCapabilityProfile(capabilities: RuntimeCapabilities): RuntimeCapabilityProfile;
 
-type AuthContext = {
-    userId: string;
-    token?: string | null;
-    refreshToken?: string | null;
-    customToken?: string | null;
-    tokenProvider?: (forceRefresh?: boolean) => Promise<string | null>;
-    expiresAtMs?: number | null;
-};
-
 interface WasmBridgeOptions {
     apiKey?: string;
     discoveryMode?: DiscoveryMode;
+    space?: string;
     spaceKey?: string;
     authMode?: AuthMode;
     signalingMode?: SignalingMode;
     projectId?: string;
     storagePrefix?: string;
+    deviceIdPersistence?: 'persistent' | 'ephemeral';
+    endpointIdPersistence?: 'persistent' | 'ephemeral';
     nodeIdPersistence?: 'persistent' | 'ephemeral';
     localDeviceId?: string;
     deviceName?: string;
@@ -101,6 +116,7 @@ declare abstract class DelegatingRuntimeAdapter implements ISignalingBackend {
     stopAuthScopedActivity(): Promise<void>;
     getTurnCredentials(): Promise<any>;
     updatePresence(localNodeId: string, ticketStr: string, isOnline: boolean, ttlMs: number, metadata?: string): Promise<void>;
+    refreshLivePresence(localNodeId: string, ticketStr: string, metadata?: string): Promise<void>;
     setOffline(localNodeId: string): Promise<void>;
     cleanupStaleDevices(): Promise<void>;
     searchDevices(excludeNodeId?: string): Promise<Device[]>;
@@ -140,6 +156,9 @@ declare abstract class DelegatingRuntimeAdapter implements ISignalingBackend {
         autoConnect?: boolean;
         presence?: boolean;
     }): Promise<NativeManagedSessionStartResult>;
+    notifyNetworkChange(options?: {
+        reason?: string;
+    }): Promise<unknown>;
     getManagedNodeId(options?: {
         initializeIfMissing?: boolean;
     }): Promise<string | null>;
@@ -150,20 +169,22 @@ declare abstract class DelegatingRuntimeAdapter implements ISignalingBackend {
     registerSessionToken(token: string, scope: GrantScope, maxConnections: number): Promise<void>;
     revokeSessionTokensByScope(scope: GrantScope): Promise<string[]>;
     openPeerBi(id: string, timeoutMs?: number): Promise<BackendPeerBiStream>;
+    incoming_streams(): Promise<ReadableStream<unknown>>;
     openPeerNativeBi(id: string, label: string, timeoutMs?: number): Promise<BackendPeerBiStream>;
     openPeerBiTransportOnly(id: string, timeoutMs?: number): Promise<BackendPeerBiStream>;
     openPeerUni(id: string, timeoutMs?: number): Promise<BackendPeerUniStream>;
-    connectToDevice(params: {
-        deviceId?: string | null;
-        endpointTicket: string;
-    }): Promise<NativeConnectResult>;
+    connectToDevice(params: NativeConnectParams): Promise<NativeConnectResult>;
     disconnectDevice(deviceId: string): Promise<void>;
     isConnected(nodeId: string): Promise<boolean>;
     getConnectionStates(): Promise<BackendConnectionState[]>;
     onConnectionStateChange(callback: (state: BackendConnectionState) => void): Promise<() => void> | (() => void);
+    /** @deprecated Use named channels or `openrtc-file-transfer`. */
     sendExplicitFilePath(connectionId: string, filePath: string, transferId?: string): Promise<string>;
+    /** @deprecated Use named channels or `openrtc-file-transfer`. */
     sendExplicitFileData(params: ExplicitFileDataSendParams): Promise<void>;
+    /** @deprecated Transfer history belongs to the consumer application. */
     getTransferHistory(limit?: number): Promise<Array<[string, unknown]>>;
+    /** @deprecated Transfer history belongs to the consumer application. */
     deleteTransferJob(jobId: string): Promise<void>;
     getRuntimeCapabilities(): RuntimeCapabilities;
     onIncomingNativeMessage(callback: (connectionId: string, remoteNodeId: string | null, message: any) => void): Promise<() => void>;
@@ -177,4 +198,4 @@ declare abstract class DelegatingRuntimeAdapter implements ISignalingBackend {
     setCoreClient(client: unknown): void;
 }
 
-export { type AuthContext as A, BROWSER_WASM_RUNTIME_CAPABILITIES as B, DelegatingRuntimeAdapter as D, NATIVE_IPC_RUNTIME_CAPABILITIES as N, type RuntimeCapabilities as R, type WasmBridgeOptions as W, type RuntimeCapabilityProfile as a, type RuntimeAdapterKind as b, cloneRuntimeCapabilities as c, runtimeCapabilityProfile as r };
+export { BROWSER_WASM_RUNTIME_CAPABILITIES as B, DelegatingRuntimeAdapter as D, NATIVE_IPC_RUNTIME_CAPABILITIES as N, type RuntimeCapabilities as R, type WasmBridgeOptions as W, type RuntimeCapabilityProfile as a, type RuntimeAdapterKind as b, type NativeRuntimeStatusSnapshot as c, type NativeRuntimeTransportFeatureStatus as d, cloneRuntimeCapabilities as e, runtimeCapabilityProfile as f, runtimeCapabilitiesFromNativeStatus as r };

package/dist/IEngineBridge-C7OT2CRv.d.ts

@@ -0,0 +1,10 @@
+type AuthContext = {
+    userId: string;
+    token?: string | null;
+    refreshToken?: string | null;
+    customToken?: string | null;
+    tokenProvider?: (forceRefresh?: boolean) => Promise<string | null>;
+    expiresAtMs?: number | null;
+};
+
+export type { AuthContext as A };

package/dist/{IpcRuntimeAdapter-CtckyMol.d.ts → IpcRuntimeAdapter-DymXAsNU.d.ts}

@@ -1,5 +1,5 @@
-import { C as ClientOptions } from './types-DyCGvj9l.js';
-import { W as WasmBridgeOptions, D as DelegatingRuntimeAdapter } from './DelegatingRuntimeAdapter-CjHzBEBA.js';
+import { C as ClientOptions } from './types-CzIpGV9x.js';
+import { W as WasmBridgeOptions, D as DelegatingRuntimeAdapter } from './DelegatingRuntimeAdapter-By7pziBs.js';
 
 type PlutoIpcUnlisten = () => void | Promise<void>;
 interface PlutoIpcBridge {
@@ -7,6 +7,9 @@ interface PlutoIpcBridge {
     listen<T = unknown>(event: string, handler: (payload: T) => void): Promise<PlutoIpcUnlisten>;
     isAvailable?(): boolean | Promise<boolean>;
 }
+type NativeIpcFailureKind = 'command-unavailable' | 'runtime-unavailable' | 'timeout' | 'unknown';
+declare function classifyNativeIpcFailure(error: unknown): NativeIpcFailureKind;
+declare function isNativeIpcCommandUnavailable(error: unknown): boolean;
 
 interface NativeIpcBridgeOptions extends WasmBridgeOptions {
     allowWasmFallback?: boolean;
@@ -22,4 +25,4 @@ declare class IpcRuntimeAdapter extends DelegatingRuntimeAdapter {
     constructor(options: IpcRuntimeAdapterOptions);
 }
 
-export { IpcRuntimeAdapter as I, type NativeIpcBridgeOptions as N, type PlutoIpcBridge as P, type IpcRuntimeAdapterOptions as a, type PlutoIpcUnlisten as b };
+export { IpcRuntimeAdapter as I, type NativeIpcBridgeOptions as N, type PlutoIpcBridge as P, type IpcRuntimeAdapterOptions as a, type NativeIpcFailureKind as b, type PlutoIpcUnlisten as c, classifyNativeIpcFailure as d, isNativeIpcCommandUnavailable as i };

package/dist/auth/index.js

@@ -1 +1 @@
-export{D as authHost,C as getAuthHost,B as registerDesktopAuthRelay}from'../chunk-YHJOXD46.js';
+export{H as authHost,G as getAuthHost,F as registerDesktopAuthRelay}from'../chunk-W5JHUOK5.js';

package/dist/auth/internal.js

@@ -1 +1 @@
-export{B as registerDesktopAuthRelay}from'../chunk-YHJOXD46.js';
+export{F as registerDesktopAuthRelay}from'../chunk-W5JHUOK5.js';