lnurlcash-kit 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -3,6 +3,84 @@
 Semantic versioning. While the LUD-25 draft is unmerged, `0.x` minor bumps
 may carry breaking changes; pin an exact version.
 
+## 0.4.0 - 2026-08-26
+
+**Breaking: `restoreNotes` asks by hash, and no longer discloses note
+secrets by default.**
+
+The walk queries every index up to `gap` past the last one in use, and those
+are exactly the indices the wallet is about to mint into next. Asking by
+secret therefore published the next `gap` secrets the wallet would ever use,
+in cleartext query strings, and the returned `next` then pointed straight at
+one of them. A five-note wallet put twenty-five live-or-future secrets on the
+wire and resumed at an index it had just disclosed.
+
+- The walk now uses the informational GET's `h` parameter (LUD-25, "Checking
+  a note without exposing it"), so nothing spendable leaves the wallet.
+  `fetchNoteInfoByHash` and `buildNoteInfoUrlByHash` expose it directly, and
+  `RestoredNote.callback` carries the callback so a caller need not ask again
+  with the raw secret.
+- `RestoreOptions.allowSecretDisclosure` (default `false`) permits the old
+  form as an explicit fallback, never automatically. When it is used,
+  `RestoreResult.disclosesSecrets` is `true` and `next` skips every index the
+  walk touched, because a disclosed secret is spent whether or not a note was
+  ever minted under it.
+- `h` support is OPTIONAL in LUD-25 with no capability flag, so a SERVICE
+  that cannot answer by hash is indistinguishable from one holding none of
+  the notes asked about. A walk that never gets a positive answer now throws
+  `HashLookupUnsupportedError` rather than reporting an empty wallet.
+  `RestoreOptions.probeK1` supplies a positive control, and
+  `RestoreResult.hashLookupsConfirmed` reports what was established.
+
+**`requestInvoice` names the mint output with a LUD-12 `comment`.**
+
+LUD-25 specifies the mint-time output hash as `comment = hex(h)`, and that is
+what a conforming SERVICE reads. The kit sent only `h`, a parameter one
+implementation adopted before the comment form was written, so a wallet
+naming an output against a conforming mint was silently ignored and its note
+was keyed by the payment preimage instead.
+
+- `comment` is now sent alongside `h`. A SERVICE reading either gets the same
+  hash; one reading neither behaves exactly as before.
+- This matters beyond conformance: an unnamed mint's `k1` **is** the payment
+  preimage `P`, so a SERVICE offering LUD-21 `verify` on that payment hands
+  the note to whoever holds the verify URL. Naming the output is what makes
+  `verify` safe to offer at all.
+
+- `PayRequestInfo.commentAllowed` is surfaced and `namesMintOutput()` decides
+  the capability from either spelling: LUD-25 advertises it as
+  `commentAllowed >= 64`, one mint shipped `mintToHash` first. One rule in
+  one place, because both directions of a wrong answer cost a note - read it
+  as no and the note is the payment preimage, published on the mint's verify
+  URL; read it as yes and the wallet waits for a note minted elsewhere.
+
+**Also breaking: an unrecognised refusal no longer aborts a restore, and no
+longer counts toward the gap.**
+
+`classifyNoteError` falls through to a bare `ServiceRejectedError` for any
+reason string it has no pattern for, and the walk rethrew it, so a single
+unfamiliar reason from a SERVICE ended the whole restore. Any new note state
+- expiry being the obvious one - would have done it.
+
+- Only `NoteUnknownError` advances the gap counter now. Every other refusal
+  means the SERVICE knows the index, so it resets the counter and is reported
+  in the new `RestoreResult.unresolved`. Advancing it was how a walk could
+  terminate early and silently abandon live notes beyond the run.
+- Transport and protocol failures still throw: a SERVICE being down is not a
+  statement about an index.
+
+## 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

@@ -31,6 +31,9 @@ declare const grossUpForMintFee: (netMsat: number, fee: MintFee) => number;
 declare const formatFeePercent: (ppm: number) => string;
 declare const describeMintFee: (fee: MintFee) => string;
 
+type NoteInfoByHash = Omit<WithdrawRequestInfo, 'k1'> & {
+    k1?: string;
+};
 type WithdrawRequestInfo = {
     tag: 'withdrawRequest';
     callback: string;
@@ -42,6 +45,7 @@ type WithdrawRequestInfo = {
     payLink?: string;
 };
 declare const fetchNoteInfo: (url: string, options?: LnurlcashOptions) => Promise<WithdrawRequestInfo>;
+declare const fetchNoteInfoByHash: (withdrawLink: string, h: string, options?: LnurlcashOptions) => Promise<NoteInfoByHash>;
 declare const probeBurnedNote: (url: string, options?: LnurlcashOptions) => Promise<"live" | "gone" | "unknown">;
 type MintContact = {
     nostr?: string;
@@ -126,13 +130,27 @@ type PayRequestInfo = {
     mintPubkey?: string;
     mintFee?: MintFee;
     mintToHash?: boolean;
+    commentAllowed?: number;
 };
 declare const fetchPayRequest: (url: string, options?: LnurlcashOptions) => Promise<PayRequestInfo>;
+declare const namesMintOutput: (info: {
+    mintToHash?: boolean;
+    commentAllowed?: number;
+}) => boolean;
 type InvoiceResult = {
     pr: string;
     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 +160,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;
@@ -168,16 +189,27 @@ type RestoredNote = {
     k1: string;
     amountMsat: number | null;
     state: 'live' | 'pending';
+    callback?: string;
+};
+type UnresolvedIndex = {
+    index: number;
+    k1: string;
+    reason: string;
 };
 type RestoreResult = {
     found: RestoredNote[];
+    unresolved: UnresolvedIndex[];
     next: number;
+    hashLookupsConfirmed: boolean;
+    disclosesSecrets: boolean;
 };
 type RestoreOptions = {
     gap?: number;
     start?: number;
+    probeK1?: string;
+    allowSecretDisclosure?: boolean;
 };
-declare const restoreNotes: (baseUrl: string, root: Uint8Array, host: string, { gap, start }?: RestoreOptions, options?: LnurlcashOptions) => Promise<RestoreResult>;
+declare const restoreNotes: (baseUrl: string, root: Uint8Array, host: string, { gap, start, probeK1, allowSecretDisclosure }?: RestoreOptions, options?: LnurlcashOptions) => Promise<RestoreResult>;
 
 declare const isBech32Lnurl: (data: string) => boolean;
 declare const toBech32Lnurl: (url: string) => string;
@@ -198,6 +230,7 @@ declare const noteDeclaredAmount: (url: string) => number | null;
 declare const noteSignature: (url: string) => string | null;
 declare const resolveNoteInput: (value: string) => string | null;
 declare const isValidNoteInput: (value: string) => boolean;
+declare const buildNoteInfoUrlByHash: (withdrawLink: string, h: string) => string;
 declare const buildNoteUrl: (withdrawLink: string, k1: string, amountMsat?: number) => string;
 declare const withNewK1: (url: string, k1: string, amountMsat: number, signature?: string) => string;
 declare const withoutK1: (url: string, amountMsat: number, signature?: string) => string;
@@ -226,7 +259,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 +270,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;
@@ -262,6 +299,8 @@ declare class NoteSpentError extends ServiceRejectedError {
 declare class NoteUnknownError extends ServiceRejectedError {
     constructor(reason: string);
 }
+declare class HashLookupUnsupportedError extends LnurlcashError {
+}
 declare class AmbiguousMintError extends LnurlcashError {
 }
 declare class AmbiguousMutationError extends AmbiguousMintError {
@@ -278,6 +317,7 @@ declare const classifyNoteError: (reason: string) => ServiceRejectedError;
 
 declare const createClient: (options?: LnurlcashOptions) => {
     fetchNoteInfo: (url: string) => Promise<WithdrawRequestInfo>;
+    fetchNoteInfoByHash: (withdrawLink: string, h: string) => Promise<NoteInfoByHash>;
     probeBurnedNote: (url: string) => Promise<"live" | "gone" | "unknown">;
     fetchMintAddress: (url: string) => Promise<MintAddressInfo>;
     meltNote: (callback: string, k1: string, pr: string) => Promise<MeltResult>;
@@ -297,4 +337,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, HashLookupUnsupportedError, 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, type NoteInfoByHash, 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 UnresolvedIndex, type ValidatedBoundMintReceipt, type VerifyResult, type WithdrawRequestInfo, type WithdrawSuccessResponse, applyMintFee, buildNoteInfoUrlByHash, buildNoteUrl, claimMintedNote, classifyNoteError, createClient, decodeBolt11AmountMsat, decodePaymentRequest, defaultRandomSecret, deriveNoteRoot, deriveNoteSecret, derivedSecretSource, describeMintFee, encodePaymentRequest, fetchInvoiceVerification, fetchMintAddress, fetchNoteInfo, fetchNoteInfoByHash, fetchPayRequest, formatFeePercent, fromBech32Lnurl, fromLud17, grossUpForMintFee, hashK1, isAllowedServiceUrl, isBech32Lnurl, isBolt11Invoice, isLightningAddress, isPaymentRequest, isPreimage, isValidNoteInput, lightningAddressUsername, meltNote, mergeNotes, mergeNotesWithHash, mintAddressUrl, mintFeeBand, namesMintOutput, 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

@@ -182,6 +182,18 @@ var resolveNoteInput = (value) => {
   return url;
 };
 var isValidNoteInput = (value) => resolveNoteInput(value) !== null;
+var buildNoteInfoUrlByHash = (withdrawLink, h) => {
+  const hex = h.trim().toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(hex)) {
+    throw new Error("A note hash must be 32 bytes of hex.");
+  }
+  const url = new URL(fromLud17(withdrawLink.trim()));
+  url.searchParams.delete("k1");
+  url.searchParams.delete("amount");
+  url.searchParams.delete("sig");
+  url.searchParams.set("h", hex);
+  return url.toString();
+};
 var buildNoteUrl = (withdrawLink, k1, amountMsat) => {
   const url = new URL(fromLud17(withdrawLink.trim()));
   url.searchParams.set("k1", k1.trim().toLowerCase());
@@ -248,6 +260,8 @@ var NoteUnknownError = class extends ServiceRejectedError {
     this.message = `The service doesn't recognise this note (service says: "${reason}").`;
   }
 };
+var HashLookupUnsupportedError = class extends LnurlcashError {
+};
 var AmbiguousMintError = class extends LnurlcashError {
 };
 var AmbiguousMutationError = class extends AmbiguousMintError {
@@ -627,8 +641,69 @@ 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 assertWithdrawRequestShape = (body, { requireK1 }) => {
+  if (body?.tag !== "withdrawRequest" || typeof body.callback !== "string" || requireK1 && typeof body.k1 !== "string" || typeof body.maxWithdrawable !== "number" || !Number.isSafeInteger(body.maxWithdrawable) || body.maxWithdrawable < 0 || body.minWithdrawable !== void 0 && (typeof body.minWithdrawable !== "number" || !Number.isSafeInteger(body.minWithdrawable) || body.minWithdrawable < 0 || body.minWithdrawable > body.maxWithdrawable)) {
+    throw new ProtocolError("Not a withdrawRequest (unexpected response).");
+  }
+};
 var fetchNoteInfo = async (url, options = {}) => {
   const opts = resolveOptions(options);
   const reqUrl = new URL(url);
@@ -640,9 +715,7 @@ var fetchNoteInfo = async (url, options = {}) => {
     if (err instanceof ServiceRejectedError) throw classifyNoteError(err.reason);
     throw err;
   }
-  if (body?.tag !== "withdrawRequest" || typeof body.callback !== "string" || typeof body.k1 !== "string" || typeof body.maxWithdrawable !== "number" || !Number.isSafeInteger(body.maxWithdrawable) || body.maxWithdrawable < 0 || body.minWithdrawable !== void 0 && (typeof body.minWithdrawable !== "number" || !Number.isSafeInteger(body.minWithdrawable) || body.minWithdrawable < 0 || body.minWithdrawable > body.maxWithdrawable)) {
-    throw new ProtocolError("Not a withdrawRequest (unexpected response).");
-  }
+  assertWithdrawRequestShape(body, { requireK1: true });
   const queried = noteK1(url);
   if (queried && body.k1.toLowerCase() !== queried) {
     throw new ProtocolError(
@@ -655,6 +728,23 @@ var fetchNoteInfo = async (url, options = {}) => {
   else info.payLink = payLink;
   return info;
 };
+var fetchNoteInfoByHash = async (withdrawLink, h, options = {}) => {
+  const opts = resolveOptions(options);
+  const reqUrl = new URL(buildNoteInfoUrlByHash(withdrawLink, h));
+  let body;
+  try {
+    body = await lnurlFetch(reqUrl, opts);
+  } catch (err) {
+    if (err instanceof ServiceRejectedError) throw classifyNoteError(err.reason);
+    throw err;
+  }
+  assertWithdrawRequestShape(body, { requireK1: false });
+  const info = body;
+  const payLink = sameOriginPayLink(body.payLink, reqUrl);
+  if (payLink === void 0) delete info.payLink;
+  else info.payLink = payLink;
+  return info;
+};
 var sameOriginPayLink = (value, noteUrl) => {
   if (typeof value !== "string" || value.length === 0) return void 0;
   let candidate;
@@ -902,7 +992,21 @@ var fetchPayRequest = async (url, options = {}) => {
   return {
     ...body,
     mintFee: mintFee ?? void 0,
-    mintToHash: asBoolean(body.mintToHash)
+    mintToHash: asBoolean(body.mintToHash),
+    commentAllowed: asNumber(body.commentAllowed)
+  };
+};
+var namesMintOutput = (info) => info.mintToHash === true || typeof info.commentAllowed === "number" && info.commentAllowed >= 64;
+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 = {}) => {
@@ -914,7 +1018,9 @@ var requestInvoice = async (payCallback, amountMsat, options = {}) => {
         "An output hash must be 32 bytes of hex - no invoice was requested."
       );
     }
-    cbUrl.searchParams.set("h", options.h.trim().toLowerCase());
+    const h = options.h.trim().toLowerCase();
+    cbUrl.searchParams.set("comment", h);
+    cbUrl.searchParams.set("h", h);
   }
   const body = await lnurlFetch(cbUrl, resolveOptions(options));
   if (typeof body?.pr !== "string") {
@@ -930,7 +1036,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 +1048,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 +1125,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();
@@ -1063,18 +1174,86 @@ var settleNoteForValue = async (noteUrl, { mints, minMsat, requireSignature = fa
 };
 
 // src/restore.ts
-var restoreNotes = async (baseUrl, root, host, { gap = 20, start = 0 } = {}, options = {}) => {
+var restoreNotes = async (baseUrl, root, host, { gap = 20, start = 0, probeK1, allowSecretDisclosure = false } = {}, options = {}) => {
   if (!Number.isSafeInteger(gap) || gap < 1) {
     throw new RangeError(`The gap limit must be a positive integer, not ${gap}.`);
   }
+  if (!Number.isSafeInteger(start) || start < 0) {
+    throw new RangeError(`The start index must be a non-negative integer, not ${start}.`);
+  }
+  let hashLookupsConfirmed = false;
+  if (probeK1) {
+    try {
+      await fetchNoteInfoByHash(baseUrl, hashK1(probeK1), options);
+      hashLookupsConfirmed = true;
+    } catch (err) {
+      if (!(err instanceof ServiceRejectedError)) throw err;
+    }
+  }
+  const byHash = await walk(
+    start,
+    gap,
+    async (k1) => {
+      const info = await fetchNoteInfoByHash(baseUrl, hashK1(k1), options);
+      hashLookupsConfirmed = true;
+      return info;
+    },
+    root,
+    host
+  );
+  if (byHash.found.length > 0 || byHash.unresolved.length > 0) hashLookupsConfirmed = true;
+  if (hashLookupsConfirmed) {
+    return {
+      found: byHash.found,
+      unresolved: byHash.unresolved,
+      next: byHash.lastUsed === null ? start : byHash.lastUsed + 1,
+      hashLookupsConfirmed: true,
+      disclosesSecrets: false
+    };
+  }
+  if (!allowSecretDisclosure) {
+    throw new HashLookupUnsupportedError(
+      "This service never answered a lookup by hash, so a restore cannot tell an empty wallet from a service that only accepts raw secrets. Pass a probeK1 for a note known to exist here, or allowSecretDisclosure to walk by secret instead."
+    );
+  }
+  const bySecret = await walk(
+    start,
+    gap,
+    (k1) => fetchNoteInfo(buildNoteUrl(baseUrl, k1), options),
+    root,
+    host
+  );
+  const walkedThrough = bySecret.highestWalked === null ? start - 1 : bySecret.highestWalked;
+  const used = bySecret.lastUsed === null ? start - 1 : bySecret.lastUsed;
+  return {
+    found: bySecret.found,
+    unresolved: bySecret.unresolved,
+    // Every index this walk touched is burned, whether or not a note was
+    // ever minted under it: its secret is in a log somewhere now, so
+    // minting into it later would be minting a note a stranger can spend.
+    next: Math.max(used, walkedThrough) + 1,
+    hashLookupsConfirmed: false,
+    disclosesSecrets: true
+  };
+};
+var walk = async (start, gap, lookup, root, host) => {
   const found = [];
+  const unresolved = [];
   let lastUsed = null;
+  let highestWalked = null;
   let unknownRun = 0;
   for (let index = start; unknownRun < gap; index++) {
     const k1 = deriveNoteSecret(root, host, index);
+    highestWalked = index;
     try {
-      const info = await fetchNoteInfo(buildNoteUrl(baseUrl, k1), options);
-      found.push({ index, k1, amountMsat: info.maxWithdrawable, state: "live" });
+      const info = await lookup(k1);
+      found.push({
+        index,
+        k1,
+        amountMsat: info.maxWithdrawable,
+        state: "live",
+        callback: info.callback
+      });
       lastUsed = index;
       unknownRun = 0;
     } catch (err) {
@@ -1087,17 +1266,22 @@ var restoreNotes = async (baseUrl, root, host, { gap = 20, start = 0 } = {}, opt
         unknownRun = 0;
       } else if (err instanceof NoteUnknownError) {
         unknownRun++;
+      } else if (err instanceof ServiceRejectedError) {
+        unresolved.push({ index, k1, reason: err.reason });
+        lastUsed = index;
+        unknownRun = 0;
       } else {
         throw err;
       }
     }
   }
-  return { found, next: lastUsed === null ? start : lastUsed + 1 };
+  return { found, unresolved, lastUsed, highestWalked };
 };
 
 // src/index.ts
 var createClient = (options = {}) => ({
   fetchNoteInfo: (url) => fetchNoteInfo(url, options),
+  fetchNoteInfoByHash: (withdrawLink, h) => fetchNoteInfoByHash(withdrawLink, h, options),
   probeBurnedNote: (url) => probeBurnedNote(url, options),
   fetchMintAddress: (url) => fetchMintAddress(url, options),
   meltNote: (callback, k1, pr) => meltNote(callback, k1, pr, options),
@@ -1119,4 +1303,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, HashLookupUnsupportedError, InsufficientValueError, LnurlcashError, NoteSpentError, NoteUnknownError, PAYMENT_REQUEST_PREFIX, PendingNoteError, ProtocolError, RequestRefusedError, ServiceRejectedError, applyMintFee, buildNoteInfoUrlByHash, buildNoteUrl, claimMintedNote, classifyNoteError, createClient, decodeBolt11AmountMsat, decodePaymentRequest, defaultRandomSecret, deriveNoteRoot, deriveNoteSecret, derivedSecretSource, describeMintFee, encodePaymentRequest, fetchInvoiceVerification, fetchMintAddress, fetchNoteInfo, fetchNoteInfoByHash, fetchPayRequest, formatFeePercent, fromBech32Lnurl, fromLud17, grossUpForMintFee, hashK1, isAllowedServiceUrl, isBech32Lnurl, isBolt11Invoice, isLightningAddress, isPaymentRequest, isPreimage, isValidNoteInput, lightningAddressUsername, meltNote, mergeNotes, mergeNotesWithHash, mintAddressUrl, mintFeeBand, namesMintOutput, 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.4.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"