lnurlcash-conformance 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,102 @@ 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.6.0 - 2026-09-03
+
+**Offline verification and mutation replay now grade the current LUD-25
+MUSTs.** A rotate, split or merge without a valid note signature fails rather
+than warning, as does a byte-identical retry that is answered as already
+spent. The conforming mock now replays mutations by default; `signatures=false`
+and `retriedMutation=refuse` remain explicit adversarial fixtures.
+
+The optional hash lookup is also checked end to end once a mint offers it.
+The runner requires exactly one of `k1` and `h`, compares the unknown-h response
+with an unknown-k1 response, then burns the original note and confirms its hash
+still gets that same unknown-note answer. This catches the privacy leak where a
+mint answers a burned `h` as already spent. The mock gains separate
+`revealsSpent` and `acceptsBoth` fixtures proving those checks fail.
+
+The signature vectors now describe `mintPubkey` as a stable SERVICE key. It may
+be the funding node identity where compatible signing exists, or a dedicated,
+persistent secp256k1 key where it does not.
+
+**The client-facing vectors carry the same MUSTs.** They had been left behind
+by the prose, still describing a signature as one accepted shape among
+several, so a wallet library could pass every vector while ignoring the
+requirement entirely.
+
+`withdraw-info.json` now puts `mintPubkey` on every accepted withdrawRequest
+and rejects a response that omits it or publishes something that is not a
+33-byte compressed secp256k1 key. A wallet handed a note by a mint that
+publishes no key has nothing to verify it against, which is the gap offline
+verification exists to close.
+
+`responses.json` gains an `unverifiable` outcome for a mutation the SERVICE
+confirms but does not sign. It is deliberately not folded into the existing
+`error` or `ambiguous` outcomes: the mutation definitely landed, so the
+wallet-generated secret is the only key to a real note and must be kept, and
+a consumer that treats this as an ordinary failure loses the money it is
+trying to protect. Every case now also declares the `op` it is driven
+through, because a melt mints nothing and so needs no signature, while a
+rotate returning none is the new outcome.
+
+**The mock mint starts when its path reaches it through a symlink.** The
+standalone guard compared `import.meta.url` against `file://` plus
+`process.argv[1]`, and node resolves a module's URL to its real path while
+argv[1] stays exactly as it was typed. A checkout symlinked into a sibling
+workspace - which is how the language ports pick this repo up locally - failed
+that comparison, so the mint exited silently, printing nothing at all. Every
+port's adversarial suite then hung to EOF and reported the mint as never having
+announced itself, which says nothing about the cause. CI, checking the repo out
+for real, was never affected, so this only ever broke the local run.
+
+## 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

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) |
 
@@ -92,7 +92,7 @@ must survive:
 | `--echoWrongK1` | answers the informational GET with a different `k1` |
 | `--lieAboutValue=N` | reports a `maxWithdrawable` it never signed |
 | `--signatureLayout=leading` | emits the recovery id at the other end |
-| `--signatures=false` | issues no signatures at all |
+| `--signatures=false` | deliberately violates LUD-25 by issuing no signatures |
 | `--serverGeneratedSecrets` | hands back a secret it generated — the exposure `h` exists to close |
 | `--meltNeverSettles` | holds every melt in flight, so notes stay `pending` |
 | `--meltAlwaysFails` | fails every payment, restoring the note |
@@ -100,24 +100,27 @@ 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 |
+| `--retriedMutation=refuse` | deliberately answers an identical mutation retry as already spent instead of replaying its original success |
+| `--hashLookup=echoesK1` | offers hash lookup but puts a `k1` back in the response |
+| `--hashLookup=answersUnknown` | offers hash lookup but invents a note for an unknown hash |
+| `--hashLookup=revealsSpent` | offers hash lookup but distinguishes a burned hash from an unknown note |
+| `--hashLookup=acceptsBoth` | offers hash lookup but accepts `k1` and `h` together |
 | `--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
 capability cannot misuse it.
-| `--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 |
 
-Five behaviours are outside LUD-25 and outside that table, because none
-of them is misbehaviour. All are absent or off unless you ask
-for them, so a mock started with no options answers exactly what it always
-answered:
+The remaining flags enable optional features, legal wire variants, or make a
+conforming default explicit. Optional fields stay absent unless requested:
 
 | Flag | What it does |
 | --- | --- |
+| `--verify=false` | provides no LUD-21 endpoint at all, rather than merely leaving it 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 |
 | `--name --description --contact --tosUrl --motd --version` | mint info on the experimental discovery endpoint: who runs this, how to reach them, the terms, and what the operator wants holders to know today |
 | `--baseFeeMsat --feePpm` | also publishes `fees: {baseFeeMsat, feePpm}` on that endpoint, the structured twin of the fee line in the payRequest metadata |
 | `--stats` | serves `GET /stats`: what the mint owes, what is in flight, what the node holds, and the coverage between them |
@@ -125,8 +128,9 @@ answered:
 | `--previousPubkeys=a,b` | keys this mint has signed under before, so notes issued before a rotation still verify |
 | `--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 |
+| `--retriedMutation=replay` | answers a byte-identical repeat of a mutation with the original success. This is the conforming default; use `refuse` only as an adversarial fixture |
+| `--hashLookup=true` | accepts an informational lookup by `h=sha256(k1)` without returning the bearer secret. Off by default because the capability is optional |
+| `--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 +159,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
@@ -243,8 +227,7 @@ advertised `mintPubkey` or any key the mint still publishes as a previous
 one, that split and merge conserve value - exactly,
 under LUD-25's fee algebra, when the mint's fee advertisement is known -
 that a byte-identical repeat of a mutation is answered with the original
-success rather than as an already-spent input (a SHOULD, so a mint that
-has not implemented it is reported as such rather than failed), and that a
+success rather than as an already-spent input, and that a
 burned secret cannot be replayed. It also probes three adversarial shapes a
 mint must refuse atomically: a duplicated `k1` (which a careless mint counts
 twice, minting money from nothing), an output hash that collides with an

package/mock-mint/index.d.ts

@@ -10,6 +10,13 @@ export type WithdrawLinkForm = 'lnurlw' | 'plain'
 
 export type RetriedMutation = 'refuse' | 'replay'
 
+export type HashLookup =
+  | boolean
+  | 'echoesK1'
+  | 'answersUnknown'
+  | 'revealsSpent'
+  | 'acceptsBoth'
+
 /** where a mint claims it accepts an `h` on its pay callback */
 export type MintToHashPlace = 'payRequest' | 'mintAddress' | 'quote'
 
@@ -26,7 +33,7 @@ export interface MockMintOptions {
    * signmessage output unreordered.
    */
   signatureLayout?: SignatureLayout
-  /** withhold sig/sig2 entirely, as a SERVICE with no funding source does */
+  /** non-compliant: withhold the mandatory sig/sig2 */
   signatures?: boolean
   /**
    * How the payRequest spells its withdrawLink. 'plain' (default) is the
@@ -124,27 +131,27 @@ export interface MockMintOptions {
   /**
    * What a retried mutation gets. A rotate, split or merge is a GET and
    * HTTP stacks retry a GET on a dropped connection, so a SERVICE sees
-   * the byte-identical request twice. 'refuse' (default) answers the
-   * second one as an already-spent input; 'replay' answers it with the
-   * original success, which is what stops a holder discarding a note the
-   * SERVICE really did mint. Identical means the same input k1 set, the
+   * the byte-identical request twice. 'replay' (default) returns the
+   * original success as LUD-25 requires; 'refuse' is the non-compliant
+   * fixture. Identical means the same input k1 set, the
    * same h, the same h2 and the same amount; anything else naming a
    * burned input is refused exactly as before.
    */
   retriedMutation?: RetriedMutation
+  /**
+   * Optional informational lookup by sha256(k1). `true` is conforming;
+   * string values reproduce distinct non-compliant responses.
+   */
+  hashLookup?: HashLookup
   /** serve GET /stats, the liabilities endpoint. Off means 404, as before. */
   stats?: boolean
   /** 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 +183,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
   /**
@@ -236,8 +241,8 @@ export interface MockMintState {
   opts: Required<MockMintOptions>
   /**
    * Fund a note directly, bypassing the minting flow. Returns the note's
-   * signature, or undefined when this mint was started with `signatures:
-   * false` (as a SERVICE with no funding source behaves).
+   * signature, or undefined only for the deliberately non-compliant
+   * `signatures: false` fixture.
    *
    * Pass `{previousKey: true}` to sign it under `previousPrivateKey`
    * instead, which is how a case puts one note under the old signing key