🎨 feat(signatures): wire SignatureManager and API into client

Author: Kakudou

pyoaev/apis/signature.py

@@ -92,7 +92,7 @@ def send_signatures(
         if len(serialized) <= self._max_payload_size:
             self._send_with_retry(inject_id, payload)
         else:
-            self._send_chunked(inject_id, payload["signatures"], phase=phase)
+            self._send_chunked(inject_id, payload["expectation_signature"], phase=phase)
 
     def _build_callback_payload(
         self,
@@ -119,7 +119,7 @@ def _build_callback_payload(
         try:
             envelope = SignatureCallbackPayload.model_validate(
                 {
-                    "signatures": signatures,
+                    "expectation_signature": signatures,
                     "phase": phase,
                     "chunk_index": chunk_index,
                     "total_chunks": total_chunks,
@@ -216,7 +216,7 @@ def _send_chunked(
             candidate = current_chunk + [target]
             size = len(
                 json.dumps(
-                    {"signatures": {"targets": candidate}},
+                    {"expectation_signature": {"targets": candidate}},
                     separators=(",", ":"),
                 ).encode()
             )
@@ -237,7 +237,7 @@ def _send_chunked(
             current_chunk = [target]
             solo_size = len(
                 json.dumps(
-                    {"signatures": {"targets": [target]}},
+                    {"expectation_signature": {"targets": [target]}},
                     separators=(",", ":"),
                 ).encode()
             )
@@ -280,7 +280,9 @@ def callback(
         result = self.openaev.http_post(path, post_data=data, **kwargs)
         return result
 
-    def _send_with_retry(self, inject_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+    def _send_with_retry(
+        self, inject_id: str, payload: dict[str, Any]
+    ) -> dict[str, Any]:
         """Retry callback() with exponential backoff on 5xx, immediate raise on 4xx.
 
         Args:

pyoaev/client.py

@@ -75,6 +75,7 @@ def __init__(
         self.payload = apis.PayloadManager(self)
         self.security_platform = apis.SecurityPlatformManager(self)
         self.inject_expectation_trace = apis.InjectExpectationTraceManager(self)
+        self.signature = apis.SignatureApiManager(self)
         self.tag = apis.TagManager(self)
 
     @staticmethod

pyoaev/signatures/__init__.py

@@ -0,0 +1,22 @@
+from pyoaev.signatures.models import (
+    ExpectationSignatureGroup,
+    SignatureCallbackPayload,
+    SignaturePayload,
+    SignatureTarget,
+    SignatureValue,
+    TargetSignatures,
+)
+from pyoaev.signatures.signature_manager import SignatureManager
+from pyoaev.signatures.types import MatchTypes, SignatureTypes
+
+__all__ = [
+    "ExpectationSignatureGroup",
+    "MatchTypes",
+    "SignatureCallbackPayload",
+    "SignatureManager",
+    "SignaturePayload",
+    "SignatureTarget",
+    "SignatureTypes",
+    "SignatureValue",
+    "TargetSignatures",
+]

pyoaev/signatures/models.py

@@ -55,7 +55,7 @@ class SignatureCallbackPayload(BaseModel):
 
     model_config = ConfigDict(populate_by_name=True, extra="forbid")
 
-    signatures: SignaturePayload
+    expectation_signature: SignaturePayload
     phase: str | None = None
     chunk_index: int | None = None
     total_chunks: int | None = None

pyoaev/signatures/signature_manager.py

@@ -11,8 +11,13 @@
 
 from pyoaev.exceptions import OpenAEVError
 from pyoaev.signatures.models import (
+    ExpectationSignatureGroup,
     PostExecutionSignature,
     PreExecutionSignature,
+    SignaturePayload,
+    SignatureTarget,
+    SignatureValue,
+    TargetSignatures,
     ToolOutput,
 )
 
@@ -211,6 +216,49 @@ def _merge_post(
 
         return merged
 
+    def build_payload(
+        self,
+        post_signatures: dict[str, Any] | list[dict[str, Any]],
+        targets_meta: dict[str, str] | list[dict[str, str]],
+        expectation_type: str = "DETECTION",
+    ) -> dict[str, Any]:
+        """Build the nested wire payload from flat post-execution signatures.
+
+        Bridges the gap between compile_post_execution_signatures output (flat dicts)
+        and send_signatures input (nested wire format).
+
+        Args:
+            post_signatures: A single post-execution dict or a list (multi-target).
+            targets_meta: Target metadata dict(s) with keys like agent, asset, asset_group.
+            expectation_type: The expectation type label (e.g. 'DETECTION', 'PREVENTION').
+
+        Returns:
+            A payload dict ready for send_signatures.
+        """
+        if isinstance(post_signatures, dict):
+            post_signatures = [post_signatures]
+        if isinstance(targets_meta, dict):
+            targets_meta = [targets_meta] * len(post_signatures)
+
+        targets = []
+        for sig, meta in zip(post_signatures, targets_meta):
+            values = [
+                SignatureValue(signature_type=k, signature_value=str(v))
+                for k, v in sig.items()
+            ]
+            targets.append(
+                TargetSignatures(
+                    signature_target=SignatureTarget(**meta),
+                    signature_values=[
+                        ExpectationSignatureGroup(
+                            expectation_type=expectation_type, values=values
+                        )
+                    ],
+                )
+            )
+
+        return SignaturePayload(targets=targets).model_dump()
+
     def send_signatures(
         self,
         inject_id: str,

test/signatures/test_signature_manager_transmission.py

@@ -208,11 +208,6 @@ def compiled_payload_single_target(
     "a compiled payload whose serialised size exceeds MAX_PAYLOAD_SIZE by at least a factor of 2"
 )
 def compiled_large_payload(context):
-    # Each target serialises to ~450 bytes with the canonical signature_target
-    # shape (`agent`/`asset`/`asset_group`) and the 140-char hostname below.
-    # Budget chosen so a single target fits but two don't, producing 6 chunks
-    # of one target each. Total payload (~2.7 KiB) exceeds max_payload_size
-    # (700 B) by ~4x, satisfying the feature's "at least factor of 2" wording.
     context["signature_manager"] = SignatureManager(
         context["mock_client"],
         logger=context["logger"],
@@ -321,8 +316,6 @@ def compiled_payload_grouped_by_expectation(
     expectation_a,
     expectation_b,
 ):
-    # Feed FLAT form (mixed expectation_types in a single signature_values list).
-    # SignatureManager must regroup it into the canonical wire schema.
     context["signatures"] = {
         "targets": [
             {
@@ -395,7 +388,7 @@ def assert_post_request_sent_to_callback(context, inject_id):
 @then("the POST request body contains signatures.targets as a list")
 def assert_targets_is_list(context):
     body = context["captured_calls"][-1]["post_data"]
-    assert isinstance(body["signatures"]["targets"], list)
+    assert isinstance(body["expectation_signature"]["targets"], list)
 
 
 @then(
@@ -405,7 +398,7 @@ def assert_targets_is_list(context):
 )
 def assert_expectation_type(context, expected_value):
     body = context["captured_calls"][-1]["post_data"]
-    assert body["signatures"]["targets"][0]["signature_values"][0][
+    assert body["expectation_signature"]["targets"][0]["signature_values"][0][
         "expectation_type"
     ] == (expected_value)
 
@@ -418,7 +411,7 @@ def assert_expectation_type(context, expected_value):
 def assert_signature_type(context, expected_value):
     body = context["captured_calls"][-1]["post_data"]
     assert (
-        body["signatures"]["targets"][0]["signature_values"][0]["values"][0][
+        body["expectation_signature"]["targets"][0]["signature_values"][0]["values"][0][
             "signature_type"
         ]
         == expected_value
@@ -433,7 +426,7 @@ def assert_signature_type(context, expected_value):
 def assert_signature_value(context, expected_value):
     body = context["captured_calls"][-1]["post_data"]
     assert (
-        body["signatures"]["targets"][0]["signature_values"][0]["values"][0][
+        body["expectation_signature"]["targets"][0]["signature_values"][0]["values"][0][
             "signature_value"
         ]
         == expected_value
@@ -443,7 +436,7 @@ def assert_signature_value(context, expected_value):
 @then("signatures.targets[0] contains a signature_target key")
 def assert_signature_target_key(context):
     body = context["captured_calls"][-1]["post_data"]
-    assert "signature_target" in body["signatures"]["targets"][0]
+    assert "signature_target" in body["expectation_signature"]["targets"][0]
 
 
 @then(
@@ -484,7 +477,7 @@ def assert_total_chunks_present(context):
     'each POST request body contains only "signatures", "chunk_index" and "total_chunks" at the top level'
 )
 def assert_chunked_envelope_is_strict(context):
-    expected_keys = {"signatures", "chunk_index", "total_chunks", "phase"}
+    expected_keys = {"expectation_signature", "chunk_index", "total_chunks", "phase"}
     for call_item in context["captured_calls"]:
         post_data = call_item["post_data"]
         assert set(post_data.keys()) == expected_keys, (
@@ -499,13 +492,12 @@ def assert_targets_union_matches_original(context):
     sent_targets = [
         target
         for call_item in context["captured_calls"]
-        for target in call_item["post_data"]["signatures"]["targets"]
+        for target in call_item["post_data"]["expectation_signature"]["targets"]
     ]
     assert len(sent_targets) == len(original_targets), (
         f"Expected {len(original_targets)} targets across all chunks, "
         f"got {len(sent_targets)}"
     )
-    # signature_target identifiers must match one-to-one (order-preserved).
     for original, sent in zip(original_targets, sent_targets):
         assert sent["signature_target"] == original["signature_target"]
 
@@ -622,7 +614,7 @@ def assert_no_exception_from_resolve_container_ip(context):
 )
 def assert_signature_values_nested_by_expectation_type(context):
     body = context["captured_calls"][-1]["post_data"]
-    entries = body["signatures"]["targets"][0]["signature_values"]
+    entries = body["expectation_signature"]["targets"][0]["signature_values"]
     expectation_types = {entry["expectation_type"] for entry in entries}
     assert expectation_types == {"DETECTION", "PREVENTION"}
 
@@ -632,14 +624,12 @@ def assert_signature_values_nested_by_expectation_type(context):
 )
 def assert_detection_values_grouped_correctly(context):
     body = context["captured_calls"][-1]["post_data"]
-    entries = body["signatures"]["targets"][0]["signature_values"]
+    entries = body["expectation_signature"]["targets"][0]["signature_values"]
     detection_entry = next(
         entry for entry in entries if entry["expectation_type"] == "DETECTION"
     )
-    # Two DETECTION items were fed in flat form; both must be grouped here.
     detection_values = {value["signature_value"] for value in detection_entry["values"]}
     assert detection_values == {"203.0.113.5", "host-a.internal"}
-    # No PREVENTION value should have leaked into the DETECTION group.
     assert "198.51.100.10" not in detection_values
 
 
@@ -648,14 +638,13 @@ def assert_detection_values_grouped_correctly(context):
 )
 def assert_prevention_values_grouped_correctly(context):
     body = context["captured_calls"][-1]["post_data"]
-    entries = body["signatures"]["targets"][0]["signature_values"]
+    entries = body["expectation_signature"]["targets"][0]["signature_values"]
     prevention_entry = next(
         entry for entry in entries if entry["expectation_type"] == "PREVENTION"
     )
     prevention_values = {
         value["signature_value"] for value in prevention_entry["values"]
     }
     assert prevention_values == {"198.51.100.10"}
-    # No DETECTION value should have leaked into the PREVENTION group.
     assert "203.0.113.5" not in prevention_values
     assert "host-a.internal" not in prevention_values