| 1 | // SPDX-License-Identifier: AGPL-3.0-or-later |
| 2 | |
| 3 | // Package audit writes structured rows into the auth_audit_log table for |
| 4 | // security-relevant events. The schema is generic — actor, action, target, |
| 5 | // meta JSON — so future sprints reuse this for permission changes, |
| 6 | // org-membership changes, admin actions, etc. |
| 7 | // |
| 8 | // Callers MUST NOT put secret material in the meta JSON. The values land |
| 9 | // unredacted in the DB; treat the table contents as confidential but |
| 10 | // never sensitive (no plaintext passwords, no TOTP secrets, no PATs). |
| 11 | package audit |
| 12 | |
| 13 | import ( |
| 14 | "context" |
| 15 | "encoding/json" |
| 16 | "errors" |
| 17 | "fmt" |
| 18 | |
| 19 | "github.com/jackc/pgx/v5/pgtype" |
| 20 | |
| 21 | usersdb "github.com/tenseleyFlow/shithub/internal/users/sqlc" |
| 22 | ) |
| 23 | |
| 24 | // DBTX matches sqlc's DBTX so callers can pass *pgxpool.Pool or a tx. |
| 25 | type DBTX = usersdb.DBTX |
| 26 | |
| 27 | // Action is a typed action constant. Reuse these across packages so the |
| 28 | // set stays tight and grep-able. |
| 29 | type Action string |
| 30 | |
| 31 | const ( |
| 32 | Action2FAEnabled Action = "2fa_enabled" |
| 33 | Action2FADisabled Action = "2fa_disabled" |
| 34 | ActionRecoveryCodesIssued Action = "recovery_codes_issued" |
| 35 | ActionRecoveryCodeUsed Action = "recovery_code_used" |
| 36 | ActionRecoveryRegenerated Action = "recovery_codes_regenerated" |
| 37 | ActionAdminCleared2FA Action = "admin_cleared_2fa" |
| 38 | ActionPasswordChanged Action = "password_changed" |
| 39 | ActionPasswordReset Action = "password_reset_consumed" |
| 40 | ActionLoginSucceeded Action = "login_succeeded" |
| 41 | ActionLoginFailedThrottled Action = "login_failed_throttled" |
| 42 | ActionAccountSuspended Action = "account_suspended" |
| 43 | ActionSSHKeyAdded Action = "ssh_key_added" |
| 44 | ActionSSHKeyDeleted Action = "ssh_key_deleted" |
| 45 | ActionPATCreated Action = "pat_created" |
| 46 | ActionPATRevoked Action = "pat_revoked" |
| 47 | ActionUsernameChanged Action = "username_changed" |
| 48 | ActionAccountDeleted Action = "account_deleted" |
| 49 | ActionAccountRestored Action = "account_restored" |
| 50 | ActionRepoCreated Action = "repo_created" |
| 51 | ActionRepoRenamed Action = "repo_renamed" |
| 52 | ActionRepoArchived Action = "repo_archived" |
| 53 | ActionRepoUnarchived Action = "repo_unarchived" |
| 54 | ActionRepoVisibilityChanged Action = "repo_visibility_changed" |
| 55 | ActionRepoSoftDeleted Action = "repo_soft_deleted" |
| 56 | ActionRepoRestored Action = "repo_restored" |
| 57 | ActionRepoHardDeleted Action = "repo_hard_deleted" |
| 58 | ActionRepoTransferRequested Action = "repo_transfer_requested" |
| 59 | ActionRepoTransferAccepted Action = "repo_transfer_accepted" |
| 60 | ActionRepoTransferDeclined Action = "repo_transfer_declined" |
| 61 | ActionRepoTransferCanceled Action = "repo_transfer_canceled" |
| 62 | ActionRepoTransferExpired Action = "repo_transfer_expired" |
| 63 | ) |
| 64 | |
| 65 | // Target is a typed target-type constant. |
| 66 | type Target string |
| 67 | |
| 68 | const ( |
| 69 | TargetUser Target = "user" |
| 70 | TargetRepo Target = "repo" |
| 71 | ) |
| 72 | |
| 73 | // Recorder writes audit rows. Bound to the sqlc queries handle. |
| 74 | type Recorder struct { |
| 75 | q *usersdb.Queries |
| 76 | } |
| 77 | |
| 78 | // NewRecorder constructs a recorder. |
| 79 | func NewRecorder() *Recorder { return &Recorder{q: usersdb.New()} } |
| 80 | |
| 81 | // Record inserts a single audit-log row. actorID is the user_id of the |
| 82 | // actor performing the action (use 0 for system / admin-CLI actions). |
| 83 | // targetID is the affected entity (use 0 for actions without a single |
| 84 | // concrete target). |
| 85 | // |
| 86 | // meta MUST be a JSON-serializable map; secrets and PII (tokens, raw |
| 87 | // passwords, etc.) MUST NOT appear here. |
| 88 | func (r *Recorder) Record( |
| 89 | ctx context.Context, db DBTX, |
| 90 | actorID int64, action Action, target Target, targetID int64, meta map[string]any, |
| 91 | ) error { |
| 92 | if action == "" || target == "" { |
| 93 | return errors.New("audit: action and target_type required") |
| 94 | } |
| 95 | if meta == nil { |
| 96 | meta = map[string]any{} |
| 97 | } |
| 98 | metaJSON, err := json.Marshal(meta) |
| 99 | if err != nil { |
| 100 | return fmt.Errorf("audit: marshal meta: %w", err) |
| 101 | } |
| 102 | var actorParam pgtype.Int8 |
| 103 | if actorID != 0 { |
| 104 | actorParam = pgtype.Int8{Int64: actorID, Valid: true} |
| 105 | } |
| 106 | var targetParam pgtype.Int8 |
| 107 | if targetID != 0 { |
| 108 | targetParam = pgtype.Int8{Int64: targetID, Valid: true} |
| 109 | } |
| 110 | return r.q.InsertAuditLog(ctx, db, usersdb.InsertAuditLogParams{ |
| 111 | ActorID: actorParam, |
| 112 | Action: string(action), |
| 113 | TargetType: string(target), |
| 114 | TargetID: targetParam, |
| 115 | Meta: metaJSON, |
| 116 | }) |
| 117 | } |
| 118 |