nostr-bray 3.4.2 → 3.5.0

package/README.md

@@ -1,6 +1,6 @@
 # nostr-bray
 
-**Trust-aware Nostr MCP for AI and humans.** 258 tools across 29 groups. Model-agnostic. Works with Claude, ChatGPT, Gemini, Cursor, Windsurf, or any MCP client.
+**Trust-aware Nostr MCP for AI and humans.** 260 tools across 29 groups. Model-agnostic. Works with Claude, ChatGPT, Gemini, Cursor, Windsurf, or any MCP client.
 
 [![npm](https://img.shields.io/npm/v/nostr-bray)](https://www.npmjs.com/package/nostr-bray)
 [![CI](https://github.com/forgesworn/bray/actions/workflows/ci.yml/badge.svg)](https://github.com/forgesworn/bray/actions/workflows/ci.yml)
@@ -166,12 +166,13 @@ nostr-bray implements or integrates the following NIPs:
 | **NIP-44** | Encrypted payloads v2 |
 | **NIP-45** | Event counts |
 | **NIP-46** | Nostr Connect (bunker) |
+| **NIP-47** | Nostr Wallet Connect: pay BOLT-11 invoices, balance, invoices, and scoped spending connections over one wallet. NIP-44 v2 only |
 | **NIP-49** | Private key encryption (ncryptsec) |
 | **NIP-50** | Search |
 | **NIP-51** | Lists (mute, pin, follow sets, bookmarks) |
 | **NIP-52** | Calendar events |
 | **NIP-54** | Wiki pages |
-| **NIP-57** | Lightning zaps |
+| **NIP-57** | Zap receipts (kind 9735) are read. bray pays BOLT-11 invoices over NIP-47 but does not build kind 9734 zap requests or resolve LNURL, so it cannot yet zap a profile or note by itself |
 | **NIP-58** | Badges |
 | **NIP-65** | Relay list metadata |
 | **NIP-72** | Communities |
@@ -214,6 +215,10 @@ Search order: `BRAY_CONFIG` env var > `$XDG_CONFIG_HOME/bray/config.json` > `~/.
 | `NOSTR_NCRYPTSEC` | NIP-49 encrypted key |
 | `NOSTR_NCRYPTSEC_PASSWORD` | Password for ncryptsec |
 | `NWC_URI_FILE` | Path to a private `0600` file containing the NWC bearer URI |
+| `BRAY_MAX_PAYMENT_MSAT` | bray's ceiling on any one payment, in msat (default `5000000`, 5,000 sats) |
+| `BRAY_MAX_DAILY_MSAT` | bray's ceiling on spending in any rolling 24 hours, in msat (default `20000000`, 20,000 sats) |
+| `BRAY_WALLET_SERVICE` | Set `1` to register `wallet-grant`, `wallet-refill` and `wallet-serve` |
+| `BRAY_HOME` | Directory for bray's state files (default `$XDG_CONFIG_HOME/bray`, else `~/.config/bray`) |
 | `NOSTR_RELAYS` | Comma-separated relay URLs |
 | `NOSTR_FORBID_PUBKEY` | Comma-separated npubs or hex this process must never sign as. See below. |
 | `TOR_PROXY` | SOCKS5h proxy for Tor |
@@ -224,7 +229,8 @@ Search order: `BRAY_CONFIG` env var > `$XDG_CONFIG_HOME/bray/config.json` > `~/.
 All secret env vars are deleted from `process.env` before parsing can fail.
 Raw `NWC_URI` is refused; use `NWC_URI_FILE` or `wallet connect <nwc-file>` so
 the bearer credential never appears in a process environment, command argument
-or MCP tool argument.
+or MCP tool argument. The wallet must speak NIP-44 v2 encryption for NWC;
+wallets that only offer NIP-04 are refused.
 
 ### Keys this process must never be
 
@@ -252,13 +258,45 @@ everything.
 The active npub is printed on stderr on every start, so the answer to "which
 key is this?" does not depend on asking the agent.
 
+## Spending limits
+
+**The hard limit is the wallet's own.** Point `NWC_URI_FILE` (or
+`wallet connect <file>`) at a connection your wallet issued with a spending
+budget. Whatever bray does, and whatever a model asks of it, the wallet will
+not pay past that budget. Everything below is bray policing itself, which is
+worth having but is not the same thing.
+
+On top of that, every payment bray makes (`zap-send`, `marketplace-pay`, the
+CLI's `zap-send` and `wallet pay`, the SDK, and payments made through the
+scoped connections below) is checked before anything is sent:
+
+- **Per payment:** at most `BRAY_MAX_PAYMENT_MSAT` (default 5,000 sats).
+- **Per day:** at most `BRAY_MAX_DAILY_MSAT` in any rolling 24 hours (default
+  20,000 sats), counting a 1% (minimum 1 sat) fee reserve until the real fee
+  is known. Attempts are written to `payment-ledger.json` in the state
+  directory before the wallet is asked, so a restart does not hand the
+  allowance back.
+- **Once per invoice:** an invoice is never paid twice, and an attempt whose
+  outcome is unknown is only retried after a lookup shows it failed.
+
+`confirm: true` is set by the model, so it is not a human approval. When your
+MCP client supports elicitation, `zap-send` and `marketplace-pay` also ask
+you directly and pay only on an explicit yes; clients without elicitation
+fall back to `confirm`, with the caps still applying. `zap-send` is not in
+the default tool list either: it is reached through `search-actions`.
+
 ## Handing out a wallet connection
 
 `zap-send` spends through the NWC URI you configured. That URI is an
 unbounded capability over the wallet behind it: every method it supports, no
 ceiling, until it is rotated. Handing one to an agent hands over everything.
 
-`wallet-grant` issues connections over the same wallet that are narrower.
+`wallet-grant` issues scoped spending connections over that one wallet: one
+wallet, one balance, and several narrower ways in. They are not separate
+wallets. The tools that mint or widen spending authority (`wallet-grant`,
+`wallet-refill`, `wallet-serve`) are registered only with
+`BRAY_WALLET_SERVICE=1`; `wallet-grants` and `wallet-revoke` are always
+available.
 
 ```
 wallet-grant   { name: "research-agent", methods: ["get_info","pay_invoice"],
@@ -269,11 +307,20 @@ wallet-refill  { nameOrId: "research-agent", budgetMsat: 50000 }
 wallet-serve   { action: "start" }
 ```
 
+`wallet-grant` writes the new connection's `nostr+walletconnect://` URI to a
+`0600` file under `wallet-connections/` beside the grants file and returns
+the path; the URI itself never appears in a tool result.
+
 What a connection may do is an allowlist, and the default grants no spending
-and does not disclose the balance: `get_info`, `make_invoice`,
-`lookup_invoice`. Both of the others are opt-in per connection, and **a
-connection that can spend must carry a budget** - there is no unlimited grant
-to issue by accident.
+and does not disclose anything: `get_info` and `make_invoice`. The others are
+opt-in per connection, and **a connection that can spend must carry a
+budget** - there is no unlimited grant to issue by accident. A connection
+sees only itself:
+
+- `get_balance` reports the connection's remaining budget, never the
+  wallet's balance.
+- `lookup_invoice` answers only for invoices that connection issued or paid;
+  anything else is reported as not found.
 
 The rules exist because a payment cannot be recalled:
 
@@ -286,8 +333,13 @@ The rules exist because a payment cannot be recalled:
   `expiration` tag claims.
 - Each connection has **its own service key**: two grants share nothing a
   relay can correlate, and revoking one is deleting a key.
-- The budget is charged what the **invoice** says, decoded here. A budget
-  checked against a figure the payer supplied is not a budget.
+- The budget is charged what the **invoice** says, decoded here, plus the
+  routing fee: a fee reserve is held until the wallet reports the real fee.
+  Invoices that state no amount are refused. A budget checked against a
+  figure the payer supplied is not a budget.
+- A definite refusal from the wallet (insufficient balance, say) gives the
+  budget back, and the connection is not told why the wallet refused.
+- bray's own per-payment and daily caps apply to these payments as well.
 - A claimed payment whose preimage does not settle the invoice is refused
   rather than passed on. Repeating an unproven claim would make this service
   the one telling the lie.
@@ -298,6 +350,12 @@ as long as this process is alive. That is worth telling whoever you hand a URI
 to: a connection that works while an MCP session is open is a different
 promise from one that works overnight.
 
+The file is the record, shared by every bray process on the machine. Only one
+process may serve the grants at a time, the serving process re-reads a grant
+before every request, and every change is a locked update of the file, so a
+revocation or refill made from any process applies to the next request and
+cannot be written away by another.
+
 ## CLI
 
 ```bash
@@ -335,6 +393,15 @@ See [llms.txt](./llms.txt) for a concise summary optimised for AI context window
 | [dominion](https://github.com/forgesworn/dominion) | Epoch-based encrypted access control |
 | [nostr-veil](https://github.com/forgesworn/nostr-veil) | Privacy-preserving Web of Trust |
 
+## Support
+
+For issues and feature requests, see [GitHub Issues](https://github.com/forgesworn/bray/issues).
+
+If bray is useful to you, a tip is always welcome:
+
+- Lightning: `profusemeat89@walletofsatoshi.com`
+- Nostr zaps: `npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2`
+
 ## Licence
 
 MIT

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/catalog.d.ts

@@ -5,6 +5,14 @@ type ToolHandler = (args: any) => Promise<{
         text: string;
     }>;
 }>;
+/**
+ * Tools registered directly on the MCP server, always in the client's tool
+ * list. Everything else is reached through search-actions + execute-action.
+ *
+ * Nothing that spends is promoted: a payment tool in the default list
+ * invites a model to reach for it. zap-send stays one search away.
+ */
+export declare const PROMOTED_TOOLS: ReadonlySet<string>;
 /**
  * Holds non-promoted tool definitions and exposes them via search-actions
  * and execute-action meta-tools. This keeps the primary tool list lean
@@ -12,6 +20,8 @@ type ToolHandler = (args: any) => Promise<{
  */
 export declare class ActionCatalog {
     private readonly entries;
+    /** Promoted tools actually registered on the server, as counted by the proxy. */
+    promotedCount: number;
     add(name: string, definition: any, handler: ToolHandler): void;
     get size(): number;
     search(intent: string): Array<{
@@ -31,7 +41,7 @@ export declare class ActionCatalog {
  * Create a proxy around McpServer that intercepts registerTool calls.
  * Promoted tools go to the real server; everything else goes to the catalog.
  */
-export declare function createCatalogProxy(server: McpServer, catalog: ActionCatalog, promoted: Set<string>): McpServer;
+export declare function createCatalogProxy(server: McpServer, catalog: ActionCatalog, promoted: ReadonlySet<string>): McpServer;
 /**
  * Coerce execute-action's `params`/`parameters` argument into a plain object.
  *

package/dist/catalog.js

@@ -1,4 +1,28 @@
 import { z } from 'zod';
+/**
+ * Tools registered directly on the MCP server, always in the client's tool
+ * list. Everything else is reached through search-actions + execute-action.
+ *
+ * Nothing that spends is promoted: a payment tool in the default list
+ * invites a model to reach for it. zap-send stays one search away.
+ */
+export const PROMOTED_TOOLS = new Set([
+    'whoami', 'social-post', 'social-reply', 'social-feed',
+    'dm-send', 'dm-read', 'zap-balance',
+    'identity-switch', 'relay-query',
+    'signet-badge', 'trust-score', 'vault-read',
+    'dispatch-send', 'dispatch-check', 'dispatch-reply',
+    'dispatch-ack', 'dispatch-status', 'dispatch-cancel',
+    'dispatch-refuse', 'dispatch-failure', 'dispatch-query',
+    'article-publish', 'article-read', 'article-list',
+    'search-notes', 'search-profiles', 'hashtag-feed',
+    'social-profile-get', 'dm-conversation', 'verify-person',
+    'dispatch-propose', 'dispatch-capability-publish', 'dispatch-capability-discover', 'dispatch-capability-read',
+    'badge-create', 'badge-award', 'badge-accept', 'badge-list',
+    'community-create', 'community-feed', 'community-post', 'community-approve', 'community-list',
+    'calendar-create', 'calendar-read', 'calendar-rsvp',
+    'listing-create', 'listing-read', 'listing-search', 'listing-close',
+]);
 /**
  * Holds non-promoted tool definitions and exposes them via search-actions
  * and execute-action meta-tools. This keeps the primary tool list lean
@@ -6,6 +30,8 @@ import { z } from 'zod';
  */
 export class ActionCatalog {
     entries = new Map();
+    /** Promoted tools actually registered on the server, as counted by the proxy. */
+    promotedCount = 0;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     add(name, definition, handler) {
         this.entries.set(name, {
@@ -88,7 +114,7 @@ export class ActionCatalog {
             description: `Search ${catalog.size} additional actions by describing what you want to do. ` +
                 'Returns matching actions with names, descriptions, and parameter schemas. ' +
                 'Use this when the promoted tools (whoami, social-post, social-reply, social-feed, ' +
-                'dm-send, dm-read, zap-send, zap-balance, identity-switch, relay-query) ' +
+                'dm-send, dm-read, zap-balance, identity-switch, relay-query) ' +
                 'do not cover what you need.',
             inputSchema: {
                 intent: z.string().describe('Describe what you want to do (e.g. "upload a file", "verify an attestation", ' +
@@ -171,6 +197,7 @@ export function createCatalogProxy(server, catalog, promoted) {
                 // eslint-disable-next-line @typescript-eslint/no-explicit-any
                 return (name, definition, handler) => {
                     if (promoted.has(name)) {
+                        catalog.promotedCount++;
                         return target.registerTool(name, definition, handler);
                     }
                     catalog.add(name, definition, handler);

package/dist/cli/commands/wallet.js

@@ -1,4 +1,4 @@
-import { handleZapSend, handleZapBalance, handleZapListTransactions, resolveNwcUri, loadWallets, saveWallets, parseNwcUri, normaliseNwcUriFile, } from '../../exports.js';
+import { handleZapSend, handleZapBalance, handleZapListTransactions, resolveNwcUri, loadWallets, saveWallets, parseNwcUri, normaliseNwcUriFile, defaultPaymentGuard, } from '../../exports.js';
 /**
  * Dispatch `wallet *` subcommands (NIP-47 Nostr Wallet Connect).
  *
@@ -50,6 +50,7 @@ export async function dispatch(cmd, _cmdArgs, h, ctx, pool, extras) {
             const result = await handleZapSend(ctx, pool, {
                 invoice: req(1, 'wallet pay <bolt11>'),
                 nwcUri: resolveNwcUri(ctx, walletsFile, globalNwcUri),
+                guard: defaultPaymentGuard(),
             });
             // A preimage can be an L402 bearer credential when the challenge macaroon
             // is known. Report verified payment without printing the preimage.

package/dist/cli/commands/zap.js

@@ -1,11 +1,11 @@
-import { handleZapSend, handleZapBalance, handleZapMakeInvoice, handleZapLookupInvoice, handleZapListTransactions, handleZapReceipts, handleZapDecode, resolveNwcUri } from '../../exports.js';
+import { handleZapSend, handleZapBalance, handleZapMakeInvoice, handleZapLookupInvoice, handleZapListTransactions, handleZapReceipts, handleZapDecode, resolveNwcUri, defaultPaymentGuard } from '../../exports.js';
 import * as fmt from '../../format.js';
 export async function dispatch(cmd, cmdArgs, h, ctx, pool, extras) {
     const { req, flag, out } = h;
     const { globalNwcUri, walletsFile } = extras;
     switch (cmd) {
         case 'zap-send': {
-            const result = await handleZapSend(ctx, pool, { invoice: req(1, 'zap-send <bolt11>'), nwcUri: resolveNwcUri(ctx, walletsFile, globalNwcUri) });
+            const result = await handleZapSend(ctx, pool, { invoice: req(1, 'zap-send <bolt11>'), nwcUri: resolveNwcUri(ctx, walletsFile, globalNwcUri), guard: defaultPaymentGuard() });
             out({ paid: true, verified: result.verified, paymentHash: result.paymentHash, feesPaidMsats: result.fees_paid });
             break;
         }

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/config.d.ts

@@ -38,6 +38,8 @@ interface ConfigFile {
     dispatchIdentities?: string;
     /** Public keys this process must never sign as. See ContextOptions. */
     forbidPubkeys?: string[];
+    /** Register the tools that mint spending connections (wallet-grant, wallet-refill, wallet-serve). */
+    walletService?: boolean;
 }
 /**
  * Load config from a JSON file. Searches in order:

package/dist/config.js

@@ -2,6 +2,7 @@ import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { readNwcUriFile } from './zap/nwc-file.js';
+import { paymentLimitsFromEnv } from './zap/payment-guard.js';
 const NSEC_RE = /^nsec1[a-z0-9]{58}$/;
 const HEX_RE = /^[0-9a-f]{64}$/;
 const NCRYPTSEC_RE = /^ncryptsec1[a-z0-9]+$/;
@@ -225,6 +226,8 @@ export async function loadConfig() {
     if (nwcFilePath) {
         nwcUri = readNwcUriFile(nwcFilePath);
     }
+    // A mistyped spending ceiling is a startup error, not a silent default.
+    paymentLimitsFromEnv();
     // --- Relays ---
     const relays = process.env.NOSTR_RELAYS
         ? parseRelays(process.env.NOSTR_RELAYS)
@@ -291,6 +294,11 @@ export async function loadConfig() {
     ]
         .map((s) => s.trim())
         .filter(Boolean);
+    // --- Wallet service ---
+    // Off unless asked for: wallet-grant, wallet-refill and wallet-serve hand
+    // out spending authority over the operator's wallet, which is not
+    // something a model should find in its tool list by default.
+    const walletService = process.env.BRAY_WALLET_SERVICE === '1' || file.walletService === true;
     // --- Wallets file ---
     const walletsFile = process.env.BRAY_WALLETS_FILE
         ?? file.walletsFile
@@ -318,5 +326,6 @@ export async function loadConfig() {
         bindAddress,
         dispatchIdentities,
         forbidPubkeys,
+        walletService,
     };
 }

package/dist/dispatch/tools.js

@@ -262,7 +262,7 @@ export function registerDispatchTools(server, deps) {
     server.registerTool('dispatch-capability-publish', {
         description: 'Publish your agent\'s dispatch capabilities as a NIP-89 capability card (kind 31990). Lets other agents discover you on Nostr without needing a pre-shared identities file. The card advertises what task types you support, which repos you can work on, and your availability.',
         inputSchema: {
-            name: z.string().describe('Agent name (e.g. "prometheus", "forge-worker")'),
+            name: z.string().describe('Agent name (e.g. "research-agent", "forge-worker")'),
             description: z.string().describe('What this agent does (e.g. "Full-stack TypeScript agent for TROTT ecosystem")'),
             task_types: z.array(z.string()).describe('Supported task types: "think", "build", or custom types'),
             repos: z.array(z.string()).optional().describe('Repository names this agent can work on (e.g. ["toll-booth", "nsec-tree"])'),

package/dist/file-lock.d.ts

@@ -0,0 +1,2 @@
+/** Run `fn` while holding an exclusive lock at `${path}.lock`. */
+export declare function withFileLock<T>(path: string, fn: () => T): T;

package/dist/file-lock.js

@@ -0,0 +1,71 @@
+import { closeSync, openSync, readFileSync, statSync, unlinkSync, writeSync } from 'node:fs';
+// A short-lived advisory lock between bray processes that share one state
+// file. Held only for a read-modify-write, never across a network call, so
+// waiting for it is a matter of milliseconds.
+//
+// The lock is a file created with O_EXCL. A holder that died leaves it
+// behind; it is taken over once its process is gone or it is older than
+// anything a read-modify-write could plausibly take.
+const STALE_MS = 10_000;
+const WAIT_MS = 5_000;
+const SLEEP = new Int32Array(new SharedArrayBuffer(4));
+function holderIsGone(lockPath) {
+    try {
+        const age = Date.now() - statSync(lockPath).mtimeMs;
+        if (age > STALE_MS)
+            return true;
+        const pid = Number.parseInt(readFileSync(lockPath, 'utf8'), 10);
+        if (!Number.isSafeInteger(pid) || pid <= 0)
+            return false;
+        if (pid === process.pid)
+            return false;
+        try {
+            process.kill(pid, 0);
+            return false;
+        }
+        catch (err) {
+            return err.code === 'ESRCH';
+        }
+    }
+    catch {
+        // vanished between the failed create and this look: try again
+        return false;
+    }
+}
+/** Run `fn` while holding an exclusive lock at `${path}.lock`. */
+export function withFileLock(path, fn) {
+    const lockPath = `${path}.lock`;
+    const deadline = Date.now() + WAIT_MS;
+    let descriptor;
+    while (descriptor === undefined) {
+        try {
+            descriptor = openSync(lockPath, 'wx', 0o600);
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+            if (holderIsGone(lockPath)) {
+                try {
+                    unlinkSync(lockPath);
+                }
+                catch { /* another waiter took it over first */ }
+                continue;
+            }
+            if (Date.now() > deadline) {
+                throw new Error(`Timed out waiting for ${lockPath}; another bray process is holding it.`);
+            }
+            Atomics.wait(SLEEP, 0, 0, 10);
+        }
+    }
+    try {
+        writeSync(descriptor, String(process.pid));
+        return fn();
+    }
+    finally {
+        closeSync(descriptor);
+        try {
+            unlinkSync(lockPath);
+        }
+        catch { /* already gone */ }
+    }
+}

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>;