railiance-bootstrap/docs/identity-recovery.md

Bootstrap from an identity backup

Use this handoff when recovering an existing Railiance identity, before introducing new issuer or MFA keys. railiance-bootstrap sequences recovery; NetKingdom owns identity capture and acceptance, S1/S2 own the replacement host/cluster and S3 owns database/custody service recovery. There is no automatic bare-VM production restore.

1. Independently obtain the reviewed repositories/toolchain and the railiance-backup age key from offline/password-safe custody. Do not depend on the failed SSO or OpenBao instance to obtain these. The key stays in the operator's hidden terminal.
2. Retrieve the exact encrypted net-kingdom-identity-*.tar.age generation and safe transfer receipt from Storage Share Backup/railiance-backups/net-kingdom-identity/. The initial implementation is pending owner admission and first full bundle; existing privacyIDEA database-only dumps do not include service keys. Runtime publisher/retention shares are not recovery authority. During a healthy attended drill, NetKingdom retrieve-identity.py binds an independent Backup-account download by strong ETag/size/SHA256. That helper currently uses a healthy OpenBao custody path: during total custody loss, use independently held provider access to download and obtain an owner-reviewed transfer receipt before verification. That offline provider adapter is not implemented here.
3. Follow the exact NetKingdom recovery ceremony. On a healthy workstation with age and Docker, invoke the bootstrap handoff through the hidden-key wrapper:

../net-kingdom/sso-mfa/bootstrap/sops-custody-unlock.sh \
  --expected-recipient age1zvryunvjhvpkmasskauga2heeg0ztnte9ymgppvjge36ekumk50syr3tsz \
  --prompt -- bash bin/railiance identity-recovery \
  --transfer-receipt /PRIVATE/independent-transfer.json \
  --receipt /PRIVATE/new-recovery-result.json

Paths are operator-selected private files; never paste keys or restored values into chat/logs. The command delegates to the reviewed sibling NetKingdom verifier. NETKINGDOM_RECOVERY_ROOT selects an explicitly reviewed alternate checkout. Verification decrypts privately, rejects a wrong key, checks the encrypted manifest/SQLite integrity/original RSA pairs, restores PostgreSQL in a pinned networkless disposable container and verifies cleanup. Its safe receipt does not contain restored credentials. A successful archive receipt is not full-service recovery.

4. Provision an isolated replacement through S1 → S2 → S3, with outbound notification/provider writes disabled and fresh host/volume bindings reviewed by the owners. Production-target UIDs in the backup capture profile deliberately prevent capture tools from silently operating on a replacement cluster. Do not rebind them merely to make a check pass.
5. Have NetKingdom/service owners restore original directory/storage/encryption/signing/audit material into the isolated environment through a separately reviewed restore procedure. Prove existing-user authentication, issuer/JWKS/policy/client continuity, existing-token decryption/MFA, historical/new audit signatures and negative cases. The archive verifier deletes its plaintext; it is not a production restore/import command. Keep restored identities and outbound effects isolated until owner acceptance, then hand operation to the ordinary layers.
6. Retain the known-good independently recovered generation, record the exact artifact/hash and owner acceptance, retire temporary custody and verify cleanup. New backup grants and daily timer activation are separate owner-reviewed steps in the NetKingdom ceremony.

Discovery: capability.security.bootstrap-recovery in the owning NetKingdom registry, related to capability.railiance.bootstrap-sequencing. Search reuse-surface for identity backup, restore, privacyidea or disaster-recovery. Neither a registry entry nor this dispatcher grants credentials or certifies an unattended disaster rebuild.