capiscio-sdk 0.3.0__py3-none-any.whl → 2.3.1__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- capiscio_sdk/__init__.py +67 -1
- capiscio_sdk/_rpc/__init__.py +7 -0
- capiscio_sdk/_rpc/client.py +1321 -0
- capiscio_sdk/_rpc/gen/__init__.py +1 -0
- capiscio_sdk/_rpc/process.py +232 -0
- capiscio_sdk/badge.py +737 -0
- capiscio_sdk/badge_keeper.py +304 -0
- capiscio_sdk/dv.py +296 -0
- capiscio_sdk/executor.py +5 -5
- capiscio_sdk/integrations/fastapi.py +3 -2
- capiscio_sdk/scoring/__init__.py +73 -3
- capiscio_sdk/simple_guard.py +196 -204
- capiscio_sdk/validators/__init__.py +59 -2
- capiscio_sdk/validators/_core.py +376 -0
- capiscio_sdk-2.3.1.dist-info/METADATA +532 -0
- {capiscio_sdk-0.3.0.dist-info → capiscio_sdk-2.3.1.dist-info}/RECORD +18 -10
- {capiscio_sdk-0.3.0.dist-info → capiscio_sdk-2.3.1.dist-info}/WHEEL +1 -1
- capiscio_sdk-0.3.0.dist-info/METADATA +0 -126
- {capiscio_sdk-0.3.0.dist-info → capiscio_sdk-2.3.1.dist-info}/licenses/LICENSE +0 -0
|
@@ -0,0 +1,532 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: capiscio-sdk
|
|
3
|
+
Version: 2.3.1
|
|
4
|
+
Summary: Runtime security middleware for A2A agents
|
|
5
|
+
Project-URL: Homepage, https://capisc.io
|
|
6
|
+
Project-URL: Documentation, https://docs.capisc.io/sdk-python
|
|
7
|
+
Project-URL: Repository, https://github.com/capiscio/capiscio-sdk-python
|
|
8
|
+
Project-URL: Issues, https://github.com/capiscio/capiscio-sdk-python/issues
|
|
9
|
+
Author-email: Capiscio Team <team@capisc.io>
|
|
10
|
+
License: Apache-2.0
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: a2a,agent,agent-to-agent,middleware,security,validation
|
|
13
|
+
Classifier: Development Status :: 3 - Alpha
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: License :: OSI Approved :: Apache Software License
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Topic :: Security
|
|
22
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
23
|
+
Requires-Python: >=3.10
|
|
24
|
+
Requires-Dist: a2a-sdk>=0.1.0
|
|
25
|
+
Requires-Dist: cachetools>=5.3.0
|
|
26
|
+
Requires-Dist: cryptography>=42.0.0
|
|
27
|
+
Requires-Dist: grpcio>=1.60.0
|
|
28
|
+
Requires-Dist: httpx>=0.27.0
|
|
29
|
+
Requires-Dist: protobuf>=4.25.0
|
|
30
|
+
Requires-Dist: pydantic>=2.0.0
|
|
31
|
+
Requires-Dist: pyjwt[crypto]>=2.8.0
|
|
32
|
+
Provides-Extra: dev
|
|
33
|
+
Requires-Dist: black>=24.0.0; extra == 'dev'
|
|
34
|
+
Requires-Dist: fastapi>=0.100.0; extra == 'dev'
|
|
35
|
+
Requires-Dist: mypy>=1.9.0; extra == 'dev'
|
|
36
|
+
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
|
|
37
|
+
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
|
|
38
|
+
Requires-Dist: pytest>=8.0.0; extra == 'dev'
|
|
39
|
+
Requires-Dist: ruff>=0.3.0; extra == 'dev'
|
|
40
|
+
Requires-Dist: starlette>=0.27.0; extra == 'dev'
|
|
41
|
+
Requires-Dist: types-cachetools>=5.3.0; extra == 'dev'
|
|
42
|
+
Provides-Extra: web
|
|
43
|
+
Requires-Dist: fastapi>=0.100.0; extra == 'web'
|
|
44
|
+
Requires-Dist: starlette>=0.27.0; extra == 'web'
|
|
45
|
+
Description-Content-Type: text/markdown
|
|
46
|
+
|
|
47
|
+
# CapiscIO SDK (Python)
|
|
48
|
+
|
|
49
|
+
**Enforcement-First Security for A2A Agents.**
|
|
50
|
+
|
|
51
|
+
[](https://badge.fury.io/py/capiscio-sdk)
|
|
52
|
+
[](https://opensource.org/licenses/Apache-2.0)
|
|
53
|
+
[](https://www.python.org/downloads/)
|
|
54
|
+
|
|
55
|
+
**CapiscIO** is the "Customs Officer" for your AI Agent. It provides military-grade Identity and Integrity enforcement for the [Agent-to-Agent (A2A) Protocol](https://github.com/google/A2A) with **zero configuration**.
|
|
56
|
+
|
|
57
|
+
## 🚀 The 60-Second Upgrade
|
|
58
|
+
|
|
59
|
+
Turn any FastAPI application into a Verified A2A Agent in 3 lines of code.
|
|
60
|
+
|
|
61
|
+
```python
|
|
62
|
+
from fastapi import FastAPI
|
|
63
|
+
from capiscio_sdk.simple_guard import SimpleGuard
|
|
64
|
+
from capiscio_sdk.integrations.fastapi import CapiscioMiddleware
|
|
65
|
+
|
|
66
|
+
# 1. Initialize Guard (Auto-generates keys in dev_mode)
|
|
67
|
+
guard = SimpleGuard(dev_mode=True)
|
|
68
|
+
|
|
69
|
+
app = FastAPI()
|
|
70
|
+
|
|
71
|
+
# 2. Add Enforcement Middleware
|
|
72
|
+
app.add_middleware(CapiscioMiddleware, guard=guard)
|
|
73
|
+
|
|
74
|
+
@app.post("/agent/task")
|
|
75
|
+
async def handle_task(request: Request):
|
|
76
|
+
# 🔒 Only reachable if Identity + Integrity are verified
|
|
77
|
+
caller = request.state.agent_id
|
|
78
|
+
return {"status": "accepted", "verified_caller": caller}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
## 🛡️ What You Get (Out of the Box)
|
|
82
|
+
|
|
83
|
+
1. **Zero-Config Identity**:
|
|
84
|
+
* Auto-generates **Ed25519** keys and `agent-card.json` on first run.
|
|
85
|
+
* No manual key management required for development.
|
|
86
|
+
|
|
87
|
+
2. **Payload Integrity**:
|
|
88
|
+
* Enforces **SHA-256 Body Hash (`bh`)** verification.
|
|
89
|
+
* Blocks tampered payloads instantly (returns `403 Forbidden`).
|
|
90
|
+
|
|
91
|
+
3. **Replay Protection**:
|
|
92
|
+
* Enforces strict **60-second** token expiration (`exp`).
|
|
93
|
+
* Prevents replay attacks and ensures freshness.
|
|
94
|
+
|
|
95
|
+
4. **Performance Telemetry**:
|
|
96
|
+
* Adds `<1ms` overhead.
|
|
97
|
+
* Includes `Server-Timing` headers for transparent monitoring.
|
|
98
|
+
|
|
99
|
+
## Installation
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
pip install capiscio-sdk
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
## 🎯 Agent Card Validation with CoreValidator
|
|
106
|
+
|
|
107
|
+
The SDK includes a **Go core-backed validator** for Agent Card validation. This ensures consistent validation behavior across all CapiscIO SDKs (Python, Node.js, etc.).
|
|
108
|
+
|
|
109
|
+
### Quick Validation
|
|
110
|
+
|
|
111
|
+
```python
|
|
112
|
+
from capiscio_sdk.validators import validate_agent_card
|
|
113
|
+
|
|
114
|
+
# One-shot validation
|
|
115
|
+
result = validate_agent_card({
|
|
116
|
+
"name": "My Agent",
|
|
117
|
+
"url": "https://myagent.example.com",
|
|
118
|
+
"version": "1.0.0",
|
|
119
|
+
"skills": [{"id": "chat", "name": "Chat", "description": "Chat skill"}]
|
|
120
|
+
})
|
|
121
|
+
|
|
122
|
+
print(f"Valid: {result.success}")
|
|
123
|
+
print(f"Compliance Score: {result.compliance.total}/100 ({result.compliance.rating})")
|
|
124
|
+
print(f"Trust Score: {result.trust.total}/100 ({result.trust.rating})")
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
### Multi-Dimensional Scoring
|
|
128
|
+
|
|
129
|
+
CoreValidator returns rich multi-dimensional scores:
|
|
130
|
+
|
|
131
|
+
```python
|
|
132
|
+
from capiscio_sdk.validators import CoreValidator
|
|
133
|
+
|
|
134
|
+
with CoreValidator() as validator:
|
|
135
|
+
result = validator.validate_agent_card(card)
|
|
136
|
+
|
|
137
|
+
# 📊 Compliance Score (0-100)
|
|
138
|
+
print(f"Compliance: {result.compliance.total}")
|
|
139
|
+
print(f" - Core Fields: {result.compliance.breakdown.core_fields.score}")
|
|
140
|
+
print(f" - Skills Quality: {result.compliance.breakdown.skills_quality.score}")
|
|
141
|
+
print(f" - Format Compliance: {result.compliance.breakdown.format_compliance.score}")
|
|
142
|
+
print(f" - Data Quality: {result.compliance.breakdown.data_quality.score}")
|
|
143
|
+
|
|
144
|
+
# 🔒 Trust Score (0-100)
|
|
145
|
+
print(f"Trust: {result.trust.total}")
|
|
146
|
+
print(f" - Signatures: {result.trust.breakdown.signatures.score}")
|
|
147
|
+
print(f" - Provider: {result.trust.breakdown.provider.score}")
|
|
148
|
+
print(f" - Security: {result.trust.breakdown.security.score}")
|
|
149
|
+
print(f" - Documentation: {result.trust.breakdown.documentation.score}")
|
|
150
|
+
|
|
151
|
+
# 📡 Availability Score (when tested)
|
|
152
|
+
if result.availability.tested:
|
|
153
|
+
print(f"Availability: {result.availability.total}")
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
### Score Ratings
|
|
157
|
+
|
|
158
|
+
| Score Range | Compliance Rating | Trust Rating |
|
|
159
|
+
|-------------|-------------------|--------------|
|
|
160
|
+
| 90-100 | A+ | Verified |
|
|
161
|
+
| 80-89 | A | High |
|
|
162
|
+
| 70-79 | B | Good |
|
|
163
|
+
| 60-69 | C | Moderate |
|
|
164
|
+
| 50-59 | D | Low |
|
|
165
|
+
| 0-49 | F | Untrusted |
|
|
166
|
+
|
|
167
|
+
### Async Fetch and Validate
|
|
168
|
+
|
|
169
|
+
```python
|
|
170
|
+
async def check_remote_agent(agent_url: str):
|
|
171
|
+
with CoreValidator() as validator:
|
|
172
|
+
result = await validator.fetch_and_validate(agent_url)
|
|
173
|
+
return result.success and result.compliance.total >= 80
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
### Migration from Legacy Validators
|
|
177
|
+
|
|
178
|
+
```python
|
|
179
|
+
# ❌ Deprecated (will be removed in v1.0.0)
|
|
180
|
+
from capiscio_sdk.validators import AgentCardValidator
|
|
181
|
+
validator = AgentCardValidator() # Shows deprecation warning
|
|
182
|
+
|
|
183
|
+
# ✅ Recommended
|
|
184
|
+
from capiscio_sdk.validators import CoreValidator, validate_agent_card
|
|
185
|
+
result = validate_agent_card(card) # Uses Go core
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
## 🔏 Trust Badge Verification (RFC-002)
|
|
189
|
+
|
|
190
|
+
CapiscIO Trust Badges provide cryptographic proof of agent identity verification. The SDK supports verifying badges issued by the CapiscIO registry or self-signed badges for development.
|
|
191
|
+
|
|
192
|
+
### Trust Levels
|
|
193
|
+
|
|
194
|
+
| Level | Name | Description |
|
|
195
|
+
|-------|------|-------------|
|
|
196
|
+
| 0 | Self-Signed (SS) | No external validation, `did:key` issuer |
|
|
197
|
+
| 1 | Domain Validated (DV) | Domain ownership verified |
|
|
198
|
+
| 2 | Organization Validated (OV) | Organization identity verified |
|
|
199
|
+
| 3 | Extended Validated (EV) | Highest level of identity verification |
|
|
200
|
+
| 4 | Community Vouched (CV) | Verified with peer attestations |
|
|
201
|
+
|
|
202
|
+
### Verify a Trust Badge
|
|
203
|
+
|
|
204
|
+
```python
|
|
205
|
+
from capiscio_sdk._rpc.client import CapiscioRPCClient
|
|
206
|
+
|
|
207
|
+
# Connect to gRPC server (auto-starts if needed)
|
|
208
|
+
client = CapiscioRPCClient()
|
|
209
|
+
client.connect()
|
|
210
|
+
|
|
211
|
+
# Badge token (JWS format)
|
|
212
|
+
badge_token = "eyJhbGciOiJFZERTQSJ9.eyJqdGkiOi..."
|
|
213
|
+
|
|
214
|
+
# Verify badge (production - rejects self-signed)
|
|
215
|
+
valid, claims, warnings, error = client.badge.verify_badge_with_options(
|
|
216
|
+
badge_token,
|
|
217
|
+
accept_self_signed=False # Default: reject self-signed badges
|
|
218
|
+
)
|
|
219
|
+
|
|
220
|
+
if valid:
|
|
221
|
+
print(f"✅ Badge verified!")
|
|
222
|
+
print(f" Issuer: {claims['iss']}")
|
|
223
|
+
print(f" Subject: {claims['sub']}")
|
|
224
|
+
print(f" Trust Level: {claims['trust_level']}") # "0", "1", "2", "3", or "4"
|
|
225
|
+
print(f" Expires: {claims['exp']}")
|
|
226
|
+
else:
|
|
227
|
+
print(f"❌ Verification failed: {error}")
|
|
228
|
+
|
|
229
|
+
client.close()
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
### Accept Self-Signed Badges (Development)
|
|
233
|
+
|
|
234
|
+
For development/testing, you can accept self-signed (Level 0) badges:
|
|
235
|
+
|
|
236
|
+
```python
|
|
237
|
+
# Development mode - accept self-signed badges
|
|
238
|
+
valid, claims, warnings, error = client.badge.verify_badge_with_options(
|
|
239
|
+
badge_token,
|
|
240
|
+
accept_self_signed=True # ⚠️ Only for development!
|
|
241
|
+
)
|
|
242
|
+
|
|
243
|
+
if valid and claims['trust_level'] == '0':
|
|
244
|
+
print("⚠️ Self-signed badge - not suitable for production")
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
### Verification Options
|
|
248
|
+
|
|
249
|
+
```python
|
|
250
|
+
# Full verification options
|
|
251
|
+
valid, claims, warnings, error = client.badge.verify_badge_with_options(
|
|
252
|
+
token=badge_token,
|
|
253
|
+
accept_self_signed=False, # Reject Level 0 badges
|
|
254
|
+
trusted_issuers=["https://registry.capisc.io"], # Allowlist of trusted CAs
|
|
255
|
+
audience="my-service", # Expected audience claim
|
|
256
|
+
skip_revocation=False, # Check revocation status
|
|
257
|
+
skip_agent_status=False # Check agent is not disabled
|
|
258
|
+
)
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
### Badge Claims Structure
|
|
262
|
+
|
|
263
|
+
```python
|
|
264
|
+
# Example claims from a verified badge
|
|
265
|
+
claims = {
|
|
266
|
+
"jti": "550e8400-e29b-41d4-a716-446655440000", # Unique badge ID
|
|
267
|
+
"iss": "https://registry.capisc.io", # Issuer URL
|
|
268
|
+
"sub": "did:web:registry.capisc.io:agents:abc123", # Agent DID
|
|
269
|
+
"iat": 1702234567, # Issued at (Unix timestamp)
|
|
270
|
+
"exp": 1702320967, # Expires at (Unix timestamp)
|
|
271
|
+
"trust_level": "2", # "0"-"4"
|
|
272
|
+
"aud": ["my-service"], # Audience (optional)
|
|
273
|
+
}
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
## 🔌 gRPC SDK Integration (All 7 Services)
|
|
277
|
+
|
|
278
|
+
The SDK provides a comprehensive gRPC client that wraps all `capiscio-core` functionality. The client auto-starts the local gRPC server if needed.
|
|
279
|
+
|
|
280
|
+
### Connection Modes
|
|
281
|
+
|
|
282
|
+
```python
|
|
283
|
+
from capiscio_sdk._rpc.client import CapiscioRPCClient
|
|
284
|
+
|
|
285
|
+
# Auto-start mode (recommended for local development)
|
|
286
|
+
client = CapiscioRPCClient() # Auto-starts capiscio-core gRPC server
|
|
287
|
+
client.connect()
|
|
288
|
+
|
|
289
|
+
# Connect to existing Unix socket
|
|
290
|
+
client = CapiscioRPCClient(address="unix:///tmp/capiscio.sock", auto_start=False)
|
|
291
|
+
client.connect()
|
|
292
|
+
|
|
293
|
+
# Connect to remote TCP server
|
|
294
|
+
client = CapiscioRPCClient(address="localhost:50051", auto_start=False)
|
|
295
|
+
client.connect()
|
|
296
|
+
|
|
297
|
+
# Context manager (auto-cleanup)
|
|
298
|
+
with CapiscioRPCClient() as client:
|
|
299
|
+
# Use client...
|
|
300
|
+
pass # Automatically disconnects
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
### 1. BadgeService - Trust Badge Operations
|
|
304
|
+
|
|
305
|
+
```python
|
|
306
|
+
import time
|
|
307
|
+
|
|
308
|
+
with CapiscioRPCClient() as client:
|
|
309
|
+
# Sign a badge
|
|
310
|
+
token, claims = client.badge.sign_badge(
|
|
311
|
+
claims={
|
|
312
|
+
"jti": "550e8400-e29b-41d4-a716-446655440000",
|
|
313
|
+
"iss": "https://registry.capisc.io",
|
|
314
|
+
"sub": "did:web:registry.capisc.io:agents:my-agent",
|
|
315
|
+
"iat": int(time.time()),
|
|
316
|
+
"exp": int(time.time()) + 300,
|
|
317
|
+
"trust_level": "2"
|
|
318
|
+
},
|
|
319
|
+
private_key_jwk='{"kty":"OKP",...}',
|
|
320
|
+
key_id="key-1"
|
|
321
|
+
)
|
|
322
|
+
|
|
323
|
+
# Verify with full options
|
|
324
|
+
valid, claims, warnings, error = client.badge.verify_badge_with_options(
|
|
325
|
+
token,
|
|
326
|
+
accept_self_signed=True,
|
|
327
|
+
trusted_issuers=["https://registry.capisc.io"],
|
|
328
|
+
audience="my-service"
|
|
329
|
+
)
|
|
330
|
+
|
|
331
|
+
# Parse without verification
|
|
332
|
+
claims, error = client.badge.parse_badge(token)
|
|
333
|
+
|
|
334
|
+
# Request CA-signed badge
|
|
335
|
+
token, error = client.badge.request_badge(
|
|
336
|
+
agent_id="my-agent-123",
|
|
337
|
+
api_key="capi_key_...",
|
|
338
|
+
ca_url="https://registry.capisc.io"
|
|
339
|
+
)
|
|
340
|
+
|
|
341
|
+
# Start badge keeper (auto-renewal)
|
|
342
|
+
for event in client.badge.start_keeper(
|
|
343
|
+
private_key_jwk='{"kty":"OKP",...}',
|
|
344
|
+
subject="did:web:registry.capisc.io:agents:my-agent",
|
|
345
|
+
ca_url="https://registry.capisc.io",
|
|
346
|
+
ttl_seconds=300,
|
|
347
|
+
renew_before_seconds=60
|
|
348
|
+
):
|
|
349
|
+
if event.event_type == "renewed":
|
|
350
|
+
print(f"Badge renewed: {event.badge_token}")
|
|
351
|
+
```
|
|
352
|
+
|
|
353
|
+
### 2. DIDService - DID Parsing
|
|
354
|
+
|
|
355
|
+
```python
|
|
356
|
+
with CapiscioRPCClient() as client:
|
|
357
|
+
# Parse did:web identifier
|
|
358
|
+
did_info, error = client.did.parse("did:web:registry.capisc.io:agents:my-agent")
|
|
359
|
+
|
|
360
|
+
if did_info:
|
|
361
|
+
print(f"Method: {did_info['method']}") # "web"
|
|
362
|
+
print(f"Domain: {did_info['domain']}") # "registry.capisc.io"
|
|
363
|
+
print(f"Path: {did_info['path']}") # "agents/my-agent"
|
|
364
|
+
print(f"Document URL: {did_info['document_url']}") # "https://registry.capisc.io/agents/my-agent/did.json"
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
### 3. TrustStoreService - Manage Trusted CA Keys
|
|
368
|
+
|
|
369
|
+
```python
|
|
370
|
+
with CapiscioRPCClient() as client:
|
|
371
|
+
# Add trusted CA key
|
|
372
|
+
kid, error = client.trust.add_key(
|
|
373
|
+
did="did:web:registry.capisc.io",
|
|
374
|
+
public_key=b'{"kty":"OKP",...}',
|
|
375
|
+
format="JWK"
|
|
376
|
+
)
|
|
377
|
+
|
|
378
|
+
print(f"Added key: {kid}")
|
|
379
|
+
```
|
|
380
|
+
|
|
381
|
+
### 4. RevocationService - Check Revocation Status
|
|
382
|
+
|
|
383
|
+
```python
|
|
384
|
+
with CapiscioRPCClient() as client:
|
|
385
|
+
# Check if badge is revoked
|
|
386
|
+
is_revoked = client.revocation.is_revoked("badge-jti-12345")
|
|
387
|
+
|
|
388
|
+
if is_revoked:
|
|
389
|
+
print("⚠️ Badge has been revoked!")
|
|
390
|
+
```
|
|
391
|
+
|
|
392
|
+
### 5. ScoringService - Agent Card Scoring
|
|
393
|
+
|
|
394
|
+
```python
|
|
395
|
+
with CapiscioRPCClient() as client:
|
|
396
|
+
# Score an agent card
|
|
397
|
+
result, error = client.scoring.score_agent_card(agent_card_json)
|
|
398
|
+
|
|
399
|
+
if result:
|
|
400
|
+
print(f"Overall Score: {result['overall_score']}/100")
|
|
401
|
+
print(f"Compliance: {result['compliance_score']}/100")
|
|
402
|
+
print(f"Trust: {result['trust_score']}/100")
|
|
403
|
+
print(f"Availability: {result['availability_score']}/100")
|
|
404
|
+
|
|
405
|
+
# Validate a specific rule
|
|
406
|
+
rule_result, error = client.scoring.validate_rule("rule-001", agent_card_json)
|
|
407
|
+
|
|
408
|
+
# List available rule sets
|
|
409
|
+
rule_sets, error = client.scoring.list_rule_sets()
|
|
410
|
+
|
|
411
|
+
# Get specific rule set
|
|
412
|
+
rule_set, error = client.scoring.get_rule_set("default")
|
|
413
|
+
|
|
414
|
+
# Aggregate multiple scores
|
|
415
|
+
aggregated, error = client.scoring.aggregate_scores(
|
|
416
|
+
results=[
|
|
417
|
+
{"overall_score": 85},
|
|
418
|
+
{"overall_score": 90},
|
|
419
|
+
{"overall_score": 88}
|
|
420
|
+
],
|
|
421
|
+
method="average" # or "min", "max"
|
|
422
|
+
)
|
|
423
|
+
```
|
|
424
|
+
|
|
425
|
+
### 6. SimpleGuardService - JWS Signing & Verification
|
|
426
|
+
|
|
427
|
+
```python
|
|
428
|
+
with CapiscioRPCClient() as client:
|
|
429
|
+
# Sign a payload
|
|
430
|
+
signature, error = client.simpleguard.sign(
|
|
431
|
+
payload=b"important message",
|
|
432
|
+
key_id="my-key-1"
|
|
433
|
+
)
|
|
434
|
+
|
|
435
|
+
# Verify a signature
|
|
436
|
+
valid, payload, error = client.simpleguard.verify(
|
|
437
|
+
signature=signature,
|
|
438
|
+
expected_payload=b"important message",
|
|
439
|
+
public_key_jwk='{"kty":"OKP",...}'
|
|
440
|
+
)
|
|
441
|
+
|
|
442
|
+
# Sign with attached payload (JWS Compact)
|
|
443
|
+
jws, error = client.simpleguard.sign_attached(
|
|
444
|
+
payload=b"message",
|
|
445
|
+
key_id="my-key-1"
|
|
446
|
+
)
|
|
447
|
+
|
|
448
|
+
# Verify attached signature
|
|
449
|
+
valid, payload, error = client.simpleguard.verify_attached(
|
|
450
|
+
jws=jws,
|
|
451
|
+
public_key_jwk='{"kty":"OKP",...}'
|
|
452
|
+
)
|
|
453
|
+
|
|
454
|
+
# Get key information
|
|
455
|
+
key_info, error = client.simpleguard.get_key_info("my-key-1")
|
|
456
|
+
```
|
|
457
|
+
|
|
458
|
+
### 7. RegistryService - Fetch Agent Cards
|
|
459
|
+
|
|
460
|
+
```python
|
|
461
|
+
with CapiscioRPCClient() as client:
|
|
462
|
+
# Get agent card by DID
|
|
463
|
+
agent_card, error = client.registry.get_agent(
|
|
464
|
+
did="did:web:registry.capisc.io:agents:my-agent"
|
|
465
|
+
)
|
|
466
|
+
|
|
467
|
+
if agent_card:
|
|
468
|
+
print(f"Agent Name: {agent_card['name']}")
|
|
469
|
+
print(f"URL: {agent_card['url']}")
|
|
470
|
+
```
|
|
471
|
+
|
|
472
|
+
### Process Manager
|
|
473
|
+
|
|
474
|
+
The SDK includes automatic process management for the `capiscio-core` gRPC server:
|
|
475
|
+
|
|
476
|
+
```python
|
|
477
|
+
from capiscio_sdk._rpc.process import get_process_manager
|
|
478
|
+
|
|
479
|
+
# Get singleton process manager
|
|
480
|
+
pm = get_process_manager()
|
|
481
|
+
|
|
482
|
+
# Ensure server is running (auto-starts if needed)
|
|
483
|
+
address = pm.ensure_running(timeout=10.0)
|
|
484
|
+
print(f"gRPC server running at: {address}")
|
|
485
|
+
|
|
486
|
+
# Manually start server
|
|
487
|
+
pm.start()
|
|
488
|
+
|
|
489
|
+
# Stop server
|
|
490
|
+
pm.stop()
|
|
491
|
+
|
|
492
|
+
# Check if running
|
|
493
|
+
if pm.is_running():
|
|
494
|
+
print("Server is running")
|
|
495
|
+
```
|
|
496
|
+
|
|
497
|
+
**Auto-Start Behavior:**
|
|
498
|
+
- ✅ Automatically downloads `capiscio-core` binary if not found
|
|
499
|
+
- ✅ Starts on Unix socket by default (`~/.capiscio/rpc.sock`)
|
|
500
|
+
- ✅ Handles server crashes and restarts
|
|
501
|
+
- ✅ Cleans up on process exit
|
|
502
|
+
|
|
503
|
+
## How It Works
|
|
504
|
+
|
|
505
|
+
### 1. The Handshake
|
|
506
|
+
CapiscIO enforces the **A2A Trust Protocol**:
|
|
507
|
+
* **Sender**: Signs the request body (JWS + Body Hash).
|
|
508
|
+
* **Receiver**: Verifies the signature and re-hashes the body to ensure integrity.
|
|
509
|
+
|
|
510
|
+
### 2. The "Customs Officer"
|
|
511
|
+
The `SimpleGuard` acts as a local authority. It manages your agent's "Passport" (Agent Card) and verifies the "Visas" (Tokens) of incoming requests.
|
|
512
|
+
|
|
513
|
+
### 3. Go Core Integration
|
|
514
|
+
The SDK delegates validation to `capiscio-core` (Go) via gRPC for:
|
|
515
|
+
* **Consistent behavior** across all CapiscIO SDKs
|
|
516
|
+
* **High performance** validation (Go's speed + Python's flexibility)
|
|
517
|
+
* **Single source of truth** for validation rules
|
|
518
|
+
|
|
519
|
+
### 4. Telemetry
|
|
520
|
+
Every response includes a `Server-Timing` header showing exactly how fast the verification was:
|
|
521
|
+
```http
|
|
522
|
+
Server-Timing: capiscio-auth;dur=0.618;desc="CapiscIO Verification"
|
|
523
|
+
```
|
|
524
|
+
|
|
525
|
+
## Documentation
|
|
526
|
+
|
|
527
|
+
- [Official Documentation](https://docs.capisc.io)
|
|
528
|
+
- [A2A Protocol Spec](https://github.com/google/A2A)
|
|
529
|
+
|
|
530
|
+
## License
|
|
531
|
+
|
|
532
|
+
Apache License 2.0 - see [LICENSE](LICENSE) for details.
|
|
@@ -1,20 +1,28 @@
|
|
|
1
|
-
capiscio_sdk/__init__.py,sha256=
|
|
1
|
+
capiscio_sdk/__init__.py,sha256=s4wpl1PgPbYiF75ArKjBNSlkmXPqnzm99YzkWMcx3UY,2683
|
|
2
|
+
capiscio_sdk/badge.py,sha256=6dGyv12oweTVRf5L7mZqNDW5LYAnruOGmJAvepCzTVI,24219
|
|
3
|
+
capiscio_sdk/badge_keeper.py,sha256=JrxksWiGM7zfKi8BxCqVbVfg4RKEQELH0rUx3Jf-nfg,10900
|
|
2
4
|
capiscio_sdk/config.py,sha256=-1KNubnRE06SENRXcnGvrj-y1EfKz2uAMdz7s0n6ark,3972
|
|
5
|
+
capiscio_sdk/dv.py,sha256=wCHjkWTpeKR0INcrusYG-ub3-rnI-e3JiO0nWgaKoF4,8078
|
|
3
6
|
capiscio_sdk/errors.py,sha256=vGk7fhf07MM4-p7tvMXZlIz0yHQw9J03yIGGqRAEWDY,2107
|
|
4
|
-
capiscio_sdk/executor.py,sha256=
|
|
7
|
+
capiscio_sdk/executor.py,sha256=rVYr5xmyjMu_ZHmn6Efe2_8b6N8li0hTt_DKTHA_Hs0,7783
|
|
5
8
|
capiscio_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
6
|
-
capiscio_sdk/simple_guard.py,sha256=
|
|
9
|
+
capiscio_sdk/simple_guard.py,sha256=ZOmJQCN0MVud07pqAzFJYf0tYBkwMv2t2zXUKC6IDLg,13717
|
|
7
10
|
capiscio_sdk/types.py,sha256=A_0SLhrbX7apkH5yYGTkG-_284xRjCK0N3lEseVRJRs,7978
|
|
11
|
+
capiscio_sdk/_rpc/__init__.py,sha256=nMnCp5CIisoEA2SX3tYgLprAOyMxVxFfKIWj3glkneA,275
|
|
12
|
+
capiscio_sdk/_rpc/client.py,sha256=_CYmNhOQp1suZt9-5I3mm53Y_cEjDeWkwuQMOlgAhAA,47104
|
|
13
|
+
capiscio_sdk/_rpc/process.py,sha256=5jyPUDT3Ig1x2UXhAPWPuKqQScAeMkzvs8USshqYrCM,7445
|
|
14
|
+
capiscio_sdk/_rpc/gen/__init__.py,sha256=JgqmySPbQjyx56NVnyIe_BvNdjwWy-or_OcZPomydYE,29
|
|
8
15
|
capiscio_sdk/infrastructure/__init__.py,sha256=5yK7kbk1tcHqlnFIN0lR5N_4ZWWquNivLfHkXOAtso0,152
|
|
9
16
|
capiscio_sdk/infrastructure/cache.py,sha256=FjIRRzNbsPxFZrxdeek51IwFSmR682Wpj1bvvmgqwiU,1841
|
|
10
17
|
capiscio_sdk/infrastructure/rate_limiter.py,sha256=7Q_GfcooWKjioDeB46PpPb00laDmkLpUYGM0Ui8nXqI,3642
|
|
11
|
-
capiscio_sdk/integrations/fastapi.py,sha256=
|
|
12
|
-
capiscio_sdk/scoring/__init__.py,sha256=
|
|
18
|
+
capiscio_sdk/integrations/fastapi.py,sha256=zww7Pg8OMG7Ts03Omq1-1h4ZRR08819FpsTkHW-M8Ak,2949
|
|
19
|
+
capiscio_sdk/scoring/__init__.py,sha256=ldC3WyM7jbcGjsEWQK_anB7VjG8y9mZMbNaBUwPgRrY,3621
|
|
13
20
|
capiscio_sdk/scoring/availability.py,sha256=CzXA1ED48U1Cc06sh0Mtl_kxZP6af-9cceBumTXQhO8,9130
|
|
14
21
|
capiscio_sdk/scoring/compliance.py,sha256=JZyYuT18A_eiDNdOz-doTIYwW6YhVPvfRj_siNAkkTY,9780
|
|
15
22
|
capiscio_sdk/scoring/trust.py,sha256=u3dposV0zWfh4mW6XzpWDLP7Mora8y3k2_KwVtEuQPw,10955
|
|
16
23
|
capiscio_sdk/scoring/types.py,sha256=4D-2kWVrPNxugxug_q-tZiQI5_Cv1ThtSPmOH-KbSrs,10051
|
|
17
|
-
capiscio_sdk/validators/__init__.py,sha256=
|
|
24
|
+
capiscio_sdk/validators/__init__.py,sha256=q1UjIFUkztKgfC-5N8mGb-zfET3vsEbKbxtN7f9E7b4,2603
|
|
25
|
+
capiscio_sdk/validators/_core.py,sha256=S76QX_KTdqDbuQPy9WxV2Z0jP4o1H65rABWBwp_6R74,13301
|
|
18
26
|
capiscio_sdk/validators/agent_card.py,sha256=d8VfGXvtHiuU0DuC1W64Z_JPVqOVh-nRMVShOAznJbk,18506
|
|
19
27
|
capiscio_sdk/validators/certificate.py,sha256=7RguWk9ahtrxe3TuRqiv5t5vBGta_cUp4qjcx7GwAl0,14373
|
|
20
28
|
capiscio_sdk/validators/message.py,sha256=TGVCAwFHcen1v9KLK5UtxVXq61yOqOnd4yudxSxFMmw,15472
|
|
@@ -22,7 +30,7 @@ capiscio_sdk/validators/protocol.py,sha256=bkaJJXseulTJ4Sdiio8gE8Q_Pyqj0BRsJe6BG
|
|
|
22
30
|
capiscio_sdk/validators/semver.py,sha256=mlF3GO5ZPA-w6FzSxhjcr56sgCdS0YVVAd1dUr1bxWs,6385
|
|
23
31
|
capiscio_sdk/validators/signature.py,sha256=lI8XzaKfG_dXSOQXZ40Lda0ntga9EqqC4zAId2kOt6g,8072
|
|
24
32
|
capiscio_sdk/validators/url_security.py,sha256=SdpOrB48hrfgAMuLvpWH2P0LLCJtg6QBohGDIye8f1E,9802
|
|
25
|
-
capiscio_sdk-
|
|
26
|
-
capiscio_sdk-
|
|
27
|
-
capiscio_sdk-
|
|
28
|
-
capiscio_sdk-
|
|
33
|
+
capiscio_sdk-2.3.1.dist-info/METADATA,sha256=dVbl4wh1ep30mfNfX23mjJrmQ2gxRLG9aipj-fE5ZdI,17302
|
|
34
|
+
capiscio_sdk-2.3.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
|
|
35
|
+
capiscio_sdk-2.3.1.dist-info/licenses/LICENSE,sha256=AMM_E-ILcCpX0JALqX3BL9yfgSx654BtkhX-CBFYp1Q,10758
|
|
36
|
+
capiscio_sdk-2.3.1.dist-info/RECORD,,
|