Audit log surface

patterns specs/patterns/audit-log.kmd

The immutable, filterable trail of "who did what, when" for a tenant — security/compliance events rendered as a sortable, searchable, exportable events table with a stable event model and tamper-evidence. Specializes the admin data table for append-only audit data. GitLab Pajamas (audit events) parity. Used by Koder ID, Flow, Console, and any product with compliance needs.

When this pattern applies

Primary triggers

All triggers

Pattern — Audit log

Status: v0.1.0 — Draft. Promoted from the GitLab Pajamas parity scan (meta/docs/stack #093). Source: https://design.gitlab.com/ (audit events). Retention/PII rules align with policies/identity-data-retention.kmd.

R1 — Event model (stable)

Each entry has a fixed shape: actor (who — user/machine/system), action (what — a stable verb key), target (the affected resource), timestamp (UTC, with locale display), outcome (success/denied), and context (source IP / device / request id where applicable). The action verb is a stable key (not a free string) so filtering and i18n work.

R2 — Immutable & tamper-evident

  • The log is append-only: entries are never edited or deleted by users (retention purges are a system policy, not a user action).
  • Tamper-evidence (e.g. a hash chain / signed batches) is recommended for high-assurance tenants; the UI surfaces a verification status when present.

R3 — Filter / sort / search (specializes admin-data-table)

Built on specs/patterns/admin-data-table.kmd: filter by actor, action, target, date range, and outcome; sort by time (default newest-first); full-text search over targets. Large logs virtualize/paginate with any truncation disclosed (no silent cap).

R4 — Retention, PII, export

  • Retention follows policies/identity-data-retention.kmd / specs/multi-tenancy/contract.kmd; entries past the window are purged by the system, and that is itself disclosed (not silent).
  • No secrets/credentials are ever logged; PII is minimized and access-gated. The surface never renders raw sensitive payloads.
  • Export (CSV/JSON) is available to authorized roles and is itself an audited action.

R5 — Access control & tenancy

  • Visible only to authorized roles (security/admin); per-tenant isolation per specs/multi-tenancy/contract.kmd — a tenant sees only its events.
  • A failed/denied access attempt to the audit log is itself an auditable event.

R6 — Accessibility & i18n

  • A real table with header semantics (inherits admin-data-table a11y).
  • Action verbs + outcomes are localized from their stable keys (specs/i18n/contract.kmd); timestamps render in the viewer's locale + timezone with the UTC value available.
  • Outcome (success/denied) conveyed by text + icon, not color alone.

Não-escopo

  • The event-ingestion pipeline / storage backend (observe / kdb).
  • Application logs / debug logging (policies/observability-first.kmd).
  • The tamper-evidence cryptography itself (a backend contract).

References