b723e2bd7d
- Created skills/ directory - Moved 272 skills to skills/ subfolder - Kept agents/ at root level - Kept installation scripts and docs at root level Repository structure: - skills/ - All 272 skills from skills.sh - agents/ - Agent definitions - *.sh, *.ps1 - Installation scripts - README.md, etc. - Documentation Co-Authored-By: Claude <noreply@anthropic.com>
136 lines
5.0 KiB
Markdown
136 lines
5.0 KiB
Markdown
---
|
|
name: supabase-best-practices
|
|
description: Supabase security and performance guidelines with Clerk authentication integration. Contains 40+ rules across 10 categories covering RLS policies, Clerk setup, database security, and more.
|
|
license: MIT
|
|
metadata:
|
|
author: AI Engineering Team
|
|
version: "1.0.1"
|
|
last_updated: "2025-01-27"
|
|
---
|
|
|
|
# Supabase Best Practices
|
|
|
|
Comprehensive security and performance optimization guide for Supabase applications with Clerk authentication integration. Contains 40+ rules across 10 categories, prioritized by impact to guide secure development and code review.
|
|
|
|
## When to Apply
|
|
|
|
Reference these guidelines when:
|
|
- Setting up a new Supabase project
|
|
- Integrating Clerk authentication with Supabase
|
|
- Writing Row Level Security (RLS) policies
|
|
- Designing database schemas
|
|
- Implementing real-time features
|
|
- Configuring Storage buckets
|
|
- Writing Edge Functions
|
|
- Reviewing code for security issues
|
|
|
|
## Rule Categories by Priority
|
|
|
|
| Priority | Category | Impact | Prefix |
|
|
|----------|----------|--------|--------|
|
|
| 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-` |
|
|
|
|
## Quick Reference
|
|
|
|
### 1. Row Level Security (CRITICAL)
|
|
|
|
- `rls-always-enable` - Always enable RLS on public schema tables
|
|
- `rls-wrap-functions-select` - Wrap auth functions with (SELECT ...) for performance
|
|
- `rls-add-indexes` - Add indexes on columns used in RLS policies
|
|
- `rls-specify-roles` - Specify roles with TO authenticated clause
|
|
- `rls-security-definer` - Use SECURITY DEFINER functions for complex policies
|
|
- `rls-minimize-joins` - Minimize joins in RLS policies
|
|
- `rls-explicit-auth-check` - Use explicit auth.uid() checks
|
|
- `rls-restrictive-policies` - Use RESTRICTIVE policies for additional constraints
|
|
|
|
### 2. Clerk Integration (CRITICAL)
|
|
|
|
- `clerk-setup-third-party` - Use Third-Party Auth integration (not JWT templates)
|
|
- `clerk-client-server-side` - Use accessToken callback for server-side clients
|
|
- `clerk-client-client-side` - Use useSession() hook for client-side clients
|
|
- `clerk-role-claim` - Configure role: authenticated claim in Clerk
|
|
- `clerk-org-policies` - Use organization claims for multi-tenant RLS
|
|
- `clerk-mfa-policies` - Enforce MFA with RESTRICTIVE policies
|
|
- `clerk-no-jwt-templates` - Never use deprecated JWT template integration
|
|
|
|
### 3. Database Security (HIGH)
|
|
|
|
- `db-migrations-versioned` - Use versioned migrations for schema changes
|
|
- `db-schema-design` - Follow proper schema design patterns
|
|
- `db-indexes-strategy` - Implement proper indexing strategy
|
|
- `db-foreign-keys` - Always use foreign key constraints
|
|
- `db-triggers-security` - Secure trigger functions properly
|
|
- `db-views-security-invoker` - Use SECURITY INVOKER for views
|
|
|
|
### 4. Authentication Patterns (HIGH)
|
|
|
|
- `auth-jwt-claims-validation` - Always validate JWT claims
|
|
- `auth-user-metadata-safety` - Treat user_metadata as untrusted
|
|
- `auth-app-metadata-authorization` - Use app_metadata for authorization
|
|
- `auth-session-management` - Implement proper session management
|
|
|
|
### 5. API Security (HIGH)
|
|
|
|
- `api-filter-queries` - Always filter queries even with RLS
|
|
- `api-publishable-keys` - Use publishable keys correctly
|
|
- `api-service-role-server-only` - Never expose service role key to client
|
|
|
|
### 6. Storage Security (MEDIUM-HIGH)
|
|
|
|
- `storage-rls-policies` - Enable RLS on storage.objects
|
|
- `storage-bucket-security` - Configure bucket-level security
|
|
- `storage-signed-urls` - Use signed URLs for private files
|
|
|
|
### 7. Realtime Security (MEDIUM)
|
|
|
|
- `realtime-private-channels` - Use private channels for sensitive data
|
|
- `realtime-rls-authorization` - RLS policies apply to realtime
|
|
- `realtime-cleanup-subscriptions` - Clean up subscriptions on unmount
|
|
|
|
### 8. Edge Functions (MEDIUM)
|
|
|
|
- `edge-verify-jwt` - Always verify JWT in edge functions
|
|
- `edge-cors-handling` - Handle CORS properly
|
|
- `edge-secrets-management` - Use secrets for sensitive data
|
|
|
|
### 9. Testing (MEDIUM)
|
|
|
|
- `test-pgtap-rls` - Test RLS policies with pgTAP
|
|
- `test-isolation` - Isolate tests properly
|
|
- `test-helpers` - Use test helper functions
|
|
|
|
### 10. Security (MEDIUM)
|
|
|
|
- `security-validate-inputs` - Validate all inputs before processing
|
|
- `security-audit-advisors` - Regularly run Security Advisor checks
|
|
|
|
## How to Use
|
|
|
|
Read individual rule files for detailed explanations and code examples:
|
|
|
|
```
|
|
references/rules/rls-always-enable.md
|
|
references/rules/clerk-setup-third-party.md
|
|
references/rules/_sections.md
|
|
```
|
|
|
|
Each rule file contains:
|
|
- Brief explanation of why it matters
|
|
- Incorrect code example with explanation
|
|
- Correct code example with explanation
|
|
- When NOT to use the pattern
|
|
- Reference links to official documentation
|
|
|
|
## Full Compiled Document
|
|
|
|
For the complete guide with all rules expanded: `references/supabase-guidelines.md`
|