audit

Package audit defines audit events and the Recorder contract that any module uses to record who did what to which resource, and whether it worked. Storage lives in separate modules (for example auditpg).

Audit events are not application logs: they have their own retention, integrity and access rules (ADR-0026).

Stability: pre-1.0 (ADR-0015).

Types#

type Event#

type Event struct {
	// OccurredAt is set by recorders when zero.
	OccurredAt time.Time

	ActorKind  actor.Kind
	ActorID    string
	ActorLabel string

	// Action is a dotted, past-tense name namespaced by module, such as
	// "auth.session.revoked". Action names are public API (ADR-0015).
	Action string

	ResourceType string
	ResourceID   string
	Outcome      Outcome
	OrgID        string

	RequestID string
	TraceID   string
	IP        string
	UserAgent string

	// Metadata holds structured detail. Recorders apply redaction rules.
	Metadata map[string]any
}

An Event records one audited action.

func FromContext#

func FromContext(ctx context.Context, e Event) Event

FromContext returns e with empty actor, organisation, request and trace fields filled from ctx.

func (Event) Validate#

func (e Event) Validate() error

Validate reports whether e has a well-formed action and a known outcome.

type LogRecorder#

type LogRecorder struct {
	// contains filtered or unexported fields
}

LogRecorder writes audit events to a structured logger. It is meant for development and apps without an audit store; metadata is not logged.

func NewLogRecorder#

func NewLogRecorder(logger *slog.Logger) *LogRecorder

NewLogRecorder returns a recorder logging to logger.

func (*LogRecorder) Record#

func (r *LogRecorder) Record(ctx context.Context, e Event) error

Record validates e, fills it from ctx and logs it.

type Outcome#

type Outcome string

Outcome is the result of an audited action.

const OutcomeSuccess, …#

const (
	OutcomeSuccess Outcome = "success"
	OutcomeFailure Outcome = "failure"
	OutcomeDenied  Outcome = "denied"
)

Outcomes.

type Recorder#

type Recorder interface {
	Record(ctx context.Context, e Event) error
}

A Recorder stores audit events. Implementations must be safe for concurrent use and return an error when the event can't be stored.

type RecorderFunc#

type RecorderFunc func(ctx context.Context, e Event) error

RecorderFunc adapts a function to the Recorder interface.

func (RecorderFunc) Record#

func (f RecorderFunc) Record(ctx context.Context, e Event) error

Record calls f(ctx, e).