@buoy-gg/sync-broker 7.0.36 → 7.0.39

package/README.md

@@ -1,57 +1,50 @@
 # @buoy-gg/sync-broker
 
-Headless Socket.IO **broker** for the Buoy devtool sync protocol (v1).
+Host the Socket.IO message router used by Buoy Desktop and MCP. It routes device capabilities, watched snapshots, and remote actions between device and dashboard clients. Most users should run Desktop or MCP instead of hosting this package directly.
 
-This is the message router that sits between **devices** (React Native apps running a Buoy devtool, connected as Socket.IO clients) and **dashboard clients** (the Buoy desktop app, and the Buoy MCP server). It was extracted from the desktop app's `apps/desktop/src/server` so the same implementation can be hosted by either:
+## Install
 
-- the **desktop app** (which owns its own express/http server), or
-- a **standalone process** such as the Buoy MCP server, when no desktop app is running.
+```bash
+npm install @buoy-gg/sync-broker
+```
+
+This is a Node host package. Use the exported `createBroker`, `socketHandle`, and protocol types when implementing a custom host.
 
-## Usage
+## Host a broker
 
-### Host a complete broker (standalone / MCP)
+The host must independently validate its Buoy account and supply admission through `canUseDesktop`. The default denies access. This integration sketch expects your host's existing `account` object; `hasAccess()` must reflect current verified admission, not merely the presence of a key:
 
 ```ts
 import { createBroker, DEFAULT_BROKER_PORT } from "@buoy-gg/sync-broker";
 
 const broker = createBroker({
-  port: DEFAULT_BROKER_PORT, // 42831
-  onListening: (port) => console.log(`broker listening on ${port}`),
-  onError: (err) => {
-    if (err.code === "EADDRINUSE") {
-      // Another broker (e.g. the desktop app) already owns the port —
-      // connect to it as a client instead of hosting your own.
-    }
-  },
+  port: DEFAULT_BROKER_PORT,
+  canUseDesktop: () => account.hasAccess(),
+  onListening: (port) => console.log(`Broker listening on ${port}`),
+  onError: (error) => console.error(error),
 });
 
-// later
+// Call when your account lifecycle changes admission:
+broker.refreshAccess();
+
+// Call during host shutdown:
 await broker.close();
 ```
 
-### Attach to an existing Socket.IO server (desktop app)
+Keep account revalidation and expiry handling active for the host's lifetime. Refresh routing when access changes. Device and client admission is separate from the host callback. A listening HTTP endpoint does not prove that a device has been admitted.
 
-```ts
-import { Server } from "socket.io";
-import { socketHandle } from "@buoy-gg/sync-broker";
+Try connecting to an existing broker before starting another. If startup reports EADDRINUSE, connect to the broker already using that port or resolve the conflict. The default port is `42831`.
 
-const io = new Server(httpServer, socketOptions);
-socketHandle({ io });
-```
+## Existing HTTP server
+
+For an existing Socket.IO server, use `socketHandle({ io, canUseDesktop })` and retain its returned `refreshAccess` function. Your host owns the HTTP server, Socket.IO options, account lifecycle, and shutdown. Do not attach routing twice to the same server.
 
-## Protocol
+## Message flow
 
-The wire contract (events, message shapes, watch/backpressure model) is **v1**, canonically defined in [`@buoy-gg/external-sync`](../external-sync). The broker reproduces the server-relevant types in `src/protocol.ts` to stay a dependency-light Node package (no React Native / `socket.io-client`).
+Devices announce capabilities. Dashboard watch requests control adapter subscriptions; the broker consolidates those requests. Device snapshots flow to watching clients, while named actions and their results travel in the opposite directions. Broker logs help diagnose admission, connection, and protocol problems. Offline device history is in memory and can be forgotten or age out.
 
-Topology and message flow:
+## Network and verification
 
-- Devices connect with a handshake carrying `deviceId`, `platform`, etc.
-- Dashboard clients connect with `deviceName: "Dashboard"` (exact, no suffix).
-- Devices announce `devtool-capabilities`; the broker replays them to dashboards.
-- Dashboards `devtool-watch` tools; the broker **consolidates** watch counts so a device receives a single `watching` true/false per `(device, tool)` regardless of how many dashboards are watching.
-- Dashboards invoke `devtool-action`; devices reply `devtool-action-result`.
-- Devices push `devtool-sync` snapshots; the broker forwards them to dashboards.
-- The broker emits `broker-log` entries to dashboards (handshakes, disconnect reasons, duplicate-name renames, protocol-version mismatches), buffering the last 200 so a dashboard that connects late still sees earlier failures.
-- Dashboards emit `forget-device` to remove an **offline** device from history; offline devices also age out automatically after 24h (`User.lastSeenAt`).
+The standalone server listens without a loopback-only host restriction. Default CORS allows any origin; CORS is not client authentication. Use a trusted development network and review access controls before exposing a custom host beyond it. Account admission does not establish app-specific authorization for every remote action.
 
-> **Security:** dev-only. No authentication, CORS is open (`*`), intended for loopback / trusted LAN.
+Test with a verified host and device account: connect, watch a known tool, and confirm its snapshot. Then revoke host admission and verify that access closes. Reconnect after restoring valid access and check that watch state resumes. See the [Desktop guide](https://buoy.gg/buoy/latest/docs/desktop) and [MCP guide](https://buoy.gg/buoy/latest/docs/mcp) for supported end-user hosts.

package/dist/index.d.mts

@@ -3,6 +3,7 @@ import http from 'http';
 
 type DefaultEventsMap = Record<string, (...args: any[]) => void>;
 interface Props {
+    canUseDesktop?: () => boolean;
     io: Server<DefaultEventsMap, DefaultEventsMap, DefaultEventsMap, any>;
 }
 /**
@@ -12,7 +13,9 @@ interface Props {
  * - Query state synchronization
  * - Action forwarding
  */
-declare function socketHandle({ io }: Props): void;
+declare function socketHandle({ io, canUseDesktop }: Props): {
+    refreshAccess(): void;
+};
 
 /** Default port the Buoy sync broker listens on. */
 declare const DEFAULT_BROKER_PORT = 42831;
@@ -24,6 +27,8 @@ declare const SOCKET_CONFIG: Partial<ServerOptions>;
 interface CreateBrokerOptions {
     /** Port to listen on. @default DEFAULT_BROKER_PORT (42831) */
     port?: number;
+    /** The host must supply its independently verified account admission. */
+    canUseDesktop?: () => boolean;
     /**
      * Extra Socket.IO server options merged over {@link SOCKET_CONFIG}. Use to
      * override CORS, transports, etc. for a specific host.
@@ -48,6 +53,7 @@ interface BrokerHandle {
     port: number;
     /** Stop the broker and release the port. */
     close: () => Promise<void>;
+    refreshAccess: () => void;
 }
 /**
  * Create and start a headless Buoy sync broker: an HTTP + Socket.IO server with
@@ -153,10 +159,17 @@ interface DevToolActionMessage {
     params?: unknown;
 }
 /**
- * A client's access tier. Mirrors `BuoyTier` in @buoy-gg/license; redeclared
- * here because the broker is a standalone node process with no client deps.
+ * A client's tier. Mirrors `BuoyTier` in @buoy-gg/license; redeclared here
+ * because the broker is a standalone node process with no client deps.
  */
-type BuoyTier = "anonymous" | "free" | "pro";
+type BuoyTier = "free" | "pro";
+/**
+ * What the broker knows about a device's account: its tier once the device
+ * has announced an admitted account, or "locked" until then. "locked" is not
+ * a tier — it is the broker's default for every socket, and what a device
+ * announces when its own account access ends.
+ */
+type DeviceTier = BuoyTier | "locked";
 /**
  * A connected client (device or dashboard) as tracked by the broker.
  * Mirrors the desktop dashboard's `User` type; the dashboard UI carries a few
@@ -194,12 +207,12 @@ interface User {
      * The device's access tier. Absent from clients older than the tier split —
      * derive it from `isPro` in that case (see `tierFromLicensePayload`).
      */
-    tier?: BuoyTier;
+    tier?: DeviceTier;
     /**
      * The device's Buoy license key, if any. Local dev connection only.
      *
      * Forwarded for free keys too, not just Pro ones, so the desktop dashboard
-     * can mirror the device's tier instead of sitting at anonymous while the
+     * can mirror the device's tier instead of showing it locked while the
      * phone it is attached to is signed in.
      */
     licenseKey?: string;

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import http from 'http';
 
 type DefaultEventsMap = Record<string, (...args: any[]) => void>;
 interface Props {
+    canUseDesktop?: () => boolean;
     io: Server<DefaultEventsMap, DefaultEventsMap, DefaultEventsMap, any>;
 }
 /**
@@ -12,7 +13,9 @@ interface Props {
  * - Query state synchronization
  * - Action forwarding
  */
-declare function socketHandle({ io }: Props): void;
+declare function socketHandle({ io, canUseDesktop }: Props): {
+    refreshAccess(): void;
+};
 
 /** Default port the Buoy sync broker listens on. */
 declare const DEFAULT_BROKER_PORT = 42831;
@@ -24,6 +27,8 @@ declare const SOCKET_CONFIG: Partial<ServerOptions>;
 interface CreateBrokerOptions {
     /** Port to listen on. @default DEFAULT_BROKER_PORT (42831) */
     port?: number;
+    /** The host must supply its independently verified account admission. */
+    canUseDesktop?: () => boolean;
     /**
      * Extra Socket.IO server options merged over {@link SOCKET_CONFIG}. Use to
      * override CORS, transports, etc. for a specific host.
@@ -48,6 +53,7 @@ interface BrokerHandle {
     port: number;
     /** Stop the broker and release the port. */
     close: () => Promise<void>;
+    refreshAccess: () => void;
 }
 /**
  * Create and start a headless Buoy sync broker: an HTTP + Socket.IO server with
@@ -153,10 +159,17 @@ interface DevToolActionMessage {
     params?: unknown;
 }
 /**
- * A client's access tier. Mirrors `BuoyTier` in @buoy-gg/license; redeclared
- * here because the broker is a standalone node process with no client deps.
+ * A client's tier. Mirrors `BuoyTier` in @buoy-gg/license; redeclared here
+ * because the broker is a standalone node process with no client deps.
  */
-type BuoyTier = "anonymous" | "free" | "pro";
+type BuoyTier = "free" | "pro";
+/**
+ * What the broker knows about a device's account: its tier once the device
+ * has announced an admitted account, or "locked" until then. "locked" is not
+ * a tier — it is the broker's default for every socket, and what a device
+ * announces when its own account access ends.
+ */
+type DeviceTier = BuoyTier | "locked";
 /**
  * A connected client (device or dashboard) as tracked by the broker.
  * Mirrors the desktop dashboard's `User` type; the dashboard UI carries a few
@@ -194,12 +207,12 @@ interface User {
      * The device's access tier. Absent from clients older than the tier split —
      * derive it from `isPro` in that case (see `tierFromLicensePayload`).
      */
-    tier?: BuoyTier;
+    tier?: DeviceTier;
     /**
      * The device's Buoy license key, if any. Local dev connection only.
      *
      * Forwarded for free keys too, not just Pro ones, so the desktop dashboard
-     * can mirror the device's tier instead of sitting at anonymous while the
+     * can mirror the device's tier instead of showing it locked while the
      * phone it is attached to is signed in.
      */
     licenseKey?: string;

package/dist/index.js

@@ -41,10 +41,9 @@ module.exports = __toCommonJS(index_exports);
 // src/protocol.ts
 var SYNC_PROTOCOL_VERSION = 1;
 function tierFromLicensePayload(payload) {
-  if (payload?.tier === "pro" || payload?.tier === "free" || payload?.tier === "anonymous") {
-    return payload.tier;
-  }
-  return payload?.isPro === "1" || payload?.isPro === true ? "pro" : "anonymous";
+  if (payload?.tier === "pro" || payload?.tier === "free") return payload.tier;
+  if (payload?.tier === "locked" || payload?.tier === "anonymous") return "locked";
+  return payload?.isPro === "1" || payload?.isPro === true ? "pro" : "locked";
 }
 
 // src/watchRegistry.ts
@@ -130,19 +129,31 @@ var WatchRegistry = class {
 };
 
 // src/socketHandle.ts
-var users = [];
-var allDevices = [];
-var dashboardClients = [];
-var deviceIdMap = /* @__PURE__ */ new Map();
-var activeConnectionsMap = /* @__PURE__ */ new Map();
-var instanceIdMap = /* @__PURE__ */ new Map();
-var deviceCapabilities = /* @__PURE__ */ new Map();
-var watches = new WatchRegistry();
-var brokerLogBuffer = [];
 var BROKER_LOG_BUFFER_MAX = 200;
 var MAX_OFFLINE_AGE_MS = 24 * 60 * 60 * 1e3;
-function socketHandle({ io }) {
+function redactAccountKeys(raw) {
+  if (!raw) return void 0;
+  try {
+    const value = JSON.parse(raw);
+    if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+    for (const key of ["BUOY_LICENSE_KEY", "BUOY_KEY", "EXPO_PUBLIC_BUOY_KEY", "VITE_BUOY_KEY", "REACT_APP_BUOY_KEY", "licenseKey"]) delete value[key];
+    return JSON.stringify(value);
+  } catch {
+    return void 0;
+  }
+}
+function socketHandle({ io, canUseDesktop = () => false }) {
   const LOG_PREFIX = "[SERVER]";
+  let users = [];
+  const allDevices = [];
+  let dashboardClients = [];
+  const deviceIdMap = /* @__PURE__ */ new Map();
+  const socketTiers = /* @__PURE__ */ new Map();
+  const activeConnectionsMap = /* @__PURE__ */ new Map();
+  const instanceIdMap = /* @__PURE__ */ new Map();
+  const deviceCapabilities = /* @__PURE__ */ new Map();
+  let watches = new WatchRegistry();
+  const brokerLogBuffer = [];
   function brokerLog(level, message, data) {
     console.log(`${LOG_PREFIX} ${message}`);
     const entry = { ts: Date.now(), level, message, data };
@@ -162,6 +173,20 @@ function socketHandle({ io }) {
     return instances.size;
   }
   function emitAllDevices() {
+    if (!canUseDesktop()) {
+      io.emit("all-devices-update", []);
+      return;
+    }
+    for (const device of [...users, ...allDevices]) {
+      if (device.deviceName === "Dashboard" || !device.isConnected) continue;
+      const tier = socketTiers.get(device.id) ?? "locked";
+      device.tier = tier === "pro" ? "pro" : tier === "free" ? "free" : "locked";
+      device.isPro = tier === "pro";
+      if (tier !== "free" && tier !== "pro") {
+        delete device.envVariables;
+        delete device.extraDeviceInfo;
+      }
+    }
     const now = Date.now();
     for (const device of allDevices) {
       if (!device.deviceId) continue;
@@ -191,7 +216,7 @@ function socketHandle({ io }) {
     }
     io.emit(
       "all-devices-update",
-      allDevices.filter((device) => device.deviceName !== "Dashboard")
+      allDevices.filter((device) => device.deviceName !== "Dashboard").map(({ licenseKey: _key, ...device }) => device)
     );
   }
   function handleClose(id, reason) {
@@ -199,6 +224,7 @@ function socketHandle({ io }) {
     const deviceId = deviceIdMap.get(id);
     deviceIdMap.delete(id);
     instanceIdMap.delete(id);
+    socketTiers.delete(id);
     let survivor;
     if (deviceId) {
       for (const [socketId, mappedDeviceId] of deviceIdMap) {
@@ -386,9 +412,11 @@ function socketHandle({ io }) {
   }
   function handleUserMessage(message, deviceName) {
     console.log(`${LOG_PREFIX} Message from ${deviceName}: ${message}`);
+    if (!canUseDesktop()) return;
     io.emit("message", `Device ${deviceName} sent message: ${message}`);
   }
   function forwardToDashboards(event, message) {
+    if (!canUseDesktop()) return;
     dashboardClients = dashboardClients.filter(
       (id) => io.sockets.sockets.has(id)
     );
@@ -400,6 +428,11 @@ function socketHandle({ io }) {
     }
   }
   function withTargetUsers(targetDeviceId, action, actionName) {
+    if (!canUseDesktop()) return;
+    const admitted = (user) => {
+      const tier = socketTiers.get(user.id);
+      return tier === "free" || tier === "pro";
+    };
     const deviceName = getDeviceFromDeviceId(targetDeviceId)?.deviceName;
     if (targetDeviceId === "No devices available") {
       console.log(
@@ -415,10 +448,10 @@ function socketHandle({ io }) {
       console.log(
         `${LOG_PREFIX} Sending to ${deviceUsers.length} devices: ${deviceUsers.map((u) => u.deviceName).join(", ")}`
       );
-      deviceUsers.forEach(action);
+      deviceUsers.filter(admitted).forEach(action);
     } else {
       const targetUser = users.find((user) => user.deviceId === targetDeviceId);
-      if (targetUser) {
+      if (targetUser && admitted(targetUser)) {
         console.log(
           `${LOG_PREFIX} Sending to target device ${targetUser.deviceName} (${targetUser.deviceId}) targetDeviceId: ${targetDeviceId}`
         );
@@ -469,6 +502,27 @@ function socketHandle({ io }) {
     }
   }
   io.on("connection", (socket) => {
+    const sendAccess = () => socket.emit("buoy:access", { protocol: 1, ready: canUseDesktop() });
+    sendAccess();
+    socket.on("buoy:access:request", sendAccess);
+    socket.use((_packet, next) => {
+      if (_packet[0] === "buoy:access:request") {
+        next();
+        return;
+      }
+      if (!canUseDesktop()) {
+        sendAccess();
+        return;
+      }
+      const control = _packet[0] === "device-license";
+      if (control) {
+        const payload = _packet[1] ?? {};
+        socketTiers.set(socket.id, tierFromLicensePayload(payload));
+      }
+      const deviceAdmitted = socketTiers.get(socket.id) === "free" || socketTiers.get(socket.id) === "pro";
+      if (control || dashboardClients.includes(socket.id) || deviceAdmitted) next();
+      else sendAccess();
+    });
     const {
       deviceName,
       deviceId,
@@ -482,18 +536,18 @@ function socketHandle({ io }) {
       instanceIdMap.set(socket.id, instanceId);
     }
     console.log(
-      `${LOG_PREFIX} New connection - ID: ${socket.id}, Name: ${deviceName || "Unknown Device"}${deviceId ? `, DeviceId: ${deviceId}` : ""}${platform ? `, Platform: ${platform}` : ""}${extraDeviceInfo ? `, ExtraDeviceInfo: ${extraDeviceInfo}` : ""}${envVariables ? `, EnvVariables: ${envVariables}` : ""}`
+      `${LOG_PREFIX} New connection - ID: ${socket.id}, Name: ${deviceName || "Unknown Device"}${deviceId ? `, DeviceId: ${deviceId}` : ""}${platform ? `, Platform: ${platform}` : ""}`
     );
     addNewUser({
       id: socket.id,
       deviceName: deviceName || "Unknown Device Name",
       deviceId,
       platform,
-      extraDeviceInfo,
-      envVariables,
+      extraDeviceInfo: void 0,
+      envVariables: void 0,
       connectionNonce
     });
-    if (deviceName === "Dashboard") {
+    if (canUseDesktop() && deviceName === "Dashboard") {
       for (const capabilities of deviceCapabilities.values()) {
         socket.emit("devtool-capabilities", capabilities);
       }
@@ -506,25 +560,32 @@ function socketHandle({ io }) {
       (payload) => {
         const nextTier = tierFromLicensePayload(payload ?? {});
         const nextIsPro = nextTier === "pro";
-        const nextKey = nextTier === "anonymous" ? void 0 : payload?.licenseKey || void 0;
+        socketTiers.set(socket.id, nextTier);
         const user = users.find((u) => u.id === socket.id);
         if (user) {
           user.isPro = nextIsPro;
           user.tier = nextTier;
-          user.licenseKey = nextKey;
+          delete user.licenseKey;
         }
         const did = user?.deviceId || deviceIdMap.get(socket.id);
+        if (nextTier !== "locked") {
+          for (const record of [...users, ...allDevices].filter((record2) => record2.id === socket.id)) {
+            record.extraDeviceInfo = redactAccountKeys(extraDeviceInfo);
+            record.envVariables = redactAccountKeys(envVariables);
+          }
+        }
         if (did) {
+          if (nextTier === "locked") deviceCapabilities.delete(did);
           const device = allDevices.find((d) => d.deviceId === did);
           if (device) {
             device.isPro = nextIsPro;
             device.tier = nextTier;
-            device.licenseKey = nextKey;
+            delete device.licenseKey;
           }
         }
         brokerLog(
           "debug",
-          `device-license from ${user?.deviceName || socket.id}: tier=${nextTier}${nextKey ? ", key set" : ""}`,
+          `device-license from ${user?.deviceName || socket.id}: tier=${nextTier}`,
           { socketId: socket.id }
         );
         emitAllDevices();
@@ -538,6 +599,7 @@ function socketHandle({ io }) {
       handleUserMessage(msg, deviceName || "Unknown");
     });
     socket.on("devtool-capabilities", (message) => {
+      if (!message || !Array.isArray(message.tools) || message.persistentDeviceId !== deviceIdMap.get(socket.id)) return;
       console.log(
         `${LOG_PREFIX} Capabilities from ${message.persistentDeviceId}: ${message.tools.map((tool) => `${tool.toolId}@v${tool.version}`).join(", ")}`
       );
@@ -567,11 +629,13 @@ function socketHandle({ io }) {
       }
     });
     socket.on("devtool-sync", (message) => {
+      if (!message || message.persistentDeviceId !== deviceIdMap.get(socket.id)) return;
       forwardToDashboards("devtool-sync", message);
     });
     socket.on(
       "devtool-action-result",
       (message) => {
+        if (!message || message.persistentDeviceId !== deviceIdMap.get(socket.id)) return;
         console.log(
           `${LOG_PREFIX} Action result from ${message.persistentDeviceId}: ${message.toolId}.${message.action} -> ${message.ok ? "ok" : `error: ${message.error}`}`
         );
@@ -624,6 +688,24 @@ function socketHandle({ io }) {
       );
     });
   });
+  return {
+    refreshAccess() {
+      const ready = canUseDesktop();
+      if (!ready) {
+        socketTiers.clear();
+        deviceCapabilities.clear();
+        brokerLogBuffer.length = 0;
+        watches = new WatchRegistry();
+        for (const device of [...users, ...allDevices]) {
+          delete device.licenseKey;
+          delete device.envVariables;
+          delete device.extraDeviceInfo;
+        }
+      }
+      io.emit("buoy:access", { protocol: 1, ready });
+      emitAllDevices();
+    }
+  };
 }
 
 // src/createBroker.ts
@@ -658,7 +740,7 @@ function createBroker(options = {}) {
     ...SOCKET_CONFIG,
     ...options.socketOptions
   });
-  socketHandle({ io });
+  const routing = socketHandle({ io, canUseDesktop: options.canUseDesktop });
   httpServer.on("error", (error) => {
     options.onError?.(error);
   });
@@ -670,7 +752,7 @@ function createBroker(options = {}) {
       httpServer.close(() => resolve());
     });
   });
-  return { io, httpServer, port, close };
+  return { io, httpServer, port, close, refreshAccess: routing.refreshAccess };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.mjs

@@ -1,10 +1,9 @@
 // src/protocol.ts
 var SYNC_PROTOCOL_VERSION = 1;
 function tierFromLicensePayload(payload) {
-  if (payload?.tier === "pro" || payload?.tier === "free" || payload?.tier === "anonymous") {
-    return payload.tier;
-  }
-  return payload?.isPro === "1" || payload?.isPro === true ? "pro" : "anonymous";
+  if (payload?.tier === "pro" || payload?.tier === "free") return payload.tier;
+  if (payload?.tier === "locked" || payload?.tier === "anonymous") return "locked";
+  return payload?.isPro === "1" || payload?.isPro === true ? "pro" : "locked";
 }
 
 // src/watchRegistry.ts
@@ -90,19 +89,31 @@ var WatchRegistry = class {
 };
 
 // src/socketHandle.ts
-var users = [];
-var allDevices = [];
-var dashboardClients = [];
-var deviceIdMap = /* @__PURE__ */ new Map();
-var activeConnectionsMap = /* @__PURE__ */ new Map();
-var instanceIdMap = /* @__PURE__ */ new Map();
-var deviceCapabilities = /* @__PURE__ */ new Map();
-var watches = new WatchRegistry();
-var brokerLogBuffer = [];
 var BROKER_LOG_BUFFER_MAX = 200;
 var MAX_OFFLINE_AGE_MS = 24 * 60 * 60 * 1e3;
-function socketHandle({ io }) {
+function redactAccountKeys(raw) {
+  if (!raw) return void 0;
+  try {
+    const value = JSON.parse(raw);
+    if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+    for (const key of ["BUOY_LICENSE_KEY", "BUOY_KEY", "EXPO_PUBLIC_BUOY_KEY", "VITE_BUOY_KEY", "REACT_APP_BUOY_KEY", "licenseKey"]) delete value[key];
+    return JSON.stringify(value);
+  } catch {
+    return void 0;
+  }
+}
+function socketHandle({ io, canUseDesktop = () => false }) {
   const LOG_PREFIX = "[SERVER]";
+  let users = [];
+  const allDevices = [];
+  let dashboardClients = [];
+  const deviceIdMap = /* @__PURE__ */ new Map();
+  const socketTiers = /* @__PURE__ */ new Map();
+  const activeConnectionsMap = /* @__PURE__ */ new Map();
+  const instanceIdMap = /* @__PURE__ */ new Map();
+  const deviceCapabilities = /* @__PURE__ */ new Map();
+  let watches = new WatchRegistry();
+  const brokerLogBuffer = [];
   function brokerLog(level, message, data) {
     console.log(`${LOG_PREFIX} ${message}`);
     const entry = { ts: Date.now(), level, message, data };
@@ -122,6 +133,20 @@ function socketHandle({ io }) {
     return instances.size;
   }
   function emitAllDevices() {
+    if (!canUseDesktop()) {
+      io.emit("all-devices-update", []);
+      return;
+    }
+    for (const device of [...users, ...allDevices]) {
+      if (device.deviceName === "Dashboard" || !device.isConnected) continue;
+      const tier = socketTiers.get(device.id) ?? "locked";
+      device.tier = tier === "pro" ? "pro" : tier === "free" ? "free" : "locked";
+      device.isPro = tier === "pro";
+      if (tier !== "free" && tier !== "pro") {
+        delete device.envVariables;
+        delete device.extraDeviceInfo;
+      }
+    }
     const now = Date.now();
     for (const device of allDevices) {
       if (!device.deviceId) continue;
@@ -151,7 +176,7 @@ function socketHandle({ io }) {
     }
     io.emit(
       "all-devices-update",
-      allDevices.filter((device) => device.deviceName !== "Dashboard")
+      allDevices.filter((device) => device.deviceName !== "Dashboard").map(({ licenseKey: _key, ...device }) => device)
     );
   }
   function handleClose(id, reason) {
@@ -159,6 +184,7 @@ function socketHandle({ io }) {
     const deviceId = deviceIdMap.get(id);
     deviceIdMap.delete(id);
     instanceIdMap.delete(id);
+    socketTiers.delete(id);
     let survivor;
     if (deviceId) {
       for (const [socketId, mappedDeviceId] of deviceIdMap) {
@@ -346,9 +372,11 @@ function socketHandle({ io }) {
   }
   function handleUserMessage(message, deviceName) {
     console.log(`${LOG_PREFIX} Message from ${deviceName}: ${message}`);
+    if (!canUseDesktop()) return;
     io.emit("message", `Device ${deviceName} sent message: ${message}`);
   }
   function forwardToDashboards(event, message) {
+    if (!canUseDesktop()) return;
     dashboardClients = dashboardClients.filter(
       (id) => io.sockets.sockets.has(id)
     );
@@ -360,6 +388,11 @@ function socketHandle({ io }) {
     }
   }
   function withTargetUsers(targetDeviceId, action, actionName) {
+    if (!canUseDesktop()) return;
+    const admitted = (user) => {
+      const tier = socketTiers.get(user.id);
+      return tier === "free" || tier === "pro";
+    };
     const deviceName = getDeviceFromDeviceId(targetDeviceId)?.deviceName;
     if (targetDeviceId === "No devices available") {
       console.log(
@@ -375,10 +408,10 @@ function socketHandle({ io }) {
       console.log(
         `${LOG_PREFIX} Sending to ${deviceUsers.length} devices: ${deviceUsers.map((u) => u.deviceName).join(", ")}`
       );
-      deviceUsers.forEach(action);
+      deviceUsers.filter(admitted).forEach(action);
     } else {
       const targetUser = users.find((user) => user.deviceId === targetDeviceId);
-      if (targetUser) {
+      if (targetUser && admitted(targetUser)) {
         console.log(
           `${LOG_PREFIX} Sending to target device ${targetUser.deviceName} (${targetUser.deviceId}) targetDeviceId: ${targetDeviceId}`
         );
@@ -429,6 +462,27 @@ function socketHandle({ io }) {
     }
   }
   io.on("connection", (socket) => {
+    const sendAccess = () => socket.emit("buoy:access", { protocol: 1, ready: canUseDesktop() });
+    sendAccess();
+    socket.on("buoy:access:request", sendAccess);
+    socket.use((_packet, next) => {
+      if (_packet[0] === "buoy:access:request") {
+        next();
+        return;
+      }
+      if (!canUseDesktop()) {
+        sendAccess();
+        return;
+      }
+      const control = _packet[0] === "device-license";
+      if (control) {
+        const payload = _packet[1] ?? {};
+        socketTiers.set(socket.id, tierFromLicensePayload(payload));
+      }
+      const deviceAdmitted = socketTiers.get(socket.id) === "free" || socketTiers.get(socket.id) === "pro";
+      if (control || dashboardClients.includes(socket.id) || deviceAdmitted) next();
+      else sendAccess();
+    });
     const {
       deviceName,
       deviceId,
@@ -442,18 +496,18 @@ function socketHandle({ io }) {
       instanceIdMap.set(socket.id, instanceId);
     }
     console.log(
-      `${LOG_PREFIX} New connection - ID: ${socket.id}, Name: ${deviceName || "Unknown Device"}${deviceId ? `, DeviceId: ${deviceId}` : ""}${platform ? `, Platform: ${platform}` : ""}${extraDeviceInfo ? `, ExtraDeviceInfo: ${extraDeviceInfo}` : ""}${envVariables ? `, EnvVariables: ${envVariables}` : ""}`
+      `${LOG_PREFIX} New connection - ID: ${socket.id}, Name: ${deviceName || "Unknown Device"}${deviceId ? `, DeviceId: ${deviceId}` : ""}${platform ? `, Platform: ${platform}` : ""}`
     );
     addNewUser({
       id: socket.id,
       deviceName: deviceName || "Unknown Device Name",
       deviceId,
       platform,
-      extraDeviceInfo,
-      envVariables,
+      extraDeviceInfo: void 0,
+      envVariables: void 0,
       connectionNonce
     });
-    if (deviceName === "Dashboard") {
+    if (canUseDesktop() && deviceName === "Dashboard") {
       for (const capabilities of deviceCapabilities.values()) {
         socket.emit("devtool-capabilities", capabilities);
       }
@@ -466,25 +520,32 @@ function socketHandle({ io }) {
       (payload) => {
         const nextTier = tierFromLicensePayload(payload ?? {});
         const nextIsPro = nextTier === "pro";
-        const nextKey = nextTier === "anonymous" ? void 0 : payload?.licenseKey || void 0;
+        socketTiers.set(socket.id, nextTier);
         const user = users.find((u) => u.id === socket.id);
         if (user) {
           user.isPro = nextIsPro;
           user.tier = nextTier;
-          user.licenseKey = nextKey;
+          delete user.licenseKey;
         }
         const did = user?.deviceId || deviceIdMap.get(socket.id);
+        if (nextTier !== "locked") {
+          for (const record of [...users, ...allDevices].filter((record2) => record2.id === socket.id)) {
+            record.extraDeviceInfo = redactAccountKeys(extraDeviceInfo);
+            record.envVariables = redactAccountKeys(envVariables);
+          }
+        }
         if (did) {
+          if (nextTier === "locked") deviceCapabilities.delete(did);
           const device = allDevices.find((d) => d.deviceId === did);
           if (device) {
             device.isPro = nextIsPro;
             device.tier = nextTier;
-            device.licenseKey = nextKey;
+            delete device.licenseKey;
           }
         }
         brokerLog(
           "debug",
-          `device-license from ${user?.deviceName || socket.id}: tier=${nextTier}${nextKey ? ", key set" : ""}`,
+          `device-license from ${user?.deviceName || socket.id}: tier=${nextTier}`,
           { socketId: socket.id }
         );
         emitAllDevices();
@@ -498,6 +559,7 @@ function socketHandle({ io }) {
       handleUserMessage(msg, deviceName || "Unknown");
     });
     socket.on("devtool-capabilities", (message) => {
+      if (!message || !Array.isArray(message.tools) || message.persistentDeviceId !== deviceIdMap.get(socket.id)) return;
       console.log(
         `${LOG_PREFIX} Capabilities from ${message.persistentDeviceId}: ${message.tools.map((tool) => `${tool.toolId}@v${tool.version}`).join(", ")}`
       );
@@ -527,11 +589,13 @@ function socketHandle({ io }) {
       }
     });
     socket.on("devtool-sync", (message) => {
+      if (!message || message.persistentDeviceId !== deviceIdMap.get(socket.id)) return;
       forwardToDashboards("devtool-sync", message);
     });
     socket.on(
       "devtool-action-result",
       (message) => {
+        if (!message || message.persistentDeviceId !== deviceIdMap.get(socket.id)) return;
         console.log(
           `${LOG_PREFIX} Action result from ${message.persistentDeviceId}: ${message.toolId}.${message.action} -> ${message.ok ? "ok" : `error: ${message.error}`}`
         );
@@ -584,6 +648,24 @@ function socketHandle({ io }) {
       );
     });
   });
+  return {
+    refreshAccess() {
+      const ready = canUseDesktop();
+      if (!ready) {
+        socketTiers.clear();
+        deviceCapabilities.clear();
+        brokerLogBuffer.length = 0;
+        watches = new WatchRegistry();
+        for (const device of [...users, ...allDevices]) {
+          delete device.licenseKey;
+          delete device.envVariables;
+          delete device.extraDeviceInfo;
+        }
+      }
+      io.emit("buoy:access", { protocol: 1, ready });
+      emitAllDevices();
+    }
+  };
 }
 
 // src/createBroker.ts
@@ -618,7 +700,7 @@ function createBroker(options = {}) {
     ...SOCKET_CONFIG,
     ...options.socketOptions
   });
-  socketHandle({ io });
+  const routing = socketHandle({ io, canUseDesktop: options.canUseDesktop });
   httpServer.on("error", (error) => {
     options.onError?.(error);
   });
@@ -630,7 +712,7 @@ function createBroker(options = {}) {
       httpServer.close(() => resolve());
     });
   });
-  return { io, httpServer, port, close };
+  return { io, httpServer, port, close, refreshAccess: routing.refreshAccess };
 }
 export {
   DEFAULT_BROKER_PORT,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buoy-gg/sync-broker",
-  "version": "7.0.36",
+  "version": "7.0.39",
   "description": "Headless Socket.IO broker for the Buoy devtool sync protocol (v1) — routes messages between devices and dashboard/MCP clients",
   "main": "dist/index.js",
   "module": "dist/index.mjs",