nostr-bray 3.4.2 → 3.4.3

package/dist/bunker-context.d.ts

@@ -16,6 +16,24 @@ import { BunkerSigner } from 'nostr-tools/nip46';
 import { SimplePool } from 'nostr-tools/pool';
 import type { PublicIdentity, SignFn } from './types.js';
 import type { SigningContext } from './signing-context.js';
+/** Bound the NIP-46 connect handshake. nostr-tools' BunkerSigner has no
+ *  per-request timeout, so an offline signer or unreachable relays make the
+ *  connect hang forever. A hardware signer (e.g. Heartwood) may also wait on
+ *  a physical button press -- roughly a 30-second window -- so this must sit
+ *  comfortably above that, not at or under it. */
+export declare const CONNECT_TIMEOUT_MS = 60000;
+/** Bound individual signer round-trips (sign_event, get_public_key, nip44).
+ *  Same button-press headroom as {@link CONNECT_TIMEOUT_MS}. */
+export declare const REQUEST_TIMEOUT_MS = 60000;
+/**
+ * Thrown by {@link withTimeout} when the wrapped promise does not settle in
+ * time. A distinct class (rather than a plain `Error`) lets callers tell a
+ * timeout apart from a genuine rejection -- e.g. `HeartwoodContext.probe()`
+ * treats a timed-out request differently from a denied one.
+ */
+export declare class TimeoutError extends Error {
+    constructor(message: string);
+}
 /**
  * Reject if `promise` does not settle within `ms`. Converts a silent NIP-46
  * hang into a catchable error so callers can fail fast or retry with backoff

package/dist/bunker-context.js

@@ -21,10 +21,25 @@ import { readStateFile, writeStateFile } from './state.js';
 useWebSocketImplementation(WebSocket);
 /** Bound the NIP-46 connect handshake. nostr-tools' BunkerSigner has no
  *  per-request timeout, so an offline signer or unreachable relays make the
- *  connect hang forever. */
-const CONNECT_TIMEOUT_MS = 15_000;
-/** Bound individual signer round-trips (sign_event, get_public_key, nip44). */
-const REQUEST_TIMEOUT_MS = 30_000;
+ *  connect hang forever. A hardware signer (e.g. Heartwood) may also wait on
+ *  a physical button press -- roughly a 30-second window -- so this must sit
+ *  comfortably above that, not at or under it. */
+export const CONNECT_TIMEOUT_MS = 60_000;
+/** Bound individual signer round-trips (sign_event, get_public_key, nip44).
+ *  Same button-press headroom as {@link CONNECT_TIMEOUT_MS}. */
+export const REQUEST_TIMEOUT_MS = 60_000;
+/**
+ * Thrown by {@link withTimeout} when the wrapped promise does not settle in
+ * time. A distinct class (rather than a plain `Error`) lets callers tell a
+ * timeout apart from a genuine rejection -- e.g. `HeartwoodContext.probe()`
+ * treats a timed-out request differently from a denied one.
+ */
+export class TimeoutError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TimeoutError';
+    }
+}
 /**
  * Reject if `promise` does not settle within `ms`. Converts a silent NIP-46
  * hang into a catchable error so callers can fail fast or retry with backoff
@@ -34,7 +49,7 @@ const REQUEST_TIMEOUT_MS = 30_000;
 export function withTimeout(promise, ms, label) {
     let timer;
     const timeout = new Promise((_resolve, reject) => {
-        timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+        timer = setTimeout(() => reject(new TimeoutError(`${label} timed out after ${ms}ms`)), ms);
     });
     return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
 }

package/dist/cli/index.js

@@ -382,6 +382,8 @@ if (config.bunkerUri) {
     if (hw)
         ctx = hw;
     console.error(`Connected to ${hw ? 'Heartwood' : 'bunker'} — signing as ${ctx.activeNpub}`);
+    if (hw && !hw.listingAvailable)
+        console.error(hw.listingUnavailableMessage);
 }
 else {
     ctx = new IdentityContext(config.secretKey, config.secretFormat, { forbidPubkeys: config.forbidPubkeys });

package/dist/heartwood-context.d.ts

@@ -9,22 +9,68 @@ import { BunkerContext } from './bunker-context.js';
 import type { LinkageProof } from 'nsec-tree';
 import type { PublicIdentity } from './types.js';
 import type { ExtendedSigningContext } from './signing-context.js';
+/**
+ * Why {@link HeartwoodContext.listIdentities} is unavailable for this
+ * pairing, set by {@link HeartwoodContext.probe} when it could not confirm
+ * identity listing works.
+ *
+ * - `'denied'` -- the device (or a strict-policy slot) refused
+ *   `heartwood_list_identities` with an unauthorised/denied error.
+ * - `'pending-approval'` -- the probe's `heartwood_list_identities` request
+ *   timed out, most likely because it is awaiting a button press on the
+ *   device right now.
+ */
+export type HeartwoodListingUnavailableReason = 'denied' | 'pending-approval';
 export declare class HeartwoodContext extends BunkerContext implements ExtendedSigningContext {
+    /** Whether `listIdentities()` (and thus features that depend on the
+     *  device's identity list) is expected to work for this pairing. `true`
+     *  unless `probe()` could not confirm listing works. */
+    listingAvailable: boolean;
+    /** Set by `probe()` alongside `listingAvailable = false`; explains why. */
+    listingUnavailableReason?: HeartwoodListingUnavailableReason;
+    /** Human-readable explanation of `listingUnavailableReason`, suitable for
+     *  logging or surfacing to a caller. Undefined when listing is available. */
+    listingUnavailableMessage?: string;
     /**
      * Probe a connected BunkerContext for Heartwood extensions.
-     * Returns a HeartwoodContext if extensions are available, null otherwise.
      *
-     * The probe sends a single heartwood_list_identities request. If the remote
-     * signer responds with a result (not an error), the extensions are available.
+     * Returns `null` when the remote signer does not speak the Heartwood
+     * dialect at all (method unknown/unsupported, or a response that doesn't
+     * look like an identity list) -- the base context stays a plain bunker,
+     * silently, as before.
+     *
+     * Returns a `HeartwoodContext` in every other case where the device IS a
+     * Heartwood but identity listing could not be confirmed:
+     * - the request was refused by policy (`unauthorised`/denied -- e.g. a
+     *   strict slot that doesn't list `heartwood_list_identities`), or
+     * - the request timed out, most likely because it's awaiting a button
+     *   press on the device right now.
+     *
+     * In both of those cases `listingAvailable` is set to `false` and
+     * `listingUnavailableReason` / `listingUnavailableMessage` explain why.
+     * Callers that only check "is this a Heartwood" (`hw !== null` /
+     * `instanceof HeartwoodContext`) see no change in behaviour.
      */
     static probe(base: BunkerContext): Promise<HeartwoodContext | null>;
-    /** Derive a child identity by purpose and index on the Heartwood device. */
+    /** Re-class `base` as a HeartwoodContext with listing marked unavailable. */
+    private static upgrade;
+    /** Derive a child identity by purpose and index on the Heartwood device.
+     *  Does not depend on `heartwood_list_identities` -- works even when
+     *  `listingAvailable` is `false`. */
     derive(purpose: string, index: number): Promise<PublicIdentity>;
-    /** Derive a named persona on the Heartwood device. */
+    /** Derive a named persona on the Heartwood device.
+     *  Does not depend on `heartwood_list_identities` -- works even when
+     *  `listingAvailable` is `false`. */
     derivePersona(name: string, index: number): Promise<PublicIdentity>;
-    /** List all known identities on the Heartwood device. */
+    /** List all known identities on the Heartwood device.
+     *
+     * Throws immediately, without a device round trip, when `probe()` already
+     * established that listing isn't available for this pairing -- retrying
+     * would just re-hit the same denial or wait out the same timeout. */
     listIdentities(): Promise<PublicIdentity[]>;
-    /** Switch the active identity on the Heartwood device. */
+    /** Switch the active identity on the Heartwood device.
+     *  Does not depend on `heartwood_list_identities` -- works even when
+     *  `listingAvailable` is `false`. */
     switch(purposeOrName: string, index?: number): Promise<void>;
     /** Create a linkage proof on the Heartwood device. */
     prove(mode?: 'blind' | 'full'): Promise<LinkageProof>;

package/dist/heartwood-context.js

@@ -5,50 +5,148 @@
  * extension methods for identity derivation, switching, proofs, and recovery.
  * HeartwoodContext auto-detects these extensions by probing the remote signer.
  */
-import { BunkerContext } from './bunker-context.js';
+import { BunkerContext, withTimeout, TimeoutError, REQUEST_TIMEOUT_MS } from './bunker-context.js';
+/** Matches an error whose text indicates the remote signer does not know the method at all. */
+function isMethodUnknownError(message) {
+    return /unsupported method|method not found|unknown method|no such method|not implemented/i.test(message);
+}
+/** Matches an error whose text indicates the request was understood but refused by policy. */
+function isUnauthorisedError(message) {
+    return /unauthori[sz]ed|denied|not permitted|forbidden/i.test(message);
+}
+/** How long a Heartwood request runs before we hint that it's probably
+ *  waiting on a device button press. Well under REQUEST_TIMEOUT_MS so the
+ *  hint has a chance to show before the request either completes or times out. */
+const APPROVAL_HINT_MS = 3_000;
+/**
+ * Wrap a Heartwood NIP-46 request with the standard 60s timeout, and log a
+ * one-off hint to stderr if it's still pending after {@link APPROVAL_HINT_MS}.
+ * bray is an MCP server over stdio, so this MUST go to stderr (console.error,
+ * same channel every other log line in this codebase uses) and never stdout,
+ * which carries the JSON-RPC transport.
+ */
+function withApprovalHint(promise, label) {
+    const hint = setTimeout(() => {
+        console.error(`Waiting for approval on your Heartwood (${label})...`);
+    }, APPROVAL_HINT_MS);
+    return withTimeout(promise, REQUEST_TIMEOUT_MS, label).finally(() => clearTimeout(hint));
+}
+/** Extract a human-readable message from whatever `sendRequest` rejected with.
+ *  NIP-46 error responses reject with a bare string (the signer's `error`
+ *  field); our own code (timeouts, network failures) rejects with an `Error`. */
+function errorMessage(e) {
+    if (typeof e === 'string')
+        return e;
+    if (e instanceof Error)
+        return e.message;
+    return String(e);
+}
 export class HeartwoodContext extends BunkerContext {
+    /** Whether `listIdentities()` (and thus features that depend on the
+     *  device's identity list) is expected to work for this pairing. `true`
+     *  unless `probe()` could not confirm listing works. */
+    listingAvailable = true;
+    /** Set by `probe()` alongside `listingAvailable = false`; explains why. */
+    listingUnavailableReason;
+    /** Human-readable explanation of `listingUnavailableReason`, suitable for
+     *  logging or surfacing to a caller. Undefined when listing is available. */
+    listingUnavailableMessage;
     /**
      * Probe a connected BunkerContext for Heartwood extensions.
-     * Returns a HeartwoodContext if extensions are available, null otherwise.
      *
-     * The probe sends a single heartwood_list_identities request. If the remote
-     * signer responds with a result (not an error), the extensions are available.
+     * Returns `null` when the remote signer does not speak the Heartwood
+     * dialect at all (method unknown/unsupported, or a response that doesn't
+     * look like an identity list) -- the base context stays a plain bunker,
+     * silently, as before.
+     *
+     * Returns a `HeartwoodContext` in every other case where the device IS a
+     * Heartwood but identity listing could not be confirmed:
+     * - the request was refused by policy (`unauthorised`/denied -- e.g. a
+     *   strict slot that doesn't list `heartwood_list_identities`), or
+     * - the request timed out, most likely because it's awaiting a button
+     *   press on the device right now.
+     *
+     * In both of those cases `listingAvailable` is set to `false` and
+     * `listingUnavailableReason` / `listingUnavailableMessage` explain why.
+     * Callers that only check "is this a Heartwood" (`hw !== null` /
+     * `instanceof HeartwoodContext`) see no change in behaviour.
      */
     static async probe(base) {
+        // Cast to access protected signer — safe because HeartwoodContext extends BunkerContext
+        const signer = base.signer;
+        let result;
         try {
-            // Cast to access protected signer — safe because HeartwoodContext extends BunkerContext
-            const signer = base.signer;
-            const result = await signer.sendRequest('heartwood_list_identities', []);
-            if (!isHeartwoodIdentitiesResponse(result))
-                return null;
-            // Re-class the base context as HeartwoodContext
-            return Object.setPrototypeOf(base, HeartwoodContext.prototype);
+            result = await withTimeout(signer.sendRequest('heartwood_list_identities', []), REQUEST_TIMEOUT_MS, 'heartwood probe (heartwood_list_identities)');
         }
-        catch {
+        catch (e) {
+            const message = errorMessage(e);
+            if (e instanceof TimeoutError) {
+                return HeartwoodContext.upgrade(base, 'pending-approval', 'Heartwood is awaiting approval on the device for identity listing ' +
+                    '(heartwood_list_identities timed out) -- approve the pending request on the device.');
+            }
+            if (isUnauthorisedError(message)) {
+                return HeartwoodContext.upgrade(base, 'denied', 'Heartwood denied identity listing for this pairing; allow heartwood_list_identities for this app in Sapwood.');
+            }
+            if (isMethodUnknownError(message))
+                return null;
+            // Anything else is genuinely ambiguous -- keep the previous, conservative
+            // behaviour of treating it as "not a Heartwood" rather than guessing.
             return null;
         }
+        if (!isHeartwoodIdentitiesResponse(result))
+            return null;
+        // Re-class the base context as HeartwoodContext. Object.setPrototypeOf
+        // only swaps the prototype -- it does NOT re-run class field
+        // initialisers on an object that was constructed as a plain
+        // BunkerContext, so `listingAvailable` must be set explicitly here.
+        const hw = Object.setPrototypeOf(base, HeartwoodContext.prototype);
+        hw.listingAvailable = true;
+        hw.listingUnavailableReason = undefined;
+        hw.listingUnavailableMessage = undefined;
+        return hw;
+    }
+    /** Re-class `base` as a HeartwoodContext with listing marked unavailable. */
+    static upgrade(base, reason, message) {
+        const hw = Object.setPrototypeOf(base, HeartwoodContext.prototype);
+        hw.listingAvailable = false;
+        hw.listingUnavailableReason = reason;
+        hw.listingUnavailableMessage = message;
+        return hw;
     }
-    /** Derive a child identity by purpose and index on the Heartwood device. */
+    /** Derive a child identity by purpose and index on the Heartwood device.
+     *  Does not depend on `heartwood_list_identities` -- works even when
+     *  `listingAvailable` is `false`. */
     async derive(purpose, index) {
-        const result = await this.signer.sendRequest('heartwood_derive', [purpose, String(index)]);
+        const result = await withApprovalHint(this.signer.sendRequest('heartwood_derive', [purpose, String(index)]), 'heartwood derive');
         return JSON.parse(result);
     }
-    /** Derive a named persona on the Heartwood device. */
+    /** Derive a named persona on the Heartwood device.
+     *  Does not depend on `heartwood_list_identities` -- works even when
+     *  `listingAvailable` is `false`. */
     async derivePersona(name, index) {
-        const result = await this.signer.sendRequest('heartwood_derive_persona', [name, String(index)]);
+        const result = await withApprovalHint(this.signer.sendRequest('heartwood_derive_persona', [name, String(index)]), 'heartwood derive persona');
         return JSON.parse(result);
     }
-    /** List all known identities on the Heartwood device. */
+    /** List all known identities on the Heartwood device.
+     *
+     * Throws immediately, without a device round trip, when `probe()` already
+     * established that listing isn't available for this pairing -- retrying
+     * would just re-hit the same denial or wait out the same timeout. */
     async listIdentities() {
-        const result = await this.signer.sendRequest('heartwood_list_identities', []);
+        if (!this.listingAvailable) {
+            throw new Error(this.listingUnavailableMessage ?? 'Heartwood identity listing is unavailable for this pairing.');
+        }
+        const result = await withApprovalHint(this.signer.sendRequest('heartwood_list_identities', []), 'heartwood list identities');
         return JSON.parse(result);
     }
-    /** Switch the active identity on the Heartwood device. */
+    /** Switch the active identity on the Heartwood device.
+     *  Does not depend on `heartwood_list_identities` -- works even when
+     *  `listingAvailable` is `false`. */
     async switch(purposeOrName, index) {
         const params = index !== undefined
             ? [purposeOrName, String(index)]
             : [purposeOrName];
-        const raw = await this.signer.sendRequest('heartwood_switch', params);
+        const raw = await withApprovalHint(this.signer.sendRequest('heartwood_switch', params), 'heartwood switch');
         // Parse response — device may return { npub } object or a bare npub string
         const { decode, npubEncode } = await import('nostr-tools/nip19');
         let npub;
@@ -80,13 +178,13 @@ export class HeartwoodContext extends BunkerContext {
     }
     /** Create a linkage proof on the Heartwood device. */
     async prove(mode = 'blind') {
-        const result = await this.signer.sendRequest('heartwood_create_proof', [this.activePublicKeyHex, mode]);
+        const result = await withApprovalHint(this.signer.sendRequest('heartwood_create_proof', [this.activePublicKeyHex, mode]), 'heartwood create proof');
         return JSON.parse(result);
     }
     /** Recover identities by scanning derived keys on the Heartwood device. */
     async recover(lookahead) {
         const params = lookahead !== undefined ? [String(lookahead)] : [];
-        const result = await this.signer.sendRequest('heartwood_recover', params);
+        const result = await withApprovalHint(this.signer.sendRequest('heartwood_recover', params), 'heartwood recover');
         return JSON.parse(result);
     }
 }

package/dist/index.js

@@ -79,8 +79,11 @@ async function establishBunkerInBackground(base) {
                 // Probe for Heartwood extensions and upgrade the prototype in place so
                 // tools that check `ctx instanceof HeartwoodContext` see it.
                 const hw = await HeartwoodContext.probe(base);
-                if (hw)
+                if (hw) {
                     console.error(`Heartwood extensions detected -- ${base.activeNpub}`);
+                    if (!hw.listingAvailable)
+                        console.error(hw.listingUnavailableMessage);
+                }
             }
             catch (e) {
                 console.error('Heartwood probe failed (non-fatal):', e.message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nostr-bray",
-  "version": "3.4.2",
+  "version": "3.4.3",
   "mcpName": "dev.forgesworn/bray",
   "description": "Trust-aware Nostr for AI and humans. Three dimensions of trust -- verification, proximity, and access -- woven into every interaction.",
   "type": "module",
@@ -178,9 +178,9 @@
   "devDependencies": {
     "@types/node": "^25.5.0",
     "@types/ws": "^8.18.1",
-    "@vitest/coverage-v8": "^4.1.1",
+    "@vitest/coverage-v8": "^5.0.0",
     "typescript": "^6.0.2",
-    "vitest": "^4.1.1",
+    "vitest": "^5.0.0",
     "yaml": "^2.9.0"
   },
   "publishConfig": {