@opengroundplan/core 0.1.1

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

@@ -0,0 +1,102 @@
+"""The only place an audit default may appear.
+
+Every other audit module reads this table; a path, a hash name, or a redacted field
+written at a call site is a bug.
+"""
+
+import os
+from dataclasses import dataclass, field
+from functools import lru_cache
+
+_PREFIX = "{{ auditEnvPrefix }}"
+
+_SINK_KINDS = ("file", "stdout", "memory")
+
+# Read through a name, not inline: a literal ``"a,b".split(",")`` is flagged by ruff (SIM905).
+_REDACT_FIELDS_RAW = "{{ auditRedactFields }}"
+_TRUE = {"1", "true", "yes", "on"}
+
+
+def _raw(key: str) -> str | None:
+    value = os.environ.get(f"{_PREFIX}_{key}")
+    return value.strip() if value and value.strip() else None
+
+
+def _int(key: str, fallback: int) -> int:
+    value = _raw(key)
+    if value is None:
+        return fallback
+    try:
+        parsed = int(value)
+    except ValueError as exc:  # fail at startup, not at the first record written
+        raise ValueError(f"{_PREFIX}_{key} must be an integer, got {value!r}") from exc
+    if parsed < 0:
+        raise ValueError(f"{_PREFIX}_{key} must be non-negative, got {parsed}")
+    return parsed
+
+
+def _bool(key: str, fallback: bool) -> bool:
+    value = _raw(key)
+    return fallback if value is None else value.lower() in _TRUE
+
+
+def _csv(key: str, fallback: tuple[str, ...]) -> tuple[str, ...]:
+    value = _raw(key)
+    if value is None:
+        return fallback
+    return tuple(item.strip() for item in value.split(",") if item.strip())
+
+
+def _sink(key: str, fallback: str) -> str:
+    value = _raw(key)
+    if value is None:
+        return fallback
+    if value.lower() not in _SINK_KINDS:
+        raise ValueError(f"{_PREFIX}_{key} must be one of {', '.join(_SINK_KINDS)}, got {value!r}")
+    return value.lower()
+
+
+@dataclass(frozen=True, slots=True)
+class AuditSettings:
+    """Typed defaults. Change a value here or in the environment, never at a call site."""
+
+    enabled: bool = True
+    sink: str = "{{ auditSink }}"
+    file_path: str = "{{ auditFilePath }}"
+    service: str = "{{ solutionName | kebab }}"
+    environment: str = "local"
+    chain_enabled: bool = True
+    hash_algorithm: str = "{{ auditHashAlgorithm }}"
+    redact_fields: tuple[str, ...] = field(
+        default_factory=lambda: tuple(
+            item.strip() for item in _REDACT_FIELDS_RAW.split(",") if item.strip()
+        )
+    )
+    redact_placeholder: str = "[redacted]"
+    retention_days: int = {{ auditRetentionDays }}
+    max_memory_events: int = {{ auditMaxMemoryEvents }}
+    fail_closed: bool = True
+
+
+def load_settings() -> AuditSettings:
+    defaults = AuditSettings()
+    return AuditSettings(
+        enabled=_bool("ENABLED", defaults.enabled),
+        sink=_sink("SINK", defaults.sink),
+        file_path=_raw("FILE_PATH") or defaults.file_path,
+        service=_raw("SERVICE") or defaults.service,
+        environment=_raw("ENVIRONMENT") or defaults.environment,
+        chain_enabled=_bool("CHAIN_ENABLED", defaults.chain_enabled),
+        hash_algorithm=_raw("HASH_ALGORITHM") or defaults.hash_algorithm,
+        redact_fields=_csv("REDACT_FIELDS", defaults.redact_fields),
+        redact_placeholder=_raw("REDACT_PLACEHOLDER") or defaults.redact_placeholder,
+        retention_days=_int("RETENTION_DAYS", defaults.retention_days),
+        max_memory_events=_int("MAX_MEMORY_EVENTS", defaults.max_memory_events),
+        fail_closed=_bool("FAIL_CLOSED", defaults.fail_closed),
+    )
+
+
+@lru_cache
+def get_settings() -> AuditSettings:
+    """Cached so the environment is read once and every caller shares one instance."""
+    return load_settings()

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

@@ -0,0 +1,121 @@
+"""The append-only sink seam plus its three implementations.
+
+The port has no update and no delete on purpose — a sink that cannot rewrite history is
+the cheapest way to guarantee it.
+"""
+
+import json
+import sys
+from pathlib import Path
+from typing import Protocol
+
+from {{ solutionName | snake }}.audit.event import AuditRecord
+from {{ solutionName | snake }}.audit.redact import canonical
+from {{ solutionName | snake }}.audit.settings import AuditSettings
+
+
+class AuditSinkError(RuntimeError):
+    """Raised when a record could not be made durable, or a trail could not be read back."""
+
+
+class AuditSink(Protocol):
+    def append(self, record: AuditRecord) -> None: ...
+
+    def last(self) -> AuditRecord | None:
+        """Last stored record, so a restarted process continues the same chain."""
+        ...
+
+    def read_all(self) -> list[AuditRecord]:
+        """Whole trail in write order. Raises on sinks that cannot read their own output."""
+        ...
+
+    def close(self) -> None: ...
+
+
+class FileAuditSink:
+    """Newline-delimited JSON: one record per line, appended, never rewritten."""
+
+    def __init__(self, settings: AuditSettings) -> None:
+        self._path = Path(settings.file_path).resolve()
+        self._directory_ready = False
+
+    def append(self, record: AuditRecord) -> None:
+        if not self._directory_ready:
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            self._directory_ready = True
+        # "a" is atomic for small writes on POSIX, so concurrent appends stay line-clean.
+        with self._path.open("a", encoding="utf-8") as handle:
+            handle.write(canonical(record.as_dict()) + "\n")
+
+    def last(self) -> AuditRecord | None:
+        records = self.read_all()
+        return records[-1] if records else None
+
+    def read_all(self) -> list[AuditRecord]:
+        if not self._path.exists():
+            return []  # an absent trail is an empty trail, not a failure
+        records: list[AuditRecord] = []
+        with self._path.open("r", encoding="utf-8") as handle:
+            for number, line in enumerate(handle, start=1):
+                if not line.strip():
+                    continue
+                try:
+                    records.append(AuditRecord.from_dict(json.loads(line)))
+                except (ValueError, KeyError) as exc:
+                    raise AuditSinkError(
+                        f"audit: line {number} of {self._path} is unreadable"
+                    ) from exc
+        return records
+
+    def close(self) -> None:
+        self._directory_ready = False
+
+
+class StdoutAuditSink:
+    """For a collector that already owns durability. Not readable back, so not verifiable here."""
+
+    def __init__(self) -> None:
+        self._last: AuditRecord | None = None
+
+    def append(self, record: AuditRecord) -> None:
+        sys.stdout.write(canonical(record.as_dict()) + "\n")
+        self._last = record
+
+    def last(self) -> AuditRecord | None:
+        return self._last
+
+    def read_all(self) -> list[AuditRecord]:
+        raise AuditSinkError("audit: the stdout sink cannot read its own output")
+
+    def close(self) -> None:
+        self._last = None
+
+
+class MemoryAuditSink:
+    """Tests and dry runs. Bounded, because an unbounded list behind a write API is a leak."""
+
+    def __init__(self, settings: AuditSettings) -> None:
+        self._records: list[AuditRecord] = []
+        self._limit = settings.max_memory_events
+
+    def append(self, record: AuditRecord) -> None:
+        if len(self._records) >= self._limit:
+            raise AuditSinkError(f"audit: in-memory sink is full at {self._limit} records")
+        self._records.append(record)
+
+    def last(self) -> AuditRecord | None:
+        return self._records[-1] if self._records else None
+
+    def read_all(self) -> list[AuditRecord]:
+        return list(self._records)
+
+    def close(self) -> None:
+        self._records.clear()
+
+
+def create_sink(settings: AuditSettings) -> AuditSink:
+    if settings.sink == "file":
+        return FileAuditSink(settings)
+    if settings.sink == "stdout":
+        return StdoutAuditSink()
+    return MemoryAuditSink(settings)

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

@@ -0,0 +1,14 @@
+"""Reads the whole trail back and checks it. Run from a cron job or a compliance command."""
+
+from {{ solutionName | snake }}.audit.chain import ChainVerification, verify_chain
+from {{ solutionName | snake }}.audit.settings import get_settings
+from {{ solutionName | snake }}.audit.sinks import create_sink
+
+
+def verify_audit_trail() -> ChainVerification:
+    settings = get_settings()
+    sink = create_sink(settings)
+    try:
+        return verify_chain(sink.read_all(), settings)
+    finally:
+        sink.close()

package/templates/layers/audit-log/files/src/audit/chain.ts

@@ -0,0 +1,59 @@
+/**
+ * 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 { createHash } from 'node:crypto';
+import { canonicalPayload } from './redact.js';
+import type { AuditRecord } from './event.js';
+import type { AuditSettings } from './settings.js';
+
+/**
+ * Genesis link — a fixed sentinel, not a digest, so a chain that starts at record 1 cannot
+ * be confused with one whose head was truncated. Width is independent of the hash choice.
+ */
+export const GENESIS_HASH = '0'.repeat(64);
+
+export function hashRecord(record: AuditRecord, settings: AuditSettings): string {
+  return createHash(settings.hashAlgorithm)
+    .update(`${record.previousHash}|${canonicalPayload(record)}`, 'utf8')
+    .digest('hex');
+}
+
+export interface ChainBreak {
+  sequence: number;
+  id: string;
+  reason: 'hash-mismatch' | 'broken-link' | 'sequence-gap';
+}
+
+export interface ChainVerification {
+  valid: boolean;
+  checked: number;
+  breaks: ChainBreak[];
+}
+
+/**
+ * Verifies records in write order. Reports every break rather than stopping at the first —
+ * an investigator needs the full extent of the damage, not its earliest symptom.
+ */
+export function verifyChain(records: readonly AuditRecord[], settings: AuditSettings): ChainVerification {
+  const breaks: ChainBreak[] = [];
+  let previousHash = GENESIS_HASH;
+  let expectedSequence = 1;
+
+  for (const record of records) {
+    if (record.sequence !== expectedSequence) {
+      breaks.push({ sequence: record.sequence, id: record.id, reason: 'sequence-gap' });
+    }
+    if (record.previousHash !== previousHash) {
+      breaks.push({ sequence: record.sequence, id: record.id, reason: 'broken-link' });
+    }
+    if (hashRecord(record, settings) !== record.hash) {
+      breaks.push({ sequence: record.sequence, id: record.id, reason: 'hash-mismatch' });
+    }
+
+    previousHash = record.hash;
+    expectedSequence = record.sequence + 1;
+  }
+
+  return { valid: breaks.length === 0, checked: records.length, breaks };
+}

package/templates/layers/audit-log/files/src/audit/event.ts

@@ -0,0 +1,73 @@
+/**
+ * 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.
+ */
+
+export const AUDIT_SCHEMA_VERSION = 1;
+
+/** `denied` is distinct from `failure` — a refused authorization is not a malfunction. */
+export type AuditOutcome = 'success' | 'failure' | 'denied';
+
+export type AuditActorType = 'user' | 'service' | 'system' | 'anonymous';
+
+export type AuditMetadata = Record<string, unknown>;
+
+/** What a caller supplies. Everything else is stamped by the recorder. */
+export interface AuditEvent {
+  action: string;
+  outcome: AuditOutcome;
+  actorId: string;
+  actorType?: AuditActorType;
+  actorIp?: string;
+  resourceType?: string;
+  resourceId?: string;
+  /** Why, in the caller's words — required reading when the outcome is `denied`. */
+  reason?: string;
+  correlationId?: string;
+  metadata?: AuditMetadata;
+}
+
+/** What is written. Field order here is the canonical serialization order. */
+export interface AuditRecord {
+  schemaVersion: number;
+  sequence: number;
+  id: string;
+  occurredAt: string;
+  service: string;
+  environment: string;
+  action: string;
+  outcome: AuditOutcome;
+  actorId: string;
+  actorType: AuditActorType;
+  actorIp: string;
+  resourceType: string;
+  resourceId: string;
+  reason: string;
+  correlationId: string;
+  metadata: AuditMetadata;
+  previousHash: string;
+  hash: string;
+}
+
+export class AuditEventError extends Error {}
+
+const MAX_ACTION_LENGTH = 200;
+
+/**
+ * Rejects an unusable event at the call site instead of writing a record nobody can
+ * interpret during an investigation.
+ */
+export function assertValidEvent(event: AuditEvent): void {
+  if (!event.action || event.action.trim() === '') {
+    throw new AuditEventError('audit: action is required');
+  }
+  if (event.action.length > MAX_ACTION_LENGTH) {
+    throw new AuditEventError(`audit: action exceeds ${MAX_ACTION_LENGTH} characters`);
+  }
+  if (!event.actorId || event.actorId.trim() === '') {
+    throw new AuditEventError('audit: actorId is required — use "system" for unattended work');
+  }
+  if (event.outcome !== 'success' && event.outcome !== 'failure' && event.outcome !== 'denied') {
+    throw new AuditEventError(`audit: unknown outcome "${String(event.outcome)}"`);
+  }
+}

package/templates/layers/audit-log/files/src/audit/index.ts

@@ -0,0 +1,32 @@
+/** Public surface of the audit layer. Import from here, never from a sibling module. */
+export { AUDIT_SCHEMA_VERSION, AuditEventError, assertValidEvent } from './event.js';
+export type { AuditActorType, AuditEvent, AuditMetadata, AuditOutcome, AuditRecord } from './event.js';
+
+export { GENESIS_HASH, hashRecord, verifyChain } from './chain.js';
+export type { ChainBreak, ChainVerification } from './chain.js';
+
+export { canonicalize, redactMetadata } from './redact.js';
+
+export { AuditRecorder, auditRecorder, resetAuditRecorder } from './recorder.js';
+
+export { AuditSinkError, FileAuditSink, MemoryAuditSink, StdoutAuditSink, createSink } from './sinks.js';
+export type { AuditSink } from './sinks.js';
+
+export { auditSettings, loadAuditSettings, resetAuditSettings } from './settings.js';
+export type { AuditSettings, AuditSinkKind } from './settings.js';
+
+import { verifyChain } from './chain.js';
+import { createSink } from './sinks.js';
+import { auditSettings } from './settings.js';
+import type { ChainVerification } from './chain.js';
+
+/** Reads the whole trail back and checks it. Run it from a cron job or a compliance command. */
+export async function verifyAuditTrail(): Promise<ChainVerification> {
+  const settings = auditSettings();
+  const sink = createSink(settings);
+  try {
+    return verifyChain(await sink.readAll(), settings);
+  } finally {
+    await sink.close();
+  }
+}

package/templates/layers/audit-log/files/src/audit/recorder.ts

@@ -0,0 +1,108 @@
+/**
+ * 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 { randomUUID } from 'node:crypto';
+import { GENESIS_HASH, hashRecord } from './chain.js';
+import { assertValidEvent, AUDIT_SCHEMA_VERSION } from './event.js';
+import { redactMetadata } from './redact.js';
+import { createSink } from './sinks.js';
+import { auditSettings } from './settings.js';
+import type { AuditEvent, AuditRecord } from './event.js';
+import type { AuditSink } from './sinks.js';
+import type { AuditSettings } from './settings.js';
+
+export class AuditRecorder {
+  private readonly settings: AuditSettings;
+  private readonly sink: AuditSink;
+  private previousHash = GENESIS_HASH;
+  private sequence = 0;
+  private initialized = false;
+  /** Appends are chained so two concurrent callers cannot claim the same sequence number. */
+  private queue: Promise<unknown> = Promise.resolve();
+
+  constructor(settings: AuditSettings = auditSettings(), sink?: AuditSink) {
+    this.settings = settings;
+    this.sink = sink ?? createSink(settings);
+  }
+
+  /** Resolves once the record is durable in the sink. Rejects if it is not. */
+  async record(event: AuditEvent): Promise<AuditRecord> {
+    assertValidEvent(event);
+    const next = this.queue.then(() => this.appendLocked(event));
+    // Keep the chain alive after a rejection; the failure still reaches this caller.
+    this.queue = next.catch(() => undefined);
+    return next;
+  }
+
+  private async appendLocked(event: AuditEvent): Promise<AuditRecord> {
+    await this.restore();
+
+    const record: AuditRecord = {
+      schemaVersion: AUDIT_SCHEMA_VERSION,
+      sequence: this.sequence + 1,
+      id: randomUUID(),
+      occurredAt: new Date().toISOString(),
+      service: this.settings.service,
+      environment: this.settings.environment,
+      action: event.action,
+      outcome: event.outcome,
+      actorId: event.actorId,
+      actorType: event.actorType ?? 'user',
+      actorIp: event.actorIp ?? '',
+      resourceType: event.resourceType ?? '',
+      resourceId: event.resourceId ?? '',
+      reason: event.reason ?? '',
+      correlationId: event.correlationId ?? '',
+      metadata: redactMetadata(event.metadata ?? {}, this.settings),
+      previousHash: this.settings.chainEnabled ? this.previousHash : GENESIS_HASH,
+      hash: '',
+    };
+    record.hash = hashRecord(record, this.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 (!this.settings.enabled) return record;
+
+    try {
+      await this.sink.append(record);
+    } catch (error) {
+      // 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 (this.settings.failClosed) throw error;
+      return record;
+    }
+
+    this.sequence = record.sequence;
+    this.previousHash = record.hash;
+    return record;
+  }
+
+  /** Continue an existing trail across restarts instead of forking a second chain. */
+  private async restore(): Promise<void> {
+    if (this.initialized) return;
+    this.initialized = true;
+    const last = await this.sink.last();
+    if (last === undefined) return;
+    this.sequence = last.sequence;
+    this.previousHash = last.hash;
+  }
+
+  async close(): Promise<void> {
+    await this.queue;
+    await this.sink.close();
+  }
+}
+
+let shared: AuditRecorder | undefined;
+
+/** One recorder per process; a second one would issue duplicate sequence numbers. */
+export function auditRecorder(): AuditRecorder {
+  shared ??= new AuditRecorder();
+  return shared;
+}
+
+export async function resetAuditRecorder(): Promise<void> {
+  await shared?.close();
+  shared = undefined;
+}

package/templates/layers/audit-log/files/src/audit/redact.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 type { AuditMetadata, AuditRecord } from './event.js';
+import type { AuditSettings } from './settings.js';
+
+const MAX_DEPTH = 12;
+
+/** Deep-copies while replacing matched keys; the caller's object is never mutated. */
+export function redact(value: unknown, settings: AuditSettings, depth = 0): unknown {
+  if (depth > MAX_DEPTH) return '[truncated]';
+
+  if (Array.isArray(value)) {
+    return value.map((item) => redact(item, settings, depth + 1));
+  }
+  if (value === null || typeof value !== 'object') return value;
+
+  const blocked = new Set(settings.redactFields.map((field) => field.toLowerCase()));
+  const out: Record<string, unknown> = {};
+  for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+    out[key] = blocked.has(key.toLowerCase())
+      ? settings.redactPlaceholder
+      : redact(item, settings, depth + 1);
+  }
+  return out;
+}
+
+export function redactMetadata(metadata: AuditMetadata, settings: AuditSettings): AuditMetadata {
+  return redact(metadata, settings) as AuditMetadata;
+}
+
+/**
+ * Canonical JSON: keys sorted, no whitespace. Two processes must serialize the same
+ * record byte-identically or the chain cannot be verified anywhere but where it was built.
+ */
+export function canonicalize(value: unknown): string {
+  if (value === undefined) return 'null';
+  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null';
+  if (Array.isArray(value)) return `[${value.map(canonicalize).join(',')}]`;
+
+  const entries = Object.entries(value as Record<string, unknown>)
+    .filter(([, item]) => item !== undefined)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([key, item]) => `${JSON.stringify(key)}:${canonicalize(item)}`);
+  return `{${entries.join(',')}}`;
+}
+
+/** The bytes a record's hash commits to: everything except the hash itself. */
+export function canonicalPayload(record: AuditRecord): string {
+  const rest: Record<string, unknown> = { ...record };
+  delete rest.hash;
+  return canonicalize(rest);
+}

package/templates/layers/audit-log/files/src/audit/settings.ts

@@ -0,0 +1,113 @@
+/**
+ * The only place an audit default may appear. Every other audit module reads these
+ * settings — a path, a hash name, or a redacted field written at a call site is a bug.
+ */
+
+export type AuditSinkKind = 'file' | 'stdout' | 'memory';
+
+export interface AuditSettings {
+  enabled: boolean;
+  sink: AuditSinkKind;
+  filePath: string;
+  service: string;
+  environment: string;
+  chainEnabled: boolean;
+  hashAlgorithm: string;
+  redactFields: readonly string[];
+  redactPlaceholder: string;
+  retentionDays: number;
+  maxMemoryEvents: number;
+  failClosed: boolean;
+}
+
+const PREFIX = '{{ auditEnvPrefix }}';
+
+const SINK_KINDS: readonly AuditSinkKind[] = ['file', 'stdout', 'memory'];
+
+/** Typed defaults. Change a value here or in the environment, never at a call site. */
+const defaults: AuditSettings = {
+  enabled: true,
+  sink: '{{ auditSink }}',
+  filePath: '{{ auditFilePath }}',
+  service: '{{ solutionName | kebab }}',
+  environment: 'local',
+  chainEnabled: true,
+  hashAlgorithm: '{{ auditHashAlgorithm }}',
+  redactFields: '{{ auditRedactFields }}'.split(','),
+  redactPlaceholder: '[redacted]',
+  retentionDays: {{ auditRetentionDays }},
+  maxMemoryEvents: {{ auditMaxMemoryEvents }},
+  failClosed: true,
+};
+
+type Env = Record<string, string | undefined>;
+
+function read(env: Env, key: string): string | undefined {
+  const value = env[`${PREFIX}_${key}`];
+  return value === undefined || value.trim() === '' ? undefined : value.trim();
+}
+
+function integer(env: Env, key: string, fallback: number): number {
+  const raw = read(env, key);
+  if (raw === undefined) return fallback;
+  const parsed = Number(raw);
+  // Fail at startup rather than let a bad bound surface as a silent truncation later.
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new Error(`${PREFIX}_${key} must be a non-negative integer, got "${raw}"`);
+  }
+  return parsed;
+}
+
+function boolean(env: Env, key: string, fallback: boolean): boolean {
+  const raw = read(env, key)?.toLowerCase();
+  if (raw === undefined) return fallback;
+  return raw === '1' || raw === 'true' || raw === 'yes' || raw === 'on';
+}
+
+function list(env: Env, key: string, fallback: readonly string[]): readonly string[] {
+  const raw = read(env, key);
+  if (raw === undefined) return fallback;
+  return raw
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function sinkKind(env: Env, key: string, fallback: AuditSinkKind): AuditSinkKind {
+  const raw = read(env, key)?.toLowerCase();
+  if (raw === undefined) return fallback;
+  if (!SINK_KINDS.includes(raw as AuditSinkKind)) {
+    throw new Error(`${PREFIX}_${key} must be one of ${SINK_KINDS.join(', ')}, got "${raw}"`);
+  }
+  return raw as AuditSinkKind;
+}
+
+export function loadAuditSettings(env: Env = process.env): AuditSettings {
+  return {
+    enabled: boolean(env, 'ENABLED', defaults.enabled),
+    sink: sinkKind(env, 'SINK', defaults.sink),
+    filePath: read(env, 'FILE_PATH') ?? defaults.filePath,
+    service: read(env, 'SERVICE') ?? defaults.service,
+    environment: read(env, 'ENVIRONMENT') ?? defaults.environment,
+    chainEnabled: boolean(env, 'CHAIN_ENABLED', defaults.chainEnabled),
+    hashAlgorithm: read(env, 'HASH_ALGORITHM') ?? defaults.hashAlgorithm,
+    redactFields: list(env, 'REDACT_FIELDS', defaults.redactFields),
+    redactPlaceholder: read(env, 'REDACT_PLACEHOLDER') ?? defaults.redactPlaceholder,
+    retentionDays: integer(env, 'RETENTION_DAYS', defaults.retentionDays),
+    maxMemoryEvents: integer(env, 'MAX_MEMORY_EVENTS', defaults.maxMemoryEvents),
+    failClosed: boolean(env, 'FAIL_CLOSED', defaults.failClosed),
+  };
+}
+
+let cached: AuditSettings | undefined;
+
+/** Cached so the environment is read once and every caller shares one instance. */
+export function auditSettings(): AuditSettings {
+  cached ??= loadAuditSettings();
+  return cached;
+}
+
+/** Tests mutate the environment between cases; production never calls this. */
+export function resetAuditSettings(): void {
+  cached = undefined;
+}