@jmruthers/pace-core 0.5.76 → 0.5.78

package/docs/migration/README.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Migration Guide
 
 > **🔄 Upgrade and Migration** | [Unified Migration Guide](./MIGRATION_GUIDE.md) | [RBAC Migration](./rbac-migration.md)
@@ -464,7 +470,7 @@ import '@jmruthers/pace-core/src/styles/core.css';
 ## 📚 Additional Resources
 
 - **[RBAC Migration Guide](./rbac-migration.md)** - Detailed RBAC migration
-- **[Version Migration](../troubleshooting/migration.md)** - Version-specific migration
+- **[Migration Guide](./MIGRATION_GUIDE.md)** - Complete migration reference
 - **[Common Issues](../troubleshooting/common-issues.md)** - Troubleshooting migration issues
 - **[API Reference](../api-reference/)** - Complete API documentation
 

package/docs/migration/organisation-context-timing-fix.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Organisation Context Timing Fix Migration
 
 ## Overview

package/docs/migration/rbac-migration.md

@@ -1,10 +1,53 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # RBAC Migration Guide
 
 Migrate from the legacy RBAC system to the new PACE Core RBAC module.
 
 ## Overview
 
-The new RBAC system provides improved performance, better type safety, and enhanced security features. This guide will help you migrate from the old `useRBAC` hook to the new `@jmruthers/pace-core/rbac` module.
+The new RBAC system provides improved performance, better type safety, and enhanced security features. This guide will help you migrate from the old RBAC system to the new `@jmruthers/pace-core/rbac` module.
+
+## ⚠️ Recent Changes
+
+### v0.4.2: Service Provider Refactoring
+
+**Service Instance Management**: All service providers now use `useRef` instead of `useMemo` with dependencies to prevent unnecessary recreation on auth state changes. This fixes React StrictMode issues and "Request aborted" errors.
+
+**Loading State Initialization**: All services now start with `isLoading = false` to prevent UI blocking issues. Loading states are only set to `true` when actively fetching data.
+
+**Removed `enableRBAC` Prop**: RBAC is now always enabled. The `enableRBAC` prop has been removed from `UnifiedAuthProvider`.
+
+### v0.4.1: Hook Name Changes
+
+**IMPORTANT**: The provider hook has been renamed to avoid confusion:
+
+- **Old**: `useRBAC()` from `RBACProvider` context
+- **New**: `useRBACContext()` from `RBACProvider` context
+
+This prevents confusion with the main `useRBAC()` hook from the RBAC module:
+
+```tsx
+// For RBAC provider context (legacy)
+import { useRBACContext } from '@jmruthers/pace-core/rbac/providers';
+
+// For new RBAC system (recommended)
+import { useRBAC } from '@jmruthers/pace-core/rbac';
+```
+
+### Deprecated APIs
+
+The following are deprecated and will be removed in a future version:
+
+- `RBACService` class - Use RBACEngine instead
+- `useRBACService` hook - Use `useRBAC()` instead
+- `usePermissionCheck` hook - Use `useCan()` instead
+
+See deprecation warnings in code for migration instructions.
 
 ## Breaking Changes
 

package/docs/migration/service-architecture.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Provider Architecture: Service-Based Design
 
 ## Overview

package/docs/migration/v0.4.15-tailwind-scanning.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Migration Guide: v0.4.15 Tailwind Content Scanning
 
 This guide helps you migrate to pace-core v0.4.15+ which includes source files for proper Tailwind v4 content scanning.

package/docs/migration/v0.4.16-css-first-approach.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Migration Guide: v0.4.16 CSS-First Approach
 
 This guide helps you migrate to pace-core v0.4.16+ which uses Tailwind v4's CSS-first approach with `@source` directives for automatic content scanning.

package/docs/migration/v0.4.17-source-path-fix.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Migration Guide: v0.4.17 Source Path Fix
 
 This guide explains the critical fix in pace-core v0.4.17 that resolves the @source directive path issue.

package/docs/rbac/README-rbac-rls-integration.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # RBAC-RLS Integration: Dynamic Permission Enforcement
 
 > **🚨 Critical Architecture Fix** - This integration solves the fundamental disconnect between configurable RBAC permissions and hardcoded RLS policies that was breaking core functionality.

package/docs/rbac/README.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # RBAC System
 
 > **📚 RBAC System** | [← Back to Documentation](../README.md) | [Quick Start](./quick-start.md) | [Permissions](../core-concepts/permissions.md)

package/docs/rbac/advanced-patterns.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Advanced RBAC Patterns
 
 Advanced usage patterns, optimizations, and complex scenarios for the PACE Core RBAC system.

package/docs/rbac/api-reference.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # RBAC API Reference
 
 Complete API documentation for the PACE Core RBAC system.
@@ -847,7 +853,7 @@ interface PermissionCheck {
   pageId?: UUID;
 }
 
-type PermissionMap = Record<string, Operation[]>;
+type PermissionMap = Record<Permission | '*', boolean>;
 ```
 
 ### Role Types

package/docs/rbac/breaking-changes-v3.md

@@ -0,0 +1,222 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
+# Breaking Changes in v3.0.0
+
+This document describes all breaking changes in pace-core v3.0.0, specifically related to the auth/RBAC system.
+
+## Summary
+
+The auth/RBAC system has been significantly enhanced with mandatory security validation, comprehensive audit logging, and improved rate limiting. These changes improve security but require migration for existing code.
+
+## Breaking Changes
+
+### 1. Mandatory SecurityContext in RBACEngine
+
+**Changed**: `SecurityContext` parameter is now required in `RBACEngine.isPermitted()`
+
+**Before**:
+```typescript
+await engine.isPermitted({ userId, scope, permission });
+```
+
+**After**:
+```typescript
+await engine.isPermitted(
+  { userId, scope, permission },
+  { userId, organisationId, timestamp: new Date() }
+);
+```
+
+**Migration**: Use the API layer's `isPermitted()` function which automatically creates the security context:
+
+```typescript
+import { isPermitted } from '@jmruthers/pace-core/rbac';
+
+// No changes needed - API handles security context automatically
+await isPermitted({ userId, scope, permission });
+```
+
+### 2. Enhanced Rate Limiting
+
+**Changed**: Rate limiting is now mandatory and enforced on all permission checks
+
+**Before**: Optional rate limiting that always returned true
+
+**After**: Mandatory rate limiting with configurable limits (default: 100 requests/minute)
+
+**Impact**: High-traffic applications may need to increase the limit:
+
+```typescript
+import { setupRBAC } from '@jmruthers/pace-core/rbac';
+
+setupRBAC(supabase, {
+  maxPermissionChecksPerMinute: 200 // Customize as needed
+});
+```
+
+### 3. Comprehensive Audit Logging
+
+**Changed**: All permission checks are now audited, including those without organisation context
+
+**Before**: Audit events only emitted when organisationId was present
+
+**After**: All permission checks are audited with special handling for events without organisation context
+
+**Impact**: The `rbac_audit_events` table now includes:
+- Events without organisation context (using null UUID fallback)
+- Metadata flag `no_organisation_context: true` for tracking
+- More comprehensive security monitoring
+
+### 4. Optional organisationId in SecurityContext
+
+**Changed**: `organisationId` is now optional in `SecurityContext` interface
+
+**Before**:
+```typescript
+interface SecurityContext {
+  userId: UUID;
+  organisationId: UUID; // Required
+  timestamp: Date;
+}
+```
+
+**After**:
+```typescript
+interface SecurityContext {
+  userId: UUID;
+  organisationId?: UUID; // Optional
+  timestamp: Date;
+}
+```
+
+**Impact**: No breaking change for consumers - the field is now optional.
+
+### 5. Input Validation is Mandatory
+
+**Changed**: Input validation is now always performed, not conditional on securityContext presence
+
+**Before**: Input validation only performed if securityContext was provided
+
+**After**: Input validation is mandatory for all permission checks
+
+**Impact**: Invalid inputs will trigger security events and deny access.
+
+**Required validations**:
+- User ID must be valid UUID
+- Permission must match `operation:resource` pattern
+- Scope must include at least one valid identifier
+
+## Non-Breaking Changes
+
+### Enhanced Security Event Logging
+
+Security events are now logged with more detail:
+- Timestamp
+- User agent
+- IP address (when available)
+- Context information
+
+### Improved Rate Limiting
+
+Rate limiting now uses sliding window algorithm instead of simple counters:
+- More accurate limiting
+- Automatic cleanup of expired entries
+- Memory-efficient implementation
+
+## Migration Timeline
+
+### Deprecation Period (v2.0.0 - v2.9.0)
+
+- All changes marked as deprecated
+- Warnings in console
+- Backward compatibility maintained
+
+### Breaking Changes (v3.0.0)
+
+- SecurityContext mandatory
+- Rate limiting mandatory
+- All breaking changes enforced
+
+### Support Period
+
+- Migration guide available
+- Community support provided
+- Automated migration tools (where possible)
+
+## Upgrade Instructions
+
+1. **Update Dependencies**:
+   ```bash
+   npm install @jmruthers/pace-core@^3.0.0
+   ```
+
+2. **Review Breaking Changes**: Read this document and the migration guide
+
+3. **Update Code**: Apply migration patterns from the [Migration Guide](./migration-guide.md)
+
+4. **Test**: Run your test suite and verify all permission checks work
+
+5. **Monitor**: Check logs for security events and rate limiting
+
+## Compatibility Matrix
+
+| Feature | v2.0.0 | v3.0.0 |
+|---------|--------|--------|
+| Optional SecurityContext | ✅ | ❌ |
+| Rate Limiting | Optional | Mandatory |
+| Input Validation | Conditional | Always |
+| Audit Logging | Partial | Complete |
+| Type Safety | Basic | Enhanced |
+
+## Frequently Asked Questions
+
+### Q: Why is SecurityContext now mandatory?
+
+**A**: To ensure all permission checks go through proper security validation, rate limiting, and audit logging. This prevents security vulnerabilities where validation is skipped.
+
+### Q: Will rate limiting affect my app's performance?
+
+**A**: The default limit of 100 requests/minute is generous for most applications. High-traffic apps can increase this limit or implement caching to reduce permission check frequency.
+
+### Q: How do I handle events without organisation context?
+
+**A**: Use the `no_organisation_context` metadata flag in audit queries:
+
+```typescript
+const { data } = await supabase
+  .from('rbac_audit_events')
+  .select('*')
+  .eq('metadata->no_organisation_context', true);
+```
+
+### Q: Can I disable rate limiting?
+
+**A**: No. Rate limiting is mandatory for security. However, you can increase the limit if needed.
+
+### Q: Will existing code break?
+
+**A**: Only if you're calling `RBACEngine.isPermitted()` directly. Using the API layer's `isPermitted()` function maintains backward compatibility.
+
+## Getting Help
+
+- **Migration Guide**: See [Migration Guide](./migration-guide.md)
+- **API Reference**: See [API Reference](./api-reference.md)
+- **Troubleshooting**: See [Troubleshooting Guide](./troubleshooting.md)
+- **Issues**: Open an issue on the project repository
+
+## Changelog
+
+Full changelog for v3.0.0:
+
+- ✅ Made SecurityContext mandatory in RBACEngine
+- ✅ Implemented real rate limiting with sliding window algorithm
+- ✅ Enhanced audit logging to include all permission checks
+- ✅ Made organisationId optional in SecurityContext
+- ✅ Added comprehensive input validation
+- ✅ Improved security event logging
+- ✅ Added metadata flags for tracking events without organisation context
+

package/docs/rbac/examples/rbac-rls-integration-example.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # RBAC-RLS Integration Example
 
 This example demonstrates how to use the new RBAC-RLS integration system to solve the critical architectural issue where RBAC permissions and RLS policies were disconnected.

package/docs/rbac/examples.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # RBAC Examples
 
 Practical examples showing how to use the PACE Core RBAC system in real applications.

package/docs/rbac/getting-started.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # RBAC Getting Started Guide
 
 > **📚 New to RBAC?** This guide will get you up and running with the PACE Core RBAC system in under 10 minutes.

package/docs/rbac/migration-guide.md

@@ -0,0 +1,260 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
+# RBAC Migration Guide - Breaking Changes
+
+This guide helps you migrate to the new mandatory security validation in the RBAC system.
+
+## Overview
+
+The RBAC system now requires mandatory security validation for all permission checks. This ensures all operations go through proper security validation, rate limiting, and audit logging.
+
+## What Changed
+
+### Before (v2.0.0 and earlier)
+
+```typescript
+// SecurityContext was optional
+const hasPermission = await engine.isPermitted({
+  userId,
+  scope,
+  permission
+}); // No securityContext parameter
+```
+
+### After (v3.0.0)
+
+```typescript
+// SecurityContext is now mandatory
+const hasPermission = await engine.isPermitted({
+  userId,
+  scope,
+  permission
+}, {
+  userId,
+  organisationId: scope.organisationId,
+  timestamp: new Date()
+});
+```
+
+## Migration Options
+
+### Option 1: Use the API Layer (Recommended)
+
+The easiest migration path is to use the `isPermitted()` function from the API layer, which automatically creates the security context:
+
+```typescript
+import { isPermitted } from '@jmruthers/pace-core/rbac';
+
+// No changes needed - API creates security context automatically
+const hasPermission = await isPermitted({
+  userId,
+  scope,
+  permission
+});
+```
+
+### Option 2: Create Security Context Manually
+
+If you're calling the engine directly, create a security context:
+
+```typescript
+import { RBACEngine, setupRBAC } from '@jmruthers/pace-core/rbac';
+
+// Setup RBAC once
+setupRBAC(supabase);
+
+// Create security context
+const securityContext = {
+  userId,
+  organisationId: scope.organisationId,
+  timestamp: new Date()
+};
+
+// Use with engine
+const engine = getRBACEngine();
+const hasPermission = await engine.isPermitted({
+  userId,
+  scope,
+  permission
+}, securityContext);
+```
+
+## Breaking Changes
+
+### 1. SecurityContext Now Required
+
+**Impact**: All direct calls to `RBACEngine.isPermitted()` must provide security context.
+
+**Migration**: Use the API layer's `isPermitted()` function instead of calling the engine directly.
+
+### 2. organisationId Now Optional in SecurityContext
+
+**Impact**: Events without organisation context (e.g., global admin operations) are now properly logged.
+
+**Migration**: No action needed if you're using the API layer. If creating security context manually, you can omit `organisationId`:
+
+```typescript
+const securityContext = {
+  userId,
+  // organisationId is now optional
+  timestamp: new Date()
+};
+```
+
+## Enhanced Features
+
+### 1. Mandatory Rate Limiting
+
+All permission checks now go through rate limiting. By default, users are limited to 100 permission checks per minute.
+
+To configure rate limits:
+
+```typescript
+import { setupRBAC } from '@jmruthers/pace-core/rbac';
+
+setupRBAC(supabase, {
+  maxPermissionChecksPerMinute: 200 // Increase for high-traffic apps
+});
+```
+
+### 2. Comprehensive Audit Logging
+
+All permission checks are now audited, including:
+- Super admin bypasses
+- Operations without organisation context
+- Failed authentication attempts
+
+Audit events are stored in the `rbac_audit_events` table with the following structure:
+
+```typescript
+{
+  event_type: 'permission_check' | 'permission_denied' | 'role_granted' | 'role_denied' | 'rls_denied',
+  user_id: UUID,
+  organisation_id: UUID, // May be null UUID for global operations
+  event_id?: string,
+  app_id?: UUID,
+  page_id?: UUID,
+  permission?: string,
+  decision?: boolean,
+  source: 'api' | 'ui' | 'middleware' | 'rls',
+  bypass?: boolean,
+  duration_ms?: number,
+  metadata: {
+    cache_hit?: boolean,
+    cache_source?: 'memory' | 'database' | 'rpc',
+    no_organisation_context?: boolean
+  }
+}
+```
+
+### 3. Input Validation
+
+All inputs are now validated before processing:
+- User ID format (must be valid UUID)
+- Permission format (must match `operation:resource` pattern)
+- Scope format (must include at least one valid identifier)
+
+Invalid inputs trigger security events and return false (deny access).
+
+## Security Improvements
+
+### Rate Limiting
+
+The system now implements in-memory rate limiting with a sliding window algorithm:
+
+- **Window**: 1 minute
+- **Default limit**: 100 requests per minute per user
+- **Automatic cleanup**: Expired entries are cleared every 5 minutes
+
+To implement distributed rate limiting, migrate to Redis or Supabase Edge Functions.
+
+### Security Event Logging
+
+Security events are now logged even without organisation context:
+
+```typescript
+// These events are now audited:
+// 1. Super admin bypasses (bypass: true)
+// 2. Permission denied events
+// 3. Invalid input events
+// 4. Rate limit exceeded events
+// 5. Suspicious activity events
+```
+
+## Migration Checklist
+
+- [ ] Update all calls to `RBACEngine.isPermitted()` to use API layer
+- [ ] Remove optional securityContext parameters from code
+- [ ] Configure rate limits for your application's needs
+- [ ] Update audit log queries to handle events without organisation context
+- [ ] Test permission checks with various user roles
+- [ ] Monitor rate limiting to ensure no false positives
+
+## Backward Compatibility
+
+The API layer maintains backward compatibility:
+
+```typescript
+// This still works - API creates security context automatically
+import { isPermitted } from '@jmruthers/pace-core/rbac';
+
+const hasPermission = await isPermitted({
+  userId,
+  scope,
+  permission
+});
+```
+
+## Common Issues
+
+### Issue: Rate Limit Exceeded
+
+**Symptom**: `rate_limit_exceeded` security events in logs.
+
+**Solution**: Increase the rate limit or implement caching for frequently accessed permissions.
+
+### Issue: Invalid Input
+
+**Symptom**: Permission checks returning false with `invalid_input` events.
+
+**Solution**: Ensure all UUIDs are valid and permission strings match the `operation:resource` pattern.
+
+### Issue: Missing Organisation Context
+
+**Symptom**: Warnings in console about missing organisation context.
+
+**Solution**: Either provide organisation context or update your queries to filter by `no_organisation_context` metadata flag.
+
+## Testing Your Migration
+
+1. **Test with all user roles**:
+   - Super admin
+   - Organisation admin
+   - Event admin
+   - Regular users
+
+2. **Test rate limiting**:
+   - Make more than 100 permission checks in a minute
+   - Verify rate limit exceeded events are logged
+
+3. **Test audit logging**:
+   - Check `rbac_audit_events` table
+   - Verify all permission checks are logged
+   - Verify events without organisation context are flagged
+
+4. **Test error handling**:
+   - Invalid UUIDs
+   - Malformed permission strings
+   - Missing required fields
+
+## Support
+
+For questions or issues with the migration, please:
+1. Check the [Troubleshooting Guide](./troubleshooting.md)
+2. Review the [API Reference](./api-reference.md)
+3. Open an issue on the project repository
+