starfish-audit 3.0.0a5__tar.gz

starfish_audit-3.0.0a5/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: starfish-audit
+Version: 3.0.0a5
+Summary: Starfish audit logging extension (console / callback / no-op audit loggers for server pull/push events)
+Requires-Python: >=3.11
+Requires-Dist: starfish-protocol
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: starfish-server; extra == "dev"

starfish_audit-3.0.0a5/README.md

@@ -0,0 +1,53 @@
+# starfish-audit
+
+Starfish audit logging extension for Python — ready-made audit loggers for
+recording the server's pull/push access events. The `AuditEntry` / `AuditLogger`
+contract lives in `starfish-protocol`; this package ships the concrete loggers.
+
+## Install
+
+```sh
+pip install starfish-server starfish-audit
+```
+
+## Usage
+
+Pass a logger to the sync router via `audit_logger`:
+
+```python
+from starfish_server.router.route_builder import create_sync_router, SyncRouterOptions
+from starfish_audit import ConsoleAuditLogger
+
+router = create_sync_router(
+    SyncRouterOptions(
+        store=store,
+        config=config,
+        role_resolver=role_resolver,
+        audit_logger=ConsoleAuditLogger(),
+    ),
+)
+```
+
+Write your own sink with `CallbackAuditLogger` (sync or async callback):
+
+```python
+from starfish_audit import CallbackAuditLogger, AuditEntry
+
+async def _record(entry: AuditEntry) -> None:
+    await db.audit.insert(entry)
+
+audit_logger = CallbackAuditLogger(_record)
+```
+
+`NoopAuditLogger` discards entries.
+
+The server **awaits** `record()` for each request, so the entry is durable before
+the response is returned. Keep the sink fast and resilient: a slow logger adds
+request latency and a raising one surfaces as a request error.
+
+> Audit logging is server-side observability — this package depends only on
+> `starfish-protocol` and registers no cap-cert validator. Note: the Python
+> server currently emits audit entries on **push** operations (the TypeScript
+> server emits on both pull and push).
+
+See `docs/python/audit/` (and the TypeScript counterpart in `docs/ts/audit/`) for the full guide.

starfish_audit-3.0.0a5/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "starfish-audit"
+version = "3.0.0a5"
+description = "Starfish audit logging extension (console / callback / no-op audit loggers for server pull/push events)"
+requires-python = ">=3.11"
+dependencies = [
+  "starfish-protocol",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0",
+  "pytest-asyncio>=0.21",
+  "httpx>=0.27",
+  "starfish-server",
+]
+
+[tool.uv.sources]
+starfish-protocol = { path = "../protocol", editable = true }
+starfish-server = { path = "../server", editable = true }
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

starfish_audit-3.0.0a5/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

starfish_audit-3.0.0a5/starfish_audit/__init__.py

@@ -0,0 +1,22 @@
+"""``starfish-audit`` — audit logging extension.
+
+Ready-made audit loggers for recording the server's pull/push access events.
+The ``AuditEntry`` / ``AuditLogger`` contract lives in ``starfish_protocol``;
+this package re-exports them alongside the concrete loggers for convenience.
+"""
+
+from starfish_protocol import AuditEntry, AuditLogger
+
+from starfish_audit.audit import (
+    CallbackAuditLogger,
+    ConsoleAuditLogger,
+    NoopAuditLogger,
+)
+
+__all__ = [
+    "AuditEntry",
+    "AuditLogger",
+    "ConsoleAuditLogger",
+    "CallbackAuditLogger",
+    "NoopAuditLogger",
+]

starfish_audit-3.0.0a5/starfish_audit/audit.py

@@ -0,0 +1,44 @@
+"""Concrete audit loggers for the Starfish server.
+
+The ``AuditEntry`` dataclass and ``AuditLogger`` base class live in
+``starfish_protocol``; this module supplies the ready-made implementations.
+"""
+
+import inspect
+from typing import Awaitable, Callable
+
+from starfish_protocol import AuditEntry, AuditLogger
+
+
+class ConsoleAuditLogger(AuditLogger):
+    """Audit logger that writes to console."""
+
+    async def record(self, entry: AuditEntry) -> None:
+        status = "OK" if entry.success else "FAIL"
+        identity = entry.identity or "anonymous"
+        print(
+            f"[Starfish:AUDIT] {entry.action.upper()} {entry.collection} "
+            f"by {identity} → {status} ({entry.status_code})"
+        )
+
+
+class CallbackAuditLogger(AuditLogger):
+    """Audit logger that delegates to a sync or async callback."""
+
+    def __init__(self, callback: Callable[[AuditEntry], None | Awaitable[None]]) -> None:
+        self._callback = callback
+
+    async def record(self, entry: AuditEntry) -> None:
+        result = self._callback(entry)
+        if inspect.isawaitable(result):
+            await result
+
+
+class NoopAuditLogger(AuditLogger):
+    """No-op audit logger (discards entries)."""
+
+    async def record(self, entry: AuditEntry) -> None:
+        pass
+
+
+__all__ = ["ConsoleAuditLogger", "CallbackAuditLogger", "NoopAuditLogger"]

starfish_audit-3.0.0a5/starfish_audit.egg-info/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: starfish-audit
+Version: 3.0.0a5
+Summary: Starfish audit logging extension (console / callback / no-op audit loggers for server pull/push events)
+Requires-Python: >=3.11
+Requires-Dist: starfish-protocol
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: starfish-server; extra == "dev"

starfish_audit-3.0.0a5/starfish_audit.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+starfish_audit/__init__.py
+starfish_audit/audit.py
+starfish_audit.egg-info/PKG-INFO
+starfish_audit.egg-info/SOURCES.txt
+starfish_audit.egg-info/dependency_links.txt
+starfish_audit.egg-info/requires.txt
+starfish_audit.egg-info/top_level.txt
+tests/test_audit.py
+tests/test_audit_router.py

starfish_audit-3.0.0a5/starfish_audit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

starfish_audit-3.0.0a5/starfish_audit.egg-info/requires.txt

@@ -0,0 +1,7 @@
+starfish-protocol
+
+[dev]
+pytest>=7.0
+pytest-asyncio>=0.21
+httpx>=0.27
+starfish-server

starfish_audit-3.0.0a5/starfish_audit.egg-info/top_level.txt

@@ -0,0 +1 @@
+starfish_audit

starfish_audit-3.0.0a5/tests/test_audit.py

@@ -0,0 +1,55 @@
+"""Tests for audit logging."""
+
+import pytest
+from starfish_audit import AuditEntry, ConsoleAuditLogger, CallbackAuditLogger, NoopAuditLogger
+
+
+def _make_entry() -> AuditEntry:
+    return AuditEntry(
+        timestamp=1234,
+        action="pull",
+        collection="settings",
+        identity="user-1",
+        document_key="users/user-1/settings",
+        success=True,
+        status_code=200,
+    )
+
+
+@pytest.mark.asyncio
+async def test_console_audit_logger(capsys):
+    logger = ConsoleAuditLogger()
+    await logger.record(_make_entry())
+    captured = capsys.readouterr()
+    assert "PULL" in captured.out
+    assert "settings" in captured.out
+
+
+@pytest.mark.asyncio
+async def test_callback_audit_logger_sync():
+    entries = []
+    logger = CallbackAuditLogger(lambda e: entries.append(e))
+    entry = _make_entry()
+    await logger.record(entry)
+    assert len(entries) == 1
+    assert entries[0] == entry
+
+
+@pytest.mark.asyncio
+async def test_callback_audit_logger_async():
+    entries = []
+    async def async_cb(e: AuditEntry) -> None:
+        entries.append(e)
+    logger = CallbackAuditLogger(async_cb)
+    entry = _make_entry()
+    await logger.record(entry)
+    assert len(entries) == 1
+    assert entries[0] == entry
+
+
+@pytest.mark.asyncio
+async def test_noop_audit_logger(capsys):
+    logger = NoopAuditLogger()
+    await logger.record(_make_entry())
+    captured = capsys.readouterr()
+    assert captured.out == ""

starfish_audit-3.0.0a5/tests/test_audit_router.py

@@ -0,0 +1,227 @@
+"""AuditLogger must be called on push operations in the Python router.
+This test suite verifies that
+SyncRouterOptions.audit_logger is wired through the push handler.
+"""
+
+import asyncio
+
+import pytest
+from fastapi import FastAPI, Request
+from httpx import AsyncClient, ASGITransport
+
+from starfish_server.config.schema import SyncConfig, CollectionConfig
+from starfish_server.router.route_builder import create_sync_router, SyncRouterOptions, AuthResult
+from starfish_audit import AuditLogger, AuditEntry
+from tests.helpers import MemoryObjectStore
+
+
+def _make_app_with_audit(audit_logger: AuditLogger) -> tuple[FastAPI, MemoryObjectStore]:
+    store = MemoryObjectStore()
+    config = SyncConfig(
+        version=1,
+        collections=[
+            CollectionConfig(
+                name="settings",
+                storagePath="users/{identity}/settings",
+                readRoles=["self"],
+                writeRoles=["self"],
+                encryption="none",
+                maxBodyBytes=65536,
+            ),
+        ],
+    )
+
+    async def role_resolver(request: Request) -> AuthResult:
+        return AuthResult(identity="user-1", roles=["self"])
+
+    router = create_sync_router(
+        SyncRouterOptions(
+            store=store,
+            config=config,
+            role_resolver=role_resolver,
+            audit_logger=audit_logger,
+        ),
+    )
+    app = FastAPI()
+    app.include_router(router)
+    return app, store
+
+
+# ─── successful push emits audit entry ──────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_successful_push_records_audit_entry():
+    """A 200 push must call audit_logger.record with success=True."""
+    recorded: list[AuditEntry] = []
+
+    class CapturingLogger(AuditLogger):
+        async def record(self, entry: AuditEntry) -> None:
+            recorded.append(entry)
+
+    app, _ = _make_app_with_audit(CapturingLogger())
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client:
+        resp = await client.post(
+            "/push/users/user-1/settings",
+            json={"data": {"x": 1}, "baseHash": None},
+        )
+
+    assert resp.status_code == 200
+    assert len(recorded) == 1
+    entry = recorded[0]
+    assert entry.action == "push"
+    assert entry.success is True
+    assert entry.status_code == 200
+    assert entry.collection == "settings"
+    assert entry.identity == "user-1"
+
+
+# ─── conflict (409) push emits audit entry with failure ─────────────────
+
+@pytest.mark.asyncio
+async def test_conflict_push_records_audit_entry():
+    """ A 409 conflict push must call audit_logger.record with success=False."""
+    recorded: list[AuditEntry] = []
+
+    class CapturingLogger(AuditLogger):
+        async def record(self, entry: AuditEntry) -> None:
+            recorded.append(entry)
+
+    app, _ = _make_app_with_audit(CapturingLogger())
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client:
+        # First push succeeds
+        await client.post(
+            "/push/users/user-1/settings",
+            json={"data": {"x": 1}, "baseHash": None},
+        )
+        # Second push with wrong baseHash → 409
+        conflict_resp = await client.post(
+            "/push/users/user-1/settings",
+            json={"data": {"x": 2}, "baseHash": "wrong-hash"},
+        )
+
+    assert conflict_resp.status_code == 409
+    assert len(recorded) == 2  # both pushes recorded
+    conflict_entry = recorded[1]
+    assert conflict_entry.action == "push"
+    assert conflict_entry.success is False
+    assert conflict_entry.status_code == 409
+
+
+# ─── no audit_logger → no error ────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_push_without_audit_logger_does_not_crash():
+    """ When audit_logger is None (default), push must still work normally."""
+    store = MemoryObjectStore()
+    config = SyncConfig(
+        version=1,
+        collections=[
+            CollectionConfig(
+                name="settings",
+                storagePath="users/{identity}/settings",
+                readRoles=["self"],
+                writeRoles=["self"],
+                encryption="none",
+                maxBodyBytes=65536,
+            ),
+        ],
+    )
+
+    async def role_resolver(request: Request) -> AuthResult:
+        return AuthResult(identity="user-1", roles=["self"])
+
+    # No audit_logger passed → must default to None
+    router = create_sync_router(
+        SyncRouterOptions(store=store, config=config, role_resolver=role_resolver),
+    )
+    app = FastAPI()
+    app.include_router(router)
+
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client:
+        resp = await client.post(
+            "/push/users/user-1/settings",
+            json={"data": {"y": 2}, "baseHash": None},
+        )
+    assert resp.status_code == 200
+
+
+# ─── auth denial (403) emits an audit entry with failure ────────────────
+
+@pytest.mark.asyncio
+async def test_denied_push_records_audit_entry():
+    """A 403 auth denial must call audit_logger.record with success=False.
+
+    Without this, only requests that pass the auth gate are ever audited — so
+    denied (401/403) attempts leave no trace in the trail.
+    """
+    recorded: list[AuditEntry] = []
+
+    class CapturingLogger(AuditLogger):
+        async def record(self, entry: AuditEntry) -> None:
+            recorded.append(entry)
+
+    store = MemoryObjectStore()
+    config = SyncConfig(
+        version=1,
+        collections=[
+            CollectionConfig(
+                name="settings",
+                storagePath="users/{identity}/settings",
+                readRoles=["admin"],
+                writeRoles=["admin"],  # a role the caller never holds
+                encryption="none",
+                maxBodyBytes=65536,
+            ),
+        ],
+    )
+
+    async def role_resolver(request: Request) -> AuthResult:
+        return AuthResult(identity="user-1", roles=[])  # no roles → write denied
+
+    router = create_sync_router(
+        SyncRouterOptions(
+            store=store, config=config, role_resolver=role_resolver, audit_logger=CapturingLogger()
+        ),
+    )
+    app = FastAPI()
+    app.include_router(router)
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client:
+        resp = await client.post(
+            "/push/users/user-1/settings",
+            json={"data": {"x": 1}, "baseHash": None},
+        )
+
+    assert resp.status_code == 403
+    assert len(recorded) == 1
+    assert recorded[0].action == "push"
+    assert recorded[0].success is False
+    assert recorded[0].status_code == 403
+    assert recorded[0].collection == "settings"
+
+
+@pytest.mark.asyncio
+async def test_awaits_async_audit_logger_before_returning_push_response():
+    # Cross-language divergence. Python does `await audit_logger.record(...)`, so an
+    # async logger's write completes before the response is returned (this test).
+    # TS calls `opts.auditLogger.record(...)` WITHOUT await, so an async logger is
+    # fire-and-forget — the entry may not be written before the response, and a
+    # rejected logger becomes an unhandled rejection. This is the reference for the
+    # convergent durable behaviour; the TS side is pinned as it.fails in
+    # router-emission.test.ts.
+    audit_completed = False
+
+    class SlowLogger(AuditLogger):
+        async def record(self, entry: AuditEntry) -> None:
+            nonlocal audit_completed
+            await asyncio.sleep(0)
+            audit_completed = True
+
+    app, _ = _make_app_with_audit(SlowLogger())
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client:
+        resp = await client.post(
+            "/push/users/user-1/settings",
+            json={"data": {"x": 1}, "baseHash": None},
+        )
+
+    assert resp.status_code == 200
+    assert audit_completed is True  # Python awaits the record call before responding