@xtr-dev/rondevu-client 0.20.1 → 0.21.3

package/dist/api/client.js

@@ -7,237 +7,318 @@ import { RpcBatcher } from './batcher.js';
  * RondevuAPI - RPC-based API client for Rondevu signaling server
  */
 export class RondevuAPI {
-    constructor(baseUrl, username, keypair, cryptoAdapter, batcherOptions) {
+    constructor(baseUrl, credential, cryptoAdapter, batcherOptions) {
         this.baseUrl = baseUrl;
-        this.username = username;
-        this.keypair = keypair;
-        this.batcher = null;
+        this.credential = credential;
         // Use WebCryptoAdapter by default (browser environment)
         this.crypto = cryptoAdapter || new WebCryptoAdapter();
-        // Create batcher if not explicitly disabled
-        if (batcherOptions !== false) {
-            this.batcher = new RpcBatcher((requests) => this.rpcBatchDirect(requests), batcherOptions);
+        // Create batcher for request batching with throttling
+        this.batcher = new RpcBatcher(baseUrl, batcherOptions);
+        // Validate credential format early to provide clear error messages
+        if (!credential.name || typeof credential.name !== 'string') {
+            throw new Error('Invalid credential: name must be a non-empty string');
+        }
+        // Validate name format (alphanumeric, dots, underscores, hyphens only)
+        // Limit to prevent HTTP header size issues
+        if (credential.name.length > RondevuAPI.DEFAULT_CREDENTIAL_NAME_MAX_LENGTH) {
+            throw new Error(`Invalid credential: name must not exceed ${RondevuAPI.DEFAULT_CREDENTIAL_NAME_MAX_LENGTH} characters`);
+        }
+        if (!/^[a-zA-Z0-9._-]+$/.test(credential.name)) {
+            throw new Error('Invalid credential: name must contain only alphanumeric characters, dots, underscores, and hyphens');
+        }
+        // Validate secret
+        if (!credential.secret || typeof credential.secret !== 'string') {
+            throw new Error('Invalid credential: secret must be a non-empty string');
+        }
+        // Minimum 256 bits (64 hex characters) for security
+        if (credential.secret.length < RondevuAPI.DEFAULT_SECRET_MIN_LENGTH) {
+            throw new Error(`Invalid credential: secret must be at least 256 bits (${RondevuAPI.DEFAULT_SECRET_MIN_LENGTH} hex characters)`);
+        }
+        // Validate secret is valid hex (even length, only hex characters)
+        if (credential.secret.length % 2 !== 0) {
+            throw new Error('Invalid credential: secret must be a valid hex string (even length)');
+        }
+        if (!/^[0-9a-fA-F]+$/.test(credential.secret)) {
+            throw new Error('Invalid credential: secret must contain only hexadecimal characters');
         }
     }
     /**
-     * Create canonical JSON string with sorted keys for deterministic signing
+     * Canonical JSON serialization with sorted keys
+     * Ensures deterministic output regardless of property insertion order
      */
-    canonicalJSON(obj) {
-        if (obj === null || obj === undefined) {
-            return JSON.stringify(obj);
+    canonicalJSON(obj, depth = 0) {
+        // Prevent stack overflow from deeply nested objects
+        if (depth > RondevuAPI.MAX_CANONICALIZE_DEPTH) {
+            throw new Error('Object nesting too deep for canonicalization');
+        }
+        // Handle null
+        if (obj === null) {
+            return 'null';
+        }
+        // Handle undefined
+        if (obj === undefined) {
+            return JSON.stringify(undefined);
         }
-        if (typeof obj !== 'object') {
+        // Validate primitive types
+        const type = typeof obj;
+        // Reject unsupported types
+        if (type === 'function') {
+            throw new Error('Functions are not supported in RPC parameters');
+        }
+        if (type === 'symbol' || type === 'bigint') {
+            throw new Error(`${type} is not supported in RPC parameters`);
+        }
+        // Validate numbers (reject NaN and Infinity)
+        if (type === 'number' && !Number.isFinite(obj)) {
+            throw new Error('NaN and Infinity are not supported in RPC parameters');
+        }
+        // Handle primitives (string, number, boolean)
+        if (type !== 'object') {
             return JSON.stringify(obj);
         }
+        // Handle arrays recursively
         if (Array.isArray(obj)) {
-            return '[' + obj.map(item => this.canonicalJSON(item)).join(',') + ']';
+            return '[' + obj.map(item => this.canonicalJSON(item, depth + 1)).join(',') + ']';
         }
+        // Handle objects - sort keys alphabetically for deterministic output
         const sortedKeys = Object.keys(obj).sort();
         const pairs = sortedKeys.map(key => {
-            return JSON.stringify(key) + ':' + this.canonicalJSON(obj[key]);
+            return JSON.stringify(key) + ':' + this.canonicalJSON(obj[key], depth + 1);
         });
         return '{' + pairs.join(',') + '}';
     }
     /**
-     * Generate authentication headers for RPC request
-     * Signs the payload (method + params + timestamp + username)
-     */
-    async generateAuthHeaders(request, includePublicKey = false) {
-        const timestamp = Date.now();
-        // Create payload with timestamp and username for signing: { method, params, timestamp, username }
-        const payload = { ...request, timestamp, username: this.username };
-        // Create canonical JSON representation for signing
-        const canonical = this.canonicalJSON(payload);
-        // Sign the canonical representation
-        const signature = await this.crypto.signMessage(canonical, this.keypair.privateKey);
-        const headers = {
-            'X-Signature': signature,
-            'X-Timestamp': timestamp.toString(),
-            'X-Username': this.username,
-        };
-        if (includePublicKey) {
-            headers['X-Public-Key'] = this.keypair.publicKey;
-        }
-        return headers;
-    }
-    /**
-     * Generate authentication fields embedded in request body (for batch requests)
-     * Signs the payload (method + params + timestamp + username)
+     * Build signature message following server format
+     * Format: timestamp:nonce:method:canonicalJSON(params || {})
+     *
+     * Uses canonical JSON (sorted keys) to ensure deterministic serialization
+     * across different JavaScript engines and platforms.
+     *
+     * Note: When params is undefined, it's serialized as "{}" (empty object).
+     * This matches the server's expectation for parameterless RPC calls.
      */
-    async generateAuthForRequest(request, includePublicKey = false) {
-        const timestamp = Date.now();
-        // Create payload with timestamp and username for signing: { method, params, timestamp, username }
-        const payload = { ...request, timestamp, username: this.username };
-        // Create canonical JSON representation for signing
-        const canonical = this.canonicalJSON(payload);
-        // Sign the canonical representation
-        const signature = await this.crypto.signMessage(canonical, this.keypair.privateKey);
-        const authRequest = {
-            ...request,
-            signature,
-            timestamp,
-            username: this.username,
-        };
-        if (includePublicKey) {
-            authRequest.publicKey = this.keypair.publicKey;
-        }
-        return authRequest;
-    }
-    /**
-     * Execute RPC call with optional batching
-     */
-    async rpc(request, authHeaders) {
-        // Use batcher if enabled
-        if (this.batcher) {
-            return await this.batcher.add(request);
-        }
-        // Direct call without batching
-        return await this.rpcDirect(request, authHeaders);
-    }
-    /**
-     * Execute single RPC call directly (bypasses batcher)
-     */
-    async rpcDirect(request, authHeaders) {
-        const response = await fetch(`${this.baseUrl}/rpc`, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                ...authHeaders,
-            },
-            body: JSON.stringify(request),
-        });
-        if (!response.ok) {
-            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    buildSignatureMessage(timestamp, nonce, method, params) {
+        if (!method || typeof method !== 'string') {
+            throw new Error('Invalid method: must be a non-empty string');
         }
-        const result = await response.json();
-        if (!result.success) {
-            throw new Error(result.error || 'RPC call failed');
-        }
-        return result.result;
+        const paramsJson = this.canonicalJSON(params || {});
+        return `${timestamp}:${nonce}:${method}:${paramsJson}`;
     }
     /**
-     * Execute batch RPC calls directly (bypasses batcher)
-     * Each request in the batch has its own embedded authentication (signature, timestamp, username, publicKey)
+     * Generate cryptographically secure nonce
+     * Uses crypto.randomUUID() if available, falls back to secure random bytes
+     *
+     * Note: this.crypto is always initialized in constructor (WebCryptoAdapter or NodeCryptoAdapter)
+     * and TypeScript enforces that both implement randomBytes(), so the fallback is always safe.
      */
-    async rpcBatchDirect(requests) {
-        // Add auth to each request in the batch
-        const requestsWithAuth = await Promise.all(requests.map(req => this.generateAuthForRequest(req, true)));
-        const response = await fetch(`${this.baseUrl}/rpc`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify(requestsWithAuth),
-        });
-        if (!response.ok) {
-            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-        }
-        const results = await response.json();
-        if (!Array.isArray(results)) {
-            throw new Error('Server returned invalid batch response (not an array)');
+    generateNonce() {
+        // Get crypto object from global scope (supports various contexts)
+        // In browsers: window.crypto or self.crypto
+        // In modern environments: global crypto
+        const globalCrypto = typeof crypto !== 'undefined'
+            ? crypto
+            : (typeof window !== 'undefined' && window.crypto) ||
+                (typeof self !== 'undefined' && self.crypto) ||
+                undefined;
+        // Prefer crypto.randomUUID() for widespread support and standard format
+        // UUIDv4 provides 122 bits of entropy (6 fixed version/variant bits)
+        if (globalCrypto && typeof globalCrypto.randomUUID === 'function') {
+            return globalCrypto.randomUUID();
         }
-        // Map results, throwing error for any failed request
-        return results.map((result, i) => {
-            if (!result.success) {
-                throw new Error(result.error || `RPC call ${i} failed`);
-            }
-            return result.result;
-        });
+        // Fallback: 16 random bytes (128 bits entropy) as hex string
+        // Slightly more entropy than UUID, but both are cryptographically secure
+        // Safe because this.crypto is guaranteed to implement CryptoAdapter interface
+        const randomBytes = this.crypto.randomBytes(16);
+        return this.crypto.bytesToHex(randomBytes);
     }
-    // ============================================
-    // Ed25519 Cryptography Helpers
-    // ============================================
     /**
-     * Generate an Ed25519 keypair for username claiming and service publishing
-     * @param cryptoAdapter - Optional crypto adapter (defaults to WebCryptoAdapter)
-     */
-    static async generateKeypair(cryptoAdapter) {
-        const adapter = cryptoAdapter || new WebCryptoAdapter();
-        return await adapter.generateKeypair();
-    }
-    /**
-     * Sign a message with an Ed25519 private key
-     * @param cryptoAdapter - Optional crypto adapter (defaults to WebCryptoAdapter)
+     * Generate authentication headers for RPC request
+     * Uses HMAC-SHA256 signature with nonce for replay protection
+     *
+     * Security notes:
+     * - Nonce: Cryptographically secure random value (UUID or 128-bit hex)
+     * - Timestamp: Prevents replay attacks outside the server's time window
+     *   - Server validates timestamp is within acceptable range (typically ±5 minutes)
+     *   - Tolerates reasonable clock skew between client and server
+     *   - Requests with stale timestamps are rejected
+     * - Signature: HMAC-SHA256 ensures message integrity and authenticity
+     * - Server validates nonce uniqueness to prevent replay within time window
+     *   - Each nonce can only be used once within the timestamp validity window
+     *   - Server maintains nonce cache with expiration matching timestamp window
      */
-    static async signMessage(message, privateKeyBase64, cryptoAdapter) {
-        const adapter = cryptoAdapter || new WebCryptoAdapter();
-        return await adapter.signMessage(message, privateKeyBase64);
+    async generateAuthHeaders(request) {
+        const timestamp = Date.now();
+        const nonce = this.generateNonce();
+        // Build message and generate signature
+        const message = this.buildSignatureMessage(timestamp, nonce, request.method, request.params);
+        const signature = await this.crypto.generateSignature(this.credential.secret, message);
+        return {
+            'X-Name': this.credential.name,
+            'X-Timestamp': timestamp.toString(),
+            'X-Nonce': nonce,
+            'X-Signature': signature,
+        };
     }
     /**
-     * Verify an Ed25519 signature
-     * @param cryptoAdapter - Optional crypto adapter (defaults to WebCryptoAdapter)
+     * Execute RPC call via batcher
+     * Requests are batched with throttling for efficiency
      */
-    static async verifySignature(message, signatureBase64, publicKeyBase64, cryptoAdapter) {
-        const adapter = cryptoAdapter || new WebCryptoAdapter();
-        return await adapter.verifySignature(message, signatureBase64, publicKeyBase64);
+    async rpc(request, authHeaders) {
+        return this.batcher.add(request, authHeaders);
     }
     // ============================================
-    // Username Management
+    // Credential Management
     // ============================================
     /**
-     * Check if a username is available
+     * Generate new credentials (name + secret pair)
+     * This is the entry point for new users - no authentication required
+     * Credentials are generated server-side to ensure security and uniqueness
+     *
+     * ⚠️ SECURITY NOTE:
+     * - Store the returned credential securely
+     * - The secret provides full access to this identity
+     * - Credentials should be persisted encrypted and never logged
+     *
+     * @param baseUrl - Rondevu server URL
+     * @param expiresAt - Optional custom expiry timestamp (defaults to 1 year)
+     * @param options - Optional: { maxRetries: number, timeout: number }
+     * @returns Generated credential with name and secret
      */
-    async isUsernameAvailable(username) {
+    static async generateCredentials(baseUrl, options) {
+        const maxRetries = options?.maxRetries ?? RondevuAPI.DEFAULT_MAX_RETRIES;
+        const timeout = options?.timeout ?? RondevuAPI.DEFAULT_TIMEOUT_MS;
+        let lastError = null;
+        // Build params object with optional name and expiresAt
+        const params = {};
+        if (options?.name)
+            params.name = options.name;
+        if (options?.expiresAt)
+            params.expiresAt = options.expiresAt;
         const request = {
-            method: 'getUser',
-            params: { username },
+            method: 'generateCredentials',
+            params: Object.keys(params).length > 0 ? params : undefined,
         };
-        const authHeaders = await this.generateAuthHeaders(request, false);
-        const result = await this.rpc(request, authHeaders);
-        return result.available;
+        for (let attempt = 0; attempt < maxRetries; attempt++) {
+            // httpStatus is scoped to each iteration intentionally - resets on each retry
+            let httpStatus = null;
+            try {
+                // Create abort controller for timeout
+                if (typeof AbortController === 'undefined') {
+                    throw new Error('AbortController not supported in this environment');
+                }
+                const controller = new AbortController();
+                const timeoutId = setTimeout(() => controller.abort(), timeout);
+                try {
+                    const response = await fetch(`${baseUrl}/rpc`, {
+                        method: 'POST',
+                        headers: {
+                            'Content-Type': 'application/json',
+                        },
+                        body: JSON.stringify([request]), // Server expects array (batch format)
+                        signal: controller.signal,
+                    });
+                    httpStatus = response.status;
+                    if (!response.ok) {
+                        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+                    }
+                    // Server returns array of responses
+                    const results = await response.json();
+                    const result = results[0];
+                    if (!result || !result.success) {
+                        throw new Error(result?.error || 'Failed to generate credentials');
+                    }
+                    // Validate credential structure
+                    const credential = result.result;
+                    if (!credential || typeof credential !== 'object') {
+                        throw new Error('Invalid credential response: result is not an object');
+                    }
+                    if (typeof credential.name !== 'string' || !credential.name) {
+                        throw new Error('Invalid credential response: missing or invalid name');
+                    }
+                    if (typeof credential.secret !== 'string' || !credential.secret) {
+                        throw new Error('Invalid credential response: missing or invalid secret');
+                    }
+                    return credential;
+                }
+                finally {
+                    // Always clear timeout to prevent memory leaks
+                    clearTimeout(timeoutId);
+                }
+            }
+            catch (error) {
+                lastError = error;
+                // Don't retry on abort (timeout)
+                if (error instanceof Error && error.name === 'AbortError') {
+                    throw new Error(`Credential generation timed out after ${timeout}ms`);
+                }
+                // Don't retry on 4xx errors (client errors) - check actual status
+                if (httpStatus !== null && httpStatus >= 400 && httpStatus < 500) {
+                    throw error;
+                }
+                // Retry with exponential backoff + jitter for network/server errors (5xx or network failures)
+                // Jitter prevents thundering herd when many clients retry simultaneously
+                // Cap backoff to prevent excessive waits
+                if (attempt < maxRetries - 1) {
+                    const backoffMs = Math.min(1000 * Math.pow(2, attempt) + Math.random() * 1000, RondevuAPI.MAX_BACKOFF_MS);
+                    await new Promise(resolve => setTimeout(resolve, backoffMs));
+                }
+            }
+        }
+        throw new Error(`Failed to generate credentials after ${maxRetries} attempts: ${lastError?.message || 'Unknown error'}`);
     }
     /**
-     * Check if current username is claimed
+     * Generate a random secret locally (for advanced use cases)
+     * @param cryptoAdapter - Optional crypto adapter
      */
-    async isUsernameClaimed() {
-        const request = {
-            method: 'getUser',
-            params: { username: this.username },
-        };
-        const authHeaders = await this.generateAuthHeaders(request, false);
-        const result = await this.rpc(request, authHeaders);
-        return !result.available;
+    static generateSecret(cryptoAdapter) {
+        const adapter = cryptoAdapter || new WebCryptoAdapter();
+        return adapter.generateSecret();
     }
     // ============================================
-    // Service Management
+    // Tags-based Offer Management (v2)
     // ============================================
     /**
-     * Publish a service
+     * Publish offers with tags
      */
-    async publishService(service) {
-        const request = {
-            method: 'publishService',
+    async publish(request) {
+        const rpcRequest = {
+            method: 'publishOffer',
             params: {
-                serviceFqn: service.serviceFqn,
-                offers: service.offers,
-                ttl: service.ttl,
+                tags: request.tags,
+                offers: request.offers,
+                ttl: request.ttl,
             },
         };
-        const authHeaders = await this.generateAuthHeaders(request, true);
-        return await this.rpc(request, authHeaders);
+        const authHeaders = await this.generateAuthHeaders(rpcRequest);
+        return await this.rpc(rpcRequest, authHeaders);
     }
     /**
-     * Get service by FQN (direct lookup, random, or paginated)
+     * Discover offers by tags
+     * @param request - Discovery request with tags and optional pagination
+     * @returns Paginated response if limit provided, single offer if not
      */
-    async getService(serviceFqn, options) {
-        const request = {
-            method: 'getService',
+    async discover(request) {
+        const rpcRequest = {
+            method: 'discover',
             params: {
-                serviceFqn,
-                ...options,
+                tags: request.tags,
+                limit: request.limit,
+                offset: request.offset,
             },
         };
-        const authHeaders = await this.generateAuthHeaders(request, true);
-        return await this.rpc(request, authHeaders);
+        const authHeaders = await this.generateAuthHeaders(rpcRequest);
+        return await this.rpc(rpcRequest, authHeaders);
     }
     /**
-     * Delete a service
+     * Delete an offer by ID
      */
-    async deleteService(serviceFqn) {
+    async deleteOffer(offerId) {
         const request = {
-            method: 'deleteService',
-            params: { serviceFqn },
+            method: 'deleteOffer',
+            params: { offerId },
         };
-        const authHeaders = await this.generateAuthHeaders(request, true);
-        await this.rpc(request, authHeaders);
+        const authHeaders = await this.generateAuthHeaders(request);
+        return await this.rpc(request, authHeaders);
     }
     // ============================================
     // WebRTC Signaling
@@ -245,24 +326,24 @@ export class RondevuAPI {
     /**
      * Answer an offer
      */
-    async answerOffer(serviceFqn, offerId, sdp) {
+    async answerOffer(offerId, sdp) {
         const request = {
             method: 'answerOffer',
-            params: { serviceFqn, offerId, sdp },
+            params: { offerId, sdp },
         };
-        const authHeaders = await this.generateAuthHeaders(request, true);
+        const authHeaders = await this.generateAuthHeaders(request);
         await this.rpc(request, authHeaders);
     }
     /**
      * Get answer for a specific offer (offerer polls this)
      */
-    async getOfferAnswer(serviceFqn, offerId) {
+    async getOfferAnswer(offerId) {
         try {
             const request = {
                 method: 'getOfferAnswer',
-                params: { serviceFqn, offerId },
+                params: { offerId },
             };
-            const authHeaders = await this.generateAuthHeaders(request, true);
+            const authHeaders = await this.generateAuthHeaders(request);
             return await this.rpc(request, authHeaders);
         }
         catch (err) {
@@ -280,29 +361,29 @@ export class RondevuAPI {
             method: 'poll',
             params: { since },
         };
-        const authHeaders = await this.generateAuthHeaders(request, true);
+        const authHeaders = await this.generateAuthHeaders(request);
         return await this.rpc(request, authHeaders);
     }
     /**
      * Add ICE candidates to a specific offer
      */
-    async addOfferIceCandidates(serviceFqn, offerId, candidates) {
+    async addOfferIceCandidates(offerId, candidates) {
         const request = {
             method: 'addIceCandidates',
-            params: { serviceFqn, offerId, candidates },
+            params: { offerId, candidates },
         };
-        const authHeaders = await this.generateAuthHeaders(request, true);
+        const authHeaders = await this.generateAuthHeaders(request);
         return await this.rpc(request, authHeaders);
     }
     /**
      * Get ICE candidates for a specific offer
      */
-    async getOfferIceCandidates(serviceFqn, offerId, since = 0) {
+    async getOfferIceCandidates(offerId, since = 0) {
         const request = {
             method: 'getIceCandidates',
-            params: { serviceFqn, offerId, since },
+            params: { offerId, since },
         };
-        const authHeaders = await this.generateAuthHeaders(request, true);
+        const authHeaders = await this.generateAuthHeaders(request);
         const result = await this.rpc(request, authHeaders);
         return {
             candidates: result.candidates || [],
@@ -310,3 +391,10 @@ export class RondevuAPI {
         };
     }
 }
+// Default values for credential generation
+RondevuAPI.DEFAULT_MAX_RETRIES = 3;
+RondevuAPI.DEFAULT_TIMEOUT_MS = 30000; // 30 seconds
+RondevuAPI.DEFAULT_CREDENTIAL_NAME_MAX_LENGTH = 128;
+RondevuAPI.DEFAULT_SECRET_MIN_LENGTH = 64; // 256 bits
+RondevuAPI.MAX_BACKOFF_MS = 60000; // 60 seconds max backoff
+RondevuAPI.MAX_CANONICALIZE_DEPTH = 100; // Prevent stack overflow

package/dist/connections/answerer.d.ts

@@ -2,14 +2,17 @@
  * Answerer-side WebRTC connection with answer creation and offer processing
  */
 import { RondevuConnection } from './base.js';
-import { RondevuAPI } from '../api/client.js';
+import { RondevuAPI, IceCandidate } from '../api/client.js';
 import { ConnectionConfig } from './config.js';
+import { WebRTCAdapter } from '../webrtc/adapter.js';
 export interface AnswererOptions {
     api: RondevuAPI;
-    serviceFqn: string;
+    ownerUsername: string;
+    tags: string[];
     offerId: string;
     offerSdp: string;
     rtcConfig?: RTCConfiguration;
+    webrtcAdapter?: WebRTCAdapter;
     config?: Partial<ConnectionConfig>;
 }
 /**
@@ -17,7 +20,8 @@ export interface AnswererOptions {
  */
 export declare class AnswererConnection extends RondevuConnection {
     private api;
-    private serviceFqn;
+    private ownerUsername;
+    private tags;
     private offerId;
     private offerSdp;
     constructor(options: AnswererOptions);
@@ -34,19 +38,24 @@ export declare class AnswererConnection extends RondevuConnection {
      */
     protected getApi(): any;
     /**
-     * Get the service FQN
+     * Get the owner username
      */
-    protected getServiceFqn(): string;
+    protected getOwnerUsername(): string;
     /**
      * Answerers accept ICE candidates from offerers only
      */
     protected getIceCandidateRole(): 'offerer' | null;
     /**
-     * Attempt to reconnect
+     * Attempt to reconnect to the same user
      */
     protected attemptReconnect(): void;
     /**
      * Get the offer ID we're answering
      */
     getOfferId(): string;
+    /**
+     * Handle remote ICE candidates received from polling
+     * Called by Rondevu when poll:ice event is received
+     */
+    handleRemoteIceCandidates(candidates: IceCandidate[]): void;
 }