Add Your Own Audit Events

Declare an action and a scope type in audit.config.ts and record it from a page action, a cron or a queue job.

Your actions live in apps/web/config/audit.config.ts. The kit's own kit.* actions are merged in for you; you can't declare one yourself.

Declare an Action and a Scope Type

A scope type is the kind of owner an event belongs to. organization and user are built in; add your own (here project) in scopes:

import { z } from 'zod';
import { defineAuditConfig } from '@kit/audit';
export const auditConfig = defineAuditConfig({
scopes: ['project'],
actions: {
'project.deleted': {
scope: 'project',
severity: 'warning', // info | warning | critical
metadata: z.object({ fileCount: z.number() }),
},
'organization.exported': {
scope: 'organization',
severity: 'info',
},
},
});

Rules, checked when the app starts (and by the types):

  • A scope type matches [a-z][a-z0-9_-]*, at most 31 characters.
  • An action's scope is built in or declared in scopes.
  • Names starting with kit. are reserved.
  • Metadata is a flat z.object of strings, numbers, booleans, enums or literals (optional is fine), at most 1 KB once serialized. Keys called email, ip, name, phone or address, and email or IP string formats (z.email(), z.string().email(), z.ipv4()…), are refused: ids only. These checks catch honest mistakes; they can't see what a plain z.string() holds, so never put a person's details in metadata or in an id.

Record It

Call recordAudit from #/lib/audit.server.ts after the write has committed. The actor is the signed-in user (the admin while impersonating); you can't pass one:

import { defineHandler } from 'void';
import { recordAudit } from '#/lib/audit.server.ts';
export const actions = {
deleteProject: defineHandler.withValidator({ body: deleteBody })(
async (c, { body }) => {
const organization = requireActiveOrganization({ c });
const { fileCount } = await deleteProject(body.projectId);
recordAudit({
c,
action: 'project.deleted',
scope: { type: 'project', id: body.projectId },
target: { type: 'project', id: body.projectId },
organizationId: organization.id,
metadata: { fileCount },
});
return c.redirect('/projects');
},
),
};

For a cron, queue job or webhook there is no session: use recordSystemAudit({ system: 'nightly-sync', action, scope, metadata }).

Scope ids and other ids are printable ASCII, at most 64 characters, without :. An id of an organization or user scope can't name a different organization or user than the scope.

Record only after the write commits: an event for a rolled-back write would be false. Never put a person's details in metadata.