Architecture
Immutable semantic security events, access boundaries, retention, and export workflows.
CentraKit audit logs are the product-facing security record for tenant and platform mutations. They are separate from operational telemetry, PostgreSQL/PGAudit diagnostics, and log drains, which remain debugging and infrastructure-observability tools.
The domain follows the standard provider-swappable service layers:
packages/platform/src/audit-log/ defines event schemas, the semantic event catalog, cursor encoding, errors, and AuditLogService.packages/supabase-platform/src/audit-log/ implements the service against Supabase.packages/core wires request-scoped services and trusted actors; apps never import the provider directly.Coverage is hybrid. Database triggers capture registered table mutations as a durable baseline, while application mutation adapters emit semantic events with business-level summaries, targets, outcomes, request IDs, correlation IDs, and idempotency keys. Auth and webhook boundaries use the same semantic model.
Audit recording must not add user-visible latency or turn a successful business mutation into a failure. Request paths schedule best-effort recording after the primary mutation; durable workflows record their own outcomes. Trigger capture remains the fallback for registered tables.
Audit rows are append-only. Application roles receive no update or delete grants; retention cleanup runs through privileged database functions.
Safe metadata is limited to 4 KiB and rejects credential, cookie, password, secret, session, and token-like keys. Restricted request context is stored separately and excludes secrets and tokens. Organization views mask platform-admin actor identity. Revealing restricted fields requires a dedicated permission and writes another semantic audit event.
Overview lists use offset pages with an exact filtered count so the table can share the same sort, filter, and pagination chrome as other hubs. Export workflows still walk stable keyset cursors over (occurred_at, id).
/{orgSlug}/audit-log and /{orgSlug}/audit-log/{eventId}/admin/audit-log and /admin/audit-log/{eventId}Organization reads are always scoped by the organization resolved from the route. Platform reads may span organizations. The navigation entries and page guards require OrgPerm.auditLog.view or SysPerm.auditLog.view.
Permissions are split by operation:
organization.audit-log.view|export|revealsystem.audit-log.view|export|revealCSV exports are asynchronous Workflow jobs. Requests normalize a bounded date range, then the workflow reads cursor pages, applies row and byte limits, writes a private storage object, and exposes it for 24 hours. Restricted fields are available only for authorized platform exports. Export request, completion, failure, download, and reveal operations are audited.
A daily workflow deletes expired export objects before marking jobs expired and purges audit events in bounded batches. Default retention is 1 day for Starter, 7 days for Pro, 90 days for Business, and 365 days for Enterprise. Enterprise subscriptions may set a platform-managed organization override.