chore(attestation): address SEP-2787 PR review feedback

vaaraio · vaaraio · commit 3d7af54b581c · 2026-05-26T16:43:00.000+03:00
- Rename the test helper _emit_hs256 to _emit_attestation. It builds
  envelopes for all three signing algorithms, not only HS256, so the
  HS256-only name is misleading.
- Add test_ttl_clock_skew_tolerance_window covering the verifier's
  default 30-second skew window: a 60-second TTL with iat + 75 still
  verifies, iat + 91 does not.
- Switch the optional-dependency probe from a try/import block to
  importlib.util.find_spec. Eliminates the CodeQL unused-import
  finding on rfc8785 without changing skip semantics.
- Convert the docs/sep2787-overt-mapping.md reference to COMPLIANCE.md
  into a relative markdown link.
diff --git a/docs/sep2787-overt-mapping.md b/docs/sep2787-overt-mapping.md
@@ -61,4 +61,4 @@ equivalent in the proposed shape.
 
 - OVERT 1.0 standard: <https://overt.is>
 - SEP-2787 PR: <https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2787>
-- Vaara COMPLIANCE.md "Position relative to open runtime-attestation standards"
+- [Vaara COMPLIANCE.md](../COMPLIANCE.md): section "Position relative to open runtime-attestation standards"
diff --git a/tests/test_attestation_sep2787.py b/tests/test_attestation_sep2787.py
@@ -2,30 +2,33 @@
 
 from __future__ import annotations
 
+import importlib.util
+from datetime import datetime, timezone
+
 import pytest
 
-try:
-    import rfc8785  # noqa: F401
-    from cryptography.hazmat.primitives.asymmetric import ec, rsa
-
-    from vaara.attestation.sep2787 import (
-        ArgsRef,
-        Attestation,
-        AttestationError,
-        IssuerAsserted,
-        PlannerDeclared,
-        ToolCallBinding,
-        canonical_json,
-        emit_attestation,
-        make_args_digest,
-        make_args_projection,
-        verify_attestation,
-    )
-except ImportError:
-    pytest.skip(
-        "attestation extra not installed (pip install 'vaara[attestation]')",
-        allow_module_level=True,
-    )
+for _mod in ("rfc8785", "cryptography"):
+    if importlib.util.find_spec(_mod) is None:
+        pytest.skip(
+            "attestation extra not installed (pip install 'vaara[attestation]')",
+            allow_module_level=True,
+        )
+
+from cryptography.hazmat.primitives.asymmetric import ec, rsa  # noqa: E402
+
+from vaara.attestation.sep2787 import (  # noqa: E402
+    ArgsRef,
+    Attestation,
+    AttestationError,
+    IssuerAsserted,
+    PlannerDeclared,
+    ToolCallBinding,
+    canonical_json,
+    emit_attestation,
+    make_args_digest,
+    make_args_projection,
+    verify_attestation,
+)
 
 
 HS_SECRET = b"\x42" * 32
@@ -46,7 +49,7 @@ def _planner(args=None) -> PlannerDeclared:
     )
 
 
-def _emit_hs256(**overrides) -> Attestation:
+def _emit_attestation(**overrides) -> Attestation:
     kwargs = dict(
         planner_declared=_planner(),
         iss="issuer://test",
@@ -60,7 +63,7 @@ def _emit_hs256(**overrides) -> Attestation:
 
 
 def test_hs256_emit_and_verify_round_trip():
-    env = _emit_hs256()
+    env = _emit_attestation()
     assert env.alg == "HS256"
     assert env.version == 1
     assert env.signature
@@ -69,19 +72,19 @@ def test_hs256_emit_and_verify_round_trip():
 
 def test_es256_emit_and_verify_round_trip():
     priv = ec.generate_private_key(ec.SECP256R1())
-    env = _emit_hs256(alg="ES256", signing_material=priv)
+    env = _emit_attestation(alg="ES256", signing_material=priv)
     assert len(env.signature) == 128
     assert verify_attestation(env, verifying_material=priv.public_key()) is True
 
 
 def test_rs256_emit_and_verify_round_trip():
     priv = rsa.generate_private_key(public_exponent=65537, key_size=2048)
-    env = _emit_hs256(alg="RS256", signing_material=priv)
+    env = _emit_attestation(alg="RS256", signing_material=priv)
     assert verify_attestation(env, verifying_material=priv.public_key()) is True
 
 
 def test_tampered_planner_block_fails_verification():
-    env = _emit_hs256()
+    env = _emit_attestation()
     tampered_planner = PlannerDeclared(
         intent="archive obsolete report per Q4 retention policy",
         tool_calls=env.planner_declared.tool_calls,
@@ -99,7 +102,7 @@ def test_tampered_planner_block_fails_verification():
 
 
 def test_tampered_issuer_block_fails_verification():
-    env = _emit_hs256()
+    env = _emit_attestation()
     tampered_issuer = IssuerAsserted(
         iss=env.issuer_asserted.iss,
         sub="agent:HIJACKED",
@@ -125,7 +128,7 @@ def test_args_digest_round_trip_three_shapes():
     r = ArgsRef(ref="ipfs://Qm...", digest="sha256:" + "0" * 64)
     p = make_args_projection({"redacted_user_id": "u-001"})
     for args in (d, r, p):
-        env = _emit_hs256(planner_declared=_planner(args=args))
+        env = _emit_attestation(planner_declared=_planner(args=args))
         assert verify_attestation(env, verifying_material=HS_SECRET)
         assert env.payload_derived[0].kind == args.kind
 
@@ -154,34 +157,50 @@ def test_make_args_digest_is_deterministic():
 
 
 def test_ttl_expired_returns_false():
-    env = _emit_hs256(exp_seconds=60)
+    env = _emit_attestation(exp_seconds=60)
     far_future = 9_999_999_999.0
     assert verify_attestation(
         env, verifying_material=HS_SECRET, now=far_future,
     ) is False
 
 
+def test_ttl_clock_skew_tolerance_window():
+    iat = "2026-05-26T12:00:00Z"
+    iat_epoch = datetime(
+        2026, 5, 26, 12, 0, 0, tzinfo=timezone.utc,
+    ).timestamp()
+    env = _emit_attestation(exp_seconds=60, iat=iat)
+    # default clock_skew_seconds=30: iat + 60 + 15 still inside window
+    assert verify_attestation(
+        env, verifying_material=HS_SECRET, now=iat_epoch + 60 + 15,
+    ) is True
+    # iat + 60 + 31 is past the default skew window
+    assert verify_attestation(
+        env, verifying_material=HS_SECRET, now=iat_epoch + 60 + 31,
+    ) is False
+
+
 def test_emit_rejects_empty_intent():
     bad = PlannerDeclared(
         intent="   ",
         tool_calls=_planner().tool_calls,
     )
     with pytest.raises(AttestationError, match="intent"):
-        _emit_hs256(planner_declared=bad)
+        _emit_attestation(planner_declared=bad)
 
 
 def test_emit_rejects_unsupported_alg():
     with pytest.raises(AttestationError, match="unsupported alg"):
-        _emit_hs256(alg="HS512")
+        _emit_attestation(alg="HS512")
 
 
 def test_hs256_rejects_non_bytes_secret():
     with pytest.raises(AttestationError, match="bytes shared_secret"):
-        _emit_hs256(signing_material="not-bytes")
+        _emit_attestation(signing_material="not-bytes")
 
 
 def test_to_dict_round_trip_shape():
-    env = _emit_hs256()
+    env = _emit_attestation()
     d = env.to_dict()
     assert set(d) == {
         "version", "alg", "planner_declared",
@@ -192,6 +211,6 @@ def test_to_dict_round_trip_shape():
 
 
 def test_cross_alg_verification_fails():
-    env = _emit_hs256()
+    env = _emit_attestation()
     priv = ec.generate_private_key(ec.SECP256R1())
     assert verify_attestation(env, verifying_material=priv.public_key()) is False
