austial-auth 0.2.0__tar.gz

austial_auth-0.2.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+.env
+*.db
+.pytest_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.DS_Store

austial_auth-0.2.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.5
+Name: austial-auth
+Version: 0.2.0
+Summary: Authentication primitives -- Argon2 hasher, JWT strategy, TOTP MFA, AuthGuard, refresh-token store -- mirrors @nestjs/passport + @nestjs/jwt.
+Requires-Python: >=3.11
+Requires-Dist: argon2-cffi>=23.1.0
+Requires-Dist: austial-common
+Requires-Dist: austial-core
+Requires-Dist: pyjwt>=2.9.0
+Requires-Dist: pyotp>=2.9.0

austial_auth-0.2.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "austial-auth"
+dynamic = ["version"]
+description = "Authentication primitives -- Argon2 hasher, JWT strategy, TOTP MFA, AuthGuard, refresh-token store -- mirrors @nestjs/passport + @nestjs/jwt."
+requires-python = ">=3.11"
+dependencies = [
+    "austial-common",
+    "austial-core",
+    "argon2-cffi>=23.1.0",
+    "pyjwt>=2.9.0",
+    "pyotp>=2.9.0",
+]
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/austial"]
+
+[tool.uv.sources]
+austial-common = { workspace = true }
+austial-core = { workspace = true }
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+root = "../.."

austial_auth-0.2.0/src/austial/auth/__init__.py

@@ -0,0 +1,57 @@
+"""``austial.auth`` -- authentication primitives.
+
+Ships an ``AuthModule.for_root(...)`` dynamic module, an ``Argon2Hasher`` (OWASP-recommended
+password hashing), a ``JwtStrategy`` (short-lived access + opaque rotating refresh tokens),
+a ``TotpStrategy`` (RFC 6238 MFA), an ``AuthGuard`` (bearer-token verification), the
+``@Public`` decorator to skip that guard, and a ``CurrentUser`` param decorator to inject
+the authenticated principal into a handler. The product supplies the user model and the
+persistent refresh-token store (an in-memory default is provided for tests).
+
+Design mirrors ``@nestjs/passport`` + ``@nestjs/jwt``: the framework provides *strategies*
+and *guards*; product wires them together against its own user entity. Everything is
+side-effect-free and testable in isolation.
+"""
+
+from austial.auth.argon2_hasher import Argon2Hasher, PasswordHasher, PasswordVerificationError
+from austial.auth.auth_guard import AuthGuard, AuthPrincipal
+from austial.auth.auth_module import AuthModule
+from austial.auth.auth_service import AuthService
+from austial.auth.config import AuthConfig
+from austial.auth.decorators import IS_PUBLIC_METADATA, CurrentUser, Public
+from austial.auth.errors import (
+    AuthenticationError,
+    InvalidTokenError,
+    MfaRequiredError,
+    TokenExpiredError,
+)
+from austial.auth.jwt_strategy import JwtStrategy, TokenPayload
+from austial.auth.refresh_token_store import (
+    InMemoryRefreshTokenStore,
+    RefreshTokenRecord,
+    RefreshTokenStore,
+)
+from austial.auth.totp_strategy import TotpStrategy
+
+__all__ = [
+    "Argon2Hasher",
+    "AuthConfig",
+    "AuthenticationError",
+    "AuthGuard",
+    "AuthModule",
+    "AuthPrincipal",
+    "AuthService",
+    "CurrentUser",
+    "InMemoryRefreshTokenStore",
+    "InvalidTokenError",
+    "IS_PUBLIC_METADATA",
+    "JwtStrategy",
+    "MfaRequiredError",
+    "PasswordHasher",
+    "PasswordVerificationError",
+    "Public",
+    "RefreshTokenRecord",
+    "RefreshTokenStore",
+    "TokenExpiredError",
+    "TokenPayload",
+    "TotpStrategy",
+]

austial_auth-0.2.0/src/austial/auth/argon2_hasher.py

@@ -0,0 +1,73 @@
+"""``Argon2Hasher`` -- OWASP ASVS L2 password hashing.
+
+Argon2id with defaults calibrated to OWASP's 2024 recommendations for interactive
+authentication (>=19 MiB memory, >=2 iterations, 1 lane). The hasher is stateless and
+injectable; callers use ``hash()`` at registration/password-change and ``verify()`` at
+login, and check ``needs_rehash()`` to opportunistically upgrade older hashes.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from argon2 import PasswordHasher as _Argon2
+from argon2.exceptions import InvalidHashError, VerifyMismatchError
+
+from austial.common.decorators.injectable import Injectable
+
+
+class PasswordVerificationError(Exception):
+    """Raised when the supplied password does not match the stored hash."""
+
+
+@runtime_checkable
+class PasswordHasher(Protocol):
+    """Injectable interface: any hasher that implements these three methods
+    is a drop-in replacement for ``Argon2Hasher`` (useful in tests)."""
+
+    def hash(self, password: str) -> str: ...
+
+    def verify(self, password: str, encoded: str) -> None: ...
+
+    def needs_rehash(self, encoded: str) -> bool: ...
+
+
+@Injectable()
+class Argon2Hasher:
+    """Argon2id password hasher. Defaults tuned to OWASP's 2024 interactive-login profile."""
+
+    def __init__(
+        self,
+        *,
+        time_cost: int = 2,
+        memory_cost: int = 19 * 1024,  # 19 MiB, per OWASP 2024 minimum
+        parallelism: int = 1,
+        hash_len: int = 32,
+        salt_len: int = 16,
+    ) -> None:
+        self._hasher = _Argon2(
+            time_cost=time_cost,
+            memory_cost=memory_cost,
+            parallelism=parallelism,
+            hash_len=hash_len,
+            salt_len=salt_len,
+        )
+
+    def hash(self, password: str) -> str:
+        """Return a PHC-string-encoded Argon2id hash of ``password``."""
+        return self._hasher.hash(password)
+
+    def verify(self, password: str, encoded: str) -> None:
+        """Verify ``password`` against ``encoded``; raise ``PasswordVerificationError``
+        on any mismatch or malformed hash. Callers should treat all failures identically
+        to avoid leaking why authentication failed."""
+        try:
+            self._hasher.verify(encoded, password)
+        except (VerifyMismatchError, InvalidHashError) as exc:
+            raise PasswordVerificationError("password verification failed") from exc
+
+    def needs_rehash(self, encoded: str) -> bool:
+        """True if ``encoded`` was produced with older parameters and should be rehashed
+        with the current profile on next successful login. Callers should silently
+        rehash + persist to keep pace with parameter upgrades."""
+        return self._hasher.check_needs_rehash(encoded)

austial_auth-0.2.0/src/austial/auth/auth_guard.py

@@ -0,0 +1,67 @@
+"""``AuthGuard`` -- bearer-token verification for every request.
+
+Runs before the handler (see the request pipeline in ``austial.core``). Skips routes
+marked ``@Public``. On success, populates ``request.state.user`` with an
+``AuthPrincipal`` so ``CurrentUser`` can retrieve it. On failure, raises
+``UnauthorizedException`` (401).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from austial.auth.decorators import is_public
+from austial.auth.errors import AuthenticationError, InvalidTokenError
+from austial.auth.jwt_strategy import JwtStrategy, TokenPayload
+from austial.common.decorators.injectable import Injectable
+from austial.common.guards.base import CanActivate, ExecutionContext
+
+
+@dataclass(frozen=True, slots=True)
+class AuthPrincipal:
+    """The authenticated caller. ``subject`` is the user id; ``claims`` is the JWT
+    payload minus system claims. Accessible via ``CurrentUser()`` or
+    ``request.state.user``."""
+
+    subject: str
+    claims: dict[str, Any]
+    token_id: str | None = None
+
+
+@Injectable()
+class AuthGuard(CanActivate):
+    """Verifies a ``Bearer`` token from the ``Authorization`` header via ``JwtStrategy``.
+
+    Product code can subclass this to enforce additional claims (tenant, roles, session
+    freshness) after the base verification succeeds -- override ``after_verify`` and
+    raise ``UnauthorizedException`` to reject."""
+
+    def __init__(self, jwt_strategy: JwtStrategy) -> None:
+        self._jwt = jwt_strategy
+
+    async def can_activate(self, context: ExecutionContext) -> bool:
+        handler = context.get_handler()
+        controller = context.get_class()
+        if is_public(handler) or is_public(controller):
+            return True
+
+        request = context.get_request()
+        header = request.headers.get("Authorization", "")
+        if not header or not header.lower().startswith("bearer "):
+            raise AuthenticationError("missing bearer token")
+
+        token = header.split(" ", 1)[1].strip()
+        if not token:
+            raise InvalidTokenError("empty bearer token")
+
+        payload = self._jwt.verify(token)
+        principal = AuthPrincipal(subject=payload.subject, claims=payload.claims, token_id=payload.token_id)
+        await self.after_verify(request, payload, principal)
+        request.state.user = principal
+        return True
+
+    async def after_verify(self, request: Any, payload: TokenPayload, principal: AuthPrincipal) -> None:
+        """Hook for subclasses to add checks (e.g. session revocation) after the
+        base signature/expiry checks pass. Raise an exception to reject."""
+        # base implementation intentionally does nothing

austial_auth-0.2.0/src/austial/auth/auth_module.py

@@ -0,0 +1,89 @@
+"""``AuthModule.for_root(...)`` -- wires ``JwtStrategy``, ``TotpStrategy``,
+``Argon2Hasher``, ``AuthGuard`` and (optionally) an in-memory refresh-token store
+into the DI container.
+
+Product code overrides the refresh-token store with a persistent implementation
+by passing ``refresh_token_store=MyPersistentStore``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from austial.auth.argon2_hasher import Argon2Hasher, PasswordHasher
+from austial.auth.auth_guard import AuthGuard
+from austial.auth.auth_service import AuthService
+from austial.auth.config import AuthConfig
+from austial.auth.jwt_strategy import JwtStrategy
+from austial.auth.refresh_token_store import InMemoryRefreshTokenStore, RefreshTokenStore
+from austial.auth.totp_strategy import TotpStrategy
+from austial.common.decorators.modules import Module
+from austial.core.dynamic_module import DynamicModule
+
+
+@Module()
+class AuthModule:
+    """Import via ``AuthModule.for_root(config, refresh_token_store=...)`` in ``AppModule``'s
+    ``imports=[...]``. Registered ``@Global`` by default so any module can inject
+    ``JwtStrategy``, ``TotpStrategy``, ``PasswordHasher``, ``AuthService`` and ``AuthGuard``."""
+
+    @staticmethod
+    def for_root(
+        config: AuthConfig,
+        *,
+        refresh_token_store: type | RefreshTokenStore | None = None,
+        password_hasher: type | PasswordHasher | None = None,
+        is_global: bool = True,
+    ) -> DynamicModule:
+        jwt = JwtStrategy(
+            secret=config.jwt_secret,
+            issuer=config.issuer,
+            algorithm=config.algorithm,
+            access_ttl=config.access_ttl,
+        )
+        totp = TotpStrategy(
+            issuer=config.issuer,
+            digits=config.totp_digits,
+            window=config.totp_window,
+        )
+        hasher: PasswordHasher = (
+            Argon2Hasher() if password_hasher is None or isinstance(password_hasher, type) else password_hasher
+        )
+        # A class (not an instance) is registered with ``useClass`` so the container can inject its own
+        # dependencies -- a persistent store needs repositories, which do not exist before DI runs.
+        store_provider: Any = (
+            {"provide": RefreshTokenStore, "useClass": refresh_token_store}
+            if isinstance(refresh_token_store, type)
+            else {"provide": RefreshTokenStore, "useValue": refresh_token_store or InMemoryRefreshTokenStore()}
+        )
+        hasher_provider: Any = (
+            {"provide": PasswordHasher, "useClass": password_hasher}
+            if isinstance(password_hasher, type)
+            else {"provide": PasswordHasher, "useValue": hasher}
+        )
+
+        providers: list[Any] = [
+            {"provide": JwtStrategy, "useValue": jwt},
+            {"provide": TotpStrategy, "useValue": totp},
+            hasher_provider,
+            {"provide": Argon2Hasher, "useValue": hasher if isinstance(hasher, Argon2Hasher) else Argon2Hasher()},
+            store_provider,
+            {"provide": AuthConfig, "useValue": config},
+            AuthService,
+            AuthGuard,
+        ]
+
+        return DynamicModule(
+            module=AuthModule,
+            providers=providers,
+            exports=[
+                JwtStrategy,
+                TotpStrategy,
+                PasswordHasher,
+                Argon2Hasher,
+                RefreshTokenStore,
+                AuthConfig,
+                AuthService,
+                AuthGuard,
+            ],
+        )

austial_auth-0.2.0/src/austial/auth/auth_service.py

@@ -0,0 +1,112 @@
+"""``AuthService`` -- orchestrates login/refresh/logout on top of the strategies.
+
+The service is agnostic to the user model: the product calls
+``verify_password(...)`` with the stored hash it already loaded from its user
+table, and ``issue_tokens(subject, claims)`` to mint the access + refresh pair.
+This keeps the framework decoupled from persistence.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+from austial.auth.argon2_hasher import PasswordHasher, PasswordVerificationError
+from austial.auth.config import AuthConfig
+from austial.auth.errors import AuthenticationError, MfaRequiredError
+from austial.auth.jwt_strategy import JwtStrategy
+from austial.auth.refresh_token_store import RefreshTokenRecord, RefreshTokenStore
+from austial.auth.totp_strategy import TotpStrategy
+from austial.common.decorators.injectable import Injectable
+
+#: ``claims`` for :meth:`AuthService.refresh` may be a callable that receives the *rotated* token's record
+#: and returns the access-token claims (sync or async). Needed because the claims usually depend on what
+#: the record points at (its session, the subject's current tenant/roles), which is only known once the
+#: refresh token has been resolved.
+ClaimsProvider = Callable[[RefreshTokenRecord], dict[str, Any] | Awaitable[dict[str, Any]]]
+
+
+@dataclass(frozen=True, slots=True)
+class TokenPair:
+    """Returned to the caller on login/refresh."""
+
+    access_token: str
+    refresh_token: str
+    expires_in_seconds: int
+
+
+@Injectable()
+class AuthService:
+    def __init__(
+        self,
+        jwt: JwtStrategy,
+        totp: TotpStrategy,
+        hasher: PasswordHasher,
+        refresh_store: RefreshTokenStore,
+        config: AuthConfig,
+    ) -> None:
+        self._jwt = jwt
+        self._totp = totp
+        self._hasher = hasher
+        self._refresh_store = refresh_store
+        self._config = config
+
+    def verify_password(self, password: str, encoded: str) -> None:
+        """Raise ``AuthenticationError`` on any mismatch. Never leak which failure."""
+        try:
+            self._hasher.verify(password, encoded)
+        except PasswordVerificationError as exc:
+            raise AuthenticationError("invalid credentials") from exc
+
+    def require_mfa(self, secret: str, code: str | None) -> None:
+        """Raise ``MfaRequiredError`` if MFA is enrolled and ``code`` is missing or invalid."""
+        if secret and not (code and self._totp.verify(secret, code)):
+            raise MfaRequiredError()
+
+    async def issue_tokens(
+        self, subject: str, *, claims: dict[str, Any] | None = None, session_id: str | None = None
+    ) -> TokenPair:
+        access = self._jwt.sign(subject, claims=claims)
+        opaque, _ = await self._refresh_store.issue(subject, ttl=self._config.refresh_ttl, session_id=session_id)
+        return TokenPair(
+            access_token=access,
+            refresh_token=opaque,
+            expires_in_seconds=int(self._config.access_ttl.total_seconds()),
+        )
+
+    async def refresh(
+        self, opaque_refresh_token: str, *, claims: dict[str, Any] | ClaimsProvider | None = None
+    ) -> TokenPair:
+        """Rotate the refresh token and mint a fresh access token.
+
+        ``claims`` is either a fixed dict or a ``ClaimsProvider`` called with the rotated token's
+        ``RefreshTokenRecord`` -- use the latter to derive the claims from the record's ``session_id`` /
+        ``subject`` (an exception raised by the provider, e.g. ``AuthenticationError`` for a
+        deactivated account, propagates to the caller)."""
+        try:
+            new_opaque, record = await self._refresh_store.rotate(opaque_refresh_token, ttl=self._config.refresh_ttl)
+        except LookupError as exc:
+            raise AuthenticationError("invalid refresh token") from exc
+
+        resolved: dict[str, Any] | None
+        if callable(claims):
+            produced = claims(record)
+            resolved = await produced if inspect.isawaitable(produced) else produced
+        else:
+            resolved = claims
+        access = self._jwt.sign(record.subject, claims=resolved)
+        return TokenPair(
+            access_token=access,
+            refresh_token=new_opaque,
+            expires_in_seconds=int(self._config.access_ttl.total_seconds()),
+        )
+
+    async def logout(self, opaque_refresh_token: str) -> None:
+        await self._refresh_store.revoke(opaque_refresh_token)
+
+    async def logout_everywhere(self, subject: str) -> int:
+        """Revoke every refresh token for ``subject`` (password change, MFA re-enrol,
+        admin action)."""
+        return await self._refresh_store.revoke_all_for_subject(subject)

austial_auth-0.2.0/src/austial/auth/config.py

@@ -0,0 +1,24 @@
+"""``AuthConfig`` -- configuration passed to ``AuthModule.for_root(...)``.
+
+Lives in its own module so ``AuthService`` (which needs the TTLs) can import it
+without pulling in ``AuthModule`` (which needs ``AuthService`` in its providers).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import timedelta
+
+
+@dataclass(frozen=True, slots=True)
+class AuthConfig:
+    """Every field is required so that a misconfiguration is a startup error,
+    not a runtime surprise."""
+
+    jwt_secret: str
+    issuer: str
+    algorithm: str = "HS256"
+    access_ttl: timedelta = timedelta(minutes=15)
+    refresh_ttl: timedelta = timedelta(days=14)
+    totp_digits: int = 6
+    totp_window: int = 1

austial_auth-0.2.0/src/austial/auth/decorators.py

@@ -0,0 +1,53 @@
+"""Decorators: ``@Public`` and ``CurrentUser``.
+
+``@Public`` marks a route as unauthenticated -- ``AuthGuard`` checks for this
+metadata and short-circuits.
+
+``CurrentUser`` binds the authenticated principal (``request.state.user``, set by
+``AuthGuard``) into a handler parameter, resolved *after* every guard for the route has
+run -- unlike a plain FastAPI ``Depends``, which would resolve before the guard loop and
+always see an empty ``request.state`` (see ``austial.common.FromRequestState``). If no
+guard ran (e.g. the route is ``@Public``) the value is ``None``, so handlers can accept
+an optional user cleanly.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from austial.common.decorators.params import FromRequestState
+from austial.core.metadata import get_metadata, set_metadata
+
+IS_PUBLIC_METADATA = "austial:auth:is_public"
+
+
+def Public() -> Callable:  # noqa: N802 - decorator naming mirrors Nest's ``@Public()``
+    """Mark a controller class or a single route handler as public. ``AuthGuard``
+    treats a decorated target as unauthenticated and allows the request through."""
+
+    def decorator(target):
+        set_metadata(IS_PUBLIC_METADATA, True)(target)
+        return target
+
+    return decorator
+
+
+def is_public(target: Any) -> bool:
+    """Return ``True`` if ``target`` (a handler or its owning class) is marked public."""
+    return bool(get_metadata(IS_PUBLIC_METADATA, target, False))
+
+
+def CurrentUser() -> Any:  # noqa: N802 - Nest-parity naming
+    """Inject the authenticated principal (set by ``AuthGuard``) into a handler
+    parameter. Returns ``None`` on a ``@Public`` route.
+
+    Usage::
+
+        @Controller("/me")
+        class MeController:
+            @Get()
+            def me(self, user=CurrentUser()):
+                return {"id": user.subject}
+    """
+    return FromRequestState("user", default=None)

austial_auth-0.2.0/src/austial/auth/errors.py

@@ -0,0 +1,38 @@
+"""Auth-specific exceptions.
+
+These extend Austial's ``UnauthorizedException`` so the framework's exception dispatch
+maps them to ``401`` without a translation layer, but each carries a distinct type so a
+product-level filter can render a different response body if it wants to.
+"""
+
+from __future__ import annotations
+
+from austial.common.exceptions import UnauthorizedException
+
+
+class AuthenticationError(UnauthorizedException):
+    """Base for authentication failures."""
+
+    def __init__(self, message: str = "Authentication failed"):
+        super().__init__(message)
+
+
+class InvalidTokenError(AuthenticationError):
+    """The token is malformed, has a bad signature, or fails claims validation."""
+
+    def __init__(self, message: str = "Invalid token"):
+        super().__init__(message)
+
+
+class TokenExpiredError(AuthenticationError):
+    """The token's ``exp`` claim is in the past."""
+
+    def __init__(self, message: str = "Token expired"):
+        super().__init__(message)
+
+
+class MfaRequiredError(AuthenticationError):
+    """A valid password was supplied but MFA verification is still pending."""
+
+    def __init__(self, message: str = "MFA required"):
+        super().__init__(message)

austial_auth-0.2.0/src/austial/auth/jwt_strategy.py

@@ -0,0 +1,118 @@
+"""``JwtStrategy`` -- short-lived HS256 access tokens (default 15 min).
+
+Design notes:
+
+- **Access tokens are the JWT.** They are short-lived and self-contained: the app can
+  authenticate a request from the token alone, without a database call.
+- **Refresh tokens are NOT JWTs**; they are opaque strings persisted in a
+  ``RefreshTokenStore`` so that they can be revoked. This is issued and rotated by
+  ``AuthService``, not here -- ``JwtStrategy`` only signs/verifies JWTs.
+- Signing uses HS256 by default (the config supplies the secret). Callers who need
+  RS256 pass ``algorithm="RS256"`` and a PEM key pair; the strategy stays the same.
+- Every token carries ``iss``, ``iat``, ``exp``, ``jti``, and application claims. The
+  ``jti`` gives you the hook for token-level revocation if you ever want it, without
+  changing the wire format.
+"""
+
+from __future__ import annotations
+
+import secrets
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+import jwt as _jwt
+
+from austial.auth.errors import InvalidTokenError, TokenExpiredError
+from austial.common.decorators.injectable import Injectable
+
+
+@dataclass(frozen=True, slots=True)
+class TokenPayload:
+    """Decoded JWT contents surfaced to callers.
+
+    ``subject`` is the user identifier; ``claims`` is the application-defined payload
+    (tenant id, roles, session id -- whatever was passed to ``sign()``). System claims
+    (``iss``, ``iat``, ``exp``, ``jti``) are surfaced as top-level fields.
+    """
+
+    subject: str
+    claims: dict[str, Any] = field(default_factory=dict)
+    issuer: str | None = None
+    issued_at: datetime | None = None
+    expires_at: datetime | None = None
+    token_id: str | None = None
+
+
+@Injectable()
+class JwtStrategy:
+    """Signs and verifies HS256/RS256 access tokens."""
+
+    def __init__(
+        self,
+        *,
+        secret: str,
+        issuer: str,
+        algorithm: str = "HS256",
+        access_ttl: timedelta = timedelta(minutes=15),
+        clock_skew_seconds: int = 30,
+    ) -> None:
+        if not secret or len(secret) < 32:
+            raise ValueError("JWT secret must be at least 32 characters (see OWASP ASVS V6)")
+        self._secret = secret
+        self._issuer = issuer
+        self._algorithm = algorithm
+        self._access_ttl = access_ttl
+        self._clock_skew_seconds = clock_skew_seconds
+
+    def sign(self, subject: str, claims: dict[str, Any] | None = None, *, ttl: timedelta | None = None) -> str:
+        """Sign a JWT for ``subject`` with application ``claims``.
+
+        Passing ``ttl`` overrides the strategy default (useful for step-up MFA
+        tokens or short-lived one-time actions)."""
+        now = datetime.now(UTC)
+        payload: dict[str, Any] = {
+            **(claims or {}),
+            "iss": self._issuer,
+            "sub": subject,
+            "iat": int(now.timestamp()),
+            "exp": int((now + (ttl or self._access_ttl)).timestamp()),
+            "jti": secrets.token_urlsafe(16),
+        }
+        return _jwt.encode(payload, self._secret, algorithm=self._algorithm)
+
+    def verify(self, token: str) -> TokenPayload:
+        """Verify ``token``; raise ``TokenExpiredError`` or ``InvalidTokenError`` on failure.
+
+        The caller decides what to do with the decoded payload; this method never
+        touches the database and is safe to call from a guard."""
+        try:
+            data = _jwt.decode(
+                token,
+                self._secret,
+                algorithms=[self._algorithm],
+                issuer=self._issuer,
+                leeway=self._clock_skew_seconds,
+            )
+        except _jwt.ExpiredSignatureError as exc:
+            raise TokenExpiredError() from exc
+        except _jwt.InvalidTokenError as exc:  # covers signature, issuer, malformed
+            raise InvalidTokenError(str(exc)) from exc
+
+        subject = data.pop("sub", None)
+        if subject is None:
+            raise InvalidTokenError("token missing 'sub' claim")
+
+        issuer = data.pop("iss", None)
+        iat = data.pop("iat", None)
+        exp = data.pop("exp", None)
+        jti = data.pop("jti", None)
+
+        return TokenPayload(
+            subject=str(subject),
+            claims=data,
+            issuer=issuer,
+            issued_at=datetime.fromtimestamp(iat, UTC) if iat is not None else None,
+            expires_at=datetime.fromtimestamp(exp, UTC) if exp is not None else None,
+            token_id=jti,
+        )

austial_auth-0.2.0/src/austial/auth/refresh_token_store.py

@@ -0,0 +1,129 @@
+"""Refresh-token store contract + in-memory reference implementation.
+
+Refresh tokens are opaque, rotating, and revocable. The framework defines the
+contract; the product supplies a persistent implementation (typically an
+append-only table via ``austial.orm``) so tokens can be revoked on password
+change, MFA re-enrolment, or explicit sign-out. The in-memory implementation is
+useful in tests and in local dev without a database.
+"""
+
+from __future__ import annotations
+
+import secrets
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from typing import Protocol, runtime_checkable
+
+from austial.common.decorators.injectable import Injectable
+
+
+@dataclass(frozen=True, slots=True)
+class RefreshTokenRecord:
+    """One row in a refresh-token store."""
+
+    token_id: str
+    subject: str
+    expires_at: datetime
+    revoked_at: datetime | None = None
+    session_id: str | None = None
+
+
+@runtime_checkable
+class RefreshTokenStore(Protocol):
+    """Inject this interface; supply an implementation from the product's persistence layer."""
+
+    async def issue(
+        self, subject: str, *, ttl: timedelta, session_id: str | None = None
+    ) -> tuple[str, RefreshTokenRecord]:
+        """Return ``(opaque_token, record)``. The opaque token is what the client keeps."""
+        ...
+
+    async def rotate(self, opaque_token: str, *, ttl: timedelta) -> tuple[str, RefreshTokenRecord]:
+        """Revoke the presented token and issue a replacement in one atomic step.
+        Raises ``LookupError`` if the token is unknown, expired, or already revoked."""
+        ...
+
+    async def revoke(self, opaque_token: str) -> None:
+        """Idempotent: revoking an unknown or already-revoked token is a no-op."""
+        ...
+
+    async def revoke_all_for_subject(self, subject: str) -> int:
+        """Revoke every active refresh token for ``subject``; return the count revoked."""
+        ...
+
+
+@Injectable()
+class InMemoryRefreshTokenStore:
+    """Reference implementation for tests and local dev.
+
+    Tokens are hashed before storage (SHA-256) so a memory dump does not surrender them
+    verbatim; the raw opaque token is only ever held by the caller. Not for production."""
+
+    def __init__(self) -> None:
+        self._records: dict[str, RefreshTokenRecord] = {}
+
+    def _hash(self, opaque: str) -> str:
+        import hashlib
+
+        return hashlib.sha256(opaque.encode()).hexdigest()
+
+    async def issue(
+        self, subject: str, *, ttl: timedelta, session_id: str | None = None
+    ) -> tuple[str, RefreshTokenRecord]:
+        opaque = secrets.token_urlsafe(48)
+        token_id = self._hash(opaque)
+        record = RefreshTokenRecord(
+            token_id=token_id,
+            subject=subject,
+            expires_at=datetime.now(UTC) + ttl,
+            session_id=session_id,
+        )
+        self._records[token_id] = record
+        return opaque, record
+
+    async def rotate(self, opaque_token: str, *, ttl: timedelta) -> tuple[str, RefreshTokenRecord]:
+        token_id = self._hash(opaque_token)
+        existing = self._records.get(token_id)
+        if existing is None:
+            raise LookupError("unknown refresh token")
+        if existing.revoked_at is not None:
+            raise LookupError("refresh token already revoked")
+        if existing.expires_at < datetime.now(UTC):
+            raise LookupError("refresh token expired")
+
+        self._records[token_id] = RefreshTokenRecord(
+            token_id=existing.token_id,
+            subject=existing.subject,
+            expires_at=existing.expires_at,
+            revoked_at=datetime.now(UTC),
+            session_id=existing.session_id,
+        )
+        return await self.issue(existing.subject, ttl=ttl, session_id=existing.session_id)
+
+    async def revoke(self, opaque_token: str) -> None:
+        token_id = self._hash(opaque_token)
+        existing = self._records.get(token_id)
+        if existing is None or existing.revoked_at is not None:
+            return
+        self._records[token_id] = RefreshTokenRecord(
+            token_id=existing.token_id,
+            subject=existing.subject,
+            expires_at=existing.expires_at,
+            revoked_at=datetime.now(UTC),
+            session_id=existing.session_id,
+        )
+
+    async def revoke_all_for_subject(self, subject: str) -> int:
+        revoked = 0
+        now = datetime.now(UTC)
+        for token_id, record in list(self._records.items()):
+            if record.subject == subject and record.revoked_at is None:
+                self._records[token_id] = RefreshTokenRecord(
+                    token_id=record.token_id,
+                    subject=record.subject,
+                    expires_at=record.expires_at,
+                    revoked_at=now,
+                    session_id=record.session_id,
+                )
+                revoked += 1
+        return revoked

austial_auth-0.2.0/src/austial/auth/totp_strategy.py

@@ -0,0 +1,58 @@
+"""``TotpStrategy`` -- RFC 6238 TOTP for multi-factor authentication.
+
+Generates enrolment secrets, builds the ``otpauth://`` provisioning URI (the QR-code
+payload authenticators consume), verifies 6-digit codes with a one-window drift
+allowance, and produces recovery codes for the account-recovery flow.
+
+The secret is *not* stored by this class; the product persists it against the user
+record. Every method here is pure/stateless so it is trivial to unit-test.
+"""
+
+from __future__ import annotations
+
+import secrets
+
+import pyotp
+
+from austial.common.decorators.injectable import Injectable
+
+
+@Injectable()
+class TotpStrategy:
+    """RFC 6238 TOTP -- 30-second step, SHA-1 digest, 6-digit codes."""
+
+    def __init__(self, *, issuer: str, digits: int = 6, interval_seconds: int = 30, window: int = 1) -> None:
+        self._issuer = issuer
+        self._digits = digits
+        self._interval = interval_seconds
+        # ``window`` is the number of intervals on either side of "now" we accept, to
+        # absorb clock drift on the client. 1 = ±30 seconds; do not exceed 2 (per ASVS).
+        self._window = min(window, 2)
+
+    def generate_secret(self) -> str:
+        """Return a fresh base32-encoded secret to persist for the user."""
+        return pyotp.random_base32()
+
+    def provisioning_uri(self, secret: str, account_name: str) -> str:
+        """Return the ``otpauth://totp/...`` URI the authenticator app scans."""
+        totp = pyotp.TOTP(secret, digits=self._digits, interval=self._interval)
+        return totp.provisioning_uri(name=account_name, issuer_name=self._issuer)
+
+    def verify(self, secret: str, code: str) -> bool:
+        """Constant-time TOTP verification with one-window drift allowance."""
+        if not code or not code.isdigit() or len(code) != self._digits:
+            return False
+        totp = pyotp.TOTP(secret, digits=self._digits, interval=self._interval)
+        return totp.verify(code, valid_window=self._window)
+
+    def generate_recovery_codes(self, count: int = 10, *, group_size: int = 5) -> list[str]:
+        """Return ``count`` cryptographically-random single-use recovery codes.
+
+        Codes are grouped for human readability (``ABCDE-FGHIJ``); persist them **hashed**
+        (via ``Argon2Hasher``) so that a database leak does not compromise them."""
+        codes: list[str] = []
+        alphabet = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"  # no ambiguous glyphs
+        for _ in range(count):
+            raw = "".join(secrets.choice(alphabet) for _ in range(group_size * 2))
+            codes.append(f"{raw[:group_size]}-{raw[group_size:]}")
+        return codes

austial_auth-0.2.0/test/auth_spec.py

@@ -0,0 +1,271 @@
+"""``austial.auth`` unit tests.
+
+Covers the five load-bearing behaviours a product depends on:
+
+- Argon2 hash-and-verify round-trip; a wrong password fails; a hash produced with
+  weaker parameters is flagged for rehash.
+- JWT sign-and-verify round-trip; an expired token surfaces ``TokenExpiredError``;
+  a tampered token surfaces ``InvalidTokenError``.
+- TOTP secret-and-verify round-trip; the wrong code fails; recovery codes are unique
+  and correctly grouped.
+- ``InMemoryRefreshTokenStore`` issue → rotate → revoke lifecycle.
+- ``AuthGuard`` allows ``@Public`` routes, rejects requests without a bearer token,
+  and populates ``request.state.user`` on a valid token.
+"""
+
+from __future__ import annotations
+
+from datetime import timedelta
+from types import SimpleNamespace
+
+import pytest
+
+from austial.auth import (
+    Argon2Hasher,
+    AuthConfig,
+    AuthGuard,
+    AuthPrincipal,
+    AuthService,
+    InMemoryRefreshTokenStore,
+    InvalidTokenError,
+    JwtStrategy,
+    PasswordVerificationError,
+    Public,
+    TokenExpiredError,
+    TotpStrategy,
+)
+from austial.common import ExecutionContext
+from austial.common.exceptions import UnauthorizedException
+
+
+class _FakeExecutionContext(ExecutionContext):
+    def __init__(self, request, controller_class, handler):
+        self._request = request
+        self._controller_class = controller_class
+        self._handler = handler
+
+    def get_request(self):
+        return self._request
+
+    def get_class(self):
+        return self._controller_class
+
+    def get_handler(self):
+        return self._handler
+
+
+def _fake_request(headers: dict[str, str] | None = None):
+    class _State:
+        pass
+
+    return SimpleNamespace(headers=headers or {}, state=_State())
+
+
+# ---------------------------------------------------------------------------
+# Argon2Hasher
+
+
+def test_argon2_hash_and_verify_round_trip():
+    hasher = Argon2Hasher()
+    encoded = hasher.hash("hunter2!")
+    hasher.verify("hunter2!", encoded)  # must not raise
+
+
+def test_argon2_verify_rejects_wrong_password():
+    hasher = Argon2Hasher()
+    encoded = hasher.hash("hunter2!")
+    with pytest.raises(PasswordVerificationError):
+        hasher.verify("nope", encoded)
+
+
+def test_argon2_needs_rehash_flags_weaker_parameters():
+    weak = Argon2Hasher(time_cost=1, memory_cost=8 * 1024, parallelism=1)
+    strong = Argon2Hasher(time_cost=3, memory_cost=64 * 1024, parallelism=2)
+    old = weak.hash("hunter2!")
+    assert strong.needs_rehash(old) is True
+
+
+# ---------------------------------------------------------------------------
+# JwtStrategy
+
+
+def _jwt() -> JwtStrategy:
+    return JwtStrategy(secret="x" * 40, issuer="austial-tests", access_ttl=timedelta(minutes=15))
+
+
+def test_jwt_sign_and_verify_round_trip():
+    jwt = _jwt()
+    token = jwt.sign("user-1", claims={"tenant": "acme", "roles": ["ops"]})
+    decoded = jwt.verify(token)
+    assert decoded.subject == "user-1"
+    assert decoded.claims == {"tenant": "acme", "roles": ["ops"]}
+    assert decoded.issuer == "austial-tests"
+    assert decoded.token_id is not None
+
+
+def test_jwt_rejects_expired_token():
+    # ttl beyond the default 30s clock-skew leeway
+    jwt = JwtStrategy(secret="x" * 40, issuer="austial-tests", access_ttl=timedelta(seconds=-120))
+    token = jwt.sign("user-1")
+    with pytest.raises(TokenExpiredError):
+        jwt.verify(token)
+
+
+def test_jwt_rejects_tampered_signature():
+    jwt = _jwt()
+    token = jwt.sign("user-1")
+    tampered = token[:-2] + ("aa" if not token.endswith("aa") else "bb")
+    with pytest.raises(InvalidTokenError):
+        jwt.verify(tampered)
+
+
+def test_jwt_secret_must_be_long_enough():
+    with pytest.raises(ValueError):
+        JwtStrategy(secret="short", issuer="x")
+
+
+# ---------------------------------------------------------------------------
+# TotpStrategy
+
+
+def test_totp_secret_and_verify_round_trip():
+    totp = TotpStrategy(issuer="austial-tests")
+    secret = totp.generate_secret()
+    import pyotp
+
+    code = pyotp.TOTP(secret).now()
+    assert totp.verify(secret, code) is True
+
+
+def test_totp_rejects_wrong_code():
+    totp = TotpStrategy(issuer="austial-tests")
+    secret = totp.generate_secret()
+    assert totp.verify(secret, "000000") is False
+    assert totp.verify(secret, "abc") is False
+    assert totp.verify(secret, "") is False
+
+
+def test_totp_recovery_codes_are_unique_and_formatted():
+    totp = TotpStrategy(issuer="austial-tests")
+    codes = totp.generate_recovery_codes(count=8, group_size=5)
+    assert len(codes) == 8
+    assert len(set(codes)) == 8
+    for c in codes:
+        left, _, right = c.partition("-")
+        assert len(left) == 5 and len(right) == 5
+
+
+def test_totp_provisioning_uri_is_otpauth():
+    totp = TotpStrategy(issuer="austial-tests")
+    uri = totp.provisioning_uri("SECRETSECRETSECRET", "user@example.com")
+    assert uri.startswith("otpauth://totp/")
+    assert "issuer=austial-tests" in uri
+
+
+# ---------------------------------------------------------------------------
+# InMemoryRefreshTokenStore
+
+
+@pytest.mark.asyncio
+async def test_refresh_store_issue_rotate_revoke_lifecycle():
+    store = InMemoryRefreshTokenStore()
+    opaque, record = await store.issue("user-1", ttl=timedelta(minutes=5))
+    assert record.subject == "user-1"
+
+    new_opaque, new_record = await store.rotate(opaque, ttl=timedelta(minutes=5))
+    assert new_opaque != opaque
+    assert new_record.subject == "user-1"
+
+    # rotating the old token again is now rejected
+    with pytest.raises(LookupError):
+        await store.rotate(opaque, ttl=timedelta(minutes=5))
+
+    await store.revoke(new_opaque)
+    # revoking is idempotent
+    await store.revoke(new_opaque)
+
+
+@pytest.mark.asyncio
+async def test_refresh_store_revoke_all_for_subject():
+    store = InMemoryRefreshTokenStore()
+    await store.issue("u1", ttl=timedelta(minutes=5))
+    await store.issue("u1", ttl=timedelta(minutes=5))
+    await store.issue("u2", ttl=timedelta(minutes=5))
+    revoked = await store.revoke_all_for_subject("u1")
+    assert revoked == 2
+    # calling again reports 0
+    assert await store.revoke_all_for_subject("u1") == 0
+
+
+# ---------------------------------------------------------------------------
+# AuthGuard
+
+
+@pytest.mark.asyncio
+async def test_auth_guard_allows_public_routes():
+    guard = AuthGuard(_jwt())
+
+    @Public()
+    def _handler():
+        pass
+
+    ctx = _FakeExecutionContext(_fake_request(), object, _handler)
+    assert await guard.can_activate(ctx) is True
+
+
+@pytest.mark.asyncio
+async def test_auth_guard_rejects_missing_bearer():
+    guard = AuthGuard(_jwt())
+
+    def _handler():
+        pass
+
+    ctx = _FakeExecutionContext(_fake_request(headers={}), object, _handler)
+    with pytest.raises(UnauthorizedException):
+        await guard.can_activate(ctx)
+
+
+@pytest.mark.asyncio
+async def test_auth_guard_populates_request_state_on_valid_token():
+    jwt = _jwt()
+    token = jwt.sign("user-42", claims={"tenant": "acme"})
+    guard = AuthGuard(jwt)
+
+    def _handler():
+        pass
+
+    req = _fake_request(headers={"Authorization": f"Bearer {token}"})
+    ctx = _FakeExecutionContext(req, object, _handler)
+    assert await guard.can_activate(ctx) is True
+    assert isinstance(req.state.user, AuthPrincipal)
+    assert req.state.user.subject == "user-42"
+    assert req.state.user.claims == {"tenant": "acme"}
+
+
+# ---------------------------------------------------------------------------
+# AuthService orchestration
+
+
+@pytest.mark.asyncio
+async def test_auth_service_issue_and_refresh_round_trip():
+    jwt = _jwt()
+    totp = TotpStrategy(issuer="austial-tests")
+    hasher = Argon2Hasher()
+    store = InMemoryRefreshTokenStore()
+    config = AuthConfig(jwt_secret="x" * 40, issuer="austial-tests")
+    svc = AuthService(jwt, totp, hasher, store, config)
+
+    tokens = await svc.issue_tokens("user-1", claims={"tenant": "acme"})
+    decoded = jwt.verify(tokens.access_token)
+    assert decoded.subject == "user-1"
+
+    refreshed = await svc.refresh(tokens.refresh_token)
+    assert refreshed.refresh_token != tokens.refresh_token
+    assert jwt.verify(refreshed.access_token).subject == "user-1"
+
+    await svc.logout(refreshed.refresh_token)
+    # a revoked refresh token cannot be used again
+    from austial.auth.errors import AuthenticationError
+
+    with pytest.raises(AuthenticationError):
+        await svc.refresh(refreshed.refresh_token)