bvandeusenandClaude Opus 5.5
d191a28217
Comment blocks in cmd/minstrel and 30 smaller internal packages, rewritten
to rule 32's standard with each citation read in context: task, milestone
and rule ids go, and so do the stories they were attached to ("used to",
"Before #N", measurements from one install, quotes, pointers to Fabled
Librarian's records and to docs/superpowers files that are not in the
repo). Where a story wrapped a real constraint, the constraint stays as a
present-tense fact.
Comments that had gone stale are corrected:
- taste.Config: the tuned values are overlaid by internal/recsettings;
it is no longer "a later follow-up".
- StorageConfig: the data dir holds art, caches and the stream secret,
not only playlist covers.
- the Subsonic album list and getUser comments describe what they do
today rather than a milestone that would change it.
Checked: the non-comment token stream of every changed file matches
HEAD, and gofmt -l is empty.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
111 lines
4.4 KiB
Go
111 lines
4.4 KiB
Go
// Package audit writes admin-driven user-management events to audit_log.
|
|
// Thin wrapper over the sqlc-generated WriteAuditLog query — the value
|
|
// is centralizing the action-name vocabulary and the metadata
|
|
// marshaling so callers don't repeat boilerplate.
|
|
//
|
|
// Audit writes are best-effort from the caller's perspective: a failed
|
|
// audit write must NOT fail the user-facing operation. Callers
|
|
// log-and-continue. The audit log is observability, not a transaction
|
|
// participant.
|
|
package audit
|
|
|
|
import (
|
|
"context"
|
|
"encoding/json"
|
|
"log/slog"
|
|
|
|
"github.com/jackc/pgx/v5/pgtype"
|
|
"github.com/jackc/pgx/v5/pgxpool"
|
|
|
|
"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
|
|
)
|
|
|
|
// Action is the discriminator stored in audit_log.action. New values
|
|
// added in U2/U3 + future tasks; declare them here so callers don't
|
|
// stringly-type and so a future audit-search UI has a single source
|
|
// of truth for the vocabulary.
|
|
type Action string
|
|
|
|
const (
|
|
// U1
|
|
ActionRegister Action = "register"
|
|
ActionPromoteAdmin Action = "promote_admin"
|
|
ActionDemoteAdmin Action = "demote_admin"
|
|
ActionInviteCreate Action = "invite_create"
|
|
ActionInviteRedeem Action = "invite_redeem"
|
|
ActionInviteRevoke Action = "invite_revoke"
|
|
|
|
// U2 (declared early; callers in U1 don't use them yet, but
|
|
// having them here means U2's diff is purely additive on the
|
|
// caller side, not also touching this file).
|
|
ActionCreateUserAdmin Action = "create_user_admin"
|
|
ActionDeleteUser Action = "delete_user"
|
|
ActionPasswordResetAdmin Action = "password_reset_admin"
|
|
ActionAutoApproveToggle Action = "auto_approve_toggle"
|
|
|
|
// U3
|
|
ActionPasswordChangeSelf Action = "password_change_self"
|
|
ActionTokenRegenerate Action = "token_regenerate"
|
|
ActionForgotPasswordInit Action = "forgot_password_initiated"
|
|
ActionPasswordResetByEmail Action = "password_reset_via_email"
|
|
|
|
// Revoking sessions is what a user does when they think an account is
|
|
// compromised, so it is audited: the trail matters most exactly then.
|
|
ActionSessionRevoke Action = "session_revoke"
|
|
ActionSessionRevokeOthers Action = "session_revoke_others"
|
|
|
|
// Duplicate merge. Irreversible: a copy's file and row are removed
|
|
// and its history moved onto the copy kept. The metadata names both, so the
|
|
// log can answer "where did that file go" long after the report is gone.
|
|
ActionDuplicateMerge Action = "duplicate_merge"
|
|
// The resolver settling a group without a merge:
|
|
// dismissing two versions of a song that are not duplicates, and removing
|
|
// copies that filled another song's track slot (their tracks are kept,
|
|
// marked missing, and fetched again).
|
|
ActionDuplicateDismiss Action = "duplicate_dismiss"
|
|
ActionDuplicateWrongFile Action = "duplicate_wrong_file"
|
|
|
|
// Subsonic password: generated in Settings for t/s-only clients.
|
|
ActionSubsonicPasswordSet Action = "subsonic_password_set"
|
|
ActionSubsonicPasswordClear Action = "subsonic_password_clear"
|
|
)
|
|
|
|
// Write inserts one audit_log row. metadata is marshaled as JSON;
|
|
// nil metadata writes SQL NULL. Errors are returned so callers can
|
|
// log them — but per package doc, callers should NOT fail user-facing
|
|
// operations on audit-write failures.
|
|
//
|
|
// actorID may be a zero/invalid pgtype.UUID for system actions
|
|
// (e.g. self-registration where the new user is both actor and
|
|
// target — pass them as the same id, or pass invalid for actor and
|
|
// the new user as target).
|
|
func Write(ctx context.Context, pool *pgxpool.Pool, actorID, targetID pgtype.UUID, action Action, metadata map[string]any) error {
|
|
q := dbq.New(pool)
|
|
var jsonMeta []byte
|
|
if metadata != nil {
|
|
b, err := json.Marshal(metadata)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
jsonMeta = b
|
|
}
|
|
return q.WriteAuditLog(ctx, dbq.WriteAuditLogParams{
|
|
ActorID: actorID,
|
|
TargetID: targetID,
|
|
Action: string(action),
|
|
Metadata: jsonMeta,
|
|
})
|
|
}
|
|
|
|
// WriteOrLog writes the audit row; on error, logs at Warn and swallows
|
|
// (audit failures must not break user-facing operations — see package doc).
|
|
// Use this when the audit is observability, not gating; use Write directly
|
|
// when the caller needs strict semantics (e.g. tests).
|
|
func WriteOrLog(ctx context.Context, pool *pgxpool.Pool, logger *slog.Logger, actorID, targetID pgtype.UUID, action Action, metadata map[string]any) {
|
|
if err := Write(ctx, pool, actorID, targetID, action, metadata); err != nil {
|
|
if logger != nil {
|
|
logger.Warn("audit failed", "action", string(action), "err", err)
|
|
}
|
|
}
|
|
}
|