@johnnyboy11234/esg-idea-contest 0.1.0 → 0.2.0

package/backend/db/migration/V002__audit_log_full.sql

@@ -0,0 +1,32 @@
+-- V002 (B1-03): the remaining audit_log columns (PRD 6.11 "Fields"). Expand-only: V001 created
+-- the skeleton (id, occurred_at); the table is still empty, so NOT NULL columns are safe.
+-- Append-only: application code only INSERTs (test/arch scans for anything else).
+-- "before" / "after" are reserved words in MariaDB, hence before_json / after_json.
+-- No foreign keys: a row must outlive the user or Idea it describes.
+
+ALTER TABLE audit_log
+    ADD COLUMN request_id       UUID              NULL     COMMENT 'X-Request-Id of the request' AFTER occurred_at,
+    ADD COLUMN actor_emp_no     VARCHAR(64)       NULL     COMMENT 'NULL for ANONYMOUS and SYSTEM' AFTER request_id,
+    ADD COLUMN actor_role       VARCHAR(16)       NOT NULL AFTER actor_emp_no,
+    ADD COLUMN action           VARCHAR(40)       NOT NULL AFTER actor_role,
+    ADD COLUMN outcome          VARCHAR(16)       NOT NULL AFTER action,
+    ADD COLUMN target_type      VARCHAR(16)       NULL     AFTER outcome,
+    ADD COLUMN target_id        UUID              NULL     AFTER target_type,
+    ADD COLUMN method           VARCHAR(8)        NULL     AFTER target_id,
+    ADD COLUMN route            VARCHAR(200)      NULL     COMMENT 'route template, never the raw path' AFTER method,
+    ADD COLUMN status           SMALLINT UNSIGNED NULL     AFTER route,
+    ADD COLUMN error_code       VARCHAR(64)       NULL     AFTER status,
+    ADD COLUMN ip               INET6             NULL     AFTER error_code,
+    ADD COLUMN user_agent       VARCHAR(256)      NULL     AFTER ip,
+    ADD COLUMN submitted_emp_no VARCHAR(64)       NULL     COMMENT 'sanitized employee ID typed into a failed login or registration' AFTER user_agent,
+    ADD COLUMN before_json      JSON              NULL     AFTER submitted_emp_no,
+    ADD COLUMN after_json       JSON              NULL     AFTER before_json,
+    -- Reserved for the optional hash chain (PRD 9 #5); nothing writes them yet.
+    ADD COLUMN prev_hash        BINARY(32)        NULL,
+    ADD COLUMN hash             BINARY(32)        NULL,
+    ADD CONSTRAINT ck_audit_log_actor_role  CHECK (actor_role IN ('USER', 'ADMIN', 'ANONYMOUS', 'SYSTEM')),
+    ADD CONSTRAINT ck_audit_log_outcome     CHECK (outcome IN ('SUCCESS', 'FAILED', 'DENIED', 'THROTTLED')),
+    ADD CONSTRAINT ck_audit_log_target_type CHECK (target_type IS NULL OR target_type IN ('USER', 'IDEA', 'DEADLINE')),
+    ADD KEY ix_audit_log_actor (actor_emp_no, occurred_at, id),
+    ADD KEY ix_audit_log_request (request_id),
+    ADD KEY ix_audit_log_target (target_id, occurred_at, id);

package/backend/db/migration/V003__app_user.sql

@@ -0,0 +1,36 @@
+-- V003 (B1-05): app_user, the one table for Users and Admins (PRD 4, 6.3).
+-- Field rules are enforced here as well as in Go, so no code path can store a value the API would reject.
+--   emp_no     exactly 6 ASCII digits (string; keeps leading zeros)
+--   name       1-50 code points, no control characters, none of  / \ : * ? " < > |  (PRD 6.2 #5, #8);
+--              the NFC / whitespace clean-up itself is done by shared/text before the INSERT
+--   email      printable ASCII only, no whitespace, one '@' with non-empty sides, <= 254, already lower-cased (OI-14);
+--              unique byte-exact (utf8mb4_bin). NULL only for Admins, who have no email (PRD 4).
+--   password_hash  bcrypt, cost 10 only (PRD 6.4, OI-13)
+-- Enumerations are VARCHAR + CHECK, never ENUM. Times are database time in UTC.
+
+CREATE TABLE app_user (
+    id            UUID         NOT NULL DEFAULT UUID(),
+    emp_no        CHAR(6)      NOT NULL,
+    name          VARCHAR(50)  NOT NULL,
+    email         VARCHAR(254) NULL,
+    password_hash CHAR(60)     NOT NULL,
+    role          VARCHAR(8)   NOT NULL,
+    -- Every authenticated request checks this (PRD 4); an Admin removed from Vault is disabled, not deleted.
+    enabled       BOOLEAN      NOT NULL DEFAULT TRUE,
+    created_at    DATETIME(6)  NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+    updated_at    DATETIME(6)  NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6),
+    PRIMARY KEY (id),
+    UNIQUE KEY uq_app_user_emp_no (emp_no),
+    -- Several NULLs are allowed (Admins); non-NULL values are unique.
+    UNIQUE KEY uq_app_user_email (email),
+    CONSTRAINT ck_app_user_emp_no CHECK (CHAR_LENGTH(emp_no) = 6 AND emp_no NOT REGEXP '[^0-9]'),
+    CONSTRAINT ck_app_user_name_length CHECK (CHAR_LENGTH(name) BETWEEN 1 AND 50),
+    CONSTRAINT ck_app_user_name_chars CHECK (name NOT REGEXP '[[:cntrl:]]' AND name NOT REGEXP '[/\\\\:*?"<>|]'),
+    CONSTRAINT ck_app_user_email CHECK (email IS NULL OR (
+        email NOT REGEXP '[^!-~]'
+        AND email = LOWER(email)
+        AND email REGEXP '^[^@]+@[^@]+$')),
+    CONSTRAINT ck_app_user_hash CHECK (password_hash REGEXP '^[$]2[aby][$]10[$][./A-Za-z0-9]{53}$'),
+    CONSTRAINT ck_app_user_role CHECK (role IN ('USER', 'ADMIN')),
+    CONSTRAINT ck_app_user_email_by_role CHECK ((role = 'USER' AND email IS NOT NULL) OR (role = 'ADMIN' AND email IS NULL))
+) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE = utf8mb4_bin;

package/backend/internal/audit/event.go

@@ -0,0 +1,119 @@
+// Package audit writes the Audit Log (PRD §6.11, Backend.md §7). Two tracks:
+//
+//   - Record joins the caller's transaction, so a successful write and its audit
+//     row commit or roll back together (fail-closed).
+//   - RecordRejected opens its own transaction for DENIED / FAILED / THROTTLED
+//     rows; it is best effort and counts its failures.
+//
+// The table is append-only: this package only ever INSERTs.
+package audit
+
+import (
+	"encoding/json"
+	"net/netip"
+
+	"github.com/google/uuid"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/security"
+)
+
+// Action is the audit action (PRD §6.11).
+type Action string
+
+// The recorded actions.
+const (
+	AuthRegister        Action = "AUTH_REGISTER"
+	AuthLogin           Action = "AUTH_LOGIN"
+	AuthLogout          Action = "AUTH_LOGOUT"
+	IdeaCreate          Action = "IDEA_CREATE"
+	IdeaUpdate          Action = "IDEA_UPDATE"
+	IdeaDelete          Action = "IDEA_DELETE"
+	IdeaView            Action = "IDEA_VIEW"
+	SlidesReplace       Action = "SLIDES_REPLACE"
+	SlidesDownload      Action = "SLIDES_DOWNLOAD"
+	JoinRequestCreate   Action = "JOIN_REQUEST_CREATE"
+	JoinRequestApprove  Action = "JOIN_REQUEST_APPROVE"
+	JoinRequestReject   Action = "JOIN_REQUEST_REJECT"
+	JoinRequestWithdraw Action = "JOIN_REQUEST_WITHDRAW"
+	MemberRemove        Action = "MEMBER_REMOVE"
+	MemberLeave         Action = "MEMBER_LEAVE"
+	DeadlineUpdate      Action = "DEADLINE_UPDATE"
+	AdminSync           Action = "ADMIN_SYNC"
+	AuditQuery          Action = "AUDIT_QUERY"
+)
+
+var actions = map[Action]bool{
+	AuthRegister: true, AuthLogin: true, AuthLogout: true,
+	IdeaCreate: true, IdeaUpdate: true, IdeaDelete: true, IdeaView: true,
+	SlidesReplace: true, SlidesDownload: true,
+	JoinRequestCreate: true, JoinRequestApprove: true, JoinRequestReject: true, JoinRequestWithdraw: true,
+	MemberRemove: true, MemberLeave: true,
+	DeadlineUpdate: true, AdminSync: true, AuditQuery: true,
+}
+
+// Valid reports whether a is a known action.
+func (a Action) Valid() bool { return actions[a] }
+
+// Outcome is the result of the audited operation.
+type Outcome string
+
+// The outcomes. SUCCESS goes through Record; the other three are rejected
+// attempts and go through RecordRejected (ADMIN_SYNC FAILED may use either).
+const (
+	Success   Outcome = "SUCCESS"
+	Failed    Outcome = "FAILED"
+	Denied    Outcome = "DENIED"
+	Throttled Outcome = "THROTTLED"
+)
+
+// Valid reports whether o is a known outcome.
+func (o Outcome) Valid() bool {
+	return o == Success || o == Failed || o == Denied || o == Throttled
+}
+
+// TargetType is the kind of resource a row is about.
+type TargetType string
+
+// The target types. DEADLINE has no ID.
+const (
+	TargetUser     TargetType = "USER"
+	TargetIdea     TargetType = "IDEA"
+	TargetDeadline TargetType = "DEADLINE"
+)
+
+// Valid reports whether t is a known target type.
+func (t TargetType) Valid() bool {
+	return t == TargetUser || t == TargetIdea || t == TargetDeadline
+}
+
+// Event is one audit row. The request ID and, unless overridden, the actor come
+// from the context; occurred_at is the database clock.
+type Event struct {
+	Action  Action
+	Outcome Outcome
+
+	// Actor override. Needed where the context has no principal yet (a login
+	// that just succeeded) or the actor is not the caller (ADMIN_SYNC). When
+	// ActorRole is empty both fields come from the context.
+	ActorRole  security.ActorRole
+	ActorEmpNo string
+
+	TargetType TargetType
+	TargetID   uuid.UUID // uuid.Nil = none
+
+	Method    string
+	Route     string // route template, e.g. /ideas/{id}
+	Status    int    // HTTP status; 0 = none
+	ErrorCode string
+	IP        netip.Addr // zero = none
+	UserAgent string
+
+	// SubmittedEmpNo is the raw employee ID typed into a failed login or
+	// registration; it is sanitized before it is stored.
+	SubmittedEmpNo string
+
+	// Before and After are JSON documents (changed fields only). Secrets are
+	// redacted by key name before they are stored.
+	Before json.RawMessage
+	After  json.RawMessage
+}

package/backend/internal/audit/integration_test.go

@@ -0,0 +1,270 @@
+//go:build integration
+
+package audit_test
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"net/netip"
+	"strings"
+	"testing"
+
+	"github.com/google/uuid"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/audit"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/db"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/dbtest"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/security"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/web"
+)
+
+type row struct {
+	RequestID, ActorEmpNo, TargetType, TargetID, Method, Route, ErrorCode, IP, UserAgent, Submitted sql.NullString
+	ActorRole, Action, Outcome                                                                      string
+	Status                                                                                          sql.NullInt64
+	Before, After                                                                                   sql.NullString
+	PrevHash, Hash                                                                                  []byte
+	OccurredAtSet                                                                                   bool
+}
+
+// floor is the highest audit_log.id before the current subtest; rows() sees only newer rows. The
+// table is append-only, so tests never clear it (test/arch scans for that).
+var floor int64
+
+func rows(t *testing.T, d *sql.DB) []row {
+	t.Helper()
+	rs, err := d.Query(`SELECT request_id, actor_emp_no, target_type, target_id, method, route, error_code,
+	  ip, user_agent, submitted_emp_no, actor_role, action, outcome, status, before_json, after_json,
+	  prev_hash, hash, occurred_at IS NOT NULL FROM audit_log WHERE id > ? ORDER BY id`, floor)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer rs.Close()
+	var out []row
+	for rs.Next() {
+		var r row
+		if err := rs.Scan(&r.RequestID, &r.ActorEmpNo, &r.TargetType, &r.TargetID, &r.Method, &r.Route, &r.ErrorCode,
+			&r.IP, &r.UserAgent, &r.Submitted, &r.ActorRole, &r.Action, &r.Outcome, &r.Status, &r.Before, &r.After,
+			&r.PrevHash, &r.Hash, &r.OccurredAtSet); err != nil {
+			t.Fatal(err)
+		}
+		out = append(out, r)
+	}
+	if err := rs.Err(); err != nil {
+		t.Fatal(err)
+	}
+	return out
+}
+
+func reset(t *testing.T, d *sql.DB) {
+	t.Helper()
+	if err := d.QueryRow(`SELECT COALESCE(MAX(id), 0) FROM audit_log`).Scan(&floor); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestAudit(t *testing.T) {
+	d := dbtest.New(t)
+	svc := audit.New(d, nil)
+	reqID := uuid.NewString()
+
+	// Request ID is stored by web.RequestID middleware; reproduce it through the real middleware.
+	ctxWithReq := func(principal *security.Principal) context.Context {
+		var got context.Context
+		h := web.RequestID(handlerFunc(func(ctx context.Context) { got = ctx }))
+		h.ServeHTTP(httptest.NewRecorder(), newReq(reqID))
+		if principal != nil {
+			return security.WithPrincipal(got, *principal)
+		}
+		return got
+	}
+
+	t.Run("track A is written in the caller's transaction and carries every field", func(t *testing.T) {
+		reset(t, d)
+		ctx := ctxWithReq(&security.Principal{UserID: 7, EmpNo: "E0001", Role: security.RoleUser})
+		target := uuid.New()
+		out, err := db.InTx(ctx, d, func(ctx context.Context, tx *sql.Tx) error {
+			return svc.Record(ctx, tx, audit.Event{
+				Action: audit.IdeaUpdate, Outcome: audit.Success,
+				TargetType: audit.TargetIdea, TargetID: target,
+				Method: "PATCH", Route: "/ideas/{id}", Status: 200,
+				IP: netip.MustParseAddr("203.0.113.9"), UserAgent: "ua",
+				Before: []byte(`{"name":"a"}`), After: []byte(`{"name":"b","password":"p"}`),
+			})
+		})
+		if err != nil || out != db.Committed {
+			t.Fatalf("InTx = %v, %v", out, err)
+		}
+		got := rows(t, d)
+		if len(got) != 1 {
+			t.Fatalf("rows = %d, want 1", len(got))
+		}
+		r := got[0]
+		if r.RequestID.String != reqID || r.ActorEmpNo.String != "E0001" || r.ActorRole != "USER" ||
+			r.Action != "IDEA_UPDATE" || r.Outcome != "SUCCESS" || r.TargetType.String != "IDEA" ||
+			r.TargetID.String != target.String() || r.Method.String != "PATCH" || r.Route.String != "/ideas/{id}" ||
+			r.Status.Int64 != 200 || r.UserAgent.String != "ua" || !r.OccurredAtSet {
+			t.Errorf("row = %+v", r)
+		}
+		if r.IP.String != "::ffff:203.0.113.9" {
+			t.Errorf("ip = %q (IPv4 is stored as INET6 mapped)", r.IP.String)
+		}
+		if r.Before.String != `{"name": "a"}` && r.Before.String != `{"name":"a"}` {
+			t.Errorf("before = %q", r.Before.String)
+		}
+		if strings.Contains(r.After.String, "\"p\"") || !strings.Contains(r.After.String, "[REDACTED]") {
+			t.Errorf("password not redacted: %q", r.After.String)
+		}
+		if r.PrevHash != nil || r.Hash != nil {
+			t.Error("hash-chain columns must stay NULL")
+		}
+	})
+
+	t.Run("track A rolls back with the transaction", func(t *testing.T) {
+		reset(t, d)
+		boom := errors.New("business failure")
+		out, err := db.InTx(context.Background(), d, func(ctx context.Context, tx *sql.Tx) error {
+			if err := svc.Record(ctx, tx, audit.Event{Action: audit.AuthLogout, Outcome: audit.Success}); err != nil {
+				return err
+			}
+			return boom
+		})
+		if !errors.Is(err, boom) || out != db.RolledBack {
+			t.Fatalf("InTx = %v, %v", out, err)
+		}
+		if n := len(rows(t, d)); n != 0 {
+			t.Errorf("rows = %d, want 0 (rolled back with the business write)", n)
+		}
+	})
+
+	t.Run("track A failure fails the operation", func(t *testing.T) {
+		reset(t, d)
+		out, err := db.InTx(context.Background(), d, func(ctx context.Context, tx *sql.Tx) error {
+			return svc.Record(ctx, tx, audit.Event{Action: "BOGUS", Outcome: audit.Success})
+		})
+		if err == nil || out != db.RolledBack {
+			t.Errorf("InTx = %v, %v; want RolledBack and an error", out, err)
+		}
+	})
+
+	t.Run("track B persists although the business transaction rolled back", func(t *testing.T) {
+		reset(t, d)
+		ctx := ctxWithReq(nil)
+		_, err := db.InTx(ctx, d, func(ctx context.Context, tx *sql.Tx) error {
+			svc.RecordRejected(ctx, audit.Event{
+				Action: audit.IdeaDelete, Outcome: audit.Denied, TargetType: audit.TargetIdea,
+				TargetID: uuid.New(), Method: "DELETE", Route: "/ideas/{id}", Status: 404, ErrorCode: "NOT_FOUND",
+			})
+			return errors.New("rejected")
+		})
+		if err == nil {
+			t.Fatal("want error")
+		}
+		got := rows(t, d)
+		if len(got) != 1 || got[0].Outcome != "DENIED" || got[0].ActorRole != "ANONYMOUS" ||
+			got[0].ActorEmpNo.Valid || got[0].ErrorCode.String != "NOT_FOUND" || got[0].RequestID.String != reqID {
+			t.Errorf("rows = %+v", got)
+		}
+	})
+
+	t.Run("track B survives a cancelled request context", func(t *testing.T) {
+		reset(t, d)
+		ctx, cancel := context.WithCancel(context.Background())
+		cancel()
+		svc.RecordRejected(ctx, audit.Event{Action: audit.AuthLogin, Outcome: audit.Failed, SubmittedEmpNo: "E0009"})
+		if got := rows(t, d); len(got) != 1 || got[0].Submitted.String != "E0009" {
+			t.Errorf("rows = %+v", got)
+		}
+	})
+
+	t.Run("track B failure is counted, not returned", func(t *testing.T) {
+		reset(t, d)
+		before := svc.RejectedFailures()
+		svc.RecordRejected(context.Background(), audit.Event{Action: "BOGUS", Outcome: audit.Denied})
+		if svc.RejectedFailures() != before+1 {
+			t.Error("failure not counted")
+		}
+		if n := len(rows(t, d)); n != 0 {
+			t.Errorf("rows = %d", n)
+		}
+	})
+
+	t.Run("hostile input is sanitized and truncated, never fatal", func(t *testing.T) {
+		reset(t, d)
+		svc.RecordRejected(context.Background(), audit.Event{
+			Action: audit.AuthLogin, Outcome: audit.Failed,
+			UserAgent:      strings.Repeat("創", 1000) + "\r\nforged",
+			SubmittedEmpNo: "E1\x00\n" + strings.Repeat("9", 500),
+			Route:          strings.Repeat("r", 1000), ErrorCode: strings.Repeat("c", 1000),
+		})
+		got := rows(t, d)
+		if len(got) != 1 {
+			t.Fatalf("rows = %d, want 1", len(got))
+		}
+		r := got[0]
+		if n := len([]rune(r.UserAgent.String)); n != 256 {
+			t.Errorf("user agent = %d code points, want 256", n)
+		}
+		if strings.ContainsAny(r.Submitted.String, "\x00\n") || len(r.Submitted.String) != 64 {
+			t.Errorf("submitted = %q", r.Submitted.String)
+		}
+		if len(r.Route.String) != 200 || len(r.ErrorCode.String) != 64 {
+			t.Errorf("route/errorCode lengths = %d/%d", len(r.Route.String), len(r.ErrorCode.String))
+		}
+	})
+
+	t.Run("actor override wins over the context", func(t *testing.T) {
+		reset(t, d)
+		ctx := security.WithSystem(context.Background())
+		_, err := db.InTx(ctx, d, func(ctx context.Context, tx *sql.Tx) error {
+			return svc.Record(ctx, tx, audit.Event{Action: audit.AuthLogin, Outcome: audit.Success,
+				ActorRole: security.ActorAdmin, ActorEmpNo: "A0001", TargetType: audit.TargetUser, TargetID: uuid.New()})
+		})
+		if err != nil {
+			t.Fatal(err)
+		}
+		if r := rows(t, d)[0]; r.ActorRole != "ADMIN" || r.ActorEmpNo.String != "A0001" {
+			t.Errorf("row = %+v", r)
+		}
+	})
+
+	t.Run("system actor and deadline target without an ID", func(t *testing.T) {
+		reset(t, d)
+		ctx := security.WithSystem(context.Background())
+		_, err := db.InTx(ctx, d, func(ctx context.Context, tx *sql.Tx) error {
+			return svc.Record(ctx, tx, audit.Event{Action: audit.AdminSync, Outcome: audit.Success,
+				TargetType: audit.TargetDeadline, After: []byte(`null`)})
+		})
+		if err != nil {
+			t.Fatal(err)
+		}
+		if r := rows(t, d)[0]; r.ActorRole != "SYSTEM" || r.TargetID.Valid || r.After.Valid {
+			t.Errorf("row = %+v", r)
+		}
+	})
+
+	t.Run("database CHECKs reject values outside the sets", func(t *testing.T) {
+		for _, stmt := range []string{
+			`INSERT INTO audit_log (actor_role, action, outcome) VALUES ('ROOT', 'X', 'SUCCESS')`,
+			`INSERT INTO audit_log (actor_role, action, outcome) VALUES ('USER', 'X', 'MAYBE')`,
+			`INSERT INTO audit_log (actor_role, action, outcome, target_type) VALUES ('USER', 'X', 'SUCCESS', 'TEAM')`,
+		} {
+			if _, err := d.Exec(stmt); err == nil {
+				t.Errorf("accepted: %s", stmt)
+			}
+		}
+	})
+}
+
+type handlerFunc func(ctx context.Context)
+
+func (f handlerFunc) ServeHTTP(_ http.ResponseWriter, r *http.Request) { f(r.Context()) }
+
+func newReq(id string) *http.Request {
+	r := httptest.NewRequest(http.MethodGet, "/", nil)
+	r.Header.Set(web.RequestIDHeader, id)
+	return r
+}

package/backend/internal/audit/sanitize.go

@@ -0,0 +1,102 @@
+package audit
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"strings"
+	"unicode"
+	"unicode/utf8"
+)
+
+// Column limits (V002). User-controlled text is cut to these by code point, so
+// a hostile header can never make the audit insert fail.
+const (
+	maxEmpNo     = 64
+	maxMethod    = 8
+	maxRoute     = 200
+	maxErrorCode = 64
+	maxUserAgent = 256 // PRD §6.11
+
+	// maxJSONBytes caps before_json / after_json; a bigger document is replaced
+	// by a marker, never cut in the middle (that would be invalid JSON).
+	maxJSONBytes = 16 << 10
+)
+
+// redacted replaces the value of a secret-looking key.
+const redacted = "[REDACTED]"
+
+// secretKeys are JSON keys whose values are never stored (PRD §6.11: no
+// passwords, tokens, session IDs, CSRF values or file contents). Compared after
+// lower-casing and removing "_" and "-".
+var secretKeys = map[string]bool{
+	"password": true, "passwd": true, "newpassword": true, "oldpassword": true, "currentpassword": true,
+	"token": true, "csrf": true, "csrftoken": true, "xcsrftoken": true,
+	"session": true, "sessionid": true, "cookie": true, "setcookie": true,
+	"authorization": true, "secret": true, "content": true, "filecontent": true,
+}
+
+// clean makes s safe to store and cuts it to max code points: invalid UTF-8
+// and control characters (including NUL and line breaks, which would forge log
+// lines) are dropped, and the result is trimmed.
+func clean(s string, max int) string {
+	s = strings.ToValidUTF8(s, "")
+	s = strings.Map(func(r rune) rune {
+		if unicode.IsControl(r) || r == '
' || r == '
' {
+			return -1
+		}
+		return r
+	}, s)
+	s = strings.TrimSpace(s)
+	if utf8.RuneCountInString(s) > max {
+		s = string([]rune(s)[:max])
+	}
+	return s
+}
+
+// cleanJSON validates raw, redacts secret keys and returns the compact
+// document; nil means "store NULL" (empty input or JSON null).
+func cleanJSON(raw json.RawMessage) ([]byte, error) {
+	if len(bytes.TrimSpace(raw)) == 0 {
+		return nil, nil
+	}
+	dec := json.NewDecoder(bytes.NewReader(raw))
+	dec.UseNumber() // keep numbers exactly as written
+	var v any
+	if err := dec.Decode(&v); err != nil {
+		return nil, fmt.Errorf("audit: invalid JSON: %w", err)
+	}
+	if dec.More() {
+		return nil, fmt.Errorf("audit: trailing data after JSON value")
+	}
+	if v == nil {
+		return nil, nil
+	}
+	out, err := json.Marshal(redact(v))
+	if err != nil {
+		return nil, fmt.Errorf("audit: marshal JSON: %w", err)
+	}
+	if len(out) > maxJSONBytes {
+		return json.Marshal(map[string]any{"truncated": true, "bytes": len(out)})
+	}
+	return out, nil
+}
+
+func redact(v any) any {
+	switch t := v.(type) {
+	case map[string]any:
+		for k, val := range t {
+			norm := strings.NewReplacer("_", "", "-", "").Replace(strings.ToLower(k))
+			if secretKeys[norm] {
+				t[k] = redacted
+			} else {
+				t[k] = redact(val)
+			}
+		}
+	case []any:
+		for i, val := range t {
+			t[i] = redact(val)
+		}
+	}
+	return v
+}