Audit Log Schema
What it does
The audit log is the system of record for every meaningful event in the legal AI platform. It answers: who did what, to what, when, from where, and with what result. In a legal product, the audit log serves dual purposes: operational observability and legal/regulatory accountability.
Specifically, the audit log must be able to answer:
- "Did the AI access this client's documents before the conflict check was complete?"
- "What version of skill X was used when the AI generated this engagement letter?"
- "Who approved the deletion of matter Y's data, and when?"
- "Was the user's session authenticated before they queried a privileged document?"
Canonical event record
Every audit log entry is a single JSON object:
{
"event_id": "ulid or uuid-v7",
"event_type": "skill.invoked | user.auth | document.accessed | matter.created | ...",
"timestamp": "2025-05-14T09:31:42.123Z",
"timestamp_local": "2025-05-14T12:31:42.123+03:00",
"actor": {
"user_id": "usr_abc123",
"role": "associate | partner | admin | system",
"session_id": "sess_xyz789",
"ip_address": "203.0.113.42",
"user_agent": "..."
},
"resource": {
"type": "matter | document | skill | tool | session | user | org",
"id": "matter_2025-UAE-0147",
"name": "Al Baraka SPA"
},
"action": {
"name": "read | create | update | delete | invoke | approve | reject | transmit",
"detail": "Skill efirm-conflict-check invoked for new matter",
"result": "success | failure | partial",
"error_code": null,
"error_message": null
},
"context": {
"skill_id": "efirm-conflict-check",
"skill_version": "1.0",
"model_id": "claude-sonnet-4-6",
"trace_id": "langfuse-trace-id",
"request_id": "req_abc123"
},
"metadata": {
"org_id": "org_haqq",
"workspace_id": "ws_default",
"environment": "production | staging"
},
"integrity": {
"prev_hash": "sha256-of-previous-entry",
"entry_hash": "sha256-of-this-entry"
}
}
Required fields (no nullable)
| Field |
Type |
Purpose |
event_id |
ULID or UUIDv7 |
Monotonic ordering + uniqueness |
event_type |
enum string |
Fast filtering and alerting |
timestamp |
ISO 8601 UTC |
Canonical time reference |
actor.user_id |
string |
Who acted; "system" for automated events |
actor.role |
enum |
Authorization context |
actor.session_id |
string |
Links to authentication record |
resource.type |
enum |
What was acted upon |
resource.id |
string |
Specific resource identifier |
action.name |
enum |
What happened |
action.result |
enum |
Success / failure / partial |
context.request_id |
string |
Links to request log |
Event type taxonomy
Authentication events
user.auth.login.success
user.auth.login.failure
user.auth.logout
user.auth.token.refresh
user.auth.mfa.success
user.auth.mfa.failure
Matter and document events
matter.created
matter.status.changed
matter.accessed
document.created
document.accessed
document.transmitted (to external party — high importance)
document.deleted
document.version.created
Skill invocation events
skill.invoked
skill.completed
skill.failed
skill.escalated (skill routed to human review)
Conflict and compliance events
conflict.check.run
conflict.check.result.clean
conflict.check.result.concern
conflict.check.result.conflict
aml.screening.run
aml.flag.raised
Data events
data.export.requested
data.export.delivered
data.deletion.requested
data.deletion.completed
Admin events
user.created
user.role.changed
user.access.granted
user.access.revoked
org.settings.changed
Tamper-evidence (chained hashes)
For regulatory and malpractice defensibility, the audit log must be tamper-evident:
- Compute
entry_hash = SHA256(event_id + event_type + timestamp + actor + resource + action + prev_hash).
- Each entry's
prev_hash is the entry_hash of the immediately preceding entry.
- Any insertion, deletion, or modification breaks the hash chain.
- Periodically anchor the chain head to an external timestamp authority (e.g., RFC 3161 timestamp token) for legal evidentiary strength.
Indexing strategy
| Index |
Purpose |
(org_id, timestamp) |
Org-scoped time-range queries |
(actor.user_id, timestamp) |
User activity history |
(resource.id, timestamp) |
Resource event history |
(event_type, timestamp) |
Alert and monitoring queries |
(context.trace_id) |
Cross-service trace correlation |
(action.result, event_type, timestamp) |
Failure analysis |
Use a write-optimized append-only store (e.g., ClickHouse, BigQuery, S3+Athena, or a dedicated audit table in PostgreSQL with UNLOGGED disabled and row-level security). Do not use the same database table as application data.
Retention policy
| Event category |
Minimum retention |
Rationale |
| Authentication |
1 year |
Security investigation |
| Matter / document access |
7 years |
Bar file retention; malpractice |
| Conflict check |
7 years |
Bar discipline defense |
| Skill invocations |
2 years |
Operational; AI accountability |
| Financial events (billing, invoices) |
7 years |
Tax and audit |
| Data deletion events |
Permanent |
Proof of compliance |
Retention may be extended by firm policy or jurisdiction-specific requirements.
Access control
- The audit log is readable by: system admins, managing partner (org-level), compliance officer.
- Individual users can read their own events only.
- No user — including admins — can delete or update audit log entries.
- Write access: system only (no user-facing write endpoint).
Related skills
- [[eng-langfuse-trace-inspector]]
- [[eng-latency-slo-by-skill]]
- [[eng-cost-per-message-tracker]]
- [[eng-mcp-tool-registry]]
1---2name: eng-audit-log-schema3description: Use when designing or reviewing the audit log schema for a legal AI product. Defines the canonical event record structure, required fields for legal-product compliance (attorney-client privilege considerations, regulatory retention rules, tamper-evidence), indexing strategy, retention policies, and the specific event types that must be logged in a law-firm or legal-AI context. Engineering skill — no practice-area jurisdictional notes.4license: MIT5metadata:6 id: eng.audit-log-schema7 category: eng8 jurisdictions: [__multi__]9 priority: P210 intent: [audit-log, schema, compliance, tamper-evidence, retention, observability]11 related:12 - eng-langfuse-trace-inspector13 - eng-latency-slo-by-skill14 - eng-cost-per-message-tracker15 - eng-mcp-tool-registry16 source: https://skillmd.com/skills/sboghossian-mini-claude-for-legal/eng-audit-log-schema17 upstream: Louis — HAQQ Legal AI (github.com/sboghossian/mini-claude-for-legal)18 version: "1.0"19---2021# Audit Log Schema2223## What it does2425The audit log is the system of record for every meaningful event in the legal AI platform. It answers: who did what, to what, when, from where, and with what result. In a legal product, the audit log serves dual purposes: operational observability and legal/regulatory accountability.2627Specifically, the audit log must be able to answer:28- "Did the AI access this client's documents before the conflict check was complete?"29- "What version of skill X was used when the AI generated this engagement letter?"30- "Who approved the deletion of matter Y's data, and when?"31- "Was the user's session authenticated before they queried a privileged document?"3233## Canonical event record3435Every audit log entry is a single JSON object:3637```json38{39 "event_id": "ulid or uuid-v7",40 "event_type": "skill.invoked | user.auth | document.accessed | matter.created | ...",41 "timestamp": "2025-05-14T09:31:42.123Z",42 "timestamp_local": "2025-05-14T12:31:42.123+03:00",43 "actor": {44 "user_id": "usr_abc123",45 "role": "associate | partner | admin | system",46 "session_id": "sess_xyz789",47 "ip_address": "203.0.113.42",48 "user_agent": "..."49 },50 "resource": {51 "type": "matter | document | skill | tool | session | user | org",52 "id": "matter_2025-UAE-0147",53 "name": "Al Baraka SPA"54 },55 "action": {56 "name": "read | create | update | delete | invoke | approve | reject | transmit",57 "detail": "Skill efirm-conflict-check invoked for new matter",58 "result": "success | failure | partial",59 "error_code": null,60 "error_message": null61 },62 "context": {63 "skill_id": "efirm-conflict-check",64 "skill_version": "1.0",65 "model_id": "claude-sonnet-4-6",66 "trace_id": "langfuse-trace-id",67 "request_id": "req_abc123"68 },69 "metadata": {70 "org_id": "org_haqq",71 "workspace_id": "ws_default",72 "environment": "production | staging"73 },74 "integrity": {75 "prev_hash": "sha256-of-previous-entry",76 "entry_hash": "sha256-of-this-entry"77 }78}79```8081## Required fields (no nullable)8283| Field | Type | Purpose |84|---|---|---|85| `event_id` | ULID or UUIDv7 | Monotonic ordering + uniqueness |86| `event_type` | enum string | Fast filtering and alerting |87| `timestamp` | ISO 8601 UTC | Canonical time reference |88| `actor.user_id` | string | Who acted; "system" for automated events |89| `actor.role` | enum | Authorization context |90| `actor.session_id` | string | Links to authentication record |91| `resource.type` | enum | What was acted upon |92| `resource.id` | string | Specific resource identifier |93| `action.name` | enum | What happened |94| `action.result` | enum | Success / failure / partial |95| `context.request_id` | string | Links to request log |9697## Event type taxonomy9899### Authentication events100- `user.auth.login.success`101- `user.auth.login.failure`102- `user.auth.logout`103- `user.auth.token.refresh`104- `user.auth.mfa.success`105- `user.auth.mfa.failure`106107### Matter and document events108- `matter.created`109- `matter.status.changed`110- `matter.accessed`111- `document.created`112- `document.accessed`113- `document.transmitted` (to external party — high importance)114- `document.deleted`115- `document.version.created`116117### Skill invocation events118- `skill.invoked`119- `skill.completed`120- `skill.failed`121- `skill.escalated` (skill routed to human review)122123### Conflict and compliance events124- `conflict.check.run`125- `conflict.check.result.clean`126- `conflict.check.result.concern`127- `conflict.check.result.conflict`128- `aml.screening.run`129- `aml.flag.raised`130131### Data events132- `data.export.requested`133- `data.export.delivered`134- `data.deletion.requested`135- `data.deletion.completed`136137### Admin events138- `user.created`139- `user.role.changed`140- `user.access.granted`141- `user.access.revoked`142- `org.settings.changed`143144## Tamper-evidence (chained hashes)145146For regulatory and malpractice defensibility, the audit log must be tamper-evident:1471481. Compute `entry_hash = SHA256(event_id + event_type + timestamp + actor + resource + action + prev_hash)`.1492. Each entry's `prev_hash` is the `entry_hash` of the immediately preceding entry.1503. Any insertion, deletion, or modification breaks the hash chain.1514. Periodically anchor the chain head to an external timestamp authority (e.g., RFC 3161 timestamp token) for legal evidentiary strength.152153## Indexing strategy154155| Index | Purpose |156|---|---|157| `(org_id, timestamp)` | Org-scoped time-range queries |158| `(actor.user_id, timestamp)` | User activity history |159| `(resource.id, timestamp)` | Resource event history |160| `(event_type, timestamp)` | Alert and monitoring queries |161| `(context.trace_id)` | Cross-service trace correlation |162| `(action.result, event_type, timestamp)` | Failure analysis |163164Use a write-optimized append-only store (e.g., ClickHouse, BigQuery, S3+Athena, or a dedicated audit table in PostgreSQL with `UNLOGGED` disabled and row-level security). Do not use the same database table as application data.165166## Retention policy167168| Event category | Minimum retention | Rationale |169|---|---|---|170| Authentication | 1 year | Security investigation |171| Matter / document access | 7 years | Bar file retention; malpractice | 172| Conflict check | 7 years | Bar discipline defense |173| Skill invocations | 2 years | Operational; AI accountability |174| Financial events (billing, invoices) | 7 years | Tax and audit |175| Data deletion events | Permanent | Proof of compliance |176177Retention may be extended by firm policy or jurisdiction-specific requirements.178179## Access control180181- The audit log is readable by: system admins, managing partner (org-level), compliance officer.182- Individual users can read their own events only.183- No user — including admins — can delete or update audit log entries.184- Write access: system only (no user-facing write endpoint).185186## Related skills187188- [[eng-langfuse-trace-inspector]]189- [[eng-latency-slo-by-skill]]190- [[eng-cost-per-message-tracker]]191- [[eng-mcp-tool-registry]]