csrd-auth 0.5.0

Pluggable JWT authentication — authenticators, key providers, and FastAPI dependency factories

csrd-auth

Pluggable JWT authentication for FastAPI — authenticators, key providers, and dependency factories.

Tier 2 (bridge) — depends on csrd-models and csrd-context only.

Installation

pip install "csrd-auth @ git+https://github.com/csrd-api/fastapi-common.git#subdirectory=packages/auth"

Usage

from csrd.auth import (
    JWTAuthenticator,
    StaticKeyProvider,
    create_bearer_dependency,
    create_jwt_bearer,
)

Quick start — JWT bearer dependency

# Standalone (provide your own token_finder)
from csrd.auth import create_jwt_bearer

auth_dep = create_jwt_bearer(
    key="your-secret",
    token_finder=lambda: extract_token_from_request(),
)

When used with csrd.versioning, wire in find_token explicitly:

from csrd.auth import create_jwt_bearer
from csrd.versioning import find_token

auth_dep = create_jwt_bearer(key="your-secret", token_finder=find_token)

Authenticators

Class	Strategy
JWTAuthenticator	Decode & verify JWT locally via PyJWT
StaticAuthenticator	Accept a fixed token (dev/testing)
RemoteAuthenticator	Validate via upstream HTTP endpoint
CallbackAuthenticator	Delegate to any sync/async callable
ChainedAuthenticator	Try multiple authenticators in order

Key Providers

Class	Strategy
StaticKeyProvider	Fixed string, bytes, or SecretStr
EnvKeyProvider	Read from app.state or settings loader
JWKSKeyProvider	Fetch from JWKS endpoint (cached with TTL)
MultiKeyProvider	Route by kid header or try all
CallbackKeyProvider	Delegate to any callable

Protocols

• Authenticator — (Request, str) -> UserClaims
• KeyProvider — (token_headers, app) -> key

Both are @runtime_checkable protocols.

Dependency Tier

Tier 1      csrd.models  csrd.lifespan  csrd.context
Tier 2      csrd.auth  csrd.logging  csrd.delegate  csrd.repository  csrd.service
Tier 3      csrd.versioning

csrd.auth depends only on csrd.models (for UserClaims) and csrd.context (for user_info_context). It has no dependency on csrd.versioning.