Agent Attestation

Pavri attestation provides cryptographic identity verification for AI agents. An attestation claim is a signed assertion that a specific agent, running a specific configuration, is who it claims to be.

Why Attestation

In multi-agent environments, agents call other agents. Without identity verification, a compromised or spoofed agent could impersonate a trusted service and escalate privileges or exfiltrate data.

Attestation solves this by binding an agent's identity to:

• Agent fingerprint — a hash of the agent's code and plugin configuration
• Config hash — a hash of the agent's runtime configuration
• Signing key — a shared secret (HMAC) or future asymmetric key

A downstream agent can verify an incoming call by checking the attestation claim before processing any request.

Claim Structure

Every attestation claim contains:

Field	Description
claim_id	Unique identifier for this claim (atst-{hex})
agent_id	The agent this claim belongs to
org_id	The organization context
agent_fingerprint	Hash of the agent's code and plugin state
config_hash	Hash of the agent's configuration
signing_algorithm	hmac-sha256 (v1)
signature	Hex-encoded HMAC-SHA256 of the canonical message
status	valid, expired, revoked, or verification_failed
issued_at	When the claim was issued (UTC ISO 8601)
expires_at	When the claim expires (UTC ISO 8601)
key_reference	Logical name of the signing key used

How It Works (HMAC-SHA256)

The v1 attestation scheme uses HMAC-SHA256 with a shared secret. The canonical message signed is:

{claim_id}|{agent_id}|{fingerprint}|{config_hash}|{issued_at_isoformat}

Note that expires_at is not part of the signed message. The signature covers only the fields that identify the agent. Expiry is checked at verification time by comparing expires_at to the current clock.

Issuing a Claim

from pavri.core.attestation import AttestationSigner

signer = AttestationSigner(
    key=b"my-shared-secret-32-bytes-minimum",
    key_reference="key-v1",
    ttl_seconds=3600,  # 1 hour validity
)

result = signer.sign(
    agent_id="agt-payroll-001",
    org_id="org-acme",
    fingerprint="fp-abc123",
    config_hash="cfg-xyz789",
)

claim = result.claim
print(claim.claim_id)      # atst-{hex}
print(claim.signature)     # hex-encoded HMAC bytes
print(claim.expires_at)    # datetime

Verifying a Claim

from pavri.core.attestation import AttestationVerifier

verifier = AttestationVerifier(key=b"my-shared-secret-32-bytes-minimum")

verification = verifier.verify(
    claim_id=claim.claim_id,
    agent_id=claim.agent_id,
    fingerprint=claim.agent_fingerprint,
    config_hash=claim.config_hash,
    issued_at=claim.issued_at,
    expires_at=claim.expires_at,
    signature=claim.signature,
)

if verification.status.value != "valid":
    raise PermissionError(f"Attestation failed: {verification.reason}")

Claim Statuses

Status	Meaning
valid	Claim is current, signature verified.
expired	Claim has passed its expires_at timestamp.
revoked	Claim was administratively revoked before expiry.
verification_failed	HMAC signature check failed — possible tampering.

Attestation and Trust Tiers

Attestation is the mechanism by which an agent earns a verified trust tier in the agent governance system. Operators or automated pipelines set the trust tier based on attestation status:

• No attestation → low trust tier
• Attestation present but expired → medium trust tier (at operator discretion)
• Valid attestation → high or verified trust tier

This trust tier is then evaluated by AgentGovernance.evaluate_peer_call() when agents call each other.

Viewing Attestation in the Dashboard

The Agent Detail page shows the latest attestation claim for an agent in the Trust & Identity rail. The display includes:

• Status badge (valid, expired, revoked, verification_failed)
• Claim ID (monospace)
• Signing algorithm
• Last verified timestamp and verifier identity (if recorded)

To see all claims for your organization, use the Attestation API.

API

POST /api/v1/governance/attestation/issue   # Issue a new claim
POST /api/v1/governance/attestation/verify  # Verify a claim
GET  /api/v1/governance/attestation/{agentId}  # Get claims for an agent

Phase 3 Roadmap

The v1 attestation scheme uses HMAC-SHA256 with a shared secret. Phase 3 will upgrade to asymmetric key pairs (RSA or EC) to support:

• Per-agent signing keys without distributing shared secrets
• Hardware Security Module (HSM) integration
• Cross-organization claim verification