neva-auth

Authentication & identity toolkit for the Neva framework — Laravel philosophy, framework-agnostic core, composable so you adopt only the slice you need.

Design: see DESIGN.md for the full architecture, contracts, schema, composability rules, v1 scope, and roadmap.

Status

The framework-agnostic core is complete and tested end to end — token engine, contracts, the extensibility model, security events, and the flows below — and is ready to adopt as a token-issuance backbone (bring your own drivers). For what's planned beyond today, see the roadmap in DESIGN.md.

Flows. client_credentials (M2M), authorization_code + PKCE (S256; public and confidential clients), and refresh_token (rotation with reuse detection — replaying a rotated token revokes the whole family) all run through POST /oauth/token; POST /oauth/introspect validates. First-party password login (POST /auth/login, over an agnostic UserProvider) issues tokens, and GET /auth/me resolves the user via the CurrentUser dependency.

Extensibility (DESIGN §7.1). Every pluggable axis with runtime dispatch is a StrategyResolver registry — guards (AuthManager), authn methods (AuthnManager), and OAuth grants (GrantManager) — so a consumer registers its own driver under a name. The token format and backend are boot-time bindings chosen by config; bring your own by implementing the protocol. The wire token need not carry the jti (a format sets ParsedToken.lookup_key), so reference / split-token schemes plug in unchanged.

Events. The engine emits TokenIssued / TokenRevoked / TokenReuseDetected; the login flow emits LoginSucceeded / LoginFailed. Consumers project these onto their own model for presence or audit — the toolkit ships no presence service (DESIGN §10).

The FastAPI layer lives in neva.auth.http behind the [fastapi] extra and is mounted manually (app.include_router(...)), so neva-auth and neva-fastapi never require each other — the bridge is opt-in.

Modules

Each module ships its own ServiceProvider and (where relevant) its own migrations, so a consumer wires only what they list in config/providers.py. The HTTP layer lives in neva.auth.http (the [fastapi] extra) — never in neva-fastapi, which stays unaware of auth.

Develop

uv sync
poe lint     # ruff check
poe fmt      # ruff format
poe tc       # mypy
poe test     # pytest

asyncio_mode = "auto" is set, so async tests need no @pytest.mark.asyncio.

Contributing

Commits follow Conventional Commits with gitmoji prefixes, enforced by cz_gitmoji. Commitizen is a dev dependency — run cz commit for the guided wizard, or format manually as :gitmoji: type(scope): subject.

Releases are cut per-repo with commitizen from the repo root:

cz bump                          # bump version in pyproject, write CHANGELOG, tag v<version>
git push --follow-tags origin main
uv build && uv publish           # build + publish the wheel/sdist

cz bump derives the level from the commits since the last tag, updates CHANGELOG.md, and runs scripts/retag-with-changelog.sh to rewrite the new tag with the rendered changelog as its annotation.