@blod-nm/user-kit 0.1.6 → 0.1.8

package/src/auth.js

@@ -1,229 +0,0 @@
-/**
- * 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（响应原样）
- *   POST /auth/v1/signin { username,password | verification_token } → 基础登录（响应原样 + 补 uid + 建档）
- *   POST /auth/v1/signin/custom { provider_id:'custom', ticket }    → 自定义登录（uid 链收尾）
- *   POST /auth/v1/token { grant_type:'refresh_token', refresh_token, client_id:envId }
- *   POST /auth/v1/verification/verify { verification_id, verification_code } → verification_token
- *   POST /auth/v1/user/reauthenticate（Bearer）；GET /auth/v1/token/introspect（Bearer）
- *
- * 语义:
- *   · 透传三种（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（手机/邮箱验证码注册，建档+托管+签发 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「用户注册失败」。凭证类能力（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 ——
- *   返回一律网关原样；错误走 throwGatewayError（非 2xx 原样 / 网络 502「登录请求失败」）。
- *
- * 注入面（9 个，缺省=真实现，单测零网络）: sendVerification / signinRequest / code2Session / wxResolveUid /
- *   createTicket / customSignin / refreshTokenRequest / fetchPrefixConfig / gateway(method, path, opts)。
- * @cloudbase/node-sdk（ticket 签发，Node 侧）只在本文件 import（A3 grep 白名单）。
- */
-import cloudbase from '@cloudbase/node-sdk'
-import { code2Session as wxCode2Session } from './wechat.js'
-import { decodeJWT, throwGatewayError, makeGateway } from './user.js'
-import { withSchemas } from './schemas.js'
-
-export { decodeJWT }   // 供消费方/测试从包主入口取（真身在 user.js）
-
-const DEFAULT_DOMAIN = 'api.tcloudbasegateway.com'
-const TICKET_TTL = { refresh: 7 * 24 * 3600 * 1000, expire: 30 * 24 * 3600 * 1000 }
-const err = (code, message, extra = {}) => Object.assign(new Error(message), { code, ...extra })
-
-/* —— tcb 私钥/票（懒加载缓存；私钥只在内存解析，不落日志）—— */
-
-export async function loadCredentials(raw, envId) {
-  const value = String(raw || '').trim()
-  if (!value) throw new Error('缺少自定义登录私钥：tcbAuthCredentials（JSON 文案或文件路径，按 { 开头自动识别）')
-  // 文件路径形态用动态 import 取 fs（保持静态 import 面干净；spec 允许两种形态）
-  const text = value.startsWith('{') ? value : await (await import('node:fs/promises')).readFile(value, 'utf-8')
-  const credentials = JSON.parse(text)
-  // 控制台下载的私钥字段名 private_key_id → SDK 需要 key_id；短形态缺 env_id 段用 cfg.envId 补
-  if ('private_key_id' in credentials && !('key_id' in credentials)) credentials.key_id = credentials.private_key_id
-  if (!credentials.key_id || !credentials.private_key) throw new Error('credentials must include key_id and private_key')
-  if (!credentials.env_id) credentials.env_id = envId
-  return credentials
-}
-
-let tcbAppCache = null
-async function tcbCreateTicket(cfg, uid) {
-  if (!tcbAppCache) {
-    const credentials = await loadCredentials(cfg.tcbAuthCredentials, cfg.envId)
-    tcbAppCache = cloudbase.init({ env: credentials.env_id, credentials })
-  }
-  // ★ TTL 与现网一字不差（refresh 7d / expire 30d，相对毫秒；gateway 对这两个值有兜底解释，改了就变）
-  return tcbAppCache.auth().createTicket(uid, TICKET_TTL)
-}
-
-/* —— 能力目录 + 编排（ability 闭包持有 cfg/inject/kit/deps）—— */
-
-// 刷新请求器：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 }))
-  const signinRequest = inject.signinRequest || (body => kit.req(`${origin}/auth/v1/signin`, { method: 'POST', body }))
-  const customSignin = inject.customSignin || (ticket => kit.req(`${origin}/auth/v1/signin/custom`, { method: 'POST', body: { provider_id: 'custom', ticket } }))
-  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 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) } }
-  // verification 端点：旧注入口优先（sendSmsCode/sendEmailCode/sendVerification 共用）
-  const postVerification = body => inject.sendVerification ? inject.sendVerification(body) : gw('POST', '/auth/v1/verification', { body })
-
-  // 自定义链收尾（wxcode / unionid 共用）：createTicket → signin/custom
-  async function finishLogin(uid) {
-    const ticket = await createTicket(uid)
-    let res
-    try { res = await customSignin(ticket) } catch { throw err(502, '自定义登录请求失败') }
-    const { access_token: at, refresh_token: rt, expires_in } = res
-    return { at, rt, expires_in }   // 仅内部传递；官方 token 不出域
-  }
-
-  // 建档统一翻 500「用户注册失败」
-  async function upsertOr500(args) {
-    try { await kit.ctx.run('user.upsert', args) } catch { throw err(500, '用户注册失败') }
-  }
-
-  // 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
-
-  // 登录收尾（§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} 必填`)
-    }
-    let payload
-    try { payload = await signinRequest(body) } catch (e) { throwGatewayError(e) }
-    const uid = uidOfPayload(payload)
-    if (!uid) throw err(500, '用户注册失败')
-    await upsertOr500({ uid, profile: {} })
-    return issueSession(uid, payload)
-  }
-
-  return withSchemas([
-    ['auth.sendVerification', { describe: '发验证码（phone/email 二选一）：POST /auth/v1/verification，网关原样（含 verification_token）', run: async (args = {}) => {
-      const body = {}
-      for (const k of ['phone', 'email', 'email_redirect_to']) if (args[k] !== undefined) body[k] = args[k]
-      if (!body.phone && !body.email) throw err(400, 'phone 或 email 二选一必填')
-      return postVerification(body)
-    } }],
-
-    ['auth.sendSmsCode', { describe: '发短信验证码：sendVerification 薄别名（phone 必填）', run: async ({ phone } = {}) => {
-      if (!phone) throw err(400, 'phone 必填')
-      return postVerification({ phone })
-    } }],
-
-    ['auth.sendEmailCode', { describe: '发邮箱验证码：sendVerification 薄别名（email 必填）', run: async ({ email } = {}) => {
-      if (!email) throw err(400, 'email 必填')
-      return postVerification({ email })
-    } }],
-
-    ['auth.verifyCode', { describe: '验证码校验：POST /auth/v1/verification/verify，网关原样（含 verification_token）', run: async ({ verification_id, verification_code } = {}) => {
-      if (!verification_id) throw err(400, 'verification_id 必填')
-      if (!verification_code) throw err(400, 'verification_code 必填')
-      return gw('POST', '/auth/v1/verification/verify', { body: { verification_id, verification_code } })
-    } }],
-
-    ['auth.reauthenticate', { describe: '重认证发码：POST /auth/v1/user/reauthenticate（Bearer；verify_opt ∈ phone_code|email_code）', run: async (args = {}) => {
-      const { apikey, verify_opt } = args
-      if (!['phone_code', 'email_code'].includes(verify_opt)) throw err(400, 'verify_opt 必填（phone_code|email_code）')
-      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 ({ 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']) }],
-
-    ['auth.loginBySms', { describe: '短信验证码登录（透传+建档）：POST /auth/v1/signin { verification_token }', run: async (args = {}) => passthroughLogin({ verification_token: args.verification_token }, ['verification_token']) }],
-
-    ['auth.loginByEmail', { describe: '邮箱验证码登录（与 SMS 同端点同实现，命名只表达调用意图）', run: async (args = {}) => passthroughLogin({ verification_token: args.verification_token }, ['verification_token']) }],
-
-    ['auth.loginByWxcode', { describe: '微信 code 登录全链：建档+自定义令牌+prefix_config（7 字段裸对象）', run: async (args = {}) => {
-      const { code } = args
-      if (!code || typeof code !== 'string') throw err(400, 'user-kit: 参数 code 必填')
-      let wx
-      try { wx = await code2Session(code) } catch { throw err(502, 'code2Session 请求失败') }
-      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 } })
-      const session = await issueSession(uid, await finishLogin(uid))
-      return { ...session, config: await fetchPrefixConfig() }
-    } }],
-
-    ['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 issueSession(unionid, await finishLogin(unionid))
-    } }],
-
-    ['auth.signup', { describe: '注册（手机/邮箱/provider_token 三形态）：POST /auth/v1/signup，响应原样+补 uid+建档', run: async (args = {}) => {
-      // 三种形态：手机号+验证码 / 邮箱+验证码 / provider_token（第三方授权注册）
-      const codePath = !!(args?.phone_number || args?.email)
-      if (codePath && !args?.verification_token) throw err(400, 'verification_token 必填')
-      if (!codePath && !args?.provider_token) throw err(400, 'phone_number/email/provider_token 必填其一')
-      const payload = await gw('POST', '/auth/v1/signup', { body: args })
-      const uid = uidOfPayload(payload)
-      if (!uid) throw err(500, '用户注册失败')
-      const profile = {}   // 建档只放传入的可入档字段（username/email/phone 有则带），不编造
-      if (args.username !== undefined) profile.username = args.username
-      if (args.email !== undefined) profile.email = args.email
-      if (args.phone_number !== undefined) profile.phone = args.phone_number
-      await upsertOr500({ uid, profile })
-      return issueSession(uid, payload)
-    } }],
-
-    ['auth.signOut', { describe: '登出：POST /auth/v1/user/signout（Bearer），不写档', run: async (args = {}) => {
-      const { apikey, ...rest } = args ?? {}
-      const { token } = await sessionOf(apikey)
-      return gw('POST', '/auth/v1/user/signout', { body: rest, token })
-    } }],
-  ])
-}

package/src/index.js

@@ -1,70 +0,0 @@
-/**
- * user-kit — user/auth 域能力套件（base-cb 装载叠加 → Ctx 总线）
- *
- * 主出口（应用型）:
- *   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.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）→ 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）；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, 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.env || 'prod', akDefaultKeyTtlSec: cfg.akDefaultKeyTtlSec ?? DEFAULT_KEY_TTL_SEC }
-  const base = createBaseKit(finalCfg)
-
-  // §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)
-  }
-
-  // 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,333 +0,0 @@
-/**
-  schemas.js — 能力面元数据（纯数据 · 纯对象 JSON Schema，不引 zod）
-
-  职责: 22 条在册能力（DC-06：旧 token 刷新能力已注销）的 title / description / auth / inputSchema / outputSchema / annotations。
-        能力实现（auth.js / user.js）只负责 run；约束与开放策略集中在这里，挂 MCP 时原样透传。
-
-  auth 分类（DC-06：对外凭证统一 apikey；官方令牌由服务端换托管凭证注入 Authorization: Bearer）:
-    'public'  开放接口，不校验凭证
-    'user'    需要 apikey（schema 只暴露 apikey 入参，官方令牌字段不出域）
-    'self'    同 user，且 uid 由 apikey 档案解析（只能操作自己的档案）
-    内部能力标 mcp:false —— 不注册为 MCP 工具（登录自动建档 / 部署动作）
-
-  取用: withSchemas([[key, ability], ...])
-*/
-const str = (description, extra = {}) => ({ type: 'string', description, ...extra })
-// 与 assertUid 运行时规则一致：≤128 字符、无控制字符
-const uidField = { type: 'string', description: '唯一用户 id（≤128 字符，不含控制字符）', maxLength: 128, pattern: '^[^\\u0000-\\u001f\\u007f]+$' }
-const freeObj = description => ({ type: 'object', description, additionalProperties: true })
-const obj = (properties = {}, { required = [], anyOf, additionalProperties = true } = {}) => ({
-  type: 'object',
-  properties,
-  ...(required.length ? { required } : {}),
-  ...(anyOf ? { anyOf } : {}),
-  additionalProperties,
-})
-// 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 sessionOut = { type: 'object', properties: { ...sessionProps }, required: ['apikey', 'expires_at'], additionalProperties: false }
-
-export const SCHEMAS = {
-  /* ---------- auth：自定义登录（public） ---------- */
-  'auth.loginByWxcode': {
-    auth: 'public',
-    title: '微信小程序登录',
-    description: '用 wx.login 的 code 登录：自动建档并返回会话令牌与下发配置',
-    inputSchema: obj({ code: str('wx.login 得到的 code（必填）') }, { required: ['code'], additionalProperties: false }),
-    outputSchema: obj({
-      ...sessionProps,
-      config: { type: 'object', description: 'prefix_config（必返，客户端强依赖）' },
-    }, { required: ['apikey', 'expires_at', 'config'], additionalProperties: false }),
-    annotations: { openWorldHint: true },
-  },
-  'auth.loginByUnionid': {
-    auth: 'public',
-    title: '唯一 id 登录',
-    description: '用业务唯一 id 直接登录：自动建档并返回会话令牌',
-    inputSchema: obj({ unionid: str('调用方唯一用户 id（必填）') }, { required: ['unionid'], additionalProperties: false }),
-    outputSchema: sessionOut,
-    annotations: { openWorldHint: true },
-  },
-
-  /* ---------- auth：透传登录（public） ---------- */
-  'auth.loginByPassword': {
-    auth: 'public',
-    title: '账号密码登录',
-    description: '账号密码登录：建档 + 托管官方令牌并签发 apikey',
-    inputSchema: obj({ username: str('用户名（必填）'), password: str('密码（必填）') }, { required: ['username', 'password'] }),
-    outputSchema: sessionOut,
-    annotations: { openWorldHint: true },
-  },
-  'auth.loginBySms': {
-    auth: 'public',
-    title: '短信验证码登录',
-    description: '用 verifyCode 换来的 verification_token 登录：建档 + 托管官方令牌并签发 apikey',
-    inputSchema: obj({ verification_token: str('verifyCode 得到的令牌（必填）') }, { required: ['verification_token'] }),
-    outputSchema: sessionOut,
-    annotations: { openWorldHint: true },
-  },
-  'auth.loginByEmail': {
-    auth: 'public',
-    title: '邮箱验证码登录',
-    description: '用 verifyCode 换来的 verification_token 登录（邮箱）：建档 + 托管官方令牌并签发 apikey',
-    inputSchema: obj({ verification_token: str('verifyCode 得到的令牌（必填）') }, { required: ['verification_token'] }),
-    outputSchema: sessionOut,
-    annotations: { openWorldHint: true },
-  },
-  'auth.signup': {
-    auth: 'public',
-    title: '注册',
-    description: '注册新用户：手机号+验证码 / 邮箱+验证码 / 第三方 provider_token 三选一，自动建档',
-    inputSchema: obj({
-      phone_number: str('手机号（与 email / provider_token 三选一）'),
-      email: str('邮箱（与 phone_number / provider_token 三选一）'),
-      provider_token: str('第三方 provider_token（三选一；与验证码方式互斥）'),
-      verification_token: str('验证码令牌（手机/邮箱方式必填；provider_token 方式不需要）'),
-      username: str('用户名（可选）'),
-      password: str('密码（可选）'),
-    }, {
-      anyOf: [
-        { required: ['verification_token', 'phone_number'] },
-        { required: ['verification_token', 'email'] },
-        { required: ['provider_token'] },
-      ],
-    }),
-    outputSchema: sessionOut,
-    annotations: { openWorldHint: true },
-  },
-
-  /* ---------- auth：验证码（public） ---------- */
-  'auth.sendVerification': {
-    auth: 'public',
-    title: '发送验证码',
-    description: '向手机号或邮箱发送验证码（二选一）',
-    inputSchema: obj({
-      phone: str('手机号（与 email 二选一）'),
-      email: str('邮箱（与 phone 二选一）'),
-      email_redirect_to: str('Magic Link 跳转地址（可选，仅邮箱）'),
-    }, { anyOf: [{ required: ['phone'] }, { required: ['email'] }] }),
-    outputSchema: obj({ verification_id: str('验证码会话 id（必返）') }, { required: ['verification_id'] }),
-  },
-  'auth.sendSmsCode': {
-    auth: 'public',
-    title: '发送短信验证码',
-    description: '向手机号发送短信验证码',
-    inputSchema: obj({ phone: str('手机号（必填）') }, { required: ['phone'], additionalProperties: false }),
-    outputSchema: obj({ verification_id: str('验证码会话 id（必返）') }, { required: ['verification_id'] }),
-  },
-  'auth.sendEmailCode': {
-    auth: 'public',
-    title: '发送邮箱验证码',
-    description: '向邮箱发送验证码',
-    inputSchema: obj({ email: str('邮箱（必填）') }, { required: ['email'], additionalProperties: false }),
-    outputSchema: obj({ verification_id: str('验证码会话 id（必返）') }, { required: ['verification_id'] }),
-  },
-  'auth.verifyCode': {
-    auth: 'public',
-    title: '校验验证码',
-    description: '校验用户输入的验证码，换取登录用的 verification_token',
-    inputSchema: obj({
-      verification_id: str('验证码会话 id（必填）'),
-      verification_code: str('用户输入的验证码（必填）'),
-    }, { required: ['verification_id', 'verification_code'], additionalProperties: false }),
-    outputSchema: obj({ verification_token: str('验证码令牌（必返）') }, { required: ['verification_token'] }),
-  },
-
-  /* ---------- auth：会话 ---------- */
-  'auth.reauthenticate': {
-    auth: 'user',
-    title: '敏感操作二次验证',
-    description: '改密码/注销前的二次验证：向当前用户发送验证码',
-    inputSchema: obj({
-      ...apikeyIn,
-      verify_opt: { type: 'string', enum: ['phone_code', 'email_code'], description: '验证方式（必填）' },
-    }, { required: ['apikey', 'verify_opt'], additionalProperties: false }),
-    outputSchema: obj({ verification_id: str('验证码会话 id（必返）') }),
-  },
-  'auth.introspect': {
-    auth: 'user',
-    title: '校验令牌',
-    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.signOut': {
-    auth: 'user',
-    title: '退出登录',
-    description: '退出当前会话（令牌作废）',
-    inputSchema: obj({
-      ...apikeyIn,
-      client_id: str('客户端 id（可选，默认环境 id）'),
-      x_device_id: str('设备 id（可选）'),
-    }, { required: ['apikey'], additionalProperties: true }),
-    outputSchema: { type: 'object', description: '网关响应（通常为空对象）' },
-    annotations: { destructiveHint: true },
-  },
-
-  /* ---------- user：本地档案 ---------- */
-  'user.upsert': {
-    mcp: false,
-    auth: 'user',
-    title: '建档 / 合并档案',
-    description: '建档或刷新 updated_at（登录链路内部步，登录时自动执行）',
-    inputSchema: obj({ uid: uidField, profile: freeObj('要合并进档案 profile 段的字段（可选）'), env: str('建档环境标签（可选，缺省 prod）') }, { required: ['uid'], additionalProperties: false }),
-    outputSchema: obj({ id: str('档案行 id'), data: { type: 'object', description: '档案 data 段' } }, { additionalProperties: false }),
-  },
-  'user.get': {
-    auth: 'self',
-    title: '读取自己的档案',
-    description: '读取当前登录用户的业务档案（profile/settings），无档案时返回 null',
-    inputSchema: obj({}, { additionalProperties: false }),
-    outputSchema: {
-      type: 'object',
-      description: '档案行（无行时 structuredContent 省略，content 文本为 null）',
-      properties: { id: str('档案行 id'), data: { type: 'object' }, status: str('状态'), deleted_at: { type: ['string', 'null'] } },
-      additionalProperties: true,
-    },
-    annotations: { readOnlyHint: true },
-  },
-  'user.patchProfile': {
-    auth: 'self',
-    title: '更新自己的档案',
-    description: '浅合并更新当前登录用户的业务档案 profile 段（本地字段，不走网关）',
-    inputSchema: obj({
-      patch: freeObj('要浅合并进 profile 的字段（必填）'),
-    }, { required: ['patch'], additionalProperties: false }),
-    outputSchema: obj({ section: { type: ['object', 'null'], description: '合并后的 profile 段' } }),
-  },
-  'user.schemaStatus': {
-    mcp: false,
-    auth: 'user',
-    title: '档案表状态',
-    description: '探测建档表 / 主键 / 四索引的在位状态（运维面）',
-    inputSchema: obj({}, { required: [], additionalProperties: false }),
-    outputSchema: obj({
-      table: { type: 'boolean', description: '表是否存在' },
-      primaryKey: { type: 'boolean', description: '主键是否存在' },
-      indexes: { type: 'object', description: '四个索引的存在性' },
-    }, { required: ['table', 'primaryKey', 'indexes'], additionalProperties: false }),
-    annotations: { readOnlyHint: true },
-  },
-  'user.ensureSchema': {
-    mcp: false,
-    auth: 'user',
-    title: '初始化档案表',
-    description: '幂等初始化建档表与索引（部署动作，登录链路不执行）',
-    inputSchema: obj({}, { required: [], additionalProperties: false }),
-    outputSchema: obj({
-      table: { type: 'string', enum: ['created', 'exists'], description: '本次建表结果' },
-      indexes: { type: 'object', description: '{ created: string[], existing: string[] }' },
-      status: { type: 'object', description: '执行后的探测结果' },
-    }, { required: ['table', 'indexes', 'status'], additionalProperties: false }),
-    annotations: { readOnlyHint: true, idempotentHint: true },
-  },
-
-  /* ---------- user：用户令牌面（user，token 走头） ---------- */
-  'user.me': {
-    auth: 'user',
-    title: '当前用户',
-    description: '读取网关侧当前用户信息（资料 / 绑定 / 角色）',
-    inputSchema: obj({ ...apikeyIn }, { required: ['apikey'], additionalProperties: false }),
-    outputSchema: { type: 'object', description: '网关用户信息（原样）' },
-    annotations: { readOnlyHint: true },
-  },
-  'user.updateBasic': {
-    auth: 'user',
-    title: '修改资料（含手机号/邮箱）',
-    description: '修改网关侧用户资料；改手机号/邮箱需先 reauthenticate 拿验证码令牌；成功后自动同步本地档案',
-    inputSchema: obj({
-      ...apikeyIn,
-      nickname: str('昵称（可选）'),
-      username: str('用户名（可选）'),
-      phone: str('手机号（可选，修改需验证码）'),
-      email: str('邮箱（可选，修改需验证码）'),
-      avatar_url: str('头像 URL（可选）'),
-      gender: { type: 'string', enum: ['MALE', 'FEMALE'], description: '性别（可选）' },
-      description: str('个人简介（可选）'),
-      verification_token: str('手机号/邮箱变更的验证码令牌（可选，改手机/邮箱时需要）'),
-    }, { required: ['apikey'], additionalProperties: true }),
-    outputSchema: { type: 'object', description: '网关响应（原样）' },
-  },
-  'user.changePassword': {
-    auth: 'user',
-    title: '修改密码',
-    description: '修改当前用户密码（需先 reauthenticate 二次验证）',
-    inputSchema: obj({
-      ...apikeyIn,
-      password: str('新密码（必填）'),
-      verification_token: str('二次验证令牌（可选，按网关要求）'),
-    }, { required: ['apikey', 'password'] }),
-    outputSchema: { type: 'object', description: '网关响应（通常为空对象）' },
-    annotations: { destructiveHint: true },
-  },
-  'user.deleteMe': {
-    auth: 'user',
-    title: '注销账号',
-    description: '注销当前用户（需先 reauthenticate 二次验证）',
-    inputSchema: obj({
-      ...apikeyIn,
-      verification_token: str('二次验证令牌（可选，按网关要求）'),
-    }, { 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） */
-export const withSchemas = entries => entries.map(([key, ability]) => [key, { ...ability, ...(SCHEMAS[key] ?? {}) }])