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,297 @@
+# Recovery Package
+
+This package implements local recovery for Loop's static-address and L402
+state.
+
+## Goal
+
+Recovery is generation-based. A generation is anchored by:
+
+- one paid L402 token
+- one immutable static-address generation root tied to that L402
+
+Today that generation root still materializes locally as one legacy static
+address. The backup format now also stores the stable generation metadata that
+future multi-address `main`/`change` issuance will recover by scanning from,
+without rewriting the backup file.
+
+The recovery flow is designed to let a fresh or repaired Loop instance rebuild
+that generation after local disk loss, data-directory replacement, or partial
+corruption.
+
+The current PR intentionally uses a single immutable backup per L402
+generation. Once written, that backup file is never updated in place.
+
+## Backup Model
+
+The daemon writes at most one encrypted backup file for each paid L402 token
+ID:
+
+`<loop-data-dir>/L402_backup_<l402-created-at-unix-ns>_<l402-token-id>.enc`
+
+In the normal layout this resolves inside the active network-specific Loop data
+directory, for example:
+
+`~/.loop/mainnet/L402_backup_1776159001000000000_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef.enc`
+
+There is no canonical mutable "latest backup" file anymore.
+
+If `loop recover` is called without `--backup_file`, Loop scans the active
+network directory, validates all immutable backups it can decrypt, and restores
+the backup with the latest timestamp in its filename. Legacy timestamp-less
+backup filenames remain readable and fall back to the encrypted payload's L402
+creation time for ordering.
+
+## What Is Backed Up
+
+Each encrypted backup stores:
+
+- a backup format version
+- the Loop network
+- the paid L402 token ID
+- the paid L402 token creation time
+- the raw paid `l402.token` file
+- immutable static-address generation metadata
+- the static-address protocol version
+- the generation server pubkey
+- the static-address expiry
+- the `main` key family
+- the `change` key locator
+- the `change` key family
+- the `change` key index
+- the generation start height
+- the restore lookahead
+- the current legacy static-address materialization
+- the static-address client pubkey
+- the static-address client key locator
+- the static-address `pkScript`
+- the derived taproot address string
+- the static-address initiation height
+
+The L402 file is preserved as a raw blob so restore remains compatible with the
+current Aperture token-store format.
+
+Deposit FSM state is not serialized into the backup. Deposits are rediscovered
+after restore through the normal reconciliation path.
+
+## Why The Backup Stores Both Root And Legacy Address Data
+
+The immutable generation metadata is the forward-compatible root for future
+multi-address recovery. The legacy single-address materialization is still kept
+because the current branch restores the V0 one-address model directly.
+
+That means the backup already contains the stable metadata that a future
+multi-address PR will need, while today's restore path can still recreate the
+existing legacy static address exactly.
+
+## 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 main key family
+- key index `0`
+
+This ties backup decryption to the same lnd seed that controls the static
+address keys without introducing a user-managed recovery password in this
+phase.
+
+## When Backups Are Written
+
+The backup is only written once a complete recoverable generation exists.
+Today that means both of the following must already exist locally:
+
+- a paid current `l402.token`
+- a local legacy static address bound to that token
+
+Pending tokens are not backed up.
+
+If the immutable backup file for the current paid token ID already exists,
+backup creation is a no-op.
+
+## Startup Behavior
+
+Startup is responsible for materializing the current generation before the
+backup is written.
+
+On startup `loopd` now:
+
+1. creates the recovery service
+2. if the install is fresh and immutable backup files already exist locally,
+   restores the latest backup by filename timestamp
+3. otherwise, asks the static-address manager for the current static address
+4. if the address does not exist yet, fetches the paid L402, derives the
+   client key, requests the legacy static address from the server, stores it,
+   and imports the tapscript into lnd
+5. writes the immutable backup for the resulting paid-L402/static-address
+   generation
+
+This gives the branch the "one backup per L402" property without later backup
+refreshes.
+
+### Existing Users
+
+For existing users that already have a paid L402 and a legacy static address,
+the first startup with the upgraded client backfills the missing immutable
+backup for the active generation.
+
+### Fresh Installs
+
+For fresh installations, startup first checks whether immutable backups already
+exist in the active Loop data directory.
+
+If they do, Loop restores the latest backup by filename timestamp instead of
+creating a new paid L402 generation.
+
+If they do not, startup materializes the initial paid L402 plus legacy static-
+address generation so the backup can be written immediately.
+
+The `loop static new` command is therefore no longer the only creation point.
+It now returns the current static address and only falls back to on-demand
+creation if startup initialization did not complete earlier.
+
+## Restore Flow
+
+`loop recover --backup_file <path>` restores a specific immutable backup. If
+`--backup_file` is omitted, Loop restores the most recent valid immutable
+backup in the active network directory.
+
+Current restore performs the following steps:
+
+1. derive the local encryption key from lnd
+2. read and decrypt the backup file
+3. validate the backup version, network, and L402 token ID
+4. restore the paid `l402.token` file if it is not already present with the
+   same contents
+5. if legacy static-address metadata is present, reconstruct the client pubkey
+6. recreate the local legacy static-address record and re-import its tapscript
+   into lnd
+7. trigger best-effort deposit reconciliation
+
+Client-key reconstruction uses the following strategy:
+
+- first try the exact backed-up key locator, including locator `0/0`
+- if that fails, scan a `+/-20` child-index window around the backed-up
+  locator in the static-address main key family
+- when the backup contains the client pubkey, require that the derived key
+  matches it before accepting the address reconstruction
+
+The multi-address scan-and-rebuild flow is intentionally not activated in this
+branch yet. This branch only makes sure the immutable backup already contains
+the metadata that future flow will need.
+
+## Future Multi-Address Generation
+
+The planned multi-address model uses only two client-side key families:
+
+- `main` addresses for externally visible static-address deposits
+- `change` addresses for outputs that return value back into the static-address
+  address space
+
+The future `static_addresses` table remains a table of concrete derived
+addresses. Each row represents one address child and stores:
+
+- the client pubkey
+- the server pubkey
+- the client key family
+- the client key index
+- the resulting `pkScript`
+- the protocol version
+- the generation initiation height
+
+The immutable backup does not store every row. Instead it stores the generation
+root metadata that allows those rows to be rediscovered by scanning.
+
+For each future `main` or `change` address:
+
+1. the client chooses the appropriate key family
+2. the client derives the next pubkey from lnd for that family
+3. the client combines that pubkey with the L402-bound server pubkey using the
+   static-address MuSig2 construction for the backed-up protocol version
+4. the taproot tweak commits to the static-address timeout leaf
+5. the resulting taproot output key yields the final P2TR `pkScript`
+6. the concrete child row is stored locally in `static_addresses`
+
+Because the backup is immutable, future restore must regenerate candidate
+`main` and `change` children from the backed-up branch metadata, rescan from
+the backed-up start height, and rebuild local table rows from what is found on
+chain. It must not depend on a mutable "last issued child index" snapshot.
+
+## Server Proof For Multi-Address Inputs
+
+For a future static swap or withdrawal that spends multi-address inputs, the
+server-side proof model is:
+
+1. the paid L402 authenticates the request and identifies the generation
+2. the L402 selects the fixed generation server pubkey and the fixed
+   protocol/expiry parameters
+3. for each input, the client sends the concrete client pubkey that was used to
+   construct that input's address
+4. the server recomputes the timeout leaf for the backed-up protocol version
+   and expiry
+5. the server recomputes the MuSig2 aggregate key from the concrete client
+   pubkey for that input, the server pubkey bound to the L402 generation, and
+   the taproot tweak implied by the timeout leaf
+6. the server derives the expected taproot output key and the expected P2TR
+   `pkScript`
+7. the server compares that derived `pkScript` with the prevout `pkScript` of
+   the input being authorized
+
+If they match, the input belongs to that L402 generation because the output
+commits to the generation's server key and the concrete client pubkey used for
+that input.
+
+This proof is about generation membership, not about proving a particular child
+index to the server. The immutable backup therefore only needs the stable
+generation root metadata, while exact row discovery remains a client-side
+wallet-and-chain scan problem.
+
+## Operational Limits
+
+Current restore still restores the legacy one-address model only.
+
+Some practical consequences follow from that:
+
+- restoring an older immutable backup is best done into a fresh Loop data
+  directory
+- only one legacy static address can be recreated directly by the current
+  restore code
+- historical deposit state is rebuilt best-effort from reconciliation, not by
+  replaying every stored deposit transition
+
+## Why The Backup Is Immutable
+
+The multi-address work needs recovery to be based on stable root material, not
+on mutable local cursor snapshots.
+
+Using one immutable backup per L402 forces that discipline now:
+
+- the backup must describe a recoverable generation root
+- restore must be able to rediscover state from deterministic wallet- and
+  chain-derived scanning
+- later address issuance must not depend on backup files being rewritten
+
+That is the key design constraint for the next PRs.
+
+## Package Boundaries
+
+This package owns:
+
+- backup payload definition
+- backup encryption and decryption
+- immutable backup-file discovery and selection
+- paid L402 token-file backup and restore
+- legacy static-address key re-derivation and restore orchestration
+- immutable generation metadata for future multi-address restore
+- post-restore deposit reconciliation orchestration
+
+This package does not own:
+
+- CLI command handling
+- gRPC transport
+- the static-address server protocol
+- the future multi-address scanning implementation
+- `loopd` startup wiring