認証スキル

Better Auth を使用して TypeScript/JavaScript アプリケーションに認証を追加するためのガイド。

コード例と構文については、better-auth.com/docsを参照してください。

---

判断フロー

これは新規/空のプロジェクトですか?
├─ はい → 新規プロジェクトのセットアップ
│   1. フレームワークを特定する
│   2. データベースを選択する
│   3. better-auth をインストールする
│   4. auth.ts + auth-client.ts を作成する
│   5. ルートハンドラーをセットアップする
│   6. CLI migrate/generate を実行する
│   7. プラグインで機能を追加する
│
└─ いいえ → プロジェクトに既存の認証がありますか?
    ├─ はい → 移行/拡張
    │   • 現在の認証の不足部分を監査する
    │   • 段階的な移行を計画する
    │   • ドキュメント内の移行ガイドを参照する
    │
    └─ いいえ → 既存プロジェクトに認証を追加する
        1. プロジェクト構造を分析する
        2. better-auth をインストールする
        3. 認証設定を作成する
        4. ルートハンドラーを追加する
        5. スキーママイグレーションを実行する
        6. 既存ページに統合する

---

インストール

コア: npm install better-auth

スコープ付きパッケージ(必要に応じて):

パッケージ	ユースケース
@better-auth/passkey	WebAuthn/Passkey 認証
@better-auth/sso	SAML/OIDC エンタープライズ SSO
@better-auth/stripe	Stripe 支払い
@better-auth/scim	SCIM ユーザープロビジョニング
@better-auth/expo	React Native/Expo

---

環境変数

BETTER_AUTH_SECRET=<32文字以上、以下で生成: openssl rand -base64 32>
BETTER_AUTH_URL=http://localhost:3000
DATABASE_URL=<データベース接続文字列>

必要に応じて OAuth シークレットを追加します: GITHUB_CLIENT_ID、GITHUB_CLIENT_SECRET、GOOGLE_CLIENT_ID など。

---

サーバー設定 (auth.ts)

場所: lib/auth.ts または src/lib/auth.ts

最小限の設定が必要:

• database - コネクションまたはアダプター
• emailAndPassword: { enabled: true } - メール/パスワード認証用

標準設定の追加:

• socialProviders - OAuth プロバイダー(google、github など)
• emailVerification.sendVerificationEmail - メール確認ハンドラー
• emailAndPassword.sendResetPassword - パスワードリセットハンドラー

完全な設定の追加:

• plugins - 機能プラグインの配列
• session - 有効期限、クッキーキャッシュ設定
• account.accountLinking - マルチプロバイダーリンク
• rateLimit - レート制限設定

エクスポート型: export type Session = typeof auth.$Infer.Session

---

クライアント設定 (auth-client.ts)

フレームワークでインポート:

フレームワーク	インポート
React/Next.js	better-auth/react
Vue	better-auth/vue
Svelte	better-auth/svelte
Solid	better-auth/solid
Vanilla JS	better-auth/client

クライアントプラグインは createAuthClient({ plugins: [...] }) に指定します。

一般的なエクスポート: signIn、signUp、signOut、useSession、getSession

---

ルートハンドラーのセットアップ

フレームワーク	ファイル	ハンドラー
Next.js App Router	app/api/auth/[...all]/route.ts	toNextJsHandler(auth) → { GET, POST } をエクスポート
Next.js Pages	pages/api/auth/[...all].ts	toNextJsHandler(auth) → デフォルトエクスポート
Express	任意のファイル	app.all("/api/auth/*", toNodeHandler(auth))
SvelteKit	src/hooks.server.ts	svelteKitHandler(auth)
SolidStart	ルートファイル	solidStartHandler(auth)
Hono	ルートファイル	auth.handler(c.req.raw)

Next.js サーバーコンポーネント: 認証設定に nextCookies() プラグインを追加します。

---

データベースマイグレーション

アダプター	コマンド
ビルトイン Kysely	npx @better-auth/cli@latest migrate (直接適用)
Prisma	npx @better-auth/cli@latest generate --output prisma/schema.prisma の後に npx prisma migrate dev
Drizzle	npx @better-auth/cli@latest generate --output src/db/auth-schema.ts の後に npx drizzle-kit push

プラグイン追加後に再実行してください。

---

データベースアダプター

データベース	セットアップ
SQLite	better-sqlite3 または bun:sqlite インスタンスを直接渡す
PostgreSQL	pg.Pool インスタンスを直接渡す
MySQL	mysql2 プールを直接渡す
Prisma	better-auth/adapters/prisma からの prismaAdapter(prisma, { provider: "postgresql" })
Drizzle	better-auth/adapters/drizzle からの drizzleAdapter(db, { provider: "pg" })
MongoDB	better-auth/adapters/mongodb からの mongodbAdapter(db)

---

一般的なプラグイン

プラグイン	サーバーインポート	クライアントインポート	用途
twoFactor	better-auth/plugins	twoFactorClient	TOTP/OTP による 2FA
organization	better-auth/plugins	organizationClient	チーム/組織
admin	better-auth/plugins	adminClient	ユーザー管理
bearer	better-auth/plugins	-	API トークン認証
openAPI	better-auth/plugins	-	API ドキュメント
passkey	@better-auth/passkey	passkeyClient	WebAuthn
sso	@better-auth/sso	-	エンタープライズ SSO

プラグインパターン: サーバープラグイン + クライアントプラグイン + マイグレーション実行。

---

認証 UI の実装

サインインフロー:

1. signIn.email({ email, password }) または signIn.social({ provider, callbackURL })
2. レスポンスの error を処理する
3. 成功時にリダイレクトする

セッションチェック(クライアント): useSession() フックは { data: session, isPending } を返します

セッションチェック(サーバー): auth.api.getSession({ headers: await headers() })

保護されたルート: セッションをチェックし、null の場合は /sign-in にリダイレクトします。

---

セキュリティチェックリスト

• BETTER_AUTH_SECRET が設定されている(32文字以上)
• 本番環境で advanced.useSecureCookies: true が有効
• trustedOrigins が設定されている
• レート制限が有効
• メール確認が有効
• パスワードリセットが実装されている
• 機密アプリケーションに 2FA がある
• CSRF 保護が無効になっていない
• account.accountLinking がレビュー済み

---

トラブルシューティング

問題	解決方法
「Secret not set」	BETTER_AUTH_SECRET 環境変数を追加する
「Invalid Origin」	ドメインを trustedOrigins に追加する
クッキーが設定されない	baseURL がドメインと一致することを確認; 本番環境でセキュアクッキーを有効にする
OAuth コールバックエラー	プロバイダーダッシュボードでリダイレクト URI を確認する
プラグイン追加後の型エラー	CLI generate/migrate を再実行する

---

リソース

• ドキュメント
• サンプル
• プラグイン
• CLI
• 移行ガイド