认证

外脑编辑器 API 支持四种认证方式，所有认证信息通过 Authorization 请求头传递。

源码: apps/backend/src/middleware/combined-auth.ts, apps/backend/src/middleware/api-key-auth.ts, apps/backend/src/middleware/oauth-auth.ts

认证方式总览

方式	Token 格式	适用场景	适用端点
JWT Token	Bearer <supabase-jwt>	前端用户会话	大部分端点
API Key	Bearer wn-xxx	外部 API 调用	/my, /api/released-app/*, ROMP 会话/消息
Schedule Token	Bearer <schedule-jwt>	定时任务内部触发	/api/released-app/*
OAuth Token	Bearer wno-xxx	第三方应用	/api/released-app/*, /oauth/userinfo

1. JWT Token 认证

通过 Supabase Auth 获取的 JWT Token，用于前端用户会话。

使用方式

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  https://block2-api.wainao.chat/my

验证流程

1. 后端优先使用 JWT_SECRET 进行本地验证（快速，无网络请求）
2. 若未配置 JWT_SECRET，降级调用 supabase.auth.getUser() 远程验证
3. 验证通过后，从 JWT payload 中提取 sub（用户 ID）、email、user_metadata 等信息

认证上下文

{
  method: 'jwt',
  userId: string,        // 用户 ID（JWT payload.sub）
  user: {
    id: string,
    email: string,
    role: string,
    user_metadata: object,
    app_metadata: object,
  }
}

错误响应

状态码	错误	说明
401	Missing or invalid authorization header	缺少或格式错误的 Authorization 头
401	Token expired	JWT 已过期
401	Invalid token	无效的 JWT
401	JWT authentication failed	JWT 验证失败

2. API Key 认证

以 wn- 前缀标识的 API Key，用于外部程序调用。

获取 API Key

在项目设置中创建 API Key，系统会生成 wn-xxx 格式的密钥。

使用方式

curl -H "Authorization: Bearer wn-your-api-key" \
  https://block2-api.wainao.chat/api/released-app/DEPLOYMENT_ID/run \
  -d '{"inputs": {"text": "hello"}}'

验证流程

1. 对 API Key 进行 SHA-256 哈希
2. 在 api_keys 表中查找匹配记录
3. 检查 Key 是否已被撤销（deleted_at 或 revoked_at 任一非空即拒绝）
4. 检查 Key 是否已过期（expires_at 非空且早于当前时间即拒绝）
5. 检查额度限制（limit_credits vs usage_credits）
6. 异步更新 last_used_at 时间戳

验证逻辑由 authenticateApiKey() 共享函数统一实现，apiKeyAuth 和 combinedAuth 两个中间件均调用此函数，确保行为一致。

端点白名单

通过 combinedAuth 中间件的 API Key 仅允许访问以下端点：

• /my - 自检端点
• /romp/v1/conversations - ROMP 会话
• /romp/v1/messages - ROMP 消息

通过 apiKeyAuth 中间件的 API Key（/api/released-app/*）无路径限制。

认证上下文

{
  method: 'api-key',
  apiKeyId: string,   // API Key 记录 ID
  teamId: string,     // 所属团队 ID
  userId: string,     // Key 创建者的用户 ID
}

错误响应

状态码	错误	说明
401	Invalid API key	Key 不存在
401	API key has been revoked	Key 已被撤销（deleted_at 或 revoked_at 非空）
401	API key has expired	Key 已过期（expires_at 早于当前时间）
401	Authentication failed	认证过程中发生内部错误
403	API key credit limit exceeded	Key 额度已用尽
403	API key is not allowed for this endpoint	Key 不可访问该端点
429	Too many requests, please try again later	超出限流阈值（per-key 600/min）

3. Schedule Token 认证

系统内部生成的短时 JWT，用于定时任务触发 API 运行。

使用场景

定时任务调度器在触发执行时，自动生成包含 schedule_id、team_id、deployment_id 等信息的短时 JWT。该 Token 仅用于 /api/released-app/* 路径。

认证上下文

{
  method: 'schedule',
  scheduleId: string,     // 定时任务 ID
  teamId: string,         // 所属团队 ID
  userId: string,         // 空字符串（Schedule 无关联用户）
  deploymentId: string,   // 目标部署 ID
}

安全限制

• Schedule Token 会验证请求的 deploymentId 是否与 Token 中声明的一致，防止越权执行

4. OAuth Token 认证

通过 OAuth 2.0 Authorization Code + PKCE 流程获取的 access_token，用于第三方应用。

注意：OAuth Token 认证不通过全局 combinedAuth，而是使用 route-local 的 oauthAuth 中间件，仅挂到明确允许的路由上。

使用方式

curl -H "Authorization: Bearer wno-your-access-token" \
  https://block2-api.wainao.chat/api/released-app/r/my-app/v1/chat/completions

认证上下文

{
  method: 'oauth',
  userId: string,     // 授权用户 ID
  appId: string,      // OAuth App ID
  scopes: string[],   // 授权的 scope 列表
}

Scope 限制

OAuth Token 只能访问 scope 对应的路由。当前支持的 scope：

Scope	允许的路由
chat:completions	/api/released-app/*

访问未授权路由返回 403 insufficient_scope。

获取 Token

详见 OAuth 2.0 API。

安全建议

• 永远不要在客户端代码中暴露 API Key
• 定期轮换 API Key
• 使用环境变量存储密钥
• 为 API Key 设置合理的额度限制
• 第三方应用优先使用 OAuth 2.0 而非直接暴露 API Key