ledgix-python 0.1.2__tar.gz → 0.1.3__tar.gz

{ledgix_python-0.1.2 → ledgix_python-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ledgix-python
-Version: 0.1.2
+Version: 0.1.3
 Summary: Agent-agnostic compliance shim for SOX 404 policy enforcement via the ALCV Vault
 Project-URL: Homepage, https://github.com/ledgix-dev/python-sdk
 Project-URL: Documentation, https://docs.ledgix.dev
@@ -40,7 +40,7 @@ Description-Content-Type: text/markdown
 
 # Ledgix ALCV — Python SDK
 
-[![PyPI](https://img.shields.io/pypi/v/ledgix-python)](https://pypi.org/project/ledgix-python/)
+[![PyPI](https://img.shields.io/badge/pypi-v0.1.3-blue)](https://pypi.org/project/ledgix-python/)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://python.org)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 

{ledgix_python-0.1.2 → ledgix_python-0.1.3}/README.md

@@ -1,6 +1,6 @@
 # Ledgix ALCV — Python SDK
 
-[![PyPI](https://img.shields.io/pypi/v/ledgix-python)](https://pypi.org/project/ledgix-python/)
+[![PyPI](https://img.shields.io/badge/pypi-v0.1.3-blue)](https://pypi.org/project/ledgix-python/)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://python.org)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 

{ledgix_python-0.1.2 → ledgix_python-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ledgix-python"
-version = "0.1.2"
+version = "0.1.3"
 description = "Agent-agnostic compliance shim for SOX 404 policy enforcement via the ALCV Vault"
 readme = "README.md"
 license = { text = "MIT" }

{ledgix_python-0.1.2 → ledgix_python-0.1.3}/src/ledgix_python/__init__.py

@@ -27,6 +27,9 @@ from .exceptions import (
 from .models import (
     ClearanceRequest,
     ClearanceResponse,
+    LedgerEntry,
+    LedgerManifest,
+    LedgerVerificationResult,
     PolicyRegistration,
     PolicyRegistrationResponse,
 )
@@ -43,6 +46,9 @@ __all__ = [
     # Models
     "ClearanceRequest",
     "ClearanceResponse",
+    "LedgerEntry",
+    "LedgerManifest",
+    "LedgerVerificationResult",
     "PolicyRegistration",
     "PolicyRegistrationResponse",
     # Exceptions

{ledgix_python-0.1.2 → ledgix_python-0.1.3}/src/ledgix_python/client.py

@@ -6,8 +6,11 @@ from __future__ import annotations
 import json
 import random
 import time
+import hashlib
+import base64
 from collections.abc import Awaitable, Callable
 from typing import Any
+from urllib.parse import urlencode
 
 import httpx
 import jwt
@@ -25,6 +28,9 @@ from .exceptions import (
 from .models import (
     ClearanceRequest,
     ClearanceResponse,
+    LedgerEntry,
+    LedgerManifest,
+    LedgerVerificationResult,
     PolicyRegistration,
     PolicyRegistrationResponse,
 )
@@ -316,6 +322,106 @@ class LedgixClient:
         self._jwks_cache = response.json()
         return self._jwks_cache
 
+    def fetch_ledger(self, limit: int = 100) -> list[LedgerEntry]:
+        """Fetch recent ledger entries for the authenticated tenant (sync)."""
+        query = urlencode({"limit": max(1, min(limit, 500))})
+        try:
+            response = self._sync_retry(lambda: self._get_sync_client().get(f"/ledger?{query}"))
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            raise VaultConnectionError(
+                f"Failed to fetch ledger: HTTP {exc.response.status_code}"
+            ) from exc
+
+        payload = response.json()
+        return [LedgerEntry.model_validate(item) for item in payload.get("entries", [])]
+
+    async def afetch_ledger(self, limit: int = 100) -> list[LedgerEntry]:
+        """Fetch recent ledger entries for the authenticated tenant (async)."""
+        query = urlencode({"limit": max(1, min(limit, 500))})
+        try:
+            response = await self._async_retry(lambda: self._get_async_client().get(f"/ledger?{query}"))
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            raise VaultConnectionError(
+                f"Failed to fetch ledger: HTTP {exc.response.status_code}"
+            ) from exc
+
+        payload = response.json()
+        return [LedgerEntry.model_validate(item) for item in payload.get("entries", [])]
+
+    def fetch_ledger_manifests(self, limit: int = 24) -> list[LedgerManifest]:
+        """Fetch recent signed ledger manifests for the authenticated tenant (sync)."""
+        query = urlencode({"limit": max(1, min(limit, 500))})
+        try:
+            response = self._sync_retry(
+                lambda: self._get_sync_client().get(f"/ledger/manifests?{query}")
+            )
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            raise VaultConnectionError(
+                f"Failed to fetch ledger manifests: HTTP {exc.response.status_code}"
+            ) from exc
+
+        payload = response.json()
+        return [LedgerManifest.model_validate(item) for item in payload.get("manifests", [])]
+
+    async def afetch_ledger_manifests(self, limit: int = 24) -> list[LedgerManifest]:
+        """Fetch recent signed ledger manifests for the authenticated tenant (async)."""
+        query = urlencode({"limit": max(1, min(limit, 500))})
+        try:
+            response = await self._async_retry(
+                lambda: self._get_async_client().get(f"/ledger/manifests?{query}")
+            )
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            raise VaultConnectionError(
+                f"Failed to fetch ledger manifests: HTTP {exc.response.status_code}"
+            ) from exc
+
+        payload = response.json()
+        return [LedgerManifest.model_validate(item) for item in payload.get("manifests", [])]
+
+    def verify_ledger_proof(
+        self,
+        entries: list[LedgerEntry | dict[str, Any]] | None = None,
+        manifests: list[LedgerManifest | dict[str, Any]] | None = None,
+    ) -> LedgerVerificationResult:
+        """Verify ledger row receipts and manifest signatures offline using the Vault JWKS."""
+        entries = (
+            [item if isinstance(item, LedgerEntry) else LedgerEntry.model_validate(item) for item in entries]
+            if entries is not None
+            else self.fetch_ledger()
+        )
+        manifests = (
+            [item if isinstance(item, LedgerManifest) else LedgerManifest.model_validate(item) for item in manifests]
+            if manifests is not None
+            else self.fetch_ledger_manifests()
+        )
+        if self._jwks_cache is None:
+            self.fetch_jwks()
+        return self._verify_ledger_proof(entries, manifests)
+
+    async def averify_ledger_proof(
+        self,
+        entries: list[LedgerEntry | dict[str, Any]] | None = None,
+        manifests: list[LedgerManifest | dict[str, Any]] | None = None,
+    ) -> LedgerVerificationResult:
+        """Async variant of ``verify_ledger_proof``."""
+        entries = (
+            [item if isinstance(item, LedgerEntry) else LedgerEntry.model_validate(item) for item in entries]
+            if entries is not None
+            else await self.afetch_ledger()
+        )
+        manifests = (
+            [item if isinstance(item, LedgerManifest) else LedgerManifest.model_validate(item) for item in manifests]
+            if manifests is not None
+            else await self.afetch_ledger_manifests()
+        )
+        if self._jwks_cache is None:
+            await self.afetch_jwks()
+        return self._verify_ledger_proof(entries, manifests)
+
     def verify_token(self, token: str) -> dict[str, Any]:
         """Verify an A-JWT using the Vault's public key (sync).
 
@@ -374,6 +480,111 @@ class LedgixClient:
         except Exception as exc:
             raise TokenVerificationError(f"Token verification failed: {exc}") from exc
 
+    def _verify_ledger_proof(
+        self,
+        entries: list[LedgerEntry],
+        manifests: list[LedgerManifest],
+    ) -> LedgerVerificationResult:
+        if not self._jwks_cache:
+            return LedgerVerificationResult(
+                intact=False,
+                verified_entries=0,
+                verified_manifests=0,
+                latest_row_hash=None,
+                latest_manifest_hash=None,
+                error="No JWKS available from Vault",
+            )
+
+        try:
+            jwks = self._jwks_cache
+            keys = jwks.get("keys") if isinstance(jwks, dict) else None
+            if not isinstance(keys, list) or not keys:
+                raise TokenVerificationError("JWKS contains no keys")
+
+            algorithm = jwt.algorithms.get_default_algorithms()["EdDSA"]
+            key_cache: dict[str, Any] = {}
+
+            def key_for_kid(kid: str) -> Any:
+                if kid in key_cache:
+                    return key_cache[kid]
+                match = next(
+                    (
+                        item
+                        for item in keys
+                        if isinstance(item, dict) and item.get("kid") == kid
+                    ),
+                    None,
+                )
+                if match is None:
+                    raise TokenVerificationError(f"No public key found for kid {kid}")
+                public_key = jwt.algorithms.OKPAlgorithm.from_jwk(json.dumps(match))
+                key_cache[kid] = public_key
+                return public_key
+
+            previous_row_hash = "0" * 64
+            sorted_entries = sorted(entries, key=lambda item: item.seq)
+            for entry in sorted_entries:
+                if entry.prev_row_hash != previous_row_hash:
+                    raise TokenVerificationError(f"Ledger chain broken at seq {entry.seq}")
+                if not entry.receipt_payload or not entry.row_signature or not entry.signer_key_id:
+                    raise TokenVerificationError(f"Missing receipt proof data at seq {entry.seq}")
+                if not algorithm.verify(
+                    self._decode_base64url(entry.receipt_payload),
+                    key_for_kid(entry.signer_key_id),
+                    self._decode_base64url(entry.row_signature),
+                ):
+                    raise TokenVerificationError(f"Ledger receipt signature invalid at seq {entry.seq}")
+                previous_row_hash = entry.row_hash
+
+            previous_manifest_hash = "sha256:" + ("0" * 64)
+            sorted_manifests = sorted(manifests, key=lambda item: item.period_start)
+            for manifest in sorted_manifests:
+                if manifest.prev_manifest_hash != previous_manifest_hash:
+                    raise TokenVerificationError(
+                        f"Manifest chain broken at {manifest.period_start}"
+                    )
+                if not manifest.manifest_payload or not manifest.manifest_signature or not manifest.signer_key_id:
+                    raise TokenVerificationError(
+                        f"Missing manifest proof data at {manifest.period_start}"
+                    )
+                payload_bytes = self._decode_base64url(manifest.manifest_payload)
+                if not algorithm.verify(
+                    payload_bytes,
+                    key_for_kid(manifest.signer_key_id),
+                    self._decode_base64url(manifest.manifest_signature),
+                ):
+                    raise TokenVerificationError(
+                        f"Manifest signature invalid at {manifest.period_start}"
+                    )
+                payload_hash = hashlib.sha256(payload_bytes).hexdigest()
+                if f"sha256:{payload_hash}" != manifest.manifest_hash:
+                    raise TokenVerificationError(
+                        f"Manifest hash mismatch at {manifest.period_start}"
+                    )
+                previous_manifest_hash = manifest.manifest_hash
+
+            return LedgerVerificationResult(
+                intact=True,
+                verified_entries=len(sorted_entries),
+                verified_manifests=len(sorted_manifests),
+                latest_row_hash=sorted_entries[-1].row_hash if sorted_entries else None,
+                latest_manifest_hash=sorted_manifests[-1].manifest_hash if sorted_manifests else None,
+            )
+        except Exception as exc:
+            return LedgerVerificationResult(
+                intact=False,
+                verified_entries=0,
+                verified_manifests=0,
+                latest_row_hash=None,
+                latest_manifest_hash=None,
+                error=str(exc),
+            )
+
+    @staticmethod
+    def _decode_base64url(value: str) -> bytes:
+        padded = value + "=" * ((4 - len(value) % 4) % 4)
+        return base64.urlsafe_b64decode(padded.encode("ascii"))
+
     # ------------------------------------------------------------------
     # Lifecycle
     # ------------------------------------------------------------------

{ledgix_python-0.1.2 → ledgix_python-0.1.3}/src/ledgix_python/models.py

@@ -63,3 +63,57 @@ class PolicyRegistrationResponse(BaseModel):
     policy_id: str = Field(..., description="Confirmed policy ID")
     status: str = Field(default="registered", description="Registration status")
     message: str = Field(default="", description="Additional information")
+
+
+class LedgerEntry(BaseModel):
+    """Ledger entry returned by the Vault's ledger endpoints."""
+
+    seq: int
+    request_id: str
+    agent_id: str = ""
+    policy_id: str = ""
+    intent_hash: str = ""
+    tool_name: str
+    tool_args: dict[str, Any] = Field(default_factory=dict)
+    reason: str = ""
+    citations: list[dict[str, Any]] = Field(default_factory=list)
+    evidence_chunks: list[dict[str, Any]] = Field(default_factory=list)
+    confidence: float = Field(default=0.0, ge=0.0, le=1.0)
+    approved: bool
+    decided_at: str
+    prev_row_hash: str = ""
+    row_hash: str
+    signature_algorithm: str = ""
+    signer_key_id: str = ""
+    row_signature: str = ""
+    receipt_payload: str = ""
+
+
+class LedgerManifest(BaseModel):
+    """Signed chain-head manifest returned by the Vault."""
+
+    period_start: str
+    period_end_exclusive: str
+    generated_at: str
+    head_seq: int
+    head_row_hash: str
+    head_row_signature: str = ""
+    manifest_hash: str
+    prev_manifest_hash: str = ""
+    signature_algorithm: str = ""
+    signer_key_id: str = ""
+    manifest_signature: str = ""
+    manifest_payload: str = ""
+    anchor_uri: str = ""
+    anchored_at: str | None = None
+
+
+class LedgerVerificationResult(BaseModel):
+    """Result of independent offline ledger verification."""
+
+    intact: bool
+    verified_entries: int
+    verified_manifests: int
+    latest_row_hash: str | None = None
+    latest_manifest_hash: str | None = None
+    error: str | None = None

{ledgix_python-0.1.2 → ledgix_python-0.1.3}/tests/test_client.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import base64
+import hashlib
 import json
 
 import httpx
@@ -309,6 +311,186 @@ class TestTokenVerification:
         assert result.approved is True
 
 
+class TestLedgerProofVerification:
+    """Tests for ledger fetch + offline proof verification."""
+
+    @staticmethod
+    def _b64url(value: bytes) -> str:
+        return base64.urlsafe_b64encode(value).decode("ascii").rstrip("=")
+
+    @respx.mock
+    def test_fetch_ledger_and_manifests(self, client: LedgixClient):
+        respx.get("https://vault.test/ledger?limit=2").mock(
+            return_value=Response(
+                200,
+                json={
+                    "entries": [
+                        {
+                            "seq": 2,
+                            "request_id": "req-2",
+                            "tool_name": "stripe_refund",
+                            "approved": True,
+                            "decided_at": "2026-03-15T12:00:00Z",
+                            "row_hash": "b" * 64,
+                        }
+                    ]
+                },
+            )
+        )
+        respx.get("https://vault.test/ledger/manifests?limit=3").mock(
+            return_value=Response(
+                200,
+                json={
+                    "manifests": [
+                        {
+                            "period_start": "2026-03-15T12:00:00Z",
+                            "period_end_exclusive": "2026-03-15T13:00:00Z",
+                            "generated_at": "2026-03-15T13:00:00Z",
+                            "head_seq": 2,
+                            "head_row_hash": "b" * 64,
+                            "manifest_hash": "sha256:" + ("c" * 64),
+                        }
+                    ]
+                },
+            )
+        )
+
+        entries = client.fetch_ledger(limit=2)
+        manifests = client.fetch_ledger_manifests(limit=3)
+
+        assert len(entries) == 1
+        assert entries[0].request_id == "req-2"
+        assert len(manifests) == 1
+        assert manifests[0].head_seq == 2
+
+    @respx.mock
+    def test_verify_ledger_proof(
+        self,
+        client: LedgixClient,
+        ed25519_private_key,
+        jwks_response: dict,
+    ):
+        row_payload = b'{"client_id":"demo","seq":1,"row_hash":"' + ("a" * 64).encode("ascii") + b'"}'
+        row_signature = ed25519_private_key.sign(row_payload)
+        manifest_payload = (
+            b'{"period_start":"2026-03-15T12:00:00Z","head_seq":1,"head_row_hash":"'
+            + ("a" * 64).encode("ascii")
+            + b'"}'
+        )
+        manifest_signature = ed25519_private_key.sign(manifest_payload)
+        manifest_hash = "sha256:" + hashlib.sha256(manifest_payload).hexdigest()
+
+        respx.get("https://vault.test/.well-known/jwks.json").mock(
+            return_value=Response(200, json=jwks_response)
+        )
+
+        result = client.verify_ledger_proof(
+            entries=[
+                {
+                    "seq": 1,
+                    "request_id": "req-1",
+                    "agent_id": "agent-1",
+                    "policy_id": "policy-1",
+                    "tool_name": "stripe_refund",
+                    "tool_args": {"amount": 45},
+                    "reason": "ok",
+                    "approved": True,
+                    "confidence": 0.91,
+                    "decided_at": "2026-03-15T12:00:00Z",
+                    "prev_row_hash": "0" * 64,
+                    "row_hash": "a" * 64,
+                    "signer_key_id": "test-key-001",
+                    "row_signature": self._b64url(row_signature),
+                    "receipt_payload": self._b64url(row_payload),
+                }
+            ],
+            manifests=[
+                {
+                    "period_start": "2026-03-15T12:00:00Z",
+                    "period_end_exclusive": "2026-03-15T13:00:00Z",
+                    "generated_at": "2026-03-15T13:00:00Z",
+                    "head_seq": 1,
+                    "head_row_hash": "a" * 64,
+                    "head_row_signature": self._b64url(row_signature),
+                    "manifest_hash": manifest_hash,
+                    "prev_manifest_hash": "sha256:" + ("0" * 64),
+                    "signer_key_id": "test-key-001",
+                    "manifest_signature": self._b64url(manifest_signature),
+                    "manifest_payload": self._b64url(manifest_payload),
+                    "anchor_uri": "s3://ledgix-ledger/demo/2026-03-15T13:00:00Z.json",
+                    "anchored_at": "2026-03-15T13:00:30Z",
+                }
+            ],
+        )
+
+        assert result.intact is True
+        assert result.verified_entries == 1
+        assert result.verified_manifests == 1
+        assert result.latest_row_hash == "a" * 64
+
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_verify_ledger_proof_async(
+        self,
+        client: LedgixClient,
+        ed25519_private_key,
+        jwks_response: dict,
+    ):
+        row_payload = b'{"client_id":"demo","seq":2,"row_hash":"' + ("b" * 64).encode("ascii") + b'"}'
+        row_signature = ed25519_private_key.sign(row_payload)
+        manifest_payload = (
+            b'{"period_start":"2026-03-15T13:00:00Z","head_seq":2,"head_row_hash":"'
+            + ("b" * 64).encode("ascii")
+            + b'"}'
+        )
+        manifest_signature = ed25519_private_key.sign(manifest_payload)
+        manifest_hash = "sha256:" + hashlib.sha256(manifest_payload).hexdigest()
+
+        respx.get("https://vault.test/.well-known/jwks.json").mock(
+            return_value=Response(200, json=jwks_response)
+        )
+
+        result = await client.averify_ledger_proof(
+            entries=[
+                {
+                    "seq": 2,
+                    "request_id": "req-2",
+                    "agent_id": "agent-2",
+                    "policy_id": "policy-2",
+                    "tool_name": "stripe_refund",
+                    "tool_args": {"amount": 60},
+                    "reason": "ok",
+                    "approved": True,
+                    "confidence": 0.88,
+                    "decided_at": "2026-03-15T13:00:00Z",
+                    "prev_row_hash": "0" * 64,
+                    "row_hash": "b" * 64,
+                    "signer_key_id": "test-key-001",
+                    "row_signature": self._b64url(row_signature),
+                    "receipt_payload": self._b64url(row_payload),
+                }
+            ],
+            manifests=[
+                {
+                    "period_start": "2026-03-15T13:00:00Z",
+                    "period_end_exclusive": "2026-03-15T14:00:00Z",
+                    "generated_at": "2026-03-15T14:00:00Z",
+                    "head_seq": 2,
+                    "head_row_hash": "b" * 64,
+                    "head_row_signature": self._b64url(row_signature),
+                    "manifest_hash": manifest_hash,
+                    "prev_manifest_hash": "sha256:" + ("0" * 64),
+                    "signer_key_id": "test-key-001",
+                    "manifest_signature": self._b64url(manifest_signature),
+                    "manifest_payload": self._b64url(manifest_payload),
+                }
+            ],
+        )
+
+        assert result.intact is True
+        assert result.latest_manifest_hash == manifest_hash
+
+
 # ──────────────────────────────────────────────────────────────────────
 # Client lifecycle
 # ──────────────────────────────────────────────────────────────────────