@johnnyboy11234/esg-idea-contest 0.1.0 → 0.2.0

package/backend/internal/audit/sanitize_test.go

@@ -0,0 +1,134 @@
+package audit
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/google/uuid"
+)
+
+func TestClean(t *testing.T) {
+	tests := []struct {
+		name string
+		in   string
+		max  int
+		want string
+	}{
+		{"plain", "E12345", 64, "E12345"},
+		{"control chars and newlines dropped", "a\x00b\r\nc\td", 64, "abcd"},
+		{"line separators dropped", "a
b
c", 64, "abc"},
+		{"invalid utf-8 dropped", "ab\xffcd", 64, "abcd"},
+		{"trimmed", "  x  ", 64, "x"},
+		{"cut by code point, not byte", strings.Repeat("創", 10), 4, "創創創創"},
+		{"emoji kept whole", "😀😀😀", 2, "😀😀"},
+		{"empty", "", 8, ""},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := clean(tc.in, tc.max); got != tc.want {
+				t.Errorf("clean(%q, %d) = %q, want %q", tc.in, tc.max, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestCleanJSON(t *testing.T) {
+	tests := []struct {
+		name    string
+		in      string
+		want    string // "" = NULL
+		wantErr bool
+	}{
+		{"empty is NULL", ``, "", false},
+		{"blank is NULL", "  \n", "", false},
+		{"null is NULL", `null`, "", false},
+		{"compacted", "{ \"a\": 1 }", `{"a":1}`, false},
+		{"big number kept exactly", `{"n":12345678901234567890}`, `{"n":12345678901234567890}`, false},
+		{"password redacted", `{"password":"hunter2","name":"x"}`, `{"name":"x","password":"[REDACTED]"}`, false},
+		{"key spelling ignored", `{"Session_ID":"s","x-csrf-token":"c","Set-Cookie":"k"}`,
+			`{"Session_ID":"[REDACTED]","Set-Cookie":"[REDACTED]","x-csrf-token":"[REDACTED]"}`, false},
+		{"nested and arrays", `{"a":[{"token":"t","ok":true}]}`, `{"a":[{"ok":true,"token":"[REDACTED]"}]}`, false},
+		{"file content redacted", `{"filename":"a.pptx","content":"AAAA"}`, `{"content":"[REDACTED]","filename":"a.pptx"}`, false},
+		{"invalid", `{"a":`, "", true},
+		{"trailing data", `{"a":1} {"b":2}`, "", true},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got, err := cleanJSON(json.RawMessage(tc.in))
+			if (err != nil) != tc.wantErr {
+				t.Fatalf("err = %v, wantErr %v", err, tc.wantErr)
+			}
+			if string(got) != tc.want {
+				t.Errorf("got %s, want %s", got, tc.want)
+			}
+			if tc.want == "" && got != nil {
+				t.Errorf("want nil slice (NULL), got %q", got)
+			}
+		})
+	}
+}
+
+func TestCleanJSONOversizeIsMarker(t *testing.T) {
+	big := `{"text":"` + strings.Repeat("x", maxJSONBytes) + `"}`
+	got, err := cleanJSON(json.RawMessage(big))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var m map[string]any
+	if err := json.Unmarshal(got, &m); err != nil {
+		t.Fatalf("marker is not valid JSON: %v", err)
+	}
+	if m["truncated"] != true || len(got) > 100 {
+		t.Errorf("marker = %s", got)
+	}
+}
+
+func TestInsertRejectsBadEventsBeforeTouchingTheDatabase(t *testing.T) {
+	ok := Event{Action: AuthLogin, Outcome: Success}
+	tests := []struct {
+		name string
+		mod  func(*Event)
+		ctx  context.Context
+	}{
+		{"unknown action", func(e *Event) { e.Action = "NOPE" }, nil},
+		{"empty action", func(e *Event) { e.Action = "" }, nil},
+		{"unknown outcome", func(e *Event) { e.Outcome = "MAYBE" }, nil},
+		{"unknown target type", func(e *Event) { e.TargetType = "TEAM" }, nil},
+		{"target id without type", func(e *Event) { e.TargetID = uuid.New() }, nil},
+		{"unknown actor role", func(e *Event) { e.ActorRole = "ROOT" }, nil},
+		{"bad before", func(e *Event) { e.Before = json.RawMessage(`{`) }, nil},
+		{"bad after", func(e *Event) { e.After = json.RawMessage(`[`) }, nil},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			e := ok
+			tc.mod(&e)
+			ctx := tc.ctx
+			if ctx == nil {
+				ctx = context.Background()
+			}
+			// A nil execer would panic if validation did not stop first.
+			if err := insert(ctx, nil, e); err == nil {
+				t.Error("want error")
+			}
+		})
+	}
+}
+
+func TestRecordNeedsTransaction(t *testing.T) {
+	var tx *sql.Tx
+	if err := New(nil, nil).Record(context.Background(), tx, Event{Action: AuthLogin, Outcome: Success}); err == nil {
+		t.Error("want error for nil tx")
+	}
+}
+
+func TestRecordRejectedRefusesSuccess(t *testing.T) {
+	s := New(nil, nil) // a nil DB would panic if it got that far
+	s.RecordRejected(context.Background(), Event{Action: AuthLogin, Outcome: Success})
+	if s.RejectedFailures() != 1 {
+		t.Errorf("failures = %d, want 1", s.RejectedFailures())
+	}
+}

package/backend/internal/audit/service.go

@@ -0,0 +1,157 @@
+package audit
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"log/slog"
+	"sync/atomic"
+
+	"github.com/google/uuid"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/db"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/security"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/web"
+)
+
+// Service writes audit rows.
+type Service struct {
+	db  *sql.DB
+	log *slog.Logger
+
+	rejectedFailures atomic.Uint64
+}
+
+// New returns a Service. log may be nil.
+func New(database *sql.DB, log *slog.Logger) *Service {
+	if log == nil {
+		log = slog.New(slog.DiscardHandler)
+	}
+	return &Service{db: database, log: log}
+}
+
+// RejectedFailures counts track-B rows that could not be written (the
+// audit-write-failures metric of PRD §10 reads this).
+func (s *Service) RejectedFailures() uint64 { return s.rejectedFailures.Load() }
+
+// Record is track A: it inserts the row in the caller's transaction, so the row
+// commits or rolls back with the business write. An error must make the caller
+// roll back (fail-closed). Any outcome is allowed.
+func (s *Service) Record(ctx context.Context, tx *sql.Tx, e Event) error {
+	if tx == nil {
+		return errors.New("audit: Record needs the caller's transaction")
+	}
+	return insert(ctx, tx, e)
+}
+
+// RecordRejected is track B: it writes a rejected attempt (DENIED, FAILED or
+// THROTTLED) in its own transaction. It is best effort: a failure is logged and
+// counted, never returned, and a client disconnect does not drop the row (the
+// transaction runs on a context detached from ctx, as db.InTx does). Only the
+// central error adapter calls it (Backend.md §7).
+func (s *Service) RecordRejected(ctx context.Context, e Event) {
+	if e.Outcome == Success {
+		s.rejectedFailed(ctx, e, errors.New("audit: RecordRejected called with outcome SUCCESS"))
+		return
+	}
+	_, err := db.InTx(ctx, s.db, func(ctx context.Context, tx *sql.Tx) error {
+		return insert(ctx, tx, e)
+	})
+	if err != nil {
+		s.rejectedFailed(ctx, e, err)
+	}
+}
+
+func (s *Service) rejectedFailed(ctx context.Context, e Event, err error) {
+	s.rejectedFailures.Add(1)
+	s.log.ErrorContext(ctx, "audit: rejected attempt not recorded",
+		"action", string(e.Action), "outcome", string(e.Outcome), "error", err)
+}
+
+type execer interface {
+	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
+}
+
+const insertSQL = `INSERT INTO audit_log
+ (request_id, actor_emp_no, actor_role, action, outcome, target_type, target_id,
+  method, route, status, error_code, ip, user_agent, submitted_emp_no, before_json, after_json)
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+
+// insert validates and sanitizes e, then writes it. occurred_at is the column
+// default, i.e. database time.
+func insert(ctx context.Context, x execer, e Event) error {
+	if !e.Action.Valid() {
+		return fmt.Errorf("audit: unknown action %q", e.Action)
+	}
+	if !e.Outcome.Valid() {
+		return fmt.Errorf("audit: unknown outcome %q", e.Outcome)
+	}
+	if e.TargetType != "" && !e.TargetType.Valid() {
+		return fmt.Errorf("audit: unknown target type %q", e.TargetType)
+	}
+	if e.TargetID != uuid.Nil && e.TargetType == "" {
+		return errors.New("audit: target ID without target type")
+	}
+
+	role, empNo := e.ActorRole, e.ActorEmpNo
+	if role == "" {
+		role, empNo = security.ActorRoleFrom(ctx), security.ActorEmpNo(ctx)
+	}
+	switch role {
+	case security.ActorUser, security.ActorAdmin, security.ActorAnonymous, security.ActorSystem:
+	default:
+		return fmt.Errorf("audit: unknown actor role %q", role)
+	}
+
+	before, err := cleanJSON(e.Before)
+	if err != nil {
+		return fmt.Errorf("before: %w", err)
+	}
+	after, err := cleanJSON(e.After)
+	if err != nil {
+		return fmt.Errorf("after: %w", err)
+	}
+
+	var reqID any
+	if id, err := uuid.Parse(web.RequestIDFrom(ctx)); err == nil {
+		reqID = id.String()
+	}
+	var targetID any
+	if e.TargetID != uuid.Nil {
+		targetID = e.TargetID.String()
+	}
+	var status any
+	if e.Status > 0 {
+		status = e.Status
+	}
+	var ip any
+	if e.IP.IsValid() {
+		ip = e.IP.WithZone("").String() // INET6 has no zone
+	}
+
+	_, err = x.ExecContext(ctx, insertSQL,
+		reqID, nullStr(clean(empNo, maxEmpNo)), string(role), string(e.Action), string(e.Outcome),
+		nullStr(string(e.TargetType)), targetID,
+		nullStr(clean(e.Method, maxMethod)), nullStr(clean(e.Route, maxRoute)), status,
+		nullStr(clean(e.ErrorCode, maxErrorCode)), ip, nullStr(clean(e.UserAgent, maxUserAgent)),
+		nullStr(clean(e.SubmittedEmpNo, maxEmpNo)), nullBytes(before), nullBytes(after))
+	if err != nil {
+		return fmt.Errorf("audit: insert: %w", err)
+	}
+	return nil
+}
+
+func nullStr(s string) any {
+	if s == "" {
+		return nil
+	}
+	return s
+}
+
+func nullBytes(b []byte) any {
+	if b == nil {
+		return nil
+	}
+	return string(b) // JSON column: send text, not a binary blob
+}

package/backend/internal/server/errors.go

@@ -0,0 +1,95 @@
+package server
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"log/slog"
+	"net/http"
+	"net/netip"
+
+	"github.com/go-chi/chi/v5"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/audit"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/web"
+)
+
+// Rejecter writes track-B audit rows. *audit.Service implements it.
+type Rejecter interface {
+	RecordRejected(ctx context.Context, e audit.Event)
+}
+
+// ErrorAdapter is the one place that turns a handler's error into a response
+// and, when the error asks for it, into a track-B audit row (Backend.md §7).
+// No other code calls RecordRejected.
+type ErrorAdapter struct {
+	Audit Rejecter
+	Log   *slog.Logger // nil = discard
+}
+
+// Write answers err as problem+json. When err wraps a *web.Error with an
+// AuditReason, the rejected attempt is recorded first (best effort: the row's
+// failure never changes the response). Errors without a reason are not audited,
+// and neither is anything that is not a *web.Error (it answers 500).
+func (a ErrorAdapter) Write(w http.ResponseWriter, r *http.Request, err error) {
+	var e *web.Error
+	if !errors.As(err, &e) {
+		web.WriteError(w, r, err)
+		return
+	}
+	if e.AuditReason != "" {
+		a.record(r, e)
+	}
+	web.WriteProblem(w, r, e)
+}
+
+func (a ErrorAdapter) record(r *http.Request, e *web.Error) {
+	log := a.Log
+	if log == nil {
+		log = slog.New(slog.DiscardHandler)
+	}
+	if a.Audit == nil || e.AuditAction == "" {
+		// A programming error: the attempt cannot be recorded. Say so loudly,
+		// but still answer the client.
+		log.ErrorContext(r.Context(), "audit: rejected attempt without action or recorder",
+			"code", string(e.Code), "reason", e.AuditReason)
+		return
+	}
+	outcome := audit.Outcome(e.AuditOutcome)
+	if outcome == "" {
+		outcome = audit.Denied
+	}
+	after, _ := json.Marshal(map[string]string{"reason": e.AuditReason}) // map of strings cannot fail
+	ev := audit.Event{
+		Action:     audit.Action(e.AuditAction),
+		Outcome:    outcome,
+		TargetType: audit.TargetType(e.AuditTargetType),
+		TargetID:   e.AuditTargetID,
+		Method:     r.Method,
+		Route:      routeTemplate(r),
+		Status:     e.Status,
+		ErrorCode:  string(e.Code),
+		IP:         remoteIP(r),
+		UserAgent:  r.UserAgent(),
+		After:      after,
+	}
+	a.Audit.RecordRejected(r.Context(), ev)
+}
+
+// routeTemplate is the matched chi pattern (/api/v1/ideas/{id}), never the raw
+// path, so IDs do not leak into the log and rows group by route.
+func routeTemplate(r *http.Request) string {
+	if rc := chi.RouteContext(r.Context()); rc != nil {
+		return rc.RoutePattern()
+	}
+	return ""
+}
+
+// remoteIP is the TCP peer. Trusted-proxy handling is not decided yet.
+func remoteIP(r *http.Request) netip.Addr {
+	ap, err := netip.ParseAddrPort(r.RemoteAddr)
+	if err != nil {
+		return netip.Addr{}
+	}
+	return ap.Addr().Unmap()
+}

package/backend/internal/server/errors_test.go

@@ -0,0 +1,98 @@
+package server_test
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/google/uuid"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/audit"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/server"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/web"
+)
+
+type fakeRejecter struct{ got []audit.Event }
+
+func (f *fakeRejecter) RecordRejected(_ context.Context, e audit.Event) { f.got = append(f.got, e) }
+
+func serve(t *testing.T, ad server.ErrorAdapter, err error) *httptest.ResponseRecorder {
+	t.Helper()
+	r := chi.NewRouter()
+	r.Get("/ideas/{id}", func(w http.ResponseWriter, req *http.Request) { ad.Write(w, req, err) })
+	req := httptest.NewRequest("GET", "/ideas/123", nil)
+	req.RemoteAddr = "192.0.2.7:5555"
+	req.Header.Set("User-Agent", "ua/1")
+	rec := httptest.NewRecorder()
+	r.ServeHTTP(rec, req)
+	return rec
+}
+
+func TestAdapterWithReasonRecordsDenied(t *testing.T) {
+	id := uuid.New()
+	e := web.NewError(web.CodeNotFound, "resource not found")
+	e.AuditReason, e.AuditAction = "NOT_FOUND", "IDEA_VIEW"
+	e.AuditTargetType, e.AuditTargetID = "IDEA", id
+	f := &fakeRejecter{}
+
+	rec := serve(t, server.ErrorAdapter{Audit: f}, fmt.Errorf("wrapped: %w", e))
+
+	if rec.Code != 404 {
+		t.Fatalf("status = %d", rec.Code)
+	}
+	if len(f.got) != 1 {
+		t.Fatalf("rows = %d, want 1", len(f.got))
+	}
+	g := f.got[0]
+	if g.Outcome != audit.Denied || g.Action != audit.IdeaView || g.TargetType != audit.TargetIdea || g.TargetID != id ||
+		g.Method != "GET" || g.Route != "/ideas/{id}" || g.Status != 404 || g.ErrorCode != "NOT_FOUND" ||
+		g.IP.String() != "192.0.2.7" || g.UserAgent != "ua/1" || string(g.After) != `{"reason":"NOT_FOUND"}` {
+		t.Fatalf("event = %+v (after %s)", g, g.After)
+	}
+	if body := rec.Body.String(); contains(body, "reason") {
+		t.Fatalf("reason leaked to client: %s", body)
+	}
+}
+
+func TestAdapterOutcomeOverride(t *testing.T) {
+	e := web.NewError(web.CodeLoginThrottled, "")
+	e.AuditReason, e.AuditAction, e.AuditOutcome = "KEY_LOCKED", "AUTH_LOGIN", "THROTTLED"
+	f := &fakeRejecter{}
+	serve(t, server.ErrorAdapter{Audit: f}, e)
+	if len(f.got) != 1 || f.got[0].Outcome != audit.Throttled {
+		t.Fatalf("got %+v", f.got)
+	}
+}
+
+func TestAdapterWithoutReasonRecordsNothing(t *testing.T) {
+	f := &fakeRejecter{}
+	rec := serve(t, server.ErrorAdapter{Audit: f}, web.NewError(web.CodeEmailTaken, "x"))
+	if rec.Code != 409 || len(f.got) != 0 {
+		t.Fatalf("status %d rows %d", rec.Code, len(f.got))
+	}
+}
+
+func TestAdapterPlainErrorIs500AndUnaudited(t *testing.T) {
+	f := &fakeRejecter{}
+	rec := serve(t, server.ErrorAdapter{Audit: f}, errors.New("db password=hunter2"))
+	if rec.Code != 500 || len(f.got) != 0 || contains(rec.Body.String(), "hunter2") {
+		t.Fatalf("status %d rows %d body %s", rec.Code, len(f.got), rec.Body)
+	}
+}
+
+func TestAdapterReasonWithoutActionStillAnswers(t *testing.T) {
+	e := web.NewError(web.CodeForbidden, "no")
+	e.AuditReason = "ROLE"
+	f := &fakeRejecter{}
+	rec := serve(t, server.ErrorAdapter{Audit: f}, e)
+	if rec.Code != 403 || len(f.got) != 0 {
+		t.Fatalf("status %d rows %d", rec.Code, len(f.got))
+	}
+}
+
+func contains(s, sub string) bool { return strings.Contains(s, sub) }

package/backend/internal/shared/security/security.go

@@ -0,0 +1,98 @@
+// Package security holds the authenticated caller's identity: the Principal
+// built by the session middleware and the context accessors every later layer
+// uses to read it (Backend.md §6). It has no dependencies inside the module so
+// that any package may import it.
+package security
+
+import "context"
+
+// Role is an account role (PRD §3). Leader, Member and Applicant are relations
+// to one Idea, not roles.
+type Role string
+
+// The two account roles.
+const (
+	RoleUser  Role = "USER"
+	RoleAdmin Role = "ADMIN"
+)
+
+// Valid reports whether r is one of the two account roles.
+func (r Role) Valid() bool { return r == RoleUser || r == RoleAdmin }
+
+// ActorRole is the role recorded in the audit log (PRD §7): an account role, or
+// ANONYMOUS (no session) or SYSTEM (no caller, e.g. background cleanup).
+type ActorRole string
+
+// The audit actor roles.
+const (
+	ActorUser      ActorRole = "USER"
+	ActorAdmin     ActorRole = "ADMIN"
+	ActorAnonymous ActorRole = "ANONYMOUS"
+	ActorSystem    ActorRole = "SYSTEM"
+)
+
+// Principal is the caller resolved from a valid session. The role is read from
+// the account on every request, never copied into the session (PRD §6.5).
+type Principal struct {
+	UserID int64
+	EmpNo  string
+	Role   Role
+}
+
+// IsAdmin reports whether the principal has role ADMIN.
+func (p Principal) IsAdmin() bool { return p.Role == RoleAdmin }
+
+// ActorRole maps the account role to its audit value. An invalid role maps to
+// ANONYMOUS so an unexpected value is never recorded as privileged.
+func (p Principal) ActorRole() ActorRole {
+	switch p.Role {
+	case RoleUser:
+		return ActorUser
+	case RoleAdmin:
+		return ActorAdmin
+	}
+	return ActorAnonymous
+}
+
+type ctxKey int
+
+const (
+	principalKey ctxKey = iota
+	systemKey
+)
+
+// WithPrincipal returns a context carrying p.
+func WithPrincipal(ctx context.Context, p Principal) context.Context {
+	return context.WithValue(ctx, principalKey, p)
+}
+
+// PrincipalFrom returns the principal in ctx; ok is false when there is none.
+func PrincipalFrom(ctx context.Context) (p Principal, ok bool) {
+	p, ok = ctx.Value(principalKey).(Principal)
+	return p, ok
+}
+
+// WithSystem marks ctx as a system action (no caller). A principal in ctx still
+// wins, so a request can never be recorded as SYSTEM by accident.
+func WithSystem(ctx context.Context) context.Context {
+	return context.WithValue(ctx, systemKey, true)
+}
+
+// ActorRoleFrom returns the audit actor role for ctx: the principal's role,
+// else SYSTEM if marked with WithSystem, else ANONYMOUS.
+func ActorRoleFrom(ctx context.Context) ActorRole {
+	if p, ok := PrincipalFrom(ctx); ok {
+		return p.ActorRole()
+	}
+	if sys, _ := ctx.Value(systemKey).(bool); sys {
+		return ActorSystem
+	}
+	return ActorAnonymous
+}
+
+// ActorEmpNo returns the caller's employee ID for the audit log, or "" when
+// there is no principal.
+func ActorEmpNo(ctx context.Context) string {
+	p, _ := PrincipalFrom(ctx)
+	return p.EmpNo
+}

package/backend/internal/shared/security/security_test.go

@@ -0,0 +1,60 @@
+package security_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/security"
+)
+
+func TestPrincipalRoundTrip(t *testing.T) {
+	ctx := context.Background()
+	if _, ok := security.PrincipalFrom(ctx); ok {
+		t.Fatal("empty context must have no principal")
+	}
+	want := security.Principal{UserID: 7, EmpNo: "A123", Role: security.RoleUser}
+	got, ok := security.PrincipalFrom(security.WithPrincipal(ctx, want))
+	if !ok || got != want {
+		t.Fatalf("got %+v, %v", got, ok)
+	}
+}
+
+func TestActorRole(t *testing.T) {
+	bg := context.Background()
+	user := security.Principal{UserID: 1, EmpNo: "U1", Role: security.RoleUser}
+	admin := security.Principal{UserID: 2, EmpNo: "A1", Role: security.RoleAdmin}
+	bad := security.Principal{UserID: 3, EmpNo: "X", Role: "ROOT"}
+
+	tests := []struct {
+		name string
+		ctx  context.Context
+		want security.ActorRole
+		emp  string
+	}{
+		{"anonymous", bg, security.ActorAnonymous, ""},
+		{"user", security.WithPrincipal(bg, user), security.ActorUser, "U1"},
+		{"admin", security.WithPrincipal(bg, admin), security.ActorAdmin, "A1"},
+		{"invalid role is never privileged", security.WithPrincipal(bg, bad), security.ActorAnonymous, "X"},
+		{"system", security.WithSystem(bg), security.ActorSystem, ""},
+		{"principal wins over system", security.WithSystem(security.WithPrincipal(bg, user)), security.ActorUser, "U1"},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := security.ActorRoleFrom(tc.ctx); got != tc.want {
+				t.Errorf("ActorRoleFrom = %q, want %q", got, tc.want)
+			}
+			if got := security.ActorEmpNo(tc.ctx); got != tc.emp {
+				t.Errorf("ActorEmpNo = %q, want %q", got, tc.emp)
+			}
+		})
+	}
+}
+
+func TestRole(t *testing.T) {
+	if !security.RoleUser.Valid() || !security.RoleAdmin.Valid() || security.Role("").Valid() || security.Role("ROOT").Valid() {
+		t.Error("Valid wrong")
+	}
+	if !(security.Principal{Role: security.RoleAdmin}).IsAdmin() || (security.Principal{Role: security.RoleUser}).IsAdmin() {
+		t.Error("IsAdmin wrong")
+	}
+}

package/backend/internal/shared/web/problem.go

@@ -3,6 +3,8 @@ package web
 import (
 	"encoding/json"
 	"net/http"
+
+	"github.com/google/uuid"
 )
 
 // ProblemContentType is the RFC 9457 media type.
@@ -16,15 +18,29 @@ type FieldError struct {
 }
 
 // Error is the one error type handlers and services return. The central
-// adapter turns it into problem+json; AuditReason (set later by the audit PRs)
-// makes the adapter record a track-B row.
+// adapter turns it into problem+json; a non-empty AuditReason makes the adapter
+// record a track-B row (Backend.md §7). Without a reason nothing is audited.
+//
+// The Audit* fields are plain strings because package audit imports web.
 type Error struct {
-	Status      int
-	Code        ErrorCode
-	Detail      string
-	Fields      []FieldError
+	Status int
+	Code   ErrorCode
+	Detail string
+	Fields []FieldError
+	Cause  error
+
+	// AuditReason is the real reason of a rejected attempt (CSRF, role, state,
+	// not-yours, not-found). It is stored in the row's after_json, never sent
+	// to the client.
 	AuditReason string
-	Cause       error
+	// AuditAction is the audit action of the attempted operation, e.g.
+	// "IDEA_VIEW". Required whenever AuditReason is set.
+	AuditAction string
+	// AuditOutcome is DENIED, FAILED or THROTTLED; empty means DENIED.
+	AuditOutcome string
+	// AuditTargetType and AuditTargetID name the resource, when there is one.
+	AuditTargetType string
+	AuditTargetID   uuid.UUID
 }
 
 func (e *Error) Error() string {