Audit Logging

Overview

Every significant action is written to the audit_log table via a write-behind buffer. The buffer flushes every 1 second or when it reaches 64 entries — writes never block the critical path.

Action Categories

Category	Events	Retention
`auth.*`	login, logout, token_refresh, role_change	2 years
`memory.*`	create, read, update, delete, search, share	2 years
`tool.*`	execute, permission_grant, permission_deny	1 year
`agent.*`	session_create, prompt, complete, session_delete	1 year
`file.*`	read, write, delete (sandbox)	1 year
`admin.*`	user_crud, role_crud, template_crud, tenant_settings	2 years
`data.*`	export, import, bulk_delete	2 years

Audit Entry Shape

interface AuditEntry {
  tenantId?: string
  userId?: string
  actor: string       // "user:<id>" | "system" | "agent:<sessionId>"
  action: string      // dotted: "auth.login", "tool.execute"
  target?: string
  sessionId?: string
  channel?: string
  ipAddress?: string
  userAgent?: string
  durationMs?: number
  payload?: Record<string, unknown>
}

Querying Audit Logs

Via REST API

GET /v1/admin/audit-log?action=tool.execute&limit=50&since=2026-01-01
Authorization: Bearer <admin-token>

Supported filters: action (exact match), userId, since, until, and limit (max 500).

The response is shaped as { entries: [...], count: number }.

Via TUI

/audit tool.execute      # filter by action prefix
/audit auth.login        # all login events

Via Web Dashboard

Admin → Audit Log — filterable table with pagination, exportable as CSV.

Writing Audit Entries

Use the audit service in any request handler:

import { createAuditService } from "@orginabox/core/audit"

const audit = createAuditService(db, log)

audit.log({
  tenantId: ctx.tenantId,
  userId: ctx.userId,
  actor: `user:${ctx.userId}`,
  action: "memory.create",
  target: memoryId,
  sessionId: ctx.sessionId,
})

// Flush explicitly on shutdown
await audit.flush()
await audit.close()

SOC 2 Notes

All audit entries include tenant_id and user_id for multi-tenant isolation
IP address and user-agent are captured on all auth events
Duration is recorded for all agent turns
The data.export event fires whenever audit logs themselves are exported
Audit entries are append-only — no DELETE endpoint exists