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
scopeis built in or declared inscopes. - Names starting with
kit.are reserved. - Metadata is a flat
z.objectof strings, numbers, booleans, enums or literals (optional is fine), at most 1 KB once serialized. Keys calledemail,ip,name,phoneoraddress, 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 plainz.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.