{"id":38549553,"url":"https://github.com/capiscio/capiscio-sdk-python","last_synced_at":"2026-01-17T07:31:19.959Z","repository":{"id":318732558,"uuid":"1072681981","full_name":"capiscio/capiscio-sdk-python","owner":"capiscio","description":"Runtime security middleware for A2A (Agent-to-Agent) protocol agents. Provides always-on validation, signature verification, and rate limiting for AI agent interactions.","archived":false,"fork":false,"pushed_at":"2026-01-14T21:16:20.000Z","size":303,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-16T21:16:22.049Z","etag":null,"topics":["a2a","a2a-protocol","agent-to-agent","ai-agents","middleware","protocol","python","rate-limiting","sdk","security","trust","validation"],"latest_commit_sha":null,"homepage":"https://capisc.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/capiscio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-09T04:24:18.000Z","updated_at":"2026-01-14T21:16:11.000Z","dependencies_parsed_at":"2025-10-13T21:19:29.804Z","dependency_job_id":"68600e90-72c1-42e1-9ee4-207b3bc8ccf1","html_url":"https://github.com/capiscio/capiscio-sdk-python","commit_stats":null,"previous_names":["capiscio/a2a-security","capiscio/capiscio-sdk-python"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/capiscio/capiscio-sdk-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capiscio%2Fcapiscio-sdk-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capiscio%2Fcapiscio-sdk-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capiscio%2Fcapiscio-sdk-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capiscio%2Fcapiscio-sdk-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/capiscio","download_url":"https://codeload.github.com/capiscio/capiscio-sdk-python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capiscio%2Fcapiscio-sdk-python/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28504355,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T06:57:29.758Z","status":"ssl_error","status_checked_at":"2026-01-17T06:56:03.931Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a2a","a2a-protocol","agent-to-agent","ai-agents","middleware","protocol","python","rate-limiting","sdk","security","trust","validation"],"created_at":"2026-01-17T07:31:18.848Z","updated_at":"2026-01-17T07:31:19.947Z","avatar_url":"https://github.com/capiscio.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CapiscIO SDK (Python)\n\n**Enforcement-First Security for A2A Agents.**\n\n[![PyPI version](https://badge.fury.io/py/capiscio-sdk.svg)](https://badge.fury.io/py/capiscio-sdk)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n\n**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**.\n\n## 🚀 The 60-Second Upgrade\n\nTurn any FastAPI application into a Verified A2A Agent in 3 lines of code.\n\n```python\nfrom fastapi import FastAPI\nfrom capiscio_sdk.simple_guard import SimpleGuard\nfrom capiscio_sdk.integrations.fastapi import CapiscioMiddleware\n\n# 1. Initialize Guard (Auto-generates keys in dev_mode)\nguard = SimpleGuard(dev_mode=True)\n\napp = FastAPI()\n\n# 2. Add Enforcement Middleware\napp.add_middleware(CapiscioMiddleware, guard=guard)\n\n@app.post(\"/agent/task\")\nasync def handle_task(request: Request):\n    # 🔒 Only reachable if Identity + Integrity are verified\n    caller = request.state.agent_id\n    return {\"status\": \"accepted\", \"verified_caller\": caller}\n```\n\n## 🛡️ What You Get (Out of the Box)\n\n1.  **Zero-Config Identity**:\n    *   Auto-generates **Ed25519** keys and `agent-card.json` on first run.\n    *   No manual key management required for development.\n\n2.  **Payload Integrity**:\n    *   Enforces **SHA-256 Body Hash (`bh`)** verification.\n    *   Blocks tampered payloads instantly (returns `403 Forbidden`).\n\n3.  **Replay Protection**:\n    *   Enforces strict **60-second** token expiration (`exp`).\n    *   Prevents replay attacks and ensures freshness.\n\n4.  **Performance Telemetry**:\n    *   Adds `\u003c1ms` overhead.\n    *   Includes `Server-Timing` headers for transparent monitoring.\n\n## Installation\n\n```bash\npip install capiscio-sdk\n```\n\n## 🎯 Agent Card Validation with CoreValidator\n\nThe SDK includes a **Go core-backed validator** for Agent Card validation. This ensures consistent validation behavior across all CapiscIO SDKs (Python, Node.js, etc.).\n\n### Quick Validation\n\n```python\nfrom capiscio_sdk.validators import validate_agent_card\n\n# One-shot validation\nresult = validate_agent_card({\n    \"name\": \"My Agent\",\n    \"url\": \"https://myagent.example.com\",\n    \"version\": \"1.0.0\",\n    \"skills\": [{\"id\": \"chat\", \"name\": \"Chat\", \"description\": \"Chat skill\"}]\n})\n\nprint(f\"Valid: {result.success}\")\nprint(f\"Compliance Score: {result.compliance.total}/100 ({result.compliance.rating})\")\nprint(f\"Trust Score: {result.trust.total}/100 ({result.trust.rating})\")\n```\n\n### Multi-Dimensional Scoring\n\nCoreValidator returns rich multi-dimensional scores:\n\n```python\nfrom capiscio_sdk.validators import CoreValidator\n\nwith CoreValidator() as validator:\n    result = validator.validate_agent_card(card)\n    \n    # 📊 Compliance Score (0-100)\n    print(f\"Compliance: {result.compliance.total}\")\n    print(f\"  - Core Fields: {result.compliance.breakdown.core_fields.score}\")\n    print(f\"  - Skills Quality: {result.compliance.breakdown.skills_quality.score}\")\n    print(f\"  - Format Compliance: {result.compliance.breakdown.format_compliance.score}\")\n    print(f\"  - Data Quality: {result.compliance.breakdown.data_quality.score}\")\n    \n    # 🔒 Trust Score (0-100)\n    print(f\"Trust: {result.trust.total}\")\n    print(f\"  - Signatures: {result.trust.breakdown.signatures.score}\")\n    print(f\"  - Provider: {result.trust.breakdown.provider.score}\")\n    print(f\"  - Security: {result.trust.breakdown.security.score}\")\n    print(f\"  - Documentation: {result.trust.breakdown.documentation.score}\")\n    \n    # 📡 Availability Score (when tested)\n    if result.availability.tested:\n        print(f\"Availability: {result.availability.total}\")\n```\n\n### Score Ratings\n\n| Score Range | Compliance Rating | Trust Rating |\n|-------------|-------------------|--------------|\n| 90-100      | A+                | Verified     |\n| 80-89       | A                 | High         |\n| 70-79       | B                 | Good         |\n| 60-69       | C                 | Moderate     |\n| 50-59       | D                 | Low          |\n| 0-49        | F                 | Untrusted    |\n\n### Async Fetch and Validate\n\n```python\nasync def check_remote_agent(agent_url: str):\n    with CoreValidator() as validator:\n        result = await validator.fetch_and_validate(agent_url)\n        return result.success and result.compliance.total \u003e= 80\n```\n\n### Migration from Legacy Validators\n\n```python\n# ❌ Deprecated (will be removed in v1.0.0)\nfrom capiscio_sdk.validators import AgentCardValidator\nvalidator = AgentCardValidator()  # Shows deprecation warning\n\n# ✅ Recommended\nfrom capiscio_sdk.validators import CoreValidator, validate_agent_card\nresult = validate_agent_card(card)  # Uses Go core\n```\n\n## 🔏 Trust Badge Verification (RFC-002)\n\nCapiscIO 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.\n\n### Trust Levels\n\n| Level | Name | Description |\n|-------|------|-------------|\n| 0 | Self-Signed (SS) | No external validation, `did:key` issuer |\n| 1 | Domain Validated (DV) | Domain ownership verified |\n| 2 | Organization Validated (OV) | Organization identity verified |\n| 3 | Extended Validated (EV) | Highest level of identity verification |\n| 4 | Community Vouched (CV) | Verified with peer attestations |\n\n### Verify a Trust Badge\n\n```python\nfrom capiscio_sdk._rpc.client import CapiscioRPCClient\n\n# Connect to gRPC server (auto-starts if needed)\nclient = CapiscioRPCClient()\nclient.connect()\n\n# Badge token (JWS format)\nbadge_token = \"eyJhbGciOiJFZERTQSJ9.eyJqdGkiOi...\"\n\n# Verify badge (production - rejects self-signed)\nvalid, claims, warnings, error = client.badge.verify_badge_with_options(\n    badge_token,\n    accept_self_signed=False  # Default: reject self-signed badges\n)\n\nif valid:\n    print(f\"✅ Badge verified!\")\n    print(f\"   Issuer: {claims['iss']}\")\n    print(f\"   Subject: {claims['sub']}\")\n    print(f\"   Trust Level: {claims['trust_level']}\")  # \"0\", \"1\", \"2\", \"3\", or \"4\"\n    print(f\"   Expires: {claims['exp']}\")\nelse:\n    print(f\"❌ Verification failed: {error}\")\n\nclient.close()\n```\n\n### Accept Self-Signed Badges (Development)\n\nFor development/testing, you can accept self-signed (Level 0) badges:\n\n```python\n# Development mode - accept self-signed badges\nvalid, claims, warnings, error = client.badge.verify_badge_with_options(\n    badge_token,\n    accept_self_signed=True  # ⚠️ Only for development!\n)\n\nif valid and claims['trust_level'] == '0':\n    print(\"⚠️ Self-signed badge - not suitable for production\")\n```\n\n### Verification Options\n\n```python\n# Full verification options\nvalid, claims, warnings, error = client.badge.verify_badge_with_options(\n    token=badge_token,\n    accept_self_signed=False,      # Reject Level 0 badges\n    trusted_issuers=[\"https://registry.capisc.io\"],  # Allowlist of trusted CAs\n    audience=\"my-service\",         # Expected audience claim\n    skip_revocation=False,         # Check revocation status\n    skip_agent_status=False        # Check agent is not disabled\n)\n```\n\n### Badge Claims Structure\n\n```python\n# Example claims from a verified badge\nclaims = {\n    \"jti\": \"550e8400-e29b-41d4-a716-446655440000\",  # Unique badge ID\n    \"iss\": \"https://registry.capisc.io\",            # Issuer URL\n    \"sub\": \"did:web:registry.capisc.io:agents:abc123\",  # Agent DID\n    \"iat\": 1702234567,                              # Issued at (Unix timestamp)\n    \"exp\": 1702320967,                              # Expires at (Unix timestamp)\n    \"trust_level\": \"2\",                             # \"0\"-\"4\"\n    \"aud\": [\"my-service\"],                          # Audience (optional)\n}\n```\n\n## 🔌 gRPC SDK Integration (All 7 Services)\n\nThe SDK provides a comprehensive gRPC client that wraps all `capiscio-core` functionality. The client auto-starts the local gRPC server if needed.\n\n### Connection Modes\n\n```python\nfrom capiscio_sdk._rpc.client import CapiscioRPCClient\n\n# Auto-start mode (recommended for local development)\nclient = CapiscioRPCClient()  # Auto-starts capiscio-core gRPC server\nclient.connect()\n\n# Connect to existing Unix socket\nclient = CapiscioRPCClient(address=\"unix:///tmp/capiscio.sock\", auto_start=False)\nclient.connect()\n\n# Connect to remote TCP server\nclient = CapiscioRPCClient(address=\"localhost:50051\", auto_start=False)\nclient.connect()\n\n# Context manager (auto-cleanup)\nwith CapiscioRPCClient() as client:\n    # Use client...\n    pass  # Automatically disconnects\n```\n\n### 1. BadgeService - Trust Badge Operations\n\n```python\nimport time\n\nwith CapiscioRPCClient() as client:\n    # Sign a badge\n    token, claims = client.badge.sign_badge(\n        claims={\n            \"jti\": \"550e8400-e29b-41d4-a716-446655440000\",\n            \"iss\": \"https://registry.capisc.io\",\n            \"sub\": \"did:web:registry.capisc.io:agents:my-agent\",\n            \"iat\": int(time.time()),\n            \"exp\": int(time.time()) + 300,\n            \"trust_level\": \"2\"\n        },\n        private_key_jwk='{\"kty\":\"OKP\",...}',\n        key_id=\"key-1\"\n    )\n\n    # Verify with full options\n    valid, claims, warnings, error = client.badge.verify_badge_with_options(\n        token,\n        accept_self_signed=True,\n        trusted_issuers=[\"https://registry.capisc.io\"],\n        audience=\"my-service\"\n    )\n\n    # Parse without verification\n    claims, error = client.badge.parse_badge(token)\n\n    # Request CA-signed badge\n    token, error = client.badge.request_badge(\n        agent_id=\"my-agent-123\",\n        api_key=\"capi_key_...\",\n        ca_url=\"https://registry.capisc.io\"\n    )\n\n    # Start badge keeper (auto-renewal)\n    for event in client.badge.start_keeper(\n        private_key_jwk='{\"kty\":\"OKP\",...}',\n        subject=\"did:web:registry.capisc.io:agents:my-agent\",\n        ca_url=\"https://registry.capisc.io\",\n        ttl_seconds=300,\n        renew_before_seconds=60\n    ):\n        if event.event_type == \"renewed\":\n            print(f\"Badge renewed: {event.badge_token}\")\n```\n\n### 2. DIDService - DID Parsing\n\n```python\nwith CapiscioRPCClient() as client:\n    # Parse did:web identifier\n    did_info, error = client.did.parse(\"did:web:registry.capisc.io:agents:my-agent\")\n\n    if did_info:\n        print(f\"Method: {did_info['method']}\")          # \"web\"\n        print(f\"Domain: {did_info['domain']}\")          # \"registry.capisc.io\"\n        print(f\"Path: {did_info['path']}\")              # \"agents/my-agent\"\n        print(f\"Document URL: {did_info['document_url']}\")  # \"https://registry.capisc.io/agents/my-agent/did.json\"\n```\n\n### 3. TrustStoreService - Manage Trusted CA Keys\n\n```python\nwith CapiscioRPCClient() as client:\n    # Add trusted CA key\n    kid, error = client.trust.add_key(\n        did=\"did:web:registry.capisc.io\",\n        public_key=b'{\"kty\":\"OKP\",...}',\n        format=\"JWK\"\n    )\n\n    print(f\"Added key: {kid}\")\n```\n\n### 4. RevocationService - Check Revocation Status\n\n```python\nwith CapiscioRPCClient() as client:\n    # Check if badge is revoked\n    is_revoked = client.revocation.is_revoked(\"badge-jti-12345\")\n\n    if is_revoked:\n        print(\"⚠️ Badge has been revoked!\")\n```\n\n### 5. ScoringService - Agent Card Scoring\n\n```python\nwith CapiscioRPCClient() as client:\n    # Score an agent card\n    result, error = client.scoring.score_agent_card(agent_card_json)\n\n    if result:\n        print(f\"Overall Score: {result['overall_score']}/100\")\n        print(f\"Compliance: {result['compliance_score']}/100\")\n        print(f\"Trust: {result['trust_score']}/100\")\n        print(f\"Availability: {result['availability_score']}/100\")\n\n    # Validate a specific rule\n    rule_result, error = client.scoring.validate_rule(\"rule-001\", agent_card_json)\n\n    # List available rule sets\n    rule_sets, error = client.scoring.list_rule_sets()\n\n    # Get specific rule set\n    rule_set, error = client.scoring.get_rule_set(\"default\")\n\n    # Aggregate multiple scores\n    aggregated, error = client.scoring.aggregate_scores(\n        results=[\n            {\"overall_score\": 85},\n            {\"overall_score\": 90},\n            {\"overall_score\": 88}\n        ],\n        method=\"average\"  # or \"min\", \"max\"\n    )\n```\n\n### 6. SimpleGuardService - JWS Signing \u0026 Verification\n\n```python\nwith CapiscioRPCClient() as client:\n    # Sign a payload\n    signature, error = client.simpleguard.sign(\n        payload=b\"important message\",\n        key_id=\"my-key-1\"\n    )\n\n    # Verify a signature\n    valid, payload, error = client.simpleguard.verify(\n        signature=signature,\n        expected_payload=b\"important message\",\n        public_key_jwk='{\"kty\":\"OKP\",...}'\n    )\n\n    # Sign with attached payload (JWS Compact)\n    jws, error = client.simpleguard.sign_attached(\n        payload=b\"message\",\n        key_id=\"my-key-1\"\n    )\n\n    # Verify attached signature\n    valid, payload, error = client.simpleguard.verify_attached(\n        jws=jws,\n        public_key_jwk='{\"kty\":\"OKP\",...}'\n    )\n\n    # Get key information\n    key_info, error = client.simpleguard.get_key_info(\"my-key-1\")\n```\n\n### 7. RegistryService - Fetch Agent Cards\n\n```python\nwith CapiscioRPCClient() as client:\n    # Get agent card by DID\n    agent_card, error = client.registry.get_agent(\n        did=\"did:web:registry.capisc.io:agents:my-agent\"\n    )\n\n    if agent_card:\n        print(f\"Agent Name: {agent_card['name']}\")\n        print(f\"URL: {agent_card['url']}\")\n```\n\n### Process Manager\n\nThe SDK includes automatic process management for the `capiscio-core` gRPC server:\n\n```python\nfrom capiscio_sdk._rpc.process import get_process_manager\n\n# Get singleton process manager\npm = get_process_manager()\n\n# Ensure server is running (auto-starts if needed)\naddress = pm.ensure_running(timeout=10.0)\nprint(f\"gRPC server running at: {address}\")\n\n# Manually start server\npm.start()\n\n# Stop server\npm.stop()\n\n# Check if running\nif pm.is_running():\n    print(\"Server is running\")\n```\n\n**Auto-Start Behavior:**\n- ✅ Automatically downloads `capiscio-core` binary if not found\n- ✅ Starts on Unix socket by default (`~/.capiscio/rpc.sock`)\n- ✅ Handles server crashes and restarts\n- ✅ Cleans up on process exit\n\n## How It Works\n\n### 1. The Handshake\nCapiscIO enforces the **A2A Trust Protocol**:\n*   **Sender**: Signs the request body (JWS + Body Hash).\n*   **Receiver**: Verifies the signature and re-hashes the body to ensure integrity.\n\n### 2. The \"Customs Officer\"\nThe `SimpleGuard` acts as a local authority. It manages your agent's \"Passport\" (Agent Card) and verifies the \"Visas\" (Tokens) of incoming requests.\n\n### 3. Go Core Integration\nThe SDK delegates validation to `capiscio-core` (Go) via gRPC for:\n*   **Consistent behavior** across all CapiscIO SDKs\n*   **High performance** validation (Go's speed + Python's flexibility)\n*   **Single source of truth** for validation rules\n\n### 4. Telemetry\nEvery response includes a `Server-Timing` header showing exactly how fast the verification was:\n```http\nServer-Timing: capiscio-auth;dur=0.618;desc=\"CapiscIO Verification\"\n```\n\n## Documentation\n\n- [Official Documentation](https://docs.capisc.io)\n- [A2A Protocol Spec](https://github.com/google/A2A)\n\n## License\n\nApache License 2.0 - see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcapiscio%2Fcapiscio-sdk-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcapiscio%2Fcapiscio-sdk-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcapiscio%2Fcapiscio-sdk-python/lists"}