@forgesworn/moneyer 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [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.**
+  A holder reported "notes already spent" on every melt and the journal for
+  that whole day carried startup banners and one invoice sweep - nothing to
+  compare the report against. Refusals now log the method, the path and the
+  reason. Never the query string, because a note URL carries the k1 and log
+  files travel; and never the informational GET, which a single restore
+  walks twenty-odd unknown indexes of by design.
+
 ## [0.3.2] - 2026-08-22
 
 - **A note with a melt in flight is no longer advertised as withdrawable.**

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,28 @@ 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`.
+
+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

@@ -302,7 +302,15 @@ 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'}`);
         const host = new URL(origin).host;
         const send = (body, status = 200) => {
             res.writeHead(status, {
@@ -312,7 +320,20 @@ export const createMoneyer = async (config, deps = {}) => {
             });
             res.end(JSON.stringify(body));
         };
-        const fail = (reason, status = 200) => send({ status: 'ERROR', reason }, status);
+        // Refusals go to the operator's log, because a mint that refuses in
+        // silence cannot be debugged from the outside: a wallet shows its user
+        // "already spent" and the operator has nothing at all to compare it to.
+        //
+        // The PATHNAME only, never the query string: a note URL carries the k1,
+        // and a k1 is the money. And never the informational GET, which a
+        // single restore walks twenty-odd unknown indexes of by design - that
+        // is not news, and burying the rare refusals under it defeats the point.
+        const fail = (reason, status = 200) => {
+            if (requestUrl.pathname !== '/w') {
+                log(`refused ${req.method ?? 'GET'} ${requestUrl.pathname}: ${reason}`);
+            }
+            send({ status: 'ERROR', reason }, status);
+        };
         const knownUser = (user) => user === config.username || user === '_';
         // ---- the mint's face ----
         if (requestUrl.pathname === '/' && (req.method === 'GET' || req.method === 'HEAD')) {

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.2",
+  "version": "0.4.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",