bsv-mcp 0.2.15 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # BSV MCP Server Changelog
 
+## [0.3.1] - 2026-09-05
+
+### Added
+- Connect an existing BRC-100 HTTP signer without loading local private keys or provisioning wallet storage.
+- Inspect sponsor access and submit sponsored push/fund operations with the connected signer.
+
+### Fixed
+- Preserve wallet permission arguments through MCP schemas.
+- Block automatic HTTP payment during sponsor authentication and avoid ambiguous write retries.
+- Preserve explicitly requested satoshi amounts in legacy Droplit taps.
+
+## [0.3.0] - 2026-07-30
+
+### Breaking Changes
+
+- **Spending now requires approval.** `WalletPermissionsManager` was constructed
+  with `seekSpendingPermissions: false`, so no spend was ever gated. It is armed,
+  and a handler is bound to `onSpendingAuthorizationRequested`. Clients that
+  support elicitation prompt the user with the exact satoshi amount and itemised
+  line items; approval grants that amount ephemerally. **On a client without
+  elicitation support, spends are denied.** The refusal names the amount and the
+  reason. This is deliberate — a confirmation gate that silently passes when the
+  client cannot be asked is not a gate.
+- `wallet_setupDroplit` is replaced by three tools —
+  `wallet_registerDroplitKey`, `wallet_createDroplitFaucet`, and
+  `wallet_checkDroplitFaucetStatus`. It had put three unrelated operations behind
+  an `action` enum, which made every argument conditional.
+- `wallet_purchaseListing` no longer accepts `description`. The underlying
+  purchase actions have no parameter for it, so it was advertised and discarded.
+
+### Security
+
+- **`DISABLE_BROADCASTING` did nothing for the tools that move money.** The
+  startup banner printed `Broadcasting: Disabled` while the flag reached only the
+  BAP tools; `wallet_sendBsv`, `sendAllBsv`, the three sweeps, `purchaseListing`
+  and `sendMnee` never received it. Setting the variable, reading "Disabled", and
+  calling `wallet_sendBsv` moved real money. Sixteen transaction-submitting tools
+  now assert through one guard that reads the same environment variable the
+  banner reads.
+- **WIF redaction covered one of three exit paths.** The sweep tools each defined
+  a sanitizer commented "sanitize WIF from any error output" and applied it only
+  in the `catch`. The `result.error` branch and the serialised success payload
+  both returned raw, on tools that take a raw WIF as an argument. One shared
+  redactor now covers all three exits in all three tools, and additionally
+  catches testnet WIFs and xprvs.
+- The admin originator was the package name, `bsv-mcp` — the exact string a
+  caller reaches for when a parameter named `originator` wants a value. Passing
+  it would have bypassed the spending gate while the configuration reported it
+  armed.
+- Two identity-key paths caught an invalid WIF, logged a warning, and continued
+  unsigned. Both now fail.
+
+### Added
+
+- Audit log at `~/.bsv-mcp/audit.log` (JSON Lines, directory `0700`, file
+  `0600`), routed through the key redactor. A failed write reports to stderr and
+  does not break a payment the user already approved.
+- Amount validation on the money-moving tools. `sendBsv`, `sendMnee`, `lockBsv`
+  and `listOrdinal` took a bare `z.number()`, so negative, zero and NaN amounts
+  reached the SDK; a negative USD amount converted to a negative satoshi count.
+
+### Fixed
+
+- `wallet_createOrdinals` accepted `destinationAddress` and never forwarded it,
+  so an ordinal minted to a named address silently locked to a wallet-derived
+  self key.
+- Droplit authentication was hand-rolled and could never have succeeded. It is
+  now BRC-103/104 via `AuthFetch`, verified against the live service.
+- Five packages the code imports were never declared, `zod` among them, so a
+  clean install of the published package could not resolve them.
+- The stdio guard was dead code. Its replacement is a first-position side-effect
+  import, since ES imports evaluate before any top-level statement.
+- `purchaseListing`'s marketplace-rate arithmetic is a pure function, so a fee
+  bug can be told apart from an execution bug.
+
+### Changed
+
+- Core SDKs to current: `@modelcontextprotocol/sdk` 1.27.1 → 1.29.0,
+  `@modelcontextprotocol/ext-apps` 1.2.0 → 1.7.5, `@1sat/actions` 0.0.41 →
+  0.0.192, `@bsv/sdk` 2.0.6 → 2.2.0, `bsv-bap` 0.1.23 → 0.3.4.
+- `Droplet` is spelled `Droplit` throughout, matching droplit.dev. Environment
+  variables are now `DROPLIT_API_URL` and `DROPLIT_FAUCET_NAME`.
+- Test coverage 15 → 45.
+
 ## [0.2.15] - 2026-03-10
 
 ### Fixed
@@ -129,29 +213,29 @@
 - Improved error handling with standardized error types
 - Better code organization with new utility modules
 
-## v0.1.0 - Droplet API Integration & Claude Code CLI Support
+## v0.1.0 - Droplit API Integration & Claude Code CLI Support
 
 ### Major Features
-- **Droplet API Integration**: Added support for running without local keys using Droplet faucet API
+- **Droplit API Integration**: Added support for running without local keys using Droplit faucet API
   - New `IntegratedWallet` class supports both local and remote wallet modes
-  - BSM (Bitcoin Signed Message) authentication for Droplet API communication
-  - Environment variable configuration: `USE_DROPLET_API`, `DROPLET_API_URL`, `DROPLET_FAUCET_NAME`
-  - Automatic faucet funding and transaction broadcasting through Droplet service
+  - BSM (Bitcoin Signed Message) authentication for Droplit API communication
+  - Environment variable configuration: `USE_DROPLIT_API`, `DROPLIT_API_URL`, `DROPLIT_FAUCET_NAME`
+  - Automatic faucet funding and transaction broadcasting through Droplit service
 - **Claude Code CLI Compatibility**: Fixed stdio transport configuration for seamless Claude Code integration
   - Updated smithery.yaml configuration for proper MCP CLI operation
   - Enhanced testing and debugging workflows with Claude CLI
 
 ### Technical Improvements
-- Created `DropletClient` class for robust API communication with go-faucet-api
-- Added comprehensive error handling and validation for Droplet operations
+- Created `DroplitClient` class for robust API communication with go-faucet-api
+- Added comprehensive error handling and validation for Droplit operations
 - Enhanced documentation with testing instructions and troubleshooting guides
 - Improved dual-mode wallet architecture maintaining backward compatibility
 - Updated development documentation with detailed testing workflows
 
 ### Environment Variables
-- `USE_DROPLET_API`: Enable Droplet API mode (default: false)
-- `DROPLET_API_URL`: Droplet service endpoint (default: http://localhost:4000)
-- `DROPLET_FAUCET_NAME`: Faucet name for API operations (required in Droplet mode)
+- `USE_DROPLIT_API`: Enable Droplit API mode (default: false)
+- `DROPLIT_API_URL`: Droplit service endpoint (default: http://localhost:4000)
+- `DROPLIT_FAUCET_NAME`: Faucet name for API operations (required in Droplit mode)
 - `TRANSPORT`: MCP transport mode (stdio/http) for Claude Code compatibility
 
 ## v0.0.37 - Resource Updates

package/README.md

@@ -8,6 +8,51 @@
 
 A collection of Bitcoin SV (BSV) tools for the Model Context Protocol (MCP) framework. This library provides wallet, ordinals, and utility functions for BSV blockchain interaction.
 
+## Connect an existing BRC-100 signer
+
+Set `BRC100_WALLET_URL` to explicitly use an existing wallet through the SDK's
+`HTTPWalletJSON` signer RPC transport. For example, **if your wallet already
+exposes this signer RPC**:
+
+```bash
+BRC100_WALLET_URL=http://127.0.0.1:3321 BRC100_WALLET_ORIGINATOR=bsv-mcp.local bun run index.ts --stdio
+```
+
+`BRC100_WALLET_ORIGINATOR` is optional and defaults to `bsv-mcp.local`; use a
+domain or HTTP(S) origin without credentials, paths, queries or fragments.
+Empty, malformed and `admin.bsv-mcp.internal` origins are rejected. The SDK
+sends the origin as both `Origin` and `Originator` headers in Node/Bun.
+Signer URLs must use HTTPS, or HTTP on loopback (`localhost`, `127.0.0.0/8`,
+`[::1]`), without credentials, queries or fragments. Redirects are rejected.
+
+Remove `PRIVATE_KEY_WIF`, `IDENTITY_KEY_WIF`, `DROPLIT_API_URL` and
+`DROPLIT_FAUCET_NAME`, and disable `USE_DROPLIT_API` before enabling this mode:
+explicit conflicting configuration is rejected. Existing local key files are
+left unread. This mode generates no keys, creates no local wallet or storage,
+and provisions no remote storage. Startup performs one identity-public-key
+request with a 10-second timeout. Failure stops startup with a nonzero exit;
+there is no endpoint probing or identity fallback. All signer calls have a
+10-second timeout and no automatic retries; a timed-out write may have reached
+the signer, so inspect its state before resubmitting.
+
+The external wallet remains the permission authority, including spending and
+identity disclosure. Tool arguments (including `seekPermission`) reach it
+without a permission-bypass wrapper or automatic approval. Approve requests
+in your wallet. MCP shutdown does not shut down the signer.
+
+Context wallet/BRC-100 tools are available without a legacy wallet. Legacy
+collection minting/gathering, A2B publication, BAP/raw-key, BSocial and MNEE
+tools are unavailable in this mode. `BSV_CHAIN` selects `main` (default) or
+`test`. Existing `ONESAT_API_URL` configures the auxiliary OneSat API clients
+used by context actions; it is separate from the signer URL. Those actions
+still require the corresponding OneSat service capabilities and the signer's
+support for the requested protocol/baskets. Existing tool disable flags apply.
+
+**Transport distinction:** `1sat serve wallet` exposes **storage RPC**, not
+the SDK signer RPC. Do not set `BRC100_WALLET_URL` to that storage endpoint.
+This server does not start or supply a signer daemon. Without
+`BRC100_WALLET_URL`, the existing local wallet configuration remains in effect.
+
 ## Installation Options
 
 ### Option 1: Claude Code Plugin (Simplest)
@@ -576,34 +621,34 @@ The BSV MCP server can be customized using environment variables to enable or di
 | `IDENTITY_KEY_WIF`    | `not set` | Optional WIF for identity key; if set, ordinals inscriptions will be signed with sigma-protocol for authentication, curation, and web-of-trust. |
 | `DISABLE_BROADCASTING` | `false` | Set to `true` to disable transaction broadcasting; returns raw transaction hex instead - useful for testing and transaction review before broadcasting |
 
-### Droplet API Configuration
+### Droplit API Configuration
 
-The BSV MCP server supports running in Droplet API mode, which allows operation without local private keys by using a remote faucet service:
+The BSV MCP server supports running in Droplit API mode, which allows operation without local private keys by using a remote faucet service:
 
 | Environment Variable | Default | Description |
 | -------------------- | ------- | ----------- |
-| `USE_DROPLET_API` | `false` | Set to `true` to enable Droplet API mode for remote wallet operations |
-| `DROPLET_API_URL` | `http://localhost:4000` | Base URL for the Droplet faucet API service |
-| `DROPLET_FAUCET_NAME` | `not set` | Name of the faucet to use (required when `USE_DROPLET_API` is true) |
+| `USE_DROPLIT_API` | `false` | Set to `true` to enable Droplit API mode for remote wallet operations |
+| `DROPLIT_API_URL` | `http://localhost:4000` | Base URL for the Droplit faucet API service |
+| `DROPLIT_FAUCET_NAME` | `not set` | Name of the faucet to use (required when `USE_DROPLIT_API` is true) |
 | `TRANSPORT` | `stdio` | MCP transport mode (stdio/http) - automatically set to stdio for Claude Code compatibility |
 
-#### Droplet API Mode
+#### Droplit API Mode
 
-When `USE_DROPLET_API=true` is set, the server operates in remote mode:
+When `USE_DROPLIT_API=true` is set, the server operates in remote mode:
 
 - **No Local Keys Required**: The server doesn't need `PRIVATE_KEY_WIF` or local key files
-- **Remote Wallet Operations**: Transactions are funded and broadcast through the Droplet API
+- **Remote Wallet Operations**: Transactions are funded and broadcast through the Droplit API
 - **BSM Authentication**: Uses Bitcoin Signed Message (BSM) authentication for secure API communication
 - **Automatic Funding**: The faucet automatically provides UTXOs for transactions
 - **Seamless Integration**: All existing wallet tools work transparently with the remote service
 
-#### Example Droplet Configuration
+#### Example Droplit Configuration
 
 ```bash
-# Enable Droplet API mode
-USE_DROPLET_API=true
-DROPLET_API_URL=https://your-droplet-service.com
-DROPLET_FAUCET_NAME=your-faucet-name
+# Enable Droplit API mode
+USE_DROPLIT_API=true
+DROPLIT_API_URL=https://your-droplit-service.com
+DROPLIT_FAUCET_NAME=your-faucet-name
 TRANSPORT=stdio
 ```
 
@@ -830,3 +875,40 @@ npm test
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+
+### Use a sponsor with your connected wallet
+
+```sh
+BRC100_WALLET_URL=http://127.0.0.1:3321
+BRC100_WALLET_ORIGINATOR=bsv-mcp.local
+DROPLIT_API_URL=https://api.droplit.dev/droplit
+DROPLIT_FAUCET_NAME=your-sponsor-slug
+```
+
+Set both sponsor values explicitly. The URL includes the server's configured
+base path. Leave `USE_DROPLIT_API` unset: these sponsor tools appear alongside
+normal wallet tools and use the same connected signer identity. Existing local
+BRC-100 wallet contexts also support this sponsor pair. `1sat serve` exposes a
+wallet stack service; it is not itself a BRC-100 signer RPC endpoint.
+
+Call `droplit_getAccess` to inspect your own authorization and quotas. An
+`approval_required` response includes a `https://droplit.dev` link for manual
+owner review. Do not automatically open, approve, or register to obtain access.
+Public status and public-key registration do not prove sponsor approval, and
+creating your own faucet requires funding rather than providing free credit.
+Missing quota kinds are unrestricted for authorized users; a configured zero
+count remains denied. Count and transfer quotas exclude a guaranteed miner-fee
+budget.
+
+`droplit_push` accepts `data: string[]` and `encoding: "hex" | "utf8"`.
+`droplit_fund` accepts `rawtx` transaction hex and requests sponsor funding and
+broadcast. Both obey broadcasting disable settings and make one client
+submission, with no automatic 402 payment or ambiguous-write retry. Wallet
+signing permissions remain controlled by the configured signer. The API authentication
+facade forwards signer methods but rejects payment creation/signing, so SDK
+BRC-105 payment handling cannot spend funds; a 402 requires human review. Structured
+401/403/429 errors identify authentication, approval, or quota problems;
+available quota reset information is retained. `unknown_outcome` means reconcile
+transaction/history before retrying; no idempotency-key support is claimed.
+The legacy `USE_DROPLIT_API=true` wallet mode remains available separately.