hawkapi-auth 0.1.0__tar.gz → 0.2.0__tar.gz

hawkapi_auth-0.2.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## 0.2.0 — 2026-05-16
+
+Security hardening.
+
+- 401 responses now return a generic ``"Invalid or expired token"`` detail; the
+  underlying PyJWT message is logged at DEBUG instead of leaked to clients
+  (CWE-201).
+- ``TokenIssuer`` rejects HMAC secrets shorter than 32 bytes per RFC 7518 §3.2
+  (CWE-1022).
+- ``requires_scopes`` uses explicit ``scope`` → ``scopes`` precedence so an
+  explicit empty ``scope`` no longer silently falls back (CWE-840).
+- ``requires_scopes()`` with no arguments raises ``ValueError`` at construction
+  rather than producing a permissive dependency (CWE-284).
+- Reserved JWT claims (``exp``, ``iat``, ``jti``, ``type``, ``sub``, ``iss``,
+  ``aud``, ``nbf``) supplied via ``extra_claims`` are dropped with a warning
+  instead of overwriting issuer-controlled values.
+- ``PasswordHasher`` now uses explicit OWASP-aligned argon2id parameters
+  (``time_cost=3``, ``memory_cost=65536``, ``parallelism=4``).
+- The active-issuer registry uses ``WeakKeyDictionary`` to avoid the ``id(app)``
+  ABA hazard.
+
+## 0.1.0 — 2026-05-16
+
+Initial release.
+
+- JWT access + refresh tokens (HS256/384/512, RS*, ES*).
+- argon2id password hashing with `needs_rehash`.
+- DI guards: `requires_user`, `requires_claims`, `requires_scopes`.
+- In-memory `RevocationList` with lazy expiry sweep.
+- `init_auth(app, config=...)` plugin entry point.

{hawkapi_auth-0.1.0 → hawkapi_auth-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hawkapi-auth
-Version: 0.1.0
+Version: 0.2.0
 Summary: JWT auth for HawkAPI — access + refresh tokens, password hashing, DI guards
 Project-URL: Homepage, https://pypi.org/project/hawkapi-auth/
 Project-URL: Repository, https://github.com/ashimov/hawkapi-auth

{hawkapi_auth-0.1.0 → hawkapi_auth-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hawkapi-auth"
-version = "0.1.0"
+version = "0.2.0"
 description = "JWT auth for HawkAPI — access + refresh tokens, password hashing, DI guards"
 readme = "README.md"
 license = { file = "LICENSE" }

{hawkapi_auth-0.1.0 → hawkapi_auth-0.2.0}/src/hawkapi_auth/__init__.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 from hawkapi_auth._deps import requires_claims, requires_scopes, requires_user
 from hawkapi_auth._passwords import hash_password, needs_rehash, verify_password

{hawkapi_auth-0.1.0 → hawkapi_auth-0.2.0}/src/hawkapi_auth/_deps.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import logging
 from typing import Any
 
 from hawkapi.exceptions import HTTPException
@@ -9,6 +10,8 @@ from hawkapi.requests.request import Request
 
 from hawkapi_auth._tokens import TokenError
 
+logger = logging.getLogger("hawkapi_auth")
+
 
 def _bearer_token(request: Request) -> str | None:
     auth = request.headers.get("authorization")
@@ -48,7 +51,12 @@ async def requires_user(request: Request) -> str:
     try:
         claims = issuer.verify_access(token)
     except TokenError as exc:
-        raise HTTPException(401, detail=str(exc), headers={"WWW-Authenticate": "Bearer"}) from exc
+        logger.debug("token verification failed: %s", exc)
+        raise HTTPException(
+            401,
+            detail="Invalid or expired token",
+            headers={"WWW-Authenticate": "Bearer"},
+        ) from None
     sub = claims.get("sub")
     if not isinstance(sub, str):
         raise HTTPException(401, detail="Token has no subject")
@@ -68,7 +76,12 @@ async def requires_claims(request: Request) -> dict[str, Any]:
     try:
         return issuer.verify_access(token)
     except TokenError as exc:
-        raise HTTPException(401, detail=str(exc), headers={"WWW-Authenticate": "Bearer"}) from exc
+        logger.debug("token verification failed: %s", exc)
+        raise HTTPException(
+            401,
+            detail="Invalid or expired token",
+            headers={"WWW-Authenticate": "Bearer"},
+        ) from None
 
 
 def requires_scopes(*required: str):
@@ -82,10 +95,18 @@ def requires_scopes(*required: str):
         @app.get("/admin", dependencies=[Depends(requires_scopes("admin"))])
         async def admin(): ...
     """
+    if not required:
+        raise ValueError("requires_scopes() must receive at least one scope")
 
     async def _dep(request: Request) -> dict[str, Any]:
         claims = await requires_claims(request)
-        raw = claims.get("scope") or claims.get("scopes") or []
+        # Explicit precedence: "scope" beats "scopes" even if "scope" is empty.
+        if "scope" in claims:
+            raw = claims["scope"]
+        elif "scopes" in claims:
+            raw = claims["scopes"]
+        else:
+            raw = []
         granted: set[str] = set()
         if isinstance(raw, str):
             granted = set(raw.split())

{hawkapi_auth-0.1.0 → hawkapi_auth-0.2.0}/src/hawkapi_auth/_passwords.py

@@ -2,10 +2,19 @@
 
 from __future__ import annotations
 
-from argon2 import PasswordHasher
+from argon2 import PasswordHasher, Type
 from argon2.exceptions import VerifyMismatchError
 
-_hasher = PasswordHasher()
+# Explicit OWASP-aligned parameters (argon2id, 64MiB memory, 3 iterations,
+# parallelism 4). Hash output 32 bytes, salt 16 bytes.
+_hasher = PasswordHasher(
+    time_cost=3,
+    memory_cost=65536,
+    parallelism=4,
+    hash_len=32,
+    salt_len=16,
+    type=Type.ID,
+)
 
 
 def hash_password(password: str) -> str:

{hawkapi_auth-0.1.0 → hawkapi_auth-0.2.0}/src/hawkapi_auth/_plugin.py

@@ -2,7 +2,9 @@
 
 from __future__ import annotations
 
+import contextlib
 from typing import Any
+from weakref import WeakKeyDictionary
 
 from hawkapi_auth._tokens import JWTConfig, RevocationList, TokenIssuer
 
@@ -13,7 +15,9 @@ class _StateNamespace:
     auth: Any  # set by init_auth
 
 
-_ACTIVE_ISSUERS: dict[int, TokenIssuer] = {}
+# WeakKeyDictionary avoids the ABA hazard where ``id(app)`` is reused
+# after the original app object is garbage-collected.
+_ACTIVE_ISSUERS: WeakKeyDictionary[Any, TokenIssuer] = WeakKeyDictionary()
 _LAST_ISSUER: list[TokenIssuer | None] = [None]
 
 
@@ -24,7 +28,10 @@ def resolve_issuer(app: Any) -> TokenIssuer | None:
     ``scope["app"]``, so the DI dependency uses a module-level registry.
     """
     if app is not None:
-        issuer = _ACTIVE_ISSUERS.get(id(app))
+        try:
+            issuer = _ACTIVE_ISSUERS.get(app)
+        except TypeError:
+            issuer = None
         if issuer is not None:
             return issuer
     return _LAST_ISSUER[0]
@@ -56,7 +63,9 @@ def init_auth(
     if getattr(app, "state", None) is None:
         app.state = _StateNamespace()
     app.state.auth = issuer
-    _ACTIVE_ISSUERS[id(app)] = issuer
+    with contextlib.suppress(TypeError):
+        # Non-weakrefable app — fall back to last-attached lookup only.
+        _ACTIVE_ISSUERS[app] = issuer
     _LAST_ISSUER[0] = issuer
     return issuer
 

{hawkapi_auth-0.1.0 → hawkapi_auth-0.2.0}/src/hawkapi_auth/_tokens.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import logging
 import secrets
 import time
 import uuid
@@ -11,6 +12,12 @@ from typing import Any
 import jwt
 from jwt.exceptions import InvalidTokenError
 
+logger = logging.getLogger("hawkapi_auth")
+
+_RESERVED_CLAIMS: frozenset[str] = frozenset(
+    {"exp", "iat", "jti", "type", "sub", "iss", "aud", "nbf"}
+)
+
 
 class TokenError(Exception):
     """Raised when a token fails validation."""
@@ -82,6 +89,14 @@ class TokenIssuer:
         self.revocation.revoke(jti, exp)
 
     def _issue(self, subject: str, token_type: str, ttl: int, extra: dict[str, Any]) -> str:
+        # Drop any caller-supplied keys that collide with reserved JWT claims —
+        # callers must not be able to forge ``exp``, ``type``, ``sub`` etc.
+        dropped = [k for k in extra if k in _RESERVED_CLAIMS]
+        if dropped:
+            logger.warning(
+                "ignoring caller-supplied reserved claim(s): %s", ", ".join(sorted(dropped))
+            )
+            extra = {k: v for k, v in extra.items() if k not in _RESERVED_CLAIMS}
         now = int(time.time())
         payload: dict[str, Any] = {
             "sub": subject,
@@ -98,6 +113,8 @@ class TokenIssuer:
         key = self.config.private_key or self.config.secret
         if not key:
             raise TokenError("JWTConfig has no secret or private_key")
+        if self.config.algorithm.startswith("HS") and len(key.encode("utf-8")) < 32:
+            raise TokenError("HMAC secret must be at least 32 bytes (RFC 7518 §3.2)")
         return jwt.encode(payload, key, algorithm=self.config.algorithm)
 
     def _verify(

hawkapi_auth-0.2.0/tests/test_security.py

@@ -0,0 +1,76 @@
+"""Regression tests for 0.2.0 hardening fixes."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+from hawkapi import Depends, HawkAPI
+from hawkapi.testing import TestClient
+
+from hawkapi_auth import (
+    JWTConfig,
+    TokenError,
+    TokenIssuer,
+    init_auth,
+    random_secret,
+    requires_scopes,
+    requires_user,
+)
+
+
+@pytest.fixture
+def app() -> HawkAPI:
+    app = HawkAPI(openapi_url=None, docs_url=None, redoc_url=None, scalar_url=None)
+    init_auth(app, config=JWTConfig(secret=random_secret()))
+
+    @app.get("/me")
+    async def me(user_id: str = Depends(requires_user)) -> dict[str, str]:
+        return {"user_id": user_id}
+
+    @app.get("/admin")
+    async def admin(c: dict[str, Any] = Depends(requires_scopes("admin"))) -> dict[str, str]:
+        return {"who": c["sub"]}
+
+    return app
+
+
+def test_invalid_token_returns_generic_detail(app: HawkAPI) -> None:
+    """No library-internal error message must leak through the 401 detail."""
+    client = TestClient(app)
+    r = client.get("/me", headers={"Authorization": "Bearer not.a.jwt"})
+    assert r.status_code == 401
+    assert r.json()["detail"] == "Invalid or expired token"
+
+
+def test_short_hmac_secret_rejected() -> None:
+    """HS256 with <32-byte secret must refuse to issue."""
+    issuer = TokenIssuer(config=JWTConfig(secret="abc"))
+    with pytest.raises(TokenError, match="HMAC secret"):
+        issuer.issue_access("u")
+
+
+def test_scope_takes_precedence_over_scopes(app: HawkAPI) -> None:
+    """Explicit empty ``scope`` must NOT silently fall back to ``scopes``."""
+    issuer = app.state.auth  # type: ignore[attr-defined]
+    token = issuer.issue_access("alice", scope="", scopes=["admin"])
+    client = TestClient(app)
+    r = client.get("/admin", headers={"Authorization": f"Bearer {token}"})
+    assert r.status_code == 403
+
+
+def test_requires_scopes_zero_args_raises() -> None:
+    """``requires_scopes()`` with no scopes is a programmer error."""
+    with pytest.raises(ValueError, match="at least one scope"):
+        requires_scopes()
+
+
+def test_extra_claims_cannot_shadow_reserved() -> None:
+    """Caller-supplied reserved claims (exp/type/sub/...) must be ignored."""
+    issuer = TokenIssuer(config=JWTConfig(secret=random_secret()))
+    token = issuer.issue_access("u", exp=0, type="admin", sub="attacker")
+    # _verify treats exp=0 as long-expired — caller injection must NOT take effect.
+    claims = issuer.verify_access(token)
+    assert claims["type"] == "access"
+    assert claims["sub"] == "u"
+    assert claims["exp"] > 0

{hawkapi_auth-0.1.0 → hawkapi_auth-0.2.0}/tests/test_tokens.py

@@ -59,13 +59,13 @@ def test_extra_claims_carried_through(issuer: TokenIssuer) -> None:
 
 
 def test_audience_required_when_configured() -> None:
-    issuer = TokenIssuer(config=JWTConfig(secret="s", audience="api"))
+    issuer = TokenIssuer(config=JWTConfig(secret=random_secret(), audience="api"))
     token = issuer.issue_access("u")
     assert issuer.verify_access(token)["aud"] == "api"
 
 
 def test_issuer_required_when_configured() -> None:
-    issuer = TokenIssuer(config=JWTConfig(secret="s", issuer="hawk"))
+    issuer = TokenIssuer(config=JWTConfig(secret=random_secret(), issuer="hawk"))
     token = issuer.issue_access("u")
     assert issuer.verify_access(token)["iss"] == "hawk"
 
@@ -80,7 +80,7 @@ def test_revoked_refresh_rejected() -> None:
 
 
 def test_revoke_without_revocation_list_errors() -> None:
-    issuer = TokenIssuer(config=JWTConfig(secret="s"))
+    issuer = TokenIssuer(config=JWTConfig(secret=random_secret()))
     token = issuer.issue_refresh("u")
     with pytest.raises(TokenError, match="RevocationList"):
         issuer.revoke_refresh(token)

{hawkapi_auth-0.1.0 → hawkapi_auth-0.2.0}/uv.lock

@@ -160,7 +160,7 @@ wheels = [
 
 [[package]]
 name = "hawkapi-auth"
-version = "0.1.0"
+version = "0.2.0"
 source = { editable = "." }
 dependencies = [
     { name = "argon2-cffi" },

hawkapi_auth-0.1.0/CHANGELOG.md

@@ -1,11 +0,0 @@
-# Changelog
-
-## 0.1.0 — 2026-05-16
-
-Initial release.
-
-- JWT access + refresh tokens (HS256/384/512, RS*, ES*).
-- argon2id password hashing with `needs_rehash`.
-- DI guards: `requires_user`, `requires_claims`, `requires_scopes`.
-- In-memory `RevocationList` with lazy expiry sweep.
-- `init_auth(app, config=...)` plugin entry point.