lnurlcash-kit 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 Semantic versioning. While the LUD-25 draft is unmerged, `0.x` minor bumps
 may carry breaking changes; pin an exact version.
 
+## 0.3.0 - 2026-08-24
+
+- Additive bound-mint receipt parsing and validation for sealed signers:
+  `InvoiceResult.mint`, `VerifyResult.mint`, `requireBoundMintQuote` and
+  `validateBoundMintReceipt`. The quote must commit the requested `h` and
+  exact net amount before payment; the settled LUD-21 response must match the
+  invoice and commitment and carry a valid ordinary LUD-25 note signature.
+- `noteSignatureMessageForHash`, `noteSignatureDigestForHash`,
+  `verifyNoteSignatureHash` and `verifyNoteSignatureHashAgainst` expose the
+  existing signature construction when a signer deliberately retains `k1`.
+  Existing secret-based helpers delegate to them unchanged.
+
 ## 0.2.1 - 2026-08-22
 
 - `WithdrawRequestInfo` carries `payLink`, the way home a SERVICE may

package/README.md

@@ -358,6 +358,47 @@ is yours from the moment it exists. The claim GET does show the secret to the
 mint it is a claim on, which is a different thing from showing it to whoever
 scanned the QR, and you can still rotate if you want the offline signature.
 
+### A sealed signer: confirm without exporting the secret
+
+A hardware vault cannot use the claim GET above without handing `k1` to its
+companion. A receipt-capable mint can instead commit the quote to the requested
+`h` and exact net amount, then place the ordinary LUD-25 note signature on its
+settled LUD-21 response. The extension is optional; absence means use the
+unchanged preimage-import-and-rotate flow before showing an invoice.
+
+```ts
+import {
+  requestInvoice, fetchInvoiceVerification,
+  requireBoundMintQuote, validateBoundMintReceipt
+} from 'lnurlcash-kit'
+
+const staged = await vault.newSecret() // {id, h}; k1 stays in the vault
+const expectedNetMsat = 21_000
+const quote = await requestInvoice(pay.callback, 21_000, {h: staged.h})
+
+// Do this before displaying or paying quote.pr.
+requireBoundMintQuote(quote, staged.h, expectedNetMsat)
+if (!quote.verify) throw new Error('No settlement receipt offered')
+
+// After payment, poll quote.verify until settled.
+const verification = await fetchInvoiceVerification(quote.verify)
+const receipt = validateBoundMintReceipt(
+  quote,
+  verification,
+  staged.h,
+  expectedNetMsat,
+  pinnedMintPubkeys
+)
+await vault.confirm(staged.id, receipt.amountMsat, mintHost, receipt.signature)
+```
+
+`quote.mint` is `{h, amountMsat}` in the typed API (`amount` on the wire).
+The settled response must repeat that commitment and add `signature` (`sig`
+on the wire). Validation matches the invoice, output and amount, refuses a
+pre-settlement signature, and recovers the signer against the pinned current
+or previous mint keys. The payment preimage remains proof of payment; it never
+replaces the vault's staged secret.
+
 ## Asking to be paid
 
 "Send me 500 sat" today means handing over a Lightning Address, which is a

package/dist/index.d.ts

@@ -133,6 +133,15 @@ type InvoiceResult = {
     verify?: string;
     disposable: boolean;
     mintToHash: boolean;
+    mint?: BoundMintCommitment;
+};
+type BoundMintCommitment = {
+    h: string;
+    amountMsat: number;
+    signature?: string;
+};
+type ValidatedBoundMintReceipt = Required<BoundMintCommitment> & {
+    pubkey: string;
 };
 type InvoiceRequestOptions = LnurlcashOptions & {
     h?: string;
@@ -142,8 +151,11 @@ type VerifyResult = {
     settled: boolean;
     preimage: string | null;
     pr: string;
+    mint?: BoundMintCommitment;
 };
 declare const fetchInvoiceVerification: (verifyUrl: string, options?: LnurlcashOptions) => Promise<VerifyResult>;
+declare const requireBoundMintQuote: (invoice: InvoiceResult, expectedH: string, expectedAmountMsat: number) => BoundMintCommitment;
+declare const validateBoundMintReceipt: (invoice: InvoiceResult, verification: VerifyResult, expectedH: string, expectedAmountMsat: number, mintPubkeys: string | string[]) => ValidatedBoundMintReceipt;
 type MintClaim = {
     state: 'minted' | 'unminted' | 'pending' | 'spent';
     k1: string;
@@ -226,7 +238,9 @@ declare const decodePaymentRequest: (value: string, { now }?: DecodeOptions) =>
 declare const isPaymentRequest: (value: string) => boolean;
 
 declare const noteSignatureMessage: (k1: string, amountMsat: number) => string;
+declare const noteSignatureMessageForHash: (h: string, amountMsat: number) => string;
 declare const noteSignatureDigest: (k1: string, amountMsat: number) => Uint8Array;
+declare const noteSignatureDigestForHash: (h: string, amountMsat: number) => Uint8Array;
 type SignatureCheck = {
     valid: true;
     pubkey: string;
@@ -235,7 +249,9 @@ type SignatureCheck = {
     pubkey: null;
 };
 declare const verifyNoteSignatureAgainst: (k1: string, amountMsat: number, signatureHex: string, mintPubkeys: string | string[]) => SignatureCheck;
+declare const verifyNoteSignatureHashAgainst: (h: string, amountMsat: number, signatureHex: string, mintPubkeys: string | string[]) => SignatureCheck;
 declare const verifyNoteSignature: (k1: string, amountMsat: number, signatureHex: string, mintPubkeys: string | string[]) => boolean;
+declare const verifyNoteSignatureHash: (h: string, amountMsat: number, signatureHex: string, mintPubkeys: string | string[]) => boolean;
 
 declare const isBolt11Invoice: (value: string) => boolean;
 declare const sameInvoice: (a: string, b: string) => boolean;
@@ -297,4 +313,4 @@ declare const createClient: (options?: LnurlcashOptions) => {
 };
 type LnurlcashClient = ReturnType<typeof createClient>;
 
-export { AmbiguousMintError, AmbiguousMutationError, type DecodeOptions, type HashedMutationResult, type HashedSplitResult, InsufficientValueError, type InvoiceRequestOptions, type InvoiceResult, type LnurlcashClient, LnurlcashError, type LnurlcashOptions, type MeltResult, type MintAddressInfo, type MintClaim, type MintContact, type MintFee, type MintFeeBand, NoteSpentError, NoteUnknownError, PAYMENT_REQUEST_PREFIX, type PayRequestInfo, type PaymentRequest, type PaymentRequestMethodDetails, PendingNoteError, ProtocolError, type RandomSecret, RequestRefusedError, type RestoreOptions, type RestoreResult, type RestoredNote, type RotateResult, ServiceRejectedError, type SettleForValueOptions, type SettledForValue, type SettledNote, type SignatureCheck, type SplitResult, type VerifyResult, type WithdrawRequestInfo, type WithdrawSuccessResponse, applyMintFee, buildNoteUrl, claimMintedNote, classifyNoteError, createClient, decodeBolt11AmountMsat, decodePaymentRequest, defaultRandomSecret, deriveNoteRoot, deriveNoteSecret, derivedSecretSource, describeMintFee, encodePaymentRequest, fetchInvoiceVerification, fetchMintAddress, fetchNoteInfo, fetchPayRequest, formatFeePercent, fromBech32Lnurl, fromLud17, grossUpForMintFee, hashK1, isAllowedServiceUrl, isBech32Lnurl, isBolt11Invoice, isLightningAddress, isPaymentRequest, isPreimage, isValidNoteInput, lightningAddressUsername, meltNote, mergeNotes, mergeNotesWithHash, mintAddressUrl, mintFeeBand, newSecretsOf, noteDeclaredAmount, noteK1, noteSignature, noteSignatureDigest, noteSignatureMessage, parseMintFee, paymentRequestAmountMsat, probeBurnedNote, requestInvoice, requireNoteK1, resolveLnurlInput, resolveMintInput, resolveNoteInput, restoreNotes, rotateNote, rotateNoteWithHash, sameInvoice, serverOf, settleNote, settleNoteForValue, splitNote, splitNoteWithHash, toBech32Lnurl, toLud17w, verifyNoteSignature, verifyNoteSignatureAgainst, withNewK1, withinMintFeeBand, withoutK1 };
+export { AmbiguousMintError, AmbiguousMutationError, type BoundMintCommitment, type DecodeOptions, type HashedMutationResult, type HashedSplitResult, InsufficientValueError, type InvoiceRequestOptions, type InvoiceResult, type LnurlcashClient, LnurlcashError, type LnurlcashOptions, type MeltResult, type MintAddressInfo, type MintClaim, type MintContact, type MintFee, type MintFeeBand, NoteSpentError, NoteUnknownError, PAYMENT_REQUEST_PREFIX, type PayRequestInfo, type PaymentRequest, type PaymentRequestMethodDetails, PendingNoteError, ProtocolError, type RandomSecret, RequestRefusedError, type RestoreOptions, type RestoreResult, type RestoredNote, type RotateResult, ServiceRejectedError, type SettleForValueOptions, type SettledForValue, type SettledNote, type SignatureCheck, type SplitResult, type ValidatedBoundMintReceipt, type VerifyResult, type WithdrawRequestInfo, type WithdrawSuccessResponse, applyMintFee, buildNoteUrl, claimMintedNote, classifyNoteError, createClient, decodeBolt11AmountMsat, decodePaymentRequest, defaultRandomSecret, deriveNoteRoot, deriveNoteSecret, derivedSecretSource, describeMintFee, encodePaymentRequest, fetchInvoiceVerification, fetchMintAddress, fetchNoteInfo, fetchPayRequest, formatFeePercent, fromBech32Lnurl, fromLud17, grossUpForMintFee, hashK1, isAllowedServiceUrl, isBech32Lnurl, isBolt11Invoice, isLightningAddress, isPaymentRequest, isPreimage, isValidNoteInput, lightningAddressUsername, meltNote, mergeNotes, mergeNotesWithHash, mintAddressUrl, mintFeeBand, newSecretsOf, noteDeclaredAmount, noteK1, noteSignature, noteSignatureDigest, noteSignatureDigestForHash, noteSignatureMessage, noteSignatureMessageForHash, parseMintFee, paymentRequestAmountMsat, probeBurnedNote, requestInvoice, requireBoundMintQuote, requireNoteK1, resolveLnurlInput, resolveMintInput, resolveNoteInput, restoreNotes, rotateNote, rotateNoteWithHash, sameInvoice, serverOf, settleNote, settleNoteForValue, splitNote, splitNoteWithHash, toBech32Lnurl, toLud17w, validateBoundMintReceipt, verifyNoteSignature, verifyNoteSignatureAgainst, verifyNoteSignatureHash, verifyNoteSignatureHashAgainst, withNewK1, withinMintFeeBand, withoutK1 };

package/dist/index.js

@@ -627,6 +627,62 @@ var describeMintFee = (fee) => [
   fee.baseFeeMsat > 0 ? `${Math.round(fee.baseFeeMsat / 1e3)} sat flat` : null,
   fee.feePpm > 0 ? `${formatFeePercent(fee.feePpm)}% of the amount paid` : null
 ].filter(Boolean).join(" + ");
+var LIGHTNING_SIGNED_MESSAGE_PREFIX = utf8ToBytes("Lightning Signed Message:");
+var noteSignatureMessage = (k1, amountMsat) => noteSignatureMessageForHash(hashK1(k1), amountMsat);
+var noteSignatureMessageForHash = (h, amountMsat) => `LNURLcash:${amountMsat}:${h.trim().toLowerCase()}`;
+var noteSignatureDigest = (k1, amountMsat) => noteSignatureDigestForHash(hashK1(k1), amountMsat);
+var noteSignatureDigestForHash = (h, amountMsat) => sha256(
+  sha256(
+    new Uint8Array([
+      ...LIGHTNING_SIGNED_MESSAGE_PREFIX,
+      ...utf8ToBytes(noteSignatureMessageForHash(h, amountMsat))
+    ])
+  )
+);
+var NO_MATCH = { valid: false, pubkey: null };
+var verifyNoteSignatureAgainst = (k1, amountMsat, signatureHex, mintPubkeys) => {
+  let h;
+  try {
+    h = hashK1(k1);
+  } catch {
+    return NO_MATCH;
+  }
+  return verifyNoteSignatureHashAgainst(h, amountMsat, signatureHex, mintPubkeys);
+};
+var verifyNoteSignatureHashAgainst = (h, amountMsat, signatureHex, mintPubkeys) => {
+  const targets = (Array.isArray(mintPubkeys) ? mintPubkeys : [mintPubkeys]).filter((key) => typeof key === "string").map((key) => key.trim().toLowerCase());
+  if (targets.length === 0) return NO_MATCH;
+  let wireSig;
+  try {
+    wireSig = hexToBytes(signatureHex);
+  } catch {
+    return NO_MATCH;
+  }
+  if (wireSig.length !== 65) return NO_MATCH;
+  let digest;
+  try {
+    if (!/^[0-9a-fA-F]{64}$/.test(h.trim())) return NO_MATCH;
+    digest = noteSignatureDigestForHash(h, amountMsat);
+  } catch {
+    return NO_MATCH;
+  }
+  const recoveryIdFirst = new Uint8Array([
+    wireSig[64],
+    ...wireSig.subarray(0, 64)
+  ]);
+  for (const candidate of [recoveryIdFirst, wireSig]) {
+    try {
+      const recovered = bytesToHex(
+        secp256k1.recoverPublicKey(candidate, digest, { prehash: false })
+      );
+      if (targets.includes(recovered)) return { valid: true, pubkey: recovered };
+    } catch {
+    }
+  }
+  return NO_MATCH;
+};
+var verifyNoteSignature = (k1, amountMsat, signatureHex, mintPubkeys) => verifyNoteSignatureAgainst(k1, amountMsat, signatureHex, mintPubkeys).valid;
+var verifyNoteSignatureHash = (h, amountMsat, signatureHex, mintPubkeys) => verifyNoteSignatureHashAgainst(h, amountMsat, signatureHex, mintPubkeys).valid;
 
 // src/client.ts
 var fetchNoteInfo = async (url, options = {}) => {
@@ -905,6 +961,18 @@ var fetchPayRequest = async (url, options = {}) => {
     mintToHash: asBoolean(body.mintToHash)
   };
 };
+var asBoundMintCommitment = (value) => {
+  if (!value || typeof value !== "object") return void 0;
+  const raw = value;
+  if (typeof raw.h !== "string" || !/^[0-9a-fA-F]{64}$/.test(raw.h) || typeof raw.amount !== "number" || !Number.isSafeInteger(raw.amount) || raw.amount <= 0 || raw.sig !== void 0 && typeof raw.sig !== "string") {
+    return void 0;
+  }
+  return {
+    h: raw.h.toLowerCase(),
+    amountMsat: raw.amount,
+    ...typeof raw.sig === "string" ? { signature: raw.sig } : {}
+  };
+};
 var requestInvoice = async (payCallback, amountMsat, options = {}) => {
   const cbUrl = new URL(payCallback);
   cbUrl.searchParams.set("amount", String(amountMsat));
@@ -930,7 +998,8 @@ var requestInvoice = async (payCallback, amountMsat, options = {}) => {
     pr: body.pr,
     verify: typeof body.verify === "string" ? body.verify : void 0,
     disposable: body.disposable !== false,
-    mintToHash: body.mintToHash === true
+    mintToHash: body.mintToHash === true,
+    mint: asBoundMintCommitment(body.mint)
   };
 };
 var fetchInvoiceVerification = async (verifyUrl, options = {}) => {
@@ -941,9 +1010,56 @@ var fetchInvoiceVerification = async (verifyUrl, options = {}) => {
   return {
     settled: body.settled,
     preimage: typeof body.preimage === "string" ? body.preimage : null,
-    pr: body.pr
+    pr: body.pr,
+    mint: asBoundMintCommitment(body.mint)
   };
 };
+var requireBoundMintQuote = (invoice, expectedH, expectedAmountMsat) => {
+  const h = expectedH.trim().toLowerCase();
+  if (!isPreimage(h)) throw new ProtocolError("The expected mint output hash is malformed.");
+  if (!Number.isSafeInteger(expectedAmountMsat) || expectedAmountMsat <= 0) {
+    throw new ProtocolError("The expected mint amount must be positive integer millisatoshis.");
+  }
+  if (!invoice.mintToHash || !invoice.mint) {
+    throw new ProtocolError("The service did not commit this quote to a bound mint output.");
+  }
+  if (invoice.mint.h !== h) {
+    throw new ProtocolError("The service committed the quote to a different mint output.");
+  }
+  if (invoice.mint.amountMsat !== expectedAmountMsat) {
+    throw new ProtocolError("The service committed the quote to a different mint amount.");
+  }
+  if (invoice.mint.signature !== void 0) {
+    throw new ProtocolError("The service signed a mint output before the invoice settled.");
+  }
+  return invoice.mint;
+};
+var validateBoundMintReceipt = (invoice, verification, expectedH, expectedAmountMsat, mintPubkeys) => {
+  const quote = requireBoundMintQuote(invoice, expectedH, expectedAmountMsat);
+  if (!verification.settled) {
+    throw new ProtocolError("The invoice has not settled.");
+  }
+  if (!sameInvoice(invoice.pr, verification.pr)) {
+    throw new ProtocolError("The settlement receipt names a different invoice.");
+  }
+  const receipt = verification.mint;
+  if (!receipt || receipt.h !== quote.h || receipt.amountMsat !== quote.amountMsat) {
+    throw new ProtocolError("The settlement receipt does not match the mint quote.");
+  }
+  if (!receipt.signature) {
+    throw new ProtocolError("The settled mint receipt has no note signature.");
+  }
+  const checked = verifyNoteSignatureHashAgainst(
+    receipt.h,
+    receipt.amountMsat,
+    receipt.signature,
+    mintPubkeys
+  );
+  if (!checked.valid) {
+    throw new ProtocolError("The settled mint receipt has an invalid note signature.");
+  }
+  return { ...receipt, signature: receipt.signature, pubkey: checked.pubkey };
+};
 var claimMintedNote = async (withdrawLink, k1, options = {}) => {
   const secret = k1.trim().toLowerCase();
   if (!isPreimage(secret)) {
@@ -971,49 +1087,6 @@ var claimMintedNote = async (withdrawLink, k1, options = {}) => {
     throw err;
   }
 };
-var LIGHTNING_SIGNED_MESSAGE_PREFIX = utf8ToBytes("Lightning Signed Message:");
-var noteSignatureMessage = (k1, amountMsat) => `LNURLcash:${amountMsat}:${hashK1(k1)}`;
-var noteSignatureDigest = (k1, amountMsat) => sha256(
-  sha256(
-    new Uint8Array([
-      ...LIGHTNING_SIGNED_MESSAGE_PREFIX,
-      ...utf8ToBytes(noteSignatureMessage(k1, amountMsat))
-    ])
-  )
-);
-var NO_MATCH = { valid: false, pubkey: null };
-var verifyNoteSignatureAgainst = (k1, amountMsat, signatureHex, mintPubkeys) => {
-  const targets = (Array.isArray(mintPubkeys) ? mintPubkeys : [mintPubkeys]).filter((key) => typeof key === "string").map((key) => key.trim().toLowerCase());
-  if (targets.length === 0) return NO_MATCH;
-  let wireSig;
-  try {
-    wireSig = hexToBytes(signatureHex);
-  } catch {
-    return NO_MATCH;
-  }
-  if (wireSig.length !== 65) return NO_MATCH;
-  let digest;
-  try {
-    digest = noteSignatureDigest(k1, amountMsat);
-  } catch {
-    return NO_MATCH;
-  }
-  const recoveryIdFirst = new Uint8Array([
-    wireSig[64],
-    ...wireSig.subarray(0, 64)
-  ]);
-  for (const candidate of [recoveryIdFirst, wireSig]) {
-    try {
-      const recovered = bytesToHex(
-        secp256k1.recoverPublicKey(candidate, digest, { prehash: false })
-      );
-      if (targets.includes(recovered)) return { valid: true, pubkey: recovered };
-    } catch {
-    }
-  }
-  return NO_MATCH;
-};
-var verifyNoteSignature = (k1, amountMsat, signatureHex, mintPubkeys) => verifyNoteSignatureAgainst(k1, amountMsat, signatureHex, mintPubkeys).valid;
 
 // src/settle.ts
 var normaliseHost = (value) => serverOf(value.trim().replace(/^@/, "")).toLowerCase();
@@ -1119,4 +1192,4 @@ var createClient = (options = {}) => ({
   settleNoteForValue: (noteUrl, terms) => settleNoteForValue(noteUrl, terms, options)
 });
 
-export { AmbiguousMintError, AmbiguousMutationError, InsufficientValueError, LnurlcashError, NoteSpentError, NoteUnknownError, PAYMENT_REQUEST_PREFIX, PendingNoteError, ProtocolError, RequestRefusedError, ServiceRejectedError, applyMintFee, buildNoteUrl, claimMintedNote, classifyNoteError, createClient, decodeBolt11AmountMsat, decodePaymentRequest, defaultRandomSecret, deriveNoteRoot, deriveNoteSecret, derivedSecretSource, describeMintFee, encodePaymentRequest, fetchInvoiceVerification, fetchMintAddress, fetchNoteInfo, fetchPayRequest, formatFeePercent, fromBech32Lnurl, fromLud17, grossUpForMintFee, hashK1, isAllowedServiceUrl, isBech32Lnurl, isBolt11Invoice, isLightningAddress, isPaymentRequest, isPreimage, isValidNoteInput, lightningAddressUsername, meltNote, mergeNotes, mergeNotesWithHash, mintAddressUrl, mintFeeBand, newSecretsOf, noteDeclaredAmount, noteK1, noteSignature, noteSignatureDigest, noteSignatureMessage, parseMintFee, paymentRequestAmountMsat, probeBurnedNote, requestInvoice, requireNoteK1, resolveLnurlInput, resolveMintInput, resolveNoteInput, restoreNotes, rotateNote, rotateNoteWithHash, sameInvoice, serverOf, settleNote, settleNoteForValue, splitNote, splitNoteWithHash, toBech32Lnurl, toLud17w, verifyNoteSignature, verifyNoteSignatureAgainst, withNewK1, withinMintFeeBand, withoutK1 };
+export { AmbiguousMintError, AmbiguousMutationError, InsufficientValueError, LnurlcashError, NoteSpentError, NoteUnknownError, PAYMENT_REQUEST_PREFIX, PendingNoteError, ProtocolError, RequestRefusedError, ServiceRejectedError, applyMintFee, buildNoteUrl, claimMintedNote, classifyNoteError, createClient, decodeBolt11AmountMsat, decodePaymentRequest, defaultRandomSecret, deriveNoteRoot, deriveNoteSecret, derivedSecretSource, describeMintFee, encodePaymentRequest, fetchInvoiceVerification, fetchMintAddress, fetchNoteInfo, fetchPayRequest, formatFeePercent, fromBech32Lnurl, fromLud17, grossUpForMintFee, hashK1, isAllowedServiceUrl, isBech32Lnurl, isBolt11Invoice, isLightningAddress, isPaymentRequest, isPreimage, isValidNoteInput, lightningAddressUsername, meltNote, mergeNotes, mergeNotesWithHash, mintAddressUrl, mintFeeBand, newSecretsOf, noteDeclaredAmount, noteK1, noteSignature, noteSignatureDigest, noteSignatureDigestForHash, noteSignatureMessage, noteSignatureMessageForHash, parseMintFee, paymentRequestAmountMsat, probeBurnedNote, requestInvoice, requireBoundMintQuote, requireNoteK1, resolveLnurlInput, resolveMintInput, resolveNoteInput, restoreNotes, rotateNote, rotateNoteWithHash, sameInvoice, serverOf, settleNote, settleNoteForValue, splitNote, splitNoteWithHash, toBech32Lnurl, toLud17w, validateBoundMintReceipt, verifyNoteSignature, verifyNoteSignatureAgainst, verifyNoteSignatureHash, verifyNoteSignatureHashAgainst, withNewK1, withinMintFeeBand, withoutK1 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lnurlcash-kit",
-  "version": "0.2.1",
+  "version": "0.3.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.2.2",
+    "lnurlcash-conformance": "^0.3.0",
     "tsup": "^8.5.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"