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

2.3 KiB Raw Blame History