Enrichment

ORM adapters capture raw audit data — table name, operation, before/after snapshots. Enrichment layers on human-readable meaning: labels, severity levels, compliance tags, and dynamic descriptions. You register rules once and they apply automatically to every matching entry, without touching your route handlers or service code.

audit.enrich() — the API

audit.enrich(table, operation, config)

• table — SQL table name, or "*" for all tables.
• operation — "INSERT", "UPDATE", "DELETE", or "*" for all operations.
• config — enrichment options (see sections below).

Three typical patterns:

src/audit.ts

import { betterAudit } from "@usebetterdev/audit";
import { drizzleAuditAdapter } from "@usebetterdev/audit/drizzle";

const audit = betterAudit({
  database: drizzleAuditAdapter(db),
  auditTables: ["users", "payments", "orders"],
});

// Pattern 1: specific table + specific operation
audit.enrich("users", "DELETE", {
  label: "User account deleted",
  severity: "critical",
  compliance: ["gdpr"],
});

// Pattern 2: specific table + all operations
audit.enrich("payments", "*", {
  severity: "high",
  compliance: ["pci"],
});

// Pattern 3: global default — all tables, all operations
audit.enrich("*", "*", {
  severity: "low",
  compliance: ["soc2"],
});

You can call audit.enrich() as many times as you like. Rules for the same table/operation pair accumulate — they are merged according to the specificity rules below.

Human-readable labels

The label field attaches a short, human-readable name to an audit entry. Without enrichment, entries only carry raw table names and operations:

// Without enrichment
{ "tableName": "users", "operation": "DELETE", "recordId": "u_123" }

// With enrichment
{ "tableName": "users", "operation": "DELETE", "recordId": "u_123", "label": "User account deleted" }

Set a label per rule:

audit.enrich("users", "INSERT", { label: "New user registered" });
audit.enrich("users", "UPDATE", { label: "User profile updated" });
audit.enrich("users", "DELETE", { label: "User account deleted" });

Precedence: if label is passed directly to captureLog(), it takes precedence over the registry label. The registry fills the gap when no per-call label is set.

Severity levels

Four severity levels are available: "low", "medium", "high", "critical".

Operation	Suggested severity
INSERT	"low"
UPDATE (non-sensitive)	"medium"
DELETE	"high"
DELETE on PII tables	"critical"
Bulk mutations	"high" or "critical"

audit.enrich("*", "INSERT", { severity: "low" });
audit.enrich("*", "UPDATE", { severity: "medium" });
audit.enrich("*", "DELETE", { severity: "high" });

// Override for sensitive tables
audit.enrich("users", "DELETE", { severity: "critical" });
audit.enrich("payments", "*", { severity: "high" });

Compliance tags

The compliance field attaches framework tags to entries. Common values: "gdpr", "soc2", "hipaa", "pci".

When multiple rules match, compliance arrays are concatenated and deduplicated — more specific rules add to, rather than replace, tags from less specific ones:

// Tier 1: global default — applies to every entry
audit.enrich("*", "*", {
  compliance: ["soc2"],
});

// Tier 4: specific rule — adds "gdpr" for user deletes
audit.enrich("users", "DELETE", {
  compliance: ["gdpr"],
});

// Result for users DELETE: ["soc2", "gdpr"]
// Result for orders INSERT: ["soc2"]

Tag values are freeform strings — use whatever your compliance team standardises on.

Dynamic descriptions

The description option is a function called at write time with context about the mutation. Use it to generate richer, event-specific descriptions beyond what a static label provides:

audit.enrich("users", "UPDATE", {
  label: "User profile updated",
  description: ({ before, after, diff, actorId }) => {
    const fields = diff?.changedFields.join(", ") ?? "unknown fields";
    return `Actor ${actorId ?? "unknown"} changed: ${fields}`;
  },
});

EnrichmentDescriptionContext

Field	Type	Description
before	Record<string, unknown> | undefined	Pre-mutation row snapshot.
after	Record<string, unknown> | undefined	Post-mutation row snapshot.
diff	{ changedFields: string[] } | undefined	Fields that changed between before and after.
actorId	string | undefined	Actor from the current context.
metadata	Record<string, unknown> | undefined	Merged metadata from the current context.

Caution

The before, after, and diff fields contain post-redaction data. If you use redact or include on the same rule (or a less specific rule), redacted fields will be absent from what the description function sees. Use this intentionally — do not read sensitive fields inside description that you also redact.

Error handling: if the description function throws, the error is swallowed and description is left unset on the log entry. The entry is still written.

Notifications

The notify flag marks an entry for downstream notification integrations. Setting it to true does not trigger anything on its own — it is a signal for external systems (webhooks, alerting pipelines) that consume the audit log to act on the entry:

audit.enrich("users", "DELETE", {
  label: "User account deleted",
  severity: "critical",
  notify: true,
});

Like label and severity, notify is a scalar — more specific tiers overwrite less specific ones.

Custom metadata

There are two ways to attach metadata to audit entries.

Per-request metadata via context

Use mergeAuditContext() to inject metadata into the current request scope. Every captureLog() call inside the callback inherits it:

Hono

src/routes/users.ts

import { Hono } from "hono";
import { mergeAuditContext } from "@usebetterdev/audit";

const app = new Hono();

app.delete("/users/:id", async (c) => {
  await mergeAuditContext(
    { metadata: { requestId: c.req.header("x-request-id"), region: "eu-west-1" } },
    async () => {
      await deleteUser(c.req.param("id"));
    },
  );
  return c.json({ ok: true });
});

Express

src/routes/users.ts

import express from "express";
import { mergeAuditContext } from "@usebetterdev/audit";

const router = express.Router();

router.delete("/users/:id", async (req, res, next) => {
  try {
    await mergeAuditContext(
      { metadata: { requestId: req.headers["x-request-id"], region: "eu-west-1" } },
      async () => {
        await deleteUser(req.params.id);
      },
    );
    res.json({ ok: true });
  } catch (error) {
    next(error);
  }
});

See the Actor Context guide for full details on context propagation.

Static metadata via beforeLog hooks

For metadata that is the same for every entry — environment, service name, version — use a beforeLog hook:

src/audit.ts

import { betterAudit } from "@usebetterdev/audit";
import { drizzleAuditAdapter } from "@usebetterdev/audit/drizzle";

const audit = betterAudit({
  database: drizzleAuditAdapter(db),
  auditTables: ["users"],
  beforeLog: [
    (log) => {
      log.metadata = {
        ...log.metadata,
        environment: process.env.NODE_ENV,
        service: "api",
      };
    },
  ],
});

Note

Metadata is not subject to redaction. redact and include only apply to beforeData and afterData. Avoid storing PII directly in metadata.

Specificity tiers and rule merging

When multiple rules match an event, they are resolved from least to most specific:

Tier	Pattern	Matches
1 (least specific)	"*", "*"	All tables, all operations
2	"*", "DELETE"	All tables, specific operation
3	"users", "*"	Specific table, all operations
4 (most specific)	"users", "DELETE"	Specific table, specific operation

Merge rules:

• Scalar fields (label, severity, description, notify): last-write-wins — more specific tiers overwrite less specific ones.
• Array fields (compliance, redact, include): concatenated and deduplicated across all matching tiers.

// Tier 1
audit.enrich("*", "*", {
  severity: "low",
  compliance: ["soc2"],
});

// Tier 3
audit.enrich("users", "*", {
  severity: "medium",          // overwrites "low"
  compliance: ["internal"],    // merged → ["soc2", "internal"]
});

// Tier 4
audit.enrich("users", "DELETE", {
  severity: "critical",        // overwrites "medium"
  compliance: ["gdpr"],        // merged → ["soc2", "internal", "gdpr"]
});

// users DELETE resolves to: severity="critical", compliance=["soc2", "internal", "gdpr"]
// users INSERT resolves to: severity="medium",   compliance=["soc2", "internal"]
// orders DELETE resolves to: severity="low",     compliance=["soc2"]

Field redaction

Control which fields appear in beforeData and afterData snapshots. Two modes are available — use one or the other.

Blocklist (redact)

Remove specific fields. Everything else is kept:

audit.enrich("users", "*", {
  redact: ["password", "ssn", "secret_key"],
});
// beforeData: { id: "1", name: "Alice", password: "hash" }
// stored as:  { id: "1", name: "Alice" }

Allowlist (include)

Keep only the listed fields. Everything else is removed:

audit.enrich("users", "*", {
  include: ["id", "email", "name"],
});
// beforeData: { id: "1", name: "Alice", email: "[email protected]", password: "hash", ssn: "123" }
// stored as:  { id: "1", name: "Alice", email: "[email protected]" }

Caution

redact and include are mutually exclusive. Setting both on the same enrichment rule throws at registration time. Setting them on different rules that resolve to the same event also throws at write time.

Caution

Only top-level keys are matched. To redact a nested field like profile.ssn, list the parent key "profile" — the entire object is removed.

When fields are redacted, the redactedFields column on the audit entry records which fields were removed. This is useful for compliance audits that need proof sensitive data was excluded.

Processing order

When a log entry is written, enrichment is applied in this order:

1. Field redaction — redact / include applied to beforeData, afterData, diff.changedFields
2. Description function — called with post-redaction data; result stored in description (only if not already set per-call)
3. Scalar and array fields — label, severity, compliance, notify applied (only fill gaps; per-call values and context values take precedence)
4. beforeLog hooks — run on the fully enriched log

Next steps

• Compliance Overview — map SOC 2, HIPAA, GDPR, and PCI DSS requirements to Better Audit features
• Configuration — full betterAudit() options reference, retention, and lifecycle hooks
• Actor Context — per-request metadata, mergeAuditContext(), and audit.withContext()
• Adapters — middleware setup, actor extractors, and error handling