Skip to content

application.commands.auth_commands

src.application.commands.auth_commands

Authentication commands (CQRS write operations).

Commands represent user intent to change system state. All commands are immutable (frozen=True) and use keyword-only arguments (kw_only=True).

Pattern: - Commands are data containers (no logic) - Handlers execute business logic - Commands don't return values (handlers return Result types) - Use Annotated types for validation (DRY principle)

Attributes

Classes

RegisterUser dataclass

Register new user account.

Creates user with email/password, generates email verification token. User cannot login until email is verified.

Attributes:

Name Type Description
email Email

User's email address (validated, normalized).
password Password

User's password (validated strength, plain text, will be hashed).
Example

command = RegisterUser( ... email="user@example.com", ... password="SecurePass123!", ... ) result = await handler.handle(command)

Source code in src/application/commands/auth_commands.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
@dataclass(frozen=True, kw_only=True)
class RegisterUser:
    """Register new user account.

    Creates user with email/password, generates email verification token.
    User cannot login until email is verified.

    Attributes:
        email: User's email address (validated, normalized).
        password: User's password (validated strength, plain text, will be hashed).

    Example:
        >>> command = RegisterUser(
        ...     email="user@example.com",
        ...     password="SecurePass123!",
        ... )
        >>> result = await handler.handle(command)
    """

    email: Email
    password: Password

AuthenticateUser dataclass

Authenticate user credentials.

Single responsibility: Verify user credentials only. Does NOT create sessions or generate tokens (CQRS separation).

Validates credentials, checks email verification, checks account lockout. Returns AuthenticatedUser on success (user_id, email, roles).

Attributes:

Name Type Description
email Email

User's email address (validated, normalized).
password Password

User's password (plain text, validated strength).
Example

command = AuthenticateUser( ... email="user@example.com", ... password="SecurePass123!", ... ) result = await handler.handle(command)

Returns Success(AuthenticatedUser) or Failure(error)
Source code in src/application/commands/auth_commands.py 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
@dataclass(frozen=True, kw_only=True)
class AuthenticateUser:
    """Authenticate user credentials.

    Single responsibility: Verify user credentials only.
    Does NOT create sessions or generate tokens (CQRS separation).

    Validates credentials, checks email verification, checks account lockout.
    Returns AuthenticatedUser on success (user_id, email, roles).

    Attributes:
        email: User's email address (validated, normalized).
        password: User's password (plain text, validated strength).

    Example:
        >>> command = AuthenticateUser(
        ...     email="user@example.com",
        ...     password="SecurePass123!",
        ... )
        >>> result = await handler.handle(command)
        >>> # Returns Success(AuthenticatedUser) or Failure(error)
    """

    email: Email
    password: Password

VerifyEmail dataclass

Verify user's email address.

Validates verification token, marks user as verified. User can login after email verification.

Attributes:

Name Type Description
token VerificationToken

Email verification token (validated hex format).
Example

command = VerifyEmail(token="abc123def456...") result = await handler.handle(command)

Source code in src/application/commands/auth_commands.py 
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
@dataclass(frozen=True, kw_only=True)
class VerifyEmail:
    """Verify user's email address.

    Validates verification token, marks user as verified.
    User can login after email verification.

    Attributes:
        token: Email verification token (validated hex format).

    Example:
        >>> command = VerifyEmail(token="abc123def456...")
        >>> result = await handler.handle(command)
    """

    token: VerificationToken

RefreshAccessToken dataclass

Refresh access token using refresh token.

Validates refresh token, generates new access token + new refresh token. Implements token rotation (old refresh token deleted).

Attributes:

Name Type Description
refresh_token RefreshToken

Opaque refresh token (validated urlsafe base64 format).
Example

command = RefreshAccessToken(refresh_token="dGhpcyBpcyB...") result = await handler.handle(command)

Source code in src/application/commands/auth_commands.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
@dataclass(frozen=True, kw_only=True)
class RefreshAccessToken:
    """Refresh access token using refresh token.

    Validates refresh token, generates new access token + new refresh token.
    Implements token rotation (old refresh token deleted).

    Attributes:
        refresh_token: Opaque refresh token (validated urlsafe base64 format).

    Example:
        >>> command = RefreshAccessToken(refresh_token="dGhpcyBpcyB...")
        >>> result = await handler.handle(command)
    """

    refresh_token: RefreshToken

RequestPasswordReset dataclass

Request password reset for user.

Generates password reset token, sends email with reset link. Always returns success (no user enumeration).

Attributes:

Name Type Description
email Email

User's email address (validated, normalized).
ip_address str | None

Client IP address (for audit, abuse detection).
user_agent str | None

Client user agent (for audit).
Example

command = RequestPasswordReset( ... email="user@example.com", ... ip_address="192.168.1.1", ... user_agent="Mozilla/5.0...", ... ) result = await handler.handle(command)

Source code in src/application/commands/auth_commands.py 
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
@dataclass(frozen=True, kw_only=True)
class RequestPasswordReset:
    """Request password reset for user.

    Generates password reset token, sends email with reset link.
    Always returns success (no user enumeration).

    Attributes:
        email: User's email address (validated, normalized).
        ip_address: Client IP address (for audit, abuse detection).
        user_agent: Client user agent (for audit).

    Example:
        >>> command = RequestPasswordReset(
        ...     email="user@example.com",
        ...     ip_address="192.168.1.1",
        ...     user_agent="Mozilla/5.0...",
        ... )
        >>> result = await handler.handle(command)
    """

    email: Email
    ip_address: str | None = None
    user_agent: str | None = None

ConfirmPasswordReset dataclass

Confirm password reset with token and new password.

Validates reset token, updates user password, revokes all sessions. Forces user to login again after password change.

Attributes:

Name Type Description
token VerificationToken

Password reset token (validated hex format).
new_password Password

New password (validated strength, plain text, will be hashed).
Example

command = ConfirmPasswordReset( ... token="xyz789abc123...", ... new_password="NewSecurePass456!", ... ) result = await handler.handle(command)

Source code in src/application/commands/auth_commands.py 
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
@dataclass(frozen=True, kw_only=True)
class ConfirmPasswordReset:
    """Confirm password reset with token and new password.

    Validates reset token, updates user password, revokes all sessions.
    Forces user to login again after password change.

    Attributes:
        token: Password reset token (validated hex format).
        new_password: New password (validated strength, plain text, will be hashed).

    Example:
        >>> command = ConfirmPasswordReset(
        ...     token="xyz789abc123...",
        ...     new_password="NewSecurePass456!",
        ... )
        >>> result = await handler.handle(command)
    """

    token: VerificationToken
    new_password: Password

LogoutUser dataclass

Logout user and revoke refresh token.

Revokes refresh token associated with current session. JWT access token cannot be revoked (expires naturally in 15 minutes).

Attributes:

Name Type Description
user_id UUID

User's unique identifier (from JWT).
refresh_token RefreshToken

Refresh token to revoke (validated urlsafe base64 format).
Example

command = LogoutUser( ... user_id=UUID("123e4567-e89b-12d3-a456-426614174000"), ... refresh_token="dGhpcyBpcyB...", ... ) result = await handler.handle(command)

Source code in src/application/commands/auth_commands.py 
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
@dataclass(frozen=True, kw_only=True)
class LogoutUser:
    """Logout user and revoke refresh token.

    Revokes refresh token associated with current session.
    JWT access token cannot be revoked (expires naturally in 15 minutes).

    Attributes:
        user_id: User's unique identifier (from JWT).
        refresh_token: Refresh token to revoke (validated urlsafe base64 format).

    Example:
        >>> command = LogoutUser(
        ...     user_id=UUID("123e4567-e89b-12d3-a456-426614174000"),
        ...     refresh_token="dGhpcyBpcyB...",
        ... )
        >>> result = await handler.handle(command)
    """

    user_id: UUID
    refresh_token: RefreshToken  # Type alias from domain.types