hawkapi-auth 0.1.0__tar.gz

hawkapi_auth-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: ruff check
+        run: uv run ruff check .
+      - name: ruff format check
+        run: uv run ruff format --check .
+
+  typecheck:
+    name: Typecheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: pyright
+        run: uv run pyright src/
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: Run tests
+        run: uv run pytest tests/ -q

hawkapi_auth-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,25 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write  # required for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+      - name: Build package
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

hawkapi_auth-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+.venv/
+venv/
+env/
+.env
+*.log
+.mypy_cache/
+.pyright/
+.ruff_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+.hypothesis/
+.tox/
+.nox/
+*.swp
+*.swo
+*~
+.DS_Store
+.idea/
+.vscode/
+.history/
+site/
+.remember/

hawkapi_auth-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# 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.

hawkapi_auth-0.1.0/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.

hawkapi_auth-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,157 @@
+# 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/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hawkapi-auth"
+version = "0.1.0"
+description = "JWT auth for HawkAPI — access + refresh tokens, password hashing, DI guards"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.12"
+authors = [
+    { name = "HawkAPI Contributors", email = "hawkapi@users.noreply.github.com" },
+]
+keywords = ["hawkapi", "auth", "jwt", "authentication", "argon2", "bcrypt"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Security",
+    "Typing :: Typed",
+]
+dependencies = [
+    "hawkapi>=0.1.7",
+    "PyJWT>=2.8",
+    "argon2-cffi>=23.1",
+]
+
+[project.urls]
+Homepage = "https://pypi.org/project/hawkapi-auth/"
+Repository = "https://github.com/ashimov/hawkapi-auth"
+Issues = "https://github.com/ashimov/hawkapi-auth/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "httpx>=0.27",
+    "ruff>=0.8",
+    "pyright>=1.1",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hawkapi_auth"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+filterwarnings = ["ignore::DeprecationWarning"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "S"]
+ignore = ["S101", "B008"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S"]
+
+[tool.pyright]
+pythonVersion = "3.12"
+typeCheckingMode = "strict"
+reportUnknownVariableType = false
+reportUnknownMemberType = false
+reportUnknownArgumentType = false

hawkapi_auth-0.1.0/src/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",
+]