npm - @forgesworn/moneyer - Versions diffs - 0.1.2 → 0.2.0 - Mend

@forgesworn/moneyer 0.1.2 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (41) hide show

package/CHANGELOG.md +170 -0
package/README.md +447 -11
package/THREAT-MODEL.md +15 -6
package/dist/admin.d.ts +12 -0
package/dist/admin.js +410 -0
package/dist/announce.d.ts +12 -0
package/dist/announce.js +82 -0
package/dist/backends/cln.js +30 -8
package/dist/backends/fake-bolt11.d.ts +1 -1
package/dist/backends/fake-bolt11.js +3 -1
package/dist/backends/fake.d.ts +7 -1
package/dist/backends/fake.js +27 -11
package/dist/backends/lnd.js +30 -6
package/dist/backends/types.d.ts +3 -0
package/dist/cli.js +25 -3
package/dist/config.d.ts +29 -0
package/dist/config.js +194 -3
package/dist/index.d.ts +5 -2
package/dist/index.js +4 -1
package/dist/landing.d.ts +2 -0
package/dist/landing.js +42 -2
package/dist/melt.d.ts +1 -0
package/dist/melt.js +2 -1
package/dist/names.d.ts +39 -0
package/dist/names.js +172 -0
package/dist/privacy.d.ts +2 -0
package/dist/privacy.js +14 -0
package/dist/server.d.ts +13 -0
package/dist/server.js +561 -41
package/dist/signing.d.ts +2 -0
package/dist/signing.js +34 -0
package/dist/stats.d.ts +31 -0
package/dist/stats.js +115 -0
package/dist/store.d.ts +105 -3
package/dist/store.js +355 -19
package/dist/version.d.ts +1 -0
package/dist/version.js +17 -0
package/dist/zap.d.ts +52 -0
package/dist/zap.js +294 -0
package/llms.txt +25 -8
package/package.json +4 -3

package/dist/landing.js CHANGED Viewed

@@ -1,3 +1,4 @@
+import { MINT_KNOWS, MINT_KNOWS_HEADING } from "./privacy.js";
 import { applyMintFee } from 'lnurlcash-kit';
 // The mint's face: one self-contained page at GET /, no build step, no
 // external assets. It states what a visitor needs before trusting a mint
@@ -7,6 +8,7 @@ import { applyMintFee } from 'lnurlcash-kit';
 const escapeHtml = (value) => value.replace(/[&<>"']/g, char => `&#${char.charCodeAt(0)};`);
 export const landingPage = (args) => {
     const { config, host, mintPubkey, nodeInfo } = args;
+    const stats = args.stats ?? null;
     const address = `${config.username}@${host}`;
     const fee = config.mintFee;
     const feeLine = fee
@@ -14,12 +16,37 @@ export const landingPage = (args) => {
         : 'none';
     const maxNet = fee ? applyMintFee(config.maxSendableMsat, fee) : config.maxSendableMsat;
     const sats = (msat) => `${(msat / 1000).toLocaleString('en-GB')} sat`;
+    const title = config.name ?? nodeInfo.alias ?? 'moneyer';
+    // Contacts are shown as text, not links: a mailto or an npub someone
+    // else chose is not something this page should hand a click to. The
+    // terms are a link because a URL the operator set is the point of it.
+    // "coverage 1.92x (outstanding 48,120 sat, node 92,400 sat)", or the
+    // ratio alone in ratio-only mode. A mint with nothing outstanding has
+    // no ratio to state, so it says so in words instead.
+    const coverageLine = (() => {
+        if (!stats)
+            return null;
+        if (stats.coverage !== undefined) {
+            const ratio = `${stats.coverage.toFixed(2)}\u00d7`;
+            return stats.outstandingMsat === undefined || stats.localBalanceMsat === undefined
+                ? ratio
+                : `${ratio} (outstanding ${sats(stats.outstandingMsat)}, node ${sats(stats.localBalanceMsat)})`;
+        }
+        if (stats.outstandingMsat === 0)
+            return 'nothing outstanding';
+        return stats.outstandingMsat === undefined ? null : `outstanding ${sats(stats.outstandingMsat)}`;
+    })();
+    const contacts = [
+        config.contact?.email ? { label: 'email', value: config.contact.email } : null,
+        config.contact?.nostr ? { label: 'nostr', value: config.contact.nostr } : null,
+        config.contact?.url ? { label: 'contact', value: config.contact.url } : null
+    ].filter(entry => entry !== null);
     return `<!doctype html>
 <html lang="en">
 <head>
 <meta charset="utf-8"/>
 <meta name="viewport" content="width=device-width, initial-scale=1"/>
-<title>${escapeHtml(host)} - an LNURLcash mint</title>
+<title>${escapeHtml(title)} - an LNURLcash mint</title>
 <meta name="description" content="A moneyer strikes Lightning bearer notes. Pay ${escapeHtml(address)} and the invoice's preimage becomes your note."/>
 <style>
 :root{--bg:#0e0f12;--raise:#16181d;--line:rgba(226,233,242,.09);--ink:#eef1f6;--dim:#98a0ac;--accent:#c9ced8;--accent-deep:#8f97a4}
@@ -40,13 +67,19 @@ h1 small{display:block;font-size:16px;color:var(--dim);font-weight:500;margin-to
 .kv span{color:var(--dim)}
 .kv code{font-family:ui-monospace,Menlo,monospace;font-size:12.5px;word-break:break-all;text-align:right}
 p.small{color:var(--dim);font-size:13.5px;line-height:1.65;text-align:center}
+.knows{background:var(--raise);border:1px solid var(--line);border-radius:20px;padding:20px 22px;display:flex;flex-direction:column;gap:10px}
+.knows h2{font-size:15px;letter-spacing:.04em;text-transform:uppercase;color:var(--dim);font-weight:600}
+.knows p{font-size:14px;line-height:1.65}
+.motd{background:var(--raise);border:1px solid var(--line);border-left:3px solid var(--accent);border-radius:14px;padding:14px 18px;font-size:14.5px;line-height:1.6}
+.motd b{display:block;font-size:12px;letter-spacing:.09em;text-transform:uppercase;color:var(--dim);margin-bottom:4px}
 a{color:var(--accent)}
 </style>
 </head>
 <body>
 <main>
 <svg class="mark" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="9"/><path d="M12 7.6v8.8"/><path d="M15.4 9.4c-.7-1.1-1.9-1.8-3.4-1.8-2 0-3.6 1.1-3.6 2.7 0 3.4 7.2 1.8 7.2 5 0 1.6-1.6 2.7-3.6 2.7-1.5 0-2.7-.7-3.4-1.8"/></svg>
-<h1>${escapeHtml(nodeInfo.alias ?? 'moneyer')}<small>An LNURLcash mint. Pay the address below and the invoice's payment preimage <em>is</em> your bearer note - money as a secret you hold.</small></h1>
+<h1>${escapeHtml(title)}<small>An LNURLcash mint. Pay the address below and the invoice's payment preimage <em>is</em> your bearer note - money as a secret you hold.</small></h1>
+${config.motd ? `<div class="motd"><b>notice</b>${escapeHtml(config.motd)}</div>` : ''}
 <div class="addr"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M13 2 4.5 13.5H11L9.5 22 18 10.5h-6.5L13 2z"/></svg>${escapeHtml(address)}</div>
 <div class="card">
 <div class="kv"><span>mints</span><b>${sats(config.minSendableMsat)} to ${sats(config.maxSendableMsat)}</b></div>
@@ -54,8 +87,15 @@ a{color:var(--accent)}
 <div class="kv"><span>largest note</span><b>${sats(maxNet)}</b></div>
 ${mintPubkey ? `<div class="kv"><span>notes signed by</span><code>${escapeHtml(mintPubkey)}</code></div>` : '<div class="kv"><span>note signatures</span><b>not offered</b></div>'}
 ${nodeInfo.uri ? `<div class="kv"><span>node</span><code>${escapeHtml(nodeInfo.uri)}</code></div>` : ''}
+${coverageLine ? `<div class="kv"><span>coverage</span><b>${escapeHtml(coverageLine)}</b></div>` : ''}
 ${config.sunset ? '<div class="kv"><span>status</span><b>sunsetting - redeem only</b></div>' : ''}
+${contacts.map(entry => `<div class="kv"><span>${entry.label}</span><code>${escapeHtml(entry.value)}</code></div>`).join('\n')}
+${config.tosUrl ? `<div class="kv"><span>terms</span><a href="${escapeHtml(config.tosUrl)}" rel="noopener noreferrer">${escapeHtml(config.tosUrl)}</a></div>` : ''}
 </div>
+<section class="knows">
+<h2>${escapeHtml(MINT_KNOWS_HEADING)}</h2>
+${MINT_KNOWS.map(paragraph => `<p>${escapeHtml(paragraph)}</p>`).join('\n')}
+</section>
 <p class="small">Works with any LUD-25 wallet - <a href="https://github.com/forgesworn/notecase">notecase</a> among them. Verify a note offline against the signing key above.<br/>Independent implementation of the <a href="https://github.com/lnurl/luds/pull/301">LNURLcash draft</a> - graded by <a href="https://github.com/TheCryptoDonkey/lnurlcash-conformance">lnurlcash-conformance</a>.</p>
 </main>
 </body>

package/dist/melt.d.ts CHANGED Viewed

@@ -5,6 +5,7 @@ export type MeltJob = {
     noteId: string;
     pr: string;
     amountMsat: number;
+    payAmountMsat?: number;
 };
 export type MeltDeps = {
     store: NoteStore;

package/dist/melt.js CHANGED Viewed

@@ -32,7 +32,8 @@ export const runMelt = async (job, deps) => {
     try {
         outcome = await deps.backend.payInvoice({
             pr: job.pr,
-            feeLimitMsat: deps.feeLimitMsat(job.amountMsat)
+            feeLimitMsat: deps.feeLimitMsat(job.amountMsat),
+            ...(job.payAmountMsat !== undefined ? { amountMsat: job.payAmountMsat } : {})
         });
     }
     catch (err) {

package/dist/names.d.ts ADDED Viewed

@@ -0,0 +1,39 @@
+import { NoteStore } from './store.ts';
+export declare const NIP98_KIND = 27235;
+export declare const NIP98_WINDOW_SECS = 60;
+export declare const NAME_RULE: RegExp;
+export declare const ALWAYS_RESERVED: readonly ["_", "admin", "mint"];
+export declare const FREE_NAMES_PER_PUBKEY = 3;
+export type Nip98Failure = {
+    reason: string;
+};
+export type Nip98Success = {
+    pubkey: string;
+};
+export declare const validateNip98: (authorization: string | undefined, request: {
+    url: string;
+    method: string;
+    body: string;
+    nowSecs?: number;
+}) => Nip98Success | Nip98Failure;
+export type NameRefusal = {
+    reason: string;
+    status: number;
+};
+export type NameGranted = {
+    name: string;
+    pubkey: string;
+    paidMsat: number;
+};
+export declare const isRefusal: (result: NameGranted | NameRefusal) => result is NameRefusal;
+export declare const registerName: (args: {
+    store: NoteStore;
+    pubkey: string;
+    body: {
+        name?: unknown;
+        note?: unknown;
+    };
+    priceMsat: number | undefined;
+    reserved: string[];
+    host: string;
+}) => NameGranted | NameRefusal;

package/dist/names.js ADDED Viewed

@@ -0,0 +1,172 @@
+import { sha256 } from '@noble/hashes/sha2.js';
+import { bytesToHex, utf8ToBytes } from '@noble/hashes/utils.js';
+import { verifyEvent } from 'nostr-tools/pure';
+import { hashK1, noteK1 } from 'lnurlcash-kit';
+import { NotePendingError, NoteStore, NoteUnavailableError } from "./store.js";
+// Self-service lightning addresses.
+//
+// A name here is a lightning address whose payouts are bearer notes
+// gift-wrapped to the holder's own Nostr key: custodial for the seconds
+// between the zap settling and the wrap going out, theirs afterwards.
+// Anyone with an npub can have one, which is a reason to run a mint and a
+// reason to install a wallet.
+//
+// The identity is the NIP-98 signature and nothing else. There is no
+// account, no password and no recovery: the key that signed the
+// registration owns the name.
+export const NIP98_KIND = 27235;
+// Sixty seconds, as NIP-98 suggests. Long enough for a slow phone, short
+// enough that a captured Authorization header is worth little.
+export const NIP98_WINDOW_SECS = 60;
+// Three to thirty-two characters, starting with a letter or digit. The
+// same shape a lightning address local part and a NIP-05 name can both
+// carry without quoting.
+export const NAME_RULE = /^[a-z0-9][a-z0-9_.-]{2,31}$/;
+// Never registrable, whatever the mint is called: `_` is LUD-16's
+// bare-domain alias, and the other two are what a person types when they
+// mean the operator.
+export const ALWAYS_RESERVED = ['_', 'admin', 'mint'];
+// How many free names one pubkey may hold. Paid registration needs no cap
+// - the price is the cap.
+export const FREE_NAMES_PER_PUBKEY = 3;
+// NIP-98 over one request. Deliberately checked here rather than through
+// a helper: the payload tag must commit to the RAW body this handler
+// read, not to a re-serialisation of it, or a client whose JSON differs
+// from ours by a space is refused for no reason.
+export const validateNip98 = (authorization, request) => {
+    const header = authorization?.trim();
+    if (!header)
+        return { reason: 'Missing NIP-98 Authorization header.' };
+    const match = /^Nostr\s+(.+)$/i.exec(header);
+    if (!match)
+        return { reason: 'Authorization must be "Nostr <base64 event>".' };
+    let event;
+    try {
+        event = JSON.parse(Buffer.from(match[1].trim(), 'base64').toString('utf8'));
+    }
+    catch {
+        return { reason: 'Authorization is not a base64 Nostr event.' };
+    }
+    if (event?.kind !== NIP98_KIND)
+        return { reason: `Authorization event must be kind ${NIP98_KIND}.` };
+    if (!verifyEvent(event))
+        return { reason: 'Authorization event signature does not verify.' };
+    const nowSecs = request.nowSecs ?? Math.floor(Date.now() / 1000);
+    if (Math.abs(nowSecs - event.created_at) > NIP98_WINDOW_SECS) {
+        return { reason: `Authorization event is not within ${NIP98_WINDOW_SECS} seconds of now.` };
+    }
+    const tag = (name) => event.tags.find(t => t[0] === name)?.[1];
+    // The URL is compared without its query string, and with a trailing
+    // slash ignored: those are the two differences a proxy or an HTTP
+    // client introduces on its own.
+    const canonical = (value) => {
+        try {
+            const url = new URL(value);
+            return `${url.origin}${url.pathname.replace(/\/+$/, '')}`;
+        }
+        catch {
+            return null;
+        }
+    };
+    const signedUrl = tag('u');
+    if (!signedUrl || canonical(signedUrl) === null || canonical(signedUrl) !== canonical(request.url)) {
+        return { reason: 'Authorization event was signed for a different URL.' };
+    }
+    if ((tag('method') ?? '').toUpperCase() !== request.method.toUpperCase()) {
+        return { reason: 'Authorization event was signed for a different method.' };
+    }
+    const payload = tag('payload');
+    if (request.body.length > 0) {
+        if (!payload)
+            return { reason: 'Authorization event has no payload tag for this body.' };
+        if (payload.toLowerCase() !== bytesToHex(sha256(utf8ToBytes(request.body)))) {
+            return { reason: 'Authorization event payload tag does not match the body.' };
+        }
+    }
+    return { pubkey: event.pubkey };
+};
+const refuse = (reason, status) => ({ reason, status });
+export const isRefusal = (result) => 'reason' in result;
+// The whole registration, minus the transport. Burning the note and
+// inserting the name are the two mutations, in that order: a name that
+// exists without payment is worse than a note burned without a name,
+// and the INSERT is what settles a race between two people asking for
+// the same name at once.
+export const registerName = (args) => {
+    const { store, pubkey, priceMsat } = args;
+    if (priceMsat === undefined)
+        return refuse('This mint is not registering names.', 404);
+    const raw = typeof args.body.name === 'string' ? args.body.name.trim().toLowerCase() : '';
+    if (!NAME_RULE.test(raw)) {
+        return refuse('A name is 3 to 32 characters of a-z, 0-9, dot, dash or underscore, starting with a letter or digit.', 400);
+    }
+    if ([...ALWAYS_RESERVED, ...args.reserved.map(name => name.toLowerCase())].includes(raw)) {
+        return refuse('That name is reserved.', 403);
+    }
+    if (store.zapName(raw))
+        return refuse('That name is taken.', 409);
+    let paidMsat = 0;
+    let noteId;
+    if (priceMsat === 0) {
+        // Free names are rationed per key. The per-address limit is the
+        // reverse proxy's job; this is the one the mint can enforce itself.
+        if (store.zapNameCountFor(pubkey) >= FREE_NAMES_PER_PUBKEY) {
+            return refuse(`One key may hold ${FREE_NAMES_PER_PUBKEY} free names.`, 403);
+        }
+    }
+    else {
+        const offered = typeof args.body.note === 'string' ? args.body.note.trim() : '';
+        if (!offered)
+            return refuse(`This name costs ${priceMsat} msat - send a note of this mint in "note".`, 402);
+        // A bare secret is accepted as readily as a full note URL; a URL for
+        // somebody else's mint is not, however good the note is. The URL is
+        // read here rather than through the kit's resolver, which refuses a
+        // plain-http service - correct for a wallet reaching a stranger, and
+        // wrong for a mint reading a note it minted itself.
+        let k1 = null;
+        if (/^[0-9a-f]{64}$/i.test(offered)) {
+            k1 = offered.toLowerCase();
+        }
+        else {
+            let url;
+            try {
+                url = new URL(offered.replace(/^lnurlw:\/\//i, 'https://'));
+            }
+            catch {
+                return refuse('That is not a note.', 400);
+            }
+            if (url.host !== args.host)
+                return refuse('That note is not from this mint.', 400);
+            k1 = noteK1(url.toString());
+        }
+        if (!k1)
+            return refuse('That is not a note.', 400);
+        const note = store.noteById(hashK1(k1));
+        if (!note || note.state === 'burned')
+            return refuse('That note is spent or was never minted here.', 400);
+        if (note.state === 'pending')
+            return refuse('That note has a melt in flight.', 409);
+        if (note.amountMsat < priceMsat) {
+            return refuse(`That note is worth ${note.amountMsat} msat and a name costs ${priceMsat} msat.`, 402);
+        }
+        // The note is burned outright, with no change: the whole of it pays
+        // for the name, which is why the price is published and a wallet
+        // splits before it asks. Liabilities drop by exactly this much and
+        // the sats become revenue.
+        noteId = note.id;
+        paidMsat = note.amountMsat;
+    }
+    try {
+        store.buyZapName({ name: raw, pubkey, ...(noteId ? { noteId } : {}), paidMsat });
+    }
+    catch (err) {
+        if (err instanceof NotePendingError)
+            return refuse('That note has a melt in flight.', 409);
+        if (err instanceof NoteUnavailableError)
+            return refuse('That note is spent or was never minted here.', 400);
+        // The INSERT lost a race. Nothing was burned: the transaction took
+        // the name and the note together or not at all.
+        return refuse('That name is taken.', 409);
+    }
+    return { name: raw, pubkey, paidMsat };
+};

package/dist/privacy.d.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ export declare const MINT_KNOWS_HEADING = "What the mint knows";
2	+ export declare const MINT_KNOWS: readonly string[];

package/dist/privacy.js ADDED Viewed

@@ -0,0 +1,14 @@
+// What the mint knows, in one place so the README, the landing page and
+// the mint's own site cannot drift apart on it.
+//
+// The one property a LUD-25 mint cannot offer is blindness. A reader
+// arriving from an ecash wallet will assume otherwise unless told, so
+// this is written to be read before anyone trusts the mint with sats,
+// not buried in a threat model.
+export const MINT_KNOWS_HEADING = 'What the mint knows';
+export const MINT_KNOWS = [
+    'This mint knows every note it has issued and what each is worth. It knows every rotate, split and merge, the links between them - which note became which, and when - and the network address the request came from. It knows the invoice a melt paid.',
+    'It does not know who holds a note between those operations. A note handed to someone else offline leaves no trace here until they rotate it, which is one reason a wallet rotates on receipt.',
+    'The wallet-side mitigations are weak, and worth naming as weak. A Tor or SOCKS proxy hides the address, not the links. Rotating at unpredictable times blurs the timing, not the graph. Nothing a holder does stops this mint seeing the chain of notes it struck.',
+    'The design was chosen anyway because it needs no new cryptography, any LUD-03 wallet can cash a note out, and verifying a note offline needs a signature and nothing else. The privacy story is trust the operator, and that is worth saying plainly.'
+];

package/dist/server.d.ts CHANGED Viewed

@@ -2,6 +2,8 @@ import type { MoneyerConfig } from './config.ts';
 import { NoteStore } from './store.ts';
 import { type NoteSigner } from './signing.ts';
 import { type LightningBackend } from './backends/types.ts';
+import { type NostrTransport, type ZapBridge } from './zap.ts';
+import { type MintStats } from './stats.ts';
 import { type WebAssets } from './web-assets.ts';
 export type Moneyer = {
     url: string;
@@ -10,7 +12,11 @@ export type Moneyer = {
     store: NoteStore;
     backend: LightningBackend;
     signer: NoteSigner | null;
+    zap: ZapBridge | null;
     reconcile: () => Promise<void>;
+    stats: () => Promise<MintStats>;
+    publishStats: () => Promise<void>;
+    publishAnnouncement: () => Promise<void>;
     close: () => Promise<void>;
 };
 export type MoneyerDeps = {
@@ -19,6 +25,13 @@ export type MoneyerDeps = {
     log?: (message: string) => void;
     confirmDelaysMs?: number[];
     webAssets?: WebAssets | null;
+    nostr?: NostrTransport;
+    zapPollMs?: number;
+    statsPublishMs?: number;
 };
+export declare const describeFee: (fee: {
+    baseFeeMsat: number;
+    feePpm: number;
+}, roundedToSat: boolean) => string;
 export declare const createMoneyer: (config: MoneyerConfig, deps?: MoneyerDeps) => Promise<Moneyer>;
 export declare const sweepExpiredMintInvoices: (store: NoteStore, nowMs?: number) => number;