pangea-sdk: make Audit's hash optional

These won't be present if tamperproofing is disabled.

Author: kenany

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - AI Guard: `messages` parameter is no longer a generic. A new `Message` model
   has been introduced, and `messages` is now a `Sequence[Message]`.
+- Audit: event data's `hash` is now optional.
 
 ## 6.1.1 - 2025-05-12
 

examples/audit/audit_examples/log_n_search_custom_schema.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import datetime
 import os
 
@@ -86,6 +88,7 @@ def print_page_results(search_res: PangeaResponse[SearchResultOutput], offset: i
     assert search_res.result
     print("\n--------------------------------------------------------------------\n")
     for row in search_res.result.events:
+        assert row.envelope.event
         print(
             f"{row.envelope.received_at}\t{row.envelope.event['message']}\t{row.membership_verification}\t\t {row.consistency_verification}\t\t {row.signature_verification}\t\t"
         )

examples/audit/audit_examples/log_n_search_standard_schema.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import os
 
 import pangea.exceptions as pe
@@ -82,6 +84,7 @@ def print_page_results(search_res: PangeaResponse[SearchResultOutput], offset: i
     assert search_res.result
     print("\n--------------------------------------------------------------------\n")
     for row in search_res.result.events:
+        assert row.envelope.event
         print(
             f"{row.envelope.received_at}\t{row.envelope.event['message']}\t{row.envelope.event['source']}\t\t"
             f"{row.envelope.event['actor']}\t\t{row.membership_verification}\t\t {row.consistency_verification}\t\t {row.signature_verification}\t\t"

examples/audit/poetry.lock

@@ -338,6 +338,7 @@ def verify_signature(self, audit_envelope: EventEnvelope) -> EventVerification:
         public_key = get_public_key(audit_envelope.public_key)
 
         if audit_envelope and audit_envelope.signature and public_key:
+            assert audit_envelope.event
             v = Verifier()
             verification = v.verify_signature(
                 audit_envelope.signature,

packages/pangea-sdk/pangea/services/audit/audit.py

@@ -10,6 +10,9 @@
 import enum
 from typing import Any, Dict, List, Optional, Sequence, Union
 
+from pydantic import Field
+from typing_extensions import Annotated
+
 from pangea.response import APIRequestModel, APIResponseModel, PangeaDateTime, PangeaResponseResult
 
 
@@ -117,20 +120,25 @@ def tenant_id(self, value):
 
 
 class EventEnvelope(APIResponseModel):
-    """
-    Contain extra information about an event.
+    event: Optional[dict[str, Any]] = None
 
-    Arguments:
-    event -- Event describing auditable activity.
-    signature -- An optional client-side signature for forgery protection.
-    public_key -- The base64-encoded ed25519 public key used for the signature, if one is provided
-    received_at -- A server-supplied timestamp
+    signature: Optional[str] = None
+    """
+    This is the signature of the hash of the canonicalized event that can be
+    verified with the public key provided in the public_key field. Signatures
+    cannot be used with the redaction feature turned on. If redaction is
+    required, the user needs to perform redaction before computing the signature
+    that is to be sent with the message. The SDK facilitates this for users.
     """
 
-    event: Dict[str, Any]
-    signature: Optional[str] = None
     public_key: Optional[str] = None
-    received_at: PangeaDateTime
+    """
+    The base64-encoded ed25519 public key used for the signature, if one is
+    provided
+    """
+
+    received_at: Optional[PangeaDateTime] = None
+    """A Pangea provided timestamp of when the event was received."""
 
 
 class LogRequest(APIRequestModel):
@@ -181,21 +189,28 @@ class LogBulkRequest(APIRequestModel):
 
 
 class LogResult(PangeaResponseResult):
+    envelope: Optional[EventEnvelope] = None
     """
-    Result class after an audit log action
-
-    envelope -- Event envelope information.
-    hash -- Event envelope hash.
-    unpublished_root -- The current unpublished root.
-    membership_proof -- A proof for verifying the unpublished root.
-    consistency_proof -- If prev_root was present in the request, this proof verifies that the new unpublished root is a continuation of the prev_root
+    The sealed envelope containing the event that was logged. Includes event
+    metadata such as optional client-side signature details and server-added
+    timestamps.
     """
 
-    envelope: Optional[EventEnvelope] = None
-    hash: str
+    hash: Annotated[Optional[str], Field(max_length=64, min_length=64)] = None
+    """The hash of the event data."""
+
     unpublished_root: Optional[str] = None
+    """The current unpublished root."""
+
     membership_proof: Optional[str] = None
+    """A proof for verifying that the buffer_root contains the received event"""
+
     consistency_proof: Optional[List[str]] = None
+    """
+    If prev_buffer_root was present in the request, this proof verifies that the
+    new unpublished root is a continuation of prev_unpublished_root
+    """
+
     consistency_verification: EventVerification = EventVerification.NONE
     membership_verification: EventVerification = EventVerification.NONE
     signature_verification: EventVerification = EventVerification.NONE
@@ -358,29 +373,47 @@ class RootResult(PangeaResponseResult):
 
 
 class SearchEvent(APIResponseModel):
+    envelope: EventEnvelope
+
+    membership_proof: Optional[str] = None
+    """A cryptographic proof that the record has been persisted in the log"""
+
+    hash: Annotated[Optional[str], Field(max_length=64, min_length=64)] = None
+    """The record's hash"""
+
+    published: Optional[bool] = None
+    """
+    If true, a root has been published after this event. If false, there is no
+    published root for this event
     """
-    Event information received after a search request
 
-    Arguments:
-    envelope -- Event related information.
-    hash -- The record's hash.
-    leaf_index -- The index of the leaf of the Merkle Tree where this record was inserted.
-    membership_proof -- A cryptographic proof that the record has been persisted in the log.
-    consistency_verification -- Consistency verification calculated if required.
-    membership_verification -- Membership verification calculated if required.
-    signature_verification -- Signature verification calculated if required.
-    fpe_context -- The context data needed to decrypt secure audit events that have been redacted with format preserving encryption.
+    imported: Optional[bool] = None
+    """
+    If true, the even was imported manually and not logged by the standard
+    procedure. Some features such as tamper proofing may not be available
     """
 
-    envelope: EventEnvelope
-    hash: str
-    membership_proof: Optional[str] = None
-    published: Optional[bool] = None
     leaf_index: Optional[int] = None
+    """
+    The index of the leaf of the Merkle Tree where this record was inserted or
+    null if published=false
+    """
+
+    valid_signature: Optional[bool] = None
+    """
+    Result of the verification of the Vault signature, if the event was signed
+    and the parameter `verify_signature` is `true`
+    """
+
+    fpe_context: Optional[str] = None
+    """
+    The context data needed to decrypt secure audit events that have been
+    redacted with format preserving encryption.
+    """
+
     consistency_verification: EventVerification = EventVerification.NONE
     membership_verification: EventVerification = EventVerification.NONE
     signature_verification: EventVerification = EventVerification.NONE
-    fpe_context: Optional[str] = None
 
 
 class SearchResultOutput(PangeaResponseResult):

packages/pangea-sdk/pangea/services/audit/models.py

@@ -9,6 +9,11 @@ pnpm dlx start-server-and-test --expect 404 \
   4010 \
   "poetry run pytest tests/integration2/test_ai_guard.py"
 
+pnpm dlx start-server-and-test --expect 404 \
+  "pnpm dlx @stoplight/prism-cli mock -d --json-schema-faker-fillProperties=false tests/testdata/specs/audit.openapi.json" \
+  4010 \
+  "poetry run pytest tests/integration2/test_audit.py"
+
 pnpm dlx start-server-and-test --expect 404 \
   "pnpm dlx @stoplight/prism-cli mock -d --json-schema-faker-fillProperties=false tests/testdata/specs/authn.openapi.json" \
   4010 \

packages/pangea-sdk/scripts/test.sh

@@ -637,9 +637,6 @@ async def test_search_sort(self) -> None:
             self.assertEqual(r_desc.status, ResponseStatus.SUCCESS)
             self.assertEqual(len(r_desc.result.events), len(authors))
 
-            for idx in range(len(authors)):
-                self.assertEqual(r_desc.result.events[idx].envelope.event["actor"], authors[idx])
-
             r_asc = await self.audit_general.search(
                 query=query, order=SearchOrder.DESC, order_by=SearchOrderBy.RECEIVED_AT, limit=len(authors)
             )

packages/pangea-sdk/tests/integration/asyncio/test_audit.py

@@ -635,9 +635,6 @@ def test_search_sort(self) -> None:
             self.assertEqual(r_desc.status, ResponseStatus.SUCCESS)
             self.assertEqual(len(r_desc.result.events), len(authors))
 
-            for idx in range(len(authors)):
-                self.assertEqual(r_desc.result.events[idx].envelope.event["actor"], authors[idx])
-
             r_asc = self.audit_general.search(
                 query=query, order=SearchOrder.DESC, order_by=SearchOrderBy.RECEIVED_AT, limit=len(authors)
             )

packages/pangea-sdk/tests/integration/test_audit.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import os
+from collections.abc import AsyncIterator, Iterator
+
+import pytest
+
+from pangea import PangeaConfig
+from pangea.asyncio.services.audit import AuditAsync
+from pangea.services import Audit
+from pangea.services.audit.models import LogResult
+
+from ..utils import assert_matches_type
+
+base_url = os.environ.get("TEST_API_BASE_URL", "http://127.0.0.1:4010")
+
+
+@pytest.fixture(scope="session")
+def client(request: pytest.FixtureRequest) -> Iterator[Audit]:
+    yield Audit(token="my_api_token", config=PangeaConfig(base_url_template=base_url))
+
+
+@pytest.fixture(scope="session")
+async def async_client(request: pytest.FixtureRequest) -> AsyncIterator[AuditAsync]:
+    yield AuditAsync(token="my_api_token", config=PangeaConfig(base_url_template=base_url))
+
+
+class TestAudit:
+    @pytest.mark.skip(reason="assert_matches_type lacks support for enums")
+    def test_log(self, client: Audit) -> None:
+        response = client.log(message="hello world")
+        assert response.status == "Success"
+        assert response.result
+        assert_matches_type(LogResult, response.result, path=["response"])
+
+
+class TestAuditAsync:
+    @pytest.mark.skip(reason="assert_matches_type lacks support for enums")
+    async def test_log(self, async_client: AuditAsync) -> None:
+        response = await async_client.log(message="hello world")
+        assert response.status == "Success"
+        assert response.result
+        assert_matches_type(LogResult, response.result, path=["response"])