pwned-passwords 1.0.0

Author: le717

.vscode/settings.json

@@ -0,0 +1,17 @@
+{
+  "python.testing.unittestArgs": [
+    "-v",
+    "-s",
+    "./tests",
+    "-p",
+    "test_*.py"
+  ],
+  "python.testing.pytestEnabled": false,
+  "python.testing.unittestEnabled": true,
+  "[python]": {
+    "editor.defaultFormatter": "charliermarsh.ruff"
+  },
+  "[toml]": {
+    "editor.formatOnSave": true
+  }
+}

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Caleb
+
+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.

README.md

@@ -0,0 +1,43 @@
+# pwned-passwords
+> Pwned Passwords API wrapper
+
+## Purpose
+This project provides a simple Python API around the
+[Pwned Passwords API](https://haveibeenpwned.com/API/v3#PwnedPasswords).
+
+## Usage
+```py
+import pwned_passwords
+
+
+# Check a password for pwned-ness
+# password: bytes | str
+result: pwned_passwords.PwnedResults = pwned_passwords.check("password")
+
+# Check the results
+print(result.is_pwned)  # bool
+print(result.times_pwned)  # int
+
+# options: pwned_passwords.PwnedOptions | None
+result: pwned_passwords.PwnedResults = pwned_passwords.check(
+    "password",
+    options=pwned_passwords.PwnedOptions(
+        add_padding=True,  # Pad the API response with empty records
+        mode="ntlm",  # Get NTLM hashes instead of SHA-1
+        get_hashes=True,  # By default, the response hashes are not provided
+    ),
+)
+
+# Print all of the hashes
+print(result.hashes)  # list[pwned_passwords.PwnedHash]
+```
+
+**Note**: NTLM hash support is dependent on platform support, with fallback support provided by [pyspnego](https://pypi.org/project/pyspnego/). It is recommended to stick with the SHA-1 hash default.
+
+
+## License
+Pwned Passwords API, created and maintained at [Have I Been Pwned](https://haveibeenpwned.com/).
+
+Have I Been Pwned is not affiliated with nor endorses this project.
+
+2023 [MIT](LICENSE)

__pycache__/pwned_passwords.cpython-311.pyc

@@ -0,0 +1,32 @@
+from . import _utils
+
+# Re-export the structs for easier library consumption
+from ._structs import PwnedHash, PwnedOptions, PwnedResults
+
+
+__all__ = ["check", "check_async", "PwnedHash", "PwnedOptions", "PwnedResults"]
+
+
+def check(password: bytes | str, /, options: PwnedOptions | None = None) -> PwnedResults:
+    """Check a password against the Pwned Passwords API.
+
+    https://haveibeenpwned.com/API/v3#PwnedPasswords
+    """
+    # If API options are not given, use the defaults
+    if not isinstance(options, PwnedOptions):
+        options = PwnedOptions()
+
+    # The mode option not only changes the format the hashes are returned in,
+    # but also which format we must provide. This means we technically can have
+    # a mismatch in has sent vs received, but we don't want that, truly
+    hash = _utils.generate_hash(options.mode, password)
+
+    # Get the password out of memory now that we have the hash
+    del password
+
+    # Build out the API calling options
+    headers, params = _utils.build_request_options(options)
+
+    # Call out to the API and parse out the results
+    response_text = _utils.make_request(hash[:5], headers=headers, params=params)
+    return _utils.parse_response(hash, response_text, options.get_hashes)

poetry.lock

@@ -0,0 +1,29 @@
+from typing import NamedTuple
+
+
+__all__ = ["PwnedHash", "PwnedOptions", "PwnedResults"]
+
+
+class PwnedHash(NamedTuple):
+    """Returned a hash from a Pwned Passwords API check."""
+
+    suffix: str
+    count: int
+
+
+class PwnedOptions(NamedTuple):
+    """Pwned Passwords API options."""
+
+    add_padding: bool = False
+    mode: str = "sha1"
+
+    # Library-specific option
+    get_hashes: bool = False
+
+
+class PwnedResults(NamedTuple):
+    """Report the Pwned Passwords results."""
+
+    is_pwned: bool
+    times_pwned: int
+    hashes: list[PwnedHash]