Files
AgentLab/backend/app/api/deps.py
T
ThearchyHelios 19329c873e 访问密钥与服务账号的后端(下一轮第 2 波 W2-d,细案 04 A1–A6、总方案 X8)
外部系统(门户、OA、BI)和个人脚本要用一个身份调接口,以前只能拿个人会话 cookie 去模拟。这次加访问密钥:

- 签发(A1):users.kind 区分人和服务账号(svc- 开头、没有口令、不能登录、角色固定使用者,管理员建);access_keys 只存
  sha256 和开头一截,明文 agl_ 加 32 字节随机串只显示一次;到期必填(最长 365 天、缺省 90 天)、可撤销、可轮换(新钥 + 旧钥
  24 小时后到期);个人访问密钥由管理员开关 auth.personal_keys 管,缺省关,关掉时已有的个人密钥一并不认
- 认人与门禁(A2):Principal 加 via / key_id / key_name / scopes / app_ids(全部带默认值);中间件认 Bearer agl_…,不看
  cookie、不查 CSRF、不看 X-Actor,认不出的各回 401 带各自的 code、绝不退回匿名;WebSocket 带密钥一律拒;关登录时 409
  keys_need_login。KEY_ROUTES(方法 + 路由模板 → scope)一张表,FastAPI(dependencies=[Depends(key_gate)]) 挂一次;不在表里的
  403 key_route_forbidden,缺 scope、限定应用、个人应用和试运行各有各的 403;每把密钥每分钟 120 次(429 + Retry-After)
- 封顶(A3):按密钥认出来的一律是使用者(拥有者现在的组),现有的使用者规则和遮罩全部自动生效,管理员的密钥也一样
- 写操作(A4):发起入口、刷新视图必须带 Idempotency-Key,api_receipts 按(拥有者, 键)去重,轮换后照样认得出;状态机从
  process/hooks.py 抽到 process/receipts.py,钩子和密钥共用(钩子现有测试原样通过),另按请求指纹拒掉同一个键办另一件事;
  有文件控件的入口 422;回复待办只给个人密钥、只限审批 / 补充输入 / 编辑稿件;run.origin、task.responded 记 via=key、哪把密钥
- 视图数据(A5):GET /api/apps/{id}/views/{view}/data(agentlab.viewdata/1),印章、清单哈希、口径卡指标原值和渲染文字,
  遮罩的 value 为 null(和页面同一个判断),按需视图只读缓存、不发起运行,只给正式运行
- 留痕(A6):建 / 撤销 / 轮换密钥、建 / 停用服务账号、开关个人密钥写审计;请求记录进程内缓冲、调度循环一拍里批量写、
  保留 90 天;last_used_at 至少隔 1 分钟写一次;钩子收件记录接口(manage),验签失败只在进程内按钩子计数
- 名录与派单:服务账号在名录里标出,岗位绑定、选人候选、提交审核、改派里排除,应用授权照收;服务账号发起的实例里派给发起人
  的待办交给任何人
- 接口说明(A7):GET /api/access-keys/reference 从 KEY_ROUTES 生成(要登录)

测试:签发与各种 401、门禁合约(遍历全站路由)、CSRF 与身份来源、封顶(管理员密钥取工件也是遮过的)、幂等(含轮换后、
半路杀进程)、留痕、待办种类、视图数据(真跑的遮罩会员库)、限流、钩子收件记录。
2026-10-16 13:48:09 +08:00

373 lines
20 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""请求里的「人」:身份与权限的唯一入口(docs/design/app-platform-and-look.md §2.7、附录 C)。
登录方式三种:off(默认,今天的行为)、local、oidc。各接口不直接碰请求头或会话,只问这里:
- actor_of(header):记在各「人」列上的名字。关登录时照旧解码 X-Actor(自报署名);开了登录返回认证过的
用户名,请求头一律不看——这样各接口的签名一个都不用改;
- current_principal():完整身份(用户名、角色、组、是否认证过、登录方式、经什么认出来的),中间件按请求写进 contextvar。
访问密钥认出来的身份(via=key)一律按使用者算,另带这把密钥的 scope 和限定的应用(auth/keys.py);
- 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,握手时按运行判;
- private_run_scope:挂在只给搭建者的运行子路由(对比、可验证报告、质询、假设分析)上,别人的个人应用刷新、个人蓝图
试运行只有拥有者能碰(auth/access.py 的 private_owner),管理员、搭建者也不例外。
关登录时:所有人等同 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
from starlette.requests import HTTPConnection
from app.api.coded import CHAT_FORBIDDEN, ROLE_REQUIRED, RUN_FORBIDDEN, RUN_PRIVATE, CodedHTTPException
#: 登录方式
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"
#: 经什么认出来的(docs/design/next-round/04-对外集成与触达.md A2):off 关登录的自报署名;session 会话 cookie(开登录时
#: 匿名也是这一种:没认出会话);key 访问密钥;hook 入站钩子的签名;share 分享链接(第 3 波)
via: str = "session"
#: 按访问密钥认出来的(via=key):哪一把、叫什么、带哪些 scope、限定在哪些应用(None 是不限应用)。别的认法都是空的。
#: 权限封顶在使用者(A3,auth/keys.principal_for_key):role 一律是 user,这几项只在门禁(auth/keys.key_gate)里再收窄
key_id: str | None = None
key_name: str | None = None
scopes: frozenset[str] = field(default_factory=frozenset)
app_ids: tuple[str, ...] | None = None
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 signer_verified() -> bool:
"""signer_of 记下的署名是不是认证过的身份:开了登录、这次请求的身份认证过时为真;关登录时署名是自报的,为假。
导入清单、累积快照清单、作废记录、清除原件记录的「是否认证」记这个(docs/design/next-round/05-已知遗留.md (c)),
和审计表、待办派单、run.origin 的 verified 同一个口径。证据要在生成那一刻定下:调用方和 signed_by 一起往下传。"""
principal = _principal.get()
return principal is not None and principal.mode != "off" and bool(principal.verified)
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", via="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(没登录,auth_required)/ 403(角色不够,role_required)。关登录时放行。
用在要看请求内容才知道要什么角色的地方(比如 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() -> CodedHTTPException:
return CodedHTTPException(403, "没有权限查看这次运行", RUN_FORBIDDEN)
#: 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 及以上:这次运行它能读就能(can_read_run:别人的个人应用刷新、个人蓝图试运行读不了)。
user:这次运行它能读(can_read_run),而且查询结果在工具边界就遮过(masked_at_boundary)。两个条件缺一不可:
没在边界遮过的运行,事件里 tool.end 的预览、运行状态里是查询结果的原文,遮罩管不到——自己发起的应用实例、
有授权的应用视图运行经应用页和证据接口读(那两处按派生遮罩给)。实际上满足两条的就是它自己开登录后发起的
问数据运行;关登录时自报同名留下的老运行没在边界遮过,开了登录也读不到。"""
if principal.mode == "off":
return True
if principal.at_least("builder"):
return await can_read_run(principal, run)
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 及以上放行,只有别人的个人应用刷新、个人蓝图试运行例外(只给拥有者,
_refuse_private);user 角色只在管理员开了问数据(Q2)时能碰这组接口:
- 列表、别人的运行一律不给(记录页是给搭建者看的);
- 能发起(只能是问数据的探索运行,start_run 里按请求体再查);能停止自己的问数据运行;
- 能读运行记录、事件、运行时的图,能连 WebSocket:按运行判(run_events_readable),握手时就判,不再一刀切只给
builder。能读的就是它自己发起、查询结果在工具边界遮过的问数据运行,事件、回答里只有遮过的值;
- 自己发起的应用实例、有授权的应用视图运行、参与的实例,经应用页(/api/apps/{id}/instances)和证据接口
(evidence_scope)读,这里不给原始事件和状态:tool.end 的预览、运行状态里是查询结果的原文,遮罩管不到。"""
principal = current_principal()
if principal.mode == "off":
return
if principal.at_least("builder"):
await _refuse_private(conn, principal)
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 CodedHTTPException(403, _RUNS_FOR_BUILDERS, ROLE_REQUIRED)
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 CodedHTTPException(403, _RUNS_FOR_BUILDERS, ROLE_REQUIRED)
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 CodedHTTPException(403, "没有权限:这项操作需要搭建者及以上的角色", ROLE_REQUIRED)
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)
#: 搭建者、管理员碰别人的个人应用刷新、个人蓝图试运行时的说法
PRIVATE_RUN = "没有权限查看这次运行:个人应用的刷新和个人蓝图的试运行只有拥有者能看"
#: 运行子路由里另带的运行 id(对比的基准 ?base=)
_RUN_QUERY_KEYS = ("base",)
async def _refuse_private(conn: HTTPConnection, principal: Principal) -> None:
"""builder 及以上:路径里的运行(和对比的基准)是别人的个人应用刷新、个人蓝图试运行时拒(403,WebSocket 握手前
1008)。不存在的运行放过去,由接口照旧回 404。"""
ids = [conn.path_params.get("run_id"), *(conn.query_params.get(k) for k in _RUN_QUERY_KEYS)]
for run_id in (i for i in ids if i):
if await can_read_run(principal, run_id):
continue
if conn.scope["type"] == "websocket":
from fastapi import WebSocketException, status
raise WebSocketException(code=status.WS_1008_POLICY_VIOLATION)
raise CodedHTTPException(403, PRIVATE_RUN, RUN_PRIVATE)
async def _private_run_scope(conn: HTTPConnection) -> None:
"""只给搭建者的运行子路由(main.py 里对比、可验证报告、质询、假设分析):角色由 require_role 判,这里只管别人的
个人应用刷新、个人蓝图试运行。"""
principal = current_principal()
if principal.mode != "off":
await _refuse_private(conn, principal)
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 conn.scope["type"] != "http":
return
if principal.at_least("builder"):
await _refuse_private(conn, principal)
return
ensure_role("user")
if conn.scope.get("method", "GET") != "GET":
raise CodedHTTPException(403, "没有权限:这项操作需要搭建者及以上的角色", ROLE_REQUIRED)
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 CodedHTTPException(403, "没有权限:问数据和助手需要搭建者及以上的角色,或由管理员为使用者开启问数据",
CHAT_FORBIDDEN)
#: 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)
private_run_scope = Depends(_private_run_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)