@forgesworn/moneyer 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.5.0] - 2026-08-23
+
+- **Both doors, named.** With `MONEYER_ONION_URL` and
+  `MONEYER_PUBLIC_ORIGIN` both set, `/w` and the mint address now carry
+  `mirrors`: this mint's other origin. Both serve the same notes - a note
+  is keyed by `sha256(k1)` and not by host - but a note travels as a URL,
+  and a URL names one host, so an onion note handed to somebody without
+  Tor is unspendable to them. Naming the other door is what lets a wallet
+  offer the holder a way across.
+- Absent rather than empty when there is only one door, because a wallet
+  reading `[]` would think it had been told something. The hourly Nostr
+  announcement carries it too.
+- Documented, because it is a real limit rather than a missing feature: a
+  wallet must **not** fail over to a mirror on its own. Every request that
+  identifies a note carries the k1, and nothing in LUD-25 lets a host
+  prove it is the same mint before receiving that secret - a hostile
+  discovery document can name any host and claim any `mintPubkey`, since
+  claiming is not proving. Closing it needs a signed challenge the spec
+  does not have.
+
 ## [0.4.0] - 2026-08-23
 
 - **Reaching the mint over Tor.** `MONEYER_ONION_URL` names this mint's

package/README.md

@@ -507,6 +507,37 @@ controlled, and that property is unchanged: the worst a forged Host can do
 is get back the onion URL instead of the clearnet one, and the operator
 configured both. Anything else falls through to `MONEYER_PUBLIC_ORIGIN`.
 
+### Serving both audiences at once
+
+Both doors serve the **same notes**. A note is keyed by `sha256(k1)` and
+not by host, so a k1 struck on the onion is valid at the clearnet host and
+the other way round. What is bound to a host is only the URL a note
+travels as - and an onion note handed to somebody without Tor is
+unspendable to them, while a clearnet note redeemed over Tor is private
+only if their wallet proxies.
+
+So when both are configured, `/w` and the mint address name the other one
+in `mirrors`:
+
+```json
+{"tag": "withdrawRequest", "callback": "http://<v3>.onion/w/cb",
+ "mirrors": ["https://mint.example"], "mintPubkey": "..."}
+```
+
+Absent when there is only one door, rather than an empty array - a wallet
+reading `[]` would think it had been told something. The hourly Nostr
+announcement carries it too, so a wallet that discovers this mint on a
+relay learns both doors before it holds anything.
+
+**A wallet must not fail over to a mirror on its own.** Every request that
+identifies a note carries the k1, so switching hosts discloses a bearer
+secret to the new one, and nothing in LUD-25 lets a host prove it is the
+same mint before receiving that secret - a hostile discovery document can
+name any host and claim any `mintPubkey`, because claiming is not proving.
+Show the holder the other door and let them choose it. Closing that
+properly needs a challenge the mint signs, which the spec does not have
+yet.
+
 Running the hidden service itself is not this mint's job. Point a Tor
 `HiddenServiceDir` (or a proxy that speaks onion) at whatever host and port
 it already listens on, the same way you would front it with Caddy for

package/dist/server.js

@@ -208,7 +208,7 @@ export const createMoneyer = async (config, deps = {}) => {
     // LUD-25 discovery, built here rather than inline in its route because
     // the mint also announces itself with it, and there must be one
     // description of a mint rather than two that can drift apart.
-    const mintAddressDocument = (origin, user) => ({
+    const mintAddressDocument = (origin, user, mirrors = []) => ({
         tag: 'withdrawRequest',
         callback: `${origin}/w`,
         minWithdrawable: config.minMintMsat,
@@ -217,6 +217,7 @@ export const createMoneyer = async (config, deps = {}) => {
             : config.maxSendableMsat,
         defaultDescription: config.description,
         payLink: `${origin}/.well-known/lnurlp/${user}`,
+        ...(mirrors.length ? { mirrors } : {}),
         ...(signer ? { mintPubkey: signer.pubkey } : {}),
         // The human layer: who runs this, how to reach them, the terms,
         // and today's message. Absent unless the operator set it.
@@ -294,7 +295,7 @@ export const createMoneyer = async (config, deps = {}) => {
             kind: ANNOUNCE_KIND,
             created_at: Math.floor(Date.now() / 1000),
             tags: [['d', ANNOUNCE_D_TAG]],
-            content: announcementContent(mintAddressDocument(config.publicOrigin, config.username), config.signingKey)
+            content: announcementContent(mintAddressDocument(config.publicOrigin, config.username, config.onionUrl ? [config.onionUrl] : []), config.signingKey)
         }, hexToBytes(config.zap.nostrKey));
         const { ok, failed } = await nostr.publish(config.zap.relays, event);
         log(`mint announced to ${ok.length} relay${ok.length === 1 ? '' : 's'}${failed.length ? `, ${failed.length} refused` : ''}`);
@@ -311,6 +312,14 @@ export const createMoneyer = async (config, deps = {}) => {
         const origin = onionHost && askedFor === onionHost
             ? config.onionUrl
             : (config.publicOrigin ?? `http://${req.headers.host ?? '127.0.0.1'}`);
+        // This mint's OTHER doors. A note is keyed by sha256(k1) and not by
+        // host, so every one of these serves the same notes - but a note
+        // travels as a URL, and a URL names one host. An onion note handed to
+        // somebody without Tor is unspendable to them, and a clearnet note
+        // redeemed over Tor is only private if their wallet proxies. Saying
+        // which other host answers is what lets a wallet move a note between
+        // them instead of the holder finding out it cannot.
+        const mirrors = [config.publicOrigin, config.onionUrl].filter((candidate) => Boolean(candidate) && candidate !== origin);
         const host = new URL(origin).host;
         const send = (body, status = 200) => {
             res.writeHead(status, {
@@ -555,7 +564,7 @@ export const createMoneyer = async (config, deps = {}) => {
         if (lnurlwMatch) {
             if (!knownUser(lnurlwMatch[1]))
                 return fail('Unknown user.', 404);
-            return send(mintAddressDocument(origin, lnurlwMatch[1]));
+            return send(mintAddressDocument(origin, lnurlwMatch[1], mirrors));
         }
         // ---- LUD-06 pay callback: issue a mint invoice ----
         if (requestUrl.pathname === '/p/cb') {
@@ -725,6 +734,10 @@ export const createMoneyer = async (config, deps = {}) => {
                 // signing keys. Without it a wallet that only ever received notes
                 // cannot tell an announced key rotation from a substituted key.
                 payLink: `${origin}/.well-known/lnurlp/${config.username}`,
+                // Where else this same note can be redeemed. A holder with nothing
+                // but a note learns from the note itself that the other door
+                // exists.
+                ...(mirrors.length ? { mirrors } : {}),
                 ...(signer ? { mintPubkey: signer.pubkey } : {})
             });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgesworn/moneyer",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "An LNURLcash (LUD-25) mint - strikes Lightning bearer notes. Independent implementation, cln/lnd funding sources, SQLite, zero HTTP framework.",
   "author": "TheCryptoDonkey",
   "license": "MIT",