diff --git a/docs/assets/samples/agent-card-full.json b/docs/assets/samples/agent-card-full.json index 0bf18f3..f839a4c 100644 --- a/docs/assets/samples/agent-card-full.json +++ b/docs/assets/samples/agent-card-full.json @@ -3,6 +3,7 @@ "description": "AI-powered code review assistant that analyzes pull requests for bugs, security issues, and style improvements", "url": "https://codereview.example.com", "version": "2.1.0", + "protocolVersion": "0.2.1", "documentationUrl": "https://docs.codereview.example.com", "provider": { "organization": "DevTools Inc", diff --git a/docs/assets/samples/agent-card.json b/docs/assets/samples/agent-card.json index 3a2d2c3..5776af6 100644 --- a/docs/assets/samples/agent-card.json +++ b/docs/assets/samples/agent-card.json @@ -3,6 +3,7 @@ "description": "A helpful AI assistant built with CapiscIO", "url": "https://my-agent.example.com", "version": "1.0.0", + "protocolVersion": "0.2.1", "provider": { "organization": "My Company", "url": "https://mycompany.com" diff --git a/docs/getting-started/complete-workflow.md b/docs/getting-started/complete-workflow.md index 1993031..9e626d4 100644 --- a/docs/getting-started/complete-workflow.md +++ b/docs/getting-started/complete-workflow.md @@ -47,6 +47,7 @@ Every A2A agent needs an `agent-card.json` that describes its capabilities: "description": "A helpful assistant that can answer questions", "url": "https://my-agent.example.com", "version": "1.0.0", + "protocolVersion": "{{ protocol_version }}", "provider": { "organization": "My Company", "url": "https://example.com" diff --git a/docs/getting-started/secure/1-intro.md b/docs/getting-started/secure/1-intro.md index 917c961..faa6aff 100644 --- a/docs/getting-started/secure/1-intro.md +++ b/docs/getting-started/secure/1-intro.md @@ -99,13 +99,15 @@ The token contains: ```json { - "iss": "did:capiscio:agent:my-agent", "iat": 1701432000, "exp": 1701432060, "bh": "sha256-hash-of-body" } ``` +!!! note "Production vs Dev Mode" + In production with registered badges, the token also includes `"iss"` (the agent's DID). In dev mode, only `iat`, `exp`, and `bh` are present. + --- ## What You'll Learn diff --git a/docs/getting-started/secure/2-sdk.md b/docs/getting-started/secure/2-sdk.md index 8ad0e65..c01bb13 100644 --- a/docs/getting-started/secure/2-sdk.md +++ b/docs/getting-started/secure/2-sdk.md @@ -154,7 +154,7 @@ async def handle_message(request: Request): # 3. Verify the signature try: claims = guard.verify_inbound(badge_token, body=body) - print(f"✅ Verified request from: {claims.get('iss')}") + print(f"✅ Verified request from: {claims.get('iss', 'dev-mode agent')}") except Exception as e: raise HTTPException(status_code=401, detail=f"Signature verification failed: {e}") diff --git a/docs/getting-started/secure/3-guard.md b/docs/getting-started/secure/3-guard.md index 8bee456..f82b3bf 100644 --- a/docs/getting-started/secure/3-guard.md +++ b/docs/getting-started/secure/3-guard.md @@ -52,13 +52,15 @@ your-project/ Decoded claims: { - "iss": "local-dev-agent", "iat": 1701432000, "exp": 1701432060, "bh": "sha256:a1b2c3d4e5f6..." } ``` + !!! note + In dev mode, claims contain `iat`, `exp`, and `bh`. The `iss` claim (agent DID) is added when using registered badges in production. + ### Use the Signature in HTTP === "Code" @@ -112,7 +114,7 @@ your-project/ try: claims = guard.verify_inbound(jws=badge, body=body) - print(f"✓ Valid request from: {claims['iss']}") + print(f"✓ Valid request") print(f" Issued at: {claims['iat']}") print(f" Expires: {claims['exp']}") except VerificationError as e: @@ -122,7 +124,7 @@ your-project/ === "Valid Request" ``` - ✓ Valid request from: partner-agent + ✓ Valid request Issued at: 1701432000 Expires: 1701432060 ``` @@ -216,6 +218,9 @@ When you call `verify_inbound()`, SimpleGuard checks: | **Not Expired** | `exp` > now | `Token expired` | | **Not Future** | `iat` <= now | `Token not yet valid` | +!!! warning "Dev Mode Trust" + In `dev_mode=True`, the trust store is permissive — all valid Ed25519 signatures are accepted. The **Trust** check above only rejects untrusted keys when you have a configured trust store (i.e., keys in `capiscio_keys/trusted/`) or when using the `CapiscioMiddleware`. See [Step 4: Test Enforcement](4-test.md) for an example that demonstrates trust rejection via the middleware. + --- ## Managing the Trust Store diff --git a/docs/getting-started/validate/2-install.md b/docs/getting-started/validate/2-install.md index 948c2c3..de18a6b 100644 --- a/docs/getting-started/validate/2-install.md +++ b/docs/getting-started/validate/2-install.md @@ -25,7 +25,7 @@ The CapiscIO CLI is available for Node.js and Python. Choose your preferred plat Expected output: ``` - capiscio/{{ capiscio_version }} (darwin-arm64) + capiscio version {{ capiscio_version }} (commit: ) ``` === "pip (Python)" @@ -42,7 +42,7 @@ The CapiscIO CLI is available for Node.js and Python. Choose your preferred plat Expected output: ``` - capiscio/{{ capiscio_version }} (darwin-arm64) + capiscio version {{ capiscio_version }} (commit: ) ``` === "Go (Direct)" diff --git a/docs/getting-started/validate/3-validate.md b/docs/getting-started/validate/3-validate.md index 95ba7bb..e05294c 100644 --- a/docs/getting-started/validate/3-validate.md +++ b/docs/getting-started/validate/3-validate.md @@ -21,6 +21,7 @@ First, grab our sample agent card: "description": "A helpful AI assistant", "url": "https://my-agent.example.com", "version": "1.0.0", + "protocolVersion": "{{ protocol_version }}", "capabilities": { "streaming": true, "pushNotifications": false