beignet 0.23.1 → 0.24.1

package/README.md

@@ -160,6 +160,7 @@ const res = await Wallet.create({
 ```
 
 - **Failover:** with multiple servers the wallet rotates through them in order on connect/reconnect failure, then through hardcoded fallback peers for the network, with a per-server cooldown so dead servers are not hammered. Inspect `wallet.electrum.currentServer` and `wallet.electrum.rotationCount`.
+- **Certificate verification:** by default a TLS Electrum connection is encrypted but the server certificate is not checked, because the client library dials with `rejectUnauthorized: false`. An on-path attacker can therefore stand in for the server. On Node, pass `tls: withTlsVerification(tls)` to accept only certificates that chain to a trusted CA and match the host, and add `{ fingerprints: ['AB:CD:…'] }` to also accept self-signed servers by SHA-256 fingerprint (`openssl x509 -noout -fingerprint -sha256`). The CLI/daemon and React Native do not verify yet.
 - **Fee source:** `'electrum'` queries only the connected server via `blockchain.estimatefee`, so fee lookups never leak to mempool.space/blocktank over clearnet. `'auto'` prefers Electrum and falls back to HTTP. All remote rates are clamped to 5000 sat/vB.
 - **Networks:** mainnet, testnet, regtest and signet work end to end (wallet, Electrum, CLI/daemon `--network signet`, Lightning chain hash and `tbs` invoice prefix). Signet shares testnet address formats and coin type 1.
 - **BIP21:** `encodeBip21({ address, amountSats?, label?, message? })` builds a `bitcoin:` URI.
@@ -194,7 +195,7 @@ The full read-only surface works: address generation, gap-limit scanning, Electr
 <details>
 <summary><b>Hardware wallets and external signers (PSBT)</b></summary>
 
-`buildPsbt` runs the normal setup (coin selection, change, fee) but stops before signing, returning a base64 PSBT populated with what a hardware signer needs: `witnessUtxo` (or `nonWitnessUtxo` for legacy p2pkh), `redeemScript` for p2sh-p2wpkh, `tapInternalKey` plus `tapBip32Derivation` for p2tr, and `bip32Derivation` on every wallet input. Works on full and watch-only wallets.
+`buildPsbt` runs the normal setup (coin selection, change, fee) but stops before signing, returning a base64 PSBT populated with what a hardware signer needs: `witnessUtxo` (or `nonWitnessUtxo` for legacy p2pkh), `redeemScript` for p2sh-p2wpkh, `tapInternalKey` plus `tapBip32Derivation` for p2tr, and `bip32Derivation` on every wallet input. The change output carries the same derivation fields, so the signer shows it as change rather than as a second recipient. Works on full and watch-only wallets.
 
 ```typescript
 // 1. Build (never touches private keys)
@@ -205,9 +206,10 @@ const { psbtBase64, fee, vsizeEstimate } = build.value;
 // 2. Sign externally (hardware wallet, HWI, another machine)
 const signedBase64 = await myHardwareWallet.signPsbt(psbtBase64);
 
-// 3. Import: validates a signature on EVERY input, finalizes, does NOT broadcast
+// 3. Import: checks the inputs and outputs are the ones built, validates a
+//    signature on EVERY input, finalizes, does NOT broadcast
 const imported = wallet.importSignedPsbt(signedBase64);
-if (imported.isErr()) return; // missing/invalid signatures are rejected loudly
+if (imported.isErr()) return; // changed outputs, missing/invalid signatures are rejected loudly
 const { txHex, txid } = imported.value;
 
 // 4. Broadcast when ready
@@ -217,9 +219,11 @@ await wallet.broadcastTransaction(txHex);
 const combined = wallet.combinePsbts([copyA, copyB]);
 ```
 
+`importSignedPsbt` finalizes only a PSBT that spends the same inputs to the same outputs as one this wallet instance built (it remembers its 50 most recent builds, in memory). To import a PSBT built elsewhere, or after a restart, pass the unsigned PSBT as the second argument: `wallet.importSignedPsbt(signedBase64, psbtBase64)`. Inputs the signer already finalized are refused, since their signatures cannot be checked.
+
 For watch-only wallets the true master fingerprint is unknowable from an account xpub, so the xpub's parent fingerprint is used: signers should locate keys by derivation path.
 
-Also on the daemon (`POST /psbt/build`, `/psbt/import-signed`, `/psbt/combine`) and the CLI (`beignet psbt build|import-signed|combine`).
+Also on the daemon (`POST /psbt/build`, `/psbt/import-signed`, `/psbt/combine`) and the CLI (`beignet psbt build|import-signed|combine`). A restart forgets the daemon's builds, so the import there takes the unsigned PSBT too: `unsignedPsbtBase64` on the route, a second argument to `beignet psbt import-signed`.
 
 </details>
 
@@ -262,10 +266,11 @@ const signedA = walletA.signPsbtWithOurKey(unsigned);
 const signedB = walletB.signPsbtWithOurKey(unsigned);
 if (signedA.isErr() || signedB.isErr()) return;
 
-// 5. Combine, finalize at threshold, broadcast.
+// 5. Combine, finalize at threshold, broadcast. The coordinator did not build
+//    the PSBT, so it checks the combined one against the unsigned original.
 const combined = coordinator.combinePsbts([signedA.value, signedB.value]);
 if (combined.isErr()) return;
-const finalized = coordinator.importSignedPsbt(combined.value); // 2-of-3 met
+const finalized = coordinator.importSignedPsbt(combined.value, unsigned); // 2-of-3 met
 if (finalized.isErr()) return;
 await coordinator.broadcastTransaction(finalized.value.txHex);
 
@@ -750,7 +755,9 @@ Recommended safeguards in production:
 - Cap exposure with `maxPaymentSats` and `dailySpendLimitSats`. Both count a
   payment's amount plus its routing-fee cap, so the fee cannot slip past them:
   the cap is `maxFeeSats`/`maxFeeMsat` when you pass one, and 1% of the
-  amount (never below 50 sats) when you do not.
+  amount (never below 50 sats) when you do not. Both also cover external
+  on-chain sends (amount plus fee); see the Spending Limits section of
+  `src/cli/README.md`.
 - Call `validatePayment()` before every send.
 - Set `backupPath` for automated database backups, and keep an SCB (`beignet backup scb`).
 - Keep `~/.beignet` and the data directory owner-only. The CLI creates them `0700`/`0600` and tightens an older config on load; check them again after copying files between hosts.

package/dist/cli/backup-destination.js

@@ -0,0 +1,89 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveBackupDestination = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const backup_mac_1 = require("./backup-mac");
+function canonicalPath(p) {
+    const resolved = path.resolve(p);
+    try {
+        return fs.realpathSync.native(resolved);
+    }
+    catch {
+        return path.join(fs.realpathSync.native(path.dirname(resolved)), path.basename(resolved));
+    }
+}
+function resolveBackupDestination(destPath, protectedPaths, overwrite) {
+    let target;
+    try {
+        target = canonicalPath(destPath);
+    }
+    catch {
+        return {
+            refusal: `Backup directory does not exist: ${path.dirname(path.resolve(destPath))}`
+        };
+    }
+    if (target !== target.trim()) {
+        return { refusal: 'Backup filename must not start or end with whitespace' };
+    }
+    const stat = fs.statSync(target, { throwIfNoEntry: false });
+    if (!stat && fs.lstatSync(target, { throwIfNoEntry: false })) {
+        return { refusal: `destPath is a broken symlink: ${target}` };
+    }
+    for (const p of protectedPaths) {
+        let own;
+        try {
+            own = canonicalPath(p);
+        }
+        catch {
+            own = path.resolve(p);
+        }
+        if (own === target) {
+            return { refusal: `Refusing to overwrite a daemon file: ${target}` };
+        }
+    }
+    if (stat && !stat.isFile()) {
+        return { refusal: `destPath is not a regular file: ${target}` };
+    }
+    if (stat && !overwrite) {
+        return {
+            refusal: `destPath already exists: ${target}. Pass overwrite: true to replace it`
+        };
+    }
+    const macPath = (0, backup_mac_1.backupMacPath)(target);
+    const macStat = fs.lstatSync(macPath, { throwIfNoEntry: false });
+    if (macStat && !macStat.isFile()) {
+        return { refusal: `MAC path is not a regular file: ${macPath}` };
+    }
+    if (macStat && !overwrite) {
+        return {
+            refusal: `MAC path already exists: ${macPath}. Pass overwrite: true to replace it`
+        };
+    }
+    return { path: target };
+}
+exports.resolveBackupDestination = resolveBackupDestination;
+//# sourceMappingURL=backup-destination.js.map

package/dist/cli/backup-destination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup-destination.js","sourceRoot":"","sources":["../../src/cli/backup-destination.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAYA,uCAAyB;AACzB,2CAA6B;AAC7B,6CAA6C;AAS7C,SAAS,aAAa,CAAC,CAAS;IAC/B,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACjC,IAAI;QACH,OAAO,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;KACxC;IAAC,MAAM;QACP,OAAO,IAAI,CAAC,IAAI,CACf,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,EAC9C,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CACvB,CAAC;KACF;AACF,CAAC;AAMD,SAAgB,wBAAwB,CACvC,QAAgB,EAChB,cAAwB,EACxB,SAAkB;IAElB,IAAI,MAAc,CAAC;IACnB,IAAI;QACH,MAAM,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;KACjC;IAAC,MAAM;QACP,OAAO;YACN,OAAO,EAAE,oCAAoC,IAAI,CAAC,OAAO,CACxD,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CACtB,EAAE;SACH,CAAC;KACF;IAED,IAAI,MAAM,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE;QAC7B,OAAO,EAAE,OAAO,EAAE,uDAAuD,EAAE,CAAC;KAC5E;IACD,MAAM,IAAI,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,CAAC;IAE5D,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,EAAE;QAC7D,OAAO,EAAE,OAAO,EAAE,iCAAiC,MAAM,EAAE,EAAE,CAAC;KAC9D;IACD,KAAK,MAAM,CAAC,IAAI,cAAc,EAAE;QAC/B,IAAI,GAAW,CAAC;QAChB,IAAI;YACH,GAAG,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;SACvB;QAAC,MAAM;YACP,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;SACtB;QACD,IAAI,GAAG,KAAK,MAAM,EAAE;YACnB,OAAO,EAAE,OAAO,EAAE,wCAAwC,MAAM,EAAE,EAAE,CAAC;SACrE;KACD;IACD,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE;QAC3B,OAAO,EAAE,OAAO,EAAE,mCAAmC,MAAM,EAAE,EAAE,CAAC;KAChE;IACD,IAAI,IAAI,IAAI,CAAC,SAAS,EAAE;QACvB,OAAO;YACN,OAAO,EAAE,4BAA4B,MAAM,sCAAsC;SACjF,CAAC;KACF;IAED,MAAM,OAAO,GAAG,IAAA,0BAAa,EAAC,MAAM,CAAC,CAAC;IACtC,MAAM,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,CAAC;IACjE,IAAI,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE;QACjC,OAAO,EAAE,OAAO,EAAE,mCAAmC,OAAO,EAAE,EAAE,CAAC;KACjE;IACD,IAAI,OAAO,IAAI,CAAC,SAAS,EAAE;QAC1B,OAAO;YACN,OAAO,EAAE,4BAA4B,OAAO,sCAAsC;SAClF,CAAC;KACF;IACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AACzB,CAAC;AAvDD,4DAuDC"}

package/dist/cli/backup-mac.js

@@ -0,0 +1,74 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readBackupMac = exports.writeBackupMac = exports.fileMac = exports.deriveBackupMacKey = exports.backupMacPath = void 0;
+const crypto_1 = require("crypto");
+const fs = __importStar(require("fs"));
+const encryption_1 = require("../lightning/storage/encryption");
+const fs_utils_1 = require("./fs-utils");
+const BACKUP_MAC_INFO = 'beignet-db-backup-mac-v1';
+const BACKUP_MAC_PREFIX = 'beignet-db-mac-v1:';
+function backupMacPath(backupPath) {
+    return `${backupPath}.hmac`;
+}
+exports.backupMacPath = backupMacPath;
+function deriveBackupMacKey(seed) {
+    return (0, encryption_1.hkdfKey)(seed, BACKUP_MAC_INFO);
+}
+exports.deriveBackupMacKey = deriveBackupMacKey;
+async function fileMac(key, filePath) {
+    const hmac = (0, crypto_1.createHmac)('sha256', key);
+    for await (const chunk of fs.createReadStream(filePath)) {
+        hmac.update(chunk);
+    }
+    return hmac.digest();
+}
+exports.fileMac = fileMac;
+async function writeBackupMac(key, backupPath) {
+    const mac = await fileMac(key, backupPath);
+    (0, fs_utils_1.writeFileAtomic)(backupMacPath(backupPath), `${BACKUP_MAC_PREFIX}${mac.toString('hex')}\n`);
+}
+exports.writeBackupMac = writeBackupMac;
+function readBackupMac(backupPath) {
+    const macPath = backupMacPath(backupPath);
+    let text;
+    try {
+        text = fs.readFileSync(macPath, 'utf8').trim();
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+    const hex = text.startsWith(BACKUP_MAC_PREFIX)
+        ? text.slice(BACKUP_MAC_PREFIX.length)
+        : '';
+    if (!/^[0-9a-f]{64}$/.test(hex)) {
+        throw new Error(`Malformed backup MAC file: ${macPath}`);
+    }
+    return Buffer.from(hex, 'hex');
+}
+exports.readBackupMac = readBackupMac;
+//# sourceMappingURL=backup-mac.js.map

package/dist/cli/backup-mac.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup-mac.js","sourceRoot":"","sources":["../../src/cli/backup-mac.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAUA,mCAAoC;AACpC,uCAAyB;AACzB,gEAA0D;AAC1D,yCAA6C;AAE7C,MAAM,eAAe,GAAG,0BAA0B,CAAC;AACnD,MAAM,iBAAiB,GAAG,oBAAoB,CAAC;AAG/C,SAAgB,aAAa,CAAC,UAAkB;IAC/C,OAAO,GAAG,UAAU,OAAO,CAAC;AAC7B,CAAC;AAFD,sCAEC;AAGD,SAAgB,kBAAkB,CAAC,IAAY;IAC9C,OAAO,IAAA,oBAAO,EAAC,IAAI,EAAE,eAAe,CAAC,CAAC;AACvC,CAAC;AAFD,gDAEC;AAGM,KAAK,UAAU,OAAO,CAAC,GAAW,EAAE,QAAgB;IAC1D,MAAM,IAAI,GAAG,IAAA,mBAAU,EAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACvC,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,EAAE;QACxD,IAAI,CAAC,MAAM,CAAC,KAAe,CAAC,CAAC;KAC7B;IACD,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC;AACtB,CAAC;AAND,0BAMC;AAGM,KAAK,UAAU,cAAc,CACnC,GAAW,EACX,UAAkB;IAElB,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IAC3C,IAAA,0BAAe,EACd,aAAa,CAAC,UAAU,CAAC,EACzB,GAAG,iBAAiB,GAAG,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAC9C,CAAC;AACH,CAAC;AATD,wCASC;AAMD,SAAgB,aAAa,CAAC,UAAkB;IAC/C,MAAM,OAAO,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;IAC1C,IAAI,IAAY,CAAC;IACjB,IAAI;QACH,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;KAC/C;IAAC,OAAO,GAAG,EAAE;QACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAClE,MAAM,GAAG,CAAC;KACV;IACD,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,iBAAiB,CAAC;QAC7C,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,MAAM,CAAC;QACtC,CAAC,CAAC,EAAE,CAAC;IACN,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE;QAChC,MAAM,IAAI,KAAK,CAAC,8BAA8B,OAAO,EAAE,CAAC,CAAC;KACzD;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;AAChC,CAAC;AAhBD,sCAgBC"}