lnurlcash-kit 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.13.0 - 2026-09-11
+
+**A plain note is unsigned.** LUD-25 Part 2 certifies `cp1` notes only, and
+the reference mint and moneyer now answer a rotate, split or merge to a hash
+output with a bare `{"status":"OK"}`. This library follows.
+
+- `requireSignatures` now defaults to **false**. A hash output that comes
+  back unsigned is the spec, not a fault: `signature` (and `changeSignature`)
+  is undefined, and no `UnverifiableNoteError` is raised. Set it true to
+  keep demanding the old Part 1 signature over the hash.
+- A `cp1` output is owed its `cs1` certificate regardless of the option: a
+  rotate, split or merge naming one that comes back without `sig` (or
+  `sig2` for a `cp1` change) raises `UnverifiableNoteError`, carrying the
+  fresh secrets as before.
+- New option `requireMintPubkey`, default true, takes over the
+  `withdrawRequest` check that `requireSignatures` used to carry. A Part
+  1-only mint that publishes no `mintPubkey` is admitted with it set false.
+- Graded by lnurlcash-conformance 0.10.0's response vectors, which now
+  carry `output`/`change: "cp1"` on the cases that mint a `cp1` note.
+
+If you relied on the default to refuse unsigned plain notes, set
+`requireSignatures: true`; if you only ever wanted verifiable notes, hold
+`cp1` notes, which are the only kind the spec makes verifiable.
+
+## 0.12.1 - 2026-09-11
+
+- `fetchNoteInfo` compares the mint's echoed `k1` with the one it asked
+  about as the note each names (`noteIdOf`), not as strings. One Part 2 note
+  has many valid `ck1`s: anyone can turn one into its high-S twin, and its
+  holder can re-sign, so a mint echoing another spelling of the same note
+  was reported as having handed back a different note. An echo that names no
+  note at all is still refused, and a Part 1 secret compares as it always did.
+
 ## 0.12.0 - 2026-09-11
 
 **A Part 2 branch rooted in a Nostr key.**

package/README.md

@@ -58,14 +58,14 @@ console.log(info.maxWithdrawable, 'msat')
 // that GET put the secret on the wire, so rotate it
 const fresh = await rotateNote(info.callback, info.k1)
 
-// and check the mint really issued it, without asking anyone. Both fields
-// are guaranteed here: LUD-25 requires the mint to publish mintPubkey and
-// to sign what it mints, and this library refuses a mint that does neither.
-verifyNoteSignature(fresh.k1, info.maxWithdrawable, fresh.signature!, info.mintPubkey)
+// A plain note comes back unsigned: LUD-25 Part 2 certifies cp1 notes
+// only, and a hash has nothing to attest to without disclosing the secret.
+// To hold something a recipient can check offline, rotate into a cp1 key
+// (see Part 2 below) and verify its cs1 against info.mintPubkey.
 ```
 
 Every request function takes options last — `fetch`, `timeoutMs`, `offline`,
-`randomSecret`, `requireSignatures`, `mutationRetries`.
+`randomSecret`, `requireSignatures`, `requireMintPubkey`, `mutationRetries`.
 `createClient(options)` binds one set once:
 
 ```ts
@@ -189,12 +189,15 @@ sig     = 65 bytes, r || s || recovery_id
 ```
 
 A `withdrawRequest` publishing no `mintPubkey`, or one that is not a 33-byte
-compressed secp256k1 key, is refused with a `ProtocolError`. A mutation the
-service confirms but does not sign raises `UnverifiableNoteError` — which
-**carries the fresh secrets**, because the mutation landed and the note it
-minted is real; read them with `newSecretsOf` and persist them before
-anything else. Pass `requireSignatures: false` to deal with a mint that
-predates the requirement.
+compressed secp256k1 key, is refused with a `ProtocolError`; pass
+`requireMintPubkey: false` for a Part 1-only mint that publishes none. A
+mutation to a `cp1` output the service confirms but does not certify raises
+`UnverifiableNoteError` — which **carries the fresh secrets**, because the
+mutation landed and the note it minted is real; read them with
+`newSecretsOf` and persist them before anything else. A mutation to a plain
+hash output is unsigned by design and comes back with `signature`
+undefined; pass `requireSignatures: true` to demand the old Part 1
+signature over the hash instead, as mints issued before the Part 2 rewrite.
 
 `verifyNoteSignature` recovers the pubkey and compares it to `mintPubkey`.
 It accepts the recovery id at either end, because lnurl-mint once emitted
@@ -422,8 +425,9 @@ Three things worth knowing:
 - **`i` is any uint32**, serialised as 4 bytes big-endian, never hardened.
   lnurl-wallet and lnurl-mint agree on that; the spec does not say.
 
-`test/vectors/part2.json` was generated from lnurl-wallet and checked against
-lnurl-mint. It moves into lnurlcash-conformance next.
+The tests grade against lnurlcash-conformance's `vectors/part2.json`, built
+from the primitives there and identical to vectors generated from lnurl-wallet
+and checked against lnurl-mint.
 
 **A branch rooted in a Nostr key.** A holder with no BIP-39 words, such as a
 hardware signer that keeps only its identity key, or a wallet that never made
@@ -431,7 +435,7 @@ any, can still be paid to keys of its own. `deriveNostrAddressNode(secretKey,
 host)` takes the branch from the key that owns the lightning address:
 `HMAC-SHA256(key = secret key, msg = "LNURLcash/nostr-seed")`, then the path
 above unchanged. heartwood-esp32 derives exactly this on the device, graded
-against the same `test/vectors/nostr-seed.json`, so its notes come back from
+against the same values as conformance's `vectors/nostr-seed.json`, so its notes come back from
 its nsec (or the phrase the nsec came from) without the device. This is ours,
 not LUD-25's; a mint sees an ordinary `cx1` either way.
 

package/dist/index.d.ts

@@ -14,6 +14,7 @@ type LnurlcashOptions = {
     offline?: boolean;
     randomSecret?: RandomSecret;
     requireSignatures?: boolean;
+    requireMintPubkey?: boolean;
     mutationRetries?: number;
 };
 

package/dist/index.js

@@ -690,7 +690,8 @@ var resolveOptions = (options = {}) => ({
   timeoutMs: options.timeoutMs ?? 3e4,
   offline: options.offline ?? false,
   randomSecret: options.randomSecret ?? defaultRandomSecret,
-  requireSignatures: options.requireSignatures ?? true,
+  requireSignatures: options.requireSignatures ?? false,
+  requireMintPubkey: options.requireMintPubkey ?? true,
   // A negative or non-finite count is read as none rather than thrown on:
   // this is a resilience knob, and refusing the whole operation over it
   // would be a worse answer than not retrying.
@@ -964,10 +965,11 @@ var fetchNoteInfo = async (url, options = {}) => {
   }
   assertWithdrawRequestShape(body, {
     requireK1: true,
-    requireMintPubkey: opts.requireSignatures
+    requireMintPubkey: opts.requireMintPubkey
   });
   const queried = noteK1(url);
-  if (queried && body.k1.toLowerCase() !== queried) {
+  const echoed = noteIdOf(body.k1);
+  if (queried && (echoed === null || echoed !== noteIdOf(queried))) {
     throw new ProtocolError(
       "The service echoed back a different k1 than was queried - the note may have been redeemed elsewhere, or the service isn't spec-compliant."
     );
@@ -990,7 +992,7 @@ var fetchNoteInfoByHash = async (withdrawLink, h, options = {}) => {
   }
   assertWithdrawRequestShape(body, {
     requireK1: false,
-    requireMintPubkey: opts.requireSignatures
+    requireMintPubkey: opts.requireMintPubkey
   });
   const info = body;
   const payLink = sameOriginPayLink(body.payLink, reqUrl);
@@ -1138,8 +1140,13 @@ var replayableCallbackRequest = async (callback, params, options) => {
   }
   throw lastError;
 };
-var requireSignature = (value, options, what) => {
+var requireSignature = (value, options, what, output) => {
   if (typeof value === "string" && value.length > 0) return value;
+  if (isCp1(output)) {
+    throw new UnverifiableNoteError(
+      `The service confirmed the ${what} to a cp1 output but returned no cs1 certificate, which LUD-25 Part 2 requires, so the note it just minted cannot be verified offline. The note exists - keep the key.`
+    );
+  }
   if (!resolveOptions(options).requireSignatures) return void 0;
   throw new UnverifiableNoteError(
     `The service confirmed the ${what} but returned no signature, so the note it just minted cannot be verified offline. The note exists - keep the secret.`
@@ -1172,7 +1179,7 @@ var rotateNoteWithHash = async (callback, k1, h, options = {}) => {
     ],
     options
   );
-  return { signature: requireSignature(body.sig, options, "rotate") };
+  return { signature: requireSignature(body.sig, options, "rotate", h) };
 };
 var splitNoteWithHash = async (callback, k1s, amountMsat, h, h2, options = {}) => {
   const body = await replayableCallbackRequest(
@@ -1186,8 +1193,8 @@ var splitNoteWithHash = async (callback, k1s, amountMsat, h, h2, options = {}) =
     options
   );
   return {
-    signature: requireSignature(body.sig, options, "split"),
-    changeSignature: requireSignature(body.sig2, options, "split's change")
+    signature: requireSignature(body.sig, options, "split", h),
+    changeSignature: requireSignature(body.sig2, options, "split's change", h2)
   };
 };
 var mergeNotesWithHash = async (callback, k1s, h, options = {}) => {
@@ -1196,7 +1203,7 @@ var mergeNotesWithHash = async (callback, k1s, h, options = {}) => {
     [...k1s.map((k1) => ["k1", k1]), outputParam(h, 1)],
     options
   );
-  return { signature: requireSignature(body.sig, options, "merge") };
+  return { signature: requireSignature(body.sig, options, "merge", h) };
 };
 var keepingOutputs = (err, newSecrets) => {
   if (err instanceof NoteSpentError || err instanceof NoteUnknownError) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lnurlcash-kit",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "LNURLcash (LUD-25) bearer note client for TypeScript - mint, rotate, split, merge, melt, and verify offline",
   "author": "TheCryptoDonkey",
   "license": "MIT",
@@ -60,7 +60,7 @@
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
-    "lnurlcash-conformance": "^0.8.0",
+    "lnurlcash-conformance": "^0.10.0",
     "tsup": "^8.5.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"