magicrew-auth 0.3.26 → 0.3.29

package/src/captcha.mjs

@@ -1,17 +1,32 @@
-// 无头登录的底层：旋转验证码 + 手机验证码换取登录态
+// 无头登录的底层：旋转验证码 + 手机/邮箱验证码换取登录态
 //
 // 全部是**纯 HTTP**，不开浏览器、不读 localStorage。协议是从网页版
-// `SMSVerificationCodeForm` chunk 里逆出来的，每一步都实测过
+// `SMSVerificationCodeForm` / `LoginCoreForm` chunk 里逆出来的，每一步都实测过
 // （见 docs/internals.md「无头登录」一节）：
 //
-//   ① POST /captcha/generate   { account_type, mobile, state_code }
+//   ① POST /captcha/generate   { account_type, mobile, state_code }      手机
+//                              { account_type, email }                   邮箱
 //        → { token, image(data:image/webp;base64,…), expire_time }
 //   ② 算角度 → angle = enc(deg, n)
 //   ③ POST /captcha/verify     { token, angle, account_type, mobile, state_code }
+//                              { token, angle, account_type, email }
 //        → { verified: true, business_token: "biz_…" }
-//   ④ POST /v4/user/send-sms   { type, phone, state_code }
-//        + header `X-Captcha-Token: <business_token>`
-//   ⑤ POST /v4/user/login      { type: "phone_captcha", phone, state_code, code, device }
+//   ④ 发验证码（两条路**是两个端点**，别混）：
+//        手机 POST /v4/user/send-sms     { type, phone, state_code }
+//        邮箱 POST /v4/user/send-email   { email, type }
+//        + header `X-Captcha-Token: <business_token>`，type 都是 "account_login"
+//   ⑤ 换登录态（同样是两个端点）：
+//        手机 POST /v4/user/login        { type:"phone_captcha", phone, state_code, code, device }
+//        邮箱 POST /v4/user/login-email  { email, captcha, device }
+//
+// ⚠ 邮箱那条为什么走 `/v4/user/login-email` 而不是 `/v4/user/login`：
+//   实测（2026-10-28，两站）——往 `/v4/user/login` 发任何 type（email / email_captcha
+//   / email_code）都回 2000「phone 字段是必须的」，服务端根本不认邮箱。
+//   前端 `UserApi` 里也是两条独立方法：`loginByEmail()` → `/v4/user/login-email`，
+//   并且它显式 `delete("organization-code")`。
+//
+// ⚠ 邮箱那条的**验证码字段名是 `captcha`，不是 `code`** —— 实测发 `code` 回
+//   2000「captcha 字段是必须的」；发 `captcha` 回 2168「验证码错误」。
 //
 // ⚠ 三个域名各管一段，别混：
 //     www.<站点>            → 前端页面（只用来取 Origin，别的没用）
@@ -23,6 +38,34 @@
 //      · 「验证不存在或已过期」 expire_time 给 10 分钟
 //      · 「验证提交过于频繁」  连续批量提交会被拦
 //   ⇒ 不能枚举角度，一次要算准；失败就换图重来。
+//
+// ═══════════════════════════════════════════════════════════════════════
+// 那张旋转图到底能不能绕开（2026-10-29 逐条实测，别再来一遍）
+// ═══════════════════════════════════════════════════════════════════════
+//
+// 结论：**只有「这个号已注册」这一条免费通道**，其余一律必须看懂图。
+//
+// ① 已注册的号 —— 服务端**不出图**：`/captcha/generate` 直接回 `business_token`。
+//      实测：已注册邮箱 → business_token；没注册过的邮箱 → token + image。
+//      ⇒ 「把我已有的账号加进 magpie」根本不需要识图模型（见 headless.mjs 里
+//        startCodeLogin 的「先取图、再判模型」顺序）。
+//
+// ② 新号的答案**不在前端**，也不在图里：
+//      · 前端提交的 `angle` 就是**用户拖动的角度**（`verify(r)` → 这个文件里的
+//        encodeAngle），前端不知道正确答案 —— 知道的话就不会让你拖了；
+//      · 图里没有任何元数据：解剖 webp 只有 `VP8X` / `ALPH` / `VP8` 三个 chunk，
+//        没有 EXIF / XMP / ICC / 自定义块，字符串扫描也是空的；
+//      · 服务端强制：`verify` 不传 angle → 「angle 字段是必须的」；乱填 →
+//        「验证失败，请重试」；发码不带 `X-Captcha-Token`（哪怕带上账号自己的 JWT
+//        和 organization-code）→ 「需要验证码验证」。
+//      ⇒ 答案 = 服务端生成图时随机定的角度，存在它自己的会话里（10 分钟过期）。
+//        要过它只有两条路：识图模型，或人眼看。
+//
+// ③ 不经过验证码的登录入口只有两条，都不是邮箱验证码的替代品：
+//      · 手机号 + 密码 → `POST /api/v1/sessions {type:"phone_password"}`
+//      · 本机浏览器里已登录 → 读它的 localStorage（见 local-browser.mjs）
+//      邮箱 + 密码（`type:"email_password"`）端点认这个 type，但要账号**事先设过
+//      密码** —— 实测对一个已注册邮箱回 `33002 账号不存在`，不能当通用路。
 
 /** 服务端只认这一套 Unicode；错误码直接用数字，日志里好 grep */
 export const CAPTCHA_CODE = {
@@ -44,6 +87,33 @@ export function keewoodOf(site) {
   return site.id === "magicrew" ? "https://i-keewood-service.teamshare.cn" : "https://keewood-service.magicrew.ai"
 }
 
+/**
+ * 「这条链路在给谁发验证码」→ 服务端要的那几个字段。
+ *
+ * 手机和邮箱走的是**同一套 captcha 协议**，只有三处不同，全收敛在这里：
+ *   ① 标识字段：`mobile` + `state_code` vs `email`
+ *   ② `account_type`：`"mobile"` vs `"email"`
+ *   ③ 端点：`/v4/user/send-sms` + `/v4/user/login` vs
+ *      `/v4/user/send-email` + `/v4/user/login-email`
+ *
+ * ⚠ 邮箱**不带 `state_code`** —— 前端邮箱表单的初始值里就没有这个字段
+ *   （实测抓到的请求体逐字符是 `{"account_type":"email","email":"…"}`）。
+ *
+ * @param {{mobile?:string, stateCode?:string, email?:string}} ident
+ * @returns {{account_type:"mobile"|"email", mobile?:string, state_code?:string, email?:string}}
+ */
+export function identFields(ident = {}) {
+  const email = String(ident?.email ?? "").trim()
+  if (email) return { account_type: "email", email }
+  const mobile = String(ident?.mobile ?? "").replace(/[\s-]/g, "")
+  return { account_type: "mobile", mobile, state_code: ident?.stateCode || "+86" }
+}
+
+/** 这条链路是手机还是邮箱 —— 决定走哪两个端点 */
+export function identKind(ident = {}) {
+  return String(ident?.email ?? "").trim() ? "email" : "mobile"
+}
+
 /**
  * 拖动角度 → 服务端要的 angle 字符串。
  *
@@ -109,14 +179,12 @@ async function postJSON(url, body, { headers = {}, timeoutMs = 20_000 } = {}) {
   return { status: res.status, text, json }
 }
 
-/** ① 取图。返回 null 表示服务端认为这个号**已经注册**，直接给了 business_token（跳过验证） */
-export async function generateCaptcha(site, { mobile, stateCode = "+86" } = {}) {
+/** ① 取图。服务端认为这个号**已经注册**时直接给 business_token（跳过验证） */
+export async function generateCaptcha(site, ident = {}) {
   const host = keewoodOf(site)
-  const { json } = await postJSON(`${host}/captcha/generate`, {
-    account_type: "mobile",
-    mobile,
-    state_code: stateCode,
-  }, { headers: { origin: site.web } })
+  const { json } = await postJSON(`${host}/captcha/generate`, identFields(ident), {
+    headers: { origin: site.web },
+  })
 
   const data = json?.data ?? {}
   if (data.business_token) return { registered: true, businessToken: data.business_token }
@@ -131,16 +199,14 @@ export async function generateCaptcha(site, { mobile, stateCode = "+86" } = {})
   }
 }
 
-/** ③ 提交角度 */
-export async function verifyCaptcha(site, { token, deg, mobile, stateCode = "+86" }) {
+/** ③ 提交角度（手机 / 邮箱同一套，标识字段由 identFields 决定） */
+export async function verifyCaptcha(site, { token, deg, ...ident }) {
   const host = keewoodOf(site)
   const n = randomN()
   const { json } = await postJSON(`${host}/captcha/verify`, {
-    account_type: "mobile",
     token,
     angle: encodeAngle(deg, n),
-    mobile,
-    state_code: stateCode,
+    ...identFields(ident),
   }, { headers: { origin: site.web } })
 
   const data = json?.data ?? {}
@@ -149,28 +215,42 @@ export async function verifyCaptcha(site, { token, deg, mobile, stateCode = "+86
 }
 
 /**
- * ④ 发短信。businessToken 缺了/假的都会被打回来，所以它必须是真的。
+ * ④ 发验证码。businessToken 缺了/假的都会被打回来，所以它必须是真的。
  *
  * ⚠ `type` 是 **`"account_login"`**，不是 `"login"`、也不是登录枚举里的 `phone_captcha`。
  *   填错的表现是「服务异常，请联系管理员」(9999) —— 后端内部炸了，不是参数校验失败，
  *   所以从错误信息上完全看不出是 type 的问题。这个值是从浏览器真实请求里抓到的：
- *     {"type":"account_login","phone":"199…","state_code":"+86"}
- *   ⇒ 别再按直觉改它。
+ *     手机 {"type":"account_login","phone":"199…","state_code":"+86"}
+ *     邮箱 {"email":"…","type":"account_login"}
+ *   ⇒ 别再按直觉改它。两站实测：邮箱发 `type:"login"` 同样回 2000「服务异常」。
+ *
+ * ⚠ 邮箱和手机是**两个端点**：`/v4/user/send-email` vs `/v4/user/send-sms`。
+ *   把邮箱发去 send-sms 会 404（`/v4/user/send-sms` 只认 phone）。
  */
-export async function sendSms(site, { phone, stateCode = "+86", businessToken, type = "account_login" }) {
+export async function sendCode(site, ident = {}, { businessToken, type = "account_login" } = {}) {
   const host = keewoodOf(site)
-  const { json } = await postJSON(`${host}/v4/user/send-sms`, {
-    type,
-    phone,
-    state_code: stateCode,
-  }, { headers: { origin: site.web, "X-Captcha-Token": businessToken || "" } })
+  const f = identFields(ident)
+  const isEmail = f.account_type === "email"
+  const path = isEmail ? "/v4/user/send-email" : "/v4/user/send-sms"
+  const body = isEmail
+    ? { email: f.email, type }
+    : { type, phone: f.mobile, state_code: f.state_code }
+
+  const { json } = await postJSON(`${host}${path}`, body, {
+    headers: { origin: site.web, "X-Captcha-Token": businessToken || "" },
+  })
 
   if (json?.code === CAPTCHA_CODE.OK) return { ok: true }
-  return { ok: false, message: json?.message ?? "发送短信失败" }
+  return { ok: false, message: json?.message ?? "发送验证码失败" }
+}
+
+/** 旧签名兼容：手机号发短信 */
+export async function sendSms(site, { phone, stateCode = "+86", businessToken, type = "account_login" }) {
+  return sendCode(site, { mobile: phone, stateCode }, { businessToken, type })
 }
 
 /**
- * ⑤ 验证码换登录态。
+ * ⑤ 验证码换登录态（手机 / 邮箱两个端点）。
  *
  * ⚠ `device` 是必须的，而且结构是一层层试出来的：
  *     缺 device        → 「系统异常」(9999)
@@ -179,7 +259,7 @@ export async function sendSms(site, { phone, stateCode = "+86", businessToken, t
  *     { id, name }     → 放行，返回 2168「验证码错误」
  *   ⇒ { id: 64 位 hex, name: "web" } 就够。
  *
- * ⚠ `auto_register` / `redirect` 一个都不能省（这是网页表单的初始值，抠出来的）：
+ * ⚠ 手机那条的 `auto_register` / `redirect` 一个都不能省（这是网页表单的初始值，抠出来的）：
  *
  *     { phone, state_code, code, auto_register: true,
  *       type: "phone_captcha", redirect: window.location.href }
@@ -188,29 +268,52 @@ export async function sendSms(site, { phone, stateCode = "+86", businessToken, t
  *   · `redirect` 是**当前页面的 URL**，服务端从它上面取 `?invitation=<码>`。
  *     ⇒ **邀请码是靠 redirect 传的，不是独立字段**。这就是为什么浏览器登录的
  *       URL 必须带 `?invitation=`：不带，新注册的号就没有邀请关系。
+ *
+ * ⚠ 邮箱那条**验证码字段叫 `captcha`，不叫 `code`**（实测：发 code 回
+ *   2000「captcha 字段是必须的」；发 captcha 回 2168「验证码错误」）。
+ *   端点也不同：`/v4/user/login-email`，前端调它时会先 `delete("organization-code")`。
+ *   `auto_register` / `redirect` 前端没传，但我们**照传** —— 实测多这两个字段
+ *   服务端不报错（仍回 2168），而新号注册和邀请码都指着它们。
  */
-export async function loginBySmsCode(
+export async function loginByCode(
   site,
-  { phone, stateCode = "+86", code, device, autoRegister = true, redirect },
+  { code, device, autoRegister = true, redirect, ...ident },
 ) {
   const host = keewoodOf(site)
-  const body = {
-    type: "phone_captcha",
-    phone,
-    state_code: stateCode,
-    code,
-    auto_register: autoRegister,
-    device: device ?? { id: makeDeviceId(), name: "web" },
-  }
+  const f = identFields(ident)
+  const isEmail = f.account_type === "email"
+
+  const body = isEmail
+    ? {
+        email: f.email,
+        captcha: code,
+        auto_register: autoRegister,
+        device: device ?? { id: makeDeviceId(), name: "web" },
+      }
+    : {
+        type: "phone_captcha",
+        phone: f.mobile,
+        state_code: f.state_code,
+        code,
+        auto_register: autoRegister,
+        device: device ?? { id: makeDeviceId(), name: "web" },
+      }
   if (redirect) body.redirect = redirect
 
-  const { json, status, text } = await postJSON(`${host}/v4/user/login`, body, {
-    headers: { origin: site.web },
-  })
+  const { json, status, text } = await postJSON(
+    `${host}${isEmail ? "/v4/user/login-email" : "/v4/user/login"}`,
+    body,
+    { headers: { origin: site.web } },
+  )
 
   return { json, status, text }
 }
 
+/** 旧签名兼容：手机号验证码换登录态 */
+export async function loginBySmsCode(site, { phone, stateCode = "+86", ...rest }) {
+  return loginByCode(site, { mobile: phone, stateCode, ...rest })
+}
+
 /** 64 位 hex，形状与网页版 cus.device_id 一致 */
 export function makeDeviceId() {
   const bytes = new Uint8Array(32)

package/src/headless.mjs

@@ -1,8 +1,12 @@
 // 无头登录的编排：一条纯 HTTP 的链路，不开浏览器
 //
-//   取图 → 识图判角度 → 过验证 → 发短信 → （用户填码）→ 换登录态 → 拿组织码
+//   取图 → 识图判角度 → 过验证 → 发验证码 → （用户填码）→ 换登录态 → 拿组织码
 //
-// 每一步都实测过（见 docs/internals.md「无头登录」）：
+// **手机号和邮箱走同一条编排** —— 协议、风控、识图全一样，只有「标识字段」
+// 和「发码 / 登录两个端点」不同，那些差异全在 captcha.mjs 里按 identFields 分派。
+//
+// 每一步都实测过（协议逐字段记在 src/captcha.mjs 头部；两站实测记录见
+// CHANGELOG 0.3.17「手机号验证码」与 0.3.28「邮箱验证码 + 已有账号免图」）：
 //   · 取图/过验证在 keewood 用户中心，纯 JSON，不需要 cookie 或指纹
 //   · 角度必须「一次算准」：同一 token 试错次数有限，且高频会被拦
 //   · 识图模型是用户在 magpie 里选的那个（settings.json 的 vision）
@@ -14,8 +18,9 @@
 import {
   extractCreds,
   generateCaptcha,
-  loginBySmsCode,
-  sendSms,
+  identKind,
+  loginByCode,
+  sendCode,
   verifyCaptcha,
 } from "./captcha.mjs"
 import { decideDegFromImage, readVisionModel } from "./vision.mjs"
@@ -30,14 +35,20 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
 /**
  * 过掉旋转验证，拿到 business_token。
  *
+ * 手机和邮箱共用：只有传给服务端的「标识字段」不同（`{mobile, stateCode}` / `{email}`）。
+ *
+ * @param {object} site  站点对象（要有 id / web）
+ * @param {{mobile?:string, stateCode?:string, email?:string}} ident
+ * @param {object|null} firstCap 已经取到的那张图（调用方为了让「已注册免图」
+ *   这条短路先跑，会自己先调一次 generateCaptcha）—— 传进来就省一次取图
  * @returns {Promise<{businessToken:string, rounds:number, log:string[]}>}
  */
-export async function passCaptcha(site, { mobile, stateCode = "+86" } = {}) {
+export async function passCaptcha(site, ident = {}, firstCap = null) {
   const log = []
   let lastReason = ""
 
   for (let round = 1; round <= MAX_CAPTCHA_ROUNDS; round++) {
-    const cap = await generateCaptcha(site, { mobile, stateCode })
+    const cap = round === 1 && firstCap ? firstCap : await generateCaptcha(site, ident)
     // 已注册的号，服务端直接给 business_token，连图都不用看
     if (cap.registered) {
       log.push(`第 ${round} 轮：服务端直接放行（该号已注册）`)
@@ -53,7 +64,7 @@ export async function passCaptcha(site, { mobile, stateCode = "+86" } = {}) {
       continue
     }
 
-    const res = await verifyCaptcha(site, { token: cap.token, deg: decided.deg, mobile, stateCode })
+    const res = await verifyCaptcha(site, { token: cap.token, deg: decided.deg, ...ident })
     if (res.ok) {
       log.push(`第 ${round} 轮：deg=${decided.deg}（钟点 ${decided.clock?.toFixed?.(2) ?? "?"}，分歧 ${decided.spread?.toFixed?.(1) ?? 0}）→ 通过`)
       return { businessToken: res.businessToken, rounds: round, log }
@@ -71,45 +82,79 @@ export async function passCaptcha(site, { mobile, stateCode = "+86" } = {}) {
 }
 
 /**
- * 第 1 步：发短信。成功即代表「验证已经过了」——服务端把 business_token 当门票。
+ * 第 1 步：发验证码（短信 / 邮件）。成功即代表「验证已经过了」——服务端把 business_token 当门票。
+ *
+ * ⚠ **顺序很重要：先取图，再决定要不要识图模型。**
+ *
+ *   服务端对**已注册**的号根本不要求过旋转验证 —— `POST /captcha/generate` 直接回
+ *   `business_token`，连图都不给（实测：2026-10-29，已注册邮箱 `…@qq.com` → 免图；
+ *   同一个接口换一个没注册过的邮箱 → 给了 token+image）。
+ *
+ *   所以「加一个我自己已有的账号」这条最常见的路，**根本不需要识图模型**。
+ *   早先把 `readVisionModel()` 的判断放在取图**之前**，等于让没配识图模型的人
+ *   连自己已有的账号都加不进来 —— 那是白拦。现在只有确实要给新号过图时才要求它。
+ *
+ * @throws 需要过图但没配识图模型时，抛带 `code: "no-vision-model"` 的错误，
+ *         让调用方去回退浏览器（而不是在这里瞎猜角度）
  */
-export async function startSmsLogin(site, { mobile, stateCode = "+86" } = {}) {
-  if (!readVisionModel()) {
-    // 调用方应该先判断这个；走到这里说明判断被绕过了 —— 明确报出来，别静默瞎猜
-    throw Object.assign(new Error("没有配置识图模型，不能无头过旋转验证"), { code: "no-vision-model" })
+export async function startCodeLogin(site, ident = {}) {
+  const kind = identKind(ident)
+  const what = kind === "email" ? "邮件" : "短信"
+
+  // ① 先探一次。这一步是纯 JSON、不需要模型，也**不会真的发码**。
+  const first = await generateCaptcha(site, ident)
+
+  let businessToken
+  let rounds
+  let log
+
+  if (first.registered) {
+    // ⚡ 已注册 → 免图直接发码。识图模型在这条路上完全用不到。
+    businessToken = first.businessToken
+    rounds = 0
+    log = ["服务端认为该号已注册 → 免旋转验证"]
+  } else {
+    // ② 新号必须过图：这时才需要识图模型
+    if (!readVisionModel()) {
+      throw Object.assign(new Error("这个号还没注册，注册要过旋转验证，而你没配识图模型"), {
+        code: "no-vision-model",
+      })
+    }
+    const r = await passCaptcha(site, ident, first)
+    businessToken = r.businessToken
+    rounds = r.rounds
+    log = r.log
   }
 
-  const { businessToken, rounds, log } = await passCaptcha(site, { mobile, stateCode })
-  const sms = await sendSms(site, { phone: mobile, stateCode, businessToken })
-  if (!sms.ok) {
-    throw Object.assign(new Error(`发短信失败：${sms.message}`), { captchaLog: log })
+  const sent = await sendCode(site, ident, { businessToken })
+  if (!sent.ok) {
+    throw Object.assign(new Error(`发${what}失败：${sent.message}`), { captchaLog: log })
   }
-  return { businessToken, rounds, log }
+  return { businessToken, rounds, log, skippedCaptcha: Boolean(first.registered) }
+}
+
+/** 旧签名兼容：手机号发短信 */
+export async function startSmsLogin(site, { mobile, stateCode = "+86" } = {}) {
+  return startCodeLogin(site, { mobile, stateCode })
 }
 
 /**
  * 第 2 步：验证码换登录态，并补齐组织码。
  *
- * ⚠ 登录响应里 jwt / 组织码的**确切形状没实测过**（手上没有能收短信的号，
- *   只能验到 2168「验证码错误」）。所以：
+ * ⚠ 登录响应里 jwt / 组织码的**确切形状没实测过**（手上没有能收短信/收信的号，
+ *   只能验到 2168「验证码错误」——手机和邮箱都一样）。所以：
  *     · jwt 用 extractCreds 从响应里按特征找（以 eyJ 开头的三段式）
  *     · 组织码找不着就调 `/api/v1/aggregation/login-data`（带 authorization 头，
  *       服务端会回这个账号所在的组织列表）—— 这条路径是文档里查得到的
  */
-export async function finishSmsLogin(site, { mobile, stateCode = "+86", code, device, redirect }) {
-  const { json, status, text } = await loginBySmsCode(site, {
-    phone: mobile,
-    stateCode,
-    code,
-    device,
-    autoRegister: true,
-    redirect,
-  })
+export async function finishCodeLogin(site, { code, device, redirect, ...ident } = {}) {
+  const { json, status, text } = await loginByCode(site, { code, device, redirect, ...ident })
   if (!json) {
     throw new Error(`登录接口回了非 JSON（HTTP ${status}）：${String(text).slice(0, 200)}`)
   }
   if (json.code !== 1000) {
-    // 2168 是验证码错；其余原样透出，别把它吞成「登录失败」
+    // 2168（手机 / 邮箱都是它）= 验证码错；2167 = 短信验证码无效或已过期；
+    // 其余原样透出，别把它吞成「登录失败」
     throw Object.assign(new Error(`登录失败：${json.message ?? json.code}`), {
       code: json.code,
       raw: json,
@@ -140,6 +185,11 @@ export async function finishSmsLogin(site, { mobile, stateCode = "+86", code, de
   return { jwt, org: orgs[0], orgs, raw: json }
 }
 
+/** 旧签名兼容：手机号验证码换登录态 */
+export async function finishSmsLogin(site, { mobile, stateCode = "+86", ...rest } = {}) {
+  return finishCodeLogin(site, { mobile, stateCode, ...rest })
+}
+
 /**
  * 把一段 JSON 的形状描述出来：**只有键名和类型，没有任何值**。
  *