hawkapi-auth 0.1.0__py3-none-any.whl

hawkapi_auth/__init__.py

@@ -0,0 +1,32 @@
+"""hawkapi-auth — JWT auth (access + refresh) + password hashing for HawkAPI."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from hawkapi_auth._deps import requires_claims, requires_scopes, requires_user
+from hawkapi_auth._passwords import hash_password, needs_rehash, verify_password
+from hawkapi_auth._plugin import init_auth
+from hawkapi_auth._tokens import (
+    JWTConfig,
+    RevocationList,
+    TokenError,
+    TokenIssuer,
+    random_secret,
+)
+
+__all__ = [
+    "JWTConfig",
+    "RevocationList",
+    "TokenError",
+    "TokenIssuer",
+    "__version__",
+    "hash_password",
+    "init_auth",
+    "needs_rehash",
+    "random_secret",
+    "requires_claims",
+    "requires_scopes",
+    "requires_user",
+    "verify_password",
+]

hawkapi_auth/_deps.py

@@ -0,0 +1,102 @@
+"""DI dependencies — extract + verify access tokens from incoming requests."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from hawkapi.exceptions import HTTPException
+from hawkapi.requests.request import Request
+
+from hawkapi_auth._tokens import TokenError
+
+
+def _bearer_token(request: Request) -> str | None:
+    auth = request.headers.get("authorization")
+    if not auth:
+        return None
+    parts = auth.split(" ", 1)
+    if len(parts) != 2 or parts[0].lower() != "bearer":
+        return None
+    return parts[1].strip() or None
+
+
+def _issuer_from_request(request: Request) -> Any:
+    from hawkapi_auth._plugin import resolve_issuer  # noqa: PLC0415
+
+    return resolve_issuer(request.scope.get("app"))
+
+
+async def requires_user(request: Request) -> str:
+    """DI helper: validate the ``Authorization: Bearer <jwt>`` header.
+
+    Returns the ``sub`` claim of the access token. Raises ``HTTPException(401)``
+    on missing / invalid / revoked tokens.
+
+    Usage:
+        @app.get("/me")
+        async def me(user_id: str = Depends(requires_user)):
+            return await db.fetch_user(user_id)
+    """
+    token = _bearer_token(request)
+    if token is None:
+        raise HTTPException(
+            401, detail="Missing bearer token", headers={"WWW-Authenticate": "Bearer"}
+        )
+    issuer = _issuer_from_request(request)
+    if issuer is None:
+        raise HTTPException(500, detail="hawkapi-auth not initialised")
+    try:
+        claims = issuer.verify_access(token)
+    except TokenError as exc:
+        raise HTTPException(401, detail=str(exc), headers={"WWW-Authenticate": "Bearer"}) from exc
+    sub = claims.get("sub")
+    if not isinstance(sub, str):
+        raise HTTPException(401, detail="Token has no subject")
+    return sub
+
+
+async def requires_claims(request: Request) -> dict[str, Any]:
+    """DI helper that returns the full set of verified claims, not just ``sub``."""
+    token = _bearer_token(request)
+    if token is None:
+        raise HTTPException(
+            401, detail="Missing bearer token", headers={"WWW-Authenticate": "Bearer"}
+        )
+    issuer = _issuer_from_request(request)
+    if issuer is None:
+        raise HTTPException(500, detail="hawkapi-auth not initialised")
+    try:
+        return issuer.verify_access(token)
+    except TokenError as exc:
+        raise HTTPException(401, detail=str(exc), headers={"WWW-Authenticate": "Bearer"}) from exc
+
+
+def requires_scopes(*required: str):
+    """Build a DI dependency that gates on the ``scope`` claim.
+
+    The access token must carry a ``scope`` claim — either a space-separated
+    string (OAuth2 style) or a list of strings. All entries in *required* must
+    be present.
+
+    Usage:
+        @app.get("/admin", dependencies=[Depends(requires_scopes("admin"))])
+        async def admin(): ...
+    """
+
+    async def _dep(request: Request) -> dict[str, Any]:
+        claims = await requires_claims(request)
+        raw = claims.get("scope") or claims.get("scopes") or []
+        granted: set[str] = set()
+        if isinstance(raw, str):
+            granted = set(raw.split())
+        elif isinstance(raw, list):
+            granted = {s for s in raw if isinstance(s, str)}
+        missing = [s for s in required if s not in granted]
+        if missing:
+            raise HTTPException(403, detail=f"Missing scopes: {', '.join(missing)}")
+        return claims
+
+    return _dep
+
+
+__all__ = ["requires_user", "requires_claims", "requires_scopes"]

hawkapi_auth/_passwords.py

@@ -0,0 +1,40 @@
+"""Password hashing helpers — argon2id by default."""
+
+from __future__ import annotations
+
+from argon2 import PasswordHasher
+from argon2.exceptions import VerifyMismatchError
+
+_hasher = PasswordHasher()
+
+
+def hash_password(password: str) -> str:
+    """Return an argon2id hash of *password* (PHC string format)."""
+    return _hasher.hash(password)
+
+
+def verify_password(password: str, stored_hash: str) -> bool:
+    """Constant-time check of *password* against a stored argon2 hash.
+
+    Returns False on mismatch or invalid hash format. Never raises so it is
+    safe to use directly in handler logic.
+    """
+    try:
+        return _hasher.verify(stored_hash, password)
+    except (VerifyMismatchError, Exception):
+        return False
+
+
+def needs_rehash(stored_hash: str) -> bool:
+    """True when *stored_hash* should be re-hashed with current parameters.
+
+    Call this after a successful login and re-hash the password if it returns
+    True — protects against algorithm / parameter upgrades over time.
+    """
+    try:
+        return _hasher.check_needs_rehash(stored_hash)
+    except Exception:
+        return False
+
+
+__all__ = ["hash_password", "verify_password", "needs_rehash"]

hawkapi_auth/_plugin.py

@@ -0,0 +1,64 @@
+"""``init_auth`` — wires a JWT issuer into the HawkAPI app."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from hawkapi_auth._tokens import JWTConfig, RevocationList, TokenIssuer
+
+
+class _StateNamespace:
+    """Lightweight attribute bag for ``app.state`` when none exists."""
+
+    auth: Any  # set by init_auth
+
+
+_ACTIVE_ISSUERS: dict[int, TokenIssuer] = {}
+_LAST_ISSUER: list[TokenIssuer | None] = [None]
+
+
+def resolve_issuer(app: Any) -> TokenIssuer | None:
+    """Look up the active TokenIssuer for *app*, or the last-attached as a fallback.
+
+    Mirrors the lookup pattern from hawkapi-cache: TestClient does not populate
+    ``scope["app"]``, so the DI dependency uses a module-level registry.
+    """
+    if app is not None:
+        issuer = _ACTIVE_ISSUERS.get(id(app))
+        if issuer is not None:
+            return issuer
+    return _LAST_ISSUER[0]
+
+
+def init_auth(
+    app: Any,
+    *,
+    config: JWTConfig,
+    revocation: RevocationList | None = None,
+) -> TokenIssuer:
+    """Mount a :class:`TokenIssuer` on ``app.state.auth`` and register lookup.
+
+    ```python
+    from hawkapi import HawkAPI
+    from hawkapi_auth import init_auth, JWTConfig, random_secret
+
+    app = HawkAPI()
+    init_auth(app, config=JWTConfig(secret=random_secret()))
+    ```
+
+    After this call:
+
+    * ``app.state.auth`` is the :class:`TokenIssuer`.
+    * ``Depends(requires_user)`` resolves the ``sub`` claim from
+      ``Authorization: Bearer …`` headers.
+    """
+    issuer = TokenIssuer(config=config, revocation=revocation)
+    if getattr(app, "state", None) is None:
+        app.state = _StateNamespace()
+    app.state.auth = issuer
+    _ACTIVE_ISSUERS[id(app)] = issuer
+    _LAST_ISSUER[0] = issuer
+    return issuer
+
+
+__all__ = ["init_auth", "resolve_issuer"]

hawkapi_auth/_tokens.py

@@ -0,0 +1,168 @@
+"""JWT access + refresh token issue/verify."""
+
+from __future__ import annotations
+
+import secrets
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+import jwt
+from jwt.exceptions import InvalidTokenError
+
+
+class TokenError(Exception):
+    """Raised when a token fails validation."""
+
+
+@dataclass(frozen=True, slots=True)
+class JWTConfig:
+    """JWT signing configuration.
+
+    Attributes:
+        secret: HMAC secret for symmetric algorithms (HS256/384/512). For RS*
+            / ES* use ``private_key`` + ``public_key`` instead.
+        algorithm: Signing algorithm. ``HS256`` by default.
+        access_ttl_seconds: Lifetime of issued access tokens. 15 minutes default.
+        refresh_ttl_seconds: Lifetime of issued refresh tokens. 30 days default.
+        issuer: Optional ``iss`` claim.
+        audience: Optional ``aud`` claim (string or list of strings).
+        private_key: PEM-encoded private key when using asymmetric algorithms.
+        public_key: PEM-encoded public key when using asymmetric algorithms.
+    """
+
+    secret: str = ""
+    algorithm: str = "HS256"
+    access_ttl_seconds: int = 15 * 60
+    refresh_ttl_seconds: int = 30 * 24 * 60 * 60
+    issuer: str | None = None
+    audience: str | list[str] | None = None
+    private_key: str = ""
+    public_key: str = ""
+    # Token-type claim values — exposed so consumers can match on them.
+    access_type: str = "access"
+    refresh_type: str = "refresh"
+
+
+@dataclass
+class TokenIssuer:
+    """Issue + verify JWTs against a :class:`JWTConfig`.
+
+    Stateless. For refresh-token revocation use :class:`RevocationList`.
+    """
+
+    config: JWTConfig
+    revocation: RevocationList | None = None
+
+    def issue_access(self, subject: str, **extra_claims: Any) -> str:
+        return self._issue(
+            subject, self.config.access_type, self.config.access_ttl_seconds, extra_claims
+        )
+
+    def issue_refresh(self, subject: str, **extra_claims: Any) -> str:
+        return self._issue(
+            subject, self.config.refresh_type, self.config.refresh_ttl_seconds, extra_claims
+        )
+
+    def verify_access(self, token: str) -> dict[str, Any]:
+        return self._verify(token, expected_type=self.config.access_type)
+
+    def verify_refresh(self, token: str) -> dict[str, Any]:
+        return self._verify(token, expected_type=self.config.refresh_type)
+
+    def revoke_refresh(self, token: str) -> None:
+        if self.revocation is None:
+            raise TokenError("no RevocationList configured")
+        claims = self._verify(token, expected_type=self.config.refresh_type, allow_revoked=True)
+        jti = claims.get("jti")
+        if not isinstance(jti, str):
+            raise TokenError("token has no jti claim")
+        exp = int(claims.get("exp", 0))
+        self.revocation.revoke(jti, exp)
+
+    def _issue(self, subject: str, token_type: str, ttl: int, extra: dict[str, Any]) -> str:
+        now = int(time.time())
+        payload: dict[str, Any] = {
+            "sub": subject,
+            "iat": now,
+            "exp": now + ttl,
+            "jti": uuid.uuid4().hex,
+            "type": token_type,
+            **extra,
+        }
+        if self.config.issuer:
+            payload["iss"] = self.config.issuer
+        if self.config.audience:
+            payload["aud"] = self.config.audience
+        key = self.config.private_key or self.config.secret
+        if not key:
+            raise TokenError("JWTConfig has no secret or private_key")
+        return jwt.encode(payload, key, algorithm=self.config.algorithm)
+
+    def _verify(
+        self, token: str, *, expected_type: str, allow_revoked: bool = False
+    ) -> dict[str, Any]:
+        key = self.config.public_key or self.config.secret
+        if not key:
+            raise TokenError("JWTConfig has no secret or public_key")
+        options: dict[str, Any] = {}
+        if self.config.audience is None:
+            options["verify_aud"] = False
+        try:
+            claims: dict[str, Any] = jwt.decode(
+                token,
+                key,
+                algorithms=[self.config.algorithm],
+                audience=self.config.audience,
+                issuer=self.config.issuer,
+                options=options,  # type: ignore[arg-type]
+            )
+        except InvalidTokenError as exc:
+            raise TokenError(str(exc)) from exc
+        if claims.get("type") != expected_type:
+            raise TokenError(f"expected {expected_type!r} token, got {claims.get('type')!r}")
+        if not allow_revoked and self.revocation is not None:
+            jti = claims.get("jti")
+            if isinstance(jti, str) and self.revocation.is_revoked(jti):
+                raise TokenError("token revoked")
+        return claims
+
+
+@dataclass
+class RevocationList:
+    """In-memory revoked-token registry. Keys are JTI claims; values are expiry.
+
+    Expired entries are dropped lazily on every access. For multi-process
+    deployments use a Redis-backed implementation (TODO v0.2.0).
+    """
+
+    _store: dict[str, int] = field(default_factory=dict)
+
+    def revoke(self, jti: str, exp_timestamp: int) -> None:
+        self._sweep()
+        self._store[jti] = exp_timestamp
+
+    def is_revoked(self, jti: str) -> bool:
+        self._sweep()
+        return jti in self._store
+
+    def _sweep(self) -> None:
+        now = int(time.time())
+        dead = [k for k, exp in self._store.items() if exp <= now]
+        for k in dead:
+            self._store.pop(k, None)
+
+
+def random_secret(length: int = 64) -> str:
+    """Return a URL-safe random secret suitable for JWTConfig.secret."""
+    return secrets.token_urlsafe(length)
+
+
+__all__ = [
+    "JWTConfig",
+    "RevocationList",
+    "TokenError",
+    "TokenIssuer",
+    "random_secret",
+]

hawkapi_auth-0.1.0.dist-info/METADATA

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: hawkapi-auth
+Version: 0.1.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
+Project-URL: Issues, https://github.com/ashimov/hawkapi-auth/issues
+Author-email: HawkAPI Contributors <hawkapi@users.noreply.github.com>
+License: MIT License
+        
+        Copyright (c) 2026 HawkAPI Contributors
+        
+        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.
+License-File: LICENSE
+Keywords: argon2,auth,authentication,bcrypt,hawkapi,jwt
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: argon2-cffi>=23.1
+Requires-Dist: hawkapi>=0.1.7
+Requires-Dist: pyjwt>=2.8
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# hawkapi-auth
+
+JWT auth for [HawkAPI](https://github.com/ashimov/HawkAPI). Access + refresh tokens, argon2id password hashing, DI guards, scope-based access control.
+
+## Install
+
+```bash
+pip install hawkapi-auth
+```
+
+## Quickstart
+
+```python
+from hawkapi import Depends, HawkAPI, HTTPException
+from hawkapi_auth import (
+    JWTConfig,
+    hash_password,
+    init_auth,
+    random_secret,
+    requires_user,
+    verify_password,
+)
+
+app = HawkAPI()
+init_auth(app, config=JWTConfig(secret=random_secret()))
+
+
+@app.post("/register")
+async def register(email: str, password: str):
+    await db.create_user(email=email, password_hash=hash_password(password))
+    return {"ok": True}
+
+
+@app.post("/login")
+async def login(email: str, password: str):
+    user = await db.find_user(email)
+    if not user or not verify_password(password, user.password_hash):
+        raise HTTPException(401, detail="Invalid credentials")
+    issuer = app.state.auth
+    return {
+        "access_token": issuer.issue_access(user.id),
+        "refresh_token": issuer.issue_refresh(user.id),
+    }
+
+
+@app.get("/me")
+async def me(user_id: str = Depends(requires_user)):
+    return await db.fetch_user(user_id)
+```
+
+## Token issue / verify
+
+```python
+issuer = app.state.auth      # TokenIssuer
+
+access = issuer.issue_access("user-1", role="admin", scope="read write")
+refresh = issuer.issue_refresh("user-1")
+
+claims = issuer.verify_access(access)        # raises TokenError on bad token
+claims = issuer.verify_refresh(refresh)      # ditto, plus checks the token type
+```
+
+`issue_access` / `issue_refresh` accept arbitrary keyword claims (`role`, `scope`, anything JSON-serialisable).
+
+## JWTConfig
+
+```python
+JWTConfig(
+    secret="…",                  # HMAC secret for HS256/384/512
+    algorithm="HS256",
+    access_ttl_seconds=15 * 60,
+    refresh_ttl_seconds=30 * 24 * 60 * 60,
+    issuer="my-service",          # optional iss claim
+    audience="my-api",            # optional aud claim
+    private_key="",               # RS*/ES* — PEM
+    public_key="",
+)
+```
+
+Use `random_secret()` to mint one. Store it outside of git.
+
+## DI guards
+
+```python
+from hawkapi_auth import requires_user, requires_claims, requires_scopes
+
+@app.get("/me")
+async def me(user_id: str = Depends(requires_user)):
+    ...
+
+@app.get("/dump")
+async def dump(claims: dict = Depends(requires_claims)):
+    ...
+
+@app.get("/admin", dependencies=[Depends(requires_scopes("admin"))])
+async def admin():
+    ...
+```
+
+`requires_scopes(*scopes)` expects either a space-separated `scope` claim or a list under `scope` / `scopes`. Missing scopes → 403.
+
+## Refresh + revocation
+
+```python
+from hawkapi_auth import RevocationList
+
+rev = RevocationList()
+init_auth(app, config=JWTConfig(secret=...), revocation=rev)
+
+@app.post("/refresh")
+async def refresh(refresh_token: str):
+    issuer = app.state.auth
+    claims = issuer.verify_refresh(refresh_token)
+    return {"access_token": issuer.issue_access(claims["sub"])}
+
+@app.post("/logout")
+async def logout(refresh_token: str):
+    app.state.auth.revoke_refresh(refresh_token)
+    return {"ok": True}
+```
+
+`RevocationList` is in-memory only. For multi-process deployments, swap in a Redis-backed implementation (planned in v0.2.0).
+
+## Password hashing
+
+```python
+from hawkapi_auth import hash_password, verify_password, needs_rehash
+
+h = hash_password("hunter2")              # argon2id
+ok = verify_password("hunter2", h)        # constant-time, returns bool
+if needs_rehash(h):
+    h = hash_password("hunter2")          # re-hash after a successful login
+```
+
+`verify_password` never raises — safe to use directly in handler bodies.
+
+## What's not included (v0.2.0 roadmap)
+
+* Social OAuth providers (Google / GitHub / Discord / Microsoft).
+* Email-based password reset + verification flows.
+* Pre-built user model and storage.
+* Redis-backed `RevocationList`.
+
+## Development
+
+```bash
+git clone https://github.com/ashimov/hawkapi-auth.git
+cd hawkapi-auth
+uv sync --extra dev
+uv run pytest -q
+uv run ruff check . && uv run ruff format --check .
+uv run pyright src/
+```
+
+## License
+
+MIT.

hawkapi_auth-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+hawkapi_auth/__init__.py,sha256=wszL8wfaZObC3F8X8Y92uuGPr8ypWVvrNF5amuQUsWU,749
+hawkapi_auth/_deps.py,sha256=IgHC0bVXfqGRGgchWDLqmjMPb-bgzi25csN6OQVZxPc,3479
+hawkapi_auth/_passwords.py,sha256=5mTy64MP3icz3hRwufLgWVOpLp5XY3v3OM_pnikdZds,1195
+hawkapi_auth/_plugin.py,sha256=3d3ybjllXf6sUVzZvS8VS523HfG1DUHCkpTQ1ZSVnZw,1783
+hawkapi_auth/_tokens.py,sha256=9HtRxbqgQm1-dQqfFugeraeepvkiavw3d_HetlrhNo8,5755
+hawkapi_auth-0.1.0.dist-info/METADATA,sha256=JlK9jvSD1H8lfuyP69F_ZD27EmXDomu9a7LmbvmZwsw,6654
+hawkapi_auth-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+hawkapi_auth-0.1.0.dist-info/licenses/LICENSE,sha256=_RpjhvsfLqqeG_gv2cRatjIxCTGXTpXhKU9jqLZXYa4,1077
+hawkapi_auth-0.1.0.dist-info/RECORD,,

hawkapi_auth-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

hawkapi_auth-0.1.0.dist-info/licenses/LICENSE

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