Skip to content

Commit e9c1c3b

Browse files
Areo-JoeAreo-Joe
committed
feat: auth skills
1 parent 161b72d commit e9c1c3b

File tree

15 files changed

+1404
-0
lines changed

15 files changed

+1404
-0
lines changed

‎config/skills/auth-skill/SKILL.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
name: CloudBase Auth
3+
description: A single skill that helps design and implement CloudBase Auth v2 using Web SDK, Node SDK, and HTTP APIs, including login methods, tokens, and best practices.
4+
---
5+
6+
## When to use this skill
7+
8+
Use this skill whenever the task involves **authentication or user identity** in a CloudBase project, for example:
9+
10+
- Designing which login methods to support (anonymous, username/password, SMS, email, WeChat, custom login)
11+
- Implementing auth with **Web SDK** (`@cloudbase/js-sdk@2.x`) on the frontend
12+
- Working with **Node SDK** for user info, admin operations, or issuing **custom login tickets**
13+
- Calling **HTTP auth APIs** directly from any backend or script
14+
- Understanding tokens, login state, and auth-related best practices
15+
16+
If the task is not about authentication (e.g. only about database or storage), this skill is probably not needed.
17+
18+
## Quick orientation
19+
20+
CloudBase Auth v2 provides:
21+
22+
- Multiple **login methods** with a unified user identity system
23+
- Clear **user types** (internal, external, anonymous) and account linking
24+
- A token-based **session model** with JWT access tokens and refresh tokens
25+
- SDKs (Web, Node) and **HTTP APIs** that expose the same core flows
26+
27+
This `SKILL.md` acts as a **launcher**. For deeper details, read the linked files only as needed.
28+
29+
## Table of contents (progressive disclosure)
30+
31+
### 1. Concepts & design
32+
33+
- `concepts/overview.md` – what CloudBase Auth v2 is, high-level architecture, and where to configure it.
34+
- `concepts/login_methods.md` – supported login methods, when to use each, and tradeoffs.
35+
- `concepts/user_accounts_and_roles.md` – internal vs external vs anonymous users, UIDs, and multi-account linking.
36+
- `concepts/tokens_and_sessions.md` – access_token vs refresh_token, v1 vs v2, and validation.
37+
38+
### 2. Web SDK (`@cloudbase/js-sdk@2.x`)
39+
40+
- `web-sdk/web_quickstart.md` – install/init SDK, get `auth` instance, basic sign-up/sign-in flow.
41+
- `web-sdk/web_login_flows.md` – concrete flows for:
42+
- Username/password
43+
- SMS verification code login
44+
- Email verification code login
45+
- Anonymous login and upgrade
46+
- WeChat OAuth login
47+
- `web-sdk/captcha_and_rate_limits.md` – when captchas are triggered, how to integrate the captcha adapter + UI, and how to handle errors.
48+
- `web-sdk/web_best_practices.md` – avoiding redundant logins, login-state persistence, and common UX patterns.
49+
50+
### 3. Node SDK & custom login
51+
52+
- `node-sdk/node_overview_and_user_info.md` – using the Node SDK to get user info, end-user info, query users, and read client IP.
53+
- `node-sdk/node_custom_login_ticket.md` – issuing custom login tickets on the server and integrating with your own user system.
54+
55+
### 4. HTTP APIs
56+
57+
- `http-api/http_overview.md` – the HTTP API surface for auth and how to discover endpoints.
58+
- `http-api/http_login_and_token_flows.md` – high-level flows for sign-in, sign-up, anonymous login, token grant/refresh/revoke, and user operations over HTTP.
59+
60+
### 5. Troubleshooting & FAQ
61+
62+
- `troubleshooting/faq.md` – common questions and pitfalls: anonymous vs unauthenticated, token expiry, verification limits, etc.
63+
64+
## How to use this skill
65+
66+
When working on a CloudBase auth task, follow this sequence:
67+
68+
1. **Clarify the scenario**
69+
- Is this **frontend Web**, **Node backend/cloud function**, or a generic backend calling **HTTP APIs**?
70+
- What login methods are required (e.g. phone, email, WeChat, custom SSO, anonymous trial)?
71+
- Are there existing users/identity systems that must be integrated?
72+
73+
2. **Load only the relevant conceptual context**
74+
- For high-level decisions, read:
75+
- `concepts/overview.md`
76+
- `concepts/login_methods.md`
77+
- `concepts/user_accounts_and_roles.md`
78+
- Read `concepts/tokens_and_sessions.md` only if token behavior or migration is important to the task.
79+
80+
3. **Jump to the relevant implementation section**
81+
- For **Web** implementation details, read `web-sdk/web_quickstart.md` and then the specific flow file (e.g. `web-sdk/web_login_flows.md`, `web-sdk/captcha_and_rate_limits.md`).
82+
- For **Node/server** logic or custom login ticket issuance, use the `node-sdk/` files.
83+
- For **language-agnostic HTTP integration**, use the `http-api/` files.
84+
85+
4. **Design first, then code**
86+
- Use the conceptual files to pick login methods, user types, and token strategy.
87+
- Then use Web/Node/HTTP sections to implement and verify the flow end-to-end.
88+
89+
5. **Use troubleshooting only when needed**
90+
- Only read `troubleshooting/faq.md` when the user has issues like “anonymous vs not logged in”, unexpected expiration, or captcha errors.
91+
92+
Keep this file short in context. Load deeper files selectively based on the user’s question to keep the context window efficient.

‎config/skills/auth-skill/concepts/login_methods.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
## Login methods in CloudBase Auth v2
2+
3+
This file summarizes the login methods and when to use them.
4+
5+
### Anonymous login
6+
7+
**What it is**
8+
9+
- The SDK creates an **anonymous user** with a stable `uid` on the device.
10+
- The user can access CloudBase resources according to your security rules.
11+
12+
**Typical use cases**
13+
14+
- Guest users trying a product without registration.
15+
- Games or apps where you want to store personal progress before sign-up.
16+
17+
**Key points**
18+
19+
- One anonymous user per device; it **never expires** logically, but clearing local data may drop it.
20+
- You can later **upgrade** an anonymous user to a formal user (see below).
21+
22+
### Username/password login
23+
24+
**What it is**
25+
26+
- User logs in with a **username** and **password**.
27+
- `username` can be:
28+
- Phone number
29+
- Email
30+
- Custom username
31+
32+
**Key points**
33+
34+
- Direct sign-up via “username + password” alone is **not allowed**.
35+
- Users are usually registered via SMS/email verification, then a username is bound.
36+
- This reduces spam/abuse from arbitrary username registrations.
37+
38+
### SMS verification code login
39+
40+
**What it is**
41+
42+
- User logs in with **phone number + SMS code**.
43+
44+
**Key points**
45+
46+
- Requires enabling SMS login and configuring SMS sending.
47+
- Flow typically:
48+
1. Send verification code to phone.
49+
2. Verify code.
50+
3. Login or sign-up depending on whether the user exists.
51+
- Subject to per-number **frequency limits** (e.g. 30 seconds between sends, daily quotas).
52+
53+
### Email verification code login
54+
55+
**What it is**
56+
57+
- User logs in with **email + one-time email code**.
58+
59+
**Key points**
60+
61+
- Requires enabling email login and setting up SMTP (sender, host, port, security mode).
62+
- Similar flow to SMS:
63+
1. Send verification to email.
64+
2. Verify code.
65+
3. Login or sign-up.
66+
67+
### WeChat login
68+
69+
**What it is**
70+
71+
- Login via **WeChat Open Platform**.
72+
- Users authorize via WeChat; CloudBase creates or reuses a corresponding user.
73+
74+
**Key points**
75+
76+
- You must configure WeChat app ID/secret in the CloudBase console.
77+
- The Web SDK helps generate the WeChat OAuth URL and exchange authorization `code` for a provider token.
78+
- Subsequent calls use a CloudBase token, not the raw WeChat token.
79+
80+
### Custom login
81+
82+
**What it is**
83+
84+
- You already have your own identity system and want to map your user IDs to CloudBase users.
85+
- Your backend/Cloud Function issues **custom login tickets** signed with a private key.
86+
87+
**Key points**
88+
89+
- Steps:
90+
1. Download CloudBase custom login private key from the console.
91+
2. Use Node SDK (or HTTP API) to issue tickets for your users.
92+
3. The client uses the ticket to log into CloudBase.
93+
- CloudBase creates a CloudBase user on first login and keeps the mapping to your `customUserId`.
94+
95+
### Anonymous → formal user upgrade
96+
97+
Regardless of the initial login method, you can:
98+
99+
- Let users start anonymously.
100+
- Later, when they provide phone/email/username, upgrade that anonymous account:
101+
- Data created while anonymous is preserved and associated with the new formal identity.
102+
103+
This pattern is critical for:
104+
105+
- Reducing friction at first use.
106+
- Avoiding data loss when users decide to register.
107+
108+

‎config/skills/auth-skill/concepts/overview.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
## CloudBase Auth v2 overview
2+
3+
CloudBase Auth v2 is the identity layer for CloudBase. It provides:
4+
5+
- A unified **user account system** with a stable `uid` per user
6+
- Multiple **login methods** (anonymous, username/password, SMS, email, WeChat, custom login)
7+
- **Token-based** authentication using JWT `access_token` and long-lived `refresh_token`
8+
- Tight integration with **database**, **storage**, and **security rules**
9+
10+
From the console perspective, you configure auth in **云开发控制台 → 身份认证** where you can:
11+
12+
- Open or close login methods
13+
- View and manage users
14+
- Inspect login records and basic behavior
15+
16+
From the app perspective:
17+
18+
- Every request from a logged-in user carries an auth token.
19+
- CloudBase validates the token and enforces **permissions** before executing operations.
20+
21+
## Supported login methods
22+
23+
Auth v2 supports:
24+
25+
- **Anonymous login** – frictionless trial, no registration; the user still has a stable `uid` on one device.
26+
- **Username/password login** – traditional credentials; username can be phone, email, or a custom username.
27+
- **SMS code login** – phone number + verification code.
28+
- **Email code login** – email + verification code.
29+
- **WeChat login** – via WeChat Open Platform for web/mobile apps.
30+
- **Custom login** – you issue a ticket from your own identity system; CloudBase trusts and maps it to a CloudBase user.
31+
32+
Each method ultimately produces the same kind of CloudBase user and token set. The main differences are in:
33+
34+
- UX and friction
35+
- Regulation/verification requirements (e.g. phone or email ownership)
36+
- How you bootstrap the user into your product
37+
38+
Details per login method are summarized in `concepts/login_methods.md`.
39+
40+

‎config/skills/auth-skill/concepts/tokens_and_sessions.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
## Tokens, sessions, and v1 vs v2 differences
2+
3+
CloudBase Auth v2 uses a **dual token** model:
4+
5+
- Short-lived **access token** (`access_token`)
6+
- Long-lived **refresh token** (`refresh_token`)
7+
8+
The Web/Node SDKs automatically manage these tokens for you; HTTP integrations need to manage them explicitly.
9+
10+
### Access token (v2)
11+
12+
- Format: **standard JWT**.
13+
- Encryption/signature: asymmetric (e.g. `ES256` / `RS256` style).
14+
- Public keys:
15+
- Exposed via `https://{{EnvID}}.ap-shanghai.tcb-api.tencentcloudapi.com/auth/v1/certs`
16+
- Replace `{{EnvID}}` with your actual environment ID.
17+
- Supports **distributed verification**:
18+
- Any service with the public key can verify tokens without talking back to CloudBase.
19+
20+
Typical properties:
21+
22+
- Short lifetime (e.g. ~2 hours).
23+
- Used as the bearer token to call CloudBase services.
24+
25+
### Refresh token
26+
27+
Refresh tokens:
28+
29+
- Are long-lived (e.g. ~30 days).
30+
- Are used to get new access tokens.
31+
- Are usually stored and rotated by the SDK.
32+
33+
Important behaviors:
34+
35+
- As long as the refresh token is valid, the SDK can silently refresh the access token.
36+
- For anonymous users, refresh tokens can auto-renew to preserve long-term anonymous sessions.
37+
38+
### v1 vs v2 access tokens (for migration)
39+
40+
Key differences:
41+
42+
- **Format**
43+
- v2: standard JWT
44+
- v1: non-standard JWT string (often with environment-specific suffixes)
45+
- **Signing**
46+
- v2: asymmetric; public keys rotate regularly
47+
- v1: symmetric per-environment key
48+
- **Verification**
49+
- v2: supports distributed verification through public keys
50+
- v1: typically verified only by CloudBase itself
51+
52+
When building new systems, prefer **v2**. For migration:
53+
54+
- Be aware that token parsing and validation code must be updated.
55+
- If you previously depended on v1’s specific string format, refactor to treat v2 as a standard JWT.
56+
57+
### Validating v2 access tokens in your backend
58+
59+
For backends that need to trust CloudBase tokens directly:
60+
61+
1. Choose a JWT library for your language (see `jwt.io`).
62+
2. Fetch CloudBase public keys:
63+
- `https://{{EnvID}}.ap-shanghai.tcb-api.tencentcloudapi.com/auth/v1/certs`
64+
3. Configure your verifier with:
65+
- The key set
66+
- Expected issuer (`iss`)
67+
- Expected audience (`aud`)
68+
4. Verify:
69+
- Signature is valid
70+
- Token is not expired
71+
- Claims such as `user_id`, `user_type`, `project_id` meet your expectations
72+
73+
If signature and validity checks pass, you can trust the token as representing a CloudBase user.
74+
75+
### Login state persistence (Web SDK)
76+
77+
In the Web SDK v2:
78+
79+
- Only `local` storage mode is supported for login state.
80+
- This means:
81+
- Login state persists across browser reloads.
82+
- It persists until the user explicitly signs out or you clear local data.
83+
84+
Implications:
85+
86+
- UX is smoother (fewer forced re-logins).
87+
- You should **check for existing login state** on app startup to avoid redundant sign-in flows.
88+
89+

0 commit comments

Comments
 (0)