AgentLab/backend/app/api/deps.py

"""请求里的「人」：身份与权限的唯一入口（docs/design/app-platform-and-look.md §2.7、附录 C）。

登录方式三种：off（默认，今天的行为）、local、oidc。各接口不直接碰请求头或会话，只问这里：
- actor_of(header)：记在各「人」列上的名字。关登录时照旧解码 X-Actor（自报署名）；开了登录返回认证过的
  用户名，请求头一律不看——这样各接口的签名一个都不用改；
- current_principal()：完整身份（用户名、角色、组、是否认证过、登录方式），中间件按请求写进 contextvar；
- require_role(role)：挂在 main.py 的 include_router(..., dependencies=[...]) 上的路由级依赖；
- can_read_run / can_read_artifact：运行、工件的读权限（user 角色只能读有授权的应用视图运行、自己参与的实例）；
- ensure_role / ensure_can_publish：接口内部按请求内容判定的权限（MCP 的 stdio、受管级发布、版本退役，Q8）；
- restricted()：这次请求是不是开登录后的 user 角色（按请求内容收窄的接口用：问数据只能发起探索运行、工件按白名单给）；
- run_events_readable(principal, run)：运行的原始记录、事件、实时流能不能读（user 只读查询结果在工具边界遮过的）；
- ensure_conversation_access(session, conversation_id)：接受 conversation_id 的接口核对对话归属（对话按人隔离）；
- run_scope / evidence_scope / chat_scope：main.py 挂在运行、证据、问数据几组路由上的依赖，按 run_id 判断能不能读。
  run_scope 同样管运行的 WebSocket，握手时按运行判。

关登录时：所有人等同 admin、全部放行，行为和加这一层之前一模一样（界面上挂横幅说明）。

开登录（local / oidc）的实现由 app/auth/ 提供：会话、中间件、OIDC、引导第一个管理员。这个模块只定接口。
"""
from __future__ import annotations

from contextvars import ContextVar
from dataclasses import dataclass, field
from typing import Any
from urllib.parse import unquote

from fastapi import Depends, HTTPException
from starlette.requests import HTTPConnection

#: 登录方式
AUTH_MODES = ("off", "local", "oidc")
#: 角色由高到低
ROLE_RANK = {"user": 1, "builder": 2, "admin": 3}


@dataclass(frozen=True)
class Principal:
    """这次请求是谁。

    username：开登录时是认证过的用户名（不可改）；关登录时是自报的署名，可能为空。
    verified：是不是认证过的身份。关登录时恒为 False——审计、派给人的记录、run.origin 照实记。
    """

    username: str | None
    role: str = "admin"
    display_name: str | None = None
    user_id: str | None = None
    groups: tuple[str, ...] = field(default_factory=tuple)
    verified: bool = False
    mode: str = "off"

    def at_least(self, role: str) -> bool:
        return ROLE_RANK.get(self.role, 0) >= ROLE_RANK.get(role, 99)


#: 中间件按请求写入（app/auth/）。没写（关登录、测试直接调函数）时为 None
_principal: ContextVar[Principal | None] = ContextVar("agentlab_principal", default=None)


def set_principal(principal: Principal | None) -> Any:
    """中间件用：写入这次请求的身份，返回 token 供 reset。"""
    return _principal.set(principal)


def reset_principal(token: Any) -> None:
    _principal.reset(token)


def auth_mode() -> str:
    """当前的登录方式。环境变量 AGENTLAB_AUTH_MODE 优先于设置页（app/auth/ 实现读取与缓存）。"""
    from app.auth import current_mode

    return current_mode()


def decode_actor(header: str | None) -> str | None:
    """请求头 X-Actor 里的署名（设置页填的那个），没填就是 None。

    浏览器的请求头只能是 Latin-1：中文署名原样放进去，fetch 直接抛错、整个请求
    发不出去。所以前端按 encodeURIComponent 编码后发，这里解回来；老客户端发的
    纯 ASCII 署名解码前后一样。
    """
    value = unquote((header or "").strip()).strip()
    return value[:100] or None


def actor_of(header: str | None) -> str | None:
    """记在各「人」列上的名字。开了登录：认证过的用户名，请求头不看；关登录：解码 X-Actor。"""
    principal = _principal.get()
    if principal is not None and principal.mode != "off":
        return principal.username
    return decode_actor(header)


def signer_of(given: Any, header: str | None, limit: int = 100) -> str | None:
    """请求体里自带署名（signed_by）的留痕记谁：开了登录一律是认证过的用户名，请求体里填的不看——不然随手填一个名字就
    盖掉了登录的人；关登录时请求体里填的优先（截到 limit 个字），其次 X-Actor，都只原样记下（未认证）。"""
    principal = _principal.get()
    if principal is not None and principal.mode != "off":
        return principal.username
    if isinstance(given, str) and given.strip():
        return given.strip()[:limit]
    return decode_actor(header)


def current_principal() -> Principal:
    """这次请求的完整身份。关登录时：等同 admin、未认证，username 是中间件按 X-Actor 解出的自报署名；中间件没写
    （不在请求里，比如测试直接调函数、启动时的整理、调度循环）时同样等同 admin、未认证，username 为空。"""
    principal = _principal.get()
    if principal is not None:
        return principal
    return Principal(username=None, role="admin", verified=False, mode="off")


def actor_verified() -> bool:
    return current_principal().verified


def require_role(role: str) -> Any:
    """路由级依赖：至少是 role。关登录时放行。开登录时：没登录 401，角色不够 403（app/auth/ 实现）。"""
    from app.auth import role_dependency

    return role_dependency(role)


async def can_read_run(principal: Principal, run: Any) -> bool:
    """能不能读这次运行（证据、事件、工件）。关登录或 builder 以上：能。user：有授权的应用视图运行、自己参与的实例。"""
    from app.auth import run_readable

    return await run_readable(principal, run)


async def can_read_artifact(principal: Principal, artifact_id: str) -> bool:
    """能不能读这件工件：它属于的某次运行能读就能读。"""
    from app.auth import artifact_readable

    return await artifact_readable(principal, artifact_id)


def ensure_role(role: str) -> None:
    """接口内部用：至少是 role，否则 401（没登录）/ 403（角色不够）。关登录时放行。
    用在要看请求内容才知道要什么角色的地方（比如 MCP 的 stdio 只有管理员能建）。"""
    from app.auth import require

    require(role)


def ensure_can_publish(level: str | None) -> None:
    """发布工作流（Q8）：受管级只给管理员，已发布级给搭建者及以上。版本退役直接 ensure_role("admin")。
    BE-3 在 api/workflows.py 的发布、退役接口开头调。"""
    ensure_role("admin" if level == "governed" else "builder")


def user_can_chat() -> bool:
    """开登录后 user 角色能不能用问数据（Q2，管理员在「设置 → 身份」里开）。"""
    from app.auth import user_can_chat as allowed

    return allowed()


async def ensure_conversation_access(session: Any, conversation_id: str | None) -> Any:
    """接受 conversation_id 的接口（助手的 generate-stream、generate、app-stream、from-run……）在读这段对话的历史、记来源
    之前调：这段对话这个人能不能用（对话按人隔离，D-d）。能用交回对话（Conversation）；没给 id、对话不存在交回 None
    （和以前一样当没有历史，不报错）；存在但不能用回 403。规则见 api/conversations.py 的同名函数。"""
    from app.api.conversations import ensure_conversation_access as check

    return await check(session, conversation_id)


def _forbidden() -> HTTPException:
    return HTTPException(403, "没有权限查看这次运行")


#: user 角色在自己的问数据运行上能读的（GET /api/runs/{id} 之后的部分）：运行记录、事件、运行时的图，加上实时流
#: （WebSocket /stream，握手时另判）。这几样就是问数据页要的；状态、工件列表、checkpoint 历史不给
_CHAT_RUN_READS = ("", "/events", "/graph")
_RUNS_FOR_BUILDERS = "没有权限：运行记录只对搭建者及以上的角色开放"


def masked_at_boundary(run: Any) -> bool:
    """这次运行的查询结果是不是发起时就定下在工具边界遮（tools/datasource.py 的 MASK_RESULTS_OPTION）。开登录后 user 角色
    发起的问数据运行一定带它（api/runs.py 的 start_run），随运行记录沿用到续跑、审批恢复。"""
    from app.tools.datasource import MASK_RESULTS_OPTION

    options = getattr(run, "options", None)
    return isinstance(options, dict) and bool(options.get(MASK_RESULTS_OPTION))


async def run_events_readable(principal: Principal, run: Any) -> bool:
    """能不能读这次运行的原始记录、事件和实时流（GET /api/runs/{id}、/events、/graph，WebSocket /stream）。

    关登录、builder 及以上：能。user：这次运行它能读（can_read_run），而且查询结果在工具边界就遮过（masked_at_boundary）。
    两个条件缺一不可：没在边界遮过的运行，事件里 tool.end 的预览、运行状态里是查询结果的原文，遮罩管不到——自己发起的
    应用实例、有授权的应用视图运行经应用页和证据接口读（那两处按派生遮罩给）。实际上满足两条的就是它自己开登录后发起的
    问数据运行；关登录时自报同名留下的老运行没在边界遮过，开了登录也读不到。"""
    if principal.mode == "off" or principal.at_least("builder"):
        return True
    if run is None or not principal.username or not masked_at_boundary(run):
        return False
    return await can_read_run(principal, run)


def _own_chat_run(principal: Principal, run: Any) -> bool:
    return run is not None and bool(principal.username) and run.started_by == principal.username \
        and run.origin_kind == "chat"


async def _run_scope(conn: HTTPConnection) -> None:
    """/api/runs 下的接口和运行的实时流。builder 及以上全部放行；user 角色只在管理员开了问数据（Q2）时能碰这组接口：
    - 列表、别人的运行一律不给（记录页是给搭建者看的）；
    - 能发起（只能是问数据的探索运行，start_run 里按请求体再查）；能停止自己的问数据运行；
    - 能读运行记录、事件、运行时的图，能连 WebSocket：按运行判（run_events_readable），握手时就判，不再一刀切只给
      builder。能读的就是它自己发起、查询结果在工具边界遮过的问数据运行，事件、回答里只有遮过的值；
    - 自己发起的应用实例、有授权的应用视图运行、参与的实例，经应用页（/api/apps/{id}/instances）和证据接口
      （evidence_scope）读，这里不给原始事件和状态：tool.end 的预览、运行状态里是查询结果的原文，遮罩管不到。"""
    principal = current_principal()
    if principal.mode == "off" or principal.at_least("builder"):
        return
    if conn.scope["type"] == "websocket":
        # 握手前拒：服务端回 1008，不建立连接。没登录的中间件已经挡掉了，这里只剩按运行判
        if not (principal.username and user_can_chat()
                and await run_events_readable(principal, await _load_run(conn.path_params.get("run_id")))):
            from fastapi import WebSocketException, status

            raise WebSocketException(code=status.WS_1008_POLICY_VIOLATION)
        return
    ensure_role("user")
    if not user_can_chat():
        raise HTTPException(403, _RUNS_FOR_BUILDERS)
    method = conn.scope.get("method", "GET")
    run_id = conn.path_params.get("run_id")
    if run_id is None:
        if method == "POST" and conn.url.path.rstrip("/") == "/api/runs":
            return
        raise HTTPException(403, _RUNS_FOR_BUILDERS)
    run = await _load_run(run_id)
    rest = conn.url.path.rstrip("/").removeprefix(f"/api/runs/{run_id}")
    if method == "GET" and rest in _CHAT_RUN_READS:
        if await run_events_readable(principal, run):
            return
        raise _forbidden()
    if not _own_chat_run(principal, run):
        raise _forbidden()
    if method == "POST" and rest == "/cancel":
        return
    raise HTTPException(403, "没有权限：这项操作需要搭建者及以上的角色")


async def _load_run(run_id: str | None) -> Any:
    if not run_id:
        return None
    from app.db.base import SessionLocal
    from app.db.models import Run

    async with SessionLocal() as session:
        return await session.get(Run, run_id)


def restricted() -> bool:
    """这次请求的人是不是开登录后的 user 角色：对它来说遮罩就是边界，只能做问数据、用应用这几件事。"""
    principal = current_principal()
    return principal.mode != "off" and not principal.at_least("builder")


async def _evidence_scope(conn: HTTPConnection) -> None:
    """/api/runs/{run_id}/evidence… 这组证据接口：builder 及以上全部放行；user 角色只读（GET），而且这次运行要能读
    （can_read_run）。证据接口交出的查询行本身按派生遮罩处理过。"""
    principal = current_principal()
    if principal.mode == "off" or principal.at_least("builder") or conn.scope["type"] != "http":
        return
    ensure_role("user")
    if conn.scope.get("method", "GET") != "GET":
        raise HTTPException(403, "没有权限：这项操作需要搭建者及以上的角色")
    run_id = conn.path_params.get("run_id")
    if not run_id or not await can_read_run(principal, run_id):
        raise _forbidden()


async def _chat_scope(conn: HTTPConnection) -> None:
    """问数据和助手（对话、生成）：builder 及以上；user 角色要管理员开了问数据（Q2），而且只给问数据用得到的那几个接口。
    对话按人隔离（只看得到、只改得动自己建的）在 api/conversations.py 里按对话判（ensure_conversation_access）。"""
    principal = current_principal()
    if principal.mode == "off" or principal.at_least("builder"):
        return
    ensure_role("user")
    path = conn.url.path.rstrip("/")
    method = conn.scope.get("method", "GET")
    if user_can_chat() and (path.startswith("/api/conversations") or (method, path) in _CHAT_ROUTES):
        return
    raise HTTPException(403, "没有权限：问数据和助手需要搭建者及以上的角色，或由管理员为使用者开启问数据")


#: user 角色开了问数据时能用的其余接口：问数据的生成流、读当前助手模型、问数据页选数据源用的数据源名单
#: （GET /api/datasources/names，只有名字、说明和种类，不含连接信息）
_CHAT_ROUTES = frozenset({("POST", "/api/copilot/generate-stream"), ("GET", "/api/copilot/model"),
                          ("GET", "/api/datasources/names")})

run_scope = Depends(_run_scope)
evidence_scope = Depends(_evidence_scope)
chat_scope = Depends(_chat_scope)


def role_by_method(*, read: str, write: str) -> Any:
    """读（GET、HEAD）要 read，改动要 write 的路由级依赖：模型接入、运行默认值这类搭建者只读的设置。"""

    async def _check(conn: HTTPConnection) -> None:
        ensure_role(read if conn.scope.get("method", "GET") in ("GET", "HEAD") else write)

    return Depends(_check)