@guiie/buda-mcp 1.5.0 → 1.5.2

package/.cursor/rules/marketplace-docs-sync.mdc

@@ -0,0 +1,32 @@
+---
+description: Keep marketplace documentation in sync with tool changes
+globs: src/tools/**/*.ts
+alwaysApply: false
+---
+
+# Marketplace Documentation Sync
+
+Any change to `src/tools/` that adds, removes, or modifies a tool **must** be accompanied by matching updates to all three marketplace files.
+
+## Files to keep in sync
+
+| File | What to update |
+|------|----------------|
+| `marketplace/claude-listing.md` | Add/remove/update `### \`tool_name\`` section in the correct group (Public or Authenticated) |
+| `marketplace/gemini-tools.json` | Add/remove/update entry in `functionDeclarations[]` with Gemini types (`STRING`, `INTEGER`, `NUMBER`, `OBJECT`) |
+| `marketplace/openapi.yaml` | Add/remove/update path + response schema — **public tools only** (auth tools are excluded intentionally) |
+
+## When each file needs updating
+
+- **New tool added** → add to all applicable files above
+- **Tool removed** → remove from all files
+- **Parameter added/changed/removed** → update description and `required` array in all files
+- **Tool description changed** → update all files
+- **Auth status changed** (public ↔ auth) → move between sections in `claude-listing.md`, update `gemini-tools.json`, add/remove from `openapi.yaml`
+
+## Quick checklist before committing
+
+- [ ] `claude-listing.md` reflects all 46+ tools (run `grep "^### \`" marketplace/claude-listing.md | wc -l` to count)
+- [ ] `gemini-tools.json` `functionDeclarations` count matches
+- [ ] `openapi.yaml` paths count matches public tool count
+- [ ] `CHANGELOG.md` has an entry describing the change

package/CHANGELOG.md

@@ -7,6 +7,81 @@ This project uses [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [Unreleased]
+
+---
+
+## [1.5.2] – 2026-04-11
+
+### Security
+
+- **Trust proxy configured for Railway** — added `app.set("trust proxy", 1)` to Express before any middleware. Without this, `express-rate-limit` saw the proxy IP for every request instead of the real client IP, making per-IP rate limiting effectively useless in the Railway deployment.
+
+- **Constant-time bearer token comparison** — `mcpAuthMiddleware` now uses `crypto.timingSafeEqual` via a new `safeTokenEqual()` helper (exported from `src/utils.ts`) instead of plain string equality, eliminating the theoretical timing side-channel on the `MCP_AUTH_TOKEN` comparison.
+
+- **PORT and MCP_RATE_LIMIT startup validation** — both environment variables are now parsed through a new `parseEnvInt(raw, fallback, min, max, name)` helper that throws a descriptive error and exits on `NaN` or out-of-range values, preventing silent misconfigurations (e.g. `MCP_RATE_LIMIT=abc` previously resolved to `NaN` and could disable the rate limiter).
+
+- **MCP_AUTH_TOKEN entropy warning** — server now emits a `console.warn` at startup if `MCP_AUTH_TOKEN` is set but shorter than 32 characters, nudging operators toward adequately random secrets.
+
+- **Dead man's switch fully isolated to stdio transport** — `renew_cancel_timer` and `disarm_cancel_timer` now also return `TRANSPORT_NOT_SUPPORTED` on HTTP transport (previously only `schedule_cancel_all` was blocked). An attacker with HTTP access could previously disarm or renew a timer armed via the stdio process, since both share the same module-level `timers` Map.
+
+- **Input validation in `compare_markets`** — `base_currency` is now validated with `validateCurrency()` before fetching tickers, consistent with all other tools that accept a currency parameter. Arbitrary-length strings no longer reach the cache or API.
+
+- **BOLT-11 invoice regex strengthened** — regex updated from `/^ln(bc|tb|bcrt)\d/i` to `/^ln(bc|tb|bcrt)\d*[munp]?1[a-z0-9]{20,}$/i`. The new pattern requires the bech32 separator `1`, at least 20 characters of bech32 data after it, and anchors at `$` — rejecting malformed strings that happen to start with the right prefix.
+
+- **API path redaction from error responses** — removed the `path` field from all `BudaApiError` catch blocks across 31 tool handlers. The field was included in MCP tool responses, leaking internal API endpoint patterns (e.g. `/currencies/BTC/withdrawals`) to clients. The `path` property still exists on `BudaApiError` for internal use in audit logs.
+
+- **Structured audit logging for destructive operations** — new `src/audit.ts` module with `logAudit(event: AuditEvent)` writes newline-delimited JSON to `process.stderr` for all 11 handlers with financial side-effects: `place_order`, `cancel_order`, `cancel_all_orders`, `cancel_order_by_client_id`, `place_batch_orders`, `create_withdrawal`, `lightning_withdrawal`, `create_receive_address`, `quote_remittance`, `accept_remittance_quote`, `schedule_cancel_all`. Audit events include `ts`, `tool`, `transport`, `args_summary` (sanitized — never includes `confirmation_token`, `invoice`, or `address`), `success`, and `error_code`. Each handler exposes an optional `transport` parameter (default `"stdio"`) for future HTTP-aware logging.
+
+### Added
+
+- **`safeTokenEqual(a, b)` utility** — exported from `src/utils.ts`; constant-time string comparison using `crypto.timingSafeEqual`. Usable by any future code that compares secrets.
+- **`parseEnvInt(raw, fallback, min, max, name)` utility** — exported from `src/utils.ts`; safe environment variable integer parsing with range validation. Used for `PORT` and `MCP_RATE_LIMIT` at startup.
+- **`handleCompareMarkets` exported handler** — `compare_markets.ts` logic extracted from the inline registration closure into a named, exported function for unit testability.
+
+### Tests
+
+- **+28 unit tests** covering all new security behaviors: `safeTokenEqual` (5 cases), `parseEnvInt` (6 cases), `handleCompareMarkets` validateCurrency guard (4 cases), improved BOLT-11 regex (3 cases), DMS HTTP transport guard for renew and disarm (4 cases), `logAudit` output format and secret redaction (3 cases), audit integration with `handlePlaceOrder` (1 case), `path` field absence in error responses (2 cases).
+- **Updated 3 existing test fixtures** — replaced placeholder invoice string `"lnbc1000u1ptest..."` (which contained dots — invalid bech32) with a well-formed test value that satisfies the improved BOLT-11 regex.
+
+---
+
+## [1.5.1] – 2026-04-11
+
+### Security
+
+- **HTTP startup guard for missing `MCP_AUTH_TOKEN`** — when `BUDA_API_KEY`/`BUDA_API_SECRET` are present but `MCP_AUTH_TOKEN` is not set, the HTTP server now exits with a `FATAL` error at startup instead of silently leaving the `/mcp` endpoint publicly accessible. This closes the opt-in footgun where operators could deploy credentials without a protecting token.
+
+- **Rate limiting on `/mcp`** — `express-rate-limit` middleware (120 req/min per IP by default) is applied to `POST /mcp` and `GET /mcp` before auth, preventing looping agents from saturating the Buda API. Configurable via the `MCP_RATE_LIMIT` environment variable.
+
+- **Crypto address format validation in `create_withdrawal`** — the `address` field is now validated against per-currency regex rules for BTC, ETH, USDC, USDT, LTC, BCH, and XRP before any API call. Unknown currencies pass through to the exchange. Returns `INVALID_ADDRESS` on failure. Tool description now explicitly warns that crypto withdrawals are irreversible.
+
+- **BOLT-11 invoice format validation in `lightning_withdrawal`** — the `invoice` field is now checked against a prefix regex (`/^ln(bc|tb|bcrt)\d/i`) before the API call, rejecting non-invoice strings (e.g. a Bitcoin address pasted by mistake). Zod minimum length tightened from 1 to 50 characters.
+
+- **Dead man's switch blocked on HTTP transport** — `schedule_cancel_all` now returns `TRANSPORT_NOT_SUPPORTED` when called via the HTTP server, where a process restart (deploy, crash, autoscale) silently drops all in-memory timers. `renew_cancel_timer` and `disarm_cancel_timer` remain callable. The `register()` function accepts a new `transport: "stdio" | "http"` parameter (default `"stdio"`).
+
+### Added
+
+- **Batch orders optional notional cap** — `place_batch_orders` now accepts an optional `max_notional` parameter. If the sum of `amount × limit_price` across all limit orders exceeds the cap, the entire batch is rejected before any API call with `NOTIONAL_CAP_EXCEEDED`. Market orders contribute 0 (execution price unknown).
+
+### Fixed
+
+- **Security: path traversal in MCP resource handlers** — `buda://ticker/{market}` and `buda://summary/{market}` resource handlers now call `validateMarketId` before interpolating the parameter into the API URL, preventing path traversal to unintended Buda API endpoints.
+- **Security: bearer token auth for HTTP server** — `src/http.ts` now supports an optional `MCP_AUTH_TOKEN` environment variable. When set, all requests to `/mcp` must include `Authorization: Bearer <token>`. Health check and server-card endpoints remain public.
+- **Bug: NaN propagation in `flattenAmount`** — now throws an explicit error on invalid amount strings instead of silently returning `NaN`.
+- **Bug: nonce collision on concurrent HTTP requests** — `BudaClient` now uses a per-instance counter to guarantee unique nonces even when multiple requests land within the same millisecond.
+- **Bug: `version.ts` crash on missing `package.json`** — `readFileSync` is now wrapped in `try/catch` with fallback `"unknown"` to prevent process crash in deployments without `package.json`.
+- **Bug: incorrect PUT payload in `cancel_order` and `dead_mans_switch`** — body is now `{ order: { state: "canceling" } }` per Buda API Rails convention, matching `cancel_order_by_client_id` and `remittances`.
+- **Bug: `ttl_seconds` bounds not enforced in `handleScheduleCancelAll`** — added explicit validation (10–300, integer) in the handler itself, independent of Zod schema; a negative TTL would previously have fired the timer immediately.
+- **Bug: `gtd_timestamp` not validated in `place_order`** — now checks that the value is a valid ISO 8601 datetime and is in the future before sending it to the API.
+- **Bug: `sma_50` returned incorrect partial average** — `get_technical_indicators` now returns `null` for `sma_50` (with an `sma_50_warning` field) when fewer than 50 candles are available, instead of silently computing an average over fewer points.
+- **Security: `quote_remittance` now requires `confirmation_token="CONFIRM"`** — this tool is non-idempotent (each call creates a new remittance record); the confirmation guard prevents accidental or repeated invocations.
+- **Security: `create_receive_address` now requires `confirmation_token="CONFIRM"`** — this tool is non-idempotent (each call generates a new blockchain address); the confirmation guard prevents accidental repeated calls.
+- **Marketplace docs updated** — `gemini-tools.json`, `claude-listing.md`, `openapi.yaml`, and `README.md` updated to reflect all changes.
+- **Marketplace documentation gap** — `claude-listing.md`, `gemini-tools.json`, and `openapi.yaml` were missing 18 tools that were already implemented and registered in the server. All three files now reflect the full set of 46 tools.
+
+---
+
 ## [1.5.0] – 2026-04-11
 
 ### Added

package/PUBLISH_CHECKLIST.md

@@ -1,8 +1,6 @@
-# Publish Checklist — buda-mcp v1.4.0
+# Publish Checklist — buda-mcp v1.5.2
 
-Steps to publish `v1.4.0` to npm, the MCP registry, and notify community directories.
-
-> **Important for v1.4.0:** The new `schedule_cancel_all` tool uses in-memory timer state that is lost on server restart. This is prominently documented in the tool description, README auth section, and CHANGELOG. Do NOT encourage users to rely on this tool in hosted/Railway deployments.
+Steps to publish `v1.5.2` to npm, the MCP registry, and notify community directories.
 
 ---
 
@@ -10,13 +8,13 @@ Steps to publish `v1.4.0` to npm, the MCP registry, and notify community directo
 
 ```bash
 # Confirm version
-node -e "console.log(require('./package.json').version)"  # should print 1.4.0
+node -e "console.log(require('./package.json').version)"  # should print 1.5.2
 
 # Build and test
 npm run build
 npm test
 
-# Sync server.json version (already done, but run again to confirm)
+# Sync server.json version (already done, but confirm)
 npm run sync-version
 
 # Verify no credentials are logged (audit)
@@ -39,58 +37,9 @@ Verify: https://www.npmjs.com/package/@guiie/buda-mcp
 
 ## 3. GitHub release
 
-```bash
-git add -A
-git commit -m "chore: release v1.4.0
-
-- simulate_order: live order cost simulation (no order placed, simulation: true)
-- calculate_position_size: Kelly-style sizing from capital/risk/entry/stop (client-side)
-- get_market_sentiment: composite score -100..+100 from price/volume/spread
-- get_technical_indicators: RSI/MACD/BB/SMA20/SMA50 from trade history (no libs)
-- schedule_cancel_all + renew_cancel_timer + disarm_cancel_timer: in-memory dead man's switch (auth-gated)
-- aggregateTradesToCandles() extracted to utils.ts (shared by price_history + technical_indicators)
-- OhlcvCandle interface moved to types.ts
-- 59 unit tests (24 new)"
-
-git tag v1.4.0
-git push origin main --tags
-```
-
-Then create a GitHub Release from the tag:
-
----
-
-**Release notes template (GitHub):**
-
-```
-## buda-mcp v1.4.0 — Trading Tools
-
-### 5 new tools
+Tag and release already created via `gh release create v1.5.2`. Verify at:
 
-**`simulate_order`** (public)
-Simulates a buy or sell order using live ticker data — no order placed. Returns estimated fill price, fee (actual taker rate from market data: 0.8% crypto / 0.5% stablecoin), total cost, and slippage vs mid. All outputs include simulation: true.
-
-**`calculate_position_size`** (public)
-Kelly-style position sizing from capital, risk %, entry, and stop-loss. Fully client-side. Returns units, capital_at_risk, position_value, fee_impact, and a plain-text risk note.
-
-**`get_market_sentiment`** (public)
-Composite sentiment score (−100 to +100) from price variation 24h (40%), volume vs 7d average (35%), and spread vs market-type baseline (25%). Returns score, label, component breakdown, and disclaimer.
-
-**`get_technical_indicators`** (public)
-RSI (14), MACD (12/26/9), Bollinger Bands (20, 2σ), SMA 20, SMA 50 — computed server-side from Buda trade history with no external libraries. Returns signal interpretations and structured warning if insufficient candles.
-
-**`schedule_cancel_all` + `renew_cancel_timer` + `disarm_cancel_timer`** (auth-gated)
-In-memory dead man's switch: arms a timer that cancels all open orders if not renewed. WARNING: timer state is lost on server restart. Use only on locally-run instances.
-
-### Infrastructure
-- `aggregateTradesToCandles()` extracted to `utils.ts` — shared by `get_price_history` and `get_technical_indicators`
-- `OhlcvCandle` interface exported from `types.ts`
-- 59 unit tests (was 35)
-
-```bash
-npx @guiie/buda-mcp
-```
-```
+https://github.com/gtorreal/buda-mcp/releases/tag/v1.5.2
 
 ---
 
@@ -115,19 +64,23 @@ Verify: https://smithery.ai/server/@guiie/buda-mcp
 **Email/message template:**
 
 ```
-Subject: [Update] buda-mcp v1.4.0 — simulate_order, technical indicators, sentiment, position sizing, dead man's switch
+Subject: [Update] buda-mcp v1.5.2 — Security hardening (second pass)
 
 Hi mcp.so team,
 
-I've released v1.4.0 of buda-mcp (@guiie/buda-mcp on npm).
+I've released v1.5.2 of buda-mcp (@guiie/buda-mcp on npm).
 
-Key changes (5 new tools + 3 sub-tools):
-- simulate_order: live order cost simulation with actual fee rates (no order placed)
-- calculate_position_size: Kelly-style position sizing (fully client-side)
-- get_market_sentiment: composite score -100..+100 from price/volume/spread microstructure
-- get_technical_indicators: RSI/MACD/Bollinger Bands/SMA (no external libs, from trade history)
-- schedule_cancel_all / renew_cancel_timer / disarm_cancel_timer: in-memory dead man's switch (auth-gated)
-- 59 unit tests (was 35)
+Key changes (security hardening, no new tools):
+- Constant-time token comparison (timing-safe Bearer token auth)
+- Strict environment variable validation (PORT, MCP_RATE_LIMIT) with safe exit on bad config
+- MCP_AUTH_TOKEN entropy warning (< 32 chars)
+- trust proxy support for correct client IP detection behind reverse proxies
+- Audit logging for all 11 destructive tool handlers (structured JSON to stderr)
+- Dead man's switch: renew/disarm also blocked on HTTP transport
+- validateCurrency() added to compare_markets tool
+- Stronger BOLT-11 regex validation in lightning_withdrawal
+- Internal API paths redacted from all error responses (31 tool handlers)
+- 28 new unit tests (total now 184)
 
 Links:
 - npm: https://www.npmjs.com/package/@guiie/buda-mcp
@@ -146,23 +99,25 @@ Thank you!
 **Message template:**
 
 ```
-Subject: [Update] buda-mcp v1.4.0
+Subject: [Update] buda-mcp v1.5.2
 
 Hi Glama team,
 
-buda-mcp has been updated to v1.4.0.
+buda-mcp has been updated to v1.5.2.
 
 Package: @guiie/buda-mcp (npm)
 Registry: io.github.gtorreal/buda-mcp (MCP Registry)
-Version: 1.4.0
-
-Changes (5 new tools + 3 sub-tools):
-- simulate_order: order simulation with live data, simulation: true always set
-- calculate_position_size: client-side position sizing
-- get_market_sentiment: composite sentiment score with disclaimers
-- get_technical_indicators: RSI/MACD/BB/SMA from trade history
-- schedule_cancel_all + renew/disarm: in-memory dead man's switch (auth-gated, local use only)
-- 59 unit tests
+Version: 1.5.2
+
+Changes (security hardening, second pass):
+- Constant-time token comparison (timing-safe auth)
+- Strict env var validation (PORT, MCP_RATE_LIMIT)
+- Audit logging for all destructive handlers
+- Dead man's switch: renew/disarm also blocked on HTTP
+- validateCurrency() in compare_markets
+- Stronger BOLT-11 regex
+- Internal paths redacted from error responses
+- 184 unit tests
 
 Quick start:
   npx @guiie/buda-mcp
@@ -177,21 +132,25 @@ Thank you!
 
 ## 8. Post-publish verification
 
-- [ ] `npx @guiie/buda-mcp@1.4.0` starts successfully
-- [ ] `npm info @guiie/buda-mcp version` returns `1.4.0`
-- [ ] GitHub release tag `v1.4.0` is visible
-- [ ] MCP Registry entry reflects v1.4.0
-- [ ] Smithery server card lists 14 public tools (including 4 new: simulate_order, calculate_position_size, get_market_sentiment, get_technical_indicators)
-- [ ] Smithery server card lists 7 auth tools (including schedule_cancel_all, renew_cancel_timer, disarm_cancel_timer)
-- [ ] `GET /health` returns `"version":"1.4.0"` on Railway deployment
-- [ ] simulate_order response includes `simulation: true`
-- [ ] get_technical_indicators returns `warning: "insufficient_data"` for markets with few trades
-- [ ] schedule_cancel_all requires `confirmation_token="CONFIRM"` (test with wrong token)
+- [ ] `npx @guiie/buda-mcp@1.5.2` starts successfully
+- [ ] `npm info @guiie/buda-mcp version` returns `1.5.2`
+- [ ] GitHub release tag `v1.5.2` is visible
+- [ ] MCP Registry entry reflects v1.5.2
+- [ ] Smithery server card lists all tools
+- [ ] `GET /health` returns `"version":"1.5.2"` on Railway deployment
+- [ ] HTTP server exits if `BUDA_API_KEY` set but `MCP_AUTH_TOKEN` is absent
+- [ ] `create_withdrawal` rejects a truncated BTC address with `INVALID_ADDRESS`
+- [ ] `lightning_withdrawal` rejects a non-BOLT11 string with `INVALID_INVOICE`
+- [ ] `place_batch_orders` with `max_notional` rejects over-cap batch before API call
+- [ ] `schedule_cancel_all` via HTTP returns `TRANSPORT_NOT_SUPPORTED`
+- [ ] `renew_cancel_timer` via HTTP returns `TRANSPORT_NOT_SUPPORTED`
+- [ ] Error responses do NOT include internal `path` field
+- [ ] Audit events appear in stderr as JSON with `audit: true`
 - [ ] mcp.so listing updated
 - [ ] Glama.ai listing updated
 
 ---
 
-## ARCHIVED: v1.3.0 checklist
+## ARCHIVED: previous checklists
 
-See git tag `v1.3.0` for the v1.3.0 release notes and verification steps.
+See git tags `v1.5.0`, `v1.5.1`, `v1.4.0`, `v1.4.1`, `v1.4.2` for previous release notes and verification steps.