M1: 后端

[DeliciousBuding]

背景

负责 Hub Server，以及 Edge Server 与 Hub Server 的通信边界。目标是让后续 Web/Mobile、同步、中继和远程控制有清楚的 Go 服务基础。

要做什么

• 搭建 hub-server/ Go 服务入口和基础路由。
• 明确 Edge 注册、心跳、设备状态、同步、relay 的接口边界。
• 在 edge-server/ 中保留 Hub client 入口，不把 Hub 逻辑写死进 Edge 本地执行路径。
• 对齐 api/openapi.yaml 和 api/events.md，缺接口先补 API 再实现。
• 优先参考 docs/reference/03-build/backend/16-hub-server-requirements.md 和 02-go-services.md。

验收标准

• Hub Server 能启动并提供 health endpoint。
• Edge-Hub 注册/心跳接口有最小可运行实现或清楚 mock。
• 服务边界写入对应 README 或实现文档。
• go test ./... 可运行，暂时不能运行时写明原因。

[DeliciousBuding]

审计补充：Hub auth/device 会话链路需要先收敛

这次审计只基于公开仓库代码和文档，没有使用任何私有配置或生产数据。下面两个问题都能落到当前实现，建议并入后端 M1 的 auth/session hardening。

1. 登录、刷新、登出的 device_id 语义目前不一致

证据：

• hub-server/internal/service/auth.go:89-109：Login 先生成 devUUID := uuidv7.Must()，随后 UpsertDevice 创建的设备 ID 是另一个 uuidv7.Must()；access token 却用客户端请求里的 deviceID 生成；refresh token 行保存的是 devUUID。
• hub-server/migrations/0015_refresh_tokens.up.sql:5：refresh_tokens.device_id 是 uuid NOT NULL REFERENCES devices(id)。
• hub-server/internal/service/auth.go:148：logout 按当前 access token 里的 device_id 撤销 refresh token。
• app/desktop/src/api/hubAuth.ts:201-206：桌面密码登录生成 desktop_<timestamp>_<random> 这样的非 UUID device id；另一个稳定 UUID 只在 useDeviceRegistration.ts 中生成，登录没有复用它。

影响：

• 在真实 PostgreSQL 外键约束下，Login 可能因为 refresh token 的 device_id 不指向 devices.id 而失败。
• 即使某些测试/环境放过了写入，access token 中的 device_id 和 refresh token 行的 device_id 也不同，/client/auth/logout 无法撤销本次登录签发的 refresh token。
• RefreshToken 会用 refresh token 行里的 device_id 重新签 access token，用户同一会话刷新后 device identity 会变化，后续 /edge/*、WS 路由和登出语义都会变得不可预测。

建议验收：

• 明确一种模型：要么客户端先注册并传入真实 devices.id UUID，登录/refresh/logout 全链路都复用它；要么把 device_id 设计成客户端稳定 public id，并同步修改 DB 类型、外键和路由逻辑。
• 增加一条真实 PostgreSQL 或 FK-enabled 集成测试：登录成功后，devices.id、access token claim device_id、refresh_tokens.device_id 三者一致。
• 增加 logout 回归测试：登录后调用 logout，再用同一个 refresh token 调 /client/auth/refresh 必须失败。

2. TokenDance ID bearer 兼容路径缺少 iss / aud 强校验

证据：

• hub-server/internal/jwtutil/tokendance.go:132-181 只按 JWKS kid 校验 RS256 签名和标准时间类 claim；函数没有接收 expected issuer/client id，也没有显式验证 audience。
• hub-server/internal/middleware/auth.go:30-35 只要 ParseTokenDanceJWT 成功，就把 claims.Subject 当作 Hub user_id 放进 Gin context。
• hub-server/README.md:183 已把显式 iss / aud 校验列为 P0 hardening 项。

影响：同一个 issuer 的其它 client token，或缺少目标 audience 的 token，可能被 Hub 当作 AgentHub API bearer token 接受。即便这是兼容路径，也应该至少校验 iss == cfg.TokenDanceID.IssuerURL 且 aud 包含 AgentHub Hub 的 client id。

建议验收：

• ParseTokenDanceJWT 或 middleware 接收 expectedIssuer / expectedAudience，并覆盖 issuer mismatch、audience mismatch、missing audience 的单测。
• 如果 TokenDance bearer 只是临时兼容路径，文档和接口返回也要明确不能替代 Hub 本地 session issuance。

[DeliciousBuding]

审计补充（2026-05-25）：TokenDance ID / Hub auth 边界

这轮只记录有代码证据的问题，不包含任何生产拓扑或私密环境信息。

1. TokenDance ID bearer 路径缺少显式 issuer/audience 校验

证据

• hub-server/internal/middleware/auth.go:31 在配置了 TokenDance ID 时直接调用 jwtutil.ParseTokenDanceJWT(tokenStr)，成功后设置 auth_source=tokendance_id 并放行请求。
• hub-server/internal/jwtutil/tokendance.go:135 的 ParseTokenDanceJWT(tokenString string) 只接收 token 本身；当前签名没有 expected issuer / audience / client id 参数，调用点也没有传入这些约束。
• README.md 的 TokenDance ID 鉴权边界已经把“TokenDance ID 路径缺少显式 issuer/audience 校验”标成 P0 hardening 项。

影响

REST bearer 路径目前依赖 JWKS/RS256 和标准过期校验，但没有把 token 绑定到 AgentHub 这个 relying party。对 server-backed Hub API 来说，iss 和 aud 必须是授权边界的一部分，否则同一身份系统里面向其他 client 的 token 可能被误接受。

建议验收

• ParseTokenDanceJWT 或上层 middleware 接收 expected issuer 与 expected audience/client id。
• 校验失败时返回 401，并有单元测试覆盖 wrong issuer、wrong audience、missing audience、expired、unknown kid。
• 配置项中明确 AgentHub Hub Server 期望的 TokenDance ID issuer 与 audience，不把它们写死在业务代码里。

2. /client/ws 的认证边界和 REST 不一致

证据

• REST middleware 支持 TokenDance ID RS256 bearer，再 fallback 到 Hub local HS256：hub-server/internal/middleware/auth.go:29-51。
• WebSocket 首帧 auth 只调用 jwtutil.ParseToken(accessToken, h.jwtSecret)：hub-server/internal/handler/ws.go:93-101。
• Desktop Hub WS 客户端会把当前 getToken() 的 token 放进首帧 access_token：app/desktop/src/api/hubWS.ts:66-82。

影响

同一个用户 token 可能出现“REST /client/auth/me 可用，但 Hub WebSocket auth.fail”的状态。对 IM / message sync / remote dispatch 来说，这会把登录成功和实时能力割裂。

建议验收

• 最终浏览器/桌面登录流优先落到 Hub-issued access/refresh session；WS 和 REST 都只消费一致的 Hub session 边界。
• 如果保留 TokenDance ID bearer 兼容路径，WS 首帧也应执行同等 issuer/audience/JWKS 校验，而不是只走 Hub local HS256。
• 增加测试：Hub local token REST+WS 均可用；TokenDance ID token 的兼容策略在 REST+WS 一致；错误 issuer/audience 在 REST+WS 均拒绝。

[DeliciousBuding]

Cleanup pass note: this issue still points at an older surface. Please retarget it to latest dev/delicious233 before implementation. Current remaining work should be phrased against Web/Desktop/Hub/Edge real-mode contracts, TokenDanceID readiness, and release evidence rather than the old M1 or root runner wording.

[DeliciousBuding]

Cleanup decision: closing as stale/resolved against current dev/delicious233.

Evidence checked against origin/dev/delicious233 9283579:

• The issue body is an old M1 backend container.
• The important TokenDance ID auth hardening called out in comments is now implemented through ParseTokenDanceJWT(token, expectedIssuer, expectedAudience) and middleware passes cfg.TokenDanceID.IssuerURL + cfg.TokenDanceID.ClientID.
• Tests now cover expected audience rejection and OIDC issuer/audience validation paths.
• Remaining backend release blockers should stay in specific security/risk issues, not this old aggregate M1 issue.

No source changes made in this cleanup pass.