refactor(identity): layer the module into router/service/repository/github (#61)

- repository.py owns every query against github_users; the service no longer builds SQL
- github.py is a typed boundary: GitHubOAuthToken and GitHubUserProfile replace the bare dicts that used to cross the domain, so a GitHub shape change fails at the edge instead of as a KeyError in a service
- service.py exposes use cases (authenticate_with_code, sync_user, refresh_tokens) and returns a TokenPair object instead of an untyped 2-tuple; get_user_stats returns UserStatsResponse instead of a dict
- container/repository.py is introduced to own the ContainerSession aggregates the dashboard needs, so identity stops writing SQL over another module's tables
- router.py is thin: validate, call one use case, shape the response. Inline UnauthorizedError imports hoisted, cookie policy factored into one helper
- logout now clears the cookie with the same attributes used to set it (it was hardcoded secure=True, so it silently failed over plain HTTP) and is rate-limited like its neighbours
- dead RefreshRequest schema removed
- tests rewritten off unittest.mock onto httpx.MockTransport: 17 -> 26 tests covering the boundary parsing, token claims and the stats path

317 tests pass, ruff and mypy clean.

Author: mariuspruvot

apps/api/src/helprs/modules/container/repository.py

@@ -0,0 +1,101 @@
+"""Persistence for container sessions and their events.
+
+Container sessions belong to this module, so every query against them lives
+here — including the aggregates other modules need. That keeps the identity
+dashboard from writing SQL over tables it does not own.
+"""
+
+import uuid
+from dataclasses import dataclass
+from datetime import date, datetime
+
+from sqlalchemy import case, cast, func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.types import Date
+
+from helprs.modules.container.models import ContainerSession, ContainerStatus
+
+
+@dataclass(frozen=True)
+class StatusCounts:
+    """Session totals per terminal status, for one set of installations."""
+
+    completed: int
+    failed: int
+    timeout: int
+    total: int
+
+    @classmethod
+    def empty(cls) -> "StatusCounts":
+        return cls(completed=0, failed=0, timeout=0, total=0)
+
+
+@dataclass(frozen=True)
+class DailyCount:
+    """How many sessions ran on a given day."""
+
+    day: date
+    count: int
+
+
+async def count_by_status(session: AsyncSession, installation_ids: list[uuid.UUID]) -> StatusCounts:
+    """Count sessions per terminal status across the given installations."""
+    if not installation_ids:
+        return StatusCounts.empty()
+
+    result = await session.execute(
+        select(
+            func.count(ContainerSession.id).label("total"),
+            func.count(case((ContainerSession.status == ContainerStatus.COMPLETED, 1))).label("completed"),
+            func.count(case((ContainerSession.status == ContainerStatus.FAILED, 1))).label("failed"),
+            func.count(case((ContainerSession.status == ContainerStatus.TIMEOUT, 1))).label("timeout"),
+        ).where(ContainerSession.installation_id.in_(installation_ids))
+    )
+    row = result.one()
+    return StatusCounts(
+        completed=row.completed,
+        failed=row.failed,
+        timeout=row.timeout,
+        total=row.total,
+    )
+
+
+async def count_per_day(
+    session: AsyncSession,
+    installation_ids: list[uuid.UUID],
+    *,
+    since: datetime,
+) -> list[DailyCount]:
+    """Count sessions per calendar day since ``since``, oldest first."""
+    if not installation_ids:
+        return []
+
+    result = await session.execute(
+        select(
+            cast(ContainerSession.created_at, Date).label("day"),
+            func.count(ContainerSession.id).label("count"),
+        )
+        .where(
+            ContainerSession.installation_id.in_(installation_ids),
+            ContainerSession.created_at >= since,
+        )
+        .group_by("day")
+        .order_by("day")
+    )
+    return [DailyCount(day=row.day, count=row.count) for row in result.all()]
+
+
+async def count_grouped_by_installation(
+    session: AsyncSession,
+    installation_ids: list[uuid.UUID],
+) -> dict[uuid.UUID, int]:
+    """Session count per installation — one GROUP BY, never a query per row."""
+    if not installation_ids:
+        return {}
+
+    result = await session.execute(
+        select(ContainerSession.installation_id, func.count(ContainerSession.id))
+        .where(ContainerSession.installation_id.in_(installation_ids))
+        .group_by(ContainerSession.installation_id)
+    )
+    return {installation_id: count for installation_id, count in result.all()}

apps/api/src/helprs/modules/identity/github.py

@@ -0,0 +1,90 @@
+"""Typed boundary to GitHub's OAuth and user APIs.
+
+Every GitHub response is parsed into a model here, so a shape change surfaces
+as a validation error at the edge instead of a ``KeyError`` deep in a service.
+Nothing downstream of this module handles raw JSON.
+"""
+
+import httpx
+from pydantic import BaseModel, Field, ValidationError
+
+from helprs.core.config import Settings
+from helprs.core.exceptions import ExternalServiceError, UnauthorizedError
+
+GITHUB_TOKEN_URL = "https://github.com/login/oauth/access_token"
+GITHUB_USER_URL = "https://api.github.com/user"
+
+_TIMEOUT_SECONDS = 10.0
+
+
+class GitHubOAuthToken(BaseModel):
+    """The credential GitHub hands back for an authorization code."""
+
+    access_token: str
+    token_type: str = "bearer"
+    scope: str = ""
+
+
+class GitHubUserProfile(BaseModel):
+    """The subset of GitHub's user payload the application stores."""
+
+    github_id: int = Field(alias="id")
+    login: str
+    email: str | None = None
+    avatar_url: str | None = None
+
+
+def _parse[ModelT: BaseModel](model: type[ModelT], payload: object, what: str) -> ModelT:
+    try:
+        return model.model_validate(payload)
+    except ValidationError as e:
+        raise ExternalServiceError(f"Unexpected {what} payload from GitHub") from e
+
+
+async def exchange_code_for_token(code: str, settings: Settings) -> GitHubOAuthToken:
+    """Exchange an OAuth authorization code for a user access token."""
+    try:
+        async with httpx.AsyncClient(timeout=_TIMEOUT_SECONDS) as client:
+            resp = await client.post(
+                GITHUB_TOKEN_URL,
+                data={
+                    "client_id": settings.GITHUB_CLIENT_ID,
+                    "client_secret": settings.GITHUB_CLIENT_SECRET,
+                    "code": code,
+                },
+                headers={"Accept": "application/json"},
+            )
+            resp.raise_for_status()
+    except httpx.TimeoutException as e:
+        raise ExternalServiceError("GitHub is temporarily unavailable") from e
+    except httpx.HTTPStatusError as e:
+        raise ExternalServiceError("GitHub token exchange failed") from e
+
+    payload = resp.json()
+    # GitHub answers 200 with an ``error`` key for a bad or expired code.
+    if isinstance(payload, dict) and "error" in payload:
+        raise UnauthorizedError(f"GitHub OAuth error: {payload['error']}")
+
+    return _parse(GitHubOAuthToken, payload, "OAuth token")
+
+
+async def fetch_user_profile(access_token: str) -> GitHubUserProfile:
+    """Fetch the profile of the user owning ``access_token``."""
+    try:
+        async with httpx.AsyncClient(timeout=_TIMEOUT_SECONDS) as client:
+            resp = await client.get(
+                GITHUB_USER_URL,
+                headers={
+                    "Authorization": f"Bearer {access_token}",
+                    "Accept": "application/json",
+                },
+            )
+            resp.raise_for_status()
+    except httpx.TimeoutException as e:
+        raise ExternalServiceError("GitHub is temporarily unavailable") from e
+    except httpx.HTTPStatusError as e:
+        if e.response.status_code == 401:
+            raise UnauthorizedError("GitHub token is invalid or revoked") from e
+        raise ExternalServiceError("GitHub API error") from e
+
+    return _parse(GitHubUserProfile, resp.json(), "user")

apps/api/src/helprs/modules/identity/repository.py

@@ -0,0 +1,29 @@
+"""Persistence for GitHub user identities.
+
+Every query against ``github_users`` lives here; services above never build
+SQL and never see an ``AsyncSession`` method other than through this module.
+"""
+
+import uuid
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from helprs.modules.identity.models import GitHubUser
+
+
+async def get_by_github_id(session: AsyncSession, github_id: int) -> GitHubUser | None:
+    result = await session.execute(select(GitHubUser).where(GitHubUser.github_id == github_id))
+    return result.scalar_one_or_none()
+
+
+async def get_by_id(session: AsyncSession, user_id: uuid.UUID) -> GitHubUser | None:
+    result = await session.execute(select(GitHubUser).where(GitHubUser.id == user_id))
+    return result.scalar_one_or_none()
+
+
+async def add(session: AsyncSession, user: GitHubUser) -> GitHubUser:
+    """Stage a new user and flush so its generated id is available."""
+    session.add(user)
+    await session.flush()
+    return user