lnurlcash-conformance 0.1.0-next.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+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.0 - 2026-08-20
+
+First release. Three things, usable independently.
+
+- **`vectors/`** - language-neutral JSON test vectors, generated and frozen.
+  Load them from a suite in any language; the release gate regenerates them
+  and refuses to publish if a single byte moved.
+- **`mock-mint/`** - a real HTTP mint that misbehaves on demand, in every
+  way the spec warns about: destroyed responses, never-settling melts,
+  wrong-`k1` echoes, mutation on non-GET, secrets served before settlement.
+  Typed for TypeScript consumers.
+- **`runner/`** - `lnurlcash-conform <mint>` grades a live service and exits
+  non-zero if it is non-compliant. Read-only by default; `--spend` opts into
+  the mutating checks, `--note`/`--paid` adds the minted-value check without
+  spending anything.
+
+Checks in this release cover the six LUD-25 endpoints, the fee algebra on
+mutations (base fee from split change, `(n-1)` refunds on merge, insufficient
+value), the adversarial mutation shapes a mint must refuse, that a mint never
+mutates on a non-GET request, and that LUD-21 verify serves no secret before
+settlement.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TheCryptoDonkey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,179 @@
+# lnurlcash-conformance
+
+Conformance vectors, an adversarial mock mint, and a grader for LNURLcash
+([LUD-25 draft](https://github.com/lnurl/luds/pull/301)) implementations.
+
+Three things, all usable independently:
+
+| | |
+| --- | --- |
+| **`vectors/`** | language-neutral JSON. Load them directly from your test suite, in any language. |
+| **`mock-mint/`** | a real HTTP mint that can be told to misbehave, on demand, in every way the spec warns about. |
+| **`runner/`** | `lnurlcash-conform <mint>` — grades a live service and exits non-zero if it is non-compliant. |
+
+If you are writing an LNURLcash implementation in any language, run these
+before you run real sats through it.
+
+## Why this exists
+
+LNURLcash notes are bearer instruments: whoever holds the `k1` can spend it,
+and a mistake is silent, immediate and irreversible. The wire protocol is
+small enough that anyone can implement it in an afternoon, which is exactly
+the problem — the protocol is easy and the *discipline* is not. Ambiguous
+mutations, melt semantics, who generates a replacement secret, which end of
+a signature carries the recovery id: get any of those wrong and it works
+perfectly until it costs somebody their money.
+
+These vectors are the shared statement of what the discipline is, so that
+every implementation can be wrong in the same place at the same time, and
+find out about it in CI rather than in production.
+
+## Using the vectors
+
+```bash
+npm install --save-dev lnurlcash-conformance
+```
+
+They are plain JSON — load them from any language, no dependency required:
+
+```js
+const cases = JSON.parse(readFileSync('vectors/signature.json', 'utf8')).cases
+for (const c of cases) {
+  assert.equal(verify(c.k1, c.amountMsat, c.signature, c.mintPubkey), c.valid)
+}
+```
+
+| File | Covers |
+| --- | --- |
+| `signature.json` | offline verification, both recovery-id orderings, malformed input |
+| `bech32.json` | LUD-01 encoding, round trips, corrupted checksums |
+| `url-admission.json` | which URLs may be fetched, and why `data:` must never be |
+| `input-resolution.json` | bech32, LUD-17, Lightning Addresses, bare domains |
+| `note-url.json` | parsing and building note URLs, secret casing, stale signatures |
+| `fees.json` | fee advertisement, application, gross-up minimality, overflow |
+| `bolt11.json` | amount extraction, invoice equality, preimage shape |
+| `callbacks.json` | the exact query each operation puts on the wire |
+| `responses.json` | classifying every reply, including the ambiguous ones |
+| `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 |
+
+Regenerate with `npm run generate`; check them with `npm test`, which
+verifies every digest recomputes, every declared signature really does
+verify, and every fee expectation follows from the formula.
+
+## The mock mint
+
+```bash
+npx lnurlcash-mock-mint --port=8899
+```
+
+Prints a lightning address, a spendable 21 sat note, and its pubkey.
+Nothing is payable — it invents its invoices, and a conformance run must
+never be mistakable for a mainnet one.
+
+Every misbehaviour is a flag, and each reproduces a real failure a holder
+must survive:
+
+| Flag | What it does |
+| --- | --- |
+| `--dropAfterMutation` | applies the mutation, then hangs up. The outcome is genuinely unknowable. |
+| `--unconfirmedMutation` | replies 200 with a body confirming nothing |
+| `--malformedJson` | replies with something that is not JSON |
+| `--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 |
+| `--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 |
+| `--slowMs=N` | delays every response |
+| `--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 |
+| `--verify=false` | no LUD-21 endpoint at all, not merely unadvertised |
+
+As a library, for your own test suite:
+
+```js
+import {createMockMint} from 'lnurlcash-conformance/mock-mint'
+
+const mint = await createMockMint({dropAfterMutation: true})
+mint.state.creditNote(k1, 21000)
+// ... drive your client against mint.url, then
+await mint.close()
+```
+
+`mint.state` exposes `creditNote`, `noteState`, `settleMelt`, `failMelt` and
+the raw note and invoice maps, so a test can assert what the SERVICE
+actually did rather than what it said.
+
+## The grader
+
+```bash
+npx lnurlcash-conform mint@example.com
+```
+
+Read-only by default: resolves the payRequest, checks the `withdrawLink`,
+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
+unknown note is reported distinguishably from a spent one, and the
+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:
+
+```bash
+npx lnurlcash-conform mint@example.com --note='lnurlw://...?k1=...' --paid=500000
+# or --pr=<the mint invoice>, when it carries an amount
+```
+
+This is still read-only. The full run spends:
+
+```bash
+npx lnurlcash-conform mint@example.com --note='lnurlw://...?k1=...' --spend
+```
+
+It burns the note it is given and prints where the value ended up. It
+checks that the informational GET is idempotent and echoes the queried
+`k1`, that the URL's own `amount` is ignored, that a rotate with no `h` is
+refused, that a rotate returns no secret, that signatures verify against the
+advertised `mintPubkey`, that split and merge conserve value - exactly,
+under LUD-25's fee algebra, when the mint's fee advertisement is known -
+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
+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
+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.
+
+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
+is the one thing it must never do.
+
+## Scope and neutrality
+
+This repo takes no position on whose implementation is correct. Where the
+vectors and an implementation disagree, either may be wrong, and the LUD-25
+PR is where that gets settled.
+
+Spec and reference implementations, all by dni, all MIT:
+
+- [LUD-25 draft](https://github.com/lnurl/luds/pull/301)
+- [lnurl-mint](https://github.com/dni/lnurl-mint) — the reference service
+- [lnurl-wallet](https://github.com/dni/lnurl-wallet) — the reference wallet
+
+Contributions of vectors are welcome, particularly from implementers who
+found a case these missed. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT.

package/llms.txt

@@ -0,0 +1,73 @@
+# lnurlcash-conformance
+
+Test vectors, an adversarial mock mint, and a grader for LNURLcash (LUD-25).
+MIT. Use these when implementing LNURLcash in ANY language.
+
+npm install --save-dev lnurlcash-conformance
+
+## Vectors
+
+Plain JSON in vectors/, loadable from any language, listed in
+vectors/index.json:
+
+signature.json       offline verification, both recovery-id orderings
+bech32.json          LUD-01 encoding
+url-admission.json   which URLs may be fetched (https, or http to loopback/.onion)
+input-resolution.json bech32, LUD-17, Lightning Address, bare domain
+note-url.json        parsing/building note URLs
+fees.json            fee advertisement, application, gross-up, overflow case
+bolt11.json          amount extraction, invoice equality
+callbacks.json       exact query per operation
+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
+
+## Mock mint
+
+import {createMockMint} from 'lnurlcash-conformance/mock-mint'
+const mint = await createMockMint({dropAfterMutation: true})
+mint.state.creditNote(k1, 21000)   // then drive your client at mint.url
+await mint.close()
+
+Misbehaviour flags: dropAfterMutation, unconfirmedMutation, malformedJson,
+echoWrongK1, lieAboutValue, signatureLayout=leading, signatures=false,
+serverGeneratedSecrets, meltNeverSettles, meltAlwaysFails, slowMs, sunset,
+baseFeeMsat, feePpm, verify=false.
+
+CLI: npx lnurlcash-mock-mint --port=8899  (nothing is payable)
+
+## Grader
+
+npx lnurlcash-conform mint@example.com                        read-only
+npx lnurlcash-conform mint@example.com --note=<url> --spend   full, burns the note
+
+Exit code non-zero on any failure.
+
+## The signature scheme, canonically
+
+note_id = hex(sha256(k1))
+message = "LNURLcash:" + amount_msat + ":" + note_id
+digest  = sha256(sha256("Lightning Signed Message:" + message))
+sig     = 65 bytes, r || s || recovery_id (wire format)
+pubkey  = 33-byte compressed, hex
+
+Recover from digest with NO further hashing (prehash off). Verifiers MUST
+also accept recovery_id || r || s. Library layouts differ:
+@noble recid-leading; coincurve trailing; Rust secp256k1 64-byte compact +
+RecoveryId; Go btcec recid+27 leading.
+
+## Fee arithmetic
+
+apply(gross, fee) = max(0, gross - base - floor(gross*ppm/1e6))
+Compute the proportional term as floor(gross/1e6)*ppm + floor((gross%1e6)*ppm/1e6):
+a direct multiply overflows u64 at realistic amounts (2.1e15 msat * 999999 ppm).
+grossUp(net, fee) = the SMALLEST gross where apply(gross) == net. Use binary
+search; apply is non-decreasing with steps of 0 or 1. An estimate-then-walk
+implementation is unbounded at 999999 ppm and returns non-minimal answers.
+
+## Spec
+
+https://github.com/lnurl/luds/pull/301
+Reference mint: https://github.com/dni/lnurl-mint
+Reference wallet: https://github.com/dni/lnurl-wallet

package/mock-mint/index.d.ts

@@ -0,0 +1,75 @@
+// Types for the mock mint, so TypeScript consumers get the misbehaviour flags
+// checked rather than reaching for `any`. Hand-written to match index.mjs;
+// the flag list here is the same one DEFAULTS declares there.
+
+export type SignatureLayout = 'trailing' | 'leading'
+
+export type NoteState = 'outstanding' | 'pending' | 'burned'
+
+export interface MockMintOptions {
+  username?: string
+  minSendableMsat?: number
+  maxSendableMsat?: number
+  /** withheld on minting, advertised in the payRequest metadata */
+  baseFeeMsat?: number
+  feePpm?: number
+  /**
+   * 'trailing' is the LUD-25 wire format (r || s || recovery id). 'leading'
+   * reproduces the layout lnurl-mint once emitted, forwarding its node's
+   * signmessage output unreordered.
+   */
+  signatureLayout?: SignatureLayout
+  /** withhold sig/sig2 entirely, as a SERVICE with no funding source does */
+  signatures?: boolean
+  /** LUD-21 verify endpoint. Off means 404, not merely unadvertised. */
+  verify?: boolean
+  privateKey?: string
+
+  // ---- misbehaviour ----
+  /** answer the informational GET with a k1 other than the one queried */
+  echoWrongK1?: boolean
+  /** report a maxWithdrawable that is not what the note is worth */
+  lieAboutValue?: number
+  /** hang up mid-mutation, leaving the outcome unknown while it still lands */
+  dropAfterMutation?: boolean
+  /** reply 200 with a body that confirms nothing */
+  unconfirmedMutation?: boolean
+  /** reply with a body that is not JSON at all */
+  malformedJson?: boolean
+  /** hold every melt in flight forever, so the note stays locked as pending */
+  meltNeverSettles?: boolean
+  /** fail every melt's payment, restoring the note */
+  meltAlwaysFails?: boolean
+  /** non-compliant: generate the replacement secret SERVICE-side and hand it back */
+  serverGeneratedSecrets?: boolean
+  /** delay before responding, in milliseconds */
+  slowMs?: number
+  /** reject splits and mints, as a mint winding down does */
+  sunset?: boolean
+  /** expose /_test/ endpoints. Never enable against anything real. */
+  testHooks?: boolean
+}
+
+export interface MockMintState {
+  notes: Map<string, {amountMsat: number; state: NoteState}>
+  invoices: Map<string, {amountMsat: number; preimage: string; settled: boolean}>
+  pubkey: string
+  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).
+   */
+  creditNote(k1: string, amountMsat: number): string | undefined
+  noteState(k1: string): NoteState | null
+  settleMelt(k1: string): void
+}
+
+export interface MockMint {
+  url: string
+  port: number
+  state: MockMintState
+  close(): Promise<void>
+}
+
+export function createMockMint(options?: MockMintOptions): Promise<MockMint>