lnurlcash-conformance 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -4,6 +4,28 @@ 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.2.2 - 2026-08-22
+
+- The mock mint publishes `payLink` on a note's informational GET, as the
+  reference mint does. That is the way home for a holder who has nothing
+  but a note: without it a wallet that only ever received notes cannot
+  reach the document carrying the mint's retired signing keys, so a
+  correctly announced key rotation is indistinguishable from a substituted
+  key. `noteInfoPayLink: false` models a mint that does not publish it, and
+  `payLinkOffOrigin: true` is the misbehaviour where a mint points its
+  `payLink` at a different origin, nominating a third party to vouch for
+  its own key history - a client must ignore that.
+
+## 0.2.1 - 2026-08-22
+
+- The grader ships its own TypeScript declarations. The mock mint had them
+  and the runner did not, so a TypeScript consumer hand-wrote a
+  `declare module` shim, and those drift: moneyer carried one, `gradeBoundMint`
+  landed here, and the shim did not know about it. A consumer could not call
+  the newest check without editing a copy of a declaration it does not own.
+  Now `runner/index.d.ts` sits next to the code it describes and the exports
+  map points at it. No runtime change of any kind.
+
 ## 0.2.0 - 2026-08-22
 
 - Naming the note you are buying. In LUD-25 a minted note's `k1` is the

package/mock-mint/index.d.ts

@@ -38,7 +38,19 @@ export interface MockMintOptions {
   verify?: boolean
   privateKey?: string
 
+  /**
+   * Publish `payLink` on a note's informational GET - the way home for a
+   * holder who has nothing but the note. On by default, as the reference
+   * mint does it.
+   */
+  noteInfoPayLink?: boolean
+
   // ---- misbehaviour ----
+  /**
+   * Point `payLink` at a different origin, nominating a third party to
+   * vouch for this mint's key history. A client must ignore it.
+   */
+  payLinkOffOrigin?: boolean
   /** answer the informational GET with a k1 other than the one queried */
   echoWrongK1?: boolean
   /** report a maxWithdrawable that is not what the note is worth */

package/mock-mint/index.mjs

@@ -70,7 +70,14 @@ const DEFAULTS = {
   // preimage it serves IS a bearer secret, so an operator needs a real
   // off switch.
   verify: true,
+  // Publish `payLink` on a note's informational GET, the way home for a
+  // holder who has nothing but the note. On by default because the
+  // reference mint does it; turn it off for a mint that does not.
+  noteInfoPayLink: true,
   // ---- misbehaviour ----
+  // point `payLink` at a DIFFERENT origin, nominating a third party to
+  // vouch for this mint's key history. A client must ignore it.
+  payLinkOffOrigin: false,
   // answer the informational GET with a k1 other than the one queried
   echoWrongK1: false,
   // report a maxWithdrawable that is not what the note is worth
@@ -673,6 +680,19 @@ export const createMockMint = async (options = {}) => {
         minWithdrawable: 0,
         maxWithdrawable: note.amountMsat + opts.lieAboutValue,
         defaultDescription: 'an LNURLcash note',
+        // The way home, as the reference mint publishes it. A holder with
+        // nothing but a note can reach the document carrying this mint's
+        // terms and its retired signing keys; without it a wallet that only
+        // ever received notes cannot tell an announced key rotation from a
+        // substituted key, because the document lives under a username the
+        // note never mentions.
+        ...(opts.noteInfoPayLink
+          ? {
+              payLink: opts.payLinkOffOrigin
+                ? 'https://elsewhere.example/.well-known/lnurlp/mint'
+                : `${origin}/.well-known/lnurlp/${opts.username}`
+            }
+          : {}),
         mintPubkey: pubkey
       })
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lnurlcash-conformance",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Language-neutral conformance vectors, an adversarial mock mint, and a grader for LNURLcash (LUD-25) implementations",
   "author": "TheCryptoDonkey",
   "license": "MIT",
@@ -34,7 +34,10 @@
     "llms.txt"
   ],
   "exports": {
-    ".": "./runner/index.mjs",
+    ".": {
+      "types": "./runner/index.d.ts",
+      "default": "./runner/index.mjs"
+    },
     "./vectors/*": "./vectors/*",
     "./mock-mint": {
       "types": "./mock-mint/index.d.ts",

package/runner/index.d.ts

@@ -0,0 +1,100 @@
+// Types for the grader, so a TypeScript consumer gets its shape checked
+// rather than hand-writing a `declare module` shim of its own. Hand-written
+// to match index.mjs.
+//
+// This file exists because those shims drift. moneyer carried one, the
+// grader grew gradeBoundMint, and the shim did not: the consumer could not
+// call the newest check without editing a copy of a declaration it does not
+// own. Shipping the declarations puts that in one place, next to the code
+// they describe.
+
+/** what the mint fee is, in LUD-25's own two terms */
+export interface MintFee {
+  baseFeeMsat: number
+  feePpm: number
+}
+
+export type ReportStatus = 'pass' | 'fail' | 'warn' | 'skip'
+
+export interface ReportResult {
+  status: ReportStatus
+  name: string
+  /** what the check saw, in a sentence. Present on nearly every result */
+  detail?: string
+}
+
+export interface Report {
+  results: ReportResult[]
+  pass(name: string, detail?: string): void
+  fail(name: string, detail?: string): void
+  warn(name: string, detail?: string): void
+  skip(name: string, detail?: string): void
+  /**
+   * Runs `fn` and records the outcome. A thrown error is a failure; an
+   * error carrying a truthy `warning` is a warning, which is how an
+   * optional extension in the wrong shape is reported without failing a
+   * mint that need not have published it at all.
+   */
+  check(name: string, fn: () => Promise<unknown> | unknown): Promise<void>
+  /** how many results are failures */
+  readonly failed: number
+}
+
+export declare const createReport: () => Report
+
+/** an `lnurlw://` or `lnurlp://` URL as its https equivalent, per LUD-17 */
+export declare const fromLud17: (value: string) => string
+
+/** a lightning address or LNURL as the payRequest URL to fetch */
+export declare const resolveMint: (input: string) => string
+
+/** the msat a bolt11 invoice states, or null where it states none */
+export declare const invoiceAmountMsat: (pr: string) => number | null
+
+/** what a gross mint of `gross` msat leaves once `fee` is withheld */
+export declare const applyMintFee: (gross: number, fee: MintFee | null) => number
+
+/** the `Mint fees: base,ppm` line out of a payRequest's metadata array */
+export declare const parseAdvertisedMintFee: (metadata: string) => MintFee | null
+
+/** the read-only mint checks: payRequest, withdrawLink, fees, verify, extensions */
+export declare const gradeMint: (payUrl: string, report: Report) => Promise<void>
+
+/**
+ * Read-only. Needs a freshly minted, never-rotated note and what its mint
+ * invoice was paid at, and grades the note's value against the advertised
+ * fee.
+ */
+export declare const gradeMintedValue: (
+  noteUrl: string,
+  report: Report,
+  options: {paidMsat: number; mintFee?: MintFee | null}
+) => Promise<void>
+
+/**
+ * Read-only. Needs a note minted against a hash the WALLET chose, plus the
+ * payment preimage of the invoice that funded it. Checks that the note is
+ * at the wallet's own secret and that the preimage opens nothing.
+ *
+ * `payCallback` is optional: with it, the runner also checks that the id
+ * the note occupies cannot be sold again as a mint quote.
+ */
+export declare const gradeBoundMint: (
+  noteUrl: string,
+  report: Report,
+  options: {preimage: string; payCallback?: string | null}
+) => Promise<void>
+
+/**
+ * SPENDS. Burns the note it is given and leaves the value in a fresh one.
+ *
+ * `mintFee` absent means unknown, and the conservation checks are bounded
+ * rather than exact; null means known fee-free. `previousPubkeys` are keys
+ * the mint has signed under before, so a note issued before a rotation is
+ * not graded as a bad signature.
+ */
+export declare const gradeNote: (
+  noteUrl: string,
+  report: Report,
+  options?: {mintFee?: MintFee | null; previousPubkeys?: string[]}
+) => Promise<void>