aevum-spiffe 0.4.0__tar.gz

aevum_spiffe-0.4.0/.gitignore

@@ -0,0 +1,49 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.venv/
+*.egg-info/
+
+# Build
+dist/
+build/
+site/
+
+# Tools
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.hypothesis/
+.cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Verify scripts (run locally, never commit)
+verify_*.py
+scripts/verify_*.py
+
+# Aevum development — never commit (Phase 0+)
+aevum_principles.key
+signed_principles_draft.yaml
+tools/sign_principles.py
+
+# Private keys — never commit
+*.key
+*.pem
+
+# OpenSSF Scorecard output (Phase 0+)
+results.sarif
+verify_phase3.py
+verify_phase7.py
+verify_phase8.py
+verify_phase*.py

aevum_spiffe-0.4.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: aevum-spiffe
+Version: 0.4.0
+Summary: Aevum — SPIFFE/SPIRE cryptographic agent identity complication.
+Project-URL: Homepage, https://aevum.build
+Project-URL: Repository, https://github.com/aevum-labs/aevum
+License: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aevum-core
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Provides-Extra: spiffe
+Requires-Dist: spiffe>=0.2.3; extra == 'spiffe'
+Description-Content-Type: text/markdown
+
+# aevum-spiffe
+
+SPIFFE/SPIRE agent identity complication for Aevum.
+
+Provides cryptographically-attested agent identity via JWT-SVIDs from the
+SPIFFE Workload API. When `on_approved()` is called, emits a `spiffe.attested`
+AuditEvent recording the SPIFFE ID and SVID metadata in the sigchain.
+
+Requires SPIRE or a compatible SPIFFE Workload API (Vault SPIFFE secrets
+engine, KUDO, etc.) to be running at attestation time.
+
+```bash
+pip install aevum-spiffe[spiffe]
+```
+
+```python
+from aevum.core import Engine
+from aevum.spiffe import SpiffeComplication
+
+engine = Engine()
+comp = SpiffeComplication(
+    socket_path="unix:///run/spire/sockets/agent.sock",  # optional
+    audience=["aevum"],                                   # optional
+)
+engine.install_complication(comp)
+engine.approve_complication("aevum-spiffe")
+comp.on_approved(engine)   # emits spiffe.attested into the sigchain
+```
+
+The chain now contains a signed `spiffe.attested` event:
+
+```json
+{
+  "event_type": "spiffe.attested",
+  "actor": "aevum-spiffe",
+  "payload": {
+    "spiffe_id": "spiffe://example.org/billing-agent",
+    "trust_domain": "example.org",
+    "audience": ["aevum"],
+    "svid_type": "jwt",
+    "source": "workload-api",
+    "socket": "unix:///run/spire/sockets/agent.sock",
+    "expiry": "2026-05-06T15:00:00+00:00"
+  }
+}
+```
+
+## Lifecycle note
+
+The Aevum Engine does not call lifecycle hooks automatically at approval time.
+After `engine.approve_complication("aevum-spiffe")`, callers must invoke
+`comp.on_approved(engine)` explicitly to trigger attestation. This is the
+correct pattern for all complications that need to act at approval time.
+
+## Downstream use
+
+Other complications can read the attested SPIFFE ID:
+
+```python
+spiffe_comp = engine.get_active_complication_by_capability("spiffe-identity")
+spiffe_id = spiffe_comp.get_actor_spiffe_id() if spiffe_comp else None
+payload = {"actor_spiffe_id": spiffe_id, ...}
+```
+
+## Without SPIRE
+
+If the SPIFFE socket is unavailable or py-spiffe is not installed,
+`on_approved()` logs a warning and continues without attestation.
+Engine startup is never blocked.
+
+## Trust boundary
+
+The SPIFFE ID in the `spiffe.attested` event is cryptographically attested
+by SPIRE's attestation plugins. It is NOT caller-asserted (unlike the `actor`
+field). An auditor can verify the attestation by checking the SVID's parent
+trust chain against the SPIFFE trust bundle.
+
+The JWT token itself is NOT stored in the AuditEvent — it expires (typically
+1 hour) and is large. Only the SPIFFE ID string and metadata are recorded.
+
+## See also
+
+- [ADR-006: SPIFFE integration](../../docs/adrs/adr-006-spiffe-integration.md)
+- [py-spiffe](https://github.com/HewlettPackard/py-spiffe)
+- [SPIFFE specification](https://spiffe.io)

aevum_spiffe-0.4.0/README.md

@@ -0,0 +1,85 @@
+# aevum-spiffe
+
+SPIFFE/SPIRE agent identity complication for Aevum.
+
+Provides cryptographically-attested agent identity via JWT-SVIDs from the
+SPIFFE Workload API. When `on_approved()` is called, emits a `spiffe.attested`
+AuditEvent recording the SPIFFE ID and SVID metadata in the sigchain.
+
+Requires SPIRE or a compatible SPIFFE Workload API (Vault SPIFFE secrets
+engine, KUDO, etc.) to be running at attestation time.
+
+```bash
+pip install aevum-spiffe[spiffe]
+```
+
+```python
+from aevum.core import Engine
+from aevum.spiffe import SpiffeComplication
+
+engine = Engine()
+comp = SpiffeComplication(
+    socket_path="unix:///run/spire/sockets/agent.sock",  # optional
+    audience=["aevum"],                                   # optional
+)
+engine.install_complication(comp)
+engine.approve_complication("aevum-spiffe")
+comp.on_approved(engine)   # emits spiffe.attested into the sigchain
+```
+
+The chain now contains a signed `spiffe.attested` event:
+
+```json
+{
+  "event_type": "spiffe.attested",
+  "actor": "aevum-spiffe",
+  "payload": {
+    "spiffe_id": "spiffe://example.org/billing-agent",
+    "trust_domain": "example.org",
+    "audience": ["aevum"],
+    "svid_type": "jwt",
+    "source": "workload-api",
+    "socket": "unix:///run/spire/sockets/agent.sock",
+    "expiry": "2026-05-06T15:00:00+00:00"
+  }
+}
+```
+
+## Lifecycle note
+
+The Aevum Engine does not call lifecycle hooks automatically at approval time.
+After `engine.approve_complication("aevum-spiffe")`, callers must invoke
+`comp.on_approved(engine)` explicitly to trigger attestation. This is the
+correct pattern for all complications that need to act at approval time.
+
+## Downstream use
+
+Other complications can read the attested SPIFFE ID:
+
+```python
+spiffe_comp = engine.get_active_complication_by_capability("spiffe-identity")
+spiffe_id = spiffe_comp.get_actor_spiffe_id() if spiffe_comp else None
+payload = {"actor_spiffe_id": spiffe_id, ...}
+```
+
+## Without SPIRE
+
+If the SPIFFE socket is unavailable or py-spiffe is not installed,
+`on_approved()` logs a warning and continues without attestation.
+Engine startup is never blocked.
+
+## Trust boundary
+
+The SPIFFE ID in the `spiffe.attested` event is cryptographically attested
+by SPIRE's attestation plugins. It is NOT caller-asserted (unlike the `actor`
+field). An auditor can verify the attestation by checking the SVID's parent
+trust chain against the SPIFFE trust bundle.
+
+The JWT token itself is NOT stored in the AuditEvent — it expires (typically
+1 hour) and is large. Only the SPIFFE ID string and metadata are recorded.
+
+## See also
+
+- [ADR-006: SPIFFE integration](../../docs/adrs/adr-006-spiffe-integration.md)
+- [py-spiffe](https://github.com/HewlettPackard/py-spiffe)
+- [SPIFFE specification](https://spiffe.io)

aevum_spiffe-0.4.0/pyproject.toml

@@ -0,0 +1,61 @@
+[project]
+name = "aevum-spiffe"
+version = "0.4.0"
+description = "Aevum — SPIFFE/SPIRE cryptographic agent identity complication."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.11",
+    "Typing :: Typed",
+]
+dependencies = [
+    "aevum-core",
+]
+
+[project.optional-dependencies]
+spiffe = ["spiffe>=0.2.3"]
+dev = [
+    "pytest>=8.0",
+    "mypy>=1.10",
+    "ruff>=0.9",
+]
+
+[project.entry-points."aevum.complications"]
+spiffe = "aevum.spiffe.complication:SpiffeComplication"
+
+[project.urls]
+Homepage = "https://aevum.build"
+Repository = "https://github.com/aevum-labs/aevum"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aevum"]
+
+[tool.uv.sources]
+aevum-core = { workspace = true }
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--tb=short"
+pythonpath = ["src", "../../packages/aevum-core/src"]
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+mypy_path = "src"
+explicit_package_bases = true
+ignore_missing_imports = true
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "UP", "B", "SIM", "I", "ANN"]
+ignore = ["ANN401"]

aevum_spiffe-0.4.0/src/aevum/spiffe/__init__.py

@@ -0,0 +1,23 @@
+"""
+aevum.spiffe — SPIFFE/SPIRE cryptographic agent identity complication.
+
+Provides cryptographically-attested agent identity via SPIFFE JWT-SVIDs.
+Emits a spiffe.attested AuditEvent when on_approved() is called, recording
+the SPIFFE ID and SVID metadata (not the JWT itself).
+
+Requires: pip install aevum-spiffe[spiffe]  (installs py-spiffe 0.2.3+)
+
+Without py-spiffe installed: importing this module succeeds but
+SpiffeComplication.on_approved() will warn and skip gracefully.
+
+Usage:
+    from aevum.spiffe import SpiffeComplication
+    engine.install_complication(comp)
+    engine.approve_complication("aevum-spiffe")
+    comp.on_approved(engine)  # emit spiffe.attested event
+"""
+
+from aevum.spiffe.complication import SpiffeComplication
+
+__version__ = "0.4.0"
+__all__ = ["SpiffeComplication"]

aevum_spiffe-0.4.0/src/aevum/spiffe/complication.py

@@ -0,0 +1,184 @@
+"""
+SpiffeComplication — SPIFFE agent identity via JWT-SVIDs.
+
+ADR-006 implementation. See docs/adrs/adr-006-spiffe-integration.md.
+
+Lifecycle note: the Engine has no on_approved callback mechanism. Callers
+must invoke comp.on_approved(engine) explicitly after
+engine.approve_complication("aevum-spiffe") to trigger attestation.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from typing import Any
+
+log = logging.getLogger(__name__)
+
+_DEFAULT_SOCKET = "unix:///tmp/spire-agent/public/api.sock"
+_DEFAULT_AUDIENCE = ["aevum"]
+
+# Module-level sentinel. Not a top-level import — py-spiffe is imported lazily
+# inside _fetch_svid(). This name exists so tests can patch
+# aevum.spiffe.complication.WorkloadApiClient without triggering a real import.
+WorkloadApiClient: Any = None
+
+
+class SpiffeComplication:
+    """
+    SPIFFE/SPIRE agent identity complication.
+
+    When on_approved() is called, fetches a JWT-SVID from the SPIFFE Workload
+    API and emits a spiffe.attested AuditEvent recording the SPIFFE ID and
+    metadata. The JWT token itself is never stored.
+
+    Failure modes (all non-fatal):
+    - py-spiffe not installed: warn and skip
+    - SPIFFE socket unavailable: warn and skip
+    - Invalid SVID: warn and skip
+
+    The complication never prevents Engine startup or operation.
+
+    Engine integration (no automatic lifecycle hook):
+        engine.install_complication(comp)
+        engine.approve_complication("aevum-spiffe")
+        comp.on_approved(engine)  # caller must invoke this explicitly
+    """
+
+    name: str = "aevum-spiffe"
+    version: str = "0.4.0"
+    capabilities: list[str] = ["spiffe-identity"]
+
+    def __init__(
+        self,
+        socket_path: str | None = None,
+        audience: list[str] | None = None,
+    ) -> None:
+        self._socket = socket_path or os.environ.get(
+            "AEVUM_SPIFFE_SOCKET", _DEFAULT_SOCKET
+        )
+        self._audience = audience or list(_DEFAULT_AUDIENCE)
+        self._spiffe_id: str | None = None
+        self._trust_domain: str | None = None
+        self._attested: bool = False
+
+    def manifest(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "version": self.version,
+            "description": "SPIFFE/SPIRE cryptographic agent identity via JWT-SVIDs",
+            "capabilities": list(self.capabilities),
+            "classification_max": 0,
+            "functions": ["commit"],
+            "auth": {"scopes_required": [], "public_key": None},
+            "schema_version": "1.0",
+        }
+
+    # ── Lifecycle ─────────────────────────────────────────────────────────────
+
+    def on_approved(self, engine: Any) -> None:
+        """
+        Call after engine.approve_complication("aevum-spiffe") to trigger
+        SPIFFE attestation and emit the spiffe.attested event.
+
+        The Engine does not call this automatically; callers must invoke it.
+        """
+        self._attest_and_emit(engine)
+
+    def _attest_and_emit(self, engine: Any) -> None:
+        try:
+            spiffe_id, trust_domain, expiry = self._fetch_svid()
+        except ImportError:
+            log.warning(
+                "aevum-spiffe: py-spiffe not installed. "
+                "Install with: pip install aevum-spiffe[spiffe]. "
+                "Continuing without agent identity attestation."
+            )
+            return
+        except Exception as exc:
+            log.warning(
+                "aevum-spiffe: SPIFFE attestation failed (%s). "
+                "Is SPIRE running at %s? "
+                "Continuing without agent identity attestation.",
+                exc,
+                self._socket,
+            )
+            return
+
+        self._spiffe_id = spiffe_id
+        self._trust_domain = trust_domain
+        self._attested = True
+
+        self._write_attested_event(engine, spiffe_id, trust_domain, expiry)
+        log.info("aevum-spiffe: attested as %s", spiffe_id)
+
+    def _fetch_svid(self) -> tuple[str, str, str]:
+        """
+        Fetch a JWT-SVID from the SPIFFE Workload API.
+        Returns (spiffe_id, trust_domain, expiry_iso8601).
+        Raises ImportError if py-spiffe is not installed.
+        Raises Exception if attestation fails.
+        """
+        import datetime
+
+        # Honour the module-level name so tests can patch it; fall back to lazy import.
+        _module = sys.modules.get(__name__)
+        wac = getattr(_module, "WorkloadApiClient", None) if _module else None
+        if wac is None:
+            from spiffe import WorkloadApiClient as _wac  # noqa: PLC0415
+            wac = _wac
+
+        with wac(workload_api_address=self._socket) as client:
+            svid = client.fetch_jwt_svid(audiences=self._audience)
+
+        spiffe_id = str(svid.spiffe_id)
+        trust_domain = svid.spiffe_id.trust_domain.name
+        expiry_dt = datetime.datetime.fromtimestamp(
+            svid.expiry, tz=datetime.UTC
+        )
+        expiry = expiry_dt.isoformat()
+        return spiffe_id, trust_domain, expiry
+
+    def _write_attested_event(
+        self,
+        engine: Any,
+        spiffe_id: str,
+        trust_domain: str,
+        expiry: str,
+    ) -> None:
+        try:
+            engine._ledger.append(
+                event_type="spiffe.attested",
+                payload={
+                    "spiffe_id": spiffe_id,
+                    "trust_domain": trust_domain,
+                    "audience": self._audience,
+                    "svid_type": "jwt",
+                    "source": "workload-api",
+                    "socket": self._socket,
+                    "expiry": expiry,
+                },
+                actor="aevum-spiffe",
+            )
+        except Exception as exc:
+            log.error("aevum-spiffe: failed to write spiffe.attested event: %s", exc)
+
+    # ── Public API for downstream complications ───────────────────────────────
+
+    def get_actor_spiffe_id(self) -> str | None:
+        """
+        Return the attested SPIFFE ID, or None if not yet attested.
+
+        Downstream complications can call this to add actor_spiffe_id to
+        their event payloads:
+            spiffe_comp = engine.get_active_complication_by_capability("spiffe-identity")
+            spiffe_id = spiffe_comp.get_actor_spiffe_id() if spiffe_comp else None
+        """
+        return self._spiffe_id
+
+    @property
+    def is_attested(self) -> bool:
+        """True if SPIFFE attestation succeeded."""
+        return self._attested

aevum_spiffe-0.4.0/tests/test_spiffe_complication.py

@@ -0,0 +1,225 @@
+"""
+Tests for SpiffeComplication.
+Uses mocked SPIFFE WorkloadApiClient — no real SPIRE deployment required.
+"""
+from __future__ import annotations
+
+import datetime
+import sys
+import unittest.mock
+
+
+def _make_mock_svid(spiffe_id_str: str = "spiffe://example.org/billing") -> unittest.mock.MagicMock:
+    """Build a minimal mock JWT-SVID."""
+    mock_svid = unittest.mock.MagicMock()
+    mock_spiffe_id = unittest.mock.MagicMock()
+    mock_spiffe_id.__str__ = lambda self: spiffe_id_str
+    mock_trust_domain = unittest.mock.MagicMock()
+    mock_trust_domain.name = "example.org"
+    mock_spiffe_id.trust_domain = mock_trust_domain
+    mock_svid.spiffe_id = mock_spiffe_id
+    mock_svid.expiry = datetime.datetime(
+        2026, 5, 6, 14, 0, 0, tzinfo=datetime.UTC
+    ).timestamp()
+    return mock_svid
+
+
+def _make_mock_client(svid: unittest.mock.MagicMock) -> unittest.mock.MagicMock:
+    """Build a mock WorkloadApiClient context manager."""
+    client = unittest.mock.MagicMock()
+    client.__enter__ = unittest.mock.MagicMock(return_value=client)
+    client.__exit__ = unittest.mock.MagicMock(return_value=False)
+    client.fetch_jwt_svid = unittest.mock.MagicMock(return_value=svid)
+    return client
+
+
+def _make_mock_engine() -> unittest.mock.MagicMock:
+    """Minimal engine mock with a ledger."""
+    engine = unittest.mock.MagicMock()
+    engine._ledger.append = unittest.mock.MagicMock(return_value=None)
+    return engine
+
+
+class TestSpiffeComplicationWithMockSPIRE:
+
+    def test_on_approved_emits_spiffe_attested(self) -> None:
+        """Successful attestation must emit a spiffe.attested event."""
+        from aevum.spiffe import SpiffeComplication
+
+        mock_svid = _make_mock_svid()
+        mock_client = _make_mock_client(mock_svid)
+        mock_engine = _make_mock_engine()
+
+        comp = SpiffeComplication(socket_path="unix:///fake/socket")
+
+        with unittest.mock.patch(
+            "aevum.spiffe.complication.WorkloadApiClient",
+            return_value=mock_client,
+        ):
+            comp.on_approved(mock_engine)
+
+        assert comp.is_attested is True
+        assert comp.get_actor_spiffe_id() == "spiffe://example.org/billing"
+
+        mock_engine._ledger.append.assert_called_once()
+        call_kwargs = mock_engine._ledger.append.call_args.kwargs
+        assert call_kwargs["event_type"] == "spiffe.attested"
+        assert call_kwargs["payload"]["spiffe_id"] == "spiffe://example.org/billing"
+        assert call_kwargs["payload"]["trust_domain"] == "example.org"
+        assert call_kwargs["actor"] == "aevum-spiffe"
+
+    def test_missing_spiffe_library_degrades_gracefully(self) -> None:
+        """Missing py-spiffe must warn and not raise."""
+        from aevum.spiffe import SpiffeComplication
+
+        mock_engine = _make_mock_engine()
+        comp = SpiffeComplication()
+
+        with unittest.mock.patch.dict(sys.modules, {"spiffe": None}):
+            comp.on_approved(mock_engine)
+
+        assert comp.is_attested is False
+        assert comp.get_actor_spiffe_id() is None
+        mock_engine._ledger.append.assert_not_called()
+
+    def test_socket_unavailable_degrades_gracefully(self) -> None:
+        """Unreachable SPIFFE socket must warn and not raise."""
+        from aevum.spiffe import SpiffeComplication
+
+        mock_engine = _make_mock_engine()
+        comp = SpiffeComplication(socket_path="unix:///nonexistent/socket")
+
+        bad_client = unittest.mock.MagicMock()
+        bad_client.__enter__ = unittest.mock.MagicMock(
+            side_effect=Exception("Connection refused")
+        )
+        bad_client.__exit__ = unittest.mock.MagicMock(return_value=False)
+
+        with unittest.mock.patch(
+            "aevum.spiffe.complication.WorkloadApiClient",
+            return_value=bad_client,
+        ):
+            comp.on_approved(mock_engine)
+
+        assert comp.is_attested is False
+        mock_engine._ledger.append.assert_not_called()
+
+    def test_get_actor_spiffe_id_before_attestation(self) -> None:
+        """get_actor_spiffe_id() returns None before attestation."""
+        from aevum.spiffe import SpiffeComplication
+
+        comp = SpiffeComplication()
+        assert comp.get_actor_spiffe_id() is None
+
+    def test_spiffe_id_format_preserved(self) -> None:
+        """SPIFFE ID must be stored verbatim as returned by the SVID."""
+        from aevum.spiffe import SpiffeComplication
+
+        spiffe_id = "spiffe://production.example.com/service/billing-agent-v2"
+        mock_svid = _make_mock_svid(spiffe_id)
+        mock_client = _make_mock_client(mock_svid)
+        mock_engine = _make_mock_engine()
+
+        comp = SpiffeComplication()
+
+        with unittest.mock.patch(
+            "aevum.spiffe.complication.WorkloadApiClient",
+            return_value=mock_client,
+        ):
+            comp.on_approved(mock_engine)
+
+        assert comp.get_actor_spiffe_id() == spiffe_id
+
+        call_kwargs = mock_engine._ledger.append.call_args.kwargs
+        assert call_kwargs["payload"]["spiffe_id"] == spiffe_id
+        assert call_kwargs["payload"]["trust_domain"] == "example.org"
+
+    def test_audience_passed_to_workload_api(self) -> None:
+        """Custom audience must be forwarded to fetch_jwt_svid."""
+        from aevum.spiffe import SpiffeComplication
+
+        mock_svid = _make_mock_svid()
+        mock_client = _make_mock_client(mock_svid)
+        mock_engine = _make_mock_engine()
+
+        comp = SpiffeComplication(audience=["billing-service", "audit"])
+
+        with unittest.mock.patch(
+            "aevum.spiffe.complication.WorkloadApiClient",
+            return_value=mock_client,
+        ):
+            comp.on_approved(mock_engine)
+
+        mock_client.fetch_jwt_svid.assert_called_once_with(
+            audiences=["billing-service", "audit"]
+        )
+
+    def test_svid_jwt_not_stored(self) -> None:
+        """The JWT token itself must NOT appear in the spiffe.attested payload."""
+        from aevum.spiffe import SpiffeComplication
+
+        mock_svid = _make_mock_svid()
+        mock_svid.token = "eyJhbGciOiJFZERTQSJ9.SENSITIVE.CONTENT"
+        mock_client = _make_mock_client(mock_svid)
+        mock_engine = _make_mock_engine()
+
+        comp = SpiffeComplication()
+
+        with unittest.mock.patch(
+            "aevum.spiffe.complication.WorkloadApiClient",
+            return_value=mock_client,
+        ):
+            comp.on_approved(mock_engine)
+
+        call_kwargs = mock_engine._ledger.append.call_args.kwargs
+        payload_str = str(call_kwargs["payload"])
+        assert "eyJ" not in payload_str, "JWT token must not appear in payload"
+        assert "SENSITIVE" not in payload_str, "JWT token must not appear in payload"
+
+    def test_manifest_passes_validation(self) -> None:
+        """manifest() must satisfy ManifestValidator (all required fields present)."""
+        from aevum.spiffe import SpiffeComplication
+
+        sys.path.insert(0, "../../packages/aevum-core/src")
+        from aevum.core.complications.manifest_validator import ManifestValidator
+
+        comp = SpiffeComplication()
+        errors = ManifestValidator().validate(comp.manifest())
+        assert errors == [], f"Manifest validation errors: {errors}"
+
+
+class TestSpiffeComplicationWithEngine:
+
+    def test_spiffe_attested_appears_in_sigchain(self) -> None:
+        """spiffe.attested must be a verifiable, signed event in the chain."""
+        # Engine lives in aevum-core; pythonpath configured in pyproject.toml
+        from aevum.core import Engine
+
+        from aevum.spiffe import SpiffeComplication
+
+        mock_svid = _make_mock_svid()
+        mock_client = _make_mock_client(mock_svid)
+
+        comp = SpiffeComplication()
+        engine = Engine()
+
+        with unittest.mock.patch(
+            "aevum.spiffe.complication.WorkloadApiClient",
+            return_value=mock_client,
+        ):
+            engine.install_complication(comp)
+            engine.approve_complication("aevum-spiffe")
+            # Engine has no automatic on_approved hook; caller invokes it.
+            comp.on_approved(engine)
+
+        entries = engine.get_ledger_entries()
+        event_types = [e["event_type"] for e in entries]
+
+        assert "spiffe.attested" in event_types, (
+            f"spiffe.attested not in chain. Events: {event_types}"
+        )
+        assert engine.verify_sigchain() is True, "Chain must be intact after attestation"
+
+        attested = next(e for e in entries if e["event_type"] == "spiffe.attested")
+        assert attested["payload"]["spiffe_id"] == "spiffe://example.org/billing"
+        assert attested["actor"] == "aevum-spiffe"