权限上下文路由:agent-memory 按记忆类型分流授权策略的 PEP 设计实战
权限上下文路由: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 的路由取值规则:
- 先从规范化
FilterExpr中提取逻辑上强制的唯一等值(_required_filter_metadata,local_support.py):OR 多值、NOT、AND 冲突以及未限定字段不会产出候选值; - 再由
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):
- 先做基础 scope 门槛(
_unit_lookup_permission_context,仅含 unit_id 与 scope); - 调用
Engine.permission_context_for_unit(unit_id, scope)从真源解析 unit 元数据; - 用解析出的真实
memory_type/tags再做类型化权限检查。
真源解析的实现(两个 Engine 完全一致,_permission_context_from_unit)从 unit.system_metadata 读取 memory_type、pipeline,并把 unit_id、scope、tags 一并带入:
- in_memory_engine.py(InMemoryEngine,走 KVStore)
- cloud_engine.py(CloudEngine,走 DomainStore)
对应 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:
fallback必须指向一个已存在的具名 permission policy;fallback不得是allow_all:fallback 承接的是"路由值缺失"的请求——调用方只要不写 filters 就能触发,此时没有路由值可回注为系统谓词、查询范围不受约束,若 fallback 又是allow_all,等于把"不声明类型"变成免鉴权后门。fallback 必须是最小权限策略;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 的门」。
两道防线:
- 授权所依据的路由值被回注为系统谓词: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 也无法稀释这条约束。 - 路由值缺失时无值可注入,全部落 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)。
拒绝的方案
特性文档明确拒绝了三类方案,理解它们有助于把握本特性的设计边界:
- 拒绝让
MemoryPipeline接管权限判断:权限是 API 层 PEP 的统一入口,交给 pipeline 会让审计、grant/revoke 和管理面权限语义分裂; - 拒绝把
memory_type作为 get/update/delete 的用户入参:已有 unit 的类型必须以真源 metadata 为准,否则调用方可以通过伪造memory_type绕过严格策略; - 拒绝一次性新增完整 RBAC/ABAC 规则语言:当前需求只需要把资源上下文传给权限后端,并提供按上下文选择 delegate 的基础能力。
已知遗留
- delete 按 selector 预解析候选上下文会扫描 KV,大规模后端需要更高效的 metadata-only 查询接口;
- audit / admin / job 权限仍走全局或 scope 级上下文,没有按 memory_type 分流;
- routing 权限后端的 route key 当前只支持
memory_type、pipeline、resource_type或可规范为字符串的 metadata 等值。
参考与深入阅读
- 特性文档:docs/features/control/F04-permission-context-routing.md
- 控制层规约(PermissionManager 契约与 routing 配置示例):docs/specs/S03-control.md
- 接口定义:jiuwen_memory/control/permission.py、jiuwen_memory/control/types.py
- routing 实现:jiuwen_memory/control/permission_impl/routing_permission_manager.py
- PEP 侧上下文构造与回注:jiuwen_memory/api/memory_api_impl/local_support.py、jiuwen_memory/api/memory_api_impl/query_ops.py
- 真源元数据解析:jiuwen_memory/control/engine_impl/in_memory_engine.py、jiuwen_memory/control/engine_impl/cloud_engine.py
- 专项测试:tests/unit/control/test_permission_context_routing.py