mobius-auditlog-py 1.0.0__py3-none-any.whl

mobius_auditlog/__init__.py

@@ -0,0 +1,56 @@
+"""Mobius Audit Log for Python.
+
+Build, sign, and publish CloudEvents-style audit events from Mobius FastAPI
+services. Provides the event model, a fluent builder, integrity hashing/signing,
+a Kafka publisher, and an optional per-request capture middleware.
+"""
+from __future__ import annotations
+
+from .bootstrap import setup_auditlog
+from .builder import AuditLogBuilder
+from .middleware import AuditLogMiddleware
+from .models import (
+    Action,
+    AuditLogEvent,
+    EventData,
+    EventMetadata,
+    Kubernetes,
+    Network,
+    ObjectRef,
+    Security,
+    Subject,
+)
+from .publisher import (
+    AuditLogPublisher,
+    LogEventSender,
+    PyKafkaProducerClientSender,
+    get_publisher,
+    set_publisher,
+)
+from .security import compute_hash, seal, sign, verify
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "setup_auditlog",
+    "AuditLogBuilder",
+    "AuditLogMiddleware",
+    "AuditLogEvent",
+    "Subject",
+    "Kubernetes",
+    "ObjectRef",
+    "Action",
+    "Network",
+    "EventData",
+    "EventMetadata",
+    "Security",
+    "AuditLogPublisher",
+    "LogEventSender",
+    "PyKafkaProducerClientSender",
+    "set_publisher",
+    "get_publisher",
+    "seal",
+    "verify",
+    "compute_hash",
+    "sign",
+]

mobius_auditlog/bootstrap.py

@@ -0,0 +1,89 @@
+"""One-call setup for FastAPI services.
+
+Builds the publisher (from a py-kafka-producer-client config/instance or any
+sender) and registers the audit middleware.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any, Iterable, Optional
+
+from .middleware import DEFAULT_SKIP_PATHS, AuditLogMiddleware
+from .publisher import (
+    DEFAULT_TOPIC,
+    AuditLogPublisher,
+    LogEventSender,
+    PyKafkaProducerClientSender,
+    set_publisher,
+)
+
+log = logging.getLogger(__name__)
+
+
+def setup_auditlog(
+    app: Optional[Any] = None,
+    *,
+    topic: str = DEFAULT_TOPIC,
+    signing_key: Optional[str] = None,
+    kafka_config: Optional[Any] = None,
+    kafka_producer: Optional[Any] = None,
+    kafka_sender: Optional[LogEventSender] = None,
+    skip_paths: Iterable[str] = DEFAULT_SKIP_PATHS,
+    capture_payloads: bool = False,
+    compliance_category: Optional[str] = None,
+) -> Optional[AuditLogPublisher]:
+    """Configure audit logging and (optionally) register the middleware.
+
+    Publisher resolution: ``kafka_sender`` -> ``kafka_producer`` -> ``kafka_config``
+    -> the configured ``py-kafka-producer-client`` singleton. If none resolve,
+    the middleware simply emits nothing.
+
+    Returns the registered :class:`AuditLogPublisher`, if any.
+    """
+    sender = _resolve_sender(kafka_sender, kafka_producer, kafka_config)
+
+    publisher: Optional[AuditLogPublisher] = None
+    if sender is not None:
+        publisher = AuditLogPublisher(sender, topic=topic, signing_key=signing_key)
+        set_publisher(publisher)
+    else:
+        log.warning("mobius-auditlog: no Kafka producer resolved; audit events will not publish.")
+
+    if app is not None:
+        app.add_middleware(
+            AuditLogMiddleware,
+            publisher=publisher,
+            skip_paths=skip_paths,
+            capture_payloads=capture_payloads,
+            compliance_category=compliance_category,
+        )
+
+    return publisher
+
+
+def _resolve_sender(
+    kafka_sender: Optional[LogEventSender],
+    kafka_producer: Optional[Any],
+    kafka_config: Optional[Any],
+) -> Optional[LogEventSender]:
+    if kafka_sender is not None:
+        return kafka_sender
+    if kafka_producer is not None:
+        return PyKafkaProducerClientSender(kafka_producer)
+
+    try:
+        from kafka_producer_client.action_logger import (
+            configure_kafka_producer,
+            get_kafka_producer,
+        )
+    except ImportError:
+        log.warning("mobius-auditlog: py-kafka-producer-client not installed.")
+        return None
+
+    try:
+        if kafka_config is not None:
+            configure_kafka_producer(kafka_config)
+        return PyKafkaProducerClientSender(get_kafka_producer())
+    except Exception:  # noqa: BLE001 - publisher is optional, never crash setup
+        log.warning("mobius-auditlog: could not initialize py-kafka-producer-client.", exc_info=True)
+        return None

mobius_auditlog/builder.py

@@ -0,0 +1,90 @@
+"""Fluent builder for :class:`AuditLogEvent`.
+
+Fills the envelope (id/specversion/timestamp + identity from context) and lets
+you set the audit-specific sections, then ``build()`` returns the event.
+"""
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Mapping, Optional
+
+from . import context as ctx
+from .models import (
+    Action,
+    AuditLogEvent,
+    DEFAULT_SPECVERSION,
+    EventData,
+    EventMetadata,
+    Network,
+    ObjectRef,
+    Subject,
+)
+
+
+class AuditLogBuilder:
+    def __init__(self, *, specversion: str = DEFAULT_SPECVERSION) -> None:
+        self._event = AuditLogEvent(
+            id=str(uuid.uuid4()),
+            specversion=specversion,
+            timestamp=datetime.now(timezone.utc).isoformat(),
+        )
+
+    def from_context(self, headers: Optional[Mapping[str, str]] = None) -> "AuditLogBuilder":
+        identity = ctx.gather_identity(headers)
+        self._event.tenantid = identity.get("tenantid")
+        self._event.traceid = identity.get("traceid")
+        self._event.transactionid = identity.get("transactionid")
+        self._event.subject = ctx.subject_from_identity(identity)
+        self._event.kubernetes = ctx.kubernetes_from_env()
+        return self
+
+    def envelope(
+        self,
+        *,
+        tenantid: Optional[str] = None,
+        traceid: Optional[str] = None,
+        transactionid: Optional[str] = None,
+    ) -> "AuditLogBuilder":
+        if tenantid:
+            self._event.tenantid = tenantid
+        if traceid:
+            self._event.traceid = traceid
+        if transactionid:
+            self._event.transactionid = transactionid
+        return self
+
+    def subject(self, userid: str = None, type: str = None, groups: List[str] = None):
+        self._event.subject = Subject(userid=userid, type=type, groups=groups or [])
+        return self
+
+    def object_ref(self, resource=None, resourceid=None, apiversion=None) -> "AuditLogBuilder":
+        self._event.objectref = ObjectRef(
+            resource=resource, resourceid=resourceid, apiversion=apiversion
+        )
+        return self
+
+    def action(self, name=None, method=None, severity=None, status=None) -> "AuditLogBuilder":
+        self._event.action = Action(name=name, method=method, severity=severity, status=status)
+        return self
+
+    def network(self, sourceip=None, useragent=None) -> "AuditLogBuilder":
+        self._event.network = Network(sourceip=sourceip, useragent=useragent)
+        return self
+
+    def event_data(
+        self,
+        requestpayload: Optional[Dict[str, Any]] = None,
+        responsepayload: Optional[Dict[str, Any]] = None,
+        issensitive: bool = False,
+        compliancecategory: Optional[str] = None,
+    ) -> "AuditLogBuilder":
+        self._event.eventdata = EventData(
+            requestpayload=requestpayload or {},
+            responsepayload=responsepayload or {},
+            metadata=EventMetadata(issensitive=issensitive, compliancecategory=compliancecategory),
+        )
+        return self
+
+    def build(self) -> AuditLogEvent:
+        return self._event

mobius_auditlog/context.py

@@ -0,0 +1,51 @@
+"""Gather envelope/subject context and Kubernetes metadata.
+
+Identity (tenant/trace/transaction/user) is read from the mobius-tracer-py
+request context when that package is installed, otherwise from request headers.
+Kubernetes details come from the standard downward-API environment variables.
+"""
+from __future__ import annotations
+
+import os
+from typing import Dict, Mapping, Optional
+
+from .models import Kubernetes, Subject
+
+
+def gather_identity(headers: Optional[Mapping[str, str]] = None) -> Dict[str, Optional[str]]:
+    """Return envelope identity fields from the tracer context or headers."""
+    try:
+        from mobius_tracer import current
+
+        ctx = current()
+        return {
+            "tenantid": ctx.tenant_id,
+            "traceid": ctx.trace_id,
+            "transactionid": ctx.req_transaction_id,
+            "userid": ctx.action_log_user_id,
+            "type": ctx.requester_type,
+        }
+    except Exception:  # noqa: BLE001 - tracer not installed / no active context
+        pass
+
+    headers = headers or {}
+    return {
+        "tenantid": headers.get("tenantId"),
+        "traceid": headers.get("x-b3-traceid"),
+        "transactionid": headers.get("X-Transaction-Id"),
+        "userid": headers.get("actionLogUserId"),
+        "type": headers.get("RequesterType"),
+    }
+
+
+def subject_from_identity(identity: Mapping[str, Optional[str]]) -> Subject:
+    return Subject(userid=identity.get("userid"), type=identity.get("type"))
+
+
+def kubernetes_from_env() -> Kubernetes:
+    return Kubernetes(
+        namespacename=os.getenv("POD_NAMESPACE") or os.getenv("NAMESPACE"),
+        podname=os.getenv("POD_NAME") or os.getenv("HOSTNAME"),
+        containername=os.getenv("CONTAINER_NAME"),
+        nodename=os.getenv("NODE_NAME"),
+    )

mobius_auditlog/middleware.py

@@ -0,0 +1,167 @@
+"""Optional FastAPI / Starlette ASGI middleware that emits an audit event per
+request.
+
+It fills `action` (route + method + status + severity), `network` (client IP +
+user-agent), `objectref` (from the path), and the envelope/subject from the
+request context, then publishes via the configured publisher.
+
+Request/response payload capture is OFF by default (privacy + overhead); enable
+`capture_payloads=True` to buffer bodies (JSON-parsed, size-capped).
+"""
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, Dict, Iterable, Optional
+
+from starlette.datastructures import Headers
+
+from .builder import AuditLogBuilder
+from .models import DEFAULT_SPECVERSION
+from .publisher import AuditLogPublisher, get_publisher
+
+log = logging.getLogger(__name__)
+
+DEFAULT_SKIP_PATHS = ("actuator", "health", "metrics", "error", "prometheus",
+                      "swagger", "api-docs", "favicon")
+
+
+class AuditLogMiddleware:
+    def __init__(
+        self,
+        app,
+        publisher: Optional[AuditLogPublisher] = None,
+        *,
+        specversion: str = DEFAULT_SPECVERSION,
+        skip_paths: Iterable[str] = DEFAULT_SKIP_PATHS,
+        capture_payloads: bool = False,
+        max_payload_bytes: int = 65536,
+        compliance_category: Optional[str] = None,
+    ) -> None:
+        self.app = app
+        self.publisher = publisher
+        self.specversion = specversion
+        self.skip_paths = tuple(skip_paths)
+        self.capture_payloads = capture_payloads
+        self.max_payload_bytes = max_payload_bytes
+        self.compliance_category = compliance_category
+
+    async def __call__(self, scope, receive, send):
+        if scope.get("type") != "http" or self._should_skip(scope.get("path", "")):
+            await self.app(scope, receive, send)
+            return
+
+        request_body = bytearray()
+        receive = await self._buffer_request(receive, request_body) if self.capture_payloads else receive
+
+        status = {"code": 0}
+        response_body = bytearray()
+
+        async def send_wrapper(message):
+            if message["type"] == "http.response.start":
+                status["code"] = message["status"]
+            elif message["type"] == "http.response.body" and self.capture_payloads:
+                self._append_capped(response_body, message.get("body", b""))
+            await send(message)
+
+        try:
+            await self.app(scope, receive, send_wrapper)
+        finally:
+            try:
+                self._emit(scope, status["code"], bytes(request_body), bytes(response_body))
+            except Exception:  # noqa: BLE001 - auditing must never break the request
+                log.warning("Failed to emit audit event", exc_info=True)
+
+    # --- emit ---
+
+    def _emit(self, scope, status_code: int, req_body: bytes, resp_body: bytes) -> None:
+        publisher = self.publisher or get_publisher()
+        if publisher is None:
+            return
+
+        headers = Headers(scope=scope)
+        path = scope.get("path", "")
+        method = scope.get("method", "")
+        client = scope.get("client")
+        source_ip = client[0] if client else None
+
+        builder = (
+            AuditLogBuilder(specversion=self.specversion)
+            .from_context(headers)
+            .action(
+                name=path,
+                method=method,
+                severity=_severity(status_code),
+                status="SUCCESS" if status_code < 400 else "FAILURE",
+            )
+            .network(sourceip=source_ip, useragent=headers.get("user-agent"))
+            .object_ref(resource=_resource(path))
+        )
+
+        if self.capture_payloads:
+            builder.event_data(
+                requestpayload=_as_object(req_body, self.max_payload_bytes),
+                responsepayload=_as_object(resp_body, self.max_payload_bytes),
+                compliancecategory=self.compliance_category,
+            )
+
+        publisher.publish(builder.build())
+
+    # --- body buffering ---
+
+    async def _buffer_request(self, receive, sink: bytearray):
+        messages = []
+        while True:
+            message = await receive()
+            messages.append(message)
+            if message["type"] != "http.request":
+                break
+            self._append_capped(sink, message.get("body", b""))
+            if not message.get("more_body", False):
+                break
+
+        index = 0
+
+        async def replay():
+            nonlocal index
+            if index < len(messages):
+                message = messages[index]
+                index += 1
+                return message
+            return await receive()
+
+        return replay
+
+    def _append_capped(self, sink: bytearray, body: bytes) -> None:
+        room = self.max_payload_bytes - len(sink)
+        if room > 0 and body:
+            sink.extend(body[:room])
+
+    def _should_skip(self, path: str) -> bool:
+        return any(skip in path for skip in self.skip_paths)
+
+
+def _severity(status_code: int) -> str:
+    if status_code >= 500:
+        return "ERROR"
+    if status_code >= 400:
+        return "WARNING"
+    return "INFO"
+
+
+def _resource(path: str) -> Optional[str]:
+    segments = [s for s in path.split("/") if s]
+    return segments[0] if segments else None
+
+
+def _as_object(body: bytes, cap: int) -> Dict[str, Any]:
+    if not body:
+        return {}
+    text = body[:cap].decode("utf-8", errors="replace")
+    try:
+        parsed = json.loads(text)
+    except ValueError:
+        return {"_raw": text}
+    if isinstance(parsed, dict):
+        return parsed
+    return {"_value": parsed}

mobius_auditlog/models.py

@@ -0,0 +1,119 @@
+"""Audit log event models.
+
+A CloudEvents-style audit event with a flat envelope plus nested sections.
+Serialization rules match the platform schema:
+  - empty values (None, "", [], {}) are omitted;
+  - keys are emitted in alphabetical order;
+  - boolean ``false`` / numeric ``0`` are kept (not treated as empty).
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+DEFAULT_SPECVERSION = "1.0"
+
+
+class Subject(BaseModel):
+    userid: Optional[str] = None
+    type: Optional[str] = None
+    groups: List[str] = Field(default_factory=list)
+
+
+class Kubernetes(BaseModel):
+    namespacename: Optional[str] = None
+    podname: Optional[str] = None
+    containername: Optional[str] = None
+    nodename: Optional[str] = None
+
+
+class ObjectRef(BaseModel):
+    resource: Optional[str] = None
+    resourceid: Optional[str] = None
+    apiversion: Optional[str] = None
+
+
+class Action(BaseModel):
+    name: Optional[str] = None
+    method: Optional[str] = None
+    severity: Optional[str] = None
+    status: Optional[str] = None
+
+
+class Network(BaseModel):
+    sourceip: Optional[str] = None
+    useragent: Optional[str] = None
+
+
+class EventMetadata(BaseModel):
+    issensitive: bool = False
+    compliancecategory: Optional[str] = None
+
+
+class EventData(BaseModel):
+    requestpayload: Dict[str, Any] = Field(default_factory=dict)
+    responsepayload: Dict[str, Any] = Field(default_factory=dict)
+    metadata: Optional[EventMetadata] = None
+
+
+class Security(BaseModel):
+    hash: Optional[str] = None
+    signature: Optional[str] = None
+
+
+class AuditLogEvent(BaseModel):
+    id: Optional[str] = None
+    specversion: Optional[str] = None
+    timestamp: Optional[str] = None
+    traceid: Optional[str] = None
+    transactionid: Optional[str] = None
+    tenantid: Optional[str] = None
+
+    subject: Optional[Subject] = None
+    kubernetes: Optional[Kubernetes] = None
+    objectref: Optional[ObjectRef] = None
+    action: Optional[Action] = None
+    network: Optional[Network] = None
+    eventdata: Optional[EventData] = None
+    security: Optional[Security] = None
+
+    def to_dict(self, *, include_security: bool = True) -> Dict[str, Any]:
+        """Pruned dict: empty values dropped, ready to publish."""
+        data = self.model_dump()
+        if not include_security:
+            data.pop("security", None)
+        return prune_empty(data)
+
+    def to_json(self, *, include_security: bool = True) -> str:
+        """Canonical JSON: pruned + alphabetically ordered keys."""
+        return json.dumps(
+            self.to_dict(include_security=include_security),
+            sort_keys=True,
+            separators=(",", ":"),
+            default=str,
+        )
+
+
+def prune_empty(value: Any) -> Any:
+    """Recursively drop None, empty strings, and empty lists/dicts, emitting
+    keys in alphabetical order.
+
+    Booleans and numbers (incl. ``False`` / ``0``) are preserved.
+    """
+    if isinstance(value, dict):
+        out: Dict[str, Any] = {}
+        for key in sorted(value.keys()):
+            pruned = prune_empty(value[key])
+            if pruned is None:
+                continue
+            if isinstance(pruned, str) and pruned == "":
+                continue
+            if isinstance(pruned, (list, dict, set)) and len(pruned) == 0:
+                continue
+            out[key] = pruned
+        return out
+    if isinstance(value, list):
+        return [prune_empty(item) for item in value]
+    return value

mobius_auditlog/publisher.py

@@ -0,0 +1,79 @@
+"""Publishes audit events to Kafka.
+
+Depends only on a small :class:`LogEventSender` protocol so the library has no
+hard Kafka dependency. Mobius FastAPI services publish via
+``py-kafka-producer-client``; wrap it with :class:`PyKafkaProducerClientSender`
+(or pass any object exposing ``send(value, *, topic)``).
+
+Publishing is best-effort and runs on a background thread pool so it never
+blocks the request path; failures are logged, never raised.
+"""
+from __future__ import annotations
+
+import logging
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Dict, Optional, Protocol, runtime_checkable
+
+from .models import AuditLogEvent
+from .security import seal
+
+log = logging.getLogger(__name__)
+
+DEFAULT_TOPIC = "audit-logs"
+
+_executor = ThreadPoolExecutor(max_workers=2, thread_name_prefix="mobius-auditlog")
+
+
+@runtime_checkable
+class LogEventSender(Protocol):
+    def send(self, value: Dict[str, Any], *, topic: str) -> Any:  # pragma: no cover
+        ...
+
+
+class PyKafkaProducerClientSender:
+    """Adapter for the internal ``py-kafka-producer-client`` (>=0.1.7)."""
+
+    def __init__(self, producer: Any) -> None:
+        self._producer = producer
+
+    def send(self, value: Dict[str, Any], *, topic: str) -> Any:
+        return self._producer.send(value, topic=topic)
+
+
+class AuditLogPublisher:
+    def __init__(
+        self,
+        sender: LogEventSender,
+        *,
+        topic: str = DEFAULT_TOPIC,
+        signing_key: Optional[str] = None,
+    ) -> None:
+        self._sender = sender
+        self._topic = topic
+        self._signing_key = signing_key
+
+    def publish(self, event: AuditLogEvent) -> None:
+        """Seal (hash/sign) and publish an event, fire-and-forget."""
+        seal(event, self._signing_key)
+        payload = event.to_dict()
+        _executor.submit(self._send, payload)
+
+    def _send(self, value: Dict[str, Any]) -> None:
+        try:
+            self._sender.send(value, topic=self._topic)
+        except Exception:  # noqa: BLE001 - never break the caller
+            log.warning("Failed to publish audit event", exc_info=True)
+
+
+# --- module-level default publisher (set at app startup) ---
+
+_default_publisher: Optional[AuditLogPublisher] = None
+
+
+def set_publisher(publisher: Optional[AuditLogPublisher]) -> None:
+    global _default_publisher
+    _default_publisher = publisher
+
+
+def get_publisher() -> Optional[AuditLogPublisher]:
+    return _default_publisher

mobius_auditlog/security.py

@@ -0,0 +1,45 @@
+"""Integrity for audit events: a content hash and an optional HMAC signature.
+
+The hash is SHA-256 over the canonical JSON of the event *excluding* the
+``security`` block, so it is deterministic and verifiable. The signature is an
+HMAC-SHA256 of that hash with a configured key.
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+from typing import Optional
+
+from .models import AuditLogEvent, Security
+
+
+def compute_hash(event: AuditLogEvent) -> str:
+    canonical = event.to_json(include_security=False)
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+def sign(value: str, key: str) -> str:
+    return hmac.new(key.encode("utf-8"), value.encode("utf-8"), hashlib.sha256).hexdigest()
+
+
+def seal(event: AuditLogEvent, signing_key: Optional[str] = None) -> AuditLogEvent:
+    """Populate ``event.security`` with the hash (and signature if a key is set)."""
+    digest = compute_hash(event)
+    signature = sign(digest, signing_key) if signing_key else None
+    event.security = Security(hash=digest, signature=signature)
+    return event
+
+
+def verify(event: AuditLogEvent, signing_key: Optional[str] = None) -> bool:
+    """Return True if the event's hash (and signature, if a key is given) match."""
+    if event.security is None or not event.security.hash:
+        return False
+    expected_hash = compute_hash(event)
+    if not hmac.compare_digest(expected_hash, event.security.hash):
+        return False
+    if signing_key:
+        expected_sig = sign(expected_hash, signing_key)
+        return bool(event.security.signature) and hmac.compare_digest(
+            expected_sig, event.security.signature
+        )
+    return True

mobius_auditlog_py-1.0.0.dist-info/METADATA

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: mobius-auditlog-py
+Version: 1.0.0
+Summary: CloudEvents-style audit event model, builder, integrity signing and Kafka publishing for Mobius Python (FastAPI) services.
+Author: Mobius Platform
+Keywords: audit,auditlog,fastapi,mobius,cloudevents
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0
+Requires-Dist: starlette>=0.27
+Requires-Dist: py-kafka-producer-client>=0.1.7
+Provides-Extra: tracer
+Requires-Dist: mobius-tracer-py>=1.0; extra == "tracer"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: starlette>=0.27; extra == "dev"
+Requires-Dist: httpx>=0.24; extra == "dev"
+
+# mobius-auditlog-py
+
+Build, sign, and publish **CloudEvents-style audit events** from Mobius
+**Python (FastAPI / Starlette)** services.
+
+- **PyPI:** `pip install mobius-auditlog-py`
+- **Import package:** `mobius_auditlog`
+- **Python:** 3.10+
+
+## Install
+
+```bash
+pip install mobius-auditlog-py
+```
+
+`pydantic`, `starlette`, and `py-kafka-producer-client` are installed
+automatically.
+
+## Quick start (auto-capture middleware)
+
+```python
+from fastapi import FastAPI
+from kafka_producer_client import KafkaProducerConfig
+from mobius_auditlog import setup_auditlog
+
+app = FastAPI()
+
+setup_auditlog(
+    app,
+    topic="audit-logs",
+    signing_key="your-hmac-key",                # optional signature
+    kafka_config=KafkaProducerConfig(bootstrap_servers="broker:9092"),
+    capture_payloads=False,                      # set True to buffer req/resp bodies
+    compliance_category="GDPR",
+)
+```
+
+The middleware emits one audit event per request: `action` (route, method,
+status, severity), `network` (client IP + user-agent), `objectref` (from the
+path), and the envelope/`subject` from the request context. It skips
+health/metrics/swagger paths.
+
+## The event schema
+
+`AuditLogEvent` — flat envelope + nested sections, serialized with empty values
+omitted and keys alphabetically ordered:
+
+| Section | Fields |
+|---|---|
+| envelope | `id`, `specversion`, `timestamp`, `traceid`, `transactionid`, `tenantid` |
+| `subject` | `userid`, `type`, `groups[]` |
+| `kubernetes` | `namespacename`, `podname`, `containername`, `nodename` |
+| `objectref` | `resource`, `resourceid`, `apiversion` |
+| `action` | `name`, `method`, `severity`, `status` |
+| `network` | `sourceip`, `useragent` |
+| `eventdata` | `requestpayload{}`, `responsepayload{}`, `metadata{issensitive, compliancecategory}` |
+| `security` | `hash`, `signature` |
+
+```python
+event.to_dict()    # pruned dict (empties dropped), ready to publish
+event.to_json()    # canonical JSON: pruned + sorted keys (used for hashing)
+```
+
+## Building events manually
+
+```python
+from mobius_auditlog import AuditLogBuilder
+
+event = (
+    AuditLogBuilder()
+    .from_context()                              # tenant/trace/txn/subject from context
+    .object_ref(resource="order", resourceid="order-789", apiversion="v1.0")
+    .action(name="order.create", method="POST", severity="INFO", status="SUCCESS")
+    .network(sourceip="1.2.3.4", useragent="curl/8")
+    .event_data(requestpayload={"amount": 42}, issensitive=True, compliancecategory="PCI")
+    .build()
+)
+```
+
+`from_context()` pulls `tenantid`/`traceid`/`transactionid`/`subject` from the
+`mobius-tracer-py` request context when that package is installed, and
+`kubernetes` from the downward-API env vars (`POD_NAMESPACE`, `POD_NAME`,
+`CONTAINER_NAME`, `NODE_NAME`).
+
+## Integrity: hash + signature
+
+```python
+from mobius_auditlog import seal, verify, compute_hash
+
+seal(event, signing_key="key")     # sets security.hash (+ signature)
+verify(event, signing_key="key")   # True if hash + signature match
+```
+
+- `hash` = SHA-256 over the canonical JSON **excluding** the `security` block.
+- `signature` = HMAC-SHA256 of the hash with your key (omitted if no key).
+
+The publisher seals events automatically before sending.
+
+## Publishing
+
+The publisher depends only on a small protocol — no hard Kafka coupling:
+
+```python
+class LogEventSender(Protocol):
+    def send(self, value: dict, *, topic: str) -> Any: ...
+```
+
+`setup_auditlog` resolves a publisher from (in order) `kafka_sender` →
+`kafka_producer` → `kafka_config` → the configured `py-kafka-producer-client`
+singleton. Or use it directly:
+
+```python
+from mobius_auditlog import AuditLogPublisher, PyKafkaProducerClientSender, set_publisher
+
+publisher = AuditLogPublisher(PyKafkaProducerClientSender(client),
+                              topic="audit-logs", signing_key="key")
+set_publisher(publisher)
+publisher.publish(event)           # seals + sends, fire-and-forget
+```
+
+Publishing runs on a background thread and never raises into the request path.
+
+## Payload capture
+
+With `capture_payloads=True`, the middleware buffers request and response bodies
+(JSON-parsed, size-capped at 64 KB) into `eventdata.requestpayload` /
+`responsepayload`. Off by default for privacy and overhead. Non-JSON bodies are
+stored as `{"_raw": "..."}`.
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```

mobius_auditlog_py-1.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+mobius_auditlog/__init__.py,sha256=cq3kHahKiEtg-evakXO_e4wgkFxf1TQGM8cZ1kbId5s,1216
+mobius_auditlog/bootstrap.py,sha256=fETB9TTauuB8nS_4MNmT6QscjDuRSBQyJjhqc6DR6DQ,2905
+mobius_auditlog/builder.py,sha256=WXiGic73LsvUC3ZBVSPlaaE-S2JJRvZElEkRS9jpcrM,3124
+mobius_auditlog/context.py,sha256=87LEPIbpWHKRG-r3C8JpfnSFr1pCPuOM267QwObzoQs,1769
+mobius_auditlog/middleware.py,sha256=Mb1TJ8csui1QATiQ0Yq8jpKl8L368NxLB90AtaAgWgc,5562
+mobius_auditlog/models.py,sha256=MzLN-aj2O6dy7ks750cJgd9L_he5_qSqCWXnDhGkvNA,3500
+mobius_auditlog/publisher.py,sha256=yng5t8nioaGOQehuvH5pXwg0MCJTSxZvSdFRQHRcA7c,2434
+mobius_auditlog/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mobius_auditlog/security.py,sha256=rPjAAI_sGm21hlL70NF0RpUvwrIw9880xTovqq-Jyng,1667
+mobius_auditlog_py-1.0.0.dist-info/METADATA,sha256=kBmJdOXzq9xli8tK7HpQQYlWMAHR-7fjkEF-5lhyiyk,5087
+mobius_auditlog_py-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mobius_auditlog_py-1.0.0.dist-info/top_level.txt,sha256=QHP6jxiFMYE0AmA-pwlsa9RXLRxTcvScAyYDZk4XxTk,16
+mobius_auditlog_py-1.0.0.dist-info/RECORD,,

mobius_auditlog_py-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mobius_auditlog_py-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mobius_auditlog