@opengroundplan/core 0.1.1

package/templates/layers/audit-log/files/internal/audit/audit_test.go

@@ -0,0 +1,141 @@
+package audit
+
+import (
+	"errors"
+	"testing"
+)
+
+func testConfig(t *testing.T) Config {
+	t.Helper()
+	t.Setenv(envPrefix+"SINK", SinkMemory)
+	cfg, err := Load()
+	if err != nil {
+		t.Fatalf("load config: %v", err)
+	}
+	return cfg
+}
+
+func trail(t *testing.T, count int) ([]Record, Config, *MemorySink) {
+	t.Helper()
+	cfg := testConfig(t)
+	sink := NewMemorySink(cfg)
+	recorder := NewRecorder(cfg, sink)
+	for i := 1; i <= count; i++ {
+		_, err := recorder.Record(Event{
+			Action:       "invoice.approved",
+			Outcome:      OutcomeSuccess,
+			ActorID:      "user-1",
+			ResourceType: "invoice",
+		})
+		if err != nil {
+			t.Fatalf("record %d: %v", i, err)
+		}
+	}
+	records, err := sink.ReadAll()
+	if err != nil {
+		t.Fatalf("read all: %v", err)
+	}
+	return records, cfg, sink
+}
+
+func TestChainVerifiesClean(t *testing.T) {
+	records, cfg, _ := trail(t, 3)
+	for i, record := range records {
+		if record.Sequence != int64(i+1) {
+			t.Fatalf("sequence %d, want %d", record.Sequence, i+1)
+		}
+	}
+	result, err := VerifyChain(records, cfg)
+	if err != nil {
+		t.Fatalf("verify: %v", err)
+	}
+	if !result.Valid {
+		t.Fatalf("clean trail reported %d breaks", len(result.Breaks))
+	}
+}
+
+func TestEditedRecordIsDetected(t *testing.T) {
+	records, cfg, _ := trail(t, 3)
+	records[1].Action = "invoice.deleted"
+	result, err := VerifyChain(records, cfg)
+	if err != nil {
+		t.Fatalf("verify: %v", err)
+	}
+	if result.Valid || !hasBreak(result, BreakHashMismatch) {
+		t.Fatalf("edit not detected: %+v", result)
+	}
+}
+
+func TestRemovedRecordIsDetected(t *testing.T) {
+	records, cfg, _ := trail(t, 3)
+	result, err := VerifyChain([]Record{records[0], records[2]}, cfg)
+	if err != nil {
+		t.Fatalf("verify: %v", err)
+	}
+	if !hasBreak(result, BreakSequenceGap) || !hasBreak(result, BreakBrokenLink) {
+		t.Fatalf("removal not detected: %+v", result)
+	}
+}
+
+func TestChainContinuesAfterRestart(t *testing.T) {
+	cfg := testConfig(t)
+	sink := NewMemorySink(cfg)
+	for _, action := range []string{"a", "b"} {
+		if _, err := NewRecorder(cfg, sink).Record(newSystemEvent(action)); err != nil {
+			t.Fatalf("record %s: %v", action, err)
+		}
+	}
+	records, _ := sink.ReadAll()
+	result, err := VerifyChain(records, cfg)
+	if err != nil || !result.Valid {
+		t.Fatalf("restart broke the chain: %+v (%v)", result, err)
+	}
+}
+
+func TestConfiguredFieldsAreRedacted(t *testing.T) {
+	cfg := testConfig(t)
+	sink := NewMemorySink(cfg)
+	record, err := NewRecorder(cfg, sink).Record(Event{
+		Action:  "user.login",
+		Outcome: OutcomeFailure,
+		ActorID: "user-1",
+		Metadata: map[string]any{
+			"attempt":     2,
+			"credentials": map[string]any{"password": "hunter2", "Token": "abc"},
+		},
+	})
+	if err != nil {
+		t.Fatalf("record: %v", err)
+	}
+	credentials, ok := record.Metadata["credentials"].(map[string]any)
+	if !ok {
+		t.Fatalf("credentials missing from metadata")
+	}
+	if credentials["password"] != cfg.RedactPlaceholder || credentials["Token"] != cfg.RedactPlaceholder {
+		t.Fatalf("secret survived redaction: %+v", credentials)
+	}
+	if record.Metadata["attempt"] != 2 {
+		t.Fatalf("unrelated field was altered: %+v", record.Metadata)
+	}
+}
+
+func TestEventWithoutActorIsRejected(t *testing.T) {
+	cfg := testConfig(t)
+	_, err := NewRecorder(cfg, NewMemorySink(cfg)).Record(Event{Action: "x", Outcome: OutcomeSuccess})
+	if !errors.Is(err, ErrInvalidEvent) {
+		t.Fatalf("want ErrInvalidEvent, got %v", err)
+	}
+}
+
+func newSystemEvent(action string) Event {
+	return Event{Action: action, Outcome: OutcomeSuccess, ActorID: ActorSystem, ActorType: ActorSystem}
+}
+
+func hasBreak(result Verification, reason string) bool {
+	for _, item := range result.Breaks {
+		if item.Reason == reason {
+			return true
+		}
+	}
+	return false
+}

package/templates/layers/audit-log/files/internal/audit/chain.go

@@ -0,0 +1,91 @@
+package audit
+
+import (
+	"crypto/sha256"
+	"crypto/sha512"
+	"encoding/hex"
+	"fmt"
+	"hash"
+	"strings"
+)
+
+// GenesisHash is a fixed sentinel, not a digest, so a chain starting at record 1 cannot be
+// confused with one whose head was truncated. Width is independent of the hash choice.
+var GenesisHash = strings.Repeat("0", 64)
+
+// Break reasons.
+const (
+	BreakHashMismatch = "hash-mismatch"
+	BreakBrokenLink   = "broken-link"
+	BreakSequenceGap  = "sequence-gap"
+)
+
+func newHasher(algorithm string) (hash.Hash, error) {
+	switch algorithm {
+	case "sha256":
+		return sha256.New(), nil
+	case "sha512":
+		return sha512.New(), nil
+	default:
+		return nil, fmt.Errorf("audit: unsupported hash algorithm %q", algorithm)
+	}
+}
+
+// HashRecord commits a record to its predecessor's hash.
+func HashRecord(record Record, cfg Config) (string, error) {
+	payload, err := canonicalPayload(record)
+	if err != nil {
+		return "", err
+	}
+	hasher, err := newHasher(cfg.HashAlgorithm)
+	if err != nil {
+		return "", err
+	}
+	hasher.Write([]byte(record.PreviousHash))
+	hasher.Write([]byte("|"))
+	hasher.Write(payload)
+	return hex.EncodeToString(hasher.Sum(nil)), nil
+}
+
+// ChainBreak names one place where the trail stopped being self-consistent.
+type ChainBreak struct {
+	Sequence int64  `json:"sequence"`
+	ID       string `json:"id"`
+	Reason   string `json:"reason"`
+}
+
+// Verification is the result of walking a whole trail.
+type Verification struct {
+	Valid   bool         `json:"valid"`
+	Checked int          `json:"checked"`
+	Breaks  []ChainBreak `json:"breaks"`
+}
+
+// VerifyChain walks records in write order and reports every break, not just the first —
+// an investigator needs the full extent of the damage, not its earliest symptom.
+func VerifyChain(records []Record, cfg Config) (Verification, error) {
+	breaks := make([]ChainBreak, 0)
+	previousHash := GenesisHash
+	expectedSequence := int64(1)
+
+	for _, record := range records {
+		if record.Sequence != expectedSequence {
+			breaks = append(breaks, ChainBreak{record.Sequence, record.ID, BreakSequenceGap})
+		}
+		if record.PreviousHash != previousHash {
+			breaks = append(breaks, ChainBreak{record.Sequence, record.ID, BreakBrokenLink})
+		}
+		computed, err := HashRecord(record, cfg)
+		if err != nil {
+			return Verification{}, err
+		}
+		if computed != record.Hash {
+			breaks = append(breaks, ChainBreak{record.Sequence, record.ID, BreakHashMismatch})
+		}
+
+		previousHash = record.Hash
+		expectedSequence = record.Sequence + 1
+	}
+
+	return Verification{Valid: len(breaks) == 0, Checked: len(records), Breaks: breaks}, nil
+}

package/templates/layers/audit-log/files/internal/audit/config.go

@@ -0,0 +1,143 @@
+// Package audit is an append-only, tamper-evident record of who did what to which resource.
+//
+// The write API has no update and no delete. That is the whole design.
+package audit
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+)
+
+// Prefixed so several services can share one environment without colliding.
+const envPrefix = "{{ auditEnvPrefix }}_"
+
+// Sink kinds are protocol literals, not tunables.
+const (
+	SinkFile   = "file"
+	SinkStdout = "stdout"
+	SinkMemory = "memory"
+)
+
+// Config is the fully resolved audit settings for one process.
+type Config struct {
+	Enabled           bool
+	Sink              string
+	FilePath          string
+	Service           string
+	Environment       string
+	ChainEnabled      bool
+	HashAlgorithm     string
+	RedactFields      []string
+	RedactPlaceholder string
+	RetentionDays     int
+	MaxMemoryEvents   int
+	FailClosed        bool
+}
+
+// defaults is the single source of truth for every tunable. Add a knob here first;
+// the environment only ever overrides a key that already exists in this table.
+var defaults = map[string]string{
+	"ENABLED":            "true",
+	"SINK":               "{{ auditSink }}",
+	"FILE_PATH":          "{{ auditFilePath }}",
+	"SERVICE":            "{{ solutionName | kebab }}",
+	"ENVIRONMENT":        "local",
+	"CHAIN_ENABLED":      "true",
+	"HASH_ALGORITHM":     "{{ auditHashAlgorithm }}",
+	"REDACT_FIELDS":      "{{ auditRedactFields }}",
+	"REDACT_PLACEHOLDER": "[redacted]",
+	"RETENTION_DAYS":     "{{ auditRetentionDays }}",
+	"MAX_MEMORY_EVENTS":  "{{ auditMaxMemoryEvents }}",
+	"FAIL_CLOSED":        "true",
+}
+
+// Load reads the environment once at startup and reports every bad value at once.
+func Load() (Config, error) {
+	r := &reader{}
+	cfg := Config{
+		Enabled:           r.boolVal("ENABLED"),
+		Sink:              r.sink("SINK"),
+		FilePath:          r.str("FILE_PATH"),
+		Service:           r.str("SERVICE"),
+		Environment:       r.str("ENVIRONMENT"),
+		ChainEnabled:      r.boolVal("CHAIN_ENABLED"),
+		HashAlgorithm:     r.str("HASH_ALGORITHM"),
+		RedactFields:      r.list("REDACT_FIELDS"),
+		RedactPlaceholder: r.str("REDACT_PLACEHOLDER"),
+		RetentionDays:     r.intVal("RETENTION_DAYS"),
+		MaxMemoryEvents:   r.intVal("MAX_MEMORY_EVENTS"),
+		FailClosed:        r.boolVal("FAIL_CLOSED"),
+	}
+	if len(r.errs) > 0 {
+		return Config{}, errors.Join(r.errs...)
+	}
+	return cfg, nil
+}
+
+// MustLoad is for tests and for main, where a bad audit configuration must stop the process.
+func MustLoad() Config {
+	cfg, err := Load()
+	if err != nil {
+		panic(err)
+	}
+	return cfg
+}
+
+type reader struct {
+	errs []error
+}
+
+func (r *reader) str(key string) string {
+	def, declared := defaults[key]
+	if !declared {
+		r.errs = append(r.errs, fmt.Errorf("audit: no default declared for %q", key))
+		return ""
+	}
+	if v, found := os.LookupEnv(envPrefix + key); found && strings.TrimSpace(v) != "" {
+		return strings.TrimSpace(v)
+	}
+	return def
+}
+
+func (r *reader) intVal(key string) int {
+	raw := r.str(key)
+	v, err := strconv.Atoi(raw)
+	if err != nil || v < 0 {
+		r.errs = append(r.errs, fmt.Errorf("audit: %s%s must be a non-negative integer, got %q", envPrefix, key, raw))
+	}
+	return v
+}
+
+func (r *reader) boolVal(key string) bool {
+	switch strings.ToLower(r.str(key)) {
+	case "1", "true", "yes", "on":
+		return true
+	default:
+		return false
+	}
+}
+
+func (r *reader) list(key string) []string {
+	parts := strings.Split(r.str(key), ",")
+	out := make([]string, 0, len(parts))
+	for _, part := range parts {
+		if trimmed := strings.TrimSpace(part); trimmed != "" {
+			out = append(out, trimmed)
+		}
+	}
+	return out
+}
+
+func (r *reader) sink(key string) string {
+	raw := strings.ToLower(r.str(key))
+	switch raw {
+	case SinkFile, SinkStdout, SinkMemory:
+		return raw
+	default:
+		r.errs = append(r.errs, fmt.Errorf("audit: %s%s must be file, stdout or memory, got %q", envPrefix, key, raw))
+		return ""
+	}
+}

package/templates/layers/audit-log/files/internal/audit/event.go

@@ -0,0 +1,87 @@
+package audit
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+)
+
+// SchemaVersion is stamped on every record. Once a trail exists on disk, renaming a JSON
+// field invalidates every hash already written — bump this instead.
+const SchemaVersion = 1
+
+// Outcomes. "denied" is distinct from "failure": a refused authorization is not a malfunction.
+const (
+	OutcomeSuccess = "success"
+	OutcomeFailure = "failure"
+	OutcomeDenied  = "denied"
+)
+
+// Actor kinds.
+const (
+	ActorUser      = "user"
+	ActorService   = "service"
+	ActorSystem    = "system"
+	ActorAnonymous = "anonymous"
+)
+
+const maxActionLength = 200
+
+// ErrInvalidEvent wraps every rejection so callers can match on one sentinel.
+var ErrInvalidEvent = errors.New("audit: invalid event")
+
+// Event is what a caller supplies. Everything else is stamped by the Recorder.
+type Event struct {
+	Action        string
+	Outcome       string
+	ActorID       string
+	ActorType     string
+	ActorIP       string
+	ResourceType  string
+	ResourceID    string
+	Reason        string
+	CorrelationID string
+	Metadata      map[string]any
+}
+
+// Record is what is written. JSON names are part of the hashed payload.
+type Record struct {
+	SchemaVersion int            `json:"schemaVersion"`
+	Sequence      int64          `json:"sequence"`
+	ID            string         `json:"id"`
+	OccurredAt    string         `json:"occurredAt"`
+	Service       string         `json:"service"`
+	Environment   string         `json:"environment"`
+	Action        string         `json:"action"`
+	Outcome       string         `json:"outcome"`
+	ActorID       string         `json:"actorId"`
+	ActorType     string         `json:"actorType"`
+	ActorIP       string         `json:"actorIp"`
+	ResourceType  string         `json:"resourceType"`
+	ResourceID    string         `json:"resourceId"`
+	Reason        string         `json:"reason"`
+	CorrelationID string         `json:"correlationId"`
+	Metadata      map[string]any `json:"metadata"`
+	PreviousHash  string         `json:"previousHash"`
+	Hash          string         `json:"hash"`
+}
+
+// Validate rejects an unusable event at the call site instead of writing a record nobody
+// can interpret during an investigation.
+func (e Event) Validate() error {
+	if strings.TrimSpace(e.Action) == "" {
+		return fmt.Errorf("%w: action is required", ErrInvalidEvent)
+	}
+	if len(e.Action) > maxActionLength {
+		return fmt.Errorf("%w: action exceeds %d characters", ErrInvalidEvent, maxActionLength)
+	}
+	if strings.TrimSpace(e.ActorID) == "" {
+		return fmt.Errorf("%w: actor id is required, use %q for unattended work", ErrInvalidEvent, ActorSystem)
+	}
+	switch e.Outcome {
+	case OutcomeSuccess, OutcomeFailure, OutcomeDenied:
+		return nil
+	default:
+		return fmt.Errorf("%w: unknown outcome %q", ErrInvalidEvent, e.Outcome)
+	}
+}

package/templates/layers/audit-log/files/internal/audit/recorder.go

@@ -0,0 +1,133 @@
+package audit
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"sync"
+	"time"
+)
+
+// Recorder is the write API. It exposes Record and nothing else — no update, no delete, no
+// way to reach the sink's storage. Append-only is enforced by the shape of this type.
+type Recorder struct {
+	cfg  Config
+	sink Sink
+
+	// Serialized so two goroutines cannot claim the same sequence number.
+	mu           sync.Mutex
+	previousHash string
+	sequence     int64
+	restored     bool
+}
+
+func NewRecorder(cfg Config, sink Sink) *Recorder {
+	return &Recorder{cfg: cfg, sink: sink, previousHash: GenesisHash}
+}
+
+// Record returns once the entry is durable in the sink. It returns an error if it is not.
+func (r *Recorder) Record(event Event) (Record, error) {
+	if err := event.Validate(); err != nil {
+		return Record{}, err
+	}
+
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if err := r.restore(); err != nil {
+		return Record{}, err
+	}
+
+	id, err := newID()
+	if err != nil {
+		return Record{}, err
+	}
+
+	record := Record{
+		SchemaVersion: SchemaVersion,
+		Sequence:      r.sequence + 1,
+		ID:            id,
+		OccurredAt:    time.Now().UTC().Format(time.RFC3339Nano),
+		Service:       r.cfg.Service,
+		Environment:   r.cfg.Environment,
+		Action:        event.Action,
+		Outcome:       event.Outcome,
+		ActorID:       event.ActorID,
+		ActorType:     orDefault(event.ActorType, ActorUser),
+		ActorIP:       event.ActorIP,
+		ResourceType:  event.ResourceType,
+		ResourceID:    event.ResourceID,
+		Reason:        event.Reason,
+		CorrelationID: event.CorrelationID,
+		Metadata:      redactedMetadata(event.Metadata, r.cfg),
+		PreviousHash:  GenesisHash,
+	}
+	if r.cfg.ChainEnabled {
+		record.PreviousHash = r.previousHash
+	}
+
+	if record.Hash, err = HashRecord(record, r.cfg); err != nil {
+		return Record{}, err
+	}
+
+	// A disabled trail still builds and validates the record, so turning it on never
+	// reveals a bug that was hidden while it was off.
+	if !r.cfg.Enabled {
+		return record, nil
+	}
+
+	if err := r.sink.Append(record); err != nil {
+		// Fail-open is a configured, deliberate choice; nothing was written, so the chain
+		// state is left untouched and the next record takes this sequence number.
+		if r.cfg.FailClosed {
+			return Record{}, err
+		}
+		return record, nil
+	}
+
+	r.sequence = record.Sequence
+	r.previousHash = record.Hash
+	return record, nil
+}
+
+// restore continues an existing trail across restarts instead of forking a second chain.
+func (r *Recorder) restore() error {
+	if r.restored {
+		return nil
+	}
+	r.restored = true
+	last, found, err := r.sink.Last()
+	if err != nil || !found {
+		return err
+	}
+	r.sequence = last.Sequence
+	r.previousHash = last.Hash
+	return nil
+}
+
+func (r *Recorder) Close() error { return r.sink.Close() }
+
+func redactedMetadata(metadata map[string]any, cfg Config) map[string]any {
+	if metadata == nil {
+		return map[string]any{}
+	}
+	redacted, _ := Redact(metadata, cfg).(map[string]any)
+	return redacted
+}
+
+func orDefault(value, fallback string) string {
+	if value == "" {
+		return fallback
+	}
+	return value
+}
+
+// newID is a random UUIDv4 built on crypto/rand, so the package stays dependency-free.
+func newID() (string, error) {
+	buf := make([]byte, 16)
+	if _, err := rand.Read(buf); err != nil {
+		return "", err
+	}
+	buf[6] = (buf[6] & 0x0f) | 0x40
+	buf[8] = (buf[8] & 0x3f) | 0x80
+	hexed := hex.EncodeToString(buf)
+	return hexed[0:8] + "-" + hexed[8:12] + "-" + hexed[12:16] + "-" + hexed[16:20] + "-" + hexed[20:], nil
+}

package/templates/layers/audit-log/files/internal/audit/redact.go

@@ -0,0 +1,83 @@
+package audit
+
+import (
+	"bytes"
+	"encoding/json"
+	"strings"
+)
+
+const maxRedactDepth = 12
+
+// Redact deep-copies while replacing matched keys. It runs before serialization, so a
+// secret never reaches the sink and never enters the hash chain — removing it afterwards
+// would break every subsequent hash.
+func Redact(value any, cfg Config) any {
+	return redactDepth(value, blockedFields(cfg), cfg.RedactPlaceholder, 0)
+}
+
+func blockedFields(cfg Config) map[string]struct{} {
+	blocked := make(map[string]struct{}, len(cfg.RedactFields))
+	for _, name := range cfg.RedactFields {
+		blocked[strings.ToLower(name)] = struct{}{}
+	}
+	return blocked
+}
+
+func redactDepth(value any, blocked map[string]struct{}, placeholder string, depth int) any {
+	if depth > maxRedactDepth {
+		return "[truncated]"
+	}
+	switch typed := value.(type) {
+	case map[string]any:
+		out := make(map[string]any, len(typed))
+		for key, item := range typed {
+			if _, hit := blocked[strings.ToLower(key)]; hit {
+				out[key] = placeholder
+				continue
+			}
+			out[key] = redactDepth(item, blocked, placeholder, depth+1)
+		}
+		return out
+	case []any:
+		out := make([]any, len(typed))
+		for i, item := range typed {
+			out[i] = redactDepth(item, blocked, placeholder, depth+1)
+		}
+		return out
+	default:
+		return value
+	}
+}
+
+// canonical produces byte-identical JSON for equal values: encoding/json sorts map keys, so
+// re-encoding through the generic form removes any dependence on struct field order.
+func canonical(value any) ([]byte, error) {
+	raw, err := json.Marshal(value)
+	if err != nil {
+		return nil, err
+	}
+	decoder := json.NewDecoder(bytes.NewReader(raw))
+	// Keeps numbers as their original text instead of round-tripping through float64.
+	decoder.UseNumber()
+	var generic any
+	if err := decoder.Decode(&generic); err != nil {
+		return nil, err
+	}
+	return json.Marshal(generic)
+}
+
+// canonicalPayload is the byte sequence a record's hash commits to: everything but the hash.
+func canonicalPayload(record Record) ([]byte, error) {
+	raw, err := json.Marshal(record)
+	if err != nil {
+		return nil, err
+	}
+	decoder := json.NewDecoder(bytes.NewReader(raw))
+	decoder.UseNumber()
+	fields := map[string]any{}
+	if err := decoder.Decode(&fields); err != nil {
+		return nil, err
+	}
+	delete(fields, "hash")
+	return json.Marshal(fields)
+}