auth-nodejs-cloudbase

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When to use this skill

何时使用该技能

Use this skill whenever the task involves server-side authentication or identity in a CloudBase project, and the code is running in Node.js, for example:

CloudBase 云函数 (Node runtime) that needs to know who is calling
Node services that use CloudBase Node SDK to look up user information
Backends that issue custom login tickets for Web / mobile clients
Admin or ops tools that need to inspect CloudBase end-user profiles

Do NOT use this skill for:

Frontend Web login / sign-up flows using
```
@cloudbase/js-sdk
```
(handle those with the CloudBase Web Auth skill at
```
skills/web-auth-skill
```
, not this Node skill).
Direct HTTP auth API integrations (this skill does not describe raw HTTP endpoints; use the CloudBase HTTP Auth skill at
```
skills/auth-http-api-skill
```
instead).
Database or storage operations that do not involve identity (use database/storage docs or skills).

When the user request mixes frontend and backend concerns (e.g. "build a web login page and a Node API that knows the user"), treat them separately:

Use Web-side auth docs/skills for client login and UX.
Use this Node Auth skill for how the backend sees and uses the authenticated user.

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

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

请勿将本技能用于：

使用
```
@cloudbase/js-sdk
```
的前端Web登录/注册流程（此类场景请使用位于
```
skills/web-auth-skill
```
的CloudBase Web Auth技能，而非本Node技能）。
直接HTTP认证API集成（本技能不描述原始HTTP端点；请改用位于
```
skills/auth-http-api-skill
```
的CloudBase HTTP Auth技能）。
不涉及身份识别的数据库或存储操作（请使用数据库/存储文档或对应技能）。

当用户请求混合了前端和后端需求时（例如“构建一个Web登录页面和一个能识别用户的Node API”），请分开处理：

客户端登录和用户体验相关内容使用Web端认证文档/技能。
后端如何查看和使用已认证用户的内容使用本Node Auth技能。

How to use this skill (for a coding agent)

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

When you load this skill to work on a task:

Clarify the runtime and responsibility

Ask the user:
- Where does this Node code run?
  - CloudBase 云函数
  - Long‑running Node service using CloudBase
- What do they need from auth?
  - Just the caller identity for authorization?
  - Look up arbitrary users by UID / login identifier?
  - Bridge their own user system into CloudBase via custom login?
Confirm CloudBase environment and SDK
- Ask for:
  - ```
  env
```
  – CloudBase environment ID
- Install the latest
```
@cloudbase/node-sdk
```
  from npm if it is not already available.
- Always initialize the SDK using this pattern (values can change, shape must not):
ts
```
import tcb from "@cloudbase/node-sdk";

const app = tcb.init({ env: "your-env-id" });
const auth = app.auth();
```
Pick the relevant scenario from this file
- For caller identity inside a function, use the
```
getUserInfo
```
  scenarios.
- For full user profile or admin lookup, use the
```
getEndUserInfo
```
  and
```
queryUserInfo
```
  scenarios.
- For client systems that already have their own users, use the custom login ticket scenarios built on
```
createTicket
```
  .
- For logging / security, use the
```
getClientIP
```
  scenario.
Follow Node SDK API shapes exactly
- Treat all
```
auth.*
```
  methods and parameter shapes in this file as canonical.
- You may change variable names and framework (e.g. Express vs 云函数 handler), but do not change SDK method names or parameter fields.
- If you see a method in older code that is not listed here or in the Node SDK docs mirror, treat it as suspect and avoid using it.
If you are unsure about an API
- Consult the official CloudBase Auth Node SDK documentation.
- Only use methods and shapes that appear in the official documentation.
- If you cannot find an API you want:
  - Prefer composing flows from the documented methods, or
  - Explain that this skill only covers Node SDK auth, and suggest using the relevant CloudBase Web or HTTP auth documentation for client-side or raw-HTTP flows.

当你加载本技能处理任务时：

明确运行环境和职责

询问用户：
- 该Node代码运行在何处？
  - CloudBase 云函数
  - 使用CloudBase的长期运行Node服务
- 他们需要认证提供什么能力？
  - 仅用于授权的调用者身份？
  - 通过UID/登录标识符查询任意用户？
  - 通过自定义登录将自有用户系统接入CloudBase？
确认CloudBase环境和SDK
- 询问用户获取：
  - ```
  env
```
  – CloudBase环境ID
- 如果尚未安装，请从npm安装最新版
```
@cloudbase/node-sdk
```
  。
- 始终使用以下模式初始化SDK（值可修改，但结构不能变）：
ts
```
import tcb from "@cloudbase/node-sdk";

const app = tcb.init({ env: "your-env-id" });
const auth = app.auth();
```
从本文档中选择相关场景
- 对于云函数中的调用者身份识别，使用
```
getUserInfo
```
  场景。
- 对于完整用户资料或管理员查询，使用
```
getEndUserInfo
```
  和
```
queryUserInfo
```
  场景。
- 对于已有自有用户系统的客户端，使用基于
```
createTicket
```
  的自定义登录票据场景。
- 对于日志/安全需求，使用
```
getClientIP
```
  场景。
严格遵循Node SDK API结构
- 将本文档中所有
```
auth.*
```
  方法和参数结构视为标准规范。
- 你可以修改变量名和框架（例如Express vs 云函数处理器），但请勿修改SDK方法名或参数字段。
- 如果你在旧代码中看到本文档或Node SDK文档镜像中未列出的方法，请视为不可靠并避免使用。
若对API有疑问
- 查阅官方CloudBase Auth Node SDK文档。
- 仅使用官方文档中列出的方法和结构。
- 如果你找不到所需API：
  - 优先使用已记录方法组合实现流程，或者
  - 说明本技能仅覆盖Node SDK认证，并建议使用相关CloudBase Web或HTTP认证文档处理客户端或原生HTTP流程。

Node auth architecture – how Node fits into CloudBase Auth

Node认证架构——Node在CloudBase Auth中的角色

CloudBase Auth v2 separates where users log in from where backend code runs:

Users log in through the supported auth methods (anonymous, username/password, SMS, email, WeChat, custom login, etc.) using client SDKs or HTTP interfaces, as described in the official CloudBase Auth overview documentation.
Once logged in, CloudBase attaches the user identity and tokens to the environment.
Node code then reads that identity using the Node SDK, or bridges external identities into CloudBase using custom login.

In practice, Node code usually does one or more of:

Identify the current caller
- In 云函数, use
```
auth.getUserInfo()
```
  to read
```
uid
```
  ,
```
openId
```
  , and
```
customUserId
```
  .
- Use this identity for authorization decisions, logging, and personalisation.
Look up other users
- Use
```
auth.getEndUserInfo(uid)
```
  when you know the CloudBase
```
uid
```
  .
- Use
```
auth.queryUserInfo({ platform, platformId, uid? })
```
  when you only have login identifiers such as phone, email, username, or a custom ID.
Issue custom login tickets
- When you already have your own user system, your Node backend can call
```
auth.createTicket(customUserId, options)
```
  and return the ticket to a trusted client.
- The client (typically Web) then uses this ticket with the Web SDK to log the user into CloudBase without forcing them to sign up again.
Log client IP for security
- In 云函数,
```
auth.getClientIP()
```
  returns the caller IP, which you can use for audit logs, anomaly detection, or access control.

The scenarios later in this file turn these responsibilities into explicit, copy‑pasteable patterns.

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

用户通过支持的认证方式（匿名、用户名/密码、短信、邮箱、微信、自定义登录等），使用客户端SDK或HTTP接口登录，具体请参考官方CloudBase Auth概述文档。
登录后，CloudBase会将用户身份和令牌关联到环境中。
Node代码随后通过Node SDK读取该身份，或通过自定义登录将外部身份接入CloudBase。

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

识别当前调用者
- 在云函数中，使用
```
auth.getUserInfo()
```
  读取
```
uid
```
  、
```
openId
```
  和
```
customUserId
```
  。
- 将该身份用于授权决策、日志记录和个性化处理。
查询其他用户
- 当你知道CloudBase
```
uid
```
  时，使用
```
auth.getEndUserInfo(uid)
```
  。
- 当你仅有登录标识符（如手机号、邮箱、用户名或自定义ID）时，使用
```
auth.queryUserInfo({ platform, platformId, uid? })
```
  。
颁发自定义登录票据
- 当你已有自有用户系统时，你的Node后端可以调用
```
auth.createTicket(customUserId, options)
```
  并将票据返回给受信任的客户端。
- 客户端（通常是Web端）随后使用该票据通过Web SDK登录CloudBase，无需用户再次注册。
记录客户端IP用于安全目的
- 在云函数中，
```
auth.getClientIP()
```
  返回调用者的IP地址，你可以将其用于审计日志、异常检测或访问控制。

本文档后续的场景将这些职责转化为可直接复制粘贴的代码模式。

Node Auth APIs covered by this skill

本技能覆盖的Node Auth API

This skill covers the following

auth

methods on the CloudBase Node SDK. Treat these method signatures as the only supported entry points for Node auth flows when using this skill:

getUserInfo(): IGetUserInfoResult

Returns

{ openId, appId, uid, customUserId }

for the current caller.

getEndUserInfo(uid?: string, opts?: ICustomReqOpts): Promise<{ userInfo: EndUserInfo; requestId?: string }>

Returns detailed CloudBase end‑user profile for a given

uid

or for the current caller (when

uid

is omitted).

queryUserInfo(query: IUserInfoQuery, opts?: ICustomReqOpts): Promise<{ userInfo: EndUserInfo; requestId?: string }>

Finds a user by login identifier (

platform

platformId

) or

uid

```
getClientIP(): string
```
Returns the caller’s IP address when running in a supported environment (e.g. 云函数).
```
createTicket(customUserId: string, options?: ICreateTicketOpts): string
```
Creates a custom login ticket for the given
```
customUserId
```
that clients can exchange for a CloudBase login.

The exact field names and allowed values for

EndUserInfo

IUserInfoQuery

, and

ICreateTicketOpts

are defined by the official CloudBase Node SDK typings and documentation. When writing Node code, do not guess shapes; follow the SDK types and the examples in this file.

本技能覆盖CloudBase Node SDK上的以下

auth

方法。使用本技能时，请将这些方法签名视为Node认证流程唯一支持的入口：

getUserInfo(): IGetUserInfoResult

返回当前调用者的

{ openId, appId, uid, customUserId }

。

getEndUserInfo(uid?: string, opts?: ICustomReqOpts): Promise<{ userInfo: EndUserInfo; requestId?: string }>

返回指定

uid

用户或当前调用者（当省略

uid

时）的详细CloudBase终端用户资料。

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类型和本文档中的示例。

Scenarios – Node auth patterns

场景——Node认证模式

Scenario 1: Initialize Node SDK and auth in a CloudBase function

场景1：在CloudBase函数中初始化Node SDK和认证模块

Use this when writing a CloudBase 云函数 that needs to interact with Auth:

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
};

Key points:

Use the same
```
env
```
as configured for the function’s CloudBase 环境.
Avoid hardcoding sensitive values; prefer environment variables or function configuration.

当你编写需要与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) => {
  // 你的业务逻辑
};

关键点：

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

Scenario 2: Get caller identity in a CloudBase function

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

Use this when you need to know who is calling your cloud function:

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
};

Best practices:

Treat
```
uid
```
as the canonical CloudBase user identifier.
Use
```
customUserId
```
only when you have enabled 自定义登录 and mapped your own users.
Never trust
```
openId
```
/
```
appId
```
alone for authorization; they are WeChat‑specific identifiers.

当你需要知晓谁在调用你的云函数时使用：

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("调用者身份", { openId, appId, uid, customUserId });

  // 使用uid/customUserId进行授权决策
  // 例如检查角色、权限或数据归属
};

最佳实践：

将
```
uid
```
视为CloudBase用户的标准标识符。
仅当你启用了自定义登录并映射了自有用户时，才使用
```
customUserId
```
。
永远不要仅依赖
```
openId
```
/
```
appId
```
进行授权；它们是微信特定的标识符。

Scenario 3: Get full end‑user profile by UID

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

Use this when you know a user’s CloudBase

uid

(for example, from a database record) and you need detailed profile information:

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);
  }
};

Best practices:

Call
```
getEndUserInfo
```
from trusted backend code only; do not expose it directly to untrusted clients.
Log minimal necessary data for debugging; avoid logging full profiles in production.

当你知道用户的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("用户资料", userInfo);
  } catch (error) {
    console.error("获取终端用户资料失败", error.message);
  }
};

最佳实践：

仅从受信任的后端代码调用
```
getEndUserInfo
```
；不要直接暴露给不受信任的客户端。
仅记录调试所需的最少数据；生产环境中避免记录完整用户资料。

Scenario 4: Get full profile for the current caller

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

Use this when you want the current caller’s full profile without manually passing

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);
  }
};

This relies on the environment providing the caller’s identity (e.g. within a CloudBase 云函数). If called where no caller context exists, refer to the official docs and handle errors gracefully.

当你需要当前调用者的完整资料且不想手动传递

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("当前调用者资料", userInfo);
  } catch (error) {
    console.error("获取当前调用者资料失败", error.message);
  }
};

这依赖于环境提供调用者身份（例如在CloudBase云函数中）。如果在没有调用者上下文的环境中调用，请参考官方文档并优雅处理错误。

Scenario 5: Query user by login identifier

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

Use this when you only know a user’s login identifier (phone, email, username, or custom ID) and need their CloudBase profile:

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: "test@example.com",
    });

    // 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);
  }
};

Best practices:

Prefer
```
uid
```
when you already have it; use
```
queryUserInfo
```
only when needed.
Make sure
```
platformId
```
uses the exact format you used at sign‑up (e.g.
```
+86
```
+ phone number).

当你仅有用户的登录标识符（手机号、邮箱、用户名或自定义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 {
    // 通过手机号查找
    const { userInfo: byPhone } = await auth.queryUserInfo({
      platform: "PHONE",
      platformId: "+86 13800000000",
    });

    // 通过邮箱查找
    const { userInfo: byEmail } = await auth.queryUserInfo({
      platform: "EMAIL",
      platformId: "test@example.com",
    });

    // 通过customUserId查找
    const { userInfo: byCustomId } = await auth.queryUserInfo({
      platform: "CUSTOM",
      platformId: "your-customUserId",
    });

    console.log({ byPhone, byEmail, byCustomId });
  } catch (error) {
    console.error("查询用户资料失败", error.message);
  }
};

最佳实践：

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

Scenario 6: Get client IP in a function

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

Use this for logging or basic IP‑based checks:

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
};

用于日志记录或基于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("调用者IP", ip);

  // 例如拦截或标记可疑IP
};

Custom login tickets (Node side only)

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

Custom login lets you keep your existing user system while still mapping each user to a CloudBase account.

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

Scenario 7: Initialize Node SDK with custom login credentials

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

Before issuing tickets, install the custom login private key file from the CloudBase console and load it in 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();

Keep

tcb_custom_login.json

secret and never bundle it into frontend code.

在颁发票据之前，请从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

，绝对不要将其打包到前端代码中。

Scenario 8: Issue a custom login ticket for a given customUserId

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

Use this in backend code that has already authenticated your own user and wants to let them log into 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 };
};

Constraints for

customUserId

(from official docs):

Length 4–32 characters.
Allowed characters: letters, digits, and
```
_-#@(){}[]:.,<>+#~
```
.

Best practices:

Only issue tickets after your own user authentication succeeds.
Store
```
customUserId
```
in your own user database and keep it stable over time.
Do not reuse
```
customUserId
```
for multiple distinct people.

当你的后端代码已完成自有用户认证，并希望让用户登录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刷新间隔（毫秒）
    expire: 24 * 3600 * 1000,   // 票据过期时间（毫秒）
  });

  // 将票据返回给受信任的客户端（例如通过HTTP响应）
  return { ticket };
};

customUserId

的约束（来自官方文档）：

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

最佳实践：

仅在自有用户认证成功后颁发票据。
将
```
customUserId
```
存储在自有用户数据库中，并保持长期稳定。
不要为多个不同用户重用
```
customUserId
```
。

Scenario 9: How this pairs with Web custom login

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

This skill only covers Node-side ticket issuance. For the client-side flow:

On the client (Web), use
```
@cloudbase/js-sdk
```
's custom login support:
- Call your backend endpoint that returns
```
ticket
```
  .
- Configure
```
auth.setCustomSignFunc(async () => ticketFromBackend)
```
  .
- Call
```
auth.signInWithCustomTicket()
```
  to finish login.

Keep the responsibility clear:

Node: authenticate your own user → create ticket → return ticket securely.
Web: receive ticket → sign into CloudBase using documented Web SDK APIs.

本技能仅覆盖Node端的票据颁发。客户端流程请参考：

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

请明确职责划分：

Node端：认证自有用户 → 创建票据 → 安全返回票据。
Web端：接收票据 → 使用官方Web SDK API登录CloudBase。

Node auth best practices

Node认证最佳实践

Single source of truth for identity
- Treat CloudBase
```
uid
```
  as the primary key when relating end‑user records.
- Use
```
customUserId
```
  only as a bridge to your own user system.
Least privilege
- Perform authorization checks in Node using
```
uid
```
  , roles, and ownership, not just login success.
- Avoid exposing raw
```
getEndUserInfo
```
  /
```
queryUserInfo
```
  results directly to clients.
Error handling
- Wrap all
```
auth.*
```
  calls in
```
try/catch
```
  when they return promises.
- Log
```
error.message
```
  (and
```
error.code
```
  if present), but avoid logging sensitive data.
Security
- Protect
```
tcb_custom_login.json
```
  as you would any private key.
- Rotate custom login keys according to CloudBase guidance when necessary.
- Use HTTPS and proper authentication between your clients and Node backend when exchanging tickets.

身份单一数据源
- 将CloudBase
```
uid
```
  作为关联终端用户记录的主键。
- 仅将
```
customUserId
```
  作为接入自有用户系统的桥梁。
最小权限原则
- 在Node端使用
```
uid
```
  、角色和归属关系进行授权检查，而不仅仅依赖登录成功。
- 避免将原始的
```
getEndUserInfo
```
  /
```
queryUserInfo
```
  结果直接暴露给客户端。
错误处理
- 对所有返回Promise的
```
auth.*
```
  调用使用
```
try/catch
```
  包裹。
- 记录
```
error.message
```
  （如果有
```
error.code
```
  也一并记录），但避免记录敏感数据。
安全防护
- 像保护任何私钥一样保护
```
tcb_custom_login.json
```
  。
- 必要时按照CloudBase指南轮换自定义登录密钥。
- 在客户端和Node后端交换票据时使用HTTPS和适当的认证机制。

Summary

总结

Use this Node Auth skill whenever you need to:

Know who is calling your Node code in CloudBase.
Look up CloudBase users by
```
uid
```
or login identifier.
Bridge an existing user system into CloudBase with custom login tickets.
Apply consistent, secure, server‑side auth best practices.

For end‑to‑end experiences, pair this skill with:

Web‑side auth documentation (for all browser‑side login and UX using
```
@cloudbase/js-sdk
```
).
CloudBase HTTP auth documentation (for language‑agnostic HTTP integrations, if you are using those).

Treat the official CloudBase Auth Node SDK documentation as the canonical reference for Node auth APIs, and treat the scenarios in this file as vetted best‑practice building blocks.

当你需要以下能力时，使用本Node Auth技能：

识别CloudBase中调用Node代码的用户身份。
通过
```
uid
```
或登录标识符查询CloudBase用户。
通过自定义登录票据将自有用户系统接入CloudBase。
应用一致、安全的服务端认证最佳实践。

对于端到端的体验，请将本技能与以下内容配合使用：

Web端认证文档（使用
```
@cloudbase/js-sdk
```
的所有浏览器端登录和用户体验相关内容）。
CloudBase HTTP认证文档（如果你使用与语言无关的HTTP集成）。

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