STDIO MCP server 透传认证用户身份（opt-in per server，供 on-behalf-of 调用 REST 后端）

[ncw1992120]

需求

把发起调用的认证用户身份透传给 STDIO MCP server，让 MCP server 能代表该用户调用底层 RESTful 后端（on-behalf-of）。

为什么现状做不到

• STDIO MCP client 是每个 server 配置一个共享、长期存活的子进程（McpClientManager.clients = ConcurrentHashMap<serverId, McpSyncClient>），所有用户/workspace/会话共用。
• env（envJson）在子进程 spawn 时一次性注入，expandEnvVars 只展开 JVM system property + OS env，没有 per-user 上下文，spawn 后不可变。
• STDIO 没有 HTTP 那种 per-request header 通道。

所以身份不能走 env（共享进程 + 静态），必须随每次 tool call 在带内传递。而当前 PrefixedNameToolCallback.call(toolInput, toolContext) 只把 LLM 产生的参数原样发给子进程，没有注入身份。

方案：受信层每次调用注入身份（opt-in per server）

• MateClaw 在 tool-call 时已知道认证用户：ToolExecutionContext.username(toolContext)。
• 在 McpClientManager.wrapServerCallbacks 里，对显式开启的 server，把每个 callback 再包一层 IdentityForwardingToolCallback：调用前把 __mateclaw_user__ 注入进 toolInput 的 JSON（覆盖 LLM 可能伪造的同名值），再转发。
• MCP server 侧读出该字段、剥掉，作为 header（如 X-On-Behalf-Of）连同后端 API Key 一起调 REST。

安全要点

• 必须 opt-in per server：默认全量注入会把用户名泄漏给任意第三方 MCP server。用配置允许清单 mateclaw.mcp.identity-forward.servers（按 server name 或 id）开启。
• 身份由受信 Java 代码注入、不经 LLM；LLM 若塞了同名字段会被覆盖。
• 明文 username 仅适合 REST 在内网、且信任 MCP 子进程的场景；更强场景应改为 MateClaw 签发短时 JWT（本 issue 先做明文 opt-in，签名 token 可作后续）。

范围

• 新增 IdentityForwardingToolCallback + McpIdentityForwardProperties（允许清单）。
• McpClientManager.wrapServerCallbacks 对 opt-in server 包装。
• 单测覆盖：注入存在、覆盖 LLM 值、未 opt-in 不注入、无用户名不注入。
• 文档：MCP 接入说明里写明 opt-in 配置 + MCP server 侧如何读取 __mateclaw_user__。

[ncw1992120]

更新：增加"签名 token"信任模型（已实现，并入 PR #460）

明文 username 让 REST 后端裸信一个来自共享、LLM 相邻的 MCP 服务的不可验证断言（confused-deputy）。增加一个 opt-in 的签名 token 模式，让身份以短时 RS256 JWT跨信任边界，后端用公钥验签。

流程

MateClaw 现签 JWT(私钥, sub=user, aud=server, exp≈60s)
  → 注入 args["__mateclaw_token__"]（覆盖 LLM 同名值）
  → Python MCP server 透传 Authorization: Bearer <jwt>（不验签）
  → REST 后端用公钥验签 + 校 iss/aud/exp → 取 sub 做 per-user 授权

配置

mateclaw:
  mcp:
    identity-forward:
      servers: [ my-internal-api ]
      token:
        enabled: true            # 默认 false → 退回明文（向后兼容）
        issuer: mateclaw
        ttl-seconds: 60
        key-id: mateclaw-mcp-1
        private-key-pem: ${MCP_IDFWD_PRIVATE_KEY_PEM:}   # PKCS#8 PEM, RS256
        audiences: { my-internal-api: https://api.internal }

关键决策

• 非对称 RS256：MateClaw 持私钥签，REST 持公钥只验——后端无法伪造/冒充。
• fail-closed：token 模式开但无私钥 → 不签不注入（后端拒），不偷偷退回明文。
• claims：iss/sub/aud/iat/exp/jti；aud+短 exp 把重放限制在几十秒、单一后端。
• sub 当前是 MateClaw 用户标识（ChatOrigin.requesterId）；按不可变数字 id 鉴权可在签发前解析（刻意不耦合用户存储）。

仍待办（follow-up，非阻塞）

• JWKS 端点自动分发公钥 + 轮换（当前公钥带外配置）。
• sub 解析成不可变 user id。
• 可选：把注入从 args 切到 MCP _meta（语义更干净，需绕过 Spring AI 的 callback 直连 callTool）。

实现：McpIdentityForwardService（签发）+ IdentityForwardingToolCallback（注入）+ token 配置；测试覆盖 mint+验签/明文/无用户·无私钥 fail-closed；文档含 keygen + REST 验签示例。74 个 MCP 测试全绿。

[ncw1992120]

Review：webchat / api 渠道下 requesterId 的身份语义错配（接上一条更新）

上一条更新提到 sub/__mateclaw_user__ 当前取自 ChatOrigin.requesterId。这里补一个跨渠道的语义盲点：requesterId 在不同渠道含义不同，无差别注入会让 on-behalf-of 在访客渠道下传递"非认证身份"。

requesterId 的渠道差异

渠道	requesterId 来源	语义	MCP 后端能否据此鉴权
WebAPI / Studio（JWT/PAT 登录）	auth.getName()（ChatController:167）	MateClaw 账号用户名	✅ 能
IM（飞书等）	message.getSenderId()	IM 发送者 id	⚠️ 外部平台 id
WebChat（访客）	visitorId（WebChatController:223）	访客匿名标识	❌ 后端查无此人
cron	写死 "system"（ChatOrigin.cron）	系统	❌ 非真实用户

WebChat 渠道的具体问题

WebChat 是"单 MateClaw 账号 + 一个 API Key（X-MC-Key）服务多个匿名访客"的对外渠道。visitorId 由调用方自报、服务端 HMAC 签发 visitorToken 防伪（WebChatController:1628-1745），设计目的是区分共享账号背后的不同终端用户、做记忆隔离——它不是 MateClaw 账号体系内的认证身份。

McpIdentityForwardService.resolve()（:74）对所有渠道无差别取 ToolExecutionContext.username(ctx)，在 webchat 下拿到的是裸 visitorId，直接注入 __mateclaw_user__/JWT sub。这带来三个问题：

1. on-behalf-of 失效：MCP server 的 REST 后端不认识 visitorId，"代表该用户调用"无的放矢。若后端拿它当用户名查权限，要么查无此人，要么 visitorId 碰巧等于某真实用户名时误中他人账户（撞库风险）。

2. 前缀不一致，无法关联：记忆隔离用带前缀的 api:<visitorId>（MemoryOwnerResolver:51），会话归属用 webchat:<visitorId>（webchatUsername:1660），但 MCP 透传用裸 visitorId。同一访客在三处身份标识长得不同，审计无法对齐。

3. token 模式的"认证背书"隐患（d204b702）：用 visitorId 作 sub 签发 RS256 JWT，后端验签通过（MateClaw 私钥签的）——签名给了一个非认证身份以"已认证"的外观。如果 MCP 后端把"签名有效"等同于"是 MateClaw 认证用户"，webchat 访客会获得本不该有的信任级。这可能比明文更危险。

建议（follow-up，非阻塞当前 PR）

• 渠道感知注入：McpIdentityForwardService.resolve() 根据 ChatOrigin.channelType() 区分。对 api/访客渠道：要么 fail-closed 不注入（最安全），要么注入带语义前缀的标识（如 webchat:<channelId>:<visitorId>），让 MCP 后端明确知道这是访客而非账号身份。
• JWT 加渠道声明：token 模式签发时增加 channel_type claim（web/api/im），后端可据此降级访客身份的信任级，或拒绝 on-behalf-of。
• 文档明确：在 STDIO MCP server 透传认证用户身份（opt-in per server，供 on-behalf-of 调用 REST 后端） #459 设计文档里写清"webchat/IM 渠道透传的是访客/外部 id，非认证账号身份"，提醒 MCP server 实现者区分对待。

ps：这条与"待办：sub 解析成不可变 user id"是相邻问题——后者解决"WebAPI 用户用什么 id"，本条指出"访客渠道根本不该按账号身份透传"。