shithub Public

Watch 1 Fork 0 Star 0
Go · 5988 bytes Raw Blame History
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 ActionIssueStateChanged Action = "issue_state_changed"
64 ActionIssueLockChanged Action = "issue_lock_changed"
65 ActionIssueCommentCreated Action = "issue_comment_created"
66 ActionPullStateChanged Action = "pull_state_changed"
67 ActionPullMerged Action = "pull_merged"
68 ActionStarCreated Action = "star_created"
69 ActionStarDeleted Action = "star_deleted"
70 ActionWatchSet Action = "watch_set"
71 ActionWatchUnset Action = "watch_unset"
72 ActionRepoForked Action = "repo_forked"
73 ActionRepoForkSynced Action = "repo_fork_synced"
74
75 // S34 — site admin actions. Always recorded with the real admin's
76 // id in actor_id; impersonation flows additionally carry the
77 // impersonated user's id in meta.impersonated_user_id.
78 ActionAdminSiteAdminGranted Action = "admin_site_admin_granted"
79 ActionAdminSiteAdminRevoked Action = "admin_site_admin_revoked"
80 ActionAdminUserSuspended Action = "admin_user_suspended"
81 ActionAdminUserUnsuspended Action = "admin_user_unsuspended"
82 ActionAdminUserForceDeleted Action = "admin_user_force_deleted"
83 ActionAdminUserPasswordReset Action = "admin_user_password_reset"
84 ActionAdminRepoForceArchived Action = "admin_repo_force_archived"
85 ActionAdminRepoForceDeleted Action = "admin_repo_force_deleted"
86 ActionAdminJobRetried Action = "admin_job_retried"
87 ActionAdminJobDiscarded Action = "admin_job_discarded"
88 ActionAdminImpersonateStarted Action = "admin_impersonate_started"
89 ActionAdminImpersonateStopped Action = "admin_impersonate_stopped"
90 ActionAdminImpersonateWriteOn Action = "admin_impersonate_write_on"
91 )
92
93 // Target is a typed target-type constant.
94 type Target string
95
96 const (
97 TargetUser Target = "user"
98 TargetRepo Target = "repo"
99 TargetIssue Target = "issue"
100 TargetPull Target = "pull"
101 )
102
103 // Recorder writes audit rows. Bound to the sqlc queries handle.
104 type Recorder struct {
105 q *usersdb.Queries
106 }
107
108 // NewRecorder constructs a recorder.
109 func NewRecorder() *Recorder { return &Recorder{q: usersdb.New()} }
110
111 // Record inserts a single audit-log row. actorID is the user_id of the
112 // actor performing the action (use 0 for system / admin-CLI actions).
113 // targetID is the affected entity (use 0 for actions without a single
114 // concrete target).
115 //
116 // meta MUST be a JSON-serializable map; secrets and PII (tokens, raw
117 // passwords, etc.) MUST NOT appear here.
118 func (r *Recorder) Record(
119 ctx context.Context, db DBTX,
120 actorID int64, action Action, target Target, targetID int64, meta map[string]any,
121 ) error {
122 if action == "" || target == "" {
123 return errors.New("audit: action and target_type required")
124 }
125 if meta == nil {
126 meta = map[string]any{}
127 }
128 metaJSON, err := json.Marshal(meta)
129 if err != nil {
130 return fmt.Errorf("audit: marshal meta: %w", err)
131 }
132 var actorParam pgtype.Int8
133 if actorID != 0 {
134 actorParam = pgtype.Int8{Int64: actorID, Valid: true}
135 }
136 var targetParam pgtype.Int8
137 if targetID != 0 {
138 targetParam = pgtype.Int8{Int64: targetID, Valid: true}
139 }
140 return r.q.InsertAuditLog(ctx, db, usersdb.InsertAuditLogParams{
141 ActorID: actorParam,
142 Action: string(action),
143 TargetType: string(target),
144 TargetID: targetParam,
145 Meta: metaJSON,
146 })
147 }
148