terp-cap-auth 0.1.0__tar.gz

terp_cap_auth-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+.venv-*/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# uv
+uv.lock
+
+# Node
+node_modules/
+.pnpm-store/
+*.tsbuildinfo
+
+# Playwright (conformance e2e) artifacts
+test-results/
+playwright-report/
+blob-report/
+playwright/.cache/
+.last-run.json
+
+# Local frontend template render checks
+apps/example/_frontend_tpl_check/
+
+# Editor / OS
+.DS_Store
+.idea/
+*.local
+
+# Local environment overrides — never commit (a real .env may hold SECRET_KEY).
+# The tracked template is `.env.example`.
+.env
+.env.*
+!.env.example
+!.env.example.jinja
+# Rendered app-declared variables (environment.schema.json) — may hold secrets.
+.app.env

terp_cap_auth-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: terp-cap-auth
+Version: 0.1.0
+Summary: Terp auth capability — Argon2 password hashing, JWT access tokens, and the get_principal seam.
+License-Expression: Apache-2.0
+Requires-Python: >=3.13
+Requires-Dist: pwdlib[argon2]>=0.2
+Requires-Dist: pyjwt>=2.8
+Requires-Dist: terp-core==0.1.0

terp_cap_auth-0.1.0/escape-hatch-budget.json

@@ -0,0 +1,3 @@
+{
+  "arch-allow-schemas-exclude-sensitive-fields": 1
+}

terp_cap_auth-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "terp-cap-auth"
+version = "0.1.0"
+description = "Terp auth capability — Argon2 password hashing, JWT access tokens, and the get_principal seam."
+requires-python = ">=3.13"
+license = "Apache-2.0"
+dependencies = [
+    "terp-core==0.1.0",
+    "pwdlib[argon2]>=0.2",
+    "pyjwt>=2.8",
+]
+
+# PEP 420 namespace package: this distribution owns only `terp.capabilities.auth`.
+[tool.hatch.build.targets.wheel]
+sources = ["src"]
+only-include = ["src/terp/capabilities/auth"]

terp_cap_auth-0.1.0/src/terp/capabilities/auth/__init__.py

@@ -0,0 +1,91 @@
+"""terp.capabilities.auth — authentication (Argon2 hashing + JWT + ``get_principal``).
+
+The first opt-in capability. It fills the kernel's ``get_principal`` seam with a
+real Bearer-JWT provider and supplies password hashing + a login router. It is
+**decoupled from the user store**: the app (or, later, the identity capability)
+supplies an ``authenticate`` callback, so auth never needs to know where users
+live.
+"""
+
+from __future__ import annotations
+
+from terp.capabilities.auth.deps import (
+    TokenValidator,
+    build_get_principal,
+    build_realtime_validator,
+    get_principal,
+    tenant_from_bearer,
+)
+from terp.capabilities.auth.hashing import (
+    hash_password,
+    verify_password,
+    verify_password_dummy,
+)
+from terp.capabilities.auth.refresh import (
+    RefreshRotation,
+    clear_refresh_cookie,
+    generate_refresh_token,
+    refresh_token_digest,
+    set_refresh_cookie,
+)
+from terp.capabilities.auth.router import (
+    Authenticator,
+    CurrentUserResolver,
+    LoginTenantResolver,
+    PrincipalResolver,
+    RefreshIssuer,
+    RefreshRotator,
+    TokenRevoker,
+    TokenVersionResolver,
+    build_login_module,
+    build_login_router,
+    build_me_module,
+    build_me_router,
+)
+from terp.capabilities.auth.schemas import AccessToken, CurrentUser, LoginRequest
+from terp.capabilities.auth.throttle import AccountLockedError, LoginThrottle
+from terp.capabilities.auth.tokens import (
+    TOKEN_AUDIENCE,
+    TOKEN_ISSUER,
+    AccessTokenClaims,
+    create_access_token,
+    decode_access_token,
+)
+
+__all__ = [
+    "AccessToken",
+    "AccessTokenClaims",
+    "AccountLockedError",
+    "Authenticator",
+    "CurrentUser",
+    "CurrentUserResolver",
+    "LoginRequest",
+    "LoginTenantResolver",
+    "LoginThrottle",
+    "PrincipalResolver",
+    "RefreshIssuer",
+    "RefreshRotation",
+    "RefreshRotator",
+    "TOKEN_AUDIENCE",
+    "TOKEN_ISSUER",
+    "TokenRevoker",
+    "TokenValidator",
+    "TokenVersionResolver",
+    "build_get_principal",
+    "build_realtime_validator",
+    "build_login_module",
+    "build_login_router",
+    "build_me_module",
+    "build_me_router",
+    "clear_refresh_cookie",
+    "create_access_token",
+    "decode_access_token",
+    "generate_refresh_token",
+    "get_principal",
+    "hash_password",
+    "refresh_token_digest",
+    "set_refresh_cookie",
+    "tenant_from_bearer",
+    "verify_password",
+    "verify_password_dummy",
+]

terp_cap_auth-0.1.0/src/terp/capabilities/auth/deps.py

@@ -0,0 +1,156 @@
+"""The auth ``get_principal`` provider — turns a Bearer JWT into a ``Principal``.
+
+This is the implementation that fills the kernel's ``get_principal`` seam: pass
+it as ``create_app(..., principal_provider=get_principal)``. A missing or invalid
+token yields ``None`` (unauthenticated), which the deny-by-default guard turns
+into HTTP 401.
+
+Two providers are offered:
+
+* :func:`get_principal` — the **stateless** default: it trusts a validly-signed,
+  unexpired token for its whole lifetime (no store lookup). Simple and zero
+  per-request DB cost, at the price of the access-TTL staleness window.
+* :func:`build_get_principal` — the **revocable** provider (ADR 0031): it runs an
+  app-supplied ``TokenValidator`` against the store every request, so a token whose
+  user was deactivated, demoted, re-tenanted, password-reset, or logged out is
+  rejected mid-session. Auth owns the *seam* and never imports the store; the app
+  wires the implementation (e.g. ``IdentityService(...).token_is_current``), exactly
+  as it wires ``authenticate`` and ``tenant_resolver``.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Callable
+
+from fastapi import Request
+from sqlmodel import Session
+from starlette.requests import HTTPConnection
+
+from terp.core import (
+    AuthenticationError,
+    Principal,
+    SessionDep,
+    mark_token_revocation_provider,
+)
+
+from terp.capabilities.auth.tokens import AccessTokenClaims, decode_access_token
+
+_BEARER_PREFIX = "bearer "
+
+# The app-wired validity check the revocable provider consults every request: given the
+# request session and the decoded claims, return whether the token is still valid (the
+# subject is active and its token epoch is current). Auth owns the type; the app supplies
+# the implementation, so auth never imports the user store (symmetric with the
+# ``authenticate`` / ``tenant_resolver`` seams).
+TokenValidator = Callable[[Session, AccessTokenClaims], bool]
+
+
+def _bearer_token(connection: HTTPConnection) -> str | None:
+    """Return the raw ``Authorization: Bearer`` token, or ``None`` if absent."""
+    header = connection.headers.get("Authorization")
+    if not header or not header.lower().startswith(_BEARER_PREFIX):
+        return None
+    return header[len(_BEARER_PREFIX):].strip()
+
+
+def get_principal(connection: HTTPConnection) -> Principal | None:
+    """Extract the caller's principal from the ``Authorization: Bearer`` header.
+
+    The stateless provider: it does **no** per-request store lookup, so an already-issued
+    token stays valid until it expires. Use :func:`build_get_principal` for prompt
+    revocation (deactivate / demote / password-reset / logout taking effect mid-session).
+    """
+    token = _bearer_token(connection)
+    if token is None:
+        return None
+    try:
+        claims = decode_access_token(token)
+    except AuthenticationError:
+        return None
+    return Principal(id=claims.subject, role=claims.role)
+
+
+def build_get_principal(
+    token_validator: TokenValidator | None = None,
+) -> Callable[..., Principal | None]:
+    """Build a ``get_principal`` seam that re-validates the token against the store.
+
+    When *token_validator* is supplied, the returned provider rejects (→ ``None`` → 401)
+    a token the validator fails — the runtime half of the session-revocation control
+    (ADR 0031). The provider depends on the request ``Session`` so the validator can do
+    its one indexed lookup (the guard already opens a session per guarded request, so
+    there is no extra cost there). The returned provider is **marked** as
+    revocation-enforcing (:func:`~terp.core.mark_token_revocation_provider`), so
+    ``create_app(require_token_revocation=True)`` accepts it and refuses the stateless
+    default. With no validator it behaves like :func:`get_principal` (stateless) and is
+    left unmarked.
+    """
+
+    def get_principal(
+        connection: HTTPConnection, session: SessionDep
+    ) -> Principal | None:
+        token = _bearer_token(connection)
+        if token is None:
+            return None
+        try:
+            claims = decode_access_token(token)
+        except AuthenticationError:
+            return None
+        if token_validator is not None and not token_validator(session, claims):
+            return None
+        return Principal(id=claims.subject, role=claims.role)
+
+    if token_validator is not None:
+        mark_token_revocation_provider(get_principal)
+    return get_principal
+
+
+def build_realtime_validator() -> Callable[[Principal, str], bool]:
+    """Validate the server-retained bearer behind a realtime connection ticket.
+
+    Native transports cannot send the Authorization header after the generated
+    client mints their one-use ticket. The ticket retains the credential only
+    in server-side TTL state; this validator rechecks signature/expiry and that
+    its subject+role still match the captured principal. Store-backed epoch /
+    active-user revocation is an app concern (it owns the identity store):
+    compose this validator inside the realtime capability's
+    ``principal_validator`` with the app's own fresh-session check.
+    """
+
+    def validate(principal: Principal, credential: str) -> bool:
+        if not credential:
+            return False
+        try:
+            claims = decode_access_token(credential)
+        except AuthenticationError:
+            return False
+        return claims.subject == principal.id and claims.role == principal.role
+
+    return validate
+
+
+def tenant_from_bearer(request: Request) -> uuid.UUID | None:
+    """Resolve the signed ``tenant`` claim from the request's Bearer token.
+
+    A ready-made resolver for ``terp.capabilities.tenancy.TenantMiddleware``: the
+    tenant is only as trustworthy as the token that carries it. A missing,
+    invalid, or tenant-less token resolves to ``None`` — scoped services then fail
+    closed rather than leaking another tenant's rows.
+    """
+    token = _bearer_token(request)
+    if token is None:
+        return None
+    try:
+        return decode_access_token(token).tenant
+    except AuthenticationError:
+        return None
+
+
+__all__ = [
+    "TokenValidator",
+    "build_get_principal",
+    "build_realtime_validator",
+    "get_principal",
+    "tenant_from_bearer",
+]

terp_cap_auth-0.1.0/src/terp/capabilities/auth/hashing.py

@@ -0,0 +1,40 @@
+"""Argon2 password hashing (recommended defaults)."""
+
+from __future__ import annotations
+
+from pwdlib import PasswordHash
+
+_password_hash = PasswordHash.recommended()
+
+# Lazily-built fixed hash that `verify_password_dummy` burns a verification
+# against, so a refused login costs the same as a real password check.
+_dummy_hash: str | None = None
+
+
+def hash_password(password: str) -> str:
+    """Hash *password* with Argon2 (per-password salt, recommended parameters)."""
+    return _password_hash.hash(password)
+
+
+def verify_password(password: str, password_hash: str) -> bool:
+    """Return ``True`` iff *password* matches *password_hash*."""
+    return _password_hash.verify(password, password_hash)
+
+
+def verify_password_dummy() -> None:
+    """Burn one Argon2 verification against a fixed dummy hash (timing equalization).
+
+    An authenticate path that refuses *before* verifying — unknown email, inactive
+    account, SSO-only user with no local credential — must call this so the refusal
+    costs the same as a real password check. Without it, a login attempt against a
+    valid email takes ~an Argon2 verify while an invalid one returns in microseconds:
+    a remote timing side channel that enumerates registered accounts. The dummy hash
+    is built lazily on first use (never at import) and the result is discarded.
+    """
+    global _dummy_hash
+    if _dummy_hash is None:
+        _dummy_hash = _password_hash.hash("terp-timing-equalization-dummy")
+    _password_hash.verify("terp-timing-equalization-probe", _dummy_hash)
+
+
+__all__ = ["hash_password", "verify_password", "verify_password_dummy"]

terp_cap_auth-0.1.0/src/terp/capabilities/auth/refresh.py

@@ -0,0 +1,88 @@
+"""Refresh-token mechanics for the auth capability (ADR 0054).
+
+Auth owns the *mechanics* of the refresh credential — how a token is generated, how it is
+digested for storage, and how it rides an httpOnly cookie — but **not** where it is stored:
+the row lives in the identity store, reached through the app-wired refresh seams (symmetric
+with ``authenticate`` / ``token_version_resolver``), so auth never imports identity.
+
+The refresh token is opaque, 256-bit ``secrets`` randomness (not a JWT — its only meaning is
+"this row is still live", which is what makes it individually revocable). It is stored as a
+**keyed HMAC-SHA256 digest**: the key is derived from the app ``SECRET_KEY`` with domain
+separation, so a database leak alone cannot use or even confirm a token without the app
+secret, while the digest stays deterministic — one indexed lookup on ``/refresh``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import secrets
+import uuid
+from dataclasses import dataclass
+
+from fastapi import Response
+
+from terp.core import settings
+
+# 32 bytes = 256 bits of entropy; url-safe so it is a valid cookie value verbatim.
+_TOKEN_NBYTES = 32
+# Domain-separates the refresh-digest key from every other use of SECRET_KEY.
+_DIGEST_CONTEXT = b"terp.refresh-token.v1"
+
+
+@dataclass(frozen=True)
+class RefreshRotation:
+    """The outcome of a successful refresh: whose session, and the new token to re-cookie."""
+
+    user_id: uuid.UUID
+    token: str
+
+
+def generate_refresh_token() -> str:
+    """A fresh opaque refresh token — 256 bits of URL-safe randomness."""
+    return secrets.token_urlsafe(_TOKEN_NBYTES)
+
+
+def refresh_token_digest(raw_token: str) -> str:
+    """The at-rest digest of *raw_token*: a SECRET_KEY-keyed (peppered) HMAC-SHA256 hex.
+
+    Keyed so a leaked database of digests is useless without the app secret; deterministic
+    so ``/refresh`` looks the row up in one indexed read. The key is derived from
+    ``SECRET_KEY`` (read at call time, so tests and rotation see the live value) with a
+    context prefix, keeping it separate from the access-token signing use of the secret.
+    """
+    key = hashlib.sha256(_DIGEST_CONTEXT + b":" + settings.SECRET_KEY.encode()).digest()
+    return hmac.new(key, raw_token.encode(), hashlib.sha256).hexdigest()
+
+
+def set_refresh_cookie(response: Response, token: str) -> None:
+    """Attach the rotating refresh token as an httpOnly, path-scoped cookie (ADR 0054)."""
+    response.set_cookie(
+        key=settings.REFRESH_COOKIE_NAME,
+        value=token,
+        max_age=settings.REFRESH_FAMILY_TTL_SECONDS,
+        path=settings.REFRESH_COOKIE_PATH,
+        httponly=True,
+        secure=settings.refresh_cookie_secure,
+        samesite=settings.REFRESH_COOKIE_SAMESITE,
+    )
+
+
+def clear_refresh_cookie(response: Response) -> None:
+    """Delete the refresh cookie (logout) — matched on name + path so the browser drops it."""
+    response.delete_cookie(
+        key=settings.REFRESH_COOKIE_NAME,
+        path=settings.REFRESH_COOKIE_PATH,
+        httponly=True,
+        secure=settings.refresh_cookie_secure,
+        samesite=settings.REFRESH_COOKIE_SAMESITE,
+    )
+
+
+__all__ = [
+    "RefreshRotation",
+    "clear_refresh_cookie",
+    "generate_refresh_token",
+    "refresh_token_digest",
+    "set_refresh_cookie",
+]

terp_cap_auth-0.1.0/src/terp/capabilities/auth/router.py

@@ -0,0 +1,311 @@
+"""Login + logout router + ``ModuleSpec`` builder for the auth capability.
+
+The capability does **not** own a user store (the identity capability does). The
+app supplies an ``authenticate(session, email, password) -> Principal | None``
+callback; auth only checks that the credential resolves to a principal and then issues
+a token. The login route is mounted with ``Policy.public`` so it is reachable without a
+token; the optional logout route revokes the caller's sessions through an app-supplied
+seam (auth does not own the store it must write).
+
+Session-management seams (ADR 0031), all optional and app-wired so auth never imports
+the store:
+
+* ``token_version_resolver`` signs the subject's **current token epoch** into the issued
+  token, so a freshly-minted token is valid against the store (without it, the first
+  token issued after any revoking change would be instantly stale);
+* ``revoke_sessions`` bumps the caller's epoch on ``POST /logout`` (mounted only when
+  wired); and
+* ``throttle`` is the per-account login lockout (on by default, ADR 0031 / L3).
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Callable
+
+from fastapi import APIRouter, Depends, Request, Response
+from sqlmodel import Session
+
+from terp.core import (
+    AuthenticationError,
+    ModuleSpec,
+    Policy,
+    Principal,
+    SessionDep,
+    get_principal,
+    settings,
+)
+
+from terp.capabilities.auth.refresh import (
+    RefreshRotation,
+    clear_refresh_cookie,
+    set_refresh_cookie,
+)
+from terp.capabilities.auth.schemas import AccessToken, CurrentUser, LoginRequest
+from terp.capabilities.auth.throttle import LoginThrottle
+from terp.capabilities.auth.tokens import create_access_token
+
+Authenticator = Callable[[Session, str, str], Principal | None]
+LoginTenantResolver = Callable[[Session, Principal], uuid.UUID | None]
+# Resolve the subject's current token epoch so login signs it (see module docstring).
+TokenVersionResolver = Callable[[Session, Principal], int]
+# Revoke (invalidate) a subject's outstanding tokens — the logout write-back, app-wired
+# to the store (e.g. ``UsersService.revoke_sessions``) since auth does not own it.
+TokenRevoker = Callable[[Session, uuid.UUID], None]
+# Refresh-token seams (ADR 0054), app-wired to the identity refresh store so auth never
+# imports it. Issue the first token at login; rotate (single-use + reuse-detect) a presented
+# token; resolve an ACTIVE subject's principal by id (the /refresh analog of authenticate,
+# which needs a password). All three are wired together or not at all.
+RefreshIssuer = Callable[[Session, uuid.UUID], str]
+RefreshRotator = Callable[[Session, str], RefreshRotation | None]
+PrincipalResolver = Callable[[Session, uuid.UUID], Principal | None]
+# Resolve the authenticated caller's own identity for ``GET /me`` — app-wired to the
+# store (e.g. ``IdentityService.current_user``) so auth never imports where users live
+# (symmetric with the authenticate / tenant_resolver / revoke_sessions seams).
+CurrentUserResolver = Callable[[Session, Principal], CurrentUser]
+
+
+def build_login_router(
+    authenticate: Authenticator,
+    *,
+    tenant_resolver: LoginTenantResolver | None = None,
+    token_version_resolver: TokenVersionResolver | None = None,
+    revoke_sessions: TokenRevoker | None = None,
+    throttle: LoginThrottle | None = None,
+    refresh_issuer: RefreshIssuer | None = None,
+    refresh_rotator: RefreshRotator | None = None,
+    principal_resolver: PrincipalResolver | None = None,
+    require_refresh: bool = False,
+) -> APIRouter:
+    """Build a ``/login`` (+ optional ``/logout`` / ``/refresh``) router via *authenticate*.
+
+    When *tenant_resolver* is supplied, the authenticated principal is mapped to a
+    tenant and that tenant is signed into the token's ``tenant`` claim — so a
+    multi-tenant app issues a tenant-bound token through this one seam (symmetric with
+    ``TenantMiddleware``'s ``resolve_tenant``), without the auth capability needing to
+    know how a tenant is stored. *token_version_resolver* likewise signs the subject's
+    current token epoch (ADR 0031). *throttle* (default: a fresh on-by-default
+    :class:`LoginThrottle`) locks an account after repeated failed logins. When
+    *revoke_sessions* is supplied, a ``POST /logout`` route is mounted that bumps the
+    caller's epoch (idempotent; an unauthenticated call is a no-op).
+
+    Refresh-token rotation (ADR 0054) is opt-in and **all-or-nothing**: supply
+    *refresh_issuer* (open a family + mint the first token at login), *refresh_rotator*
+    (validate + single-use rotate + reuse-detect), and *principal_resolver* (resolve an
+    active subject by id) together — plus *revoke_sessions*, so ``/logout`` revokes the
+    family server-side and not just the cookie — to mount ``POST /refresh`` and have
+    ``/login`` / ``/logout`` set / clear the httpOnly refresh cookie. Wiring only some of
+    the seams, omitting *revoke_sessions*, or passing *require_refresh* without them,
+    raises at construction (fail-closed).
+    """
+    router = APIRouter(tags=["auth"])
+    active_throttle = throttle if throttle is not None else LoginThrottle()
+
+    # Refresh rotation is all-or-nothing: a token issued at login that nothing can rotate
+    # (or vice versa) is a fail-closed misconfiguration caught here, at construction.
+    refresh_enabled = (
+        refresh_issuer is not None
+        and refresh_rotator is not None
+        and principal_resolver is not None
+    )
+    any_refresh_seam = (
+        refresh_issuer is not None
+        or refresh_rotator is not None
+        or principal_resolver is not None
+    )
+    if any_refresh_seam and not refresh_enabled:
+        raise ValueError(
+            "refresh-token rotation is half-wired: refresh_issuer, refresh_rotator, and "
+            "principal_resolver must be supplied together (ADR 0054)."
+        )
+    if refresh_enabled and revoke_sessions is None:
+        # Without a server-side revoker, /logout could only drop the browser cookie while
+        # every token in the family stayed live in the store — a logout that does not log
+        # out. Refuse the half-secure shape at construction (fail-closed).
+        raise ValueError(
+            "refresh-token rotation requires revoke_sessions: without it a logout clears "
+            "the cookie but leaves the refresh-token family live server-side (ADR 0054)."
+        )
+    if require_refresh and not refresh_enabled:
+        raise ValueError(
+            "require_refresh=True but the refresh seams are not wired (ADR 0054)."
+        )
+
+    def _mint_access_token(session: Session, principal: Principal) -> str:
+        tenant = tenant_resolver(session, principal) if tenant_resolver is not None else None
+        token_version = (
+            token_version_resolver(session, principal)
+            if token_version_resolver is not None
+            else 0
+        )
+        return create_access_token(
+            subject=principal.id,
+            role=principal.role,
+            tenant=tenant,
+            token_version=token_version,
+        )
+
+    @router.post("/login", response_model=AccessToken)
+    def login(
+        credentials: LoginRequest, session: SessionDep, response: Response
+    ) -> AccessToken:
+        active_throttle.check(credentials.email)
+        principal = authenticate(session, credentials.email, credentials.password)
+        if principal is None:
+            active_throttle.record_failure(credentials.email)
+            raise AuthenticationError()
+        active_throttle.record_success(credentials.email)
+        token = _mint_access_token(session, principal)
+        if refresh_issuer is not None:
+            # Open a fresh refresh-token family and set its httpOnly cookie beside the
+            # bearer, so the session survives a reload and can outlive the access TTL.
+            set_refresh_cookie(response, refresh_issuer(session, principal.id))
+        return AccessToken(access_token=token)
+
+    if refresh_rotator is not None and principal_resolver is not None:
+        rotate_token = refresh_rotator
+        resolve_principal = principal_resolver
+
+        @router.post("/refresh", response_model=AccessToken)
+        def refresh(
+            request: Request, session: SessionDep, response: Response
+        ) -> AccessToken:
+            # The refresh cookie is the credential here (no bearer): rotate it (single-use +
+            # reuse-detection), re-check the subject is still active, then mint a fresh
+            # access token and set the rotated cookie. Any failure is a clean 401.
+            raw = request.cookies.get(settings.REFRESH_COOKIE_NAME)
+            if raw is None:
+                raise AuthenticationError()
+            rotation = rotate_token(session, raw)
+            if rotation is None:
+                raise AuthenticationError()
+            principal = resolve_principal(session, rotation.user_id)
+            if principal is None:
+                raise AuthenticationError()
+            token = _mint_access_token(session, principal)
+            set_refresh_cookie(response, rotation.token)
+            return AccessToken(access_token=token)
+
+    if revoke_sessions is not None or refresh_enabled:
+
+        @router.post("/logout", status_code=204)
+        def logout(
+            session: SessionDep,
+            principal: Principal | None = Depends(get_principal),
+        ) -> Response:
+            # Logout is idempotent: with no (or an already-revoked) token there is nothing
+            # to invalidate. Otherwise bump the caller's epoch (the wired revoke also kills
+            # the refresh families), and always drop the refresh cookie.
+            if principal is not None and revoke_sessions is not None:
+                revoke_sessions(session, principal.id)
+            response = Response(status_code=204)
+            if refresh_enabled:
+                clear_refresh_cookie(response)
+            return response
+
+    return router
+
+
+def build_login_module(
+    authenticate: Authenticator,
+    *,
+    name: str = "auth",
+    tenant_resolver: LoginTenantResolver | None = None,
+    token_version_resolver: TokenVersionResolver | None = None,
+    revoke_sessions: TokenRevoker | None = None,
+    throttle: LoginThrottle | None = None,
+    refresh_issuer: RefreshIssuer | None = None,
+    refresh_rotator: RefreshRotator | None = None,
+    principal_resolver: PrincipalResolver | None = None,
+    require_refresh: bool = False,
+) -> ModuleSpec:
+    """Build the auth ``ModuleSpec`` (public login + optional logout / refresh endpoints).
+
+    When the refresh seams are wired, the configured refresh-cookie path must match where
+    this module is mounted (``/api/v1/<name>``) — a path-scoped cookie the browser never
+    sends to ``/refresh`` would make refresh silently never work, so the mismatch is
+    refused here, at construction (fail-closed).
+    """
+    refresh_enabled = (
+        refresh_issuer is not None
+        and refresh_rotator is not None
+        and principal_resolver is not None
+    )
+    mount_prefix = f"/api/v1/{name}"
+    if refresh_enabled and settings.REFRESH_COOKIE_PATH != mount_prefix:
+        raise ValueError(
+            f"REFRESH_COOKIE_PATH ({settings.REFRESH_COOKIE_PATH!r}) does not match this "
+            f"module's mount prefix ({mount_prefix!r}); the browser would never send the "
+            "refresh cookie to /refresh (ADR 0054)."
+        )
+    return ModuleSpec(
+        name=name,
+        router=build_login_router(
+            authenticate,
+            tenant_resolver=tenant_resolver,
+            token_version_resolver=token_version_resolver,
+            revoke_sessions=revoke_sessions,
+            throttle=throttle,
+            refresh_issuer=refresh_issuer,
+            refresh_rotator=refresh_rotator,
+            principal_resolver=principal_resolver,
+            require_refresh=require_refresh,
+        ),
+        policy=Policy.public_write(
+            reason="authentication endpoints must be reachable without a token"
+        ),
+    )
+
+
+def build_me_router(resolve_current_user: CurrentUserResolver) -> APIRouter:
+    """Build the ``GET /me`` (who-am-I) router via the *resolve_current_user* seam.
+
+    The route is **self-scoped**: it reports only the authenticated caller's own identity
+    (read from ``principal.id``), so it takes no id parameter and cannot be turned into a
+    read of another subject. Mounted behind ``Policy.default()`` (any authenticated
+    caller), it answers through the wired principal provider — the revocable one in the
+    bundled stack — so a deactivated / demoted / re-tenanted token is already rejected and
+    the response reflects the live record rather than stale token claims.
+    """
+    router = APIRouter(tags=["auth"])
+
+    @router.get("/", response_model=CurrentUser)
+    def me(
+        session: SessionDep,
+        principal: Principal | None = Depends(get_principal),
+    ) -> CurrentUser:
+        # The module guard authorizes against Policy.default() (rejecting anonymous)
+        # before this handler runs; the explicit check keeps the router correct — a clean
+        # 401, never an AttributeError — even if it were ever mounted without that guard.
+        if principal is None:
+            raise AuthenticationError()
+        return resolve_current_user(session, principal)
+
+    return router
+
+
+def build_me_module(
+    resolve_current_user: CurrentUserResolver, *, name: str = "me"
+) -> ModuleSpec:
+    """Build the who-am-I ``ModuleSpec`` (``GET /api/v1/me``, any authenticated caller)."""
+    return ModuleSpec(
+        name=name,
+        router=build_me_router(resolve_current_user),
+        policy=Policy.default(),
+    )
+
+
+__all__ = [
+    "Authenticator",
+    "CurrentUserResolver",
+    "LoginTenantResolver",
+    "PrincipalResolver",
+    "RefreshIssuer",
+    "RefreshRotator",
+    "TokenRevoker",
+    "TokenVersionResolver",
+    "build_login_module",
+    "build_login_router",
+    "build_me_module",
+    "build_me_router",
+]

terp_cap_auth-0.1.0/src/terp/capabilities/auth/schemas.py

@@ -0,0 +1,38 @@
+"""Auth request/response DTOs."""
+
+from __future__ import annotations
+
+import uuid
+
+from sqlmodel import Field
+
+from terp.core import BaseSchema
+
+
+class LoginRequest(BaseSchema):
+    email: str = Field(max_length=320)
+    password: str = Field(max_length=256)
+
+
+class AccessToken(BaseSchema):
+    access_token: str  # arch-allow-schemas-exclude-sensitive-fields: the bearer token the login endpoint exists to mint
+    token_type: str = "bearer"
+
+
+class CurrentUser(BaseSchema):
+    """The authenticated caller's own identity — the ``/me`` (who-am-I) response.
+
+    The frontend's session contract pairs this with :class:`AccessToken`. It is the
+    server-validated current identity (resolved through the wired principal provider —
+    the revocable one in the bundled stack), so it reflects the live store, not just the
+    token's claims. The caller's role is on the wire as both the numeric ``role_rank``
+    (the comparable primitive, ADR 0004 / 0022) and a human-readable ``role_name``.
+    """
+
+    id: uuid.UUID
+    email: str
+    role_rank: int
+    role_name: str
+
+
+__all__ = ["AccessToken", "CurrentUser", "LoginRequest"]

terp_cap_auth-0.1.0/src/terp/capabilities/auth/throttle.py

@@ -0,0 +1,132 @@
+"""Per-account login lockout — a fail-closed brute-force throttle (ADR 0031, L3).
+
+A login-specific complement to the generic rate limiter: it counts *failed* logins per
+account and locks the account for a window once a threshold is crossed, so credential
+stuffing against a single user is throttled even when the generic rate limit (which
+counts all requests from all callers) would not bite.
+
+The lockout state lives in a pluggable :class:`~terp.core.ThrottleStore` (ADR 0036):
+the default :class:`~terp.core.InMemoryThrottleStore` is per app instance / in process —
+unchanged behaviour — while a multi-instance deployment passes the same shared store the
+rate limiter uses, so the lockout is correct across workers. A store error fails closed
+(the account is treated as locked). It is on by default; an app turns it off only with
+an explicit, reason-bearing :meth:`LoginThrottle.disabled`.
+"""
+
+from __future__ import annotations
+
+import datetime
+import logging
+
+from terp.core import AppError, InMemoryThrottleStore, ThrottleStore
+
+_logger = logging.getLogger("terp.capabilities.auth.throttle")
+
+
+class AccountLockedError(AppError):
+    """429 — too many failed login attempts; the account is temporarily locked."""
+
+    status_code = 429
+    code = "account_locked"
+    default_message = (
+        "Too many failed login attempts. This account is temporarily locked; "
+        "please wait and try again."
+    )
+
+
+def _utc_now() -> datetime.datetime:
+    """UTC ``now`` provider — kept private so tests can monkeypatch the clock."""
+    return datetime.datetime.now(datetime.UTC)
+
+
+class LoginThrottle:
+    """Per-account failed-login lockout over a pluggable :class:`ThrottleStore`.
+
+    After *max_attempts* failed logins for one identifier within *window*, the
+    identifier is locked for *lockout*; while locked, even a correct credential is
+    refused (the login route calls :meth:`check` *before* verifying the password). A
+    successful login clears the counter. State is keyed by a normalized identifier
+    (trimmed + lower-cased) so case variants of an email cannot dodge the count. With no
+    *store* the default per-instance in-memory store is used (clocked off :func:`_utc_now`
+    so tests can drive it); a multi-instance app passes a shared store for one correct
+    global counter.
+    """
+
+    def __init__(
+        self,
+        *,
+        max_attempts: int = 5,
+        window: datetime.timedelta = datetime.timedelta(minutes=15),
+        lockout: datetime.timedelta = datetime.timedelta(minutes=15),
+        store: ThrottleStore | None = None,
+    ) -> None:
+        if max_attempts < 1:
+            raise ValueError("LoginThrottle.max_attempts must be >= 1")
+        self.enabled = True
+        self.disabled_reason = ""
+        self._max_attempts = max_attempts
+        self._window = int(window.total_seconds())
+        self._lockout = int(lockout.total_seconds())
+        self._store = store if store is not None else InMemoryThrottleStore(
+            clock=lambda: _utc_now().timestamp()
+        )
+
+    @classmethod
+    def disabled(cls, *, reason: str) -> LoginThrottle:
+        """An explicitly-disabled throttle (no lockout). *reason* is required (fail-closed).
+
+        Mirrors ``CorsPolicy.disabled`` / ``AuditPolicy.disabled``: turning a
+        secure-by-default control off is a visible, justified act, never a silent
+        omission, so an empty reason is refused.
+        """
+        if not reason.strip():
+            raise ValueError("LoginThrottle.disabled requires a non-empty reason")
+        throttle = cls()
+        throttle.enabled = False
+        throttle.disabled_reason = reason
+        return throttle
+
+    def check(self, identifier: str) -> None:
+        """Raise :class:`AccountLockedError` if *identifier* is currently locked."""
+        if not self.enabled:
+            return
+        try:
+            locked = self._store.locked(self._key(identifier)) > 0
+        except Exception as exc:  # a shared store outage fails closed
+            raise AccountLockedError() from exc
+        if locked:
+            raise AccountLockedError()
+
+    def record_failure(self, identifier: str) -> None:
+        """Record a failed attempt; lock *identifier* once the threshold is reached."""
+        if not self.enabled:
+            return
+        key = self._key(identifier)
+        try:
+            count, _ = self._store.hit(key, self._window)
+            if count >= self._max_attempts:
+                self._store.lock(key, self._lockout)
+        except Exception as exc:  # a shared store outage fails closed
+            raise AccountLockedError() from exc
+
+    def record_success(self, identifier: str) -> None:
+        """Clear *identifier*'s failure state after a successful login."""
+        if not self.enabled:
+            return
+        try:
+            self._store.clear(self._key(identifier))
+        except Exception as exc:  # best-effort cleanup: never block an already-valid login
+            _logger.warning("login_throttle_clear_failed", exc_info=exc)
+
+    def reset(self) -> None:
+        """Clear all tracked state (a test seam; per-instance state otherwise persists)."""
+        reset = getattr(self._store, "reset", None)
+        if callable(reset):
+            reset()
+
+    @staticmethod
+    def _key(identifier: str) -> str:
+        return f"lt:{identifier.strip().lower()}"
+
+
+__all__ = ["AccountLockedError", "LoginThrottle"]

terp_cap_auth-0.1.0/src/terp/capabilities/auth/tokens.py

@@ -0,0 +1,139 @@
+"""Signed JWT access tokens, keyed on the kernel ``SECRET_KEY``."""
+
+from __future__ import annotations
+
+import datetime
+import uuid
+from dataclasses import dataclass
+from typing import Final
+
+import jwt
+
+from terp.core import AuthenticationError, Role, Roles, as_role, settings
+
+_ALGORITHM = "HS256"
+DEFAULT_ACCESS_TOKEN_TTL = datetime.timedelta(minutes=15)
+
+#: The ``iss`` / ``aud`` claims every Terp access token carries and every decode
+#: **requires** (ADR 0076): a JWT minted by any other issuer for any other audience
+#: — even one signed with the same shared secret (another service reusing the key,
+#: an OIDC provider, a future token type) — is refused, never confused for an
+#: access credential.
+TOKEN_ISSUER: Final[str] = "terp.auth"
+TOKEN_AUDIENCE: Final[str] = "terp.api"
+
+# Every claim an access token is refused without: the registered pair above plus
+# the identity/lifetime pair — a token missing any of them never authenticates.
+_REQUIRED_CLAIMS: Final[tuple[str, ...]] = ("exp", "iat", "sub", "aud", "iss")
+
+
+@dataclass(frozen=True)
+class AccessTokenClaims:
+    """The trusted claims carried by a decoded access token."""
+
+    subject: uuid.UUID
+    role: Role
+    tenant: uuid.UUID | None = None
+    token_version: int = 0
+
+
+def create_access_token(
+    *,
+    subject: uuid.UUID,
+    role: Role | Roles,
+    tenant: uuid.UUID | None = None,
+    token_version: int = 0,
+    expires_in: datetime.timedelta = DEFAULT_ACCESS_TOKEN_TTL,
+) -> str:
+    """Issue a short-lived HS256 access token for *subject* with *role*.
+
+    *role* may be a typed :class:`~terp.core.Role` or the legacy ``Roles`` enum;
+    its name and rank are both signed in, so a consumer-defined role round-trips
+    without being coerced to a fixed tier. When *tenant* is given it is signed as
+    the ``tenant`` claim, so a tenant-aware app can bind request scope from the
+    verified token (see ``terp.capabilities.tenancy.TenantMiddleware``).
+
+    *token_version* signs the subject's current **token epoch** as the ``tv`` claim
+    (ADR 0031). A principal provider wired with a validator rejects the token once the
+    stored epoch moves past it, so deactivating, demoting, re-tenanting, resetting the
+    password of, or logging out a user invalidates their outstanding tokens at once —
+    sign the user's current epoch here (default ``0`` = revocation inactive).
+
+    Every token also signs the fixed :data:`TOKEN_ISSUER` / :data:`TOKEN_AUDIENCE`
+    pair (ADR 0076), which :func:`decode_access_token` requires — scoping the
+    credential to this framework's API even under a shared signing key. Signing
+    always uses the **current** ``SECRET_KEY`` (never a fallback).
+    """
+    typed = as_role(role)
+    now = datetime.datetime.now(datetime.UTC)
+    payload: dict[str, object] = {
+        "sub": str(subject),
+        "role": typed.name,
+        "rank": typed.rank,
+        "tv": token_version,
+        "iss": TOKEN_ISSUER,
+        "aud": TOKEN_AUDIENCE,
+        "iat": now,
+        "exp": now + expires_in,
+    }
+    if tenant is not None:
+        payload["tenant"] = str(tenant)
+    return jwt.encode(payload, settings.SECRET_KEY, algorithm=_ALGORITHM)
+
+
+def _verify(token: str) -> dict:
+    """Verify *token* against the current key, then each rotation fallback.
+
+    ``SECRET_KEY`` verifies first; a **signature** mismatch (and only that) moves
+    on to the next ``SECRET_KEY_FALLBACKS`` entry, so an access token issued just
+    before a key rotation stays valid through the configured window (ADR 0076).
+    Any other verification failure — expired, wrong ``aud``/``iss``, a missing
+    required claim — is final and never retried against another key.
+    """
+    keys = (settings.SECRET_KEY, *settings.SECRET_KEY_FALLBACKS)
+    rejected: jwt.InvalidSignatureError | None = None
+    for key in keys:
+        try:
+            return jwt.decode(
+                token,
+                key,
+                algorithms=[_ALGORITHM],
+                audience=TOKEN_AUDIENCE,
+                issuer=TOKEN_ISSUER,
+                options={"require": list(_REQUIRED_CLAIMS)},
+            )
+        except jwt.InvalidSignatureError as exc:
+            rejected = exc
+        except jwt.PyJWTError as exc:
+            raise AuthenticationError() from exc
+    raise AuthenticationError() from rejected
+
+
+def decode_access_token(token: str) -> AccessTokenClaims:
+    """Verify + decode *token*. Raises :class:`AuthenticationError` if invalid.
+
+    Verification is fail-closed on the registered claims: the signature (current
+    key or a rotation fallback), the ``exp``/``iat`` lifetime, and the exact
+    :data:`TOKEN_ISSUER` / :data:`TOKEN_AUDIENCE` pair must all hold.
+    """
+    payload = _verify(token)
+    try:
+        raw_tenant = payload.get("tenant")
+        return AccessTokenClaims(
+            subject=uuid.UUID(payload["sub"]),
+            role=Role(str(payload["role"]), int(payload["rank"])),
+            tenant=uuid.UUID(raw_tenant) if raw_tenant is not None else None,
+            token_version=int(payload.get("tv", 0)),
+        )
+    except (KeyError, ValueError, TypeError) as exc:
+        raise AuthenticationError() from exc
+
+
+__all__ = [
+    "AccessTokenClaims",
+    "DEFAULT_ACCESS_TOKEN_TTL",
+    "TOKEN_AUDIENCE",
+    "TOKEN_ISSUER",
+    "create_access_token",
+    "decode_access_token",
+]