🔐 OAuthドライバー

OAuthドライバーは、Passport.jsを使用してサードパーティOAuthプロバイダーの一貫した統合レイヤーを提供します。プロバイダー戦略のセットアップをカプセル化し、ルートや機能に合成できるシンプルなリクエストとコールバックヘルパーを公開します。

---

🎯 概要

NodeBlocksのOAuthドライバーは、Passport.js戦略をラップする薄いラッパーで、以下を提供します：

• 戦略セットアップ - プロバイダーの認証情報とスコープを使用
• Promiseベースのリクエスト/コールバックヘルパー - 合成用
• プラグ可能な検証コールバック - プロバイダープロフィールを正規化

---

📋 利用可能なOAuthドライバー

Google OAuth Driver

Google OAuthドライバーは、Passport.js Google戦略を統合し、リクエストとコールバック処理用のヘルパーを公開します。

PROVIDER_GOOGLE

アイデンティティ解決とドライバー設定で使用されるGoogle OAuthプロバイダーの定数識別子。

Type: string

Value: 'google'

使用例:

import { PROVIDER_GOOGLE } from '@nodeblocks/backend-sdk';

// アイデンティティクエリで使用：
const identity = await identitiesCollection.findOne({
  provider: PROVIDER_GOOGLE,
  providerId: profile.id
});

---

verifyGoogleCallback

Google OAuthコールバックを検証し、Google Passport.js認証用のユーザープロフィールデータを処理します。

パラメータ:

• _req: Request — Expressリクエストオブジェクト（この実装では未使用）
• accessToken: string — APIアクセス用のGoogle OAuthアクセストークン
• refreshToken: string — トークン更新用のGoogle OAuthリフレッシュトークン
• profile: Profile — OAuthコールバックからのGoogleユーザープロフィールデータ
• done: VerifyCallback — Passport.js検証コールバック関数

戻り値: void — 結果またはエラーでdoneコールバックを呼び出す

ハンドラープロセス:

• 入力: Expressリクエスト、アクセストークン、リフレッシュトークン、Googleプロフィール、検証コールバック
• 処理: プロフィールからemailとidを抽出し、両方が存在することを検証し、displayName、email、idフィールドでプロフィールデータをフォーマット
• 出力: フォーマットされたプロフィールデータ（{ displayName, email, id }）またはエラーでdoneコールバックを呼び出す
• エラー: Googleプロフィールにemailまたはidが欠落している場合、AuthenticationBadRequestError

使用例:

passport.use(new GoogleStrategy({
  verify: verifyGoogleCallback
}));

createGoogleOAuthDriver

Passport.js戦略と認証ハンドラーを使用してGoogle OAuthドライバーを作成します。

パラメータ:

• clientID: string — Google Cloud ConsoleからのGoogle OAuthクライアントID
• clientSecret: string — Google Cloud ConsoleからのGoogle OAuthクライアントシークレット
• callbackURL: string — OAuth完了後にGoogleがリダイレクトするURL
• scope: string[] — リクエストするOAuthスコープの配列（デフォルト: ['email', 'profile']）
• verify: typeof verifyGoogleCallback — オプションの検証関数（デフォルト: verifyGoogleCallback）

戻り値: GoogleOAuthDriver — 完全なOAuthフロー管理を持つGoogleOAuthDriverオブジェクト

ハンドラープロセス:

• 入力: Google OAuth認証情報（clientID、clientSecret）、コールバックURL、スコープ、オプションの検証関数
• 処理: Passport.js Google戦略を設定し、Promiseラッパーでコールバックとリクエストハンドラーを作成
• 出力: コールバック、初期化、リクエスト関数を持つGoogleOAuthDriverオブジェクト
• エラー: Passport.js認証またはPromise拒否からのエラー

使用例:

// Google OAuthドライバーを作成：
const googleDriver = createGoogleOAuthDriver(
  'your-client-id',
  'your-client-secret',
  'https://app.com/auth/google/callback'
);

// Use in Express app:
app.use('/auth/google', googleDriver.initialize);

Twitter OAuth Driver

Twitter OAuthドライバーは、Passport.js Twitter戦略を統合し、リクエストとコールバック処理用のヘルパーを公開します。

PROVIDER_TWITTER

アイデンティティ解決とドライバー設定で使用されるTwitter OAuthプロバイダーの定数識別子。

Type: string

Value: 'twitter'

使用例:

import { PROVIDER_TWITTER } from '@nodeblocks/backend-sdk';

// アイデンティティクエリで使用：
const identity = await identitiesCollection.findOne({
  provider: PROVIDER_TWITTER,
  providerId: profile.id
});

---

verifyTwitterCallback

Twitter OAuthコールバックを検証し、ユーザー情報を抽出します。

パラメータ:

• _req: Request — Expressリクエストオブジェクト（未使用）
• accessToken: string — OAuthアクセストークン（未使用）
• refreshToken: string — OAuthリフレッシュトークン（未使用）
• profile: TwitterUserInfoPayload — Twitterユーザープロフィール情報
• done: VerifyCallback — 完了を通知するコールバック関数

戻り値: void — 結果またはエラーでdoneコールバックを呼び出す

ハンドラープロセス:

• 入力: OAuthトークンとTwitterユーザープロフィールを受信
• 処理: プロフィール、id、ユーザー名の存在を検証
• 出力: displayName、id、ユーザー名を含むユーザー情報を返す
• エラー: プロフィール、id、またはユーザー名が欠落している場合、AuthenticationOAuthErrorを返す

使用例:

passport.use(new TwitterStrategy({
  clientID: TWITTER_CLIENT_ID,
  clientSecret: TWITTER_CLIENT_SECRET,
  callbackURL: "http://www.example.com/auth/twitter/callback"
}, verifyTwitterCallback));

createTwitterOAuthDriver

認証フローを処理するためのTwitter OAuthドライバーを作成します。

パラメータ:

• clientID: string — TwitterアプリケーションのクライアントID
• clientSecret: string — Twitterアプリケーションのクライアントシークレット
• callbackURL: string — Twitter OAuthのコールバックURL
• sessionSecret: string — セッション管理用のシークレット
• verify: VerifyFunctionWithRequest — Twitter OAuthコールバックを処理するためのオプションの検証関数

戻り値: TwitterOAuthDriver — 完全なOAuthフロー管理を持つTwitterOAuthDriverオブジェクト

ハンドラープロセス:

• 入力: clientID、clientSecret、callbackURL、sessionSecret、およびオプションのverify関数を受け入れる
• 処理: PassportでTwitter戦略を設定し、コールバック状態管理用のセッションミドルウェアをセットアップ
• 出力: コールバック、初期化、リクエスト処理用のメソッドを持つTwitterOAuthDriverを返す

主な機能:

• リクエストとコールバック間でOAuth状態を維持するためにセッションミドルウェアを使用
• セッションミドルウェアはドライバー初期化中にのみ適用され、特定のルートには適用されない
• Twitter OAuthに必要なステートフル認証フローを提供

使用例:

const twitterDriver = createTwitterOAuthDriver(
  'your-client-id',
  'your-client-secret',
  'https://yourapp.com/auth/twitter/callback',
  'your-session-secret'
);

// Use in Express app:
app.use('/auth/twitter', twitterDriver.initialize);

LINE OAuth Driver

LINE OAuthドライバーは、Passport.js LINE戦略を統合し、リクエストとコールバック処理用のヘルパーを公開します。

verifyLineCallback

LINE OAuthコールバックを検証し、LINE Passport.js認証用のユーザープロフィールデータを処理します。

パラメータ:

• _req: Request — Expressリクエストオブジェクト（この実装では未使用）
• accessToken: string — APIアクセス用のLINE OAuthアクセストークン
• refreshToken: string — トークン更新用のLINE OAuthリフレッシュトークン
• profile: LineUserInfoPayload — OAuthコールバックからのLINEユーザープロフィールデータ
• done: VerifyCallback — Passport.js検証コールバック関数

戻り値: void — 結果またはエラーでdoneコールバックを呼び出す

ハンドラープロセス:

• 入力: Expressリクエスト、アクセストークン、リフレッシュトークン、LINEプロフィール、検証コールバック
• 処理: プロフィールからsub（サブジェクト識別子）を抽出し、subの存在を検証し、認証用にプロフィールデータをフォーマット
• 出力: nameとsubを含むフォーマットされたプロフィールデータでdoneコールバックを呼び出す
• エラー: LINEプロフィールにsubが欠落している場合、AuthenticationOAuthError

使用例:

passport.use(new LineStrategy({
  verify: verifyLineCallback
}));

createLineOAuthDriver

Passport.js戦略と認証ハンドラーを使用してLINE OAuthドライバーを作成します。

パラメータ:

• clientID: string — LINE Developers ConsoleからのLINEチャネルID
• clientSecret: string — LINE Developers ConsoleからのLINEチャネルシークレット
• callbackURL: string — OAuth完了後にLINEがリダイレクトするURL
• scope: string[] — リクエストするOAuthスコープの配列（デフォルト: ['profile', 'openid', 'email']）
• verify: VerifyFunctionWithRequest — オプションの検証関数（デフォルト: verifyLineCallback）

戻り値: LineOAuthDriver — 完全なOAuthフロー管理を持つLineOAuthDriverオブジェクト

ハンドラープロセス:

• 入力: LINE OAuth認証情報（clientID、clientSecret）、コールバックURL、スコープ、オプションの検証関数
• 処理: Passport.js LINE戦略を設定し、Promiseラッパーでコールバックとリクエストハンドラーを作成
• 出力: コールバック、初期化、リクエスト関数を持つLineOAuthDriverオブジェクト
• エラー: Passport.js認証、Promise拒否、または認証失敗時のAuthenticationOAuthErrorからのエラー

使用例:

// LINE OAuthドライバーを作成：
const lineDriver = createLineOAuthDriver(
  'your-channel-id',
  'your-channel-secret',
  'https://app.com/auth/line/callback'
);

// Use in Express app:
app.use('/auth/line', lineDriver.initialize);

---

🔗 関連ドキュメント

• OAuth Blocks — OAuthフローのビジネスロジック
• OAuth Routes — OAuth用のHTTPルート合成