接口鉴权 (Authentication)

当您在 APayShop 中购买了类型为 dynamic_api(动态 API 额度销售)的商品时,系统会自动为您生成一个专属的 API Key。您需要使用该 Key 来调用对应的服务接口。

网页单会话策略

系统设置 disable_multi_device_login 开启后,每个用户只保留最近一次建立的浏览器 Cookie 会话。密码登录、注册、OAuth、Minimal 上游登录和 Qingpu 结账交接均使用 APay 核心的统一会话签发器。

旧网页会话在下一次访问受保护 API 时收到 HTTP 401,其中 data.code = "SESSION_REPLACED"。全局页面也会通过 GET /api/auth/session-status 取得替换通知,展示新登录的设备类型、浏览器、操作系统、UTC 登录时间、IP 和可用的地区快照。

API Token、MCP OAuth/限域令牌(apay_mcp_)、Qingpu 扩展/桌面设备 Token、管理员会话和员工委派会话使用各自独立生命周期,不会被这项仅针对网页的策略撤销。

原生应用独立会话

服务端原生登录入口调用 issueNativeSession,保留现有加密 nuxt-session Cookie 和账号 API。原生会话 90 天有效,独立核对撤销、有效期与账号状态,不更新网页单会话指针。POST /api/auth/logout 只撤销当前原生会话,旧 Cookie 重放会被拒绝。无类型标记的存量 Cookie 继续按网页会话兼容,重新登录后迁入原生会话。

浏览器应用授权使用独立的 10 分钟短期事务。主题通过 beginAppAuthorization 创建事务;密码/注册请求显式携带 X-App-Authorization,Google/GitHub 将事务绑定到独立 OAuth state。认证成功返回 {success,appAuthorization:true,returnPath,user},不建立参与互踢的网页登录。主题先用 consumeAppAuthorization 原子消费授权,再签发 App 回跳 code。待授权事务本身不是账号登录,也不会改变普通网页登录行为。

启用原生会话签发前,先执行核心增量迁移并升级所有鉴权实例。完整接入、发布与回滚说明见 docs/native-app-sessions.zh-CN.md;回归命令为 npm run check:native-sessions。

核心 MCP OAuth 2.1 与限域令牌系统

APay 内置了通用的 Model Context Protocol (MCP) OAuth 2.1 授权体系与 Streamable HTTP 服务端,允许 Claude Desktop、Cursor、Windsurf、VS Code Copilot、WorkBuddy 等 MCP 客户端以最小权限(Scoped Token)完成一键登录授权,替代全权限裸 API Key。

1. OAuth 2.1 与 RFC 9728 / RFC 8414 自动发现

  • 受保护资源元数据 (RFC 9728):GET /.well-known/oauth-protected-resource(含 /.well-known/oauth-protected-resource/api/mcp 子路径)
  • 授权服务器元数据 (RFC 8414):GET /.well-known/oauth-authorization-server
  • 动态客户端注册 (RFC 7591):POST /api/oauth/register(签发带 HMAC 签名、绑定合法 redirect_uris 的自包含 mcp_client_... 标识)
  • 浏览器授权同意页与接口:
    • 授权确认页面:/user/mcp-authorize
    • 授权预检与审批接口:GET /api/oauth/authorize 与 POST /api/oauth/authorize(强制要求 PKCE code_challenge_method=S256)
  • 令牌兑换与刷新轮换:POST /api/oauth/token
    • 支持 grant_type=authorization_code(原子级单次消费授权码 + PKCE S256 校验)与 grant_type=refresh_token(同时轮换新 Refresh Token 与 Access Token)。
  • 令牌吊销 (RFC 7009):POST /api/oauth/revoke

2. 限域 MCP 访问令牌 (apay_mcp_) 与 Scope Gate

  • 入库 SHA-256 哈希:所有 apay_mcp_ 访问令牌、OAuth 授权码及 Refresh Token 在 user_tokens.token 中均以 SHA-256 哈希形态存储(apay_mcp_sha256_<hex> / mcp_oauth_sha256_<hex>),数据库不落明文密钥。
  • 支持的权限域 (Scopes):
    • mcp:tools:允许访问 /api/mcp JSON-RPC 2.0 端点
    • mcp:profile:read:读取账户基础资料(/api/auth/me、/api/users/profile)
    • mcp:orders:read:读取订单列表、支付状态与履约摘要
    • mcp:subscriptions:read:读取当前有效订阅套餐
    • mcp:notifications:read:读取站内通知
    • mcp:tickets:read / mcp:tickets:write:读取或创建/回复售后工单
    • mcp:theme:read / mcp:theme:plan:只读访问主题业务状态或生成助手执行计划(所有确认/执行写接口仍必须在网页端由人工确认)
  • 高危路径硬拒绝 (Hard Deny):无论授予何种 Scope,限域令牌在 server/middleware/auth.ts 均被无条件禁止访问 /api/admin/**、/api/users/tokens、/api/users/password、/api/users/email、/api/users/account-deletion、/api/users/billing、/api/users/wallet、/api/orders/checkout、/api/orders/topup、/api/payments/**、/api/qingpu/stores 及 /api/qingpu/device-tokens。
  • 手动签发与管理:用户也可在 /user/tokens 页面手动创建、查看与吊销带 Scope 的 apay_mcp_ 令牌(GET/POST /api/users/tokens、DELETE /api/users/tokens/:id),页面内置 Claude Desktop / Cursor / Windsurf 的 mcpServers JSON 配置一键复制。
  • 管理员紧急吊销:管理员可通过 POST /api/admin/users/:id/revoke-tokens 一键吊销指定用户名下的全部 API / MCP 令牌并清除关联 Refresh Token。

3. 核心 MCP 服务端点 (/api/mcp)

  • 端点地址:POST /api/mcp(Streamable HTTP JSON-RPC 2.0)
  • 鉴权要求:强制要求 Authorization: Bearer <token> 或 X-Api-Key: <token>。仅携带浏览器 Cookie 的请求会被拒绝并返回 401 与 WWW-Authenticate: Bearer resource_metadata="..." 响应头,从而消除跨站页面通过 Cookie 对 MCP 工具执行端点的 CSRF 攻击面。
  • 内置核心工具:
    • apay_get_profile / apay_get_account_profile (mcp:profile:read)
    • apay_list_products (mcp:tools)
    • apay_list_orders / apay_get_order_detail (mcp:orders:read)
    • apay_list_subscriptions (mcp:subscriptions:read)
    • apay_list_notifications (mcp:notifications:read)
    • apay_list_tickets / apay_get_ticket_detail (mcp:tickets:read)
    • apay_create_ticket / apay_reply_ticket (mcp:tickets:write)
    • 主题模块可通过 server/utils/mcpServer.ts 的 registerMcpTool() 注册扩展工具。

账户注销申请与永久封存机制

APay 核心内置了完整的「用户提交申请 -> 后台管理员审核 -> 永久封存禁登」账户生命周期能力(account_deletion_requests 表 + users.status = -1),在不破坏订单、充值与审计外键完整性的前提下永久终止账户登录权限。

  • 用户侧接口(仅允许主账号网页登录会话调用,禁止 API/MCP 令牌与员工委派会话调用):
    • GET /api/users/account-deletion:获取当前账户状态、密码/第三方验证模式、资产预检指标(可用余额、生效中订阅数、历史已付订单数)、待审申请及历史记录。
    • POST /api/users/account-deletion:核验当前登录密码(纯第三方登录账号核验完整绑定邮箱 confirmEmail)后提交待审核注销申请,自动留存申请时刻的资产与环境快照。
    • POST /api/users/account-deletion/cancel:在管理员审核前撤回处于 pending 状态的注销申请。
    • 核心页面与可复用组件:/user/account(<AccountDeletionPanel /> 与 useAccountDeletion())。
  • 管理后台审核与直接封存接口(受 customers:view / customers:edit 权限保护并写入操作审计日志):
    • GET /api/admin/users/deletion-requests:分页查询注销申请记录,支持按状态与关键词筛选并返回全局各状态汇总计数。
    • POST /api/admin/users/deletion-requests/:id/review:审核待处理申请,支持批准封存(action = "approve")或驳回(action = "reject",自动向用户下发站内通知说明原因)。
    • DELETE /api/admin/users/:id:管理员直接对指定客户执行无外键冲突的封存删除。
  • 永久封存与全链路禁登(users.status = -1):
    • 审核通过或直接封存后,users.status 置为 -1、清空 currentSessionId、吊销全部活跃 user_sessions(网页、原生客户端、App 授权事务)、清除一次性与 OAuth 刷新令牌、吊销全部个人 API/MCP/设备令牌、将生效中订阅标记为期末不续订(cancelAtPeriodEnd = true),并广播 user.deleted 事件。
    • 封存账户在全局鉴权中间件、原生会话校验、Bearer 令牌、密码登录、第三方 OAuth 登录与绑定、找回密码、find-or-create 及同邮箱重新注册入口均会被拦截并返回 ACCOUNT_ARCHIVED。

鉴权方式

APayShop 采用标准的 HTTP Authorization 头部进行鉴权。在发送 API 请求时,请将您的 API Key 作为 Bearer Token 放入请求头中。

格式要求

请求头名称: Authorization 请求头内容: Bearer 您的_API_KEY

示例请求

以下是一个使用 cURL 发送带鉴权请求的示例:

curl -X GET https://yourdomain.com/api/v1/some-service \
  -H "Authorization: Bearer sk_test_1234567890abcdef" \
  -H "Content-Type: application/json"

如何获取 API Key?

  1. 在前台商店购买 dynamic_api 类型的商品并完成支付。
  2. 支付成功后,前往 "Order History" (订单历史) 页面。
  3. 点击对应订单的详情,您将直接在履约结果(Fulfillment Result)区域看到系统为您分配的 API Key 以及可用额度。

⚠️ 安全警告

请将您的 API Key 视为密码一样妥善保管。绝对不要将其硬编码在客户端代码(如浏览器端 JS、移动端 App)中,也不要提交到公开的 GitHub 仓库。如果您的密钥泄露,请立即联系管理员在后台将其作废并重新生成。

额度消耗机制

每次使用有效的 API Key 成功调用计费接口时,系统会自动从您的可用额度(Quota)中扣除相应的值。 当额度耗尽后,API 将拒绝服务并返回 402 Payment Required 或 403 Forbidden 状态码。您可以再次购买该商品来补充额度。