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 ¶

Zero-config security middleware for A2A agents.

SimpleGuard handles message signing and verification using Ed25519 keys. All cryptographic operations are performed by the capiscio-core Go library via gRPC, ensuring consistent behavior across all SDKs.

Example

guard = SimpleGuard(dev_mode=True) token = guard.sign_outbound({"sub": "test"}, body=b"hello") claims = guard.verify_inbound(token, body=b"hello")

With explicit agent_id:¶

guard = SimpleGuard(agent_id="did:web:example.com:agents:myagent")

In dev mode, did:key is auto-generated:¶

guard = SimpleGuard(dev_mode=True) print(guard.agent_id) # didz6Mk...

init ¶

__init__(
    base_dir: Optional[Union[str, Path]] = None,
    dev_mode: bool = False,
    rpc_address: Optional[str] = None,
    agent_id: Optional[str] = None,
    badge_token: Optional[str] = None,
) -> 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 with did:key identity (RFC-002 §6.1). TYPE: `bool` DEFAULT: `False`
`rpc_address`	gRPC server address. If None, auto-starts local server. TYPE: `Optional[str]` DEFAULT: `None`
`agent_id`	Explicit agent DID. If None: - In dev_mode: Auto-generates did:key from keypair - Otherwise: Loaded from agent-card.json TYPE: `Optional[str]` DEFAULT: `None`
`badge_token`	Pre-obtained badge token to use for identity. When set, make_headers() will use this token instead of signing. TYPE: `Optional[str]` DEFAULT: `None`

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]

Generate headers containing the Badge (RFC-002 §9.1).

If a badge_token was provided at construction, it will be used. Otherwise, signs the payload to create a token.

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

RETURNS	DESCRIPTION
`Dict[str, str]`	Dict with X-Capiscio-Badge header.

set_badge_token ¶

set_badge_token(token: str) -> None

Update the badge token used for outbound requests.

This is typically called by the badge keeper when a new token is obtained.

PARAMETER	DESCRIPTION
`token`	The new badge token (compact JWS). TYPE: `str`

close ¶

close() -> None

Close the gRPC connection.