@jmruthers/pace-core 0.5.108 → 0.5.110

package/docs/rbac/migration-guide.md

@@ -1,260 +0,0 @@
----
-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
-