@blod-nm/user-kit 0.1.5 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blod-nm/user-kit",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "private": false,
   "type": "module",
   "description": "CloudBase user-center kit: auth (wechat code / unionid / password / sms / email / signup) + crm_user_detail archive on @blod-nm/base-cb.",

package/src/access-key.js

@@ -0,0 +1,130 @@
+/**
+ * access-key.js — apikey 签发 / verify（+30s 进程缓存）/ key 域能力（spec §3.1 · §3.4 · §3.5 · §3.7）
+ *
+ * 形态: key='a1_'+b64u(randomBytes(32))（只在签发响应出现一次）· key_hash=sha256hex(key)（档案表主键，库内不存明文）
+ *       key_id='k_'+key_hash[0:12]（展示/吊销句柄）· key_prefix=key[0:11]（识别用，不含敏感信息）
+ *       expires_at=unix 秒（now + (ttl ?? cfg.akDefaultKeyTtlSec)）
+ * 两张表: __user_token_cache（token 托管，broker 读写）/ __user_access_key（key 档案，本文件读写）
+ * verify: 一条 SQL 查 key_hash → 四分支（malformed/revoked/expired/ok）；ok 结果进程内 Map 缓存 30s；
+ *         revoke 用 RETURNING key_hash 主动清缓存；DB 异常 → 503（fail-closed，查不到=拒绝）。
+ * key 域: create（当前 key 换 uid → 签发新 key）/ list（不含明文与 hash）/ revoke（他人 key → 404）/ verify。
+ * 禁止: 任何官方网关调用 / HMAC / masterSecret（查表派：档案表是唯一真相）。
+ */
+import { createHash, randomBytes } from 'node:crypto'
+
+const CACHE_TTL_MS = 30_000
+const DEFAULT_TTL_SEC = 2592000
+
+export const DDL_USER_TOKEN_CACHE = `CREATE TABLE IF NOT EXISTS __user_token_cache (
+  uid text PRIMARY KEY, access_token text NOT NULL, refresh_token text NOT NULL,
+  expires_at bigint NOT NULL, updated_at timestamptz DEFAULT now() NOT NULL)`
+
+export const DDL_USER_ACCESS_KEY = `CREATE TABLE IF NOT EXISTS __user_access_key (
+  key_hash text PRIMARY KEY, key_id text NOT NULL UNIQUE, uid text NOT NULL,
+  scene text NOT NULL DEFAULT '', key_prefix text NOT NULL,
+  created_at timestamptz DEFAULT now() NOT NULL, expires_at bigint NOT NULL,
+  revoked_at timestamptz, updated_at timestamptz DEFAULT now() NOT NULL)`
+
+export const DDL_USER_ACCESS_KEY_INDEX = 'CREATE INDEX IF NOT EXISTS idx_user_access_key_uid ON __user_access_key(uid)'
+
+const SQL_SELECT_KEY = 'SELECT key_id, uid, scene, key_prefix, revoked_at, expires_at FROM __user_access_key WHERE key_hash=$1'
+const SQL_INSERT_KEY = 'INSERT INTO __user_access_key (key_hash, key_id, uid, scene, key_prefix, expires_at) VALUES ($1, $2, $3, $4, $5, $6)'
+const SQL_LIST_KEYS = 'SELECT key_id, key_prefix, scene, created_at, expires_at, revoked_at FROM __user_access_key WHERE uid=$1 ORDER BY created_at DESC'
+const SQL_REVOKE_KEY = 'UPDATE __user_access_key SET revoked_at=now(), updated_at=now() WHERE key_id=$1 AND uid=$2 AND revoked_at IS NULL RETURNING key_hash'
+
+const err = (code, message) => Object.assign(new Error(message), { code })
+const nowSec = () => Math.floor(Date.now() / 1000)
+export const sha256hex = s => createHash('sha256').update(String(s)).digest('hex')
+
+/** 进程内 verify 缓存（key_hash → { result, until }）；只缓存 ok 结果，写路径不读 */
+export const createVerifyCache = (ttlMs = CACHE_TTL_MS) => {
+  const store = new Map()
+  return {
+    get(hash) {
+      const hit = store.get(hash)
+      if (!hit) return null
+      if (hit.until <= Date.now()) { store.delete(hash); return null }
+      return hit.result
+    },
+    set(hash, result) { store.set(hash, { result, until: Date.now() + ttlMs }) },
+    clear(hash) { store.delete(hash) },
+    size: () => store.size,
+  }
+}
+
+/**
+ * key 域工厂：verify / issue 闭包共享缓存与 runSql 接缝；abilities 为 auth.key.* 四条注册项。
+ * runSql(sql, parameters) 是本文件唯一表读写入口（§3.7，pg 适配器由 index.js 注入）。
+ */
+export function createKeyAbilities({ cfg, runSql }) {
+  const cache = createVerifyCache()
+  const ttlSec = () => Number(cfg?.akDefaultKeyTtlSec ?? DEFAULT_TTL_SEC)
+
+  // 签发：生成明文 + 落档（只返回 hash 供内部使用，明文仅由调用方取走一次性响应）
+  async function issue(uid, { scene = '', ttl } = {}) {
+    const apikey = 'a1_' + randomBytes(32).toString('base64url')
+    const keyHash = sha256hex(apikey)
+    const keyId = 'k_' + keyHash.slice(0, 12)
+    const keyPrefix = apikey.slice(0, 11)
+    const expiresAt = nowSec() + Number(ttl ?? ttlSec())
+    await runSql(SQL_INSERT_KEY, [keyHash, keyId, uid, scene ?? '', keyPrefix, expiresAt])
+    return { apikey, key_hash: keyHash, key_id: keyId, key_prefix: keyPrefix, expires_at: expiresAt }
+  }
+
+  // 唯一裁决路径：sha256(key) → 一行 SQL → 四分支；ok 结果 30s 缓存
+  async function verify(apikey, { useCache = true } = {}) {
+    const keyHash = sha256hex(apikey ?? '')
+    if (useCache) {
+      const hit = cache.get(keyHash)
+      if (hit) return hit
+    }
+    let rows
+    try { rows = await runSql(SQL_SELECT_KEY, [keyHash]) } catch { throw err(503, 'apikey 校验失败') }
+    const row = rows?.[0]
+    const result = !row ? { ok: false, reason: 'malformed' }
+      : row.revoked_at != null ? { ok: false, reason: 'revoked' }
+      : Number(row.expires_at) <= nowSec() ? { ok: false, reason: 'expired' }
+      : { ok: true, auth: { uidRef: row.uid, scene: row.scene ?? '', keyId: row.key_id, keyPrefix: row.key_prefix, expiresAt: Number(row.expires_at) } }
+    if (result.ok) cache.set(keyHash, result)
+    return result
+  }
+
+  // 凭证类能力共用：verify → 401 / 返回 uid（内部调用无缓存，避免读到过期判定）
+  async function uidOf(apikey) {
+    const v = await verify(apikey, { useCache: false })
+    if (!v.ok) throw err(401, 'apikey 无效')
+    return v.auth.uidRef
+  }
+
+  const abilities = [
+    ['auth.key.create', { describe: '签发新 apikey（当前 key 换 uid；scene 只存不用）', run: async (args = {}) => {
+      const uid = await uidOf(args.apikey)
+      const scene = typeof args.scene === 'string' ? args.scene : ''
+      let issued
+      try { issued = await issue(uid, { scene }) } catch { throw err(500, 'apikey 签发失败') }
+      return { apikey: issued.apikey, key_id: issued.key_id, key_prefix: issued.key_prefix, expires_at: issued.expires_at }
+    } }],
+
+    ['auth.key.list', { describe: '当前用户的 key 档案列表（不含明文/key_hash）', run: async (args = {}) => {
+      const uid = await uidOf(args.apikey)
+      let rows
+      try { rows = await runSql(SQL_LIST_KEYS, [uid]) } catch { throw err(503, '查询 key 失败') }
+      return (rows ?? []).map(r => ({ ...r, expires_at: Number(r.expires_at) }))
+    } }],
+
+    ['auth.key.revoke', { describe: '吊销 key（key_id 必须属于当前用户；0 行 → 404）', run: async (args = {}) => {
+      const uid = await uidOf(args.apikey)
+      if (!args.key_id) throw err(400, 'key_id 必填')
+      let rows
+      try { rows = await runSql(SQL_REVOKE_KEY, [args.key_id, uid]) } catch { throw err(503, '吊销 key 失败') }
+      const keyHash = rows?.[0]?.key_hash
+      if (!keyHash) throw err(404, 'key 不存在或不属于当前用户')
+      cache.clear(keyHash)   // 写路径不读缓存；成功即失效该 key
+      return { revoked: true, key_id: args.key_id }
+    } }],
+
+    ['auth.key.verify', { describe: '校验 apikey（唯一裁决路径，返回 verify 结果对象）', run: async (args = {}) => verify(args.apikey) }],
+  ]
+
+  return { verify, issue, uidOf, abilities, cache }
+}

package/src/auth.js

@@ -1,5 +1,5 @@
 /**
- * auth.js — auth 域能力目录（8 条）+ 编排（登录链路/错误翻译 · spec §3.1–3.5 · §3.7）
+ * auth.js — auth 域能力目录（13 条）+ 编排（登录链路/错误翻译 · spec §3.1–3.5 · §3.7）
  *
  * 端点（主场实测确认，{origin}=https://<envId>.api.tcloudbasegateway.com）:
  *   POST /auth/v1/verification { phone | email }           → 发验证码，返回 verification_token（响应原样）
@@ -10,20 +10,22 @@
  *   POST /auth/v1/user/reauthenticate（Bearer）；GET /auth/v1/token/introspect（Bearer）
  *
  * 语义:
- *   · 透传三种（password/sms/email）：body 原样、响应原样返回（不裁剪不翻译，只补 uid）+ 成功后建档。
- *     uid 提取：payload.user.id 优先，否则 decodeJWT(access_token).sub（不验签，token 刚由网关签发）；
- *     都取不到 → 500「用户注册失败」。建档失败 → 同 500。
+ *   · 透传三种（password/sms/email）：body 原样发网关；uid 提取：payload.sub → payload.user.id →
+ *     decodeJWT(access_token).sub（不验签，token 刚由网关签发）；都取不到 → 500「用户注册失败」。建档失败 → 同 500。
+ *   · 登录收尾（§3.2）：建档 → 官方 token 托管（broker.upsert，失败 500）→ 签发 apikey（失败 500）；
+ *     响应只含 { apikey, expires_at }（wxcode 另有 config），官方 token/uid 字段不出域。
  *   · 网关非 2xx：原样透传 { code: 网关状态, payload }，不改写错误码（INVALID_USERNAME_OR_PASSWORD 原样可见）；
  *     网络异常（无 status）→ 502「登录请求失败」。
  *   · 自定义链路：customSignin 非 2xx → 502「自定义登录请求失败」；code2Session errcode 非零 → 400{errcode,errmsg}。
  *   · loginByWxcode：uid=唯一 id（wxResolveUid 缺省 identity：uid=openid），unionid 字段=微信原始值|null，不可互换。
  *
- * §3.12 补全: auth.signup（手机/邮箱验证码注册，响应原样+补 uid+建档）/ auth.signOut（不写档）。
+ * §3.12 补全: auth.signup（手机/邮箱验证码注册，建档+托管+签发 key）/ auth.signOut（不写档，apikey 入参）。
  *   自定义登录只有两个入口（钉死）：loginByWxcode（配置的微信小程序 appid/secret，code→openid→唯一 id→ticket→signin/custom）
  *   与 loginByUnionid（外部传唯一 id→ticket→signin/custom）；二者都必须建档；unionid=我们的唯一 id，与微信 openid/unionid 语义无关。
  *
  * §3.13 uid 提取顺序（统一所有登录/注册类）: payload.sub → payload.user.id → decodeJWT(access_token).sub →
- *   无则登录/注册类 500「用户注册失败」（token 类走 uidFromToken 400「access_token 无效」）。
+ *   无则登录/注册类 500「用户注册失败」。凭证类能力（signOut/reauthenticate/introspect）入参 apikey：
+ *   verify 不通过 → 401「apikey 无效」，通过后 broker.get(uid) 换官方 Bearer。
  *
  * §3.8 增补（4 条）: auth.sendVerification（phone/email 二选一；sendSmsCode/sendEmailCode 保留薄别名）/
  *   auth.verifyCode / auth.reauthenticate（verify_opt ∈ phone_code|email_code）/ auth.introspect ——
@@ -35,7 +37,7 @@
  */
 import cloudbase from '@cloudbase/node-sdk'
 import { code2Session as wxCode2Session } from './wechat.js'
-import { decodeJWT, throwGatewayError, makeGateway, uidFromToken } from './user.js'
+import { decodeJWT, throwGatewayError, makeGateway } from './user.js'
 import { withSchemas } from './schemas.js'
 
 export { decodeJWT }   // 供消费方/测试从包主入口取（真身在 user.js）
@@ -69,9 +71,14 @@ async function tcbCreateTicket(cfg, uid) {
   return tcbAppCache.auth().createTicket(uid, TICKET_TTL)
 }
 
-/* —— 能力目录 + 编排（ability 闭包持有 cfg/inject/kit）—— */
+/* —— 能力目录 + 编排（ability 闭包持有 cfg/inject/kit/deps）—— */
 
-export function createAuthAbilities(cfg, kit) {
+// 刷新请求器：broker 单飞刷新使用（inject.refreshTokenRequest 可替换）
+export const makeRefreshTokenRequest = (cfg, kit) => (cfg.inject || {}).refreshTokenRequest
+  || (body => kit.req(`https://${cfg.envId}.${cfg.domain || DEFAULT_DOMAIN}/auth/v1/token`, { method: 'POST', body }))
+
+// deps（index.js 注入）: broker（token 托管）/ verify（apikey 裁决）/ issue（签发新 key）/ refreshTokenRequest
+export function createAuthAbilities(cfg, kit, deps = {}) {
   const inject = cfg.inject || {}
   const origin = `https://${cfg.envId}.${cfg.domain || DEFAULT_DOMAIN}`
   const sendVerification = inject.sendVerification || (body => kit.req(`${origin}/auth/v1/verification`, { method: 'POST', body }))
@@ -80,7 +87,6 @@ export function createAuthAbilities(cfg, kit) {
   const code2Session = inject.code2Session || (code => wxCode2Session(cfg, code))
   const wxResolveUid = inject.wxResolveUid || (wx => wx.openid)   // 缺省 identity：uid=openid（现网语义）
   const createTicket = inject.createTicket || (uid => tcbCreateTicket(cfg, uid))
-  const refreshTokenRequest = inject.refreshTokenRequest || (body => kit.req(`${origin}/auth/v1/token`, { method: 'POST', body }))
   const fetchPrefixConfig = inject.fetchPrefixConfig || (() => kit.req(`${origin}/v1/storages/object/store/public/wx_mp_conf/prefix_config.json`, { headers: { 'Cache-Control': 'no-cache' } }))
   const gateway = makeGateway(cfg, kit)
   const gw = async (method, path, opts) => { try { return await gateway(method, path, opts) } catch (e) { throwGatewayError(e) } }
@@ -92,7 +98,8 @@ export function createAuthAbilities(cfg, kit) {
     const ticket = await createTicket(uid)
     let res
     try { res = await customSignin(ticket) } catch { throw err(502, '自定义登录请求失败') }
-    return { access_token: res.access_token, refresh_token: res.refresh_token, expires_in: res.expires_in }
+    const { access_token: at, refresh_token: rt, expires_in } = res
+    return { at, rt, expires_in }   // 仅内部传递；官方 token 不出域
   }
 
   // 建档统一翻 500「用户注册失败」
@@ -103,7 +110,27 @@ export function createAuthAbilities(cfg, kit) {
   // uid 提取四级顺序（§3.13）：payload.sub → payload.user.id → decodeJWT(access_token).sub
   const uidOfPayload = p => p?.sub || p?.user?.id || decodeJWT(p?.access_token).sub || null
 
-  // 透传三种共用：body 原样发网关，响应原样返回（只补 uid）+ 成功后建档
+  // 登录收尾（§3.2）：官方 token 托管落库 → 签发 key（托管不落库就不发 key，fail-closed）
+  async function issueSession(uid, tokens) {
+    const expiresAt = Math.floor(Date.now() / 1000) + (Number(tokens?.expires_in) || 0)
+    const at = tokens?.at ?? tokens?.access_token
+    const rt = tokens?.rt ?? tokens?.refresh_token
+    try { await deps.broker.upsert(uid, at, rt, expiresAt) }
+    catch { throw err(500, '官方凭证托管失败') }
+    let issued
+    try { issued = await deps.issue(uid) } catch { throw err(500, 'apikey 签发失败') }
+    return { apikey: issued.apikey, expires_at: issued.expires_at }
+  }
+
+  // 凭证类统一序（§3.3）：verify(apikey) → 401 → broker.get(uid) → 官方 Bearer 调用
+  async function sessionOf(apikey) {
+    const v = await deps.verify(apikey)
+    if (!v.ok) throw err(401, 'apikey 无效')
+    const { access_token: token } = await deps.broker.get(v.auth.uidRef)
+    return { uid: v.auth.uidRef, token }   // 官方 token 只在内部/网关 Bearer 使用
+  }
+
+  // 透传三种共用：body 原样发网关 → uid → 建档 → 托管 + 签发 key
   async function passthroughLogin(body, required) {
     for (const field of required) {
       if (!body?.[field]) throw err(400, `${field} 必填`)
@@ -113,7 +140,7 @@ export function createAuthAbilities(cfg, kit) {
     const uid = uidOfPayload(payload)
     if (!uid) throw err(500, '用户注册失败')
     await upsertOr500({ uid, profile: {} })
-    return { ...payload, uid }
+    return issueSession(uid, payload)
   }
 
   return withSchemas([
@@ -141,16 +168,15 @@ export function createAuthAbilities(cfg, kit) {
     } }],
 
     ['auth.reauthenticate', { describe: '重认证发码：POST /auth/v1/user/reauthenticate（Bearer；verify_opt ∈ phone_code|email_code）', run: async (args = {}) => {
-      const { access_token, verify_opt } = args
-      uidFromToken(access_token)
+      const { apikey, verify_opt } = args
       if (!['phone_code', 'email_code'].includes(verify_opt)) throw err(400, 'verify_opt 必填（phone_code|email_code）')
-      const { access_token: _t, ...rest } = args
-      return gw('POST', '/auth/v1/user/reauthenticate', { body: rest, token: access_token })
+      const { token } = await sessionOf(apikey)
+      return gw('POST', '/auth/v1/user/reauthenticate', { body: { verify_opt }, token })
     } }],
 
-    ['auth.introspect', { describe: 'token 校验：GET /auth/v1/token/introspect（Bearer），网关原样（含 sub）', run: async ({ access_token } = {}) => {
-      uidFromToken(access_token)
-      return gw('GET', '/auth/v1/token/introspect', { token: access_token })
+    ['auth.introspect', { describe: 'token 校验：GET /auth/v1/token/introspect（Bearer），网关原样（含 sub）', run: async ({ apikey } = {}) => {
+      const { token } = await sessionOf(apikey)
+      return gw('GET', '/auth/v1/token/introspect', { token })
     } }],
 
     ['auth.loginByPassword', { describe: '账号密码登录（透传+建档）：POST /auth/v1/signin { username, password }，响应原样补 uid', run: async (args = {}) => passthroughLogin({ username: args.username, password: args.password }, ['username', 'password']) }],
@@ -167,14 +193,15 @@ export function createAuthAbilities(cfg, kit) {
       if (wx.errcode) throw err(400, wx.errmsg || 'code2Session 失败', { errcode: wx.errcode, errmsg: wx.errmsg || 'code2Session 失败' })
       const uid = await wxResolveUid(wx)
       await upsertOr500({ uid, profile: { openid: wx.openid, unionid: wx.unionid || null } })
-      return { uid, openid: wx.openid, unionid: wx.unionid || null, ...(await finishLogin(uid)), config: await fetchPrefixConfig() }
+      const session = await issueSession(uid, await finishLogin(uid))
+      return { ...session, config: await fetchPrefixConfig() }
     } }],
 
-    ['auth.loginByUnionid', { describe: '开放登录：唯一 id 注册登录（建档→ticket→signin/custom；5 字段，不含 config）', run: async (args = {}) => {
+    ['auth.loginByUnionid', { describe: '开放登录：唯一 id 注册登录（建档→ticket→signin/custom→托管+签发 key）', run: async (args = {}) => {
       const { unionid } = args
       if (!unionid) throw err(400, '缺少 unionid')
       await upsertOr500({ uid: unionid, profile: {} })
-      return { uid: unionid, unionid, ...(await finishLogin(unionid)) }
+      return issueSession(unionid, await finishLogin(unionid))
     } }],
 
     ['auth.signup', { describe: '注册（手机/邮箱/provider_token 三形态）：POST /auth/v1/signup，响应原样+补 uid+建档', run: async (args = {}) => {
@@ -190,21 +217,13 @@ export function createAuthAbilities(cfg, kit) {
       if (args.email !== undefined) profile.email = args.email
       if (args.phone_number !== undefined) profile.phone = args.phone_number
       await upsertOr500({ uid, profile })
-      return { ...payload, uid }
+      return issueSession(uid, payload)
     } }],
 
     ['auth.signOut', { describe: '登出：POST /auth/v1/user/signout（Bearer），不写档', run: async (args = {}) => {
-      const { access_token, ...rest } = args ?? {}
-      uidFromToken(access_token)
-      return gw('POST', '/auth/v1/user/signout', { body: rest, token: access_token })
-    } }],
-
-    ['auth.refresh', { describe: 'refresh_token 换新令牌（3 字段裸对象）', run: async (args = {}) => {
-      const { refresh_token } = args
-      if (!refresh_token) throw err(400, '缺少 refresh_token')
-      let res
-      try { res = await refreshTokenRequest({ grant_type: 'refresh_token', refresh_token, client_id: cfg.envId }) } catch { throw err(502, '令牌刷新请求失败') }
-      return { access_token: res.access_token, refresh_token: res.refresh_token, expires_in: res.expires_in }
+      const { apikey, ...rest } = args ?? {}
+      const { token } = await sessionOf(apikey)
+      return gw('POST', '/auth/v1/user/signout', { body: rest, token })
     } }],
   ])
 }

package/src/index.js

@@ -5,33 +5,66 @@
  *   import { createKit } from '@blod-nm/user-kit'
  *   const kit = createKit({ envId, apiKey, wxAppid, wxSecret, tcbAuthCredentials, env?, inject?, signinProviders?, …透传 base-cb })
  *   await kit.ctx.run('pg.exec', { sql: 'select 1' })        // base-cb 网关 14 能力原样可用
- *   await kit.ctx.run('auth.loginByWxcode', { code })        // user 域与网关能力同总线
- *   kit.describe()                                           // 能力元数据（14 + 21）
+ *   await kit.ctx.run('auth.loginByPassword', { username, password })   // → { apikey, expires_at }
+ *   await kit.ctx.run('user.me', { apikey })                 // 凭证面统一 apikey
+ *   kit.key.verify({ apikey }) / kit.broker.get(uid)         // key 域 / token 托管便捷入口
+ *   kit.describe()                                           // 能力元数据
  *
- * 数据流: cfg fail-fast → createBaseKit(cfg)（base-cb req/gate/ctx）→ 同一 ctx register
- *         auth 域 12 条（含 2 别名）+ user 域 9 条（闭包持有 cfg/inject/kit）→ kit { ctx, req, cfg, describe }
+ * 数据流: cfg fail-fast → createBaseKit(cfg)（base-cb req/gate/ctx）→ runSql 单接缝（pg.exec）
+ *         → broker（token 托管）/ key 域（签发+verify+缓存）→ auth/user 域闭包持 deps → 注册 auth.cbToken.get（总线消费 broker）
+ *         → kit { ctx, req, cfg, broker, key, describe }
  *
  * cfg 约定（spec §3.0）:
  *   必填 envId / apiKey / wxAppid / wxSecret / tcbAuthCredentials（缺一即抛，fail-fast）
- *   env 缺省 'prod'（建档 tag from_env）；inject.* 九口（含 gateway）原样存 kit.cfg（缺省 = 真实现）
- *   domain/proxy/proxyBase/timeoutMs/role 透传 base-cb
+ *   env 缺省 'prod'（建档 tag from_env）；akDefaultKeyTtlSec 缺省 2592000（30 天）
+ *   inject.* 九口（含 gateway）原样存 kit.cfg（缺省 = 真实现）；domain/proxy/proxyBase/timeoutMs/role 透传 base-cb
  */
 import { createKit as createBaseKit } from '@blod-nm/base-cb'
-import { createAuthAbilities } from './auth.js'
+import { createAuthAbilities, makeRefreshTokenRequest } from './auth.js'
 import { createUserAbilities } from './user.js'
+import { createKeyAbilities } from './access-key.js'
+import { createCbTokenBroker, makeRunSql } from './token-broker.js'
+import { withSchemas } from './schemas.js'
 
 const REQUIRED = ['envId', 'apiKey', 'wxAppid', 'wxSecret', 'tcbAuthCredentials']
+const DEFAULT_KEY_TTL_SEC = 2592000
 
 export function createKit(cfg = {}) {
   for (const field of REQUIRED) {
     if (!cfg?.[field]) throw new Error(`user-kit: cfg 缺 ${field}`)
   }
-  const finalCfg = cfg.env ? cfg : { ...cfg, env: 'prod' }
+  const finalCfg = { ...cfg, env: cfg.env || 'prod', akDefaultKeyTtlSec: cfg.akDefaultKeyTtlSec ?? DEFAULT_KEY_TTL_SEC }
   const base = createBaseKit(finalCfg)
-  for (const [key, ability] of [...createAuthAbilities(finalCfg, base), ...createUserAbilities(finalCfg, base)]) {
+
+  // §3.7 存储接缝 + §3.6 token 托管 + §3.5 key 域（verify 唯一裁决路径）
+  const runSql = makeRunSql(base)
+  const refreshTokenRequest = makeRefreshTokenRequest(finalCfg, base)
+  const broker = createCbTokenBroker({ cfg: finalCfg, refreshTokenRequest, runSql })
+  const keyDomain = createKeyAbilities({ cfg: finalCfg, runSql })
+  const deps = { broker, runSql, verify: keyDomain.verify, issue: keyDomain.issue, refreshTokenRequest }
+
+  // 宿主经总线消费 broker 的唯一通道（透传前 uid → 托管官方 token）
+  const cbToken = {
+    describe: '托管官方 token 兑换：uid → { access_token, expires_at, from_cache }（宿主透传前取 Bearer）',
+    run: async (args = {}) => {
+      if (!args?.uid) throw Object.assign(new Error('缺少 uid'), { code: 400 })
+      return broker.get(args.uid)
+    },
+  }
+
+  for (const [key, ability] of [...createAuthAbilities(finalCfg, base, deps), ...createUserAbilities(finalCfg, base, deps), ...keyDomain.abilities, ...withSchemas([['auth.cbToken.get', cbToken]])]) {
     base.ctx.register(key, ability)
   }
-  return { ctx: base.ctx, req: base.req, cfg: finalCfg, describe: () => base.ctx.describe() }
+
+  // key 域便捷入口（同 ctx 能力）
+  const key = {
+    create: args => base.ctx.run('auth.key.create', args),
+    list: args => base.ctx.run('auth.key.list', args),
+    revoke: args => base.ctx.run('auth.key.revoke', args),
+    verify: args => base.ctx.run('auth.key.verify', args),
+  }
+
+  return { ctx: base.ctx, req: base.req, cfg: finalCfg, broker, key, describe: () => base.ctx.describe() }
 }
 
 export default createKit

package/src/schemas.js

@@ -1,13 +1,13 @@
 /**
   schemas.js — 能力面元数据（纯数据 · 纯对象 JSON Schema，不引 zod）
 
-  职责: 23 条 user-kit 能力的 title / description / auth / inputSchema / outputSchema / annotations。
+  职责: 22 条在册能力（DC-06：旧 token 刷新能力已注销）的 title / description / auth / inputSchema / outputSchema / annotations。
         能力实现（auth.js / user.js）只负责 run；约束与开放策略集中在这里，挂 MCP 时原样透传。
 
-  auth 分类（浅层认证，token 走 HTTP 头 Authorization: Bearer，服务端注入 args.access_token）:
-    'public'  开放接口，不校验头
-    'user'    需要 Bearer 用户令牌（schema 里不再出现 access_token）
-    'self'    同 user，且 uid 强制取令牌的 JWT.sub（只能操作自己的档案）
+  auth 分类（DC-06：对外凭证统一 apikey；官方令牌由服务端换托管凭证注入 Authorization: Bearer）:
+    'public'  开放接口，不校验凭证
+    'user'    需要 apikey（schema 只暴露 apikey 入参，官方令牌字段不出域）
+    'self'    同 user，且 uid 由 apikey 档案解析（只能操作自己的档案）
     内部能力标 mcp:false —— 不注册为 MCP 工具（登录自动建档 / 部署动作）
 
   取用: withSchemas([[key, ability], ...])
@@ -23,13 +23,14 @@ const obj = (properties = {}, { required = [], anyOf, additionalProperties = tru
   ...(anyOf ? { anyOf } : {}),
   additionalProperties,
 })
-const tokens = {
-  access_token: str('访问令牌（必返）'),
-  refresh_token: str('刷新令牌（必返）'),
-  expires_in: { type: 'number', description: '有效期秒数（必返）' },
+// DC-06 契约：所有登录/注册只出 apikey（官方令牌不出域）
+const apikeyField = str('apikey（必填；a1_ 前缀）')
+const apikeyIn = { apikey: apikeyField }
+const sessionProps = {
+  apikey: str('新签发的 apikey（必返；明文只出现这一次）'),
+  expires_at: { type: 'number', description: 'apikey 过期时间（unix 秒，必返）' },
 }
-const tokenOut = { type: 'object', properties: { ...tokens }, required: ['access_token', 'refresh_token', 'expires_in'] }
-const uidOut = { type: 'object', properties: { uid: str('唯一用户 id（必返）'), access_token: str('访问令牌（必返）') }, required: ['uid', 'access_token'] }
+const sessionOut = { type: 'object', properties: { ...sessionProps }, required: ['apikey', 'expires_at'], additionalProperties: false }
 
 export const SCHEMAS = {
   /* ---------- auth：自定义登录（public） ---------- */
@@ -39,12 +40,9 @@ export const SCHEMAS = {
     description: '用 wx.login 的 code 登录：自动建档并返回会话令牌与下发配置',
     inputSchema: obj({ code: str('wx.login 得到的 code（必填）') }, { required: ['code'], additionalProperties: false }),
     outputSchema: obj({
-      uid: str('唯一用户 id（必返）'),
-      openid: str('微信 openid（必返）'),
-      unionid: { type: ['string', 'null'], description: '微信 unionid，可能为 null（必返）' },
-      ...tokens,
+      ...sessionProps,
       config: { type: 'object', description: 'prefix_config（必返，客户端强依赖）' },
-    }, { required: ['uid', 'openid', 'unionid', 'access_token', 'refresh_token', 'expires_in', 'config'], additionalProperties: false }),
+    }, { required: ['apikey', 'expires_at', 'config'], additionalProperties: false }),
     annotations: { openWorldHint: true },
   },
   'auth.loginByUnionid': {
@@ -52,11 +50,7 @@ export const SCHEMAS = {
     title: '唯一 id 登录',
     description: '用业务唯一 id 直接登录：自动建档并返回会话令牌',
     inputSchema: obj({ unionid: str('调用方唯一用户 id（必填）') }, { required: ['unionid'], additionalProperties: false }),
-    outputSchema: obj({
-      uid: str('唯一用户 id（必返）'),
-      unionid: str('唯一用户 id（必返）'),
-      ...tokens,
-    }, { required: ['uid', 'unionid', 'access_token', 'refresh_token', 'expires_in'], additionalProperties: false }),
+    outputSchema: sessionOut,
     annotations: { openWorldHint: true },
   },
 
@@ -64,25 +58,25 @@ export const SCHEMAS = {
   'auth.loginByPassword': {
     auth: 'public',
     title: '账号密码登录',
-    description: '账号密码登录：返回网关令牌并自动建档',
+    description: '账号密码登录：建档 + 托管官方令牌并签发 apikey',
     inputSchema: obj({ username: str('用户名（必填）'), password: str('密码（必填）') }, { required: ['username', 'password'] }),
-    outputSchema: uidOut,
+    outputSchema: sessionOut,
     annotations: { openWorldHint: true },
   },
   'auth.loginBySms': {
     auth: 'public',
     title: '短信验证码登录',
-    description: '用 verifyCode 换来的 verification_token 登录：返回网关令牌并自动建档',
+    description: '用 verifyCode 换来的 verification_token 登录：建档 + 托管官方令牌并签发 apikey',
     inputSchema: obj({ verification_token: str('verifyCode 得到的令牌（必填）') }, { required: ['verification_token'] }),
-    outputSchema: uidOut,
+    outputSchema: sessionOut,
     annotations: { openWorldHint: true },
   },
   'auth.loginByEmail': {
     auth: 'public',
     title: '邮箱验证码登录',
-    description: '用 verifyCode 换来的 verification_token 登录（邮箱）：返回网关令牌并自动建档',
+    description: '用 verifyCode 换来的 verification_token 登录（邮箱）：建档 + 托管官方令牌并签发 apikey',
     inputSchema: obj({ verification_token: str('verifyCode 得到的令牌（必填）') }, { required: ['verification_token'] }),
-    outputSchema: uidOut,
+    outputSchema: sessionOut,
     annotations: { openWorldHint: true },
   },
   'auth.signup': {
@@ -103,7 +97,7 @@ export const SCHEMAS = {
         { required: ['provider_token'] },
       ],
     }),
-    outputSchema: uidOut,
+    outputSchema: sessionOut,
     annotations: { openWorldHint: true },
   },
 
@@ -150,33 +144,28 @@ export const SCHEMAS = {
     title: '敏感操作二次验证',
     description: '改密码/注销前的二次验证：向当前用户发送验证码',
     inputSchema: obj({
+      ...apikeyIn,
       verify_opt: { type: 'string', enum: ['phone_code', 'email_code'], description: '验证方式（必填）' },
-    }, { required: ['verify_opt'], additionalProperties: false }),
+    }, { required: ['apikey', 'verify_opt'], additionalProperties: false }),
     outputSchema: obj({ verification_id: str('验证码会话 id（必返）') }),
   },
   'auth.introspect': {
     auth: 'user',
     title: '校验令牌',
-    description: '校验当前 Bearer 令牌是否有效，返回用户 sub',
-    inputSchema: obj({}, { additionalProperties: false }),
+    description: '校验当前 apikey 对应的官方令牌是否有效，返回用户 sub',
+    inputSchema: obj({ ...apikeyIn }, { required: ['apikey'], additionalProperties: false }),
     outputSchema: obj({ sub: str('令牌对应的用户 id'), active: { type: 'boolean', description: '是否有效' } }),
     annotations: { readOnlyHint: true, openWorldHint: true },
   },
-  'auth.refresh': {
-    auth: 'public',
-    title: '刷新令牌',
-    description: '用 refresh_token 换一对新令牌',
-    inputSchema: obj({ refresh_token: str('刷新令牌（必填）') }, { required: ['refresh_token'], additionalProperties: false }),
-    outputSchema: tokenOut,
-  },
   'auth.signOut': {
     auth: 'user',
     title: '退出登录',
     description: '退出当前会话（令牌作废）',
     inputSchema: obj({
+      ...apikeyIn,
       client_id: str('客户端 id（可选，默认环境 id）'),
       x_device_id: str('设备 id（可选）'),
-    }, { additionalProperties: true }),
+    }, { required: ['apikey'], additionalProperties: true }),
     outputSchema: { type: 'object', description: '网关响应（通常为空对象）' },
     annotations: { destructiveHint: true },
   },
@@ -244,7 +233,7 @@ export const SCHEMAS = {
     auth: 'user',
     title: '当前用户',
     description: '读取网关侧当前用户信息（资料 / 绑定 / 角色）',
-    inputSchema: obj({}, { additionalProperties: false }),
+    inputSchema: obj({ ...apikeyIn }, { required: ['apikey'], additionalProperties: false }),
     outputSchema: { type: 'object', description: '网关用户信息（原样）' },
     annotations: { readOnlyHint: true },
   },
@@ -253,6 +242,7 @@ export const SCHEMAS = {
     title: '修改资料（含手机号/邮箱）',
     description: '修改网关侧用户资料；改手机号/邮箱需先 reauthenticate 拿验证码令牌；成功后自动同步本地档案',
     inputSchema: obj({
+      ...apikeyIn,
       nickname: str('昵称（可选）'),
       username: str('用户名（可选）'),
       phone: str('手机号（可选，修改需验证码）'),
@@ -261,7 +251,7 @@ export const SCHEMAS = {
       gender: { type: 'string', enum: ['MALE', 'FEMALE'], description: '性别（可选）' },
       description: str('个人简介（可选）'),
       verification_token: str('手机号/邮箱变更的验证码令牌（可选，改手机/邮箱时需要）'),
-    }, { additionalProperties: true }),
+    }, { required: ['apikey'], additionalProperties: true }),
     outputSchema: { type: 'object', description: '网关响应（原样）' },
   },
   'user.changePassword': {
@@ -269,9 +259,10 @@ export const SCHEMAS = {
     title: '修改密码',
     description: '修改当前用户密码（需先 reauthenticate 二次验证）',
     inputSchema: obj({
+      ...apikeyIn,
       password: str('新密码（必填）'),
       verification_token: str('二次验证令牌（可选，按网关要求）'),
-    }, { required: ['password'] }),
+    }, { required: ['apikey', 'password'] }),
     outputSchema: { type: 'object', description: '网关响应（通常为空对象）' },
     annotations: { destructiveHint: true },
   },
@@ -280,11 +271,62 @@ export const SCHEMAS = {
     title: '注销账号',
     description: '注销当前用户（需先 reauthenticate 二次验证）',
     inputSchema: obj({
+      ...apikeyIn,
       verification_token: str('二次验证令牌（可选，按网关要求）'),
-    }, { additionalProperties: true }),
+    }, { required: ['apikey'], additionalProperties: true }),
     outputSchema: { type: 'object', description: '网关响应（通常为空对象）' },
     annotations: { destructiveHint: true },
   },
+
+  /* ---------- key 域（DC-06）+ cbToken（mcp:false：宿主能力，挂 MCP = 可冒充任意 uid 兑官方 token） ---------- */
+  'auth.key.create': {
+    auth: 'user',
+    title: '签发新 apikey',
+    description: '用当前 apikey 换 uid 再签发一个新 apikey（多设备/多场景）；key 明文只在本次响应出现一次',
+    inputSchema: obj({ apikey: str('当前 apikey（必填）'), scene: str('场景标签（可选，缺省空串）') }, { required: ['apikey'], additionalProperties: false }),
+    outputSchema: obj({
+      apikey: str('新 apikey 明文（必返，仅此一次）'),
+      key_id: str('key id（吊销/list 句柄）'),
+      key_prefix: str('前 11 字符识别段（不含敏感信息）'),
+      expires_at: { type: 'number', description: '过期 unix 秒' },
+    }, { required: ['apikey', 'key_id', 'key_prefix', 'expires_at'], additionalProperties: false }),
+  },
+  'auth.key.list': {
+    auth: 'user',
+    title: '列出我的 apikey',
+    description: '当前 apikey 所属用户的全部 key 档案（不含 key 明文）',
+    inputSchema: obj({ apikey: str('当前 apikey（必填）') }, { required: ['apikey'], additionalProperties: false }),
+    outputSchema: { type: 'array', description: 'key 档案行数组（key_id/key_prefix/scene/created_at/expires_at/revoked_at）' },
+    annotations: { readOnlyHint: true },
+  },
+  'auth.key.revoke': {
+    auth: 'user',
+    title: '吊销 apikey',
+    description: '吊销本用户名下的指定 key（即时生效）',
+    inputSchema: obj({ apikey: str('当前 apikey（必填）'), key_id: str('要吊销的 key id（必填）') }, { required: ['apikey', 'key_id'], additionalProperties: false }),
+    outputSchema: obj({ revoked: { type: 'boolean', description: '是否成功' }, key_id: str('被吊销的 key id') }, { required: ['revoked', 'key_id'], additionalProperties: false }),
+    annotations: { destructiveHint: true },
+  },
+  'auth.key.verify': {
+    auth: 'public',
+    title: '验证 apikey',
+    description: '验证 apikey 合法性：通过返回 { ok, auth }，失败返回 { ok:false, reason }',
+    inputSchema: obj({ apikey: str('待验证的 apikey（必填）') }, { required: ['apikey'], additionalProperties: false }),
+    outputSchema: { type: 'object', description: 'verify 结果（ok/auth 或 ok/reason）' },
+    annotations: { readOnlyHint: true },
+  },
+  'auth.cbToken.get': {
+    mcp: false,
+    auth: 'user',
+    title: '官方 token 托管兑换',
+    description: 'uid → 托管官方 access_token（宿主透传专用；不挂 MCP）',
+    inputSchema: obj({ uid: uidField }, { required: ['uid'], additionalProperties: false }),
+    outputSchema: obj({
+      access_token: str('官方 access_token'),
+      expires_at: { type: 'number', description: '过期 unix 秒' },
+      from_cache: { type: 'boolean', description: '是否命中托管缓存' },
+    }, { required: ['access_token', 'expires_at', 'from_cache'], additionalProperties: false }),
+  },
 }
 
 /** 把元数据合并进 [key, ability] 列表（能力对象原样保留 describe/run） */

package/src/token-broker.js

@@ -0,0 +1,62 @@
+/**
+ * token-broker.js — 官方 token 托管（单飞刷新 · spec §3.6 · §3.7）
+ *
+ * 职责: get(uid) 查 __user_token_cache → 未过期直返；过期则单飞刷新（实例内 Map<uid, Promise>）→ 回写；
+ *       upsert(uid, access_token, refresh_token, expiresAt) 供登录收尾落库；markInvalid(uid) 删行。
+ * 失败语义: 刷新失败/无行 → 删行 + 401「官方凭证已失效，请重新登录」（fail-closed，refresh_token 不出域）。
+ * 接缝: runSql=kit.ctx.run('pg.exec',…) 封装（§3.7 唯一表读写入口；未来换后端只换适配器）。
+ * 禁止: 档案表（__user_access_key）读写——那是 access-key.js 的地盘。
+ */
+const SQL_SELECT = 'SELECT uid, access_token, refresh_token, expires_at FROM __user_token_cache WHERE uid=$1'
+const SQL_UPSERT = `INSERT INTO __user_token_cache (uid, access_token, refresh_token, expires_at)
+     VALUES ($1, $2, $3, $4)
+     ON CONFLICT (uid) DO UPDATE SET access_token = EXCLUDED.access_token,
+       refresh_token = EXCLUDED.refresh_token, expires_at = EXCLUDED.expires_at, updated_at = now()`
+const SQL_DELETE = 'DELETE FROM __user_token_cache WHERE uid=$1'
+
+const err = (code, message) => Object.assign(new Error(message), { code })
+const nowSec = () => Math.floor(Date.now() / 1000)
+
+/** pg 适配器：全包唯一表读写接缝（kit.ctx.run('pg.exec') + cloudbase_postgres 角色） */
+export const makeRunSql = kit => (sql, parameters = []) =>
+  kit.ctx.run('pg.exec', { sql, parameters, role: 'cloudbase_postgres' })
+
+export function createCbTokenBroker({ cfg, refreshTokenRequest, runSql }) {
+  const inflight = new Map()   // uid → Promise（实例内单飞；跨实例靠 DB 幂等写兜底）
+
+  // 单飞刷新：失败删行 + 401；成功回写（expires_at=now+expires_in）
+  async function refresh(uid, row) {
+    let res
+    try {
+      res = await refreshTokenRequest({ grant_type: 'refresh_token', refresh_token: row.refresh_token, client_id: cfg.envId })
+    } catch {
+      await runSql(SQL_DELETE, [uid]).catch(() => {})
+      throw err(401, '官方凭证已失效，请重新登录')
+    }
+    const expiresAt = nowSec() + (Number(res?.expires_in) || 0)
+    await runSql(SQL_UPSERT, [uid, res.access_token, res.refresh_token, expiresAt])
+    return { access_token: res.access_token, expires_at: expiresAt, from_cache: false }
+  }
+
+  async function get(uid) {
+    const rows = await runSql(SQL_SELECT, [uid])
+    const row = rows?.[0]
+    if (row && Number(row.expires_at) > nowSec()) {
+      return { access_token: row.access_token, expires_at: Number(row.expires_at), from_cache: true }
+    }
+    if (!row) throw err(401, '官方凭证已失效，请重新登录')   // 无行 = 从未托管/已失效，无可刷新
+    if (inflight.has(uid)) return inflight.get(uid)
+    const task = refresh(uid, row).finally(() => inflight.delete(uid))
+    inflight.set(uid, task)
+    return task
+  }
+
+  const upsert = async (uid, access_token, refresh_token, expiresAt) => {
+    await runSql(SQL_UPSERT, [uid, access_token, refresh_token, expiresAt])
+    return { uid, expires_at: expiresAt }
+  }
+
+  const markInvalid = async uid => { await runSql(SQL_DELETE, [uid]); return { uid } }
+
+  return { get, upsert, markInvalid }
+}

package/src/user.js

@@ -14,11 +14,11 @@
  *
  * token 面（4 条，网关透传不裁剪；inject.gateway(method, path, { body, token }) 统一覆盖）:
  *   user.me — GET；user.updateBasic — POST /auth/v1/user/basic/edit（body 只发传入字段，
- *     成功 → patchProfile({ uid: JWT.sub, patch: 可入档字段 })，verification_token 不入档）；
- *   user.changePassword PATCH /auth/v1/user/password；user.deleteMe DELETE /auth/v1/user/me；user.signOut 不写档。
+ *     成功 → patchProfile({ uid: verify.uidRef, patch: 可入档字段 })，verification_token 不入档）；
+ *   user.changePassword PATCH /auth/v1/user/password；user.deleteMe DELETE /auth/v1/user/me。
  *
- * 硬规则（§3.9/§3.10）: token 类能力 uid 一律从 access_token 的 JWT.sub 取（不验签），**不接收调用方传 uid**
- *   防越权；解码失败 → 400「access_token 无效」。changePassword/deleteMe/signOut 不自动写档（身份面与业务档解耦）。
+ * 硬规则（§3.3）: token 类能力入参 access_token → apikey；统一序 verify(apikey) → 401「apikey 无效」→
+ *   broker.get(uid) → 官方 Bearer；**不接收调用方传 uid** 防越权。changePassword/deleteMe 不自动写档。
  *
  * 数据流: 入参（uid 校验/token 解码）→ gateway 网关原样 / build*Query → ctx.run('pg.exec',
  *         { sql, parameters, role:'cloudbase_postgres' })；网关非 2xx → { code: 网关状态, payload } 原样，
@@ -27,6 +27,7 @@
  */
 
 import { withSchemas } from './schemas.js'
+import { DDL_USER_TOKEN_CACHE, DDL_USER_ACCESS_KEY, DDL_USER_ACCESS_KEY_INDEX } from './access-key.js'
 
 const DEFAULT_DOMAIN = 'api.tcloudbasegateway.com'
 
@@ -115,8 +116,8 @@ export function buildPatchProfileQuery(uid, patch) {
   }
 }
 
-/* —— schema 面（§3.11 · DDL 逐字来源 apps/wx-mp-fn/db/schema.full.sql L164/L536/L540，全 if not exists）—— */
-const PROBE_TABLE = `select to_regclass('public.crm_user_detail') is not null as "exists"`
+/* —— schema 面（§3.11 建档表 + §3.1 两张新表；DDL 全 if not exists，先探后建）—— */
+const PROBE_TABLE = `select to_regclass('public.crm_user_detail') is not null as "table", to_regclass('public.__user_token_cache') is not null as "token_cache", to_regclass('public.__user_access_key') is not null as "access_key"`
 const PROBE_INDEXES = `select indexname from pg_indexes where schemaname='public' and tablename='crm_user_detail'`
 const PROBE_PKEY = `select 1 from pg_constraint where conrelid='public.crm_user_detail'::regclass and contype='p'`
 const DDL_TABLE = `create table if not exists public.crm_user_detail (id uuid default gen_random_uuid() not null, ns text[] not null, data jsonb default '{}'::jsonb not null, ext jsonb, tag text[] default '{}'::text[], status text default 'active' not null, created_at timestamptz default now() not null, updated_at timestamptz default now() not null, deleted_at timestamptz)`
@@ -133,16 +134,27 @@ const INDEX_ORDER = ['idx_crm_user_detail_ns_unique', 'idx_crm_user_detail_ns',
 const EDIT_BODY = ['nickname', 'username', 'phone', 'email', 'avatar_url', 'gender', 'description', 'verification_token']
 const ARCHIVABLE = ['nickname', 'username', 'phone', 'email', 'avatar_url', 'gender', 'description']
 
-export function createUserAbilities(cfg, kit) {
+// deps（index.js 注入）: verify（apikey 裁决）/ broker（token 托管，官方 Bearer 来源）
+export function createUserAbilities(cfg, kit, deps = {}) {
   const gateway = makeGateway(cfg, kit)
   // 网关调用统一翻错（非 2xx 原样 / 网络 502）
   const gw = async (method, path, opts) => { try { return await gateway(method, path, opts) } catch (e) { throwGatewayError(e) } }
+  // 凭证类统一序（§3.3）：verify(apikey) → 401 → broker.get(uid) → 官方 Bearer
+  const sessionOf = async apikey => {
+    const v = await deps.verify(apikey)
+    if (!v.ok) throw Object.assign(new Error('apikey 无效'), { code: 401 })
+    const token = await deps.broker.get(v.auth.uidRef)
+    return { uid: v.auth.uidRef, access_token: token.access_token }
+  }
   const pg = q => kit.ctx.run('pg.exec', { sql: q.sql, parameters: q.parameters, role: 'cloudbase_postgres' })
   // 探测：表在不在 / 四索引在不在 / 主键在不在（只读，三次 pg.exec）
   const probe = async () => {
     const [t, i, k] = [await pg({ sql: PROBE_TABLE, parameters: [] }), await pg({ sql: PROBE_INDEXES, parameters: [] }), await pg({ sql: PROBE_PKEY, parameters: [] })]
     const names = new Set(i.map(r => r.indexname))
-    return { table: !!t[0]?.exists, indexes: Object.fromEntries(INDEX_ORDER.map(n => [n, names.has(n)])), primaryKey: k.length > 0 }
+    return {
+      table: !!t[0]?.table, tokenCache: !!t[0]?.token_cache, accessKey: !!t[0]?.access_key,
+      indexes: Object.fromEntries(INDEX_ORDER.map(n => [n, names.has(n)])), primaryKey: k.length > 0,
+    }
   }
 
   return withSchemas([
@@ -171,17 +183,17 @@ export function createUserAbilities(cfg, kit) {
       throw Object.assign(new Error('用户不可用'), { code: 403 })
     } }],
 
-    /* token 面（网关透传；uid 只认 JWT.sub） */
-    ['user.me', { describe: '当前用户（资料/绑定/角色）：GET /auth/v1/user/me，网关原样', run: async ({ access_token } = {}) => {
-      uidFromToken(access_token)
+    /* token 面（网关透传；身份 = apikey → verify.uidRef → broker 托管 token） */
+    ['user.me', { describe: '当前用户（资料/绑定/角色）：GET /auth/v1/user/me，网关原样', run: async ({ apikey } = {}) => {
+      const { access_token } = await sessionOf(apikey)
       return gw('GET', '/auth/v1/user/me', { token: access_token })
     } }],
 
     ['user.updateBasic', { describe: '资料/手机/邮箱变更：POST /auth/v1/user/basic/edit（body 只发传入字段）→ 成功 patchProfile', run: async (args = {}) => {
-      const uid = uidFromToken(args.access_token)
+      const { uid, access_token } = await sessionOf(args.apikey)
       const body = {}
       for (const k of EDIT_BODY) if (args[k] !== undefined) body[k] = args[k]
-      const payload = await gw('POST', '/auth/v1/user/basic/edit', { body, token: args.access_token })
+      const payload = await gw('POST', '/auth/v1/user/basic/edit', { body, token: access_token })
       const patch = {}
       for (const k of ARCHIVABLE) if (k in body) patch[k] = body[k]    // verification_token 不入档
       await kit.ctx.run('user.patchProfile', { uid, patch })
@@ -189,14 +201,14 @@ export function createUserAbilities(cfg, kit) {
     } }],
 
     ['user.changePassword', { describe: '改密（前置 reauthenticate）：PATCH /auth/v1/user/password，网关原样（不写档）', run: async (args = {}) => {
-      const { access_token, ...rest } = args
-      uidFromToken(access_token)
+      const { apikey, ...rest } = args
+      const { access_token } = await sessionOf(apikey)
       return gw('PATCH', '/auth/v1/user/password', { body: rest, token: access_token })
     } }],
 
     ['user.deleteMe', { describe: '删号（前置 reauthenticate）：DELETE /auth/v1/user/me，网关原样（不自行标删/不写档）', run: async (args = {}) => {
-      const { access_token, ...rest } = args
-      uidFromToken(access_token)
+      const { apikey, ...rest } = args
+      const { access_token } = await sessionOf(apikey)
       return gw('DELETE', '/auth/v1/user/me', { body: rest, token: access_token })
     } }],
 
@@ -207,6 +219,8 @@ export function createUserAbilities(cfg, kit) {
       const before = await probe()
       const plan = []
       if (!before.table) plan.push(DDL_TABLE)
+      if (!before.tokenCache) plan.push(DDL_USER_TOKEN_CACHE)         // §3.1 token 托管表
+      if (!before.accessKey) plan.push(DDL_USER_ACCESS_KEY, DDL_USER_ACCESS_KEY_INDEX)   // §3.1 key 档案表 + uid 索引
       if (!before.primaryKey) plan.push(DDL_PKEY)                     // 主键仅缺失时补（alter 无 if not exists）
       const missing = INDEX_ORDER.filter(n => !before.indexes[n])
       for (const name of missing) plan.push(DDL_INDEXES[name])
@@ -215,7 +229,13 @@ export function createUserAbilities(cfg, kit) {
           throw e?.status ? Object.assign(new Error(e.message), { code: e.status, payload: e.payload }) : e   // 原样透传
         }
       }
-      return { table: before.table ? 'exists' : 'created', indexes: { created: missing, existing: INDEX_ORDER.filter(n => !missing.includes(n)) }, status: await probe() }
+      return {
+        table: before.table ? 'exists' : 'created',
+        tokenCache: before.tokenCache ? 'exists' : 'created',
+        accessKey: before.accessKey ? 'exists' : 'created',
+        indexes: { created: missing, existing: INDEX_ORDER.filter(n => !missing.includes(n)) },
+        status: await probe(),
+      }
     } }],
   ])
 }