Architecture¶
How Attestix is structured internally.
Project Layout¶
attestix/
main.py # MCP server entry point (registers all 47 tools)
config.py # Configuration loader (env vars, defaults)
errors.py # Custom exception hierarchy
auth/
signing.py # Ed25519 key management (generation, loading, signing, verification)
ssrf.py # SSRF protection for outbound HTTP requests
services/
identity_service.py # UAIT creation, resolution, verification, translation, GDPR erasure
agent_card_service.py # A2A agent card parsing, generation, discovery
did_service.py # DID creation (did:key, did:web), resolution
delegation_service.py # UCAN-style delegation with JWT tokens
reputation_service.py # Recency-weighted trust scoring
compliance_service.py # EU AI Act risk profiles, assessments, declarations
credential_service.py # W3C Verifiable Credentials and Presentations
provenance_service.py # Training data, model lineage, audit trail
blockchain_service.py # On-chain anchoring via EAS on Base L2
blockchain/
merkle.py # Merkle tree implementation for batch anchoring
tools/
identity_tools.py # MCP tool definitions for Identity module (8 tools)
agent_card_tools.py # MCP tool definitions for Agent Cards module (3 tools)
did_tools.py # MCP tool definitions for DID module (3 tools)
delegation_tools.py # MCP tool definitions for Delegation module (4 tools)
reputation_tools.py # MCP tool definitions for Reputation module (3 tools)
compliance_tools.py # MCP tool definitions for Compliance module (7 tools)
credential_tools.py # MCP tool definitions for Credentials module (8 tools)
provenance_tools.py # MCP tool definitions for Provenance module (5 tools)
blockchain_tools.py # MCP tool definitions for Blockchain module (6 tools)
tests/
test_identity.py # Unit tests for identity service
test_compliance.py # Unit tests for compliance service
test_credentials.py # Unit tests for credential service
test_provenance.py # Unit tests for provenance service
test_delegation.py # Unit tests for delegation service
test_reputation.py # Unit tests for reputation service
test_blockchain.py # Unit tests for blockchain service
test_tools.py # Integration tests for MCP tool registration
e2e/ # End-to-end persona-based tests
Layered Architecture¶
graph TD
A["MCP Protocol Layer<br/><i>main.py - FastMCP server</i>"] --> B
A --> C
A --> D
B["Tool Layer<br/><i>tools/*.py</i><br/>Input parsing & formatting"] --> E
C["Tool Layer<br/><i>tools/*.py</i>"] --> E
D["Tool Layer<br/><i>tools/*.py</i>"] --> E
E["Service Layer<br/><i>services/*_service.py</i><br/>Business logic, validation, orchestration"] --> F
F["Auth / Crypto Layer<br/><i>auth/signing.py, auth/ssrf.py</i><br/>Ed25519 key management, SSRF protection"] --> G
G["Storage Layer<br/><i>JSON files with file locking</i><br/>identities.json, credentials.json, etc."]
style A fill:#4f46e5,color:#fff
style B fill:#6366f1,color:#fff
style C fill:#6366f1,color:#fff
style D fill:#6366f1,color:#fff
style E fill:#e1a32c,color:#fff
style F fill:#059669,color:#fff
style G fill:#475569,color:#fffData Flow: Identity Creation¶
sequenceDiagram
participant U as User / Agent
participant T as Tool Layer<br/>identity_tools.py
participant S as Service Layer<br/>identity_service.py
participant A as Auth Layer<br/>signing.py
participant D as Storage Layer<br/>identities.json
U->>T: create_agent_identity(display_name="MyBot", ...)
T->>T: Parse capabilities, validate inputs
T->>S: create_identity(...)
S->>S: Generate agent_id: attestix:{hex16}
S->>S: Build UAIT, set timestamps
S->>A: Sign UAIT
A->>A: Load/generate Ed25519 keypair
A->>A: Derive DID: did:key:z6Mk...
A-->>S: Signed UAIT
S->>D: Acquire file lock
D->>D: Read, append, atomic write
D-->>S: Stored
S-->>U: UAIT with signature, DID, metadataData Flow: Credential Issuance¶
sequenceDiagram
participant U as User / Agent
participant T as Tool Layer<br/>credential_tools.py
participant S as Service Layer<br/>credential_service.py
participant A as Auth Layer<br/>signing.py
participant D as Storage Layer<br/>credentials.json
U->>T: issue_credential(subject_agent_id, type, claims)
T->>T: Parse claims JSON, validate subject
T->>S: issue_credential(...)
S->>S: Build W3C VC structure
S->>S: Set @context, type, issuer, dates
S->>A: Create Ed25519Signature2020 proof
A->>A: proofPurpose: assertionMethod
A-->>S: Signed credential
S->>D: Store in credentials.json
S-->>U: W3C Verifiable Credential with proofData Flow: Blockchain Anchoring¶
sequenceDiagram
participant U as User / Agent
participant S as Service Layer<br/>blockchain_service.py
participant B as Base L2 (EAS)
participant D as Storage Layer
U->>S: anchor_credential(credential_id)
S->>S: Load credential from credentials.json
S->>S: Compute SHA-256 hash of canonical JSON
S->>B: Connect to Base L2 RPC
S->>B: Build EAS attestation transaction
B->>B: Sign with wallet key, submit TX
B-->>S: Transaction receipt
S->>D: Record anchor: artifact_id, tx_hash, block
S-->>U: tx_hash, block_number, chain_id, explorer_urlSecurity Boundaries¶
| Boundary | Protection |
|---|---|
| Tool inputs | All string inputs validated for length, format, and type. Comma-separated lists parsed safely. JSON inputs parsed with error handling. |
| Outbound HTTP | SSRF protection in auth/ssrf.py blocks requests to private IP ranges, localhost, and link-local addresses. HTTPS only for agent discovery. |
| Signing keys | .signing_key.json and .keypairs.json are never included in tool outputs. Files are excluded from git by default. |
| File storage | Cross-platform file locking prevents concurrent corruption. Atomic writes with backups protect against interrupted writes. |
| Delegation tokens | JWT tokens signed with EdDSA. Expiry enforced. Revocation checked on verification. Capability attenuation (delegatee cannot escalate beyond delegator's capabilities). |
| Audit trail | Hash-chained entries where each entry includes the hash of the previous entry. Tampering with any entry breaks the chain. |
Configuration¶
Attestix uses environment variables for configuration. No config files needed. See Configuration for details.
Testing¶
193 tests across unit and end-to-end suites: