openrtc 0.1.0

package/dist/core/config.d.ts

@@ -0,0 +1,31 @@
+import type { AuthMode, ClientOptions, DiscoveryMode, SignalingOptions } from './types';
+/** Validate that a string looks like a pluto-rtc API key (pk_live_... or pk_test_...). */
+export declare function isValidApiKeyFormat(value: string): boolean;
+/**
+ * Derive a deterministic space namespace from apiKey + spaceKey.
+ * Uses a simple hash to create a Firestore-safe document ID.
+ */
+export declare function deriveSpaceNamespace(apiKey: string, spaceKey: string): Promise<string>;
+/**
+ * Resolve the Firestore namespace for device discovery.
+ *
+ * For personal mode with a spaceKey: `spaces/{sha256(apiKey+spaceKey)}`
+ * For managed mode: `apps/{appTag}/users/{userId}`
+ * For legacy/fallback: `apps/{appTag}`
+ */
+export declare function resolveAppTag(options: Pick<ClientOptions, 'apiKey' | 'allowAnonymousHostedDefaults'> | Pick<SignalingOptions, 'apiKey' | 'allowAnonymousHostedDefaults'>): string;
+/**
+ * Resolve the Firestore collection path for device discovery based on discovery mode.
+ *
+ * - personal + spaceKey: `spaces/{hash}/devices`
+ * - user-scoped: `apps/{appTag}/users/{userId}/devices`
+ * - fallback: `apps/{appTag}/users/{userId}/devices`
+ */
+export declare function resolveDiscoveryPath(options: Pick<ClientOptions, 'apiKey' | 'discoveryMode' | 'spaceKey'>, context: {
+    userId?: string;
+    orgId?: string;
+}): Promise<string>;
+export declare function resolveDiscoveryMode(options: Pick<ClientOptions, 'discoveryMode'>): DiscoveryMode;
+export declare function resolveAuthMode(options: Pick<ClientOptions, 'authMode' | 'apiKey' | 'spaceKey'> | Pick<SignalingOptions, 'authMode'>): AuthMode;
+export declare function resolveProjectId(options: Pick<ClientOptions, 'projectId'> | Pick<SignalingOptions, 'projectId'>): string;
+export declare function resolveStorageNamespace(options: Pick<ClientOptions, 'apiKey' | 'storagePrefix'> | Pick<SignalingOptions, 'apiKey'>): string;

package/dist/core/config.js

@@ -0,0 +1,138 @@
+import { PLUTO_HOSTED_PROJECT_ID } from '../presets/plutoHosted';
+const warned = new Set();
+function warnOnce(key, message) {
+    if (warned.has(key))
+        return;
+    warned.add(key);
+    console.warn(message);
+}
+function allowAnonymousHostedDefaults(options) {
+    return options.allowAnonymousHostedDefaults === true;
+}
+/** Validate that a string looks like a pluto-rtc API key (pk_live_... or pk_test_...). */
+export function isValidApiKeyFormat(value) {
+    return /^pk_(live|test)_[0-9a-f]{40}$/.test(value);
+}
+/**
+ * Derive a deterministic space namespace from apiKey + spaceKey.
+ * Uses a simple hash to create a Firestore-safe document ID.
+ */
+export async function deriveSpaceNamespace(apiKey, spaceKey) {
+    const input = `${apiKey}:${spaceKey}`;
+    const encoder = new TextEncoder();
+    const data = encoder.encode(input);
+    const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    const hashHex = hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
+    return hashHex;
+}
+/**
+ * Resolve the Firestore namespace for device discovery.
+ *
+ * For personal mode with a spaceKey: `spaces/{sha256(apiKey+spaceKey)}`
+ * For managed mode: `apps/{appTag}/users/{userId}`
+ * For legacy/fallback: `apps/{appTag}`
+ */
+export function resolveAppTag(options) {
+    const apiKey = typeof options.apiKey === 'string' ? options.apiKey.trim() : '';
+    if (apiKey) {
+        if (!isValidApiKeyFormat(apiKey)) {
+            warnOnce(`invalid-api-key:${apiKey.slice(0, 10)}`, "[pluto-rtc] The provided `apiKey` does not match the expected format (pk_live_... or pk_test_...). " +
+                "Create an app at https://api.openrtc.app/developer.");
+        }
+        return `app_${apiKey.slice(-16)}`;
+    }
+    if (!allowAnonymousHostedDefaults(options)) {
+        throw new Error('[openrtc] `apiKey` is required. ' +
+            'If you intentionally need the old shared hosted fallback for a controlled demo or test, ' +
+            'set `allowAnonymousHostedDefaults: true` explicitly.');
+    }
+    warnOnce('no-api-key', "[pluto-rtc] No `apiKey` provided. Operating on the legacy shared hosted namespace because " +
+        "`allowAnonymousHostedDefaults` is enabled explicitly. Create an app at https://api.openrtc.app/developer.");
+    return 'app_anonymous';
+}
+/**
+ * Resolve the Firestore collection path for device discovery based on discovery mode.
+ *
+ * - personal + spaceKey: `spaces/{hash}/devices`
+ * - user-scoped: `apps/{appTag}/users/{userId}/devices`
+ * - fallback: `apps/{appTag}/users/{userId}/devices`
+ */
+export async function resolveDiscoveryPath(options, context) {
+    const rawMode = options.discoveryMode;
+    if (rawMode === 'org-scoped') {
+        throw new Error('[openrtc] discoveryMode "org-scoped" is not supported yet. Use "personal" or "user-scoped".');
+    }
+    if (rawMode && rawMode !== 'personal' && rawMode !== 'user-scoped') {
+        throw new Error(`[openrtc] Unsupported discoveryMode "${rawMode}". Use "personal" or "user-scoped".`);
+    }
+    const mode = rawMode === 'user-scoped' ? 'user-scoped' : 'personal';
+    const appTag = resolveAppTag(options);
+    if (mode === 'personal') {
+        const apiKey = typeof options.apiKey === 'string' ? options.apiKey.trim() : '';
+        const spaceKey = typeof options.spaceKey === 'string' ? options.spaceKey.trim() : '';
+        if (apiKey && spaceKey) {
+            const namespace = await deriveSpaceNamespace(apiKey, spaceKey);
+            return `spaces/${namespace}/devices`;
+        }
+        // No spaceKey: fall back to user-scoped path if userId available
+        if (context.userId) {
+            return `apps/${appTag}/users/${context.userId}/devices`;
+        }
+        warnOnce('personal-no-space-key', '[pluto-rtc] Personal mode without a spaceKey requires authentication. ' +
+            'Provide a spaceKey for passwordless device discovery, or set discoveryMode to "user-scoped".');
+        return `apps/${appTag}/users/anonymous/devices`;
+    }
+    // user-scoped (default for managed)
+    return `apps/${appTag}/users/${context.userId ?? 'anonymous'}/devices`;
+}
+export function resolveDiscoveryMode(options) {
+    const rawMode = options.discoveryMode;
+    if (rawMode === 'org-scoped') {
+        throw new Error('[openrtc] discoveryMode "org-scoped" is not supported yet. Use "personal" or "user-scoped".');
+    }
+    if (rawMode && rawMode !== 'personal' && rawMode !== 'user-scoped') {
+        throw new Error(`[openrtc] Unsupported discoveryMode "${rawMode}". Use "personal" or "user-scoped".`);
+    }
+    return rawMode === 'user-scoped' ? 'user-scoped' : 'personal';
+}
+export function resolveAuthMode(options) {
+    if (options.authMode) {
+        return options.authMode;
+    }
+    // Personal Mode with spaceKey doesn't use auth at all — suppress the irrelevant warning.
+    const isPersonalMode = 'apiKey' in options &&
+        'spaceKey' in options &&
+        typeof options.apiKey === 'string' &&
+        options.apiKey.trim().length > 0 &&
+        typeof options.spaceKey === 'string' &&
+        options.spaceKey.trim().length > 0;
+    if (!isPersonalMode) {
+        warnOnce('default-auth-mode', "[pluto-rtc] `authMode` is not set; defaulting to `anonymous` for compatibility.");
+    }
+    return 'anonymous';
+}
+export function resolveProjectId(options) {
+    const projectId = typeof options.projectId === 'string' ? options.projectId.trim() : '';
+    if (projectId)
+        return projectId;
+    warnOnce('default-project-id', "[pluto-rtc] `projectId` is not set; defaulting to the built-in PlutoRTC Firebase project.");
+    return PLUTO_HOSTED_PROJECT_ID;
+}
+function sanitizeStorageSegment(value) {
+    return value
+        .trim()
+        .replace(/[^a-zA-Z0-9._-]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+export function resolveStorageNamespace(options) {
+    const explicitPrefix = 'storagePrefix' in options && typeof options.storagePrefix === 'string'
+        ? sanitizeStorageSegment(options.storagePrefix)
+        : '';
+    if (explicitPrefix) {
+        return explicitPrefix;
+    }
+    const appTag = sanitizeStorageSegment(resolveAppTag(options));
+    return appTag || 'default';
+}

package/dist/core/transports/ITransport.d.ts

@@ -0,0 +1,12 @@
+export interface ITransport {
+    readonly name: string;
+    readonly isReady: boolean;
+    init(localNodeId: string, remoteNodeId: string, options: any): Promise<void>;
+    send(data: Uint8Array): Promise<void>;
+    close(): void;
+    onMessage(callback: (data: Uint8Array) => void): void;
+    onStateChange(callback: (state: 'connecting' | 'connected' | 'failed' | 'disconnected') => void): void;
+    handleSignalingMessage?(msg: any): void;
+    getSignalingHandler?(): (msg: any) => Promise<void>;
+    getNativeTransport?(): any;
+}

package/dist/core/transports/ITransport.js

@@ -0,0 +1 @@
+export {};

package/dist/core/transports/LocalDaemonBridge.d.ts

@@ -0,0 +1,41 @@
+import { LocalDaemonEventName, LocalDaemonEventPayloadMap, LocalDaemonInfo } from '../types';
+type EventHandler<T extends LocalDaemonEventName> = (payload: LocalDaemonEventPayloadMap[T]) => void;
+type BridgeStatus = {
+    enabled: boolean;
+    connected: boolean;
+    endpoint?: string;
+    daemonDeviceId?: string;
+    lastError?: string;
+};
+type LocalDaemonBridgeOptions = {
+    enabled?: boolean;
+    autoDiscover?: boolean;
+    connectTimeoutMs?: number;
+    eventAllowlist?: LocalDaemonEventName[];
+};
+type DiscoveryFn = () => Promise<LocalDaemonInfo[]>;
+export declare class LocalDaemonBridge {
+    private options;
+    private discoverDaemons;
+    private socket;
+    private connectedInfo;
+    private handlers;
+    private pendingSubscriptions;
+    private enabled;
+    private lastError;
+    constructor(discoverDaemons: DiscoveryFn, options?: LocalDaemonBridgeOptions);
+    configure(options?: LocalDaemonBridgeOptions): void;
+    getStatus(): BridgeStatus;
+    enable(options?: LocalDaemonBridgeOptions): Promise<boolean>;
+    disable(): Promise<void>;
+    maybeAutoDiscover(): Promise<void>;
+    subscribe<T extends LocalDaemonEventName>(eventName: T, handler: EventHandler<T>): () => void;
+    private connect;
+    private openSocket;
+    private installSocketHandlers;
+    private handleRawMessage;
+    private dispatch;
+    private sendSubscriptions;
+    private sendUnsubscribe;
+}
+export {};

package/dist/core/transports/LocalDaemonBridge.js

@@ -0,0 +1,227 @@
+function nowMs() {
+    return Date.now();
+}
+function toProtocol(token) {
+    return `pluto-local.${token}`;
+}
+export class LocalDaemonBridge {
+    constructor(discoverDaemons, options) {
+        this.socket = null;
+        this.connectedInfo = null;
+        this.handlers = new Map();
+        this.pendingSubscriptions = new Set();
+        this.enabled = false;
+        this.discoverDaemons = discoverDaemons;
+        this.options = {
+            enabled: options?.enabled ?? false,
+            autoDiscover: options?.autoDiscover ?? false,
+            connectTimeoutMs: options?.connectTimeoutMs ?? 1500,
+            eventAllowlist: options?.eventAllowlist ?? [],
+        };
+        this.enabled = this.options.enabled;
+    }
+    configure(options) {
+        if (!options)
+            return;
+        this.options = {
+            enabled: options.enabled ?? this.options.enabled,
+            autoDiscover: options.autoDiscover ?? this.options.autoDiscover,
+            connectTimeoutMs: options.connectTimeoutMs ?? this.options.connectTimeoutMs,
+            eventAllowlist: options.eventAllowlist ?? this.options.eventAllowlist,
+        };
+        this.enabled = this.options.enabled;
+    }
+    getStatus() {
+        return {
+            enabled: this.enabled,
+            connected: !!this.socket && this.socket.readyState === WebSocket.OPEN,
+            endpoint: this.connectedInfo
+                ? `ws://${this.connectedInfo.host}:${this.connectedInfo.localPort}`
+                : undefined,
+            daemonDeviceId: this.connectedInfo?.deviceId,
+            lastError: this.lastError,
+        };
+    }
+    async enable(options) {
+        this.configure({ ...options, enabled: true });
+        if (this.socket && this.socket.readyState === WebSocket.OPEN) {
+            return true;
+        }
+        return this.connect();
+    }
+    async disable() {
+        this.enabled = false;
+        if (this.socket) {
+            try {
+                this.socket.close();
+            }
+            catch {
+                // noop
+            }
+        }
+        this.socket = null;
+        this.connectedInfo = null;
+    }
+    async maybeAutoDiscover() {
+        if (!this.enabled || !this.options.autoDiscover)
+            return;
+        if (this.socket && this.socket.readyState === WebSocket.OPEN)
+            return;
+        await this.connect();
+    }
+    subscribe(eventName, handler) {
+        const allowed = this.options.eventAllowlist;
+        if (allowed.length > 0 && !allowed.includes(eventName)) {
+            throw new Error(`Event '${eventName}' is not in daemon bridge allowlist`);
+        }
+        let set = this.handlers.get(eventName);
+        if (!set) {
+            set = new Set();
+            this.handlers.set(eventName, set);
+        }
+        const rawHandler = handler;
+        set.add(rawHandler);
+        this.pendingSubscriptions.add(eventName);
+        this.sendSubscriptions();
+        return () => {
+            const current = this.handlers.get(eventName);
+            if (!current)
+                return;
+            current.delete(rawHandler);
+            if (current.size === 0) {
+                this.handlers.delete(eventName);
+                this.pendingSubscriptions.delete(eventName);
+                this.sendUnsubscribe(eventName);
+            }
+        };
+    }
+    async connect() {
+        if (!this.enabled)
+            return false;
+        if (typeof window === 'undefined' || typeof WebSocket === 'undefined') {
+            this.lastError = 'WebSocket is unavailable in this runtime';
+            return false;
+        }
+        const daemons = await this.discoverDaemons().catch((error) => {
+            this.lastError = error instanceof Error ? error.message : String(error);
+            return [];
+        });
+        const now = nowMs();
+        const candidates = daemons
+            .filter((entry) => entry.expiresAt > now)
+            .sort((a, b) => (b.updatedAt || b.expiresAt) - (a.updatedAt || a.expiresAt));
+        for (const candidate of candidates) {
+            try {
+                const socket = await this.openSocket(candidate, this.options.connectTimeoutMs);
+                this.lastError = undefined;
+                this.socket = socket;
+                this.connectedInfo = candidate;
+                this.installSocketHandlers(socket);
+                this.sendSubscriptions();
+                return true;
+            }
+            catch (error) {
+                this.lastError = error instanceof Error ? error.message : String(error);
+            }
+        }
+        return false;
+    }
+    openSocket(candidate, timeoutMs) {
+        const host = candidate.host || '127.0.0.1';
+        const url = `ws://${host}:${candidate.localPort}/pluto-rtc?token=${encodeURIComponent(candidate.localToken)}`;
+        const protocol = toProtocol(candidate.localToken);
+        return new Promise((resolve, reject) => {
+            const socket = new WebSocket(url, [protocol]);
+            const timeout = window.setTimeout(() => {
+                try {
+                    socket.close();
+                }
+                catch {
+                    // noop
+                }
+                reject(new Error('timeout opening daemon bridge socket'));
+            }, timeoutMs);
+            socket.onopen = () => {
+                window.clearTimeout(timeout);
+                resolve(socket);
+            };
+            socket.onerror = () => {
+                window.clearTimeout(timeout);
+                reject(new Error('daemon bridge socket open failed'));
+            };
+        });
+    }
+    installSocketHandlers(socket) {
+        socket.onmessage = (event) => {
+            if (typeof event.data !== 'string')
+                return;
+            this.handleRawMessage(event.data);
+        };
+        socket.onclose = () => {
+            this.socket = null;
+            this.connectedInfo = null;
+        };
+        socket.onerror = () => {
+            this.lastError = 'daemon bridge socket error';
+        };
+    }
+    handleRawMessage(raw) {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        if (parsed?.type === 'event' && typeof parsed.eventType === 'string') {
+            this.dispatch(parsed.eventType, parsed.payload ?? {});
+            return;
+        }
+        if (typeof parsed?.type === 'string' && parsed.payload && parsed.type.startsWith('local.')) {
+            this.dispatch(parsed.type, parsed.payload);
+            return;
+        }
+        if (parsed?.type === 'subscribed' && Array.isArray(parsed.events)) {
+            return;
+        }
+        if (parsed?.type === 'error') {
+            this.lastError = typeof parsed.message === 'string' ? parsed.message : 'daemon bridge error';
+        }
+    }
+    dispatch(eventName, payload) {
+        const listeners = this.handlers.get(eventName);
+        if (!listeners || listeners.size === 0)
+            return;
+        for (const handler of listeners) {
+            try {
+                handler(payload);
+            }
+            catch (error) {
+                console.error('[LocalDaemonBridge] handler failed:', error);
+            }
+        }
+    }
+    sendSubscriptions() {
+        if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
+            return;
+        }
+        const events = Array.from(this.pendingSubscriptions);
+        if (events.length === 0)
+            return;
+        const envelope = {
+            type: 'subscribeLocalEvents',
+            events,
+        };
+        this.socket.send(JSON.stringify(envelope));
+    }
+    sendUnsubscribe(eventName) {
+        if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
+            return;
+        }
+        const envelope = {
+            type: 'unsubscribeLocalEvents',
+            events: [eventName],
+        };
+        this.socket.send(JSON.stringify(envelope));
+    }
+}

package/dist/core/transports/TauriSignaling.d.ts

@@ -0,0 +1,28 @@
+import { Device, ISignalingBackend } from '../types';
+import { WasmSignalingBackend } from './WasmSignaling';
+declare global {
+    interface Window {
+        __TAURI_INTERNALS__?: Record<string, any>;
+    }
+}
+export declare class TauriSignalingBackend extends WasmSignalingBackend implements ISignalingBackend {
+    private daemonSignalingEnabled;
+    private subscriptionNonce;
+    private lastSyncedAuthToken;
+    private cachedLocalDeviceId;
+    constructor(options: {
+        tag: string;
+        storagePrefix?: string;
+        nodeIdPersistence?: 'persistent' | 'ephemeral';
+    });
+    setDaemonSignalingEnabled(enabled: boolean): void;
+    private ensureDaemonAuth;
+    private resolveLocalDeviceId;
+    private withPresenceMetadata;
+    updatePresence(localNodeId: string, ticketStr: string, isOnline?: boolean, ttlMs?: number, metadata?: string): Promise<void>;
+    searchDevices(excludeNodeId?: string): Promise<Device[]>;
+    setOffline(localNodeId: string): Promise<void>;
+    onDevicesChange(callback: (devices: Device[]) => void, excludeNodeId?: string): () => void;
+    subscribeDevices(userId: string): Promise<ReadableStream<import('../types').DeviceEvent[]>>;
+    subscribeSessions(localDeviceId: string): Promise<ReadableStream<import('../types').SessionEvent[]>>;
+}