lnurlcash-conformance 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -4,6 +4,80 @@ 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.
 
+## 0.1.2 - 2026-08-21
+
+- The minted-value check took a band instead of a single number, because
+  it was failing the reference implementation.
+  - LUD-25 states the mint fee as `base_fee_msat` plus a ppm cut and says
+    nothing about rounding. dni's lnurl-mint ceilings that fee to a whole
+    sat on purpose, so the mint is "never short a sat"; moneyer is
+    msat-exact. Every public mint on the awesome list except moneyer runs
+    lnurl-mint, so the majority of live services round.
+  - The check asserted equality against the msat-exact formula, and even
+    named the rounding in its failure message as something "the formula
+    does not allow". Measured on real sats: 40,000 msat at
+    mint.forgesworn.dev with a 1000 + 1000 ppm fee credits 38,000, not
+    38,960. A clean grade was unreachable for the reference.
+  - Deciding which reading is right is not this repo's job - "either may
+    be wrong, and the LUD-25 PR is where that gets settled". So the
+    compliant answer is now the range between the two: the formula is the
+    most a holder can be credited, the sat-ceilinged fee the least. The
+    report names which one it saw.
+  - Both edges are graded, and selfgrade proves it: a msat past the
+    ceilinged fee fails, and so does crediting more than the formula. A
+    band with no edges would grade nothing. The mock's `roundFeeToSat` is
+    reclassified from a misbehaviour to the reference's behaviour, and
+    gains `extraFeeMsat` for landing outside the band deliberately.
+
+- Two refusals LUD-25 spells out were never graded. Both are reachable
+  against a live mint, and both were being stepped around rather than
+  tested.
+  - `refuses a split with no h2`: a split names two outputs, so a mint
+    given only `h` either refuses or invents the change note's secret
+    itself. The second is the exact prior-holder exposure wallet-generated
+    secrets exist to close, and it was ungraded.
+  - `refuses a split whose change cannot cover the base fee`: the grader
+    already knew the advertised base fee, and skipped (`note too small to
+    split past the advertised base fee`) rather than deliberately leaving
+    change one msat short of it. It now does that on purpose and expects
+    `insufficient value`. Warns when no fee is advertised, since the rule
+    cannot bite.
+  - Both confirm the note survives the refusal, and both are self-verified:
+    the mock gains `acceptsMissingH2` and `splitIgnoresBaseFee`, and
+    selfgrade asserts each is caught by name rather than by failure count.
+- The grader never melts, so `pending`, restore-on-failure and a melt's own
+  LUD-21 `verify` cannot be graded against a live service - melting real
+  sats is not something a grader may do on its own initiative. The mock
+  covers all three for client-side suites. Said so in the README, which
+  previously left the gap to be inferred.
+
+- `withdrawLink` has two legal spellings in the wild. LUD-25 calls it "a
+  raw, non bech32-encoded URL as described in LUD-17", and LUD-17 describes
+  both the `lnurlw://` scheme and the plain `https://` URL it stands for.
+  lnurl-mint (and the spec's own diagram) emit `https://mint.example/w`;
+  moneyer emits `lnurlw://moneyer.dev/w`. The mock mint only ever served
+  the second, so a client that broke on the reference mint's form would
+  still have passed here.
+  - The mock mint now serves the plain `https://` spelling by default,
+    matching the reference mint, and takes `withdrawLinkForm: 'lnurlw'`
+    for the other. A test asserting the old `lnurlw://` default needs
+    updating (lnurlcash-kit's did).
+  - `pay-request.json` gains accepted cases for the plain form and for an
+    onion host; a parser must pass both through untouched.
+  - The grader accepts either spelling, rejects a bech32 `lnurl1...` value,
+    and names the form in its report. Its three ad-hoc `lnurlw://` rewrites
+    are now one exported `fromLud17`.
+  - Selfgrade runs the compliant mock in both forms.
+
+## 0.1.1 - 2026-08-20
+
+- The mock mint's mint-address response now carries the node stats
+  lnurl-mint advertises: `nodeCapacity` (msat), `nodeNumChannels` and
+  `nodeNumPeers`. `nodeCapacity` is the field an implementation is most
+  likely to rename on its own side and then forget to map - lnurl-wallet
+  and lnurlcash-kit both did, and neither test caught it, because nothing
+  they tested against ever sent the wire name.
+
 ## 0.1.0 - 2026-08-20
 
 First release. Three things, usable independently.

package/README.md

@@ -57,6 +57,7 @@ for (const c of cases) {
 | `withdraw-info.json` | the informational GET, and what makes a response invalid |
 | `pay-request.json` | minting, LUD-11 disposable, LUD-21 verify |
 | `lifecycle.json` | behavioural requirements, as scenarios to drive |
+| `threat-suite.json` | the transport/exposure scorecard — candidate spec options against fixed attacks (non-normative) |
 
 Regenerate with `npm run generate`; check them with `npm test`, which
 verifies every digest recomputes, every declared signature really does
@@ -93,6 +94,7 @@ must survive:
 | `--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 |
 | `--verify=false` | no LUD-21 endpoint at all, not merely unadvertised |
+| `--withdrawLinkForm=lnurlw` | spells `withdrawLink` as `lnurlw://host/w` instead of the plain `https://host/w` the reference mint emits. Both are legal; a client has to take both |
 
 As a library, for your own test suite:
 
@@ -115,7 +117,8 @@ actually did rather than what it said.
 npx lnurlcash-conform mint@example.com
 ```
 
-Read-only by default: resolves the payRequest, checks the `withdrawLink`,
+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
@@ -124,8 +127,14 @@ experimental mint address.
 
 One check needs a real payment, which the runner cannot make on its own.
 Given a freshly minted, never-rotated note and what its mint invoice was
-paid at, it compares the note's value against the fee formula - msat-exact,
-so a fee implementation that quietly rounds up to whole sats is caught:
+paid at, it compares the note's value against the advertised fee:
+
+LUD-25 says nothing about whether that fee rounds, and the two live
+implementations differ. dni's lnurl-mint ceilings it to a whole sat on
+purpose, so the mint is never short a sat; moneyer withholds the
+msat-exact amount. Both pass. The check grades the range between them and
+names which it saw, and a msat outside it either way fails - a mint taking
+more than the ceilinged fee, or crediting more than it advertised.
 
 ```bash
 npx lnurlcash-conform mint@example.com --note='lnurlw://...?k1=...' --paid=500000
@@ -148,12 +157,24 @@ and that a burned secret cannot be replayed. It also probes three adversarial sh
 mint must refuse atomically: a duplicated `k1` (which a careless mint counts
 twice, minting money from nothing), an output hash that collides with an
 existing note id (minting over it hands the output to whoever already knows
-that id's preimage), and a split whose `h` equals `h2` (one id cannot carry
-two notes). And it replays the callback as a POST and as an OPTIONS
+that id's preimage), a split whose `h` equals `h2` (one id cannot carry
+two notes), a split naming only one output hash (a mint that accepts it is
+generating the change secret itself), and a split leaving change one msat
+short of the advertised base fee (which LUD-25 says to refuse with
+`insufficient value`, not to serve at a loss). And it replays the callback as a POST and as an OPTIONS
 preflight - real HTTP stacks send both on their own initiative, so the
 mutating endpoint must answer GET only. After every refusal it confirms the refused note is still
 spendable. Use a small note. Exit code is non-zero if anything failed.
 
+**What the grader cannot reach.** It never melts. Melting spends real sats
+against a real mint, which is not something a grading tool may decide to do,
+so `pending` on a k1 mid-melt, restoring the note when the outgoing payment
+fails, and the melt's own LUD-21 `verify` are all outside what a grade can
+say anything about. They are not unspecified and not untested: the mock mint
+implements every one of them (`meltNeverSettles`, `meltAlwaysFails`), so a
+client suite driving the mock covers the whole melt path. A clean grade
+means the read-only and non-melt mutating surface is compliant, no more.
+
 The grader shares no code with any LNURLcash library — it is written against
 `fetch` and `@noble` directly. A grader that shared an implementation with
 the thing it grades would agree with that implementation's mistakes, which
@@ -171,6 +192,9 @@ Spec and reference implementations, all by dni, all MIT:
 - [lnurl-mint](https://github.com/dni/lnurl-mint) — the reference service
 - [lnurl-wallet](https://github.com/dni/lnurl-wallet) — the reference wallet
 
+Implementations to run these vectors against are indexed in
+[awesome-lnurlcash](https://github.com/TheCryptoDonkey/awesome-lnurlcash).
+
 Contributions of vectors are welcome, particularly from implementers who
 found a case these missed. See [CONTRIBUTING.md](CONTRIBUTING.md).
 

package/llms.txt

@@ -22,6 +22,7 @@ responses.json       classifying replies incl. ambiguous outcomes
 withdraw-info.json   the informational GET
 pay-request.json     minting, LUD-11, LUD-21
 lifecycle.json       behavioural scenarios
+threat-suite.json    transport/exposure scorecard, options vs attacks (non-normative)
 
 ## Mock mint
 
@@ -33,7 +34,8 @@ await mint.close()
 Misbehaviour flags: dropAfterMutation, unconfirmedMutation, malformedJson,
 echoWrongK1, lieAboutValue, signatureLayout=leading, signatures=false,
 serverGeneratedSecrets, meltNeverSettles, meltAlwaysFails, slowMs, sunset,
-baseFeeMsat, feePpm, verify=false.
+baseFeeMsat, feePpm, verify=false, withdrawLinkForm=lnurlw (the lnurlw://
+spelling of withdrawLink; default is the plain https://, as lnurl-mint).
 
 CLI: npx lnurlcash-mock-mint --port=8899  (nothing is payable)
 

package/mock-mint/index.d.ts

@@ -6,6 +6,8 @@ export type SignatureLayout = 'trailing' | 'leading'
 
 export type NoteState = 'outstanding' | 'pending' | 'burned'
 
+export type WithdrawLinkForm = 'lnurlw' | 'plain'
+
 export interface MockMintOptions {
   username?: string
   minSendableMsat?: number
@@ -21,6 +23,12 @@ export interface MockMintOptions {
   signatureLayout?: SignatureLayout
   /** withhold sig/sig2 entirely, as a SERVICE with no funding source does */
   signatures?: boolean
+  /**
+   * How the payRequest spells its withdrawLink. 'plain' (default) is the
+   * fetchable https:// URL the reference mint emits and the spec's diagram
+   * shows; 'lnurlw' is the LUD-17 scheme form. Both are legal; test against both.
+   */
+  withdrawLinkForm?: WithdrawLinkForm
   /** LUD-21 verify endpoint. Off means 404, not merely unadvertised. */
   verify?: boolean
   privateKey?: string
@@ -42,6 +50,14 @@ export interface MockMintOptions {
   meltAlwaysFails?: boolean
   /** non-compliant: generate the replacement secret SERVICE-side and hand it back */
   serverGeneratedSecrets?: boolean
+  /** ceiling the mint fee to a whole sat, as dni's lnurl-mint does; compliant */
+  roundFeeToSat?: boolean
+  /** withhold this many msat on top of the fee, landing outside the compliant band */
+  extraFeeMsat?: number
+  /** non-compliant: accept a split with no h2, generating the change secret instead of refusing */
+  acceptsMissingH2?: boolean
+  /** non-compliant: split without taking the base fee out of change, and so without its floor */
+  splitIgnoresBaseFee?: boolean
   /** delay before responding, in milliseconds */
   slowMs?: number
   /** reject splits and mints, as a mint winding down does */

package/mock-mint/index.mjs

@@ -59,6 +59,13 @@ const DEFAULTS = {
   signatureLayout: 'trailing',
   // withhold sig/sig2 entirely, as a SERVICE with no funding source does
   signatures: true,
+  // how the payRequest spells its withdrawLink. 'plain' is the fetchable
+  // https:// URL the reference mint emits and the spec's diagram shows;
+  // 'lnurlw' is the LUD-17 scheme form some mints emitted under the
+  // draft's looser wording. Both are legal raw, non-bech32 URLs, and a
+  // 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.
@@ -83,9 +90,13 @@ const DEFAULTS = {
   // it back, the exposure LUD-25's h/h2 exists to close
   serverGeneratedSecrets: false,
   // non-compliant: round the total mint fee up to a whole sat, as a fee
-  // implementation that works in sats rather than msat does - the note
-  // mints short of the formula
+  // ceiling the mint fee to a whole sat, as dni's lnurl-mint does on
+  // purpose. Compliant: LUD-25 does not say whether the fee rounds, so
+  // the grader accepts anything between this and the msat-exact formula
   roundFeeToSat: false,
+  // beyond the band: withhold this much on top of the ceilinged fee, the
+  // one thing the minted-value check must still catch
+  extraFeeMsat: 0,
   // non-compliant: serve the preimage from /verify before settlement. On
   // a mint that value IS the bearer secret of the note the payment will
   // create, so this hands the note to anyone holding the payment hash
@@ -133,6 +144,7 @@ export const createMockMint = async (options = {}) => {
       Math.floor(((gross % 1e6) * opts.feePpm) / 1e6)
     let fee = opts.baseFeeMsat + proportional
     if (opts.roundFeeToSat) fee = Math.ceil(fee / 1000) * 1000
+    fee += opts.extraFeeMsat
     return Math.max(0, gross - fee)
   }
 
@@ -276,7 +288,8 @@ export const createMockMint = async (options = {}) => {
         minSendable: minSendableMsat,
         maxSendable: opts.maxSendableMsat,
         metadata: JSON.stringify(metadata),
-        withdrawLink: `lnurlw://${req.headers.host}/w`,
+        withdrawLink:
+          opts.withdrawLinkForm === 'plain' ? `${origin}/w` : `lnurlw://${req.headers.host}/w`,
         disposable: false
       })
     }
@@ -298,7 +311,14 @@ export const createMockMint = async (options = {}) => {
         mintPubkey: pubkey,
         nodeAlias: 'mock-mint',
         nodeUri: `${pubkey}@127.0.0.1:9735`,
-        nodeColor: '#ff9900'
+        nodeColor: '#ff9900',
+        // The node stats lnurl-mint advertises. `nodeCapacity` is msat, like
+        // every other amount, and is named without the suffix on the wire -
+        // an implementation that renames it on its own side has to map it,
+        // and one that spreads the response through will read undefined.
+        nodeCapacity: 500_000_000,
+        nodeNumChannels: 4,
+        nodeNumPeers: 6
       })
     }
 
@@ -437,7 +457,10 @@ export const createMockMint = async (options = {}) => {
       }
 
       if (!h) return fail('missing h')
-      if (amountRaw !== null && !h2) return fail('missing h2')
+      // opts.acceptsMissingH2: the misbehaviour where a SERVICE fills in the
+      // change note's secret itself rather than refusing. Whoever runs the
+      // mint is then a prior holder of half the split.
+      if (amountRaw !== null && !h2 && !opts.acceptsMissingH2) return fail('missing h2')
       if (!/^[0-9a-f]{64}$/.test(h)) return fail('missing h')
       if (h2 && !/^[0-9a-f]{64}$/.test(h2)) return fail('missing h2')
       // One id cannot carry two notes, and an id already in use - as a note
@@ -469,8 +492,16 @@ export const createMockMint = async (options = {}) => {
         // change that cannot cover the fee, or would land at exactly
         // nothing, refuses with the spec's own reason.
         const changeBeforeFee = total - amount
-        if (changeBeforeFee < opts.baseFeeMsat) return fail('insufficient value')
-        const change = changeBeforeFee - opts.baseFeeMsat
+        // opts.splitIgnoresBaseFee: the misbehaviour where a SERVICE never
+        // learned the split-fee rule at all - no fee out of change, and so
+        // no floor to refuse against either.
+        let change
+        if (opts.splitIgnoresBaseFee) {
+          change = changeBeforeFee
+        } else {
+          if (changeBeforeFee < opts.baseFeeMsat) return fail('insufficient value')
+          change = changeBeforeFee - opts.baseFeeMsat
+        }
         if (change < 1) return fail('insufficient value')
         for (const {note} of found) note.state = 'burned'
         const sig = mintNote(h, amount)

package/package.json

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

package/runner/index.mjs

@@ -42,6 +42,19 @@ const verifySignature = (k1, amountMsat, signatureHex, pubkeyHex) => {
   return false
 }
 
+// LUD-17: lnurlw://host/path is https://host/path, or http:// when the host
+// is an onion service (the spec) or loopback (development). A plain
+// https:// or http:// URL passes through untouched, so a caller can hand
+// this either form a SERVICE emits.
+export const fromLud17 = value => {
+  const v = String(value).trim()
+  if (!/^lnurl[wpc]:\/\//i.test(v)) return v
+  const rest = v.slice(v.indexOf('://') + 3)
+  const host = rest.split(/[/?#]/, 1)[0].replace(/:\d+$/, '').toLowerCase()
+  const plain = ['localhost', '127.0.0.1', '0.0.0.0'].includes(host) || host.endsWith('.onion')
+  return (plain ? 'http://' : 'https://') + rest
+}
+
 const isAllowedUrl = value => {
   let url
   try {
@@ -187,9 +200,21 @@ export const gradeMint = async (payUrl, report) => {
       typeof pay.withdrawLink === 'string',
       'no withdrawLink - this is an ordinary payRequest, not an LNURLcash mint'
     )
-    const resolved = pay.withdrawLink.replace(/^lnurlw:\/\//i, 'https://')
-    assert(isAllowedUrl(resolved), `withdrawLink is not fetchable: ${pay.withdrawLink}`)
-    return pay.withdrawLink
+    const link = pay.withdrawLink.trim()
+    assert(
+      !/^lnurl1/i.test(link),
+      'withdrawLink is bech32-encoded - LUD-25 wants the raw URL, not an LNURL'
+    )
+    // Both forms are in the wild: lnurl-mint emits the plain https:// URL
+    // (as the spec's own diagram does), moneyer the lnurlw:// LUD-17 form.
+    // Either is a raw, non-bech32 URL; a WALLET has to take both.
+    const form = /^lnurlw:\/\//i.test(link) ? 'lnurlw:// form' : 'plain URL form'
+    assert(
+      /^(lnurlw|https?):\/\//i.test(link),
+      `withdrawLink has an unexpected scheme: ${link}`
+    )
+    assert(isAllowedUrl(fromLud17(link)), `withdrawLink is not fetchable: ${link}`)
+    return `${link} (${form})`
   })
 
   await report.check('metadata parses, and any fee advertisement is valid', async () => {
@@ -250,9 +275,7 @@ export const gradeMint = async (payUrl, report) => {
   })
 
   await report.check('reports an unknown note distinguishably', async () => {
-    const withdrawUrl = (pay.withdrawLink ?? '').replace(/^lnurlw:\/\//i, m =>
-      /localhost|127\.0\.0\.1|\.onion/.test(pay.withdrawLink) ? 'http://' : 'https://'
-    )
+    const withdrawUrl = pay.withdrawLink ? fromLud17(pay.withdrawLink) : ''
     if (!withdrawUrl) throw soft('no withdrawLink to probe')
     const url = new URL(withdrawUrl)
     url.searchParams.set('k1', bytesToHex(randomBytes(32)))
@@ -294,25 +317,40 @@ export const gradeMint = async (payUrl, report) => {
 export const gradeMintedValue = async (noteUrl, report, {mintFee = null, paidMsat}) => {
   await report.check('a minted note is worth the amount paid minus the fee', async () => {
     assert(Number.isFinite(paidMsat) && paidMsat > 0, `paidMsat was ${paidMsat}`)
-    const url = new URL(noteUrl.replace(/^lnurlw:\/\//i, m =>
-      /localhost|127\.0\.0\.1|\.onion/.test(noteUrl) ? 'http://' : 'https://'
-    ))
+    const url = new URL(fromLud17(noteUrl))
     const info = await get(url)
     assert(info.status !== 'ERROR', `refused: ${info.reason}`)
     assert(Number.isFinite(info.maxWithdrawable), 'no maxWithdrawable')
-    const expected = applyMintFee(paidMsat, mintFee)
+    const exact = applyMintFee(paidMsat, mintFee)
     const feeText = mintFee
       ? `${mintFee.baseFeeMsat} msat + ${mintFee.feePpm} ppm`
       : 'no advertised fee'
-    const satRounded = expected - (expected % 1000)
+    // LUD-25 gives the fee as base plus a ppm cut and says nothing about
+    // rounding, and the two live implementations read that differently:
+    // dni's lnurl-mint - the reference, and what every public mint but
+    // moneyer runs - ceilings the fee to a whole sat on purpose, moneyer
+    // is msat-exact. Grading either as a failure would be this repo
+    // picking a side the draft has not picked. So the compliant answer is
+    // a band: the formula is the most a holder can be credited, the
+    // sat-ceilinged fee the least. Anything outside is still wrong, which
+    // is what this check is for.
+    const exactFee = paidMsat - exact
+    const ceilinged = Math.max(0, paidMsat - Math.ceil(exactFee / 1000) * 1000)
+    assert(
+      info.maxWithdrawable <= exact,
+      `paid ${paidMsat} msat against ${feeText}: the note holds ${info.maxWithdrawable} msat, more than the ${exact} the formula allows`
+    )
     assert(
-      info.maxWithdrawable === expected,
-      `paid ${paidMsat} msat against ${feeText}: the formula nets ${expected} msat, the note holds ${info.maxWithdrawable}` +
-        (info.maxWithdrawable === satRounded && satRounded !== expected
-          ? ' - consistent with the fee being rounded up to a whole sat, which the formula does not allow'
-          : '')
+      info.maxWithdrawable >= ceilinged,
+      `paid ${paidMsat} msat against ${feeText}: the note holds ${info.maxWithdrawable} msat, short of ${ceilinged} - beyond even a fee ceilinged to a whole sat`
     )
-    return `${paidMsat} msat paid -> ${info.maxWithdrawable} msat note (${feeText})`
+    const how =
+      info.maxWithdrawable === exact
+        ? 'msat-exact'
+        : info.maxWithdrawable === ceilinged
+          ? 'fee ceilinged to a whole sat, as the reference mint does'
+          : 'inside the band'
+    return `${paidMsat} msat paid -> ${info.maxWithdrawable} msat note (${feeText}, ${how})`
   })
 }
 
@@ -328,9 +366,7 @@ export const gradeMintedValue = async (noteUrl, report, {mintFee = null, paidMsa
 // every split's change, and a merge of n notes refunds (n - 1) base fees.
 export const gradeNote = async (noteUrl, report, options = {}) => {
   const knownBaseFee = 'mintFee' in options ? (options.mintFee?.baseFeeMsat ?? 0) : null
-  const url = new URL(noteUrl.replace(/^lnurlw:\/\//i, m =>
-    /localhost|127\.0\.0\.1|\.onion/.test(noteUrl) ? 'http://' : 'https://'
-  ))
+  const url = new URL(fromLud17(noteUrl))
   const k1 = url.searchParams.get('k1')?.toLowerCase()
   assert(k1 && /^[0-9a-f]{64}$/.test(k1), 'that note carries no 32-byte hex k1')
 
@@ -383,6 +419,23 @@ export const gradeNote = async (noteUrl, report, options = {}) => {
     return body.reason
   })
 
+  await report.check('refuses a split with no h2', async () => {
+    const cb = new URL(info.callback)
+    cb.searchParams.append('k1', k1)
+    cb.searchParams.append('amount', String(Math.max(1, Math.floor(info.maxWithdrawable / 2))))
+    cb.searchParams.append('h', noteId(bytesToHex(randomBytes(32))))
+    const body = await get(cb)
+    assert(
+      body.status === 'ERROR',
+      'accepted a split with only one output hash - the change note has nowhere to go but a SERVICE-generated secret'
+    )
+    const after = new URL(url)
+    after.searchParams.set('k1', k1)
+    const still = await get(after)
+    assert(still.status !== 'ERROR', `a refused split burned the note anyway: ${still.reason}`)
+    return body.reason
+  })
+
   let current = k1
   let currentSig = null
   await report.check('rotate mints a note the service never saw the secret of', async () => {
@@ -537,6 +590,37 @@ export const gradeNote = async (noteUrl, report, options = {}) => {
     return 'POST and OPTIONS left the note untouched'
   })
 
+  await report.check('refuses a split whose change cannot cover the base fee', async () => {
+    if (knownBaseFee === null) throw soft('fee unknown - pass --paid to grade the fee rules')
+    if (knownBaseFee === 0) throw soft('no base fee advertised, so the rule cannot bite')
+    // Leave the change one msat short of the base fee. LUD-25 says fail the
+    // whole split rather than hand back a change note worth less than the
+    // fee that was meant to come out of it.
+    const amount = info.maxWithdrawable - knownBaseFee + 1
+    if (amount < 1 || amount >= info.maxWithdrawable) {
+      throw soft('note too small to leave change short of the base fee')
+    }
+    const cb = new URL(info.callback)
+    cb.searchParams.append('k1', current)
+    cb.searchParams.append('amount', String(amount))
+    cb.searchParams.append('h', noteId(bytesToHex(randomBytes(32))))
+    cb.searchParams.append('h2', noteId(bytesToHex(randomBytes(32))))
+    const body = await get(cb)
+    assert(
+      body.status === 'ERROR',
+      `accepted a split leaving ${info.maxWithdrawable - amount} msat of change against a ${knownBaseFee} msat base fee`
+    )
+    const after = new URL(url)
+    after.searchParams.set('k1', current)
+    const still = await get(after)
+    assert(still.status !== 'ERROR', `a refused split burned the note anyway: ${still.reason}`)
+    assert(
+      still.maxWithdrawable === info.maxWithdrawable,
+      `a refused split changed the note's value: ${info.maxWithdrawable} -> ${still.maxWithdrawable}`
+    )
+    return body.reason
+  })
+
   await report.check('split conserves value', async () => {
     const half = Math.floor(info.maxWithdrawable / 2)
     if (half < 1) throw soft('note too small to split')

package/vectors/index.json

@@ -15,6 +15,7 @@
     "responses.json",
     "withdraw-info.json",
     "pay-request.json",
-    "lifecycle.json"
+    "lifecycle.json",
+    "threat-suite.json"
   ]
 }

package/vectors/pay-request.json

@@ -16,6 +16,34 @@
       "withdrawLink": "lnurlw://mint.example/w",
       "mintFee": null
     },
+    {
+      "name": "withdrawLink in plain URL form",
+      "body": {
+        "tag": "payRequest",
+        "callback": "https://mint.example/p/cb",
+        "minSendable": 1000,
+        "maxSendable": 100000000,
+        "metadata": "[[\"text/plain\",\"a mint\"],[\"text/identifier\",\"mint@mint.example\"]]",
+        "withdrawLink": "https://mint.example/w"
+      },
+      "withdrawLink": "https://mint.example/w",
+      "mintFee": null,
+      "why": "LUD-25 says a raw, non-bech32 URL \"as described in LUD-17\", and LUD-17 describes both the lnurlw:// scheme and the plain URL it stands for. lnurl-mint, and the spec diagram, use this form; moneyer uses lnurlw://. A WALLET MUST accept either, unchanged, and resolve it through the same LUD-17 rule as any other input"
+    },
+    {
+      "name": "withdrawLink on an onion service",
+      "body": {
+        "tag": "payRequest",
+        "callback": "http://mintmintmintmintmintmintmintmintmintmintmintmintmintmi.onion/p/cb",
+        "minSendable": 1000,
+        "maxSendable": 100000000,
+        "metadata": "[[\"text/plain\",\"a mint\"]]",
+        "withdrawLink": "lnurlw://mintmintmintmintmintmintmintmintmintmintmintmintmintmi.onion/w"
+      },
+      "withdrawLink": "lnurlw://mintmintmintmintmintmintmintmintmintmintmintmintmintmi.onion/w",
+      "mintFee": null,
+      "why": "the parser passes the link through; resolution to http:// happens when a note is built from it (see note-url.json build)"
+    },
     {
       "name": "with an advertised fee",
       "body": {

package/vectors/threat-suite.json

@@ -0,0 +1,327 @@
+{
+  "version": 1,
+  "spec": "LUD-25 draft (lnurl/luds#301)",
+  "description": "The transport/exposure scorecard from the LUD-25 design debate: candidate spec options measured against a fixed set of attacks, so proposed changes are argued against the same scenarios instead of in the abstract. NON-NORMATIVE - option A is the current draft and every other option is a proposal, marked as such below; only rows with status \"pins-current\" describe behavior the draft already requires, and rows pinning today's vulnerable behavior exist to be INVERTED by the PR landing the named option. The executable twin of this file is lnurl-mint's tests/test_bearer_threat_suite_poc.py (dni/lnurl-mint#22).",
+  "options": {
+    "A": {
+      "name": "status quo",
+      "status": "current-draft",
+      "summary": "lnurl/luds#301 as drafted"
+    },
+    "B": {
+      "name": "comment-secret",
+      "status": "proposal",
+      "summary": "A + a secret the WALLET attaches to the payRequest (LUD-12 comment), encrypted to the mint; the note's k1 becomes \"<secret>:<preimage>\" and the public LUD-21 preimage alone no longer redeems"
+    },
+    "C": {
+      "name": "?p= everywhere",
+      "status": "proposal",
+      "summary": "every k1 replaced in transport by that k1 encrypted to the mint"
+    },
+    "D": {
+      "name": "hash-keyed informational GET",
+      "status": "proposal",
+      "summary": "A + poll /w by sha256(k1), never k1"
+    },
+    "E": {
+      "name": "blinded signatures",
+      "status": "proposal",
+      "summary": "the chaumian model"
+    },
+    "F": {
+      "name": "B + D",
+      "status": "proposal",
+      "summary": "comment-secret plus the hash-keyed informational GET"
+    },
+    "G": {
+      "name": "locked notes",
+      "status": "proposal",
+      "summary": "a second asset class, not a bearer variant: redemption requires an LUD-04 signature from the LUD-05/LUD-13 linkingKey registered at mint/rotate time, over the FULL redemption request (k1, h/h2, amount/pr), so logged signatures are not replayable. Scored separately per scenario as lockedNotes, because the trades differ by note type"
+    }
+  },
+  "policy": {
+    "redGreen": "Scenarios asserting today's vulnerable behavior are pins that must be INVERTED by the PR landing the named option, mirroring the INVERTS WHEN policy in this file's executable companion, lnurl-mint's tests/test_bearer_threat_suite_poc.py (dni/lnurl-mint#22): that PR flips the pin red and forces the assertion to be rewritten against the fixed behavior. Controls (T4, T5) assert behavior that must never change.",
+    "coreTheorem": "Re-encrypting a bearer credential to the party that redeems it never shrinks its exposure set: the mint honors the ciphertext, so the ciphertext IS the note. The only encryption that helps is encrypting to the holder, which kills bearer-ness - option G takes that trade deliberately, via signatures rather than ciphertext.",
+    "seedRecoverableNotes": "A WALLET deriving note secrets deterministically (BIP85, or an LUD-05-style HMAC path plus a counter) can restore outstanding notes from the seed via hash-keyed lookup - option D doubles as the restore API. Restore covers device loss, NOT theft: anyone who copied a circulating note may have spent it long before the restore runs. One derivation convention must be pinned in the spec, or wallets fragment and restores silently miss notes."
+  },
+  "scenarios": [
+    {
+      "id": "T1",
+      "name": "verify race",
+      "kind": "attack",
+      "adversary": "anyone who saw the unpaid mint invoice - the payment hash travels inside it",
+      "steps": [
+        "observe an unpaid mint invoice and extract its payment hash",
+        "poll the LUD-21 verify endpoint until the invoice settles",
+        "take the disclosed preimage the moment it settles",
+        "rotate the note before the payer does"
+      ],
+      "currentBehavior": "succeeds when verify is on",
+      "options": {
+        "closedBy": [
+          "B",
+          "F"
+        ],
+        "notClosedBy": [
+          "C",
+          "E"
+        ],
+        "lockedNotes": "closed - the note is locked to its linkingKey from birth, so a racer holding only P cannot redeem"
+      },
+      "status": "inverts-when-option-B",
+      "notes": "C does not close it: encrypting to the mint is a public operation (mintPubkey is advertised), so the racer wraps the leaked preimage himself and replays. E does not either: the race becomes \"whoever presents P plus a blinded B first gets the signature\"."
+    },
+    {
+      "id": "T2",
+      "name": "routing-node race",
+      "kind": "attack",
+      "adversary": "every routing hop on the mint payment's path - each learns the preimage as the HTLC settles",
+      "steps": [
+        "sit on the payment path of a mint invoice",
+        "learn the preimage as the settling HTLC propagates back",
+        "rotate before the payer"
+      ],
+      "currentBehavior": "succeeds even with VERIFY_ENABLED=false - no spec endpoint is involved",
+      "options": {
+        "closedBy": [
+          "B",
+          "F"
+        ],
+        "lockedNotes": "closed for locked notes only"
+      },
+      "status": "inverts-when-option-B",
+      "notes": "The same outcome as T1 with no verify at all: the preimage leaks from the payment protocol itself, not from any endpoint."
+    },
+    {
+      "id": "T3",
+      "name": "poll-log replay",
+      "kind": "attack",
+      "adversary": "anyone reading whatever retains request URLs - a proxy, an access log, browser history",
+      "steps": [
+        "the holder polls the informational GET /w?k1=<live note>",
+        "the poll burns nothing, so the SPENDABLE k1 is left in the log",
+        "the reader replays it into a rotate"
+      ],
+      "currentBehavior": "succeeds - every value poll leaves the SPENDABLE k1 in whatever retains request URLs",
+      "options": {
+        "closedBy": [
+          "D",
+          "F"
+        ],
+        "notClosedBy": [
+          "C"
+        ],
+        "lockedNotes": "closed - a logged k1 is useless without the key"
+      },
+      "status": "inverts-when-option-D",
+      "notes": "D leaves only a harmless hash in those logs. C does not close it: a logged p redeems exactly like a logged k1 - the mint honors the ciphertext, so the ciphertext IS the note."
+    },
+    {
+      "id": "T4",
+      "name": "callback-log replay",
+      "kind": "control",
+      "adversary": "anyone reading a logged mutating callback URL",
+      "steps": [
+        "a k1 is captured from a MUTATING callback URL",
+        "the request it rode in on already burned it",
+        "replay it later"
+      ],
+      "currentBehavior": "fails with \"Invalid or already spent k1.\" - the burn from the original request is the protection",
+      "options": {
+        "holdsUnder": [
+          "A",
+          "B",
+          "C",
+          "D",
+          "E",
+          "F",
+          "G"
+        ]
+      },
+      "status": "pins-current",
+      "notes": "Must hold under every option. A replay landing in the same millisecond as the original is a plain race, not a logging problem."
+    },
+    {
+      "id": "T5",
+      "name": "note at rest",
+      "kind": "control",
+      "adversary": "whoever finds the note URL - chat history, a screenshot, a printed QR",
+      "steps": [
+        "find a note URL at rest",
+        "spend it"
+      ],
+      "currentBehavior": "the finder spends it - a note URL at rest IS the money",
+      "options": {
+        "notClosedBy": [
+          "A",
+          "B",
+          "C",
+          "D",
+          "E",
+          "F"
+        ],
+        "lockedNotes": "beaten - the only option that beats the at-rest axiom, precisely because it surrenders bearer-ness"
+      },
+      "status": "pins-current",
+      "notes": "The bearer axiom: every bearer option \"fails\" this by design, and the all-minus row is deliberate. Any future option claiming to fix at-rest exposure has to answer this scenario first."
+    },
+    {
+      "id": "T6",
+      "name": "operator correlation",
+      "kind": "property",
+      "adversary": "the mint operator",
+      "steps": [
+        "at rotate, the WALLET discloses h = sha256(new_k1)",
+        "the mint keys its storage by h",
+        "a later spend of new_k1 matches the recorded h"
+      ],
+      "currentBehavior": "issuance links to redemption - a full transaction graph at the operator",
+      "options": {
+        "closedBy": [
+          "E"
+        ],
+        "notClosedBy": [
+          "A",
+          "B",
+          "C",
+          "D",
+          "F"
+        ],
+        "lockedNotes": "open - the operator knows exactly which key owns which notes"
+      },
+      "status": "privacy-axis",
+      "notes": "h-preimages give log confidentiality (T4) but not unlinkability from the operator; only blinded issuance closes this."
+    },
+    {
+      "id": "T7",
+      "name": "legacy LUD-03 melt",
+      "kind": "property",
+      "adversary": "none - a compatibility property",
+      "steps": [
+        "a wallet that knows nothing of LNURLcash melts a note to a BOLT-11 pr, as plain LUD-03"
+      ],
+      "currentBehavior": "works - the note melts to a BOLT-11 pr as plain LUD-03",
+      "options": {
+        "preservedBy": [
+          "A",
+          "B",
+          "D",
+          "E",
+          "F"
+        ],
+        "brokenBy": [
+          "C"
+        ],
+        "lockedNotes": "broken - a plain LUD-03 wallet cannot lnurl-auth, so locked notes have no legacy story"
+      },
+      "status": "pins-current",
+      "notes": "C breaks it because legacy wallets cannot encrypt - unless mixed mode re-admits plaintext k1, which voids C's only claim."
+    },
+    {
+      "id": "T8",
+      "name": "first-contact offline verify",
+      "kind": "gap",
+      "adversary": "an attacker who self-signs a note and supplies their own key",
+      "steps": [
+        "a recipient who has never interacted with this mint receives a note",
+        "it has no mintPubkey on record, so it cannot verify the note's sig offline",
+        "embedding the pubkey in the note URL proves nothing - an attacker self-signs and supplies their own key"
+      ],
+      "currentBehavior": "no offline verification on first contact - a spec-level gap, no endpoint to hit",
+      "options": {
+        "closedBy": []
+      },
+      "status": "spec-gap",
+      "notes": "No option on the scorecard addresses this; it needs a key-distribution story, not a transport change."
+    },
+    {
+      "id": "T9",
+      "name": "comment silently ignored",
+      "kind": "gap",
+      "adversary": "none - a silent downgrade hazard, not an attacker",
+      "steps": [
+        "a wallet already sending a LUD-12 comment calls the payRequest callback",
+        "the callback takes no comment param and unknown query params are dropped silently",
+        "the wallet gets a bare k1=P note with verify advertised anyway"
+      ],
+      "currentBehavior": "a silent downgrade with no signal to the wallet",
+      "options": {
+        "closedBy": [
+          "B",
+          "F"
+        ]
+      },
+      "status": "inverts-when-option-B",
+      "notes": "Option B must define semantics - fail-closed (reject the callback) or fallback (k1=P, no verify for that invoice) - never silent."
+    },
+    {
+      "id": "T10",
+      "name": "merge URL budget",
+      "kind": "property",
+      "adversary": "none - pure URL arithmetic",
+      "steps": [
+        "build a merge callback carrying one k1 per input note plus h for the result",
+        "compare its length against the ~2000-character practical GET budget LUD-12 itself notes"
+      ],
+      "currentBehavior": "a merge of 25 notes fits in plaintext hex k1s (64 chars each)",
+      "options": {
+        "preservedBy": [
+          "A",
+          "B",
+          "D",
+          "E",
+          "F"
+        ],
+        "brokenBy": [
+          "C"
+        ]
+      },
+      "arithmetic": {
+        "budgetChars": 2000,
+        "exampleCallback": "https://mint.example/w/cb",
+        "plaintextK1Chars": 64,
+        "encryptedK1": {
+          "layout": "33-byte ephemeral pubkey + 12-byte nonce + 32-byte ciphertext + 16-byte tag",
+          "bytes": 93,
+          "base64Chars": 124
+        },
+        "mergeOf25": {
+          "plaintextChars": 1792,
+          "plaintextFits": true,
+          "encryptedChars": 3267,
+          "encryptedFits": false
+        },
+        "mergeCapacity": {
+          "plaintext": 28,
+          "encrypted": 15,
+          "advertisedMaxK1s": 100
+        }
+      },
+      "status": "arithmetic",
+      "notes": "The same merge with every k1 swapped for an encrypted-to-the-mint blob (option C) does not fit. max_k1s=100 is unreachable in BOTH variants under the budget - plaintext caps at 28, blobs at 15 - so C would halve the merge ceiling in exchange for nothing, per T1/T2/T3."
+    },
+    {
+      "id": "T11",
+      "name": "offline handoff",
+      "kind": "property",
+      "adversary": "none - the bearer property itself",
+      "steps": [
+        "hand a bearer note to its next holder with no mint contact at handoff time"
+      ],
+      "currentBehavior": "works - the spec's Offline circulation section",
+      "options": {
+        "preservedBy": [
+          "A",
+          "B",
+          "C",
+          "D",
+          "E",
+          "F"
+        ],
+        "lockedNotes": "lost - transfer requires an online re-lock via the mint"
+      },
+      "status": "pins-current",
+      "notes": "Structural, no endpoint. Locked notes are registered claims, not cash; the bearer core and locked notes are complements, not competitors."
+    }
+  ]
+}