xrk-auth

name	xrk-auth
description	当你需要解释/排查 HTTP 或 WebSocket 的 401、127 回环例外、API Key 机制时使用；确保业务层不重复鉴权。

文档与代码

• docs/AUTH.md
• 门面：src/agent-runtime.js（_authMiddleware、checkApiAuthorization、wsConnect）
• 实现：src/infrastructure/http/runtime-auth.js、runtime-ws.js、auth.js

原则

• /api/ 由 HttpApi + AgentRuntime.checkApiAuthorization；公开路由 systemAuth: false。
• 默认所有客户端须 API Key；server.auth.loopbackExempt===true 时才允许「本机 Host+127」免 Key（公网/反代勿开）。runEnabled=true 时即便 exempt 也强制 Key。
• 控制台鉴权模式：公开 GET /api/system/auth-mode → requiresKey；禁止用无 Key 打受保护接口靠 401 探测。
• WS：wsConnect → runtime-ws；AgentRuntime.wsf[path] 可为 { handler, skipAuth: true } 跳过系统 Key。

API Key 携带

Header：X-API-Key、Api-Key、Authorization: Bearer|Token|ApiKey <key>；查询仅 api_key / apiKey。不接受 body 与 token/key 等易撞字段。

Node 26

• 扩展时判错用 Error.isError，勿 instanceof Error（skill xrk-node-runtime）。
• 业务 Core 不重复实现鉴权；HTTP 超时仍用 AbortSignal.timeout。