recovery: add backup and restore package

Introduce a dedicated recovery package for encrypted local backups of
static-address state and raw l402 token files.

The package owns the backup file format, seed-derived encryption,
static-address key re-derivation with gap fallback, token file restore,
and best-effort deposit reconciliation orchestration. It also includes
package-level documentation and focused tests for the file helpers.

Author: hieblmi

recovery/README.md

@@ -0,0 +1,184 @@
+# Recovery Package
+
+This package implements phase-1 local recovery for Loop static addresses and
+L402 authentication state.
+
+## Goal
+
+The recovery flow is meant to let a fresh or repaired Loop instance continue
+using the same static address and the same L402-backed server identity after a
+local crash, disk loss, or Loop data-directory replacement.
+
+The package also keeps older generations of recoverable state around. That
+matters when a user first creates one paid-L402/static-address pair, later
+loses the local Loop state, and then creates a different paid-L402/static-
+address pair. In that case the older deposits are still recoverable as long as
+the older timestamped backup file is kept.
+
+The recovery data is intentionally local:
+
+- It is written into the active Loop network data directory.
+- It contains only the minimum local state needed to rebuild client-side state.
+- It is encrypted with a key derived from the same lnd seed material that backs
+  static-address keys.
+
+## What Is Backed Up
+
+Each encrypted backup stores:
+
+- A backup format version.
+- The active Loop network.
+- Static-address protocol version.
+- Static-address server pubkey.
+- Static-address expiry.
+- The exact client key locator when available.
+- The static-address `pkScript`.
+- The derived taproot address string as an additional recovery hint.
+- The address initiation height.
+- The paid local `l402.token` file.
+
+The paid token file is preserved as a raw blob instead of decomposed token
+fields so the restore path remains compatible with Aperture's current file-store
+format without requiring a public token constructor.
+
+A given backup can contain:
+
+- Only a paid L402 token.
+- A paid L402 token together with a static address.
+
+Deposit state itself is not serialized into the backup file. Deposits are
+rediscovered on restore through the normal reconciliation path.
+
+## File Location
+
+This package keeps two backup forms in the active Loop network data directory:
+
+- A canonical latest snapshot:
+  `<loop-data-dir>/L402_backup.enc`
+- Immutable timestamped snapshots:
+  `<loop-data-dir>/L402_backup_<timestamp>.enc`
+  or `<loop-data-dir>/L402_backup_<timestamp>_<n>.enc`
+
+In the normal `loopd` layout this resolves inside the active network-specific
+directory, for example:
+
+`~/.loop/mainnet/L402_backup.enc`
+
+and
+
+`~/.loop/mainnet/L402_backup_20260414T093001.000000123Z.enc`
+
+The canonical `L402_backup.enc` file is always updated to the latest snapshot
+for compatibility and convenience. The timestamped files are the archival
+history that lets the user recover older generations.
+
+## Encryption Model
+
+The file is encrypted with `secretbox` using a symmetric key derived from lnd
+via `Signer.DeriveSharedKey`.
+
+The derivation uses:
+
+- A fixed NUMS public key.
+- The static-address key family.
+- Key index `0`.
+
+This gives the backup a deterministic local encryption key tied to the lnd seed
+without requiring an interactive password in phase 1.
+
+## Backup Creation Flow
+
+On startup, `loopd` asks this package to backfill the latest snapshot if any
+recoverable state exists.
+
+The backup write is a no-op when:
+
+- No static address exists locally.
+- No paid `l402.token` file exists locally.
+
+If either state source exists, the package:
+
+1. Collects the local static-address parameters.
+2. Reads the paid `l402.token` file from the Loop data dir.
+3. Serializes the payload as JSON.
+4. Encrypts it.
+5. If the recoverable state changed, atomically writes a new timestamped backup.
+6. Updates `L402_backup.enc` to the same latest snapshot.
+
+If the recoverable state did not change, no new timestamped archive is created.
+This avoids producing duplicate backups on every startup.
+
+The daemon also triggers backup refreshes when:
+
+- A usable paid L402 token has just been fetched and stored locally.
+- A new static address has just been created, stored, and imported into lnd.
+
+Pending or otherwise intermediate L402 token state is intentionally not backed
+up.
+
+## Restore Flow
+
+`loop recover --backup_file <path>` eventually calls into this package from
+inside `loopd`.
+
+If the backup path is omitted, the package uses the timestamped backup with the
+latest filename timestamp, falling back to `L402_backup.enc` for legacy or
+backfill-only states.
+
+Restore performs the following steps:
+
+1. Read and decrypt the backup file.
+2. Validate backup version and network.
+3. If static-address metadata is present, reconstruct the static-address client
+   pubkey:
+   - First try the exact backed-up key locator.
+   - If the locator is missing or unusable, scan backward with a gap of 20 in
+     the static-address key family.
+4. If static-address metadata is present, re-create the local static-address
+   record.
+5. If static-address metadata is present, re-import the static-address
+   tapscript into lnd.
+6. If a paid token is present, restore the paid `l402.token` file into the
+   local token store directory.
+7. If static-address metadata is present, trigger best-effort deposit
+   reconciliation.
+
+Restoring an older timestamped backup is expected to be done into a fresh Loop
+data directory because Loop still only supports a single local static address at
+a time. The same recommendation applies when the local directory already
+contains a different paid L402 token, because recovery is intended to recreate a
+specific prior generation of local state rather than merge multiple ones.
+
+## Deposit Reconciliation
+
+This package does not attempt to fully rebuild the complete historical deposit
+state from chain data alone.
+
+Instead, after static-address restore it calls the deposit manager's normal
+reconciliation path and lets Loop discover currently visible deposits from lnd's
+wallet view.
+
+This is intentionally best effort:
+
+- It is enough to recover practical local usability.
+- It avoids duplicating the full deposit FSM logic in the recovery layer.
+- It keeps the restore path aligned with normal manager behavior.
+
+## Package Boundaries
+
+This package owns:
+
+- Backup payload definition.
+- Encryption/decryption.
+- Reading/writing backup files.
+- Reading/writing paid L402 token files.
+- Static-address key re-derivation and restore orchestration.
+- Post-restore deposit reconciliation orchestration.
+
+This package does not own:
+
+- gRPC transport.
+- CLI command handling.
+- `loopd` startup wiring.
+
+Those remain in `loopd/` and `cmd/loop/`.