a704a72b6e
Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a092fe-13b1-7f12-ac74-7d258af4d79c
84 lines
4.9 KiB
Markdown
84 lines
4.9 KiB
Markdown
# 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.
|