@forgesworn/moneyer 0.3.3 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # 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
+  hidden service, and a request arriving on that host gets every URL built
+  from it: the callback, the `withdrawLink`, the `payLink`, the lightning
+  address in the metadata. Without it a Tor visitor was answered with the
+  clearnet origin, so their wallet was told to leave Tor to finish the job
+  - the callback fetch going out over clearnet, from their address, naming
+  the mint they bank with. That is worse than not working, because it looks
+  like it worked.
+- The Host header **chooses** between origins here and never builds one.
+  `MONEYER_PUBLIC_ORIGIN` exists because that header is attacker
+  controlled, and the 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.
+
 ## [0.3.3] - 2026-08-22
 
 - **Refusals are logged, so an operator can see why a wallet is failing.**

package/README.md

@@ -76,6 +76,7 @@ default, and a variable set to an empty string counts as unset.
 | `MONEYER_HOST` | `127.0.0.1` | listen address |
 | `MONEYER_PORT` | `3737` | listen port |
 | `MONEYER_PUBLIC_ORIGIN` | derived from `Host` | the origin wallets are told to call back on. Required behind a reverse proxy, and required for zap-to-note |
+| `MONEYER_ONION_URL` | | this mint as a Tor hidden service, e.g. `http://<v3>.onion`. A request arriving on that host gets its URLs built from it (see below) |
 | `MONEYER_USERNAME` | `mint` | the local part of the mint's own lightning address |
 | `MONEYER_DESCRIPTION` | `an LNURLcash note` | what a note is called on the wire (`defaultDescription`, and `description` on discovery) |
 | `MONEYER_DB` | `moneyer.sqlite` | SQLite path; `:memory:` allowed |
@@ -489,6 +490,59 @@ A registered name resolves on both rails at once:
 The discovery endpoint advertises `namePriceMsat` while registration is
 open, so a wallet can offer the flow without asking.
 
+## Reaching the mint over Tor
+
+Set `MONEYER_ONION_URL` to this mint's hidden service address and a request
+that arrives on that host gets every URL built from it: the callback, the
+`withdrawLink`, the `payLink`, the lightning address in the metadata.
+
+Without it a Tor visitor is answered with the clearnet origin, and their
+wallet is then told to leave Tor to finish the job - the callback fetch
+goes out over clearnet, from their address, naming the mint they bank
+with. That is worse than not working, because it looks like it worked.
+
+The Host header **chooses** between origins here; it never builds one.
+`MONEYER_PUBLIC_ORIGIN` exists precisely because the header is attacker
+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
+clearnet.
+
 ## Endpoints
 
 | | |

package/dist/config.d.ts

@@ -21,6 +21,7 @@ export type MoneyerConfig = {
     host: string;
     port: number;
     publicOrigin?: string;
+    onionUrl?: string;
     username: string;
     description: string;
     name?: string;

package/dist/config.js

@@ -139,6 +139,32 @@ export const configFromEnv = (env = process.env) => {
             throw new Error(`MONEYER_PUBLIC_ORIGIN must be http or https, got ${JSON.stringify(publicOrigin)}.`);
         }
     }
+    // The same mint reached over Tor. A hidden service is a different
+    // origin, and a mint that answers a Tor visitor with its clearnet URL
+    // has told that visitor's wallet to leave Tor to finish the job - which
+    // is both broken and the exact thing they came here to avoid.
+    //
+    // Setting this does not weaken the reason publicOrigin exists. The Host
+    // header is spoofable, which is why it is not trusted to BUILD an
+    // origin; it is only used to CHOOSE between origins the operator
+    // configured. The worst a forged Host can do is get the onion URL back
+    // instead of the clearnet one, and the operator set both.
+    const onionUrl = env.MONEYER_ONION_URL;
+    if (onionUrl) {
+        let parsed;
+        try {
+            parsed = new URL(onionUrl);
+        }
+        catch {
+            throw new Error(`MONEYER_ONION_URL is not a URL: ${JSON.stringify(onionUrl)}.`);
+        }
+        if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+            throw new Error(`MONEYER_ONION_URL must be http or https, got ${JSON.stringify(onionUrl)}.`);
+        }
+        if (!parsed.hostname.endsWith('.onion')) {
+            throw new Error(`MONEYER_ONION_URL must be a .onion address, got ${JSON.stringify(parsed.hostname)}.`);
+        }
+    }
     const motd = text(env.MONEYER_MOTD);
     if (motd !== undefined && motd.length > MOTD_MAX) {
         throw new Error(`MONEYER_MOTD must be at most ${MOTD_MAX} characters - it is a banner, not a page.`);
@@ -174,6 +200,7 @@ export const configFromEnv = (env = process.env) => {
         host: env.MONEYER_HOST ?? DEFAULTS.host,
         port: int(env.MONEYER_PORT, DEFAULTS.port),
         ...(publicOrigin ? { publicOrigin } : {}),
+        ...(onionUrl ? { onionUrl } : {}),
         username: env.MONEYER_USERNAME ?? DEFAULTS.username,
         description: env.MONEYER_DESCRIPTION ?? DEFAULTS.description,
         ...(name ? { name } : {}),

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` : ''}`);
@@ -302,7 +303,23 @@ export const createMoneyer = async (config, deps = {}) => {
     const handle = async (req, res) => {
         const requestUrl = new URL(req.url ?? '/', `http://${req.headers.host ?? '127.0.0.1'}`);
         const q = requestUrl.searchParams;
-        const origin = config.publicOrigin ?? `http://${req.headers.host ?? '127.0.0.1'}`;
+        // Which of this mint's own origins the caller reached it on. The Host
+        // header chooses between them and never builds one: it is attacker
+        // controlled, and the worst a forged value can do here is get back an
+        // origin the operator configured anyway.
+        const onionHost = config.onionUrl ? new URL(config.onionUrl).host.toLowerCase() : null;
+        const askedFor = (req.headers.host ?? '').toLowerCase();
+        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, {
@@ -547,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') {
@@ -717,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/llms.txt

@@ -65,6 +65,11 @@ verifyAnnouncement(content, mintPubkey) -> {valid, document}
   discovery document + sig by the note signing key. MONEYER_ANNOUNCE=true,
   off by default.
 configFromEnv(env?) -> MoneyerConfig     MONEYER_* environment variables
+  MONEYER_ONION_URL: this mint as a Tor hidden service. A request arriving on
+  that Host gets every URL (callback, withdrawLink, payLink, the address in
+  the metadata) built from it; anything else falls through to
+  MONEYER_PUBLIC_ORIGIN. The Host header only CHOOSES between origins the
+  operator configured - it never builds one.
 createFakeBackend() -> LightningBackend with .control test hooks
 createClnBackend({url, rune}) / createLndBackend({url, macaroon})
 createNoteSigner(privHex) -> {pubkey, sign(noteId, amountMsat)}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgesworn/moneyer",
-  "version": "0.3.3",
+  "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",