@jmruthers/pace-core 0.5.75 → 0.5.77

package/docs/api-reference/utilities.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Utilities API Reference
 
 This section provides detailed documentation for all utility functions in `@jmruthers/pace-core`.
@@ -378,6 +384,207 @@ import { sanitizeFormData } from '@jmruthers/pace-core';
 const sanitizedData = sanitizeFormData(formData);
 ```
 
+## Utility Functions
+
+### cn (ClassName Merge)
+
+Utility for merging Tailwind CSS classes with conflict resolution.
+
+```typescript
+function cn(...inputs: ClassValue[]): string;
+```
+
+#### Usage
+
+```typescript
+import { cn } from '@jmruthers/pace-core';
+
+// Merge classes
+cn('px-4 py-2', 'bg-main-500', 'hover:bg-main-600')
+
+// Conditional classes
+cn('base-class', isActive && 'active-class', isDisabled && 'disabled-class')
+
+// Override conflicts (last one wins)
+cn('px-4', 'px-2') // Returns 'px-2'
+```
+
+### formatCurrency
+
+Format a number as currency.
+
+```typescript
+function formatCurrency(
+  value: number, 
+  currencyCode?: string, 
+  locale?: string
+): string;
+```
+
+#### Usage
+
+```typescript
+import { formatCurrency } from '@jmruthers/pace-core';
+
+formatCurrency(1234.56) // '$1,234.56'
+formatCurrency(1234.56, 'EUR') // '€1,234.56'
+formatCurrency(1234.56, 'USD', 'en-AU') // '$1,234.56'
+```
+
+### formatNumber
+
+Format a number with custom Intl.NumberFormat options.
+
+```typescript
+function formatNumber(
+  value: number,
+  options?: Intl.NumberFormatOptions,
+  locale?: string
+): string;
+```
+
+#### Usage
+
+```typescript
+import { formatNumber } from '@jmruthers/pace-core';
+
+formatNumber(1234.56, { minimumFractionDigits: 2, maximumFractionDigits: 2 })
+formatNumber(1234.56, { style: 'decimal', minimumFractionDigits: 0 })
+```
+
+### formatPercent
+
+Format a number as a percentage.
+
+```typescript
+function formatPercent(
+  value: number,
+  locale?: string,
+  decimals?: number
+): string;
+```
+
+#### Usage
+
+```typescript
+import { formatPercent } from '@jmruthers/pace-core';
+
+formatPercent(45.5) // '45.5%'
+formatPercent(45.5, 'en-US', 2) // '45.50%'
+```
+
+### formatCompactNumber
+
+Format large numbers with K, M, B abbreviations.
+
+```typescript
+function formatCompactNumber(value: number, locale?: string): string;
+```
+
+#### Usage
+
+```typescript
+import { formatCompactNumber } from '@jmruthers/pace-core';
+
+formatCompactNumber(1000) // '1K'
+formatCompactNumber(1500000) // '1.5M'
+formatCompactNumber(2300000000) // '2.3B'
+```
+
+### formatFileSize
+
+Format file size in bytes to human-readable string.
+
+```typescript
+function formatFileSize(bytes: number): string;
+```
+
+#### Usage
+
+```typescript
+import { formatFileSize } from '@jmruthers/pace-core';
+
+formatFileSize(1024) // '1 KB'
+formatFileSize(1048576) // '1 MB'
+formatFileSize(0) // '0 Bytes'
+```
+
+### App Configuration Utilities
+
+#### setAppConfig
+
+Set the current application configuration.
+
+```typescript
+function setAppConfig(config: AppConfig): void;
+
+interface AppConfig {
+  appName: string;
+  appId: string;
+}
+```
+
+#### Usage
+
+```typescript
+import { setAppConfig } from '@jmruthers/pace-core';
+
+setAppConfig({
+  appName: 'My App',
+  appId: 'my-app-id'
+});
+```
+
+#### getAppConfig
+
+Get the current application configuration.
+
+```typescript
+function getAppConfig(): AppConfig;
+```
+
+#### Usage
+
+```typescript
+import { getAppConfig } from '@jmruthers/pace-core';
+
+const config = getAppConfig();
+console.log(config.appName); // 'My App'
+console.log(config.appId);   // 'my-app-id'
+```
+
+#### getCurrentAppName
+
+Get the current app name.
+
+```typescript
+function getCurrentAppName(): string;
+```
+
+#### Usage
+
+```typescript
+import { getCurrentAppName } from '@jmruthers/pace-core';
+
+const appName = getCurrentAppName(); // 'My App'
+```
+
+#### getCurrentAppId
+
+Get the current app ID.
+
+```typescript
+function getCurrentAppId(): string;
+```
+
+#### Usage
+
+```typescript
+import { getCurrentAppId } from '@jmruthers/pace-core';
+
+const appId = getCurrentAppId(); // 'my-app-id'
+```
+
 ## Date and Time Utilities
 
 ### formatDate

package/docs/architecture/README.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # PACE Core Architecture
 
 This document provides a comprehensive overview of the PACE Core architecture, including system design, component relationships, and architectural decisions. This is the single source of truth for PACE Core's architectural documentation.

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)
@@ -16,6 +22,26 @@ Comprehensive best practices for building secure, performant, and maintainable a
 - [Accessibility](#-accessibility)
 - [Maintenance](#-maintenance)
 
+## Core Topics
+
+### Security
+- [**Security Best Practices**](./security.md) - Security guidelines and secure coding patterns
+
+### Accessibility  
+- [**Accessibility Guide**](./accessibility.md) - WCAG compliance and inclusive design
+
+### Performance
+- [**Performance Optimization**](./performance.md) - Basic optimization strategies
+- [**Advanced Performance**](./performance-expansion.md) - Advanced optimization techniques
+
+### Testing
+- [**Testing Best Practices**](./testing.md) - Testing strategies and patterns
+
+### Deployment
+- [**Deployment Guide**](./deployment.md) - Production deployment guidelines
+
+---
+
 ## 🔒 Security Best Practices
 
 ### Authentication & Authorization