@jmruthers/pace-core 0.5.109 → 0.5.110

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

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