refactor: split flat core into capability packages, layer the conversations service, English defaults for every model-facing text

src/beaver_gateway/security/audit.py

@@ -0,0 +1,94 @@
+"""Single entry point for writing :class:`AuditLog` rows.
+
+Every frontend ends up needing the same three-line pattern — open a DB
+session, append a row, swallow failures so the user-visible request
+still succeeds. Phase 4.3 inlined that pattern in the admin frontend
+under a private ``_audit()`` helper; Phase 4.4 lifts it here so the
+Messages and MCP frontends can call the same function and so the
+swallow-and-log policy lives in one place.
+
+The contract:
+
+* ``log(runtime, actor=..., kind=...)`` is fire-and-forget. It awaits
+  the DB write (so callers can ``await`` it before responding and get
+  ordering), but never raises — if the audit insert fails, the function
+  emits an ``exception`` log line and returns.
+* ``actor`` is a free-form string. By convention: ``"token:<name>"``
+  for bearer-authenticated traffic, ``"admin:<user>"`` for admin-UI
+  actions, ``"anon"`` for failed-auth paths we still want to record.
+* ``kind`` is a short tag — see :data:`KNOWN_KINDS` for the set the
+  current frontends emit; new tags don't need a code change here, the
+  column is free-form.
+* ``**detail`` is JSON-serialised by :func:`append_audit`. Keep it
+  small: paths, methods, status codes — not request bodies. Anything
+  passed here lands in ``AuditLog.detail_json`` verbatim.
+
+Why a thin wrapper rather than ``append_audit`` directly: callers want
+"write if you can, otherwise carry on", and pulling the try/except into
+every frontend was already starting to drift (admin had it, bearer
+frontends would have copy-pasted). One module, one policy.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from beaver_gateway.storage import append_audit
+
+if TYPE_CHECKING:
+    from beaver_gateway.frontends.base import GatewayRuntime
+
+
+_log = logging.getLogger("beaver_gateway.audit")
+
+
+# Tags currently emitted by the gateway. The set is informational —
+# ``AuditLog.kind`` is free-form so new code can introduce new tags
+# without touching this list — but listing them here gives the admin UI
+# and any downstream log consumers one canonical reference.
+KNOWN_KINDS: frozenset[str] = frozenset(
+    {
+        "messages",  # POST /v1/messages accepted
+        "mcp_call",  # /mcp/<ns>/... proxied
+        "tool_call",  # a model's tool call seen by the PreToolUse hook
+        "login_ok",
+        "login_failed",
+        "logout",
+        "token_create",
+        "token_revoke",
+    }
+)
+
+
+async def log(
+    runtime: GatewayRuntime,
+    *,
+    actor: str,
+    kind: str,
+    agent_name: str | None = None,
+    **detail: Any,
+) -> None:
+    """Best-effort audit insert. Never raises.
+
+    Opens its own short-lived :class:`AsyncSession` so callers don't
+    have to thread one through. If the DB hiccups (table missing,
+    disk full, connection drop), we log and move on — the audit trail
+    is observability, not a hard precondition for serving the request.
+    """
+    try:
+        async with runtime.db.session() as session:
+            await append_audit(
+                session,
+                actor=actor,
+                kind=kind,
+                agent_name=agent_name,
+                detail=detail or None,
+            )
+    except Exception:  # noqa: BLE001
+        _log.exception(
+            "audit write failed: actor=%s kind=%s agent=%s", actor, kind, agent_name
+        )
+
+
+__all__ = ["KNOWN_KINDS", "log"]