auth: add audit log helper

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))

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"}