openrtc 0.2.1 → 1.0.0

package/README.md

@@ -115,10 +115,30 @@ The recommended TypeScript extension path is:
 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
@@ -149,11 +169,40 @@ auto-connect, and connection state to one `openrtc::client::Client`. Do not use
 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. In both cases, keep the avenue semantics intact: persistent user-device rosters are not space/room live rosters.
 

package/dist/{DelegatingRuntimeAdapter-BxOcVIx_.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-D0fRvUbN.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 {
@@ -83,23 +84,17 @@ declare function cloneRuntimeCapabilities(capabilities: RuntimeCapabilities): Ru
 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;
@@ -121,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[]>;
@@ -160,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>;
@@ -174,17 +173,18 @@ declare abstract class DelegatingRuntimeAdapter implements ISignalingBackend {
     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>;
@@ -198,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, type NativeRuntimeStatusSnapshot as c, type NativeRuntimeTransportFeatureStatus as d, cloneRuntimeCapabilities as e, runtimeCapabilityProfile as f, runtimeCapabilitiesFromNativeStatus 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-U5AEH0jn.d.ts → IpcRuntimeAdapter-DymXAsNU.d.ts}

@@ -1,5 +1,5 @@
-import { C as ClientOptions } from './types-D0fRvUbN.js';
-import { W as WasmBridgeOptions, D as DelegatingRuntimeAdapter } from './DelegatingRuntimeAdapter-BxOcVIx_.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 {

package/dist/auth/index.js

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

package/dist/auth/internal.js

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