Skip to content

OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.

Python
28.7 KB
Raw Blame
"""Request identity resolution for browser, upstream, and API-key auth."""

import base64
import dataclasses
import hashlib
from typing import Optional

from fastapi import HTTPException, Request

from auth.user_identity_cache import _resolve_db_user_id
from session_manager import User
from utils.logging_config import get_logger

logger = get_logger(__name__)

# Header names whose values must never be logged verbatim. Logged as a
# redacted fingerprint (length + sha prefix) so a value can be correlated
# across hops without exposing the secret.
_SENSITIVE_HEADERS = {
    "authorization",
    "x-openrag-api-jwt",
    "x-api-key",
    "x-username",
    "cookie",
    "x-ibm-lh-credentials",
}


def _redact_header(name: str, value: str) -> str:
    """Redact a header value for logging — never emit the raw secret."""
    if not value:
        return ""
    if name.lower() in _SENSITIVE_HEADERS:
        digest = hashlib.sha256(value.encode("utf-8")).hexdigest()[:8]
        return f"<redacted len={len(value)} sha={digest}>"
    return value


async def _attach_db_user_id(request: Request, user: User | None) -> User | None:
    """Attach the internal SQL users.id to the request user.

    `User.user_id` remains the external auth subject used in JWT/OpenSearch
    flows. `User.db_user_id` is the OpenRAG owner id used by SQL-backed
    RBAC and ownership tables.
    """
    if user is None:
        request.state.db_user_id = None
        request.state.user = None
        return None
    jwt_roles = getattr(request.state, "jwt_roles", None)
    from config.settings import is_dev_role_toggle_enabled

    if is_dev_role_toggle_enabled():
        jwt_roles = None
    db_user_id = await _resolve_db_user_id(user, jwt_roles=jwt_roles)
    user_with_db_id = dataclasses.replace(user, db_user_id=db_user_id)
    request.state.db_user_id = db_user_id
    request.state.user = user_with_db_id
    return user_with_db_id


async def _attach_opensearch_jwt(
    request: Request,
    user: User | None,
    session_manager,
    token_hint: str | None = None,
) -> User | None:
    """Attach OpenSearch auth state and refresh DLS principal lookup state."""
    if user is None:
        return None

    effective_token = session_manager.get_effective_jwt_token(
        user.user_id,
        token_hint if token_hint is not None else user.jwt_token,
    )
    if effective_token != user.jwt_token:
        user = dataclasses.replace(user, jwt_token=effective_token)

    services = getattr(getattr(request, "app", None), "state", None)
    services = getattr(services, "services", {}) or {}
    dls_principal_service = services.get("dls_principal_service")

    if dls_principal_service is not None:
        try:
            principals = await dls_principal_service.refresh_user_principals(user)
            request.state.opensearch_dls_principals = principals
        except Exception as e:
            logger.warning(
                "Failed to refresh OpenSearch DLS principals",
                user_id=user.user_id,
                error=str(e),
            )

    request.state.opensearch_group_roles = []

    return user


async def _attach_request_user(
    request: Request,
    user: User | None,
    session_manager,
    token_hint: str | None = None,
) -> User | None:
    user_with_opensearch_jwt = await _attach_opensearch_jwt(
        request,
        user,
        session_manager,
        token_hint=token_hint,
    )
    return await _attach_db_user_id(request, user_with_opensearch_jwt)


def _stage_jwt_roles(request: Request, claims: dict, user_id: str | None) -> None:
    """Extract OpenRAG roles from decoded JWT *claims* and stash them on
    ``request.state.jwt_roles`` so the subsequent ``_attach_db_user_id`` call
    syncs them to the DB.

    Behavior mirrors the ibm-openrag-session cookie path:
      * RBAC off (``jwt_roles_enabled()`` False) -> ``jwt_roles = None`` so the
        legacy default-role path runs and existing DB roles are not clobbered.
      * RBAC on -> roles are extracted; if the JWT carries no recognized
        OpenRAG role, raise HTTP 401.
    """
    from auth.jwt_roles import extract_jwt_role_names, jwt_roles_enabled

    jwt_roles: list[str] | None = None
    if jwt_roles_enabled():
        jwt_roles = extract_jwt_role_names(claims)
        if not jwt_roles:
            logger.warning(
                "JWT carries no recognized OpenRAG role claim",
                user_id=user_id,
            )
            raise HTTPException(
                status_code=401,
                detail="User has no OpenRAG roles assigned",
            )
    logger.debug(f"JWT roles: {jwt_roles}")
    request.state.jwt_roles = jwt_roles


async def _resolve_lakehouse_credentials(
    request: Request, user_id: str | None
) -> tuple[str | None, str | None]:
    """Resolve the lakehouse Basic credentials used for the user-scoped
    OpenSearch client. Shared by the session-cookie surface (``_get_ibm_user``)
    and the /v1 JWT-in-header surface (``resolve_api_key_user``).
    """
    from auth.ibm_auth import extract_ibm_credentials
    from config.settings import IBM_CREDENTIALS_HEADER

    connector_service = None
    app_state = getattr(getattr(request, "app", None), "state", None)
    services = getattr(app_state, "services", None)
    if services:
        connector_service = services.get("connector_service")

    lh_credentials = request.headers.get(IBM_CREDENTIALS_HEADER, "")
    if lh_credentials and lh_credentials.strip() != "":
        logger.debug("[AUTH] IBM LH credentials found in request headers")
        opensearch_username, _ = extract_ibm_credentials(lh_credentials)
        upsert_user_id = user_id or opensearch_username
        if connector_service and upsert_user_id:
            logger.debug("[AUTH] Upserting IBM LH credentials to connections store")
            try:
                await connector_service.connection_manager.upsert_ibm_credentials(
                    user_id=upsert_user_id,
                    basic_credentials=lh_credentials,
                    username=upsert_user_id,
                )
            except Exception as exc:  # noqa: BLE001 — persistence is best-effort
                logger.warning(
                    "[AUTH] Failed to persist IBM LH credentials to connections store",
                    user_id=upsert_user_id,
                    error=str(exc),
                )
        return opensearch_username, lh_credentials

    if connector_service and user_id:
        try:
            connections = await connector_service.connection_manager.list_connections(
                user_id=user_id, connector_type="ibm_credentials"
            )
        except Exception as exc:  # noqa: BLE001 — auth must degrade, not 500
            logger.warning(
                "[AUTH] Failed to read IBM LH credentials from connections store",
                user_id=user_id,
                error=str(exc),
            )
            connections = []
        if connections:
            lh_credentials = connections[0].config.get("basic_credentials")
            if lh_credentials and lh_credentials.strip() != "":
                logger.debug("[AUTH] IBM LH credentials found in connections store")
                opensearch_username, _ = extract_ibm_credentials(lh_credentials)
                return opensearch_username, lh_credentials

    return None, None


async def _get_ibm_user(request: Request, required: bool) -> Optional["User"]:
    """Authenticate via upstream auth.

    0. Configured credentials header containing OpenSearch credentials.
    1. Configured session cookie. When JWT-role sync is enabled, the JWT is
       instead read from the gateway-forwarded header named by ``get_jwt_auth_header()``;
       identity and roles both come from that token.

    If *required* is True, raises HTTP 401 when none is present.
    If *required* is False, returns None instead of raising.
    """
    import auth.ibm_auth as ibm_auth
    from auth.ibm_auth import extract_ibm_credentials
    from auth.jwt_roles import jwt_roles_enabled
    from config.settings import IBM_SESSION_COOKIE_NAME, get_jwt_auth_header
    from config.utils import resolve_jwt_claims

    # When RBAC/JWT-role sync is on, the gateway forwards the end-user JWT in the
    # configured header; use it as the source of identity and roles. When RBAC is
    # off, preserve the existing ibm-openrag-session cookie flow.
    if jwt_roles_enabled():
        header_name = get_jwt_auth_header()
        raw_jwt = request.headers.get(header_name, "")
        logger.debug(
            "[AUTH] JWT-role header lookup",
            header_name=header_name,
            jwt_present=bool(raw_jwt and raw_jwt.strip()),
        )
        ibm_token = (
            raw_jwt[7:].strip() if raw_jwt.startswith("Bearer ") else raw_jwt.strip()
        ) or None

        claims = resolve_jwt_claims(ibm_token)
    else:
        ibm_token = request.cookies.get(IBM_SESSION_COOKIE_NAME)
        claims = None
    user_id = None
    email = None
    name = None
    # Default for the no-token / no-claims / no-sub cases; overwritten by
    # _stage_jwt_roles when a valid JWT subject is present.
    request.state.jwt_roles = None
    if ibm_token:
        if claims is None:
            logger.debug("[AUTH] IBM JWT token found in request cookies")
            claims = ibm_auth.decode_ibm_jwt(ibm_token)
        if claims is not None:
            logger.debug(
                "[AUTH] JWT claims resolved"
                if jwt_roles_enabled()
                else "[AUTH] IBM JWT claims decoded successfully"
            )
            sub = claims.get("sub")
            if not sub:
                logger.warning(
                    "IBM JWT is missing required 'sub' claim; treating as unauthenticated"
                )
            else:
                user_id = claims.get("username", sub)
                email = claims.get("username", sub)
                name = claims.get("display_name", claims.get("username", sub))
                # RBAC off -> jwt_roles stays None (legacy default-role path,
                # existing DB roles untouched). RBAC on -> extract + 401 if none.
                _stage_jwt_roles(request, claims, user_id)

    from utils.run_mode_utils import get_run_mode, is_run_mode_on_prem, is_run_mode_saas

    platform_rbac = (is_run_mode_saas() or is_run_mode_on_prem()) and jwt_roles_enabled()

    # The forwarded end-user JWT is the OpenSearch credential — OpenSearch's
    # openid_auth_domain validates it via the backend JWKS. Build it once; it's
    # used both as the platform+rbac authoritative credential and as the
    # header-less fallback in other modes.
    jwt_user = None
    if ibm_token and user_id:
        jwt_user = User(
            user_id=user_id,
            email=email,
            name=name,
            picture=None,
            provider="ibm_ams",
            jwt_token=f"Bearer {ibm_token}",
            opensearch_username=None,
            opensearch_credentials=None,
        )

    # In SaaS/on-prem + RBAC the JWT is authoritative: the lakehouse
    # `X-IBM-LH-Credentials` Basic credential must NOT override it (when the
    # gateway began injecting that header, OpenSearch rejected the Basic cred
    # with 401 and every data-plane call surfaced as a misleading 403
    # "insufficient permissions"). Return before `_resolve_lakehouse_credentials`
    # so its connections-store upsert side effect is also skipped. Mirrors the
    # /v1 surface, which already treats the JWT as primary.
    if platform_rbac:
        if jwt_user:
            logger.debug(
                "[AUTH] User created from forwarded JWT (platform+rbac; lakehouse creds bypassed)",
                run_mode=get_run_mode(),
            )
            request.state.user = jwt_user
            return jwt_user
        # SaaS/on-prem + RBAC but no valid forwarded JWT (missing header,
        # undecodable, or no `sub`). Do NOT degrade to lakehouse Basic creds or
        # the debug cookie — that would authenticate (and write DB user/role
        # rows) under a roles-less identity. Fail loud, mirroring
        # resolve_api_key_user's platform_rbac branch.
        request.state.user = None
        if required:
            logger.error(
                "[AUTH] No valid forwarded JWT under platform+RBAC; refusing lakehouse/basic fallback",
                jwt_present=bool(ibm_token),
                run_mode=get_run_mode(),
            )
            raise HTTPException(
                status_code=401,
                detail={
                    "error": "invalid_jwt" if ibm_token else "missing_user_jwt",
                    "message": (
                        "No valid user JWT was forwarded by the gateway. In "
                        "SaaS/on-prem RBAC mode the gateway must forward the "
                        "end-user JWT on every request."
                    ),
                },
            )
        return None

    # Other modes: lakehouse Basic creds take precedence when present.
    opensearch_username, lh_credentials = await _resolve_lakehouse_credentials(request, user_id)

    if lh_credentials:
        user_id = user_id or opensearch_username
        email = email or opensearch_username
        name = name or opensearch_username
        user = User(
            user_id=user_id,
            email=email,
            name=name,
            picture=None,
            provider="ibm_ams",
            jwt_token=f"Basic {lh_credentials}",
            opensearch_username=opensearch_username,
            opensearch_credentials=lh_credentials,
        )
        logger.debug("[AUTH] User created successfully")
        request.state.user = user
        return user

    if jwt_user:
        logger.warning(
            "[AUTH] IBM LH credentials not found in header or connections store. Using JWT token instead."
        )
        request.state.user = jwt_user
        return jwt_user

    if ibm_token and not user_id:
        logger.warning("IBM JWT cookie present but could not extract user_id from claims.")
        request.state.user = None
        return None

    auth_header = request.cookies.get("ibm-auth-basic", "")
    if auth_header.startswith("Basic "):
        logger.debug("[AUTH] Debug mode enabled, extracting IBM LH credentials from cookie")
        username, _ = extract_ibm_credentials(auth_header)
        logger.debug("[AUTH] IBM LH credentials extracted successfully")
        user = User(
            user_id=username,
            email=username,
            name=username,
            picture=None,
            provider="ibm_ams_basic",
            jwt_token=auth_header,
            opensearch_username=username,
            opensearch_credentials=auth_header,
        )
        logger.debug("[AUTH] User created successfully")
        request.state.user = user
        return user

    # ── Neither present ──────────────────────────────────────────────────
    if required:
        raise HTTPException(status_code=401, detail="IBM authentication required")
    request.state.user = None
    return None


async def resolve_current_user(request: Request, session_manager) -> User:
    """Require JWT cookie authentication and attach request identity state."""
    from config.settings import IBM_AUTH_ENABLED, is_no_auth_mode
    from session_manager import AnonymousUser

    # Upstream cookie auth takes priority when enabled.
    if IBM_AUTH_ENABLED:
        logger.debug("[AUTH] IBM auth mode enabled, getting current user")
        user = await _get_ibm_user(request, required=True)
        if user and user.user_id and user.user_id not in session_manager.users:
            session_manager.users[user.user_id] = user
        return await _attach_request_user(request, user, session_manager)

    if is_no_auth_mode():
        user = AnonymousUser()
        return await _attach_request_user(request, user, session_manager)

    auth_token = request.cookies.get("auth_token")
    if not auth_token:
        raise HTTPException(status_code=401, detail="Authentication required")

    user = session_manager.get_user_from_token(auth_token)
    if not user:
        raise HTTPException(status_code=401, detail="Authentication required")

    return await _attach_request_user(
        request,
        user,
        session_manager,
        token_hint=auth_token,
    )


async def resolve_optional_user(request: Request, session_manager) -> User | None:
    """Optionally extract JWT cookie user and attach request identity state."""
    from config.settings import IBM_AUTH_ENABLED, is_no_auth_mode
    from session_manager import AnonymousUser

    # Upstream cookie auth takes priority when enabled.
    if IBM_AUTH_ENABLED:
        logger.debug("[AUTH] IBM auth mode enabled, getting optional user")
        user = await _get_ibm_user(request, required=False)
        if user and user.user_id and user.user_id not in session_manager.users:
            session_manager.users[user.user_id] = user
        if user:
            return await _attach_request_user(request, user, session_manager)
        request.state.db_user_id = None
        return None

    if is_no_auth_mode():
        user = AnonymousUser()
        return await _attach_request_user(request, user, session_manager)

    auth_token = request.cookies.get("auth_token")
    if not auth_token:
        request.state.user = None
        return None

    user = session_manager.get_user_from_token(auth_token)
    if user:
        return await _attach_request_user(
            request,
            user,
            session_manager,
            token_hint=auth_token,
        )
    request.state.user = None
    request.state.db_user_id = None
    return None


async def resolve_api_key_user(request: Request, api_key_service, session_manager) -> User:
    """Require API key or upstream authentication and attach request identity state."""
    # ── JWT-in-header path ───────────────────────────────────────────────
    # An upstream gateway may forward the end-user's JWT in a configurable
    # header. Its signature is verified by discovering the issuer's keys from
    # the token's own `iss` claim (config.utils.verify_jwt_from_issuer); when
    # valid the JWT becomes the source of identity. Under RBAC it also supplies
    # the user's roles (synced via request.state.jwt_roles ->
    # _attach_db_user_id), with a 401 when no recognized role is present.
    from auth.jwt_roles import jwt_roles_enabled
    from config.settings import (
        IBM_AUTH_ENABLED,
        get_api_jwt_header,
        get_jwt_auth_header,
    )
    from config.utils import resolve_jwt_claims
    from utils.run_mode_utils import get_run_mode, is_run_mode_on_prem, is_run_mode_saas

    # SaaS/on-prem + RBAC: the gateway MUST forward the end-user JWT on every
    # /v1 request. When it doesn't, we must NOT silently degrade to lakehouse
    # Basic creds — that path does DB user writes under a degraded identity and
    # can clobber the shared users row the same person sees on UI login. Fail
    # loud (401) with no DB side effects instead; explicit orag_ API-key auth
    # still works.
    platform_rbac = (is_run_mode_saas() or is_run_mode_on_prem()) and jwt_roles_enabled()

    # Primary: the gateway-forwarded JWT header (default Authorization).
    # Fallback: the API/MCP add-on header — FastMCP strips Authorization before
    # proxying an MCP tool call to this /v1 handler, so MCP/API callers supply
    # the JWT in get_api_jwt_header() instead.
    jwt_header = get_jwt_auth_header()
    raw_jwt = request.headers.get(jwt_header, "")

    safe_headers = {k: _redact_header(k, v) for k, v in request.headers.items()}
    logger.debug("[AUTH] Incoming /v1 request headers (redacted)", headers=safe_headers)

    if not (raw_jwt and raw_jwt.strip()):
        jwt_header = get_api_jwt_header()
        raw_jwt = request.headers.get(jwt_header, "")
    logger.debug(
        "[AUTH] API-key path JWT header lookup",
        header_name=jwt_header,
        jwt_present=bool(raw_jwt and raw_jwt.strip()),
        jwt_preview=_redact_header(jwt_header, raw_jwt),
    )
    if raw_jwt and raw_jwt.strip():
        token = raw_jwt[7:].strip() if raw_jwt.startswith("Bearer ") else raw_jwt.strip()
        from services.langflow_llm_token_service import langflow_hop_audience

        secret = None
        algo = None
        app_state = getattr(getattr(request, "app", None), "state", None)
        services = getattr(app_state, "services", None) or {}
        llm_svc = services.get("langflow_llm_token_service")
        if llm_svc is not None:
            secret = getattr(llm_svc, "_verification_key", None)
            algo = getattr(llm_svc, "algorithm", None)

        hop_aud = langflow_hop_audience(token, secret=secret, algorithm=algo)
        if hop_aud:
            raise HTTPException(
                status_code=401,
                detail={
                    "error": "langflow_hop_token",
                    "message": (
                        "This token is only valid for the Langflow callback it "
                        "was issued for, not for the rest of /v1."
                    ),
                },
            )
        claims = resolve_jwt_claims(token)
        sub = claims.get("sub") if claims else None
        if sub:
            user = User(
                user_id=claims.get("username", sub),
                email=claims.get("username", sub),
                name=claims.get("display_name", claims.get("username", sub)),
                picture=None,
                # Same provider as the cookie path so the forwarded user
                # resolves to the SAME users row (oauth_provider, oauth_subject).
                provider="ibm_ams",
                jwt_token=f"Bearer {token}",
            )
            _stage_jwt_roles(request, claims, user.user_id)
            logger.debug(
                "[AUTH] API user authenticated via JWT",
                user_id=user.user_id,
                roles=getattr(request.state, "jwt_roles", None),
            )
            # The forwarded JWT is primary for ALL operations (identity, roles,
            # and downstream OpenSearch calls, which validate it via OIDC) —
            # same as the session surface (_get_ibm_user). NOTE (gateway
            # requirement): under RBAC this JWT is also the authoritative role
            # source. Traefik must mint it with the user's real OpenRAG role
            # claims (same as the UI session JWT), otherwise every /v1 call
            # re-syncs the user down to whatever the claim carries.
            request.state.user = user
            return await _attach_request_user(request, user, session_manager)
        if jwt_roles_enabled():
            # A JWT was asserted but failed verification/decode. Under RBAC we
            # must not silently downgrade to the API-key identity.
            logger.error(
                "[AUTH] JWT in request header failed verification/decode",
                header_name=jwt_header,
                jwt_preview=_redact_header(jwt_header, raw_jwt),
            )
            raise HTTPException(
                status_code=401,
                detail={
                    "error": "invalid_jwt",
                    "message": (
                        f"The JWT in the '{jwt_header}' header could not be "
                        "verified or decoded. Ensure the gateway forwards a valid, "
                        "unexpired user JWT issued by a trusted identity provider."
                    ),
                },
            )
        # RBAC off + missing/invalid JWT -> fall through to the API-key path.
    else:
        if platform_rbac:
            # In SaaS/on-prem the gateway is responsible for forwarding the
            # end-user JWT on every API/MCP request; its absence is a gateway
            # misconfiguration, not a normal client state. Fail fast here —
            # before any lakehouse / X-Username / API-key fallback — so no DB
            # user/role write ever runs under a degraded (roles-less) identity.
            logger.error(
                f"[AUTH] JWT not found in request header — run_mode={get_run_mode()} "
                "with RBAC enabled requires the gateway to forward the user JWT",
                header_name=jwt_header,
                authorization_present=bool(request.headers.get("authorization")),
                api_jwt_present=bool(request.headers.get(get_api_jwt_header())),
                seen_auth_headers={
                    k: _redact_header(k, v)
                    for k, v in request.headers.items()
                    if k.lower() in _SENSITIVE_HEADERS
                },
            )
            raise HTTPException(
                status_code=401,
                detail={
                    "error": "missing_user_jwt",
                    "message": (
                        "No user JWT was forwarded by the gateway. In "
                        "SaaS/on-prem RBAC mode the gateway must forward the "
                        "end-user JWT on every /v1 request."
                    ),
                },
            )
        if IBM_AUTH_ENABLED:
            # No JWT — fall back to lakehouse Basic credentials (credentials
            # header, upserted to the connections store), mirroring the
            # session surface's header branch in _get_ibm_user.
            os_username, lh_credentials = await _resolve_lakehouse_credentials(request, None)
            if lh_credentials:
                logger.info(
                    "[AUTH] Using IBM LH credentials as JWT token",
                    username=os_username,
                )
                user = User(
                    user_id=os_username,
                    email=os_username,
                    name=os_username,
                    picture=None,
                    provider="ibm_ams",
                    jwt_token=f"Basic {lh_credentials}",
                    opensearch_username=os_username,
                    opensearch_credentials=lh_credentials,
                )
                request.state.user = user
                return await _attach_request_user(request, user, session_manager)

    # Upstream auth path: X-Username + X-Api-Key sent directly by an MCP/SDK
    # client. Not the SaaS path — there, Traefik consumes these headers for
    # login and injects the JWT handled by the branch above.
    if IBM_AUTH_ENABLED:
        ibm_username = request.headers.get("X-Username")
        ibm_api_key = request.headers.get("X-Api-Key")
        if ibm_username and ibm_api_key:
            # check if ibm api key is base 64 encoded
            userpass = f"{ibm_username}:{ibm_api_key}"
            ibm_api_key_b64 = base64.b64encode(userpass.encode("utf-8")).decode("utf-8")

            user = User(
                user_id=ibm_username,
                email=ibm_username,
                name=ibm_username,
                picture=None,
                provider="ibm_ams",
                jwt_token=f"Basic {ibm_api_key_b64}",
                opensearch_username=ibm_username,
                opensearch_credentials=ibm_api_key_b64,
            )
            return await _attach_request_user(request, user, session_manager)

    # API key path
    api_key = request.headers.get("X-API-Key")
    if not api_key or not api_key.startswith("orag_"):
        auth_header = request.headers.get("Authorization", "")
        if auth_header.startswith("Bearer "):
            token = auth_header[7:]
            if token.startswith("orag_"):
                api_key = token

    if not api_key:
        # platform_rbac is already handled by the fail-fast 401 above (no JWT
        # -> missing_user_jwt), so reaching here means non-platform_rbac:
        # prompt for an API key as before.
        raise HTTPException(
            status_code=401,
            detail={
                "error": "API key required",
                "message": "Provide API key via X-API-Key header or Authorization: Bearer header",
            },
        )

    user_info = await api_key_service.validate_key(api_key)
    if not user_info:
        raise HTTPException(
            status_code=401,
            detail={
                "error": "Invalid API key",
                "message": "The provided API key is invalid or has been revoked",
            },
        )

    user = User(
        user_id=user_info["user_id"],
        email=user_info["user_email"],
        name=user_info.get("name", "API User"),
        picture=None,
        provider="api_key",
    )

    # Register the API key user so get_effective_jwt_token can find them
    if user.user_id not in session_manager.users:
        session_manager.users[user.user_id] = user

    request.state.api_key_id = user_info["key_id"]
    # Phase 2 will populate api_key_role_ids from the SQL api_keys table.
    # In Phase 1 we leave it unset so require_permission falls back to the
    # user's live role membership (no privilege escalation possible).
    request.state.api_key_role_ids = getattr(request.state, "api_key_role_ids", None)

    return await _attach_request_user(request, user, session_manager)