@opengroundplan/core 0.1.1

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

@@ -0,0 +1,116 @@
+using System.Buffers;
+using System.Text;
+using System.Text.Json;
+using System.Text.Json.Nodes;
+
+namespace {{ solutionName | dot }}.Auditing;
+
+/// <summary>
+/// Redaction and canonical serialization. Redaction runs before serialization, so a secret
+/// never reaches the sink and never enters the hash chain — removing it afterwards would
+/// break every subsequent hash.
+/// </summary>
+public static class AuditSerialization
+{
+    private const int MaxDepth = 12;
+
+    /// <summary>Deep-copies while replacing matched keys; the caller's object is never mutated.</summary>
+    public static JsonObject Redact(JsonObject source, AuditOptions options)
+    {
+        var blocked = new HashSet<string>(options.RedactFields, StringComparer.OrdinalIgnoreCase);
+        return (JsonObject)RedactNode(source, blocked, options.RedactPlaceholder, 0)!;
+    }
+
+    private static JsonNode? RedactNode(JsonNode? node, HashSet<string> blocked, string placeholder, int depth)
+    {
+        if (depth > MaxDepth)
+        {
+            return JsonValue.Create("[truncated]");
+        }
+
+        switch (node)
+        {
+            case JsonObject obj:
+                var copy = new JsonObject();
+                foreach (var (key, value) in obj)
+                {
+                    copy[key] = blocked.Contains(key)
+                        ? JsonValue.Create(placeholder)
+                        : RedactNode(value, blocked, placeholder, depth + 1);
+                }
+                return copy;
+
+            case JsonArray array:
+                var items = new JsonArray();
+                foreach (var value in array)
+                {
+                    items.Add(RedactNode(value, blocked, placeholder, depth + 1));
+                }
+                return items;
+
+            default:
+                return node?.DeepClone();
+        }
+    }
+
+    /// <summary>
+    /// Keys sorted, no whitespace. Two processes must serialize a record byte-identically or
+    /// the chain can only be verified where it was built.
+    /// </summary>
+    public static string Canonical(AuditRecord record) => CanonicalNode(ToNode(record));
+
+    /// <summary>The bytes a record's hash commits to: everything except the hash itself.</summary>
+    public static string CanonicalPayload(AuditRecord record)
+    {
+        var node = ToNode(record);
+        node.Remove("hash");
+        return CanonicalNode(node);
+    }
+
+    private static JsonObject ToNode(AuditRecord record) =>
+        JsonSerializer.SerializeToNode(record)!.AsObject();
+
+    private static string CanonicalNode(JsonNode node)
+    {
+        var buffer = new ArrayBufferWriter<byte>();
+        using (var writer = new Utf8JsonWriter(buffer, new JsonWriterOptions { Indented = false }))
+        {
+            Write(node, writer);
+        }
+        return Encoding.UTF8.GetString(buffer.WrittenSpan);
+    }
+
+    private static void Write(JsonNode? node, Utf8JsonWriter writer)
+    {
+        switch (node)
+        {
+            case JsonObject obj:
+                writer.WriteStartObject();
+                // Ordinal sort so the byte order never depends on the current culture.
+                foreach (var (key, value) in obj.OrderBy(pair => pair.Key, StringComparer.Ordinal))
+                {
+                    writer.WritePropertyName(key);
+                    Write(value, writer);
+                }
+                writer.WriteEndObject();
+                break;
+
+            case JsonArray array:
+                writer.WriteStartArray();
+                foreach (var value in array)
+                {
+                    Write(value, writer);
+                }
+                writer.WriteEndArray();
+                break;
+
+            case null:
+                writer.WriteNullValue();
+                break;
+
+            default:
+                node.WriteTo(writer);
+                break;
+        }
+    }
+}

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

@@ -0,0 +1,165 @@
+using System.Text;
+using System.Text.Json;
+
+namespace {{ solutionName | dot }}.Auditing;
+
+/// <summary>
+/// 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.
+/// </summary>
+public interface IAuditSink : IAsyncDisposable
+{
+    Task AppendAsync(AuditRecord record, CancellationToken cancellationToken = default);
+
+    /// <summary>Newest stored record, so a restarted process continues the same chain.</summary>
+    Task<AuditRecord?> LastAsync(CancellationToken cancellationToken = default);
+
+    /// <summary>Whole trail in write order. Throws on sinks that cannot read their own output.</summary>
+    Task<IReadOnlyList<AuditRecord>> ReadAllAsync(CancellationToken cancellationToken = default);
+}
+
+public sealed class AuditSinkException(string message, Exception? inner = null) : Exception(message, inner);
+
+/// <summary>Newline-delimited JSON: one record per line, appended, never rewritten.</summary>
+public sealed class FileAuditSink(AuditOptions options) : IAuditSink
+{
+    private readonly string _path = Path.GetFullPath(options.FilePath);
+    private readonly SemaphoreSlim _gate = new(1, 1);
+
+    public async Task AppendAsync(AuditRecord record, CancellationToken cancellationToken = default)
+    {
+        var line = AuditSerialization.Canonical(record);
+        await _gate.WaitAsync(cancellationToken).ConfigureAwait(false);
+        try
+        {
+            Directory.CreateDirectory(Path.GetDirectoryName(_path)!);
+            // Append mode never truncates, and the flush makes the entry durable before we return.
+            await using var stream = new FileStream(
+                _path, FileMode.Append, FileAccess.Write, FileShare.Read, bufferSize: 4096, useAsync: true);
+            await stream.WriteAsync(Encoding.UTF8.GetBytes(line + "\n"), cancellationToken).ConfigureAwait(false);
+            await stream.FlushAsync(cancellationToken).ConfigureAwait(false);
+        }
+        finally
+        {
+            _gate.Release();
+        }
+    }
+
+    public async Task<AuditRecord?> LastAsync(CancellationToken cancellationToken = default)
+    {
+        var records = await ReadAllAsync(cancellationToken).ConfigureAwait(false);
+        return records.Count == 0 ? null : records[^1];
+    }
+
+    public async Task<IReadOnlyList<AuditRecord>> ReadAllAsync(CancellationToken cancellationToken = default)
+    {
+        // An absent trail is an empty trail, not a failure — first run must not throw.
+        if (!File.Exists(_path))
+        {
+            return [];
+        }
+
+        var records = new List<AuditRecord>();
+        var number = 0;
+        foreach (var line in await File.ReadAllLinesAsync(_path, cancellationToken).ConfigureAwait(false))
+        {
+            number++;
+            if (string.IsNullOrWhiteSpace(line))
+            {
+                continue;
+            }
+            try
+            {
+                records.Add(JsonSerializer.Deserialize<AuditRecord>(line)
+                    ?? throw new AuditSinkException($"audit: line {number} of {_path} is null"));
+            }
+            catch (JsonException exception)
+            {
+                throw new AuditSinkException($"audit: line {number} of {_path} is unreadable", exception);
+            }
+        }
+        return records;
+    }
+
+    public ValueTask DisposeAsync()
+    {
+        _gate.Dispose();
+        return ValueTask.CompletedTask;
+    }
+}
+
+/// <summary>For a collector that already owns durability. Not readable back, so not verifiable here.</summary>
+public sealed class ConsoleAuditSink : IAuditSink
+{
+    private AuditRecord? _last;
+
+    public async Task AppendAsync(AuditRecord record, CancellationToken cancellationToken = default)
+    {
+        await Console.Out.WriteLineAsync(AuditSerialization.Canonical(record)).ConfigureAwait(false);
+        _last = record;
+    }
+
+    public Task<AuditRecord?> LastAsync(CancellationToken cancellationToken = default) =>
+        Task.FromResult(_last);
+
+    public Task<IReadOnlyList<AuditRecord>> ReadAllAsync(CancellationToken cancellationToken = default) =>
+        throw new AuditSinkException("audit: the console sink cannot read its own output");
+
+    public ValueTask DisposeAsync() => ValueTask.CompletedTask;
+}
+
+/// <summary>Tests and dry runs. Bounded, because an unbounded list behind a write API is a leak.</summary>
+public sealed class MemoryAuditSink(AuditOptions options) : IAuditSink
+{
+    private readonly List<AuditRecord> _records = [];
+    private readonly int _limit = options.MaxMemoryEvents;
+
+    public Task AppendAsync(AuditRecord record, CancellationToken cancellationToken = default)
+    {
+        lock (_records)
+        {
+            if (_records.Count >= _limit)
+            {
+                throw new AuditSinkException($"audit: in-memory sink is full at {_limit} records");
+            }
+            _records.Add(record);
+        }
+        return Task.CompletedTask;
+    }
+
+    public Task<AuditRecord?> LastAsync(CancellationToken cancellationToken = default)
+    {
+        lock (_records)
+        {
+            return Task.FromResult<AuditRecord?>(_records.Count == 0 ? null : _records[^1]);
+        }
+    }
+
+    public Task<IReadOnlyList<AuditRecord>> ReadAllAsync(CancellationToken cancellationToken = default)
+    {
+        lock (_records)
+        {
+            return Task.FromResult<IReadOnlyList<AuditRecord>>([.. _records]);
+        }
+    }
+
+    public ValueTask DisposeAsync()
+    {
+        lock (_records)
+        {
+            _records.Clear();
+        }
+        return ValueTask.CompletedTask;
+    }
+}
+
+public static class AuditSinkFactory
+{
+    public static IAuditSink Create(AuditOptions options) => options.Sink switch
+    {
+        AuditSinkKind.File => new FileAuditSink(options),
+        AuditSinkKind.Stdout => new ConsoleAuditSink(),
+        AuditSinkKind.Memory => new MemoryAuditSink(options),
+        _ => throw new AuditSinkException($"audit: unknown sink \"{options.Sink}\""),
+    };
+}

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

@@ -0,0 +1,17 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <!-- Deliberately zero PackageReferences: hashing, JSON and file append are all in the
+       base class library, and an audit trail must not drag a driver or a hosting model
+       into projects that only need to write a record. -->
+  <PropertyGroup>
+    <TargetFramework>{{ dotnetTargetFramework }}</TargetFramework>
+    <RootNamespace>{{ solutionName | dot }}.Auditing</RootNamespace>
+    <AssemblyName>{{ solutionName | dot }}.Auditing</AssemblyName>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <LangVersion>latest</LangVersion>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <NoWarn>$(NoWarn);CS1591</NoWarn>
+  </PropertyGroup>
+
+</Project>

package/templates/layers/audit-log/files/src/__solutionName.snake__/audit/chain.py

@@ -0,0 +1,56 @@
+"""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.
+"""
+
+import hashlib
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from {{ solutionName | snake }}.audit.event import AuditRecord
+from {{ solutionName | snake }}.audit.redact import canonical_payload
+from {{ solutionName | snake }}.audit.settings import AuditSettings
+
+# 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.
+GENESIS_HASH = "0" * 64
+
+
+def hash_record(record: AuditRecord, settings: AuditSettings) -> str:
+    payload = f"{record.previous_hash}|{canonical_payload(record.as_dict())}"
+    return hashlib.new(settings.hash_algorithm, payload.encode("utf-8")).hexdigest()
+
+
+@dataclass(frozen=True, slots=True)
+class ChainBreak:
+    sequence: int
+    id: str
+    reason: str
+
+
+@dataclass(frozen=True, slots=True)
+class ChainVerification:
+    valid: bool
+    checked: int
+    breaks: list[ChainBreak]
+
+
+def verify_chain(records: Sequence[AuditRecord], settings: AuditSettings) -> ChainVerification:
+    """Reports every break, not just the first — an investigator needs the full extent."""
+    breaks: list[ChainBreak] = []
+    previous_hash = GENESIS_HASH
+    expected_sequence = 1
+
+    for record in records:
+        if record.sequence != expected_sequence:
+            breaks.append(ChainBreak(record.sequence, record.id, "sequence-gap"))
+        if record.previous_hash != previous_hash:
+            breaks.append(ChainBreak(record.sequence, record.id, "broken-link"))
+        if hash_record(record, settings) != record.hash:
+            breaks.append(ChainBreak(record.sequence, record.id, "hash-mismatch"))
+
+        previous_hash = record.hash
+        expected_sequence = record.sequence + 1
+
+    return ChainVerification(valid=not breaks, checked=len(records), breaks=breaks)

package/templates/layers/audit-log/files/src/__solutionName.snake__/audit/event.py

@@ -0,0 +1,118 @@
+"""The audit record schema.
+
+Field names and the outcome set are protocol literals: once a trail exists on disk,
+renaming a field invalidates every hash already written.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+AUDIT_SCHEMA_VERSION = 1
+
+# `denied` is distinct from `failure` — a refused authorization is not a malfunction.
+Outcome = Literal["success", "failure", "denied"]
+ActorType = Literal["user", "service", "system", "anonymous"]
+
+_OUTCOMES = ("success", "failure", "denied")
+_MAX_ACTION_LENGTH = 200
+
+
+class AuditEventError(ValueError):
+    """Raised for an event that could not be interpreted during an investigation."""
+
+
+@dataclass(frozen=True, slots=True)
+class AuditEvent:
+    """What a caller supplies. Everything else is stamped by the recorder."""
+
+    action: str
+    outcome: Outcome
+    actor_id: str
+    actor_type: ActorType = "user"
+    actor_ip: str = ""
+    resource_type: str = ""
+    resource_id: str = ""
+    reason: str = ""
+    correlation_id: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class AuditRecord:
+    """What is written. Serialization sorts keys, so declaration order is not load-bearing."""
+
+    schema_version: int
+    sequence: int
+    id: str
+    occurred_at: str
+    service: str
+    environment: str
+    action: str
+    outcome: str
+    actor_id: str
+    actor_type: str
+    actor_ip: str
+    resource_type: str
+    resource_id: str
+    reason: str
+    correlation_id: str
+    metadata: dict[str, Any]
+    previous_hash: str
+    hash: str
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "schemaVersion": self.schema_version,
+            "sequence": self.sequence,
+            "id": self.id,
+            "occurredAt": self.occurred_at,
+            "service": self.service,
+            "environment": self.environment,
+            "action": self.action,
+            "outcome": self.outcome,
+            "actorId": self.actor_id,
+            "actorType": self.actor_type,
+            "actorIp": self.actor_ip,
+            "resourceType": self.resource_type,
+            "resourceId": self.resource_id,
+            "reason": self.reason,
+            "correlationId": self.correlation_id,
+            "metadata": self.metadata,
+            "previousHash": self.previous_hash,
+            "hash": self.hash,
+        }
+
+    @staticmethod
+    def from_dict(data: dict[str, Any]) -> "AuditRecord":
+        return AuditRecord(
+            schema_version=int(data["schemaVersion"]),
+            sequence=int(data["sequence"]),
+            id=str(data["id"]),
+            occurred_at=str(data["occurredAt"]),
+            service=str(data["service"]),
+            environment=str(data["environment"]),
+            action=str(data["action"]),
+            outcome=str(data["outcome"]),
+            actor_id=str(data["actorId"]),
+            actor_type=str(data["actorType"]),
+            actor_ip=str(data["actorIp"]),
+            resource_type=str(data["resourceType"]),
+            resource_id=str(data["resourceId"]),
+            reason=str(data["reason"]),
+            correlation_id=str(data["correlationId"]),
+            metadata=dict(data["metadata"]),
+            previous_hash=str(data["previousHash"]),
+            hash=str(data["hash"]),
+        )
+
+
+def assert_valid(event: AuditEvent) -> None:
+    """Rejects an unusable event at the call site instead of writing an uninterpretable record."""
+    if not event.action.strip():
+        raise AuditEventError("audit: action is required")
+    if len(event.action) > _MAX_ACTION_LENGTH:
+        raise AuditEventError(f"audit: action exceeds {_MAX_ACTION_LENGTH} characters")
+    if not event.actor_id.strip():
+        raise AuditEventError("audit: actor_id is required — use 'system' for unattended work")
+    if event.outcome not in _OUTCOMES:
+        raise AuditEventError(f"audit: unknown outcome {event.outcome!r}")

package/templates/layers/audit-log/files/src/__solutionName.snake__/audit/recorder.py

@@ -0,0 +1,118 @@
+"""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 class.
+"""
+
+import threading
+import uuid
+from dataclasses import replace
+from datetime import UTC, datetime
+
+from {{ solutionName | snake }}.audit.chain import GENESIS_HASH, hash_record
+from {{ solutionName | snake }}.audit.event import (
+    AUDIT_SCHEMA_VERSION,
+    AuditEvent,
+    AuditRecord,
+    assert_valid,
+)
+from {{ solutionName | snake }}.audit.redact import redact
+from {{ solutionName | snake }}.audit.settings import AuditSettings, get_settings
+from {{ solutionName | snake }}.audit.sinks import AuditSink, create_sink
+
+
+class AuditRecorder:
+    def __init__(
+        self, settings: AuditSettings | None = None, sink: AuditSink | None = None
+    ) -> None:
+        self._settings = settings or get_settings()
+        self._sink = sink or create_sink(self._settings)
+        self._previous_hash = GENESIS_HASH
+        self._sequence = 0
+        self._restored = False
+        # Serialized so two threads cannot claim the same sequence number.
+        self._lock = threading.Lock()
+
+    def record(self, event: AuditEvent) -> AuditRecord:
+        """Returns once the record is durable in the sink. Raises if it is not."""
+        assert_valid(event)
+        with self._lock:
+            return self._append(event)
+
+    def _append(self, event: AuditEvent) -> AuditRecord:
+        self._restore()
+
+        draft = AuditRecord(
+            schema_version=AUDIT_SCHEMA_VERSION,
+            sequence=self._sequence + 1,
+            id=str(uuid.uuid4()),
+            occurred_at=datetime.now(UTC).isoformat(timespec="milliseconds"),
+            service=self._settings.service,
+            environment=self._settings.environment,
+            action=event.action,
+            outcome=event.outcome,
+            actor_id=event.actor_id,
+            actor_type=event.actor_type,
+            actor_ip=event.actor_ip,
+            resource_type=event.resource_type,
+            resource_id=event.resource_id,
+            reason=event.reason,
+            correlation_id=event.correlation_id,
+            metadata=redact(dict(event.metadata), self._settings),
+            previous_hash=self._previous_hash if self._settings.chain_enabled else GENESIS_HASH,
+            hash="",
+        )
+        record = replace(draft, hash=hash_record(draft, self._settings))
+
+        # 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 not self._settings.enabled:
+            return record
+
+        try:
+            self._sink.append(record)
+        except Exception:
+            # 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 self._settings.fail_closed:
+                raise
+            return record
+
+        self._sequence = record.sequence
+        self._previous_hash = record.hash
+        return record
+
+    def _restore(self) -> None:
+        """Continue an existing trail across restarts instead of forking a second chain."""
+        if self._restored:
+            return
+        self._restored = True
+        last = self._sink.last()
+        if last is None:
+            return
+        self._sequence = last.sequence
+        self._previous_hash = last.hash
+
+    def close(self) -> None:
+        self._sink.close()
+
+
+_shared: AuditRecorder | None = None
+_shared_lock = threading.Lock()
+
+
+def get_recorder() -> AuditRecorder:
+    """One recorder per process; a second one would issue duplicate sequence numbers."""
+    global _shared
+    with _shared_lock:
+        if _shared is None:
+            _shared = AuditRecorder()
+        return _shared
+
+
+def reset_recorder() -> None:
+    global _shared
+    with _shared_lock:
+        if _shared is not None:
+            _shared.close()
+        _shared = None

package/templates/layers/audit-log/files/src/__solutionName.snake__/audit/redact.py

@@ -0,0 +1,41 @@
+"""Redaction and canonical serialization.
+
+Redaction runs before serialization, so a secret never reaches the sink and never enters
+the hash chain. Removing it afterwards would break every subsequent hash.
+"""
+
+import json
+from typing import Any
+
+from {{ solutionName | snake }}.audit.settings import AuditSettings
+
+_MAX_DEPTH = 12
+
+
+def redact(value: Any, settings: AuditSettings, depth: int = 0) -> Any:
+    """Deep-copies while replacing matched keys; the caller's object is never mutated."""
+    if depth > _MAX_DEPTH:
+        return "[truncated]"
+    if isinstance(value, list):
+        return [redact(item, settings, depth + 1) for item in value]
+    if not isinstance(value, dict):
+        return value
+
+    blocked = {name.lower() for name in settings.redact_fields}
+    return {
+        key: settings.redact_placeholder
+        if str(key).lower() in blocked
+        else redact(item, settings, depth + 1)
+        for key, item in value.items()
+    }
+
+
+def canonical(payload: dict[str, Any]) -> str:
+    """Keys sorted, no whitespace — two processes must serialize a record byte-identically."""
+    return json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def canonical_payload(record_dict: dict[str, Any]) -> str:
+    """The bytes a record's hash commits to: everything except the hash itself."""
+    rest = {key: item for key, item in record_dict.items() if key != "hash"}
+    return canonical(rest)