magicrew-auth 0.3.28 → 0.3.29

package/AGENTS.md

@@ -54,7 +54,7 @@ curl -s "https://usemagpie.ai/api/latest?channel=stable" | grep -o '"version":"[
 | 1 | 改好了国内站，国际站用户报同样的错 | **两站是同一个 Go 服务、逐字符同构**，改一处就要两站都验；`SITES.cn` / `SITES.intl` 只是 host 不同 | internals 一 |
 | 2 | 国际站 `/v1/chat/completions` 回 `HTTP 500` + 22 字节裸文本（不是 JSON） | 国际站网关**强制**要 `organization-code` 头，缺了就是这个 500 | internals 一 / 五 |
 | 3 | 换了 key 之后老 key 立刻失效、用户被要求重登 | **「签新 key 会吊销旧 key」已被实测推翻（2026-10-28）** —— 见下方「最容易误信的旧说法」。仍然只留一把、只走 `src/keys.mjs` 的唯一出口，理由是**本地别分叉**，不是互相吊销 | internals 十四 |
-| 4 | 刷新 token 之后两处 refresh_token 不一致、用户莫名掉登录 | 只允许**一个**出口持有 refresh_token；`src/hooks/refresh.mjs` 绕过出口就会分叉 | internals 二 / 十四 |
+| 4 | 刷新 token 之后两处 refresh_token 不一致、用户莫名掉登录 | 只允许**一个**出口持有 refresh_token；`src/hooks/refresh.mjs` 必须走 `keys.mjs` 的 `renewViaStore()`（0.3.29 起已收敛，与 `ensureKey` 共用 `renewOnce` 锁和同一个 key-store）。若改回自调 `refreshGatewayKey` 就会分叉 | internals 二 / 十四 |
 | 5 | agent 说「上下文放不下」，而实际模型能吃更长 | 上下文窗口**必须查 magpie 的模型库**，不能填保守值（早前一刀切 256K，实际 1M） | internals 十六 |
 | 6 | 流式回复拿到了，但 `usage` 永远是空、额度不扣 | 流式请求必须补 `stream_options.include_usage`，否则上游不回 usage | internals 十二 |
 | 7 | 模型被标成免费、Free first 一直派到它 | `free` 只认厂商声明（`input_points === 0`），**不能从 `rate === 0` 反推**；价格缺失 = 不列，不猜 | internals 十六 · HOOKS 十一之二 |
@@ -72,6 +72,7 @@ curl -s "https://usemagpie.ai/api/latest?channel=stable" | grep -o '"version":"[
 | 19 | 单轮回 `400 ... tools.N.function.parameters/properties/functions/items: invalid JSON Schema`，但请求里**没有**空 `items` | 上游对 **`items` 子树内部**比根节点严：`anyOf`/`oneOf`/`allOf`/`not`/`const`/`if`+`then`+`else`/`{}` 全 400，**tuple 形式的 `items`（数组）国际站拒**，而同样形态放在顶层 parameters 里 200。命中来源是 **MCP 工具 schema**（REA MCP 7 个工具的 `functions` 数组）。判据：同一请求只把 `items` 子树里的 `anyOf` 摊平 → 200；改完**必须复查没留下空 `{}`**（删 `not`/`const` 会删空）。⚠ **上游 2026-10-29 00:25 起放宽了这层校验（raw 也 200），同一夜里还出现过波动** —— 判要不要改写请看 `_probe/items-subtree-stability.mjs` 的多轮统计，别信单次探针。改写已做（`loosenItemsSchema`，**只动 `items` 子树**、顶层 union 不动） | internals 十七 · `tests/body-rewrite.mjs` · `_probe/items-subtree-upstream.mjs` |
 | 20 | 邮箱验证码登录报「phone 字段是必须的」或「captcha 字段是必须的」 | 邮箱和手机是**两套端点**：发信 `/v4/user/send-email` vs `/send-sms`，换登录态 `/v4/user/login-email` vs `/login`；邮箱那条验证码字段叫 **`captcha`**（不是 `code`）。判据：往 `/v4/user/login` 发任何 type 都回「phone 字段是必须的」 | `src/captcha.mjs` 头 · CHANGELOG 0.3.28 |
 | 21 | 无头登录「旋转验证连试 4 张图都没过」，而这号本来就是自己的 | 先分清两件事：① **已注册的号服务端根本不出图**（`/captcha/generate` 对已注册账号直接回 `business_token`）—— 所以必须**先取图、再判识图模型**，一上来就 `if (!vision) throw` 会把这条免费通道堵死；② 识图模型 `max_tokens` 太小会把推理答案饿死（`workbuddy/deepseek-v4.1-flash` 给 400 → `content:null`，判官抓空串） | CHANGELOG 0.3.28 · `src/vision.mjs` |
+| 22 | 同一账号有的请求 200、有的 403 `token无效`（`retryable=false`），换个时间又好了 | key 有两条签发路径时 store 与 magpie 各存一把，**静态挑一把必有一半踩空**。0.3.29 起 `keyCandidates()` 把 store 两槽 + `auth.access` 逐把打 chat，命中的写回 store；全被拒才交 402 让 magpie 换号。判据：`GET /v1/models` 对死 key **放行**，逐把探活必须用 `/v1/chat/completions` | CHANGELOG 0.3.29 · `tests/key-failover.mjs` |
 
 **坑 14 的两个附带判据**（都实测过）：
 

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # 更新记录
 
+## 0.3.29 — 2026-10-29
+
+**同一账号多把 key 逐把试 · 全部被拒改 402 · 续期收敛到 key-store**
+
+（核心改动来自 PR #12，作者 @baijiu666；合入时补了五处，见文末「合入时补的五处」。）
+
+### 症状
+
+ZCode 经 magpie 网关调 `magicrew-intl/deepseek-v4.1-flash` 整轮失败：
+
+```
+provider_code=403  reason=auth_failed  status=403  retryable=false
+界面显示：token无效
+```
+
+`retryable=false` ⇒ magpie 不换号，错误直接抛给客户端。同一 provider 下其他账号明明还有余额。
+
+### 根因：key 有两条签发路径，本地各存一把、静态挑一把
+
+- `src/hooks/refresh.mjs` —— magpie 的续期，签发后只交给 magpie，**不写** key-store
+- `src/keys.mjs` 的 `ensureKey` —— 请求路径自己续期，写 key-store
+
+两边各存一把；api_key 只活 2 小时，两条路各自什么时候续、续到哪把，本地并不一致。
+静态挑其中一把，踩空就是 403「token无效」。
+
+PR 提交者 2026-10-29 逐把打 `/v1/chat/completions` 实测（5 个国际站账号）：
+
+| 账号 | `auth.access` | store 当前槽 |
+|---|---|---|
+| magicrew-intl | ✅ | ❌ |
+| magicrew-intl#z983c8 | ✅ | ❌ |
+| magicrew-intl#3oqx5z | ❌ | ✅ |
+| magicrew-intl#h2mcxi | ❌ | ✅ |
+| magicrew-intl#8amjca | ❌ | ❌ |
+
+**5 个里 3 个两路状态不一致，方向还各不相同** —— 静态顺序（先 store 或先 auth）都救不了。
+
+⚠ 不要把这条读成「服务端同一账号只认最新签发的那把」—— 2026-10-28 的受控实验
+已经推翻过这个说法：同账号相隔 67 秒签的两把同时有效；12 把逐把探活，403 **全部**
+对应 `expiresAt` 已过。真正的失效原因是**手里那把过期了**，而两条路径让本地不知道
+自己手里的是哪把。逐把试解决的是这个「不知道」。
+
+补一条取证经验：对这种死 key，`GET /v1/models` 是**放行**的，只有 chat 才 403。逐把探活必须用 chat。
+
+### 修法（三处）
+
+1. **`src/keys.mjs` 新增 `keyCandidates()`** —— 同一账号的所有候选 key（store 当前槽 / 另一槽 / `auth.access`），去重后按 `expiresAt` 倒序。到期越晚 = 签发越晚 = 越可能是活着的那把。配套 `adoptKey()` 把命中的那把写回 store。
+
+2. **`src/hooks/loader.mjs` 逐把试 + 全挂改 402** —— `isKeyRejected()` 认两种形态：`HTTP 403`，以及 **`HTTP 200` + `{"code":403,"message":"token无效"}`**（绝大多数是这种，只看状态码会漏）。全部被拒时返回 **402** 而不是 403 —— 402 在 magpie 里是 `failCredit`，会把这个账号 rest 30 分钟、去问下一个账号 / 组的下一个成员，与 0.3.26「积分不足改写 402」同一条通路。SSE 一律不碰。
+
+3. **`src/hooks/refresh.mjs` 收敛到 key-store** —— 改调 `renewViaStore()`，由 store 统一持有 `refresh_token` 并写回新 key，magpie 拿到的是同一把；且与 `ensureKey` 共用 `renewOnce` 锁（按 siteId+account 去重），避免两条路径同时续期、后到的那次用废 token 被误判成「登录已失效」。
+
+### 验证（PR 提交者实测，2026-10-29）
+
+`makeLoader().fetch` 直接喂真实账号（不经过 magpie）：
+
+```
+① store 那把已死 / auth 活的（z983c8） → HTTP 200 ✅
+② 两把都死（8amjca）                  → HTTP 402 + 可读原因（交给 magpie 换号）
+③ auth 已死 / store 活的（h2mcxi）     → HTTP 200 ✅
+```
+
+全账号跑一遍：国际站 5/5 → 200；国内站 `magicrew` / `lky0b4` / `0ok4oa` → 200；`4rm3fp`（积分 -28）→ 402「可用积分已不足」（0.3.26 的改写，正确）。
+
+经网关三条链路 `magicrew/…`、`magicrew-intl/…`、`group/never-stuck` 全部 200。
+
+### 验证（合入后复核，2026-10-29 02:15）
+
+两站各取真实账号（国际 `magicrew-intl#m2orth` / 国内 `magicrew#3wbzad`），隔离 HOME、
+复制真实 key 构造四场景，用 magpie 自带的 bun 直打上游：
+
+| 场景 | 国际站 | 国内站 |
+|---|---|---|
+| A 基线（store 活 + auth 活） | 200 | 200 |
+| B store 死 / auth 活 | 200，且写回 store 另一槽 | 200，且写回 |
+| C store 活 / auth 死 | 200（命中 store 那把，不重写） | 200 |
+| D 三把全死 | 402 + 可读原因 | 402 + 可读原因 |
+
+`tests/key-failover.mjs` 25 条断言把以上全部离线钉死（`node tests/key-failover.mjs` 退出 0）。
+
+### 边界
+
+- 不跨账号借身份：只用**本账号**的 key；本账号全挂就交 402 让 magpie 决定换谁，与 0.3.23 `accountFor()` 的保守立场一致
+- 只有第一把被拒时才会多发请求；命中那把只走 1 次
+
+### 合入时补的五处
+
+1. **`renewViaStore` 会试两处 refresh_token** —— 升级上来的第一次续期，store 那份可能早被旧的 `refresh.mjs` 轮换废了；只认 store 会让用户莫名被要求重新登录。现在 store → `auth.refresh` 依次试，谁活谁写回。
+2. **`adoptKey` 空 store 时保留 `auth.refresh`** —— 首次接管、续期失败但 `auth.access` 还能用时，PR 初版写回 store 会丢掉 refresh_token，2 小时后没人能续。
+3. **`isKeyRejected` 只认业务错误码** —— PR 初版用文本正则，正常回复正文里恰好出现 `unauthorized` / `token无效` 就会被当成 key 拒绝，白白重发（可能重复计费）。现在先 `JSON.parse`，只看 `code` / `message` 字段；有 `choices` 的正常响应绝不判。
+4. **被拒响应的 body 显式取消** —— 逐把试时，每条死连接的响应体不会一直挂着等 GC。
+5. **`refresh.mjs` 不再要求 `auth.refresh` 存在** —— refresh_token 只躺在 key-store 里时（`ensureKey` 续过、magpie 那份已轮换），PR 初版直接 `return undefined`，key 到期就掉登录。
+
 ## 0.3.28 — 2026-10-29
 
 **邮箱验证码登录（内置）· 已有账号不再过旋转图 · 识图模型被 `max_tokens` 饿死的修复**

package/docs/internals.md

@@ -822,7 +822,7 @@ store  槽 a    expires 2026-10-28T14:41:03.000Z   → 200
 不管吊销机制是什么，**只留一把、只有一个出口**这个设计依然成立 ——
 理由从「否则互相吊销」改成「否则本地会分叉，说不清手里那把是不是服务端认的」。
 
-### 保活链路（2026-10-27 逐版本核对后的实况）
+### 保活链路（0.3.29 起；2026-10-29 逐版本核对）
 
 ```
 每次请求前   ensureKey(c, getAuth)          ← src/hooks/loader.mjs
@@ -831,13 +831,27 @@ store  槽 a    expires 2026-10-28T14:41:03.000Z   → 200
                             ├─ 有 refresh_token → PUT 换新的 → 覆盖落盘
                             └─ 没有 / 失败     → 退回 magpie 存的那把
 
+             keyCandidates(c, auth)        ← 同一账号的 store 两槽 + auth.access
+               └─ 逐把打 /v1/chat/completions；被拒换下一把，命中写回 store（adoptKey）
+
 到期前 10 分钟 auth.refresh(auth)           ← magpie 按 refreshLead 主动调度
-               └─ src/hooks/refresh.mjs 直接调 api.refreshGatewayKey(auth.refresh)
-                  ⚠ 不经过 keys.mjs，也不读 key-store
+               └─ src/hooks/refresh.mjs → keys.mjs 的 renewViaStore()
+                  与 ensureKey 共用 renewOnce 锁和同一个 key-store；
+                  refresh_token 先试 store 那份、再试 magpie 那份（升级兼容）
 
 每天一次     checkin → runCheckin()         ← 领积分 / 补首任务 / 新手福利，**不碰 key**
 ```
 
+⚠ 0.3.29 之前 refresh.mjs 自己调 `api.refreshGatewayKey(auth.refresh)`、不写 key-store：
+两条签发路径各存一把 key，而 key 只活 2 小时，两条路各自续到哪把、哪把已经过期，
+本地并不一致。2026-10-29 实测 5 个国际站账号里 3 个「静态挑一把」踩空，表现是
+403 `token无效` 且 `retryable=false`（magpie 不换号，整轮直接抛给客户端）。
+`keyCandidates()` 的逐把试与 `renewViaStore()` 的收敛就是为这两条路分别兜底。
+
+⚠ 别把这里读成「服务端同一账号只认最新签发的那把」—— 2026-10-28 的受控实验
+已经推翻过：同账号相隔 67 秒签的两把同时有效；12 把逐把探活，403 全部对应
+`expiresAt` 已过。真正失效的是**手里那把过期了**，不是后来签的把它顶掉了。
+
 ### checkin 现在做四件事（0.3.11 起）
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magicrew-auth",
-  "version": "0.3.28",
+  "version": "0.3.29",
   "description": "超级麦吉 / MagiCrew for magpie and OpenCode — one package, two providers: letsmagic.cn (国内) and magicrew.ai (international). Password or web-JWT sign-in, the account's own live model list, points balance, newcomer rewards, invite codes.",
   "type": "module",
   "main": "./index.mjs",

package/src/hooks/loader.mjs

@@ -14,7 +14,45 @@
 // ⚠ 不要在这里读流、不要手拼 x-api-key ——
 //   流由 magpie 处理，头由 SDK 包自动加。见 README「最小交付面」。
 
-import { ensureKey, accountOf } from "../keys.mjs"
+import { ensureKey, accountOf, keyCandidates, adoptKey } from "../keys.mjs"
+
+/**
+ * 上游「这个账号不行」的两种形态（2026-10-29 实测）：
+ *
+ *   · HTTP 403
+ *   · **HTTP 200 + `{"code":403,"message":"token无效"}`**  ← 绝大多数是这种
+ *
+ * 所以光看状态码会漏。只解析 JSON（SSE 一律不碰，读流会破坏它）。
+ */
+async function isKeyRejected(res) {
+  if (!res) return false
+  if (res.status === 401 || res.status === 403) return true
+  const ct = res.headers.get("content-type") || ""
+  if (res.status !== 200 || !ct.includes("application/json")) return false
+  let text = ""
+  try {
+    text = await res.clone().text()
+  } catch {
+    return false
+  }
+  if (text.length > 8192) return false
+  let body
+  try {
+    body = JSON.parse(text)
+  } catch {
+    return false
+  }
+  // 只认**业务错误码**。正常 chat 完成的 JSON 是 {choices:[…]}，没有顶层 code；
+  // 用文本正则会把模型回复里恰好出现的 "unauthorized" 当成 key 拒绝 ——
+  // 那会白白重发请求（可能重复计费），甚至最后把正常响应丢掉换成 402。
+  const code = Number(body?.code ?? body?.error?.code)
+  if (code === 401 || code === 403) return true
+  const msg = String(body?.message ?? body?.error?.message ?? "")
+  if (!msg) return false
+  if (/token无效|token 无效|invalid token/i.test(msg)) return true
+  // 兜底：只有 message、没有 code 的少量形态；有 choices 的正常响应绝不判
+  return !Array.isArray(body?.choices) && /unauthorized/i.test(msg)
+}
 
 /**
  * 把 JSON Schema 里的 `additionalProperties` **非布尔值**原地换成 `true`。
@@ -447,6 +485,8 @@ export async function rewriteCreditRefusal(res) {
 }
 
 export function makeLoader(c) {
+  /** 已经写回 store 的 key —— 避免每个请求都去读一次 store */
+  const adopted = new Set()
   return async (getAuth) => {
     const auth = await getAuth()
     if (!auth) return {}
@@ -489,12 +529,60 @@ export function makeLoader(c) {
         // 四处请求体改写，全在 rewriteRequestBody 里（那里有实测出处）
         body = rewriteRequestBody(body)
 
-        return rewriteCreditRefusal(await fetch(url, {
-          method: init?.method ?? "POST",
-          headers,
-          body,
-          signal: init?.signal ?? req?.signal ?? AbortSignal.timeout(300_000),
-        }))
+        const signal = init?.signal ?? req?.signal ?? AbortSignal.timeout(300_000)
+        const sendWith = (apiKey) =>
+          fetch(url, {
+            method: init?.method ?? "POST",
+            headers: { ...headers, authorization: `Bearer ${apiKey}` },
+            body,
+            signal,
+          })
+
+        // 同一账号可能握着两把 key（magpie 的 refresh 一条、插件 store 一条），
+        // 哪把还有效本地无法预判 —— 静态挑必然有一半踩空，只能逐把试。
+        // 详见 src/keys.mjs 的 keyCandidates 注释（2026-10-29 五个账号的实测表）。
+        // 传 fresh 而不是 getAuth：候选与下面 adoptKey 必须落在同一个账号上，
+        // 不能让两次 getAuth() 返回不同结果。
+        const cands = await keyCandidates(c, fresh)
+        if (!cands.length) throw new Error(`${c.SHORT} 未登录（拿不到可用的 key）`)
+
+        for (const cand of cands) {
+          const res = await sendWith(cand.apiKey)
+          if (!(await isKeyRejected(res))) {
+            // 这把能用 —— 写回 store，让 ensureKey / 额度那几路也用同一把
+            if (!adopted.has(cand.apiKey)) {
+              adopted.add(cand.apiKey)
+              adoptKey(c, fresh, cand.apiKey, cand.expiresAt)
+            }
+            return rewriteCreditRefusal(res)
+          }
+          // 这把被拒：响应不再使用，显式取消 body —— 否则逐把试时
+          // 每条死连接的响应体都挂着，等 GC 才释放。
+          try {
+            await res.body?.cancel()
+          } catch {}
+        }
+
+        // 这个账号的 key 全被拒。上游给的是 403「token无效」，magpie 会判成
+        // 「不可重试」直接抛给客户端（ZCode 显示 auth_failed / token无效）。
+        // 改写成 402：magpie 的 failure(402) 是 failCredit → 把这个账号 rest 掉、
+        // 去问下一个账号 / 组的下一个成员。与 0.3.26 的「积分不足」同一条通路。
+        return new Response(
+          JSON.stringify({
+            error: {
+              message:
+                `${c.SHORT}：本账号的 ${cands.length} 把密钥均已被上游拒绝，已交给 magpie 换下一个账号。` +
+                `（常见于登录 / 续期分叉；请重新登录这个账号）`,
+              type: "account_unavailable",
+              code: 402,
+            },
+          }),
+          {
+            status: 402,
+            statusText: "Payment Required",
+            headers: { "content-type": "application/json" },
+          },
+        )
       },
     }
   }

package/src/hooks/refresh.mjs

@@ -3,24 +3,31 @@
 // magpie 在 api_key 到期前（refreshLead）调一次，**返回的字段合并进旧账号**，
 // 不是整体替换（client.auth.set 才是替换，两者不同）。
 //
-// ⚠ 一次性 refresh_token 必须串行 —— magpie 已按账号串行化，插件里别再并发；
+// ⚠ 一次性 refresh_token 必须串行 —— magpie 已按账号串行化；插件里
+//   renewViaStore 与 ensureKey 共用 renewOnce 的同一把锁，也不会并发。
 //   服务端每次换完会轮换，必须用返回的新值。
 
-import { refreshGatewayKey } from "../api.mjs"
+import { renewViaStore } from "../keys.mjs"
 
 export function makeRefresh(c) {
   return async (auth) => {
-    if (!auth?.refresh) return undefined
+    // 不要求 auth.refresh 存在：refresh_token 可能只躺在 key-store 里
+    //（0.3.29 之前 ensureKey 续过、magpie 那份已经轮换废了）。由 renewViaStore
+    // 两处都试，这里先别把它挡掉。
+    if (!auth) return undefined
     try {
-      const k = await refreshGatewayKey(auth.refresh, c.host)
+      // ⚠ 必须走 store —— 由它统一持有 refresh_token 并把新 key 写回。
+      //   自己再调一次 refreshGatewayKey 会让两条路径各存一把，
+      //   哪把还有效本地无法预判，请求侧就会 403「token无效」（2026-10-29 实测）。
+      const k = await renewViaStore(c, auth)
       return {
         access: k.apiKey,
-        // 服务端每次 PUT 都轮换 refresh_token，必须用新的
+        // 服务端每次换完都轮换 refresh_token，必须用返回的新值
         refresh: k.refreshToken ?? auth.refresh,
-        expires: Date.now() + 2 * 3600_000,
+        expires: k.expiresAt || Date.now() + 2 * 3600_000,
       }
     } catch (e) {
-      if (/invalid|expired|401|403/i.test(String(e?.message))) {
+      if (/invalid|expired|401|403|token/i.test(String(e?.message))) {
         throw Object.assign(new Error("登录已失效，请重新登录"), { signIn: "expired" })
       }
       throw e

package/src/keys.mjs

@@ -2,21 +2,16 @@
 //
 //   登录成功  → issueAndStore()  签一把放进「另一个槽」，切过去
 //   loader    → ensureKey()      快过期就把新的签到另一个槽，切过去；旧的留着当回退
-//   refresh   → ⚠ **不经过本模块**。src/hooks/refresh.mjs 自己调
-//               api.refreshGatewayKey(auth.refresh)，magpie 拿到的不是这一把。
+//   refresh   → renewViaStore()  续期、写回 store；magpie 拿到的就是 store 里这一把
 //
 // **每个账号一套槽，互不干扰** —— 同站点登两个账号时，第二个人登录不会碰第一个人的 key。
 // 账号标识用 `org`（组织码），拿不到才退回 accountId。
 //
-// ⚠ 上面那条 refresh 是「唯一出口」这个设计里**唯一没落地的口子**（2026-10-27 核对）：
-//   refresh_token 是一次性轮换的，两条路径各用各的那份会分叉 ——
-//   ensureKey 轮换后 store 里是新值，refresh.mjs 手里 magpie 的还是旧值，
-//   再调就是 401 → magpie 判定「登录已失效」→ 让用户重新登录。
-//
-//   目前不会触发，因为 **store 从来没被写过**（本机 magicrew-key-*.json 一个都没有，
-//   说明 ensureKey 从没执行过 —— 没发过模型请求）。但这意味着：
-//   **若将来要给 checkin 补 ensureKey，必须先把这个钩子也收敛进来**，
-//   否则就是亲手把「一条路」掰成两条，用「多写一句文档」换「用户莫名掉登录」。
+// ⚠ refresh 这条口子曾经是「唯一出口」设计里唯一没落地的地方（2026-10-27 核对）：
+//   refresh.mjs 自己调 api.refreshGatewayKey(auth.refresh)，拿到的 key 只交给 magpie，
+//   与 store 各存一份 —— refresh_token 一次性轮换，两条路径必然分叉。
+//   0.3.29（PR #12）起已收敛到 renewViaStore()：与 ensureKey 共用 renewOnce 锁和
+//   同一个 key-store，refresh_token 也只从这里轮换出去。
 
 import { issueGatewayKey, refreshGatewayKey } from "./api.mjs"
 import {
@@ -84,6 +79,150 @@ export function accountFor(c, auth) {
   return direct
 }
 
+/**
+ * 这个账号**所有**可能能用的 key，按到期时间从晚到早排。
+ *
+ * 为什么需要「多把」：key 有两条签发路径 —— magpie 的 `auth.refresh` 一条
+ * （src/hooks/refresh.mjs）、本模块的 `ensureKey` 一条，两边各写各的。
+ * api_key 只活 2 小时，两条路各自什么时候续、续到哪把，本地并不一致 ——
+ * 静态「只挑一把」必然有一半概率踩空。
+ *
+ * 2026-10-29 实测（5 个国际站账号，逐把打 /v1/chat/completions）：
+ *
+ *   magicrew-intl          auth.access ✅   store 槽 b ❌
+ *   magicrew-intl#z983c8   auth.access ✅   store 槽 b ❌
+ *   magicrew-intl#3oqx5z   auth.access ❌   store 槽 a ✅
+ *   magicrew-intl#h2mcxi   auth.access ❌   store 槽 b ✅
+ *   magicrew-intl#8amjca   auth.access ❌   store 槽 a ❌  ← 两把都死
+ *
+ * **5 个里 3 个两路状态不一致，方向还各不相同** —— 先 store 或先 auth 都救不了。
+ *
+ * ⚠ 不要读成「服务端同一账号只认最新签发的那把」。2026-10-28 的受控实验已经
+ * 推翻过这个说法：同账号相隔 67 秒签的两把同时有效；12 把逐把探活，403 全部
+ * 对应 `expiresAt` 已过。真正的原因是**手里那把过期了**，而两条路径让本地
+ * 不知道自己手里的是哪把。逐把试解决的就是这个「不知道」。
+ *
+ * 到期越晚 = 签发越晚 = 越可能是活着的那把，所以按 expiresAt 倒序试。
+ *
+ * @param {object} c               站点上下文
+ * @param {Function|object} getAuth magpie 的取账号函数，或直接给 auth 对象
+ */
+export async function keyCandidates(c, getAuth) {
+  let auth = null
+  try {
+    auth = typeof getAuth === "function" ? await getAuth() : getAuth
+  } catch {}
+  const account = accountFor(c, auth)
+  const st = readStore(c.id, account)
+
+  const out = []
+  const byKey = new Map()
+  const add = (k) => {
+    if (!k?.apiKey) return
+    const rec = { apiKey: k.apiKey, expiresAt: Number(k.expiresAt) || 0 }
+    const prev = byKey.get(rec.apiKey)
+    if (prev) {
+      // 同一把 key 从两路拿到时，保留更晚的到期时间 —— 否则可能被排到死 key 后面
+      if (rec.expiresAt > prev.expiresAt) prev.expiresAt = rec.expiresAt
+      return
+    }
+    byKey.set(rec.apiKey, rec)
+    out.push(rec)
+  }
+  add(currentKey(st))
+  add(st?.keys?.[otherSlot(st.current)])
+  if (auth?.access) add({ apiKey: auth.access, expiresAt: Number(auth.expires) || 0 })
+
+  return out.sort((a, b) => Number(b.expiresAt || 0) - Number(a.expiresAt || 0))
+}
+
+/** 把实测能用的那把写回 store —— 下次直接命中，不再逐把试错 */
+export function adoptKey(c, auth, apiKey, expiresAt) {
+  try {
+    const account = accountFor(c, auth)
+    const st = readStore(c.id, account)
+    if (currentKey(st)?.apiKey === apiKey) return
+    const slot = otherSlot(st.current)
+    writeStore(c.id, account, {
+      current: slot,
+      // 空 store 首次接管时 refresh_token 只在 magpie 手里 —— 这里必须接住，
+      // 否则 2 小时后没人能续，用户被要求重新登录。
+      refreshToken: st.refreshToken || auth?.refresh || "",
+      keys: { ...st.keys, [slot]: { apiKey, expiresAt: Number(expiresAt) || 0 } },
+      at: st.at,
+    })
+  } catch {}
+}
+
+/**
+ * 续期并**写回 store** —— 给 src/hooks/refresh.mjs 用。
+ *
+ * 收敛成一条路径的原因：refresh.mjs 原来自己调 `refreshGatewayKey`，
+ * 拿到的 key 只交给 magpie，插件 store 里还是旧的。两条路径各存一份，
+ * 哪把是新签的、哪把已经过期，本地说不清 —— 2026-10-29 实测 5 个账号里
+ * 3 个两路状态不一致，就是这么来的。
+ *
+ * ⚠ refresh_token 是一次性的：谁续谁负责写回，不能让两边各存各的。
+ */
+export async function renewViaStore(c, auth) {
+  const account = accountFor(c, auth)
+
+  // 与 ensureKey 共用同一把锁（renewOnce 按 siteId+account 去重）——
+  // refresh_token 一次性，两条路径同时续期会让后到的那次用废 token → 误判掉登录。
+  let err = null
+  const rec = await renewOnce(c.id, account, async () => {
+    try {
+      const st = readStore(c.id, account)
+
+      // refresh_token 也可能有两份：store 里的（ensureKey 续过）与 magpie 手里的
+      // （0.3.29 之前的 refresh.mjs 续过）。两把都是一次性，只有一把还活着 ——
+      // 升级上来的第一次尤其：store 那份可能早被轮换废了，auth.refresh 才是活的。
+      const tokens = []
+      const seen = new Set()
+      for (const t of [st.refreshToken, auth?.refresh]) {
+        if (!t || seen.has(t)) continue
+        seen.add(t)
+        tokens.push(t)
+      }
+      if (!tokens.length) throw new Error("没有 refresh_token")
+
+      let lastErr = null
+      for (const refreshToken of tokens) {
+        try {
+          const k = await refreshGatewayKey(refreshToken, c.host)
+          const next = { apiKey: k.apiKey, expiresAt: toEpochMs(k.apiKeyExpiresAt) }
+          const slot = otherSlot(st.current)
+          const nextRefresh = k.refreshToken || refreshToken
+          writeStore(c.id, account, {
+            current: slot,
+            refreshToken: nextRefresh,
+            keys: { ...st.keys, [slot]: next },
+            at: st.at,
+          })
+          return { ...next, refreshToken: nextRefresh }
+        } catch (e) {
+          lastErr = e
+        }
+      }
+      throw lastErr ?? new Error("续期失败")
+    } catch (e) {
+      err = e
+      throw e
+    }
+  })
+
+  if (!rec) throw err ?? new Error("续期失败")
+  // 并发时可能复用 ensureKey 的 rec（它只返回 apiKey/expiresAt）——
+  // 从 store 补上最新 refresh_token，免得 magpie 那份落后一轮。
+  if (!rec.refreshToken) {
+    try {
+      const st2 = readStore(c.id, account)
+      if (st2.refreshToken) rec.refreshToken = st2.refreshToken
+    } catch {}
+  }
+  return rec
+}
+
 /**
  * 拿到这个账号一把能用的 key。**永不抛** —— 续不上就交出手里那把（哪怕不新鲜），
  * 让请求自己去撞上游的错误，比在这里抛更能说明问题。