@livedesk/hub 0.1.57 → 0.1.59

package/src/console-direct.js

@@ -8,6 +8,7 @@ import {
   createDirectConsoleWireBudget,
   encodeDirectConsoleWireMessage
 } from '../../runtime-core/src/console-direct-wire.js';
+import { workspaceRoleCanControl, workspaceRoleCanRequest } from './auth/workspace-access.js';
 
 const DEFAULT_SIGNAL_URL = 'https://livedesk-wake.lovecrdm.workers.dev';
 const DEFAULT_STUN_URLS = Object.freeze(['stun:stun.cloudflare.com:3478']);
@@ -34,10 +35,15 @@ const ICE_CONNECT_TIMEOUT_MS = 10_000;
 const PEER_DISCONNECTED_TIMEOUT_MS = 5_000;
 const ACCESS_TOKEN_TIMEOUT_MS = 8_000;
 const SIGNAL_READY_TIMEOUT_MS = 10_000;
+const SIGNAL_HEARTBEAT_INTERVAL_MS = 15_000;
+const SIGNAL_HEARTBEAT_TIMEOUT_MS = 10_000;
 const CONTROL_ASSEMBLY_TIMEOUT_MS = 15_000;
 const MEDIA_ASSEMBLY_TIMEOUT_MS = 500;
 const LOGICAL_BIND_TIMEOUT_MS = 5_000;
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const CONSOLE_ACCESS_MAX_FUTURE_MS = 10 * 60 * 1000;
+const REVOKED_MEMBER_FENCE_MS = 60_000;
+const MAX_REVOKED_MEMBER_FENCES = 128;
 
 function normalizeSignalUrl(value) {
   const source = String(value || DEFAULT_SIGNAL_URL).trim();
@@ -55,6 +61,16 @@ function normalizeSignalUrl(value) {
   }
 }
 
+function signalHttpEndpoint(signalUrl, pathname) {
+  if (!(signalUrl instanceof URL)) return null;
+  const url = new URL(signalUrl.href);
+  url.protocol = url.protocol === 'ws:' ? 'http:' : 'https:';
+  url.pathname = pathname;
+  url.search = '';
+  url.hash = '';
+  return url;
+}
+
 function normalizeStunUrls(value) {
   const values = Array.isArray(value)
     ? value
@@ -150,6 +166,7 @@ function allowedHttpRequest(method, pathname) {
     || pathname === '/api/runtime/status'
     || pathname === '/api/runtime/restart'
     || pathname === '/api/auth/status'
+    || pathname === '/api/auth/session'
     || pathname === '/api/remote/status'
     || pathname === '/api/hub/status'
     || pathname === '/api/update/status'
@@ -160,10 +177,12 @@ function allowedHttpRequest(method, pathname) {
     || /^\/api\/captures(?:\/|$)/.test(pathname)
     || /^\/api\/capture-sessions(?:\/|$)/.test(pathname)
     || /^\/api\/remote\/devices(?:\/|$)/.test(pathname)
+    || pathname === '/api/remote/wall-preferences'
     || /^\/api\/remote\/frames$/.test(pathname)
     || /^\/api\/remote\/filesystem(?:\/|$)/.test(pathname)
     || /^\/api\/remote\/files(?:\/|$)/.test(pathname)
     || /^\/api\/remote\/tasks(?:\/|$)/.test(pathname)
+    || /^\/api\/remote\/workspace(?:\/|$)/.test(pathname)
     || /^\/api\/remote\/license(?:\/sync)?$/.test(pathname)) {
     return pathname !== '/api/remote/registry-credentials'
       && pathname !== '/api/remote/pairing-pin'
@@ -269,6 +288,7 @@ async function readBoundedResponseBytes(response, maxBytes) {
 
 export function createHubConsoleDirect(options = {}) {
   const signalUrl = normalizeSignalUrl(options.url);
+  const workspaceReauthUrl = signalHttpEndpoint(signalUrl, '/v2/rtc/reauth');
   const deviceId = String(options.deviceId || '').trim();
   const requestedHubInstanceId = String(options.hubInstanceId || '').trim();
   const hubInstanceId = UUID_PATTERN.test(requestedHubInstanceId)
@@ -283,6 +303,10 @@ export function createHubConsoleDirect(options = {}) {
   const getAccessToken = typeof options.getAccessToken === 'function'
     ? options.getAccessToken
     : async () => String(options.accessToken || '').trim();
+  const getWorkspaceAccess = typeof options.getWorkspaceAccess === 'function'
+    ? options.getWorkspaceAccess
+    : () => options.workspaceAccess || null;
+  const consoleProxyToken = String(options.consoleProxyToken || '').trim();
   const createPeerConnection = typeof options.createPeerConnection === 'function'
     ? options.createPeerConnection
     : (name, config) => new nodeDataChannel.PeerConnection(name, config);
@@ -302,6 +326,20 @@ export function createHubConsoleDirect(options = {}) {
     1,
     Number(options.signalReadyTimeoutMs) || SIGNAL_READY_TIMEOUT_MS
   );
+  const signalHeartbeatIntervalMs = Math.max(
+    1,
+    Number(options.signalHeartbeatIntervalMs) || SIGNAL_HEARTBEAT_INTERVAL_MS
+  );
+  const signalHeartbeatTimeoutMs = Math.max(
+    1,
+    Number(options.signalHeartbeatTimeoutMs) || SIGNAL_HEARTBEAT_TIMEOUT_MS
+  );
+  const scheduleSignalHeartbeatTimer = typeof options.scheduleSignalHeartbeatTimer === 'function'
+    ? options.scheduleSignalHeartbeatTimer
+    : setTimeout;
+  const cancelSignalHeartbeatTimer = typeof options.cancelSignalHeartbeatTimer === 'function'
+    ? options.cancelSignalHeartbeatTimer
+    : clearTimeout;
   const mediaAssemblyTimeoutMs = Math.max(
     1,
     Number(options.mediaAssemblyTimeoutMs) || MEDIA_ASSEMBLY_TIMEOUT_MS
@@ -311,12 +349,15 @@ export function createHubConsoleDirect(options = {}) {
     Number(options.logicalBindTimeoutMs) || LOGICAL_BIND_TIMEOUT_MS
   );
   const peers = new Map();
+  const revokedMembers = new Map();
   let signalSocket = null;
   let signalGeneration = 0;
   let peerGeneration = 0;
   let retryTimer = null;
   let accessTokenAttempt = null;
+  let workspaceReauthAttempt = null;
   let signalReadyDeadline = null;
+  let signalHeartbeat = null;
   let retryAttempt = 0;
   let retryNotBeforeAt = 0;
   let nextRetryAt = '';
@@ -331,10 +372,91 @@ export function createHubConsoleDirect(options = {}) {
   let malformedWireCloses = 0;
   let wireBudgetCleanupFailures = 0;
 
+  const currentHubWorkspaceAccess = () => {
+    const access = getWorkspaceAccess() || {};
+    return {
+      workspaceId: String(access.workspaceId || '').trim(),
+      workspaceKind: String(access.workspaceKind || '').trim().toLowerCase(),
+      role: String(access.role || '').trim().toLowerCase(),
+      membershipRevision: Math.max(0, Number(access.membershipRevision || 0))
+    };
+  };
+
+  const consoleWorkspaceAccess = payload => {
+    const workspaceId = String(payload?.workspaceId || '').trim();
+    const workspaceKind = String(payload?.workspaceKind || '').trim().toLowerCase();
+    const userId = String(payload?.memberUserId || '').trim();
+    const role = String(payload?.memberRole || '').trim().toLowerCase();
+    const membershipRevision = Number(payload?.membershipRevision || 0);
+    const accessExpiresAt = Number(payload?.accessExpiresAt || 0);
+    const hubAccess = currentHubWorkspaceAccess();
+    if (!hubAccess.workspaceId && !workspaceId && !workspaceKind && !userId && !role && accessExpiresAt === 0) {
+      return Object.freeze({
+        workspaceId: 'unconfigured-personal-workspace',
+        workspaceKind: 'personal',
+        userId: 'unconfigured-personal-user',
+        role: 'owner',
+        membershipRevision: 0,
+        accessExpiresAt: Date.now() + CONSOLE_ACCESS_MAX_FUTURE_MS
+      });
+    }
+    if (!workspaceId
+      || !['personal', 'team'].includes(workspaceKind)
+      || !userId
+      || workspaceId !== hubAccess.workspaceId
+      || workspaceKind !== hubAccess.workspaceKind
+      || !workspaceRoleCanControl(role)
+      || !Number.isSafeInteger(membershipRevision)
+      || membershipRevision < 0
+      || !Number.isFinite(accessExpiresAt)
+      || (workspaceKind === 'team' && (accessExpiresAt <= Date.now()
+        || accessExpiresAt > Date.now() + CONSOLE_ACCESS_MAX_FUTURE_MS))
+      || (workspaceKind === 'personal' && accessExpiresAt !== 0)) {
+      return null;
+    }
+    return Object.freeze({ workspaceId, workspaceKind, userId, role, membershipRevision, accessExpiresAt });
+  };
+
+  const consoleProxyHeaders = owner => ({
+    'X-LiveDesk-Console-Proxy': consoleProxyToken,
+    'X-LiveDesk-Workspace-Id': owner.workspaceAccess.workspaceId,
+    'X-LiveDesk-Workspace-Kind': owner.workspaceAccess.workspaceKind,
+    'X-LiveDesk-Workspace-User-Id': owner.workspaceAccess.userId,
+    'X-LiveDesk-Workspace-Role': owner.workspaceAccess.role,
+    'X-LiveDesk-Membership-Revision': String(owner.workspaceAccess.membershipRevision),
+    'X-LiveDesk-Workspace-Access-Expires-At': String(owner.workspaceAccess.accessExpiresAt)
+  });
+
+  const ownerWorkspaceAccessCurrent = owner => owner?.workspaceAccess
+    && (owner.workspaceAccess.workspaceId === currentHubWorkspaceAccess().workspaceId
+      || (!currentHubWorkspaceAccess().workspaceId
+        && owner.workspaceAccess.workspaceId === 'unconfigured-personal-workspace'))
+    && workspaceRoleCanControl(owner.workspaceAccess.role)
+    && (owner.workspaceAccess.workspaceKind === 'personal'
+      || owner.workspaceAccess.accessExpiresAt > Date.now());
+
   const isOwnerActive = owner => !owner.retired
     && owner.hubEpoch === hubEpoch
     && peers.get(owner.consoleId) === owner
-    && owner.generation > 0;
+    && owner.generation > 0
+    && ownerWorkspaceAccessCurrent(owner);
+
+  const memberFenceKey = (workspaceId, userId) => `${String(workspaceId || '').trim()}:${String(userId || '').trim()}`;
+
+  const pruneRevokedMembers = () => {
+    const now = Date.now();
+    for (const [key, expiresAt] of revokedMembers) {
+      if (expiresAt <= now) revokedMembers.delete(key);
+    }
+    while (revokedMembers.size > MAX_REVOKED_MEMBER_FENCES) {
+      revokedMembers.delete(revokedMembers.keys().next().value);
+    }
+  };
+
+  const memberIsFenced = access => {
+    pruneRevokedMembers();
+    return Number(revokedMembers.get(memberFenceKey(access?.workspaceId, access?.userId)) || 0) > Date.now();
+  };
 
   const sendSignal = payload => {
     if (!socketIsOpen(signalSocket, SignalingWebSocketImpl)) return false;
@@ -418,6 +540,8 @@ export function createHubConsoleDirect(options = {}) {
     owner.iceTimer = null;
     clearTimeout(owner.disconnectTimer);
     owner.disconnectTimer = null;
+    clearTimeout(owner.accessTimer);
+    owner.accessTimer = null;
     for (const pending of owner.pendingHttp.values()) {
       clearTimeout(pending.timeout);
       pending.cancelled = true;
@@ -447,6 +571,24 @@ export function createHubConsoleDirect(options = {}) {
     }
   };
 
+  const armOwnerAccessDeadline = owner => {
+    clearTimeout(owner.accessTimer);
+    owner.accessTimer = null;
+    if (owner.workspaceAccess?.workspaceKind !== 'team') return;
+    const delay = Number(owner.workspaceAccess.accessExpiresAt || 0) - Date.now();
+    if (delay <= 0) {
+      retirePeer(owner, 'console-workspace-access-expired');
+      return;
+    }
+    const generation = owner.generation;
+    owner.accessTimer = setTimeout(() => {
+      owner.accessTimer = null;
+      if (peers.get(owner.consoleId) !== owner || owner.generation !== generation || owner.retired) return;
+      retirePeer(owner, 'console-workspace-access-expired');
+    }, delay);
+    owner.accessTimer.unref?.();
+  };
+
   const retireAllPeers = reason => {
     for (const owner of [...peers.values()]) retirePeer(owner, reason, { notify: false });
   };
@@ -599,6 +741,15 @@ export function createHubConsoleDirect(options = {}) {
       sendHttpResponse(owner, requestId, { error: 'console-route-not-allowed' });
       return;
     }
+    if (!workspaceRoleCanRequest(owner.workspaceAccess?.role, method, requestUrl.pathname)) {
+      sendHttpResponse(owner, requestId, { status: 403, error: 'workspace-owner-required' });
+      return;
+    }
+    if (!ownerWorkspaceAccessCurrent(owner)) {
+      sendHttpResponse(owner, requestId, { status: 403, error: 'console-workspace-access-expired' });
+      retirePeer(owner, 'console-workspace-access-expired');
+      return;
+    }
     if (owner.pendingHttp.has(requestId)) {
       sendHttpResponse(owner, requestId, { error: 'console-http-request-duplicate' });
       return;
@@ -607,12 +758,20 @@ export function createHubConsoleDirect(options = {}) {
       sendHttpResponse(owner, requestId, { error: 'console-http-capacity-reached' });
       return;
     }
+    const isAuthSessionBootstrap = method === 'POST'
+      && requestUrl.pathname === '/api/auth/session';
     let body;
-    try {
-      body = decodeBase64Bounded(payload?.bodyBase64, MAX_HTTP_REQUEST_BYTES);
-    } catch (error) {
-      sendHttpResponse(owner, requestId, { error: error instanceof Error ? error.message : error });
-      return;
+    if (isAuthSessionBootstrap) {
+      body = Buffer.from(JSON.stringify({
+        workspaceId: owner.workspaceAccess.workspaceId
+      }), 'utf8');
+    } else {
+      try {
+        body = decodeBase64Bounded(payload?.bodyBase64, MAX_HTTP_REQUEST_BYTES);
+      } catch (error) {
+        sendHttpResponse(owner, requestId, { error: error instanceof Error ? error.message : error });
+        return;
+      }
     }
     const controller = new AbortController();
     const pending = { controller, timeout: null, cancelled: false };
@@ -625,7 +784,12 @@ export function createHubConsoleDirect(options = {}) {
     try {
       const response = await fetchImpl(requestUrl.href, {
         method,
-        headers: safeContentHeaders(payload?.headers),
+        headers: {
+          ...(isAuthSessionBootstrap
+            ? { 'content-type': 'application/json' }
+            : safeContentHeaders(payload?.headers)),
+          ...consoleProxyHeaders(owner)
+        },
         body: ['GET', 'HEAD'].includes(method) || body.byteLength === 0 ? undefined : body,
         signal: controller.signal
       });
@@ -697,7 +861,8 @@ export function createHubConsoleDirect(options = {}) {
     if (channelState.openRequested
       || channelId !== channelState.channelId
       || purpose !== channelState.purpose
-      || !allowedWebSocketPath(path, purpose)) {
+      || !allowedWebSocketPath(path, purpose)
+      || !workspaceRoleCanRequest(owner.workspaceAccess?.role, 'GET', String(path || '').split('?')[0])) {
       sendLifecycleControl(owner, {
         type: 'ws-error',
         channelId: channelState.channelId,
@@ -710,6 +875,15 @@ export function createHubConsoleDirect(options = {}) {
       });
       return;
     }
+    if (!ownerWorkspaceAccessCurrent(owner)) {
+      sendLifecycleControl(owner, {
+        type: 'ws-error',
+        channelId: channelState.channelId,
+        error: 'console-workspace-access-expired'
+      });
+      retirePeer(owner, 'console-workspace-access-expired');
+      return;
+    }
     channelState.openRequested = true;
     const localUrl = new URL(path, httpBaseUrl);
     const httpOrigin = new URL(httpBaseUrl).origin;
@@ -720,7 +894,10 @@ export function createHubConsoleDirect(options = {}) {
     localUrl.protocol = localUrl.protocol === 'https:' ? 'wss:' : 'ws:';
     let socket;
     try {
-      socket = new LocalWebSocketImpl(localUrl, { perMessageDeflate: false });
+      socket = new LocalWebSocketImpl(localUrl, {
+        headers: consoleProxyHeaders(owner),
+        perMessageDeflate: false
+      });
     } catch (error) {
       sendLifecycleControl(owner, {
         type: 'ws-error',
@@ -871,6 +1048,10 @@ export function createHubConsoleDirect(options = {}) {
 
   const handleDataChannelMessage = (owner, channelState, raw) => {
     if (!isOwnerActive(owner) || channelState.closed) return;
+    if (!ownerWorkspaceAccessCurrent(owner)) {
+      retirePeer(owner, 'console-workspace-access-expired');
+      return;
+    }
     try {
       if (typeof raw === 'string') throw new Error('console-direct-unframed-message');
       const message = channelState.assembler.push(raw);
@@ -991,12 +1172,33 @@ export function createHubConsoleDirect(options = {}) {
     const connectionId = String(payload?.connectionId || '');
     const ownerHubEpoch = String(payload?.hubEpoch || '');
     const description = payload?.description;
+    const workspaceAccess = consoleWorkspaceAccess(payload);
     if (!UUID_PATTERN.test(consoleId)
       || !UUID_PATTERN.test(connectionId)
       || ownerHubEpoch !== hubEpoch
+      || !workspaceAccess
       || description?.type !== 'offer'
       || typeof description.sdp !== 'string'
       || byteLength(description.sdp) > SDP_MAX_BYTES) {
+      if (UUID_PATTERN.test(consoleId) && UUID_PATTERN.test(connectionId)) {
+        sendSignal({
+          type: 'rtc-close',
+          consoleId,
+          connectionId,
+          hubEpoch: ownerHubEpoch,
+          reason: workspaceAccess ? 'console-direct-offer-invalid' : 'console-workspace-access-invalid'
+        });
+      }
+      return null;
+    }
+    if (memberIsFenced(workspaceAccess)) {
+      sendSignal({
+        type: 'rtc-close',
+        consoleId,
+        connectionId,
+        hubEpoch: ownerHubEpoch,
+        reason: 'workspace-member-revoked'
+      });
       return null;
     }
     if (candidateIsRelay(description.sdp)) {
@@ -1062,6 +1264,7 @@ export function createHubConsoleDirect(options = {}) {
       hubEpoch: ownerHubEpoch,
       generation: ++peerGeneration,
       peer,
+      workspaceAccess,
       control: null,
       channels: new Map(),
       pendingLogicalControl: new Map(),
@@ -1069,12 +1272,14 @@ export function createHubConsoleDirect(options = {}) {
       wireBudget: createDirectConsoleWireBudget({ maxBytes: MAX_SHARED_ASSEMBLY_BYTES }),
       iceTimer: null,
       disconnectTimer: null,
+      accessTimer: null,
       peerState: 'new',
       iceState: 'new',
       retired: false,
       createdAt: Date.now()
     };
     peers.set(consoleId, owner);
+    armOwnerAccessDeadline(owner);
     peer.onLocalDescription((sdp, type) => {
       if (!isOwnerActive(owner) || String(type).toLowerCase() !== 'answer' || byteLength(sdp) > SDP_MAX_BYTES) return;
       if (candidateIsRelay(sdp)) {
@@ -1160,10 +1365,17 @@ export function createHubConsoleDirect(options = {}) {
     if (!payload?.type) return;
     if (payload.type === 'signal-ready' && payload.role === 'hub') {
       const nextEpoch = String(payload.hubEpoch || '');
+      const signaledWorkspaceId = String(payload.workspaceId || '').trim();
+      const expectedWorkspaceId = currentHubWorkspaceAccess().workspaceId;
       if (!UUID_PATTERN.test(nextEpoch)) {
         lastError = 'console-direct-hub-epoch-invalid';
         return;
       }
+      if (expectedWorkspaceId && signaledWorkspaceId !== expectedWorkspaceId) {
+        lastError = 'console-direct-workspace-mismatch';
+        try { socket?.close?.(1008, 'console-direct-workspace-mismatch'); } catch {}
+        return;
+      }
       clearSignalReadyDeadline(ownerSignalGeneration, socket);
       if (hubEpoch && hubEpoch !== nextEpoch) retireAllPeers('console-direct-hub-epoch-replaced');
       hubEpoch = nextEpoch;
@@ -1174,8 +1386,85 @@ export function createHubConsoleDirect(options = {}) {
       retryAttempt = 0;
       retryNotBeforeAt = 0;
       nextRetryAt = '';
+      armSignalHeartbeat(ownerSignalGeneration, socket, connect);
+      return;
+    }
+    if (payload.type === 'workspace-access-expired') {
+      retireAllPeers('console-workspace-access-expired');
+      lastError = 'console-workspace-access-expired';
+      return;
+    }
+    if (payload.type === 'workspace-access-refreshed') {
+      const consoleId = String(payload.consoleId || '');
+      const connectionId = String(payload.connectionId || '');
+      const owner = peers.get(consoleId);
+      const refreshedAccess = consoleWorkspaceAccess(payload);
+      if (!owner
+        || owner.connectionId !== connectionId
+        || owner.hubEpoch !== String(payload.hubEpoch || '')
+        || !refreshedAccess
+        || owner.workspaceAccess.workspaceId !== refreshedAccess.workspaceId
+        || owner.workspaceAccess.userId !== refreshedAccess.userId
+        || memberIsFenced(refreshedAccess)) {
+        if (owner) retirePeer(owner, 'console-workspace-access-refresh-invalid');
+        return;
+      }
+      owner.workspaceAccess = refreshedAccess;
+      armOwnerAccessDeadline(owner);
       return;
     }
+    if (payload.type === 'workspace-reauth-required') {
+      const workspaceId = String(payload.workspaceId || '').trim();
+      const challengeNonce = String(payload.challengeNonce || '').trim();
+      if (workspaceId !== currentHubWorkspaceAccess().workspaceId
+        || !UUID_PATTERN.test(challengeNonce)
+        || !(workspaceReauthUrl instanceof URL)) {
+        lastError = 'console-workspace-reauth-challenge-invalid';
+        return;
+      }
+      if (workspaceReauthAttempt?.challengeNonce === challengeNonce) return;
+      try { workspaceReauthAttempt?.controller?.abort?.(); } catch {}
+      if (workspaceReauthAttempt?.timer) clearTimeout(workspaceReauthAttempt.timer);
+      const controller = new AbortController();
+      const attempt = {
+        challengeNonce,
+        generation: ownerSignalGeneration,
+        socket,
+        controller,
+        timer: null
+      };
+      workspaceReauthAttempt = attempt;
+      attempt.timer = setTimeout(() => controller.abort(), accessTokenTimeoutMs);
+      attempt.timer.unref?.();
+      void readAccessToken(ownerSignalGeneration).then(async result => {
+        if (signalSocket !== socket
+          || ownerSignalGeneration !== signalGeneration
+          || result.kind !== 'value') return;
+        const accessToken = String(result.value || '').trim();
+        if (!accessToken) return;
+        try {
+          const response = await fetchImpl(workspaceReauthUrl.href, {
+            method: 'POST',
+            headers: {
+              Authorization: `Bearer ${accessToken}`,
+              'Content-Type': 'application/json',
+              Accept: 'application/json'
+            },
+            body: JSON.stringify({ workspaceId, challengeNonce }),
+            signal: controller.signal
+          });
+          if (!response?.ok) lastError = `console-workspace-reauth-failed:${Number(response?.status || 0)}`;
+        } catch (error) {
+          if (error?.name !== 'AbortError') lastError = 'console-workspace-reauth-failed';
+        }
+      }).finally(() => {
+        if (workspaceReauthAttempt !== attempt) return;
+        if (attempt.timer) clearTimeout(attempt.timer);
+        workspaceReauthAttempt = null;
+      });
+      return;
+    }
+    if (payload.type === 'workspace-reauth-ok') return;
     const consoleId = String(payload.consoleId || '');
     const connectionId = String(payload.connectionId || '');
     const ownerHubEpoch = String(payload.hubEpoch || '');
@@ -1284,6 +1573,114 @@ export function createHubConsoleDirect(options = {}) {
     signalReadyDeadline = deadline;
   };
 
+  const clearSignalHeartbeat = (ownerSignalGeneration, socket) => {
+    const heartbeat = signalHeartbeat;
+    if (!heartbeat
+      || (ownerSignalGeneration !== undefined && heartbeat.generation !== ownerSignalGeneration)
+      || (socket !== undefined && heartbeat.socket !== socket)) {
+      return false;
+    }
+    signalHeartbeat = null;
+    cancelSignalHeartbeatTimer(heartbeat.timer);
+    return true;
+  };
+
+  const failSignalHeartbeat = (heartbeat, connect, reason) => {
+    if (signalHeartbeat !== heartbeat
+      || stopped
+      || heartbeat.generation !== signalGeneration
+      || signalSocket !== heartbeat.socket) {
+      return;
+    }
+    clearSignalHeartbeat(heartbeat.generation, heartbeat.socket);
+    signalSocket = null;
+    lastHttpStatus = 0;
+    lastError = reason;
+    retireNegotiatingPeers(reason);
+    try { heartbeat.socket.terminate?.(); } catch {}
+    scheduleReconnect(connect);
+  };
+
+  const scheduleSignalHeartbeatPing = (heartbeat, connect) => {
+    if (signalHeartbeat !== heartbeat
+      || stopped
+      || heartbeat.generation !== signalGeneration
+      || signalSocket !== heartbeat.socket) {
+      return;
+    }
+    heartbeat.awaitingPong = false;
+    let pingTimer = null;
+    pingTimer = scheduleSignalHeartbeatTimer(() => {
+      if (signalHeartbeat !== heartbeat
+        || heartbeat.timer !== pingTimer
+        || stopped
+        || heartbeat.generation !== signalGeneration
+        || signalSocket !== heartbeat.socket) {
+        return;
+      }
+      heartbeat.awaitingPong = true;
+      let timeoutTimer = null;
+      timeoutTimer = scheduleSignalHeartbeatTimer(() => {
+        if (signalHeartbeat !== heartbeat
+          || heartbeat.timer !== timeoutTimer
+          || !heartbeat.awaitingPong
+          || stopped
+          || heartbeat.generation !== signalGeneration
+          || signalSocket !== heartbeat.socket) {
+          return;
+        }
+        failSignalHeartbeat(
+          heartbeat,
+          connect,
+          'console-direct-signal-heartbeat-timeout'
+        );
+      }, signalHeartbeatTimeoutMs);
+      heartbeat.timer = timeoutTimer;
+      heartbeat.timer.unref?.();
+      try {
+        if (heartbeat.socket.readyState !== WebSocket.OPEN
+          || typeof heartbeat.socket.ping !== 'function') {
+          throw new Error('console-direct-signal-heartbeat-unavailable');
+        }
+        heartbeat.socket.ping();
+      } catch {
+        failSignalHeartbeat(
+          heartbeat,
+          connect,
+          'console-direct-signal-heartbeat-failed'
+        );
+      }
+    }, signalHeartbeatIntervalMs);
+    heartbeat.timer = pingTimer;
+    heartbeat.timer.unref?.();
+  };
+
+  const armSignalHeartbeat = (ownerSignalGeneration, socket, connect) => {
+    clearSignalHeartbeat();
+    const heartbeat = {
+      generation: ownerSignalGeneration,
+      socket,
+      timer: null,
+      awaitingPong: false
+    };
+    signalHeartbeat = heartbeat;
+    scheduleSignalHeartbeatPing(heartbeat, connect);
+  };
+
+  const acceptSignalHeartbeatPong = (ownerSignalGeneration, socket, connect) => {
+    const heartbeat = signalHeartbeat;
+    if (!heartbeat
+      || heartbeat.generation !== ownerSignalGeneration
+      || heartbeat.socket !== socket
+      || !heartbeat.awaitingPong) {
+      return false;
+    }
+    cancelSignalHeartbeatTimer(heartbeat.timer);
+    heartbeat.timer = null;
+    scheduleSignalHeartbeatPing(heartbeat, connect);
+    return true;
+  };
+
   const scheduleReconnect = connect => {
     if (stopped || retryTimer || !(signalUrl instanceof URL)) return;
     const sequenceDelay = retryDelaysMs[Math.min(retryAttempt, retryDelaysMs.length - 1)];
@@ -1329,6 +1726,10 @@ export function createHubConsoleDirect(options = {}) {
     const url = new URL(signalUrl);
     url.searchParams.set('deviceId', deviceId);
     url.searchParams.set('hubInstanceId', hubInstanceId);
+    const hubWorkspaceAccess = currentHubWorkspaceAccess();
+    if (hubWorkspaceAccess.workspaceId) {
+      url.searchParams.set('workspaceId', hubWorkspaceAccess.workspaceId);
+    }
     let socket;
     try {
       socket = new SignalingWebSocketImpl(url, {
@@ -1374,12 +1775,16 @@ export function createHubConsoleDirect(options = {}) {
         handleSignalMessage(raw, ownerSignalGeneration, socket);
       }
     });
+    socket.on('pong', () => {
+      acceptSignalHeartbeatPong(ownerSignalGeneration, socket, connect);
+    });
     socket.once('close', () => {
       const wasOwner = signalSocket === socket
         && ownerSignalGeneration === signalGeneration
         && !stopped;
       if (signalSocket === socket) signalSocket = null;
       clearSignalReadyDeadline(ownerSignalGeneration, socket);
+      clearSignalHeartbeat(ownerSignalGeneration, socket);
       if (!wasOwner) return;
       retireNegotiatingPeers('console-direct-signaling-closed');
       if (!retryTimer) state = 'disconnected';
@@ -1393,6 +1798,7 @@ export function createHubConsoleDirect(options = {}) {
       }
       signalSocket = null;
       clearSignalReadyDeadline(ownerSignalGeneration, socket);
+      clearSignalHeartbeat(ownerSignalGeneration, socket);
       retireNegotiatingPeers('console-direct-signaling-error');
       try { socket.terminate?.(); } catch {}
       scheduleReconnect(connect);
@@ -1411,8 +1817,12 @@ export function createHubConsoleDirect(options = {}) {
       return;
     }
     signalGeneration += 1;
+    try { workspaceReauthAttempt?.controller?.abort?.(); } catch {}
+    if (workspaceReauthAttempt?.timer) clearTimeout(workspaceReauthAttempt.timer);
+    workspaceReauthAttempt = null;
     cancelAccessTokenAttempt();
     clearSignalReadyDeadline();
+    clearSignalHeartbeat();
     if (retryTimer) clearTimeout(retryTimer);
     retryTimer = null;
     retryAttempt = 0;
@@ -1429,8 +1839,12 @@ export function createHubConsoleDirect(options = {}) {
     if (stopped) return;
     stopped = true;
     signalGeneration += 1;
+    try { workspaceReauthAttempt?.controller?.abort?.(); } catch {}
+    if (workspaceReauthAttempt?.timer) clearTimeout(workspaceReauthAttempt.timer);
+    workspaceReauthAttempt = null;
     cancelAccessTokenAttempt();
     clearSignalReadyDeadline();
+    clearSignalHeartbeat();
     if (retryTimer) clearTimeout(retryTimer);
     retryTimer = null;
     nextRetryAt = '';
@@ -1443,6 +1857,31 @@ export function createHubConsoleDirect(options = {}) {
     state = signalUrl ? 'closed' : 'disabled';
   };
 
+  const invalidateWorkspaceAccess = (reason = 'console-workspace-access-invalidated') => {
+    retireAllPeers(String(reason || 'console-workspace-access-invalidated').slice(0, 120));
+    refresh();
+  };
+
+  const revokeWorkspaceMember = (workspaceId, userId, reason = 'workspace-member-revoked') => {
+    const normalizedWorkspaceId = String(workspaceId || '').trim();
+    const normalizedUserId = String(userId || '').trim();
+    if (!normalizedWorkspaceId || !normalizedUserId) return 0;
+    pruneRevokedMembers();
+    revokedMembers.set(
+      memberFenceKey(normalizedWorkspaceId, normalizedUserId),
+      Date.now() + REVOKED_MEMBER_FENCE_MS
+    );
+    pruneRevokedMembers();
+    let retired = 0;
+    for (const owner of [...peers.values()]) {
+      if (owner.workspaceAccess?.workspaceId !== normalizedWorkspaceId
+        || owner.workspaceAccess?.userId !== normalizedUserId) continue;
+      retirePeer(owner, String(reason || 'workspace-member-revoked').slice(0, 120));
+      retired += 1;
+    }
+    return retired;
+  };
+
   const inspect = () => {
     let logicalWebSocketChannels = 0;
     let localWebSocketChannels = 0;
@@ -1454,12 +1893,14 @@ export function createHubConsoleDirect(options = {}) {
     let iceConnectTimers = 0;
     let peerDisconnectTimers = 0;
     let assemblyDeadlineTimers = 0;
+    let workspaceAccessTimers = 0;
     for (const owner of peers.values()) {
       logicalWebSocketChannels += owner.channels.size;
       pendingHttpRequests += owner.pendingHttp.size;
       pendingLogicalControlRequests += owner.pendingLogicalControl.size;
       if (owner.iceTimer) iceConnectTimers += 1;
       if (owner.disconnectTimer) peerDisconnectTimers += 1;
+      if (owner.accessTimer) workspaceAccessTimers += 1;
       if (owner.control && !owner.control.closed) controlChannels += 1;
       if (owner.control?.assemblyTimer) assemblyDeadlineTimers += 1;
       for (const channelState of owner.channels.values()) {
@@ -1472,6 +1913,7 @@ export function createHubConsoleDirect(options = {}) {
     const reconnectTimerActive = Boolean(retryTimer);
     const accessTokenDeadlineActive = Boolean(accessTokenAttempt);
     const signalReadyDeadlineActive = Boolean(signalReadyDeadline);
+    const signalHeartbeatTimerActive = Boolean(signalHeartbeat?.timer);
     return Object.freeze({
       enabled: signalUrl instanceof URL && Boolean(deviceId),
       state,
@@ -1488,9 +1930,13 @@ export function createHubConsoleDirect(options = {}) {
       iceConnectTimers,
       peerDisconnectTimers,
       assemblyDeadlineTimers,
+      workspaceAccessTimers,
+      revokedMemberFences: (pruneRevokedMembers(), revokedMembers.size),
       reconnectTimerActive,
       accessTokenDeadlineActive,
       signalReadyDeadlineActive,
+      signalHeartbeatTimerActive,
+      signalHeartbeatAwaitingPong: signalHeartbeat?.awaitingPong === true,
       resourceTimers: iceConnectTimers
         + peerDisconnectTimers
         + assemblyDeadlineTimers
@@ -1498,7 +1944,10 @@ export function createHubConsoleDirect(options = {}) {
         + pendingLogicalControlRequests
         + Number(reconnectTimerActive)
         + Number(accessTokenDeadlineActive)
-        + Number(signalReadyDeadlineActive),
+        + workspaceAccessTimers
+        + Number(Boolean(workspaceReauthAttempt?.timer))
+        + Number(signalReadyDeadlineActive)
+        + Number(signalHeartbeatTimerActive),
       rejectedRelayCandidates,
       dataChannelBackpressureCloses,
       malformedWireCloses,
@@ -1511,7 +1960,14 @@ export function createHubConsoleDirect(options = {}) {
     });
   };
 
-  return Object.freeze({ start, refresh, close, inspect });
+  return Object.freeze({
+    start,
+    refresh,
+    close,
+    invalidateWorkspaceAccess,
+    revokeWorkspaceMember,
+    inspect
+  });
 }
 
 export const consoleDirectContract = Object.freeze({
@@ -1530,6 +1986,8 @@ export const consoleDirectContract = Object.freeze({
   maxDefaultRetryDelayMs: DEFAULT_RETRY_DELAYS_MS.at(-1),
   accessTokenTimeoutMs: ACCESS_TOKEN_TIMEOUT_MS,
   signalReadyTimeoutMs: SIGNAL_READY_TIMEOUT_MS,
+  signalHeartbeatIntervalMs: SIGNAL_HEARTBEAT_INTERVAL_MS,
+  signalHeartbeatTimeoutMs: SIGNAL_HEARTBEAT_TIMEOUT_MS,
   logicalBindTimeoutMs: LOGICAL_BIND_TIMEOUT_MS,
   iceConnectTimeoutMs: ICE_CONNECT_TIMEOUT_MS,
   peerDisconnectedTimeoutMs: PEER_DISCONNECTED_TIMEOUT_MS,