54 lines
2.3 KiB
Markdown
54 lines
2.3 KiB
Markdown
# Console TOTP Admin Reset Specification
|
|
|
|
## Purpose
|
|
|
|
Allows a `platform_admin` to clear a user's 2FA enrollment when they are locked out or the authenticator device is lost. Includes audit trail.
|
|
|
|
## Requirements
|
|
|
|
### Requirement: Admin 2FA Reset Endpoint
|
|
|
|
The system MUST provide `POST /api/platform/users/:id/2fa-reset` restricted to callers with the `platform_admin` role.
|
|
|
|
On success, the system MUST atomically clear all 2FA state for the target user: `two_factor_enabled`, `two_factor_secret_encrypted`, `two_factor_secret_nonce`, `last_totp_step_used`, `totp_locked_until`, and ALL rows in `two_factor_recovery_codes`.
|
|
|
|
After clearing, the system MUST write an audit log entry containing: actor user ID, target user ID, action `user.2fa_reset`, and timestamp. The endpoint MUST return HTTP 204.
|
|
|
|
#### Scenario: Admin resets target user's 2FA → cleared + audited
|
|
|
|
- GIVEN a `platform_admin` caller and a target user with `two_factor_enabled = true`
|
|
- WHEN `POST /api/platform/users/:id/2fa-reset` is called
|
|
- THEN the response is HTTP 204
|
|
- AND `users.two_factor_enabled` is `false` for the target
|
|
- AND `users.two_factor_secret_encrypted` and `two_factor_secret_nonce` are NULL
|
|
- AND `users.last_totp_step_used` and `users.totp_locked_until` are NULL
|
|
- AND all rows in `two_factor_recovery_codes` for the target are deleted
|
|
- AND one audit log row is written with actor, target, and action `user.2fa_reset`
|
|
|
|
#### Scenario: Non-admin caller → 403
|
|
|
|
- GIVEN an authenticated user without `platform_admin` role
|
|
- WHEN `POST /api/platform/users/:id/2fa-reset` is called
|
|
- THEN the response is HTTP 403
|
|
- AND no data is modified
|
|
|
|
#### Scenario: Target user does not exist → 404
|
|
|
|
- GIVEN a `platform_admin` caller
|
|
- WHEN `POST /api/platform/users/:id/2fa-reset` is called with an ID that does not exist
|
|
- THEN the response is HTTP 404
|
|
- AND no data is modified
|
|
|
|
#### Scenario: Target user already has 2FA disabled → 204 idempotent
|
|
|
|
- GIVEN a `platform_admin` caller and a target user with `two_factor_enabled = false`
|
|
- WHEN `POST /api/platform/users/:id/2fa-reset` is called
|
|
- THEN the response is HTTP 204
|
|
- AND an audit log row is still written
|
|
|
|
#### Scenario: Unauthenticated caller → 401
|
|
|
|
- GIVEN a request with no valid session token
|
|
- WHEN `POST /api/platform/users/:id/2fa-reset` is called
|
|
- THEN the response is HTTP 401
|