权限上下文路由:agent-memory 按记忆类型分流授权策略的 PEP 设计实战

原创2026-10-13 13:03:391,880 阅读
文章标签:Agent 记忆人工智能MCP 服务RAGAI Agent

权限上下文路由:agent-memory 按记忆类型分流授权策略的 PEP 设计实战

本篇技术指南聚焦 agent-memory 控制层新增的 权限上下文(PermissionContext)与 routing 权限后端,讲解如何在多记忆类型(coding / episodic / procedural 等)pipeline 架构下,让授权策略按资源上下文区分,同时堵住"用 A 的钥匙开 B 的门"这类越权路径。读完你将掌握 PermissionContext 的五类入口构造规则、routing_permission_manager 的配置与装配约束、以及路由值回注(系统谓词)这条核心防线,并能结合源码与测试用例验证其行为。

背景:scope/action 级鉴权在多记忆类型下的局限

agent-memory 的控制层(jiuwen_memory/control/)原本已有 PermissionManager.check(actor, target, action),但它只能表达 scope 和动作级别的权限。多记忆类型 pipeline 引入后,不同记忆类型对访问强度的要求并不一致,典型例子来自特性文档 docs/features/control/F04-permission-context-routing.md:

  • coding 记忆:包含仓库约定、工程规范等敏感内容,要求更严格的 同 owner 访问;
  • 普通情景记忆(episodic):可以使用较宽松的 grant 或 dev 策略。

问题的关键不只是"需要按类型区分策略",更在于一个安全前提:仅靠调用方传 memory_type 不够安全。add/search 的 memory_type 来自请求本身,可以直接用于入口鉴权;但 get/update/delete 作用于已有 unit,必须以真源(truth source)中保存的 metadata 为准,不能信任调用方声明——否则调用方只需伪造一个宽松类型的 memory_type,就能绕过 coding 记忆的严格策略。

PermissionContext 数据结构与兼容签名

基于上述背景,控制层引入 PermissionContext,并把 PermissionManager.check 扩展为兼容签名(新增参数带默认值,旧实现可忽略、旧调用可不传):

def check(
    actor: Scope,
    target: Scope,
    action: Action,
    context: PermissionContext | None = None,
) -> bool:
    ...

接口定义位于 jiuwen_memory/control/permission.py。PermissionContext 是 jiuwen_memory/control/types.py 中的 dataclass,承载的字段如下:

字段 含义 典型取值
resource_type 资源类型 write_input / query / memory_list / memory_unit / delete_selector / admin / job 等
memory_type 记忆类型 coding / episodic / procedural …
pipeline pipeline profile 名 调用侧或真源元数据已知时的 profile 名
unit_id 已存在记忆单元 id 非 unit 操作为空
scope 资源真实归属 未知时为空 scope
tags 标签元组 鉴权时可用的标签集合
metadata 字符串映射 路由值恒为字符串,构造点已做 str().strip() 归一化

一个值得注意的实现细节:业务 metadata 在真源中保留原生类型(如 MetadataValueType),只有进入 PermissionContext 的路由值才规范为字符串——metadata 字段类型是 dict[str, str],delegate 选择按字符串比较。此外 PermissionContext 还携带 space_facts(SpaceAuthorizationFacts | None),用于空间级判定场景(F07 群体记忆)。

API 层上下文构造:五类入口的取值规则

PermissionContext 从哪来,直接决定了鉴权结论的可靠性。API 层(PEP,即 Permission Enforcement Point)按入口分五种构造方式,实现在 jiuwen_memory/api/memory_api_impl/local_support.py 与 jiuwen_memory/api/memory_api_impl/query_ops.py:

1. add / check_write:从入参构造

_write_permission_context(local_support.py)从入参 system_metadata["memory_type"]、metadata["pipeline"] 与 tags 构造上下文,resource_type="write_input"。瞬态键(infer / procedural 的 route_ctx 等)不进入上下文,因为它们是编排用的键、不可序列化,不应越过持久化与判定边界。

2. search:filter 等值兜底 + extensions 覆盖

_recall_permission_context(local_support.py)遵循 S03 的路由取值规则:

  1. 先从规范化 FilterExpr 中提取逻辑上强制的唯一等值(_required_filter_metadata,local_support.py):OR 多值、NOT、AND 冲突以及未限定字段不会产出候选值;
  2. 再由 Context.extensions[route_key] 的非空值覆盖。

这条规则与执行侧 MemoryPipeline 的 profile 选择同源——权限若另立一套取值,就会出现"按 A 授权、按 B 执行"的错位。search 入口的完整调用链见 query_ops.py:构造上下文 → _authorize_with_context 入口鉴权 → 路由值回注 → 叠加两族系统谓词 → asyncio.run(self._queries.recall(...))。

3. list:逐类型鉴权

_list_permission_contexts(local_support.py)从入参 memory_types 构造:显式传多个类型时,逐个 memory_type 做 READ 权限检查,全部通过后才枚举。extensions 同样只解释 routing_fields() 声明的路由键,其余插件扩展值保持不透明——不进 PermissionContext.metadata,也不隐式 str()。

4. get / update:先基础门槛,再真源元数据

这是"不信任调用方声明"的落地处。流程(见 query_ops.py 的 get 与 query_ops.py 的 update):

  1. 先做基础 scope 门槛(_unit_lookup_permission_context,仅含 unit_id 与 scope);
  2. 调用 Engine.permission_context_for_unit(unit_id, scope) 从真源解析 unit 元数据;
  3. 用解析出的真实 memory_type / tags 再做类型化权限检查。

真源解析的实现(两个 Engine 完全一致,_permission_context_from_unit)从 unit.system_metadata 读取 memory_type、pipeline,并把 unit_id、scope、tags 一并带入:

对应 Engine 接口方法见 jiuwen_memory/control/engine.py,update 路径还支持 prepare_update 计划中的逐变更鉴权(update_permission_contexts)。

5. delete:selector 命中集逐条鉴权

delete 调用 Engine.permission_contexts_for_delete(selector) 解析 selector 命中的候选 unit,逐条做 DELETE 权限检查,全部通过后才执行删除(query_ops.py)。实现按 scope 分组遍历命中的 MemoryUnit(InMemory 版 in_memory_engine.py,Cloud 版 cloud_engine.py),并支持 DeleteSelector 的 unit_ids / tags / before / filters 组合匹配。

routing 权限后端:只选 delegate,不定义授权语义

新增的 routing_permission_manager(jiuwen_memory/control/permission_impl/routing_permission_manager.py)是一个策略路由器:它不自行定义授权语义,只根据 PermissionContext 选择一个已配置的 PermissionManager delegate,并把 check 委托给它。S03 的配置示例(docs/specs/S03-control.md):

permission:
  default:
    target: routing
    params:
      route_key: memory_type
      fallback: standard
      routes:
        coding: strict
  standard: sqlite
  strict: sqlite

装配期硬约束

RoutingPermissionManager.__init__(routing_permission_manager.py)在装配期强制三类校验,配错即抛 ValidationError:

  1. fallback 必须指向一个已存在的具名 permission policy;
  2. fallback 不得是 allow_all:fallback 承接的是"路由值缺失"的请求——调用方只要不写 filters 就能触发,此时没有路由值可回注为系统谓词、查询范围不受约束,若 fallback 又是 allow_all,等于把"不声明类型"变成免鉴权后门。fallback 必须是最小权限策略;
  3. routes 与 fallback 均不得指向 routing 自身。

_build(routing_permission_manager.py)同样校验 fallback 非空、routes 必须是映射、且不能指向 routing 自身,然后按 PermissionProducer.build_named 装配各 delegate。

路由取值与 delegate 选择

_select(routing_permission_manager.py)的逻辑:

  • 按 route_key 从上下文取值(_context_value,routing_permission_manager.py),支持 memory_type、pipeline、resource_type 三个内置键,或 metadata 中可规范为字符串的任意等值键;
  • 只接受 routes 中显式声明的业务值,未命中一律落 fallback;
  • 与 Pipeline 路由不同,授权侧不允许"路由值本身是 policy 名则直接使用"——若沿用该兜底,调用方就能直接点名 policy 来挑选审查自己的策略,等于"让被审查者选审查员"。

grant / revoke 广播

grant / revoke(routing_permission_manager.py)广播给全部 delegate(去重后的 _unique_policies),避免调用方需要理解授权记录应该落在哪个后端。routing_fields()(routing_permission_manager.py)返回 (self._route_key,),声明本实现鉴权路由所依据的 metadata 字段——这正是回注防线所需的能力声明。

注意 RoutingPermissionManager.check 不做额外的 deny、不对多个 policy 求交集:root / owner-cover / Grant 等基础规则(见 S03 的 check 规则 1–5)全部由被选中的 delegate 判定。曾有一个回归点:路由未解析时在 delegate 之前就 return False,导致 owner 查自己 scope 也被拒——这由测试 test_unresolved_route_keeps_owner_base_rule 固定。

路由值回注:把"授权策略"绑定到"可读数据范围"

对 search/list 而言,仅选对 delegate 仍不足以防越权。routing_permission_manager.py 的模块注释点出了结构性风险:

「谁来审查」和「能读到什么」是两个独立输入,且都由调用方控制。调用方可以把路由值填成宽松策略对应的类型、filters 却指向受严格策略保护的数据,即「用 A 的钥匙开 B 的门」。

两道防线:

  1. 授权所依据的路由值被回注为系统谓词:API 在完成权限检查后,读取 PermissionManager.routing_fields(),把路由值作为 FilterClause(EQ) 回注 RetrievalQuery.filters,并与用户表达式做外层 AND。实现是 _routing_clauses_of(local_support.py),在 query_ops.py 中以 and_merge(rq.filters, routing_clauses) 注入。于是按 memory_type=episodic 获得的授权只能读取同类型数据,不能再通过另一组 filters 指向 coding 记忆——用户表达式中的 OR 也无法稀释这条约束。
  2. 路由值缺失时无值可注入,全部落 fallback,因此 fallback 必须是最小权限策略(装配期强制)。

list 入口的等价物是 _list_routing_clauses(local_support.py):多类型请求下仅当路由值收敛为单一值时才生成 EQ 谓词,避免把多个授权结论错误合并。

四类越权路径与测试验证

特性文档要求的新测试位于 tests/unit/control/test_permission_context_routing.py,其中的配置 _routing_config 是"coding 受 strict 保护、episodic 显式放宽、fallback 取最小权限"的典型装配。测试覆盖了文档要求的全部行为:

测试 验证点
test_add_permission_routes_by_memory_type add 按请求 metadata 的 memory_type 路由
test_search_permission_routes_by_metadata_memory_type_filter search 按等值 filter 路由到 strict
test_policy_name_is_not_accepted_as_route_value 直接传 policy 名(如 standard)被拒绝
test_permissive_fallback_rejected_at_assembly allow_all 作为 fallback 在装配期失败
test_get_permission_uses_stored_memory_type_context get 按真源中已保存的 unit memory_type 路由
test_delete_permission_checks_each_matched_unit_context delete 对 selector 命中的 unit 逐条鉴权
test_route_value_injection_still_returns_own_type_data 回注谓词不得误伤本类型数据

尤为关键的是 "四条越权路径(均实测复现过,必须保持关闭)" 一组测试,它们分别对应:

  • test_escalation_1_unknown_extensions_value_falls_to_strict_fallback:未知路由值 → 落最小权限 fallback → 拒绝;
  • test_escalation_2_missing_route_value_falls_to_strict_fallback:不带任何 filters → 无值可注入 → 落 fallback;
  • test_escalation_3_ambiguous_or_filter_falls_to_strict_fallback:OR 歧义过滤推不出唯一等值 → 落 fallback(树形表达式带来的新攻击面);
  • test_escalation_4_lenient_route_cannot_read_protected_data:路由到宽松策略可以通过鉴权,但读不到受严格策略保护的数据——这条不经过 fallback,靠的是路由值回注后 memory_type=episodic 与用户的 coding 过滤 AND 后自相矛盾,返回空结果。

特性文档给出的验证基线命令为:

PYTHONPATH=. uv run --no-sync pytest -q \
  tests/unit/control/test_permission_context_routing.py \
  tests/unit/control/test_pipeline.py \
  tests/unit/api/test_handler_identity_split.py

权限后端与默认装配

  • 默认装配(jiuwen_memory/config/defaults.py)中 permission.default.target = sqlite(db_path: ":memory:"),allow_all 仅作为 dev-only 的最小放行实现(allow_all_permission_manager.py),真实部署应使用基于 SQLite 的 ACL(sqlite_permission_manager.py),它实现了 Scope() 平台管理员放行、owner-cover、跨 org 默认拒绝、grant 持久化与软撤销(revoked_at)。
  • routing 权限后端与 Pipeline 执行路由同源但职责独立:两者对 recall 都使用"extensions 优先、FilterExpr 强制唯一等值兜底"的取值规则,但 PermissionManager 选择授权策略、MemoryPipeline 选择执行组件(如 examples/config_multimodal.yml 中按 pipeline 键路由的 profile 装配),互不代替。
  • S03 明确规定:权限上下文由 API/Engine 解析,不信任调用方声明。这正是本文 get/update/delete 三段真源解析的设计出处(见 docs/specs/S03-control.md 不变量 13–15)。

拒绝的方案

特性文档明确拒绝了三类方案,理解它们有助于把握本特性的设计边界:

  1. 拒绝让 MemoryPipeline 接管权限判断:权限是 API 层 PEP 的统一入口,交给 pipeline 会让审计、grant/revoke 和管理面权限语义分裂;
  2. 拒绝把 memory_type 作为 get/update/delete 的用户入参:已有 unit 的类型必须以真源 metadata 为准,否则调用方可以通过伪造 memory_type 绕过严格策略;
  3. 拒绝一次性新增完整 RBAC/ABAC 规则语言:当前需求只需要把资源上下文传给权限后端,并提供按上下文选择 delegate 的基础能力。

已知遗留

  • delete 按 selector 预解析候选上下文会扫描 KV,大规模后端需要更高效的 metadata-only 查询接口;
  • audit / admin / job 权限仍走全局或 scope 级上下文,没有按 memory_type 分流;
  • routing 权限后端的 route key 当前只支持 memory_type、pipeline、resource_type 或可规范为字符串的 metadata 等值。

参考与深入阅读

登录后查看全文
agent-memory