---
title: Audit
description: Audit protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

Audit Log Architecture

Comprehensive audit logging system for compliance and security.

Supports SOX, HIPAA, GDPR, and other regulatory requirements.

Features:

- Records all CRUD operations on data

- Tracks authentication events (login, logout, password reset)

- Monitors authorization changes (permissions, roles)

- Configurable retention policies (180-day GDPR requirement)

- Suspicious activity detection and alerting

<Callout type="info">
**Source:** `packages/spec/src/system/audit.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { AuditEvent, AuditEventActor, AuditEventChange, AuditEventFilter, AuditEventSeverity, AuditEventTarget, AuditEventType, AuditRetentionPolicy, AuditStorageConfig } from '@objectstack/spec/system';
import type { AuditEvent, AuditEventActor, AuditEventChange, AuditEventFilter, AuditEventSeverity, AuditEventTarget, AuditEventType, AuditRetentionPolicy, AuditStorageConfig } from '@objectstack/spec/system';

// Validate data
const result = AuditEvent.parse(data);
```

---

## AuditEvent

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **id** | `string` | ✅ | Audit event ID |
| **eventType** | `Enum<'data.create' \| 'data.read' \| 'data.update' \| 'data.delete' \| 'data.export' \| 'data.import' \| 'data.bulk_update' \| 'data.bulk_delete' \| 'auth.login' \| 'auth.login_failed' \| 'auth.logout' \| 'auth.session_created' \| 'auth.session_expired' \| 'auth.password_reset' \| 'auth.password_changed' \| 'auth.email_verified' \| 'auth.mfa_enabled' \| 'auth.mfa_disabled' \| 'auth.account_locked' \| 'auth.account_unlocked' \| 'authz.permission_granted' \| 'authz.permission_revoked' \| 'authz.role_assigned' \| 'authz.role_removed' \| 'authz.role_created' \| 'authz.role_updated' \| 'authz.role_deleted' \| 'authz.policy_created' \| 'authz.policy_updated' \| 'authz.policy_deleted' \| 'system.config_changed' \| 'system.plugin_installed' \| 'system.plugin_uninstalled' \| 'system.backup_created' \| 'system.backup_restored' \| 'system.integration_added' \| 'system.integration_removed' \| 'security.access_denied' \| 'security.suspicious_activity' \| 'security.data_breach' \| 'security.api_key_created' \| 'security.api_key_revoked'>` | ✅ | Event type |
| **severity** | `Enum<'debug' \| 'info' \| 'notice' \| 'warning' \| 'error' \| 'critical' \| 'alert' \| 'emergency'>` | ✅ | Event severity |
| **timestamp** | `string` | ✅ | Event timestamp |
| **actor** | `Object` | ✅ | Event actor |
| **target** | `Object` | optional | Event target |
| **description** | `string` | ✅ | Event description |
| **changes** | `Object[]` | optional | List of changes |
| **result** | `Enum<'success' \| 'failure' \| 'partial'>` | ✅ | Action result |
| **errorMessage** | `string` | optional | Error message |
| **tenantId** | `string` | optional | Tenant identifier |
| **requestId** | `string` | optional | Request ID for tracing |
| **metadata** | `Record<string, any>` | optional | Additional metadata |
| **location** | `Object` | optional | Geographic location |


---

## AuditEventActor

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **type** | `Enum<'user' \| 'system' \| 'service' \| 'api_client' \| 'integration'>` | ✅ | Actor type |
| **id** | `string` | ✅ | Actor identifier |
| **name** | `string` | optional | Actor display name |
| **email** | `string` | optional | Actor email address |
| **ipAddress** | `string` | optional | Actor IP address |
| **userAgent** | `string` | optional | User agent string |


---

## AuditEventChange

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **field** | `string` | ✅ | Changed field name |
| **oldValue** | `any` | optional | Previous value |
| **newValue** | `any` | optional | New value |


---

## AuditEventFilter

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **eventTypes** | `Enum<'data.create' \| 'data.read' \| 'data.update' \| 'data.delete' \| 'data.export' \| 'data.import' \| 'data.bulk_update' \| 'data.bulk_delete' \| 'auth.login' \| 'auth.login_failed' \| 'auth.logout' \| 'auth.session_created' \| 'auth.session_expired' \| 'auth.password_reset' \| 'auth.password_changed' \| 'auth.email_verified' \| 'auth.mfa_enabled' \| 'auth.mfa_disabled' \| 'auth.account_locked' \| 'auth.account_unlocked' \| 'authz.permission_granted' \| 'authz.permission_revoked' \| 'authz.role_assigned' \| 'authz.role_removed' \| 'authz.role_created' \| 'authz.role_updated' \| 'authz.role_deleted' \| 'authz.policy_created' \| 'authz.policy_updated' \| 'authz.policy_deleted' \| 'system.config_changed' \| 'system.plugin_installed' \| 'system.plugin_uninstalled' \| 'system.backup_created' \| 'system.backup_restored' \| 'system.integration_added' \| 'system.integration_removed' \| 'security.access_denied' \| 'security.suspicious_activity' \| 'security.data_breach' \| 'security.api_key_created' \| 'security.api_key_revoked'>[]` | optional | Event types to include |
| **severities** | `Enum<'debug' \| 'info' \| 'notice' \| 'warning' \| 'error' \| 'critical' \| 'alert' \| 'emergency'>[]` | optional | Severity levels to include |
| **actorId** | `string` | optional | Actor identifier |
| **tenantId** | `string` | optional | Tenant identifier |
| **timeRange** | `Object` | optional | Time range filter |
| **result** | `Enum<'success' \| 'failure' \| 'partial'>` | optional | Result status |
| **searchQuery** | `string` | optional | Search query |
| **customFilters** | `Record<string, any>` | optional | Custom filters |


---

## AuditEventSeverity

### Allowed Values

* `debug`
* `info`
* `notice`
* `warning`
* `error`
* `critical`
* `alert`
* `emergency`


---

## AuditEventTarget

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **type** | `string` | ✅ | Target type |
| **id** | `string` | ✅ | Target identifier |
| **name** | `string` | optional | Target display name |
| **metadata** | `Record<string, any>` | optional | Target metadata |


---

## AuditEventType

### Allowed Values

* `data.create`
* `data.read`
* `data.update`
* `data.delete`
* `data.export`
* `data.import`
* `data.bulk_update`
* `data.bulk_delete`
* `auth.login`
* `auth.login_failed`
* `auth.logout`
* `auth.session_created`
* `auth.session_expired`
* `auth.password_reset`
* `auth.password_changed`
* `auth.email_verified`
* `auth.mfa_enabled`
* `auth.mfa_disabled`
* `auth.account_locked`
* `auth.account_unlocked`
* `authz.permission_granted`
* `authz.permission_revoked`
* `authz.role_assigned`
* `authz.role_removed`
* `authz.role_created`
* `authz.role_updated`
* `authz.role_deleted`
* `authz.policy_created`
* `authz.policy_updated`
* `authz.policy_deleted`
* `system.config_changed`
* `system.plugin_installed`
* `system.plugin_uninstalled`
* `system.backup_created`
* `system.backup_restored`
* `system.integration_added`
* `system.integration_removed`
* `security.access_denied`
* `security.suspicious_activity`
* `security.data_breach`
* `security.api_key_created`
* `security.api_key_revoked`


---

## AuditRetentionPolicy

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **retentionDays** | `integer` | ✅ | Retention period in days |
| **archiveAfterRetention** | `boolean` | ✅ | Archive logs after retention period |
| **archiveStorage** | `Object` | optional | Archive storage configuration |
| **customRetention** | `Record<string, integer>` | optional | Custom retention by event type |
| **minimumRetentionDays** | `integer` | optional | Minimum retention for compliance |


---

## AuditStorageConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **type** | `Enum<'database' \| 'elasticsearch' \| 'mongodb' \| 'clickhouse' \| 's3' \| 'gcs' \| 'azure_blob' \| 'custom'>` | ✅ | Storage backend type |
| **connectionString** | `string` | optional | Connection string |
| **config** | `Record<string, any>` | optional | Storage-specific configuration |
| **bufferEnabled** | `boolean` | ✅ | Enable buffering |
| **bufferSize** | `integer` | ✅ | Buffer size |
| **flushIntervalSeconds** | `integer` | ✅ | Flush interval in seconds |
| **compression** | `boolean` | ✅ | Enable compression |


---

