audit

Documentation

Overview

Package audit persists control-plane mutations into a queryable, tenant-scoped log. Two scopes: tenant events are readable by the org's admins (/api/teams/{id}/audit); platform events (super-admin actions on orgs/users) are super-admin only (/api/admin/audit).

Writes are best-effort from the HTTP handlers (detached, logged on failure) — the audit trail is an operations/compliance surface, not a transactional ledger.

Index

• Constants
• Variables
• func ClampLimit(n int) int
• func EnsureSchema(ctx context.Context, db *mongo.Database) error
• type Event
• type MemoryStore
  • func NewMemoryStore() *MemoryStore
  • func (s *MemoryStore) Insert(_ context.Context, e Event) error
  • func (s *MemoryStore) ListByTenant(_ context.Context, tenantID string, p Page) ([]Event, error)
  • func (s *MemoryStore) ListPlatform(_ context.Context, p Page) ([]Event, error)
• type MongoStore
  • func NewMongoStore(db *mongo.Database) *MongoStore
  • func (s *MongoStore) Insert(ctx context.Context, e Event) error
  • func (s *MongoStore) ListByTenant(ctx context.Context, tenantID string, p Page) ([]Event, error)
  • func (s *MongoStore) ListPlatform(ctx context.Context, p Page) ([]Event, error)
• type Page
• type Scope
• type Store

Constants

const RetentionDays = 400

RetentionDays bounds audit retention (Mongo TTL). 400 days covers an annual compliance cycle with margin; longer retention belongs in an exported archive, not the live collection.

Variables

var ErrNotFound = errors.New("audit: not found")

ErrNotFound is reserved for symmetric store semantics.

Functions

func ClampLimit

func ClampLimit(n int) int

ClampLimit normalises a caller-supplied page size.

func EnsureSchema

func EnsureSchema(ctx context.Context, db *mongo.Database) error

EnsureSchema creates the audit indexes idempotently.

Types

type Event

type Event struct {
	ID        string         `bson:"_id" json:"id"`
	Scope     Scope          `bson:"scope" json:"scope"`
	TenantID  string         `bson:"tenant_id,omitempty" json:"tenant_id,omitempty"`
	ActorID   string         `bson:"actor_id,omitempty" json:"actor_id,omitempty"`
	ActorKind string         `bson:"actor_kind,omitempty" json:"actor_kind,omitempty"` // user|super_admin|webhook|system
	Action    string         `bson:"action" json:"action"`
	Target    string         `bson:"target,omitempty" json:"target,omitempty"` // kind of object acted on (org|user|webhook|secret|binding|byok|member|invitation|token)
	TargetID  string         `bson:"target_id,omitempty" json:"target_id,omitempty"`
	Meta      map[string]any `bson:"meta,omitempty" json:"meta,omitempty"`
	IP        string         `bson:"ip,omitempty" json:"ip,omitempty"`
	UserAgent string         `bson:"user_agent,omitempty" json:"user_agent,omitempty"`
	CreatedAt time.Time      `bson:"created_at" json:"created_at"`
}

Event is one audit row. Action is a stable dotted token (e.g. "org.status_changed", "byok.created", "webhook.rotated") — the queryable contract; Meta carries small action-specific details (never secret material).

type MemoryStore

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

MemoryStore is the in-process audit log for tests and local mode. Keep semantics in lock-step with MongoStore.

func NewMemoryStore

func NewMemoryStore() *MemoryStore

func (*MemoryStore) Insert

func (s *MemoryStore) Insert(_ context.Context, e Event) error

func (*MemoryStore) ListByTenant

func (s *MemoryStore) ListByTenant(_ context.Context, tenantID string, p Page) ([]Event, error)

func (*MemoryStore) ListPlatform

func (s *MemoryStore) ListPlatform(_ context.Context, p Page) ([]Event, error)

type MongoStore

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

MongoStore is the production audit log.

func NewMongoStore

func NewMongoStore(db *mongo.Database) *MongoStore

func (*MongoStore) Insert

func (s *MongoStore) Insert(ctx context.Context, e Event) error

func (*MongoStore) ListByTenant

func (s *MongoStore) ListByTenant(ctx context.Context, tenantID string, p Page) ([]Event, error)

func (*MongoStore) ListPlatform

func (s *MongoStore) ListPlatform(ctx context.Context, p Page) ([]Event, error)

type Page

type Page struct {
	Offset  int
	Limit   int
	Action  string
	ActorID string
	From    time.Time
	To      time.Time
}

Page bounds + filters a listing. Zero values mean "no filter".

type Scope

type Scope string

Scope partitions readability.

const (
	// ScopeTenant events are visible to the org's admins.
	ScopeTenant Scope = "tenant"
	// ScopePlatform events (super-admin actions) are platform-only.
	ScopePlatform Scope = "platform"
)

type Store

type Store interface {
	Insert(ctx context.Context, e Event) error
	// ListByTenant returns tenant-scoped events for one org, newest
	// first.
	ListByTenant(ctx context.Context, tenantID string, p Page) ([]Event, error)
	// ListPlatform returns platform-scoped events, newest first.
	ListPlatform(ctx context.Context, p Page) ([]Event, error)
}

Store persists and lists audit events. Implementations: MongoStore (production) and MemoryStore (tests/local). Keep in lock-step.