|
| 1 | +# hawkapi-auth |
| 2 | + |
| 3 | +JWT auth for [HawkAPI](https://github.com/ashimov/HawkAPI). Access + refresh tokens, argon2id password hashing, DI guards, scope-based access control. |
| 4 | + |
| 5 | +## Install |
| 6 | + |
| 7 | +```bash |
| 8 | +pip install hawkapi-auth |
| 9 | +``` |
| 10 | + |
| 11 | +## Quickstart |
| 12 | + |
| 13 | +```python |
| 14 | +from hawkapi import Depends, HawkAPI, HTTPException |
| 15 | +from hawkapi_auth import ( |
| 16 | + JWTConfig, |
| 17 | + hash_password, |
| 18 | + init_auth, |
| 19 | + random_secret, |
| 20 | + requires_user, |
| 21 | + verify_password, |
| 22 | +) |
| 23 | + |
| 24 | +app = HawkAPI() |
| 25 | +init_auth(app, config=JWTConfig(secret=random_secret())) |
| 26 | + |
| 27 | + |
| 28 | +@app.post("/register") |
| 29 | +async def register(email: str, password: str): |
| 30 | + await db.create_user(email=email, password_hash=hash_password(password)) |
| 31 | + return {"ok": True} |
| 32 | + |
| 33 | + |
| 34 | +@app.post("/login") |
| 35 | +async def login(email: str, password: str): |
| 36 | + user = await db.find_user(email) |
| 37 | + if not user or not verify_password(password, user.password_hash): |
| 38 | + raise HTTPException(401, detail="Invalid credentials") |
| 39 | + issuer = app.state.auth |
| 40 | + return { |
| 41 | + "access_token": issuer.issue_access(user.id), |
| 42 | + "refresh_token": issuer.issue_refresh(user.id), |
| 43 | + } |
| 44 | + |
| 45 | + |
| 46 | +@app.get("/me") |
| 47 | +async def me(user_id: str = Depends(requires_user)): |
| 48 | + return await db.fetch_user(user_id) |
| 49 | +``` |
| 50 | + |
| 51 | +## Token issue / verify |
| 52 | + |
| 53 | +```python |
| 54 | +issuer = app.state.auth # TokenIssuer |
| 55 | + |
| 56 | +access = issuer.issue_access("user-1", role="admin", scope="read write") |
| 57 | +refresh = issuer.issue_refresh("user-1") |
| 58 | + |
| 59 | +claims = issuer.verify_access(access) # raises TokenError on bad token |
| 60 | +claims = issuer.verify_refresh(refresh) # ditto, plus checks the token type |
| 61 | +``` |
| 62 | + |
| 63 | +`issue_access` / `issue_refresh` accept arbitrary keyword claims (`role`, `scope`, anything JSON-serialisable). |
| 64 | + |
| 65 | +## JWTConfig |
| 66 | + |
| 67 | +```python |
| 68 | +JWTConfig( |
| 69 | + secret="…", # HMAC secret for HS256/384/512 |
| 70 | + algorithm="HS256", |
| 71 | + access_ttl_seconds=15 * 60, |
| 72 | + refresh_ttl_seconds=30 * 24 * 60 * 60, |
| 73 | + issuer="my-service", # optional iss claim |
| 74 | + audience="my-api", # optional aud claim |
| 75 | + private_key="", # RS*/ES* — PEM |
| 76 | + public_key="", |
| 77 | +) |
| 78 | +``` |
| 79 | + |
| 80 | +Use `random_secret()` to mint one. Store it outside of git. |
| 81 | + |
| 82 | +## DI guards |
| 83 | + |
| 84 | +```python |
| 85 | +from hawkapi_auth import requires_user, requires_claims, requires_scopes |
| 86 | + |
| 87 | +@app.get("/me") |
| 88 | +async def me(user_id: str = Depends(requires_user)): |
| 89 | + ... |
| 90 | + |
| 91 | +@app.get("/dump") |
| 92 | +async def dump(claims: dict = Depends(requires_claims)): |
| 93 | + ... |
| 94 | + |
| 95 | +@app.get("/admin", dependencies=[Depends(requires_scopes("admin"))]) |
| 96 | +async def admin(): |
| 97 | + ... |
| 98 | +``` |
| 99 | + |
| 100 | +`requires_scopes(*scopes)` expects either a space-separated `scope` claim or a list under `scope` / `scopes`. Missing scopes → 403. |
| 101 | + |
| 102 | +## Refresh + revocation |
| 103 | + |
| 104 | +```python |
| 105 | +from hawkapi_auth import RevocationList |
| 106 | + |
| 107 | +rev = RevocationList() |
| 108 | +init_auth(app, config=JWTConfig(secret=...), revocation=rev) |
| 109 | + |
| 110 | +@app.post("/refresh") |
| 111 | +async def refresh(refresh_token: str): |
| 112 | + issuer = app.state.auth |
| 113 | + claims = issuer.verify_refresh(refresh_token) |
| 114 | + return {"access_token": issuer.issue_access(claims["sub"])} |
| 115 | + |
| 116 | +@app.post("/logout") |
| 117 | +async def logout(refresh_token: str): |
| 118 | + app.state.auth.revoke_refresh(refresh_token) |
| 119 | + return {"ok": True} |
| 120 | +``` |
| 121 | + |
| 122 | +`RevocationList` is in-memory only. For multi-process deployments, swap in a Redis-backed implementation (planned in v0.2.0). |
| 123 | + |
| 124 | +## Password hashing |
| 125 | + |
| 126 | +```python |
| 127 | +from hawkapi_auth import hash_password, verify_password, needs_rehash |
| 128 | + |
| 129 | +h = hash_password("hunter2") # argon2id |
| 130 | +ok = verify_password("hunter2", h) # constant-time, returns bool |
| 131 | +if needs_rehash(h): |
| 132 | + h = hash_password("hunter2") # re-hash after a successful login |
| 133 | +``` |
| 134 | + |
| 135 | +`verify_password` never raises — safe to use directly in handler bodies. |
| 136 | + |
| 137 | +## What's not included (v0.2.0 roadmap) |
| 138 | + |
| 139 | +* Social OAuth providers (Google / GitHub / Discord / Microsoft). |
| 140 | +* Email-based password reset + verification flows. |
| 141 | +* Pre-built user model and storage. |
| 142 | +* Redis-backed `RevocationList`. |
| 143 | + |
| 144 | +## Development |
| 145 | + |
| 146 | +```bash |
| 147 | +git clone https://github.com/ashimov/hawkapi-auth.git |
| 148 | +cd hawkapi-auth |
| 149 | +uv sync --extra dev |
| 150 | +uv run pytest -q |
| 151 | +uv run ruff check . && uv run ruff format --check . |
| 152 | +uv run pyright src/ |
| 153 | +``` |
| 154 | + |
| 155 | +## License |
| 156 | + |
| 157 | +MIT. |
0 commit comments