@jmruthers/pace-core 0.5.76 → 0.5.78

package/docs/{database-schema-requirements.md → architecture/database-schema-requirements.md}

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Database Schema Requirements
 
 This document outlines the required database tables and schema for the `@jmruthers/pace-core` package to function correctly.

package/docs/architecture/rbac-security-architecture.md

@@ -0,0 +1,258 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
+# RBAC Security Architecture
+
+**Last Updated**: 2024
+
+## Overview
+
+This document describes the security architecture of the RBAC (Role-Based Access Control) system in `@jmruthers/pace-core`. The system is designed with **defense in depth** and **fail-secure** principles.
+
+## Architecture Principles
+
+### 1. Database-First Authority
+
+**Principle**: The database is the single source of truth for all permission decisions. Client-side metadata is never trusted.
+
+**Implementation**:
+- All permission checks query the database via secure RPC functions
+- Super admin status is checked via `rbac_global_roles` table, never from `user_metadata`
+- Organisation membership is validated via `rbac_organisation_roles` table
+- Event access is validated via `rbac_event_app_roles` table
+
+**Security Benefit**: Prevents privilege escalation by spoofing `user_metadata`.
+
+### 2. Organisation Context Enforcement
+
+**Principle**: All permission checks require organisation context and are scoped to that context.
+
+**Implementation**:
+- Every permission check includes `organisationId` as a required parameter
+- Database queries automatically filter by `organisationId` via RLS policies
+- Organisation membership is validated before any permission resolution
+
+**Security Benefit**: Prevents cross-tenant data leakage.
+
+### 3. Row-Level Security (RLS)
+
+**Principle**: Database-level policies enforce data isolation at the lowest level.
+
+**Implementation**:
+- All RBAC tables have RLS policies that restrict access to the user's organisation
+- Policies use `auth.uid()` for automatic context injection
+- Super admins bypass RLS via `auth.jwt() ->> 'global_role' = 'super_admin'`
+
+**Security Benefit**: Even if application logic fails, the database prevents unauthorized access.
+
+### 4. Fail-Secure Design
+
+**Principle**: On any error, ambiguity, or uncertainty, access is denied.
+
+**Implementation**:
+- Permission check errors return `false` (denied)
+- Missing organisation context returns `false` (denied)
+- Invalid input returns `false` (denied)
+- Database errors return `false` (denied)
+
+**Security Benefit**: Minimizes impact of bugs or vulnerabilities.
+
+### 5. Deny-Override-Allow Precedence
+
+**Principle**: Denials always override allows. If a user is explicitly denied a permission, no allow can override it.
+
+**Implementation**:
+```typescript
+// Permission resolution order:
+// 1. Check for explicit deny
+// 2. If no deny, check for allow
+// 3. If neither, deny by default
+```
+
+**Security Benefit**: Explicit deny is never accidentally overridden by a more permissive role.
+
+## Security Layers
+
+### Layer 1: Input Validation
+
+**Location**: `packages/core/src/rbac/security.ts`
+
+Validates and sanitizes all inputs before processing:
+- Permission string format: `operation:resource` (e.g., "read:users")
+- UUID format validation for all IDs
+- Organisation ID presence and format
+- Input sanitization to prevent injection attacks
+
+### Layer 2: Rate Limiting
+
+**Location**: `packages/core/src/rbac/security.ts`
+
+Prevents abuse with configurable rate limits:
+- Max requests per minute per user
+- Suspicious activity detection
+- Automatic blocking after threshold
+
+### Layer 3: Permission Resolution
+
+**Location**: `packages/core/src/rbac/engine.ts`
+
+Database-backed permission resolution:
+- Check explicit denies
+- Check explicit allows
+- Check role-based permissions
+- Check organisation membership
+- Check event access (if applicable)
+
+### Layer 4: Row-Level Security
+
+**Location**: Supabase database policies
+
+Database-level enforcement that applies even if application logic is bypassed:
+- Automatic context filtering by `organisationId`
+- User-specific data access via `auth.uid()`
+- Super admin bypass via JWT claims
+
+### Layer 5: Audit Logging
+
+**Location**: `packages/core/src/rbac/engine.ts`
+
+Comprehensive logging for security analysis:
+- All permission checks are logged
+- Denials are logged with full context
+- Rate limit violations are logged
+- Security events are logged with severity levels
+
+## Security Features
+
+### Super Admin Checks
+
+Super admin status is **never** checked from client-provided metadata. It is always queried from the database:
+
+```typescript
+// ✅ CORRECT: Database query
+const { data } = await supabase
+  .from('rbac_global_roles')
+  .select('role')
+  .eq('user_id', userId)
+  .eq('role', 'super_admin')
+  .limit(1);
+const isSuperAdmin = data && data.length > 0;
+
+// ❌ WRONG: Client metadata (spoofable)
+const isSuperAdmin = user.user_metadata?.globalRole === 'super_admin';
+```
+
+### Organisation Context Validation
+
+Every permission check validates organisation membership:
+
+```typescript
+// 1. Check organisation membership
+const membership = await supabase
+  .from('rbac_organisation_roles')
+  .select('organisation_id, role, status')
+  .eq('user_id', userId)
+  .eq('organisation_id', organisationId)
+  .eq('status', 'active')
+  .single();
+
+if (!membership) {
+  return false; // Fail-secure: deny if not a member
+}
+```
+
+### Permission Cache Security
+
+Caching improves performance but must be secure:
+- Cache keys include `userId` and `organisationId` to prevent cross-user leaks
+- Cache is invalidated on role changes via Supabase realtime
+- Cache TTL is short (60 seconds) to limit stale data exposure
+
+## Threat Model
+
+### Threat 1: Privilege Escalation
+
+**Attack**: User modifies client-side `user_metadata` to claim super admin role.
+
+**Mitigation**: Super admin status is always checked via database query, never from metadata.
+
+**Status**: ✅ Mitigated
+
+### Threat 2: Cross-Organisation Data Leakage
+
+**Attack**: User requests data with a different `organisationId` than their membership.
+
+**Mitigation**: RLS policies and application-level checks ensure users can only access their organisation's data.
+
+**Status**: ✅ Mitigated
+
+### Threat 3: Cache-Based Attacks
+
+**Attack**: Malicious user exploits cache to access another user's permissions.
+
+**Mitigation**: Cache keys include `userId`, preventing cross-user access. Cache invalidation on changes.
+
+**Status**: ✅ Mitigated
+
+### Threat 4: Race Conditions
+
+**Attack**: Exploiting concurrent permission checks to bypass security.
+
+**Mitigation**: Rate limiting and atomic database transactions prevent race conditions.
+
+**Status**: ✅ Mitigated
+
+### Threat 5: Injection Attacks
+
+**Attack**: Injecting malicious data into permission checks.
+
+**Mitigation**: Input validation and sanitization, parameterized queries only.
+
+**Status**: ✅ Mitigated
+
+## Security Best Practices
+
+### For Developers
+
+1. **Always provide organisation context**: Never call permission checks without `organisationId`
+2. **Use `useRBAC()` hook**: This hook enforces security by default
+3. **Never trust client data**: Always re-validate on the server
+4. **Use `PagePermissionGuard`**: Declarative permission checks reduce bugs
+5. **Log security events**: Use audit logging for suspicious activity
+
+### For Security Reviewers
+
+1. **Review RLS policies**: Ensure all tables have proper RLS policies
+2. **Check cache invalidation**: Verify cache clears on all role changes
+3. **Audit super admin checks**: Ensure no code path uses `user_metadata` for super admin
+4. **Test fail-secure behavior**: Verify errors result in denial, not approval
+5. **Review rate limiting**: Ensure limits are appropriate for the application
+
+## Compliance
+
+### GDPR
+
+- ✅ Data access is logged with user context
+- ✅ Organisation data is isolated via RLS
+- ✅ Right to be forgotten is supported via user deletion
+
+### SOC 2
+
+- ✅ Access control is enforced at multiple layers
+- ✅ Audit logging is comprehensive
+- ✅ Changes to permissions are tracked
+
+### ISO 27001
+
+- ✅ Defense in depth architecture
+- ✅ Fail-secure design
+- ✅ Principle of least privilege
+
+## References
+
+- [RBAC Implementation](rbac-implementation.md)
+- [RLS Policies](../migration/rls-policies.md)
+- [Security Testing](../testing/security-testing.md)

package/docs/architecture/services.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Service Architecture Documentation
 
 ## Overview
@@ -11,11 +17,13 @@ The pace-core library now uses a service-based architecture that follows SOLID p
 The service layer contains pure TypeScript classes that handle business logic without any React dependencies:
 
 - **AuthService**: Authentication operations (sign in, sign out, session management)
-- **RBACService**: Role and permission management
+- **RBACService**: Role and permission management ⚠️ **DEPRECATED** - Use RBAC Engine instead
 - **OrganisationService**: Organisation management and selection
 - **EventService**: Event management and selection
 - **InactivityService**: User inactivity tracking
 
+> **⚠️ Note**: RBACService is deprecated in favor of the new RBAC system. Use `useRBAC()` from `@jmruthers/pace-core/rbac` instead.
+
 ### Provider Layer (React Context)
 
 Each service has its own React provider that:

package/docs/best-practices/README.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Best Practices
 
 > **🎯 Build Better Apps** | [Security](#security) | [Performance](#performance) | [Testing](#testing) | [Deployment](#deployment)

package/docs/best-practices/accessibility.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Best Practices: Accessibility
 
 > **📚 Best Practices**: Accessibility & WCAG Compliance | [← Back](./README.md) | [Implementation Guides](../implementation-guides/README.md)

package/docs/{common-patterns.md → best-practices/common-patterns.md}

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Common Patterns & Best Practices
 
 > **📚 Common Patterns** | [← Back to Documentation](./README.md) | [Quick Start](./getting-started/quick-start.md) | [API Reference](./api-reference/components.md)

package/docs/best-practices/deployment.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Deployment Best Practices
 
 Proper deployment is crucial for production success. This guide provides comprehensive deployment strategies and best practices for `@jmruthers/pace-core` applications.