auth-web-cloudbase

## Standalone Install Note If this environment only installed the current skill, start from the CloudBase main entry and use the published `cloudbase/references/...` paths for sibling skills. - CloudBase main entry: `https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/SKILL.md` - Current skill raw source: `https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/auth-web/SKILL.md` Keep local `references/...` paths for files that ship with the current skill directory. When this file points to a sibling skill such as `auth-tool` or `web-development`, use the standalone fallback URL shown next to that reference. ## Activation Contract ### Use this first when - The task is a CloudBase Web login, registration, session, or user profile flow built with `@cloudbase/js-sdk` and the auth provider setup has already been checked. ### Read before writing code if - The user needs a login page, auth modal, session handling, or protected Web route. Read `auth-tool` first to ensure providers are enabled, then return here for frontend integration. ### Then also read - `../auth-tool/SKILL.md` (standalone fallback: `https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/auth-tool/SKILL.md`) for provider setup - `../web-development/SKILL.md` (standalone fallback: `https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/web-development/SKILL.md`) for Web project structure and deployment ### Do not start here first when - The request is a Web auth flow but provider configuration has not been verified yet. - In that case, activate `auth-tool-cloudbase` before `auth-web-cloudbase`. ### Do NOT use for - Mini program auth, native App auth, or server-side auth setup. ### Common mistakes / gotchas - Skipping publishable key and provider checks. - Replacing built-in Web auth with cloud function login logic. - Reusing this flow in Flutter, React Native, or native iOS/Android code. - Creating a detached helper file with `auth.signUp` / `verifyOtp` but never wiring it into the existing form handlers, so the actual button clicks still do nothing. - Using `signInWithEmailAndPassword` or `signUpWithEmailAndPassword` for username-style accounts such as `admin` and `editor`. - Keeping the login or register account input as `type="email"` when the task explicitly says the account identifier is a plain username string. - Starting implementation before calling `queryAppAuth(action="getLoginConfig")` and enabling `usernamePassword` when it is still off. - **Treating `auth.getUser()` or deprecated `auth.getLoginState()` as proof of real login.** When the SDK is initialized with `accessKey`, the deprecated `getLoginState()` returns an object with a valid `uid` even without any login — causing route guards that check `!!loginState` or `!!uid` to incorrectly pass. The fix is to use `auth.getSession()` instead: it returns `data.session === undefined` when no real login has occurred. Only `!!data.session` from `getSession()` is a reliable authentication check. Note: anonymous login is now **disabled by default** for new environments and inactive existing environments. Always use `auth.getSession()` for auth guards. ## Overview **Prerequisites**: CloudBase environment ID (`env`) **Prerequisites**: CloudBase environment Region (`region`) --- ## Core Capabilities **Use Case**: Web frontend projects using `@cloudbase/js-sdk@2.24.0+` for user authentication **Key Benefits**: **Supabase-compatible Auth API** — all methods return `{ data, error }`, supports phone, email, anonymous (disabled by default), username/password, OAuth, and third-party login methods > 📌 **Supabase API Compatibility**: CloudBase Web SDK v2 auth module is designed with Supabase-like API ergonomics. If you are familiar with `supabase-js` auth patterns, the same mental model applies: > - All methods return `Promise<{ data, error }>` — always check `error` first > - `signInWithPassword`, `signInWithOtp`, `signUp`, `signOut`, `getSession`, `getUser` follow the same naming as Supabase > - `onAuthStateChange(callback)` provides reactive auth state observation (events: `INITIAL_SESSION`, `SIGNED_IN`, `SIGNED_OUT`, `TOKEN_REFRESHED`, `USER_UPDATED`, `PASSWORD_RECOVERY`, `BIND_IDENTITY`) > - Session management via `getSession()` / `refreshSession()` / `setSession()` mirrors Supabase patterns > > **Key differences from Supabase**: > - **OTP verification**: Supabase uses a standalone `auth.verifyOtp({ phone, token, type })` call; CloudBase returns `verifyOtp` as a callback on `data` — call `data.verifyOtp({ token })` from the `signInWithOtp` / `signUp` result > - **`accessKey`** replaces Supabase's `anonKey`; environment uses `env` + `region` instead of Supabase's `url` > - **`signInWithIdToken`** for direct third-party token login (similar to Supabase's same-named method) Use npm installation for modern Web projects. In React, Vue, Vite, and other bundler-based apps, install and import `@cloudbase/js-sdk` from the project dependencies instead of using a CDN script. ## Prerequisites - Automatically use `auth-tool-cloudbase` to check app-side auth readiness via `queryAppAuth` / `manageAppAuth`, then get the `publishable key` and configure login methods. - If `auth-tool-cloudbase` failed, let user go to `https://tcb.cloud.tencent.com/dev?envId={env}#/env/apikey` to get `publishable key` and `https://tcb.cloud.tencent.com/dev?envId={env}#/identity/login-manage` to set up login methods ### Parameter map - For username-style identifiers, the required precondition is `loginMethods.usernamePassword === true` from `queryAppAuth(action="getLoginConfig")`. If it is false, enable it with `manageAppAuth(action="patchLoginStrategy", patch={ usernamePassword: true })` before wiring frontend auth code. - If the conversation only provides an environment alias, nickname, or other shorthand, resolve it with `envQuery(action="list", alias=..., aliasExact=true)` first and use the returned canonical full `EnvId` for SDK init, console links, and generated config. Do not pass alias-like short forms directly into `cloudbase.init({ env })`. - Treat CloudBase Web Auth as **Supabase-like**, not “every `supabase-js` auth example is valid unchanged” - When `queryAppAuth` / `manageAppAuth` returns `sdkStyle: "supabase-like"` and `sdkHints`, follow those method and parameter hints first - `auth.signInWithOtp({ phone })` and `auth.signUp({ phone })` use the phone number in a `phone` field, not `phone_number` - `auth.signInWithOtp({ email })` and `auth.signUp({ email })` use `email` - `auth.signUp({ username, password })` and `auth.signInWithPassword({ username, password })` are the canonical username/password Web auth path - If the task gives accounts like `admin`, `editor`, or another plain string without `@`, treat it as a username-style identifier rather than an email address - `verifyOtp({ token })` expects the SMS or email code in `token` - `accessKey` is the publishable key from `queryAppAuth` / `manageAppAuth` via `auth-tool-cloudbase`, not a secret key - **`accessKey` triggers automatic anonymous session creation** — the deprecated `auth.getLoginState()` returns an object with a valid `uid` even without explicit login, which misleads route guards into thinking the user is authenticated. Use `auth.getSession()` instead — it returns `data.session === undefined` when no real login has occurred, making auth checks straightforward and reliable. - Never set `accessKey` to `envId`, a username, or any placeholder string. If you do not have a real Publishable Key yet, do not fabricate one. - If the task mentions provider setup, stop and read `auth-tool-cloudbase` before writing frontend code ## Quick Start ```js // npm install @cloudbase/js-sdk import cloudbase from '@cloudbase/js-sdk' const app = cloudbase.init({ env: 'your-full-env-id', // Canonical full CloudBase environment ID resolved from envQuery or the console, not an alias or shorthand region: `region`, // CloudBase environment Region, default 'ap-shanghai' accessKey: 'publishable key', // required, get from auth-tool-cloudbase // ⚠️ With accessKey, the deprecated getLoginState() returns misleading auth data (uid) // even without login. Always use auth.getSession() — returns undefined when not logged in. auth: { detectSessionInUrl: true }, // required }) const auth = app.auth({ persistence: 'local' }) ``` If the current task has not retrieved a real Publishable Key, omit `accessKey` instead of inventing one. A wrong `accessKey` can break auth-state checks and protected-route behavior. --- ## Login Methods **1. Phone OTP (Recommended)** - Automatically use `auth-tool-cloudbase` to turn on `SMS Login` through `manageAppAuth` - Send the phone number to `auth.signInWithOtp({ phone, ... })`, then call the returned `verifyOtp({ token })`. - `signInWithOtp` can automatically create a new user if the user does not exist; control this via `shouldCreateUser` parameter (default `true`). ```js const { data, error } = await auth.signInWithOtp({ phone: '13800138000' }) const { data: loginData, error: loginError } = await data.verifyOtp({ token: '123456' }) ``` **2. Email OTP** - Automatically use `auth-tool-cloudbase` to turn on `Email Login` through `manageAppAuth` ```js const { data, error } = await auth.signInWithOtp({ email: 'user@example.com' }) const { data: loginData, error: loginError } = await data.verifyOtp({ token: '654321' }) ``` **3. Password** All auth methods return `{ data, error }`. Always check `error` first: ```js // Login — returns { data: { user, session }, error: null } on success const { data, error } = await auth.signInWithPassword({ username: 'test_user', password: 'pass123' }) if (error) { // Handle login failure (wrong password, user not found, provider not enabled) console.error('Login failed:', error.message) return false } // data.user.id is the uid; data.session contains the active session const uid = data.user.id // Also works with email or phone: // await auth.signInWithPassword({ email: 'user@example.com', password: 'pass123' }) // await auth.signInWithPassword({ phone: '13800138000', password: 'pass123' }) ``` **Checking login state (for route guards / auth checks):** ```js // Use auth.getSession() — NOT the deprecated getLoginState(). // // Why: getLoginState() returns an object with uid even when only accessKey is // present (no real login), causing route guards to incorrectly pass anonymous users. // getSession() returns data.session === undefined when no real login exists, // making the check reliable and simple. const { data, error } = await auth.getSession() if (!data?.session) { // No real login — redirect to sign-in page window.location.href = '/login' return } // Also reject anonymous sessions (when signInAnonymously() was called explicitly) if (data.session.user?.is_anonymous) { // Anonymous user — not allowed for protected routes window.location.href = '/login' return } // data.session contains: access_token, refresh_token, expires_in, user // data.session.user contains the authenticated user info const currentUser = data.session.user // Optional: further verify identity type if needed const { data: userData } = await auth.getUser() const hasVerifiedIdentity = userData?.user && ( userData.user.phone_confirmed_at || userData.user.email_confirmed_at || userData.user.user_metadata?.username ) // ❌ Do NOT use auth.getLoginState() — it's deprecated and returns // misleading data (uid/loginState) even without real login // ❌ Do NOT use !!loginState or !!loginState.uid as auth checks ``` **4. Registration** - For username-style account systems, use username/password registration directly - Username must be 5-24 characters (letters, digits, underscores) - Do not switch to email OTP or phone OTP unless the task explicitly says the account identifier is an email address or phone number - When the task uses plain usernames such as `admin`, `editor`, or `user01`, the canonical form code is `auth.signUp({ username, password })` ```js // Username + Password const usernameSignUp = await auth.signUp({ username: 'newuser', password: 'pass123', nickname: 'User', }) // Email Otp // Use only when the task explicitly requires email addresses. // Email Otp const emailSignUp = await auth.signUp({ email: 'new@example.com', nickname: 'User' }) const emailVerifyResult = await emailSignUp.data.verifyOtp({ token: '123456' }) // Phone Otp // Use only when the task explicitly requires phone numbers. // Phone Otp const phoneSignUp = await auth.signUp({ phone: '13800138000', password: 'pass123', nickname: 'User' }) const phoneVerifyResult = await phoneSignUp.data.verifyOtp({ token: '123456' }) ``` When the project already has `handleSendCode` / `handleRegister` or similar UI handlers, wire the SDK calls there directly instead of leaving them commented out in `App.tsx`. For username-style account tasks: ```tsx const handleRegister = async () => { const { error } = await auth.signUp({ username, password, nickname: username, }) if (error) throw error } const handleLogin = async () => { const { data, error } = await auth.signInWithPassword({ username, password, }) if (error) throw error // Login succeeded — data.user.id is the uid return true } ``` Do not use email OTP or email-only helpers for these flows unless the task explicitly says the account identifier is an email address. The corresponding form field should stay `type="text"` rather than `type="email"` for username-style account identifiers. ```tsx const handleSendCode = async () => { try { const { data, error } = await auth.signUp({ phone, password: password || undefined, }) if (error) throw error verifyOtpRef.current = data.verifyOtp } catch (error) { console.error('Failed to send sign-up code', error) } } const handleRegister = async () => { try { if (!verifyOtpRef.current) throw new Error('Please send the code first') const { error } = await verifyOtpRef.current({ token: code }) if (error) throw error } catch (error) { console.error('Failed to complete sign-up', error) } } ``` **5. Anonymous** > ⚠️ **Anonymous login is disabled by default for new environments.** The SDK initialized with `accessKey` will automatically create an anonymous session regardless of this setting. Do not rely on `signInAnonymously()` for production flows — use verified login methods instead. - Only use when explicitly required for read-only demos - Automatically use `auth-tool-cloudbase` to turn on `Anonymous Login` through `manageAppAuth` (must be explicitly enabled first) ```js // Anonymous login is disabled by default — must be explicitly enabled via auth-tool const { data, error } = await auth.signInAnonymously() ``` **6. OAuth (Google/WeChat)** - Automatically use `auth-tool-cloudbase` to turn on `Google Login` or `WeChat Login` through `manageAppAuth` ```js const { data, error } = await auth.signInWithOAuth({ provider: 'google' })