Audit Logs

@repo/audit records who did what to which entity - admin actions, billing changes, and auth security events - into the audit_logs table. It has no config flag: audit logging is always-on infrastructure, gated only by read access (platform and org admins) and a retention window.

Recording an entry

In a request handler, build a request-scoped logger that pre-fills actor, IP, and user-agent, then call .log(action, entityType, entityId, options?).

import { AUDIT_ACTIONS, createAuditContext } from "@repo/audit";

const auditCtx = createAuditContext(c.req.raw, session); // actorType from session role
await auditCtx.log(AUDIT_ACTIONS.USER_DELETED, "user", userId);

Every write path routes through audit(), so a logging failure can never break the caller's flow - no try/catch needed at the call site.

Actions and metadata

AUDIT_ACTIONS (packages/audit/src/types.ts) is the single source of truth for what can be audited - pass a constant, never a raw string.

entityType is "user" | "organization"; actorType is "user" | "admin" | "system" | "api_key". The metadata JSON column is free-form, but typed shapes are exported for structured detail.

Reading logs

Two routes read the table. Both paginate and enrich rows via enrichLogsWithEntityDetails, which attaches the current entityName, entityImage, and entityEmail from the live user or org - so an entry still shows a readable label after a rename.

Six indexes back these queries: four composite (entity, org, action, actor, each paired with timestamp), a standalone audit_logs_timestamp_idx, and a partial audit_logs_impersonated_by_idx (WHERE impersonated_by IS NOT NULL) that keeps the impersonation review query cheap.

Retention

A weekly maintenance job deletes rows older than cacheConfig.retentionDays.auditLogs (default 90 days); adjust it in packages/config/src/cache.ts. See Background jobs for the scheduler.