Skip to content

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

Python
11.7 KB
Raw Blame
"""User lifecycle service.

Single chokepoint for "given an authenticated principal, make sure a row
exists in the users table and assign a default role." Race-safe via a
serialized SQL transaction. Idempotent.

ensure_user_row is intentionally synchronous on its critical section so
parallel sign-ins from the same provider/subject collapse into a single
INSERT (the unique constraint on (oauth_provider, oauth_subject) does the
heavy lifting; we catch IntegrityError and re-fetch).
"""

from __future__ import annotations

import os
import uuid

from sqlalchemy.exc import IntegrityError
from sqlalchemy.ext.asyncio import AsyncSession

from db.models import User as UserRow
from db.repositories import AuditRepo, RoleRepo, UserRepo
from session_manager import User
from utils.logging_config import get_logger

logger = get_logger(__name__)


def _default_new_user_role() -> str:
    return os.getenv("OPENRAG_DEFAULT_ROLE", "user")


def _noauth_role() -> str:
    return os.getenv("OPENRAG_NOAUTH_ROLE", "admin")


async def ensure_user_row(
    session: AsyncSession,
    user: User,
    jwt_roles: list[str] | None = None,
) -> UserRow:
    """Ensure the authenticated `user` exists in the SQL `users` table.

    Role assignment:

    * ``jwt_roles is None`` — env-default behavior (oss / RBAC-off). Every new
      user gets ``OPENRAG_DEFAULT_ROLE`` (default ``user``); the synthetic
      anonymous user gets ``OPENRAG_NOAUTH_ROLE`` (default ``admin``). There is
      no first-user-becomes-admin bootstrap.
    * ``jwt_roles is not None`` — JWT is authoritative (saas / on_prem). The
      user's DB role assignments are reconciled against the list every call.

    Returns the persisted UserRow. Caller commits.
    """

    if not user or not user.user_id:
        raise ValueError("ensure_user_row requires a user with a user_id")

    user_repo = UserRepo(session)
    role_repo = RoleRepo(session)
    audit_repo = AuditRepo(session)

    provider = user.provider or "unknown"
    subject = user.user_id

    existing = await user_repo.get_by_oauth(provider, subject)
    if existing:
        await user_repo.update_last_login(existing.id)
        if jwt_roles is not None:
            await _sync_jwt_roles(role_repo, audit_repo, existing.id, jwt_roles)
        else:
            await _assign_default_role_if_missing(session, role_repo, audit_repo, existing.id)
        return existing

    # Possible legacy row (oauth_provider='legacy', oauth_subject==user_id)
    legacy = await user_repo.get_by_oauth("legacy", subject)
    if legacy is None and user.email:
        # Or a legacy row matched by email_lookup_hash from a prior sign-in
        by_email = await user_repo.get_by_email(user.email)
        if by_email and by_email.oauth_provider == "legacy":
            legacy = by_email

    if legacy is not None:
        merged = await user_repo.merge_legacy(
            legacy,
            real_provider=provider,
            real_subject=subject,
            email=user.email,
            display_name=user.name,
            picture_url=user.picture,
        )
        await audit_repo.write(
            event="user.merged_legacy",
            actor_user_id=merged.id,
            target_type="user",
            target_id=merged.id,
            audit_metadata={"provider": provider},
        )
        if jwt_roles is not None:
            await _sync_jwt_roles(role_repo, audit_repo, merged.id, jwt_roles)
        else:
            # Legacy rows had no role assignment — give them the default.
            await _assign_default_role(session, role_repo, audit_repo, merged.id)
        return merged

    # Brand-new row.
    # We use the OAuth subject (== user.user_id) as the DB primary key so
    # the SQL `users.id` lines up with the JWT subject and with the
    # user_id strings already used by connections.json / conversations.json.
    # If a different provider ever sign-ins with the same subject string we
    # fall back to a UUID — extremely rare in practice.
    new_id = subject if subject else str(uuid.uuid4())
    row = UserRow(
        id=new_id,
        oauth_provider=provider,
        oauth_subject=subject,
        email=user.email,
        display_name=user.name,
        picture_url=user.picture,
    )
    try:
        await user_repo.add(row)
    except IntegrityError:
        # The collision could be on any of the three unique constraints:
        # (oauth_provider, oauth_subject), email_lookup_hash, or id (PK).
        # By the time the flush raises, the peer transaction that lost the
        # race has committed, so the re-fetches below see its row.
        await session.rollback()

        # Case 1: (oauth_provider, oauth_subject) race — a peer beat us to the
        # INSERT for this exact identity.
        existing = await user_repo.get_by_oauth(provider, subject)
        if existing:
            await user_repo.update_last_login(existing.id)
            return existing

        # Case 2: email_lookup_hash collision — some row already owns this
        # email (email_lookup_hash is UNIQUE). Most common for the synthetic
        # anonymous@localhost user in no-auth mode when two concurrent requests
        # both observe an empty table.
        by_email = await user_repo.get_by_email(user.email) if user.email else None
        if by_email is not None:
            if by_email.oauth_provider == provider and by_email.oauth_subject == subject:
                # Concurrent insert of the *same* identity — safe to reuse.
                await user_repo.update_last_login(by_email.id)
                return by_email

            # A *different* identity already owns this email (e.g. the same
            # person signing in through a second provider). Re-inserting with
            # the same email is futile — it would collide on email_lookup_hash
            # again — so create this distinct principal *without* the email so
            # the request never fails on a UNIQUE constraint. The email stays
            # attached to the first identity that claimed it.
            logger.warning(
                "email already owned by another identity; creating user row without email",
                provider=provider,
                subject=subject,
                existing_provider=by_email.oauth_provider,
                existing_subject=by_email.oauth_subject,
            )
            row = UserRow(
                id=str(uuid.uuid4()),
                oauth_provider=provider,
                oauth_subject=subject,
                email=None,
                display_name=user.name,
                picture_url=user.picture,
            )
            await user_repo.add(row)
            if jwt_roles is not None:
                await _sync_jwt_roles(role_repo, audit_repo, row.id, jwt_roles)
            else:
                await _assign_default_role(session, role_repo, audit_repo, row.id)
            return row

        # Case 3: pure PK collision (id==subject already occupied by a
        # different identity, no email conflict). Retry with a UUID;
        # (provider, subject) differs from the conflicting row so the INSERT
        # succeeds.
        new_id = str(uuid.uuid4())
        row = UserRow(
            id=new_id,
            oauth_provider=provider,
            oauth_subject=subject,
            email=user.email,
            display_name=user.name,
            picture_url=user.picture,
        )
        await user_repo.add(row)

    if jwt_roles is not None:
        await _sync_jwt_roles(role_repo, audit_repo, row.id, jwt_roles)
    else:
        await _assign_default_role(session, role_repo, audit_repo, row.id)
    return row


async def sync_jwt_roles(session: AsyncSession, user_id: str, jwt_roles: list[str]) -> None:
    """Public entry point for re-syncing a user's roles from JWT claims.

    Used by the ensure-user cache fast path in ``dependencies.py``: when the
    user row is already in the per-process cache we skip ``ensure_user_row``
    but still need to reconcile roles each request. Caller commits.
    """
    role_repo = RoleRepo(session)
    audit_repo = AuditRepo(session)
    await _sync_jwt_roles(role_repo, audit_repo, user_id, jwt_roles)


async def _sync_jwt_roles(
    role_repo: RoleRepo,
    audit_repo: AuditRepo,
    user_id: str,
    jwt_roles: list[str],
) -> None:
    """Reconcile ``user_roles`` for ``user_id`` against the JWT-derived list.

    JWT is authoritative: roles missing from the JWT are revoked, new ones
    are added. Role names not present in the ``roles`` table are skipped
    (logged at WARNING). A single ``user.roles_synced`` audit row is written
    when the role set changes.
    """
    current = await role_repo.list_user_roles(user_id)
    current_by_name = {r.name: r for r in current}

    desired: dict[str, str] = {}  # name -> role_id
    for name in jwt_roles:
        if name in desired:
            continue
        role = await role_repo.get_by_name(name)
        if role is None:
            logger.warning(
                "JWT role not present in roles table; skipping",
                role=name,
                user_id=user_id,
            )
            continue
        desired[name] = role.id

    added: list[str] = []
    removed: list[str] = []

    for name, role_id in desired.items():
        if name not in current_by_name:
            await role_repo.assign_role(user_id, role_id)
            added.append(name)

    for name, role in current_by_name.items():
        if name not in desired:
            await role_repo.revoke_role(user_id, role.id)
            removed.append(name)

    if added or removed:
        await audit_repo.write(
            event="user.roles_synced",
            actor_user_id=user_id,
            target_type="user",
            target_id=user_id,
            audit_metadata={"added": added, "removed": removed, "source": "jwt"},
        )


async def _assign_default_role(
    session: AsyncSession,
    role_repo: RoleRepo,
    audit_repo: AuditRepo,
    user_id: str,
) -> None:
    """Assign the configured default role to a freshly-created user.

    Role assignment is owned outside the app: saas/on_prem deployments sync
    roles from the JWT claim (see ``_sync_jwt_roles``), and everything else
    falls back here. There is no first-user-becomes-admin bootstrap — an oss
    operator who wants an admin sets ``OPENRAG_DEFAULT_ROLE=admin``.
    """
    # No-auth synthetic user -> configurable role
    if user_id == "anonymous":
        target_name = _noauth_role()
    else:
        target_name = _default_new_user_role()

    role = await role_repo.get_by_name(target_name)
    if role is None:
        logger.warning(
            "default role not found, skipping role assignment",
            role_name=target_name,
            user_id=user_id,
        )
        return
    await role_repo.assign_role(user_id, role.id)
    await audit_repo.write(
        event="user.created",
        actor_user_id=user_id,
        target_type="user",
        target_id=user_id,
        audit_metadata={"role": target_name},
    )


async def _assign_default_role_if_missing(
    session: AsyncSession,
    role_repo: RoleRepo,
    audit_repo: AuditRepo,
    user_id: str,
) -> None:
    roles = await role_repo.list_user_roles(user_id)
    if roles:
        return
    await _assign_default_role(session, role_repo, audit_repo, user_id)


async def get_effective_provider_keys(session: AsyncSession, user_id: str) -> dict:
    """Phase-4 helper. Returns a dict of provider -> overrides for this user.

    Phase 1 ships a no-op shape so call sites can be wired without behavior
    change. Phase 4 will fill it in by reading user_preferences.provider_overrides
    and overlaying onto config_manager's workspace defaults.
    """
    return {}


async def get_effective_agent_config(session: AsyncSession, user_id: str) -> dict | None:
    """Phase-4 helper. Returns the per-user agent config overlay (or None)."""
    return None