password-validator-s 1.0.0__py3-none-any.whl

password_validator/__init__.py

@@ -0,0 +1,30 @@
+"""
+Entry point for the password_validator package.
+A configurable password validation library that allows users to define custom rules and
+criteria for password strength and security.
+"""
+from .version import (
+    __title__,
+    __version__,
+    __author__,
+    __description__
+)
+from .engine.validator import PasswordValidator, ValidationResult
+from .strength.scorer import PasswordStrengthScorer
+
+# Package metadata
+VERSION = __version__
+
+__all__ = [
+    # Package Metadata
+    "__version__",
+    "__title__",
+    "__author__",
+    "__description__",
+    "VERSION",
+
+    # Main API
+    "PasswordValidator",
+    "ValidationResult",
+    "PasswordStrengthScorer",
+]

password_validator/config/settings.py

@@ -0,0 +1,135 @@
+"""
+Application-level configuration for password-validator.
+This module provides the top-level package configuration.
+Strength-specific configuration is maintained separately in:
+    password_validator.strength.config.StrengthConfig
+Password policy configuration is maintained here and can be
+loaded from environment variables.
+"""
+from __future__ import annotations
+from dataclasses import dataclass
+
+from ..loaders.env_loader import EnvLoader
+from ..strength.config import StrengthConfig
+from password_validator.constants import *
+
+
+@dataclass(frozen=True, slots=True)
+class PasswordRuleConfig:
+    """
+    Configuration for password policy rules.
+    These settings determine whether a password satisfies the configured password policy.
+    This is separate from password strength scoring.
+    """
+    min_length: int = 8
+    max_length: int = 128
+
+    require_uppercase: bool = True
+    require_lowercase: bool =True
+    require_digit: bool =True
+    require_special: bool = True
+    special_characters: str = "!@#$%^&*()-_=[]{}|/:;'<>?"
+
+    """
+    require_whitespace: bool
+    min_uppercase: int
+    min_lowercase: int
+    min_digit: int
+    min_special: int
+
+    allowed_special: str
+    allow_spaces: bool
+
+    max_repeat: int
+    check_sequential: bool
+    check_common_passwords: bool
+    check_dictionary: bool
+
+    custom_regex: str | None
+    min_entropy: int
+    language: str
+    """
+
+    @classmethod
+    def from_env(cls, env: EnvLoader) -> "PasswordRuleConfig":
+        """
+        Loads the password policy configuration from EnvLoader.
+        :param env: .env file. Defaults to ".env".
+        :return: password policy object
+        """
+
+        return cls(
+            min_length=env.get_int("PASSWORD_MIN_LENGTH", DEFAULT_MIN_LENGTH),
+            max_length=env.get_int("PASSWORD_MAX_LENGTH", DEFAULT_MAX_LENGTH),
+
+            require_uppercase=env.get_bool("PASSWORD_REQUIRE_UPPERCASE", DEFAULT_REQUIRE_UPPERCASE),
+            require_lowercase=env.get_bool("PASSWORD_REQUIRE_LOWERCASE", DEFAULT_REQUIRE_LOWERCASE),
+            require_digit=env.get_bool("PASSWORD_REQUIRE_DIGIT", DEFAULT_REQUIRE_DIGIT),
+            require_special=env.get_bool("PASSWORD_REQUIRE_SPECIAL", DEFAULT_REQUIRE_SPECIAL),
+            special_characters=env.get("PASSWORD_SPECIAL_CHARACTERS", DEFAULT_SPECIAL_CHARACTERS)
+        )
+
+    def validate(self) -> None:
+        """
+        Validate the configuration itself.
+        Raises:
+            ValueError: If the configuration is invalid.
+        :return:
+        """
+        if self.min_length < 1:
+            raise ValueError("PASSWORD_MIN_LENGTH must be greater than 0")
+
+        if self.max_length < self.min_length:
+            raise ValueError("PASSWORD_MAX_LENGTH must be greater than or equal to PASSWORD_MIN_LENGTH")
+
+        if self.require_special and not self.special_characters:
+            raise ValueError("PASSWORD_SPECIAL_CHARACTERS cannot be empty when PASSWORD_REQUIRE_SPECIAL=true")
+
+    @classmethod
+    def defaults(cls) -> "PasswordRuleConfig":
+        """
+        Return the package defaults.
+        Useful for applications that don't use .env.
+        :return:
+        """
+        return cls()
+
+
+@dataclass(slots=True, frozen=True)
+class Settings:
+    """
+    Root configuration object for the password-validator package.
+    This object is the main configuration boundary for the package.
+
+    Environment variables are loaded once and converted into typed configuration objects.
+    """
+    rules: PasswordRuleConfig
+    strength: StrengthConfig
+
+    @classmethod
+    def from_env(cls, env_file: str = ".env") -> "Settings":
+        """
+        Build application settings from environment file.
+        :param env_file: Path to the .env file
+        :return: Fully initialized settings object
+        """
+        env = EnvLoader(env_file)
+        rules = PasswordRuleConfig.from_env(env)
+        rules.validate()
+        strength = StrengthConfig.from_env(env_file)
+
+        return cls(rules=rules, strength=strength)
+
+    @classmethod
+    def defaults(cls) -> "Settings":
+        """
+        Return package defaults without reading an environment file
+        :return:
+        """
+        rules = PasswordRuleConfig()
+        rules.validate()
+
+        return cls(
+            rules=rules,
+            strength=StrengthConfig.defaults()
+        )

password_validator/constants.py

@@ -0,0 +1,55 @@
+"""
+All constants used in the password_validator package are defined here.
+- DEFAULT_SPECIAL_CHARACTERS
+- DEFAULT_BLACKLIST
+- DEFAULT_MIN_LENGTH
+- DEFAULT_ENTROPY
+"""
+# Password defaults
+DEFAULT_MIN_LENGTH = 8
+DEFAULT_MAX_LENGTH = 64
+
+DEFAULT_REQUIRE_UPPERCASE = True
+DEFAULT_REQUIRE_LOWERCASE = True
+DEFAULT_REQUIRE_DIGIT = True
+DEFAULT_REQUIRE_SPECIAL = True
+
+# Character defaults
+DEFAULT_SPECIAL_CHARACTERS = "!@#$%^&*()-_=+[]{}|;:'\",.<>?/`~"
+
+DEFAULT_MIN_UPPERCASE = 1
+DEFAULT_MIN_LOWERCASE = 1
+DEFAULT_MIN_DIGITS = 1
+DEFAULT_MIN_SPECIAL = 1
+
+# Security defaults
+DEFAULT_MAX_REPEAT_COUNT = 3
+DEFAULT_MIN_ENTROPY = 40
+
+# Password policies
+DEFAULT_ALLOW_SPACES = False
+DEFAULT_CHECK_SEQUENTIAL = True
+DEFAULT_CHECK_COMMON_PASSWORDS = True
+DEFAULT_CHECK_DICTIONARY = True
+
+# Regex
+DEFAULT_CUSTOM_REGEX = None
+
+# Language defaults
+DEFAULT_LANGUAGE = "en"
+
+# Common sequences and patterns
+SEQUENTIAL_PATTERNS = [
+    "abcdefghijklmnopqrstuvwxyz",
+    "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
+    "0123456789"
+]
+
+# Common password file
+DEFAULT_COMMON_PASSWORDS_FILE = "resources/common_passwords.txt"
+DEFAULT_DICTIONARY_FILE = "resources/dictionary.txt"
+
+# Error messages
+DEFAULT_ERROR_PREFIX = (
+    "Password validation failed"
+)

password_validator/engine/validator.py

@@ -0,0 +1,168 @@
+"""
+Password validation engine.
+
+The validation engine executes password policy rules and returns a
+structured validation result.
+
+It does not perform password strength analysis. Strength analysis is
+handled by password_validator.strength.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from ..config.settings import PasswordRuleConfig
+from ..models import ValidationResult
+from ..rules.base import Rule, RuleResult
+from ..rules.digits import DigitsRule
+from ..rules.length import LengthRule
+from ..rules.lowercase import LowercaseRule
+from ..rules.special import SpecialCharacterRule
+from ..rules.uppercase import UppercaseRule
+
+
+class PasswordValidator:
+    """
+    Password policy validation engine.
+    """
+
+    def __init__(
+        self,
+        config: PasswordRuleConfig | None = None,
+        rules: Sequence[Rule] | None = None,
+    ) -> None:
+        """
+        Initialize the password validator.
+
+        Args:
+            config: Password policy configuration.
+            rules: Optional custom rule collection.
+
+        When rules are supplied, they completely replace the default
+        rule collection.
+        """
+
+        self.config = config or PasswordRuleConfig()
+
+        if hasattr(self.config, "validate"):
+            self.config.validate()
+
+        if rules is not None:
+            self.rules = list(rules)
+        else:
+            self.rules = self._build_default_rules()
+
+    def _build_default_rules(self) -> list[Rule]:
+        """Build the default password policy rule collection."""
+
+        rules: list[Rule] = []
+
+        rules.append(
+            LengthRule(
+                min_length=self.config.min_length,
+                max_length=self.config.max_length,
+            )
+        )
+
+        if self.config.require_uppercase:
+            rules.append(UppercaseRule())
+
+        if self.config.require_lowercase:
+            rules.append(LowercaseRule())
+
+        if self.config.require_digit:
+            rules.append(DigitsRule())
+
+        if self.config.require_special:
+            rules.append(
+                SpecialCharacterRule(
+                    special_characters=self.config.special_characters,
+                )
+            )
+
+        return rules
+
+    def validate(self, password: str) -> ValidationResult:
+        """
+        Validate a password against all configured rules.
+
+        Args:
+            password: Password to validate.
+
+        Returns:
+            ValidationResult containing the overall status and individual
+            rule results.
+
+        Raises:
+            TypeError: If password is not a string.
+        """
+
+        if not isinstance(password, str):
+            raise TypeError("Password must be a string")
+
+        rule_results: list[RuleResult] = []
+        passed: list[str] = []
+        failed: list[str] = []
+        errors: list[str] = []
+
+        for rule in self.rules:
+            result = rule.validate(password)
+
+            rule_results.append(result)
+
+            rule_name = self._rule_name(rule, result)
+
+            if result.passed:
+                passed.append(rule_name)
+            else:
+                failed.append(rule_name)
+
+                if result.message:
+                    errors.append(result.message)
+
+        return ValidationResult(
+            valid=not failed,
+            passed=tuple(passed),
+            failed=tuple(failed),
+            errors=tuple(errors),
+            rule_results=tuple(rule_results),
+        )
+
+    @staticmethod
+    def _rule_name(
+        rule: Rule,
+        result: RuleResult,
+    ) -> str:
+        """
+        Resolve a stable rule name.
+
+        Resolution order:
+
+        1. RuleResult.rule_name
+        2. rule.name
+        3. Rule class name with the "Rule" suffix removed
+        """
+
+        result_name = getattr(result, "rule_name", None)
+
+        if result_name:
+            return str(result_name)
+
+        rule_name = getattr(rule, "name", None)
+
+        if rule_name:
+            return str(rule_name)
+
+        class_name = rule.__class__.__name__
+
+        if class_name.endswith("Rule"):
+            class_name = class_name[:-4]
+
+        return class_name.lower()
+
+
+__all__ = [
+    "PasswordValidator",
+    "ValidationResult",
+]

password_validator/enums.py

@@ -0,0 +1,72 @@
+"""
+Enums used in the password_validator package are defined here.
+- Strength
+- RuleType
+- ErrorCode
+"""
+from enum import Enum
+
+
+class Rule(str, Enum):
+    """
+    Supported validation rule types for password validation.
+    """
+
+    LENGTH = "length"
+    UPPERCASE = "uppercase"
+    LOWERCASE = "lowercase"
+    DIGIT = "digit"
+    SPECIAL = "special"
+    WHITESPACE = "whitespace"
+    REPEATED = "repeated"
+    SEQUENTIAL = "sequential"
+    BLACKLIST = "blacklist"
+    COMMON_PASSWORDS = "common_passwords"
+    DICTIONARY = "dictionary"
+    REGEX = "regex"
+    USERNAME = "username"
+    ENTROPY = "entropy"
+    HISTORY = "history"
+
+
+class StrengthLevel(str, Enum):
+    """
+    Supported strength levels for password validation.
+    """
+    VERY_WEAK = "very_weak"
+    WEAK = "weak"
+    FAIR = "fair"
+    GOOD = "good"
+    STRONG = "strong"
+    VERY_STRONG = "very_strong"
+
+
+class ErrorCode(str, Enum):
+    """
+    Supported error codes for password validation.
+    """
+    TOO_SHORT = "PASSWORD_TOO_SHORT"
+    TOO_LONG = "PASSWORD_TOO_LONG"
+    MISSING_UPPERCASE = "PASSWORD_MISSING_UPPERCASE"
+    MISSING_LOWERCASE = "PASSWORD_MISSING_LOWERCASE"
+    MISSING_DIGIT = "PASSWORD_MISSING_DIGIT"
+    MISSING_SPECIAL = "PASSWORD_MISSING_SPECIAL"
+    CONTAINS_SPACE = "PASSWORD_CONTAINS_SPACE"
+    TOO_MANY_REPEATS = "PASSWORD_TOO_MANY_REPEATS"
+    SEQUENTIAL_PATTERN = "PASSWORD_SEQUENTIAL_PATTERN"
+    COMMON_PASSWORD = "PASSWORD_COMMON_PASSWORD"
+    DICTIONARY_WORD = "PASSWORD_DICTIONARY_WORD"
+    INVALID_REGEX = "PASSWORD_INVALID_REGEX"
+    USERNAME_IN_PASSWORD = "USERNAME_IN_PASSWORD"
+    LOW_ENTROPY = "PASSWORD_LOW_ENTROPY"
+    PASSWORD_HISTORY_VIOLATION = "PASSWORD_HISTORY_VIOLATION"
+    BLACKLISTED_PASSWORD = "BLACKLISTED_PASSWORD"
+
+
+class ValidationMode(str, Enum):
+    """
+    Supported validation modes for password validation.
+    """
+    STRICT = "strict"
+    NORMAL = "normal"
+    LENIENT = "lenient"

password_validator/exceptions.py

@@ -0,0 +1,50 @@
+"""
+All exceptions used in the password_validator package are defined here.
+- PasswordValidationError
+- ConfigurationError
+- RuleConfigurationError
+"""
+
+
+class PasswordValidatorError(Exception):
+    """Raised when a password fails validation."""
+    pass
+
+
+class ConfigurationError(PasswordValidatorError):
+    """Raised when there is an issue with the configuration."""
+    pass
+
+
+class MissingConfigurationError(ConfigurationError):
+    """Raised when a required configuration is missing."""
+    pass
+
+
+class RuleConfigurationError(ConfigurationError):
+    """Raised when there is an issue with a specific rule's configuration."""
+    pass
+
+
+class InvalidConfigurationValue(PasswordValidatorError):
+    """Raised when a configuration value is invalid."""
+    """
+        Raised when an environment/configuration value
+        has an invalid type or format.
+        """
+
+    def __init__(
+            self,
+            key: str,
+            value: object,
+            expected: str,
+    ) -> None:
+        super().__init__(
+            f"Invalid configuration value for "
+            f"'{key}': {value!r}. "
+            f"Expected {expected}."
+        )
+
+        self.key = key
+        self.value = value
+        self.expected = expected

password_validator/loaders/__init__.py

@@ -0,0 +1,10 @@
+"""
+Configuration loaders
+"""
+
+from .env_loader import EnvLoader
+
+
+__all__ = [
+    "EnvLoader"
+]

password_validator/loaders/env_loader.py

@@ -0,0 +1,149 @@
+"""
+Environment configuration loader.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from ..exceptions import InvalidConfigurationValue
+
+
+class EnvLoader:
+    """
+    Loads and converts environment variables into a configuration dictionary.
+    """
+    def __init__(self, env_file: str | None = ".env") -> None:
+        """
+        Initializes the EnvLoader.
+
+        :param env_file: Path to the .env file. Defaults to ".env".
+        """
+        self._values: dict[str, str] = {}
+
+        if env_file:
+            self._load_env_file(env_file)
+
+        self._load_environment()
+
+    def _load_env_file(self, env_file: str) -> None:
+        path = Path(env_file)
+
+        if not path.exists():
+            return
+
+        for raw_line in path.read_text(encoding="utf-8").splitlines():
+            line = raw_line.strip()
+
+            if not line:
+                continue
+            if line.startswith("#"):
+                continue
+            if "=" not in line:
+                continue
+
+            key, value = line.split("=", 1)
+
+            key = key.strip()
+            value = value.strip()
+
+            if (len(value) >= 2 and
+                    value[0] == value[-1] and
+                    value[0] in {'"', "'"}):
+                value = value[1:-1]
+
+            self._values[key] = value
+
+    def _load_environment(self) -> None:
+        """
+        Environment variables override values from .env
+        :return:
+        """
+        for key, value in os.environ.items():
+            self._values[key] = value
+
+    def get(self, key: str, default: str = None) -> str:
+        """
+        Retrieves the value of an environment variable.
+
+        :param key: The environment variable key.
+        :param default: The default value if the key is not found.
+        :return: The value of the environment variable or the default.
+        """
+        return self._values.get(key, default)
+
+    def get_bool(self, key: str, default: bool = False) -> bool:
+        """
+        Retrieves the value of an environment variable as a boolean.
+
+        :param key: The environment variable key.
+        :param default: The default boolean value if the key is not found.
+        :return: The boolean value of the environment variable or the default.
+        """
+        value = self.get(key)
+
+        if value is None:
+            return default
+
+        normalized = value.strip().lower()
+
+        if normalized in ['true', '1', 'yes', 'y', "on"]:
+            return True
+
+        if value.lower() in ['false', '0', 'no', 'n', "off"]:
+            return False
+
+        raise InvalidConfigurationValue(f"Invalid boolean value for {key}: {value}")
+
+    def get_int(self, key: str, default: int = 0) -> int:
+        """
+        Retrieves the value of an environment variable as an integer.
+
+        :param key: The environment variable key.
+        :param default: The default integer value if the key is not found.
+        :return: The integer value of the environment variable or the default.
+        """
+        value = self.get(key)
+
+        if value is None:
+            return default
+
+        try:
+            return int(value)
+        except ValueError:
+            raise InvalidConfigurationValue(key, value, "integer") from None
+
+    def get_list(self, key: str, default: list[str] = None, delimiter: str = ',') -> list[str]:
+        """
+        Retrieves the value of an environment variable as a list.
+
+        :param key: The environment variable key.
+        :param default: The default list value if the key is not found.
+        :param delimiter: The delimiter used to split the string into a list. Defaults to ','.
+        :return: The list value of the environment variable or the default.
+        """
+        value = self.get(key, default)
+
+        if isinstance(value, list):
+            return value
+
+        if isinstance(value, str):
+            return [item.strip() for item in value.split(delimiter) if item.strip()]
+
+        raise InvalidConfigurationValue(f"{key}: {value} must be a list or a string")
+
+    def get_float(self, key: str, default: float = 0.0) -> float:
+        """
+        Retrieves the value of an environment variable as a float.
+
+        :param key: The environment variable key.
+        :param default: The default float value if the key is not found.
+        :return: The float value of the environment variable or the default.
+        """
+        value = self.get(key)
+        if value is None:
+            return default
+
+        try:
+            return float(value)
+        except (TypeError, ValueError) as exc:
+            raise InvalidConfigurationValue(key, value, "float") from None