@jmruthers/pace-core 0.6.9 → 0.6.10

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