codexLB-up 1.25.0b10__py3-none-any.whl

app/core/auth/providers/registry.py

@@ -0,0 +1,118 @@
+"""Process cache over ``dashboard_auth_providers`` joined with the auth mode.
+
+Same shape as :class:`app.core.auth.dashboard_users_cache.DashboardUsersCache`:
+a 5 s TTL bounds staleness inside one replica, and a provider write bumps the
+``dashboard_users`` invalidation namespace (providers govern how identities
+become users, so the two caches share one bus and one callback).
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+
+import anyio
+
+from app.core.auth.dashboard_mode import DashboardAuthMode
+from app.core.auth.providers import AuthProvider, PasswordProvider, TrustedHeaderProvider
+from app.core.auth.providers.oidc import get_oidc_provider
+from app.core.cache.invalidation import NAMESPACE_DASHBOARD_USERS, get_cache_invalidation_poller
+from app.db.models import AuthProviderKind, DashboardAuthProvider
+from app.db.session import SessionLocal
+from app.modules.auth_providers.repository import AuthProvidersRepository
+
+_IMPLEMENTATIONS: dict[AuthProviderKind, AuthProvider] = {
+    AuthProviderKind.PASSWORD: PasswordProvider(),
+    AuthProviderKind.TRUSTED_HEADER: TrustedHeaderProvider(),
+    AuthProviderKind.OIDC: get_oidc_provider(),
+}
+
+
+def provider_active(row: DashboardAuthProvider, mode: DashboardAuthMode) -> bool:
+    """A provider serves sign-ins when its row is enabled and the auth mode admits its kind.
+
+    ``password`` follows the mode's existing rules (management is refused in
+    ``disabled`` mode elsewhere), ``trusted_header`` needs the matching mode,
+    ``oidc`` serves ``standard`` and ``trusted_header`` but never ``disabled``
+    (an install that has turned dashboard authentication off must not grow a
+    sign-in flow that mints sessions and provisions accounts), and a kind with
+    no implementation is never active.
+    """
+
+    if not row.enabled:
+        return False
+    try:
+        kind = AuthProviderKind(row.kind)
+    except ValueError:
+        return False
+    if kind not in _IMPLEMENTATIONS:
+        return False
+    if kind is AuthProviderKind.TRUSTED_HEADER:
+        return mode == DashboardAuthMode.TRUSTED_HEADER
+    if kind is AuthProviderKind.OIDC:
+        return mode != DashboardAuthMode.DISABLED
+    return True
+
+
+@dataclass(frozen=True, slots=True)
+class ActiveProvider:
+    row: DashboardAuthProvider
+    provider: AuthProvider
+
+
+class AuthProviderRegistry:
+    def __init__(self, *, ttl_seconds: float = 5.0) -> None:
+        if ttl_seconds <= 0:
+            raise ValueError("ttl_seconds must be positive")
+        self._ttl_seconds = ttl_seconds
+        self._rows: tuple[tuple[DashboardAuthProvider, ...], float] | None = None
+        self._lock = anyio.Lock()
+
+    async def rows(self) -> tuple[DashboardAuthProvider, ...]:
+        now = time.monotonic()
+        if self._rows is not None and now - self._rows[1] < self._ttl_seconds:
+            return self._rows[0]
+        async with self._lock:
+            now = time.monotonic()
+            if self._rows is not None and now - self._rows[1] < self._ttl_seconds:
+                return self._rows[0]
+            async with SessionLocal() as session:
+                rows = tuple(await AuthProvidersRepository(session).list_providers())
+            self._rows = (rows, now)
+            return rows
+
+    async def get_active_providers(self, mode: DashboardAuthMode) -> list[ActiveProvider]:
+        """Active providers in table order; the password provider always lists first."""
+
+        active = [
+            ActiveProvider(row=row, provider=_IMPLEMENTATIONS[AuthProviderKind(row.kind)])
+            for row in await self.rows()
+            if provider_active(row, mode)
+        ]
+        return sorted(active, key=lambda item: item.row.kind != AuthProviderKind.PASSWORD.value)
+
+    async def get_active(
+        self, kind: AuthProviderKind, provider_key: str, mode: DashboardAuthMode
+    ) -> ActiveProvider | None:
+        for item in await self.get_active_providers(mode):
+            if item.row.kind == kind.value and item.row.provider_key == provider_key:
+                return item
+        return None
+
+    def clear(self) -> None:
+        self._rows = None
+
+    async def invalidate(self, *, propagate: bool = True) -> None:
+        async with self._lock:
+            self.clear()
+        if propagate:
+            poller = get_cache_invalidation_poller()
+            if poller is not None:
+                await poller.bump(NAMESPACE_DASHBOARD_USERS)
+
+
+_registry = AuthProviderRegistry()
+
+
+def get_auth_provider_registry() -> AuthProviderRegistry:
+    return _registry

app/core/auth/refresh.py

@@ -0,0 +1,394 @@
+from __future__ import annotations
+
+import asyncio
+import contextvars
+import logging
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import Final
+
+import aiohttp
+from pydantic import ValidationError
+
+from app.core.auth import (
+    OpenAIAuthClaims,
+    clean_account_identity_part,
+    extract_id_token_claims,
+    normalize_seat_type,
+    resolve_seat_identity,
+)
+from app.core.auth.models import OAuthTokenPayload
+from app.core.balancer import PERMANENT_FAILURE_CODES
+from app.core.clients.codex import (
+    CodexClient,
+    CodexTransportError,
+    create_codex_session,
+    require_route_or_direct_egress_opt_in,
+)
+from app.core.clients.http import _safe_json, lease_http_session
+from app.core.clients.oauth import _extract_error_code, _extract_error_message
+from app.core.config.settings import AUTH_BASE_URL, OAUTH_CLIENT_ID, OAUTH_SCOPE
+from app.core.resilience.network_recovery import (
+    PROCESS_NETWORK_UNAVAILABLE_CODE,
+    is_pre_dispatch_connection_failure,
+    is_proxy_endpoint_failure,
+    process_network_error_code,
+)
+from app.core.types import JsonObject
+from app.core.upstream_proxy import ResolvedUpstreamRoute
+from app.core.utils.request_id import get_request_id
+from app.core.utils.time import to_utc_naive, utcnow
+
+# Maximum age of an account's last successful refresh before the next request
+# proactively exchanges its refresh token (fixed; issue #1340 / PRINCIPLES.md
+# P2). This module attribute is the single source of the window: tests
+# monkeypatch it, and the traffic-parity canary suppresses proactive refresh by
+# stamping its isolated credential inside the window rather than widening it.
+TOKEN_REFRESH_INTERVAL_DAYS: Final[int] = 8
+# Total timeout of one refresh-token exchange (fixed; issue #1340 / PRINCIPLES.md
+# P2). Per-request budgets may only clamp it lower through the override below.
+TOKEN_REFRESH_TIMEOUT_SECONDS: Final[float] = 8.0
+
+logger = logging.getLogger(__name__)
+_TOKEN_REFRESH_TIMEOUT_OVERRIDE: contextvars.ContextVar[float | None] = contextvars.ContextVar(
+    "token_refresh_timeout_override",
+    default=None,
+)
+
+
+@dataclass(frozen=True)
+class TokenRefreshResult:
+    access_token: str
+    refresh_token: str
+    id_token: str
+    account_id: str | None
+    plan_type: str | None
+    email: str | None
+    workspace_id: str | None = None
+    workspace_label: str | None = None
+    seat_type: str | None = None
+    chatgpt_user_id: str | None = None
+
+
+class RefreshError(Exception):
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        is_permanent: bool,
+        *,
+        transport_error: bool = False,
+        transport_error_code: str | None = None,
+        retryable_same_contract: bool = False,
+        failed_session: aiohttp.ClientSession | None = None,
+        upstream_proxy_fail_closed_reason: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.is_permanent = is_permanent
+        self.transport_error = transport_error
+        self.transport_error_code = transport_error_code
+        self.retryable_same_contract = retryable_same_contract
+        self.failed_session = failed_session
+        self.upstream_proxy_fail_closed_reason = upstream_proxy_fail_closed_reason
+
+
+# Transient cross-replica refresh-contention codes fall into TWO semantically
+# distinct categories that share the SAME external outcome (retryable, never
+# cached, no account-health penalty, failover where applicable) but are NOT the
+# same internal condition. Conflating them would mask a genuinely degraded state
+# behind benign contention, so they are classified separately.
+#
+# (1) BENIGN CLAIM CONTENTION -- ``refresh_claim_timeout``: a peer replica holds
+#     the account's refresh claim (past the wait budget, or admission/budget was
+#     exhausted before the exchange could even start). THIS caller NEVER
+#     exchanged the token; the account's OAuth credentials are entirely healthy;
+#     only its refresh claim is contended. Pure contention -> retry, no penalty.
+REFRESH_CLAIM_CONTENTION_CODES: frozenset[str] = frozenset({"refresh_claim_timeout"})
+
+# (2) POST-EXCHANGE PERSIST/STATUS CAS CONFLICT -- ``token_persist_conflict`` /
+#     ``status_downgrade_conflict``: raised AFTER the upstream OAuth exchange has
+#     already run. ``token_persist_conflict`` in particular means the single-use
+#     refresh token was already CONSUMED upstream but the guarded writes could
+#     not persist the rotated token (a same-plaintext re-encryption storm the
+#     coordinator could not win an atomic compare-and-set window against), so the
+#     database may still hold the just-consumed token; ``status_downgrade_conflict``
+#     follows a PERMANENT refresh failure whose guarded REAUTH status write lost a
+#     compare-and-set. These signal a rare, more-serious internal race than benign
+#     contention and are logged/observed DISTINCTLY. They remain transient (a
+#     plain retry re-runs the WHOLE refresh -- a fresh upstream re-exchange, never
+#     a reuse of the possibly-consumed stored token; see ``refresh_account``), so
+#     their external outcome matches benign contention.
+REFRESH_PERSIST_CONFLICT_CODES: frozenset[str] = frozenset(
+    {
+        "token_persist_conflict",
+        "status_downgrade_conflict",
+    }
+)
+
+# Union of both categories. Every code here carries ``transport_error=True`` (it
+# is transient and retryable), but crucially the account's OAuth credentials are
+# healthy. This union is deliberately DISJOINT from ``code == "transport_error"``,
+# which ``refresh_access_token`` raises for a GENUINE OAuth transport failure (the
+# OAuth request itself timing out / the upstream connection failing).
+TRANSIENT_REFRESH_CONTENTION_CODES: frozenset[str] = REFRESH_CLAIM_CONTENTION_CODES | REFRESH_PERSIST_CONFLICT_CODES
+
+
+def is_refresh_claim_contention(exc: RefreshError) -> bool:
+    """True ONLY for benign cross-replica refresh-CLAIM contention.
+
+    Narrow predicate: matches ``refresh_claim_timeout`` (a peer replica holds the
+    account's refresh claim and THIS caller never exchanged the token). Use this
+    where the code specifically means "a peer holds the claim, we did not
+    exchange". For the failover / skip-penalty EXTERNAL outcome (which treats
+    benign contention and post-exchange persist conflicts identically) gate on
+    ``is_transient_refresh_contention`` instead.
+    """
+    return exc.transport_error and exc.code in REFRESH_CLAIM_CONTENTION_CODES
+
+
+def is_refresh_persist_conflict(exc: RefreshError) -> bool:
+    """True for a POST-EXCHANGE guarded-write compare-and-set conflict.
+
+    Matches ``token_persist_conflict`` / ``status_downgrade_conflict`` -- raised
+    after the OAuth exchange when the rotated-token or REAUTH-status guarded write
+    lost a compare-and-set. Distinct from benign claim contention: for
+    ``token_persist_conflict`` the single-use token was already consumed upstream
+    but its rotation could not be persisted, so the database may still hold the
+    consumed token. This is a rarer, more-serious internal race worth surfacing
+    distinctly in logs/metrics, though its external (retryable, unpenalized)
+    outcome matches benign contention.
+    """
+    return exc.transport_error and exc.code in REFRESH_PERSIST_CONFLICT_CODES
+
+
+def is_transient_refresh_contention(exc: RefreshError) -> bool:
+    """True for EITHER benign claim contention OR a post-exchange persist conflict.
+
+    Proxy failover paths gate their "skip the account-health penalty" behavior on
+    THIS predicate rather than on the broad ``transport_error`` flag. A GENUINE
+    OAuth transport failure (``code == "transport_error"`` -- the OAuth request
+    itself timing out or the upstream connection failing) is transient too but IS
+    the account/route's fault, so it MUST retain its normal health accounting
+    (``record_error`` / ``_handle_stream_error``) and push the broken account into
+    transient backoff instead of being reselected immediately. Only the
+    claim/persist-CAS codes -- where the account's credentials are healthy -- skip
+    the penalty. The two categories are separated by ``is_refresh_claim_contention``
+    (benign) and ``is_refresh_persist_conflict`` (post-exchange) for observability;
+    both take the same unpenalized retryable failover path here.
+    """
+    return exc.transport_error and exc.code in TRANSIENT_REFRESH_CONTENTION_CODES
+
+
+def refresh_contention_kind(exc: RefreshError) -> str | None:
+    """Classify a transient refresh contention for DISTINCT observability.
+
+    Returns ``"claim_contention"`` for benign peer-holds-claim contention,
+    ``"persist_conflict"`` for a post-exchange guarded-write CAS conflict, or
+    ``None`` when ``exc`` is not transient refresh contention. Log/metric call
+    sites use this so a rare, more-serious post-exchange persist conflict is
+    surfaced distinctly rather than lumped with benign claim contention.
+    """
+    if not exc.transport_error:
+        return None
+    if exc.code in REFRESH_CLAIM_CONTENTION_CODES:
+        return "claim_contention"
+    if exc.code in REFRESH_PERSIST_CONFLICT_CODES:
+        return "persist_conflict"
+    return None
+
+
+def should_refresh(last_refresh: datetime, now: datetime | None = None) -> bool:
+    current = to_utc_naive(now) if now is not None else utcnow()
+    last = to_utc_naive(last_refresh)
+    return current - last > timedelta(days=TOKEN_REFRESH_INTERVAL_DAYS)
+
+
+def classify_refresh_error(code: str | None) -> bool:
+    if not code:
+        return False
+    return code in PERMANENT_FAILURE_CODES
+
+
+async def refresh_access_token(
+    refresh_token: str,
+    *,
+    session: aiohttp.ClientSession | None = None,
+    route: ResolvedUpstreamRoute | None = None,
+    codex_client: CodexClient | None = None,
+    allow_direct_egress: bool = False,
+) -> TokenRefreshResult:
+    url = f"{AUTH_BASE_URL}/oauth/token"
+    payload = {
+        "grant_type": "refresh_token",
+        "client_id": OAUTH_CLIENT_ID,
+        "refresh_token": refresh_token,
+        "scope": OAUTH_SCOPE,
+    }
+    timeout = aiohttp.ClientTimeout(total=_effective_token_refresh_timeout())
+
+    headers: dict[str, str] = {}
+    request_id = get_request_id()
+    if request_id:
+        headers["x-request-id"] = request_id
+    require_route_or_direct_egress_opt_in(
+        route=route,
+        allow_direct_egress=allow_direct_egress,
+        operation="token refresh",
+    )
+    failed_session: aiohttp.ClientSession | None = None
+    try:
+        if route is not None:
+            owns_codex_client = codex_client is None
+            active_codex_client = codex_client or CodexClient(create_codex_session())
+            try:
+                resp = await active_codex_client.request(
+                    "POST",
+                    url,
+                    route=route,
+                    json=payload,
+                    headers=headers,
+                    timeout=_effective_token_refresh_timeout(),
+                )
+                data = await _safe_codex_json(resp)
+                status = int(getattr(resp, "status_code", getattr(resp, "status", 0)))
+                payload_data = _validate_token_payload(data)
+                if status >= 400:
+                    logger.warning("Token refresh failed request_id=%s status=%s", get_request_id(), status)
+                    raise _refresh_error_from_payload(payload_data, status)
+            finally:
+                if owns_codex_client:
+                    await active_codex_client.close()
+        else:
+            async with lease_http_session(session) as client_session:
+                failed_session = client_session
+                async with client_session.post(url, json=payload, headers=headers, timeout=timeout) as resp:
+                    data = await _safe_json(resp)
+                    payload_data = _validate_token_payload(data)
+                    if resp.status >= 400:
+                        logger.warning(
+                            "Token refresh failed request_id=%s status=%s",
+                            get_request_id(),
+                            resp.status,
+                        )
+                        raise _refresh_error_from_payload(payload_data, resp.status)
+    except RefreshError:
+        raise
+    except (aiohttp.ClientError, asyncio.TimeoutError, OSError, CodexTransportError) as exc:
+        message = str(exc) or exc.__class__.__name__
+        transport_error_code = (
+            exc.error_code
+            if isinstance(exc, CodexTransportError) and exc.error_code is not None
+            else process_network_error_code(
+                exc,
+                fallback="transport_error",
+                include_permanent_dns=route is None and not is_proxy_endpoint_failure(exc),
+            )
+        )
+        retryable_same_contract = (
+            exc.retryable_same_contract
+            if isinstance(exc, CodexTransportError)
+            else is_pre_dispatch_connection_failure(exc)
+        )
+        raise RefreshError(
+            "transport_error",
+            f"Transport error during token refresh: {message}",
+            False,
+            transport_error=True,
+            transport_error_code=(
+                transport_error_code if transport_error_code == PROCESS_NETWORK_UNAVAILABLE_CODE else None
+            ),
+            # A rotating refresh token may already be consumed once response
+            # headers/body reads begin. Only connector-proven pre-dispatch
+            # failures can retry the same refresh contract.
+            retryable_same_contract=retryable_same_contract,
+            failed_session=failed_session if route is None else None,
+        ) from exc
+
+    if not payload_data.access_token or not payload_data.refresh_token or not payload_data.id_token:
+        raise RefreshError("invalid_response", "Refresh response missing tokens", False)
+
+    claims = extract_id_token_claims(payload_data.id_token)
+    auth_claims = claims.auth or OpenAIAuthClaims()
+    account_id = auth_claims.chatgpt_account_id or claims.chatgpt_account_id
+    plan_type = auth_claims.chatgpt_plan_type or claims.chatgpt_plan_type
+    email = claims.email
+    workspace_id = clean_account_identity_part(auth_claims.workspace_id or claims.workspace_id)
+    workspace_label = clean_account_identity_part(auth_claims.workspace_label or claims.workspace_label)
+    seat_type = normalize_seat_type(auth_claims.seat_type or claims.seat_type)
+    chatgpt_user_id = resolve_seat_identity(claims, auth_claims)
+
+    return TokenRefreshResult(
+        access_token=payload_data.access_token,
+        refresh_token=payload_data.refresh_token,
+        id_token=payload_data.id_token,
+        account_id=account_id,
+        plan_type=plan_type,
+        email=email,
+        workspace_id=workspace_id,
+        workspace_label=workspace_label,
+        seat_type=seat_type,
+        chatgpt_user_id=chatgpt_user_id,
+    )
+
+
+def push_token_refresh_timeout_override(timeout_seconds: float | None) -> contextvars.Token[float | None]:
+    return _TOKEN_REFRESH_TIMEOUT_OVERRIDE.set(timeout_seconds)
+
+
+def pop_token_refresh_timeout_override(token: contextvars.Token[float | None]) -> None:
+    _TOKEN_REFRESH_TIMEOUT_OVERRIDE.reset(token)
+
+
+def get_token_refresh_timeout_override() -> float | None:
+    """Caller-scoped refresh budget (seconds); ``None`` when no caller set one.
+
+    Set by the proxy request path around ``AuthManager.ensure_fresh`` so that
+    everything the (shielded, caller-outliving) refresh task does — including
+    waiting on a foreign cross-replica refresh claim — stays bounded by the
+    budget of the request that started it.
+    """
+    return _TOKEN_REFRESH_TIMEOUT_OVERRIDE.get()
+
+
+async def _safe_codex_json(resp: object) -> JsonObject:
+    json_method = getattr(resp, "json", None)
+    try:
+        if callable(json_method):
+            data = json_method()
+            if asyncio.iscoroutine(data):
+                data = await data
+        else:
+            text_value = getattr(resp, "text", None)
+            if not isinstance(text_value, str):
+                content = getattr(resp, "content", b"")
+                text_value = content.decode("utf-8", errors="replace") if isinstance(content, bytes) else str(content)
+            import json
+
+            data = json.loads(text_value)
+    except Exception:
+        text_value = getattr(resp, "text", "")
+        return {"error": {"message": str(text_value).strip()}}
+    return data if isinstance(data, dict) else {"error": {"message": str(data)}}
+
+
+def _validate_token_payload(data: JsonObject) -> OAuthTokenPayload:
+    try:
+        return OAuthTokenPayload.model_validate(data)
+    except ValidationError as exc:
+        logger.warning("Token refresh response invalid request_id=%s", get_request_id())
+        raise RefreshError("invalid_response", "Refresh response invalid", False) from exc
+
+
+def _refresh_error_from_payload(payload: OAuthTokenPayload, status_code: int) -> RefreshError:
+    code = _extract_error_code(payload) or f"http_{status_code}"
+    message = _extract_error_message(payload) or f"Token refresh failed ({status_code})"
+    return RefreshError(code, message, classify_refresh_error(code))
+
+
+def _effective_token_refresh_timeout() -> float:
+    override = _TOKEN_REFRESH_TIMEOUT_OVERRIDE.get()
+    if override is None:
+        return TOKEN_REFRESH_TIMEOUT_SECONDS
+    return max(0.001, min(TOKEN_REFRESH_TIMEOUT_SECONDS, override))

app/core/auth/step_up.py

@@ -0,0 +1,117 @@
+"""Step-up re-verification for sensitive dashboard mutations (PLAN §5 H5).
+
+A signed-in account changing who may sign in (``security:write``,
+``users:manage``, ``roles:manage``) or exporting account credentials
+(``accounts:export``) must have re-proven a credential within the last five
+minutes. What counts as re-proving depends on what the account holds: its
+password (plus its TOTP code when it has a secret), or — for accounts that
+sign in through a provider and hold no password — its own TOTP code. An
+account holding neither a password nor a secret has one last option, and only
+that one: re-authenticating at the identity provider it signs in with
+(``prompt=login``). An account with none of the three cannot step up at all
+and is told so (``step_up_unavailable``); there is no silent exemption, and a
+provider's ``idp_mfa_enforced`` flag does not waive step-up.
+
+The identity provider is an alternative to *nothing*, never to a factor the
+account already holds: offering it to a password account would let a stolen
+session cookie plus a still-live provider session change security settings
+while presenting nothing the attacker does not already have.
+
+This module holds the pure pieces (window, cookie name, availability,
+freshness) plus the one lookup that turns "holds no credential" into "can
+re-authenticate at its identity provider"; the cookie stores live next to the
+session store in ``dashboard_auth.service`` and enforcement in
+``auth.dependencies``.
+"""
+
+from __future__ import annotations
+
+from typing import Final, Literal
+
+from app.core.auth.dashboard_mode import DashboardAuthMode
+from app.db.models import AuthProviderKind, DashboardUser
+
+#: How long a step-up verification is honoured, in seconds.
+STEP_UP_MAX_AGE_SECONDS: Final = 300
+#: Short-lived cookie carrying a step-up for principals that have no session
+#: cookie to carry the claim (trusted-header accounts).
+STEP_UP_COOKIE: Final = "codex_lb_step_up"
+STEP_UP_UNAVAILABLE_MESSAGE: Final = "Set up two-factor authentication or a local password to change security settings"
+
+StepUpMethod = Literal["password", "totp", "oidc"]
+
+
+def step_up_methods(user: DashboardUser, *, oidc_identity: bool = False) -> list[StepUpMethod]:
+    """The factors ``user`` must present to step up, in the order they are asked.
+
+    Every listed factor is required: a password account with a TOTP secret
+    presents both. ``oidc_identity`` says whether the account holds an identity
+    on an active OIDC provider, and is consulted **only** when the account
+    holds no credential of its own — the identity provider is the last resort,
+    not a shortcut past a factor the account already has. Empty means the
+    account cannot step up.
+    """
+
+    methods: list[StepUpMethod] = []
+    if user.password_hash is not None:
+        methods.append("password")
+    if user.totp_secret_encrypted is not None:
+        methods.append("totp")
+    if methods:
+        return methods
+    return ["oidc"] if oidc_identity else []
+
+
+async def account_step_up_methods(user: DashboardUser) -> list[StepUpMethod]:
+    """:func:`step_up_methods` for ``user``, asking the database only when it must.
+
+    An account holding a password or a TOTP secret is answered from the row
+    alone, exactly as before. Only an account holding neither — the shape that
+    is refused outright today — costs a lookup, and that lookup is what decides
+    between "re-authenticate at your identity provider" and "you cannot step up
+    at all". The gate, the ``403`` body and the session response all call this,
+    so they cannot disagree about what the account may present.
+    """
+
+    methods = step_up_methods(user)
+    if methods:
+        return methods
+    return step_up_methods(user, oidc_identity=await _has_active_oidc_identity(user))
+
+
+async def _has_active_oidc_identity(user: DashboardUser) -> bool:
+    """Whether ``user`` can actually reach an identity provider that would vouch for it.
+
+    Both halves matter: an identity row on a provider that is disabled (or on
+    an install whose auth mode does not admit it) is not a way to re-verify,
+    and an active provider the account has never signed in through cannot
+    vouch for it either.
+    """
+
+    # Imported here rather than at module scope: the registry reaches the
+    # provider and user repositories, which sit above this module in the
+    # layering, and everything else here is pure.
+    from app.core.auth.providers import DEFAULT_PROVIDER_KEY
+    from app.core.auth.providers.registry import get_auth_provider_registry
+    from app.core.config.settings import get_settings
+    from app.db.session import SessionLocal
+    from app.modules.dashboard_users.repository import DashboardUsersRepository
+
+    mode: DashboardAuthMode = get_settings().dashboard_auth_mode
+    active = await get_auth_provider_registry().get_active(AuthProviderKind.OIDC, DEFAULT_PROVIDER_KEY, mode)
+    if active is None:
+        return False
+    async with SessionLocal() as session:
+        return await DashboardUsersRepository(session).has_identity(
+            user.id, provider=AuthProviderKind.OIDC.value, provider_key=active.row.provider_key
+        )
+
+
+def is_step_up_fresh(verified_at: int | None, *, now: int) -> bool:
+    """Whether a step-up recorded at ``verified_at`` still covers a request at ``now``."""
+
+    return verified_at is not None and now - verified_at <= STEP_UP_MAX_AGE_SECONDS
+
+
+def step_up_expires_at(verified_at: int) -> int:
+    return verified_at + STEP_UP_MAX_AGE_SECONDS