@buoy-gg/external-sync 7.0.36 → 7.0.38

package/README.md

@@ -0,0 +1,79 @@
+# @buoy-gg/external-sync
+
+Connect a React Native app's Buoy tools to Buoy Desktop or MCP. This package provides the device-side socket connection, adapter synchronization, and remote-action handling. Most apps configure it through `FloatingDevTools` from `@buoy-gg/core`.
+
+## Install
+
+```bash
+npm install @buoy-gg/core @buoy-gg/external-sync @buoy-gg/network
+```
+
+## Account setup
+
+Start in a development build with a Free or Pro Buoy account key. From the app directory:
+
+```bash
+npx --package=@buoy-gg/core buoy login
+```
+
+For Expo, initialize Buoy with the key written to `.env.local`:
+
+```tsx
+import { Buoy } from "@buoy-gg/core";
+
+Buoy.init({ licenseKey: process.env.EXPO_PUBLIC_BUOY_KEY });
+```
+
+For React Native CLI, pass the key through your app's environment configuration; `.env.local` is not loaded automatically. Keep the menu inside the providers used by your app. Restart the development server after installing packages. See the [Quick Start](https://buoy.gg/buoy/latest/docs/quick-start) for the complete root component.
+
+## Connect your app
+
+Mount the menu in your existing root component after account initialization:
+
+```tsx
+import { FloatingDevTools } from "@buoy-gg/core";
+
+<FloatingDevTools />;
+```
+
+Open Desktop and sign in. In development, the app normally derives the broker address from Metro. If your network or Expo tunnel setup needs an explicit address, replace the menu above with:
+
+```tsx
+<FloatingDevTools
+  externalSync={{ socketURL: "http://YOUR_COMPUTER_LAN_IP:42831" }}
+/>;
+```
+
+`socketURL` has an uppercase URL. The device must be able to reach that address; a Metro tunnel does not automatically expose the broker. For Android over USB, follow the port-forwarding instructions in the [Desktop guide](https://buoy.gg/buoy/latest/docs/desktop).
+
+Select the device in Desktop, trigger a fresh HTTP request in the app, and check that it appears in Network. If no device appears, check both account states, the broker address, and network connectivity. If the device appears but the panel is empty, check the tool's installation and capture path.
+
+## Headless and release builds
+
+`<FloatingDevTools headless />` keeps the connection integration without the floating menu. It still needs account access and configured tools.
+
+Release sync is disabled by default. For an authorized internal release build with Pro, explicitly configure it:
+
+```tsx
+<FloatingDevTools
+  headless
+  externalSync={{
+    enableInRelease: true,
+    socketURL: "http://YOUR_COMPUTER_LAN_IP:42831",
+  }}
+/>;
+```
+
+Apply your app's authorization checks before mounting this integration. Enabling sync does not make development-only tools work in release builds.
+
+## Custom integrations
+
+The public exports include `useExternalSyncSocket`, `useExternalSync`, `ToolSyncAdapter`, URL helpers, sync-status subscriptions, and crash-flush helpers. An adapter supplies snapshots, subscriptions, and named actions. The bridge subscribes according to dashboard watch state and throttles updates; it also enforces device account admission.
+
+Prefer the core integration unless you are building a custom host. A direct hook integration must manage socket and device identity, account initialization, adapter lifecycle, and action authorization. Use the exported option types and [custom-tool guide](https://buoy.gg/buoy/latest/docs/custom-tools).
+
+## Desktop and MCP
+
+React Native connections require `@buoy-gg/external-sync`. Follow the [Desktop connection guide](https://buoy.gg/buoy/latest/docs/desktop), sign in to Desktop separately, and confirm the selected device. [MCP](https://buoy.gg/buoy/latest/docs/mcp) also needs a process account and Pro access.
+
+Device data can travel over your LAN to the configured broker. Account validation makes network requests. See [Telemetry](https://buoy.gg/buoy/latest/docs/telemetry) for data-flow details.

package/lib/commonjs/attachDeviceSync.js

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.attachDeviceSync = attachDeviceSync;
+var _license = require("@buoy-gg/license");
 var _logger = require("./utils/logger");
 var _crashFlush = require("./crashFlush");
 var _emitBudget = require("./emitBudget");
@@ -29,11 +30,16 @@ function attachDeviceSync({
   throttleMs = 200,
   enableLogs = false
 }) {
+  let disposed = false;
+  let brokerReady = false;
+  let accessGeneration = 0;
+  const allowed = () => !disposed && brokerReady && socket.connected && _license.LicenseManager.hasAccountAccess();
   const unsubs = new Map();
   const lastEmit = {};
   const timers = {};
   const isForThisDevice = targetDeviceId => targetDeviceId === "All" || targetDeviceId === deviceId;
   const safeEmit = (event, message) => {
+    if (!allowed()) return;
     try {
       socket.emit(event, message);
     } catch (error) {
@@ -42,10 +48,16 @@ function attachDeviceSync({
   };
   const warnedOversized = new Set();
   const sendSnapshot = toolId => {
+    if (!allowed()) return;
     const tool = getTools()[toolId];
     if (!tool) return;
     lastEmit[toolId] = Date.now();
-    const payload = tool.getSnapshot();
+    let payload;
+    try {
+      payload = tool.getSnapshot();
+    } catch {
+      return;
+    }
     const {
       over,
       approxBytes
@@ -108,6 +120,7 @@ function attachDeviceSync({
   /** The mode each currently-subscribed tool is wired for. */
   const activeModes = new Map();
   const watchTool = (toolId, mode) => {
+    if (!allowed()) return;
     const tool = getTools()[toolId];
     if (!tool) return;
     if (unsubs.has(toolId)) {
@@ -149,7 +162,7 @@ function attachDeviceSync({
     safeEmit("devtool-capabilities", message);
   };
   const handleWatch = message => {
-    if (!isForThisDevice(message.targetDeviceId)) return;
+    if (!allowed() || !isForThisDevice(message.targetDeviceId)) return;
     if (message.watching) {
       // `stream` is only trustworthy once a broker has merged every
       // dashboard's request (see DevToolWatchMessage.consolidated). Without
@@ -168,11 +181,12 @@ function attachDeviceSync({
     }
   };
   const handleRequest = message => {
-    if (!isForThisDevice(message.targetDeviceId)) return;
+    if (!allowed() || !isForThisDevice(message.targetDeviceId)) return;
     sendSnapshot(message.toolId);
   };
   const handleAction = async message => {
-    if (!isForThisDevice(message.targetDeviceId)) return;
+    if (!allowed() || !isForThisDevice(message.targetDeviceId)) return;
+    const startedAt = accessGeneration;
     const {
       requestId,
       toolId,
@@ -200,6 +214,9 @@ function attachDeviceSync({
     } catch (error) {
       result.error = error instanceof Error ? error.message : String(error);
     }
+
+    // A subsequent admission cannot authorize work from the previous session.
+    if (startedAt !== accessGeneration || !allowed()) return;
     if (result.ok) {
       const {
         over,
@@ -214,20 +231,61 @@ function attachDeviceSync({
     result.timestamp = Date.now();
     safeEmit("devtool-action-result", result);
   };
-  const handleConnect = () => {
+  const dropToolWork = () => {
+    accessGeneration += 1;
+    for (const toolId of [...unsubs.keys()]) unwatchTool(toolId);
+    watched.clear();
+    for (const timer of Object.values(timers)) clearTimeout(timer);
+    const buffered = socket;
+    if (buffered.sendBuffer) buffered.sendBuffer = buffered.sendBuffer.filter(packet => !["devtool-sync", "devtool-capabilities", "devtool-action-result", "device-license"].includes(String(packet.data?.[0])));
+  };
+  const announceAccount = () => {
+    const state = _license.LicenseManager.getState();
+    socket.emit("device-license", {
+      tier: state.tier,
+      isPro: state.isPro ? "1" : "0"
+    });
     sendCapabilities();
   };
-  if (socket.connected) sendCapabilities();
+  const handleAccess = message => {
+    brokerReady = message?.protocol === 1 && message.ready === true;
+    if (!allowed()) dropToolWork();else announceAccount();
+  };
+  const offAccount = _license.LicenseManager.subscribe(() => {
+    if (!_license.LicenseManager.hasAccountAccess()) {
+      if (socket.connected) socket.emit("device-license", {
+        tier: "locked",
+        isPro: "0"
+      });
+      dropToolWork();
+    } else if (allowed()) announceAccount();
+  });
+  const handleConnect = () => {
+    brokerReady = false;
+    socket.emit("buoy:access:request");
+  };
+  const handleDisconnect = () => {
+    brokerReady = false;
+    dropToolWork();
+  };
+  socket.on("buoy:access", handleAccess);
   for (const [toolId, mode] of watched) {
     if (getTools()[toolId]) watchTool(toolId, mode);
   }
   socket.on("connect", handleConnect);
+  socket.on("disconnect", handleDisconnect);
   socket.on("devtool-watch", handleWatch);
   socket.on("request-devtool-state", handleRequest);
   socket.on("devtool-action", handleAction);
+  if (socket.connected) handleConnect();
   return () => {
+    disposed = true;
+    offAccount();
+    socket.off("buoy:access", handleAccess);
+    dropToolWork();
     (0, _crashFlush.unregisterToolFlusher)(flushNow);
     socket.off("connect", handleConnect);
+    socket.off("disconnect", handleDisconnect);
     socket.off("devtool-watch", handleWatch);
     socket.off("request-devtool-state", handleRequest);
     socket.off("devtool-action", handleAction);

package/lib/commonjs/brokerAccess.js

@@ -0,0 +1,29 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.watchBrokerAccess = watchBrokerAccess;
+/** Wait for an account-aware broker before publishing any tool capabilities. */
+
+function watchBrokerAccess(socket, update) {
+  const lock = () => update(false);
+  const request = () => {
+    lock();
+    socket.emit("buoy:access:request");
+  };
+  const access = message => {
+    const info = message;
+    update(info?.protocol === 1 && info?.ready === true);
+  };
+  socket.on("connect", request);
+  socket.on("disconnect", lock);
+  socket.on("buoy:access", access);
+  lock();
+  if (socket.connected) request();
+  return () => {
+    socket.off("connect", request);
+    socket.off("disconnect", lock);
+    socket.off("buoy:access", access);
+  };
+}

package/lib/commonjs/useExternalSync.js

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.useExternalSync = useExternalSync;
+var _license = require("@buoy-gg/license");
 var _react = require("react");
 var _attachDeviceSync = require("./attachDeviceSync");
 /**
@@ -41,6 +42,8 @@ function useExternalSync({
   throttleMs = 200,
   enableLogs = false
 }) {
+  const account = (0, _license.useAccountAccess)();
+  const admitted = account.status === "admitted";
   const toolsRef = (0, _react.useRef)(tools);
   toolsRef.current = tools;
 
@@ -52,7 +55,10 @@ function useExternalSync({
   // object-reference change.
   const toolIdsKey = Object.keys(tools).sort().join(",");
   (0, _react.useEffect)(() => {
-    if (!socket || !deviceId || !enabled) return;
+    if (!socket || !deviceId || !enabled || !admitted) {
+      watchedRef.current.clear();
+      return;
+    }
     return (0, _attachDeviceSync.attachDeviceSync)({
       socket,
       deviceId,
@@ -63,5 +69,5 @@ function useExternalSync({
     });
     // toolIdsKey stands in for `tools` (see comment above its definition).
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [socket, deviceId, enabled, throttleMs, enableLogs, toolIdsKey]);
+  }, [socket, deviceId, enabled, admitted, throttleMs, enableLogs, toolIdsKey]);
 }

package/lib/commonjs/useExternalSyncSocket.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", {
 exports.buildHandshakeQuery = buildHandshakeQuery;
 exports.getInstanceId = getInstanceId;
 exports.useExternalSyncSocket = useExternalSyncSocket;
+var _brokerAccess = require("./brokerAccess");
 var _react = require("react");
 var _socket = require("socket.io-client");
 var _platformUtils = require("./utils/platformUtils");
@@ -22,6 +23,8 @@ const isDev = typeof __DEV__ !== "undefined" ? __DEV__ : false;
  */
 let globalSocketInstance = null;
 let currentSocketURL = "";
+let currentDeviceId = "";
+let currentPlatform = "";
 
 /**
  * Identifies a single socket INSTANCE. Sent in the handshake query and reused
@@ -52,12 +55,13 @@ function getInstanceId() {
  * runtime (see above). Pure, so the shape is unit-tested.
  */
 function buildHandshakeQuery(identity) {
+  const withoutAccountKey = values => values && Object.fromEntries(Object.entries(values).filter(([key]) => !["BUOY_LICENSE_KEY", "BUOY_KEY", "EXPO_PUBLIC_BUOY_KEY", "VITE_BUOY_KEY", "REACT_APP_BUOY_KEY", "licenseKey"].includes(key)));
   return {
     deviceName: identity.deviceName,
     deviceId: identity.persistentDeviceId,
     platform: identity.platform,
-    extraDeviceInfo: JSON.stringify(identity.extraDeviceInfo),
-    envVariables: JSON.stringify(identity.envVariables),
+    extraDeviceInfo: JSON.stringify(withoutAccountKey(identity.extraDeviceInfo)),
+    envVariables: JSON.stringify(withoutAccountKey(identity.envVariables)),
     connectionNonce: makeConnectionNonce(),
     instanceId: getInstanceId()
   };
@@ -83,7 +87,6 @@ function useExternalSyncSocket({
   const socketRef = (0, _react.useRef)(null);
   const [socket, setSocket] = (0, _react.useState)(null);
   const [isConnected, setIsConnected] = (0, _react.useState)(false);
-  const initialized = (0, _react.useRef)(false);
   // Derived once per render; stable string, so effect deps stay quiet.
   const resolvedSocketURL = socketURL ?? (0, _getDefaultSocketURL.getDefaultSocketURL)();
   // Tracks whether we've already logged a connection error for the current
@@ -126,13 +129,11 @@ function useExternalSyncSocket({
     (0, _logger.log)(`${logPrefix} Socket connection timeout`, enableLogs, "error");
   };
 
-  // Main socket initialization - runs only once
+  // Reuse the transport, but reattach listeners after every effect setup
+  // (including React Strict Mode replay and Fast Refresh).
   (0, _react.useEffect)(() => {
     if (!persistentDeviceId) return;
-    if (initialized.current) return;
-    initialized.current = true;
     const platformUrl = (0, _platformUtils.getPlatformSpecificURL)(resolvedSocketURL, platform);
-    currentSocketURL = platformUrl;
     (0, _syncStatusStore.setSyncStatus)({
       targetURL: platformUrl,
       state: "connecting",
@@ -140,6 +141,10 @@ function useExternalSyncSocket({
     });
     (0, _logger.log)(`${logPrefix} Platform: ${platform}, using URL: ${platformUrl}`, enableLogs);
     try {
+      if (globalSocketInstance && (currentSocketURL !== platformUrl || currentDeviceId !== persistentDeviceId || currentPlatform !== platform)) {
+        globalSocketInstance.disconnect();
+        globalSocketInstance = null;
+      }
       if (!globalSocketInstance) {
         (0, _logger.log)(`${logPrefix} Creating new socket instance to ${platformUrl}`, enableLogs);
         globalSocketInstance = (0, _socket.io)(platformUrl, {
@@ -157,32 +162,34 @@ function useExternalSyncSocket({
           reconnectionDelayMax: 5000,
           transports: ["websocket"]
         });
+        currentSocketURL = platformUrl;
+        currentDeviceId = persistentDeviceId;
+        currentPlatform = platform;
       } else {
         (0, _logger.log)(`${logPrefix} Reusing existing socket instance to ${platformUrl}`, enableLogs);
       }
       socketRef.current = globalSocketInstance;
-      setSocket(socketRef.current);
-      socketRef.current.on("connect_error", onConnectError);
-      socketRef.current.on("connect_timeout", onConnectTimeout);
-      if (socketRef.current.connected) {
-        setIsConnected(true);
+      const activeSocket = socketRef.current;
+      setSocket(activeSocket);
+      activeSocket.on("connect_error", onConnectError);
+      activeSocket.on("connect_timeout", onConnectTimeout);
+      setIsConnected(activeSocket.connected);
+      if (activeSocket.connected) {
         (0, _logger.log)(`${logPrefix} Socket already connected on init`, enableLogs);
       }
-      socketRef.current.on("connect", onConnect);
-      socketRef.current.on("disconnect", onDisconnect);
+      activeSocket.on("connect", onConnect);
+      activeSocket.on("disconnect", onDisconnect);
       return () => {
-        if (socketRef.current) {
-          (0, _logger.log)(`${logPrefix} Cleaning up socket event listeners`, enableLogs);
-          socketRef.current.off("connect", onConnect);
-          socketRef.current.off("disconnect", onDisconnect);
-          socketRef.current.off("connect_error", onConnectError);
-          socketRef.current.off("connect_timeout", onConnectTimeout);
-        }
+        (0, _logger.log)(`${logPrefix} Cleaning up socket event listeners`, enableLogs);
+        activeSocket.off("connect", onConnect);
+        activeSocket.off("disconnect", onDisconnect);
+        activeSocket.off("connect_error", onConnectError);
+        activeSocket.off("connect_timeout", onConnectTimeout);
       };
     } catch (error) {
       (0, _logger.log)(`${logPrefix} Failed to initialize socket: ${error}`, enableLogs, "error");
     }
-  }, [persistentDeviceId]);
+  }, [persistentDeviceId, resolvedSocketURL, platform]);
 
   // Update socket query parameters when deviceName changes
   (0, _react.useEffect)(() => {
@@ -196,43 +203,6 @@ function useExternalSyncSocket({
       };
     }
   }, [deviceName, logPrefix, persistentDeviceId, platform, enableLogs]);
-
-  // Update socket URL when socketURL changes
-  (0, _react.useEffect)(() => {
-    const platformUrl = (0, _platformUtils.getPlatformSpecificURL)(resolvedSocketURL, platform);
-    if (socketRef.current && currentSocketURL !== platformUrl && persistentDeviceId) {
-      (0, _logger.log)(`${logPrefix} Socket URL changed from ${currentSocketURL} to ${platformUrl}`, enableLogs);
-      try {
-        socketRef.current.disconnect();
-        currentSocketURL = platformUrl;
-        (0, _syncStatusStore.setSyncStatus)({
-          targetURL: platformUrl,
-          state: "connecting",
-          lastError: null
-        });
-        (0, _logger.log)(`${logPrefix} Creating new socket connection to ${platformUrl}`, enableLogs);
-        globalSocketInstance = (0, _socket.io)(platformUrl, {
-          autoConnect: true,
-          query: buildHandshakeQuery({
-            deviceName,
-            persistentDeviceId,
-            platform,
-            extraDeviceInfo,
-            envVariables
-          }),
-          reconnection: true,
-          reconnectionAttempts: Infinity,
-          reconnectionDelay: 1000,
-          reconnectionDelayMax: 5000,
-          transports: ["websocket"]
-        });
-        socketRef.current = globalSocketInstance;
-        setSocket(socketRef.current);
-      } catch (error) {
-        (0, _logger.log)(`${logPrefix} Failed to update socket connection: ${error}`, enableLogs, "error");
-      }
-    }
-  }, [resolvedSocketURL, deviceName, logPrefix, persistentDeviceId, platform, enableLogs]);
   function connect() {
     if (socketRef.current && !socketRef.current.connected) {
       (0, _logger.log)(`${logPrefix} Manually connecting to socket server`, enableLogs);
@@ -245,10 +215,27 @@ function useExternalSyncSocket({
       socketRef.current.disconnect();
     }
   }
+
+  // A connected transport is not permission to sync. Legacy desktop brokers
+  // never send this announcement, so updated SDKs withhold tools from them.
+  const [admittedSocket, setAdmittedSocket] = (0, _react.useState)(null);
+  (0, _react.useEffect)(() => {
+    if (!socket) return;
+    return (0, _brokerAccess.watchBrokerAccess)(socket, ready => {
+      setAdmittedSocket(ready ? socket : null);
+      (0, _syncStatusStore.setSyncStatus)(ready ? {
+        state: "connected",
+        lastError: null
+      } : {
+        state: "retrying",
+        lastError: "Update Buoy Desktop and sign in to enable desktop sync."
+      });
+    });
+  }, [socket]);
   return {
-    socket,
+    socket: admittedSocket === socket ? socket : null,
     connect,
     disconnect,
-    isConnected
+    isConnected: isConnected && admittedSocket === socket && socket !== null
   };
 }

package/lib/module/attachDeviceSync.js

@@ -1,5 +1,6 @@
 "use strict";
 
+import { LicenseManager } from "@buoy-gg/license";
 import { log } from "./utils/logger";
 import { registerToolFlusher, unregisterToolFlusher } from "./crashFlush";
 import { MAX_ACTION_RESULT_BYTES, MAX_SNAPSHOT_EMIT_BYTES, approxSizeOver } from "./emitBudget";
@@ -25,11 +26,16 @@ export function attachDeviceSync({
   throttleMs = 200,
   enableLogs = false
 }) {
+  let disposed = false;
+  let brokerReady = false;
+  let accessGeneration = 0;
+  const allowed = () => !disposed && brokerReady && socket.connected && LicenseManager.hasAccountAccess();
   const unsubs = new Map();
   const lastEmit = {};
   const timers = {};
   const isForThisDevice = targetDeviceId => targetDeviceId === "All" || targetDeviceId === deviceId;
   const safeEmit = (event, message) => {
+    if (!allowed()) return;
     try {
       socket.emit(event, message);
     } catch (error) {
@@ -38,10 +44,16 @@ export function attachDeviceSync({
   };
   const warnedOversized = new Set();
   const sendSnapshot = toolId => {
+    if (!allowed()) return;
     const tool = getTools()[toolId];
     if (!tool) return;
     lastEmit[toolId] = Date.now();
-    const payload = tool.getSnapshot();
+    let payload;
+    try {
+      payload = tool.getSnapshot();
+    } catch {
+      return;
+    }
     const {
       over,
       approxBytes
@@ -104,6 +116,7 @@ export function attachDeviceSync({
   /** The mode each currently-subscribed tool is wired for. */
   const activeModes = new Map();
   const watchTool = (toolId, mode) => {
+    if (!allowed()) return;
     const tool = getTools()[toolId];
     if (!tool) return;
     if (unsubs.has(toolId)) {
@@ -145,7 +158,7 @@ export function attachDeviceSync({
     safeEmit("devtool-capabilities", message);
   };
   const handleWatch = message => {
-    if (!isForThisDevice(message.targetDeviceId)) return;
+    if (!allowed() || !isForThisDevice(message.targetDeviceId)) return;
     if (message.watching) {
       // `stream` is only trustworthy once a broker has merged every
       // dashboard's request (see DevToolWatchMessage.consolidated). Without
@@ -164,11 +177,12 @@ export function attachDeviceSync({
     }
   };
   const handleRequest = message => {
-    if (!isForThisDevice(message.targetDeviceId)) return;
+    if (!allowed() || !isForThisDevice(message.targetDeviceId)) return;
     sendSnapshot(message.toolId);
   };
   const handleAction = async message => {
-    if (!isForThisDevice(message.targetDeviceId)) return;
+    if (!allowed() || !isForThisDevice(message.targetDeviceId)) return;
+    const startedAt = accessGeneration;
     const {
       requestId,
       toolId,
@@ -196,6 +210,9 @@ export function attachDeviceSync({
     } catch (error) {
       result.error = error instanceof Error ? error.message : String(error);
     }
+
+    // A subsequent admission cannot authorize work from the previous session.
+    if (startedAt !== accessGeneration || !allowed()) return;
     if (result.ok) {
       const {
         over,
@@ -210,20 +227,61 @@ export function attachDeviceSync({
     result.timestamp = Date.now();
     safeEmit("devtool-action-result", result);
   };
-  const handleConnect = () => {
+  const dropToolWork = () => {
+    accessGeneration += 1;
+    for (const toolId of [...unsubs.keys()]) unwatchTool(toolId);
+    watched.clear();
+    for (const timer of Object.values(timers)) clearTimeout(timer);
+    const buffered = socket;
+    if (buffered.sendBuffer) buffered.sendBuffer = buffered.sendBuffer.filter(packet => !["devtool-sync", "devtool-capabilities", "devtool-action-result", "device-license"].includes(String(packet.data?.[0])));
+  };
+  const announceAccount = () => {
+    const state = LicenseManager.getState();
+    socket.emit("device-license", {
+      tier: state.tier,
+      isPro: state.isPro ? "1" : "0"
+    });
     sendCapabilities();
   };
-  if (socket.connected) sendCapabilities();
+  const handleAccess = message => {
+    brokerReady = message?.protocol === 1 && message.ready === true;
+    if (!allowed()) dropToolWork();else announceAccount();
+  };
+  const offAccount = LicenseManager.subscribe(() => {
+    if (!LicenseManager.hasAccountAccess()) {
+      if (socket.connected) socket.emit("device-license", {
+        tier: "locked",
+        isPro: "0"
+      });
+      dropToolWork();
+    } else if (allowed()) announceAccount();
+  });
+  const handleConnect = () => {
+    brokerReady = false;
+    socket.emit("buoy:access:request");
+  };
+  const handleDisconnect = () => {
+    brokerReady = false;
+    dropToolWork();
+  };
+  socket.on("buoy:access", handleAccess);
   for (const [toolId, mode] of watched) {
     if (getTools()[toolId]) watchTool(toolId, mode);
   }
   socket.on("connect", handleConnect);
+  socket.on("disconnect", handleDisconnect);
   socket.on("devtool-watch", handleWatch);
   socket.on("request-devtool-state", handleRequest);
   socket.on("devtool-action", handleAction);
+  if (socket.connected) handleConnect();
   return () => {
+    disposed = true;
+    offAccount();
+    socket.off("buoy:access", handleAccess);
+    dropToolWork();
     unregisterToolFlusher(flushNow);
     socket.off("connect", handleConnect);
+    socket.off("disconnect", handleDisconnect);
     socket.off("devtool-watch", handleWatch);
     socket.off("request-devtool-state", handleRequest);
     socket.off("devtool-action", handleAction);

package/lib/module/brokerAccess.js

@@ -0,0 +1,25 @@
+"use strict";
+
+/** Wait for an account-aware broker before publishing any tool capabilities. */
+
+export function watchBrokerAccess(socket, update) {
+  const lock = () => update(false);
+  const request = () => {
+    lock();
+    socket.emit("buoy:access:request");
+  };
+  const access = message => {
+    const info = message;
+    update(info?.protocol === 1 && info?.ready === true);
+  };
+  socket.on("connect", request);
+  socket.on("disconnect", lock);
+  socket.on("buoy:access", access);
+  lock();
+  if (socket.connected) request();
+  return () => {
+    socket.off("connect", request);
+    socket.off("disconnect", lock);
+    socket.off("buoy:access", access);
+  };
+}

package/lib/module/useExternalSync.js

@@ -1,5 +1,6 @@
 "use strict";
 
+import { useAccountAccess } from "@buoy-gg/license";
 import { useEffect, useRef } from "react";
 import { attachDeviceSync } from "./attachDeviceSync";
 /**
@@ -37,6 +38,8 @@ export function useExternalSync({
   throttleMs = 200,
   enableLogs = false
 }) {
+  const account = useAccountAccess();
+  const admitted = account.status === "admitted";
   const toolsRef = useRef(tools);
   toolsRef.current = tools;
 
@@ -48,7 +51,10 @@ export function useExternalSync({
   // object-reference change.
   const toolIdsKey = Object.keys(tools).sort().join(",");
   useEffect(() => {
-    if (!socket || !deviceId || !enabled) return;
+    if (!socket || !deviceId || !enabled || !admitted) {
+      watchedRef.current.clear();
+      return;
+    }
     return attachDeviceSync({
       socket,
       deviceId,
@@ -59,5 +65,5 @@ export function useExternalSync({
     });
     // toolIdsKey stands in for `tools` (see comment above its definition).
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [socket, deviceId, enabled, throttleMs, enableLogs, toolIdsKey]);
+  }, [socket, deviceId, enabled, admitted, throttleMs, enableLogs, toolIdsKey]);
 }

package/lib/module/useExternalSyncSocket.js

@@ -1,5 +1,6 @@
 "use strict";
 
+import { watchBrokerAccess } from "./brokerAccess";
 import { useEffect, useRef, useState } from "react";
 import { io as socketIO } from "socket.io-client";
 import { getPlatformSpecificURL } from "./utils/platformUtils";
@@ -16,6 +17,8 @@ const isDev = typeof __DEV__ !== "undefined" ? __DEV__ : false;
  */
 let globalSocketInstance = null;
 let currentSocketURL = "";
+let currentDeviceId = "";
+let currentPlatform = "";
 
 /**
  * Identifies a single socket INSTANCE. Sent in the handshake query and reused
@@ -46,12 +49,13 @@ export function getInstanceId() {
  * runtime (see above). Pure, so the shape is unit-tested.
  */
 export function buildHandshakeQuery(identity) {
+  const withoutAccountKey = values => values && Object.fromEntries(Object.entries(values).filter(([key]) => !["BUOY_LICENSE_KEY", "BUOY_KEY", "EXPO_PUBLIC_BUOY_KEY", "VITE_BUOY_KEY", "REACT_APP_BUOY_KEY", "licenseKey"].includes(key)));
   return {
     deviceName: identity.deviceName,
     deviceId: identity.persistentDeviceId,
     platform: identity.platform,
-    extraDeviceInfo: JSON.stringify(identity.extraDeviceInfo),
-    envVariables: JSON.stringify(identity.envVariables),
+    extraDeviceInfo: JSON.stringify(withoutAccountKey(identity.extraDeviceInfo)),
+    envVariables: JSON.stringify(withoutAccountKey(identity.envVariables)),
     connectionNonce: makeConnectionNonce(),
     instanceId: getInstanceId()
   };
@@ -77,7 +81,6 @@ export function useExternalSyncSocket({
   const socketRef = useRef(null);
   const [socket, setSocket] = useState(null);
   const [isConnected, setIsConnected] = useState(false);
-  const initialized = useRef(false);
   // Derived once per render; stable string, so effect deps stay quiet.
   const resolvedSocketURL = socketURL ?? getDefaultSocketURL();
   // Tracks whether we've already logged a connection error for the current
@@ -120,13 +123,11 @@ export function useExternalSyncSocket({
     log(`${logPrefix} Socket connection timeout`, enableLogs, "error");
   };
 
-  // Main socket initialization - runs only once
+  // Reuse the transport, but reattach listeners after every effect setup
+  // (including React Strict Mode replay and Fast Refresh).
   useEffect(() => {
     if (!persistentDeviceId) return;
-    if (initialized.current) return;
-    initialized.current = true;
     const platformUrl = getPlatformSpecificURL(resolvedSocketURL, platform);
-    currentSocketURL = platformUrl;
     setSyncStatus({
       targetURL: platformUrl,
       state: "connecting",
@@ -134,6 +135,10 @@ export function useExternalSyncSocket({
     });
     log(`${logPrefix} Platform: ${platform}, using URL: ${platformUrl}`, enableLogs);
     try {
+      if (globalSocketInstance && (currentSocketURL !== platformUrl || currentDeviceId !== persistentDeviceId || currentPlatform !== platform)) {
+        globalSocketInstance.disconnect();
+        globalSocketInstance = null;
+      }
       if (!globalSocketInstance) {
         log(`${logPrefix} Creating new socket instance to ${platformUrl}`, enableLogs);
         globalSocketInstance = socketIO(platformUrl, {
@@ -151,32 +156,34 @@ export function useExternalSyncSocket({
           reconnectionDelayMax: 5000,
           transports: ["websocket"]
         });
+        currentSocketURL = platformUrl;
+        currentDeviceId = persistentDeviceId;
+        currentPlatform = platform;
       } else {
         log(`${logPrefix} Reusing existing socket instance to ${platformUrl}`, enableLogs);
       }
       socketRef.current = globalSocketInstance;
-      setSocket(socketRef.current);
-      socketRef.current.on("connect_error", onConnectError);
-      socketRef.current.on("connect_timeout", onConnectTimeout);
-      if (socketRef.current.connected) {
-        setIsConnected(true);
+      const activeSocket = socketRef.current;
+      setSocket(activeSocket);
+      activeSocket.on("connect_error", onConnectError);
+      activeSocket.on("connect_timeout", onConnectTimeout);
+      setIsConnected(activeSocket.connected);
+      if (activeSocket.connected) {
         log(`${logPrefix} Socket already connected on init`, enableLogs);
       }
-      socketRef.current.on("connect", onConnect);
-      socketRef.current.on("disconnect", onDisconnect);
+      activeSocket.on("connect", onConnect);
+      activeSocket.on("disconnect", onDisconnect);
       return () => {
-        if (socketRef.current) {
-          log(`${logPrefix} Cleaning up socket event listeners`, enableLogs);
-          socketRef.current.off("connect", onConnect);
-          socketRef.current.off("disconnect", onDisconnect);
-          socketRef.current.off("connect_error", onConnectError);
-          socketRef.current.off("connect_timeout", onConnectTimeout);
-        }
+        log(`${logPrefix} Cleaning up socket event listeners`, enableLogs);
+        activeSocket.off("connect", onConnect);
+        activeSocket.off("disconnect", onDisconnect);
+        activeSocket.off("connect_error", onConnectError);
+        activeSocket.off("connect_timeout", onConnectTimeout);
       };
     } catch (error) {
       log(`${logPrefix} Failed to initialize socket: ${error}`, enableLogs, "error");
     }
-  }, [persistentDeviceId]);
+  }, [persistentDeviceId, resolvedSocketURL, platform]);
 
   // Update socket query parameters when deviceName changes
   useEffect(() => {
@@ -190,43 +197,6 @@ export function useExternalSyncSocket({
       };
     }
   }, [deviceName, logPrefix, persistentDeviceId, platform, enableLogs]);
-
-  // Update socket URL when socketURL changes
-  useEffect(() => {
-    const platformUrl = getPlatformSpecificURL(resolvedSocketURL, platform);
-    if (socketRef.current && currentSocketURL !== platformUrl && persistentDeviceId) {
-      log(`${logPrefix} Socket URL changed from ${currentSocketURL} to ${platformUrl}`, enableLogs);
-      try {
-        socketRef.current.disconnect();
-        currentSocketURL = platformUrl;
-        setSyncStatus({
-          targetURL: platformUrl,
-          state: "connecting",
-          lastError: null
-        });
-        log(`${logPrefix} Creating new socket connection to ${platformUrl}`, enableLogs);
-        globalSocketInstance = socketIO(platformUrl, {
-          autoConnect: true,
-          query: buildHandshakeQuery({
-            deviceName,
-            persistentDeviceId,
-            platform,
-            extraDeviceInfo,
-            envVariables
-          }),
-          reconnection: true,
-          reconnectionAttempts: Infinity,
-          reconnectionDelay: 1000,
-          reconnectionDelayMax: 5000,
-          transports: ["websocket"]
-        });
-        socketRef.current = globalSocketInstance;
-        setSocket(socketRef.current);
-      } catch (error) {
-        log(`${logPrefix} Failed to update socket connection: ${error}`, enableLogs, "error");
-      }
-    }
-  }, [resolvedSocketURL, deviceName, logPrefix, persistentDeviceId, platform, enableLogs]);
   function connect() {
     if (socketRef.current && !socketRef.current.connected) {
       log(`${logPrefix} Manually connecting to socket server`, enableLogs);
@@ -239,10 +209,27 @@ export function useExternalSyncSocket({
       socketRef.current.disconnect();
     }
   }
+
+  // A connected transport is not permission to sync. Legacy desktop brokers
+  // never send this announcement, so updated SDKs withhold tools from them.
+  const [admittedSocket, setAdmittedSocket] = useState(null);
+  useEffect(() => {
+    if (!socket) return;
+    return watchBrokerAccess(socket, ready => {
+      setAdmittedSocket(ready ? socket : null);
+      setSyncStatus(ready ? {
+        state: "connected",
+        lastError: null
+      } : {
+        state: "retrying",
+        lastError: "Update Buoy Desktop and sign in to enable desktop sync."
+      });
+    });
+  }, [socket]);
   return {
-    socket,
+    socket: admittedSocket === socket ? socket : null,
     connect,
     disconnect,
-    isConnected
+    isConnected: isConnected && admittedSocket === socket && socket !== null
   };
 }

package/lib/typescript/attachDeviceSync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attachDeviceSync.d.ts","sourceRoot":"","sources":["../../src/attachDeviceSync.ts"],"names":[],"mappings":"AAOA,OAAO,EAQL,KAAK,eAAe,EACrB,MAAM,SAAS,CAAC;AAIjB,2DAA2D;AAC3D,MAAM,MAAM,UAAU,GAAG;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IACrD,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,KAAK,OAAO,CAAC;IACnE,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,KAAK,OAAO,CAAC;CACrE,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE7C,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAChD;;;;OAIG;IACH,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,UAAgB,EAChB,UAAkB,GACnB,EAAE,uBAAuB,GAAG,MAAM,IAAI,CAqPtC"}
+{"version":3,"file":"attachDeviceSync.d.ts","sourceRoot":"","sources":["../../src/attachDeviceSync.ts"],"names":[],"mappings":"AAQA,OAAO,EAQL,KAAK,eAAe,EACrB,MAAM,SAAS,CAAC;AAIjB,2DAA2D;AAC3D,MAAM,MAAM,UAAU,GAAG;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IACrD,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,KAAK,OAAO,CAAC;IACnE,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,KAAK,OAAO,CAAC;CACrE,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE7C,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAChD;;;;OAIG;IACH,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,UAAgB,EAChB,UAAkB,GACnB,EAAE,uBAAuB,GAAG,MAAM,IAAI,CAsStC"}

package/lib/typescript/brokerAccess.d.ts

@@ -0,0 +1,9 @@
+/** Wait for an account-aware broker before publishing any tool capabilities. */
+export interface AccessSocket {
+    connected: boolean;
+    on(event: string, callback: (...args: any[]) => void): unknown;
+    off(event: string, callback: (...args: any[]) => void): unknown;
+    emit(event: string): unknown;
+}
+export declare function watchBrokerAccess(socket: AccessSocket, update: (ready: boolean) => void): () => void;
+//# sourceMappingURL=brokerAccess.d.ts.map

package/lib/typescript/brokerAccess.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brokerAccess.d.ts","sourceRoot":"","sources":["../../src/brokerAccess.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC;IAC/D,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC;IAChE,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC9B;AACD,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAC/B,MAAM,IAAI,CAoBZ"}

package/lib/typescript/useExternalSync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useExternalSync.d.ts","sourceRoot":"","sources":["../../src/useExternalSync.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,eAAe,CAAC,EAC9B,KAAK,EACL,MAAM,EACN,QAAQ,EACR,OAAc,EACd,UAAgB,EAChB,UAAkB,GACnB,EAAE,oBAAoB,QA0BtB"}
+{"version":3,"file":"useExternalSync.d.ts","sourceRoot":"","sources":["../../src/useExternalSync.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,eAAe,CAAC,EAC9B,KAAK,EACL,MAAM,EACN,QAAQ,EACR,OAAc,EACd,UAAgB,EAChB,UAAkB,GACnB,EAAE,oBAAoB,QA4BtB"}

package/lib/typescript/useExternalSyncSocket.d.ts

@@ -31,7 +31,7 @@ export declare function buildHandshakeQuery(identity: HandshakeIdentity): Record
  * - Connection state tracking
  */
 export declare function useExternalSyncSocket({ deviceName, socketURL, persistentDeviceId, extraDeviceInfo, envVariables, platform, enableLogs, }: UseExternalSyncSocketProps): {
-    socket: Socket<import("@socket.io/component-emitter").DefaultEventsMap, import("@socket.io/component-emitter").DefaultEventsMap> | null;
+    socket: Socket | null;
     connect: () => void;
     disconnect: () => void;
     isConnected: boolean;

package/lib/typescript/useExternalSyncSocket.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useExternalSyncSocket.d.ts","sourceRoot":"","sources":["../../src/useExternalSyncSocket.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAM1D,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAC;AA0B1D;;;;;;;GAOG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAItC;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUvF;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,UAAU,EACV,SAAS,EACT,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,UAAkB,GACnB,EAAE,0BAA0B;;;;;EA0O5B"}
+{"version":3,"file":"useExternalSyncSocket.d.ts","sourceRoot":"","sources":["../../src/useExternalSyncSocket.ts"],"names":[],"mappings":"AAEA,OAAO,EAAkB,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAM1D,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAC;AA4B1D;;;;;;;GAOG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAItC;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAavF;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,UAAU,EACV,SAAS,EACT,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,UAAkB,GACnB,EAAE,0BAA0B,GAAG;IAC9B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,WAAW,EAAE,OAAO,CAAC;CACtB,CA4LA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buoy-gg/external-sync",
-  "version": "7.0.36",
+  "version": "7.0.38",
   "description": "Generic device-to-desktop sync for Buoy dev tools",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
@@ -26,7 +26,8 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "socket.io-client": "^4.8.1"
+    "socket.io-client": "^4.8.1",
+    "@buoy-gg/license": "^7.0.38"
   },
   "peerDependencies": {
     "react": "*",