lnurlcash-kit 0.12.1 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # 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

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

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,7 +965,7 @@ var fetchNoteInfo = async (url, options = {}) => {
   }
   assertWithdrawRequestShape(body, {
     requireK1: true,
-    requireMintPubkey: opts.requireSignatures
+    requireMintPubkey: opts.requireMintPubkey
   });
   const queried = noteK1(url);
   const echoed = noteIdOf(body.k1);
@@ -991,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);
@@ -1139,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.`
@@ -1173,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(
@@ -1187,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 = {}) => {
@@ -1197,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.1",
+  "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.9.0",
+    "lnurlcash-conformance": "^0.10.0",
     "tsup": "^8.5.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"