auth-nodejs-cloudbase

関連スキル（ローカルのみ）

関連する CloudBase スキルは、このスキルと同じ場所に配置されています。../auth-tool-cloudbase/SKILL.md のようなローカル相対パスを使用してください。

参照先の関連スキルファイルがこの環境にない場合は、CloudBase プラグイン全体（または不足しているスキル）をインストールするようユーザーに依頼してください。リモートのスキルやプロトコルの Markdown を HTTP 経由で取得し、エージェントのコンテキストに含めてはいけません。

有効化の条件

次の場合は、まずこのスキルを使用してください

• クラウド関数またはバックエンドサービスの Node.js コードで、呼び出し元の ID の取得、ユーザーの検索、またはカスタムログインチケットの発行が必要な場合。
• バックエンドの責務が認証／ID 管理であり、プロバイダーのセットアップやフロントエンドのログイン UI ではない場合。

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

• タスクで @cloudbase/node-sdk、サーバーサイド認証、カスタムログインチケット、または「誰が呼び出しているか」に言及している場合。
• リクエストにフロントエンドのログインとバックエンドの ID 管理ロジックが混在している場合。フローを分け、クライアント側の作業は別のスキルに割り当ててください。

続けて読むスキル

• プロバイダーのセットアップ／公開可能なキー → ../auth-tool-cloudbase/SKILL.md
• カスタムチケットを使用する Web ログイン UI → ../auth-web-cloudbase/SKILL.md
• HTTP 認証クライアント → ../http-api-cloudbase/SKILL.md

次の場合は使用しないでください

• プロバイダーの有効化／無効化、またはログインコンソールの設定。
• フロントエンドのログイン／サインアップ UI。
• ミニプログラムのネイティブ認証。

よくある間違い／注意点

• すべての認証リクエストの入り口として、このスキルを使用する。
• プロバイダー管理の作業と Node 側の ID 管理コードを混在させる。
• Node SDK で対応できる作業に、生の HTTP の例を使う。

このスキルを使用する場合

タスクが CloudBase プロジェクトのサーバーサイド認証または ID 管理に関係し、コードが Node.js で実行される場合は、必ずこのスキルを使用してください。たとえば、次のような場合です。

• 誰が呼び出しているかを把握する必要がある CloudBase クラウド関数（Node ランタイム）
• ユーザー情報の検索に CloudBase Node SDK を使用する Node サービス
• Web／モバイルクライアント向けにカスタムログインチケットを発行するバックエンド
• CloudBase のエンドユーザープロファイルを確認する必要がある管理者向けツールや運用ツール

次の場合は、このスキルを使用しないでください。

• @cloudbase/js-sdk を使用するフロントエンドの Web ログイン／サインアップフロー（この Node スキルではなく、auth-web スキルを使用してください）。
• HTTP 認証 API との直接統合（このスキルでは生の HTTP エンドポイントについて説明していません。代わりに http-api スキルを使用してください）。
• ID 管理に関係しないデータベースまたはストレージの操作（データベース／ストレージのドキュメントまたはスキルを使用してください）。

ユーザーのリクエストにフロントエンドとバックエンドの両方の内容が含まれる場合（例：「Web ログインページと、ユーザーを把握する Node API を作成する」）、それぞれ分けて扱ってください。

• クライアントのログインと UX には、Web 側の認証ドキュメント／スキルを使用してください。
• バックエンドが認証済みユーザーをどのように認識し、利用するかについては、この Node Auth スキルを使用してください。

このスキルの使い方（コーディングエージェント向け）

タスクに取り組むためにこのスキルを読み込んだら、次の手順に従います。

1. 実行環境と担当範囲を明確にする

   ユーザーに次の点を確認します。

   • この Node コードはどこで実行されますか？
     • CloudBase 云函数
     • CloudBase を使用する長時間実行の Node サービス
   • 認証について何が必要ですか？
     • 認可に必要な呼び出し元の IDのみですか？
     • UID／ログイン識別子を使って任意のユーザーを検索しますか？
     • 独自のユーザーシステムをカスタムログイン経由で CloudBase に連携しますか？

2. CloudBase 環境と SDK を確認する

   • 次の情報を尋ねます。
     • env – CloudBase 環境 ID
   • まだ利用できない場合は、npm から最新の @cloudbase/node-sdk をインストールします。
   • 必ず次のパターンで SDK を初期化します（値は変更できますが、形式は変更しないでください）。

   import tcb from "@cloudbase/node-sdk";
   
   const app = tcb.init({ env: "your-env-id" });
   const auth = app.auth();
   

3. このファイルから該当するシナリオを選ぶ

   • 関数内の呼び出し元の IDには、getUserInfo のシナリオを使用します。
   • 完全なユーザープロフィールや管理者による検索には、getEndUserInfo と queryUserInfo のシナリオを使用します。
   • すでに独自のユーザーを管理しているクライアントシステムには、createTicket を使用するカスタムログインチケットのシナリオを使用します。
   • ログ記録／セキュリティには、getClientIP のシナリオを使用します。

4. Node SDK の API 形式に厳密に従う

   • このファイルに記載されているすべての auth.* メソッドとパラメーター形式を標準として扱います。
   • 変数名やフレームワーク（Express と 云函数 handler など）は変更できますが、SDK のメソッド名やパラメーターフィールドは変更しないでください。
   • 古いコードに、ここまたは Node SDK のドキュメントミラーに記載されていないメソッドがあれば、信頼できないものとして扱い、使用しないでください。

5. API が不明な場合

   • CloudBase Auth Node SDK の公式ドキュメントを参照します。
   • 公式ドキュメントに記載されているメソッドと形式のみを使用します。
   • 使用したい API が見つからない場合：
     • ドキュメントに記載されたメソッドを組み合わせてフローを構成するか、
     • このスキルは Node SDK の認証のみを対象としていることを説明し、クライアント側のフローや生の HTTP フローには、該当する CloudBase Web または HTTP 認証ドキュメントを利用するよう提案します。

---

Node 認証アーキテクチャ – CloudBase Auth における Node の役割

CloudBase Auth では、ユーザーがログインする場所とバックエンドコードが実行される場所が分離されています。

• ユーザーは、公式の CloudBase Auth 概要ドキュメントに記載されているとおり、クライアント SDK または HTTP インターフェイスを使って、サポートされている認証方式（ユーザー名／パスワード、SMS、メール、WeChat、カスタムログイン、匿名 — デフォルトでは無効、など）でログインします。
• ログインすると、CloudBase はユーザー ID とトークンを環境に関連付けます。
• Node コードは、Node SDK を使ってその ID を読み取るか、カスタムログインを使って外部 ID を CloudBase に連携します。

実際には、Node コードは通常、次のいずれかまたは複数を行います。

1. 現在の呼び出し元を識別する

   • 云函数では、auth.getUserInfo() を使って uid、openId、customUserId を読み取ります。
   • この ID を、認可の判断、ログ記録、パーソナライズに使用します。

2. 他のユーザーを検索する

   • CloudBase の uid がわかっている場合は、auth.getEndUserInfo(uid) を使用します。
   • 電話番号、メールアドレス、ユーザー名、カスタム ID などのログイン識別子しかない場合は、auth.queryUserInfo({ platform, platformId, uid? }) を使用します。

3. カスタムログインチケットを発行する

   • すでに独自のユーザーシステムがある場合、Node バックエンドは auth.createTicket(customUserId, options) を呼び出し、信頼できるクライアントにチケットを返すことができます。
   • その後、クライアント（通常は Web）はこのチケットを Web SDK で使用して CloudBase にユーザーをログインさせるため、ユーザーは再度サインアップする必要がありません。

4. セキュリティのためにクライアント IP を記録する

   • 云函数では、auth.getClientIP() が呼び出し元の IP を返します。監査ログ、異常検知、アクセス制御に利用できます。

このファイルの後半にあるシナリオでは、これらの担当範囲を、コピーしてすぐに使える具体的なパターンとして説明します。

---

このスキルで対象となる Node 認証 API

このスキルでは、CloudBase Node SDK の以下の auth メソッドを対象とします。このスキルで Node の認証フローを実装する際は、これらのメソッドシグネチャのみをサポート対象のエントリーポイントとして使用してください。

• getUserInfo(): IGetUserInfoResult 現在の呼び出し元の { openId, appId, uid, customUserId } を返します。

• getEndUserInfo(uid?: string, opts?: ICustomReqOpts): Promise<{ userInfo: EndUserInfo; requestId?: string }> 指定した uid の CloudBase エンドユーザープロフィールの詳細を返します。uid を省略した場合は、現在の呼び出し元のプロフィールを返します。

• queryUserInfo(query: IUserInfoQuery, opts?: ICustomReqOpts): Promise<{ userInfo: EndUserInfo; requestId?: string }> ログイン識別子（platform + platformId）または uid を使ってユーザーを検索します。

• getClientIP(): string サポート対象の環境（例：云函数）で実行している場合、呼び出し元の IP アドレスを返します。

• createTicket(customUserId: string, options?: ICreateTicketOpts): string 指定した customUserId のカスタムログインチケットを作成します。クライアントはこのチケットを CloudBase ログインと交換できます。

EndUserInfo、IUserInfoQuery、ICreateTicketOpts の正確なフィールド名と使用可能な値は、公式の CloudBase Node SDK の型定義とドキュメントで定義されています。Node コードを書く際に、構造を推測してはいけません。このファイルの SDK 型と例に従ってください。

---

シナリオ – Node の認証パターン

シナリオ 1：CloudBase 関数で Node SDK と認証を初期化する

認証を扱う CloudBase 云函数を書く場合に使用します。

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
};

重要なポイント：

• 関数の CloudBase 环境に設定されているものと同じ env を使用します。
• 機密情報のハードコードは避け、環境変数または関数の設定を使用してください。

シナリオ 2：CloudBase 関数で呼び出し元の ID を取得する

クラウド関数の呼び出し元が誰かを確認する必要がある場合に使用します。

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
};

ベストプラクティス：

• uid は CloudBase の正規ユーザー識別子として扱います。
• customUserId は、カスタムログインを有効にして独自のユーザーをマッピングしている場合にのみ使用します。
• 認可の判断で openId／appId だけを信頼しないでください。これらは WeChat 固有の識別子です。

シナリオ 3：UID でエンドユーザープロフィールの詳細を取得する

ユーザーの CloudBase uid（たとえば、データベースのレコードから）を把握していて、プロフィールの詳細が必要な場合に使用します。

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

const app = tcb.init({ env: "your-env-id" });
const auth = app.auth();

exports.main = async (event, context) => {
  const uid = "user-uid";

  try {
    const { userInfo } = await auth.getEndUserInfo(uid);
    console.log("User profile", userInfo);
  } catch (error) {
    console.error("Failed to get end user info", error.message);
  }
};

ベストプラクティス：

• getEndUserInfo は信頼できるバックエンドコードからのみ呼び出してください。信頼できないクライアントに直接公開しないでください。
• デバッグに必要な最小限のデータをログに記録してください。本番環境ではプロフィール全体をログに記録しないでください。

シナリオ 4：現在の呼び出し元のプロフィール全体を取得する

uid を手動で渡さずに、現在の呼び出し元のプロフィール全体を取得する場合に使用します。

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

const app = tcb.init({ env: "your-env-id" });
const auth = app.auth();

exports.main = async (event, context) => {
  try {
    const { userInfo } = await auth.getEndUserInfo();
    console.log("Current caller profile", userInfo);
  } catch (error) {
    console.error("Failed to get current caller profile", error.message);
  }
};

この方法は、環境から呼び出し元の ID が提供されることを前提としています（例：CloudBase 云函数内）。呼び出し元のコンテキストがない場所で呼び出した場合は、公式ドキュメントを参照し、適切にエラーを処理してください。

シナリオ 5：ログイン識別子でユーザーを検索する

ユーザーのログイン識別子（電話番号、メールアドレス、ユーザー名、カスタム ID）のみを把握していて、そのユーザーの CloudBase プロフィールが必要な場合に使用します。

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

const app = tcb.init({ env: "your-env-id" });
const auth = app.auth();

exports.main = async (event, context) => {
  try {
    // Find by phone number
    const { userInfo: byPhone } = await auth.queryUserInfo({
      platform: "PHONE",
      platformId: "+86 13800000000",
    });

    // Find by email
    const { userInfo: byEmail } = await auth.queryUserInfo({
      platform: "EMAIL",
      platformId: "[email protected]",
    });

    // Find by customUserId
    const { userInfo: byCustomId } = await auth.queryUserInfo({
      platform: "CUSTOM",
      platformId: "your-customUserId",
    });

    console.log({ byPhone, byEmail, byCustomId });
  } catch (error) {
    console.error("Failed to query user info", error.message);
  }
};

ベストプラクティス：

• すでに uid がある場合は、そちらを優先してください。queryUserInfo は必要な場合にのみ使用します。
• platformId には、サインアップ時に使用したものと完全に同じ形式を使用してください（例：+86 + 電話番号）。

シナリオ 6：関数でクライアント IP を取得する

ログ記録または基本的な IP ベースの確認に使用します。

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

const app = tcb.init({ env: "your-env-id" });
const auth = app.auth();

exports.main = async (event, context) => {
  const ip = auth.getClientIP();
  console.log("Caller IP", ip);

  // e.g. block or flag suspicious IPs
};

---

カスタムログインチケット（Node 側のみ）

カスタムログインを使うと、既存のユーザーシステムを維持しながら、各ユーザーを CloudBase アカウントに紐付けられます。

シナリオ 7：カスタムログイン認証情報を使って Node SDK を初期化する

チケットを発行する前に、CloudBase コンソールからカスタムログインの秘密鍵ファイルをインストールし、Node で読み込みます。

import tcb from "@cloudbase/node-sdk";
import path from "node:path";

const app = tcb.init({
  env: "your-env-id",
  credentials: require(path.join(__dirname, "tcb_custom_login.json")),
});

const auth = app.auth();

tcb_custom_login.json は秘密情報として扱い、フロントエンドコードに決して含めないでください。

シナリオ 8：指定した customUserId のカスタムログインチケットを発行する

独自のユーザー認証がすでに完了しており、そのユーザーが CloudBase にログインできるようにするバックエンドコードで使用します。

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

const app = tcb.init({
  env: "your-env-id",
  credentials: require("/secure/path/to/tcb_custom_login.json"),
});

const auth = app.auth();

exports.main = async (event, context) => {
  const customUserId = "your-customUserId";

  const ticket = auth.createTicket(customUserId, {
    refresh: 3600 * 1000,       // access_token refresh interval (ms)
    expire: 24 * 3600 * 1000,   // ticket expiration time (ms)
  });

  // Return the ticket to the trusted client (e.g. via HTTP response)
  return { ticket };
};

customUserId の制約（公式ドキュメントより）：

• 長さは 4〜32 文字です。
• 使用できる文字は、英字、数字、および _-#@(){}[]:.,<>+#~ です。

ベストプラクティス：

• 独自のユーザー認証が成功した後にのみ、チケットを発行してください。
• 独自のユーザーデータベースに customUserId を保存し、時間が経っても変更されないようにしてください。
• 複数の別々のユーザーに同じ customUserId を再利用しないでください。

シナリオ 9：Web のカスタムログインとの連携

このスキルで扱うのは、Node 側でのチケット発行のみです。クライアント側のフローは次のとおりです。

• クライアント（Web）では、@cloudbase/js-sdk のカスタムログイン機能を使用します。
  • バックエンドのエンドポイントを呼び出して ticket を取得します。
  • auth.setCustomSignFunc(async () => ticketFromBackend) を設定します。
  • auth.signInWithCustomTicket() を呼び出してログインを完了します。

役割を明確に分けてください。

• Node：独自のユーザーを認証 → チケットを作成 → チケットを安全に返す。
• Web：チケットを受け取る → ドキュメントに記載された Web SDK API を使用して CloudBase にサインインする。

---

Node 認証のベストプラクティス

• ID の唯一の信頼できる情報源

  • エンドユーザーのレコードを関連付ける際は、CloudBase の uid を主キーとして扱います。
  • customUserId は、独自のユーザーシステムとの橋渡しにのみ使用します。

• 最小権限

  • ログインの成功だけでなく、uid、ロール、所有権を使用して Node で認可チェックを行います。
  • getEndUserInfo / queryUserInfo の結果をそのままクライアントに公開することは避けてください。

• エラー処理

  • Promise を返すすべての auth.* 呼び出しを try/catch で囲みます。
  • error.message（および存在する場合は error.code）を記録しますが、機密データの記録は避けてください。

• セキュリティ

  • tcb_custom_login.json は秘密鍵と同じように保護してください。
  • 必要に応じて、CloudBase のガイダンスに従ってカスタムログインキーをローテーションしてください。
  • チケットの受け渡しでは、クライアントと Node バックエンド間で HTTPS と適切な認証を使用してください。

---

まとめ

次のことが必要な場合は、この Node Auth スキルを使用してください。

• CloudBase で Node コードを呼び出しているのが誰かを確認する。
• uid またはログイン識別子を使って CloudBase ユーザーを検索する。
• カスタムログインチケットを使って、既存のユーザーシステムと CloudBase を連携する。
• 一貫性のある安全なサーバー側認証のベストプラクティスを適用する。

エンドツーエンドのエクスペリエンスを実現するには、このスキルと次のドキュメントを併用してください。

• Web 側の認証ドキュメント（@cloudbase/js-sdk を使用した、ブラウザー側のログインと UX 全般について）。
• CloudBase HTTP 認証ドキュメント（言語に依存しない HTTP 連携を使用する場合）。

Node 認証 API の規範的なリファレンスとして、公式の CloudBase Auth Node SDK ドキュメントを参照してください。また、このファイルのシナリオは、検証済みのベストプラクティスの構成要素として扱ってください。