NUT-XX: Mint Quote Lookup by Public Key

[TheMhv]

Description

The CDK implementation of NUT-XX: Mint Quote Lookup by Public Key

Closes: #1746

---

Notes to the reviewers

• Create a new route for mint quote /mint/quote/{method}/pubkey
• Create a new get_mint_quotes_by_pubkey database function and add your test
• Create a migration to add index into pubkey from mint_quote table in Database
• Create the struct for Request defined in NUT

---

Suggested CHANGELOG Updates

CHANGED

ADDED

• A new NUT file nuts/nutxx.rs
• A new route v1/mint/quote/{method}/pubkey
• Migrations for add index to pubkey field in mint_quote table

REMOVED

FIXED

---

Checklist

• I followed the code style guidelines
• I ran just final-check before committing

[codecov]

Codecov Report

❌ Patch coverage is 77.77778% with 44 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.67%. Comparing base (1ef1031) to head (1c5cf35).

Files with missing lines	Patch %	Lines
crates/cdk-axum/src/router_handlers.rs	0.00%	20 Missing ⚠️
crates/cdk/src/mint/issue/mod.rs	0.00%	19 Missing ⚠️
crates/cdk-axum/src/lib.rs	0.00%	4 Missing ⚠️
crates/cdk-sql-common/src/mint/quotes.rs	80.00%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##             main    #1834    +/-   ##
========================================
  Coverage   78.67%   78.67%            
========================================
  Files         386      387     +1     
  Lines      103373   103569   +196     
========================================
+ Hits        81330    81485   +155     
- Misses      22043    22084    +41     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[c03rad0r]

Thanks for driving this forward. I have an ESP32-S3 device with an on-device ecash wallet (using the nucula library) that I'd like to connect directly to a CDK mint supporting NUT-XX ("Get quotes by pubkeys", cashubtc/nuts#341). My current workaround routes tokens through a stratum proxy translator, but direct mint queries from the ESP32 would simplify the architecture significantly.

I can offer testing against actual ESP32 hardware with my wallet integration. The secp256k1 Schnorr signing is already available on-device. I'm very much looking forward to integrating this — let me know if there's a branch I should target for integration testing.

[cdk-bot]

Verified findings approved for disclosure:

• Signature check bypass lets pubkey quote lookup disclose other users' quotes (medium) - An attacker can query the new endpoint with arbitrary victim pubkeys and an empty or truncated signature list to read private mint-quote metadata/invoices for those pubkeys without proving ownership.

[cdk-bot]

Verified findings approved for disclosure:

• Mint quote by pubkey response is serialized with the wrong root shape (medium) - Spec-compliant clients cannot deserialize the new quote lookup response because the mint returns a top-level array instead of the required object with quotes.
• Mint quote by pubkey request uses non-standard signature field name (medium) - Spec-compliant clients sending pubkey_signatures cannot use the new endpoint because the mint expects the non-standard pubkeys_signatures field.

[cdk-bot]

The response shape for this new endpoint does not match the NUT-29 draft linked from the code. The spec defines PostMintQuotesByPubkeyResponse as an object:

{ "quotes": <Array[MintQuoteResponse]> }

But this handler returns Json(response) directly, and response is the Vec<MintQuoteResponse<QuoteId>> returned by get_mint_quote_by_pubkey, so clients receive a top-level JSON array. Spec-compliant wallets deserializing the response object will fail. Please wrap the vector in a response struct with a quotes field before serializing.

[TheMhv]

• Implemented NUT-XX: replay-protect pubkey quote lookup signatures nuts#391 on commit 35cb21df6b9ce51600ab3c3a8f805e40ff13dea1

[ye0man]

based on feedback from the wider team and to remain consistent with the spec, we should undo 948578d and add back method param

[TheMhv]

@cdk-bot review

[cdk-bot]

Verified findings approved for disclosure:

• get_mint_quotes_by_pubkey SELECT omits last_checked, so every matching row fails to decode (high) - On SQLite and Postgres backends (the only SQL implementors), any NUT-XX quote-by-pubkey lookup that matches at least one quote returns an internal error (ConversionError::MissingColumn(15, 14)) instead of the quotes. Only empty lookups succeed. The endpoint's success path is broken.
• Custom payment method named "pubkey" is silently shadowed by the new NUT-XX route (low) - A mint configuring a custom payment method literally named "pubkey" would have its POST /v1/mint/quote/pubkey (create quote) endpoint silently routed to the NUT-XX lookup handler instead of post_mint_custom_quote. Additionally, NUT-21 RoutePath::MintQuote("pubkey") no longer round-trips through FromStr. Narrow impact — only affects the unlikely configuration of a method named "pubkey".
  Additional locations included in summary:
  • crates/cashu/src/nuts/auth/nut21.rs:177
    Unanchored locations included in summary:
  • crates/cdk-axum/src/custom_router.rs:70

[TheMhv]

@cdk-bot review

[cdk-bot]

Verified findings approved for disclosure:

• NUT-XX lookup route only mounted when custom payment methods are configured, yet nutxx support is advertised unconditionally () - Mints built without custom payment methods advertise NUT-XX support in their /v1/info response but return HTTP 404 for the lookup endpoint POST /v1/mint/quote/{method}/pubkey. Spec-conformant wallets that read the advertisement will attempt the lookup and fail. In standard cdk-mintd deployments that include "bolt11" in custom_methods the route is available, but programmatic/embedded mints using create_mint_router(mint, vec![]) are affected.
  Additional locations included in summary:
  • crates/cdk/src/mint/builder.rs:107
    Unanchored locations included in summary:
  • crates/cdk-axum/src/lib.rs:126
• New route tests POST to a path that no longer exists; happy-path assertions are shadowed by the quote-creation route (method = "pubkey") () - All three new route tests POST to the wrong path (/v1/mint/quote/pubkey instead of /v1/mint/quote/{method}/pubkey). Two of the three tests would fail in CI; the third passes as a false positive (404 instead of the intended 401/403). No test actually exercises the post_mint_quote_by_pubkey handler, so the route is untested.
  Additional locations included in summary:
  • crates/cdk-axum/src/custom_router.rs:50

[TheMhv]

@cdk-bot review

[cdk-bot]

Verified findings approved for disclosure:

• NUT-XX route registered at /v1/{method}/pubkey instead of /v1/mint/quote/{method}/pubkey — spec URL is never served (high) - see inline comment
• MintQuoteByPubkey missing from RoutePath::match_specificity — case-sensitive fallback allows NUT-21/22 auth bypass with mixed-case method segment (medium) - see inline comment
  Unanchored locations included in summary:
  • crates/cashu/src/nuts/auth/nut21.rs:234
• get_mint_quotes_by_pubkey: unbounded row count plus 2N hydration queries on an anonymously reachable endpoint (medium) - see inline comment
  Additional locations included in summary:
  • crates/cdk/src/mint/issue/mod.rs:455

[cdk-bot]

Anonymous endpoint fans out into 1 + 2N SQL queries with no row cap

The new SQL implementation:

// crates/cdk-sql-common/src/mint/quotes.rs
SELECT ... FROM mint_quote WHERE pubkey IN (:pubkeys)   // no LIMIT
...
for quote in mint_quotes.as_mut_slice() {
    let payments = get_mint_quote_payments(&*conn, &quote.id).await?;   // +1 query per quote
    let issuance = get_mint_quote_issuance(&*conn, &quote.id).await?;   // +1 query per quote
    ...
}

MAX_LOOKUP_PUBKEYS = 50 caps the number of pubkeys (and thus signature verifications) per request, but nothing caps how many quote rows those pubkeys resolve to. Since mint-quote creation is unauthenticated on a default mint and accepts an arbitrary NUT-20 pubkey, an attacker can:

1. Over time, create thousands of quotes locked to their own key(s) (each quote creation may also cost the LN backend an invoice).
2. Call POST /v1/mint/quote/{method}/pubkey anonymously with a valid signature and trigger 1 + 2N database queries per request, repeatedly.

There is also no rate limiting on this endpoint — the tower dependency added to cdk-axum is a dev-dependency used only by the new tests. The per-quote hydration mirrors get_mint_quotes, but that trait method is only used by internal/management paths, not by an anonymously reachable HTTP handler, so this PR newly exposes the pattern to untrusted input.

Fix options (any combination):

• Cap total returned rows (LIMIT / rejection when a pubkey set resolves to more than a bounded number of quotes).
• Batch the hydration: one IN (:quote_ids) query each for payments and issuance instead of two queries per quote.
• Add a rate limit (e.g. tower ServiceBuilder::rate_limit, keyed per-IP) on this unauthenticated route.

[TheMhv]

@thesimplekid @crodas I don't know how we can solve this things without adding a rate limit or quote result limit.

[thesimplekid]

Yeah brought this up on the spec a bit ago. cashubtc/nuts#341 (comment)

[thesimplekid]

Can we clean up the commit history here.