better-auth

Better Auth

Better Auth ([email protected]) を使用したセルフホスト型 TypeScript 認証（サーバーインスタンス、クライアント SDK、プラグイン、アダプター、フレームワークへのマウント、セキュリティ）にこのスキルを使用してください。

スナップショット：2026-10-01。latest は 1.7.7（安定版）です。1.7 を rc／ベータとして扱わないでください。≥ 1.7.7 を必須としてください：それ以前のバージョン（1.4.0-beta.18 まで遡る）には、重大な Magic Link アカウント乗っ取り（GHSA-965c-763c-88jm）と OAuth Proxy 乗っ取り（GHSA-r4xp-prcw-77qf）の脆弱性があり、1.6.x に修正バージョンはありません。バージョンが異なる場合は、source-map.md から最新情報を取得してください。

ワークフロー

1. ローカル環境を確認します：
   • コア：better-auth（スナップショット 1.7.7）。CLI：bunx auth@latest（パッケージ [email protected]）— 古い @better-auth/[email protected] ではありません。CLI には Node.js ≥ 22.12 が必要です。
   • 環境変数：BETTER_AUTH_SECRET（32 文字以上）、BETTER_AUTH_URL / baseURL、trustedOrigins。
   • データベース：Kysely／プールと Drizzle／Prisma／Mongo アダプターのどちらか。セカンダリストレージ（Redis）。スキーマ検証はデフォルトで有効です。
   • プラグイン：サーバー側と対応するクライアント側のプラグイン。変更後にスキーマを生成します。
   • マウント：auth.handler／フレームワークヘルパーを使用して /api/auth/*（デフォルトの basePath）をマウントします。
2. 日常的なセットアップでは、まず usage-guide.md に従ってください。1.6 からは bunx auth@latest upgrade と 1.7 upgrade guide を使ってください。生成された SQL だけではアップグレードは完了しません。
3. バージョンにずれがある場合は、ドキュメントを更新してください。source-map.md から始めます。
4. 詳細は次を参照してください：
   • プラグインとスコープ付きパッケージ：plugins-ecosystem.md。
   • スキーマ、アダプター、CLI：adapters-schema.md。
   • フレームワークへのマウントとクライアント：frameworks-client.md。
   • セキュリティ、セッション、1.7 の ID／OAuth に関する注意点：security-patterns.md。
5. 個別のリリースラインに属するもの（utils、infra、agent-auth、dash）を除き、インストール済みのすべての @better-auth/* をコアと同じ 1.7.x に揃えてください。最適化時はスコープ付きアダプターを優先してください（better-auth/minimal）。
6. セッションのスモークテスト（auth.api.getSession）、サインイン／サインアウト、プラグインのスキーママイグレーション、本番環境のシークレット／オリジン設定を確認します。

中核となる判断

• デフォルトは Cookie を使用する DB セッションであり、JWT ではありません。Cookie だけでは不十分な場合に限り、jwt／bearer／API キーを使用してください。
• lib/auth.ts に auth シングルトンを置きます（名前付きエクスポートにすると CLI が検出しやすくなります）。auth-client.ts は分けてください。
• サーバー：実際のリクエストヘッダーを使って auth.api.* を呼び出します。クライアント：createAuthClient とフレームワーク用エントリーポイント（better-auth/react など）を使用します。
• 多くの機能はプラグインです。サーバー側とクライアント側の両方に登録してから、bunx auth@latest generate（ORM）または migrate（Kysely）を実行します。
• Passkey／API key／SSO／SCIM／OAuth-provider／MCP／CIMD／Stripe／Expo はスコープ付きパッケージです。MCP は @better-auth/mcp であり、better-auth/plugins ではありません。
• oidcProvider は削除されました。 @better-auth/oauth-provider を使用してください。mcp() の隣に oauthProvider() も登録しないでください。mcp() がプロバイダーです。
• Generic OAuth では signIn.social／linkSocial と /api/auth/callback/:id を使用します。genericOAuthClient() はありません。
• ミドルウェアで Cookie の存在を認証済みと見なさないでください。セッションを検証してください。CORS を「修正」するために CSRF／オリジンチェックを無効にしないでください。
• 1.7.7 へのアップグレードは、連携して切り替える必要があります。検証ストレージを共有するすべてのサーバーと、OAuth Proxy のすべての参加者を同時にアップグレードしてください。アップグレード前の保留中の Magic Link と OAuth／SAML の state は機能しなくなります。
• 開発環境ではレート制限が無効または弱く設定されています。メモリストレージは複数インスタンス環境では機能しません。本番環境では Redis／DB を使用してください。
• コマンド例では bun／bunx を優先してください。

検証

リポジトリが用意しているコマンドを優先してください。関連する項目を確認します。

• bun pm ls better-auth と、対応する @better-auth/* のバージョンを確認します（すべて 1.7.x で統一し、≥ 1.7.7）。
• 必要に応じて bunx auth@latest info / secret を実行します。プラグインの変更後はスキーマの generate / migrate を実行し、読み取り専用の bunx auth@latest check schema でアダプタースキーマを検証します。
• スモークテスト：ハンドラーのマウント、getSession、メールまたはソーシャルサインイン、サインアウト。
• プラグイン：クライアントメソッドが解決されること。有効にしている場合は、組織／2FA／パスキー／OAuth プロバイダー／MCP のフローも確認します。
• 本番環境：baseURL、シークレットの長さ、trustedOrigins、HTTPS クッキー、レート制限のストレージ、スキーマ検証でエラーが発生しないこと。
• セキュリティ：input: false を設定したロール／additionalFields、本番環境の設定に testUtils が含まれていないこと。
• 1.6 から 1.7 への移行後：Microsoft の oid 行、OAuth クライアント、SCIM の再プロビジョニング、Expo の await getCookie()、およびそのスキーマを適用している場合は 1.7.0～1.7.2 の issuer クリーンアップを確認します。

実行したチェック、実行しなかったチェック、および未確定のバージョンに関する前提を報告してください。