auth-nodejs-cloudbase

Complete guide for CloudBase Auth using the CloudBase Node SDK – caller identity, user lookup, custom login tickets, and server-side best practices.

## 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 **auth-web** skill, not this Node skill).
- Direct HTTP auth API integrations (this skill does not describe raw HTTP endpoints; use the **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.

---

## How to use this skill (for a coding agent)

When you load this skill to work on a task:

1. **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?

2. **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();
   ```

3. **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.

4. **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.

5. **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 auth architecture – how Node fits into 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:

1. **Identify the current caller**

   - In 云函数, use `auth.getUserInfo()` to read `uid`, `openId`, and `customUserId`.
   - Use this identity for **authorization decisions**, logging, and personalisation.

2. **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.

3. **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.

4. **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.

---

## Node Auth APIs covered by this skill

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.

---

## Scenarios – Node auth patterns

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

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

```ts
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.

### Scenario 2: Get caller identity in a CloudBase function

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

```ts
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.

### Scenario 3: Get full end‑user profile by UID

Use this when you know a user’s CloudBase `uid` (for example, from a database record) and you need detailed profile information:

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

const app = tcb.init({