接口文档
通用响应结构：
{
"code": 0, // 0 成功，非 0 失败
"message": "ok",
"data": { ... } // 业务数据，见各接口
}
鉴权方式：
| 调用方 | 鉴权 | 请求头 |
|---|---|---|
| Agent 客户端 | 无 api_key，Ed25519 自签 | 无 |
| 业务方后端 | api_key（product_code='agent' 应用） | Authorization: Bearer <api_key> |
接口一览
| 分组 | 接口 | Method | Path | 调用方 |
|---|---|---|---|---|
| 注册 | 发起注册 | POST | /palm/openai/x/agent/register/init | Agent 客户端 |
| 注册 | 轮询注册状态 | POST | /palm/openai/x/agent/register/status | Agent 客户端 |
| 授权 | 换取 open_id | POST | /palm/openai/x/agent/code/exchange | 业务方后端 |
| 验证 | 拉公钥 / 查设备 | POST | /palm/openai/x/agent/verify/device | 业务方后端 |
| 验证 | 在线验签 | POST | /palm/openai/x/agent/verify/signature | 业务方后端 |
| 核验 | 发起 Step-up | POST | /palm/openai/x/agent/stepup/create | 业务方后端 |
| 核验 | 查询 Step-up | POST | /palm/openai/x/agent/stepup/query | 业务方后端 |
1. 发起注册
POST /palm/openai/x/agent/register/init · Agent 客户端（Ed25519 自签）
Agent 本地生成 Ed25519 密钥对，用私钥对 message 签名自证持有私钥，返回真人授权页 URL。待签名串：message = "clawkey-register-" + timestamp_ms。
请求参数：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
AppId | string | 是 | 控制台拿到的公开 app_id |
DeviceId | string | 是 | Agent 对外身份，^[A-Za-z0-9_-]{1,64}$，注册后不可变更 |
PubkeyDer | string | 是 | base64(Ed25519 SPKI DER) |
Message | string | 是 | clawkey-register-<timestamp>，与 Timestamp 严格一致 |
Signature | string | 是 | base64(Ed25519(message))，64 字节裸签名 |
Timestamp | int64 | 是 | Unix 毫秒，须在服务端时间 ±5min 内 |
响应 data：
| 字段 | 类型 | 说明 |
|---|---|---|
SessionId | string | 注册会话 ID，用于后续轮询 |
RegistrationUrl | string | 真人授权页 URL，交给真人打开 |
ExpiresAt | int64 | 会话过期时间戳（秒），TTL 10min |
常见错误码：
| code | 含义 |
|---|---|
| 2030140 | 签名校验失败 |
| 2030141 | message 格式错误 |
| 2030142 | timestamp 超出 ±5min |
| 2030143 | 重放（同 pubkey + ts 已用过） |
| 2030144 | device_id 已被占用 |
| 2030145 | 公钥指纹已存在 |
2. 轮询注册状态
POST /palm/openai/x/agent/register/status · Agent 客户端
真人扫码刷掌确认后，Agent 凭 SessionId 轮询拿到一次性 Code（建议 2s 间隔）。
请求参数：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
SessionId | string | 是 | register/init 返回的会话 ID |
响应 data：
| 字段 | 类型 | 说明 |
|---|---|---|
Status | string | pending / completed / expired / failed |
DeviceId | string | completed 时回显 |
Code | string | completed 时返回的一次性授权码，TTL 5min；不返回 open_id |
3. 换取 open_id
POST /palm/openai/x/agent/code/exchange · 业务方后端（api_key）
业务方用一次性 Code 换取 (device_id, open_id)，再与本地账号绑定，授权至此真正完成。
请求参数：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
Code | string | 是 | Agent 转交的一次性授权码 |
响应 data：
| 字段 | 类型 | 说明 |
|---|---|---|
DeviceId | string | Agent 对外身份 |
OpenId | string | 真人 owner 的 per-app 标识 |
Registered | bool | 是否注册完成 |
Code一次性消费，过期 / 重复兑换返回错误；code.app_id须等于 api_key 对应的oc_appid，否则ErrAgentForbidden。
4. 拉公钥 / 查设备
POST /palm/openai/x/agent/verify/device · 业务方后端（api_key）
按 (device_id, open_id) 拉取公钥，供业务方缓存（TTL ≤15min）后本地验签。推荐方式。
请求参数：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
DeviceId | string | 是 | Agent 对外身份 |
OpenId | string | 否 | 可选但强烈建议：校验该设备确实绑在此人名下 |
响应 data：
| 字段 | 类型 | 说明 |
|---|---|---|
Registered | bool | 是否仍绑定真人（未激活 / 已吊销则 false） |
DeviceId | string | 回显 |
OwnerOpenId | string | 真人 owner，Registered=true 时填 |
PubkeyDer | string | base64(SPKI DER)，缓存用于本地验签 |
CreatedAt | int64 | Agent 注册时间戳（秒） |
吊销延迟 = 缓存 TTL。要更快感知吊销就调短 TTL，或对关键请求改用在线验签。
5. 在线验签
POST /palm/openai/x/agent/verify/signature · 业务方后端（api_key）
把 Agent 的签名整段提交给 Palm 在线校验。Agent 待签名串（canonical）：
"palmauth-agent-req-v1" + "\n" + device_id + "\n" + method + "\n"
+ path + "\n" + sha256_hex(body_bytes) + "\n" + timestamp_ms + "\n" + nonce
请求参数：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
DeviceId | string | 是 | Agent 对外身份 |
PubkeyDer | string | 是 | base64(SPKI DER) |
Message | string | 是 | 待验签明文（canonical 串） |
Signature | string | 是 | base64(64 字节裸签名) |
Timestamp | int64 | 是 | Unix 毫秒，±5min |
Nonce | string | 否 | 防重放随机串 |
响应 data：
| 字段 | 类型 | 说明 |
|---|---|---|
Verified | bool | 签名是否合法（密码学校验） |
Registered | bool | 是否仍绑定真人（DB 状态，独立于 Verified） |
DeviceId | string | 回显 |
OwnerOpenId | string | 真人 owner，Registered=true 时填 |
6. 发起 Step-up
POST /palm/openai/x/agent/stepup/create · 业务方后端（api_key）
请求参数：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
DeviceId | string | 是 | Agent 对外身份 |
ChallengeId | string | 是 | 业务方生成的 UUID v4，幂等键 |
Action | string | 是 | 业务动作标识，如 transfer_money |
ActionDetail | string | 是 | 透传 JSON，≤512B，会展示给真人 |
Level | int32 | 是 | 1=仅异步告知立即放行；2/3=真人刷掌确认 |
NonBlocking | bool | 否 | Level=1 时常为 true |
响应 data：
| 字段 | 类型 | 说明 |
|---|---|---|
ChallengeId | string | 回显 |
ExpiresAt | int64 | 核验过期时间戳（秒） |
Status | string | pending（Level 2/3）/ approved（Level 1） |
AssertionJwt | string | approved 时立即返回（Level 1） |
幂等：同一
ChallengeId重复提交返回已有状态，不创建新核验。
7. 查询 Step-up
POST /palm/openai/x/agent/stepup/query · 业务方后端（api_key）
短轮询核验结果，approved 时一次性返回 Assertion JWT。
请求参数：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
ChallengeId | string | 是 | 发起时的 challenge_id |
响应 data：
| 字段 | 类型 | 说明 |
|---|---|---|
Status | string | pending / approved / denied / expired |
AssertionJwt | string | approved 时一次性返回 |