Implement audited lost-factor recovery and track remaining P04 acceptance

Assistant: codex
Assistant-Model: gpt-6-astra
Assistant-Session: 01a092fe-13b1-7f12-ac74-7d258af4d79c

docs/keycape-factor-recovery.md

@@ -0,0 +1,70 @@
+# Attended lost-factor recovery
+
+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.