Module emergency 

Emergency-recovery primitives — the framework-side surface called by the rustio-admin user <op> CLI commands.

Each function performs the atomic DB-mutation chain for one emergency operation and returns a typed outcome the CLI uses to render its post-mutation summary.

D12 — CLI-only audit emission

These functions deliberately do NOT write the AuditEvent::EmergencyRecovery row. That emission lives in the CLI crate (crates/rustio-admin-cli/), so the audit row’s call-stack-of-record is always rooted in the CLI binary. The framework provides the DB transaction; the CLI provides the audit trail. The [admin::audit::tests::emergency_recovery_is_cli_only] unit test enforces this — adding an AuditEvent::EmergencyRecovery emission anywhere in crates/rustio-admin/src/ fails the default test gate.

D11 — atomic per command

Each function that mutates more than one row runs its mutations inside a single sqlx transaction. Partial failures roll back so half-applied state never lands — e.g. a reset_password that hashed + stored the new password but then failed to flip must_change_password would leave the user in a worse state than before.

Building blocks reused

• crate::auth::users::hash_password for Argon2id-hashed password storage
• crate::auth::invalidate_sessions for revocation under doctrine 22 (single writer of revoked_at)

See DESIGN_R4_EMERGENCY.md §6 for the building-block table per operation and §3 for the locked scope.

Enums

DisableMfaOutcome

Outcome of disable_mfa.

EmergencyAccessOutcome

Outcome of emergency_access.

PromoteOutcome

Outcome of promote. SoleAdministratorDemoteRefused is the only “refuse the operation outright” branch — the rest of the emergency surface allows action on any extant target (the operator already has DB access; the framework’s role is audit-visibility, not gatekeeping).

ResetOutcome

Outcome of reset_password. The CLI uses this to compose the post-mutation summary line (“password set, N sessions revoked” or “user not found”).

UnlockOutcome

Outcome of unlock.

Functions

disable_mfa

Clear every MFA column on the target user, delete every backup- code row, revoke every session for the user.

emergency_access

Issue a single-use password-reset URL bypassing the email mailer. The URL plaintext is returned in EmergencyAccessOutcome::Ok::url_path — the operator hands it to the target via whatever out-of-band channel makes sense.

fresh_correlation_id

Produce a fresh hyphenated UUID v7 for use as the CLI-emitted audit row’s correlation_id. Matches the format the framework’s correlation_id middleware writes per request, so a future cross-table audit pivot can join framework rows and CLI rows on this column without per-source post-processing.

generate_temp_password

Generate an alphanumeric temp password of len characters. The alphabet excludes visually ambiguous glyphs (0/O, 1/l/I) so an operator reading the password aloud or writing it down by hand has fewer transcription errors. Used by rustio-admin user reset-password when --temp-password is not supplied.

promote

Change the target user’s role to new_role.

reset_password

Set a new password for target_user_id, raise must_change_password = TRUE, revoke every session for the user.

unlock

Clear locked_until and reset failed_login_count = 0 on the target. Does NOT touch sessions — an unlock is not a session event per DESIGN_R4_EMERGENCY.md §7.