From 46e20de61ba809ea79cad054be2188b66c180457 Mon Sep 17 00:00:00 2001
From: Ivo Oskamp <ivooskamp@oskamp.info>
Date: Thu, 28 May 2026 15:52:06 +0200
Subject: [PATCH] auth: add audit log helper

---
 .../clearview/src/clearview_app/auth/audit.py | 20 +++++++++++++++++++
 containers/clearview/tests/test_models.py     | 10 ++++++++++
 2 files changed, 30 insertions(+)
 create mode 100644 containers/clearview/src/clearview_app/auth/audit.py

diff --git a/containers/clearview/src/clearview_app/auth/audit.py b/containers/clearview/src/clearview_app/auth/audit.py
new file mode 100644
index 0000000..4c283ae
--- /dev/null
+++ b/containers/clearview/src/clearview_app/auth/audit.py
@@ -0,0 +1,20 @@
+"""Single-entry helper for writing rows to the auth audit log."""
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy.orm import Session
+
+from .models import AuthAudit
+
+
+def record_event(
+    db: Session,
+    *,
+    event: str,
+    user_id: int | None = None,
+    ip: str | None = None,
+    detail: dict[str, Any] | None = None,
+) -> None:
+    """Add an AuthAudit row to the session. Caller commits."""
+    db.add(AuthAudit(event=event, user_id=user_id, ip=ip, detail=detail))
diff --git a/containers/clearview/tests/test_models.py b/containers/clearview/tests/test_models.py
index ef7e0f9..487974b 100644
--- a/containers/clearview/tests/test_models.py
+++ b/containers/clearview/tests/test_models.py
@@ -32,3 +32,13 @@ def test_audit_row(db_session):
     db_session.add(a); db_session.commit()
     assert a.id is not None
     assert a.detail == {"k": "v"}
+
+
+def test_record_event_persists(db_session):
+    from clearview_app.auth.audit import record_event
+    record_event(db_session, event="login_ok", user_id=None, ip="1.1.1.1", detail={"u": "x"})
+    db_session.commit()
+    rows = db_session.query(AuthAudit).all()
+    assert len(rows) == 1
+    assert rows[0].event == "login_ok"
+    assert rows[0].detail == {"u": "x"}