CurrentStation 通行证

一套账号，登录所有 Current 系产品。第三方应用全程拿不到用户密码：用户在我们的页面上授权， 应用只拿到一个只能读取被授权信息的令牌。 Issuer https://music.20110208.xyz/cm

1. 角色与流程

用户          应用（你的产品）             CurrentStation 通行证
 │                  │                              │
 │  点击「用通行证登录」                            │
 │─────────────────▶│  302 /passport/authorize     │
 │                  │  ?client_id&redirect_uri     │
 │                  │  &scope&state&code_challenge │
 │                  │─────────────────────────────▶│  未登录？先在本站登录
 │◀─────────────────────────────────────────────── │  展示同意页（应用名 + 申请的权限）
 │  点「同意」       │                              │
 │───────────────────────────────────────────────▶ │  生成一次性 code（60 秒）
 │                  │◀── 302 redirect_uri?code=…&state=… ─┘
 │                  │  POST /passport/token         │
 │                  │  code + code_verifier         │
 │                  │─────────────────────────────▶│  校验 PKCE → 发 access_token
 │                  │◀── {access_token, refresh_token?, sub} ─┘
 │                  │  GET /passport/userinfo       │
 │                  │  Authorization: Bearer …      │
 │                  │─────────────────────────────▶│  按 scope 返回昵称/头像/脱敏邮箱…

2. 快速开始（4 步）

1. 登记应用（一次性，需要 CurrentStation 管理员账号）

   用管理员登录后的会话令牌调用；返回的 clientSecret 只显示这一次，请立刻存到服务端环境变量里。原生 App / 纯前端 SPA 请用 "public": true（不发密钥，强制 PKCE）。

   curl -X POST https://music.20110208.xyz/cm/passport/apps \
     -H "Authorization: Bearer <管理员会话令牌>" -H "Content-Type: application/json" \
     -d '{"name":"CurrentSpace","redirects":["https://app.example.com/auth/callback"],
          "scopes":"openid profile email offline_access","homepage":"https://app.example.com"}'
   
   # 201
   # { "clientId": "cs_app_1a2b3c4d5e6f", "clientSecret": "cs_sk_…", … }

2. 把用户送到授权页

   生成 PKCE：verifier 为 43~128 位随机串，challenge = BASE64URL(SHA256(verifier))（去掉 =）。state 用于防 CSRF，回调时要原样校验。

   # verifier / challenge 生成（浏览器 WebCrypto，Node 18+ 亦可）
   const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
   const challenge = base64url(new Uint8Array(
     await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier))));
   
   location.href = 'https://music.20110208.xyz/cm/passport/authorize'
     + '?response_type=code'
     + '&client_id=cs_app_1a2b3c4d5e6f'
     + '&redirect_uri=' + encodeURIComponent('https://app.example.com/auth/callback')
     + '&scope=' + encodeURIComponent('openid profile email offline_access')
     + '&state=' + state
     + '&code_challenge=' + challenge + '&code_challenge_method=S256';

3. 用 code 换令牌

   code 只能用一次、60 秒过期；换令牌时 redirect_uri 必须与授权时完全一致。有密钥的客户端用 Basic 认证，公开客户端只传 code_verifier。

   curl -X POST https://music.20110208.xyz/cm/passport/token \
     -H "Content-Type: application/json" \
     -d '{"grant_type":"authorization_code","client_id":"cs_app_1a2b3c4d5e6f",
          "client_secret":"cs_sk_…","code":"cs_code_…","redirect_uri":"https://app.example.com/auth/callback",
          "code_verifier":"<PKCE verifier>"}'
   
   # 200
   # { "access_token":"cs_at_…", "token_type":"Bearer", "expires_in":7200,
   #   "scope":"openid profile email offline_access", "refresh_token":"cs_rt_…",
   #   "sub":"cs_1a2b3c4d5e6f" }

4. 拿用户信息

   curl https://music.20110208.xyz/cm/passport/userinfo -H "Authorization: Bearer cs_at_…"
   
   # 200
   # { "sub":"cs_1a2b3c4d5e6f", "nickname":"小明", "avatar":"https://…",
   #   "email":"m***@qq.com", "scope":"openid profile email offline_access",
   #   "client_id":"cs_app_1a2b3c4d5e6f" }

3. 端点

开发者平台页面：GET /developer（也支持 /cm/developer，独立于音乐客户端）。

账号本体（注册、登录、退出、在线设备）仍在 /cm/auth/*，与通行证共用同一批账号；现有 App 与网页无需改动。

4. scope

申请未登记或超出应用上限的 scope 会得到 invalid_scope；用户看到的是每个 scope 的中文说明（同意页）。

5. 令牌与有效期

刷新

curl -X POST https://music.20110208.xyz/cm/passport/token -H "Content-Type: application/json" \
  -d '{"grant_type":"refresh_token","client_id":"cs_app_…","client_secret":"cs_sk_…",
       "refresh_token":"cs_rt_…"}'

服务端到服务端（client_credentials）

只代表「应用自己」，没有用户信息；/userinfo 会对这类令牌返回 403。

curl -u "cs_app_…:cs_sk_…" -X POST https://music.20110208.xyz/cm/passport/token \
  -H "Content-Type: application/json" -d '{"grant_type":"client_credentials","scope":"openid"}'

6. 错误码

7. 安全约定

• 回调地址精确匹配：不做通配与子路径放行，非 https（本机调试除外）一律拒绝 —— 从根上堵住开放重定向。
• PKCE 必备：公开客户端（App、SPA）强制 code_challenge；机密客户端的密钥只放服务端。
• 令牌只存哈希：数据库被读走也拿不到可用令牌；授权码取用即删。
• 单点登出：用户在任意产品里退出，会连带撤销该会话发出的全部通行证授权。
• 用户可随时收回：App 内「设置 → 通行证授权」列出已授权应用，一键解除；管理员审计流水保留每次授权/换令牌/撤销。
• 限流与审计：令牌端点按「客户端 + IP」滑动窗口限流，异常（密钥错误、换令牌失败）全部留痕。

8. CurrentDeveloper 开发者平台（自助接入）

9. 已接入产品

10. 变更记录