audit

package
v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 3, 2026 License: AGPL-3.0 Imports: 12 Imported by: 0

Documentation

Overview

Package audit writes the immutable audit log: who did what to which target, before and after, from where, and whether it was allowed.

Index

Constants

View Source
const (
	Allowed = "allowed"
	Denied  = "denied"
	Failed  = "error"
)

Result of an audited action.

View Source
const SummaryPartsKey = "summary_parts"

SummaryPartsKey holds a summary made of facts joined with " · " (kept messages and plain values), under TextsKey.

View Source
const TextsKey = "i18n"

TextsKey is the metadata member that holds an entry's kept lines.

Variables

View Source
var LanguageName func(l i18n.Lang, code string) string

LanguageName names a content language's code in a reader's language, as a label ("Spanish", "Tiếng Tây Ban Nha"): internal/languages' NameIn, set by the packages that keep languages (LanguageArg). Without it a language reads as its code.

Functions

func In

func In(t i18n.Text, l i18n.Lang, english string) string

In writes a kept line in a language, or returns english when it wasn't kept (or its message is gone).

func KeepParts

func KeepParts(meta map[string]any, key string, parts ...any) map[string]any

KeepParts sets a line of an entry's metadata ("summary", "outcome") made of facts joined with " · ", like KeepSummary: the English under key, the parts under TextsKey as key_parts.

func KeepReason

func KeepReason(meta map[string]any, t i18n.Text) (string, map[string]any)

KeepReason keeps the reason of an entry that ReputeCast wrote itself (a group mapping's "no longer in Okta group “Marketing”") and returns its English, for Event.Reason; the message goes to the metadata under TextsKey. Reasons people type are kept as they typed them.

func KeepSummary

func KeepSummary(meta map[string]any, parts ...any) map[string]any

KeepSummary sets an entry's summary made of facts joined with " · ": each part is a kept message (i18n.Text) or a plain value (string) that reads the same in every language, such as a name or a permission key.

func KeepText

func KeepText(meta map[string]any, key string, t i18n.Text) map[string]any

KeepText sets a line of an entry's metadata ("summary", "detail"…): its English under key, and the message under TextsKey.

func LanguageArg

func LanguageArg(code string) map[string]any

LanguageArg is a content language as an argument of a kept line: kept as its code and named when the line is read, in the reader's language.

func PrincipalFrom

func PrincipalFrom(ctx context.Context) *authz.Principal

PrincipalFrom returns the acting principal stored in ctx, if any.

func Render

func Render(t i18n.Text, l i18n.Lang) string

Render writes a kept message in a language, its kept messages among its arguments first (without their final period), its lists as the language writes a list and its languages by their names. It returns "" when a message isn't known, like i18n.Text.In.

func WithPrincipal

func WithPrincipal(ctx context.Context, p *authz.Principal) context.Context

WithPrincipal stores the acting principal in ctx.

func WithRequest

func WithRequest(ctx context.Context, r Request) context.Context

WithRequest stores request details in ctx for later entries.

Types

type Actor

type Actor struct {
	Type authz.ActorType
	ID   *uuid.UUID
	Name string
}

Actor identifies who acted.

type Event

type Event struct {
	WorkspaceID *uuid.UUID
	Action      string // dotted verb: "routing.update", "apikey.create", "auth.sign_in"
	TargetType  string
	TargetID    string
	TargetName  string
	Result      string
	Reason      string
	Before      any
	After       any
	Metadata    map[string]any
	// Actor overrides the actor taken from the context (system jobs, sign-in).
	Actor *Actor
}

Event is one audit entry. Use Log to write it.

type Kept

type Kept struct {
	Summary      i18n.Text         `json:"summary"`
	SummaryParts []json.RawMessage `json:"summary_parts"`
	Detail       i18n.Text         `json:"detail"`
	What         i18n.Text         `json:"what"`
	Target       i18n.Text         `json:"target"`
	Note         i18n.Text         `json:"note"`
	Outcome      i18n.Text         `json:"outcome"`
	OutcomeParts []json.RawMessage `json:"outcome_parts"`
	Reason       i18n.Text         `json:"reason"`
}

Kept are an entry's kept lines, read from its metadata.

func KeptIn

func KeptIn(metadata []byte) Kept

KeptIn reads the kept lines of an entry's metadata.

func (Kept) OutcomeIn

func (k Kept) OutcomeIn(l i18n.Lang, english string) string

OutcomeIn is what an agent's call did, in a language: the kept message, the kept parts joined with " · ", or english.

func (Kept) SummaryIn

func (k Kept) SummaryIn(l i18n.Lang, english string) string

SummaryIn is the entry's summary in a language: the kept message, the kept parts joined with " · ", or english.

type Logger

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

Logger writes audit entries. Writes go through the caller's transaction when one is passed, so an action and its audit entry commit together.

func New

func New(q store.Querier, log *slog.Logger) *Logger

New returns an audit logger.

func (*Logger) Log

func (l *Logger) Log(ctx context.Context, e Event) error

Log writes an entry using the logger's own connection.

func (*Logger) LogWith

func (l *Logger) LogWith(ctx context.Context, q store.Querier, e Event) error

LogWith writes an entry through q (for example a transaction's Queries).

func (*Logger) Observe

func (l *Logger) Observe(fn func(workspaceID uuid.UUID, action string))

Observe calls fn after each workspace entry is written: every state change writes one, so it is how in-process caches learn of changes (the count cache, review 2026-11 OP-12). fn runs on the writer's goroutine, possibly inside a transaction that later rolls back; it must be quick.

type Request

type Request struct {
	IP        *netip.Addr
	UserAgent string
	RequestID string
}

Request carries per-request details stored with every entry.

func RequestFrom

func RequestFrom(ctx context.Context) Request

RequestFrom returns the request details stored in ctx.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL