@opengroundplan/core 0.1.1

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

@@ -0,0 +1,196 @@
+package audit
+
+import (
+	"bufio"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sync"
+)
+
+// Sink is the append-only storage seam. There is deliberately no update and no delete —
+// a sink that cannot rewrite history is the cheapest way to guarantee it.
+type Sink interface {
+	Append(record Record) error
+	// Last is the newest stored record, so a restarted process continues the same chain.
+	Last() (Record, bool, error)
+	// ReadAll returns the whole trail in write order, or an error on write-only sinks.
+	ReadAll() ([]Record, error)
+	Close() error
+}
+
+// ErrNotReadable is returned by sinks that cannot read back what they wrote.
+var ErrNotReadable = errors.New("audit: sink cannot read its own output")
+
+const auditFileMode = 0o600
+const auditDirMode = 0o700
+
+// FileSink writes newline-delimited JSON: one record per line, appended, never rewritten.
+type FileSink struct {
+	path string
+	mu   sync.Mutex
+}
+
+func NewFileSink(cfg Config) (*FileSink, error) {
+	path, err := filepath.Abs(cfg.FilePath)
+	if err != nil {
+		return nil, err
+	}
+	return &FileSink{path: path}, nil
+}
+
+func (s *FileSink) Append(record Record) error {
+	line, err := canonical(record)
+	if err != nil {
+		return err
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	if err := os.MkdirAll(filepath.Dir(s.path), auditDirMode); err != nil {
+		return err
+	}
+	// O_APPEND keeps concurrent writers from overwriting each other; the file is never truncated.
+	file, err := os.OpenFile(s.path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, auditFileMode)
+	if err != nil {
+		return err
+	}
+	defer file.Close()
+
+	if _, err := file.Write(append(line, '\n')); err != nil {
+		return err
+	}
+	// Durability is the point of an audit trail; a buffered write that never lands is a gap.
+	return file.Sync()
+}
+
+func (s *FileSink) Last() (Record, bool, error) {
+	records, err := s.ReadAll()
+	if err != nil || len(records) == 0 {
+		return Record{}, false, err
+	}
+	return records[len(records)-1], true, nil
+}
+
+func (s *FileSink) ReadAll() ([]Record, error) {
+	file, err := os.Open(s.path)
+	if errors.Is(err, os.ErrNotExist) {
+		return nil, nil // an absent trail is an empty trail, not a failure
+	}
+	if err != nil {
+		return nil, err
+	}
+	defer file.Close()
+
+	records := make([]Record, 0)
+	scanner := bufio.NewScanner(file)
+	scanner.Buffer(make([]byte, 0, 64*1024), 4*1024*1024)
+	for line := 1; scanner.Scan(); line++ {
+		if len(scanner.Bytes()) == 0 {
+			continue
+		}
+		var record Record
+		if err := json.Unmarshal(scanner.Bytes(), &record); err != nil {
+			return nil, fmt.Errorf("audit: line %d of %s is unreadable: %w", line, s.path, err)
+		}
+		records = append(records, record)
+	}
+	return records, scanner.Err()
+}
+
+func (s *FileSink) Close() error { return nil }
+
+// WriterSink emits one JSON object per line for a collector that already owns durability.
+type WriterSink struct {
+	out  io.Writer
+	mu   sync.Mutex
+	last Record
+	has  bool
+}
+
+func NewStdoutSink() *WriterSink { return &WriterSink{out: os.Stdout} }
+
+func (s *WriterSink) Append(record Record) error {
+	line, err := canonical(record)
+	if err != nil {
+		return err
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if _, err := s.out.Write(append(line, '\n')); err != nil {
+		return err
+	}
+	s.last, s.has = record, true
+	return nil
+}
+
+func (s *WriterSink) Last() (Record, bool, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.last, s.has, nil
+}
+
+func (s *WriterSink) ReadAll() ([]Record, error) { return nil, ErrNotReadable }
+
+func (s *WriterSink) Close() error { return nil }
+
+// MemorySink is for tests and dry runs. Bounded, because an unbounded slice behind a write
+// API is a leak.
+type MemorySink struct {
+	mu      sync.Mutex
+	records []Record
+	limit   int
+}
+
+func NewMemorySink(cfg Config) *MemorySink {
+	return &MemorySink{limit: cfg.MaxMemoryEvents}
+}
+
+func (s *MemorySink) Append(record Record) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if len(s.records) >= s.limit {
+		return fmt.Errorf("audit: in-memory sink is full at %d records", s.limit)
+	}
+	s.records = append(s.records, record)
+	return nil
+}
+
+func (s *MemorySink) Last() (Record, bool, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if len(s.records) == 0 {
+		return Record{}, false, nil
+	}
+	return s.records[len(s.records)-1], true, nil
+}
+
+func (s *MemorySink) ReadAll() ([]Record, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return append([]Record(nil), s.records...), nil
+}
+
+func (s *MemorySink) Close() error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.records = nil
+	return nil
+}
+
+// NewSink builds the sink named by configuration.
+func NewSink(cfg Config) (Sink, error) {
+	switch cfg.Sink {
+	case SinkFile:
+		return NewFileSink(cfg)
+	case SinkStdout:
+		return NewStdoutSink(), nil
+	case SinkMemory:
+		return NewMemorySink(cfg), nil
+	default:
+		return nil, fmt.Errorf("audit: unknown sink %q", cfg.Sink)
+	}
+}

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

@@ -0,0 +1,17 @@
+package audit
+
+// VerifyTrail reads the whole trail back and checks it. Run it from a cron job, a health
+// check, or a compliance command.
+func VerifyTrail(cfg Config) (Verification, error) {
+	sink, err := NewSink(cfg)
+	if err != nil {
+		return Verification{}, err
+	}
+	defer sink.Close()
+
+	records, err := sink.ReadAll()
+	if err != nil {
+		return Verification{}, err
+	}
+	return VerifyChain(records, cfg)
+}

package/templates/layers/audit-log/files/package.json

@@ -0,0 +1,5 @@
+{
+  "devDependencies": {
+    "vitest": "^4.1.10"
+  }
+}

package/templates/layers/audit-log/files/pyproject.toml

@@ -0,0 +1,2 @@
+[project]
+dependencies = ["structlog>=26.1.0"]

package/templates/layers/audit-log/files/src/__solutionName.dot__.Auditing/AuditChain.cs

@@ -0,0 +1,74 @@
+using System.Security.Cryptography;
+using System.Text;
+
+namespace {{ solutionName | dot }}.Auditing;
+
+/// <summary>Why a trail stopped being self-consistent.</summary>
+public static class AuditBreakReason
+{
+    public const string HashMismatch = "hash-mismatch";
+    public const string BrokenLink = "broken-link";
+    public const string SequenceGap = "sequence-gap";
+}
+
+public sealed record AuditChainBreak(long Sequence, string Id, string Reason);
+
+public sealed record AuditVerification(bool Valid, int Checked, IReadOnlyList<AuditChainBreak> Breaks);
+
+/// <summary>
+/// Hash chaining: each record commits to its predecessor's hash, so deleting or editing an
+/// entry breaks verification from that point on — the property an auditor actually checks.
+/// </summary>
+public static class AuditChain
+{
+    /// <summary>
+    /// 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.
+    /// </summary>
+    public static readonly string GenesisHash = new('0', 64);
+
+    public static string HashRecord(AuditRecord record, AuditOptions options)
+    {
+        var payload = Encoding.UTF8.GetBytes($"{record.PreviousHash}|{AuditSerialization.CanonicalPayload(record)}");
+        var digest = options.HashAlgorithm.ToLowerInvariant() switch
+        {
+            "sha256" => SHA256.HashData(payload),
+            "sha512" => SHA512.HashData(payload),
+            _ => throw new ArgumentException($"audit: unsupported hash algorithm \"{options.HashAlgorithm}\""),
+        };
+        // Lowercase hex, matching the other stacks' encoders so a trail is portable.
+        return Convert.ToHexString(digest).ToLowerInvariant();
+    }
+
+    /// <summary>
+    /// 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.
+    /// </summary>
+    public static AuditVerification VerifyChain(IReadOnlyList<AuditRecord> records, AuditOptions options)
+    {
+        var breaks = new List<AuditChainBreak>();
+        var previousHash = GenesisHash;
+        var expectedSequence = 1L;
+
+        foreach (var record in records)
+        {
+            if (record.Sequence != expectedSequence)
+            {
+                breaks.Add(new AuditChainBreak(record.Sequence, record.Id, AuditBreakReason.SequenceGap));
+            }
+            if (record.PreviousHash != previousHash)
+            {
+                breaks.Add(new AuditChainBreak(record.Sequence, record.Id, AuditBreakReason.BrokenLink));
+            }
+            if (HashRecord(record, options) != record.Hash)
+            {
+                breaks.Add(new AuditChainBreak(record.Sequence, record.Id, AuditBreakReason.HashMismatch));
+            }
+
+            previousHash = record.Hash;
+            expectedSequence = record.Sequence + 1;
+        }
+
+        return new AuditVerification(breaks.Count == 0, records.Count, breaks);
+    }
+}

package/templates/layers/audit-log/files/src/__solutionName.dot__.Auditing/AuditEvent.cs

@@ -0,0 +1,90 @@
+using System.Text.Json.Nodes;
+using System.Text.Json.Serialization;
+
+namespace {{ solutionName | dot }}.Auditing;
+
+/// <summary>Outcomes. "denied" is distinct from "failure" — a refused authorization is not a malfunction.</summary>
+public static class AuditOutcome
+{
+    public const string Success = "success";
+    public const string Failure = "failure";
+    public const string Denied = "denied";
+}
+
+public static class AuditActor
+{
+    public const string User = "user";
+    public const string Service = "service";
+    public const string System = "system";
+    public const string Anonymous = "anonymous";
+}
+
+public sealed class AuditEventException(string message) : Exception(message);
+
+/// <summary>What a caller supplies. Everything else is stamped by the recorder.</summary>
+public sealed record AuditEvent
+{
+    private const int MaxActionLength = 200;
+
+    public required string Action { get; init; }
+    public required string Outcome { get; init; }
+    public required string ActorId { get; init; }
+    public string ActorType { get; init; } = AuditActor.User;
+    public string ActorIp { get; init; } = "";
+    public string ResourceType { get; init; } = "";
+    public string ResourceId { get; init; } = "";
+
+    /// <summary>Why, in the caller's words — required reading when the outcome is denied.</summary>
+    public string Reason { get; init; } = "";
+    public string CorrelationId { get; init; } = "";
+    public JsonObject Metadata { get; init; } = new();
+
+    /// <summary>Rejects an event nobody could interpret during an investigation.</summary>
+    public void Validate()
+    {
+        if (string.IsNullOrWhiteSpace(Action))
+        {
+            throw new AuditEventException("audit: action is required");
+        }
+        if (Action.Length > MaxActionLength)
+        {
+            throw new AuditEventException($"audit: action exceeds {MaxActionLength} characters");
+        }
+        if (string.IsNullOrWhiteSpace(ActorId))
+        {
+            throw new AuditEventException("audit: actorId is required — use \"system\" for unattended work");
+        }
+        if (Outcome is not (AuditOutcome.Success or AuditOutcome.Failure or AuditOutcome.Denied))
+        {
+            throw new AuditEventException($"audit: unknown outcome \"{Outcome}\"");
+        }
+    }
+}
+
+/// <summary>
+/// What is written. The JSON names are part of the hashed payload: renaming one invalidates
+/// every hash already on disk, so bump <see cref="AuditRecord.CurrentSchemaVersion"/> instead.
+/// </summary>
+public sealed record AuditRecord
+{
+    public const int CurrentSchemaVersion = 1;
+
+    [JsonPropertyName("schemaVersion")] public int SchemaVersion { get; init; } = CurrentSchemaVersion;
+    [JsonPropertyName("sequence")] public long Sequence { get; init; }
+    [JsonPropertyName("id")] public string Id { get; init; } = "";
+    [JsonPropertyName("occurredAt")] public string OccurredAt { get; init; } = "";
+    [JsonPropertyName("service")] public string Service { get; init; } = "";
+    [JsonPropertyName("environment")] public string Environment { get; init; } = "";
+    [JsonPropertyName("action")] public string Action { get; init; } = "";
+    [JsonPropertyName("outcome")] public string Outcome { get; init; } = "";
+    [JsonPropertyName("actorId")] public string ActorId { get; init; } = "";
+    [JsonPropertyName("actorType")] public string ActorType { get; init; } = "";
+    [JsonPropertyName("actorIp")] public string ActorIp { get; init; } = "";
+    [JsonPropertyName("resourceType")] public string ResourceType { get; init; } = "";
+    [JsonPropertyName("resourceId")] public string ResourceId { get; init; } = "";
+    [JsonPropertyName("reason")] public string Reason { get; init; } = "";
+    [JsonPropertyName("correlationId")] public string CorrelationId { get; init; } = "";
+    [JsonPropertyName("metadata")] public JsonObject Metadata { get; init; } = new();
+    [JsonPropertyName("previousHash")] public string PreviousHash { get; init; } = "";
+    [JsonPropertyName("hash")] public string Hash { get; init; } = "";
+}

package/templates/layers/audit-log/files/src/__solutionName.dot__.Auditing/AuditOptions.cs

@@ -0,0 +1,104 @@
+namespace {{ solutionName | dot }}.Auditing;
+
+/// <summary>Where records are written. Protocol literals, not tunables.</summary>
+public enum AuditSinkKind
+{
+    File,
+    Stdout,
+    Memory,
+}
+
+/// <summary>The only place an audit setting is read. A path or field name at a call site is a bug.</summary>
+public sealed record AuditOptions
+{
+    private const string Prefix = "{{ auditEnvPrefix }}";
+
+    // Typed defaults. The single place a literal audit value may appear.
+    public bool Enabled { get; init; } = true;
+    public AuditSinkKind Sink { get; init; } = AuditSinkKind.{{ auditSink | pascal }};
+    public string FilePath { get; init; } = "{{ auditFilePath }}";
+    public string Service { get; init; } = "{{ solutionName | kebab }}";
+    public string Environment { get; init; } = "local";
+    public bool ChainEnabled { get; init; } = true;
+    public string HashAlgorithm { get; init; } = "{{ auditHashAlgorithm }}";
+    public IReadOnlyList<string> RedactFields { get; init; } = "{{ auditRedactFields }}".Split(',');
+    public string RedactPlaceholder { get; init; } = "[redacted]";
+
+    /// <summary>Reported, never enforced by deletion — expiry is an operational decision.</summary>
+    public int RetentionDays { get; init; } = {{ auditRetentionDays }};
+    public int MaxMemoryEvents { get; init; } = {{ auditMaxMemoryEvents }};
+
+    /// <summary>True aborts the audited operation when the sink fails, as most regimes require.</summary>
+    public bool FailClosed { get; init; } = true;
+
+    /// <summary>
+    /// Reads <c>{{ auditEnvPrefix }}_*</c>. Env-based so the layer stays free of a hosting
+    /// dependency; an ASP.NET host may bind its own configuration onto this record instead.
+    /// </summary>
+    public static AuditOptions FromEnvironment()
+    {
+        var defaults = new AuditOptions();
+        return defaults with
+        {
+            Enabled = Bool("ENABLED", defaults.Enabled),
+            Sink = Enum("SINK", defaults.Sink),
+            FilePath = Raw("FILE_PATH") ?? defaults.FilePath,
+            Service = Raw("SERVICE") ?? defaults.Service,
+            Environment = Raw("ENVIRONMENT") ?? defaults.Environment,
+            ChainEnabled = Bool("CHAIN_ENABLED", defaults.ChainEnabled),
+            HashAlgorithm = Raw("HASH_ALGORITHM") ?? defaults.HashAlgorithm,
+            RedactFields = List("REDACT_FIELDS", defaults.RedactFields),
+            RedactPlaceholder = Raw("REDACT_PLACEHOLDER") ?? defaults.RedactPlaceholder,
+            RetentionDays = Int("RETENTION_DAYS", defaults.RetentionDays),
+            MaxMemoryEvents = Int("MAX_MEMORY_EVENTS", defaults.MaxMemoryEvents),
+            FailClosed = Bool("FAIL_CLOSED", defaults.FailClosed),
+        };
+    }
+
+    private static string? Raw(string key)
+    {
+        var value = System.Environment.GetEnvironmentVariable($"{Prefix}_{key}")?.Trim();
+        return string.IsNullOrEmpty(value) ? null : value;
+    }
+
+    private static int Int(string key, int fallback)
+    {
+        var value = Raw(key);
+        if (value is null)
+        {
+            return fallback;
+        }
+        // Fail at startup rather than let a bad bound surface as a silent truncation later.
+        return int.TryParse(value, out var parsed) && parsed >= 0
+            ? parsed
+            : throw new ArgumentException($"{Prefix}_{key} must be a non-negative integer, got \"{value}\"");
+    }
+
+    private static bool Bool(string key, bool fallback)
+    {
+        var value = Raw(key)?.ToLowerInvariant();
+        return value is null ? fallback : value is "1" or "true" or "yes" or "on";
+    }
+
+    private static IReadOnlyList<string> List(string key, IReadOnlyList<string> fallback)
+    {
+        var value = Raw(key);
+        if (value is null)
+        {
+            return fallback;
+        }
+        return value.Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+    }
+
+    private static AuditSinkKind Enum(string key, AuditSinkKind fallback)
+    {
+        var value = Raw(key);
+        if (value is null)
+        {
+            return fallback;
+        }
+        return System.Enum.TryParse<AuditSinkKind>(value, ignoreCase: true, out var parsed)
+            ? parsed
+            : throw new ArgumentException($"{Prefix}_{key} must be file, stdout or memory, got \"{value}\"");
+    }
+}

package/templates/layers/audit-log/files/src/__solutionName.dot__.Auditing/AuditRecorder.cs

@@ -0,0 +1,106 @@
+namespace {{ solutionName | dot }}.Auditing;
+
+/// <summary>
+/// The write API. It exposes <see cref="RecordAsync"/> 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.
+/// </summary>
+public sealed class AuditRecorder(AuditOptions options, IAuditSink sink) : IAsyncDisposable
+{
+    // Serialized so two callers cannot claim the same sequence number.
+    private readonly SemaphoreSlim _gate = new(1, 1);
+    private string _previousHash = AuditChain.GenesisHash;
+    private long _sequence;
+    private bool _restored;
+
+    public static AuditRecorder FromEnvironment()
+    {
+        var options = AuditOptions.FromEnvironment();
+        return new AuditRecorder(options, AuditSinkFactory.Create(options));
+    }
+
+    /// <summary>Completes once the record is durable in the sink. Throws if it is not.</summary>
+    public async Task<AuditRecord> RecordAsync(AuditEvent auditEvent, CancellationToken cancellationToken = default)
+    {
+        auditEvent.Validate();
+
+        await _gate.WaitAsync(cancellationToken).ConfigureAwait(false);
+        try
+        {
+            await RestoreAsync(cancellationToken).ConfigureAwait(false);
+
+            var draft = new AuditRecord
+            {
+                Sequence = _sequence + 1,
+                Id = Guid.NewGuid().ToString(),
+                OccurredAt = DateTimeOffset.UtcNow.ToString("O"),
+                Service = options.Service,
+                Environment = options.Environment,
+                Action = auditEvent.Action,
+                Outcome = auditEvent.Outcome,
+                ActorId = auditEvent.ActorId,
+                ActorType = auditEvent.ActorType,
+                ActorIp = auditEvent.ActorIp,
+                ResourceType = auditEvent.ResourceType,
+                ResourceId = auditEvent.ResourceId,
+                Reason = auditEvent.Reason,
+                CorrelationId = auditEvent.CorrelationId,
+                Metadata = AuditSerialization.Redact(auditEvent.Metadata, options),
+                PreviousHash = options.ChainEnabled ? _previousHash : AuditChain.GenesisHash,
+            };
+            var record = draft with { Hash = AuditChain.HashRecord(draft, options) };
+
+            // 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 (!options.Enabled)
+            {
+                return record;
+            }
+
+            try
+            {
+                await sink.AppendAsync(record, cancellationToken).ConfigureAwait(false);
+            }
+            catch when (!options.FailClosed)
+            {
+                // 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.
+                return record;
+            }
+
+            _sequence = record.Sequence;
+            _previousHash = record.Hash;
+            return record;
+        }
+        finally
+        {
+            _gate.Release();
+        }
+    }
+
+    /// <summary>Continue an existing trail across restarts instead of forking a second chain.</summary>
+    private async Task RestoreAsync(CancellationToken cancellationToken)
+    {
+        if (_restored)
+        {
+            return;
+        }
+        _restored = true;
+        var last = await sink.LastAsync(cancellationToken).ConfigureAwait(false);
+        if (last is null)
+        {
+            return;
+        }
+        _sequence = last.Sequence;
+        _previousHash = last.Hash;
+    }
+
+    /// <summary>Reads the whole trail back and checks it. Run from a cron job or a compliance command.</summary>
+    public async Task<AuditVerification> VerifyAsync(CancellationToken cancellationToken = default) =>
+        AuditChain.VerifyChain(await sink.ReadAllAsync(cancellationToken).ConfigureAwait(false), options);
+
+    public async ValueTask DisposeAsync()
+    {
+        await sink.DisposeAsync().ConfigureAwait(false);
+        _gate.Dispose();
+    }
+}