@jmruthers/pace-core 0.6.8 → 0.6.10

package/docs/standards/6-security-rbac-standards.md

@@ -24,8 +24,8 @@ All helper functions used in RLS policies **MUST** have these attributes:
 | Requirement | Why | Example |
 |------------|-----|---------|
 | `STABLE` | Prevents re-evaluation for each row | `STABLE` |
-| `SECURITY DEFINER` | Bypass RLS to avoid recursion | `SECURITY DEFINER` |
-| `SET search_path TO 'public'` | Prevent search path injection | `SET search_path TO 'public'` |
+| `SECURITY DEFINER` | Bypass RLS to avoid circular dependencies when querying RLS-protected tables | `SECURITY DEFINER` |
+| `SET search_path TO 'public'` | **MANDATORY** - Prevents search path hijacking attacks | `SET search_path TO public` |
 | No inline `auth.uid()` | Causes InitPlan nodes, severe performance degradation | Use helper function instead |
 
 ### Helper Function Template
@@ -34,19 +34,31 @@ All helper functions used in RLS policies **MUST** have these attributes:
 CREATE OR REPLACE FUNCTION function_name(parameters)
 RETURNS return_type
 LANGUAGE plpgsql
-STABLE                    -- ✅ Required
-SECURITY DEFINER          -- ✅ Required
-SET search_path TO public -- ✅ Required
+STABLE                    -- ✅ Required for performance
+SECURITY DEFINER          -- ✅ Required if querying RLS-protected tables
+SET search_path TO public -- ✅ MANDATORY - Prevents search path hijacking
 AS $$
 DECLARE
   -- Declarations
 BEGIN
   -- Function body
+  -- Always schema-qualify table/function references (e.g., public.table_name)
   RETURN result;
 END;
 $$;
+
+-- ✅ Document why SECURITY DEFINER is needed
+COMMENT ON FUNCTION function_name(parameters) IS 
+  'Purpose description. SECURITY DEFINER required because this function queries rbac_organisation_roles which has RLS policies. STABLE for RLS policy performance.';
 ```
 
+**Security Checklist:**
+- [ ] `SET search_path TO public` is present (MANDATORY)
+- [ ] All table/function references are schema-qualified (e.g., `public.table_name`)
+- [ ] Function is marked `STABLE` or `IMMUTABLE` when possible
+- [ ] Function ownership uses least-privilege role (not superuser unless necessary)
+- [ ] COMMENT documents why SECURITY DEFINER is needed
+
 ### Forbidden Patterns
 
 **❌ NEVER use these patterns in RLS policies:**
@@ -99,6 +111,206 @@ FOR SELECT USING (
 );
 ```
 
+## SECURITY DEFINER Requirements & Security
+
+### When SECURITY DEFINER is Necessary
+
+**SECURITY DEFINER is REQUIRED when:**
+- Helper function queries tables with RLS policies (e.g., `rbac_organisation_roles`, `rbac_global_roles`)
+- Function needs to bypass RLS to avoid circular dependencies
+- Function performs administrative operations requiring elevated privileges
+
+**Why it's needed:**
+When an RLS policy calls a helper function that queries RLS-protected tables, without SECURITY DEFINER:
+1. RLS policy calls helper function
+2. Helper function queries RLS-protected table (e.g., `rbac_organisation_roles`)
+3. That query triggers RLS again → infinite recursion or circular dependency
+
+**Example:**
+```sql
+-- ✅ CORRECT: SECURITY DEFINER required because function queries rbac_organisation_roles
+CREATE OR REPLACE FUNCTION check_user_organisation_access(p_organisation_id UUID)
+RETURNS boolean
+LANGUAGE plpgsql
+STABLE
+SECURITY DEFINER          -- ✅ Required: queries rbac_organisation_roles (has RLS)
+SET search_path TO public -- ✅ MANDATORY: prevents search path hijacking
+AS $$
+BEGIN
+  -- This queries rbac_organisation_roles which has RLS policies
+  -- Without SECURITY DEFINER, this would trigger RLS again → circular dependency
+  RETURN EXISTS (
+    SELECT 1 FROM public.rbac_organisation_roles  -- ✅ Schema-qualified
+    WHERE user_id = auth.uid()
+    AND organisation_id = p_organisation_id
+  );
+END;
+$$;
+```
+
+**SECURITY DEFINER is NOT necessary when:**
+- Function only performs pure computation (no table queries)
+- Function only queries tables without RLS policies
+- Function doesn't need to bypass RLS
+
+**Example:**
+```sql
+-- ✅ CORRECT: No SECURITY DEFINER needed (pure computation, no RLS-protected queries)
+CREATE OR REPLACE FUNCTION calculate_total(p_amount NUMERIC, p_tax_rate NUMERIC)
+RETURNS NUMERIC
+LANGUAGE plpgsql
+STABLE  -- ✅ STABLE for performance, but no SECURITY DEFINER needed
+AS $$
+BEGIN
+  RETURN p_amount * (1 + p_tax_rate);
+END;
+$$;
+```
+
+### Security Risks & Mitigations
+
+**Security Risks:**
+1. **Search path hijacking** - If `search_path` includes untrusted schemas, malicious objects could be called
+2. **Privilege escalation** - Functions run with owner's privileges, not caller's
+3. **Unqualified object references** - Could resolve to objects in wrong schemas
+4. **Performance implications** - Can affect query optimization
+
+**Required Mitigations (MANDATORY):**
+
+| Mitigation | Requirement | Why |
+|------------|-------------|-----|
+| `SET search_path TO public` | **MANDATORY** | Prevents search path hijacking attacks |
+| Schema-qualify references | **MANDATORY** | Ensures objects resolve to correct schemas |
+| `STABLE` or `IMMUTABLE` | **REQUIRED** | Helps with query optimization and performance |
+| Least-privilege ownership | **RECOMMENDED** | Functions should be owned by appropriate roles (not superuser unless necessary) |
+| Document rationale | **REQUIRED** | COMMENT must explain why SECURITY DEFINER is needed |
+
+**Example with all mitigations:**
+```sql
+-- ✅ CORRECT: All security mitigations in place
+CREATE OR REPLACE FUNCTION check_user_organisation_access(p_organisation_id UUID)
+RETURNS boolean
+LANGUAGE plpgsql
+STABLE                    -- ✅ Performance optimization
+SECURITY DEFINER          -- ✅ Required: queries RLS-protected tables
+SET search_path TO public -- ✅ MANDATORY: prevents search path hijacking
+AS $$
+BEGIN
+  -- ✅ Schema-qualified references
+  RETURN EXISTS (
+    SELECT 1 FROM public.rbac_organisation_roles
+    WHERE user_id = auth.uid()
+    AND organisation_id = p_organisation_id
+  );
+END;
+$$;
+
+-- ✅ Document why SECURITY DEFINER is needed
+COMMENT ON FUNCTION check_user_organisation_access(UUID) IS 
+  'Checks if current user has access to organisation. SECURITY DEFINER required because function queries public.rbac_organisation_roles which has RLS policies. Without SECURITY DEFINER, this would create circular RLS dependency. STABLE for RLS policy performance. SET search_path TO public prevents search path hijacking.';
+```
+
+### Decision Tree: When to Use SECURITY DEFINER
+
+```
+1. Does this helper function query tables with RLS policies?
+   ├─ YES → SECURITY DEFINER required (to avoid circular RLS)
+   │         └─ Continue to step 3
+   └─ NO → Continue to step 2
+
+2. Does this function need elevated privileges for administrative operations?
+   ├─ YES → SECURITY DEFINER may be appropriate (document why)
+   │         └─ Continue to step 3
+   └─ NO → SECURITY DEFINER not needed
+            └─ Use STABLE or IMMUTABLE only
+
+3. If using SECURITY DEFINER, verify all security requirements:
+   ├─ SET search_path TO public (or specific schema list) ✅ MANDATORY
+   ├─ Schema-qualify all table/function references ✅ MANDATORY
+   ├─ Use STABLE/IMMUTABLE when possible ✅ REQUIRED
+   ├─ Owned by appropriate role (not superuser unless needed) ✅ RECOMMENDED
+   └─ Document why SECURITY DEFINER is needed in COMMENT ✅ REQUIRED
+```
+
+### Security Anti-Patterns
+
+**❌ NEVER use these patterns:**
+
+```sql
+-- ❌ BAD: Missing SET search_path (security risk)
+CREATE OR REPLACE FUNCTION bad_function()
+RETURNS boolean
+LANGUAGE plpgsql
+STABLE
+SECURITY DEFINER  -- Missing SET search_path TO public!
+AS $$
+BEGIN
+  RETURN EXISTS (SELECT 1 FROM rbac_organisation_roles);  -- Unqualified reference
+END;
+$$;
+
+-- ❌ BAD: Unqualified table reference (security risk)
+CREATE OR REPLACE FUNCTION bad_function()
+RETURNS boolean
+LANGUAGE plpgsql
+STABLE
+SECURITY DEFINER
+SET search_path TO public
+AS $$
+BEGIN
+  RETURN EXISTS (SELECT 1 FROM rbac_organisation_roles);  -- Should be public.rbac_organisation_roles
+END;
+$$;
+
+-- ❌ BAD: SECURITY DEFINER without justification
+CREATE OR REPLACE FUNCTION pure_computation(x NUMERIC)
+RETURNS NUMERIC
+LANGUAGE plpgsql
+STABLE
+SECURITY DEFINER  -- Not needed! Function doesn't query RLS-protected tables
+AS $$
+BEGIN
+  RETURN x * 2;  -- Pure computation, no table queries
+END;
+$$;
+```
+
+**✅ CORRECT patterns:**
+
+```sql
+-- ✅ GOOD: All security requirements met
+CREATE OR REPLACE FUNCTION check_user_organisation_access(p_organisation_id UUID)
+RETURNS boolean
+LANGUAGE plpgsql
+STABLE
+SECURITY DEFINER          -- ✅ Required: queries RLS-protected tables
+SET search_path TO public -- ✅ MANDATORY: prevents search path hijacking
+AS $$
+BEGIN
+  -- ✅ Schema-qualified reference
+  RETURN EXISTS (
+    SELECT 1 FROM public.rbac_organisation_roles
+    WHERE user_id = auth.uid()
+    AND organisation_id = p_organisation_id
+  );
+END;
+$$;
+
+COMMENT ON FUNCTION check_user_organisation_access(UUID) IS 
+  'SECURITY DEFINER required: queries public.rbac_organisation_roles (has RLS). Without it, circular RLS dependency would occur.';
+
+-- ✅ GOOD: No SECURITY DEFINER needed (pure computation)
+CREATE OR REPLACE FUNCTION calculate_total(p_amount NUMERIC, p_tax_rate NUMERIC)
+RETURNS NUMERIC
+LANGUAGE plpgsql
+STABLE  -- ✅ STABLE for performance, but no SECURITY DEFINER needed
+AS $$
+BEGIN
+  RETURN p_amount * (1 + p_tax_rate);  -- No table queries
+END;
+$$;
+```
+
 ## Helper Selection Quick Guide
 
 | Scenario | Helper(s) to use | Notes |
@@ -112,10 +324,11 @@ FOR SELECT USING (
 
 ## RLS Helper Requirements (enforced)
 
-- Helper functions **must** be `STABLE`, `SECURITY DEFINER`, and `SET search_path TO public`.
+- Helper functions **must** be `STABLE`, `SECURITY DEFINER` (when querying RLS-protected tables), and `SET search_path TO public` (MANDATORY for SECURITY DEFINER functions).
 - **Never** inline `auth.uid()`, `auth.role()`, or `current_setting()` inside policies.
 - Use `get_app_id()` for app UUIDs (do not hardcode UUIDs or call legacy getters).
 - Avoid subqueries inside policies; move lookups into helpers.
+- **Security**: All SECURITY DEFINER functions must schema-qualify table/function references and document why SECURITY DEFINER is needed.
 
 ## Standard Helper Functions
 
@@ -818,6 +1031,7 @@ export async function checkPermission(userId: string, permission: string) {
 - Use safe, user-friendly error messaging.
 - Prefer pace-core security helpers and secure clients (`useSecureSupabase`, RBAC helpers) over custom implementations.
 - Monitor RLS performance (avoid subqueries/InitPlan); keep helpers `STABLE SECURITY DEFINER` with `SET search_path TO public`.
+- **SECURITY DEFINER functions**: Must schema-qualify all references, use `SET search_path TO public`, and document why SECURITY DEFINER is needed.
 - **Edge Functions MUST use pace-core `isPermitted()` API - no exceptions allowed.**
 
 ### Common Pitfalls to Avoid
@@ -902,7 +1116,8 @@ Tables are assigned to specific apps for RBAC permission checking:
 - [ ] Policy coverage: All tables (except mint_*) have RLS enabled and policies
 - [ ] Performance: Queries complete in < 1 second
 - [ ] Security: Cross-organisation access is blocked
-- [ ] Helper functions: All are STABLE SECURITY DEFINER
+- [ ] Helper functions: All are STABLE, SECURITY DEFINER (when needed), with `SET search_path TO public`
+- [ ] Security: All SECURITY DEFINER functions schema-qualify references and document rationale
 
 ## Maintenance
 

package/docs/standards/7-api-tech-stack-standards.md

@@ -322,8 +322,8 @@ CREATE OR REPLACE FUNCTION data_events_list(p_organisation_id UUID)
 RETURNS TABLE (...)
 LANGUAGE plpgsql
 STABLE
-SECURITY DEFINER
-SET search_path TO public
+SECURITY DEFINER          -- ✅ Required: queries RLS-protected tables or needs elevated privileges
+SET search_path TO public -- ✅ MANDATORY: prevents search path hijacking
 AS $$
 BEGIN
   -- Check organisation access
@@ -331,11 +331,99 @@ BEGIN
     RAISE EXCEPTION 'Access denied';
   END IF;
   
+  -- ✅ Schema-qualified reference
   RETURN QUERY
-  SELECT * FROM events
+  SELECT * FROM public.events
   WHERE organisation_id = p_organisation_id;
 END;
 $$;
+
+-- ✅ Document why SECURITY DEFINER is needed
+COMMENT ON FUNCTION data_events_list(UUID) IS 
+  'Lists events for an organisation. SECURITY DEFINER required because function queries RLS-protected tables via check_user_organisation_access(). STABLE for read operation performance. SET search_path TO public prevents search path hijacking.';
+```
+
+### SECURITY DEFINER Security Requirements for RPC Functions
+
+**RPC functions that use SECURITY DEFINER MUST follow these security requirements:**
+
+| Requirement | Why | Example |
+|------------|-----|---------|
+| `SET search_path TO public` | **MANDATORY** - Prevents search path hijacking attacks | `SET search_path TO public` |
+| Schema-qualify references | **MANDATORY** - Ensures objects resolve to correct schemas | `public.events` not `events` |
+| `STABLE` for read operations | **REQUIRED** - Helps with query optimization | `STABLE` |
+| Document rationale | **REQUIRED** - COMMENT must explain why SECURITY DEFINER is needed | See COMMENT example above |
+| Least-privilege ownership | **RECOMMENDED** - Functions should be owned by appropriate roles | Not superuser unless necessary |
+
+**When SECURITY DEFINER is needed for RPC functions:**
+- Function queries RLS-protected tables (e.g., `rbac_organisation_roles`, `rbac_global_roles`)
+- Function needs to bypass RLS to avoid circular dependencies
+- Function performs administrative operations requiring elevated privileges
+
+**Security Checklist for RPC Functions with SECURITY DEFINER:**
+- [ ] `SET search_path TO public` is present (MANDATORY)
+- [ ] All table/function references are schema-qualified (e.g., `public.table_name`)
+- [ ] Function is marked `STABLE` for read operations
+- [ ] Function ownership uses least-privilege role (not superuser unless necessary)
+- [ ] COMMENT documents why SECURITY DEFINER is needed
+
+**Example with all security requirements:**
+
+```sql
+-- ✅ CORRECT: All security requirements met
+CREATE OR REPLACE FUNCTION data_events_list(p_organisation_id UUID)
+RETURNS TABLE (id UUID, name TEXT, date TIMESTAMPTZ)
+LANGUAGE plpgsql
+STABLE                    -- ✅ Performance optimization
+SECURITY DEFINER          -- ✅ Required: queries RLS-protected tables
+SET search_path TO public -- ✅ MANDATORY: prevents search path hijacking
+AS $$
+BEGIN
+  -- ✅ Schema-qualified reference
+  IF NOT public.check_user_organisation_access(p_organisation_id) THEN
+    RAISE EXCEPTION 'Access denied';
+  END IF;
+  
+  -- ✅ Schema-qualified reference
+  RETURN QUERY
+  SELECT e.id, e.name, e.date
+  FROM public.events e
+  WHERE e.organisation_id = p_organisation_id;
+END;
+$$;
+
+-- ✅ Document why SECURITY DEFINER is needed
+COMMENT ON FUNCTION data_events_list(UUID) IS 
+  'Lists events for an organisation. SECURITY DEFINER required because function queries public.rbac_organisation_roles (via check_user_organisation_access) which has RLS policies. Without SECURITY DEFINER, this would create circular RLS dependency. STABLE for read operation performance. SET search_path TO public prevents search path hijacking.';
+```
+
+**Security Anti-Patterns:**
+
+```sql
+-- ❌ BAD: Missing SET search_path (security risk)
+CREATE OR REPLACE FUNCTION bad_rpc()
+RETURNS TABLE (...)
+LANGUAGE plpgsql
+STABLE
+SECURITY DEFINER  -- Missing SET search_path TO public!
+AS $$
+BEGIN
+  RETURN QUERY SELECT * FROM events;
+END;
+$$;
+
+-- ❌ BAD: Unqualified reference (security risk)
+CREATE OR REPLACE FUNCTION bad_rpc()
+RETURNS TABLE (...)
+LANGUAGE plpgsql
+STABLE
+SECURITY DEFINER
+SET search_path TO public
+AS $$
+BEGIN
+  RETURN QUERY SELECT * FROM events;  -- Should be public.events
+END;
+$$;
 ```
 
 **Real-World Example: Complex RPC with Multiple Security Checks**

package/docs/testing/README.md

@@ -10,6 +10,14 @@ This guide covers testing strategies, patterns, and best practices for applicati
 
 > 📖 **For comprehensive testing standards and patterns**, see the [Testing Standard](../standards/testing-standard.md) - the authoritative guide for writing world-class tests in pace-core.
 
+## Quick Start
+
+**New to testing with pace-core?** Start here:
+
+1. **[Test Infrastructure Setup Guide](./test-infrastructure-setup.md)** - Complete guide to set up Vitest, coverage reporting, and test configuration in your consuming app. After following this guide, you'll be able to run `npm run test:coverage` and receive comprehensive coverage reports matching pace-core's setup.
+
+2. **This guide** - Learn testing patterns, strategies, and best practices for writing tests.
+
 ## Overview
 
 PACE Core provides comprehensive testing support with:
@@ -23,6 +31,8 @@ PACE Core provides comprehensive testing support with:
 
 ## Testing Setup
 
+> 💡 **First time setting up tests?** See the [Test Infrastructure Setup Guide](./test-infrastructure-setup.md) for complete configuration instructions.
+
 ### 1. Basic Testing Configuration
 
 ```tsx