better-auth

Next.js 16 App Router プロジェクトに、TypeScript を第一に考えた認証ライブラリ Better Auth を実装します。サーバー設定、クライアント（`createAuthClient`）、セッション管理、`app/api/auth/[...all]/route.ts` ハンドラーに加え、ルート保護用の `proxy.ts`（middleware を置き換えるもの）も扱います。

全機能を網羅します。40 種類以上の OAuth プロバイダー（Google、GitHub、Discord、Apple、Microsoft など）、20 種類以上のプラグイン（2FA、マジックリンク、パスキー、組織／マルチテナント、エンタープライズ SSO／SAML、SCIM プロビジョニング、Stripe／Polar の課金、JWT／Bearer、API キー）、データベースアダプター（Prisma、Drizzle、MongoDB、raw SQL）を扱います。Auth.js、Clerk、Auth0、Supabase、WorkOS からの移行方法も扱います。Better Auth 自体はフレームワークに依存しませんが、このスキルのアーキテクチャに関するガイダンス（proxy.ts、App Router API ルート）は Next.js 固有です。Prisma のスキーマ／クエリの詳細については prisma-7 を参照してください。

Better Auth - 完全な認証

40 種類以上の OAuth プロバイダーと20 種類以上のプラグインを備えた、TypeScript を第一に考えた認証ライブラリです。

エージェントのワークフロー（必須）

実装を始める前に、name を指定した Agent 呼び出しをそれぞれ1回行い、3つのエージェントを並行して起動してください。

1. fuse-ai-pilot:explore-codebase - 既存の認証設定とパターンを分析します
2. fuse-ai-pilot:research-expert - Context7／Exa 経由で Better Auth の最新ドキュメントを確認します
3. mcp__context7__query-docs - 利用可能なプロバイダー／プラグインを確認します

実装後、検証のために fuse-ai-pilot:sniper を実行してください。

---

概要

使用する場面

• TypeScript／JavaScript アプリケーションに認証を実装する場合
• OAuth プロバイダー（Google、GitHub、Discord、Apple、Microsoft など）が必要な場合
• 2FA、マジックリンク、パスキー、電話番号認証を追加する場合
• SAML によるエンタープライズ SSO、SCIM プロビジョニング、または組織が必要な場合
• Stripe または Polar のサブスクリプションを使った決済を統合する場合
• Sign-In with Ethereum（SIWE）による Web3 認証を実装する場合
• Auth.js、Clerk、Auth0、Supabase、WorkOS から移行する場合

Better Auth を選ぶ理由

機能	メリット
フレームワークに依存しない	Next.js、SvelteKit、Nuxt、Remix、Astro、Expo、NestJS
プラグインアーキテクチャ	必要な機能だけを追加できます（20 種類以上のプラグイン）
TypeScript 完全対応	エンドツーエンドの型安全性と型推論に対応
セルフホスト可能	データは自社のインフラストラクチャ内に保持できます
柔軟なデータベース対応	Prisma、Drizzle、MongoDB、PostgreSQL、MySQL、SQLite
エンタープライズ対応	SSO、SCIM、組織、監査ログ

バージョンに関する注意（現行の安定版：1.7.x）

以降	変更点
1.5	スタンドアロン CLI npx auth@latest（generate、migrate、secret、init、check…）が @better-auth/cli に置き換わりました。OAuth 2.1 Provider（@better-auth/oauth-provider）が追加されました
1.6	session.freshAge が createdAt から計算されるようになりました。oidcProvider は非推奨になりました
1.7	oidcProvider が削除されました。汎用 OAuth プロバイダーは signIn.social を使用します（genericOAuthClient は不要です）。DB の結合は advanced.database.joins 経由になりました。アカウントのキーは (issuer, accountId) になりました。twoFactor.enable は method で判別されるレスポンスを返します。MCP は @better-auth/mcp に移動しました。SCIM は organization から切り離されました

1.7 にアップグレードした後は、スキーマを再生成し（npx auth@latest generate）、公式の 1.7 アップグレードガイドに従ってください。

---

対応範囲

OAuth プロバイダー（40 種類以上）

Google、GitHub、Discord、Apple、Microsoft、Slack、Spotify、Twitter/X、Facebook、LinkedIn、GitLab、Bitbucket、Dropbox、Twitch、Reddit、TikTok、および providers/ に記載されているその他25 種類以上に対応しています。

プラグイン（20 種類以上）

プラグイン	用途
2FA	TOTP 認証アプリ、バックアップコード
Magic Link	パスワード不要のメールログイン
Passkey	WebAuthn による生体認証
Organization	マルチテナント、ロール、招待
SSO	エンタープライズ向け SAML／OIDC シングルサインオン
SCIM	ディレクトリ同期、ユーザープロビジョニング
Stripe	サブスクリプション課金の統合
API Key	マシン間認証
JWT/Bearer	トークンベースの API 認証

データベースアダプター

Prisma、Drizzle、MongoDB、raw SQL（PostgreSQL、MySQL、SQLite）、およびコミュニティ製アダプターに対応しています。

---

SOLID アーキテクチャ（Next.js 16）

関心の分離に従い、コンポーネントを modules/auth/ に整理しています。

• サービス：betterAuth の設定と初期化
• フック：クライアント側の認証状態を扱う createAuthClient
• API ルート：app/api/auth/[...all]/route.ts ハンドラー
• プロキシ：ルートを保護する proxy.ts（ミドルウェアを置き換えます）

---

リファレンスガイド

必要な項目	リファレンス
初期設定	installation.md、server-config.md
クライアントの使用方法	client.md、session.md
OAuth プロバイダー	providers/overview.md、各プロバイダーのドキュメント
プラグインの追加	plugins/overview.md、各プラグインのドキュメント
データベースの設定	adapters/prisma.md、adapters/drizzle.md
エンタープライズ SSO	plugins/sso.md、guides/saml-okta.md
決済	plugins/stripe.md、plugins/polar.md
移行	guides/clerk-migration.md、その他の移行ガイド
完全なサンプル	完全な実装例は examples/ を参照してください

---

ベストプラクティス

1. 必要に応じたプラグイン - 実際に必要なプラグインだけを追加します
2. 型安全なクライアント - サーバー設定から生成された型を使用します
3. セッションのキャッシュ - パフォーマンス向上のため、セッションのキャッシュを有効にします
4. レート制限 - 認証エンドポイントのレート制限を設定します
5. セキュア Cookie - secure、httpOnly、sameSite Cookie を使用します
6. データベースのインデックス - ユーザー検索フィールドにインデックスを追加します

---

概念

基本概念については concepts/ で説明しています。

• セッション - トークン管理、更新、失効
• データベース - スキーマ設計、マイグレーション、アダプター
• プラグイン - 拡張システム、構成
• OAuth - プロバイダーの設定、コールバック
• セキュリティ - CSRF、レート制限、パスワードのハッシュ化
• Cookie - セッションの保存、クロスドメイン