honeybook-mcp 0.4.4 → 0.4.6

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "HoneyBook client-portal tools for Claude Code",
-    "version": "0.4.4"
+    "version": "0.4.6"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "HoneyBook",
       "source": "./",
       "description": "HoneyBook client-portal MCP for Claude — view wedding-vendor contracts and invoices via MCP",
-      "version": "0.4.4",
+      "version": "0.4.6",
       "author": {
         "name": "Chris Chall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "honeybook",
   "displayName": "HoneyBook",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "HoneyBook client-portal MCP for Claude — view wedding-vendor contracts and invoices via MCP",
   "author": {
     "name": "Chris Chall",

package/README.md

@@ -86,7 +86,7 @@ HoneyBook has no public client-portal API. This MCP reuses the same auth state y
 **Per-vendor activation:**
 
 1. Make sure the vendor's portal tab is open (the magic link from their email).
-2. In Claude, call `use_magic_link` with the magic-link URL — the tool asks the fetchproxy extension to snapshot the page's `localStorage["jStorage"]` and the `hb-api-fingerprint` request header, then closes the bridge. No headless browser is spawned.
+2. In Claude, call `use_magic_link` with the magic-link URL — the tool asks the fetchproxy extension to snapshot the auth fields out of the page's `localStorage["HONEYBOOK_REACT_CURR_USER"]`, then closes the bridge. The tab only has to be open and signed in; nothing is read off a live request. No headless browser is spawned.
 3. All other tools use the most-recently-activated session by default. Pass `origin` explicitly when multiple vendors are active.
 
 Sessions are stored in memory and persisted to `~/.honeybook-mcp/sessions.json` (mode 0600) so they survive MCP restarts. Re-run `use_magic_link` when a session expires.
@@ -111,7 +111,26 @@ Tools that touch a vendor accept an optional `origin` argument (e.g. `https://ac
 - **"HoneyBook auth expired"** — re-open the vendor's magic link in Chrome and re-run `use_magic_link`.
 - **"No active HoneyBook session"** — call `use_magic_link` first.
 - **"fetchproxy capture failed"** — install the [fetchproxy 0.3.0 extension](https://github.com/chrischall/fetchproxy), then open the vendor's magic link in that browser.
-- **"hb-api-fingerprint header not captured"** — refresh the portal tab so the page makes an `api.honeybook.com/api/v2/*` request, then retry.
+- **"fetchproxy capture timed out"** — the extension found no signed-in portal tab to read. Open the vendor's magic link, confirm the portal page has loaded, then retry.
+- **"no confirmed browser session"** — the extension is connected but has not approved this MCP. Open the Transporter popup and approve the pair code it shows, then retry.
+- **"localStorage keys not in declared set"** — the MCP now reads a storage key your existing pairing doesn't cover. See [Upgrading from 0.4.4 or earlier](#upgrading-from-044-or-earlier). Retrying will not help, and this is not a version problem.
+
+## Upgrading from 0.4.4 or earlier
+
+**0.4.5 requires a one-time re-approval in the browser extension.** HoneyBook moved the client-portal session out of `localStorage["jStorage"]` into `localStorage["HONEYBOOK_REACT_CURR_USER"]`, so 0.4.5 reads a different storage key. The extension approves a MCP's declared scope *at pair time*, so an existing pairing does not cover the new key and every capture is refused with:
+
+```
+localStorage keys not in declared set: HONEYBOOK_REACT_CURR_USER
+```
+
+To fix it, once:
+
+1. Open the **Transporter** extension popup.
+2. **Revoke** `honeybook-mcp`.
+3. Re-run `use_magic_link` — a fresh pair code appears.
+4. Approve it in the popup. You are approving the new scope.
+
+Nothing else changes: existing sessions in `~/.honeybook-mcp/sessions.json` keep working, and a re-capture is only needed if the session itself has expired.
 
 ## Security
 

package/dist/auth.js

@@ -1,5 +1,5 @@
 // ────────────────────────────────────────────────────────────────────────────
-// Session capture — Pattern A template (read_local_storage + capture_header)
+// Session capture — Pattern A template (read_local_storage)
 // ────────────────────────────────────────────────────────────────────────────
 //
 // Mirrors the canonical "browser-bootstrap + Node-direct" shape from
@@ -20,15 +20,23 @@
 //   2. fetchproxy bootstrap (this module).
 //      The user has signed into their vendor portal via a magic link in
 //      their real Chrome (the fetchproxy 0.3.0 extension is installed).
-//      We call `@fetchproxy/bootstrap` once to:
-//        • snapshot localStorage["jStorage"] — the HoneyBook web app
-//          stores the bearer token + user id + trusted device id + the
-//          HB_CURR_USER blob here, all under one key
-//        • capture the `hb-api-fingerprint` request header on the first
-//          api.honeybook.com/api/v2/* call the page makes — this is a
-//          per-device FingerprintJS signal that the API requires on
-//          every request (it's NOT in jStorage)
-//      Then we close the bridge and operate from Node thereafter.
+//      We call `@fetchproxy/bootstrap` once to read the auth fields out
+//      of localStorage["HONEYBOOK_REACT_CURR_USER"], then close the
+//      bridge and operate from Node thereafter.
+//
+//      HoneyBook used to keep this state in the AngularJS `jStorage`
+//      blob (HB_AUTH_TOKEN / HB_AUTH_USER_ID / HB_TRUSTED_DEVICE /
+//      HB_CURR_USER). It has since moved to the React-era
+//      `HONEYBOOK_REACT_CURR_USER` key; on a live signed-in portal
+//      jStorage is down to HB_TRUSTED_DEVICE, SESSION_COMPANY_ID,
+//      REDIRECT_URL and __jstorage_meta. We read the React key and keep
+//      the surviving jStorage trusted-device as a fallback.
+//
+//      We no longer capture the `hb-api-fingerprint` request header.
+//      The API accepts requests without it (verified against
+//      /api/v2/users/{uid}/workspace_files), and capturing it was the
+//      only part of bootstrap that had to block on a live outgoing
+//      request — the "portal tab already went idle" timeout.
 //
 //   3. Error
 //      Nothing to authenticate with. We throw a message that names the
@@ -36,14 +44,14 @@
 //      extension installed) and retry the tool call.
 //
 // Why fetchproxy is only a one-shot read:
-//   The bootstrap call snapshots both buckets (localStorage +
-//   captured header) and returns. The MCP then operates from Node with
-//   direct fetch — latency and reliability are not coupled to the
-//   browser bridge for normal tool calls. When the bearer token
-//   eventually expires, the existing 401 handler in `HoneyBookClient`
-//   surfaces a helpful "re-bootstrap" error and the user re-runs the
-//   capture (typically via the `use_magic_link` tool, which now wraps
-//   this function instead of running Puppeteer).
+//   The bootstrap call snapshots the declared storage fields and
+//   returns. The MCP then operates from Node with direct fetch — latency
+//   and reliability are not coupled to the browser bridge for normal
+//   tool calls. When the bearer token eventually expires, the
+//   expired-session handler in `HoneyBookClient` surfaces a helpful
+//   "re-bootstrap" error and the user re-runs the capture (typically via
+//   the `use_magic_link` tool, which now wraps this function instead of
+//   running Puppeteer).
 //
 // Multi-domain scope:
 //   HoneyBook serves both the main app (honeybook.com) and per-vendor
@@ -93,44 +101,54 @@ export async function captureSessionViaFetchproxy(opts) {
             // portal subdomains (*.hbportal.co). The extension matches on suffix,
             // so listing both apexes covers any vendor.
             //
-            // Both are needed:
-            //   - `hbportal.co` is where the vendor magic-link tab lives, so
-            //     `jStorage` reads target it (via `storageDomain` below).
-            //   - `honeybook.com` is required for the `hb-api-fingerprint`
-            //     capture, because that header rides outgoing requests to
-            //     `api.honeybook.com/api/v2/*` and the extension gates
-            //     every captureHeader `host` against declared domains.
+            // `hbportal.co` is where the vendor magic-link tab lives, so the
+            // storage reads target it (via `storageDomain` below).
+            // `honeybook.com` stays declared because the same session is valid
+            // on the main app and callers may hold either origin.
             //
             // 0.4.1+ requires multi-domain MCPs to pick a `storageDomain` so
             // the cookie / localStorage / sessionStorage / indexedDb reads
-            // know which tab to target. captureRequestHeader is independently
-            // routed by its declared { host, path? }.
+            // know which tab to target.
             domains: ['honeybook.com', 'hbportal.co'],
             storageDomain: 'hbportal.co',
             declare: {
                 cookies: [],
-                // We don't need the full `jStorage` blob (it's ~8KB of mostly
-                // unused state). 0.4.0's JSON-pointer extraction lets us
-                // declare exactly the four fields the MCP uses; bootstrap
-                // reads `jStorage` once and applies all pointers in one call.
-                // The extension popup also shows the pointer paths verbatim
-                // so the user can see precisely what's being read.
+                // `HONEYBOOK_REACT_CURR_USER` is ~6.5KB of mostly unused user
+                // state. 0.4.0's JSON-pointer extraction lets us declare exactly
+                // the fields the MCP uses; bootstrap reads each storage key once
+                // and applies all pointers in one call. The extension popup shows
+                // the pointer paths verbatim so the user can see precisely what's
+                // being read.
                 localStorage: [],
                 localStoragePointers: [
-                    { outputKey: 'HB_AUTH_TOKEN', storageKey: 'jStorage', jsonPointer: '/HB_AUTH_TOKEN' },
-                    { outputKey: 'HB_AUTH_USER_ID', storageKey: 'jStorage', jsonPointer: '/HB_AUTH_USER_ID' },
-                    { outputKey: 'HB_TRUSTED_DEVICE', storageKey: 'jStorage', jsonPointer: '/HB_TRUSTED_DEVICE' },
-                    { outputKey: 'HB_COMPANY_NAME', storageKey: 'jStorage', jsonPointer: '/HB_CURR_USER/company/company_name' },
+                    {
+                        outputKey: 'HB_AUTH_TOKEN',
+                        storageKey: 'HONEYBOOK_REACT_CURR_USER',
+                        jsonPointer: '/authentication_token',
+                    },
+                    { outputKey: 'HB_AUTH_USER_ID', storageKey: 'HONEYBOOK_REACT_CURR_USER', jsonPointer: '/_id' },
+                    {
+                        outputKey: 'HB_TRUSTED_DEVICE',
+                        storageKey: 'HONEYBOOK_REACT_CURR_USER',
+                        jsonPointer: '/trusted_device',
+                    },
+                    {
+                        outputKey: 'HB_COMPANY_NAME',
+                        storageKey: 'HONEYBOOK_REACT_CURR_USER',
+                        jsonPointer: '/company/company_name',
+                    },
+                    // The one field of the old jStorage blob that survived the
+                    // migration. Kept as a fallback so a further reshuffle of the
+                    // React key doesn't cost us the trusted-device value too.
+                    {
+                        outputKey: 'HB_TRUSTED_DEVICE_LEGACY',
+                        storageKey: 'jStorage',
+                        jsonPointer: '/HB_TRUSTED_DEVICE',
+                    },
                 ],
                 sessionStorage: [],
-                captureHeaders: [
-                    // The page's first call to api.honeybook.com/api/v2/* carries the
-                    // `hb-api-fingerprint` header — a per-device FingerprintJS
-                    // signal that the API requires on every subsequent request.
-                    // It's NOT stored in jStorage; the only place to get it is off
-                    // a real outgoing request.
-                    { host: 'api.honeybook.com', path: '/api/v2/*', headerName: 'hb-api-fingerprint' },
-                ],
+                // Nothing to sniff off a live request any more — see the header note above.
+                captureHeaders: [],
             },
             // 0.4.0: surface the pair code (six digits) on stderr so the user
             // can verify it against the extension popup. fetchproxy 0.4.0
@@ -139,9 +157,8 @@ export async function captureSessionViaFetchproxy(opts) {
             onPairCode: (code) => {
                 process.stderr.write(`[honeybook-mcp] fetchproxy pair code: ${code}\n`);
             },
-            // 0.4.0: capture_request_header blocks on a real outgoing request
-            // to api.honeybook.com/api/v2/*. Surface a hint so the user knows
-            // to interact with the portal if the bootstrap appears to stall.
+            // Surface the library's own progress hint so a stalled bootstrap
+            // tells the user what it is waiting on.
             onWaiting: (hint) => {
                 process.stderr.write(`[honeybook-mcp] ${hint}\n`);
             },
@@ -154,53 +171,54 @@ export async function captureSessionViaFetchproxy(opts) {
             throw new Error(`HoneyBook auth: fetchproxy bridge is down (extension service worker unreachable after retry). ${bridgeError.hint ?? ''}`.trimEnd());
         }
         const msg = e instanceof Error ? e.message : String(e);
-        // The hb-api-fingerprint capture rejects with a bare `timeout` when no
-        // api.honeybook.com/api/v2/* request fires before its one-shot listener
-        // window elapses. This is the common "tab already loaded and idle" case:
-        // a HoneyBook portal fires its API calls on load, then goes quiet, so by
-        // the time bootstrap has paired, read jStorage, and armed the capture
-        // listener there's no fresh request left to sniff the header off. The fix
-        // is to make the portal issue a *new* request (refresh the tab, open a
-        // workspace) WHILE the capture is waiting — NOT to (re)open the magic
-        // link, which is already open. classifyBridgeError keys off the error
-        // class, so the capture timeout surfaces as a FetchproxyProtocolError
+        // The extension gates on the scope approved at pair time, so widening the
+        // declaration — as the HONEYBOOK_REACT_CURR_USER migration did — is refused
+        // until the user re-approves. Every user paired before that upgrade hits
+        // this exactly once. The library types the error with a `.hint` carrying
+        // the one remedy (revoke in the popup, re-run, approve the new scope), and
+        // that remedy is already inlined in `.message`; the generic suffix below is
+        // actively wrong here, because the magic link is already open. Match on the
+        // class name rather than `instanceof` so a duplicated @fetchproxy/server
+        // copy in the dependency tree can't silently defeat the check.
+        const errName = e?.name;
+        if (errName === 'FetchproxyScopeError' || /not in declared set/i.test(msg)) {
+            throw new Error(`HoneyBook auth: ${msg}`);
+        }
+        // Now that nothing blocks on a live outgoing request, a timeout means the
+        // extension never produced the declared storage reads — i.e. there is no
+        // signed-in portal tab for it to read from. classifyBridgeError keys off
+        // the error class, so this surfaces as a FetchproxyProtocolError
         // ('protocol'), not 'timeout' — match on the message too.
         if (bridgeError.type === 'timeout' || /timeout/i.test(msg)) {
-            throw new Error('HoneyBook auth: fetchproxy capture timed out waiting for the hb-api-fingerprint header. ' +
-                'That header can only be read off a live api.honeybook.com request, and a portal tab that has ' +
-                'already finished loading sits idle. Keep the vendor magic-link URL open in Chrome (with the ' +
-                'fetchproxy extension installed), then re-run use_magic_link and — within ~30s, while it waits — ' +
-                'refresh the portal tab (or open a workspace/file) so the page issues a fresh API request.');
+            throw new Error('HoneyBook auth: fetchproxy capture timed out. The extension never returned the vendor ' +
+                "portal's stored session, which usually means no tab is open and signed in on that portal. " +
+                'Open the vendor magic-link URL in Chrome (with the fetchproxy extension installed), confirm ' +
+                'the portal page has loaded, then re-run use_magic_link.');
         }
         throw new Error(`HoneyBook auth: fetchproxy capture failed: ${msg} — ` +
             'open the vendor magic-link URL in Chrome (with the fetchproxy 0.3.0 extension installed), ' +
             'then retry.');
     }
     // 0.4.0: pointer extractions land in `session.localStorage` keyed by
-    // their declared `outputKey`. The raw `jStorage` JSON is never copied
-    // into this process — only the four specific fields we actually need.
+    // their declared `outputKey`. No raw blob is ever copied into this
+    // process — only the specific fields we actually need.
     const authToken = session.localStorage['HB_AUTH_TOKEN'];
     const userId = session.localStorage['HB_AUTH_USER_ID'];
-    const trustedDevice = session.localStorage['HB_TRUSTED_DEVICE'];
+    // Only these two are load-bearing. `hb-trusted-device` is sent when we have
+    // it but the API returns 200 without it, so a missing value must not fail
+    // the capture — requiring fields the API doesn't is what turned an upstream
+    // storage rename into a total outage.
+    const trustedDevice = session.localStorage['HB_TRUSTED_DEVICE'] || session.localStorage['HB_TRUSTED_DEVICE_LEGACY'];
     const companyNameFromHb = session.localStorage['HB_COMPANY_NAME'];
     if (!authToken) {
-        throw new Error('HoneyBook auth: HB_AUTH_TOKEN not found at jStorage./HB_AUTH_TOKEN. ' +
+        throw new Error('HoneyBook auth: no auth token at HONEYBOOK_REACT_CURR_USER./authentication_token. ' +
             'Sign into the vendor portal via the magic-link URL and retry.');
     }
     if (!userId) {
-        throw new Error('HoneyBook auth: HB_AUTH_USER_ID not found at jStorage./HB_AUTH_USER_ID.');
-    }
-    if (!trustedDevice) {
-        throw new Error('HoneyBook auth: HB_TRUSTED_DEVICE not found at jStorage./HB_TRUSTED_DEVICE.');
-    }
-    const fingerprint = session.capturedHeaders['hb-api-fingerprint'];
-    if (!fingerprint) {
-        throw new Error('HoneyBook auth: hb-api-fingerprint header not captured. ' +
-            'Interact with the vendor portal (refresh the page, open a workspace) so the browser makes an ' +
-            'api.honeybook.com/api/v2/* request, then retry.');
+        throw new Error('HoneyBook auth: no user id at HONEYBOOK_REACT_CURR_USER./_id.');
     }
-    // HB_CURR_USER may not be populated immediately on a fresh tab; fall
-    // back to the portal subdomain so the user has a readable label.
+    // `company` is null on a client-side portal user, so this pointer usually
+    // resolves to nothing; fall back to the portal subdomain for a readable label.
     let companyName = companyNameFromHb || '';
     if (!companyName) {
         try {
@@ -215,8 +233,7 @@ export async function captureSessionViaFetchproxy(opts) {
         companyName,
         authToken,
         userId,
-        trustedDevice,
-        fingerprint,
+        ...(trustedDevice ? { trustedDevice } : {}),
         capturedAt: Date.now(),
     };
     sessionStore.add(captured);

package/dist/bundle.js

@@ -35026,23 +35026,19 @@ var HoneyBookClient = class {
       accept: "application/json, text/plain, */*",
       "hb-api-auth-token": this.scope.authToken,
       "hb-api-user-id": this.scope.userId,
-      "hb-trusted-device": this.scope.trustedDevice,
       "hb-api-client-version": String(this.apiVersion),
-      "hb-api-fingerprint": this.scope.fingerprint,
       "hb-api-duplicate-calls-prevention-uuid": crypto.randomUUID(),
       "hb-admin-login": "false"
     };
+    if (this.scope.trustedDevice) headers["hb-trusted-device"] = this.scope.trustedDevice;
+    if (this.scope.fingerprint) headers["hb-api-fingerprint"] = this.scope.fingerprint;
     if (body !== void 0) headers["content-type"] = "application/json";
     const response = await fetch(`${API_BASE}${path}`, {
       method,
       headers,
       ...body !== void 0 ? { body: JSON.stringify(body) } : {}
     });
-    if (response.status === 401) {
-      throw new Error(
-        `HoneyBook auth expired for portal "${this.scope.companyName}" (${this.scope.portalOrigin}). Use the \`use_magic_link\` tool to capture a fresh session.`
-      );
-    }
+    if (response.status === 401) throw this.authExpiredError();
     if (response.status === 429) {
       if (!isRateRetry) {
         await new Promise((r) => setTimeout(r, 2e3));
@@ -35052,6 +35048,9 @@ var HoneyBookClient = class {
     }
     if (!response.ok) {
       const text2 = await response.text();
+      if (response.status === 404 && text2.includes("HBUnauthorizedError")) {
+        throw this.authExpiredError();
+      }
       if (text2.includes("HBWrongAPIVersionError") && !isVersionRetry) {
         try {
           const parsed = JSON.parse(text2);
@@ -35068,6 +35067,12 @@ var HoneyBookClient = class {
     const text = await response.text();
     return text ? JSON.parse(text) : null;
   }
+  /** The one "your session died, re-capture it" error, raised from both auth paths. */
+  authExpiredError() {
+    return new Error(
+      `HoneyBook auth expired for portal "${this.scope.companyName}" (${this.scope.portalOrigin}). Use the \`use_magic_link\` tool to capture a fresh session.`
+    );
+  }
 };
 function clearClientCache() {
   clientCache.clear();
@@ -39196,7 +39201,7 @@ function bridgeErrorInfo(err) {
 // package.json
 var package_default = {
   name: "honeybook-mcp",
-  version: "0.4.4",
+  version: "0.4.6",
   mcpName: "io.github.chrischall/honeybook-mcp",
   description: "HoneyBook client-portal MCP server for Claude",
   author: "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -39272,44 +39277,54 @@ async function captureSessionViaFetchproxy(opts) {
       // portal subdomains (*.hbportal.co). The extension matches on suffix,
       // so listing both apexes covers any vendor.
       //
-      // Both are needed:
-      //   - `hbportal.co` is where the vendor magic-link tab lives, so
-      //     `jStorage` reads target it (via `storageDomain` below).
-      //   - `honeybook.com` is required for the `hb-api-fingerprint`
-      //     capture, because that header rides outgoing requests to
-      //     `api.honeybook.com/api/v2/*` and the extension gates
-      //     every captureHeader `host` against declared domains.
+      // `hbportal.co` is where the vendor magic-link tab lives, so the
+      // storage reads target it (via `storageDomain` below).
+      // `honeybook.com` stays declared because the same session is valid
+      // on the main app and callers may hold either origin.
       //
       // 0.4.1+ requires multi-domain MCPs to pick a `storageDomain` so
       // the cookie / localStorage / sessionStorage / indexedDb reads
-      // know which tab to target. captureRequestHeader is independently
-      // routed by its declared { host, path? }.
+      // know which tab to target.
       domains: ["honeybook.com", "hbportal.co"],
       storageDomain: "hbportal.co",
       declare: {
         cookies: [],
-        // We don't need the full `jStorage` blob (it's ~8KB of mostly
-        // unused state). 0.4.0's JSON-pointer extraction lets us
-        // declare exactly the four fields the MCP uses; bootstrap
-        // reads `jStorage` once and applies all pointers in one call.
-        // The extension popup also shows the pointer paths verbatim
-        // so the user can see precisely what's being read.
+        // `HONEYBOOK_REACT_CURR_USER` is ~6.5KB of mostly unused user
+        // state. 0.4.0's JSON-pointer extraction lets us declare exactly
+        // the fields the MCP uses; bootstrap reads each storage key once
+        // and applies all pointers in one call. The extension popup shows
+        // the pointer paths verbatim so the user can see precisely what's
+        // being read.
         localStorage: [],
         localStoragePointers: [
-          { outputKey: "HB_AUTH_TOKEN", storageKey: "jStorage", jsonPointer: "/HB_AUTH_TOKEN" },
-          { outputKey: "HB_AUTH_USER_ID", storageKey: "jStorage", jsonPointer: "/HB_AUTH_USER_ID" },
-          { outputKey: "HB_TRUSTED_DEVICE", storageKey: "jStorage", jsonPointer: "/HB_TRUSTED_DEVICE" },
-          { outputKey: "HB_COMPANY_NAME", storageKey: "jStorage", jsonPointer: "/HB_CURR_USER/company/company_name" }
+          {
+            outputKey: "HB_AUTH_TOKEN",
+            storageKey: "HONEYBOOK_REACT_CURR_USER",
+            jsonPointer: "/authentication_token"
+          },
+          { outputKey: "HB_AUTH_USER_ID", storageKey: "HONEYBOOK_REACT_CURR_USER", jsonPointer: "/_id" },
+          {
+            outputKey: "HB_TRUSTED_DEVICE",
+            storageKey: "HONEYBOOK_REACT_CURR_USER",
+            jsonPointer: "/trusted_device"
+          },
+          {
+            outputKey: "HB_COMPANY_NAME",
+            storageKey: "HONEYBOOK_REACT_CURR_USER",
+            jsonPointer: "/company/company_name"
+          },
+          // The one field of the old jStorage blob that survived the
+          // migration. Kept as a fallback so a further reshuffle of the
+          // React key doesn't cost us the trusted-device value too.
+          {
+            outputKey: "HB_TRUSTED_DEVICE_LEGACY",
+            storageKey: "jStorage",
+            jsonPointer: "/HB_TRUSTED_DEVICE"
+          }
         ],
         sessionStorage: [],
-        captureHeaders: [
-          // The page's first call to api.honeybook.com/api/v2/* carries the
-          // `hb-api-fingerprint` header — a per-device FingerprintJS
-          // signal that the API requires on every subsequent request.
-          // It's NOT stored in jStorage; the only place to get it is off
-          // a real outgoing request.
-          { host: "api.honeybook.com", path: "/api/v2/*", headerName: "hb-api-fingerprint" }
-        ]
+        // Nothing to sniff off a live request any more — see the header note above.
+        captureHeaders: []
       },
       // 0.4.0: surface the pair code (six digits) on stderr so the user
       // can verify it against the extension popup. fetchproxy 0.4.0
@@ -39319,9 +39334,8 @@ async function captureSessionViaFetchproxy(opts) {
         process.stderr.write(`[honeybook-mcp] fetchproxy pair code: ${code}
 `);
       },
-      // 0.4.0: capture_request_header blocks on a real outgoing request
-      // to api.honeybook.com/api/v2/*. Surface a hint so the user knows
-      // to interact with the portal if the bootstrap appears to stall.
+      // Surface the library's own progress hint so a stalled bootstrap
+      // tells the user what it is waiting on.
       onWaiting: (hint) => {
         process.stderr.write(`[honeybook-mcp] ${hint}
 `);
@@ -39335,9 +39349,13 @@ async function captureSessionViaFetchproxy(opts) {
       );
     }
     const msg = e instanceof Error ? e.message : String(e);
+    const errName = e?.name;
+    if (errName === "FetchproxyScopeError" || /not in declared set/i.test(msg)) {
+      throw new Error(`HoneyBook auth: ${msg}`);
+    }
     if (bridgeError.type === "timeout" || /timeout/i.test(msg)) {
       throw new Error(
-        "HoneyBook auth: fetchproxy capture timed out waiting for the hb-api-fingerprint header. That header can only be read off a live api.honeybook.com request, and a portal tab that has already finished loading sits idle. Keep the vendor magic-link URL open in Chrome (with the fetchproxy extension installed), then re-run use_magic_link and \u2014 within ~30s, while it waits \u2014 refresh the portal tab (or open a workspace/file) so the page issues a fresh API request."
+        "HoneyBook auth: fetchproxy capture timed out. The extension never returned the vendor portal's stored session, which usually means no tab is open and signed in on that portal. Open the vendor magic-link URL in Chrome (with the fetchproxy extension installed), confirm the portal page has loaded, then re-run use_magic_link."
       );
     }
     throw new Error(
@@ -39346,24 +39364,15 @@ async function captureSessionViaFetchproxy(opts) {
   }
   const authToken = session.localStorage["HB_AUTH_TOKEN"];
   const userId = session.localStorage["HB_AUTH_USER_ID"];
-  const trustedDevice = session.localStorage["HB_TRUSTED_DEVICE"];
+  const trustedDevice = session.localStorage["HB_TRUSTED_DEVICE"] || session.localStorage["HB_TRUSTED_DEVICE_LEGACY"];
   const companyNameFromHb = session.localStorage["HB_COMPANY_NAME"];
   if (!authToken) {
     throw new Error(
-      "HoneyBook auth: HB_AUTH_TOKEN not found at jStorage./HB_AUTH_TOKEN. Sign into the vendor portal via the magic-link URL and retry."
+      "HoneyBook auth: no auth token at HONEYBOOK_REACT_CURR_USER./authentication_token. Sign into the vendor portal via the magic-link URL and retry."
     );
   }
   if (!userId) {
-    throw new Error("HoneyBook auth: HB_AUTH_USER_ID not found at jStorage./HB_AUTH_USER_ID.");
-  }
-  if (!trustedDevice) {
-    throw new Error("HoneyBook auth: HB_TRUSTED_DEVICE not found at jStorage./HB_TRUSTED_DEVICE.");
-  }
-  const fingerprint = session.capturedHeaders["hb-api-fingerprint"];
-  if (!fingerprint) {
-    throw new Error(
-      "HoneyBook auth: hb-api-fingerprint header not captured. Interact with the vendor portal (refresh the page, open a workspace) so the browser makes an api.honeybook.com/api/v2/* request, then retry."
-    );
+    throw new Error("HoneyBook auth: no user id at HONEYBOOK_REACT_CURR_USER./_id.");
   }
   let companyName = companyNameFromHb || "";
   if (!companyName) {
@@ -39378,8 +39387,7 @@ async function captureSessionViaFetchproxy(opts) {
     companyName,
     authToken,
     userId,
-    trustedDevice,
-    fingerprint,
+    ...trustedDevice ? { trustedDevice } : {},
     capturedAt: Date.now()
   };
   sessionStore.add(captured);
@@ -39410,7 +39418,7 @@ function registerSessionTools(server) {
   server.registerTool(
     "use_magic_link",
     {
-      description: `Capture a HoneyBook client-portal session via the fetchproxy 0.3.0 browser extension. Prerequisites: install the fetchproxy extension in Chrome/Safari, then open the vendor's magic-link URL in that browser so you're signed into their portal. This tool then snapshots the page's localStorage["jStorage"] and the hb-api-fingerprint header into ~/.honeybook-mcp/sessions.json. IMPORTANT: the hb-api-fingerprint header is sniffed off the next live api.honeybook.com request, so a portal tab that has already finished loading (and gone idle) yields nothing and the capture times out. While this tool is running, refresh the portal tab (or open a workspace/file) so the page issues a fresh API request. All other tools use the most-recently-activated session by default. The magic_link_url arg is used only to derive the portalOrigin (cache key) \u2014 the tool does NOT open or navigate to it.`,
+      description: `Capture a HoneyBook client-portal session via the fetchproxy 0.3.0 browser extension. Prerequisites: install the fetchproxy extension in Chrome/Safari, then open the vendor's magic-link URL in that browser so you're signed into their portal and leave that tab open. This tool then snapshots the auth fields out of the page's localStorage["HONEYBOOK_REACT_CURR_USER"] into ~/.honeybook-mcp/sessions.json. The tab only needs to be open and signed in \u2014 nothing is sniffed off a live request, so it does not matter whether the page is idle. All other tools use the most-recently-activated session by default. The magic_link_url arg is used only to derive the portalOrigin (cache key) \u2014 the tool does NOT open or navigate to it.`,
       inputSchema: {
         magic_link_url: external_exports.string().url().describe(
           "Full magic-link URL from the vendor's HoneyBook email, e.g. https://<vendor>.hbportal.co/app/workspace_file/<id>/...  Used only to derive the portal origin; you must already have this URL open in a Chrome tab with the fetchproxy extension installed."
@@ -39833,7 +39841,7 @@ var __dirname = dirname2(fileURLToPath(import.meta.url));
 await loadDotenvSafely({ path: join4(__dirname, "..", ".env"), override: false });
 await runMcp({
   name: "honeybook-mcp",
-  version: "0.4.4",
+  version: "0.4.6",
   // x-release-please-version
   tools: [
     registerSessionTools,

package/dist/client.js

@@ -23,16 +23,23 @@ export class HoneyBookClient {
         this.apiVersion = apiVersion;
     }
     async request(method, path, body, isVersionRetry = false, isRateRetry = false) {
+        // Only the auth token, user id and a current client version are
+        // load-bearing. `hb-trusted-device` and `hb-api-fingerprint` are sent
+        // when the session has them — sessions captured by <=0.4.4 carry a
+        // fingerprint — but the API answers 200 without either, so they are
+        // omitted rather than serialized as the string "undefined".
         const headers = {
             accept: 'application/json, text/plain, */*',
             'hb-api-auth-token': this.scope.authToken,
             'hb-api-user-id': this.scope.userId,
-            'hb-trusted-device': this.scope.trustedDevice,
             'hb-api-client-version': String(this.apiVersion),
-            'hb-api-fingerprint': this.scope.fingerprint,
             'hb-api-duplicate-calls-prevention-uuid': crypto.randomUUID(),
             'hb-admin-login': 'false',
         };
+        if (this.scope.trustedDevice)
+            headers['hb-trusted-device'] = this.scope.trustedDevice;
+        if (this.scope.fingerprint)
+            headers['hb-api-fingerprint'] = this.scope.fingerprint;
         if (body !== undefined)
             headers['content-type'] = 'application/json';
         const response = await fetch(`${API_BASE}${path}`, {
@@ -40,10 +47,8 @@ export class HoneyBookClient {
             headers,
             ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
         });
-        if (response.status === 401) {
-            throw new Error(`HoneyBook auth expired for portal "${this.scope.companyName}" (${this.scope.portalOrigin}). ` +
-                `Use the \`use_magic_link\` tool to capture a fresh session.`);
-        }
+        if (response.status === 401)
+            throw this.authExpiredError();
         if (response.status === 429) {
             if (!isRateRetry) {
                 await new Promise((r) => setTimeout(r, 2000));
@@ -53,6 +58,14 @@ export class HoneyBookClient {
         }
         if (!response.ok) {
             const text = await response.text();
+            // A revoked or stale token does NOT come back as 401 — the API answers
+            // 404 with an HBUnauthorizedError body. Without this, an expired session
+            // surfaced as an opaque "HoneyBook error 404" instead of the re-capture
+            // instruction. Gate on the body so a genuinely missing resource stays a
+            // plain 404.
+            if (response.status === 404 && text.includes('HBUnauthorizedError')) {
+                throw this.authExpiredError();
+            }
             if (text.includes('HBWrongAPIVersionError') && !isVersionRetry) {
                 try {
                     const parsed = JSON.parse(text);
@@ -70,6 +83,11 @@ export class HoneyBookClient {
         const text = await response.text();
         return (text ? JSON.parse(text) : null);
     }
+    /** The one "your session died, re-capture it" error, raised from both auth paths. */
+    authExpiredError() {
+        return new Error(`HoneyBook auth expired for portal "${this.scope.companyName}" (${this.scope.portalOrigin}). ` +
+            `Use the \`use_magic_link\` tool to capture a fresh session.`);
+    }
 }
 export function clearClientCache() {
     clientCache.clear();

package/dist/index.js

@@ -11,7 +11,7 @@ import { registerContractTools } from './tools/contracts.js';
 import { registerInvoiceTools } from './tools/invoices.js';
 await runMcp({
     name: 'honeybook-mcp',
-    version: '0.4.4', // x-release-please-version
+    version: '0.4.6', // x-release-please-version
     tools: [
         registerSessionTools,
         registerWorkspaceFileTools,

package/dist/tools/sessions.js

@@ -10,10 +10,10 @@ import { captureSessionViaFetchproxy } from '../auth.js';
  * v3 behavior: the tool no longer drives Puppeteer. Instead, the user is
  * expected to have already opened the magic link in their real Chrome
  * (with the fetchproxy 0.3.0 extension installed). This tool then asks
- * the extension to snapshot the page's `localStorage["jStorage"]` and the
- * `hb-api-fingerprint` header off the first api.honeybook.com request,
- * via `@fetchproxy/bootstrap`. The result is persisted to
- * `~/.honeybook-mcp/sessions.json` and used by every other tool.
+ * the extension to snapshot the auth fields out of the page's
+ * `localStorage["HONEYBOOK_REACT_CURR_USER"]` via `@fetchproxy/bootstrap`.
+ * The result is persisted to `~/.honeybook-mcp/sessions.json` and used by
+ * every other tool.
  *
  * The `magic_link_url` arg is used only to derive the portalOrigin (the
  * cache key); we do NOT navigate to it. If the user hasn't actually
@@ -23,7 +23,7 @@ import { captureSessionViaFetchproxy } from '../auth.js';
 export async function useMagicLink(args) {
     const portalOrigin = normalizeOrigin(args.magic_link_url);
     const session = await captureSessionViaFetchproxy({ portalOrigin });
-    // Clear client cache so getActiveClient picks up the fresh fingerprint.
+    // Clear client cache so getActiveClient rebuilds against the fresh token.
     clearClientCache();
     return textResult({
         ok: true,
@@ -42,7 +42,7 @@ export async function listActiveSessions() {
 }
 export function registerSessionTools(server) {
     server.registerTool('use_magic_link', {
-        description: "Capture a HoneyBook client-portal session via the fetchproxy 0.3.0 browser extension. Prerequisites: install the fetchproxy extension in Chrome/Safari, then open the vendor's magic-link URL in that browser so you're signed into their portal. This tool then snapshots the page's localStorage[\"jStorage\"] and the hb-api-fingerprint header into ~/.honeybook-mcp/sessions.json. IMPORTANT: the hb-api-fingerprint header is sniffed off the next live api.honeybook.com request, so a portal tab that has already finished loading (and gone idle) yields nothing and the capture times out. While this tool is running, refresh the portal tab (or open a workspace/file) so the page issues a fresh API request. All other tools use the most-recently-activated session by default. The magic_link_url arg is used only to derive the portalOrigin (cache key) — the tool does NOT open or navigate to it.",
+        description: "Capture a HoneyBook client-portal session via the fetchproxy 0.3.0 browser extension. Prerequisites: install the fetchproxy extension in Chrome/Safari, then open the vendor's magic-link URL in that browser so you're signed into their portal and leave that tab open. This tool then snapshots the auth fields out of the page's localStorage[\"HONEYBOOK_REACT_CURR_USER\"] into ~/.honeybook-mcp/sessions.json. The tab only needs to be open and signed in — nothing is sniffed off a live request, so it does not matter whether the page is idle. All other tools use the most-recently-activated session by default. The magic_link_url arg is used only to derive the portalOrigin (cache key) — the tool does NOT open or navigate to it.",
         inputSchema: {
             magic_link_url: z
                 .string()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "honeybook-mcp",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "mcpName": "io.github.chrischall/honeybook-mcp",
   "description": "HoneyBook client-portal MCP server for Claude",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/honeybook-mcp",
     "source": "github"
   },
-  "version": "0.4.4",
+  "version": "0.4.6",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "honeybook-mcp",
-      "version": "0.4.4",
+      "version": "0.4.6",
       "transport": {
         "type": "stdio"
       },

package/skills/honeybook-fpx/SKILL.md

@@ -14,9 +14,10 @@ description: >-
 HoneyBook has **no server-side login** a script can drive — a client never
 gets a password, only a magic-link email per vendor. The credential is
 whatever the signed-in `*.hbportal.co` portal tab already holds: a bearer
-token + user id + device id in `localStorage["jStorage"]`, plus a per-device
-`hb-api-fingerprint` request header that only appears on a live outgoing
-`api.honeybook.com/api/v2/*` call (it's FingerprintJS, not stored anywhere).
+token + user id in `localStorage["HONEYBOOK_REACT_CURR_USER"]`. (HoneyBook
+used to keep these in the AngularJS `localStorage["jStorage"]` blob as
+`HB_AUTH_TOKEN`/`HB_AUTH_USER_ID`; that blob is now down to
+`HB_TRUSTED_DEVICE`, `SESSION_COMPANY_ID` and routing state.)
 There's no bot wall on the API itself once you have those — `honeybook-mcp`'s
 own `client.ts` proves plain Node `fetch` works fine against
 `api.honeybook.com`. So this skill is **hybrid**: `fpx` captures the session
@@ -30,9 +31,8 @@ same retry rules.
 
 Two apexes are declared on one profile:
 - `hbportal.co` — the vendor's branded portal (e.g. `acme.hbportal.co`),
-  where `jStorage` lives.
-- `honeybook.com` — required so the extension is allowed to capture the
-  `hb-api-fingerprint` header off requests to `api.honeybook.com`.
+  where the stored session lives.
+- `honeybook.com` — the main app, where the same session is also valid.
 
 ## One-time setup
 
@@ -40,8 +40,8 @@ Two apexes are declared on one profile:
 npm install -g @fetchproxy/cli   # provides `fpx`
 fpx profile add honeybook --domain honeybook.com --domain hbportal.co
 fpx profile declare honeybook \
-  --local-storage jStorage \
-  --capture-header 'hb-api-fingerprint@api.honeybook.com/api/v2/*'
+  --local-storage HONEYBOOK_REACT_CURR_USER \
+  --local-storage jStorage
 fpx pair -p honeybook            # prints a pair code → approve in Transporter
 ```
 
@@ -60,26 +60,24 @@ after the first approval every later `fpx` call reuses it.
 fpx session -p honeybook --storage-domain hbportal.co > /tmp/hb-session.json
 ```
 
-**The fingerprint capture needs a FRESH request, not a loaded page.** A
-portal tab that finished loading and went idle has no outgoing
-`api.honeybook.com/api/v2/*` call left to sniff, so the capture times out.
-While `fpx session` is waiting (~30s window), refresh the portal tab or open
-a workspace/file so the page issues a new API call.
+The tab only has to be **open and signed in**. Nothing is sniffed off a live
+request, so it does not matter whether the page has gone idle.
 
-3. Extract the fields `client.ts` needs (`jStorage` is one raw localStorage
-   value packing several keys as JSON — parse it with `fromjson`):
+3. Extract the fields `client.ts` needs (each localStorage value is one raw
+   JSON string — parse it with `fromjson`):
 
 ```sh
-AUTH_TOKEN=$(jq -r '.localStorage.jStorage | fromjson | .HB_AUTH_TOKEN' /tmp/hb-session.json)
-USER_ID=$(jq -r '.localStorage.jStorage | fromjson | .HB_AUTH_USER_ID' /tmp/hb-session.json)
-TRUSTED_DEVICE=$(jq -r '.localStorage.jStorage | fromjson | .HB_TRUSTED_DEVICE' /tmp/hb-session.json)
-FINGERPRINT=$(jq -r '.capturedHeaders["hb-api-fingerprint"]' /tmp/hb-session.json)
+AUTH_TOKEN=$(jq -r '.localStorage.HONEYBOOK_REACT_CURR_USER | fromjson | .authentication_token' /tmp/hb-session.json)
+USER_ID=$(jq -r '.localStorage.HONEYBOOK_REACT_CURR_USER | fromjson | ._id' /tmp/hb-session.json)
+# Optional — the API returns 200 without it. The React blob and jStorage hold
+# DIFFERENT values; either is accepted. `// empty` keeps an absent field from
+# becoming the literal string "null".
+TRUSTED_DEVICE=$(jq -r '.localStorage.jStorage | fromjson | .HB_TRUSTED_DEVICE // empty' /tmp/hb-session.json)
 PORTAL_ORIGIN='https://<vendor>.hbportal.co'   # the magic-link URL's origin
 ```
 
-If any of `AUTH_TOKEN`/`USER_ID`/`TRUSTED_DEVICE`/`FINGERPRINT` come back
-empty/`null`, the capture didn't see what it needed — re-open the magic link
-(or interact with the tab) and re-run step 2.
+If `AUTH_TOKEN` or `USER_ID` comes back empty/`null`, the capture didn't see
+what it needed — re-open the magic link and re-run step 2.
 
 With more than one vendor tab open at once, disambiguate with
 `--storage-subdomain <vendor>` (e.g. `--storage-subdomain acme`).
@@ -94,17 +92,19 @@ API_VERSION=$(curl -s 'https://api.honeybook.com/api/gon?callback=parseGon' \
 
 ## Core call pattern
 
-Every real request carries the same eight headers
-(`client.ts`'s `HoneyBookClient.request`):
+Every real request carries the same headers
+(`client.ts`'s `HoneyBookClient.request`). Only `hb-api-auth-token`,
+`hb-api-user-id` and a current `hb-api-client-version` are load-bearing —
+`hb-trusted-device` is optional and `hb-api-fingerprint` is no longer
+required at all:
 
 ```sh
 curl -s "https://api.honeybook.com/api/v2/users/$USER_ID/workspace_files" \
   -H 'accept: application/json, text/plain, */*' \
   -H "hb-api-auth-token: $AUTH_TOKEN" \
   -H "hb-api-user-id: $USER_ID" \
-  -H "hb-trusted-device: $TRUSTED_DEVICE" \
+  ${TRUSTED_DEVICE:+-H "hb-trusted-device: $TRUSTED_DEVICE"} \
   -H "hb-api-client-version: $API_VERSION" \
-  -H "hb-api-fingerprint: $FINGERPRINT" \
   -H "hb-api-duplicate-calls-prevention-uuid: $(uuidgen)" \
   -H 'hb-admin-login: false' \
   | jq '.data'
@@ -120,7 +120,9 @@ Ready-to-run commands for all four read endpoints are in
 
 ## The rules that matter
 
-- **401 → session expired.** Re-run the capture (magic link tab must still
+- **401, or 404 with an `HBUnauthorizedError` body → session expired.** A
+  revoked token does not reliably come back as 401, so check the body type
+  before concluding a resource is missing. Re-run the capture (magic link tab must still
   be open and signed in).
 - **429 → rate limited.** `client.ts` waits 2s and retries once; do the same
   before giving up.
@@ -146,7 +148,7 @@ Ready-to-run commands for all four read endpoints are in
 
 ## Notes
 
-- Session data (`AUTH_TOKEN`, `TRUSTED_DEVICE`, `FINGERPRINT`) is opaque and
+- Session data (`AUTH_TOKEN`, `TRUSTED_DEVICE`) is opaque and
   long-lived server-side (no client-visible JWT expiry) — keep it in shell
   variables, not a world-readable file, if you must persist it at all.
 - This project is developed and maintained by AI (Claude).

package/skills/honeybook-fpx/references/requests.md

@@ -2,10 +2,10 @@
 
 Ready-to-run commands for the four live read endpoints `honeybook-mcp`
 actually calls (from `src/tools/*.ts` + `src/client.ts`). All are
-`GET api.honeybook.com/api/v2/*`, carrying the eight headers built in
+`GET api.honeybook.com/api/v2/*`, carrying the same headers built in
 `HoneyBookClient.request` — see `../SKILL.md` for how to capture
-`$AUTH_TOKEN`/`$USER_ID`/`$TRUSTED_DEVICE`/`$FINGERPRINT`/`$API_VERSION`
-first.
+`$AUTH_TOKEN`/`$USER_ID`/`$API_VERSION` first. `$TRUSTED_DEVICE` is
+optional and `hb-api-fingerprint` is not required at all.
 
 ```sh
 hb_get() {   # $1 = path (e.g. /api/v2/users/$USER_ID/workspace_files)
@@ -13,9 +13,8 @@ hb_get() {   # $1 = path (e.g. /api/v2/users/$USER_ID/workspace_files)
     -H 'accept: application/json, text/plain, */*' \
     -H "hb-api-auth-token: $AUTH_TOKEN" \
     -H "hb-api-user-id: $USER_ID" \
-    -H "hb-trusted-device: $TRUSTED_DEVICE" \
+    ${TRUSTED_DEVICE:+-H "hb-trusted-device: $TRUSTED_DEVICE"} \
     -H "hb-api-client-version: $API_VERSION" \
-    -H "hb-api-fingerprint: $FINGERPRINT" \
     -H "hb-api-duplicate-calls-prevention-uuid: $(uuidgen)" \
     -H 'hb-admin-login: false'
 }
@@ -113,7 +112,9 @@ vendor — not an error.
 # Wrong API version — re-derive it from the error body itself (no /api/gon round-trip needed)
 jq -r 'select(type=="object") | .error_data.server_api_version // empty' /tmp/hb-resp.json
 
-# HTTP status: 401 = session expired (re-capture), 429 = rate limited (wait 2s, retry once)
+# HTTP status: 401 = session expired (re-capture), 429 = rate limited (wait 2s, retry once).
+# A 404 whose body names HBUnauthorizedError is ALSO an expired session, not a
+# missing resource — a revoked token does not reliably come back as 401.
 ```
 
 A non-2xx HTTP status with a body matching `HBWrongAPIVersionError` means