@objectstack/plugin-audit 4.0.3 → 4.0.5

package/README.md

@@ -0,0 +1,414 @@
+# @objectstack/plugin-audit
+
+Audit Plugin for ObjectStack — System audit log object and audit trail for compliance and security monitoring.
+
+## Features
+
+- **Comprehensive Audit Trail**: Track all CRUD operations across all objects
+- **User Activity Logging**: Record who did what, when, and from where
+- **Field-Level Changes**: Capture before/after values for all field changes
+- **Compliance Ready**: Meet SOC 2, HIPAA, GDPR audit requirements
+- **Query Filtering**: Search audit logs by user, object, action, date range
+- **Retention Policies**: Auto-archive or delete old audit logs
+- **Security Events**: Track authentication, authorization, and security-related events
+- **Immutable Logs**: Audit records cannot be modified or deleted (only archived)
+
+## Installation
+
+```bash
+pnpm add @objectstack/plugin-audit
+```
+
+## Basic Usage
+
+```typescript
+import { defineStack } from '@objectstack/spec';
+import { PluginAudit } from '@objectstack/plugin-audit';
+
+const stack = defineStack({
+  plugins: [
+    PluginAudit.configure({
+      enabled: true,
+      trackObjects: '*', // Track all objects
+      trackFields: '*', // Track all field changes
+    }),
+  ],
+});
+```
+
+## Configuration
+
+```typescript
+interface AuditPluginConfig {
+  /** Enable audit logging (default: true) */
+  enabled?: boolean;
+
+  /** Objects to track ('*' for all, or array of object names) */
+  trackObjects?: '*' | string[];
+
+  /** Fields to track ('*' for all, or object-specific config) */
+  trackFields?: '*' | Record<string, string[]>;
+
+  /** Track system events (login, logout, failed auth, etc.) */
+  trackSystemEvents?: boolean;
+
+  /** Retention period in days (default: 365) */
+  retentionDays?: number;
+
+  /** Auto-archive after retention period (default: true) */
+  autoArchive?: boolean;
+
+  /** Exclude certain users from audit (e.g., system users) */
+  excludeUsers?: string[];
+}
+```
+
+## Audit Log Schema
+
+The plugin automatically creates the `audit_log` object:
+
+```typescript
+{
+  id: string;              // Unique audit log entry ID
+  timestamp: datetime;     // When the action occurred
+  userId: string;          // User who performed the action
+  userName: string;        // User's name at time of action
+  userEmail: string;       // User's email at time of action
+  action: string;          // 'insert', 'update', 'delete', 'read'
+  object: string;          // Object type (e.g., 'opportunity')
+  recordId: string;        // Record ID that was affected
+  recordName: string;      // Record display name
+  changes: json;           // Field-level changes (before/after)
+  metadata: json;          // Additional context (IP, user agent, etc.)
+  ipAddress: string;       // Client IP address
+  userAgent: string;       // Client user agent
+  sessionId: string;       // Session ID
+  status: string;          // 'success' | 'failed'
+  errorMessage: string;    // Error message if action failed
+}
+```
+
+## Automatic Audit Logging
+
+All CRUD operations are automatically audited:
+
+```typescript
+// This operation is automatically audited
+await kernel.getDriver().insert({
+  object: 'opportunity',
+  data: {
+    name: 'Big Deal',
+    amount: 100000,
+    stage: 'prospecting',
+  },
+});
+
+// Audit log entry created:
+// {
+//   action: 'insert',
+//   object: 'opportunity',
+//   recordId: '123',
+//   recordName: 'Big Deal',
+//   changes: {
+//     name: { from: null, to: 'Big Deal' },
+//     amount: { from: null, to: 100000 },
+//     stage: { from: null, to: 'prospecting' }
+//   }
+// }
+```
+
+## Querying Audit Logs
+
+```typescript
+// Get audit logs via kernel
+const auditService = kernel.getService('audit');
+
+// Get all changes for a specific record
+const recordHistory = await auditService.getRecordHistory({
+  object: 'opportunity',
+  recordId: '123',
+});
+
+// Get user activity
+const userActivity = await auditService.getUserActivity({
+  userId: 'user:456',
+  from: '2024-01-01',
+  to: '2024-01-31',
+});
+
+// Search audit logs
+const logs = await auditService.searchLogs({
+  action: 'delete',
+  object: 'account',
+  from: '2024-01-01',
+  to: '2024-01-31',
+});
+
+// Get failed actions (security monitoring)
+const failures = await auditService.getFailedActions({
+  from: '2024-01-01',
+  limit: 100,
+});
+```
+
+## Selective Tracking
+
+### Track Specific Objects
+
+```typescript
+PluginAudit.configure({
+  trackObjects: ['opportunity', 'account', 'contact'],
+  // Only these objects will be audited
+});
+```
+
+### Track Specific Fields
+
+```typescript
+PluginAudit.configure({
+  trackFields: {
+    opportunity: ['stage', 'amount', 'close_date'], // Only track these fields
+    account: '*', // Track all fields for accounts
+    contact: ['email', 'phone'], // Only email and phone for contacts
+  },
+});
+```
+
+### Exclude System Users
+
+```typescript
+PluginAudit.configure({
+  excludeUsers: [
+    'system:integration',
+    'system:cron',
+    'service:automation',
+  ],
+  // These users' actions won't be audited
+});
+```
+
+## Advanced Features
+
+### Manual Audit Entries
+
+```typescript
+// Log custom security event
+await auditService.log({
+  action: 'security:password_reset',
+  userId: 'user:456',
+  metadata: {
+    resetMethod: 'email',
+    ipAddress: '192.168.1.100',
+  },
+});
+
+// Log business process event
+await auditService.log({
+  action: 'workflow:approval',
+  object: 'opportunity',
+  recordId: '123',
+  metadata: {
+    approver: 'manager:789',
+    decision: 'approved',
+  },
+});
+```
+
+### Audit Snapshots
+
+```typescript
+// Create snapshot of record state at a specific time
+const snapshot = await auditService.getRecordSnapshot({
+  object: 'opportunity',
+  recordId: '123',
+  asOf: '2024-01-15T10:30:00Z',
+});
+
+// Returns: Record state as it existed on Jan 15, 2024 at 10:30 AM
+```
+
+### Audit Reports
+
+```typescript
+// Generate compliance report
+const report = await auditService.generateReport({
+  type: 'compliance',
+  from: '2024-01-01',
+  to: '2024-03-31',
+  format: 'pdf',
+});
+
+// Generate user activity report
+const userReport = await auditService.generateReport({
+  type: 'user_activity',
+  userId: 'user:456',
+  from: '2024-01-01',
+  to: '2024-01-31',
+  includeDetails: true,
+});
+```
+
+### Data Retention & Archival
+
+```typescript
+// Archive old audit logs
+await auditService.archiveLogs({
+  olderThan: '2023-01-01',
+  destination: 's3://audit-archive/2023/',
+});
+
+// Permanently delete archived logs (compliance approved)
+await auditService.purgeLogs({
+  olderThan: '2020-01-01',
+  confirmed: true, // Safety check
+});
+```
+
+## Security Events
+
+The plugin automatically logs security-related events:
+
+- **Authentication**: Login, logout, password changes
+- **Authorization**: Permission denied, role changes
+- **Data Access**: Read operations on sensitive fields
+- **Configuration**: System setting changes
+- **API**: API key usage, rate limit violations
+
+```typescript
+// Automatically logged:
+// - Login attempts (success/failure)
+// - Permission denied errors
+// - Sensitive field access
+// - API authentication failures
+```
+
+## Compliance Integration
+
+### GDPR Compliance
+
+```typescript
+// Right to be forgotten - audit trail for deletions
+await auditService.logDataDeletion({
+  userId: 'user:456',
+  reason: 'gdpr_right_to_be_forgotten',
+  deletedRecords: [
+    { object: 'user', recordId: '456' },
+    { object: 'contact', recordId: '789' },
+  ],
+});
+
+// Right of access - audit trail for data exports
+await auditService.logDataExport({
+  userId: 'user:456',
+  reason: 'gdpr_data_access_request',
+  exportedObjects: ['user', 'contact', 'activity'],
+});
+```
+
+### SOC 2 Compliance
+
+```typescript
+// Log administrative actions
+await auditService.logAdminAction({
+  adminId: 'admin:123',
+  action: 'user_role_change',
+  targetUserId: 'user:456',
+  changes: {
+    roles: { from: ['user'], to: ['user', 'admin'] },
+  },
+});
+```
+
+### HIPAA Compliance
+
+```typescript
+// Track PHI access
+PluginAudit.configure({
+  trackFields: {
+    patient: ['ssn', 'medical_record_number', 'diagnosis'], // PHI fields
+  },
+  trackSystemEvents: true,
+});
+```
+
+## REST API Endpoints
+
+```
+GET    /api/v1/audit                      # List audit logs
+GET    /api/v1/audit/:id                  # Get specific log entry
+GET    /api/v1/audit/record/:object/:id   # Get record history
+GET    /api/v1/audit/user/:userId         # Get user activity
+POST   /api/v1/audit/report               # Generate report
+POST   /api/v1/audit/archive              # Archive old logs
+```
+
+## Dashboard Integration
+
+```typescript
+// Audit dashboard widget
+const auditWidget = {
+  title: 'Recent Activity',
+  query: {
+    object: 'audit_log',
+    limit: 50,
+    sort: [{ field: 'timestamp', direction: 'desc' }],
+  },
+};
+
+// Security alerts dashboard
+const securityWidget = {
+  title: 'Failed Login Attempts',
+  query: {
+    object: 'audit_log',
+    filters: [
+      { field: 'action', operator: 'eq', value: 'auth:login' },
+      { field: 'status', operator: 'eq', value: 'failed' },
+      { field: 'timestamp', operator: 'gte', value: 'today' },
+    ],
+  },
+};
+```
+
+## Best Practices
+
+1. **Selective Tracking**: Only audit what's necessary for compliance
+2. **Retention Policy**: Set appropriate retention based on regulations
+3. **Performance**: Archive old logs to keep query performance high
+4. **Security**: Restrict access to audit logs (admin only)
+5. **Immutability**: Never allow modification of audit records
+6. **Monitoring**: Set alerts for suspicious activity patterns
+7. **Regular Review**: Periodically review audit logs for anomalies
+
+## Performance Considerations
+
+- **Async Logging**: Audit writes happen asynchronously (no performance impact)
+- **Indexing**: Automatically indexes `userId`, `object`, `recordId`, `timestamp`
+- **Partitioning**: Consider table partitioning for high-volume deployments
+- **Archival**: Move old logs to cold storage (S3, Glacier)
+
+## Contract Implementation
+
+Implements audit logging hooks from `@objectstack/spec/contracts`:
+
+```typescript
+interface IAuditService {
+  log(entry: AuditLogEntry): Promise<void>;
+  getRecordHistory(options: RecordHistoryOptions): Promise<AuditLog[]>;
+  getUserActivity(options: UserActivityOptions): Promise<AuditLog[]>;
+  searchLogs(filter: AuditLogFilter): Promise<AuditLog[]>;
+  getRecordSnapshot(options: SnapshotOptions): Promise<any>;
+  archiveLogs(options: ArchiveOptions): Promise<void>;
+}
+```
+
+## License
+
+Apache-2.0
+
+## See Also
+
+- [SOC 2 Compliance Guide](https://www.aicpa.org/interestareas/frc/assuranceadvisoryservices/sorhome)
+- [GDPR Requirements](https://gdpr.eu/)
+- [HIPAA Compliance](https://www.hhs.gov/hipaa/)
+- [@objectstack/plugin-security](../plugin-security/)
+- [Audit Logging Best Practices](/content/docs/guides/audit/)