audit

type DBLogger ¶ added in v1.0.1

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

DBLogger writes audit events to a SQL database table using database/sql. It is compatible with any database driver (PostgreSQL, MySQL, SQLite, etc.).

Default schema ¶

Run this migration before using DBLogger with the default column layout. For PostgreSQL use JSONB for meta; for MySQL/SQLite use TEXT.

CREATE TABLE audit_logs (
    id         BIGSERIAL PRIMARY KEY,            -- BIGINT AUTO_INCREMENT for MySQL
    event_id   TEXT,
    type       TEXT        NOT NULL,
    timestamp  TIMESTAMPTZ NOT NULL,             -- DATETIME for MySQL, TEXT for SQLite
    subject    TEXT,
    resource   TEXT,
    action     TEXT,
    result     TEXT,
    ip         TEXT,
    user_agent TEXT,
    request_id TEXT,
    meta       JSONB                             -- TEXT for MySQL/SQLite
);

CREATE INDEX audit_logs_type_idx      ON audit_logs(type);
CREATE INDEX audit_logs_subject_idx   ON audit_logs(subject);
CREATE INDEX audit_logs_timestamp_idx ON audit_logs(timestamp);

Custom schema ¶

If your database has a different audit table layout, supply your own INSERT statement and a mapper via WithCustomSchema — no migration needed.

Usage ¶

db, _ := sql.Open("pgx", os.Getenv("DATABASE_URL"))
logger := audit.NewDBLogger(db)

// Alongside the JSON logger:
combined := audit.NewMultiLogger(audit.NewJSONLogger(os.Stdout), logger)

func NewDBLogger(db *sql.DB, opts ...DBLoggerOption) *DBLogger

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

func (l *DBLogger) Ping(ctx context.Context) error

func (l *DBLogger) Recent(ctx context.Context, subject string, limit int) ([]Event, error)

type DBLoggerOption ¶ added in v1.0.1

type DBLoggerOption func(*DBLogger)

DBLoggerOption configures a DBLogger.

func WithCustomSchema(insertSQL string, mapper EventMapper) DBLoggerOption

const insertSQL = `INSERT INTO audit_logs
    (id, user_id, action, entity_type, entity_id, changes, ip_address, user_agent)
    VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`

mapper := func(e audit.Event) []any {
    return []any{
        e.ID,
        e.Subject,            // user_id
        e.Action,
        e.Resource,           // entity_type
        e.Meta["entity_id"],  // entity_id
        metaToJSON(e.Meta),   // changes
        e.IP,
        e.UserAgent,
    }
}

logger := audit.NewDBLogger(db, audit.WithCustomSchema(insertSQL, mapper))

func WithTableName(name string) DBLoggerOption

type Event ¶

type Event struct {
	// ID is a unique identifier for this event (set automatically by JSONLogger
	// if left empty — applications may set their own).
	ID string `json:"id,omitempty"`

	// Type classifies the event.
	Type EventType `json:"type"`

	// Timestamp is when the event occurred. Defaults to time.Now() when zero.
	Timestamp time.Time `json:"timestamp"`

	// Subject is the entity that performed the action (user ID, service name, etc.).
	Subject string `json:"subject,omitempty"`

	// Resource is the object that was acted upon (e.g. "posts/42", "users").
	Resource string `json:"resource,omitempty"`

	// Action is the operation that was attempted (e.g. "read", "delete").
	Action string `json:"action,omitempty"`

	// Result is the outcome of the event.
	Result Result `json:"result,omitempty"`

	// IP is the client IP address.
	IP string `json:"ip,omitempty"`

	// UserAgent is the client User-Agent string.
	UserAgent string `json:"user_agent,omitempty"`

	// RequestID correlates the event with an HTTP request trace.
	RequestID string `json:"request_id,omitempty"`

	// Meta holds arbitrary additional fields.
	Meta map[string]any `json:"meta,omitempty"`
}

Event represents a single auditable security action.

type EventBuilder ¶

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

EventBuilder provides a fluent API for constructing Events.

func Eventf(t EventType, subject string, result Result) *EventBuilder

audit.Eventf(audit.EventLogin, "user-123", audit.ResultAllow).WithIP("1.2.3.4")

func (b *EventBuilder) Build() Event

func (b *EventBuilder) Log(ctx context.Context) error

func (b *EventBuilder) Logf(ctx context.Context) string

func (b *EventBuilder) WithAction(action string) *EventBuilder

func (b *EventBuilder) WithIP(ip string) *EventBuilder

func (b *EventBuilder) WithMeta(key string, value any) *EventBuilder

func (b *EventBuilder) WithRequestID(id string) *EventBuilder

func (b *EventBuilder) WithResource(resource string) *EventBuilder

type EventMapper ¶ added in v1.0.2

type EventMapper func(e Event) []any

EventMapper converts an audit.Event into the positional SQL parameters for the caller's custom INSERT statement. The returned slice must have exactly as many elements as there are placeholders in the INSERT statement.

type EventType ¶

type EventType string

EventType classifies a security-relevant action.

const (
	// Authentication events.
	EventLogin       EventType = "auth.login"
	EventLoginFailed EventType = "auth.login_failed"
	EventLogout      EventType = "auth.logout"
	EventMFASuccess  EventType = "auth.mfa_success"
	EventMFAFailed   EventType = "auth.mfa_failed"

	// Token lifecycle.
	EventTokenIssued    EventType = "token.issued"
	EventTokenVerified  EventType = "token.verified"
	EventTokenRefreshed EventType = "token.refreshed"
	EventTokenRevoked   EventType = "token.revoked"
	EventTokenExpired   EventType = "token.expired"
	EventTokenInvalid   EventType = "token.invalid"

	// API key lifecycle.
	EventAPIKeyIssued  EventType = "apikey.issued"
	EventAPIKeyUsed    EventType = "apikey.used"
	EventAPIKeyRevoked EventType = "apikey.revoked"
	EventAPIKeyInvalid EventType = "apikey.invalid"

	// Authorisation decisions.
	EventAccessGranted EventType = "authz.access_granted"
	EventAccessDenied  EventType = "authz.access_denied"

	// Rate limiting.
	EventRateLimited EventType = "rate.limited"

	// Account management.
	EventPasswordChanged EventType = "account.password_changed"
	EventPasswordReset   EventType = "account.password_reset"
	EventAccountLocked   EventType = "account.locked"
	EventAccountUnlocked EventType = "account.unlocked"
)

type JSONLogger ¶

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

JSONLogger writes newline-delimited JSON events to an io.Writer. Each event is a single JSON object terminated by a newline — compatible with log aggregators such as Loki, Datadog, CloudWatch, and Splunk.

func NewJSONLogger(w io.Writer) *JSONLogger

func (l *JSONLogger) Log(_ context.Context, e Event) error

type Logger ¶

type Logger interface {
	Log(ctx context.Context, event Event) error
}

Logger is the sink for audit events.

func FromContext(ctx context.Context) Logger

type MultiLogger ¶

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

MultiLogger fans out events to multiple loggers. All loggers are called even when one returns an error; the first error is returned.

func NewMultiLogger(loggers ...Logger) *MultiLogger

func (m *MultiLogger) Log(ctx context.Context, e Event) error

type NOOPLogger ¶

type NOOPLogger struct{}

NOOPLogger discards all events. Useful in tests or when audit logging is optional.

func (NOOPLogger) Log(_ context.Context, _ Event) error

type Result ¶

type Result string

Result is the outcome of a security event.

const (
	ResultAllow   Result = "allow"
	ResultDeny    Result = "deny"
	ResultUnknown Result = "unknown"
)