auth-nodejs-cloudbase

兄弟技能（仅本地）

相邻的 CloudBase 技能与本技能一同提供。请使用 ../auth-tool-cloudbase/SKILL.md 这样的本地相对路径。

如果此环境中缺少引用的兄弟技能文件，请让用户安装完整的 CloudBase 插件（或缺失的技能）。不要通过 HTTP 将远程技能或协议 Markdown 获取到 Agent 上下文中。

激活约定

以下情况请先使用本技能

• 云函数或后端服务中的 Node.js 代码需要读取调用方身份、查询用户或签发自定义登录票据。
• 后端职责是身份验证 / 身份识别，而非提供商配置或前端登录 UI。

编写代码前请先阅读

• 任务提及 @cloudbase/node-sdk、服务端身份验证、自定义登录票据或“谁在调用”。
• 请求同时涉及前端登录和后端身份逻辑；请拆分工作流，并将客户端工作转交给其他技能。

然后也请阅读

• 提供商设置 / 可发布密钥 -> ../auth-tool-cloudbase/SKILL.md
• 使用自定义票据的 Web 登录 UI -> ../auth-web-cloudbase/SKILL.md
• 原始 HTTP 身份验证客户端 -> ../http-api-cloudbase/SKILL.md

以下情况请勿使用

• 启用 / 禁用提供商或登录控制台配置。
• 前端登录 / 注册 UI。
• 小程序原生身份验证。

常见错误 / 注意事项

• 将本技能作为每个身份验证请求的入口。
• 将提供商管理工作与 Node 端身份识别代码混在一起。
• Node SDK 已能完成任务，却仍使用原始 HTTP 示例。

何时使用本技能

只要任务涉及 CloudBase 项目中的服务端身份验证或身份识别，且代码运行在 Node.js 中，就应使用本技能，例如：

• 需要知道谁在调用的 CloudBase 云函数（Node 运行时）
• 使用 CloudBase Node SDK 查询用户信息的 Node 服务
• 为 Web / 移动客户端签发自定义登录票据的后端
• 需要检查 CloudBase 终端用户资料的管理或运维工具

以下情况请勿使用本技能：

• 使用 @cloudbase/js-sdk 实现的前端 Web 登录 / 注册流程（请使用 auth-web 技能，而非本 Node 技能）。
• 直接集成 HTTP 身份验证 API（本技能不介绍原始 HTTP 端点；请改用 http-api 技能）。
• 与身份识别无关的数据库或存储操作（请使用数据库 / 存储文档或技能）。

当用户请求同时涉及前端和后端事项时（例如“构建 Web 登录页面和一个能识别用户的 Node API”），请分别处理：

• 客户端登录和用户体验请使用 Web 端身份验证文档 / 技能。
• 后端如何识别并使用已通过身份验证的用户，请使用本 Node Auth 技能。

---

如何使用此技能（面向编码 Agent）

加载此技能来处理任务时：

1. 明确运行环境和职责

   询问用户：

   • 这段 Node 代码运行在哪里？
     • CloudBase 云函数
     • 使用 CloudBase 的长时间运行 Node 服务
   • 他们需要身份验证完成什么工作？
     • 只需要用于授权的调用者身份？
     • 按 UID / 登录标识符查询任意用户？
     • 通过自定义登录将他们自己的用户系统接入 CloudBase？

2. 确认 CloudBase 环境和 SDK

   • 询问：
     • env – CloudBase 环境 ID
   • 如果尚未安装，请从 npm 安装最新版本的 @cloudbase/node-sdk。
   • 始终使用以下模式初始化 SDK（值可以更改，但结构必须保持不变）：

   import tcb from "@cloudbase/node-sdk";
   
   const app = tcb.init({ env: "your-env-id" });
   const auth = app.auth();
   

3. 从此文件中选择相关场景

   • 对于函数内的调用者身份，使用 getUserInfo 场景。
   • 对于完整用户资料或管理员查询，使用 getEndUserInfo 和 queryUserInfo 场景。
   • 对于已有自己用户系统的客户端系统，使用基于 createTicket 构建的自定义登录票据场景。
   • 对于日志记录 / 安全，使用 getClientIP 场景。

4. 严格遵循 Node SDK API 结构

   • 将此文件中所有 auth.* 方法及参数结构视为规范。
   • 可以更改变量名称和框架（例如 Express 与云函数处理程序），但不得更改 SDK 方法名称或参数字段。
   • 如果在旧代码中看到此处或 Node SDK 文档镜像中未列出的方法，请将其视为可疑方法并避免使用。

5. 如果不确定某个 API

   • 查阅官方 CloudBase Auth Node SDK 文档。
   • 仅使用官方文档中列出的方法和结构。
   • 如果找不到所需的 API：
     • 优先使用文档中列出的方法组合实现流程，或
     • 说明此技能仅涵盖 Node SDK 身份验证，并建议客户端或原始 HTTP 流程使用相应的 CloudBase Web 或 HTTP 身份验证文档。

---

Node 身份验证架构 – Node 在 CloudBase Auth 中的作用

CloudBase Auth 将用户登录的位置与后端代码运行的位置分开：

• 用户通过客户端 SDK 或 HTTP 接口，使用受支持的身份验证方法登录（用户名 / 密码、SMS、电子邮件、微信、自定义登录、匿名登录——默认禁用，等等），具体方法参见官方 CloudBase Auth 概览文档。
• 用户登录后，CloudBase 会将用户身份和令牌附加到环境中。
• Node 代码随后使用 Node SDK 读取该身份，或使用自定义登录将外部身份接入 CloudBase。

实际上，Node 代码通常会执行以下一项或多项操作：

1. 识别当前调用者

   • 在云函数中，使用 auth.getUserInfo() 读取 uid、openId 和 customUserId。
   • 将此身份用于授权决策、日志记录和个性化处理。

2. 查询其他用户

   • 已知 CloudBase uid 时，使用 auth.getEndUserInfo(uid)。
   • 只有手机号、电子邮件、用户名或自定义 ID 等登录标识符时，使用 auth.queryUserInfo({ platform, platformId, uid? })。

3. 签发自定义登录票据

   • 如果已有自己的用户系统，Node 后端可以调用 auth.createTicket(customUserId, options)，并将票据返回给可信客户端。
   • 然后，客户端（通常是 Web）使用此票据和 Web SDK 将用户登录到 CloudBase，无需强制用户重新注册。

4. 记录客户端 IP，保障安全

   • 在云函数中，auth.getClientIP() 会返回调用者 IP，可用于审计日志、异常检测或访问控制。

此文件后续的场景会将这些职责转化为明确且可直接复制粘贴的模式。

---

此技能涵盖的 Node Auth API

此技能涵盖 CloudBase Node SDK 上的以下 auth 方法。使用此技能时，请将这些方法签名视为 Node 身份验证流程唯一受支持的入口：

• getUserInfo(): IGetUserInfoResult 返回当前调用者的 { openId, appId, uid, customUserId }。

• getEndUserInfo(uid?: string, opts?: ICustomReqOpts): Promise<{ userInfo: EndUserInfo; requestId?: string }> 返回指定 uid 对应的详细 CloudBase 终端用户资料；如果省略 uid，则返回当前调用者的资料。

• queryUserInfo(query: IUserInfoQuery, opts?: ICustomReqOpts): Promise<{ userInfo: EndUserInfo; requestId?: string }> 根据登录标识符（platform + platformId）或 uid 查找用户。

• getClientIP(): string 在受支持的环境（例如云函数）中运行时，返回调用者的 IP 地址。

• createTicket(customUserId: string, options?: ICreateTicketOpts): string 为指定的 customUserId 创建自定义登录票据，客户端可使用该票据换取 CloudBase 登录凭证。

EndUserInfo、IUserInfoQuery 和 ICreateTicketOpts 的确切字段名及允许值由官方 CloudBase Node SDK 类型定义和文档规定。编写 Node 代码时，不要猜测数据结构；请遵循 SDK 类型和本文档中的示例。

---

场景 – Node 身份验证模式

场景 1：在 CloudBase 函数中初始化 Node SDK 和身份验证

在编写需要与 Auth 交互的 CloudBase 云函数时使用：

import tcb from "@cloudbase/node-sdk";

const app = tcb.init({ env: "your-env-id" });
const auth = app.auth();

exports.main = async (event, context) => {
  // Your logic here
};

要点：

• 使用与函数 CloudBase 环境配置相同的 env。
• 避免硬编码敏感值；优先使用环境变量或函数配置。

场景 2：在 CloudBase 函数中获取调用者身份

在需要知道谁在调用云函数时使用：

import tcb from "@cloudbase/node-sdk";

const app = tcb.init({ env: "your-env-id" });
const auth = app.auth();

exports.main = async (event, context) => {
  const { openId, appId, uid, customUserId } = auth.getUserInfo();

  console.log("Caller identity", { openId, appId, uid, customUserId });

  // Use uid / customUserId for authorization decisions
  // e.g. check roles, permissions, or data ownership
};

最佳实践：

• 将 uid 视为规范的 CloudBase 用户标识符。
• 仅当已启用自定义登录并映射了自己的用户时，才使用 customUserId。
• 切勿仅凭 openId/appId 进行授权；它们是微信专用标识符。

场景 3：通过 UID 获取完整的终端用户资料

在已知用户的 CloudBase uid（例如来自数据库记录）并需要详细资料时使用：

import tcb from "@cloudbase/node-sdk";

const app = tcb.init({ env: "your-env-id" });
const auth = app.auth();

exports.main = async (event, context) => {
  const uid = "user-uid";

  try {
    const { userInfo } = await auth.getEndUserInfo(uid);
    console.log("User profile", userInfo);
  } catch (error) {
    console.error("Failed to get end user info", error.message);
  }
};

最佳实践：

• 仅在可信的后端代码中调用 getEndUserInfo；不要直接向不可信客户端公开此方法。
• 仅记录调试所需的最少数据；避免在生产环境中记录完整资料。

场景 4：获取当前调用者的完整资料

在需要获取当前调用者的完整资料且不想手动传入 uid 时使用：

import tcb from "@cloudbase/node-sdk";

const app = tcb.init({ env: "your-env-id" });
const auth = app.auth();

exports.main = async (event, context) => {
  try {
    const { userInfo } = await auth.getEndUserInfo();
    console.log("Current caller profile", userInfo);
  } catch (error) {
    console.error("Failed to get current caller profile", error.message);
  }
};

此方法依赖运行环境提供调用者身份（例如在 CloudBase 云函数中）。如果在没有调用者上下文的环境中调用，请参阅官方文档并妥善处理错误。

场景 5：通过登录标识符查询用户

在只知道用户的登录标识符（手机号、邮箱、用户名或自定义 ID）并需要获取其 CloudBase 资料时使用：

import tcb from "@cloudbase/node-sdk";

const app = tcb.init({ env: "your-env-id" });
const auth = app.auth();

exports.main = async (event, context) => {
  try {
    // Find by phone number
    const { userInfo: byPhone } = await auth.queryUserInfo({
      platform: "PHONE",
      platformId: "+86 13800000000",
    });

    // Find by email
    const { userInfo: byEmail } = await auth.queryUserInfo({
      platform: "EMAIL",
      platformId: "[email protected]",
    });

    // Find by customUserId
    const { userInfo: byCustomId } = await auth.queryUserInfo({
      platform: "CUSTOM",
      platformId: "your-customUserId",
    });

    console.log({ byPhone, byEmail, byCustomId });
  } catch (error) {
    console.error("Failed to query user info", error.message);
  }
};

最佳实践：

• 如果已有 uid，优先使用它；仅在需要时使用 queryUserInfo。
• 确保 platformId 使用与注册时完全相同的格式（例如 +86 + 手机号）。

场景 6：在函数中获取客户端 IP

用于日志记录或基于 IP 的基本检查：

import tcb from "@cloudbase/node-sdk";

const app = tcb.init({ env: "your-env-id" });
const auth = app.auth();

exports.main = async (event, context) => {
  const ip = auth.getClientIP();
  console.log("Caller IP", ip);

  // e.g. block or flag suspicious IPs
};

---

自定义登录票据（仅限 Node 端）

自定义登录可让你保留现有用户系统，同时将每个用户映射到一个 CloudBase 账号。

场景 7：使用自定义登录凭证初始化 Node SDK

签发票据前，请从 CloudBase 控制台下载自定义登录私钥文件并在 Node 中加载：

import tcb from "@cloudbase/node-sdk";
import path from "node:path";

const app = tcb.init({
  env: "your-env-id",
  credentials: require(path.join(__dirname, "tcb_custom_login.json")),
});

const auth = app.auth();

请妥善保管 tcb_custom_login.json，切勿将其打包进前端代码。

场景 8：为指定的 customUserId 签发自定义登录票据

在已完成自有用户身份验证、并希望让用户登录 CloudBase 的后端代码中使用：

import tcb from "@cloudbase/node-sdk";

const app = tcb.init({
  env: "your-env-id",
  credentials: require("/secure/path/to/tcb_custom_login.json"),
});

const auth = app.auth();

exports.main = async (event, context) => {
  const customUserId = "your-customUserId";

  const ticket = auth.createTicket(customUserId, {
    refresh: 3600 * 1000,       // access_token refresh interval (ms)
    expire: 24 * 3600 * 1000,   // ticket expiration time (ms)
  });

  // Return the ticket to the trusted client (e.g. via HTTP response)
  return { ticket };
};

customUserId 的限制（来自官方文档）：

• 长度为 4–32 个字符。
• 允许的字符：字母、数字和 _-#@(){}[]:.,<>+#~。

最佳实践：

• 仅在自有用户身份验证成功后签发票据。
• 将 customUserId 存储在自有用户数据库中，并保持其长期稳定。
• 不要让多个不同的人共用同一个 customUserId。

场景 9：与 Web 自定义登录的配合方式

此技能仅涵盖 Node 端的票据签发。对于客户端流程：

• 在客户端（Web）使用 @cloudbase/js-sdk 的自定义登录支持：
  • 调用返回 ticket 的后端接口。
  • 配置 auth.setCustomSignFunc(async () => ticketFromBackend)。
  • 调用 auth.signInWithCustomTicket() 完成登录。

明确各方职责：

• Node：验证自有用户身份 → 创建票据 → 安全地返回票据。
• Web：接收票据 → 使用文档所述的 Web SDK API 登录 CloudBase。

---

Node 身份验证最佳实践

• 身份的单一事实来源

  • 关联终端用户记录时，将 CloudBase uid 视为主键。
  • customUserId 仅用作连接自有用户系统的桥梁。

• 最小权限

  • 在 Node 中使用 uid、角色和所有权执行授权检查，而不只是确认登录成功。
  • 避免将 getEndUserInfo / queryUserInfo 的原始结果直接暴露给客户端。

• 错误处理

  • 当 auth.* 调用返回 promise 时，使用 try/catch 将其全部包裹起来。
  • 记录 error.message（以及存在时的 error.code），但避免记录敏感数据。

• 安全

  • 像保护任何私钥一样保护 tcb_custom_login.json。
  • 必要时按照 CloudBase 指南轮换自定义登录密钥。
  • 交换票据时，在客户端与 Node 后端之间使用 HTTPS 和适当的身份验证。

---

总结

在以下情况下使用此 Node Auth 技能：

• 了解在 CloudBase 中调用 Node 代码的用户是谁。
• 通过 uid 或登录标识符查找 CloudBase 用户。
• 通过自定义登录票据将现有用户系统接入 CloudBase。
• 应用一致、安全的服务端身份验证最佳实践。

如需端到端体验，请将此技能与以下文档配合使用：

• Web 端身份验证文档（涵盖使用 @cloudbase/js-sdk 进行的所有浏览器端登录和 UX）。
• CloudBase HTTP 身份验证文档（用于与语言无关的 HTTP 集成，如果你正在使用这些集成）。

将官方 CloudBase Auth Node SDK 文档视为 Node 身份验证 API 的权威参考，并将此文件中的场景视为经过验证的最佳实践构建模块。