RuView V3 Claims Authorizer：基于声明（Claims）的 Swarm Agent 与 MCP 工具细粒度授权体系

本文以 RuView 仓库中 V3 多智能体安全层的核心组件 claims-authorizer 为主体，完整讲解其“声明（Claims）— 策略（Policy）— 审计（Audit）”三层授权模型：涵盖五类声明的定义、claude-flow CLI 授权命令的用法、RBAC/ABAC 策略文件的编写方式、MCP 工具保护映射表、Hook 自动拦截配置与审计日志记录机制。读完本文，你可以理解并复现在一个 AI Swarm 工作区中对每个 Agent、每个 MCP 工具实施最小权限访问控制的完整方案。

组件定位：V3 智能体安全层中的授权专家

在 RuView 仓库的 .claude/agents/ 目录下，项目按职能组织了大量 Claude Code 子代理（subagent）定义。其中 v3/ 子目录集中了 16 个面向 V3 架构的专家代理，claims-authorizer 是其中专职负责**授权（Authorization）**的角色。

从该文件的 YAML frontmatter 可以读出组件的完整元信息：

name: claims-authorizer
type: security
color: "#F44336"
version: "3.0.0"
description: V3 Claims-based authorization specialist implementing ADR-010 for
  fine-grained access control across swarm agents and MCP tools
capabilities:
  - claims_evaluation
  - permission_granting
  - access_control
  - policy_enforcement
  - token_validation
  - scope_management
  - audit_logging
priority: critical
adr_references:
  - ADR-010: Claims-Based Authorization

几个要点值得注意：

• type: security 表明它与安全类代理（如 security-architect、security-auditor、pii-detector、injection-analyst）同属一个安全组；其中 security-architect 的 capabilities 里显式列出了 claims_based_authorization，说明两个代理在职责上是互相衔接的——架构师负责零信任设计，授权者负责运行时执行。
• priority: critical 意味着在 Swarm 调度中它的执行优先级最高，因为授权失败必须先于任何资源访问发生。
• 文档中提到的 ADR-010: Claims-Based Authorization 来自 claude-flow V3 生态自身的 ADR 编号体系（与 adr-architect 中的 ADR 索引表一致，该表将 ADR-010 记录为 Claims-Based Authorization / Accepted）。需要特别说明：仓库 docs/adr/ 目录下按序号命名的 ADR-010（Witness Chains for Audit Trail Integrity）是 RuView 项目自身另一套编号体系，两者编号重合但主题不同，阅读时应加以区分。
• 该代理依赖的授权引擎是通过 npx claude-flow@v3alpha 拉取的外部 npm 包（v3alpha 版本），仓库内定义的是代理行为、策略与 Hook 配置本身；这一点在实际部署时需要具备 Node.js 环境与网络访问能力。

frontmatter 中还内嵌了 pre/post 钩子脚本，分别负责授权前置检查与决策落盘（详见后文 Hook 集成 与 审计日志 两节），与正文的 Hook 配置互为表里。

Claims 授权架构：AGENT → EVALUATOR → RESOURCE

文档给出的整体架构是一张清晰的三段式数据流图：

┌─────────────────────────────────────────────────────────────────────┐
│                    CLAIMS-BASED AUTHORIZATION                       │
├─────────────────────────────────────────────────────────────────────┤
│   ┌─────────────┐      ┌─────────────┐      ┌─────────────┐        │
│   │   AGENT     │      │   CLAIMS    │      │  RESOURCE   │        │
│   │             │─────▶│  EVALUATOR  │─────▶│             │        │
│   │ Claims:     │      │ Policies:   │      │ Protected   │        │
│   │ - role      │      │ - RBAC      │      │ Operations  │        │
│   │ - scope     │      │ - ABAC      │      │             │        │
│   │ - context   │      │             │      │             │        │
│   └─────────────┘      └─────────────┘      └─────────────┘        │
│                                                                     │
│   ┌─────────────────────────────────────────────────────────────┐  │
│   │                    AUDIT LOG                                │  │
│   │  All authorization decisions logged for compliance          │  │
│   └─────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘

架构包含四个要素：

1. AGENT（请求方）：Swarm 中的一个 Agent，它持有一组声明（role / scope / context）；
2. CLAIMS EVALUATOR（评估器）：授权的核心，按 RBAC（基于角色）与 ABAC（基于属性）两套策略对声明进行求值；
3. RESOURCE（受保护资源）：被保护的操作或资源命名空间；
4. AUDIT LOG（审计日志）：所有授权决策（允许或拒绝）统一写入，用于合规追溯。

这是一个典型的“无隐式信任、默认拒绝”（fail-closed）设计：Agent 不携带所需声明时，评估器直接拒绝，且文档中 Hook 命令明确带有 --auto-deny 参数作为兜底。

Claim 类型体系：五类声明及其语义

文档将声明划分为五种类型，这是整套策略语言的“词汇表”：

Claim	含义	示例取值
role	Agent 在 Swarm 中的角色	coordinator、worker、reviewer
scope	允许的操作范围	read、write、execute、admin
context	执行上下文（把权限限定在特定会话/任务内）	swarm:123、task:456
capability	具体能力项	file_write、bash_execute、memory_store
resource	资源访问（支持通配符的命名空间）	memory:patterns、mcp:tools

从这套类型设计可以看出授权判定是多维合取的：一次访问请求不仅要问“你是谁”（role），还要问“你被允许做什么级别的事”（scope）、“你能调用哪类能力”（capability）、“你能碰哪个命名空间”（resource），而 context 声明进一步把权限收敛到具体的 Swarm 实例或任务——例如一个只带 swarm:123 上下文的 Agent，即使持有 scope:write，其写入也不应越出该 Swarm 的作用域。resource 使用 命名空间:路径 的点分/冒号路径（如 memory:patterns、security:*），并支持 * 通配符，这与后文授权命令中的 --resource "memory:*" 写法一致。

授权命令：check / grant / revoke / list

授权操作的入口是 claude-flow CLI 的 claims 子命令族，文档给出的四条核心命令覆盖授权生命周期：

# 检查某 Agent 是否有权对资源执行某操作
npx claude-flow@v3alpha claims check \
  --agent "agent-123" \
  --resource "memory:patterns" \
  --action "write"

# 授予声明：允许 agent-123 对 memory:* 资源写
npx claude-flow@v3alpha claims grant \
  --agent "agent-123" \
  --claim "scope:write" \
  --resource "memory:*"

# 撤销声明：收回 agent-123 的 admin 范围
npx claude-flow@v3alpha claims revoke \
  --agent "agent-123" \
  --claim "scope:admin"

# 列出某 Agent 当前持有的全部声明
npx claude-flow@v3alpha claims list --agent "agent-123"

四个动词的语义对应了标准的权限生命周期管理：

• check：只读判定，不产生副作用。参数三元组 --agent / --resource / --action 正对应架构图中 AGENT 与 RESOURCE 两个端点。frontmatter 的 pre hook 中实际使用的正是这条命令（claims check --agent "$AGENT_ID" --resource "$RESOURCE" --action "$ACTION"），即在每次受保护操作执行前做一次实时求值。
• grant：授权。注意 --claim "scope:write" 与 --resource "memory:*" 的组合——声明（scope）与资源范围（resource）是成对绑定的，授予的是“对某命名空间执行某级别操作”的复合权利，而不是孤立的 scope。
• revoke：撤销。只按 --claim 精确收回，不影响该 Agent 的其他声明，支持权限的渐进式回收（de-escalation）。
• list：审计与排障手段，用于核对 Agent 的实际声明集合是否与策略文件（下节）的意图一致。

此外，文档在 Hook 集成中还出现了两个衍生命令形态：claims check ... --auto-deny（判定失败时直接拒绝而非降级询问）与 claims evaluate --request '$PERMISSION_REQUEST'（对整个权限请求对象做一次性求值），说明评估器既支持“资源+动作”的离散参数形式，也支持结构化的请求对象形式，可以适配不同调用场景。

RBAC 策略：coordinator 与 worker 的角色声明模板

角色策略文件用 YAML 描述“某角色出厂即持有的一组声明”。文档给出两个完整模板：

coordinator-policy.yaml（协调者：拥有对 Swarm 的完全控制权）

# coordinator-policy.yaml
role: coordinator
claims:
  - scope:read
  - scope:write
  - scope:execute
  - capability:agent_spawn
  - capability:task_orchestrate
  - capability:memory_admin
  - resource:swarm:*
  - resource:agents:*
  - resource:tasks:*

worker-policy.yaml（工作者：最小化权限的普通执行者）

# worker-policy.yaml
role: worker
claims:
  - scope:read
  - scope:write
  - capability:file_write
  - capability:bash_execute
  - resource:memory:own
  - resource:tasks:assigned

对比两份策略可以看出最小权限原则的落点：

维度	coordinator	worker
操作范围	read + write + execute（+ 隐含管理）	read + write
能力	agent_spawn / task_orchestrate / memory_admin	file_write / bash_execute
资源	swarm:*、agents:*、tasks:*（全域通配）	memory:own、tasks:assigned（仅自身/已分配）

关键差异在资源限定词上：worker 的 memory:own 与 tasks:assigned 表明其资源范围被动态限定到“自己的记忆”与“分配给自己的任务”，而 coordinator 使用 * 全域通配并获得 agent_spawn（派生新 Agent）与 memory_admin（管理记忆）这类元能力。这实际上形成了一条授权链：只有 coordinator 级的声明才能执行 MCP 工具授权 表中 swarm_init（要求 scope:admin + capability:swarm_create）与 agent_spawn（要求 scope:execute）等敏感操作。

ABAC 策略：基于属性的条件授权

角色固定的场景外，文档还定义了基于属性的策略（ABAC），以“安全架构师”为例：

# security-agent-policy.yaml
conditions:
  - agent.type == "security-architect"
  - agent.verified == true
claims:
  - scope:admin
  - capability:security_scan
  - capability:cve_check
  - resource:security:*

ABAC 的价值在于把授权决策从“静态角色”升级为“运行时条件谓词”。这里有两个条件的合取：

• agent.type == "security-architect"：Agent 的类型标记；
• agent.verified == true：一个需要外部证据支撑的属性——Agent 身份已验证。

只有两个条件同时成立，scope:admin、security_scan、cve_check 能力与 security:* 资源访问才会被授予。从设计意图看，verified 属性为接入设备认证/密钥验证等机制预留了挂点：即使某个 Agent 自报 type == "security-architect"，若验证属性为假，评估器仍会拒绝其 admin 请求。这也解释了为何 security-architect 代理的 pre hook 中包含 CVE 数据库检查（security cve --check-relevant）与 HNSW 威胁模式检索——属性值本身是由运行时证据计算出来的，而非硬编码。

MCP 工具授权：保护工具与所需声明映射

MCP（Model Context Protocol）工具是 Agent 触达外部能力的通道，文档为五类高危工具逐一指定了所需声明：

Tool	Required Claims
swarm_init	scope:admin，capability:swarm_create
agent_spawn	scope:execute，capability:agent_spawn
memory_usage	scope:read|write，resource:memory:*
security_scan	scope:admin，capability:security_scan
neural_train	scope:write，capability:neural_train

从这张映射表可以读出三层防护梯度：

1. Swarm 生命周期级（swarm_init、agent_spawn）：需要 admin/execute 高范围 + 专属 capability，双重声明缺一不可。这与 RBAC 策略中仅 coordinator 持有 agent_spawn 能力相呼应——普通 worker 即使 scope 满足也拿不到对应 capability。
2. 数据面级（memory_usage）：要求 read|write 任一操作范围 且 资源落在 memory:* 命名空间内，即 scope 与 resource 两个维度同时校验。
3. 计算/安全级（security_scan、neural_train）：安全扫描被划入 admin 级；模型训练（neural_train）只需 scope:write + 对应 capability，属于中危操作，与“训练会改写模型资产”的影响面匹配。

该表同时定义了拒绝响应的结构（见 错误处理）：请求方缺哪条声明、已持有哪条声明，评估器都会逐项列出，便于 Agent 侧的编排逻辑决定是请求提权还是改用协调者。

Hook 集成与工具调用拦截

声明检查不应依赖 Agent“自觉调用”，文档给出的方案是把它挂到 Claude Code 的 Hook 生命周期上，在所有 MCP 工具调用发生之前强制求值：

{
  "PreToolUse": [{
    "matcher": "^mcp__claude-flow__.*$",
    "hooks": [{
      "type": "command",
      "command": "npx claude-flow@v3alpha claims check --agent $AGENT_ID --tool $TOOL_NAME --auto-deny"
    }]
  }],
  "PermissionRequest": [{
    "matcher": ".*",
    "hooks": [{
      "type": "command",
      "command": "npx claude-flow@v3alpha claims evaluate --request '$PERMISSION_REQUEST'"
    }]
  }]
}

两个 Hook 的分工：

• PreToolUse + ^mcp__claude-flow__.*$：matcher 用正则只拦截 mcp__claude-flow__ 前缀的工具调用，即所有经 claude-flow MCP 服务器暴露的工具。命中后执行 claims check，并以 --agent $AGENT_ID --tool $TOOL_NAME 把当前会话变量注入命令，--auto-deny 保证求值失败或超时时的默认行为是拒绝。
• PermissionRequest + .*：对一切权限请求做全量二次评估（claims evaluate --request 接收序列化的完整请求对象），作为第一道 PreToolUse 拦截之外的第二道防线。

这套 Hook 配置与仓库实际生效的 Hook 框架是同一机制：RuView 的 .claude/settings.json 已经在使用 PreToolUse（matcher Bash，由 hook-handler.cjs 处理）、PostToolUse（matcher Write|Edit|MultiEdit）、SessionStart/SessionEnd、SubagentStart 等同类钩子类型，且每条都带 timeout 约束（如 pre-bash 5 秒、post-edit 10 秒）。从源码结构看，claims 检查 Hook 挂入后遵循同样的执行模型：钩子命令在对应事件点被 Shell 化执行，其输出/退出码决定是否放行工具调用——这也意味着把 claims check 放入 PreToolUse 后，即使提示词注入诱导模型发起越权工具调用，拦截也会发生在模型之外、执行之前。

另外注意 claims-authorizer frontmatter 自带的 pre/post 钩子：pre 阶段在 Agent 被激活时即对 $AGENT_ID/$RESOURCE/$ACTION 三元组执行 claims check，post 阶段把本次 $AUTH_DECISION 以 auth:<unix时间戳> 为键写入 audit 命名空间——Agent 级钩子（激活即校验 + 决策即落盘）与全局 Hook（每次工具调用即校验）形成双层拦截。

审计日志：全决策留痕与查询

授权体系的可信度最终由“决策可回放”保证。文档规定所有授权决策（无论 allow 还是 deny）都写入审计记忆空间：

# 写入一条授权决策（结构化 JSON 作为值）
mcp__claude-flow__memory_usage --action="store" \
  --namespace="audit" \
  --key="auth:$(date +%s)" \
  --value='{"agent":"agent-123","resource":"memory:patterns","action":"write","decision":"allow","reason":"has scope:write claim"}'

# 按模式查询最近 100 条审计记录
mcp__claude-flow__memory_search --pattern="auth:*" --namespace="audit" --limit=100

实现上有几个值得注意的工程选择：

• 命名空间隔离：审计数据存放在专用 audit 命名空间，与业务记忆（如 security、patterns）互不污染，查询时用 --pattern="auth:*" 前缀匹配即可精确圈定授权类记录。
• 键即时间戳：auth:$(date +%s) 以 Unix 秒为键，天然有序，配合查询侧的 --limit 形成“取最近 N 条”的窗口语义。
• 值即证据：--value 携带完整五元组 {agent, resource, action, decision, reason}，其中 reason 字段（如 has scope:write claim）记录了求值依据，使事后审计不仅知道“结果”，还能知道“为什么”——这是文档中“All authorization decisions logged for compliance”一语的具体落地。

值得补充的是，RuView 仓库对审计完整性还有一套更重的机制：ADR-010（Witness Chains） 用 SHAKE-256 哈希链 + ML-DSA-65 周期性锚点签名来为灾难检测事件构建防篡改见证链（锚点间隔默认每 100 条，可配置）。两套机制面向不同层面——claims 审计记录的是“谁在何时被允许/拒绝”，Witness Chain 保护的是“记录本身不可抵赖、不可篡改”，二者结合恰好覆盖授权合规的两个方向。

默认策略：按 Agent 类型的出厂权限基线

文档为常见 Agent 类型定义了默认声明集，构成无策略文件时的基线（baseline）：

Agent Type	Default Claims
coordinator	Full swarm access
coder	File write, bash execute
tester	File read, test execute
reviewer	File read, comment write
security-*	Security scan, CVE check
memory-*	Memory admin

这张表与 RBAC 策略 的 worker 模板（file_write + bash_execute）在 coder 一行上完全对应，可视为 worker-policy 的默认实例化；reviewer（只读 + 评论写）与 security-*（安全扫描 + CVE 检查，对应 security_scan/cve_check 能力）则分别覆盖了评审与安全两条职能线。security-*、memory-* 两个通配行说明默认策略本身也支持前缀匹配，与 ABAC 中 agent.type == "security-architect" 的属性判定互补：默认表管“类型基线”，ABAC 管“条件提权”。

默认策略的定位是安全兜底而非充分授权：类型未知或不匹配任何默认行时，按 fail-closed 原则只应获得最小权限（文档未授予即拒绝），需要更多权限时走 claims grant 显式授予——这与 MCP 工具授权 表、Hook 拦截共同构成“默认拒绝、显式授予、全程留痕”的闭环。

错误处理：结构化拒绝响应

被拒请求的响应体是结构化的，而不是一句模糊的“权限不足”：

// Authorization denied response
{
  "authorized": false,
  "reason": "Missing required claim: scope:admin",
  "required_claims": ["scope:admin", "capability:swarm_create"],
  "agent_claims": ["scope:read", "scope:write"],
  "suggestion": "Request elevation or use coordinator agent"
}

五个字段各有用途：

• authorized: false + reason：机器可判定的布尔结果与人类可读的原因；
• required_claims：缺口清单——本次操作需要但缺失的全部声明（上例中是 swarm_init 所要求的两条）；
• agent_claims：现有声明快照——当前 Agent 实际持有的声明；
• suggestion：可执行建议——请求提权（走 claims grant 流程）或改用已具备权限的 coordinator Agent。

这种“要求 vs 持有”双清单设计使编排层（如 Swarm 调度器）能够程序化地做权限差集运算：当 diff 仅为 context 类声明时可自动重绑定执行上下文，当 diff 涉及 scope:admin 时才需要人工/协调者介入，避免把一次简单的上下文缺失升级成一次提权申请。

适用前提与工程边界

最后明确该组件的运行前提，避免误用：

1. 运行时依赖外部包：全部 claims 子命令均经由 npx claude-flow@v3alpha 执行（v3alpha 表示该功能处于 alpha 通道），需要 Node.js/npx 环境与首次拉取的网络访问；仓库本身只包含代理定义、策略模板与 Hook 配置。
2. 环境变量契约：Hook 命令依赖 $AGENT_ID、$RESOURCE、$ACTION、$TOOL_NAME、$AUTH_DECISION、$PERMISSION_REQUEST 等由运行环境注入的变量，部署时需保证这些变量在钩子上下文中可用。
3. 与项目主业务解耦：claims-authorizer 属于 .claude/agents/ 下的开发工作区治理层（管的是“哪个 AI Agent 可以碰哪类资源/工具”），与 RuView 的 WiFi 感知核心业务（v2/crates/ 下的 Rust 感知栈、固件 等）无直接运行时依赖；其价值在于为多 Agent 协作开发本仓库的过程提供安全护栏。

小结

claims-authorizer 展示的是一套完整的声明式授权闭环：五类声明（role/scope/context/capability/resource）作为权限词汇表 → RBAC 模板 + ABAC 条件定义策略 → claims check/grant/revoke/list 四命令管理生命周期 → PreToolUse/PermissionRequest 双层 Hook 在执行前强制求值 → audit 命名空间记录全部决策五元组 → 结构化拒绝响应暴露声明缺口。对任何在 Claude Code 工作区中运行 Swarm 式多 Agent 的项目，这套“声明—策略—拦截—审计”四件套都提供了可直接参照的最小权限设计范式；结合仓库中已有的 Hook 基础设施（.claude/settings.json、hook-handler.cjs）与审计完整性机制（Witness Chains ADR），它展示了 RuView 在“AI 开发 AI”这一工程实践上的纵深安全考量。