Documentation
¶
Overview ¶
Package audit provides best-effort audit event logging to EntDB.
Audit writes MUST NOT block the user flow or propagate errors — an EntDB outage must not break login. All failures are caught and logged via zap, never returned to callers.
Usage:
l := audit.NewLogger(writer, "tenant-1", zapLogger)
l.Log(ctx, audit.EventLoginSuccess,
audit.WithActor("user-42"),
audit.WithIP("10.0.0.1"),
audit.WithUserAgent("Mozilla/5.0"),
audit.WithDetails(map[string]any{"method": "password"}),
)
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type EventType ¶
type EventType string
EventType enumerates all auditable events. Values MUST stay in sync with schema.yaml AuditEvent enum_values.
const ( EventLoginSuccess EventType = "login_success" EventLoginFailure EventType = "login_failure" EventLoginLocked EventType = "login_locked" // login attempt while account is in lockout window EventAccountLocked EventType = "account_locked" // threshold tripped, lockout window opened EventLogout EventType = "logout" EventPasswordChanged EventType = "password_changed" EventPasswordReset EventType = "password_reset" EventTotpEnabled EventType = "totp_enabled" EventTotpDisabled EventType = "totp_disabled" EventTotpVerified EventType = "totp_verified" EventPasskeyAdded EventType = "passkey_added" EventPasskeyRemoved EventType = "passkey_removed" EventPasskeyUsed EventType = "passkey_used" EventSessionRevoked EventType = "session_revoked" EventUserInvited EventType = "user_invited" EventUserDeactivated EventType = "user_deactivated" EventUserReactivated EventType = "user_reactivated" EventUserDeleted EventType = "user_deleted" EventAdminResetPassword EventType = "admin_reset_password" EventOAuthLogin EventType = "oauth_login" EventQrLoginApproved EventType = "qr_login_approved" EventQrLoginRejected EventType = "qr_login_rejected" EventAdminHelpRequested EventType = "admin_help_requested" EventAdminHelpResolved EventType = "admin_help_resolved" EventPhoneVerificationRequested EventType = "phone_verification_requested" EventPhoneVerified EventType = "phone_verified" )
type Logger ¶
type Logger struct {
// contains filtered or unexported fields
}
Logger writes audit events to EntDB. All methods are best-effort.
By default, Log writes synchronously on the caller's goroutine. Call StartAsync to move writes to a background goroutine with a bounded queue, so the auth hot path is not gated on EntDB latency. Drops when the queue is full are counted and visible via DroppedCount.
func NewLogger ¶
func NewLogger(writer NodeWriter, tenantID string, logger *zap.Logger) *Logger
NewLogger creates an audit Logger.
A nil writer is tolerated — Log calls will be silently dropped with a warning, matching the best-effort contract.
func (*Logger) DroppedCount ¶ added in v0.6.0
DroppedCount returns the cumulative number of audit events dropped because the async queue was full. Useful for tests and Prometheus exporters.
func (*Logger) Log ¶
Log writes an audit event to EntDB. It never returns an error and never panics — failures are logged via zap and silently dropped.
func (*Logger) StartAsync ¶ added in v0.6.0
StartAsync switches Log into async mode: writes are enqueued on a bounded channel and drained by a background goroutine. queueSize must be > 0. Calling StartAsync more than once is a no-op. The returned Close func stops the flusher and drains pending writes; safe to call multiple times.
type NodeWriter ¶
type NodeWriter interface {
ExecuteAtomic(
ctx context.Context,
tenantID, actor string,
ops []entdb.Operation,
) (*entdb.CommitResult, error)
}
NodeWriter is the subset of EntDB operations needed by the audit logger. Accepting an interface rather than *entdb.DbClient makes the logger testable without a live gRPC connection.
type Option ¶
type Option func(*eventConfig)
Option configures a single Log call.
func WithDetails ¶
WithDetails attaches arbitrary key-value metadata to the event.
func WithSuccess ¶
WithSuccess sets whether the audited action succeeded.
func WithTarget ¶
WithTarget sets the target user for the audit event. When omitted, defaults to the actor (the event is about the actor themselves).
func WithUserAgent ¶
WithUserAgent sets the client User-Agent header value.
Source Files