Enforcement First Security¶

CapiscIO operates on a simple principle: Enforcement First. Before an agent processes a single byte of a request, it must verify the Identity of the calling agent and the Integrity of the message.

The Trust Model¶

How it works today:

1. Each agent generates its own keys (Ed25519 keypair)
2. Public keys are shared manually (copied to trust stores)
3. Guard verifies signatures against keys in the local trust store

This is intentional. We enforce identity verification at the protocol layer without requiring a central authority. You control which agents you trust.

The "Customs Officer" Model¶

Think of SimpleGuard as a Customs Officer at the border of your agent. It stops every request and asks three questions:

1. "Who are you?" (Agent Identity)
2. "Did you really say this?" (Payload Integrity)
3. "Is this current?" (Freshness / Replay Protection)

If any answer is "No", the request is rejected immediately.

1. Agent Identity Verification (JWS)¶

CapiscIO uses JSON Web Signatures (JWS) with Ed25519 keys to prove agent identity.

The Handshake¶

1. Sender: Signs the request using their private key.
2. Header: The request includes an X-Capiscio-JWS header containing the signature.
3. Receiver:
   • Extracts the Key ID (kid) from the header.
   • Looks up the public key in the local Trust Store (./capiscio_keys/trusted/).
   • Verifies the signature.

Zero-Config Dev Mode¶

When initialized with dev_mode=True, SimpleGuard automatically:

• Generates a new Ed25519 keypair in ./capiscio_keys/.
• Creates an agent-card.json with the public key.
• Adds the public key to the local Trust Store (Self-Trust).

Adding External Agents to Your Trust Store¶

To accept requests from another agent:

# Copy their public key to your trust store
cp /path/to/other-agent/capiscio_keys/public.pem \
   ./capiscio_keys/trusted/{their-key-id}.pem

The {their-key-id} must match the kid claim in their JWS headers.

2. Integrity Verification (Body Hash)¶

Identity is not enough. An attacker could intercept a valid signed request and change the body (e.g., "Transfer $10" → "Transfer $1M").

To prevent this, CapiscIO enforces Payload Integrity using a Body Hash (bh) claim.

The Process¶

1. Sender:
   • Calculates SHA-256(HTTP Body).
   • Adds the hash to the JWS payload as claim bh.
   • Signs the JWS.
2. Receiver:
   • Verifies the JWS signature (Identity).
   • Calculates SHA-256(Received HTTP Body).
   • Compares the calculated hash with the bh claim.

If the hashes do not match, SimpleGuard raises a VerificationError and returns 403 Forbidden.

3. Freshness / Replay Protection¶

Even with valid identity and integrity, an attacker could capture a legitimate request and replay it.

CapiscIO enforces Freshness using timestamp claims:

• iat (issued at): When the request was signed
• exp (expires): When the signature expires

Guard rejects requests outside a 60-second window (with 5s clock skew tolerance).

4. Performance Telemetry¶

Security shouldn't slow you down. CapiscIO adds negligible overhead (<1ms) and proves it with every response.

Check the Server-Timing header in any response:

Server-Timing: capiscio-auth;dur=0.618;desc="CapiscIO Verification"

• dur: Duration in milliseconds.
• desc: Description of the operation.

Summary: What Guard Does and Doesn't Do¶