primarypath-server 1.0.0__py3-none-any.whl

app/auth.py

@@ -0,0 +1,714 @@
+"""SSO (OIDC) for reviewers + service-token auth for agents.
+
+Two distinct auth planes, kept deliberately separate:
+- Humans: OIDC Authorization Code flow with PKCE -> server session row ->
+  signed httpOnly cookie. Every decision then carries a verified SSO
+  subject, not a typed name.
+- Agents: a bearer service token from settings. Agents are not humans; a
+  human session never authorizes agent-facing endpoints and vice versa.
+
+Both planes are off (open, dev mode) until configured in settings.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import secrets
+import time
+from urllib.parse import urlencode
+
+import httpx
+import jwt
+from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import JSONResponse, RedirectResponse
+
+SESSION_COOKIE = "primarypath_session"
+FLOW_COOKIE = "primarypath_auth_flow"
+
+
+def session_cookie(settings) -> str:
+    """`__Host-primarypath_session` on a secure deployment (app/security)."""
+    from .security import cookie_name
+    return cookie_name(SESSION_COOKIE, settings)
+
+
+def flow_cookie(settings) -> str:
+    from .security import cookie_name
+    return cookie_name(FLOW_COOKIE, settings)
+
+
+# -- cookie signing (hmac, stdlib) --------------------------------------------
+
+def _b64(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).decode().rstrip("=")
+
+
+def _unb64(s: str) -> bytes:
+    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+
+
+def sign_value(secret: str, obj: dict) -> str:
+    payload = _b64(json.dumps(obj, separators=(",", ":")).encode())
+    sig = _b64(hmac.new(secret.encode(), payload.encode(), hashlib.sha256).digest())
+    return f"{payload}.{sig}"
+
+
+def unsign_value(secret: str, value: str) -> dict | None:
+    try:
+        payload, sig = value.split(".", 1)
+        expected = _b64(hmac.new(secret.encode(), payload.encode(),
+                                 hashlib.sha256).digest())
+        if not hmac.compare_digest(expected, sig):
+            return None
+        return json.loads(_unb64(payload))
+    except Exception:
+        return None
+
+
+# -- OIDC client ---------------------------------------------------------------
+
+class OIDC:
+    def __init__(self, issuer: str, client_id: str, client_secret: str,
+                 redirect_url: str, scopes: str,
+                 algorithms: list[str] | None = None):
+        self.issuer = issuer.rstrip("/")
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.redirect_url = redirect_url
+        self.scopes = scopes
+        self.algorithms = algorithms or ["RS256"]
+        self.http = httpx.AsyncClient(timeout=10)
+        self._config: dict | None = None
+        self._jwks: dict | None = None
+
+    async def config(self) -> dict:
+        if self._config is None:
+            r = await self.http.get(
+                f"{self.issuer}/.well-known/openid-configuration")
+            r.raise_for_status()
+            self._config = r.json()
+        return self._config
+
+    async def _jwk_key(self, kid: str | None):
+        for attempt in range(2):
+            if self._jwks is None or attempt == 1:
+                cfg = await self.config()
+                r = await self.http.get(cfg["jwks_uri"])
+                r.raise_for_status()
+                self._jwks = r.json()
+            for k in self._jwks.get("keys", []):
+                if kid is None or k.get("kid") == kid:
+                    return jwt.PyJWK(k).key
+        raise HTTPException(401, "no matching JWKS key for id_token")
+
+    async def exchange_code(self, code: str, verifier: str) -> dict:
+        cfg = await self.config()
+        r = await self.http.post(cfg["token_endpoint"], data={
+            "grant_type": "authorization_code", "code": code,
+            "redirect_uri": self.redirect_url, "client_id": self.client_id,
+            "client_secret": self.client_secret, "code_verifier": verifier})
+        if r.status_code != 200:
+            raise HTTPException(401, "token exchange failed")
+        return r.json()
+
+    async def validate_id_token(self, token: str, nonce: str) -> dict:
+        try:
+            header = jwt.get_unverified_header(token)
+            key = await self._jwk_key(header.get("kid"))
+            claims = jwt.decode(token, key=key, algorithms=self.algorithms,
+                                audience=self.client_id, issuer=self.issuer)
+        except HTTPException:
+            raise
+        except jwt.PyJWTError as e:
+            raise HTTPException(401, f"invalid id_token: {e}") from None
+        if claims.get("nonce") != nonce:
+            raise HTTPException(401, "id_token nonce mismatch")
+        return claims
+
+    def auth_url_params(self, cfg: dict, state: str, nonce: str,
+                        challenge: str) -> str:
+        return cfg["authorization_endpoint"] + "?" + urlencode({
+            "response_type": "code", "client_id": self.client_id,
+            "redirect_uri": self.redirect_url, "scope": self.scopes,
+            "state": state, "nonce": nonce,
+            "code_challenge": challenge, "code_challenge_method": "S256"})
+
+
+# -- sessions -------------------------------------------------------------------
+
+async def create_session(pool, secret: str, ttl_s: int, claims: dict,
+                         roles: list[str]) -> tuple[str, str]:
+    sid = secrets.token_urlsafe(24)
+    csrf = secrets.token_urlsafe(24)
+    groups = list(claims.get("groups") or claims.get("roles") or [])
+    async with pool.connection() as conn:
+        # opportunistic cleanup: expired rows are dead weight (they never
+        # authenticate; get_identity checks expires_at) and logins are the
+        # natural, low-frequency moment to sweep them
+        await conn.execute("DELETE FROM sessions WHERE expires_at <= %s",
+                           (int(time.time()),))
+        await conn.execute(
+            "INSERT INTO sessions (id, subject, email, name, roles, groups, "
+            "csrf, expires_at) VALUES (%s, %s, %s, %s, %s::jsonb, %s::jsonb, "
+            "%s, %s)",
+            (sid, claims["sub"], claims.get("email"),
+             claims.get("name") or claims.get("preferred_username"),
+             json.dumps(roles), json.dumps(groups), csrf,
+             int(time.time()) + ttl_s))
+    return sid, sign_value(secret, {"sid": sid})
+
+
+async def get_identity(request: Request) -> dict | None:
+    """The verified session identity, or None."""
+    settings = request.app.state.settings
+    if not settings.session_secret:
+        return None
+    raw = request.cookies.get(session_cookie(settings))
+    if not raw:
+        return None
+    data = unsign_value(settings.session_secret, raw)
+    if not data or "sid" not in data:
+        return None
+    async with request.app.state.pool.connection() as conn:
+        cur = await conn.execute(
+            "SELECT id, subject, email, name, roles, csrf, groups FROM sessions "
+            "WHERE id = %s AND expires_at > %s", (data["sid"], int(time.time())))
+        row = await cur.fetchone()
+    if row is None:
+        return None
+    return {"sid": row[0], "subject": row[1], "email": row[2], "name": row[3],
+            "roles": row[4], "csrf": row[5], "groups": row[6]}
+
+
+def reviewer_string(identity: dict) -> str:
+    return (f"{identity.get('name') or '?'} <{identity.get('email') or '?'}> "
+            f"(sub:{identity['subject']})")
+
+
+def resolve_roles(claims: dict, settings) -> list[str]:
+    """Map OIDC claims to roles. Default deny, always: once an IdP is wired,
+    an unmapped user gets no roles and no access — map at least one admin
+    via rbac_admin_emails before anyone can use the inbox."""
+    groups = set(claims.get("groups") or claims.get("roles") or [])
+    email = (claims.get("email") or "").lower()
+    roles: list[str] = []
+    if (groups & settings.admin_groups
+            or (email and email in {e.lower() for e in settings.admin_emails})):
+        roles.append("admin")
+    if roles or groups & settings.approver_groups:
+        if "approver" not in roles:
+            roles.append("approver")
+    return roles
+
+
+async def resolve_tenant(request: Request) -> str:
+    """The tenant comes from the AUTH CONTEXT, never from a request field —
+    a client-chosen tenant would be a cross-tenant hole. The API surface is
+    single-tenant today: every credential maps to the default tenant. This
+    function is the seam where a token->tenant or SSO-claim->tenant map
+    plugs in (F20 built the data layer; the product surface is deferred)."""
+    from .ledger.store import DEFAULT_TENANT
+
+    return DEFAULT_TENANT
+
+
+async def resolve_agent(request: Request) -> tuple[str, str | None]:
+    """(agent_id, unit) for an agent-plane request, resolved server-side
+    from the presented service token's record — the same discipline as
+    resolve_tenant: never from the request body, so an agent cannot claim
+    a different agent or unit (F24). The env service token and open dev
+    mode ride the default agent."""
+    from .ledger.store import DEFAULT_AGENT
+
+    rec = await _issued_token_record(request, "service")
+    if rec is not None and rec.get("agent_id"):
+        # the registry is the map: issuing a token with a unit registers it
+        # there, and PUT /api/agents moves it. The token's own unit is only
+        # what it was issued with; stamping it after a move would keep the
+        # agent's new work in the old unit (B23)
+        unit = await request.app.state.agents.unit_of(
+            rec["agent_id"], await resolve_tenant(request))
+        if unit is None:
+            unit = rec.get("unit")
+        return rec["agent_id"], unit
+    return DEFAULT_AGENT, None
+
+
+async def agent_credential(request: Request) -> str:
+    """The audit identity of the agent-plane credential presenting this
+    request, derived server-side — never typed by the caller. An issued
+    service token names the agent it is pinned to AND the revocable
+    credential (`agent:<id> (token:<token id> <label>)`), the same
+    binding decisions get under issued admin tokens; the env service
+    token is single-trust and says so; open dev mode says so too."""
+    from .ledger.store import DEFAULT_AGENT
+
+    rec = await _issued_token_record(request, "service")
+    if rec is not None:
+        agent = rec.get("agent_id") or DEFAULT_AGENT
+        label = rec.get("label")
+        bind = f"token:{rec['id']}" + (f" {label}" if label else "")
+        return f"agent:{agent} ({bind})"
+    if _service_ok(request):
+        return f"agent:{DEFAULT_AGENT} (env service token)"
+    return f"agent:{DEFAULT_AGENT} (open, no auth configured)"
+
+
+async def credential_id(request: Request) -> str:
+    """A stable, non-secret name for the presenting credential, for
+    idempotency fingerprints: issued tokens by id, env tokens by plane,
+    sessions by subject, open mode as such."""
+    for kind in ("service", "admin"):
+        rec = await _issued_token_record(request, kind)
+        if rec is not None:
+            return f"token:{rec['id']}"
+    if _service_ok(request):
+        return "env:service"
+    if _admin_token_ok(request):
+        return "env:admin"
+    identity = await get_identity(request)
+    if identity is not None:
+        return f"user:{identity.get('subject')}"
+    return "open"
+
+
+async def agent_pin(request: Request) -> str | None:
+    """The agent this credential is PINNED to, or None for an unpinned
+    credential (the env service token, open dev mode). Read from the
+    issued token record — never inferred from the agent's name: a token
+    pinned to an agent that happens to be called "default" is pinned.
+    Ownership checks (idempotent reuse, cancel, redeem) take this, so
+    only an unpinned credential has the single-trust posture."""
+    rec = await _issued_token_record(request, "service")
+    if rec is not None and rec.get("agent_id"):
+        return rec["agent_id"]
+    return None
+
+
+async def require_agent_binding(request: Request, agent: str) -> None:
+    """Evidence writes that NAME an agent (evals, deploy gates) must not
+    outrun the credential: a service token pinned to agent A could
+    otherwise record evals for agent B or squat B's gate — forged
+    evidence under a real signature. Unpinned tokens (the env token, open
+    dev) are the single-trust posture and may write for any agent."""
+    rec = await _issued_token_record(request, "service")
+    if rec is not None and rec.get("agent_id") and rec["agent_id"] != agent:
+        raise HTTPException(
+            403, f"token is bound to agent '{rec['agent_id']}' and cannot "
+                 f"write evidence for '{agent}'")
+
+
+def reviewer_role(identity: dict | None) -> str | None:
+    if identity is None:
+        return None
+    roles = identity.get("roles") or []
+    return "admin" if "admin" in roles else ("approver" if "approver" in roles else None)
+
+
+# -- route dependencies -----------------------------------------------------------
+
+def _human_plane_on(request: Request) -> bool:
+    return bool(request.app.state.settings.oidc_issuer)
+
+
+def _service_token(request: Request) -> str | None:
+    auth = request.headers.get("Authorization", "")
+    return auth.removeprefix("Bearer ").strip() if auth.startswith("Bearer ") else None
+
+
+def _service_ok(request: Request) -> bool:
+    expected = request.app.state.settings.service_token
+    got = _service_token(request)
+    return bool(expected and got and hmac.compare_digest(expected, got))
+
+
+def _admin_token_ok(request: Request) -> bool:
+    expected = request.app.state.settings.admin_token
+    got = _service_token(request)
+    return bool(expected and got and hmac.compare_digest(expected, got))
+
+
+async def _issued_token_record(request: Request, kind: str) -> dict | None:
+    """The issued (DB) token record of the given kind (F22/F24), or None.
+    Kept distinct from the other plane: a service token never verifies as
+    admin and vice versa. The token's tenant must match the request's
+    resolved tenant, so a token issued for tenant B never authenticates a
+    request resolving to A (the F20 seam; inert while resolve_tenant is the
+    default tenant)."""
+    store = getattr(request.app.state, "tokens", None)
+    tok = _service_token(request)
+    if store is None or not tok:
+        return None
+    rec = await store.verify(tok, kind)
+    if rec is None or rec["tenant_id"] != await resolve_tenant(request):
+        return None
+    return rec
+
+
+async def _issued_token_ok(request: Request, kind: str) -> bool:
+    return await _issued_token_record(request, kind) is not None
+
+
+async def _service_ok_any(request: Request) -> bool:
+    return _service_ok(request) or await _issued_token_ok(request, "service")
+
+
+async def _admin_ok_any(request: Request) -> bool:
+    return _admin_token_ok(request) or await _issued_token_ok(request, "admin")
+
+
+async def _any_auth_configured(request: Request) -> bool:
+    """Auth counts as configured the moment an OPERATOR credential exists —
+    any env setting, or a console-issued ADMIN token. Without the issued
+    clause, a deployment that issued its tokens from the console and set
+    no env token would grade as unconfigured and run every open-dev
+    fallback wide open, the issued tokens purely decorative.
+
+    Deliberately asymmetric per plane: an issued SERVICE token closes only
+    the agent plane (require_agent), not the operator surfaces — the
+    console has no bearer mode, so issuing an agent token from the open
+    evaluation console must not brick the very session that issued it.
+    Locking the operator planes is what issuing an operator credential
+    means; and the bind guard still refuses a network-reachable bind with
+    no env auth, so the open evaluation posture stays loopback-only."""
+    s = request.app.state.settings
+    if s.oidc_issuer or s.service_token or s.admin_token:
+        return True
+    store = getattr(request.app.state, "tokens", None)
+    return store is not None and await store.any_active("admin")
+
+
+async def is_agent_plane(request: Request) -> bool:
+    """Whether this request is authenticated as an agent (a service token,
+    or open dev mode where no plane is configured). The execution grant's
+    signature is returned only here: it is a bearer capability for one
+    consequential action, meant for the executor, not for the console."""
+    if not await _any_auth_configured(request):
+        return True
+    return await _service_ok_any(request)
+
+
+async def require_agent(request: Request) -> None:
+    """Agent-facing endpoints: service token only (never a human session).
+    The plane is configured by the env service token OR any issued
+    service token."""
+    if request.app.state.settings.service_token is None:
+        store = getattr(request.app.state, "tokens", None)
+        if store is None or not await store.any_active("service"):
+            return  # plane not configured: open (dev)
+    if not await _service_ok_any(request):
+        raise HTTPException(401, "service token required")
+
+
+def _require_role(identity: dict, role: str) -> None:
+    if role not in (identity.get("roles") or []):
+        raise HTTPException(403, f"{role} role required")
+
+
+async def require_reader(request: Request) -> None:
+    """Read endpoints: an approver session or a service/admin token, once
+    auth is on."""
+    if not await _any_auth_configured(request):
+        return
+    if await _service_ok_any(request) or await _admin_ok_any(request):
+        return
+    if _human_plane_on(request):
+        identity = await get_identity(request)
+        if identity is not None:
+            _require_role(identity, "approver")
+            return
+    raise HTTPException(401, "authentication required")
+
+
+async def require_console_reader(request: Request) -> None:
+    """Human-console reads (F22 traces): an approver+ session or an ADMIN
+    token — NOT the bare agent service token. Traces surface every run's
+    reasoning, tool arguments/results, and tenant-wide cost; the low-
+    privilege token every governed agent carries must not exfiltrate them.
+    (Approval reads keep the service token because the agent polls its own
+    wait_for_decision; a trace console has no such need.)"""
+    if not await _any_auth_configured(request):
+        return
+    if await _admin_ok_any(request):
+        return
+    if _human_plane_on(request):
+        identity = await get_identity(request)
+        if identity is not None:
+            _require_role(identity, "approver")
+            return
+    raise HTTPException(401, "approver session or admin token required")
+
+
+async def require_reviewer(request: Request) -> dict | None:
+    """Human mutating endpoints: approver session + CSRF when the human
+    plane is on.
+
+    Returns the identity (None in open/dev mode, where the request body
+    must carry a reviewer name instead).
+
+    Token-only deployments (tokens configured, no OIDC) require the ADMIN
+    token: reads are token-gated there, so writes must be too, and the
+    agent service token must never decide the approvals it created.
+    """
+    if not _human_plane_on(request):
+        if not await _any_auth_configured(request):
+            return None  # nothing configured: open dev mode
+        rec = await _issued_token_record(request, "admin")
+        if rec is not None:
+            # an ISSUED (per-person) admin token: bind the recorded
+            # reviewer to the credential, so token-mode decisions name a
+            # revocable identity, not just a typed string
+            return {"token_id": rec["id"], "token_label": rec.get("label"),
+                    "roles": ["admin"]}
+        if _admin_token_ok(request):
+            return None  # env admin token; body names the reviewer
+        raise HTTPException(401, "admin token or sign-in required")
+    identity = await get_identity(request)
+    if identity is None:
+        raise HTTPException(401, "sign in required")
+    header = request.headers.get("X-CSRF-Token", "")
+    if not hmac.compare_digest(identity["csrf"], header):
+        raise HTTPException(403, "missing or bad CSRF token")
+    _require_role(identity, "approver")
+    return identity
+
+
+async def require_admin(request: Request) -> dict | None:
+    """Admin endpoints: an admin session or the dedicated ADMIN token. The
+    agent service token never satisfies this — every governed agent carries
+    that token, and it must not be able to rotate keys or export the full
+    audit log. Open only when no auth at all is configured (dev)."""
+    if not await _any_auth_configured(request):
+        return None
+    if await _admin_ok_any(request):
+        return None
+    if _human_plane_on(request):
+        identity = await get_identity(request)
+        if identity is not None:
+            header = request.headers.get("X-CSRF-Token", "")
+            if (request.method not in ("GET", "HEAD")
+                    and not hmac.compare_digest(identity["csrf"], header)):
+                raise HTTPException(403, "missing or bad CSRF token")
+            _require_role(identity, "admin")
+            return identity
+    raise HTTPException(401, "authentication required")
+
+
+# -- the need-to-know read gate (F24) -----------------------------------------------
+
+UNRESTRICTED = None  # scope value: no unit filtering applies
+_BREAK_GLASS_DEDUP_S = 600
+
+
+async def admin_read_activity_enabled(request: Request, tenant: str) -> bool:
+    """Effective admin_can_read_activity: the runtime (event-sourced) toggle
+    when one has been set, else the configured default (off — separation of
+    duties ships closed)."""
+    async with request.app.state.pool.connection() as conn:
+        cur = await conn.execute(
+            "SELECT value FROM config_view WHERE tenant_id = %s "
+            "AND key = 'admin_can_read_activity'", (tenant,))
+        row = await cur.fetchone()
+    if row is not None:
+        return bool(row[0])
+    return request.app.state.settings.admin_can_read_activity
+
+
+async def record_break_glass(request: Request, tenant: str, actor: str,
+                             what: str) -> None:
+    """An admin reading activity under admin_can_read_activity is itself a
+    chained governance event — break-glass is provable. Deduped in memory
+    per (tenant, actor) so a polling console appends one record per window,
+    not one per request."""
+    dedup = getattr(request.app.state, "_break_glass_seen", None)
+    if dedup is None:
+        dedup = request.app.state._break_glass_seen = {}
+    now = time.time()
+    last = dedup.get((tenant, actor))
+    if last is not None and now - last < _BREAK_GLASS_DEDUP_S:
+        return
+    dedup[(tenant, actor)] = now
+    await request.app.state.ledger.append(
+        "admin_action",
+        {"action": "read_activity", "by": actor, "detail": what},
+        tenant=tenant)
+
+
+async def activity_scope(request: Request, record: bool = True) -> dict | None:
+    """What activity this caller may READ. Visibility follows the unit,
+    never the admin role (F24).
+
+    Returns UNRESTRICTED (None) when no gate applies — open dev mode, the
+    single-trust env tokens without a human plane, or an admin under an
+    enabled (and audited) admin_can_read_activity. Otherwise:
+
+        {"units": set[str],   # agents in these units are visible
+         "agent": str|None,   # an issued service token pinned to its agent
+         "role": str|None,    # 'admin' drives the console's locked state
+         "locked": bool}      # admin barred by separation of duties
+
+    Agents with NO unit assigned stay visible to any authorized reader
+    (enforced in the queries) — need-to-know starts when units are mapped,
+    so pre-F24 installs do not go dark.
+
+    The caller is assumed already authenticated (require_reader et al.);
+    this only narrows what an authenticated reader sees.
+    """
+    if not await _any_auth_configured(request):
+        return UNRESTRICTED
+    tenant = await resolve_tenant(request)
+
+    # agent plane: an issued token pinned to an agent reads only that agent
+    # (its own queue and decisions); tokens without a pin are the
+    # single-trust dev posture and read unrestricted
+    svc = await _issued_token_record(request, "service")
+    if svc is not None:
+        if svc.get("agent_id"):
+            return {"units": set(), "agent": svc["agent_id"], "role": None,
+                    "locked": False}
+        return UNRESTRICTED
+    if _service_ok(request):
+        return UNRESTRICTED
+
+    # operator plane without a human plane configured is the same
+    # single-trust posture (dev/tests); with OIDC on, the admin token is an
+    # operator credential and separation of duties applies to it
+    if await _admin_ok_any(request):
+        if not _human_plane_on(request):
+            return UNRESTRICTED
+        if await admin_read_activity_enabled(request, tenant):
+            if record:
+                await record_break_glass(request, tenant, "admin-token",
+                                         request.url.path)
+            return UNRESTRICTED
+        return {"units": set(), "agent": None, "role": "admin",
+                "locked": True}
+
+    identity = await get_identity(request)
+    if identity is None:
+        # authenticated by some other configured means; nothing to scope by
+        return UNRESTRICTED
+    units = set(identity.get("groups") or [])
+    role = reviewer_role(identity)
+    if role == "admin" and await admin_read_activity_enabled(request, tenant):
+        if record:
+            await record_break_glass(request, tenant,
+                                     reviewer_string(identity),
+                                     request.url.path)
+        return UNRESTRICTED
+    return {"units": units, "agent": None, "role": role,
+            "locked": role == "admin" and not units}
+
+
+def scope_units(scope: dict | None) -> set[str] | None:
+    """The `units` filter for ledger queries: None = unrestricted. An
+    agent-pinned scope filters by agent, not by unit."""
+    if scope is None or scope.get("agent") is not None:
+        return None
+    return scope["units"]
+
+
+def visible_to(scope: dict | None, agent_id: str | None,
+               unit: str | None) -> bool:
+    """Whether one record (an approval, a run) is inside the caller's
+    need-to-know scope."""
+    if scope is None:
+        return True
+    if scope.get("agent") is not None:
+        return agent_id == scope["agent"]
+    return unit is None or unit in scope["units"]
+
+
+# -- /auth routes ------------------------------------------------------------------
+
+router = APIRouter(prefix="/auth")
+
+
+def _oidc(request: Request) -> OIDC:
+    oidc = getattr(request.app.state, "oidc", None)
+    if oidc is None:
+        raise HTTPException(404, "SSO not configured")
+    return oidc
+
+
+@router.get("/login")
+async def login(request: Request):
+    oidc = _oidc(request)
+    settings = request.app.state.settings
+    state = secrets.token_urlsafe(16)
+    nonce = secrets.token_urlsafe(16)
+    verifier = secrets.token_urlsafe(48)
+    challenge = _b64(hashlib.sha256(verifier.encode()).digest())
+    cfg = await oidc.config()
+    resp = RedirectResponse(oidc.auth_url_params(cfg, state, nonce, challenge),
+                            status_code=302)
+    from .security import cookie_kwargs
+    resp.set_cookie(flow_cookie(settings),
+                    sign_value(settings.session_secret,
+                               {"state": state, "nonce": nonce,
+                                "verifier": verifier, "ts": int(time.time())}),
+                    max_age=600, **cookie_kwargs(settings))
+    return resp
+
+
+@router.get("/callback")
+async def callback(request: Request, code: str = "", state: str = ""):
+    oidc = _oidc(request)
+    settings = request.app.state.settings
+    flow = unsign_value(settings.session_secret,
+                        request.cookies.get(flow_cookie(settings), ""))
+    if not flow or not state or not hmac.compare_digest(flow["state"], state):
+        raise HTTPException(401, "state mismatch (login flow expired?)")
+    # the cookie's max_age is advice to the browser; the server must
+    # enforce the flow's lifetime itself, or a captured flow cookie
+    # (state + nonce + PKCE verifier) replays forever
+    if int(time.time()) - int(flow.get("ts", 0)) > 600:
+        raise HTTPException(401, "login flow expired, start again")
+    tokens = await oidc.exchange_code(code, flow["verifier"])
+    claims = await oidc.validate_id_token(tokens.get("id_token", ""),
+                                          flow["nonce"])
+    _, cookie = await create_session(request.app.state.pool,
+                                     settings.session_secret,
+                                     settings.session_ttl_s, claims,
+                                     resolve_roles(claims, settings))
+    from .security import cookie_kwargs
+    kw = cookie_kwargs(settings)
+    resp = RedirectResponse("/", status_code=302)
+    resp.delete_cookie(flow_cookie(settings), path=kw["path"],
+                       secure=kw["secure"], httponly=True, samesite="lax")
+    resp.set_cookie(session_cookie(settings), cookie,
+                    max_age=settings.session_ttl_s, **kw)
+    return resp
+
+
+@router.get("/me")
+async def me(request: Request):
+    if not _human_plane_on(request):
+        raise HTTPException(404, "SSO not configured")
+    identity = await get_identity(request)
+    if identity is None:
+        raise HTTPException(401, "not signed in")
+    return {"subject": identity["subject"], "email": identity["email"],
+            "name": identity["name"], "roles": identity["roles"],
+            "csrf": identity["csrf"]}
+
+
+@router.post("/logout")
+async def logout(request: Request):
+    identity = await get_identity(request)
+    if identity is not None:
+        header = request.headers.get("X-CSRF-Token", "")
+        if not hmac.compare_digest(identity["csrf"], header):
+            raise HTTPException(403, "missing or bad CSRF token")
+        async with request.app.state.pool.connection() as conn:
+            await conn.execute("DELETE FROM sessions WHERE id = %s",
+                               (identity["sid"],))
+    from .security import cookie_kwargs
+    kw = cookie_kwargs(request.app.state.settings)
+    resp = JSONResponse({"ok": True})
+    resp.delete_cookie(session_cookie(request.app.state.settings),
+                       path=kw["path"], secure=kw["secure"], httponly=True,
+                       samesite="lax")
+    return resp