fortifypass-validator 0.2.0__py3-none-any.whl

fortifypass_validator-0.2.0.dist-info/METADATA

@@ -0,0 +1,332 @@
+Metadata-Version: 2.4
+Name: fortifypass-validator
+Version: 0.2.0
+Summary: A modern password validation library powered by zxcvbn with policy enforcement and CLI support.
+Author: Botshelo Mere
+License: MIT
+Project-URL: Homepage, https://github.com/botshelo-mere/password-validator
+Project-URL: Repository, https://github.com/botshelo-mere/password-validator
+Project-URL: Issues, https://github.com/botshelo-mere/password-validator/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 4 - Beta
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: zxcvbn>=4.4.28
+Requires-Dist: colorama>=0.4.6
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
+Requires-Dist: jsonschema>=4.0; extra == "dev"
+Dynamic: license-file
+
+# password-validator
+
+[![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://python.org)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE.md)
+[![Development Status](https://img.shields.io/badge/status-beta-yellow.svg)](https://github.com/botshelo-mere/password-validator)
+[![zxcvbn powered](https://img.shields.io/badge/strength-zxcvbn%20powered-purple.svg)](https://github.com/dwolfhub/zxcvbn-python)
+
+A modern, policy-driven password validation library for Python — powered by
+[zxcvbn](https://github.com/dwolfhub/zxcvbn-python) for realistic strength
+estimation and fully configurable rule enforcement with a built-in CLI.
+
+---
+
+## Features
+
+- **Policy validation** — enforce length, character classes, spaces, and banned words
+- **Realistic strength scoring** — zxcvbn rates passwords 0–4 with human-readable labels
+- **Unified `evaluate()` API** — combines validation + strength in one call
+- **CLI interface** — interactive (colored) and non-interactive (JSON pipe) modes
+- **Resilient design** — defensive constructor, graceful zxcvbn exception handling
+- **Thread-safe** — safe to share a single `PasswordValidator` across threads
+- **Typed** — full `typing` annotations throughout
+
+---
+
+## Installation
+
+### Using uv (recommended)
+
+```bash
+git clone https://github.com/botshelo-mere/password-validator.git
+cd password-validator
+
+# Create virtual environment and install dependencies
+uv sync
+```
+
+### Using pip
+
+```bash
+pip install password-validator
+```
+
+### Dev / Testing
+
+```bash
+# Install with development extras (pytest, pytest-cov, pytest-benchmark, jsonschema)
+uv sync --extra dev
+# or
+pip install "password-validator[dev]"
+```
+
+---
+
+## Quick Start
+
+### Library Usage
+
+```python
+from password_validator import PasswordValidator
+
+# Default policy: 12–64 chars, upper, lower, digit, special required
+validator = PasswordValidator()
+
+# --- validate() → (bool, list[str]) ---
+valid, errors = validator.validate("Str0ngP@ssw0rd!")
+print(valid)   # True
+print(errors)  # []
+
+valid, errors = validator.validate("weak")
+print(valid)   # False
+print(errors)  # ['Password must be at least 12 characters long', ...]
+
+# --- estimate_strength() → dict ---
+strength = validator.estimate_strength("Str0ngP@ssw0rd!")
+print(strength["score"])    # 3
+print(strength["label"])    # 'Strong'
+print(strength["feedback"]) # []
+
+# --- evaluate() — combines both in one call ---
+result = validator.evaluate("Str0ngP@ssw0rd!")
+# {
+#   "valid": True,
+#   "errors": [],
+#   "score": 3,
+#   "label": "Strong",
+#   "feedback": []
+# }
+```
+
+### Custom Policy
+
+```python
+validator = PasswordValidator(
+    min_length=8,
+    max_length=32,
+    require_uppercase=True,
+    require_lowercase=True,
+    require_digit=True,
+    require_special=True,
+    special_chars="!@#$%",
+    allow_spaces=False,
+    banned_words=["password", "admin", "secret"],
+)
+
+valid, errors = validator.validate("Admin123!")
+# valid=False → "Contains a banned word"
+```
+
+---
+
+## Configuration Reference
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `min_length` | `int` | `12` | Minimum password length (must be ≥ 1) |
+| `max_length` | `int` | `64` | Maximum password length (must be ≥ `min_length`) |
+| `require_uppercase` | `bool` | `True` | Require at least one uppercase letter |
+| `require_lowercase` | `bool` | `True` | Require at least one lowercase letter |
+| `require_digit` | `bool` | `True` | Require at least one digit |
+| `require_special` | `bool` | `True` | Require at least one special character |
+| `special_chars` | `str` | `"!@#$%^&*"` | Set of accepted special characters |
+| `allow_spaces` | `bool` | `False` | Whether whitespace is permitted |
+| `banned_words` | `list[str] \| None` | `None` | Case-insensitive list of forbidden words |
+
+> `ValueError` is raised on construction if `min_length <= 0` or `max_length < min_length`.
+
+---
+
+## API Reference
+
+### `PasswordValidator.validate(pwd: str) → Tuple[bool, List[str]]`
+
+Runs all configured policy rules against the password.
+
+- Returns `(True, [])` if all rules pass.
+- Returns `(False, [<error messages>])` if any rule fails.
+- Raises `ValueError` if `pwd` is not a `str`.
+
+### `PasswordValidator.estimate_strength(pwd: str) → Dict[str, Any]`
+
+Uses zxcvbn to estimate password strength.
+
+- Passwords longer than 72 characters are truncated before scoring (zxcvbn limit).
+- Always returns a dictionary — never raises.
+
+| Key | Type | Description |
+|---|---|---|
+| `score` | `int` | 0 (Very Weak) → 4 (Very Strong) |
+| `label` | `str` | Human-readable label |
+| `feedback` | `list[str]` | Warnings and suggestions from zxcvbn |
+
+### `PasswordValidator.evaluate(pwd: str) → Dict[str, Any]`
+
+Combines `validate()` and `estimate_strength()` into a single result.
+
+| Key | Type | Description |
+|---|---|---|
+| `valid` | `bool` | Whether all policy rules passed |
+| `errors` | `list[str]` | Policy error messages |
+| `score` | `int` | zxcvbn score 0–4 |
+| `label` | `str` | Strength label |
+| `feedback` | `list[str]` | zxcvbn feedback |
+
+---
+
+## CLI Usage
+
+### Interactive Mode
+
+```bash
+uv run password-validator
+```
+
+```
+Password Validator v0.2.0 (zxcvbn powered)
+Type .exit() to quit
+
+Enter password: ········
+✓ Valid password
+
+Strength: Strong
+  • Use a longer keyboard pattern with more turns
+```
+
+- Type `.exit()` to quit.
+- Press `Ctrl+C` to interrupt.
+- Password input is hidden (no echo).
+
+### Non-Interactive / Pipe Mode
+
+Pipe a password directly — output is JSON, exit code is `0` for score ≥ 3, `1` otherwise:
+
+```bash
+echo "Str0ngP@ssw0rd!" | password-validator
+```
+
+```json
+{
+  "valid": true,
+  "errors": [],
+  "score": 3,
+  "label": "Strong",
+  "feedback": []
+}
+```
+
+Ideal for shell scripts and CI pipelines:
+
+```bash
+echo "$PASSWORD" | password-validator && echo "Password accepted" || echo "Password rejected"
+```
+
+---
+
+## Project Structure
+
+```
+password-validator/
+├── pyproject.toml                  # Project configuration
+├── .gitignore
+├── README.md
+├── LICENSE.md
+├── src/
+│   └── password_validator/
+│       ├── __init__.py             # Public API  (__version__, __all__)
+│       ├── validator.py            # Core validation + zxcvbn strength logic
+│       └── cli.py                  # CLI interface (colorama)
+└── tests/
+    ├── __init__.py
+    ├── test_validator.py           # Validator unit tests
+    ├── test_cli.py                 # CLI unit tests
+    └── test_performance_benchmarks.py  # pytest-benchmark performance tests
+```
+
+---
+
+## Development
+
+### Running Tests
+
+```bash
+# All tests
+uv run pytest
+
+# With coverage report
+uv run pytest --cov=password_validator --cov-report=term-missing
+
+# Verbose output
+uv run pytest -v
+```
+
+### Running Benchmarks
+
+```bash
+uv run pytest tests/test_performance_benchmarks.py --benchmark-only
+```
+
+### Code Coverage
+
+```bash
+uv run pytest --cov=password_validator --cov-branch --cov-report=html
+# Open htmlcov/index.html in your browser
+```
+
+---
+
+## Strength Score Labels
+
+| Score | Label | Meaning |
+|---|---|---|
+| 0 | Very Weak | Trivially crackable |
+| 1 | Weak | Easy to crack |
+| 2 | Moderate | Some resistance |
+| 3 | Strong | Good security |
+| 4 | Very Strong | Excellent security |
+
+Scoring is provided by [zxcvbn](https://github.com/dwolfhub/zxcvbn-python), which
+models real-world cracking strategies (dictionary attacks, keyboard patterns, etc.)
+rather than simple character-class rules.
+
+---
+
+## Version History
+
+| Version | Changes |
+|---|---|
+| **v0.2.0** | Added zxcvbn strength estimation, `evaluate()` API, banned words, full type annotations, colorama CLI, pipe mode, comprehensive test suite |
+| **v0.1.1** | Infrastructure improvements, packaging fixes |
+| **v0.1.0** | Initial public release |
+
+---
+
+## License
+
+This project is licensed under the MIT License — see [LICENSE.md](LICENSE.md) for details.
+
+---
+
+## Author
+
+**Botshelo Mere**
+GitHub: [botshelo-mere](https://github.com/botshelo-mere)

fortifypass_validator-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+fortifypass_validator-0.2.0.dist-info/licenses/LICENSE.md,sha256=MS2TipvClIKHVM1sW01QXRGs9N3kegc6OrLEbsnFHBI,1089
+password_validator/__init__.py,sha256=I3JRtOw3YyOj0LmLkr4mVBKQ9WxrzxqXhWqXXD5jFtw,96
+password_validator/cli.py,sha256=1G8uWs1IMKm2VjYhMbBUcQ6r8t0ULJFQkmyikl698bw,1911
+password_validator/validator.py,sha256=GJZfMrgAxo8dlhFrjzIQ6Av5c5amAos9MoGe5imUnMo,4440
+fortifypass_validator-0.2.0.dist-info/METADATA,sha256=G4TOwJk9sgXlO9tE0laLgmr5s_bb19YsLIjDdiLyQ9w,9581
+fortifypass_validator-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+fortifypass_validator-0.2.0.dist-info/entry_points.txt,sha256=srK4kKaMMUZBDNZklZxiOlh30kMTHubt7SK951cBbN8,67
+fortifypass_validator-0.2.0.dist-info/top_level.txt,sha256=lXxc73p4NxqiirJMlyCfZYV6_e9bW2G32Jeh0xDoc1E,19
+fortifypass_validator-0.2.0.dist-info/RECORD,,

fortifypass_validator-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fortifypass_validator-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+password-validator = password_validator.cli:main

fortifypass_validator-0.2.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Botshelo Mere
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fortifypass_validator-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+password_validator

password_validator/__init__.py

@@ -0,0 +1,4 @@
+from .validator import PasswordValidator
+
+__version__ = "0.2.0"
+__all__ = ["PasswordValidator"]

password_validator/cli.py

@@ -0,0 +1,65 @@
+import sys
+import json
+import getpass
+from colorama import init, Fore, Style
+from password_validator.validator import PasswordValidator, MAX_ZXCVBN_LEN
+
+# Initialize Colorama
+init(autoreset=True)
+
+def main():
+    validator = PasswordValidator()
+
+    # Handle piped input (non-interactive)
+    if not sys.stdin.isatty():
+        pwd = sys.stdin.read().strip()
+        
+        result = validator.evaluate(pwd)
+        print(json.dumps(result, indent=2))
+        sys.exit(0 if result["score"] >= 3 else 1)
+
+    # Interactive mode
+    print(Fore.CYAN + Style.BRIGHT + "Password Validator v0.2.0 (zxcvbn powered)")
+    print(Fore.CYAN + "Type .exit() to quit\n")
+
+    while True:
+        try:
+            pwd = getpass.getpass("Enter password: ")
+        except KeyboardInterrupt:
+            print("\n" + Fore.YELLOW + "Program interrupted by user.")
+            return
+        except EOFError:
+            print("\n" + Fore.YELLOW + "Input stream closed.")
+            return
+
+        if pwd == ".exit()":
+            print(Fore.YELLOW + "Goodbye.")
+            return
+
+        result = validator.evaluate(pwd)
+
+        # Validation output
+        if result["valid"]:
+            print(Fore.GREEN + Style.BRIGHT + "✓ Valid password")
+        else:
+            print(Fore.RED + Style.BRIGHT + "✗ Invalid password")
+            for err in result["errors"]:
+                print(Fore.RED + Style.BRIGHT + f"  • {err}")
+
+        # Strength output
+        score_color = {
+            0: Fore.RED + Style.BRIGHT,
+            1: Fore.RED + Style.BRIGHT,
+            2: Fore.YELLOW + Style.BRIGHT,
+            3: Fore.GREEN + Style.BRIGHT,
+            4: Fore.GREEN + Style.BRIGHT,
+        }[result["score"]]
+
+        print(f"\n{score_color }Strength: {result['label']}")
+        for msg in result["feedback"]:
+            print(Fore.YELLOW + f"  • {msg}")
+
+        print()
+
+if __name__ == "__main__":
+    main()

password_validator/validator.py

@@ -0,0 +1,124 @@
+import logging
+from typing import List, Tuple, Dict, Any, Optional
+from zxcvbn import zxcvbn
+
+logger = logging.getLogger(__name__)
+
+MAX_ZXCVBN_LEN = 72
+
+class PasswordValidator:
+ 
+    def __init__(
+        self,
+        min_length: int = 12,
+        max_length: int = 64,
+        require_uppercase: bool = True,
+        require_lowercase: bool = True,
+        require_digit: bool = True,
+        require_special: bool = True,
+        special_chars: str = "!@#$%^&*",
+        allow_spaces: bool = False,
+        banned_words: Optional[List[str]] = None,
+    ):
+        
+        # Defensive Config Validation
+        if min_length <= 0 or max_length < min_length:
+            raise ValueError("Invalid length constraints")
+
+        self.min_length = min_length
+        self.max_length = max_length
+        self.require_uppercase = require_uppercase
+        self.require_lowercase = require_lowercase
+        self.require_digit = require_digit
+        self.require_special = require_special
+        self.special_chars = special_chars
+        self.allow_spaces = allow_spaces
+        self.banned_words = [w.lower() for w in (banned_words or [])]
+
+    # ===== Validation =====
+    def validate(self, pwd: str) -> Tuple[bool, List[str]]:
+        errors: List[str] = []
+
+        if not isinstance(pwd, str):
+            raise ValueError("Password must be a string")
+
+        if not pwd:
+            return False, ["Password cannot be empty"]
+
+        if not self.allow_spaces and any(c.isspace() for c in pwd):
+            errors.append("Password must not contain spaces")
+
+        if len(pwd) < self.min_length:
+            errors.append(f"Password must be at least {self.min_length} characters long")
+
+        if len(pwd) > self.max_length:
+            errors.append(f"Password cannot exceed {self.max_length} characters")
+
+        if self.require_uppercase and not any(c.isupper() for c in pwd):
+            errors.append("Missing uppercase letter")
+
+        if self.require_lowercase and not any(c.islower() for c in pwd):
+            errors.append("Missing lowercase letter")
+
+        if self.require_digit and not any(c.isdigit() for c in pwd):
+            errors.append("Missing digit")
+
+        if self.require_special and not any(c in self.special_chars for c in pwd):
+            errors.append("Missing special character")
+
+        if self._contains_banned_word(pwd):
+            errors.append("Contains a banned word")
+
+        return len(errors) == 0, errors
+
+    def _contains_banned_word(self, pwd: str) -> bool:
+        pwd_lower = pwd.lower()
+        return any(word in pwd_lower for word in self.banned_words)
+
+    # ===== Strength (zxcvbn) =====    
+    def estimate_strength(self, pwd: str) -> Dict[str, Any]:
+        """
+        Uses zxcvbn for realistic password strength estimation.
+        Truncates passwords >72 characters to prevent ValueError.
+        Always returns a dictionary, even if zxcvbn misbehaves.
+        """
+        if not isinstance(pwd, str) or not pwd:
+            return {"score": 0, "label": "Very Weak", "feedback": ["Empty or invalid password"]}
+
+        truncated_pwd = pwd[:MAX_ZXCVBN_LEN]
+
+        try:
+            result = zxcvbn(truncated_pwd)
+            
+            # Defensive: ensure result is a dict
+            if not isinstance(result, dict):
+                raise ValueError(f"Unexpected zxcvbn result type: {type(result)}")
+        except Exception as e:
+            return {"score": 0, "label": "Very Weak", "feedback": [f"Strength calculation error: {str(e)}"]}
+
+        labels = ["Very Weak", "Weak", "Moderate", "Strong", "Very Strong"]
+        score = result.get("score", 0) if isinstance(result, dict) else 0
+
+        feedback = []
+        fb_dict = result.get("feedback", {}) if isinstance(result, dict) else {}
+        warning = fb_dict.get("warning")
+        suggestions = fb_dict.get("suggestions", [])
+
+        if warning:
+            feedback.append(warning)
+        feedback.extend(suggestions)
+
+        return {"score": score, "label": labels[score], "feedback": feedback}
+    
+    # ===== Public API =====
+    def evaluate(self, pwd: str) -> Dict[str, Any]:
+        valid, errors = self.validate(pwd)
+        strength = self.estimate_strength(pwd)
+        
+        return {
+            "valid": valid,
+            "errors": errors,
+            "score": strength["score"],
+            "label": strength["label"],
+            "feedback": strength["feedback"]
+            }