# 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