auth-skill

When to use this skill

Use this skill whenever the task involves authentication or user identity in a CloudBase project, for example:

• Designing which login methods to support (anonymous, username/password, SMS, email, WeChat, custom login)
• Implementing auth with Web SDK (@cloudbase/[email protected]) on the frontend
• Working with Node SDK for user info, admin operations, or issuing custom login tickets
• Calling HTTP auth APIs directly from any backend or script
• Understanding tokens, login state, and auth-related best practices

If the task is not about authentication (e.g. only about database or storage), this skill is probably not needed.

Quick orientation

CloudBase Auth v2 provides:

• Multiple login methods with a unified user identity system
• Clear user types (internal, external, anonymous) and account linking
• A token-based session model with JWT access tokens and refresh tokens
• SDKs (Web, Node) and HTTP APIs that expose the same core flows

This SKILL.md acts as a launcher. For deeper details, read the linked files only as needed.

Table of contents (progressive disclosure)

1. Concepts & design

• concepts/overview.md – what CloudBase Auth v2 is, high-level architecture, and where to configure it.
• concepts/login_methods.md – supported login methods, when to use each, and tradeoffs.
• concepts/user_accounts_and_roles.md – internal vs external vs anonymous users, UIDs, and multi-account linking.
• concepts/tokens_and_sessions.md – access_token vs refresh_token, v1 vs v2, and validation.

2. Web SDK (@cloudbase/[email protected])

• web-sdk/web_quickstart.md – install/init SDK, get auth instance, basic sign-up/sign-in flow.
• web-sdk/web_login_flows.md – concrete flows for:
  • Username/password
  • SMS verification code login
  • Email verification code login
  • Anonymous login and upgrade
  • WeChat OAuth login
• web-sdk/captcha_and_rate_limits.md – when captchas are triggered, how to integrate the captcha adapter + UI, and how to handle errors.
• web-sdk/web_best_practices.md – avoiding redundant logins, login-state persistence, and common UX patterns.

3. Node SDK & custom login

• 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.
• node-sdk/node_custom_login_ticket.md – issuing custom login tickets on the server and integrating with your own user system.

4. HTTP APIs

• http-api/http_overview.md – the HTTP API surface for auth and how to discover endpoints.
• 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.

5. Troubleshooting & FAQ

• troubleshooting/faq.md – common questions and pitfalls: anonymous vs unauthenticated, token expiry, verification limits, etc.

How to use this skill

When working on a CloudBase auth task, follow this sequence:

1. Clarify the scenario

   • Is this frontend Web, Node backend/cloud function, or a generic backend calling HTTP APIs?
   • What login methods are required (e.g. phone, email, WeChat, custom SSO, anonymous trial)?
   • Are there existing users/identity systems that must be integrated?

2. Load only the relevant conceptual context

   • For high-level decisions, read:
     • concepts/overview.md
     • concepts/login_methods.md
     • concepts/user_accounts_and_roles.md
   • Read concepts/tokens_and_sessions.md only if token behavior or migration is important to the task.

3. Jump to the relevant implementation section

   • 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).
   • For Node/server logic or custom login ticket issuance, use the node-sdk/ files.
   • For language-agnostic HTTP integration, use the http-api/ files.

4. Design first, then code

   • Use the conceptual files to pick login methods, user types, and token strategy.
   • Then use Web/Node/HTTP sections to implement and verify the flow end-to-end.

5. Use troubleshooting only when needed

   • Only read troubleshooting/faq.md when the user has issues like “anonymous vs not logged in”, unexpected expiration, or captcha errors.

Keep this file short in context. Load deeper files selectively based on the user’s question to keep the context window efficient.