beignet 0.9.2 → 0.9.3

package/dist/cli/beignet-node.js

@@ -54,6 +54,8 @@ const electrum_backend_1 = require("../lightning/chain/electrum-backend");
 const types_2 = require("../lightning/invoice/types");
 const wallet_keys_1 = require("../lightning/keys/wallet-keys");
 const recovery_1 = require("../lightning/recovery");
+const ecdh_1 = require("../lightning/crypto/ecdh");
+const auth_1 = require("./auth");
 const types_3 = require("../lightning/channel/types");
 const decode_1 = require("../lightning/invoice/decode");
 const decode_2 = require("../lightning/offer/decode");
@@ -68,6 +70,40 @@ function parseRecoveryMode(value) {
         : 'off';
 }
 exports.parseRecoveryMode = parseRecoveryMode;
+function redactUrl(url) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.username === '' && parsed.password === '')
+            return url;
+        parsed.username = '';
+        parsed.password = '';
+        return parsed.toString();
+    }
+    catch {
+        return '<invalid url>';
+    }
+}
+function redactGuardians(descriptors) {
+    return descriptors.map((g) => ({
+        guardianId: g.guardianId,
+        transports: g.transports.map((t) => ({
+            type: t.type,
+            url: redactUrl(t.url)
+        }))
+    }));
+}
+function sameGuardianIds(a, b) {
+    if (a.length !== b.length)
+        return false;
+    const sortedA = a.map((id) => id.toLowerCase()).sort();
+    const sortedB = b.map((id) => id.toLowerCase()).sort();
+    return sortedA.every((id, i) => id === sortedB[i]);
+}
+function writeFileAtomic(filePath, content) {
+    const tmp = `${filePath}.tmp`;
+    fs.writeFileSync(tmp, content);
+    fs.renameSync(tmp, filePath);
+}
 const RESTORE_ERROR_CODES = {
     'no-quorum': 'RESTORE_NO_QUORUM',
     'unknown-namespace': 'RESTORE_UNKNOWN_NAMESPACE',
@@ -224,6 +260,8 @@ class BeignetNode extends events_1.EventEmitter {
         this.recoveryGuardianSet = [];
         this._restorePending = false;
         this._restoreInFlight = false;
+        this._leaseCheckInFlight = false;
+        this._leaseCheckIntervalMs = BeignetNode.DEFAULT_LEASE_CHECK_INTERVAL_MS;
         this._lockPath = null;
         this._lockExitHandler = null;
         this.destroyed = false;
@@ -246,6 +284,10 @@ class BeignetNode extends events_1.EventEmitter {
         this._draining = false;
         this.peerStorageEnabled = true;
         this._peerRetrievedScb = null;
+        this._peerRetrievedCapsules = new Map();
+        this._pushedChannelBackup = false;
+        this._restartRequired = false;
+        this._recoveryFenceRelayed = false;
         this.mnemonic = mnemonic;
         this.networkName = networkName;
         this.dataDir = dataDir;
@@ -277,6 +319,14 @@ class BeignetNode extends events_1.EventEmitter {
         this.peerStorageEnabled = opts.peerStorageEnabled ?? true;
         this.rapidGossipSync = opts.rapidGossipSync ?? true;
         this.rapidGossipSyncUrl = opts.rapidGossipSyncUrl;
+        if (opts.recoveryLeaseCheckIntervalMs !== undefined) {
+            const ms = opts.recoveryLeaseCheckIntervalMs;
+            if (!Number.isInteger(ms) || ms < 0 || ms > BeignetNode.MAX_TIMER_MS) {
+                throw new errors_1.BeignetError('INVALID_PARAMS', `recoveryLeaseCheckIntervalMs must be an integer between 0 and ` +
+                    `${BeignetNode.MAX_TIMER_MS} (got ${String(ms)})`);
+            }
+            this._leaseCheckIntervalMs = ms;
+        }
         const networkName = this.networkName;
         if (!opts.allowMultipleInstances) {
             const lockPath = path.join(this.dataDir, `${networkName}.lock`);
@@ -316,6 +366,8 @@ class BeignetNode extends events_1.EventEmitter {
         if (opts.storageEncryption ?? true) {
             encryptionKey = (0, encryption_1.deriveStorageKey)(bip39.mnemonicToSeedSync(this.mnemonic));
         }
+        this._storageEncryptionKey = encryptionKey;
+        this.finishStagedCapsuleRestore(dbPath);
         this.storage = new sqlite_storage_1.SqliteStorage(dbPath, (err) => {
             this.log('warn', 'Skipped corrupted storage row during load', {
                 error: err instanceof Error ? err.message : String(err)
@@ -701,16 +753,7 @@ class BeignetNode extends events_1.EventEmitter {
         this.node.on('recovery:fenced', (superseding) => {
             this.log('error', 'Recovery fenced: a newer writer epoch owns this namespace; ' +
                 'this device must not send another channel message');
-            this.emit('recovery:fenced', {
-                supersededBy: superseding
-                    ? {
-                        epoch: superseding.lease.epoch.toString(),
-                        writerPublicKey: superseding.lease.writerPublicKey.toString('hex'),
-                        sequence: superseding.logHead.sequence.toString(),
-                        frameHash: superseding.logHead.frameHash.toString('hex')
-                    }
-                    : null
-            });
+            this.relayRecoveryFenced(superseding);
         });
         this.node.on('recovery:backfill-lost', (detail) => {
             this.log('error', 'Recovery backfill lost', { detail });
@@ -796,13 +839,11 @@ class BeignetNode extends events_1.EventEmitter {
             this.recoveryNodeConfig = { enabled: true, durability: 'local' };
             return;
         }
-        const guardians = (opts.recoveryGuardians ?? []).map(recovery_1.parseGuardianUri);
+        const guardians = (opts.recoveryGuardians ?? []).map(recovery_1.parseGuardianEntry);
         this.recoveryGuardianSet = guardians;
-        const coinType = this.toCoinType(this.networkName);
-        const keys = (0, wallet_keys_1.deriveLightningKeysFromMnemonic)(this.mnemonic, undefined, coinType);
         const decision = await (0, recovery_1.buildGuardianRecovery)({
             storage: this.storage,
-            nodeSecret: keys.nodePrivateKey,
+            nodeSecret: this.nodeSecret(),
             durability: mode,
             guardians,
             onBarrierEvent: (event) => {
@@ -855,19 +896,11 @@ class BeignetNode extends events_1.EventEmitter {
                     this.log('info', 'Recovery gate confirmed; peer traffic released', {
                         confirming: outcome.confirming
                     });
+                    this.startRecoveryLeaseCheck();
                     return;
                 }
                 if (outcome.state === 'fenced') {
-                    this.emit('recovery:fenced', {
-                        supersededBy: outcome.supersededBy
-                            ? {
-                                epoch: outcome.supersededBy.lease.epoch.toString(),
-                                writerPublicKey: outcome.supersededBy.lease.writerPublicKey.toString('hex'),
-                                sequence: outcome.supersededBy.logHead.sequence.toString(),
-                                frameHash: outcome.supersededBy.logHead.frameHash.toString('hex')
-                            }
-                            : null
-                    });
+                    this.relayRecoveryFenced(outcome.supersededBy);
                     return;
                 }
                 this.log('warn', 'Recovery gate still quarantined; retrying', {
@@ -889,6 +922,57 @@ class BeignetNode extends events_1.EventEmitter {
         };
         void attempt();
     }
+    relayRecoveryFenced(supersededBy) {
+        this.stopRecoveryLeaseCheck();
+        if (this._recoveryFenceRelayed)
+            return;
+        this._recoveryFenceRelayed = true;
+        this.emit('recovery:fenced', {
+            supersededBy: supersededBy
+                ? {
+                    epoch: supersededBy.lease.epoch.toString(),
+                    writerPublicKey: supersededBy.lease.writerPublicKey.toString('hex'),
+                    sequence: supersededBy.logHead.sequence.toString(),
+                    frameHash: supersededBy.logHead.frameHash.toString('hex')
+                }
+                : null
+        });
+    }
+    startRecoveryLeaseCheck() {
+        const run = this._recoveryRun;
+        if (!run || this._leaseCheckTimer || this._leaseCheckIntervalMs <= 0) {
+            return;
+        }
+        this._leaseCheckTimer = setInterval(() => {
+            if (this.destroyed || this._leaseCheckInFlight)
+                return;
+            this._leaseCheckInFlight = true;
+            run
+                .recheck()
+                .then((outcome) => {
+                if (outcome.state !== 'fenced')
+                    return;
+                this.log('error', 'Recovery lease check: a newer writer epoch owns this ' +
+                    'namespace; this device is fenced');
+                this.relayRecoveryFenced(outcome.supersededBy);
+            })
+                .catch((err) => {
+                this.log('debug', 'Recovery lease check failed', {
+                    error: err instanceof Error ? err.message : String(err)
+                });
+            })
+                .finally(() => {
+                this._leaseCheckInFlight = false;
+            });
+        }, this._leaseCheckIntervalMs);
+        this._leaseCheckTimer.unref?.();
+    }
+    stopRecoveryLeaseCheck() {
+        if (this._leaseCheckTimer) {
+            clearInterval(this._leaseCheckTimer);
+            this._leaseCheckTimer = undefined;
+        }
+    }
     get restorePending() {
         return this._restorePending;
     }
@@ -900,13 +984,30 @@ class BeignetNode extends events_1.EventEmitter {
         const profile = this.recoveryMode === 'async-remote' || this.recoveryMode === 'quorum'
             ? 'crash-v1'
             : null;
+        const capsules = this.describeRetrievedCapsules();
+        const restore = {
+            inProgress: this._restoreInFlight,
+            ...(this._lastRestoreEvent ? { lastEvent: this._lastRestoreEvent } : {})
+        };
+        if (this._restartRequired) {
+            return {
+                mode: this.recoveryMode,
+                profile,
+                guardians,
+                state: 'restart-required',
+                node: null,
+                capsules,
+                restore
+            };
+        }
         if (this.recoveryMode === 'off') {
             return {
                 mode: 'off',
                 profile: null,
                 guardians: [],
                 state: 'disabled',
-                node: null
+                node: null,
+                capsules
             };
         }
         if (this._restorePending) {
@@ -916,12 +1017,8 @@ class BeignetNode extends events_1.EventEmitter {
                 guardians,
                 state: this._restoreInFlight ? 'restoring' : 'restore-required',
                 node: null,
-                restore: {
-                    inProgress: this._restoreInFlight,
-                    ...(this._lastRestoreEvent
-                        ? { lastEvent: this._lastRestoreEvent }
-                        : {})
-                }
+                capsules,
+                restore
             };
         }
         const node = this.node.getRecoveryStatus();
@@ -930,9 +1027,402 @@ class BeignetNode extends events_1.EventEmitter {
             profile,
             guardians,
             state: node.fenced || node.gate === 'fenced' ? 'fenced' : 'running',
-            node
+            node,
+            capsules
         };
     }
+    get restartRequired() {
+        return this._restartRequired;
+    }
+    describeRetrievedCapsules() {
+        let best = null;
+        for (const [fromPeer, c] of this._peerRetrievedCapsules) {
+            if (!best ||
+                c.writerEpoch > best.epoch ||
+                (c.writerEpoch === best.epoch && c.latestSequence > best.sequence) ||
+                (c.writerEpoch === best.epoch &&
+                    c.latestSequence === best.sequence &&
+                    c.inline &&
+                    !best.inline)) {
+                best = {
+                    epoch: c.writerEpoch,
+                    sequence: c.latestSequence,
+                    writerEpoch: c.writerEpoch.toString(),
+                    latestSequence: c.latestSequence.toString(),
+                    inline: c.inline,
+                    channelCount: c.channelCount,
+                    guardians: redactGuardians(c.guardians),
+                    fromPeer,
+                    receivedAt: c.receivedAt
+                };
+            }
+        }
+        if (!best)
+            return { candidates: 0, best: null };
+        const { epoch: _e, sequence: _s, ...rest } = best;
+        return { candidates: this._peerRetrievedCapsules.size, best: rest };
+    }
+    revealCapsuleGuardians() {
+        const best = this.describeRetrievedCapsules().best;
+        if (!best) {
+            throw new errors_1.BeignetError('CAPSULE_RESTORE_NO_CANDIDATES', 'No storage peer has returned a Recovery Capsule this session. ' +
+                'Connect to the peers this node had channels with and retry.');
+        }
+        const held = this._peerRetrievedCapsules.get(best.fromPeer);
+        return {
+            fromPeer: best.fromPeer,
+            head: {
+                writerEpoch: best.writerEpoch,
+                latestSequence: best.latestSequence
+            },
+            guardians: held.guardians,
+            entries: held.guardians.map((g) => ({
+                guardianId: g.guardianId,
+                url: g.transports[0].url,
+                ...(g.auth ? { auth: g.auth } : {})
+            }))
+        };
+    }
+    async restoreFromCapsules(options = {}) {
+        if (this._restoreInFlight) {
+            throw new errors_1.BeignetError('RESTORE_IN_PROGRESS', 'A restore is already running; poll the status route.');
+        }
+        if (options.unfenced !== undefined &&
+            typeof options.unfenced !== 'boolean') {
+            throw new errors_1.BeignetError('INVALID_PARAMS', 'unfenced must be a boolean');
+        }
+        const unfencedRequested = options.unfenced === true;
+        if (this.recoveryMode !== 'peer-storage' || this._restorePending) {
+            throw new errors_1.BeignetError('CAPSULE_RESTORE_UNSUPPORTED', 'Capsule restore applies to peer-storage mode only. Guardian ' +
+                'modes restore through the guardian set (the /recovery/restore ' +
+                'route); with recovery off there is no journal to restore, so ' +
+                'use the SCB a peer returned (/backup/peer-retrieved) with the ' +
+                'SCB restore route instead.');
+        }
+        if (this._peerRetrievedCapsules.size === 0) {
+            throw new errors_1.BeignetError('CAPSULE_RESTORE_NO_CANDIDATES', 'No storage peer has returned a Recovery Capsule this session. ' +
+                'Connect to the peers this node had channels with and retry.');
+        }
+        try {
+            (0, recovery_1.assertEmptyTarget)(this.storage);
+        }
+        catch (err) {
+            throw new errors_1.BeignetError('CAPSULE_RESTORE_TARGET_DIRTY', 'This database already holds channel, payment or invoice state ' +
+                'that a restore would discard; run the restore from a fresh ' +
+                'data directory (' +
+                (err instanceof Error ? err.message : String(err)) +
+                ')');
+        }
+        this._restoreInFlight = true;
+        const progress = (type, detail) => {
+            this._lastRestoreEvent = { type, detail };
+            this.log('info', `Capsule restore: ${type}`, { detail });
+            this.emit('recovery:restore-progress', { type, detail });
+        };
+        const stagedPath = path.join(this.dataDir, `${this.networkName}.db.capsule-restore`);
+        const dropStaged = () => {
+            for (const suffix of ['', '-wal', '-shm']) {
+                try {
+                    fs.unlinkSync(`${stagedPath}${suffix}`);
+                }
+                catch {
+                }
+            }
+        };
+        try {
+            const blobs = [...this._peerRetrievedCapsules.values()].map((c) => c.blob);
+            progress('capsule:selecting', `${blobs.length} candidate capsule(s) from storage peers`);
+            dropStaged();
+            const installFailure = (err) => err instanceof recovery_1.CapsuleCandidateError
+                ? new errors_1.BeignetError('CAPSULE_RESTORE_FAILED', `No retrieved capsule could be restored: ${err.message}`)
+                : new errors_1.BeignetError('CAPSULE_RESTORE_INSTALL_FAILED', `Could not write the restored database: ${err instanceof Error ? err.message : String(err)}`);
+            let staged;
+            try {
+                staged = new sqlite_storage_1.SqliteStorage(stagedPath, () => {
+                }, this._storageEncryptionKey
+                    ? { encryptionKey: this._storageEncryptionKey }
+                    : undefined);
+                staged.open();
+            }
+            catch (err) {
+                dropStaged();
+                throw installFailure(err);
+            }
+            let result;
+            try {
+                result = (0, recovery_1.restoreBestRecoveryCapsule)(blobs, staged, this.nodeSecret(), {
+                    scratchStorage: () => {
+                        const scratch = new sqlite_storage_1.SqliteStorage(':memory:');
+                        scratch.open();
+                        return scratch;
+                    }
+                });
+                const expectedNetwork = this.toLnNetwork(this.networkName);
+                if (result.scb.network !== expectedNetwork) {
+                    throw new recovery_1.CapsuleCandidateError(`capsule SCB network "${result.scb.network}" does not match ` +
+                        `this node's network "${expectedNetwork}"`);
+                }
+            }
+            catch (err) {
+                staged.close();
+                dropStaged();
+                throw installFailure(err);
+            }
+            const head = {
+                writerEpoch: result.capsule.writerEpoch.toString(),
+                latestSequence: result.capsule.latestSequence.toString()
+            };
+            const newestSeenHead = {
+                writerEpoch: result.newestSeenHead.writerEpoch.toString(),
+                latestSequence: result.newestSeenHead.latestSequence.toString()
+            };
+            if (result.tier === 2 &&
+                (0, recovery_1.chainPromisedQuorum)(staged, (0, recovery_1.deriveRecoveryMasterKey)(this.nodeSecret()), (0, ecdh_1.getPublicKey)(this.nodeSecret()))) {
+                staged.close();
+                dropStaged();
+                throw new errors_1.BeignetError('CAPSULE_RESTORE_QUORUM_NAMESPACE', 'The best capsule carries a quorum-durability journal, which ' +
+                    'cannot boot without its guardian quorum even unfenced; ' +
+                    'restore through the guardian set, or recover the channels ' +
+                    'from the peer-retrieved backup with the SCB restore route.');
+            }
+            let unfenced;
+            if (result.capsule.guardians.length > 0) {
+                const locators = redactGuardians(result.capsule.guardians);
+                if (!unfencedRequested) {
+                    staged.close();
+                    dropStaged();
+                    this.log('warn', 'Capsule restore refused: capsule names a guardian set', {
+                        guardians: locators
+                    });
+                    throw new errors_1.BeignetError('CAPSULE_RESTORE_GUARDIAN_BACKED', `The best capsule names ${locators.length} guardian(s): its state ` +
+                        'belongs to a guardian-backed namespace, which restores through ' +
+                        'the guardian set with fencing, not from peer storage. Restart ' +
+                        'in that recovery mode with the guardians the capsule names ' +
+                        '(capsules.best.guardians on the status route, or the ' +
+                        'capsule-guardians handoff when they need credentials); for an ' +
+                        'emergency SCB-only recovery use the peer-retrieved backup with ' +
+                        'the SCB restore route. An operator whose guardian set is gone ' +
+                        'can pass unfenced: true, which cannot fence the old writer.');
+                }
+                unfenced = { guardians: locators };
+                this.log('warn', 'UNFENCED capsule restore: the capsule names a guardian set and ' +
+                    'the previous writer is not fenced; if it still runs, it keeps ' +
+                    'acting on these channels', { guardians: locators });
+                progress('capsule:unfenced', `restoring a guardian-backed capsule without fencing: the previous writer is NOT fenced (${locators.length} guardian(s) named)`);
+            }
+            const common = {
+                channelCount: result.scb.channels.length,
+                framesApplied: result.framesApplied,
+                head,
+                newestSeenHead,
+                rejectedCandidates: result.rejectedCandidates,
+                ...(unfenced ? { unfenced } : {})
+            };
+            if (result.tier === 1) {
+                staged.close();
+                dropStaged();
+                progress('capsule:tier1', `no inline journal validated; recovering ${common.channelCount} channel(s) from the embedded SCB`);
+                const { recovering, skipped } = await this.node.recoverFromStaticChannelBackup(result.scb.channels);
+                const info = {
+                    tier: 1,
+                    ...common,
+                    restartRequired: false,
+                    recovering,
+                    skipped
+                };
+                progress('restore:complete', `Tier 1: ${recovering.length} channel(s) recovering, ${skipped.length} skipped`);
+                this.emit('recovery:restored', {
+                    exact: false,
+                    framesApplied: 0,
+                    guardiansRepaired: 0,
+                    epoch: head.writerEpoch,
+                    tier: 1,
+                    restartRequired: false
+                });
+                return info;
+            }
+            try {
+                this.carryDaemonState(this.storage, staged);
+            }
+            catch (err) {
+                staged.close();
+                dropStaged();
+                throw installFailure(err);
+            }
+            staged.close();
+            progress('capsule:installed', `Tier 2: ${result.framesApplied} frame(s) replayed at epoch ${head.writerEpoch} sequence ${head.latestSequence}`);
+            const dbPath = path.join(this.dataDir, `${this.networkName}.db`);
+            const keptPath = `${dbPath}.pre-capsule-restore-${new Date()
+                .toISOString()
+                .replace(/[:.]/g, '-')}`;
+            const marker = {
+                version: 1,
+                stagedAt: Date.now(),
+                staged: path.basename(stagedPath),
+                keep: path.basename(keptPath),
+                head,
+                tier: 2
+            };
+            try {
+                writeFileAtomic(this.capsuleRestoreMarkerPath(), JSON.stringify(marker));
+            }
+            catch (err) {
+                dropStaged();
+                throw installFailure(err);
+            }
+            this._restartRequired = true;
+            this.teardownNodeForRestart();
+            try {
+                this.finishStagedCapsuleRestore(dbPath);
+            }
+            catch (err) {
+                this.log('error', 'Capsule restore swap did not complete', {
+                    error: err instanceof Error ? err.message : String(err)
+                });
+                throw new errors_1.BeignetError('CAPSULE_RESTORE_INSTALL_FAILED', 'The restored database was written but the file swap did not ' +
+                    'complete; restart the daemon, which finishes the install (' +
+                    (err instanceof Error ? err.message : String(err)) +
+                    ')');
+            }
+            const info = {
+                tier: 2,
+                ...common,
+                restartRequired: true
+            };
+            progress('restore:complete', `restored database installed (previous kept at ${path.basename(keptPath)}); restart the daemon to resume ${common.channelCount} channel(s)`);
+            this.emit('recovery:restored', {
+                exact: true,
+                framesApplied: result.framesApplied,
+                guardiansRepaired: 0,
+                epoch: head.writerEpoch,
+                tier: 2,
+                restartRequired: true
+            });
+            return info;
+        }
+        finally {
+            this._restoreInFlight = false;
+        }
+    }
+    teardownNodeForRestart() {
+        if (this.backupTimer) {
+            clearInterval(this.backupTimer);
+            this.backupTimer = undefined;
+        }
+        if (this._sweepRefreshTimer) {
+            clearInterval(this._sweepRefreshTimer);
+            this._sweepRefreshTimer = undefined;
+        }
+        if (this._fallbackRecoveryTimer) {
+            clearInterval(this._fallbackRecoveryTimer);
+            this._fallbackRecoveryTimer = undefined;
+        }
+        this.paymentQueue?.removeAllListeners();
+        this.node.destroy();
+        void this.wallet?.stop().catch(() => {
+        });
+    }
+    capsuleRestoreMarkerPath() {
+        return path.join(this.dataDir, `${this.networkName}.capsule-restore.json`);
+    }
+    carryDaemonState(from, to) {
+        const overrides = from.loadWalletData(auth_1.AUTH_KEY_OVERRIDES_STORAGE_KEY);
+        if (overrides !== null) {
+            to.saveWalletData(auth_1.AUTH_KEY_OVERRIDES_STORAGE_KEY, overrides);
+        }
+        try {
+            for (const hook of from.loadAllWebhooks()) {
+                to.saveWebhook(hook.id, hook.url, hook.events, hook.secretHash, hook.createdAt);
+            }
+        }
+        catch (err) {
+            this.log('warn', 'Could not carry webhooks into the restore', {
+                error: err instanceof Error ? err.message : String(err)
+            });
+        }
+        try {
+            for (const peer of from.loadAllPeerAddresses()) {
+                to.savePeerAddress(peer.pubkey, peer.host, peer.port);
+            }
+        }
+        catch (err) {
+            this.log('warn', 'Could not carry peer addresses into the restore', {
+                error: err instanceof Error ? err.message : String(err)
+            });
+        }
+    }
+    finishStagedCapsuleRestore(dbPath) {
+        const markerPath = this.capsuleRestoreMarkerPath();
+        if (!fs.existsSync(markerPath))
+            return;
+        let marker;
+        try {
+            marker = JSON.parse(fs.readFileSync(markerPath, 'utf8'));
+            if (marker.version !== 1 ||
+                typeof marker.staged !== 'string' ||
+                typeof marker.keep !== 'string') {
+                throw new Error('unrecognized marker shape');
+            }
+        }
+        catch (err) {
+            throw new errors_1.BeignetError('CAPSULE_RESTORE_INSTALL_FAILED', `Unreadable capsule restore marker at ${markerPath} (${err instanceof Error ? err.message : String(err)}); inspect the data directory before starting`);
+        }
+        const stagedPath = path.join(this.dataDir, marker.staged);
+        const keptPath = path.join(this.dataDir, marker.keep);
+        const sidecars = ['-wal', '-shm'];
+        const moveAside = () => {
+            const current = new sqlite_storage_1.SqliteStorage(dbPath, () => {
+            }, this._storageEncryptionKey
+                ? { encryptionKey: this._storageEncryptionKey }
+                : undefined);
+            current.open();
+            try {
+                (0, recovery_1.assertEmptyTarget)(current);
+            }
+            finally {
+                current.close();
+            }
+            fs.renameSync(dbPath, keptPath);
+            for (const suffix of sidecars) {
+                try {
+                    fs.renameSync(`${dbPath}${suffix}`, `${keptPath}${suffix}`);
+                }
+                catch {
+                }
+            }
+        };
+        const stagedExists = fs.existsSync(stagedPath);
+        const dbExists = fs.existsSync(dbPath);
+        if (stagedExists) {
+            if (dbExists)
+                moveAside();
+            for (const suffix of sidecars) {
+                try {
+                    fs.unlinkSync(`${stagedPath}${suffix}`);
+                }
+                catch {
+                }
+            }
+            fs.renameSync(stagedPath, dbPath);
+            this.log('info', 'Capsule restore installed', {
+                head: marker.head,
+                previous: marker.keep
+            });
+        }
+        else if (!dbExists) {
+            fs.unlinkSync(markerPath);
+            throw new errors_1.BeignetError('CAPSULE_RESTORE_INSTALL_FAILED', `Capsule restore marker found but neither ${marker.staged} nor ` +
+                `the database exists; the previous database may be at ` +
+                `${marker.keep}. Inspect the data directory before starting`);
+        }
+        fs.unlinkSync(markerPath);
+    }
+    nodeSecret() {
+        if (!this._nodeSecret) {
+            this._nodeSecret = (0, wallet_keys_1.deriveLightningKeysFromMnemonic)(this.mnemonic, undefined, this.toCoinType(this.networkName)).nodePrivateKey;
+        }
+        return this._nodeSecret;
+    }
     async restoreFromGuardians() {
         if (this._restoreInFlight) {
             throw new errors_1.BeignetError('RESTORE_IN_PROGRESS', 'A guardian restore is already running; watch ' +
@@ -3404,6 +3894,7 @@ class BeignetNode extends events_1.EventEmitter {
                     ? 'Channel balances are healthy'
                     : `All ${readyChannels.length} channel(s) are >90% depleted in one direction`
         });
+        checks.push(this.channelBackupReadiness());
         let score = 100;
         let hasCriticalFailure = false;
         for (const check of checks) {
@@ -3425,6 +3916,65 @@ class BeignetNode extends events_1.EventEmitter {
             checks
         };
     }
+    channelBackupReadiness() {
+        const name = 'CHANNEL_BACKUP';
+        const mode = this.recoveryMode;
+        if (mode === 'off') {
+            return {
+                name,
+                status: 'WARN',
+                severity: 'WARNING',
+                message: 'No recovery mode: a lost device can only force-close its ' +
+                    'channels from the SCB (set BEIGNET_RECOVERY_MODE)'
+            };
+        }
+        const status = this.node.getRecoveryStatus();
+        if (status.fenced || status.gate === 'fenced') {
+            return {
+                name,
+                status: 'FAIL',
+                severity: 'CRITICAL',
+                message: 'Another device owns this recovery namespace; this node is ' +
+                    'fenced and must not operate'
+            };
+        }
+        if (status.backfillLost) {
+            return {
+                name,
+                status: 'FAIL',
+                severity: 'CRITICAL',
+                message: 'This recovery namespace lost its guardian backfill; no ' +
+                    'further channel state can be proven durable'
+            };
+        }
+        if (mode === 'peer-storage') {
+            return {
+                name,
+                status: 'WARN',
+                severity: 'WARNING',
+                message: 'Recovery capsules go to storage peers only (Tier 2 restore ' +
+                    'via /recovery/restore-capsule); no guardian quorum, so no ' +
+                    'fencing between devices'
+            };
+        }
+        if (status.gate !== 'confirmed') {
+            return {
+                name,
+                status: 'WARN',
+                severity: 'WARNING',
+                message: `Guardian mode ${mode}: the quorum has not confirmed this ` +
+                    'lease yet; channels stay quarantined'
+            };
+        }
+        return {
+            name,
+            status: 'PASS',
+            severity: 'WARNING',
+            message: `Channel state replicated to a guardian quorum (${mode}, durable ` +
+                `through ${status.lastDurableSequence}); a lost device resumes ` +
+                'its channels'
+        };
+    }
     getLiquiditySnapshot() {
         const snapshot = this.node.getLiquiditySnapshot();
         let reserveMsat = 0n;
@@ -3954,15 +4504,21 @@ class BeignetNode extends events_1.EventEmitter {
         return { recovering, skipped, channelCount: backup.channels.length };
     }
     refreshStaticChannelBackup() {
-        if (this.destroyed)
+        if (this.destroyed || this._restartRequired)
             return;
         try {
-            const { encoded } = this.exportStaticChannelBackup();
-            if (this.peerStorageEnabled) {
-                const sent = this.node.distributePeerStorage(Buffer.from(encoded, 'utf8'));
-                if (sent > 0) {
-                    this.log('debug', 'Pushed SCB to peer storage', { peers: sent });
-                }
+            const { encoded, channelCount } = this.exportStaticChannelBackup();
+            if (!this.peerStorageEnabled)
+                return;
+            if (this.recoveryNodeConfig?.enabled)
+                return;
+            if (channelCount === 0 && !this._pushedChannelBackup)
+                return;
+            const sent = this.node.distributePeerStorage(Buffer.from(encoded, 'utf8'));
+            if (channelCount > 0)
+                this._pushedChannelBackup = true;
+            if (sent > 0) {
+                this.log('debug', 'Pushed SCB to peer storage', { peers: sent });
             }
         }
         catch (err) {
@@ -3972,6 +4528,66 @@ class BeignetNode extends events_1.EventEmitter {
         }
     }
     handleRetrievedPeerStorage(peerPubkey, blob) {
+        const capsule = (0, recovery_1.decodeRecoveryCapsuleBlob)(blob, this.nodeSecret());
+        if (capsule) {
+            let embedded;
+            try {
+                embedded = (0, scb_1.decodeScb)(capsule.encryptedScb, this.nodeSecret());
+            }
+            catch {
+                this.log('debug', 'Ignoring capsule whose embedded SCB does not decode', {
+                    fromPeer: peerPubkey
+                });
+                return;
+            }
+            if (!this.retrievedBackupMatchesNetwork(embedded, peerPubkey, 'capsule')) {
+                return;
+            }
+            const held = this._peerRetrievedCapsules.get(peerPubkey);
+            const inline = capsule.inlineRecoveryState !== undefined;
+            if (!held ||
+                capsule.writerEpoch > held.writerEpoch ||
+                (capsule.writerEpoch === held.writerEpoch &&
+                    capsule.latestSequence > held.latestSequence) ||
+                (capsule.writerEpoch === held.writerEpoch &&
+                    capsule.latestSequence === held.latestSequence &&
+                    (inline || !held.inline))) {
+                this._peerRetrievedCapsules.set(peerPubkey, {
+                    blob: Buffer.from(blob),
+                    writerEpoch: capsule.writerEpoch,
+                    latestSequence: capsule.latestSequence,
+                    inline,
+                    channelCount: embedded.channels.length,
+                    guardians: capsule.guardians,
+                    receivedAt: Date.now()
+                });
+                this.log('info', 'Recovered capsule from peer storage', {
+                    fromPeer: peerPubkey,
+                    writerEpoch: capsule.writerEpoch.toString(),
+                    latestSequence: capsule.latestSequence.toString(),
+                    inline,
+                    channelCount: embedded.channels.length,
+                    guardians: capsule.guardians.length
+                });
+                if (this.recoveryGuardianSet.length > 0 &&
+                    !sameGuardianIds(capsule.guardians.map((g) => g.guardianId), this.recoveryGuardianSet.map((g) => g.guardianId.toString('hex'))) &&
+                    (!held ||
+                        !sameGuardianIds(capsule.guardians.map((g) => g.guardianId), held.guardians.map((g) => g.guardianId)))) {
+                    this.log('warn', 'Retrieved capsule names a guardian set that differs from ' +
+                        'the configured one; the configured set stays in force', {
+                        fromPeer: peerPubkey,
+                        capsule: redactGuardians(capsule.guardians),
+                        configured: this.recoveryGuardianSet.map((g) => ({
+                            guardianId: g.guardianId.toString('hex'),
+                            url: g.url
+                        }))
+                    });
+                }
+            }
+            const seed = bip39.mnemonicToSeedSync(this.mnemonic);
+            this.offerRetrievedScb((0, scb_1.encodeScb)(embedded, seed), embedded, peerPubkey, 'capsule');
+            return;
+        }
         let backup;
         const encoded = blob.toString('utf8');
         try {
@@ -3984,17 +4600,42 @@ class BeignetNode extends events_1.EventEmitter {
             });
             return;
         }
-        if (this._peerRetrievedScb &&
-            this._peerRetrievedScb.createdAt >= backup.createdAt) {
+        if (!this.retrievedBackupMatchesNetwork(backup, peerPubkey, 'scb'))
             return;
+        this.offerRetrievedScb(encoded, backup, peerPubkey, 'scb');
+    }
+    retrievedBackupMatchesNetwork(backup, fromPeer, source) {
+        const expected = this.toLnNetwork(this.networkName);
+        if (backup.network === expected)
+            return true;
+        this.log('debug', 'Ignoring peer storage backup from another network', {
+            fromPeer,
+            source,
+            network: backup.network,
+            expected
+        });
+        return false;
+    }
+    offerRetrievedScb(encoded, backup, fromPeer, source) {
+        const held = this._peerRetrievedScb;
+        if (held) {
+            if (backup.channels.length === 0 && held.channelCount > 0)
+                return;
+            if (held.createdAt >= backup.createdAt &&
+                !(held.channelCount === 0 && backup.channels.length > 0)) {
+                return;
+            }
         }
         this._peerRetrievedScb = {
             encoded,
             createdAt: backup.createdAt,
-            fromPeer: peerPubkey
+            fromPeer,
+            channelCount: backup.channels.length,
+            source
         };
         this.log('info', 'Recovered SCB from peer storage', {
-            fromPeer: peerPubkey,
+            fromPeer,
+            source,
             createdAt: backup.createdAt,
             channelCount: backup.channels.length
         });
@@ -4036,6 +4677,7 @@ class BeignetNode extends events_1.EventEmitter {
             clearTimeout(this._confirmTimer);
             this._confirmTimer = undefined;
         }
+        this.stopRecoveryLeaseCheck();
         if (this._backupPromise) {
             await this._backupPromise.catch(() => {
             });
@@ -4070,6 +4712,7 @@ class BeignetNode extends events_1.EventEmitter {
             clearTimeout(this._confirmTimer);
             this._confirmTimer = undefined;
         }
+        this.stopRecoveryLeaseCheck();
         this.paymentQueue?.removeAllListeners();
         this.node?.destroy();
         this.storage.close();
@@ -4139,4 +4782,6 @@ class BeignetNode extends events_1.EventEmitter {
 }
 exports.BeignetNode = BeignetNode;
 BeignetNode.INITIAL_GOSSIP_PRIME_TIMEOUT_MS = 90000;
+BeignetNode.DEFAULT_LEASE_CHECK_INTERVAL_MS = 5 * 60000;
+BeignetNode.MAX_TIMER_MS = 2147483647;
 //# sourceMappingURL=beignet-node.js.map