anip-server 0.11.0__py3-none-any.whl

anip_server/__init__.py

@@ -0,0 +1,37 @@
+"""ANIP Server — delegation, audit, checkpoints, Merkle trees, sinks."""
+from .delegation import DelegationEngine
+from .permissions import discover_permissions
+from .manifest import build_manifest
+from .audit import AuditLog
+from .merkle import MerkleTree
+from .checkpoint import create_checkpoint, reconstruct_and_create_checkpoint, CheckpointPolicy, CheckpointScheduler
+from .sinks import CheckpointSink, LocalFileSink
+from .storage import StorageBackend, SQLiteStorage, InMemoryStorage
+from .hashing import compute_entry_hash, canonical_bytes
+from .retention_enforcer import RetentionEnforcer
+
+try:
+    from .postgres import PostgresStorage
+except ImportError:
+    pass  # asyncpg not installed
+
+__all__ = [
+    "DelegationEngine",
+    "discover_permissions",
+    "build_manifest",
+    "AuditLog",
+    "MerkleTree",
+    "create_checkpoint",
+    "reconstruct_and_create_checkpoint",
+    "CheckpointPolicy",
+    "CheckpointScheduler",
+    "CheckpointSink",
+    "LocalFileSink",
+    "StorageBackend",
+    "SQLiteStorage",
+    "InMemoryStorage",
+    "PostgresStorage",
+    "RetentionEnforcer",
+    "compute_entry_hash",
+    "canonical_bytes",
+]

anip_server/audit.py

@@ -0,0 +1,81 @@
+"""Audit log manager for ANIP services."""
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable
+from datetime import datetime, timezone
+from typing import Any, Callable
+
+from .storage import StorageBackend
+
+
+class AuditLog:
+    """Audit log backed by a StorageBackend.
+
+    Sequence numbers, hash chaining, and Merkle accumulation are now
+    handled by the storage layer (``append_audit_entry``).
+    """
+
+    def __init__(
+        self,
+        storage: StorageBackend,
+        signer: Callable[[dict[str, Any]], str | Awaitable[str]] | None = None,
+    ) -> None:
+        self._storage = storage
+        self._signer = signer
+
+    async def log_entry(self, entry_data: dict[str, Any]) -> dict[str, Any]:
+        """Log an audit entry via the storage backend.
+
+        entry_data should contain: capability, token_id, root_principal, success,
+        and optionally: issuer, subject, parameters, result_summary, failure_type,
+        cost_actual, delegation_chain.
+
+        Returns the complete entry dict (with sequence_number, timestamp, previous_hash, signature).
+        """
+        now = datetime.now(timezone.utc).isoformat()
+        entry_for_storage = {
+            "timestamp": now,
+            "capability": entry_data["capability"],
+            "token_id": entry_data.get("token_id"),
+            "issuer": entry_data.get("issuer"),
+            "subject": entry_data.get("subject"),
+            "root_principal": entry_data.get("root_principal"),
+            "parameters": entry_data.get("parameters"),
+            "success": entry_data["success"],
+            "result_summary": entry_data.get("result_summary"),
+            "failure_type": entry_data.get("failure_type"),
+            "cost_actual": entry_data.get("cost_actual"),
+            "delegation_chain": entry_data.get("delegation_chain"),
+            "invocation_id": entry_data.get("invocation_id"),
+            "client_reference_id": entry_data.get("client_reference_id"),
+            "stream_summary": entry_data.get("stream_summary"),
+            "event_class": entry_data.get("event_class"),
+            "retention_tier": entry_data.get("retention_tier"),
+            "expires_at": entry_data.get("expires_at"),
+            "storage_redacted": entry_data.get("storage_redacted", False),
+            "entry_type": entry_data.get("entry_type"),
+            "grouping_key": entry_data.get("grouping_key"),
+            "aggregation_window": entry_data.get("aggregation_window"),
+            "aggregation_count": entry_data.get("aggregation_count"),
+            "first_seen": entry_data.get("first_seen"),
+            "last_seen": entry_data.get("last_seen"),
+            "representative_detail": entry_data.get("representative_detail"),
+        }
+
+        entry = await self._storage.append_audit_entry(entry_for_storage)
+
+        if self._signer:
+            sig = self._signer(entry)
+            if inspect.isawaitable(sig):
+                sig = await sig
+            entry["signature"] = sig
+            await self._storage.update_audit_signature(entry["sequence_number"], sig)
+        else:
+            entry["signature"] = None
+
+        return entry
+
+    async def query(self, **filters: Any) -> list[dict[str, Any]]:
+        """Query audit entries with optional filters."""
+        return await self._storage.query_audit_entries(**filters)

anip_server/checkpoint.py

@@ -0,0 +1,205 @@
+"""Checkpoint policy and scheduling for ANIP audit logs."""
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+from collections.abc import Awaitable
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Callable
+
+from .hashing import canonical_bytes as _canonical_bytes
+from .merkle import MerkleTree
+from .storage import StorageBackend
+
+
+@dataclass
+class CheckpointPolicy:
+    """Defines when a checkpoint should be created."""
+
+    entry_count: int | None = None
+    interval_seconds: int | None = None
+
+    def should_checkpoint(
+        self, entries_since_last: int, seconds_since_last: float = 0
+    ) -> bool:
+        if self.entry_count is not None and entries_since_last >= self.entry_count:
+            return True
+        if (
+            self.interval_seconds is not None
+            and seconds_since_last >= self.interval_seconds
+        ):
+            return True
+        return False
+
+
+class CheckpointScheduler:
+    """Background scheduler that coordinates checkpoint generation."""
+
+    def __init__(
+        self,
+        interval_seconds: int,
+        create_fn: Callable[[], Awaitable[None]],
+        on_error: Callable[[str], None] | None = None,
+    ):
+        self._interval = interval_seconds
+        self._create_fn = create_fn
+        self._on_error = on_error
+        self._task: asyncio.Task[None] | None = None
+        self._last_run_at: str | None = None
+        self._last_error: str | None = None
+
+    @property
+    def last_run_at(self) -> str | None:
+        return self._last_run_at
+
+    @property
+    def last_error(self) -> str | None:
+        return self._last_error
+
+    def start(self) -> None:
+        loop = asyncio.get_running_loop()
+        self._task = loop.create_task(self._run())
+
+    def stop(self) -> None:
+        if self._task:
+            self._task.cancel()
+            self._task = None
+
+    async def _run(self) -> None:
+        while True:
+            await asyncio.sleep(self._interval)
+            try:
+                await self._create_fn()
+                self._last_run_at = datetime.now(timezone.utc).isoformat()
+                self._last_error = None
+            except asyncio.CancelledError:
+                raise
+            except Exception as e:
+                self._last_error = str(e)
+                if self._on_error:
+                    self._on_error(str(e))
+
+
+def create_checkpoint(
+    *,
+    merkle_snapshot: dict[str, Any],
+    service_id: str,
+    previous_checkpoint: dict[str, Any] | None,
+    sign_fn: Callable[[bytes], str] | None = None,
+) -> tuple[dict[str, Any], str]:
+    """Create a checkpoint body and sign it.
+
+    Returns (body_dict, signature_string).
+    """
+    if previous_checkpoint is None:
+        first_sequence = 1
+        prev_hash = None
+        checkpoint_number = 1
+    else:
+        first_sequence = (
+            previous_checkpoint.get("range", {}).get("last_sequence", 0) + 1
+        )
+        prev_body_canonical = json.dumps(
+            previous_checkpoint, separators=(",", ":"), sort_keys=True
+        ).encode()
+        prev_hash = f"sha256:{hashlib.sha256(prev_body_canonical).hexdigest()}"
+        prev_id = previous_checkpoint.get("checkpoint_id", "ckpt-0")
+        checkpoint_number = int(prev_id.split("-")[1]) + 1
+
+    last_sequence = merkle_snapshot["leaf_count"]
+    entry_count = last_sequence - first_sequence + 1
+
+    body = {
+        "version": "0.3",
+        "service_id": service_id,
+        "checkpoint_id": f"ckpt-{checkpoint_number}",
+        "range": {
+            "first_sequence": first_sequence,
+            "last_sequence": last_sequence,
+        },
+        "merkle_root": merkle_snapshot["root"],
+        "previous_checkpoint": prev_hash,
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "entry_count": entry_count,
+    }
+
+    canonical_bytes = json.dumps(
+        body, separators=(",", ":"), sort_keys=True
+    ).encode()
+    signature = sign_fn(canonical_bytes) if sign_fn else ""
+
+    return body, signature
+
+
+async def reconstruct_and_create_checkpoint(
+    *,
+    storage: StorageBackend,
+    service_id: str,
+    sign_fn: Callable[[bytes], str] | None = None,
+) -> tuple[dict[str, Any], str] | None:
+    """Reconstruct Merkle tree from storage and create a checkpoint.
+
+    Reads ALL audit entries from storage, rebuilds the cumulative Merkle
+    tree, and produces a new checkpoint covering everything up to the
+    current max sequence number.
+
+    Returns (body, signature) or None if no new entries since last checkpoint.
+    """
+    max_seq = await storage.get_max_audit_sequence()
+    if max_seq is None:
+        return None
+
+    checkpoints = await storage.get_checkpoints(limit=1)
+    last_cp = checkpoints[-1] if checkpoints else None
+    last_covered = last_cp["range"]["last_sequence"] if last_cp else 0
+
+    if max_seq <= last_covered:
+        return None  # No new entries
+
+    # Full reconstruction from entry 1
+    entries = await storage.get_audit_entries_range(1, max_seq)
+
+    # Rebuild Merkle tree
+    tree = MerkleTree()
+    for entry in entries:
+        tree.add_leaf(_canonical_bytes(entry))
+
+    snapshot = tree.snapshot()
+
+    # For cumulative checkpoints the range always starts at 1 because the
+    # Merkle tree is rebuilt from the very first entry.  create_checkpoint
+    # would normally compute first_sequence from the previous checkpoint's
+    # last_sequence, so we pass a synthetic copy with last_sequence=0 to
+    # force first_sequence=1 while keeping checkpoint_id for numbering.
+    synthetic_prev: dict[str, Any] | None = None
+    if last_cp is not None:
+        synthetic_prev = {
+            **last_cp,
+            "range": {**last_cp["range"], "last_sequence": 0},
+        }
+
+    body, signature = create_checkpoint(
+        merkle_snapshot=snapshot,
+        service_id=service_id,
+        previous_checkpoint=synthetic_prev,
+        sign_fn=sign_fn,
+    )
+
+    # Restore the correct previous_checkpoint hash (computed from the
+    # real stored checkpoint, not the synthetic copy).
+    if last_cp is not None:
+        prev_body_canonical = json.dumps(
+            last_cp, separators=(",", ":"), sort_keys=True
+        ).encode()
+        body["previous_checkpoint"] = (
+            f"sha256:{hashlib.sha256(prev_body_canonical).hexdigest()}"
+        )
+
+    # Re-sign with the corrected body if a sign_fn was provided.
+    if last_cp is not None and sign_fn is not None:
+        cb = json.dumps(body, separators=(",", ":"), sort_keys=True).encode()
+        signature = sign_fn(cb)
+
+    return body, signature