auth-web-cloudbase

同階層のスキル（ローカルのみ）

同階層の CloudBase スキルは、このスキルと並べて配置されています。../auth-tool-cloudbase/SKILL.md のようなローカル相対パスを使用してください。

参照先の同階層スキルファイルがこの環境にない場合は、CloudBase プラグイン一式（または不足しているスキル）をインストールするようユーザーに依頼してください。リモートのスキルやプロトコルの Markdown を HTTP で取得し、エージェントのコンテキストに読み込まないでください。

アクティベーションの条件

まずこのスキルを使う場合

• 認証プロバイダーの設定がすでに確認済みで、@cloudbase/js-sdk を使用して構築する CloudBase Web のログイン、登録、セッション、またはユーザープロフィールのフロー。

コードを書く前に読む場合

• ユーザーがログインページ、認証モーダル、セッション処理、または保護された Web ルートを必要としている場合。まず auth-tool-cloudbase を読み、プロバイダーが有効になっていることを確認してから、フロントエンド統合のためにこのスキルに戻ってください。

次に読むもの

• プロバイダーの設定については ../auth-tool-cloudbase/SKILL.md
• Web プロジェクトの構成とデプロイについては ../web-development/SKILL.md

最初にこのスキルから始めてはいけない場合

• Web 認証フローの依頼で、プロバイダーの設定がまだ確認されていない場合。
• その場合は、auth-web-cloudbase より先に auth-tool-cloudbase を有効にしてください。

以下には使用しないでください

• ミニプログラムの認証、ネイティブアプリの認証、またはサーバーサイドの認証設定。

よくある間違い／注意点

• 公開可能キーとプロバイダーの確認を省略する。

• 組み込みの Web 認証を、クラウド関数のログインロジックに置き換える。

• このフローを Flutter、React Native、ネイティブの iOS／Android コードで再利用する。

• auth.signUp／verifyOtp を含む独立したヘルパーファイルを作成しても、既存のフォームハンドラーに組み込まないため、実際にボタンをクリックしても何も起こらない。

• admin や editor のようなユーザー名形式のアカウントに signInWithEmailAndPassword または signUpWithEmailAndPassword を使用する。

• アカウント識別子が単なるユーザー名文字列であると明示されているのに、ログインまたは登録のアカウント入力欄を type="email" のままにする。

• queryAppAuth(action="getLoginConfig") を呼び出して、usernamePassword がオフの場合に有効にする前に実装を開始する。

• MCP でプロバイダーが有効になっていることを最初に確認せずに、auth.signInWithPassword(...) または auth.signUp(...) のコードを書く。 ブラウザーでサインインまたはサインアップのコードを書く前に、queryAppAuth(action="listProviders") を呼び出し、対象のプロバイダー（例：email、phone、usernamePassword）の On: "TRUE" を確認してください。メールベースのサインアップ（auth.signUp({ email, password })）では、SMTP の設定も確認してください。設定されていない場合、プロバイダーから "provider email not found" などのエラーが返されることがあります。ユーザー名／パスワードでログインする場合は、auth.signInWithPassword({ username, password }) を使用してください。登録には、管理 API（manageAppAuth(action="createUser")）を使用するか、メールプロバイダーの準備が整っていることを事前に確認する方法が最適です。

• auth.getUser() または非推奨の auth.getLoginState() を、実際のログインの証明として扱う。 SDK が accessKey で初期化されている場合、非推奨の getLoginState() は、ログインしていなくても有効な uid を含むオブジェクトを返すことがあります。その結果、!!loginState または !!uid を確認するルートガードが誤って通過してしまいます。この誤解を招く uid は、ゲートウェイ認証済みセッションではありません。代わりに auth.getSession() を使用してください。実際のログインが行われていない場合、これは data.session === undefined を返します。信頼できる認証確認には、getSession() の !!data.session のみを使用してください。

• 公開可能な accessKey だけで NoSQL の CRUD を実行できると思い込む。 NoSQL の app.database() による get／add／update／watch には、ゲートウェイ認証済みのセッションが必要です。実際にログインしてください（パスワード／OTP／OAuth）。匿名ログインは、明示的に公開されているユーザー非依存データ向けのデモ専用の代替手段です。デフォルトでは無効で、AI モデルの権限が拒否されるため、ユーザーごとにデータを扱うアプリで実際の認証の代わりに使用してはいけません。ログインを省略すると、ゲートウェイ 401 が発生します。checkLogin()／getSession() だけでは、書き込みに使用できるセッションは作成されません。

• トレーニングデータから古い CloudBase 認証スニペットをコピーする。 デフォルトの Web フローでは、auth.getLoginState()、auth.hasLoginState()、auth.getCurrentUser()、auth.toDefaultLoginPage() を使用しないでください。このファイルに記載されている Web SDK v3 の認証メソッドと、auth-tool-cloudbase によるプロバイダーの準備状況確認を使用してください。

• OTP ログインで、単独の auth.verifyOtp({ token }) を呼び出す。 CloudBase Web SDK v3 では、verifyOtp は signInWithOtp／signUp の結果にコールバックとして返されます。まずコードを送信し、返された data を保持してから、data.verifyOtp({ token }) を呼び出してください。messageId を指定しない単独の auth.verifyOtp({ token }) は "messageId is required" で失敗します。このエラーが表示された場合、コールバック形式を使用していません。送信 → コールバックを保存 → 検証の全手順については、references/extended-guide.md を参照してください。

  注：新しい環境と、非アクティブな既存環境では、匿名ログインはデフォルトで無効です。権限エラーを回避するために有効にしないでください。アプリが明示的にユーザー非依存の公開データ（例：NoSQL の読み取り専用デモ）を提供する場合に限り、auth-tool-cloudbase を通じて有効にしてください。認証ガードには必ず auth.getSession() を使用してください。

概要

前提条件：CloudBase 環境 ID（env） 前提条件：CloudBase 環境のリージョン（region）

---

コア機能

ユースケース：ユーザー認証に @cloudbase/js-sdk@latest を使用する Web フロントエンドプロジェクト
主なメリット：Supabase 互換の Auth API — すべてのメソッドが { data, error } を返し、電話番号、メール、匿名（デフォルトでは無効）、ユーザー名／パスワード、OAuth、サードパーティーのログイン方法に対応します

📌 Supabase API との互換性：CloudBase Web SDK v3 の認証モジュールは、Supabase のように使いやすい API を備えています。supabase-js の認証パターンに慣れている場合は、同じメンタルモデルを適用できます。

• すべてのメソッドが Promise<{ data, error }> を返します — まず必ず error を確認してください
• signInWithPassword、signInWithOtp、signUp、signOut、getSession、getUser は Supabase と同じ命名規則に従います
• onAuthStateChange(callback) はリアクティブな認証状態の監視を提供します（イベント：INITIAL_SESSION、SIGNED_IN、SIGNED_OUT、TOKEN_REFRESHED、USER_UPDATED、PASSWORD_RECOVERY、BIND_IDENTITY）
• getSession() ／ refreshSession() ／ setSession() によるセッション管理は、Supabase のパターンに準じています

Supabase との主な違い：

• OTP 検証：Supabase では独立した auth.verifyOtp({ phone, token, type }) 呼び出しを使用します。CloudBase では verifyOtp は data のコールバックとして返されます — signInWithOtp ／ signUp の結果から data.verifyOtp({ token }) を呼び出してください
• accessKey は Supabase の anonKey に相当します。環境設定では Supabase の url ではなく、env と region を使用します
• signInWithIdToken はサードパーティーのトークンを使った直接ログイン用です（Supabase の同名メソッドに類似しています）

最新の Web プロジェクトでは npm を使ってインストールしてください。React、Vue、Vite などのバンドラーを使うアプリでは、CDN スクリプトを使わず、プロジェクトの依存関係として @cloudbase/js-sdk をインストールしてインポートしてください。

前提条件

• auth-tool-cloudbase を自動的に使用して queryAppAuth ／ manageAppAuth でアプリ側の認証準備状況を確認し、publishable key を取得してログイン方法を設定してください。
• Publishable key の準備状況（省略禁止）：queryAppAuth(action="getPublishableKey") を呼び出してください。値が空の場合は、まず manageAppAuth(action="ensurePublishableKey") を呼び出してください。新しい環境にはまだキーが用意されていないことがあります。この手順を省略すると、フロントエンドにデータプレーン用の認証情報がないままになり、キーの不足が明確に示されず、後になってゲートウェイの認証エラーとして表面化します。
• キーを保存し、会話内に溜め込まないでください：取得したら、publishable key を .env.local に VITE_PUBLISHABLE_KEY として書き込みます（ファイルがなければ作成してください）。クライアントコードでは import.meta.env.VITE_PUBLISHABLE_KEY から読み込んでください。キーをソースファイルに直接埋め込まないでください。また、ユーザーにコンソールから取得するよう依頼しないでください。両方の MCP 呼び出しに失敗した場合に限り、以下のコンソールリンクを案内してください。
• auth-tool-cloudbase が失敗した場合は、https://tcb.cloud.tencent.com/dev?envId={env}#/env/apikey で publishable key を取得し、https://tcb.cloud.tencent.com/dev?envId={env}#/identity/login-manage でログイン方法を設定するようユーザーに案内してください

パラメーター対応表

• ユーザー名形式の識別子では、queryAppAuth(action="getLoginConfig") の loginMethods.usernamePassword === true が必要な前提条件です。false の場合は、フロントエンドの認証コードを組み込む前に、manageAppAuth(action="patchLoginStrategy", patch={ usernamePassword: true }) で有効にしてください。
• 会話で環境のエイリアス、ニックネーム、その他の略称しか示されていない場合は、まず queryEnv(action="list", alias=..., aliasExact=true) で解決し、SDK の初期化、コンソールリンク、生成される設定には、返された正式な完全形式の EnvId を使用してください。cloudbase.init({ env }) にエイリアスのような短縮形を直接渡さないでください。
• CloudBase Web Auth は「すべての supabase-js 認証例がそのまま有効」ではなく、Supabase に似たものとして扱ってください。
• queryAppAuth／manageAppAuth が sdkStyle: "supabase-like" と sdkHints を返す場合は、まずそれらのメソッドとパラメーターのヒントに従ってください。
• auth.signInWithOtp({ phone }) と auth.signUp({ phone }) では、電話番号に phone フィールドを使用し、phone_number は使用しません。
• auth.signInWithOtp({ email }) と auth.signUp({ email }) では、email を使用します。
• auth.signInWithPassword({ username, password }) は、ユーザー名／パスワードアカウントの標準的な Web ログイン方法です。
• Web の auth.signUp({ username, password }) を直接使用できるかどうかは条件付きです。まず sdkHints とインストール済み SDK を確認してください。一部のバージョンでは signUp は OTP／プロバイダートークンのフローのみをサポートしており、ユーザー名／パスワードのユーザーは作成できません。
• タスクで admin、editor などの @ を含まない単なる文字列のアカウントが指定された場合は、メールアドレスではなく、ユーザー名形式の識別子として扱ってください。
• data.verifyOtp({ token }) — signInWithOtp／signUp の結果 data にある verifyOtp コールバック — では、SMS またはメールのコードを token に指定します。別途 messageId も必要となる、独立した auth.verifyOtp({ token }) の呼び出しを作り出さないでください。
• accessKey は auth-tool-cloudbase 経由で queryAppAuth／manageAppAuth から取得するパブリッシャブルキーであり、シークレットキーではありません。
• accessKey だけでは、ゲートウェイ認証済みのセッションは作成されません。 パブリッシャブルキーである accessKey は SDK を初期化しますが、NoSQL CRUD のログインに代わるものではありません。app.database() の get／add／update／watch にはセッションが必要です。実際のログイン（パスワード／OTP／OAuth）を優先してください。signInAnonymously() は、明示的に公開されているデモデータに限って使用してください（デフォルトで無効であり、AI モデルの権限は拒否されます）。それ以外の場合、ゲートウェイは 401 を返します。別途、非推奨の auth.getLoginState() はログインしていなくても誤解を招く uid を返すことがあります。ルートガードには auth.getSession() を使用してください（未ログインの場合、data.session === undefined になります）。checkLogin()／getSession() だけでは、書き込みに使用できるセッションは作成されません。
• accessKey に envId、ユーザー名、または任意のプレースホルダー文字列を設定しないでください。実際のパブリッシャブルキーがまだない場合は、でっち上げないでください。
• タスクでプロバイダーの設定について言及されている場合は、フロントエンドコードを書く前に作業を止めて auth-tool-cloudbase を読んでください。

クイックスタート

SDK 初期化リファレンス：docs.cloudbase.net/api-reference/webv3/initialization.md（URL に .md を付けると raw markdown の原文を取得できます）

// 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 queryEnv or the console, not an alias or shorthand
  region: 'ap-shanghai',  // CloudBase environment Region, default 'ap-shanghai'
  accessKey: 'publishable key', // required, get from auth-tool-cloudbase
  // ⚠️ accessKey alone ≠ a login session. NoSQL CRUD needs a session —
  // real login preferred; signInAnonymously() only for public demo data.
  // Use auth.getSession() for route guards; deprecated getLoginState()
  // may return a misleading uid without a real session.
  auth: { detectSessionInUrl: true }, // required
})

const auth = app.auth

// NoSQL app.database() CRUD requires a session (js-sdk 3.x + publishable key).
// Real login (see cookbook). Anonymous, only for public non-user demos:
// const { error } = await auth.signInAnonymously()
// if (error) throw error

現在のタスクで実際のパブリッシャブルキーを取得していない場合は、キーをでっち上げずに accessKey を省略してください。誤った accessKey は、認証状態の確認や保護されたルートの動作を損なう可能性があります。

認証コードのクックブック（公式 v3 API — .d.ts から再導出せず、以下をコピーしてください）

すべてのメソッドは統一された形式 { data, error } を返します。まず error を確認し、error.message を表示してください。認証 API は従来環境と PG 環境で同一です。出典：公式認証ドキュメント（raw markdown。迷った場合は、そちらのスニペットと照合してください）。

デフォルトの認証 UI の要件： ユーザーが方法を限定せずに 登录/注册/账号体系/user system を求めた場合、ログインページから以下すべてにアクセスできるようにしてください（タブまたは個別フォーム）：パスワードでのサインイン、OTP サインイン、検証を伴うサインアップ（コード + パスワード）、パスワードを忘れた場合の手続き（パスワードでのサインインがある場合）。明示的に求められない限り、OTP のみ、またはパスワードのみの UI を提供してはいけません。ユーザー向けの文面で、識別子がすでに登録されているかどうかを明かしてはいけません。中立的な表現で、既存ユーザーをログインに案内してください。

パスワードでのサインイン（ユーザー名形式とメールアドレス形式のどちらの識別子も使用できます）：

const { data, error } = await auth.signInWithPassword({ username, password })
// email accounts: auth.signInWithPassword({ email, password })
if (error) { /* show error.message */ } else { /* data.user */ }

匿名サインイン — デモ専用で、デフォルトではありません。 NoSQL の app.database() CRUD ではセッションが必要です（PG の匿名読み取りには accessKey だけで十分です）。実際のログインを優先してください。匿名サインインを使うのは、アプリがユーザーに紐づかない公開データを明示的に提供し、ユーザーがトレードオフを受け入れる場合に限ります。デフォルトでは無効で、AI モデルの権限も拒否されます。また、その uid をユーザー単位の行の所有者にしてはいけません。

const { error } = await auth.signInAnonymously()

登録 — 検証コードは必須です。 パスワードのみのサインアップはありません。signUp 自体がコードを送信し、data.verifyOtp で検証を完了する必要があります。スマートなフロー：識別子が登録済みの場合 → 通常のログイン、新規の識別子の場合 → 登録して自動ログイン。電話番号／SMS は上海地域のみです。メールを優先してください。

const { data, error } = await auth.signUp({ email, password }) // or { phone, password }
if (error) throw error
// user types the code from their inbox...
const { data: login, error: verifyErr } = await data.verifyOtp({ token: code })
// login.user / login.session — signed in on both paths

OTP サインイン（パスワードなし） — signUp と同じ形式で、デフォルトではユーザーを自動作成します（不明なユーザーを拒否するには shouldCreateUser: false を指定します）。コンソールで 邮箱/短信验证码登录 を有効にする必要があります → 身份认证/登录方式：

const { data, error } = await auth.signInWithOtp({ email }) // or { phone }
const { data: login, error: verifyErr } = await data.verifyOtp({ token: code })

パスワードを忘れた場合 — メールコード → 新しいパスワードを設定 → 自動サインイン（PASSWORD_RECOVERY を発行）：

const { data, error } = await auth.resetPasswordForEmail(email)
if (error) throw error
const { data: login, error: resetErr } = await data.updateUser({ nonce: code, password: newPassword })

OTP のクロージャと単独の verifyOtp は別物です — 混同しないでください。 signUp／signInWithOtp／resetPasswordForEmail が返す data.verifyOtp にはメッセージ ID が紐づいています（{ token } だけを渡します）。単独の auth.verifyOtp(...) には messageId が必要で、ログインのみを行い、登録は行いません。必ず返されたクロージャを使用してください。

セッション確認／ルートガード — 非推奨の getLoginState() は使わず、必ず getSession() を使用してください。

const { data } = await auth.getSession()
const session = data?.session // undefined === not logged in

認証状態リスナー（アプリの起動時に一度だけ設定します）：

auth.onAuthStateChange((event, session) => {
  // event: INITIAL_SESSION | SIGNED_IN | SIGNED_OUT | PASSWORD_RECOVERY
  //        | TOKEN_REFRESHED | USER_UPDATED | BIND_IDENTITY
})

サインアウト：

const { error } = await auth.signOut()

ユーザー単位のデータにアクセスする前に、必ず認証ゲートを設けてください。 ユーザー所有の PG 行や Storage オブジェクトを読み書きする前に、セッションを確認し、存在しない場合はログイン画面を表示してください。データエラーを、signInAnonymously をひそかに呼び出して「解決」してはいけません。

const { data } = await auth.getSession()
if (!data?.session) { navigate('/login'); return }

完了基準 — 認証タスクを完了とする前に、生成したソースに以下がすべて含まれている必要があります。

• signInWithPassword（パスワードログインが UI に含まれる場合）
• 検証コードを使うフロー：signUp + data.verifyOtp および／または signInWithOtp
• ユーザー単位の DB／Storage 呼び出し前の認証ゲート（上記のルール）
• 起動時に onAuthStateChange を設定（ルートガードが SIGNED_OUT に反応）
• error.message からエラーを表示し、エラーメッセージを捏造しない
• 権限エラー時のフォールバックとして signInAnonymously を使用しない。モック／localStorage セッションも使用しない

---

拡張ガイド

詳しいシナリオ、例、パターンについては、extended-guide.md をお読みください。

リファレンス一覧

パッケージに含まれるすべてのリファレンスファイル（スキルの到達性を lint するために必要）：

• extended-guide.md