Skip to content

Sudo

Short-lived re-authentication for sensitive actions. Configure with sudo=SudoConfig() on CRUDAuth and gate routes with auth.require_sudo().

crudauth.sudo.SudoConfig dataclass 

SudoConfig(
    window_seconds: int = 300,
    max_attempts: int = 3,
    lockout_seconds: int = 900,
)

Tuning for sudo elevation and its lockout.

Parameters:

Name Type Description Default
window_seconds int

How long an elevation stays valid after a correct password (the "you're still here" window).

 300
max_attempts int

Wrong-password attempts allowed before the sudo lockout trips.

 3
lockout_seconds int

How long sudo stays locked once tripped. The login flow is unaffected - only further elevation is blocked.

 900

crudauth.sudo.SudoManager 

SudoManager(
    *,
    session_manager: SessionManager,
    repo: UserRepository,
    backend: RateLimiterBackend | None,
    hooks: AuthHooks,
    config: SudoConfig,
    mfa: MfaService | None = None,
)

Elevate and check sudo state for session-backed principals.

Built by CRUDAuth when sudo= is set and a session transport is configured, and exposed as auth.sudo.

Example 
@app.post("/sudo")
async def sudo(body: SudoIn, request: Request, user=Depends(auth.current_user())):
    await auth.sudo.elevate(user, body.password, request=request)

elevate async 

elevate(
    principal: Principal,
    password: str | None = None,
    *,
    code: str | None = None,
    db: AsyncSession | None = None,
    request: Request | None = None,
) -> datetime

Re-verify password, or an authenticator code, and stamp the session as elevated.

A code needs MFA configured, an enrolled account, and the request's db (the code's time step is claimed so it can't be reused).

Returns the absolute instant the elevation expires.

Raises:

Type Description
ValueError

Neither or both of password and code, or a code without MFA or db.
ForbiddenException

The principal isn't session-backed, or its session has since vanished (stale credential).
UnauthorizedException

Wrong password or code (counts toward the lockout).
SudoLockoutError

Too many wrong attempts; sudo is locked (429 + Retry-After). The elevation stamp is cleared on lockout.

is_elevated async 

is_elevated(principal: Principal) -> bool

Whether the principal's session holds an unexpired sudo elevation.