aiox-core 5.0.4 → 5.0.7

package/pro/squads/db-sage/templates/rls-policies-tmpl.yaml

@@ -0,0 +1,1201 @@
+template_name: "Supabase RLS Policies"
+template_version: "1.0.0"
+output_format: "markdown"
+destination: "rls-policies.md"
+description: "Row Level Security policies for Supabase tables"
+
+sections:
+  - id: overview
+    title: "RLS Overview"
+    instruction: |
+      Document the Row Level Security strategy:
+      
+      ## Purpose
+      Explain the overall security model and why RLS is being used.
+      
+      ## Authentication Context
+      - How users are authenticated (Supabase Auth, JWT, etc)
+      - Available auth context variables:
+        - `auth.uid()` - Current user ID
+        - `auth.jwt()` - JWT claims
+        - `auth.email()` - User email
+        - Custom claims in JWT
+      
+      ## Security Model
+      - Role-based access control (RBAC)
+      - Multi-tenancy approach (if applicable)
+      - Public vs authenticated vs specific role access
+      
+      ## Performance Considerations
+      - RLS policy performance impact
+      - Indexing strategy to support policies
+      - Caching considerations
+      
+      ## Testing Strategy
+      - How policies will be tested
+      - Test users and scenarios
+    elicit: true
+    
+  - id: policy-patterns
+    title: "Common Policy Patterns"
+    instruction: |
+      Document reusable policy patterns used across tables:
+      
+      ## Pattern 1: Owner-Only Access
+      ```sql
+      -- Users can only access their own records
+      (auth.uid() = user_id)
+      ```
+      
+      ## Pattern 2: Tenant-Based Access
+      ```sql
+      -- Users can access records in their organization
+      (auth.uid() IN (
+        SELECT user_id FROM org_members 
+        WHERE org_id = table.org_id
+      ))
+      ```
+      
+      ## Pattern 3: Role-Based Access
+      ```sql
+      -- Only admins can access
+      ((auth.jwt() ->> 'role')::text = 'admin')
+      ```
+      
+      ## Pattern 4: Public Read, Authenticated Write
+      ```sql
+      -- SELECT: true (public read)
+      -- INSERT/UPDATE/DELETE: auth.uid() IS NOT NULL
+      ```
+      
+      ## Pattern 5: Hierarchical Permissions
+      ```sql
+      -- Access based on organizational hierarchy
+      ```
+      
+      Document any other patterns specific to your application.
+    elicit: true
+    
+  - id: table-policies
+    title: "Table-by-Table Policies"
+    instruction: |
+      For each table requiring RLS, document comprehensive policies:
+      
+      # Table: `table_name`
+      
+      ## Enable RLS
+      ```sql
+      ALTER TABLE table_name ENABLE ROW LEVEL SECURITY;
+      ```
+      
+      ## SELECT Policies
+      
+      ### Policy: `policy_name_select`
+      **Purpose**: Describe who can read what
+      
+      **Policy Expression**:
+      ```sql
+      CREATE POLICY "policy_name_select"
+      ON table_name
+      FOR SELECT
+      TO authenticated -- or public, anon, etc
+      USING (
+        -- Policy expression
+        auth.uid() = user_id
+      );
+      ```
+      
+      **Rationale**: Explain the business rule
+      
+      **Performance**: Any indexes needed to support this policy
+      
+      ## INSERT Policies
+      
+      ### Policy: `policy_name_insert`
+      **Purpose**: Describe who can create records
+      
+      **Policy Expression**:
+      ```sql
+      CREATE POLICY "policy_name_insert"
+      ON table_name
+      FOR INSERT
+      TO authenticated
+      WITH CHECK (
+        -- Policy expression
+        auth.uid() = user_id
+      );
+      ```
+      
+      **Validation**: What validations this ensures
+      
+      ## UPDATE Policies
+      
+      ### Policy: `policy_name_update`
+      **Purpose**: Describe who can modify records
+      
+      **Policy Expression**:
+      ```sql
+      CREATE POLICY "policy_name_update"
+      ON table_name
+      FOR UPDATE
+      TO authenticated
+      USING (
+        -- Who can see the record to update it
+        auth.uid() = user_id
+      )
+      WITH CHECK (
+        -- What values they can set
+        auth.uid() = user_id
+      );
+      ```
+      
+      **Notes**: USING checks old values, WITH CHECK validates new values
+      
+      ## DELETE Policies
+      
+      ### Policy: `policy_name_delete`
+      **Purpose**: Describe who can delete records
+      
+      **Policy Expression**:
+      ```sql
+      CREATE POLICY "policy_name_delete"
+      ON table_name
+      FOR DELETE
+      TO authenticated
+      USING (
+        -- Who can delete
+        auth.uid() = user_id OR
+        (auth.jwt() ->> 'role')::text = 'admin'
+      );
+      ```
+      
+      ## ALL Policies (if using combined policy)
+      
+      Sometimes a single policy for all operations is clearer:
+      
+      ```sql
+      CREATE POLICY "policy_name_all"
+      ON table_name
+      FOR ALL
+      TO authenticated
+      USING (auth.uid() = user_id)
+      WITH CHECK (auth.uid() = user_id);
+      ```
+      
+      ---
+      
+      Repeat this section for each table.
+    elicit: true
+    
+  - id: public-tables
+    title: "Public Tables"
+    instruction: |
+      Document tables with public read access:
+      
+      # Table: `public_table_name`
+      
+      ## Public Read Policy
+      ```sql
+      ALTER TABLE public_table_name ENABLE ROW LEVEL SECURITY;
+      
+      CREATE POLICY "public_read_policy"
+      ON public_table_name
+      FOR SELECT
+      TO anon, authenticated
+      USING (true);
+      ```
+      
+      ## Restricted Write Policy
+      ```sql
+      CREATE POLICY "authenticated_write_policy"
+      ON public_table_name
+      FOR INSERT
+      TO authenticated
+      WITH CHECK (auth.uid() IS NOT NULL);
+      ```
+      
+      **Rationale**: Why this table is public
+      
+      **Security Considerations**: What data is safe to expose
+    elicit: false
+    
+  - id: service-role
+    title: "Service Role Bypass"
+    instruction: |
+      Document scenarios where service role (bypass RLS) is used:
+      
+      ## Service Role Usage
+      
+      ### Backend Operations
+      Operations that need to bypass RLS:
+      - Scheduled jobs (cron, edge functions with service key)
+      - Admin operations
+      - Data migration
+      - Analytics aggregation
+      
+      ### Safety Measures
+      - How service key is secured
+      - Where service role operations are logged
+      - Who has access to service key
+      
+      ### Alternatives
+      When possible, prefer:
+      - Security definer functions with RLS
+      - Elevated permission policies
+      - Temporary privilege escalation
+    elicit: false
+    
+  - id: helper-functions
+    title: "Security Helper Functions"
+    instruction: |
+      Document PostgreSQL functions that support RLS:
+      
+      ## Function: `check_user_permission`
+      ```sql
+      CREATE OR REPLACE FUNCTION check_user_permission(
+        user_id uuid,
+        resource_id uuid,
+        permission_type text
+      )
+      RETURNS boolean
+      LANGUAGE plpgsql
+      SECURITY DEFINER
+      AS $$
+      BEGIN
+        -- Permission checking logic
+        RETURN EXISTS (
+          SELECT 1 FROM permissions
+          WHERE user_id = $1
+          AND resource_id = $2
+          AND permission = $3
+        );
+      END;
+      $$;
+      ```
+      
+      **Usage in Policies**:
+      ```sql
+      USING (check_user_permission(auth.uid(), id, 'read'))
+      ```
+      
+      ## Function: `get_user_org_id`
+      ```sql
+      CREATE OR REPLACE FUNCTION get_user_org_id()
+      RETURNS uuid
+      LANGUAGE sql
+      STABLE
+      AS $$
+        SELECT org_id FROM user_profiles
+        WHERE user_id = auth.uid();
+      $$;
+      ```
+      
+      **Usage in Policies**:
+      ```sql
+      USING (org_id = get_user_org_id())
+      ```
+      
+      Document all helper functions used in RLS policies.
+    elicit: false
+    
+  - id: multi-tenancy
+    title: "Multi-Tenancy Implementation"
+    condition: "multi_tenant"
+    instruction: |
+      If implementing multi-tenancy with RLS:
+      
+      ## Tenant Isolation Strategy
+      
+      ### Tenant Identification
+      - How tenants are identified (org_id, team_id, etc)
+      - Where tenant ID is stored (JWT claim, database lookup)
+      
+      ### Tenant-Scoped Tables
+      
+      For each tenant-scoped table:
+      
+      ```sql
+      -- Example: projects table
+      CREATE POLICY "tenant_isolation_policy"
+      ON projects
+      FOR ALL
+      TO authenticated
+      USING (
+        org_id = (auth.jwt() ->> 'org_id')::uuid
+      )
+      WITH CHECK (
+        org_id = (auth.jwt() ->> 'org_id')::uuid
+      );
+      ```
+      
+      ### Cross-Tenant Scenarios
+      - Shared resources across tenants
+      - Super admin access
+      - Tenant-to-tenant relationships
+      
+      ### Performance
+      - Indexes on tenant_id columns
+      - Query patterns that leverage tenant isolation
+    elicit: true
+
+  - id: storage-policies
+    title: "Supabase Storage Policies"
+    instruction: |
+      RLS policies for Supabase Storage buckets (storage.objects table).
+
+      ## Overview
+
+      Supabase Storage uses RLS on the `storage.objects` system table to control file access.
+      By default, Storage requires explicit RLS policies - no uploads allowed without policies.
+
+      ## Pattern 1: User-Specific Uploads
+
+      Users can only upload files to their own folder:
+
+      ```sql
+      CREATE POLICY "Users upload own avatars"
+      ON storage.objects
+      FOR INSERT
+      TO authenticated
+      WITH CHECK (
+        bucket_id = 'avatars' AND
+        (select auth.uid())::text = (storage.foldername(name))[1]
+      );
+      ```
+
+      **Folder Structure**: `avatars/{user_id}/filename.jpg`
+
+      **How it works**:
+      - `storage.foldername(name)` splits path by `/` returning array
+      - `[1]` gets first folder (user_id)
+      - Compares with authenticated user's ID
+
+      ## Pattern 2: Public Read, Authenticated Write
+
+      Anyone can view files, only authenticated users can upload:
+
+      ```sql
+      -- Public read
+      CREATE POLICY "Public avatars readable"
+      ON storage.objects
+      FOR SELECT
+      TO public
+      USING (bucket_id = 'avatars');
+
+      -- Authenticated write
+      CREATE POLICY "Authenticated upload avatars"
+      ON storage.objects
+      FOR INSERT
+      TO authenticated
+      WITH CHECK (bucket_id = 'avatars');
+      ```
+
+      **Use case**: Public profile pictures, logos, marketing assets.
+
+      ## Pattern 3: Tenant-Scoped Files
+
+      Users can only access files from their organization:
+
+      ```sql
+      CREATE POLICY "Tenant file isolation"
+      ON storage.objects
+      FOR SELECT
+      TO authenticated
+      USING (
+        bucket_id = 'documents' AND
+        (storage.foldername(name))[1] = ((select auth.jwt()) ->> 'org_id')
+      );
+
+      CREATE POLICY "Tenant file uploads"
+      ON storage.objects
+      FOR INSERT
+      TO authenticated
+      WITH CHECK (
+        bucket_id = 'documents' AND
+        (storage.foldername(name))[1] = ((select auth.jwt()) ->> 'org_id')
+      );
+      ```
+
+      **Folder Structure**: `documents/{org_id}/{file_id}.pdf`
+
+      ## Pattern 4: Delete Own Files
+
+      Users can delete their own files:
+
+      ```sql
+      CREATE POLICY "Users delete own files"
+      ON storage.objects
+      FOR DELETE
+      TO authenticated
+      USING (
+        bucket_id = 'avatars' AND
+        (select auth.uid())::text = (storage.foldername(name))[1]
+      );
+      ```
+
+      ## Pattern 5: File Overwriting (upsert)
+
+      For file overwriting via `upsert` option, grant SELECT + UPDATE:
+
+      ```sql
+      -- Allow reading (required for upsert check)
+      CREATE POLICY "Users read own files"
+      ON storage.objects
+      FOR SELECT
+      TO authenticated
+      USING (
+        bucket_id = 'avatars' AND
+        (select auth.uid())::text = (storage.foldername(name))[1]
+      );
+
+      -- Allow updating (for upsert)
+      CREATE POLICY "Users update own files"
+      ON storage.objects
+      FOR UPDATE
+      TO authenticated
+      USING (
+        bucket_id = 'avatars' AND
+        (select auth.uid())::text = (storage.foldername(name))[1]
+      )
+      WITH CHECK (
+        bucket_id = 'avatars' AND
+        (select auth.uid())::text = (storage.foldername(name))[1]
+      );
+      ```
+
+      ## Bucket Configuration
+
+      Create buckets with appropriate public/private settings:
+
+      ```sql
+      -- Create private bucket (requires policies)
+      INSERT INTO storage.buckets (id, name, public)
+      VALUES ('avatars', 'avatars', false);
+
+      -- Create public bucket (files publicly accessible by URL)
+      INSERT INTO storage.buckets (id, name, public)
+      VALUES ('public-images', 'public-images', true);
+      ```
+
+      **Note**: Even public buckets respect RLS for uploads/deletes.
+
+      ## Helper Functions
+
+      ```sql
+      -- Extract user folder from path
+      CREATE OR REPLACE FUNCTION storage.user_owns_file(file_path text)
+      RETURNS boolean
+      LANGUAGE sql
+      STABLE
+      AS $$
+        SELECT (select auth.uid())::text = (storage.foldername(file_path))[1];
+      $$;
+
+      -- Usage in policy
+      CREATE POLICY "Users access own files"
+      ON storage.objects
+      FOR ALL
+      TO authenticated
+      USING (
+        bucket_id = 'private' AND
+        storage.user_owns_file(name)
+      );
+      ```
+
+      ## Security Considerations
+
+      1. **Always validate bucket_id** in policies (prevent cross-bucket access)
+      2. **Use folder structure** for user/tenant isolation
+      3. **Set appropriate bucket public/private** settings
+      4. **Monitor storage size** per user/tenant (implement quotas)
+      5. **Validate file types** server-side (policies can't check content)
+
+      ## Testing
+
+      Test storage policies with Supabase client:
+
+      ```typescript
+      // Test upload as user A
+      const { data, error } = await supabase.storage
+        .from('avatars')
+        .upload(`${user.id}/avatar.jpg`, file);
+
+      // Should succeed for own folder
+      expect(error).toBeNull();
+
+      // Test read as user B (should fail for user A's folder)
+      const { data: files, error: listError } = await supabase.storage
+        .from('avatars')
+        .list(`${otherUserId}/`);
+
+      // Should return empty or error
+      expect(files).toHaveLength(0);
+      ```
+
+      ## Performance
+
+      Storage policies are evaluated on every file operation.
+
+      **Optimize**:
+      - Use simple folder path checks (fast)
+      - Avoid complex JOINs in storage policies
+      - Cache JWT claims in helper functions
+      - Use indexes on bucket_id (already indexed by Supabase)
+
+      ## Common Pitfalls
+
+      - **Forgetting SELECT policy** for upsert operations
+      - **Not validating bucket_id** (allows cross-bucket access)
+      - **Complex policies** (slow file operations)
+      - **Mixing public/private** bucket settings incorrectly
+    elicit: false
+
+  - id: performance-optimization
+    title: "RLS Performance Optimization"
+    instruction: |
+      Critical performance optimizations for RLS policies validated by Supabase documentation.
+
+      ## 🚀 Optimization 1: Wrap Auth Functions with SELECT (94.97% faster)
+
+      **Critical Discovery** from Supabase docs: Wrapping auth functions enables query caching.
+
+      ### ❌ SLOW (no caching):
+      ```sql
+      CREATE POLICY "users_select"
+      ON users
+      FOR SELECT
+      TO authenticated
+      USING (auth.uid() = user_id);
+      ```
+
+      ### ✅ FAST (cached, 94.97% improvement):
+      ```sql
+      CREATE POLICY "users_select"
+      ON users
+      FOR SELECT
+      TO authenticated
+      USING ((select auth.uid()) = user_id);
+      ```
+
+      **Why**: PostgreSQL caches the result of `(select auth.uid())` for the duration of the transaction,
+      avoiding repeated function calls.
+
+      **Impact**: **19x faster queries** in high-traffic scenarios.
+
+      **Apply to all auth functions**:
+      - `(select auth.uid())`
+      - `(select auth.jwt())`
+      - `(select auth.email())`
+
+      ## 🚀 Optimization 2: Index Policy Columns (99.94% improvement)
+
+      **Always index columns used in policy expressions.**
+
+      ```sql
+      -- Policy uses user_id
+      CREATE POLICY "user_policy" ON posts
+      USING ((select auth.uid()) = user_id);
+
+      -- Index user_id (99.94% faster)
+      CREATE INDEX idx_posts_user_id ON posts(user_id);
+      ```
+
+      **Critical indexes**:
+      ```sql
+      -- Tenant isolation
+      CREATE INDEX idx_table_org_id ON table_name(org_id);
+
+      -- Owner-based policies
+      CREATE INDEX idx_table_user_id ON table_name(user_id);
+
+      -- Time-based policies
+      CREATE INDEX idx_table_scheduling
+        ON table_name(publish_at, expire_at)
+        WHERE publish_at IS NOT NULL OR expire_at IS NOT NULL;
+      ```
+
+      ## 🚀 Optimization 3: Filter Client-Side Explicitly
+
+      **Even with RLS policies, explicitly filter in client queries.**
+
+      ```typescript
+      // ❌ Relies only on RLS
+      const { data } = await supabase
+        .from('users')
+        .select('*');  // Returns only own data due to RLS, but query planner doesn't know
+
+      // ✅ Explicit filter (helps query planner)
+      const { data } = await supabase
+        .from('users')
+        .select('*')
+        .eq('user_id', userId);  // Query planner can use index
+      ```
+
+      **Why**: Explicit filters help PostgreSQL query planner choose optimal index scan.
+
+      ## 🚀 Optimization 4: Specify Roles Explicitly
+
+      ```sql
+      -- ❌ Applies to all roles (unnecessary checks)
+      CREATE POLICY "policy" ON table USING (...);
+
+      -- ✅ Specific role (fewer checks)
+      CREATE POLICY "policy" ON table
+      TO authenticated  -- Only authenticated users
+      USING (...);
+      ```
+
+      **Common roles**:
+      - `TO authenticated` - Logged-in users
+      - `TO anon` - Anonymous users
+      - `TO public` - Both authenticated and anon
+
+      ## 🚀 Optimization 5: Use Security Definer Functions
+
+      **Bypass RLS on join tables** with security definer functions.
+
+      ```sql
+      -- ❌ Policy with JOIN (slow, 99.99% slower)
+      CREATE POLICY "team_access" ON documents
+      USING (
+        team_id IN (
+          SELECT team_id FROM user_teams
+          WHERE user_id = (select auth.uid())
+        )
+      );
+
+      -- ✅ Security definer function (99.99% improvement)
+      CREATE OR REPLACE FUNCTION user_team_ids()
+      RETURNS TABLE(team_id UUID)
+      LANGUAGE sql
+      STABLE
+      SECURITY DEFINER
+      AS $$
+        SELECT team_id FROM user_teams
+        WHERE user_id = auth.uid();
+      $$;
+
+      CREATE POLICY "team_access" ON documents
+      USING (team_id IN (SELECT user_team_ids()));
+      ```
+
+      **Why**: Security definer functions run with elevated privileges, bypassing RLS on join tables.
+
+      ## 🚀 Optimization 6: Minimize Joins
+
+      **Avoid joining source and target tables in policies.**
+
+      ```sql
+      -- ❌ JOIN in policy (slow)
+      CREATE POLICY "org_access" ON documents
+      USING (
+        EXISTS (
+          SELECT 1 FROM users
+          WHERE users.id = (select auth.uid())
+            AND users.org_id = documents.org_id
+        )
+      );
+
+      -- ✅ Use JWT claims (no JOIN)
+      CREATE POLICY "org_access" ON documents
+      USING (
+        org_id = ((select auth.jwt()) ->> 'org_id')::uuid
+      );
+      ```
+
+      **Strategy**: Store necessary claims in JWT (org_id, role, tenant_id).
+
+      ## Performance Checklist
+
+      Apply to every RLS policy:
+
+      - [ ] Wrap `auth.uid()` with `(select auth.uid())`
+      - [ ] Index all columns used in USING/WITH CHECK
+      - [ ] Specify role explicitly (TO authenticated vs TO public)
+      - [ ] Use JWT claims instead of JOINs where possible
+      - [ ] Create security definer functions for complex permission checks
+      - [ ] Test query plans with EXPLAIN ANALYZE
+      - [ ] Filter client-side explicitly
+
+      ## Measuring Performance
+
+      ```sql
+      -- Check query plan (look for Sequential Scan vs Index Scan)
+      EXPLAIN ANALYZE
+      SELECT * FROM users WHERE user_id = 'xxx';
+
+      -- Monitor slow queries
+      SELECT
+        query,
+        calls,
+        mean_exec_time,
+        max_exec_time
+      FROM pg_stat_statements
+      WHERE query LIKE '%users%'
+      ORDER BY mean_exec_time DESC
+      LIMIT 10;
+      ```
+
+      ## Real-World Impact
+
+      **Before optimization**:
+      - Query time: 250ms
+      - Database CPU: 80%
+      - Queries/sec: 40
+
+      **After optimization** (wrapped functions + indexes):
+      - Query time: 12ms (95% improvement)
+      - Database CPU: 15%
+      - Queries/sec: 800 (20x increase)
+    elicit: false
+
+  - id: advanced-patterns
+    title: "Advanced RLS Patterns"
+    instruction: |
+      Advanced RLS patterns beyond basic owner-only and tenant isolation.
+
+      ## Pattern 6: Time-Based Access (Scheduled Content)
+
+      **Use case**: Blog posts with scheduled publishing, promotions with expiration, time-limited content.
+
+      ```sql
+      CREATE POLICY "scheduled_content"
+      ON posts
+      FOR SELECT
+      TO authenticated
+      USING (
+        (publish_at IS NULL OR publish_at <= NOW()) AND
+        (expire_at IS NULL OR expire_at > NOW())
+      );
+      ```
+
+      **How it works**:
+      - `publish_at IS NULL` - No schedule, always visible
+      - `publish_at <= NOW()` - Past publish date, visible
+      - `expire_at IS NULL` - No expiration, always visible
+      - `expire_at > NOW()` - Not expired, visible
+
+      **Performance**:
+      ```sql
+      -- Index for time-based queries
+      CREATE INDEX idx_posts_scheduling
+      ON posts(publish_at, expire_at)
+      WHERE publish_at IS NOT NULL OR expire_at IS NOT NULL;
+      ```
+
+      **Client-side filtering** (helps query planner):
+      ```typescript
+      const { data } = await supabase
+        .from('posts')
+        .select('*')
+        .lte('publish_at', new Date().toISOString())
+        .or('publish_at.is.null')
+        .gte('expire_at', new Date().toISOString())
+        .or('expire_at.is.null');
+      ```
+
+      ## Pattern 7: Hierarchical Organizations (Detailed)
+
+      **Use case**: Org > Team > User hierarchy with different access levels.
+
+      ### Simple Hierarchy (Org-Level):
+      ```sql
+      CREATE POLICY "org_hierarchy"
+      ON resources
+      FOR SELECT
+      TO authenticated
+      USING (
+        org_id IN (
+          SELECT org_id
+          FROM user_org_memberships
+          WHERE user_id = (select auth.uid())
+        )
+      );
+      ```
+
+      **User sees resources from ALL orgs they belong to.**
+
+      ### Complex Hierarchy (Org + Team):
+      ```sql
+      -- Option 1: User sees resources from their teams
+      CREATE POLICY "team_hierarchy"
+      ON resources
+      FOR SELECT
+      TO authenticated
+      USING (
+        team_id IN (
+          SELECT team_id
+          FROM user_team_memberships
+          WHERE user_id = (select auth.uid())
+        )
+      );
+
+      -- Option 2: Combined (org admin sees all, team member sees team only)
+      CREATE POLICY "combined_hierarchy"
+      ON resources
+      FOR SELECT
+      TO authenticated
+      USING (
+        -- Org admin sees all resources in org
+        (
+          org_id IN (
+            SELECT org_id
+            FROM user_org_memberships
+            WHERE user_id = (select auth.uid()) AND role = 'admin'
+          )
+        )
+        OR
+        -- Team member sees only team resources
+        (
+          team_id IN (
+            SELECT team_id
+            FROM user_team_memberships
+            WHERE user_id = (select auth.uid())
+          )
+        )
+      );
+      ```
+
+      **Performance**:
+      ```sql
+      -- Indexes for hierarchy lookups
+      CREATE INDEX idx_user_org_memberships_user
+        ON user_org_memberships(user_id, org_id);
+
+      CREATE INDEX idx_user_team_memberships_user
+        ON user_team_memberships(user_id, team_id);
+
+      CREATE INDEX idx_resources_org_id ON resources(org_id);
+      CREATE INDEX idx_resources_team_id ON resources(team_id);
+      ```
+
+      **Optimization** (security definer function):
+      ```sql
+      CREATE OR REPLACE FUNCTION user_accessible_orgs()
+      RETURNS TABLE(org_id UUID)
+      LANGUAGE sql
+      STABLE
+      SECURITY DEFINER
+      AS $$
+        SELECT org_id FROM user_org_memberships
+        WHERE user_id = auth.uid();
+      $$;
+
+      CREATE POLICY "org_hierarchy_optimized"
+      ON resources
+      FOR SELECT
+      TO authenticated
+      USING (org_id IN (SELECT user_accessible_orgs()));
+      ```
+
+      ## Pattern 8: Role-Based with Custom Claims (Advanced)
+
+      **Use case**: Different permissions per role (admin, manager, analyst, user).
+
+      ### Setup: Add role to JWT
+      ```sql
+      CREATE OR REPLACE FUNCTION custom_access_token_hook(event jsonb)
+      RETURNS jsonb AS $$
+      DECLARE
+        claims jsonb;
+        user_role text;
+        user_org_id uuid;
+      BEGIN
+        -- Get user role and org from profiles table
+        SELECT role, org_id INTO user_role, user_org_id
+        FROM public.user_profiles
+        WHERE user_id = (event->>'user_id')::uuid;
+
+        -- Add to JWT claims
+        claims := event->'claims';
+        claims := jsonb_set(claims, '{role}', to_jsonb(user_role));
+        claims := jsonb_set(claims, '{org_id}', to_jsonb(user_org_id));
+
+        RETURN jsonb_set(event, '{claims}', claims);
+      END;
+      $$ LANGUAGE plpgsql SECURITY DEFINER;
+      ```
+
+      **Configure in Supabase Dashboard**: Authentication > Hooks > Custom Access Token
+
+      ### Policy: Role-Based Access
+      ```sql
+      -- Admin sees all
+      CREATE POLICY "admin_full_access"
+      ON sensitive_data
+      FOR ALL
+      TO authenticated
+      USING (
+        ((select auth.jwt()) ->> 'role') = 'admin'
+      );
+
+      -- Manager sees org data
+      CREATE POLICY "manager_org_access"
+      ON sensitive_data
+      FOR SELECT
+      TO authenticated
+      USING (
+        ((select auth.jwt()) ->> 'role') = 'manager' AND
+        org_id = ((select auth.jwt()) ->> 'org_id')::uuid
+      );
+
+      -- User sees own data only
+      CREATE POLICY "user_own_access"
+      ON sensitive_data
+      FOR SELECT
+      TO authenticated
+      USING (
+        ((select auth.jwt()) ->> 'role') = 'user' AND
+        user_id = (select auth.uid())
+      );
+      ```
+
+      ### Policy: Role Hierarchy (Admin > Manager > User)
+      ```sql
+      CREATE POLICY "role_hierarchy"
+      ON resources
+      FOR ALL
+      TO authenticated
+      USING (
+        CASE ((select auth.jwt()) ->> 'role')
+          WHEN 'admin' THEN true  -- Admin sees everything
+          WHEN 'manager' THEN org_id = ((select auth.jwt()) ->> 'org_id')::uuid
+          ELSE user_id = (select auth.uid())  -- User sees own only
+        END
+      );
+      ```
+
+      ## Pattern 9: Multi-Factor Authentication (AAL2)
+
+      **Use case**: Sensitive operations require MFA.
+
+      ```sql
+      CREATE POLICY "mfa_required_for_sensitive_ops"
+      ON sensitive_operations
+      FOR INSERT
+      TO authenticated
+      USING (
+        ((select auth.jwt()) ->> 'aal') = 'aal2'  -- Assurance Level 2 (MFA)
+      );
+      ```
+
+      **AAL levels**:
+      - `aal1` - Single factor (password only)
+      - `aal2` - Multi-factor (password + OTP/biometric)
+
+      ## Pattern 10: IP-Based Restrictions
+
+      **Use case**: Restrict admin operations to office IP.
+
+      ```sql
+      CREATE POLICY "admin_office_only"
+      ON admin_operations
+      FOR ALL
+      TO authenticated
+      USING (
+        ((select auth.jwt()) ->> 'role') = 'admin' AND
+        inet_client_addr() << '192.168.1.0/24'::inet  -- Office network
+      );
+      ```
+
+      **Note**: `inet_client_addr()` returns client IP.
+
+      ## Advanced Patterns Summary
+
+      | Pattern | Use Case | Complexity | Performance Impact |
+      |---------|----------|------------|-------------------|
+      | Time-based | Scheduled content | Low | Low (with index) |
+      | Hierarchical | Org > Team > User | Medium | Medium (needs indexes) |
+      | Role-based claims | RBAC | Low | Low (JWT cached) |
+      | AAL2 MFA | Sensitive ops | Low | None |
+      | IP restrictions | Office-only | Low | None |
+
+      **Best practices**:
+      - Prefer JWT claims over database lookups (faster)
+      - Always index columns used in policies
+      - Use security definer functions for complex checks
+      - Test with EXPLAIN ANALYZE
+      - Wrap auth functions with SELECT for caching
+    elicit: false
+
+  - id: testing
+    title: "RLS Testing Strategy"
+    instruction: |
+      How to test and validate RLS policies:
+      
+      ## Unit Tests
+      
+      Test individual policies with different auth contexts:
+      
+      ```sql
+      -- Test as user A
+      SET request.jwt.claims = '{"sub": "user-a-uuid"}';
+      SELECT * FROM table_name; -- Should only see user A's records
+      
+      -- Test as user B
+      SET request.jwt.claims = '{"sub": "user-b-uuid"}';
+      SELECT * FROM table_name; -- Should only see user B's records
+      ```
+      
+      ## Integration Tests
+      
+      Test with actual Supabase client:
+      
+      ```typescript
+      // Test authenticated access
+      const { data, error } = await supabase
+        .from('table_name')
+        .select('*');
+      
+      // Verify only authorized records returned
+      ```
+      
+      ## Security Audit
+      
+      Checklist for RLS validation:
+      - [ ] All tables with sensitive data have RLS enabled
+      - [ ] No accidental policy holes (test with unauthorized users)
+      - [ ] Service role usage is documented and justified
+      - [ ] Policies perform well (no slow queries)
+      - [ ] Cross-tenant data leakage tested
+      - [ ] Anonymous vs authenticated access verified
+      - [ ] Edge cases tested (null values, missing context)
+      
+      ## Automated Testing
+      
+      Script or framework for continuous validation.
+    elicit: false
+    
+  - id: migration
+    title: "RLS Migration Scripts"
+    instruction: |
+      Concrete SQL migration for implementing these policies:
+      
+      ## Migration: `YYYYMMDDHHMMSS_add_rls_policies.sql`
+      
+      ```sql
+      -- Enable RLS on tables
+      ALTER TABLE table1 ENABLE ROW LEVEL SECURITY;
+      ALTER TABLE table2 ENABLE ROW LEVEL SECURITY;
+      
+      -- Drop existing policies if re-running
+      DROP POLICY IF EXISTS "policy_name" ON table_name;
+      
+      -- Create policies
+      CREATE POLICY "policy_name_select"
+      ON table_name
+      FOR SELECT
+      TO authenticated
+      USING (auth.uid() = user_id);
+      
+      CREATE POLICY "policy_name_insert"
+      ON table_name
+      FOR INSERT
+      TO authenticated
+      WITH CHECK (auth.uid() = user_id);
+      
+      -- ... additional policies ...
+      
+      -- Create indexes to support policies
+      CREATE INDEX IF NOT EXISTS idx_table_user_id 
+      ON table_name(user_id);
+      
+      -- Grant permissions
+      GRANT SELECT, INSERT, UPDATE, DELETE ON table_name TO authenticated;
+      GRANT SELECT ON table_name TO anon;
+      ```
+      
+      ## Rollback Migration
+      
+      ```sql
+      -- Remove policies
+      DROP POLICY IF EXISTS "policy_name_select" ON table_name;
+      DROP POLICY IF EXISTS "policy_name_insert" ON table_name;
+      
+      -- Disable RLS
+      ALTER TABLE table_name DISABLE ROW LEVEL SECURITY;
+      ```
+    elicit: false
+    
+  - id: monitoring
+    title: "RLS Monitoring & Debugging"
+    instruction: |
+      How to monitor and debug RLS policies:
+      
+      ## Query Performance
+      
+      Identify slow queries caused by RLS:
+      
+      ```sql
+      -- Check query plans
+      EXPLAIN ANALYZE
+      SELECT * FROM table_name;
+      ```
+      
+      ## Policy Effectiveness
+      
+      Verify policies are being applied:
+      
+      ```sql
+      -- Check active policies
+      SELECT schemaname, tablename, policyname, permissive, roles, cmd, qual
+      FROM pg_policies
+      WHERE tablename = 'your_table';
+      ```
+      
+      ## Common Issues
+      
+      ### Issue: Policy not applying
+      - Check RLS is enabled on table
+      - Verify user role matches policy target
+      - Check auth context is set correctly
+      
+      ### Issue: Performance degradation
+      - Add indexes for policy columns
+      - Simplify policy expressions
+      - Consider denormalization
+      
+      ### Issue: Unexpected access
+      - Audit all policies on table
+      - Check for permissive vs restrictive policies
+      - Verify no service role leakage
+      
+      ## Logging
+      
+      Log policy violations or unexpected access patterns.
+    elicit: false
+    
+  - id: best-practices
+    title: "RLS Best Practices"
+    instruction: |
+      ## Design Principles
+      
+      1. **Start Restrictive**: Default deny, explicitly allow
+      2. **Minimize Policy Complexity**: Simpler policies are easier to audit
+      3. **Use Helper Functions**: Encapsulate complex logic
+      4. **Index Policy Columns**: Performance is critical
+      5. **Test Extensively**: Security bugs are costly
+      6. **Document Everything**: Future you will thank you
+      7. **Audit Regularly**: Policies drift over time
+      8. **Avoid Service Role**: Use it only when absolutely necessary
+      
+      ## Common Pitfalls
+      
+      - Forgetting to enable RLS on new tables
+      - Policy expressions with poor performance
+      - Not testing with actual user contexts
+      - Overly permissive catch-all policies
+      - Mixing USING and WITH CHECK incorrectly
+      - Not considering null values in policies
+      
+      ## Security Checklist
+      
+      - [ ] All sensitive tables have RLS enabled
+      - [ ] Policies tested with unauthorized users
+      - [ ] Anonymous access limited to public data only
+      - [ ] Service role usage is minimal and documented
+      - [ ] Policies use indexes for performance
+      - [ ] Multi-tenant isolation is verified
+      - [ ] Edge cases tested (nulls, empty results)
+      - [ ] Policies are documented and reviewed
+    elicit: false