Skip to content
GitHub

Strutvane 0.2 is still being built. These pages describe how it will work; anything marked "Coming in 0.2" doesn't exist yet. Release notes and support policy.

Audit

View as Markdownllms.txt

An audit log is a permanent list of important things that happened in your app: who signed in, who changed a role, who exported the customer list, who edited invoice 42 and what they changed. When a customer asks “who deleted this?”, or an auditor asks “who can prove nothing was tampered with?”, the audit log answers.

Each entry is an audit event: one record with who (the actor), what (the action), when, which record, and for changes, which fields went from what to what. Strutvane writes the security events for you and gives you recordAudit() for your own.

Record that someone exported the posts:

app/http/controllers/post-export.controller.ts
import { recordAudit } from '@strutvane/framework'
import type { HttpContext } from '@strutvane/framework'
import { auditSink } from '../../audit.ts'
export class PostExportController {
async store(ctx: HttpContext): Promise<Response> {
// … build the CSV …
await recordAudit(auditSink, { action: 'post.export', resource: { type: 'post' }, reason: 'monthly report' })
return ctx.json({ data: { rows: 128 } })
}
}

What you’ll see: one new event, stored with everything it needs:

{
"id": "0193a1e0-5c2d-7a4b-9e8f-0a1b2c3d4e5f",
"occurredAt": "2026-11-15T10:22:01.123Z",
"actor": { "id": "0193a1c2-7e4b-7c1d-9f2e-5a6b7c8d9e0f", "type": "user" },
"tenantId": "acme",
"action": "post.export",
"resource": { "type": "post" },
"reason": "monthly report",
"requestId": "01JD7Q6Y9X3V2K8M4N5P6R7S8T"
}

You passed only the action, resource and reason. The id (a time-ordered UUIDv7), the time (UTC), the actor, the tenant and the request id were taken from the current request for you.

Field Always there? What it is
id yes unique, sortable by time
occurredAt yes ISO-8601 time in UTC
actor yes (may be null) { id, type } of who did it; null for anonymous actions such as a failed sign-in
action yes what happened, as resource.verb: invoice.update, auth.login.failed, role.assign
tenantId with teams the team the action happened in
resource often { type, id? }: which record
changes for updates [{ field, from, to, redacted? }]
reason sometimes why: a comment, or the policy reason for a denial. Never personal data
requestId, traceId inside a request to find the matching log lines
ip, userAgent only if you pass them store them only where your privacy policy allows; the user agent is cut to 512 characters

The actor is stored as an id and a type only: no names, emails or roles. That keeps the log small and keeps personal data in one place (the users table), so erasing a person doesn’t mean rewriting history.

action must look like resource.verb, with at least one dot, at most 200 characters:

Good Refused
post.update, post.export, auth.login.failed, team.member.removed export, Post Update, post., .update

A bad name throws right away, so a typo can’t fill the log with junk:

TypeError: audit action must look like "resource.verb" (e.g. "invoice.update")

Pass the record before and after the change, and the event gets a list of what changed:

app/http/controllers/post.controller.ts
import { authorize, recordAudit, ResourceController, type HttpContext } from '@strutvane/framework'
import { auditSink } from '../../audit.ts'
import { Post } from '../../models/post.ts'
import { PostPolicy } from '../../policies/post.policy.ts'
export class PostController extends ResourceController<typeof Post> {
protected readonly model = Post
protected readonly policy = new PostPolicy()
async publish(ctx: HttpContext): Promise<Response> {
const post = await this.visible(ctx)
await authorize(this.policy, 'update', ctx.user, post, 'post')
const before = post.toJSON()
await post.update({ status: 'published' })
await recordAudit(auditSink, { action: 'post.publish', resource: { type: 'post', id: String(post.id) }, before, after: post.toJSON() })
return ctx.json({ data: post })
}
}

What you’ll see in the event:

"changes": [
{ "field": "status", "from": "draft", "to": "published" },
{ "field": "updated_at", "from": "2026-11-14T09:00:00.000Z", "to": "2026-11-15T10:22:01.000Z" }
]
You pass You get
before and after every field that changed
only after (before: null) a create: every field, from null
only before (after: null) a delete: every field, to null
neither no changes (an action without a diff, like an export)

Fields that didn’t change are left out. Dates are compared by time, objects key by key.

updated_at changes every time and tells you nothing. Pass ignore:

await recordAudit(auditSink, { action: 'post.publish', resource: { type: 'post', id: String(post.id) }, before, after }, { ignore: ['updated_at'] })

Fields whose names look secret (password, token, secret, api_key and the rest of the shared redaction list) are recorded as changed, but both values are replaced:

{ "field": "password", "from": "[REDACTED]", "to": "[REDACTED]", "redacted": true }

You still know the password was changed, and when, and by whom; you never store it. Secret keys inside JSON values are redacted too. Add your own names:

await recordAudit(auditSink, { action: 'user.update', resource: { type: 'user', id }, before, after }, { sensitive: ['salary', 'iban'] })

Pass the resource’s policy as maskFor, and every field that has a read rule is redacted the same way. The audit log then never shows a salary or an internal note to someone who later reads the log but may not read that field.

memoryAuditSink() keeps events in a list, for tests:

tests/feature/post-publish.test.ts
import { memoryAuditSink, recordAudit } from '@strutvane/framework'
import { expect, it } from 'vitest'
it('records a publish with the status change', async () => {
const sink = memoryAuditSink()
await recordAudit(sink, { action: 'post.publish', resource: { type: 'post', id: '42' }, before: { status: 'draft' }, after: { status: 'published' } }, { now: () => new Date('2026-11-15T10:00:00Z'), id: () => 'evt-1' })
expect(sink.events).toHaveLength(1)
expect(sink.events[0]?.changes).toEqual([{ field: 'status', from: 'draft', to: 'published' }])
})

What you’ll see:

✓ tests/feature/post-publish.test.ts (1 test) 4ms

now and id make the event predictable in tests. sink.clear() empties the list between tests. A planned assertAudited({ action, resource }) helper will do this through the HTTP test client; see Testing.

An audit sink is where events go: anything with a write(event) method. In 0.2 the framework provides the sink for you:

  • an append-only audit_events table in your database, owned by the framework, created by an ordinary migration and marked internal, so it never gets an automatic API or admin screen;
  • written in the same transaction as the change it describes: if the change rolls back, so does its audit event, and if the audit write fails, the change fails too.

Your own sink, for example to also send events to a security tool, is a small object:

app/audit.ts
import type { AuditSink } from '@strutvane/framework'
import type { AuditEvent } from '@strutvane/framework/contracts'
/** Sends each event to two places; the database write is the one that must succeed. */
export function teeSink(primary: AuditSink, copy: (event: AuditEvent) => Promise<void>): AuditSink {
return {
async write(event) {
await primary.write(event)
copy(event).catch(() => undefined) // a SIEM outage must never block the app
},
}
}

These events are written without any code of yours. They carry ids, methods and counts only: a test runs every auth feature and proves that no password, token, code, cookie, link or two-factor secret ever reaches an event.

Area Events (prototype names)
Sign-in login (with method), login.failed, lockout, logout, registered
Passwords password.changed (via settings or reset), password.rehashed
Email email.verified
Two-factor and passkeys two-factor.enabled, two-factor.disabled, recovery-codes.regenerated, recovery-code.used (with how many remain), passkey.added, passkey.removed
Sessions session.revoked (with a count)
API tokens token.created, token.revoked
Teams team.created, team.switched, team.invitation.created, team.invitation.accepted, team.member.changed
Impersonation impersonation.started, impersonation.stopped (impersonator id and user id; impersonating needs the impersonate ability)

The security model adds role and permission changes, data exports, tenant lifecycle, configuration changes made in the admin UI, and policy bypasses to the mandatory list.

A typical question, “who changed post 42?”:

app/http/controllers/post-history.controller.ts
// Planned: an ORM model over the audit table. Its name isn't final.
const events = await AuditEvent.query()
.where('resource_type', 'post')
.where('resource_id', '42')
.orderBy('occurred_at', 'desc')
.limit(50)
.get()

Remember that the audit log itself is sensitive (it shows who did what), so guard any screen that reads it with a policy that only admins pass.

  • Keep audit events as long as your rules require (often years). The planned prune registry (model:prune, phase 2) will let you set a retention per table.
  • Don’t put personal data in reason. Store ip and userAgent only where your privacy policy allows.
  • Erasing a person (GDPR) removes them from users; their audit events keep only an id, which then points nowhere.

@strutvane/activity-log (catalogue #18) adds what end users see: a History tab on every record, an activity feed, and an audit explorer over the framework’s table. The installer’s question 27, “Record who changed what”, installs it; until it’s published, the installer doesn’t show that question.

tenancyAudit() (from 0.1, for PostgreSQL) is a different tool with a similar name: it inspects your database and reports tables that row-level security doesn’t protect. It writes nothing to the audit log. See Teams & Tenancy.

The audit table lives in your app’s database, so it’s in the Docker database container or on your machine, wherever the rest of your data is. node strut db:shell opens a SQL prompt in either mode if you want to look at it directly.

“audit action must look like resource.verb”

Section titled ““audit action must look like resource.verb””
TypeError: audit action must look like "resource.verb" (e.g. "invoice.update")

Why: the action has no dot, starts with a capital or a digit, or has spaces. Fix: name it resource.verb:

await recordAudit(auditSink, { action: 'post.export' })

Why: it was recorded outside a request (a command, a queued job, a test), so there was no signed-in user to take it from. Fix: pass the actor yourself, or null on purpose for system actions:

await recordAudit(auditSink, { action: 'post.prune', actor: null, reason: 'nightly clean-up of old drafts' })

Why: every save changes updated_at. Fix: { ignore: ['updated_at'] }.

Why: its column name doesn’t look secret (pin, note_private), so the redaction list didn’t catch it. Fix: add it with sensitive: ['pin'], and mark the column .secret() in its migration so the API never sends it either.

The audit event was saved but the change wasn’t (or the other way round)

Section titled “The audit event was saved but the change wasn’t (or the other way round)”

Why: you wrote the event with a sink that isn’t part of the change’s transaction. Fix: write both in one transaction (the framework’s table sink does this for you in 0.2). See Transactions.