feat: standardized audit logging schema and service

[ravisuhag]

Context

The previous auth/audit package was too simple — flat actor string, no target, no org scoping, no event publishing. Meanwhile frontier has a rich audit system with typed actors/targets, org scoping, webhook publishing, and event filtering.

Every raystack service that needs audit logging builds its own. A shared schema would enable consistent audit trails across services.

Proposed solution

Salt provides the common schema and context helpers. Projects provide storage and publishing.

Schema

type Actor struct {
    ID   string
    Type string
    Name string
}

type Target struct {
    ID   string
    Type string
    Name string
}

type Log struct {
    ID        string
    OrgID     string
    Source     string
    Action    string
    Actor     Actor
    Target    Target
    Metadata  map[string]string
    CreatedAt time.Time
}

Interfaces

type Repository interface {
    Create(ctx context.Context, log *Log) error
    List(ctx context.Context, filter Filter) ([]Log, error)
    GetByID(ctx context.Context, id string) (Log, error)
}

Context helpers

audit.SetActor(ctx, Actor{ID: "user-123", Type: "user", Name: "alice"})
audit.SetMetadata(ctx, map[string]string{"ip": "1.2.3.4"})

What projects provide themselves

• Storage implementation (postgres, kafka, external service)
• Event name constants (app.user.created, etc.)
• Publishing/webhook integration
• Target helpers specific to their domain

Design questions

• Is OrgID universal enough for the schema? (Compass doesn't have orgs)
• Should Target support multiple targets per event?
• Should the schema include a Level (info/warn/critical)?

References

• Frontier's audit: core/audit/ — rich implementation with Actor/Target structs, webhook publishing
• Guardian's audit: used old salt/audit with simple string actor
• Previous auth/audit package dropped in salt evolution PR refactor: evolve salt into raystack service framework #85