lnurlcash-conformance 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -4,6 +4,39 @@ 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.10.0 - 2026-09-11
+
+**Signatures belong to cp1 notes.** The Part 2 rewrite of LUD-25 signs a
+`cp1` note only: a plain hash has nothing to attest to without disclosing
+the secret, so a plain note is unsigned by design. The grader follows it.
+
+- `signs the notes it issues` is gone. In its place, `a plain note carries
+  no signature, or one that verifies`: a hash rotate answered with a bare
+  `{"status":"OK"}` passes, and a mint still issuing the old Part 1
+  signature over the hash passes as long as the signature is a true one.
+  `mintPubkey` is no longer demanded of a mint that issues no signature.
+- New, last in the note run: `certifies a cp1 note it issues (Part 2)`.
+  The grader rotates the note into a fresh `cp1` key, requires a `cs1` in
+  `sig` that recovers to `mintPubkey` (or a published previous key) over
+  the key and amount, requires the same certificate again on the
+  informational GET by `ck1`, then rotates home to a plain secret by that
+  `ck1`. A mint that refuses the `cp1` output warns, never fails: Part 2 is
+  optional. The mock mint has no Part 2 yet, so it warns here.
+- `vectors/responses.json` follows: a bare `{"status":"OK"}` to a hash
+  output is now `ok` (it was `unverifiable`), and so is a split that signs
+  only its first hash output. Three cases are new, and carry `output` or
+  `change: "cp1"` to say which kind of note the call mints: a `cp1` output
+  confirmed without a certificate is `unverifiable`, one certified with a
+  `cs1` is `ok`, and a `cp1` change left uncertified is `unverifiable`. A
+  consumer driving these cases picks the output by that field; a hash
+  where it is absent. Other vector prose that called the hash-note
+  signature mandatory now says which output is owed one.
+- CI runs on Node 24.
+
+The withdraw-info vector still rejects a `withdrawRequest` with no
+`mintPubkey`; relaxing that for Part 1-only mints is a wallet-side change
+across every kit and is not in this release.
+
 ## 0.9.0 - 2026-09-11
 
 **Part 2 vectors.** `vectors/part2.json` covers LUD-25 Part 2, notes keyed by

package/README.md

@@ -95,7 +95,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` | deliberately violates LUD-25 by issuing no signatures |
+| `--signatures=false` | issues no Part 1 signatures. Allowed since the Part 2 rewrite: a plain note is unsigned by design, so the grader passes it |
 | `--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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lnurlcash-conformance",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "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

@@ -5,30 +5,24 @@
 // with the thing it grades would agree with that implementation's mistakes,
 // which is the one thing it must never do.
 
-import {bech32} from '@scure/base'
+import {bech32, bech32m} from '@scure/base'
 import {sha256} from '@noble/hashes/sha2.js'
-import {secp256k1} from '@noble/curves/secp256k1.js'
+import {schnorr, secp256k1} from '@noble/curves/secp256k1.js'
 import {bytesToHex, hexToBytes, utf8ToBytes} from '@noble/hashes/utils.js'
 import {randomBytes} from 'node:crypto'
 
 const noteId = k1 => bytesToHex(sha256(hexToBytes(k1)))
 
-const verifySignature = (k1, amountMsat, signatureHex, pubkeyHex) => {
-  let sig
-  try {
-    sig = hexToBytes(signatureHex)
-  } catch {
-    return false
-  }
+// The "Lightning Signed Message" digest every LUD-25 signature is over.
+const signedMessageDigest = message =>
+  sha256(sha256(new Uint8Array([...utf8ToBytes('Lightning Signed Message:'), ...utf8ToBytes(message)])))
+
+// Does a 65-byte recoverable signature recover to that key? Both byte
+// orderings are tried: the spec wants r || s || recovery-id, a node's
+// signmessage emits the recovery id first, and a mint that forgot to
+// reorder is still signing with its own key.
+const recoversTo = (digest, sig, pubkeyHex) => {
   if (sig.length !== 65) return false
-  const digest = sha256(
-    sha256(
-      new Uint8Array([
-        ...utf8ToBytes('Lightning Signed Message:'),
-        ...utf8ToBytes(`LNURLcash:${amountMsat}:${noteId(k1)}`)
-      ])
-    )
-  )
   const leading = new Uint8Array([sig[64], ...sig.subarray(0, 64)])
   for (const candidate of [leading, sig]) {
     try {
@@ -43,6 +37,45 @@ const verifySignature = (k1, amountMsat, signatureHex, pubkeyHex) => {
   return false
 }
 
+// A Part 1 signature, over the note's hash. The spec no longer asks for
+// one, but a mint that still issues them must at least issue true ones.
+const verifySignature = (k1, amountMsat, signatureHex, pubkeyHex) => {
+  let sig
+  try {
+    sig = hexToBytes(signatureHex)
+  } catch {
+    return false
+  }
+  return recoversTo(signedMessageDigest(`LNURLcash:${amountMsat}:${noteId(k1)}`), sig, pubkeyHex)
+}
+
+// A Part 2 certificate: cs1 over the note's raw x-only public key.
+const verifyCertificate = (pubkeyHex32, amountMsat, sig, mintPubkeyHex) =>
+  recoversTo(signedMessageDigest(`LNURLcash:${amountMsat}:${pubkeyHex32}`), sig, mintPubkeyHex)
+
+// Part 2's bech32m strings: cp1 (32-byte key), ck1 and cs1 (65-byte
+// signature). Longer than BIP-173's 90 characters by design.
+const BECH32M_LIMIT = 200
+const encodeCash = (hrp, bytes) => bech32m.encode(hrp, bech32m.toWords(bytes), BECH32M_LIMIT)
+const decodeCash = (hrp, value, length) => {
+  if (typeof value !== 'string') return null
+  try {
+    const {prefix, words} = bech32m.decode(value, BECH32M_LIMIT)
+    if (prefix !== hrp) return null
+    const bytes = bech32m.fromWords(words)
+    return bytes.length === length ? bytes : null
+  } catch {
+    return null
+  }
+}
+
+// The bearer secret of a cp1 note: the key's signature over the fixed
+// message "LNURLcash", r || s || recovery-id, the same value every time.
+const ownershipProof = secretKey => {
+  const lead = secp256k1.sign(signedMessageDigest('LNURLcash'), secretKey, {format: 'recovered', prehash: false})
+  return encodeCash('ck', new Uint8Array([...lead.subarray(1), lead[0]]))
+}
+
 // 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
@@ -1046,28 +1079,33 @@ export const gradeNote = async (noteUrl, report, options = {}) => {
     return 'burned the old secret, minted the new'
   })
 
-  await report.check('signs the notes it issues', async () => {
-    assert(info.mintPubkey, 'no mintPubkey advertised - offline verification is mandatory')
-    assert(isCompressedPubkey(info.mintPubkey), 'mintPubkey is not a 33-byte compressed secp256k1 key')
-    assert(currentSig, 'the rotate returned no sig - offline verification is mandatory')
-    // A mint that has rotated its signing key may publish the old ones as
-    // previousPubkeys, so notes it issued before the rotation still
-    // verify. Any key it currently stands behind is an acceptable signer
-    // for grading purposes. That is a narrower claim than it looks: it
-    // says the signature is genuine, not that a wallet should accept the
-    // new key - LUD-25 puts that decision with the holder.
-    const signedBy = [info.mintPubkey, ...previousPubkeys].find(key =>
-      verifySignature(current, info.maxWithdrawable, currentSig, key)
-    )
-    assert(
-      signedBy,
-      previousPubkeys.length > 0
-        ? 'the signature verifies against neither the advertised mintPubkey nor any published previous key'
-        : 'the signature does not verify against the advertised mintPubkey and amount'
-    )
-    return signedBy === info.mintPubkey
+  // A mint that has rotated its signing key may publish the old ones as
+  // previousPubkeys, so notes it issued before the rotation still verify.
+  // Any key it currently stands behind is an acceptable signer for grading
+  // purposes. That is a narrower claim than it looks: it says the
+  // signature is genuine, not that a wallet should accept the new key -
+  // LUD-25 puts that decision with the holder.
+  const signerOf = verifies => [info.mintPubkey, ...previousPubkeys].find(key => verifies(key))
+  const describeSigner = signedBy =>
+    signedBy === info.mintPubkey
       ? 'verified offline'
       : `verified offline against a previous signing key (${signedBy.slice(0, 16)}...)`
+  const unverified = () =>
+    previousPubkeys.length > 0
+      ? 'the signature verifies against neither the advertised mintPubkey nor any published previous key'
+      : 'the signature does not verify against the advertised mintPubkey and amount'
+
+  await report.check('a plain note carries no signature, or one that verifies', async () => {
+    // LUD-25 Part 2 signs cp1 notes only: a hash has nothing to attest to
+    // without disclosing the secret, so a plain note is unsigned by
+    // design. A mint that still issues the old Part 1 signature over the
+    // hash is harmless, as long as the signature is a true one.
+    if (currentSig === null) return 'unsigned, as Part 2 specifies for a plain note'
+    assert(info.mintPubkey, 'a sig with no mintPubkey advertised verifies against nothing')
+    assert(isCompressedPubkey(info.mintPubkey), 'mintPubkey is not a 33-byte compressed secp256k1 key')
+    const signedBy = signerOf(key => verifySignature(current, info.maxWithdrawable, currentSig, key))
+    assert(signedBy, unverified())
+    return `a legacy Part 1 signature, ${describeSigner(signedBy)}`
   })
 
   await report.check('reports a spent hash distinguishably from an unknown hash', async () => {
@@ -1095,12 +1133,10 @@ export const gradeNote = async (noteUrl, report, options = {}) => {
   })
 
   await report.check('keeps signatures off the informational endpoint', async () => {
-    // LUD-25: "Signatures are only ever delivered in the
-    // withdrawSuccessResponse of a rotate, split or merge, the
-    // informational endpoint never returns one." A mint that hands one out
-    // here lets anyone holding only a note's PUBLIC url mint a certificate
-    // for it, and invites a wallet to treat the informational answer as an
-    // offline proof when it is an online one.
+    // A plain note has no certificate, so its informational GET carries no
+    // sig. Part 2 does hand out a cs1 here for a cp1 note, and the Part 2
+    // check below expects it; this probe is by hex k1, where one would
+    // invite a wallet to treat an online answer as an offline proof.
     const here = new URL(url)
     here.searchParams.set('k1', current)
     const body = await get(here)
@@ -1418,6 +1454,61 @@ export const gradeNote = async (noteUrl, report, options = {}) => {
     return body.reason
   })
 
+  // LUD-25 Part 2. The spec's one MUST for signatures lives here: a cp1
+  // note is a public key, and the SERVICE certifies every one it issues
+  // with a cs1 over (key, amount) that recovers to mintPubkey. Part 2 is
+  // optional, so a SERVICE that refuses the cp1 output warns rather than
+  // fails. Last, because the note comes back as a plain secret only if
+  // the rotate home succeeds.
+  await report.check('certifies a cp1 note it issues (Part 2)', async () => {
+    const secretKey = secp256k1.utils.randomSecretKey()
+    const pubkey = schnorr.getPublicKey(secretKey)
+    const cp1 = encodeCash('cp', pubkey)
+    const out = new URL(info.callback)
+    out.searchParams.append('k1', current)
+    out.searchParams.append('p1', cp1)
+    const body = await get(out)
+    if (body.status === 'ERROR') throw soft(`Part 2 not offered: a cp1 output was refused (${body.reason})`)
+    // The plain secret is burned either way; from here the bearer secret
+    // is the key's ownership proof, until the rotate home below.
+    const ck1 = ownershipProof(secretKey)
+    current = ck1
+    assert(info.mintPubkey, 'issued a cp1 note with no mintPubkey advertised - nothing to verify its certificate against')
+    assert(isCompressedPubkey(info.mintPubkey), 'mintPubkey is not a 33-byte compressed secp256k1 key')
+    const pubkeyHex = bytesToHex(pubkey)
+    const certificate = decodeCash('cs', body.sig, 65)
+    assert(certificate, `the rotate to a cp1 output returned no cs1 certificate in sig (got ${JSON.stringify(body.sig)})`)
+    const signedBy = signerOf(key => verifyCertificate(pubkeyHex, info.maxWithdrawable, certificate, key))
+    assert(signedBy, unverified())
+
+    // The informational GET by ck1 delivers the certificate again, so a
+    // holder need not rotate just to obtain one.
+    const byKey = new URL(url)
+    byKey.searchParams.set('k1', ck1)
+    const lookup = await get(byKey)
+    assert(lookup.status !== 'ERROR', `the cp1 note is not spendable by its ck1: ${lookup.reason}`)
+    assert(
+      lookup.maxWithdrawable === info.maxWithdrawable,
+      `value changed across a rotate to cp1: ${info.maxWithdrawable} -> ${lookup.maxWithdrawable}`
+    )
+    const again = decodeCash('cs', lookup.sig, 65)
+    assert(again, 'the informational GET by ck1 returned no cs1 certificate')
+    assert(
+      signerOf(key => verifyCertificate(pubkeyHex, info.maxWithdrawable, again, key)),
+      'the certificate on the informational GET does not verify'
+    )
+
+    // Home: back to a plain secret, spent by the ck1.
+    const fresh = bytesToHex(randomBytes(32))
+    const home = new URL(info.callback)
+    home.searchParams.append('k1', ck1)
+    home.searchParams.append('p1', noteId(fresh))
+    const back = await get(home)
+    assert(back.status === 'OK', `the cp1 note could not be rotated back to a plain secret by its ck1: ${back.reason}`)
+    current = fresh
+    return `${describeSigner(signedBy)}; the plain note it rotated home to is ${back.sig === undefined ? 'unsigned' : 'still signed the Part 1 way'}`
+  })
+
   return {finalSecret: current, noteUrl: (() => {
     const u = new URL(url)
     u.searchParams.set('k1', current)

package/vectors/lifecycle.json

@@ -58,7 +58,7 @@
         "the connection drops after the SERVICE applied it",
         "the HTTP stack silently resends the identical request"
       ],
-      "requirement": "a SERVICE MUST recognize the byte-identical retry from the same k1 set, h, h2 and amount, and return the original success with the same sig and sig2 without moving balance again. A WALLET still persists every fresh output secret before sending the first request and keeps it across an ambiguous transport failure. A request that changes any recorded field is a genuine double-spend attempt and gets the ordinary already-spent refusal."
+      "requirement": "a SERVICE MUST recognize the byte-identical retry from the same k1 set, h, h2 and amount, and return the original success, with the same sig and sig2 where the outputs had any, without moving balance again. A WALLET still persists every fresh output secret before sending the first request and keeps it across an ambiguous transport failure. A request that changes any recorded field is a genuine double-spend attempt and gets the ordinary already-spent refusal."
     },
     {
       "name": "settle a merge or split output",

package/vectors/note-url.json

@@ -1,7 +1,7 @@
 {
   "version": 1,
   "spec": "LUD-25 draft (lnurl/luds#301)",
-  "description": "A note is an ordinary LUD-03 withdrawRequest URL whose k1 IS the asset. `amount` alongside it is only a claim by whoever encoded the note - the authoritative value is always maxWithdrawable from an informational GET. A SERVICE returning a rotate, split or merge MUST include the offline-verification signature in `sig` (and `sig2` for the second split output).",
+  "description": "A note is an ordinary LUD-03 withdrawRequest URL whose k1 IS the asset. `amount` alongside it is only a claim by whoever encoded the note - the authoritative value is always maxWithdrawable from an informational GET. A SERVICE returning a rotate, split or merge to a cp1 output MUST include its certificate in `sig` (and `sig2` for the second split output); a plain hash output carries none, and a legacy Part 1 signature on one is harmless where it verifies.",
   "parse": [
     {
       "url": "https://mint.example/w?k1=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&amount=21000",

package/vectors/responses.json

@@ -4,7 +4,7 @@
   "description": "Classifying a SERVICE response. The distinction that matters for funds is definitive-rejection versus ambiguous-outcome: a parsed {\"status\":\"ERROR\"} means the request was processed and refused, while a transport failure, an unparseable body, or a 200 that does not confirm means the mutation MAY have landed - and for rotate/split/merge the WALLET-generated secrets are then the only copy of the outputs, so they must ride the error rather than be discarded. A confirmed mutation carrying no signature is its own outcome: it definitely landed, so the secrets matter more than ever, and the SERVICE is non-conforming. `op` says which call each case is driven through - a melt is the one mutation with no signature to return.",
   "outcomes": {
     "ok": "the operation is confirmed",
-    "unverifiable": "the mutation is confirmed but carries no signature. LUD-25 requires one on every rotate, split and merge, so this SERVICE is non-conforming - but the note EXISTS at the hash the WALLET disclosed, and its secret is the only key to that value. Keep the secret; report the mint",
+    "unverifiable": "the mutation is confirmed but a cp1 output came back without its cs1 certificate. LUD-25 Part 2 requires one on every cp1 output of a rotate, split or merge, so this SERVICE is non-conforming - but the note EXISTS at the key the WALLET disclosed, and its private key is the only key to that value. Keep the key; report the mint. A plain hash output is unsigned by design and is never this outcome",
     "pending": "this k1 has another operation in flight (a melt); retry shortly",
     "spent": "the SERVICE is authoritative that the note is already burned; a holder may lock it as spent",
     "unknown": "the SERVICE does not recognise this note; surface it, do not silently lock it",
@@ -19,8 +19,43 @@
       "body": {
         "status": "OK"
       },
+      "expect": "ok",
+      "why": "a bare OK is the conforming answer for a plain hash output since the Part 2 rewrite: the note is real, the WALLET keeps its secret, and nobody the holder hands it to can check it offline, which is what a plain note is. Only a cp1 output is owed a certificate"
+    },
+    {
+      "name": "cp1 output confirmed without a certificate",
+      "op": "mutation",
+      "output": "cp1",
+      "http": 200,
+      "body": {
+        "status": "OK"
+      },
+      "expect": "unverifiable",
+      "why": "a cp1 output is owed a cs1 certificate in sig; without one the note it names cannot be verified offline, which is the whole reason to hold a cp1 note. The note exists at the key the WALLET disclosed"
+    },
+    {
+      "name": "cp1 output certified",
+      "op": "mutation",
+      "output": "cp1",
+      "http": 200,
+      "body": {
+        "status": "OK",
+        "sig": "cs14w46h2at4w46h2at4w46h2at4w46h2at4w46h2at4w46h2at4w46h2at4w46h2at4w46h2at4w46h2at4w46h2at4w46h2at4w46h2atdv6a53"
+      },
+      "expect": "ok",
+      "signature": "cs14w46h2at4w46h2at4w46h2at4w46h2at4w46h2at4w46h2at4w46h2at4w46h2at4w46h2at4w46h2at4w46h2at4w46h2at4w46h2atdv6a53"
+    },
+    {
+      "name": "a split to a cp1 change that certifies only its first output",
+      "op": "split",
+      "change": "cp1",
+      "http": 200,
+      "body": {
+        "status": "OK",
+        "sig": "ababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababab"
+      },
       "expect": "unverifiable",
-      "why": "a bare OK was a conforming rotate answer while offline verification was optional. It is not one now: the note is real and the WALLET must keep its secret, but nobody the holder hands it to can check it"
+      "why": "the change is a cp1 note and is owed its certificate in sig2 exactly as the first output would be; the change is not a lesser note"
     },
     {
       "name": "success with an offline-verification signature",
@@ -54,8 +89,9 @@
         "status": "OK",
         "sig": "ababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababab"
       },
-      "expect": "unverifiable",
-      "why": "both outputs of a split are notes and both need a signature; the change is not a lesser note"
+      "expect": "ok",
+      "signature": "ababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababab",
+      "why": "both outputs are plain hash notes, owed nothing; a mint may still issue the old Part 1 signature over one of them, and that is harmless where it verifies"
     },
     {
       "name": "melt success with a LUD-21 style proof",

package/vectors/retried-mutation.json

@@ -10,7 +10,7 @@
   ],
   "provenance": "Recorded, never inferred. A SERVICE links the burned inputs to the outputs they minted and matches against that. Matching on \"a note exists at h\" alone would let anyone holding a burned k1 and any outstanding note id pull a success out of the SERVICE.",
   "outcomes": {
-    "replay": "the original success, byte for byte: the same status, the same sig and sig2, and no balance moved",
+    "replay": "the original success, byte for byte: the same status, the same sig and sig2 where the outputs had any, and no balance moved",
     "double-spend": "refused exactly as any other attempt to spend a burned secret, with the reason string unchanged"
   },
   "cases": [