supabase-best-practices

Supabase のベストプラクティス

Clerk 認証を統合した Supabase アプリケーション向けの、セキュリティとパフォーマンス最適化に関する包括的なガイドです。10 のカテゴリにわたる 40 以上のルールを、影響度の高い順にまとめ、安全な開発とコードレビューを支援します。

適用する場面

次のような場面で、これらのガイドラインを参照してください。

• 新しい Supabase プロジェクトをセットアップするとき
• Clerk 認証を Supabase と統合するとき
• Row Level Security（RLS）ポリシーを作成するとき
• データベーススキーマを設計するとき
• リアルタイム機能を実装するとき
• Storage バケットを設定するとき
• Edge Functions を作成するとき
• セキュリティ上の問題がないかコードをレビューするとき

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	Row Level Security	CRITICAL	rls-
2	Clerk Integration	CRITICAL	clerk-
3	Database Security	HIGH	db-
4	Authentication Patterns	HIGH	auth-
5	API Security	HIGH	api-
6	Storage Security	MEDIUM-HIGH	storage-
7	Realtime Security	MEDIUM	realtime-
8	Edge Functions	MEDIUM	edge-
9	Testing	MEDIUM	test-
10	Security	MEDIUM	security-

クイックリファレンス

1. Row Level Security（CRITICAL）

• rls-always-enable - public スキーマのテーブルでは常に RLS を有効にする
• rls-wrap-functions-select - パフォーマンス向上のため、認証関数を (SELECT ...) でラップする
• rls-add-indexes - RLS ポリシーで使用するカラムにインデックスを追加する
• rls-specify-roles - TO authenticated 句でロールを指定する
• rls-security-definer - 複雑なポリシーには SECURITY DEFINER 関数を使用する
• rls-minimize-joins - RLS ポリシーでの結合を最小限にする
• rls-explicit-auth-check - auth.uid() による明示的なチェックを使用する
• rls-restrictive-policies - 制約を追加するには RESTRICTIVE ポリシーを使用する

2. Clerk Integration（CRITICAL）

• clerk-setup-third-party - Third-Party Auth 統合を使用する（JWT テンプレートは使用しない）
• clerk-client-server-side - サーバーサイドクライアントには accessToken コールバックを使用する
• clerk-client-client-side - クライアントサイドクライアントには useSession() フックを使用する
• clerk-role-claim - Clerk で role: authenticated クレームを設定する
• clerk-org-policies - マルチテナント RLS には組織クレームを使用する
• clerk-mfa-policies - RESTRICTIVE ポリシーで MFA を強制する
• clerk-no-jwt-templates - 非推奨の JWT テンプレート統合は使用しない

3. Database Security（HIGH）

• db-migrations-versioned - スキーマ変更にはバージョン管理されたマイグレーションを使用する
• db-schema-design - 適切なスキーマ設計パターンに従う
• db-indexes-strategy - 適切なインデックス戦略を実装する
• db-foreign-keys - 常に外部キー制約を使用する
• db-triggers-security - トリガー関数を適切に保護する
• db-views-security-invoker - ビューには SECURITY INVOKER を使用する

4. Authentication Patterns（HIGH）

• auth-jwt-claims-validation - 常に JWT クレームを検証する
• auth-user-metadata-safety - user_metadata は信頼できないものとして扱う
• auth-app-metadata-authorization - 認可には app_metadata を使用する
• auth-session-management - 適切なセッション管理を実装する

5. API Security（HIGH）

• api-filter-queries - RLS が有効でも、クエリには常にフィルターを適用する
• api-publishable-keys - publishable キーを正しく使用する
• api-service-role-server-only - service role キーをクライアントに絶対に公開しない

6. Storage Security（MEDIUM-HIGH）

• storage-rls-policies - storage.objects で RLS を有効にする
• storage-bucket-security - バケットレベルのセキュリティを設定する
• storage-signed-urls - 非公開ファイルには署名付き URL を使用する

7. Realtime Security（MEDIUM）

• realtime-private-channels - 機密データにはプライベートチャンネルを使用する
• realtime-rls-authorization - RLS ポリシーはリアルタイム機能にも適用される
• realtime-cleanup-subscriptions - アンマウント時にサブスクリプションをクリーンアップする

8. Edge Functions（MEDIUM）

• edge-verify-jwt - Edge Functions では常に JWT を検証する
• edge-cors-handling - CORS を適切に処理する
• edge-secrets-management - 機密データにはシークレットを使用する

9. テスト（中）

• test-pgtap-rls - pgTAP で RLS ポリシーをテストします
• test-isolation - テストを適切に分離します
• test-helpers - テストヘルパー関数を使用します

10. セキュリティ（中）

• security-validate-inputs - 処理する前に、すべての入力を検証します
• security-audit-advisors - Security Advisor のチェックを定期的に実行します

使用方法

詳しい説明とコード例については、個々のルールファイルをお読みください。

references/rules/rls-always-enable.md
references/rules/clerk-setup-third-party.md
references/rules/_sections.md

各ルールファイルには、以下が含まれています。

• 重要な理由の簡単な説明
• 説明付きの誤ったコード例
• 説明付きの正しいコード例
• このパターンを使用しない場合
• 公式ドキュメントへの参考リンク

コンパイル済みドキュメント全文

すべてのルールを展開した完全なガイドについては、references/supabase-guidelines.md をご覧ください。