dropspace 0.0.0-stage → 0.1.1

package/dist/client/client.js

@@ -0,0 +1,1421 @@
+import { PROTOCOL_VERSION, parseSignalingMessage, serializeSignalingEnvelope, redactSignalingEnvelopeForLog, decodeWireFrame, encodeWireFrame, WireFrameType, } from "../protocol/index.js";
+import { loadOrCreateDeviceIdentity, formatCanonicalChallenge, } from "./identity.js";
+import { TypedEventEmitter } from "./events.js";
+import { SmartPeerSelector, } from "./peer-selection.js";
+import { ManagedPeerSession, } from "./peer-connection.js";
+export class DropspaceError extends Error {
+    code;
+    retryable;
+    retryAfterMs;
+    status;
+    constructor(code, message, opts) {
+        super(message);
+        this.name = "DropspaceError";
+        this.code = code;
+        this.retryable = opts?.retryable ?? false;
+        this.retryAfterMs = opts?.retryAfterMs;
+        this.status = opts?.status;
+    }
+}
+const PERMANENT_ERROR_CODES = new Set([
+    "APP_DISABLED",
+    "ORIGIN_NOT_ALLOWED",
+    "DEVICE_REVOKED",
+    "AUTH_FAILED",
+    "AUTH_REQUIRED",
+    "SPACE_EXPIRED",
+]);
+let reqCounter = 0;
+function nextRequestId() {
+    reqCounter = (reqCounter + 1) % 1_000_000_000;
+    return `req_${Date.now().toString(36)}_${reqCounter.toString(36)}`;
+}
+function defaultWebSocketFactory(url) {
+    if (typeof globalThis.WebSocket !== "function") {
+        throw new Error("Global WebSocket is not available; inject webSocketFactory in CreateDropspaceClientOptions");
+    }
+    return new globalThis.WebSocket(url);
+}
+function defaultPeerConnectionFactory(config) {
+    if (typeof globalThis.RTCPeerConnection !== "function") {
+        throw new Error("Global RTCPeerConnection is not available; inject peerConnectionFactory in CreateDropspaceClientOptions");
+    }
+    return new globalThis.RTCPeerConnection(config);
+}
+export class DropspaceClient {
+    options;
+    events = new TypedEventEmitter();
+    peerSelector = new SmartPeerSelector();
+    identity = null;
+    sessionToken = null;
+    sessionId = null;
+    sessionGeneration = 0;
+    sessionExpiresAt = 0;
+    defaultSpaceId = null;
+    turnCredentials = null;
+    signalingState = "disconnected";
+    ws = null;
+    manuallyClosed = false;
+    wsReconnectAttempt = 0;
+    wsReconnectTimer = null;
+    heartbeatTimer = null;
+    capabilities;
+    subscribedSpaces = new Set();
+    peersBySpace = new Map();
+    revokedPeersBySpace = new Map();
+    hubBySpace = new Map();
+    trustedPeers = new Map();
+    peerSessions = new Map();
+    peersWentOffline = new Set();
+    peerQuality = new Map();
+    routeByPeer = new Map();
+    pendingRequests = new Map();
+    hubSeenRelayIds = new Map();
+    debugLogs = [];
+    pairing = {
+        createInvite: (opts) => this.createPairingInvite(opts),
+        claimInvite: (tokenOrDeepLink) => this.claimPairingInvite(tokenOrDeepLink),
+        approve: (pairingId, grantedPermissions) => this.approvePairing(pairingId, grantedPermissions),
+        reject: (pairingId, reason) => this.rejectPairing(pairingId, reason),
+        cancel: (pairingId) => this.cancelPairing(pairingId),
+        revoke: (opts) => this.revokePeerAccess(opts),
+        listTrustedDevices: () => this.listTrustedDevices(),
+    };
+    devices = {
+        subscribeSpace: (spaceId) => this.subscribeSpace(spaceId),
+        getPeers: (spaceId) => this.getSpacePeers(spaceId),
+        updateCapabilities: (caps) => this.updateCapabilities(caps),
+        selectPeer: (query) => this.selectBestPeer(query),
+        setExplicitHub: (spaceId, hubDeviceId) => this.setExplicitHub(spaceId, hubDeviceId),
+        getSpaceHub: (spaceId) => this.hubBySpace.get(spaceId ?? this.defaultSpaceId ?? "") ?? null,
+    };
+    channels = {
+        sendBinary: (peerDeviceId, payload, options) => this.sendBinaryMessage(peerDeviceId, payload, options),
+        sendJson: (peerDeviceId, value, options) => this.sendJsonMessage(peerDeviceId, value, options),
+    };
+    constructor(options) {
+        this.options = options;
+        this.capabilities = [...(options.capabilities ?? ["messaging", "files", "crdt"])];
+    }
+    getIdentity() {
+        if (!this.identity) {
+            throw new Error("DropspaceClient has not been started yet; call await client.start()");
+        }
+        return this.identity;
+    }
+    getSessionInfo() {
+        return {
+            sessionId: this.sessionId,
+            generation: this.sessionGeneration,
+            expiresAt: this.sessionExpiresAt,
+            defaultSpaceId: this.defaultSpaceId,
+            signalingState: this.signalingState,
+        };
+    }
+    getDebugLogs() {
+        return this.debugLogs;
+    }
+    redactDebugValue(val) {
+        if (typeof val === "string") {
+            return val
+                .replace(/dinv_[A-Za-z0-9_-]+/g, "[REDACTED_INVITE_TOKEN]")
+                .replace(/Bearer\s+[A-Za-z0-9._-]+/gi, "Bearer [REDACTED]");
+        }
+        if (Array.isArray(val)) {
+            return val.map((item) => this.redactDebugValue(item));
+        }
+        if (val && typeof val === "object") {
+            const out = {};
+            for (const [k, v] of Object.entries(val)) {
+                if (/token|secret|password|credential|privateKey|sdp/i.test(k)) {
+                    out[k] = "[REDACTED]";
+                }
+                else {
+                    out[k] = this.redactDebugValue(v);
+                }
+            }
+            return out;
+        }
+        return val;
+    }
+    recordDebug(category, summary, details) {
+        const entry = {
+            timestamp: Date.now(),
+            category,
+            summary: String(this.redactDebugValue(summary)),
+            details: details
+                ? this.redactDebugValue(details)
+                : undefined,
+        };
+        this.debugLogs.push(entry);
+        if (this.debugLogs.length > 250) {
+            this.debugLogs.shift();
+        }
+        this.events.emit("debugEvent", entry);
+    }
+    async start(signal) {
+        if (signal?.aborted) {
+            throw new Error("DropspaceClient.start aborted");
+        }
+        this.manuallyClosed = false;
+        if (!this.identity) {
+            this.identity = await loadOrCreateDeviceIdentity({
+                storage: this.options.identityStorage,
+                deviceLabel: this.options.deviceLabel,
+                algorithm: this.options.algorithm,
+            });
+        }
+        await this.authenticateHttpSession(signal);
+        await this.connectSignalingWebSocket(signal);
+        // Subscribe to default space and load persisted trusted peers
+        if (this.defaultSpaceId) {
+            await this.subscribeSpace(this.defaultSpaceId);
+        }
+        try {
+            await this.listTrustedDevices();
+        }
+        catch {
+            // Non-fatal on startup
+        }
+        return this.identity;
+    }
+    getFetch() {
+        const f = this.options.fetchImpl ?? globalThis.fetch;
+        if (typeof f !== "function") {
+            throw new Error("fetch is not available in this runtime");
+        }
+        return f.bind(globalThis);
+    }
+    getCoreHttpUrl() {
+        const raw = this.options.coreHttpUrl ?? this.options.baseUrl ?? "";
+        if (!raw) {
+            throw new DropspaceError("INVALID_ENVELOPE", "DropspaceClient requires coreHttpUrl or baseUrl");
+        }
+        return raw.replace(/\/+$/, "");
+    }
+    async getCapabilities(signal) {
+        const fetchFn = this.getFetch();
+        const baseUrl = this.getCoreHttpUrl();
+        const url = this.options.appId
+            ? `${baseUrl}/api/v1/apps/${encodeURIComponent(this.options.appId)}/capabilities`
+            : `${baseUrl}/api/v1/capabilities`;
+        const res = await fetchFn(url, { method: "GET", signal });
+        if (!res.ok) {
+            const errBody = (await res.json().catch(() => ({})));
+            throw new DropspaceError(errBody.code ?? "INTERNAL_ERROR", errBody.message ?? `Capabilities request failed (${res.status})`, { status: res.status, retryAfterMs: errBody.retryAfterMs });
+        }
+        return (await res.json());
+    }
+    async parseHttpError(res, fallbackPrefix) {
+        const errBody = (await res.json().catch(() => ({})));
+        const retryHeader = res.headers.get("retry-after");
+        const retryAfterMs = errBody.retryAfterMs ??
+            (retryHeader && /^\d+$/.test(retryHeader) ? Number(retryHeader) * 1000 : undefined);
+        const code = errBody.code ?? "INTERNAL_ERROR";
+        const retryable = code === "RATE_LIMITED" ||
+            code === "SERVICE_OVERLOADED" ||
+            res.status === 429 ||
+            res.status === 503;
+        return new DropspaceError(code, errBody.message ?? `${fallbackPrefix} (${res.status})`, { retryable, retryAfterMs, status: res.status });
+    }
+    isPermanentStopError(err) {
+        if (err instanceof DropspaceError) {
+            if (PERMANENT_ERROR_CODES.has(err.code))
+                return true;
+            if (err.code === "TICKET_EXPIRED" && !this.options.getAccessTicket)
+                return true;
+        }
+        return false;
+    }
+    async authenticateHttpSession(signal) {
+        const id = this.getIdentity();
+        const fetchFn = this.getFetch();
+        const baseUrl = this.getCoreHttpUrl();
+        const appId = this.options.appId;
+        const accessTicket = this.options.getAccessTicket
+            ? await this.options.getAccessTicket()
+            : undefined;
+        const chalUrl = appId
+            ? `${baseUrl}/api/v1/apps/${encodeURIComponent(appId)}/auth/challenge`
+            : `${baseUrl}/api/v1/auth/challenge`;
+        // 1. Request short-lived challenge
+        const chalRes = await fetchFn(chalUrl, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                deviceId: id.deviceId,
+                publicKey: id.publicKey,
+                algorithm: id.algorithm,
+                deviceLabel: id.deviceLabel,
+                purpose: "session_auth",
+                ...(appId ? { appId } : {}),
+                ...(accessTicket ? { accessTicket } : {}),
+            }),
+            signal,
+        });
+        if (!chalRes.ok) {
+            throw await this.parseHttpError(chalRes, "Challenge request failed");
+        }
+        const chalData = (await chalRes.json());
+        // 2. Sign canonical challenge with private key
+        const canonical = formatCanonicalChallenge(chalData);
+        const signature = await id.sign(canonical);
+        // 3. Submit signature to obtain sessionToken
+        const verifyUrl = appId
+            ? `${baseUrl}/api/v1/apps/${encodeURIComponent(appId)}/auth/verify`
+            : `${baseUrl}/api/v1/auth/verify`;
+        const verifyRes = await fetchFn(verifyUrl, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                challengeId: chalData.challengeId,
+                deviceId: id.deviceId,
+                signature,
+                ...(appId ? { appId } : {}),
+            }),
+            signal,
+        });
+        if (!verifyRes.ok) {
+            throw await this.parseHttpError(verifyRes, "Challenge verification failed");
+        }
+        const verifyData = (await verifyRes.json());
+        this.sessionToken = verifyData.sessionToken;
+        this.sessionId = verifyData.sessionId;
+        this.sessionExpiresAt = verifyData.expiresAt;
+        this.defaultSpaceId = verifyData.defaultSpaceId;
+        this.turnCredentials = verifyData.turnCredentials ?? null;
+        this.subscribedSpaces.add(verifyData.defaultSpaceId);
+        this.recordDebug("security", "Authenticated HTTP challenge-response session", {
+            appId: verifyData.appId ?? appId,
+            deviceId: id.deviceId,
+            sessionId: verifyData.sessionId,
+            securityLevel: id.securityLevel,
+        });
+    }
+    getWsUrl() {
+        let wsUrl;
+        if (this.options.coreWsUrl) {
+            wsUrl = this.options.coreWsUrl;
+        }
+        else {
+            const base = this.getCoreHttpUrl();
+            if (base.startsWith("https://")) {
+                wsUrl = `wss://${base.slice("https://".length)}/ws`;
+            }
+            else if (base.startsWith("http://")) {
+                wsUrl = `ws://${base.slice("http://".length)}/ws`;
+            }
+            else {
+                wsUrl = `${base}/ws`;
+            }
+        }
+        if (this.options.appId && !wsUrl.includes("appId=")) {
+            const sep = wsUrl.includes("?") ? "&" : "?";
+            wsUrl = `${wsUrl}${sep}appId=${encodeURIComponent(this.options.appId)}`;
+        }
+        return wsUrl;
+    }
+    transitionSignalingState(next, reason) {
+        if (this.signalingState === next)
+            return;
+        const prev = this.signalingState;
+        this.signalingState = next;
+        this.events.emit("signalingStateChange", {
+            previousState: prev,
+            state: next,
+            sessionId: this.sessionId,
+            generation: this.sessionGeneration,
+            reason,
+        });
+    }
+    connectSignalingWebSocket(signal) {
+        if (!this.sessionToken) {
+            return Promise.reject(new Error("Missing sessionToken before WebSocket connect"));
+        }
+        const wsFactory = this.options.webSocketFactory ?? defaultWebSocketFactory;
+        const wsUrl = this.getWsUrl();
+        this.transitionSignalingState(this.wsReconnectAttempt > 0 ? "reconnecting" : "connecting", "opening_websocket");
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const ws = wsFactory(wsUrl);
+            this.ws = ws;
+            const onOpen = () => {
+                if (this.manuallyClosed || this.ws !== ws)
+                    return;
+                this.transitionSignalingState("authenticating", "ws_open");
+                const authReqId = nextRequestId();
+                const authEnv = {
+                    protocolVersion: PROTOCOL_VERSION,
+                    type: "auth.authenticate",
+                    requestId: authReqId,
+                    payload: {
+                        sessionToken: this.sessionToken,
+                        deviceLabel: this.identity?.deviceLabel ?? "Dropspace Device",
+                        capabilities: this.capabilities,
+                    },
+                };
+                try {
+                    ws.send(serializeSignalingEnvelope(authEnv));
+                }
+                catch (err) {
+                    if (!settled) {
+                        settled = true;
+                        reject(err instanceof Error ? err : new Error(String(err)));
+                    }
+                }
+            };
+            const onMessage = (ev) => {
+                if (this.manuallyClosed || this.ws !== ws)
+                    return;
+                const rawText = typeof ev.data === "string"
+                    ? ev.data
+                    : ev.data instanceof ArrayBuffer
+                        ? new TextDecoder().decode(ev.data)
+                        : Buffer.from(ev.data).toString("utf-8");
+                let env;
+                try {
+                    env = parseSignalingMessage(rawText);
+                }
+                catch {
+                    return;
+                }
+                this.recordDebug("signaling", `Received ${env.type}`, {
+                    envelope: redactSignalingEnvelopeForLog(env),
+                });
+                if (env.type === "auth.authenticated") {
+                    this.sessionId = String(env.payload.sessionId ?? this.sessionId ?? "");
+                    this.sessionGeneration = Number(env.payload.generation ?? 1);
+                    if (env.payload.turnCredentials) {
+                        this.turnCredentials = env.payload.turnCredentials;
+                    }
+                    this.wsReconnectAttempt = 0;
+                    this.transitionSignalingState("connected", "authenticated");
+                    this.startHeartbeat();
+                    // Re-subscribe to all active spaces on reconnect without tearing down healthy P2P connections!
+                    for (const spId of this.subscribedSpaces) {
+                        void this.sendSignalingEnvelope({
+                            protocolVersion: PROTOCOL_VERSION,
+                            type: "presence.subscribe",
+                            spaceId: spId,
+                            payload: { spaceId: spId },
+                        }).catch(() => { });
+                    }
+                    if (!settled) {
+                        settled = true;
+                        resolve();
+                    }
+                    if (env.requestId) {
+                        const pend = this.pendingRequests.get(env.requestId);
+                        if (pend) {
+                            clearTimeout(pend.timer);
+                            this.pendingRequests.delete(env.requestId);
+                            pend.resolve(env);
+                        }
+                    }
+                    return;
+                }
+                if (env.type === "error" && !settled && this.signalingState === "authenticating") {
+                    settled = true;
+                    const errCode = String(env.payload.code ?? "AUTH_FAILED");
+                    const errMsg = String(env.payload.message ?? "WebSocket authentication failed");
+                    const retryAfterMs = typeof env.payload.retryAfterMs === "number" ? env.payload.retryAfterMs : undefined;
+                    const err = new DropspaceError(errCode, errMsg, {
+                        retryable: Boolean(env.payload.retryable),
+                        retryAfterMs,
+                    });
+                    if (this.isPermanentStopError(err)) {
+                        this.manuallyClosed = true;
+                    }
+                    reject(err);
+                    return;
+                }
+                this.handleIncomingSignalingEnvelope(env);
+            };
+            const onClose = () => {
+                ws.removeEventListener("open", onOpen);
+                ws.removeEventListener("message", onMessage);
+                ws.removeEventListener("close", onClose);
+                ws.removeEventListener("error", onError);
+                this.stopHeartbeat();
+                if (!settled) {
+                    settled = true;
+                    reject(new Error("Signaling WebSocket closed before authentication completed"));
+                }
+                if (!this.manuallyClosed && this.ws === ws) {
+                    // IMPORTANT (Section 10): Signaling disconnect MUST NOT close healthy P2P connections!
+                    this.transitionSignalingState("reconnecting", "socket_closed");
+                    this.scheduleSignalingReconnect();
+                }
+            };
+            const onError = () => {
+                // Error will be followed by close
+            };
+            ws.addEventListener("open", onOpen);
+            ws.addEventListener("message", onMessage);
+            ws.addEventListener("close", onClose);
+            ws.addEventListener("error", onError);
+            if (signal) {
+                signal.addEventListener("abort", () => {
+                    if (!settled) {
+                        settled = true;
+                        ws.close();
+                        reject(new Error("WebSocket connect aborted"));
+                    }
+                }, { once: true });
+            }
+        });
+    }
+    scheduleSignalingReconnect(serverRetryAfterMs) {
+        if (this.manuallyClosed || this.wsReconnectTimer)
+            return;
+        const maxAttempts = this.options.maxReconnectAttempts ?? 20;
+        if (this.wsReconnectAttempt >= maxAttempts) {
+            this.transitionSignalingState("closed", "max_reconnect_attempts_reached");
+            return;
+        }
+        this.wsReconnectAttempt += 1;
+        const base = this.options.baseBackoffMs ?? 100;
+        const cap = 30_000;
+        const expCeiling = Math.min(cap, base * Math.pow(2, this.wsReconnectAttempt - 1));
+        // Full jitter prevents reconnect storms after outages
+        const fullJitterDelay = Math.floor(Math.random() * expCeiling);
+        const delay = typeof serverRetryAfterMs === "number" && serverRetryAfterMs > fullJitterDelay
+            ? serverRetryAfterMs
+            : fullJitterDelay;
+        this.wsReconnectTimer = setTimeout(async () => {
+            this.wsReconnectTimer = null;
+            if (this.manuallyClosed)
+                return;
+            try {
+                await this.authenticateHttpSession();
+                await this.connectSignalingWebSocket();
+            }
+            catch (err) {
+                if (this.isPermanentStopError(err)) {
+                    this.manuallyClosed = true;
+                    this.transitionSignalingState("closed", "permanent_auth_or_policy_error");
+                    if (err instanceof DropspaceError) {
+                        this.events.emit("error", {
+                            code: err.code,
+                            message: err.message,
+                            retryable: false,
+                        });
+                    }
+                    return;
+                }
+                const retryMs = err instanceof DropspaceError ? err.retryAfterMs : undefined;
+                this.scheduleSignalingReconnect(retryMs);
+            }
+        }, delay);
+    }
+    startHeartbeat() {
+        this.stopHeartbeat();
+        const intervalMs = this.options.heartbeatIntervalMs ?? 20_000;
+        this.heartbeatTimer = setInterval(() => {
+            if (this.signalingState === "connected") {
+                void this.sendSignalingEnvelope({
+                    protocolVersion: PROTOCOL_VERSION,
+                    type: "heartbeat.ping",
+                    payload: { clientTime: Date.now() },
+                }).catch(() => { });
+            }
+        }, intervalMs);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    async sendSignalingEnvelope(envelope) {
+        if (!this.ws || this.signalingState !== "connected") {
+            throw new Error("Signaling WebSocket is not connected");
+        }
+        const raw = serializeSignalingEnvelope(envelope);
+        this.recordDebug("signaling", `Sent ${envelope.type}`, {
+            envelope: redactSignalingEnvelopeForLog(envelope),
+        });
+        this.ws.send(raw);
+    }
+    sendSignalingRequest(envelope, timeoutMs = 8000) {
+        const requestId = nextRequestId();
+        const fullEnvelope = {
+            protocolVersion: PROTOCOL_VERSION,
+            requestId,
+            ...envelope,
+        };
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingRequests.delete(requestId);
+                reject(new Error(`Signaling request '${envelope.type}' timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.pendingRequests.set(requestId, { resolve, reject, timer });
+            this.sendSignalingEnvelope(fullEnvelope).catch((err) => {
+                clearTimeout(timer);
+                this.pendingRequests.delete(requestId);
+                reject(err instanceof Error ? err : new Error(String(err)));
+            });
+        });
+    }
+    handleIncomingSignalingEnvelope(env) {
+        if (env.requestId && this.pendingRequests.has(env.requestId)) {
+            const pend = this.pendingRequests.get(env.requestId);
+            clearTimeout(pend.timer);
+            this.pendingRequests.delete(env.requestId);
+            if (env.type === "error") {
+                const code = String(env.payload.code ?? "UNKNOWN_ERROR");
+                const message = String(env.payload.message ?? "Signaling error");
+                const retryable = Boolean(env.payload.retryable);
+                const retryAfterMs = typeof env.payload.retryAfterMs === "number" ? env.payload.retryAfterMs : undefined;
+                const err = new DropspaceError(code, `${code}: ${message}`, {
+                    retryable,
+                    retryAfterMs,
+                });
+                pend.reject(err);
+                this.events.emit("error", {
+                    code,
+                    message,
+                    retryable,
+                    retryAfterMs,
+                });
+                return;
+            }
+            pend.resolve(env);
+        }
+        switch (env.type) {
+            case "error": {
+                this.events.emit("error", {
+                    code: String(env.payload.code),
+                    message: String(env.payload.message),
+                    retryable: Boolean(env.payload.retryable),
+                    retryAfterMs: typeof env.payload.retryAfterMs === "number" ? env.payload.retryAfterMs : undefined,
+                });
+                break;
+            }
+            case "presence.snapshot": {
+                const spaceId = String(env.spaceId ?? env.payload.spaceId ?? "");
+                const peers = env.payload.peers ?? [];
+                const hubDeviceId = typeof env.payload.hubDeviceId === "string"
+                    ? env.payload.hubDeviceId
+                    : null;
+                const revocations = env.payload.revocations ?? [];
+                this.hubBySpace.set(spaceId, hubDeviceId);
+                const spaceMap = new Map();
+                for (const p of peers) {
+                    spaceMap.set(p.deviceId, p);
+                }
+                this.peersBySpace.set(spaceId, spaceMap);
+                let revSet = this.revokedPeersBySpace.get(spaceId);
+                if (!revSet) {
+                    revSet = new Set();
+                    this.revokedPeersBySpace.set(spaceId, revSet);
+                }
+                for (const r of revocations) {
+                    revSet.add(r.revokedDeviceId);
+                    // Close any lingering peer session with a revoked peer (offline revocation catch-up!)
+                    const sess = this.peerSessions.get(r.revokedDeviceId);
+                    if (sess) {
+                        sess.close(false);
+                        this.peerSessions.delete(r.revokedDeviceId);
+                    }
+                }
+                this.events.emit("presenceSnapshot", {
+                    spaceId,
+                    hubDeviceId,
+                    peers,
+                    revocations,
+                });
+                // Auto-connect to online trusted peers if configured
+                if (this.options.autoConnectTrustedPeers ?? true) {
+                    for (const p of peers) {
+                        if (p.deviceId !== this.identity?.deviceId &&
+                            p.online &&
+                            this.trustedPeers.has(p.deviceId)) {
+                            // Polite/impolite tie-breaker: lexicographically smaller deviceId initiates auto-connect
+                            if ((this.identity?.deviceId ?? "") < p.deviceId) {
+                                void this.connect(p.deviceId, { spaceId }).catch(() => { });
+                            }
+                        }
+                    }
+                }
+                break;
+            }
+            case "presence.update": {
+                const spaceId = String(env.spaceId ?? env.payload.spaceId ?? "");
+                const status = env.payload.status ?? "updated";
+                const peer = env.payload.peer;
+                if (!peer || !peer.deviceId)
+                    break;
+                let spaceMap = this.peersBySpace.get(spaceId);
+                if (!spaceMap) {
+                    spaceMap = new Map();
+                    this.peersBySpace.set(spaceId, spaceMap);
+                }
+                spaceMap.set(peer.deviceId, peer);
+                this.events.emit("presenceUpdate", { spaceId, status, peer });
+                // Check if this peer is the space's designated hub
+                const activeHub = this.hubBySpace.get(spaceId);
+                if (activeHub && activeHub === peer.deviceId) {
+                    this.events.emit("hubStatusChange", {
+                        spaceId,
+                        hubDeviceId: activeHub,
+                        reachable: peer.online,
+                    });
+                }
+                const existingSession = this.peerSessions.get(peer.deviceId);
+                if (!peer.online) {
+                    this.peersWentOffline.add(peer.deviceId);
+                    if (existingSession &&
+                        existingSession.getState() !== "connected" &&
+                        !existingSession.isManuallyClosed()) {
+                        existingSession.setWaitingForPeer("peer_went_offline");
+                    }
+                }
+                else {
+                    const returnedFromOffline = this.peersWentOffline.delete(peer.deviceId);
+                    if (returnedFromOffline &&
+                        existingSession &&
+                        existingSession.getState() === "connected" &&
+                        !existingSession.isManuallyClosed() &&
+                        (this.options.autoConnectTrustedPeers ?? true) &&
+                        this.trustedPeers.has(peer.deviceId) &&
+                        (this.identity?.deviceId ?? "") < peer.deviceId) {
+                        void existingSession.forceReconnect("peer_returned_online").catch(() => { });
+                    }
+                    else if (peer.deviceId !== this.identity?.deviceId &&
+                        !existingSession?.isManuallyClosed() &&
+                        (existingSession?.getState() === "waiting_for_peer" ||
+                            existingSession?.getState() === "reconnecting" ||
+                            existingSession?.getState() === "failed" ||
+                            ((this.options.autoConnectTrustedPeers ?? true) &&
+                                this.trustedPeers.has(peer.deviceId) &&
+                                (this.identity?.deviceId ?? "") < peer.deviceId))) {
+                        void this.connect(peer.deviceId, { spaceId }).catch(() => { });
+                    }
+                }
+                break;
+            }
+            case "pairing.awaiting_approval": {
+                const req = {
+                    pairingId: String(env.payload.pairingId ?? ""),
+                    spaceId: String(env.spaceId ?? env.payload.spaceId ?? ""),
+                    claimerDeviceId: String(env.payload.claimerDeviceId ?? ""),
+                    claimerLabel: String(env.payload.claimerLabel ?? "Remote Device"),
+                    claimerPublicKey: String(env.payload.claimerPublicKey ?? ""),
+                    claimerAlgorithm: env.payload.claimerAlgorithm ?? "ECDSA_P256_SHA256",
+                    claimerFingerprint: String(env.payload.claimerFingerprint ?? ""),
+                    requestedPermissions: env.payload.requestedPermissions ?? [],
+                    expiresAt: Number(env.payload.expiresAt ?? 0),
+                };
+                this.recordDebug("pairing", `Pairing ${req.pairingId} awaiting approval`, {
+                    claimerDeviceId: req.claimerDeviceId,
+                    claimerFingerprint: req.claimerFingerprint,
+                });
+                this.events.emit("pairingAwaitingApproval", req);
+                break;
+            }
+            case "pairing.accepted": {
+                const trusted = {
+                    pairingId: String(env.payload.pairingId ?? ""),
+                    spaceId: String(env.spaceId ?? env.payload.spaceId ?? ""),
+                    peerDeviceId: String(env.payload.peerDeviceId ?? ""),
+                    peerLabel: String(env.payload.peerLabel ?? "Trusted Device"),
+                    peerPublicKey: String(env.payload.peerPublicKey ?? ""),
+                    peerAlgorithm: env.payload.peerAlgorithm ?? "ECDSA_P256_SHA256",
+                    peerFingerprint: String(env.payload.peerFingerprint ?? ""),
+                    permissions: env.payload.permissions ?? [],
+                    createdAt: Number(env.payload.createdAt ?? Date.now()),
+                };
+                this.trustedPeers.set(trusted.peerDeviceId, trusted);
+                this.subscribedSpaces.add(trusted.spaceId);
+                void this.subscribeSpace(trusted.spaceId).catch(() => { });
+                this.recordDebug("pairing", `Pairing accepted with ${trusted.peerDeviceId}`, {
+                    pairingId: trusted.pairingId,
+                    spaceId: trusted.spaceId,
+                    permissions: trusted.permissions,
+                });
+                this.events.emit("pairingAccepted", trusted);
+                if ((this.options.autoConnectTrustedPeers ?? true) &&
+                    (this.identity?.deviceId ?? "") < trusted.peerDeviceId) {
+                    void this.connect(trusted.peerDeviceId, {
+                        spaceId: trusted.spaceId,
+                    }).catch(() => { });
+                }
+                break;
+            }
+            case "pairing.status_changed": {
+                this.events.emit("pairingStatusChanged", {
+                    pairingId: String(env.payload.pairingId ?? ""),
+                    spaceId: String(env.spaceId ?? env.payload.spaceId ?? ""),
+                    state: env.payload.state ?? "revoked",
+                });
+                break;
+            }
+            case "revocation.notice": {
+                const rev = {
+                    revocationId: typeof env.payload.revocationId === "string"
+                        ? env.payload.revocationId
+                        : undefined,
+                    spaceId: String(env.spaceId ?? env.payload.spaceId ?? ""),
+                    revokedDeviceId: String(env.payload.revokedDeviceId ?? ""),
+                    revokedByDeviceId: String(env.payload.revokedByDeviceId ?? ""),
+                    revokedAt: Number(env.payload.revokedAt ?? Date.now()),
+                    reason: String(env.payload.reason ?? "Access revoked"),
+                };
+                let revSet = this.revokedPeersBySpace.get(rev.spaceId);
+                if (!revSet) {
+                    revSet = new Set();
+                    this.revokedPeersBySpace.set(rev.spaceId, revSet);
+                }
+                revSet.add(rev.revokedDeviceId);
+                this.trustedPeers.delete(rev.revokedDeviceId);
+                // Immediately terminate active P2P session if the revoked device is the remote peer OR us!
+                if (rev.revokedDeviceId === this.identity?.deviceId) {
+                    this.peersBySpace.delete(rev.spaceId);
+                    for (const [key, trusted] of this.trustedPeers.entries()) {
+                        if (trusted.spaceId === rev.spaceId) {
+                            this.trustedPeers.delete(key);
+                        }
+                    }
+                    for (const [peerId, sess] of this.peerSessions.entries()) {
+                        sess.close(false);
+                        this.peerSessions.delete(peerId);
+                    }
+                }
+                else {
+                    this.peersBySpace.get(rev.spaceId)?.delete(rev.revokedDeviceId);
+                    const targetSess = this.peerSessions.get(rev.revokedDeviceId);
+                    if (targetSess) {
+                        targetSess.close(false);
+                        this.peerSessions.delete(rev.revokedDeviceId);
+                    }
+                }
+                this.recordDebug("security", `Revocation enforced for ${rev.revokedDeviceId}`, {
+                    spaceId: rev.spaceId,
+                    reason: rev.reason,
+                });
+                this.events.emit("revocationNotice", rev);
+                break;
+            }
+            case "topology.hub_changed": {
+                const spaceId = String(env.spaceId ?? env.payload.spaceId ?? "");
+                const hubDeviceId = typeof env.payload.hubDeviceId === "string"
+                    ? env.payload.hubDeviceId
+                    : null;
+                this.hubBySpace.set(spaceId, hubDeviceId);
+                this.events.emit("hubChanged", {
+                    spaceId,
+                    hubDeviceId,
+                    updatedBy: String(env.payload.updatedBy ?? ""),
+                    updatedAt: Number(env.payload.updatedAt ?? Date.now()),
+                });
+                break;
+            }
+            case "turn.credentials_response": {
+                this.turnCredentials = env.payload;
+                break;
+            }
+            case "webrtc.offer":
+            case "webrtc.answer":
+            case "webrtc.ice_candidate":
+            case "webrtc.ice_restart":
+            case "webrtc.close": {
+                const senderId = env.senderDeviceId;
+                if (!senderId)
+                    break;
+                const spaceId = env.spaceId ?? this.defaultSpaceId ?? "";
+                if (this.revokedPeersBySpace.get(spaceId)?.has(senderId)) {
+                    this.recordDebug("security", `Blocked signaling from revoked peer ${senderId}`);
+                    break;
+                }
+                const session = this.getOrCreateManagedPeerSession(senderId, spaceId);
+                void session.handleSignalingEnvelope(env);
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    async subscribeSpace(spaceId) {
+        this.subscribedSpaces.add(spaceId);
+        if (this.signalingState === "connected") {
+            await this.sendSignalingRequest({
+                type: "presence.subscribe",
+                spaceId,
+                payload: { spaceId },
+            });
+        }
+    }
+    getSpacePeers(spaceId) {
+        const sp = spaceId ?? this.defaultSpaceId ?? "";
+        const map = this.peersBySpace.get(sp);
+        if (!map)
+            return [];
+        return Array.from(map.values());
+    }
+    async updateCapabilities(capabilities) {
+        this.capabilities = [...capabilities];
+        if (this.signalingState === "connected") {
+            await this.sendSignalingEnvelope({
+                protocolVersion: PROTOCOL_VERSION,
+                type: "capability.update",
+                payload: { capabilities: this.capabilities },
+            });
+        }
+    }
+    selectBestPeer(query) {
+        const spaceId = query.spaceId ?? this.defaultSpaceId ?? "";
+        const peers = this.getSpacePeers(spaceId);
+        const revokedSet = this.revokedPeersBySpace.get(spaceId) ?? new Set();
+        const candidates = peers
+            .filter((p) => p.deviceId !== this.identity?.deviceId)
+            .map((presence) => {
+            const sess = this.peerSessions.get(presence.deviceId);
+            return {
+                presence,
+                spaceMember: true,
+                revoked: revokedSet.has(presence.deviceId),
+                hasHealthyActiveConnection: sess?.getState() === "connected",
+                quality: this.peerQuality.get(presence.deviceId),
+            };
+        });
+        const decision = this.peerSelector.selectPeer({
+            spaceId,
+            requiredPermissions: query.requiredPermissions,
+            requiredCapabilities: query.requiredCapabilities,
+            preferredDeviceId: query.preferredDeviceId,
+            requireOnline: query.requireOnline,
+        }, candidates);
+        this.recordDebug("selection", decision.explanation, {
+            selectedDeviceId: decision.selectedDeviceId,
+            hysteresisApplied: decision.hysteresisApplied,
+        });
+        return decision;
+    }
+    async createPairingInvite(opts) {
+        const spaceId = opts?.spaceId ?? this.defaultSpaceId ?? `space_${this.getIdentity().deviceId}`;
+        const permissions = opts?.permissions ?? ["connect", "messaging", "files", "crdt"];
+        const ttlMs = opts?.ttlMs ?? 300_000;
+        const resp = await this.sendSignalingRequest({
+            type: "pairing.create_invite",
+            spaceId,
+            payload: {
+                spaceId,
+                permissions,
+                ttlMs,
+            },
+        });
+        return {
+            pairingId: String(resp.payload.pairingId),
+            spaceId: String(resp.payload.spaceId ?? spaceId),
+            inviteToken: String(resp.payload.inviteToken),
+            deepLink: String(resp.payload.deepLink),
+            state: resp.payload.state ?? "created",
+            permissions: resp.payload.permissions ?? permissions,
+            expiresAt: Number(resp.payload.expiresAt),
+        };
+    }
+    async claimPairingInvite(tokenOrDeepLink) {
+        let inviteToken = tokenOrDeepLink.trim();
+        if (inviteToken.startsWith("dropspace://")) {
+            const url = new URL(inviteToken.replace(/^dropspace:\/\//, "https://dropspace.local/"));
+            inviteToken = url.searchParams.get("token") ?? inviteToken;
+        }
+        const resp = await this.sendSignalingRequest({
+            type: "pairing.claim_invite",
+            payload: { inviteToken },
+        });
+        return {
+            pairingId: String(resp.payload.pairingId),
+            spaceId: String(resp.payload.spaceId),
+            creatorDeviceId: String(resp.payload.creatorDeviceId),
+            state: resp.payload.state ?? "awaiting_approval",
+            requestedPermissions: resp.payload.requestedPermissions ?? [],
+            expiresAt: Number(resp.payload.expiresAt),
+        };
+    }
+    async approvePairing(pairingId, grantedPermissions) {
+        const resp = await this.sendSignalingRequest({
+            type: "pairing.approve",
+            payload: {
+                pairingId,
+                grantedPermissions: grantedPermissions ?? null,
+            },
+        });
+        const trusted = {
+            pairingId: String(resp.payload.pairingId),
+            spaceId: String(resp.spaceId ?? resp.payload.spaceId),
+            peerDeviceId: String(resp.payload.peerDeviceId),
+            peerLabel: String(resp.payload.peerLabel ?? "Trusted Device"),
+            peerPublicKey: String(resp.payload.peerPublicKey),
+            peerAlgorithm: resp.payload.peerAlgorithm ?? "ECDSA_P256_SHA256",
+            peerFingerprint: String(resp.payload.peerFingerprint),
+            permissions: resp.payload.permissions ?? [],
+            createdAt: Number(resp.payload.createdAt ?? Date.now()),
+        };
+        this.trustedPeers.set(trusted.peerDeviceId, trusted);
+        return trusted;
+    }
+    async rejectPairing(pairingId, reason) {
+        await this.sendSignalingRequest({
+            type: "pairing.reject",
+            payload: { pairingId, reason: reason ?? "Rejected by user" },
+        });
+    }
+    async cancelPairing(pairingId) {
+        await this.sendSignalingRequest({
+            type: "pairing.cancel",
+            payload: { pairingId },
+        });
+    }
+    async revokePeerAccess(opts) {
+        const spaceId = opts.spaceId ?? this.defaultSpaceId ?? "";
+        await this.sendSignalingRequest({
+            type: "revocation.revoke",
+            spaceId,
+            targetDeviceId: opts.targetDeviceId,
+            payload: {
+                targetDeviceId: opts.targetDeviceId,
+                spaceId,
+                pairingId: opts.pairingId ?? null,
+                reason: opts.reason ?? "User revoked access",
+            },
+        });
+    }
+    async listTrustedDevices() {
+        if (!this.sessionToken)
+            return Array.from(this.trustedPeers.values());
+        const fetchFn = this.getFetch();
+        const baseUrl = this.getCoreHttpUrl();
+        const res = await fetchFn(`${baseUrl}/api/v1/devices/trusted`, {
+            method: "GET",
+            headers: {
+                authorization: `Bearer ${this.sessionToken}`,
+            },
+        });
+        if (!res.ok) {
+            return Array.from(this.trustedPeers.values());
+        }
+        const data = (await res.json());
+        for (const peer of data.trustedPeers ?? []) {
+            this.trustedPeers.set(peer.peerDeviceId, peer);
+            this.subscribedSpaces.add(peer.spaceId);
+        }
+        return Array.from(this.trustedPeers.values());
+    }
+    async setExplicitHub(spaceId, hubDeviceId) {
+        await this.sendSignalingRequest({
+            type: "topology.set_hub",
+            spaceId,
+            payload: { hubDeviceId },
+        });
+    }
+    async getFreshIceServers() {
+        const now = Date.now();
+        if (this.signalingState === "connected" &&
+            (!this.turnCredentials || this.turnCredentials.expiresAt - now < 60_000)) {
+            try {
+                const resp = await this.sendSignalingRequest({
+                    type: "turn.credentials_request",
+                    payload: {},
+                });
+                this.turnCredentials = resp.payload;
+            }
+            catch {
+                // Use cached credentials if refresh fails
+            }
+        }
+        const servers = [];
+        if (this.options.staticStunUrls && this.options.staticStunUrls.length > 0) {
+            servers.push({ urls: this.options.staticStunUrls });
+        }
+        if (this.turnCredentials && this.turnCredentials.urls.length > 0) {
+            servers.push({
+                urls: this.turnCredentials.urls,
+                username: this.turnCredentials.username,
+                credential: this.turnCredentials.credential,
+            });
+        }
+        if (this.options.byoIceServers && this.options.byoIceServers.length > 0) {
+            for (const s of this.options.byoIceServers) {
+                servers.push(s);
+            }
+        }
+        return servers;
+    }
+    getOrCreateManagedPeerSession(remoteDeviceId, spaceId) {
+        const existing = this.peerSessions.get(remoteDeviceId);
+        if (existing)
+            return existing;
+        const maxPeers = this.options.maxPeers ?? 16;
+        if (this.peerSessions.size >= maxPeers) {
+            throw new Error(`Maximum peer connection limit (${maxPeers}) reached`);
+        }
+        const localId = this.getIdentity().deviceId;
+        const polite = localId.localeCompare(remoteDeviceId) < 0;
+        const session = new ManagedPeerSession({
+            localDeviceId: localId,
+            remoteDeviceId,
+            spaceId,
+            polite,
+            createPeerConnection: this.options.peerConnectionFactory ?? defaultPeerConnectionFactory,
+            getIceServers: () => this.getFreshIceServers(),
+            sendSignaling: async (type, connectionId, generation, payload) => {
+                await this.sendSignalingEnvelope({
+                    protocolVersion: PROTOCOL_VERSION,
+                    type,
+                    connectionId,
+                    generation,
+                    spaceId,
+                    targetDeviceId: remoteDeviceId,
+                    payload,
+                });
+            },
+            iceTransportPolicy: this.options.iceTransportPolicy,
+            disconnectGracePeriodMs: this.options.disconnectGracePeriodMs,
+            iceRestartTimeoutMs: this.options.iceRestartTimeoutMs,
+            connectTimeoutMs: this.options.connectTimeoutMs,
+            maxReconnectAttempts: this.options.maxReconnectAttempts,
+            baseBackoffMs: this.options.baseBackoffMs,
+        });
+        session.events.on("stateChange", (ev) => {
+            const qual = this.peerQuality.get(remoteDeviceId) ?? {
+                recentSuccessCount: 0,
+                recentFailureCount: 0,
+            };
+            if (ev.state === "connected") {
+                qual.recentSuccessCount += 1;
+                qual.lastConnectedAt = Date.now();
+            }
+            else if (ev.state === "failed") {
+                qual.recentFailureCount += 1;
+            }
+            this.peerQuality.set(remoteDeviceId, qual);
+            this.recordDebug("webrtc", `Peer ${remoteDeviceId} state ${ev.previousState} -> ${ev.state} (gen ${ev.generation})`, { reason: ev.reason, connectionId: ev.connectionId });
+            this.events.emit("peerStateChange", ev);
+        });
+        session.events.on("routeSelected", (ev) => {
+            const qual = this.peerQuality.get(remoteDeviceId) ?? {
+                recentSuccessCount: 1,
+                recentFailureCount: 0,
+            };
+            if (ev.rttMs !== undefined) {
+                qual.rttMs = ev.rttMs;
+            }
+            this.peerQuality.set(remoteDeviceId, qual);
+            this.routeByPeer.set(remoteDeviceId, {
+                candidateType: ev.candidateType,
+                protocol: ev.protocol,
+                rttMs: ev.rttMs,
+            });
+            this.recordDebug("webrtc", `Selected ${ev.candidateType} route for ${remoteDeviceId}`, {
+                candidateType: ev.candidateType,
+                rttMs: ev.rttMs,
+            });
+        });
+        session.multiplexer.events.on("message", (msg) => {
+            if (!this.hasPeerPermission(remoteDeviceId, "messaging", spaceId)) {
+                this.recordDebug("security", `Dropped incoming message from unauthorized peer ${remoteDeviceId}`);
+                return;
+            }
+            this.events.emit("message", msg);
+        });
+        session.multiplexer.events.on("transferFrame", (frame) => {
+            if (!this.hasPeerPermission(remoteDeviceId, "files", spaceId)) {
+                this.recordDebug("security", `Dropped incoming transferFrame from unauthorized peer ${remoteDeviceId}`);
+                return;
+            }
+            this.events.emit("transferFrame", { peerDeviceId: remoteDeviceId, frame });
+        });
+        session.multiplexer.events.on("crdtFrame", (frame) => {
+            if (!this.hasPeerPermission(remoteDeviceId, "crdt", spaceId)) {
+                this.recordDebug("security", `Dropped incoming crdtFrame from unauthorized peer ${remoteDeviceId}`);
+                return;
+            }
+            this.events.emit("crdtFrame", { peerDeviceId: remoteDeviceId, frame });
+        });
+        session.multiplexer.events.on("hubRelayFrame", (frame) => {
+            void this.handleHubRelayFrame(remoteDeviceId, frame);
+        });
+        this.peerSessions.set(remoteDeviceId, session);
+        return session;
+    }
+    /**
+     * Handles Explicit Hub forwarding or local delivery of a HUB_RELAY frame (Section 11).
+     * Enforces authorization, deduplication, hop limit, and loop prevention.
+     */
+    async handleHubRelayFrame(fromPeerId, relayFrame) {
+        const { header, payload } = relayFrame;
+        const localId = this.getIdentity().deviceId;
+        const targetId = header.targetDeviceId;
+        const sourceId = header.sourceDeviceId ?? fromPeerId;
+        const spaceId = header.spaceId ?? this.defaultSpaceId ?? "";
+        const hopCount = header.hopCount ?? 0;
+        const maxHops = header.maxHops ?? 2;
+        if (!targetId)
+            return;
+        // 1. Deduplication & loop guard
+        const now = Date.now();
+        if (this.hubSeenRelayIds.has(header.messageId)) {
+            this.recordDebug("hub", `Dropped duplicate hub relay frame ${header.messageId}`);
+            return;
+        }
+        this.hubSeenRelayIds.set(header.messageId, now);
+        if (this.hubSeenRelayIds.size > 2048) {
+            const oldestKey = this.hubSeenRelayIds.keys().next().value;
+            if (oldestKey)
+                this.hubSeenRelayIds.delete(oldestKey);
+        }
+        // 2. If addressed to us, unwrap and deliver
+        if (targetId === localId) {
+            try {
+                const inner = decodeWireFrame(payload);
+                inner.header.sourceDeviceId = sourceId;
+                const sourceSession = this.getOrCreateManagedPeerSession(sourceId, spaceId);
+                sourceSession.multiplexer.deliverHubUnwrappedFrame(inner, fromPeerId);
+            }
+            catch {
+                // Malformed inner frame
+            }
+            return;
+        }
+        // 3. Otherwise, we are asked to forward as an Explicit Hub
+        if (!this.options.enableHubRelay) {
+            this.recordDebug("hub", `Rejected relay from ${sourceId}: enableHubRelay is false`);
+            return;
+        }
+        if (hopCount >= maxHops || sourceId === targetId) {
+            this.recordDebug("hub", `Dropped relay frame ${header.messageId}: hop limit (${hopCount}/${maxHops}) or loop`);
+            return;
+        }
+        // 4. Verify both source and target are authorized, non-revoked members of spaceId
+        const revokedSet = this.revokedPeersBySpace.get(spaceId);
+        if (revokedSet?.has(sourceId) || revokedSet?.has(targetId)) {
+            this.recordDebug("security", `Hub blocked relay involving revoked peer in ${spaceId}`);
+            return;
+        }
+        const spacePeers = this.peersBySpace.get(spaceId);
+        const sourcePresence = spacePeers?.get(sourceId);
+        const targetPresence = spacePeers?.get(targetId);
+        if (sourcePresence &&
+            (!sourcePresence.permissions.includes("connect") ||
+                !sourcePresence.permissions.includes("messaging"))) {
+            this.recordDebug("security", `Hub blocked unauthorized source ${sourceId}`);
+            return;
+        }
+        if (targetPresence && !targetPresence.permissions.includes("connect")) {
+            this.recordDebug("security", `Hub blocked unauthorized target ${targetId}`);
+            return;
+        }
+        const targetSession = this.peerSessions.get(targetId);
+        if (!targetSession || targetSession.getState() !== "connected") {
+            this.recordDebug("hub", `Hub cannot forward to ${targetId}: target not connected`);
+            return;
+        }
+        const forwardedHeader = {
+            ...header,
+            hopCount: hopCount + 1,
+        };
+        const encoded = encodeWireFrame(WireFrameType.HUB_RELAY, forwardedHeader, payload);
+        await targetSession.multiplexer.sendRawWireFrame(WireFrameType.HUB_RELAY, forwardedHeader, payload);
+        void encoded;
+        this.recordDebug("hub", `Relayed frame ${header.messageId} from ${sourceId} to ${targetId} (hop ${hopCount + 1})`);
+    }
+    async connect(peerDeviceId, options) {
+        const spaceId = options?.spaceId ?? this.defaultSpaceId ?? "";
+        if (this.revokedPeersBySpace.get(spaceId)?.has(peerDeviceId)) {
+            throw new Error(`Cannot connect to revoked device '${peerDeviceId}'`);
+        }
+        const session = this.getOrCreateManagedPeerSession(peerDeviceId, spaceId);
+        await session.connect("sdk_connect");
+        if (options?.waitForOpen) {
+            await this.waitForPeerConnected(peerDeviceId, options.timeoutMs ?? 10_000);
+        }
+        return session;
+    }
+    waitForPeerConnected(peerDeviceId, timeoutMs = 10_000) {
+        const sess = this.peerSessions.get(peerDeviceId);
+        if (sess?.getState() === "connected") {
+            return Promise.resolve();
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                off();
+                reject(new Error(`Timed out waiting ${timeoutMs}ms for peer '${peerDeviceId}' to connect`));
+            }, timeoutMs);
+            const off = this.events.on("peerStateChange", (ev) => {
+                if (ev.peerDeviceId === peerDeviceId && ev.state === "connected") {
+                    clearTimeout(timer);
+                    off();
+                    resolve();
+                }
+                else if (ev.peerDeviceId === peerDeviceId && ev.state === "failed") {
+                    clearTimeout(timer);
+                    off();
+                    reject(new Error(`Connection to peer '${peerDeviceId}' failed: ${ev.reason}`));
+                }
+            });
+        });
+    }
+    getPeerSession(peerDeviceId) {
+        return this.peerSessions.get(peerDeviceId);
+    }
+    getConnectedPeerIds() {
+        const ids = [];
+        for (const [peerId, sess] of this.peerSessions.entries()) {
+            if (sess.getState() === "connected") {
+                ids.push(peerId);
+            }
+        }
+        return ids;
+    }
+    async sendBinaryMessage(peerDeviceId, payload, options = {}) {
+        if (options.viaHubDeviceId) {
+            const hubSess = this.peerSessions.get(options.viaHubDeviceId);
+            if (!hubSess || hubSess.getState() !== "connected") {
+                throw new Error(`Explicit hub '${options.viaHubDeviceId}' is not connected`);
+            }
+            const targetSess = this.getOrCreateManagedPeerSession(peerDeviceId, options.spaceId ?? this.defaultSpaceId ?? "");
+            void targetSess;
+            // Route via hub's multiplexer with targetDeviceId = peerDeviceId
+            const messageId = options.messageId ?? `hubmsg_${Date.now()}_${Math.random().toString(36).slice(2, 7)}`;
+            const innerFrame = encodeWireFrame(WireFrameType.MESSAGE_BINARY, {
+                messageId,
+                channel: options.channel ?? "default",
+                timestamp: Date.now(),
+                sourceDeviceId: this.getIdentity().deviceId,
+                targetDeviceId: peerDeviceId,
+            }, payload);
+            await hubSess.multiplexer.sendRawWireFrame(WireFrameType.HUB_RELAY, {
+                messageId: `relay_${messageId}`,
+                channel: "hub_relay",
+                timestamp: Date.now(),
+                sourceDeviceId: this.getIdentity().deviceId,
+                targetDeviceId: peerDeviceId,
+                spaceId: options.spaceId ?? this.defaultSpaceId ?? "",
+                hopCount: 0,
+                maxHops: options.maxHops ?? 2,
+            }, innerFrame, options.signal);
+            return { messageId };
+        }
+        const sess = this.peerSessions.get(peerDeviceId);
+        if (!sess || sess.getState() !== "connected") {
+            throw new Error(`Peer '${peerDeviceId}' is not connected`);
+        }
+        return sess.multiplexer.sendBinary(payload, options);
+    }
+    async sendJsonMessage(peerDeviceId, value, options = {}) {
+        if (options.viaHubDeviceId) {
+            const bytes = new TextEncoder().encode(JSON.stringify(value));
+            const hubSess = this.peerSessions.get(options.viaHubDeviceId);
+            if (!hubSess || hubSess.getState() !== "connected") {
+                throw new Error(`Explicit hub '${options.viaHubDeviceId}' is not connected`);
+            }
+            const messageId = options.messageId ?? `hubmsg_${Date.now()}_${Math.random().toString(36).slice(2, 7)}`;
+            const innerFrame = encodeWireFrame(WireFrameType.MESSAGE_JSON, {
+                messageId,
+                channel: options.channel ?? "default",
+                timestamp: Date.now(),
+                sourceDeviceId: this.getIdentity().deviceId,
+                targetDeviceId: peerDeviceId,
+            }, bytes);
+            await hubSess.multiplexer.sendRawWireFrame(WireFrameType.HUB_RELAY, {
+                messageId: `relay_${messageId}`,
+                channel: "hub_relay",
+                timestamp: Date.now(),
+                sourceDeviceId: this.getIdentity().deviceId,
+                targetDeviceId: peerDeviceId,
+                spaceId: options.spaceId ?? this.defaultSpaceId ?? "",
+                hopCount: 0,
+                maxHops: options.maxHops ?? 2,
+            }, innerFrame, options.signal);
+            return { messageId };
+        }
+        const sess = this.peerSessions.get(peerDeviceId);
+        if (!sess || sess.getState() !== "connected") {
+            throw new Error(`Peer '${peerDeviceId}' is not connected`);
+        }
+        return sess.multiplexer.sendJson(value, options);
+    }
+    /**
+     * Explicitly closes the client, all peer connections, signaling socket, timers, and listeners.
+     * Disables all automatic reconnection loops.
+     */
+    close() {
+        this.manuallyClosed = true;
+        this.stopHeartbeat();
+        if (this.wsReconnectTimer) {
+            clearTimeout(this.wsReconnectTimer);
+            this.wsReconnectTimer = null;
+        }
+        for (const pend of this.pendingRequests.values()) {
+            clearTimeout(pend.timer);
+            pend.reject(new Error("DropspaceClient closed"));
+        }
+        this.pendingRequests.clear();
+        for (const sess of this.peerSessions.values()) {
+            sess.close(false);
+            sess.multiplexer.dispose();
+        }
+        this.peerSessions.clear();
+        this.routeByPeer.clear();
+        if (this.ws) {
+            try {
+                this.ws.close(1000, "client_closed");
+            }
+            catch { }
+            this.ws = null;
+        }
+        this.transitionSignalingState("closed", "manual_close");
+        this.events.removeAllListeners();
+    }
+    hasPeerPermission(peerDeviceId, permission, spaceId) {
+        if (spaceId) {
+            if (this.revokedPeersBySpace.get(spaceId)?.has(peerDeviceId)) {
+                return false;
+            }
+            const presence = this.peersBySpace.get(spaceId)?.get(peerDeviceId);
+            if (presence) {
+                return presence.permissions.includes(permission);
+            }
+            for (const trusted of this.trustedPeers.values()) {
+                if (trusted.peerDeviceId === peerDeviceId && trusted.spaceId === spaceId) {
+                    return trusted.permissions.includes(permission);
+                }
+            }
+            return false;
+        }
+        for (const [spId, spacePeers] of this.peersBySpace.entries()) {
+            if (this.revokedPeersBySpace.get(spId)?.has(peerDeviceId))
+                continue;
+            const presence = spacePeers.get(peerDeviceId);
+            if (presence && presence.permissions.includes(permission)) {
+                return true;
+            }
+        }
+        for (const trusted of this.trustedPeers.values()) {
+            if (trusted.peerDeviceId === peerDeviceId &&
+                !this.revokedPeersBySpace.get(trusted.spaceId)?.has(peerDeviceId) &&
+                trusted.permissions.includes(permission)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    getPeerRouteInfo(peerDeviceId) {
+        return this.routeByPeer.get(peerDeviceId) ?? null;
+    }
+    getActiveResourceCounts() {
+        return {
+            listenerCount: this.events.listenerCount(),
+            pendingRequests: this.pendingRequests.size,
+            activePeerSessions: this.peerSessions.size,
+            hasHeartbeatTimer: this.heartbeatTimer !== null,
+            hasReconnectTimer: this.wsReconnectTimer !== null,
+        };
+    }
+}
+export function createClient(options) {
+    return new DropspaceClient(options);
+}
+//# sourceMappingURL=client.js.map