lnurlcash-conformance 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,97 @@ Semantic versioning. While the LUD-25 draft is unmerged, `0.x` minor bumps
 may add or tighten checks that a previously-passing mint now fails; pin an
 exact version if you gate CI on the grade.
 
+## Unreleased
+
+## 0.5.0 - 2026-08-31
+
+**Breaking: the current LUD-25 draft's mandatory mint comment is now the
+baseline.** Every minting payRequest must advertise `commentAllowed >= 64`,
+and every quote must carry `comment=hex(sha256(secret))`; missing or malformed
+comments are refused before invoice creation. The payment preimage is
+settlement proof and never a bearer credential. `mintToHash`/`h` remains an
+additive ForgeSworn compatibility and receipt extension: when used, `h` must
+repeat the mandatory comment and cannot replace it. The mock, runner,
+lifecycle and pay-request vectors all enforce the same rule, including a
+mismatched `h`/`comment` refusal. `commentFallsBack` remains only as the
+non-compliant historical fixture documented in
+`docs/COMMENT-IS-MANDATORY.md`.
+
+**A mint that is not a Lightning Address is no longer failed for having no
+mint address document.** The document is probed by swapping
+`/.well-known/lnurlp/` for `/.well-known/lnurlw/` in the payRequest URL. On a
+mint served from a plain path that swap changes nothing, so the probe
+re-fetched the payRequest, read `tag: "payRequest"`, and failed the mint for
+an optional document it has nowhere to publish. Found by grading
+`bitkarrot/lnurlmint`, which is served at `/lnurlmint/lnurlp/<id>`; it now
+grades 6 passed, 0 failed on the checks that predate the mandate above.
+
+
+**Two checks for the draft's 25 August additions, both optional-graded.**
+
+`answers a note lookup by hash without the secret` covers "Checking a note
+without exposing it". The capability is detected rather than announced: the
+draft deliberately gives an unrecognized `h` the same answer an unknown
+`k1` gets, so a live note's own hash is the only probe that separates a
+mint which implements the lookup from one which never did. A mint that does
+not offer it is not graded down; one that offers it must omit `k1` from the
+reply - a wallet asking by hash already holds the secret, and filling the
+field in puts the note back on the wire the lookup exists to keep it off -
+must report the same value by hash as by `k1`, and must refuse a hash it
+never registered.
+
+`refuses an oversized merge cleanly` covers the merge cap. The cap itself
+is a MAY, so a mint that does not name one is not graded down, only
+reported, since a wallet must then batch by URL length rather than rely on
+a refusal. The one answer that fails is `OK`: every input on that probe is
+fabricated by the runner, so a mint accepting it has minted an output
+against notes it never held, which is what a truncated `k1` list read as a
+shorter merge looks like from outside.
+
+## 0.4.0 - 2026-08-26
+
+**The mint-output naming check now reads the spelling LUD-25 actually
+specifies.** The draft names the output with a LUD-12 `comment = hex(h)`,
+advertised as a `commentAllowed` of at least 64; `mintToHash` is the
+parameter form one mint shipped before the comment form was written. The
+suite knew only the latter, so a mint naming notes exactly as the draft
+describes graded as "not offered - a minted note's k1 is the invoice
+preimage". That is the worst kind of wrong answer a conformance suite can
+give: it tells a wallet author the safe mint is the unsafe one.
+
+Both spellings are now read from the payRequest and the mint address
+document, probed with a fresh hash each (a mint that binds output ids
+uniquely would rightly refuse the second spelling for naming an output the
+first just took), and reported as `named by comment` / `named by h`.
+
+The two are deliberately not probed identically, because the draft's rules
+for them are opposites:
+
+- `h` is a parameter invented for naming, so a malformed one MUST be
+  refused before an invoice exists. Unchanged.
+- `comment` is plain LUD-12 free text any wallet may send for unrelated
+  reasons, so a comment that is not a bare hash MUST fall back to crediting
+  `k1=P` rather than be refused, and the mint MUST NOT serve LUD-21 `verify`
+  on that fallback - there the preimage is not proof of payment, it is the
+  note. Both are now checked, the second as a failure.
+
+Only `mintToHash` is expected in both documents. `commentAllowed` is a
+payRequest field; the mint address document is a withdrawRequest, where a
+LUD-12 comment has nowhere to go, so its absence there is no longer
+reported as a disagreement.
+
+**A rate-limited grade no longer accuses the mint.** Every mint quote
+issues a real invoice on a real node, so a grader firing a dozen looks like
+the abuse a limiter exists to stop - and probing two spellings nearly
+doubled the count. HTTP 429 was indistinguishable from a spec refusal, so
+the mint was reported as violating whatever check happened to be running
+when the bucket ran dry. 429 is now waited out (honouring `Retry-After`)
+and retried, and reported as an incomplete grade rather than a verdict if
+it persists.
+
+The mock mint gains `commentAllowed`, `commentRefusesMalformed` and
+`verifyOnUnnamedMint` to cover all of this.
+
 ## 0.3.0 - 2026-08-24
 
 - Add an optional bound-mint settlement receipt for sealed signers. A

package/README.md

@@ -60,7 +60,7 @@ for (const c of cases) {
 | `payment-request.json` | `lnurlcashreq1`: one holder asking another for value |
 | `settle-for-value.json` | the decision table a server works through to take a note as payment |
 | `retried-mutation.json` | what makes a repeated mutation a retry rather than a double-spend |
-| `mint-to-hash.json` | wallet-chosen mint outputs and optional bound LUD-21 receipts |
+| `mint-to-hash.json` | additive `mintToHash` compatibility and optional bound LUD-21 receipts; not baseline LUD-25 |
 | `lifecycle.json` | behavioural requirements, as scenarios to drive |
 | `threat-suite.json` | the transport/exposure scorecard — candidate spec options against fixed attacks (non-normative) |
 
@@ -100,10 +100,10 @@ must survive:
 | `--sunset` | refuses anything that grows its liabilities |
 | `--baseFeeMsat=N --feePpm=N` | advertises and withholds a mint fee |
 | `--roundFeeToSat` | rounds the withheld fee up to a whole sat — the note mints short of the formula |
-| `--verifyLeaksEarly` | serves the preimage from verify before settlement — the bearer secret, to anyone with the hash |
+| `--verifyLeaksEarly` | serves a preimage before settlement, falsely claiming payment proof before payment happened |
 | `--mintToHashAcceptsMalformedH` | claims `mintToHash` and invoices an `h` that is not 64 lowercase hex, so a wallet pays for a quote the mint will refuse |
 | `--mintToHashAcceptsUsedH` | claims it and invoices an `h` that already names a note, an invoice or another quote's output |
-| `--mintToHashIgnoresH` | claims it, echoes it back on the quote, and mints at the payment hash anyway, so the preimage is still the money |
+| `--mintToHashIgnoresH` | claims it but accepts `h` and mandatory `comment` naming different outputs |
 
 The three `mintToHash*` misbehaviours need `--mintToHash` alongside them;
 on their own they do nothing, because a mint that never offered the
@@ -126,7 +126,7 @@ answered:
 | `--previousPrivateKey=<hex>` | an old signing key the mock still holds. Its public half joins `previousPubkeys` on its own |
 | `--signWithPreviousKey` | issues every note under that old key while still advertising the new one: the mid-rotation state a mint passes through when the advertisement moves before the signer |
 | `--retriedMutation=replay` | answers a byte-identical repeat of a mutation with the original success instead of `already spent`. The default, `refuse`, is what this mock has always done |
-| `--mintToHash` | takes an optional `h` on the pay callback and credits the minted note there, so the payment preimage is not the money. Off by default, and then `h` is not read at all |
+| `--mintToHash` | accepts `h` alongside the mandatory identical comment and enables the additive quote/receipt fields. Off by default; baseline comment-bound minting remains on |
 | `--mintReceipt` | with `--mintToHash`, adds the optional quote commitment and signed LUD-21 settlement receipt |
 | `--mintToHashAdvertisedOn=quote` | narrows which of the three places claim it (`payRequest`, `mintAddress`, `quote`); all three by default. Changes only what is claimed, never what the mint does |
 
@@ -155,43 +155,23 @@ npx lnurlcash-conform mint@example.com
 
 Read-only by default: resolves the payRequest, checks the `withdrawLink`
 (either legal spelling, and the report says which one the mint uses),
-the fee advertisement, invoice amounts, that LUD-21 verify serves no
-preimage before settlement (on a mint that value IS the bearer secret, and
-everyone on the payment's route knows the payment hash), whether an
+the fee advertisement, invoice amounts, mandatory `commentAllowed: 64`,
+pre-invoice rejection of missing or malformed mint comments, whether an
 unknown note is reported distinguishably from a spent one, and the
 experimental mint address.
 
-One more is graded softly, and it is the one that changes what a bearer
-note is. In LUD-25 a minted note's `k1` is the payment preimage, so the
-preimage is the money, and every routing node on the payment path learns
-it, as does anyone who merely saw the invoice and polled LUD-21 verify with
-its payment hash. A QR on a desktop screen is exactly that. A mint may
-instead take an `h` on its pay callback, the sha256 of a secret the wallet
-chose, and credit the note there; the preimage is then an ordinary payment
-proof that opens nothing. The mint says so in three places, and they mean
-different things: `mintToHash: true` on the payRequest (every mint has one,
-so it is what a wallet decides from), the same on the experimental mint
-address document (corroboration), and the same echoed on the pay callback's
-own response when *that* quote was bound (the one that matters at the moment
-money moves, because the other two can be cached). Anything that is not
-exactly the boolean `true` is no.
-
-A mint that says nothing anywhere is reported as not offering it and passes,
-which is every mint today. A mint that claims it is asked to prove the
-refusals: a malformed `h` must get no invoice at all, since a wallet that
-pays for a quote the mint will reject has bought nothing. Malformed means
-not 32 bytes of hex, in any casing. A wallet MUST send `h` as 64 lowercase
-hex and every client here does, but hex is case-insensitive, so a service
-SHOULD normalise before comparing and MUST NOT read `AAAA...` and `aaaa...`
-as two different outputs: keying the string it was handed files the note
-where the wallet will never look for it, and nobody is told. A service that
-refuses upper case outright is being strict rather than wrong, so the grader
-does not probe it either way. Where the three
-claims disagree, the grader names the disagreement rather than failing it:
-none of those loses anyone money on its own. What is failed is a mint that
-claims the capability and does not bind, because a wallet believing the
-claim stops rotating on sight; that one needs a settlement to see, so it
-rides on `--preimage`.
+Current LUD-25 minting is always comment-bound. The wallet persists a secret,
+sends `comment=hex(sha256(secret))`, and the payment preimage remains ordinary
+settlement proof. A mint that cannot accept the 64-character commitment, or
+that silently creates a preimage-backed note, fails grading.
+
+`mintToHash` is retained as an additive compatibility field. When advertised,
+the runner sends `h` alongside the mandatory comment and requires both to name
+the same output. A malformed `h` must be rejected before invoice creation.
+The payRequest, experimental mint-address document and quote echo are checked
+separately because each claim has a different lifetime. Disagreement between
+those extension advertisements warns; failure to honour a claimed binding
+fails when the paid `--preimage` check proves where the note actually landed.
 
 Three other things a mint may publish are graded softly, because none of them
 is in LUD-25: the mint info on the discovery endpoint, a `/stats` endpoint

package/mock-mint/index.d.ts

@@ -137,14 +137,10 @@ export interface MockMintOptions {
   /** what the node behind a stats-publishing mock claims to hold */
   localBalanceMsat?: number
   /**
-   * Let a WALLET name the note it is buying. Off, and nothing about it
-   * reaches the wire: nothing is advertised anywhere and the pay callback
-   * does not read `h` at all. On, the callback takes an optional `h` - 64
-   * lowercase hex, the sha256 of a secret the wallet chose, the same
-   * thing `h` means on the withdraw callback - and credits the note at
-   * that id when the invoice settles. The payment preimage is then not a
-   * valid k1 for that note, which matters because every routing node on
-   * the payment path learns it, and so does anyone who saw the invoice.
+   * Additive compatibility spelling for the mandatory mint comment. Off,
+   * `h` is not advertised or read, while comment-bound minting remains the
+   * baseline. On, WALLET may repeat the same 64-hex output commitment as
+   * `h`, enabling the ForgeSworn/Moneyer quote and receipt vocabulary.
    *
    * The capability is advertised in three places: `mintToHash: true` on
    * the payRequest (every mint has one, so it is what a wallet decides
@@ -176,11 +172,9 @@ export interface MockMintOptions {
    */
   mintToHashAcceptsUsedH?: boolean
   /**
-   * non-compliant, mintToHash on: advertise the capability, echo it back
-   * on the quote, and credit the note at the payment hash anyway - the
-   * preimage is still the money and the wallet's own secret names
-   * nothing. The wallet stopped rotating on sight because it was told it
-   * did not need to, so this is the worst of both schemes.
+   * non-compliant, mintToHash on: accept `h` and mandatory `comment` even
+   * when they name different outputs. The normative comment still binds
+   * the note, but the extension claim and any h-watching signer disagree.
    */
   mintToHashIgnoresH?: boolean
   /**

package/mock-mint/index.mjs

@@ -66,9 +66,8 @@ const DEFAULTS = {
   // WALLET that handles one but not the other fails against real mints.
   // Run your client against both.
   withdrawLinkForm: 'plain',
-  // LUD-21 verify endpoint. Off means 404, not merely unadvertised: the
-  // preimage it serves IS a bearer secret, so an operator needs a real
-  // off switch.
+  // LUD-21 verify endpoint. Off means 404, not merely unadvertised, so the
+  // mock can exercise current mints that provide no settlement polling.
   verify: true,
   // Publish `payLink` on a note's informational GET, the way home for a
   // holder who has nothing but the note. On by default because the
@@ -166,17 +165,14 @@ const DEFAULTS = {
   //
   // ---- naming the note you are buying ----
   //
-  // Off, and nothing about it reaches the wire: nothing is advertised
-  // anywhere, the pay callback does not read `h` at all, and a minted
-  // note's secret is the payment preimage exactly as it always was.
+  // Off means only the additive `h` spelling is absent: it is not advertised
+  // and the pay callback does not read it. Mandatory comment-bound minting
+  // remains active independently.
   //
-  // On, a WALLET MAY add h=<64 lowercase hex> to the LUD-06 pay callback -
-  // the sha256 of a secret it chose, the same thing `h` means on the
-  // withdraw callback. The note is then credited at that id when the
-  // invoice settles, and the payment preimage is NOT a valid k1 for it.
-  // Which matters because two sets of untrusted people learn a preimage:
-  // every routing node on the payment path, and anyone who merely saw the
-  // invoice and polled /verify with its payment hash.
+  // On, a WALLET MAY repeat the mandatory comment hash as
+  // h=<64 lowercase hex> on the LUD-06 pay callback. This enables the
+  // earlier ForgeSworn/Moneyer capability and receipt vocabulary without
+  // changing which output the normative comment names.
   //
   // The capability is claimed in three places and they say different
   // things. `mintToHash: true` on the payRequest means "I accept an h on
@@ -187,6 +183,23 @@ const DEFAULTS = {
   // which is the one that matters at the moment money moves: the other
   // two can be cached or stale.
   mintToHash: false,
+  // LUD-25 "Checking a note without exposing it": answer the informational
+  // GET by `?h=sha256(k1)` as well as by `?k1=`, so a wallet can look a note
+  // up without putting the live secret in a query string. Optional.
+  //   true             - compliant
+  //   'echoesK1'       - non-compliant: fills in k1, putting the secret back
+  //                      on the wire the lookup existed to keep it off
+  //   'answersUnknown' - non-compliant: answers for a hash it never
+  //                      registered, instead of the unknown-note refusal
+  hashLookup: false,
+  // LUD-25 lets a SERVICE refuse an oversized merge outright rather than
+  // let the URL be mangled upstream. 0 is no explicit cap; a positive number
+  // refuses more than that many k1 with the draft's own reason string.
+  mergeCap: 0,
+  // non-compliant: answer OK to an oversized merge whatever its inputs -
+  // what a mint that parses a truncated k1 list and shrugs looks like from
+  // outside. It has minted an output against notes it never saw.
+  acceptsOversizedMerge: false,
   // Add the optional bound LUD-21 receipt to an honestly bound quote and
   // its verify response. Requires mintToHash, verify and signatures; off
   // by default so the baseline mock remains the current LUD-25 wire.
@@ -199,10 +212,10 @@ const DEFAULTS = {
   // already names a note, an invoice or another quote's output, so two
   // payers' money points at one id
   mintToHashAcceptsUsedH: false,
-  // non-compliant, mintToHash on: advertise the capability, echo it back
-  // on the quote, and credit the note at the payment hash anyway. The
-  // wallet stopped rotating on sight because it was told it did not need
-  // to, so this is the worst of both schemes
+  // non-compliant, mintToHash on: accept h and mandatory comment even when
+  // they name different outputs. The comment still binds the note, but the
+  // extension claim is false and a receipt-watching signer follows the
+  // other commitment.
   mintToHashIgnoresH: false,
   // Which of the three the mock actually says it in. Undefined means all
   // three, which is what an honest mint publishes. Narrowing it changes
@@ -211,7 +224,32 @@ const DEFAULTS = {
   // 'payRequest,mintAddress' is the one that binds without confirming at
   // the moment money moves. Read only when mintToHash is on. Accepts an
   // array or a comma-separated string, so the CLI can pass one.
-  mintToHashAdvertisedOn: undefined
+  mintToHashAdvertisedOn: undefined,
+
+  // The mandatory minting commitment in the spelling LUD-25 specifies:
+  // `comment = hex(sha256(secret))` (LUD-12), advertised as a
+  // `commentAllowed` of at least 64. A number advertises that many
+  // characters and reads `comment` as the output name. The conforming
+  // default is 64. Setting it false or below 64 deliberately models a
+  // SERVICE that cannot mint under the current draft.
+  //
+  // `h` remains an additive Moneyer compatibility field. When supplied it
+  // must be well formed and equal the mandatory comment; it never replaces
+  // the comment and cannot make an otherwise unnamed quote valid.
+  commentAllowed: 64,
+  // non-compliant, commentAllowed on: fall back to a preimage-keyed note
+  // when the comment is missing or malformed, instead of refusing. This was
+  // the draft's line 80 behaviour and is now the defect - see
+  // docs/COMMENT-IS-MANDATORY.md.
+  commentFallsBack: false,
+  // non-compliant, and narrower: refuse a malformed comment - an empty value
+  // included - but fall back when the key is absent entirely. That is the
+  // distinction the malformed loop cannot reach, and the commonest way to
+  // arrive unnamed, since it is what every ordinary LUD-06 wallet sends.
+  commentFallsBackWhenAbsent: false,
+  // non-compliant, commentAllowed on: serve LUD-21 verify even on the
+  // no-comment fallback, where the preimage it hands out IS the note
+  verifyOnUnnamedMint: false
 }
 
 export const createMockMint = async (options = {}) => {
@@ -378,10 +416,9 @@ export const createMockMint = async (options = {}) => {
       const invoice = hash ? invoices.get(hash) : null
       if (!invoice) return fail('unknown payment hash')
       invoice.settled = true
-      // paying a mint invoice is what brings its note into existence. The
-      // preimage IS the note secret and the note id IS the payment hash,
-      // unless the wallet named an output hash of its own on the quote -
-      // then the note is credited there and the preimage is nobody's key.
+      // Paying a mint invoice brings its comment-bound note into existence.
+      // The payment-hash target is reachable only under deliberate legacy
+      // defect flags that allowed an unnamed quote.
       const target = invoice.boundTo ?? hash
       if (!notes.has(target)) mintNote(target, invoice.amountMsat)
       if (invoice.boundTo) boundOutputs.delete(invoice.boundTo)
@@ -438,7 +475,13 @@ export const createMockMint = async (options = {}) => {
     const origin = `http://${req.headers.host}`
 
     // ---- LUD-16 payRequest (minting) ----
-    const lnurlpMatch = url.pathname.match(/^\/\.well-known\/lnurlp\/(.+)$/)
+    // Both shapes are in the wild. A Lightning Address mint lives under
+    // /.well-known/lnurlp/<name>; an LNbits extension serves the same
+    // payRequest at a plain path with no well-known anywhere, which is the
+    // case a grader must not mistake for a missing mint address document.
+    const lnurlpMatch =
+      url.pathname.match(/^\/\.well-known\/lnurlp\/(.+)$/) ??
+      url.pathname.match(/^\/lnurlp\/(.+)$/)
     if (lnurlpMatch) {
       const user = lnurlpMatch[1]
       if (user !== opts.username && user !== '_') {
@@ -466,6 +509,11 @@ export const createMockMint = async (options = {}) => {
         // the option is on, so a mock started with no options answers
         // exactly what it always answered.
         ...(mintToHashPlaces.has('payRequest') ? {mintToHash: true} : {}),
+        // LUD-25: "A mint payLink intending to support this SHOULD
+        // advertise a commentAllowed of at least 64". A payRequest field
+        // only - the mint address document is a withdrawRequest, where a
+        // LUD-12 comment has nowhere to go.
+        ...(opts.commentAllowed ? {commentAllowed: opts.commentAllowed} : {}),
         // A receipt verifier needs the signing key before payment. The
         // baseline mock remains byte-for-byte unchanged when receipts are
         // off; a real node-key signer can alternatively be recovered from
@@ -599,6 +647,7 @@ export const createMockMint = async (options = {}) => {
       // before the option existed.
       let boundTo = null
       let echoBound = false
+      let requestedH = null
       if (opts.mintToHash) {
         // absent is not the same as empty: a wallet that sent `h=` meant
         // to bind, and must not be handed an unbound quote in silence
@@ -627,6 +676,7 @@ export const createMockMint = async (options = {}) => {
             return fail('Invalid or already spent k1.')
           }
           if (wellFormed) {
+            requestedH = h
             // The echo says "this quote is bound", so an honest mint
             // sets it exactly when it did bind. mintToHashIgnoresH is the
             // mint that says it and does not; leaving 'quote' out of
@@ -637,6 +687,51 @@ export const createMockMint = async (options = {}) => {
         }
       }
 
+      // The LUD-25 spelling. It is mandatory for every mint quote. The
+      // additive `h` spelling may corroborate it, but never substitutes for
+      // it and must name the same output when both are present.
+      let namedByComment = false
+      // >= 64, the same threshold the runner reads the capability at: a
+      // commentAllowed too short to carry a 32-byte hash is not this
+      // capability, so nothing about it may be required either.
+      if (opts.commentAllowed >= 64) {
+        const sent = q.get('comment')
+        const wellFormed = sent !== null && sent !== '' && /^[0-9a-f]{64}$/i.test(sent)
+        {
+          if (wellFormed) {
+            const h = sent.toLowerCase()
+            // Same collision rule the `h` spelling gets: an id already
+            // spoken for must never be minted over, whichever parameter
+            // named it.
+            if (outputIdInUse(h) && !opts.mintToHashAcceptsUsedH) {
+              return fail('Invalid or already spent k1.')
+            }
+            if (
+              requestedH !== null &&
+              requestedH !== h &&
+              !opts.mintToHashIgnoresH
+            ) {
+              return fail('h and comment must name the same output.')
+            }
+            // The normative comment always binds the quote. The defect flag
+            // only models an extension implementation that ignores or fails
+            // to compare h.
+            boundTo = h
+            namedByComment = true
+          } else if (
+            !opts.commentFallsBack &&
+            !(opts.commentFallsBackWhenAbsent && sent === null)
+          ) {
+            // A mint quote without the mandatory comment can only fall back
+            // to the payment preimage. The current draft forbids that even
+            // when the additive `h` field happened to name an output too.
+            return fail(
+              'Missing or malformed comment: a hex-encoded 32-byte hashed secret is required to mint.'
+            )
+          }
+        }
+      }
+
       const preimage = bytesToHex(randomBytes(32))
       const paymentHash = noteId(preimage)
       const pr = fakeInvoice(amount, preimage)
@@ -647,7 +742,13 @@ export const createMockMint = async (options = {}) => {
       }
       invoices.set(paymentHash, invoice)
       const body = {pr, disposable: false}
-      if (opts.verify) body.verify = `${origin}/verify/${paymentHash}`
+      // Verify is safe for every conforming quote because comment-bound
+      // minting makes the payment preimage ordinary settlement proof. The
+      // conditional remains only so the mock can reproduce the retired
+      // preimage-backed behaviour when commentAllowed is deliberately off.
+      const verifySafe =
+        !(opts.commentAllowed >= 64) || Boolean(boundTo) || opts.verifyOnUnnamedMint
+      if (opts.verify && verifySafe) body.verify = `${origin}/verify/${paymentHash}`
       // Appended last, and only when the quote really was bound, so a
       // mock that was never told about any of this answers byte for byte
       // what it always answered.
@@ -676,11 +777,9 @@ export const createMockMint = async (options = {}) => {
       const body = {
         status: 'OK',
         settled: invoice.settled,
-        // the preimage IS the bearer secret here - a real SERVICE should
-        // think hard before serving it, and a WALLET that receives one
-        // must rotate immediately. The exception is a quote the wallet
-        // bound with its own h: that note is credited elsewhere, so the
-        // preimage is an ordinary payment proof and leaks nothing.
+        // For a conforming comment-bound quote this is ordinary payment
+        // proof and never the bearer secret. It becomes a bearer secret only
+        // in the mock's deliberately non-compliant legacy mode.
         preimage: invoice.settled || opts.verifyLeaksEarly ? invoice.preimage : null,
         pr: invoice.pr ?? fakeInvoice(invoice.amountMsat, invoice.preimage)
       }
@@ -699,6 +798,31 @@ export const createMockMint = async (options = {}) => {
     // ---- LUD-03 informational GET ----
     if (url.pathname === '/w') {
       const k1 = q.get('k1')?.toLowerCase()
+      // The hash lookup. Notes are already keyed by sha256(k1) internally,
+      // so this is a second way in to a lookup the mint can always do - and
+      // `h` is only ever read here, never at the callback, where the same
+      // letter means the hash of a NEW note.
+      const asked = q.get('h')?.toLowerCase()
+      if (!k1 && asked && opts.hashLookup) {
+        if (!/^[0-9a-f]{64}$/.test(asked)) return fail('Unknown note.')
+        const held = notes.get(asked)
+        const invent = opts.hashLookup === 'answersUnknown' && !held
+        if (!invent) {
+          if (!held) return fail('Unknown note.')
+          if (held.state === 'burned') return fail('Note already spent.')
+        }
+        return send({
+          tag: 'withdrawRequest',
+          callback: `${origin}/w/cb`,
+          // k1 is omitted: a wallet asking by hash already holds the secret,
+          // which is the only way it could have computed the hash to send.
+          ...(opts.hashLookup === 'echoesK1' ? {k1: 'c'.repeat(64)} : {}),
+          minWithdrawable: 0,
+          maxWithdrawable: (held?.amountMsat ?? 21000) + opts.lieAboutValue,
+          defaultDescription: 'an LNURLcash note',
+          mintPubkey: pubkey
+        })
+      }
       if (!k1) return fail('Unknown note.')
       if (!/^[0-9a-f]{64}$/.test(k1)) return fail('Unknown note.')
       const note = notes.get(noteId(k1))
@@ -737,6 +861,8 @@ export const createMockMint = async (options = {}) => {
       const h2 = q.get('h2')
 
       if (k1s.length === 0) return fail('Missing k1.')
+      if (opts.acceptsOversizedMerge && k1s.length > 20) return send({status: 'OK'})
+      if (opts.mergeCap > 0 && k1s.length > opts.mergeCap) return fail('too many k1')
       // a repeated k1 would count one note's value twice into the output -
       // refused atomically, as the reference mint does
       if (new Set(k1s).size !== k1s.length) return fail('Invalid or already spent k1.')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lnurlcash-conformance",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Language-neutral conformance vectors, an adversarial mock mint, and a grader for LNURLcash (LUD-25) implementations",
   "author": "TheCryptoDonkey",
   "license": "MIT",