feat(core): add Supabase client, Clerk auth, and HTTP client with typed deps [AYG-67]

Implement the three core infrastructure dependencies for the microservice template:

- Supabase client: factory function + FastAPI dependency from app.state
- Clerk JWT auth: validate Bearer tokens, extract Principal with roles,
  map error reasons to structured error codes (AUTH_MISSING_TOKEN,
  AUTH_EXPIRED_TOKEN, AUTH_INVALID_TOKEN)
- HTTP client wrapper: async httpx with retry on 502/503/504,
  exponential backoff, circuit breaker (5 failures/60s window),
  X-Request-ID/X-Correlation-ID header propagation from structlog
- Typed FastAPI dependencies: SupabaseDep, PrincipalDep, HttpClientDep,
  RequestIdDep via Annotated[T, Depends()]
- Lifespan context manager: init Supabase + HttpClient at startup,
  close httpx pool on shutdown
- Added session_id field to Principal model

44 new unit tests (113 total), all passing.

Fixes AYG-67

🤖 Generated by Aygentic

Co-Authored-By: Aygentic <noreply@aygentic.com>

Author: amostt

backend/app/api/deps.py

@@ -1,57 +1,42 @@
-from collections.abc import Generator
-from typing import Annotated
+"""Typed FastAPI dependency declarations.
 
-import jwt
-from fastapi import Depends, HTTPException, status
-from fastapi.security import OAuth2PasswordBearer
-from jwt.exceptions import InvalidTokenError
-from pydantic import ValidationError
-from sqlmodel import Session
+All cross-cutting concerns (database, auth, HTTP client, request context) are
+injected via ``Annotated[T, Depends(...)]`` types.  Route handlers declare what
+they need through parameter type annotations and FastAPI resolves the
+dependency chain automatically.
 
-from app.core import security
-from app.core.config import settings
-from app.core.db import engine
-from app.models import TokenPayload, User
+Every dependency listed here is overridable in tests via
+``app.dependency_overrides[fn] = mock_fn``.
+"""
 
-reusable_oauth2 = OAuth2PasswordBearer(
-    tokenUrl=f"{settings.API_V1_STR}/login/access-token"
-)
+from typing import Annotated
 
+from fastapi import Depends, Request
+from supabase import Client as SupabaseClient
 
-def get_db() -> Generator[Session, None, None]:
-    with Session(engine) as session:
-        yield session
+from app.core.auth import get_current_principal
+from app.core.http_client import HttpClient, get_http_client
+from app.core.supabase import get_supabase
+from app.models.auth import Principal
 
 
-SessionDep = Annotated[Session, Depends(get_db)]
-TokenDep = Annotated[str, Depends(reusable_oauth2)]
+def get_request_id(request: Request) -> str:
+    """Return the current request ID from request state.
 
+    The request_id is set by RequestPipelineMiddleware on every request.
+    Falls back to an empty string if middleware has not run (e.g. in tests).
+    """
+    return getattr(request.state, "request_id", "")
 
-def get_current_user(session: SessionDep, token: TokenDep) -> User:
-    try:
-        payload = jwt.decode(
-            token, settings.SECRET_KEY, algorithms=[security.ALGORITHM]
-        )
-        token_data = TokenPayload(**payload)
-    except (InvalidTokenError, ValidationError):
-        raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail="Could not validate credentials",
-        )
-    user = session.get(User, token_data.sub)
-    if not user:
-        raise HTTPException(status_code=404, detail="User not found")
-    if not user.is_active:
-        raise HTTPException(status_code=400, detail="Inactive user")
-    return user
 
+SupabaseDep = Annotated[SupabaseClient, Depends(get_supabase)]
+"""Supabase client instance, initialised at app startup."""
 
-CurrentUser = Annotated[User, Depends(get_current_user)]
+PrincipalDep = Annotated[Principal, Depends(get_current_principal)]
+"""Authenticated user principal extracted from Clerk JWT."""
 
+HttpClientDep = Annotated[HttpClient, Depends(get_http_client)]
+"""Shared async HTTP client with retry, circuit breaker, header propagation."""
 
-def get_current_active_superuser(current_user: CurrentUser) -> User:
-    if not current_user.is_superuser:
-        raise HTTPException(
-            status_code=403, detail="The user doesn't have enough privileges"
-        )
-    return current_user
+RequestIdDep = Annotated[str, Depends(get_request_id)]
+"""Current request UUID from the request pipeline middleware."""

backend/app/core/auth.py

@@ -0,0 +1,132 @@
+"""Clerk JWT authentication dependency.
+
+Provides get_current_principal(), a FastAPI dependency that validates the
+Bearer token in the Authorization header using the Clerk SDK and returns
+the authenticated Principal.
+
+Error codes:
+  AUTH_MISSING_TOKEN   — no session token in request
+  AUTH_EXPIRED_TOKEN   — token has expired
+  AUTH_INVALID_TOKEN   — signature bad, wrong party, or other failure
+"""
+
+from typing import Any
+
+import httpx
+from clerk_backend_api import AuthenticateRequestOptions, Clerk
+from clerk_backend_api.jwks_helpers import AuthErrorReason, TokenVerificationErrorReason
+from fastapi import Request
+
+from app.core.errors import ServiceError
+from app.models.auth import Principal
+
+
+def _get_clerk_sdk() -> Clerk:
+    """Return a Clerk SDK instance initialised with the current secret key.
+
+    Deferred import of settings avoids module-level instantiation failure
+    during tests where the real environment is not set up.
+    """
+    from app.core.config import settings
+
+    return Clerk(bearer_auth=settings.CLERK_SECRET_KEY.get_secret_value())
+
+
+def _get_authorized_parties() -> list[str]:
+    """Return the configured list of authorized parties.
+
+    Deferred import keeps settings out of module-level scope.
+    """
+    from app.core.config import settings
+
+    return settings.CLERK_AUTHORIZED_PARTIES
+
+
+def _convert_request(request: Request) -> httpx.Request:
+    """Convert a FastAPI/Starlette Request to an httpx.Request for the Clerk SDK."""
+    return httpx.Request(
+        method=request.method,
+        url=str(request.url),
+        headers=dict(request.headers),
+    )
+
+
+def _map_error_reason(reason: Any) -> tuple[str, str]:
+    """Map a Clerk error reason to (message, error_code).
+
+    Returns a (message, code) tuple suitable for ServiceError.
+    """
+    if reason is AuthErrorReason.SESSION_TOKEN_MISSING:
+        return ("Missing authentication token", "AUTH_MISSING_TOKEN")
+    if reason is TokenVerificationErrorReason.TOKEN_EXPIRED:
+        return ("Token expired", "AUTH_EXPIRED_TOKEN")
+    if reason is TokenVerificationErrorReason.TOKEN_INVALID_SIGNATURE:
+        return ("Invalid token signature", "AUTH_INVALID_TOKEN")
+    if reason is TokenVerificationErrorReason.TOKEN_INVALID_AUTHORIZED_PARTIES:
+        return ("Token not from authorized party", "AUTH_INVALID_TOKEN")
+    return ("Authentication failed", "AUTH_INVALID_TOKEN")
+
+
+def _extract_roles(payload: dict[str, Any]) -> list[str]:
+    """Extract roles from the Clerk JWT payload.
+
+    Clerk encodes the active organisation role under the 'o' claim:
+      payload["o"]["rol"]  -> e.g. "org:admin"
+
+    Falls back to an empty list when the user has no active organisation
+    or the claim is absent.
+    """
+    org_data = payload.get("o")
+    if not isinstance(org_data, dict):
+        return []
+    role = org_data.get("rol")
+    if not role:
+        return []
+    return [role] if isinstance(role, str) else list(role)
+
+
+async def get_current_principal(request: Request) -> Principal:
+    """FastAPI dependency: validate the Clerk session token and return Principal.
+
+    Raises:
+        ServiceError(401, ...) for any authentication failure.
+    """
+    try:
+        httpx_request = _convert_request(request)
+        options = AuthenticateRequestOptions(
+            authorized_parties=_get_authorized_parties(),
+        )
+        request_state = _get_clerk_sdk().authenticate_request(httpx_request, options)
+    except Exception as exc:
+        raise ServiceError(
+            status_code=401,
+            message="Authentication failed",
+            code="AUTH_INVALID_TOKEN",
+        ) from exc
+
+    if not request_state.is_signed_in:
+        message, code = _map_error_reason(request_state.reason)
+        raise ServiceError(status_code=401, message=message, code=code)
+
+    payload: dict[str, Any] = request_state.payload or {}
+
+    user_id = payload.get("sub")
+    session_id = payload.get("sid")
+    if not user_id or not session_id:
+        raise ServiceError(
+            status_code=401,
+            message="Authentication failed",
+            code="AUTH_INVALID_TOKEN",
+        )
+
+    principal = Principal(
+        user_id=user_id,
+        session_id=session_id,
+        org_id=payload.get("org_id"),
+        roles=_extract_roles(payload),
+    )
+
+    # Store user_id on request state so logging middleware can include it.
+    request.state.user_id = principal.user_id
+
+    return principal