Gram Audit Logging

Audit logging is how Gram records who did what to which resource. Every meaningful mutation on a project- or org-scoped resource is expected to produce one audit entry per affected row, written inside the same database transaction as the mutation so events can't drift from the state they describe. Entries are exposed to Gram users through the auditlogs management API.

Concepts and terminology

Actor. The principal that caused the event — a urn.Principal carrying a type (user, role, service account) and an id, with optional display name and slug for human rendering.

Subject. The resource the event is about — identified by a subject type (e.g. remote_mcp_server, access_role) and a subject id.

Action. What happened to the subject. Each subject declares its own set of actions, typically one per mutating verb on the subject's life cycle.

Before/after snapshot. Optional opaque JSON payloads describing the subject's state. Populated on updates, left empty on creates and deletes unless the snapshot is independently useful.

Metadata. Optional JSON bag for contextual fields that are not part of the subject's state.

Scoping. Every entry belongs to exactly one organization and zero or one projects. Org-scoped subjects (roles, members) carry no project id; project-scoped subjects carry the project UUID.

Atomicity. Audit entries are written inside the same database transaction as the mutation they describe, so the state and the record of the state commit together or not at all.

Outbox event. Every audit entry also publishes a typed webhook event to the outbox (same transaction). The event type is subject-specific — e.g. audit_log.deployment_event_v1 for deployment actions, audit_log.project_event_v1 for project actions — allowing webhook subscribers to filter by subject domain rather than receiving all audit activity under the single legacy audit_log.created type. The _v1 suffix signals the version; new event definitions must use this suffix. All subject event vars are declared in server/internal/outbox/events/audit_log.go.

Server

Audit logging lives in server/internal/audit/ with its management-API surface defined in server/design/auditlogs/. Callers are other services whose handlers emit events; the auditlogs Goa service reads them back.

Conventions

Where types live. The package-private subjectType string type and every subjectType* constant live in server/internal/audit/events.go. The public Action string type and the marshalAuditPayload snapshot helper live in the same file. The subject-type const block is kept alphabetised.

Subject type naming. Subject type values are short snake_case strings (e.g. remote_mcp_server, access_role). Constants follow the subjectType<Name> pattern.

Action naming. Values follow <subject-slug>:<verb> (e.g. remote-mcp:create, access_role:update). Verbs are typically create / update / delete; subjects may add feature-specific verbs (toolset:attach_oauth_proxy).

Subject files. One Go file per subject under server/internal/audit/, named after the subject in plural form (e.g. remotemcpservers.go, toolsets.go). Each file owns that subject's Action* constants, its Log*Event payload structs, and its Log* functions. Do not merge subjects into a shared file.

Log*Event and Log* naming. One Log<Verb>Event struct plus one Log<Verb> function per action, declared in the subject file. Log* functions take (ctx, dbtx repo.DBTX, event Log*Event) error so the audit insert is atomic with the caller's mutation. Internally each Log* function constructs a repo.InsertAuditLogParams and then calls l.log(ctx, dbtx, auditEntry{Params: entry, OutboxEvent: events.<Subject>}) — it does not call repo.New(dbtx).InsertAuditLog directly.

Subject identifier fields. Event structs carry the subject's identifier as a URN type, not a raw uuid.UUID. Field name is <Subject>URN (e.g. KeyURN urn.APIKey, McpServerURN urn.McpServer), and the Log* function populates SubjectID from event.<Subject>URN.ID.String(). If no URN type exists yet, add one under server/internal/urn/ before introducing the event struct — see server/internal/urn/api_key.go for the template.

Snapshot fields. Update event structs declare snapshot fields as <Subject>SnapshotBefore / <Subject>SnapshotAfter with concrete pointer types (e.g. *types.Toolset, *types.McpServer). Do not use any or bare SnapshotBefore / SnapshotAfter — the typed form keeps marshalAuditPayload callers honest about the shape being persisted. Pass the view through directly unless a specific field on the type needs stripping for size or sensitivity reasons (see toolsets.go for the one clone-and-strip case).

Per-row events for bulk mutations. A single bulk SQL statement that touches N rows of an audited subject produces N audit entries — one per row — not one entry that covers the batch. This is what makes the audit log a faithful reconstruction of each subject's life cycle and what lets auditlogs.list filter to a specific subject id. The most common place this gets missed is cascading soft-deletes that fan out from a parent delete; see "How to audit a cascading delete of child resources" under "Jobs to be done".

Non-generated files

Generated files

Files under server/gen/** and any repo/ subdirectory carry a DO NOT EDIT header.

Server-client contract

Audit entries are surfaced to Gram users through a small, fixed set of endpoints. New actions and subject types appear automatically — facets are computed from the rows that exist, so there is no registration step outside the Go code.

HTTP routes (design: server/design/auditlogs/design.go):

• GET /rpc/auditlogs.list — paginated list; supports cursor, project_slug, actor_id, and action filters.
• GET /rpc/auditlogs.listFacets — returns the set of actors and actions that actually appear, for UI facet pickers.

Generated client surfaces — regenerated by mise run gen:goa-server then mise run gen:sdk:

• TypeScript SDK: client/dashboard/src/sdk/src/funcs/auditlogs*.ts, client/dashboard/src/sdk/src/react-query/auditlogs*.ts, plus models under client/dashboard/src/sdk/src/models/.
• CLI bindings: server/gen/http/cli/gram/cli.go.

Jobs to be done

How to audit a handler in a service

When a handler mutates a resource whose subject already has Action*/Log* definitions, the handler opts in by calling the existing Log* function. The call has to happen inside the same dbtx as the mutation so the audit row and the state it describes commit together.

1. Open the service's impl.go and locate the handler. Confirm the handler already uses a transaction; if not, wrap the repo calls in s.db.Begin(ctx) → defer o11y.NoLogDefer(rollback) → dbtx.Commit(ctx).
2. After the primary repo writes succeed and before Commit, call the subject's audit.Log<Verb> with a populated Log<Verb>Event. Pass the same dbtx the repo writes used so the audit row commits atomically with them.
3. Build the actor from contextvalues.GetAuthContext(ctx) — typically urn.NewPrincipal(urn.PrincipalTypeUser, authCtx.UserID), plus authCtx.Email for ActorDisplayName. Principal types live in server/internal/urn. Fill in the subject-specific identifier fields (subject id, display name, slug) from the repo row you just wrote.
4. For updates, populate the typed snapshot fields (<Subject>SnapshotBefore / <Subject>SnapshotAfter) with the pre- and post-mutation state. For creates and deletes, leave them nil unless the snapshot is independently useful.
5. Treat audit-log failures as oops.CodeUnexpected. Audit logging is not optional — if it fails, fail the request.
6. Add a test that asserts the event was recorded (see "How to assert audit events in tests" below).