SimpleGuard¶

Zero-configuration security for signing and verifying A2A requests.

Overview¶

SimpleGuard is the recommended way to add security to your A2A agent. It handles:

Signing outbound requests with JWS (JSON Web Signature)
Verifying inbound requests against a trust store
Key management with file-based storage

Basic Usage¶

from capiscio_sdk.simple_guard import SimpleGuard

# Initialize - uses convention over configuration
# Looks for capiscio_keys/ and agent-card.json in project root
guard = SimpleGuard(dev_mode=True)  # Auto-generates keys for development

# Sign a request
body = b'{"method": "tasks/send", "params": {}}'
jws = guard.sign_outbound({}, body=body)

# Verify an incoming request
claims = guard.verify_inbound(jws, body=body)

Convention Over Configuration¶

SimpleGuard automatically finds keys based on directory structure:

your-project/
├── agent-card.json           # Agent identity
└── capiscio_keys/
    ├── private.pem           # Signing key
    ├── public.pem            # Public key
    └── trusted/              # Trust store
        └── {kid}.pem         # Trusted keys (filename = key ID)

In dev_mode=True, all files are auto-generated if missing.

API Reference¶

capiscio_sdk.simple_guard.SimpleGuard ¶

The "Customs Officer" for your Agent.

Enforces Identity (JWS) and Protocol (A2A) validation locally. Prioritizes local utility and zero-configuration.

init ¶

__init__(base_dir: Optional[Union[str, Path]] = None, dev_mode: bool = False) -> None

Initialize SimpleGuard.

PARAMETER	DESCRIPTION
`base_dir`	Starting directory to search for config (defaults to cwd). TYPE: `Optional[Union[str, Path]]` DEFAULT: `None`
`dev_mode`	If True, auto-generates keys and agent-card.json. TYPE: `bool` DEFAULT: `False`

sign_outbound ¶

sign_outbound(payload: Dict[str, Any], body: Optional[bytes] = None) -> str

Sign a payload for outbound transmission.

PARAMETER	DESCRIPTION
`payload`	The JSON payload to sign. TYPE: `Dict[str, Any]`
`body`	Optional HTTP body bytes to bind to the signature. TYPE: `Optional[bytes]` DEFAULT: `None`

RETURNS	DESCRIPTION
`str`	Compact JWS string.

verify_inbound ¶

verify_inbound(jws: str, body: Optional[bytes] = None) -> Dict[str, Any]

Verify an inbound JWS.

PARAMETER	DESCRIPTION
`jws`	The compact JWS string. TYPE: `str`
`body`	Optional HTTP body bytes to verify against 'bh' claim. TYPE: `Optional[bytes]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Dict[str, Any]`	The verified payload.

RAISES	DESCRIPTION
`VerificationError`	If signature is invalid, key is untrusted, or integrity check fails.

make_headers ¶

make_headers(payload: Dict[str, Any], body: Optional[bytes] = None) -> Dict[str, str]

Helper to generate the headers containing the JWS.