# Supported platform lost-factor recovery

Routine P04 recovery is now available at
https://users.coulomb.social/platform/factor-recovery. Sign in with recent MFA as
a platform operator. The private provider service verifies that signed identity;
no OpenBao login or provider credential handoff is required. Use the page to
preview an exact login/factor, confirm identity verification and shared scope,
apply recovery, and look up the audit result by support reference.

Release evidence: user-engine/docs/evidence/2026-09-13-p04-recovery.md.
The OpenBao/Kubernetes CLI described below is a historical implementation step,
not the supported routine P04 path. Its unperformed native acceptance was
cancelled when the signed-session service replaced it (KEY-WP-0036-T02).

# Historical attended owner procedure

Implementation tracked by KEY-WP-0036 and USER-WP-0030-T03. Provider-local
recovery passes isolated tests; the attended production wrapper and portal
integration still require acceptance. No real account has been recovered by
this procedure yet. Run only as an attended platform operator with Kubernetes
administration access. This is not a public recovery API.

The wrapper derives the audit actor from an authenticated OpenBao entity with
the platform-admin policy. Root and workload credentials are not substitutes.
It checks the cluster identity and invokes the reviewed KeyCape provider-local
module, without exporting provider credentials. OpenBao identity does not grant
Kubernetes access: the operator must independently have that access.

## Procedure

1. Establish the exact directory login, realm, selected factor serial and support
   reference. Verify ownership through the organization's account-recovery
   procedure; knowing a username or password alone is not identity verification.
2. Review both scripts (`scripts/keycape_factor_recovery.py` here and
   `../key-cape/scripts/factor_recovery.py`). Keep the sibling repositories at
   their reviewed revisions. Route attended authentication with `warden route
   show openbao-platform-admin-login --json` and the lane's contained execution
   procedure. The owner command must remain silent; inspect only its receipt.
3. Preview using the owner command below inside the attended envelope. Replace
   placeholders with metadata only. The receipt path must not already exist.

   ```sh
   python3 scripts/keycape_factor_recovery.py --user LOGIN --serial SERIAL      --reference SUPPORT-REFERENCE --receipt /tmp/recovery-preview.json
   ```

4. Review the receipt's identity, factor, active state, version and scope.
   `shared_identity_across_applications` means the change affects every application
   using this identity, not just one tenant. Serialize recovery operations for
   this identity/reference; this operator tool is not a concurrent request service.
5. After identity verification, invoke the same command with `--apply
   --identity-verified --expected-version VERSION` and a fresh receipt path.
   The verification flag records the operator's attestation; it does not perform
   identity verification. Preserve the original reference and preview version.
6. Require a successful receipt and durable `keycape.factor.recovery` provider
   audit entry for that reference. Recheck factor state. Guide the user through
   a fresh login and replacement-factor enrollment, including possession proof.
   Applications requiring AAL2 stay inaccessible until another confirmed factor
   is usable. Disabling one factor alone does not promise restored access.

## Failure and recovery

- Ownership/realm mismatch, missing identity verification, stale preview or a
  conflicting reference: no intended mutation; correct the target or obtain a
  new preview. Do not silently substitute another account or factor.
- Failure to persist the initial audit entry prevents disabling the factor.
- A failure after disabling may mean the change succeeded but completion evidence
  was interrupted. Retry the original approved request with the same reference
  and version. Readback reconciles its audit without repeating the mutation.
- Replacement/reassignment or reactivation invalidates the old confirmation.
- Never automatically re-enable a lost factor as rollback. Escalate the support
  case if the user cannot enroll a replacement through the supported flow.

Recovery disables exactly one owned factor; it preserves account, password and
other factors. Receipts contain support/identity metadata and must be retained
with appropriate access controls. Never attach JWTs, OTP seeds or passwords.

## Automated evidence

`make keycape-factor-tests` tests authenticated actor derivation and denial for
reader/root identities. KeyCape's `test_factor_recovery.py` tests preview,
ownership, verification, stale/replaced factors, audit outages and retry.
`provider-onboarding-contract.py` repeats recovery against the installed provider
implementation with an isolated database and separate temporary audit database.
Production wrapper/browser acceptance remains a separate task in KEY-WP-0036.