Initial commit

2025-11-29 18:46:56 +08:00
commit 9cf462a7c1
8 changed files with 1666 additions and 0 deletions
--- a/skills/supabase-rls-policy-generator/references/supabase-auth.md
+++ b/skills/supabase-rls-policy-generator/references/supabase-auth.md
@@ -0,0 +1,303 @@
+# Supabase Auth Reference
+
+This document provides reference information for Supabase authentication functions and JWT structure.
+
+## Core Auth Functions
+
+### auth.uid()
+
+Returns the UUID of the currently authenticated user.
+
+```sql
+-- Usage in RLS policy
+CREATE POLICY "User access own records"
+  ON table_name FOR SELECT
+  USING (auth.uid() = user_id);
+```
+
+**Returns**: UUID or NULL if unauthenticated
+
+**Common Uses**:
+- User ownership checks
+- Filtering user-specific data
+- Inserting records with current user ID
+
+### auth.jwt()
+
+Returns the full JSON Web Token for the authenticated user.
+
+```sql
+-- Access top-level claims
+auth.jwt() ->> 'role'  -- Returns: 'authenticated', 'anon', custom role
+
+-- Access nested app_metadata
+auth.jwt() -> 'app_metadata' ->> 'subscription_tier'
+auth.jwt() -> 'app_metadata' ->> 'organization_id'
+
+-- Access user_metadata
+auth.jwt() -> 'user_metadata' ->> 'display_name'
+```
+
+**Returns**: JSONB object or NULL if unauthenticated
+
+## JWT Structure
+
+Standard Supabase JWT contains:
+
+```json
+{
+  "aud": "authenticated",
+  "exp": 1234567890,
+  "sub": "user-uuid",
+  "email": "user@example.com",
+  "phone": "",
+  "app_metadata": {
+    "provider": "email",
+    "providers": ["email"]
+  },
+  "user_metadata": {
+    "display_name": "John Doe",
+    "avatar_url": "https://..."
+  },
+  "role": "authenticated",
+  "aal": "aal1",
+  "amr": [
+    {
+      "method": "password",
+      "timestamp": 1234567890
+    }
+  ],
+  "session_id": "session-uuid"
+}
+```
+
+### Custom Claims
+
+Add custom claims via database functions or auth hooks:
+
+```sql
+-- Example: Add custom role from database
+CREATE OR REPLACE FUNCTION auth.custom_access_token_hook(event jsonb)
+RETURNS jsonb
+LANGUAGE plpgsql
+AS $$
+DECLARE
+  user_role TEXT;
+  org_id UUID;
+BEGIN
+  -- Get user's role and organization
+  SELECT role, organization_id INTO user_role, org_id
+  FROM user_profiles
+  WHERE id = (event->>'user_id')::uuid;
+
+  -- Add custom claims
+  event := jsonb_set(event, '{claims,role}', to_jsonb(user_role));
+  event := jsonb_set(event, '{claims,organization_id}', to_jsonb(org_id::text));
+
+  RETURN event;
+END;
+$$;
+```
+
+Access custom claims in policies:
+
+```sql
+-- Check custom role
+CREATE POLICY "Admin access"
+  ON table_name FOR ALL
+  USING (auth.jwt() ->> 'role' = 'admin');
+
+-- Check custom organization
+CREATE POLICY "Organization access"
+  ON table_name FOR SELECT
+  USING (
+    organization_id = (auth.jwt() ->> 'organization_id')::uuid
+  );
+```
+
+## Common Patterns
+
+### Check Authentication Status
+
+```sql
+-- Require authenticated user
+USING (auth.uid() IS NOT NULL)
+
+-- Allow both authenticated and anonymous
+USING (true)
+
+-- Authenticated users only
+USING (auth.jwt() ->> 'role' = 'authenticated')
+```
+
+### Role-Based Access
+
+```sql
+-- Simple role check
+USING (auth.jwt() ->> 'role' = 'admin')
+
+-- Multiple roles
+USING (
+  auth.jwt() ->> 'role' IN ('admin', 'moderator')
+)
+
+-- Custom role from app_metadata
+USING (
+  auth.jwt() -> 'app_metadata' ->> 'custom_role' = 'premium_user'
+)
+```
+
+### Email Verification
+
+```sql
+-- Require verified email
+USING (
+  (auth.jwt() -> 'email_confirmed_at') IS NOT NULL
+)
+```
+
+### Multi-Factor Authentication
+
+```sql
+-- Require MFA
+USING (
+  auth.jwt() ->> 'aal' = 'aal2'
+)
+```
+
+## Session Management
+
+### Session ID
+
+Access current session:
+
+```sql
+-- Filter by session
+USING (
+  session_id = (auth.jwt() ->> 'session_id')::uuid
+)
+```
+
+### Authentication Method
+
+Check how user authenticated:
+
+```sql
+-- Check for password authentication
+USING (
+  EXISTS (
+    SELECT 1 FROM jsonb_array_elements(auth.jwt() -> 'amr') AS method
+    WHERE method ->> 'method' = 'password'
+  )
+)
+
+-- Check for OAuth
+USING (
+  EXISTS (
+    SELECT 1 FROM jsonb_array_elements(auth.jwt() -> 'amr') AS method
+    WHERE method ->> 'method' = 'oauth'
+  )
+)
+```
+
+## User Metadata vs App Metadata
+
+### User Metadata
+- User-controlled data
+- Can be updated by user
+- Store preferences, profile info
+- Access: `auth.jwt() -> 'user_metadata'`
+
+### App Metadata
+- Admin-controlled data
+- Cannot be updated by user
+- Store roles, permissions, org IDs
+- Access: `auth.jwt() -> 'app_metadata'`
+
+## Security Considerations
+
+### Always Validate User ID
+
+```sql
+-- GOOD: Enforce user ID on insert
+CREATE POLICY "Insert own records"
+  ON table_name FOR INSERT
+  WITH CHECK (auth.uid() = user_id);
+
+-- BAD: Allow any user_id
+CREATE POLICY "Insert records"
+  ON table_name FOR INSERT
+  WITH CHECK (true);
+```
+
+### Don't Trust Client-Provided IDs
+
+```sql
+-- GOOD: Use auth.uid() directly
+INSERT INTO posts (user_id, content)
+VALUES (auth.uid(), 'content');
+
+-- BAD: Trust client-provided user_id
+INSERT INTO posts (user_id, content)
+VALUES ($1, $2);  -- Client could pass any user_id
+```
+
+### Use SECURITY DEFINER Carefully
+
+```sql
+-- Mark function as SECURITY DEFINER only when necessary
+CREATE FUNCTION check_permission()
+RETURNS BOOLEAN
+SECURITY DEFINER  -- Runs with function owner's privileges
+AS $$
+  -- Be very careful here - this bypasses RLS
+$$;
+```
+
+## Testing Auth Context
+
+Test policies with different auth states:
+
+```sql
+-- Set user ID
+SET request.jwt.claim.sub = 'user-uuid';
+
+-- Set role
+SET request.jwt.claim.role = 'admin';
+
+-- Set custom claims
+SET request.jwt.claims = '{"role": "admin", "organization_id": "org-uuid"}';
+
+-- Reset
+RESET request.jwt.claim.sub;
+RESET request.jwt.claim.role;
+RESET request.jwt.claims;
+```
+
+## Common Errors
+
+### "function auth.uid() does not exist"
+- RLS is not enabled on the database
+- Not using Supabase's auth schema
+
+### NULL when expecting user ID
+- User is not authenticated
+- Token has expired
+- Policy executed outside auth context
+
+### "permission denied for relation"
+- RLS is enabled but no policies match
+- User doesn't have base GRANT permissions
+
+## Performance Tips
+
+1. **Cache JWT lookups**: Use helper functions to avoid repeated JWT parsing
+2. **Index foreign keys**: Always index user_id, tenant_id, etc.
+3. **Avoid complex JWT parsing**: Move complex logic to helper functions
+4. **Use materialized views**: For complex role hierarchies
+
+## Additional Resources
+
+- Supabase Auth Documentation: https://supabase.com/docs/guides/auth
+- Row Level Security Guide: https://supabase.com/docs/guides/auth/row-level-security
+- JWT Customization: https://supabase.com/docs/guides/auth/custom-claims-and-role-based-access-control-rbac