mud_server.api.password_policy

Password policy enforcement for secure authentication.

This module implements a comprehensive password policy that balances security with usability. The policy is based on NIST SP 800-63B guidelines and industry best practices, while avoiding overly restrictive rules that lead users to create predictable passwords.

Policy Philosophy:

Modern password security research (NIST SP 800-63B, 2017) recommends: - Length over complexity (longer passwords are more secure) - Blocking common/compromised passwords - Avoiding arbitrary complexity rules that frustrate users - Not requiring periodic password changes (unless compromise suspected)

This implementation follows these principles while providing configurable enforcement levels for different deployment scenarios.

Policy Levels:

BASIC: Minimum viable security (8 chars, basic checks)
STANDARD: Recommended for most deployments (12 chars, common password check)
STRICT: High-security environments (16 chars, all checks enabled)

Usage:

from mud_server.api.password_policy import (: validate_password_strength, PasswordPolicy, PolicyLevel,

)

# Using default (STANDARD) policy result = validate_password_strength(“my_password_123”) if not result.is_valid:

print(result.errors)

# Using a specific policy level result = validate_password_strength(“password”, level=PolicyLevel.STRICT)

# Custom policy policy = PasswordPolicy(

min_length=14, require_uppercase=True, require_lowercase=True, require_digit=True, require_special=True, check_common_passwords=True,

) result = policy.validate(“my_password”)

Security Considerations:

Common password list is checked in constant time to prevent timing attacks
Password strength feedback helps users create better passwords
All validation errors are returned at once (not fail-fast) for better UX
Entropy estimation provides a security score for password meters

Attributes

`COMMON_PASSWORDS`
`POLICY_BASIC`
`POLICY_STANDARD`
`POLICY_STRICT`

Classes

`PolicyLevel`	Predefined password policy levels for different security requirements.
`ValidationResult`	Result of password validation containing success status and feedback.
`PasswordPolicy`	Configurable password policy with comprehensive validation rules.

Functions

`validate_password_strength`(password[, level])	Validate password strength using a predefined policy level.
`get_policy`([level])	Get the PasswordPolicy instance for a given level.
`get_password_requirements`([level])	Get a human-readable description of password requirements.

Module Contents

mud_server.api.password_policy.COMMON_PASSWORDS: frozenset[str]

class mud_server.api.password_policy.PolicyLevel(*args, **kwds)[source]

Bases: enum.Enum

Predefined password policy levels for different security requirements.

Each level provides a balance between security and usability appropriate for different deployment scenarios.

BASIC: Minimum viable security. Suitable for development/testing environments or low-risk internal applications. - 8 character minimum - No complexity requirements - Basic common password check

STANDARD: Recommended for most production deployments. Provides strong security without being overly restrictive. - 12 character minimum (NIST recommended) - Encourages but doesn’t require complexity - Comprehensive common password check - Sequential/repeated character detection

STRICT: For high-security environments handling sensitive data. - 16 character minimum - Requires uppercase, lowercase, digit, and special char - All security checks enabled - Maximum entropy requirements

BASIC = 'basic'

STANDARD = 'standard'

STRICT = 'strict'

class mud_server.api.password_policy.ValidationResult[source]

Result of password validation containing success status and feedback.

This class provides detailed feedback about password validation, including all errors encountered and suggestions for improvement. All errors are collected (not fail-fast) to provide complete feedback to users.

is_valid: True if the password meets all policy requirements.

errors: List of human-readable error messages describing each validation failure. Empty if password is valid.

warnings: List of suggestions for improving password strength. May be present even for valid passwords.

score: Estimated password strength score from 0-100. Higher is better. Based on length, character diversity, and entropy estimation.

entropy_bits: Estimated entropy in bits. Passwords with 60+ bits are considered strong, 80+ bits are excellent.

Example

>>> result = validate_password_strength("weak")
>>> result.is_valid
False
>>> result.errors
['Password must be at least 12 characters long (currently 4)']
>>> result.score
15

is_valid: bool

errors: list[str] = []

warnings: list[str] = []

score: int = 0

entropy_bits: float = 0.0

class mud_server.api.password_policy.PasswordPolicy[source]

Configurable password policy with comprehensive validation rules.

This class encapsulates all password policy settings and provides validation methods. It can be configured for different security levels or customized for specific requirements.

min_length: Minimum password length. NIST recommends 8 minimum, but 12+ provides significantly better security.

max_length: Maximum password length. Set high (128) to allow passphrases. Bcrypt has a 72-byte limit internally.

require_uppercase: Require at least one uppercase letter (A-Z).

require_lowercase: Require at least one lowercase letter (a-z).

require_digit: Require at least one digit (0-9).

require_special: Require at least one special character.

special_characters: Set of characters considered “special”.

check_common_passwords: Check against known common passwords.

check_sequential: Detect sequential characters (abc, 123).

check_repeated: Detect repeated characters (aaa, 111).

max_repeated: Maximum allowed consecutive repeated characters.

Example

>>> policy = PasswordPolicy(min_length=14, require_special=True)
>>> result = policy.validate("MySecurePass123!")
>>> result.is_valid
True

min_length: int = 12

max_length: int = 128

require_uppercase: bool = False

require_lowercase: bool = False

require_digit: bool = False

require_special: bool = False

special_characters: str = '!@#$%^&*()_+-=[]{}|;\':",./<>?`~'

check_common_passwords: bool = True

check_sequential: bool = True

check_repeated: bool = True

max_repeated: int = 3

validate(password)[source]

Validate a password against this policy.

Performs all configured validation checks and returns a comprehensive result with all errors, warnings, and a strength score. Validation is not fail-fast - all checks are performed to provide complete feedback.

Parameters:

password (str) – The password string to validate. Should be the raw password before hashing.

Returns:

is_valid: True if all requirements are met
errors: List of validation failure messages
warnings: List of improvement suggestions
score: Strength score 0-100
entropy_bits: Estimated entropy

Return type:

ValidationResult containing

Example

>>> policy = PasswordPolicy()
>>> result = policy.validate("short")
>>> result.is_valid
False
>>> "at least 12 characters" in result.errors[0]
True

mud_server.api.password_policy.POLICY_BASIC

mud_server.api.password_policy.POLICY_STANDARD

mud_server.api.password_policy.POLICY_STRICT

mud_server.api.password_policy.validate_password_strength(password, level=PolicyLevel.STANDARD)[source]

Validate password strength using a predefined policy level.

This is the primary function for password validation. It uses one of the predefined policy levels (BASIC, STANDARD, or STRICT) to validate the password and return comprehensive feedback.

Parameters:

password (str) – The password to validate. Should be the raw password before any hashing.
level (PolicyLevel) – Security level to enforce. Defaults to STANDARD which is appropriate for most production deployments.

Returns:

ValidationResult containing validation status, errors, warnings, strength score, and entropy estimate.

Return type:

ValidationResult

Example

>>> result = validate_password_strength("MyStr0ng!Pass#2024")
>>> result.is_valid
True
>>> result.score
85

>>> result = validate_password_strength("weak", level=PolicyLevel.STRICT)
>>> result.is_valid
False
>>> len(result.errors) > 0
True