配置写操作审批

写审批与配置治理

明确只读的已发布工具在权限通过后执行；写工具和未分类工具需逐次审批。内建账号可通过已登录的管理台审批；仅 YAML 和无身份的高级本地模式不能审批写操作。

按需显式授予兼任角色；管理权限本身不等于写审批权限。生产写工具还应由后端落实原子版本检查与业务幂等。通知链接不能代替浏览器审批，审批完成也不会跳过执行时的权限检查。

配置步骤与完整示例见单次写审批、配置治理与双人审批、审批通知和独立归档。用户与审批人的实际操作见写操作审批。

单次写入审批

MCP 后端与 HTTP 工具组均支持 tool_rules[].effect: read / write。明确标为 read 的工具通过发布、scope 和资源检查后可直接执行；写工具和未分类工具需要逐次审批。匹配到 approval 策略也按写工具处理，不能被更宽泛的 read 规则覆盖。HTTP 方法和后端自报的 readOnlyHint 不授予权限。

启用内建账号管理，团队部署使用远程管理，为配置管理员和审批人分别授予 scope；普通 MCP 调用凭证只使用 MCP 服务的 audience。审批人的浏览器使用管理服务 audience，但无需配置管理权限：

admin:
  # 保留当前模板的管理模式、公开地址和数据库字段。
  required_scopes: [mcphub:admin]
  approvals:
    required_scopes: [mcphub:approve]
    pending_ttl: 30m
    execution_ttl: 5m
    retention: 720h
    # 内建账号默认值；企业 SSO 按实际 MFA/Passkey 策略添加企业 ACR。
    step_up_acr_values: ["urn:mcphub:auth:password-totp"]

pending_ttl 从申请时开始，范围 1 分钟至 24 小时，默认 30 分钟；execution_ttl 从批准时重新计算，范围 1 至 30 分钟，默认 5 分钟；保留期范围 1 至 365 天，默认 30 天。管理静态配置修改需重启。配置管理员默认不能审批，审批人默认不能查看或修改后端配置；需要兼任时由身份服务显式授予两组权限。管理登录页提供独立的审批人登录入口。

在现有 Tool Rules（JSON） 编辑器或 YAML 配置审批策略：

published_tools: [get_project, preview_update, update_project]
tool_rules:
  - match: get_project
    effect: read
  - match: preview_update
    effect: read
  - match: update_project
    effect: write
    required_scopes: [projects:write]
    resource_rules:
      - argument: /project
        allowed_values: [work]
    approval:
      action: 修改项目配额
      environment: production
      resource_arguments: [/project]
      require_different_reviewer: true
      require_step_up: true
      approvers:
        - subjects: [reviewer-oidc-sub]
          resources:
            - argument: /project
              allowed_values: [work]
      preview_tool: preview_update
      version_argument: /expected_version

approvers 使用同一身份服务验证过的精确 subject，不使用 Agent 提交的用户名。每个 grant 内的资源条件必须全部满足，不同 grant 之间为“或”；多个匹配 tool 规则的审批限制全部生效。资源条件可以检查项目、数据库、目录或环境参数。未配置 approvers 时，具有审批 scope 的账号均可审批；require_different_reviewer 禁止申请人自行审批。审批列表和详情也受范围限制，申请人可查看自己的申请但不因此获得批准权限。

使用流程：

1. Agent 调用写工具，收到 structuredContent.code: approval_pending、approval_id 和 approval_url。写操作尚未执行；若配置预览，会先调用指定的只读工具。
2. 用户打开链接，以审批人身份登录，核对操作摘要、目标、业务资源、完整参数，以及可用的变更前后预览；填写理由后批准一次或拒绝。
3. require_step_up: true 时，先点击“加强身份验证”。内建账号先重新验证密码和 TOTP，普通密码登录不能满足要求；企业身份则由 MCPHub 请求 OIDC max_age=0、prompt=login、nonce 和配置的 ACR，并验证签名、issuer、客户端 audience、同一 subject、nonce、auth_time 和返回的 ACR；有 at_hash 时也校验。允许最多 30 秒时钟偏差。通过后仍需点击批准，证明仅绑定该审批单和浏览器会话，2 分钟内单次有效。身份服务缺少 OIDC 或没有满足配置的认证强度时拒绝批准。ACR 的具体 MFA/Passkey 含义由身份服务配置，不是通用字符串。
4. 原调用人调用 mcphub_resume_approval，只传 {"approval_id":"..."}，执行已保存请求并重新检查当前权限、发布状态、资源范围及限流。查询进度使用独立状态工具，相同活跃请求会被合并。现有 mcpbridge connect 配置无需修改。
5. 执行前，申请人可调用 mcphub_cancel_approval，传 approval_id 和可选 reason；有审批人会话的申请人也可在页面取消。审批人可撤销尚未执行的批准。取消、撤销与执行原子竞争；已经接纳的写入可能完成，撤销不能回滚。

预览契约： preview_tool 指向同一后端/工具组中已发布且明确标为只读的原始工具名，接收与写工具相同的参数。其 structuredContent（HTTP 工具为 JSON 对象响应体）须包含 version、before、after，例如 {"version":"v7","before":{"limit":10},"after":{"limit":20}}。version_argument 指向调用参数中的具体、非空版本字符串，不能使用 *。网关在申请及恢复时都验证预览权限和资源条件，并比对预览、版本及工具代次；变化或失败均拒绝执行。后端写操作还必须原子检查该版本，例如 HTTP If-Match 或数据库条件更新；仅预览无法消除检查与写入之间的竞争。HTTP 参数可通过已有 Header 参数映射把 /expected_version 对应的参数发为 If-Match。未配置预览时仍展示管理员定义的操作摘要、资源及完整参数，不会推测变更结果。

审批页面支持状态、精确工具名、精确申请人筛选和游标分页；每页默认 25 条。批准、拒绝、撤销、取消、执行、过期和重启恢复记录审计。对“结果不确定”可填写核查结果（已生效、未生效、仍不确定）和证据说明；记录不会改变执行状态或恢复执行额度。管理 API 为 GET /api/v1/approvals?status=&tool=&subject=&limit=25&cursor=、GET /api/v1/approvals/{id}，以及 POST /api/v1/approvals/{id}；后者接受 decision（approved/rejected/revoked/cancelled/investigated）、必填 reason（最多 2048 字节），核查还需要 outcome（applied/not_applied/uncertain）。强验证入口为 POST /api/v1/approvals/{id}/verify。这些接口均要求审批浏览器会话及相应资源权限；修改还需 CSRF/Origin 验证。

SQLite/PostgreSQL 原子消费批准，并发恢复不会执行两次；重复恢复返回保存结果。取消、断网或进程中断可能留下不确定结果，需要先核查后端。本机制不保证后端恰好执行一次或回滚。工具/配置代次变化会使对应批准失效，完整 runtime 重载和重启使未执行批准失效；重启将中断执行标为不确定。参数、业务 metadata 和后端续传输入不可修改，仅进度 token 绑定恢复请求；大整数精度保持不变。后端需要另一次调用继续交互时需重新审批。

每个 issuer/subject 最多 21 个活跃申请，执行请求最多 60 KiB，预览最多 32 KiB，含策略的完整审批记录最多 64 KiB，结果最多 16 MiB。请求、预览、结果、理由及核查详情加密保存；每分钟分批清理超过保留期的终态记录及详细审计，通用活动日志保留不含参数/理由的状态记录。配置变更前已接纳的操作仍可能完成。批准写入使用新的 HTTP/1 连接防止透明重试，上游须支持 HTTP/1.1；只读调用仍复用连接。

新部署的托管数据库使用 schema 10，备份时保管数据库及匹配密钥。内建账号已登录的本地管理台可以审批；无身份的高级本地模式和仅 YAML 部署不能执行写工具或未分类工具。MCP Token 和管理 API Bearer Token 均不能批准；应隔离 Agent 与审批人浏览器、配置/数据库权限及上游写凭证。未启用配置治理时，配置管理员可直接修改工具分类；启用独立安全审批可约束这些变更。MFA 不能替代审批人核对具体内容和后端最小权限控制。