@jmruthers/pace-core 0.6.6 → 0.6.8

package/docs/standards/{08-markup-quality.md → 5-styling-standards.md}

@@ -1,6 +1,6 @@
-# Styling Standard for Consuming Apps
+# Styling Standards
 
-**🤖 Cursor Rule**: See [08-markup-quality.mdc](../../cursor-rules/08-markup-quality.mdc) for AI-optimized directives that automatically enforce markup quality (this rule is ALWAYS APPLIED).
+**🤖 Cursor Rule**: See [05-styling.mdc](../../cursor-rules/05-styling.mdc) for AI-optimized directives that automatically enforce markup quality (this rule is ALWAYS APPLIED).
 
 ## Purpose
 
@@ -11,7 +11,8 @@ This standard defines the **REQUIRED** configuration for consuming apps to prope
 - ✅ Tailwind v4 content scanning works properly
 - ✅ Consistent styling across all PACE suite applications
 
-## Component & Markup Guidance (aligns with Cursor rules)
+## Component & Markup Guidance
+
 - Components should be stateless when possible, fully typed, and accessibility-first.
 - Prefer semantic HTML elements; use `<div>` only when no semantic element fits or when required by a library.
 - Use React Fragments for grouping instead of wrapper nodes; keep markup minimal and avoid wrappers solely for styling.
@@ -20,12 +21,14 @@ This standard defines the **REQUIRED** configuration for consuming apps to prope
 - Apply layout utilities to existing semantic parents or pace-core layout components.
 
 ### Component Principles
+
 - Stateless when possible; keep surface area small and composable.
 - Accessible by default with correct roles, keyboard support, and visible focus.
 - UI primitives only; never add domain logic or data fetching inside components.
 - Support controlled + uncontrolled usage where applicable.
 
 ### Testing Expectations
+
 - Use React Testing Library + userEvent.
 - Test key interactions; snapshots only for simple components.
 - Keep components small—move non-UI logic to hooks/services.
@@ -185,7 +188,7 @@ import '@jmruthers/pace-core/styles/core.css';  /* ❌ WRONG */
 
 **All shades (50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950) plus `-raw` are REQUIRED.**
 
-## Required Import in Entry Point (and avoiding duplicate imports)
+## Required Import in Entry Point
 
 **MUST** import `app.css` in your entry point (e.g., `src/main.tsx`):
 
@@ -209,7 +212,7 @@ When you have additional entry points (storybook, tests, preview servers):
 - If you need raw styles for non-React tooling, **import `@jmruthers/pace-core/styles/core.css` once** in that tool-specific stylesheet, never alongside `app.css`.
 - If you are unsure, default to a single `app.css` import and remove any extra `core.css` imports.
 
-## Styling & Markup Rules (aligns with Cursor)
+## Styling & Markup Rules
 
 - **No inline styles**: Do not use `style={{ ... }}` except when a third-party library strictly requires it. Prefer pace-core variants + Tailwind utilities.
 - **Use theme tokens only**: Avoid arbitrary Tailwind colors (`text-gray-500`, `bg-red-500`) and bracket syntax (`bg-[oklch(...)]`). Use `main-*`, `sec-*`, `acc-*`, or semantic tokens like `text-foreground`.
@@ -334,12 +337,12 @@ import './app.css';
 
 ## Related Documentation
 
-- [PACE Core Styling Guide](../styles/README.md) - Complete styling documentation
-- [Project Structure Guide](./00-project-structure-guide.md) - File organization standards
-- [Component Standard](./03-component-standard.md) - Component development standards
+- [Standards Overview](./0-standards-overview.md) - Standards system overview
+- [Project Structure](./2-project-structure-standards.md) - File organization standards
+- [Architecture](./3-architecture-standards.md) - Component development standards
 
 ---
 
 **Last Updated:** 2025-01-28  
-**Version:** 1.0.0  
+**Version:** 2.0.0  
 **Applies to:** All consuming apps using `@jmruthers/pace-core`

package/docs/standards/{09-rbac-compliance.md → 6-security-rbac-standards.md}

@@ -1,17 +1,13 @@
----
-lastUpdated: 2025-01-28T00:00:00+11:00
-version: 0.5.182
-reviewedBy: rls-audit-and-fixes
----
-
-# RBAC and RLS Standard
+# Security & RBAC Standards
 
-**🤖 Cursor Rule**: See [09-rbac-compliance.mdc](../../cursor-rules/09-rbac-compliance.mdc) for AI-optimized directives that automatically enforce RBAC contract compliance (ESLint-enforced).
+**🤖 Cursor Rule**: See [06-security-rbac.mdc](../../cursor-rules/06-security-rbac.mdc) for AI-optimized directives that automatically enforce RBAC contract compliance (ESLint-enforced).
 
 ## Purpose
 
 Define standards for Row-Level Security (RLS) policies and Role-Based Access Control (RBAC) integration to ensure security, performance, and maintainability.
 
+**Note:** General performance optimization patterns (React, caching, bundle size) are covered in [Operations Standards](./9-operations-standards.md). This document focuses on RLS-specific performance requirements.
+
 ## Principles
 
 - **Performance First**: All RLS policies must use optimized helper functions
@@ -426,6 +422,52 @@ USING (
 
 **Example:** `file_references`, `pace_address` (can be either organisation or user-scoped)
 
+**Real-World Example: File References Table**
+
+```sql
+-- Real-world example: file_references table supports both organisation and user-scoped files
+CREATE POLICY "rbac_select_file_references" ON file_references
+FOR SELECT
+USING (
+  -- Service role can access all files (for system operations)
+  is_service_role()
+  OR
+  -- Organisation-scoped files (shared within organisation)
+  (
+    organisation_id IS NOT NULL
+    AND is_authenticated_user()
+    AND (
+      is_super_admin(safe_get_user_id_for_rls())
+      OR check_user_organisation_access(organisation_id)
+    )
+  )
+  OR
+  -- User-scoped files (personal files)
+  (
+    organisation_id IS NULL
+    AND is_authenticated_user()
+    AND get_effective_user_id() = user_id
+  )
+);
+
+-- INSERT policy: Users can upload files to their organisation or personal storage
+CREATE POLICY "rbac_insert_file_references" ON file_references
+FOR INSERT TO authenticated
+WITH CHECK (
+  -- Organisation-scoped: Must have organisation access
+  (
+    organisation_id IS NOT NULL
+    AND check_user_organisation_access(organisation_id)
+  )
+  OR
+  -- User-scoped: Must be own user_id
+  (
+    organisation_id IS NULL
+    AND get_effective_user_id() = user_id
+  )
+);
+```
+
 ### Service Role Policy
 
 **Use Case:** Allow service_role to bypass RLS for system operations.
@@ -476,6 +518,66 @@ USING (
 
 **Example:** `event` (public events), `forms` (published forms)
 
+**Real-World Example: Public Event Registration**
+
+```sql
+-- Real-world example: Events table with public registration
+-- Public users can view and register for public events
+-- Authenticated users can view all events in their organisation
+
+-- Public access: Anonymous users can view public events
+CREATE POLICY "public_select_events" ON events
+FOR SELECT TO anon
+USING (
+  is_public = true
+  AND organisation_id IS NOT NULL
+  AND status = 'published'
+);
+
+-- Authenticated access: Users can view events in their organisation
+CREATE POLICY "rbac_select_events" ON events
+FOR SELECT TO authenticated
+USING (
+  -- Public events (anyone can see)
+  (is_public = true AND organisation_id IS NOT NULL)
+  OR
+  -- Organisation events (members can see)
+  (
+    organisation_id IS NOT NULL
+    AND (
+      is_super_admin(safe_get_user_id_for_rls())
+      OR check_user_organisation_access(organisation_id)
+    )
+  )
+);
+
+-- Public registration: Anonymous users can create registrations for public events
+CREATE POLICY "public_insert_event_registrations" ON event_registrations
+FOR INSERT TO anon
+WITH CHECK (
+  -- Only for public events
+  event_id IN (
+    SELECT id FROM events
+    WHERE is_public = true AND status = 'published'
+  )
+);
+
+-- Authenticated registration: Users can register for events in their organisation
+CREATE POLICY "rbac_insert_event_registrations" ON event_registrations
+FOR INSERT TO authenticated
+WITH CHECK (
+  -- Must have access to the event's organisation
+  event_id IN (
+    SELECT id FROM events
+    WHERE organisation_id IS NOT NULL
+    AND (
+      is_super_admin(safe_get_user_id_for_rls())
+      OR check_user_organisation_access(organisation_id)
+    )
+  )
+);
+```
+
 **Combined Public + Authenticated Pattern:**
 ```sql
 -- Public access
@@ -494,7 +596,7 @@ USING (
   OR (
     organisation_id IS NOT NULL
     AND (
-      is_super_admin()
+      is_super_admin(safe_get_user_id_for_rls())
       OR check_user_organisation_access(organisation_id)
     )
   )
@@ -519,7 +621,7 @@ USING (
     is_authenticated_user()
     AND organisation_id IS NOT NULL
     AND (
-      is_super_admin()
+      is_super_admin(safe_get_user_id_for_rls())
       OR check_user_organisation_access(organisation_id)
     )
   )
@@ -710,7 +812,8 @@ export async function checkPermission(userId: string, permission: string) {
 5. **MUST NOT** create custom RBAC helper functions
 6. **MUST NOT** call `rbac_check_permission_simplified` RPC directly
 
-## Security Baseline (aligns with Security Standard)
+## Security Baseline
+
 - Never bypass RLS; validate all inputs and sanitize logs (no tokens/PII).
 - Use safe, user-friendly error messaging.
 - Prefer pace-core security helpers and secure clients (`useSecureSupabase`, RBAC helpers) over custom implementations.
@@ -779,17 +882,17 @@ Tables are assigned to specific apps for RBAC permission checking:
    supabase advisors security
    ```
 
-3. **Run Database Tests**:
+2. **Run Database Tests**:
    ```bash
    timeout 120 npm run test:db
    ```
 
-4. **Run Application Tests**:
+3. **Run Application Tests**:
    ```bash
    timeout 60 npm run test
    ```
 
-5. **Verify Performance**:
+4. **Verify Performance**:
    - Use EXPLAIN ANALYZE to verify no InitPlan nodes
    - Verify queries complete in < 1 second
    - Check Supabase Advisors show zero `auth_rls_initplan` warnings
@@ -868,7 +971,12 @@ date +"%Y%m%d%H%M%S"
 
 ## Related Documentation
 
-- Security baseline (see section above)
-- [RLS Policy Remediation Plan](../troubleshooting/rls-policy-remediation-plan-combined.md)
-- [Database Unhealthiness Diagnosis](../troubleshooting/database-unhealthiness-diagnosis.md)
-- [RBAC-RLS Integration Guide](../rbac/rbac-rls-integration.md)
+- [Standards Overview](./0-standards-overview.md) - Standards system overview
+- [pace-core Compliance](./1-pace-core-compliance-standards.md) - Secure Supabase client usage
+- [Operations](./9-operations-standards.md) - General performance patterns (React, caching, etc.)
+
+---
+
+**Last Updated:** 2025-01-28  
+**Version:** 2.0.0  
+**Applies to:** All pace-core and consuming apps