coulomb/audit-core
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Route ingestion through the backend contract; fix error semantics
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / container-smoke (push) Successful in 1s
Details

Browse source 
AUDIT-WP-0004 T01, T02, T07.

T01 - ingestion wrote to SQLite directly and never called the AuditBackend
contract, so a 202 meant a row existed rather than that a backend with a
declared retention policy had accepted the event. Adds IdempotentAuditBackend
to the contract: duplicate detection lives inside the backend so custody and
idempotency state share a transaction and cannot diverge. SQLiteAuditBackend
implements it with WAL, synchronous=FULL and a busy timeout. Ingestion now
refuses any backend declaring durable=False, so the development file backend
cannot silently become the production sink.

The atomicity claim was tested rather than asserted, and the first attempt
failed: with a single shared connection, 16 racing submissions of one event
told two callers they were first. Storage was correct but the response was
not. Fixed with per-thread connections and BEGIN IMMEDIATE around the
insert/read pair, and locked in by a test.

T02 - storage errors previously escaped the handler with start_response never
called, and the auth check sat outside the try block so a non-ASCII
Authorization header crashed the request. Adds a catch-all, maps conflict to
409, backend unavailability to 503 and unexpected faults to 500, and
documents the full response contract with the retry semantics each status
implies, since senders key their behaviour off it.

T07 - ingestion tests 2 -> 23, suite 15 -> 36. accepted_at is now UTC rather
than local time, and naive timestamps are rejected instead of silently
assumed.

Remaining in WP-0004: T03 tenant/source binding, T04 redaction policy,
T05 operator read surface, T06 production serving layer.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
tegwick 2026-08-10 14:30:20 +02:00
parent f45c4f2511
commit eb649dd747
8 changed files with 693 additions and 92 deletions
Download patch file Download diff file Expand all files Collapse all files

10
audit_core/__init__.py
View file

@ -4,21 +4,31 @@ Contract reference: ``docs/audit-backend-contract.md``.
"""
from audit_core.interface import (
AcceptResult,
AuditBackend,
AuditEvent,
BackendUnavailableError,
EventConflictError,
EventValidationError,
IdempotentAuditBackend,
RetentionPolicy,
SCHEMA_VERSION_V1ALPHA1,
validate_event,
)
from audit_core.mock_file_backend import MockFileAuditBackend
from audit_core.sqlite_backend import SQLiteAuditBackend
__all__ = [
"AcceptResult",
"AuditBackend",
"AuditEvent",
"BackendUnavailableError",
"EventConflictError",
"EventValidationError",
"IdempotentAuditBackend",
"MockFileAuditBackend",
"RetentionPolicy",
"SCHEMA_VERSION_V1ALPHA1",
"SQLiteAuditBackend",
"validate_event",
]

251
audit_core/ingestion.py
View file

@ -1,126 +1,247 @@
"""Authenticated, idempotent HTTP ingestion for user-engine outbox events."""
"""Authenticated, idempotent HTTP ingestion for user-engine outbox events.
Response contract (AUDIT-WP-0004-T02). Senders key their retry behaviour off
these, so they are part of the interface, not an implementation detail:
=== ========== =========================================================
202 accepted Event is durably in custody. Do not retry.
200 duplicate Exact resubmission of an event already in custody. Do not
retry; delivery already succeeded.
400 rejected Malformed or disallowed. Retrying will not help — dead
letter it.
401 unauthorized Credential missing or invalid. Do not retry without a
new credential.
409 conflict The event id is held with a different payload. Retrying
will not help; this indicates a sender bug or id reuse.
503 unavailable Not accepted, but retryable. Retry with backoff.
500 error Unexpected fault. Not accepted. Retryable with backoff.
=== ========== =========================================================
"""
from __future__ import annotations
import hashlib
import hmac
import json
import logging
import os
import sqlite3
from datetime import datetime
import sys
from datetime import datetime, timezone
from http import HTTPStatus
from typing import Any
from wsgiref.simple_server import make_server
from audit_core.interface import AuditEvent
from audit_core.interface import (
AuditEvent,
BackendUnavailableError,
EventConflictError,
EventValidationError,
IdempotentAuditBackend,
)
from audit_core.sqlite_backend import SQLiteAuditBackend
MAX_BODY_BYTES = 256 * 1024
_SECRET_FRAGMENTS = ("password", "secret", "token", "credential", "private_key")
class SQLiteEventStore:
def __init__(self, path: str) -> None:
self.db = sqlite3.connect(path, check_same_thread=False)
self.db.execute("""
CREATE TABLE IF NOT EXISTS events (
event_id TEXT PRIMARY KEY, payload_hash TEXT NOT NULL,
accepted_at TEXT NOT NULL, record TEXT NOT NULL
)
""")
self.db.commit()
def accept(self, event: AuditEvent, payload_hash: str) -> tuple[bool, str]:
existing = self.db.execute(
"SELECT payload_hash FROM events WHERE event_id = ?", (event.event_id,)
).fetchone()
if existing:
if existing[0] != payload_hash:
raise ValueError("event_id_conflict")
return True, f"audit:{event.event_id}"
with self.db:
self.db.execute(
"INSERT INTO events VALUES (?, ?, ?, ?)",
(event.event_id, payload_hash, datetime.now().astimezone().isoformat(),
json.dumps(event.as_record(), sort_keys=True)),
)
return False, f"audit:{event.event_id}"
log = logging.getLogger("audit_core.ingestion")
class IngestionApplication:
def __init__(self, store: SQLiteEventStore, bearer_token: str) -> None:
"""WSGI application accepting user-engine outbox events.
Writes through the audit backend contract rather than to storage directly,
so a 202 means a backend with a declared retention policy acknowledged the
event.
"""
def __init__(self, backend: IdempotentAuditBackend, bearer_token: str) -> None:
if not bearer_token:
raise ValueError("bearer token is required")
self.store = store
policy = backend.retention_policy
if not policy.durable:
# The mock file backend declares durable=False. Refusing it here is
# what stops a development sink from silently becoming the
# production one (AUDIT-WP-0004-T01).
raise ValueError(
f"backend custody_class={policy.custody_class!r} is not durable; "
"refusing to accept audit events against it"
)
self.backend = backend
self.token = bearer_token
def __call__(self, environ, start_response):
try:
return self._handle(environ, start_response)
except Exception:
# Nothing may escape: an unhandled exception here means
# start_response is never called and the sender sees a dropped
# connection it cannot classify.
log.exception("unhandled error in ingestion request")
return self._json(
start_response, HTTPStatus.INTERNAL_SERVER_ERROR, {"error": "internal_error"}
)
def _handle(self, environ, start_response):
path = environ.get("PATH_INFO", "")
if path in ("/healthz", "/readyz"):
if path == "/healthz":
return self._json(start_response, HTTPStatus.OK, {"status": "ok"})
if path == "/readyz":
return self._readiness(start_response)
if path != "/v1/events" or environ.get("REQUEST_METHOD") != "POST":
return self._json(start_response, HTTPStatus.NOT_FOUND, {"error": "not_found"})
supplied = str(environ.get("HTTP_AUTHORIZATION", ""))
if not hmac.compare_digest(supplied, f"Bearer {self.token}"):
return self._json(start_response, HTTPStatus.UNAUTHORIZED, {"error": "unauthorized"})
try:
length = int(environ.get("CONTENT_LENGTH") or 0)
if length <= 0 or length > MAX_BODY_BYTES:
raise ValueError("invalid_size")
raw = environ["wsgi.input"].read(length)
payload = json.loads(raw)
event = normalize(payload, environ.get("HTTP_IDEMPOTENCY_KEY"))
duplicate, reference = self.store.accept(
event, hashlib.sha256(raw).hexdigest()
if not self._authorized(environ):
return self._json(
start_response, HTTPStatus.UNAUTHORIZED, {"error": "unauthorized"}
)
try:
raw = self._read_body(environ)
event = normalize(json.loads(raw), environ.get("HTTP_IDEMPOTENCY_KEY"))
except (ValueError, TypeError, KeyError, json.JSONDecodeError) as exc:
return self._json(start_response, HTTPStatus.BAD_REQUEST, {"error": str(exc)})
return self._json(start_response, HTTPStatus.OK if duplicate else HTTPStatus.ACCEPTED,
{"status": "duplicate" if duplicate else "accepted",
"reference": reference})
try:
result = self.backend.accept(event, hashlib.sha256(raw).hexdigest())
except EventConflictError as exc:
log.warning("event conflict: %s", exc)
return self._json(start_response, HTTPStatus.CONFLICT, {"error": "event_id_conflict"})
except EventValidationError as exc:
return self._json(start_response, HTTPStatus.BAD_REQUEST, {"error": str(exc)})
except BackendUnavailableError as exc:
log.error("backend unavailable: %s", exc)
return self._json(
start_response, HTTPStatus.SERVICE_UNAVAILABLE, {"error": "backend_unavailable"}
)
return self._json(
start_response,
HTTPStatus.OK if result.duplicate else HTTPStatus.ACCEPTED,
{
"status": "duplicate" if result.duplicate else "accepted",
"reference": result.reference,
},
)
def _authorized(self, environ) -> bool:
supplied = str(environ.get("HTTP_AUTHORIZATION", ""))
expected = f"Bearer {self.token}"
try:
return hmac.compare_digest(supplied, expected)
except TypeError:
# compare_digest rejects non-ASCII str. A header containing one is
# simply not a valid credential.
return False
def _read_body(self, environ) -> bytes:
try:
length = int(environ.get("CONTENT_LENGTH") or 0)
except (TypeError, ValueError):
raise ValueError("invalid_content_length") from None
if length <= 0:
raise ValueError("empty_body")
if length > MAX_BODY_BYTES:
raise ValueError("payload_too_large")
raw = environ["wsgi.input"].read(length)
if len(raw) != length:
raise ValueError("truncated_body")
return raw
def _readiness(self, start_response):
try:
health = getattr(self.backend, "health", None)
if callable(health):
health()
except BackendUnavailableError as exc:
log.error("readiness failed: %s", exc)
return self._json(
start_response, HTTPStatus.SERVICE_UNAVAILABLE, {"status": "unavailable"}
)
policy = self.backend.retention_policy
return self._json(
start_response,
HTTPStatus.OK,
{"status": "ok", "custody_class": policy.custody_class, "durable": policy.durable},
)
@staticmethod
def _json(start_response, status: HTTPStatus, payload: dict[str, Any]):
body = json.dumps(payload).encode()
start_response(f"{status.value} {status.phrase}", [
("Content-Type", "application/json"), ("Content-Length", str(len(body)))
])
start_response(
f"{status.value} {status.phrase}",
[("Content-Type", "application/json"), ("Content-Length", str(len(body)))],
)
return [body]
def normalize(payload: dict[str, Any], idempotency_key: str | None) -> AuditEvent:
required = ("id", "type", "source", "subject", "tenant", "correlation_id", "occurred_at", "data")
required = (
"id", "type", "source", "subject", "tenant", "correlation_id", "occurred_at", "data",
)
if not isinstance(payload, dict) or any(not payload.get(key) for key in required):
raise ValueError("invalid_event")
if idempotency_key != payload["id"]:
raise ValueError("idempotency_key_mismatch")
if payload["source"] != "user-engine":
raise ValueError("source_not_allowed")
datetime.fromisoformat(str(payload["occurred_at"]).replace("Z", "+00:00"))
observed_at = _normalize_timestamp(payload["occurred_at"])
if _contains_secret(payload["data"]):
raise ValueError("secret_shaped_field")
return AuditEvent(
event_id=str(payload["id"]), observed_at=str(payload["occurred_at"]),
tenant=str(payload["tenant"]), scope="tenant", source="user-engine",
action=str(payload["type"]), resource=str(payload["subject"]),
outcome="recorded", actor=None,
event_id=str(payload["id"]),
observed_at=observed_at,
tenant=str(payload["tenant"]),
scope="tenant",
source="user-engine",
action=str(payload["type"]),
resource=str(payload["subject"]),
outcome="recorded",
actor=None,
details={"correlation_id": str(payload["correlation_id"]), "data": payload["data"]},
)
def _normalize_timestamp(value: Any) -> str:
"""Parse an event timestamp, requiring an explicit offset.
A naive timestamp is ambiguous by up to a day, which is not good enough for
an audit trail — the sender must say which offset it meant.
"""
try:
parsed = datetime.fromisoformat(str(value).replace("Z", "+00:00"))
except (TypeError, ValueError):
raise ValueError("invalid_timestamp") from None
if parsed.tzinfo is None:
raise ValueError("timestamp_missing_timezone")
return parsed.astimezone(timezone.utc).isoformat()
def _contains_secret(value: Any) -> bool:
if isinstance(value, dict):
return any(any(fragment in str(key).lower() for fragment in _SECRET_FRAGMENTS)
or _contains_secret(item) for key, item in value.items())
return any(
any(fragment in str(key).lower() for fragment in _SECRET_FRAGMENTS)
or _contains_secret(item)
for key, item in value.items()
)
if isinstance(value, list):
return any(_contains_secret(item) for item in value)
return False
def main() -> None:
app = IngestionApplication(
SQLiteEventStore(os.environ.get("AUDIT_CORE_DATABASE_PATH", "/data/audit-core.db")),
os.environ["AUDIT_CORE_INGEST_TOKEN"].strip(),
logging.basicConfig(
level=os.environ.get("AUDIT_CORE_LOG_LEVEL", "INFO"),
format='{"ts":"%(asctime)s","level":"%(levelname)s","logger":"%(name)s","msg":"%(message)s"}',
stream=sys.stdout,
)
with make_server(os.environ.get("AUDIT_CORE_HOST", "0.0.0.0"),
int(os.environ.get("AUDIT_CORE_HTTP_PORT", "8080")), app) as server:
backend = SQLiteAuditBackend(
os.environ.get("AUDIT_CORE_DATABASE_PATH", "/data/audit-core.db")
)
app = IngestionApplication(backend, os.environ["AUDIT_CORE_INGEST_TOKEN"].strip())
host = os.environ.get("AUDIT_CORE_HOST", "0.0.0.0")
port = int(os.environ.get("AUDIT_CORE_HTTP_PORT", "8080"))
# NOTE: wsgiref is single-threaded and has no request timeout. Replacing it
# with a production WSGI server is AUDIT-WP-0004-T06; do not deploy on this.
log.warning("serving on wsgiref development server — not for production (AUDIT-WP-0004-T06)")
with make_server(host, port, app) as server:
server.serve_forever()

53
audit_core/interface.py
View file

@ -86,6 +86,31 @@ class EventValidationError(ValueError):
"""Raised when an event record fails contract validation."""
class EventConflictError(Exception):
"""Raised when an event id is resubmitted with a different payload.
Distinct from :class:`EventValidationError`: the event is well-formed, but
it contradicts a record already in custody. Callers map this to a conflict
response rather than a rejection, because retrying it will never succeed.
"""
class BackendUnavailableError(Exception):
"""Raised when a backend cannot currently accept writes.
Signals a retryable condition — the event is not in custody and the caller
should try again. Never raised for events the backend has durably accepted.
"""
@dataclass(frozen=True)
class AcceptResult:
"""Outcome of an idempotent accept."""
duplicate: bool
reference: str
def validate_event(event: AuditEvent) -> None:
"""Validate an event against the v1alpha1 contract.
@ -127,4 +152,30 @@ class AuditBackend(Protocol):
"""Describe retention and custody guarantees for readiness checks."""
def emit(self, event: AuditEvent) -> str:
"""Persist an event and return a backend-specific reference."""
"""Persist an event and return a backend-specific reference."""
@runtime_checkable
class IdempotentAuditBackend(AuditBackend, Protocol):
"""An :class:`AuditBackend` that can absorb duplicate submissions.
Ingestion requires this rather than the plain backend protocol. The reason
is atomicity: if duplicate detection lived in the ingestion layer and
custody in the backend, the two could diverge — an event recorded as seen
but never durably stored, which is precisely the loss this service exists
to prevent. Keeping both inside one backend call lets an implementation put
them in a single transaction.
"""
def accept(self, event: AuditEvent, payload_hash: str) -> AcceptResult:
"""Durably record an event, tolerating exact resubmission.
Returns an :class:`AcceptResult` whose ``duplicate`` flag distinguishes
a first acceptance from a replay of an identical event. Both mean the
event is in custody.
Raises :class:`EventConflictError` if ``event.event_id`` is already held
with a different ``payload_hash``, and :class:`BackendUnavailableError`
if the write could not be attempted. Returning normally must mean the
event is durable.
"""

177
audit_core/sqlite_backend.py Normal file
View file

@ -0,0 +1,177 @@
"""Durable SQLite audit backend.
Implements the idempotent backend contract for single-node deployments and for
development. Production custody moves to PostgreSQL under AUDIT-WP-0005; this
backend stays the development and test implementation and defines the
behaviour the Postgres backend must match.
"""
from __future__ import annotations
import json
import sqlite3
import threading
from datetime import datetime, timezone
from audit_core.interface import (
AcceptResult,
AuditEvent,
BackendUnavailableError,
EventConflictError,
EventValidationError,
RetentionPolicy,
validate_event,
)
_SCHEMA = """
CREATE TABLE IF NOT EXISTS events (
event_id TEXT PRIMARY KEY,
payload_hash TEXT NOT NULL,
accepted_at TEXT NOT NULL,
correlation_id TEXT,
tenant TEXT NOT NULL,
record TEXT NOT NULL
);
CREATE INDEX IF NOT EXISTS events_correlation_idx ON events (correlation_id);
CREATE INDEX IF NOT EXISTS events_tenant_idx ON events (tenant);
"""
class SQLiteAuditBackend:
"""Store audit events in SQLite with idempotent accept semantics.
Configured for durability rather than speed: WAL journalling, ``synchronous
= FULL`` so an acknowledged write has reached disk, and a busy timeout so
concurrent writers wait instead of raising immediately.
"""
def __init__(self, path: str, retention_days: int | None = None, busy_timeout_ms: int = 5000) -> None:
self.path = path
self.retention_days = retention_days
self.busy_timeout_ms = int(busy_timeout_ms)
# One connection per thread. A shared connection lets concurrent
# statements interleave, which was observed to let two callers both
# believe they were the first to accept the same event.
self._local = threading.local()
with self._connect_raw() as setup:
setup.executescript(_SCHEMA)
def _connect_raw(self) -> sqlite3.Connection:
try:
db = sqlite3.connect(self.path, isolation_level=None)
db.execute("PRAGMA journal_mode = WAL")
db.execute("PRAGMA synchronous = FULL")
db.execute(f"PRAGMA busy_timeout = {self.busy_timeout_ms}")
return db
except sqlite3.Error as exc:
raise BackendUnavailableError(f"cannot open audit store: {exc}") from exc
@property
def db(self) -> sqlite3.Connection:
conn = getattr(self._local, "conn", None)
if conn is None:
conn = self._local.conn = self._connect_raw()
return conn
@property
def retention_policy(self) -> RetentionPolicy:
return RetentionPolicy(
custody_class="development",
retention_days=self.retention_days,
immutable=False,
tamper_evidence=False,
durable=True,
)
def emit(self, event: AuditEvent) -> str:
"""Persist an event, generating no idempotency guarantee."""
return self.accept(event, payload_hash=_record_hash(event)).reference
def accept(self, event: AuditEvent, payload_hash: str) -> AcceptResult:
try:
validate_event(event)
except EventValidationError:
raise
reference = f"audit:{event.event_id}"
details = event.details if isinstance(event.details, dict) else {}
db = self.db
try:
# BEGIN IMMEDIATE takes the write lock up front, so the insert and
# the follow-up read are one atomic pair. Without it, two callers
# racing on the same event id can both be told they were first.
db.execute("BEGIN IMMEDIATE")
except sqlite3.Error as exc:
raise BackendUnavailableError(str(exc)) from exc
try:
inserted = db.execute(
"""
INSERT INTO events
(event_id, payload_hash, accepted_at, correlation_id, tenant, record)
VALUES (?, ?, ?, ?, ?, ?)
ON CONFLICT(event_id) DO NOTHING
RETURNING event_id
""",
(
event.event_id,
payload_hash,
datetime.now(timezone.utc).replace(microsecond=0).isoformat(),
str(details.get("correlation_id") or "") or None,
event.tenant,
json.dumps(event.as_record(), sort_keys=True),
),
).fetchone()
existing = None
if inserted is None:
existing = db.execute(
"SELECT payload_hash FROM events WHERE event_id = ?", (event.event_id,)
).fetchone()
db.execute("COMMIT")
except sqlite3.Error as exc:
_rollback(db)
raise BackendUnavailableError(str(exc)) from exc
except BaseException:
_rollback(db)
raise
if inserted is not None:
return AcceptResult(duplicate=False, reference=reference)
if existing is None:
# The row vanished between the insert and the read inside one
# transaction, which should be impossible. Retryable rather than
# guessed at.
raise BackendUnavailableError("event disappeared during accept")
if existing[0] != payload_hash:
raise EventConflictError(
f"event_id {event.event_id} already held with a different payload"
)
return AcceptResult(duplicate=True, reference=reference)
def health(self) -> None:
"""Raise :class:`BackendUnavailableError` if the store is unusable."""
try:
self.db.execute("SELECT 1 FROM events LIMIT 1").fetchone()
except sqlite3.Error as exc:
raise BackendUnavailableError(str(exc)) from exc
def close(self) -> None:
"""Close this thread's connection, if it has one."""
conn = getattr(self._local, "conn", None)
if conn is not None:
conn.close()
self._local.conn = None
def _rollback(db: sqlite3.Connection) -> None:
try:
db.execute("ROLLBACK")
except sqlite3.Error:
pass
def _record_hash(event: AuditEvent) -> str:
import hashlib
return hashlib.sha256(
json.dumps(event.as_record(), sort_keys=True).encode("utf-8")
).hexdigest()