CapiscIO Core: The Authority Layer

CapiscIO Core is the Universal Authority Layer for AI Agents. It provides the infrastructure to Issue, Verify, and Enforce Trust Badges (Identity) for any agent, regardless of protocol (REST, MCP, A2A, etc.).

While it serves as the reference implementation for the Agent-to-Agent (A2A) Protocol, its primary mission is to secure the broader agent ecosystem.

v2.6.0 Release: Full implementation of RFC-002 Trust Badge Specification and RFC-003 Key Ownership Proof (PoP) with did:web/did:key DIDs, Trust Levels, gRPC SDK integration, and enhanced verification.

Why CapiscIO?

Building authentication for AI Agents is hard. OAuth is complex, API keys are insecure, and building a custom registry is a distraction.

CapiscIO Core acts as a Security Sidecar. It sits in front of your agent, verifies incoming requests against a trusted registry, and forwards only authenticated traffic.

[Client] --(Badge)--> [CapiscIO Gateway] --(Identity)--> [Your Agent]
                            |
                       (Verify Sig)
                            |
                       [Registry]

Key Features

• Trust Badges (RFC-002): Issue and Verify VC-aligned JWS tokens with did:web/did:key DIDs and Trust Levels (0-4: SS/REG/DV/OV/EV).
• Proof of Possession (RFC-003): Challenge-response protocol for cryptographic key ownership proof with IAL-1 assurance.
• gRPC SDK Integration: Native gRPC server for Python, Node.js, and other language SDKs with 7 specialized services (auto-started by SDKs via process manager).
• Gateway Sidecar: A high-performance Reverse Proxy that enforces identity before traffic reaches your Agent.
• Registry Interface: Pluggable trust anchors supporting Local Mode (Air-gapped/Dev), Offline Mode (Trust Store), and Cloud Mode (Enterprise).
• Go-Native: Built for speed and concurrency, deployable as a single static binary.

⚡ Quick Start (The "Minimal Stack")

1. Installation

go install github.com/capiscio/capiscio-core/v2/cmd/capiscio@latest

2. Issue a Trust Badge (Identity)

Self-Signed (Development)

# Level 1 (Domain Validated) - default
capiscio badge issue --self-sign --domain example.com

# Level 2 (Organization Validated)
capiscio badge issue --self-sign --level 2 --domain mycompany.com

# With audience restriction
capiscio badge issue --self-sign --aud "https://api.example.com"

With Persistent Key (Production)

# 1. Generate a Key Pair
capiscio key gen --out-priv private.jwk --out-pub public.jwk

# 2. Issue a Badge using the Private Key
capiscio badge issue --key private.jwk --sub "did:web:registry.capisc.io:agents:prod"

Automated Renewal (Daemon)

capiscio badge keep \
  --key private.jwk \
  --sub "did:web:registry.capisc.io:agents:prod" \
  --out badge.jwt \
  --exp 5m \
  --renew-before 1m

3. Verify a Badge

# Online verification (fetches CA key from issuer)
capiscio badge verify "$TOKEN"

# Offline verification (uses local trust store)
capiscio badge verify "$TOKEN" --offline

# With audience check
capiscio badge verify "$TOKEN" --audience "https://api.example.com"

4. Manage Trust Store (Offline Mode)

# Add CA keys from JWKS endpoint
capiscio trust add --from-jwks https://registry.capisc.io/.well-known/jwks.json

# List trusted keys
capiscio trust list

# Remove a key
capiscio trust remove <kid>

5. Start the Gateway (Enforcement)

capiscio gateway start \
  --port 8080 \
  --target http://localhost:3000 \
  --local-key public-key.json

6. Make a Request

# This will succeed (200 OK)
curl -H "X-Capiscio-Badge: $(cat badge.jwt)" http://localhost:8080/api/v1/agent

# This will fail (401 Unauthorized)
curl http://localhost:8080/api/v1/agent

🐳 Docker

The CapiscIO Guard is available as a Docker image for easy deployment:

docker pull capiscio/guard

Quick Start with Docker

# Run the gateway in front of your agent
docker run -p 8080:8080 capiscio/guard \
  gateway start \
  --port 8080 \
  --target http://host.docker.internal:3000 \
  --registry-url https://registry.capisc.io

Docker Compose

services:
  guard:
    image: capiscio/guard:latest
    ports:
      - "8080:8080"
    command:
      - gateway
      - start
      - --port=8080
      - --target=http://agent:3000
      - --registry-url=https://registry.capisc.io
    depends_on:
      - agent
  
  agent:
    image: your-agent:latest
    # Your agent runs on internal port 3000

Available Tags

Tag	Description
latest	Latest stable release
vX.Y.Z	Specific version (e.g., v2.3.0)
vX.Y	Latest patch for minor version
vX	Latest for major version

Building Locally

# Clone and build
git clone https://github.com/capiscio/capiscio-core.git
cd capiscio-core
make docker-build

# Test locally
make docker-run TARGET=http://localhost:3000

7. gRPC Server (SDK Integration)

The gRPC server provides programmatic access to all CapiscIO functionality for SDKs in Python, Node.js, and other languages. The SDKs automatically manage the gRPC server process.

# Python SDK auto-starts the gRPC server
from capiscio_sdk._rpc.client import CapiscioRPCClient
token = '<YOUR_BADGE_TOKEN_HERE>'  # Replace with your actual badge token
with CapiscioRPCClient() as client:  # Auto-starts gRPC server
    valid, claims, warnings, err = client.badge.verify_badge_with_options(
        token,
        accept_self_signed=True  # SDK flag for development
    )
    print(f'Valid: {valid}, Subject: {claims["sub"]}')

Available Services (7 total):

• BadgeService - Sign, verify, parse, request badges; start badge keeper
• DIDService - Parse did:web identifiers
• TrustStoreService - Add trusted CA keys
• RevocationService - Check revocation status
• ScoringService - Score agent cards, validate rules
• SimpleGuardService - Sign/verify payloads with JWS
• RegistryService - Fetch agent cards

🔐 Trust Levels (RFC-002)

Trust Badges include a Trust Level claim that indicates the verification depth:

Level	Name	Verification	DID Method
0	SS (Self-Signed)	No external validation	did:key
1	REG (Registered)	DID verified by registry	did:web
2	DV (Domain Validated)	Domain ownership proven	did:web
3	OV (Organization Validated)	Organization identity verified	did:web
4	EV (Extended Validation)	Extended identity verification	did:web

# Issue Level 0 (Self-Signed) - for development only
capiscio badge issue --self-sign
# Note: --self-sign issues a Level 0 badge using local keys

# Issue Level 2 (OV) - requires CA key
capiscio badge issue --key ca-private.jwk --level 2 --domain example.com

# Verify with local key
capiscio badge verify "$TOKEN" --key ca-public.jwk

# Verify offline (uses trust store)
capiscio badge verify "$TOKEN" --offline

⚠️ Production Warning: Self-signed badges should only be used for development/testing. Production deployments should use CA-issued badges with proper trust chains.

🌐 DID:Web Integration

Badges use did:web DIDs for agent identity:

did:web:registry.capisc.io:agents:my-agent-123

The pkg/did package provides utilities for parsing and constructing DIDs:

import "github.com/capiscio/capiscio-core/v2/pkg/did"

// Parse a DID
d, err := did.Parse("did:web:registry.capisc.io:agents:my-agent")

// Get the DID Document URL
url := d.DocumentURL() // https://registry.capisc.io/agents/my-agent/did.json

// Create a new agent DID
agentDID := did.NewCapiscIOAgentDID("my-agent-123")

🌍 Universal Compatibility

While capiscio-core is the reference implementation for the A2A Protocol, the Authority Layer is designed to be Protocol Agnostic.

• Any Agent: The Gateway works with any HTTP-based agent (REST, GraphQL, MCP, etc.).
• Any Identity: The Trust Badge is a standard JWT/VC that can wrap any DID.
• Any Transport: Badges are passed via standard HTTP headers (Authorization or X-Capiscio-Badge).

You can use the Gateway to secure any AI Agent, even if it doesn't fully implement the A2A Agent Card specification.

🏗️ Architecture

The Authority Layer

• Trust Badge: A standard JWS containing Identity (sub), Trust Level, and Capabilities (vc).
• Gateway: A reverse proxy that enforces badge validity before forwarding traffic.
• Registry: The source of truth for public keys (Local, Trust Store, or Cloud).
• Trust Store: Local storage for CA keys enabling offline verification.
• Revocation Cache: Local cache for revocation lists (5-minute staleness per RFC-002).

The Validation Engine (Foundation)

CapiscIO Core retains its original capabilities as a robust validator for the A2A Protocol:

• Agent Card Validation: Deep schema validation for agent-card.json files.
• Scoring Engine: Calculates "Trust Scores" based on compliance, identity proof, and availability.
• Protocol Clients: Built-in JSON-RPC and HTTP clients for testing Agent availability.

📚 Library Usage

1. Authority Layer (Gatekeeper)

import (
    "github.com/capiscio/capiscio-core/v2/pkg/badge"
    "github.com/capiscio/capiscio-core/v2/pkg/registry"
)

func main() {
    // 1. Setup Registry
    reg := registry.NewLocalRegistry("./keys/public.jwk")
    
    // 2. Create Verifier
    verifier := badge.NewVerifier(reg)
    
    // 3. Verify a Token (simple)
    claims, err := verifier.Verify(context.Background(), tokenString)
    if err != nil {
        log.Fatal("Invalid badge")
    }
    
    fmt.Printf("Authenticated Agent: %s\n", claims.Subject)
}

2. Advanced Verification (RFC-002)

import (
    "github.com/capiscio/capiscio-core/v2/pkg/badge"
)

func main() {
    verifier := badge.NewVerifier(reg)
    
    // Verify with options
    result, err := verifier.VerifyWithOptions(ctx, tokenString, badge.VerifyOptions{
        Mode:           badge.VerifyModeOffline,  // Use trust store
        TrustedIssuers: []string{"https://registry.capisc.io"},
        Audience:       "https://api.example.com",
    })
    if err != nil {
        var badgeErr *badge.BadgeError
        if errors.As(err, &badgeErr) {
            fmt.Printf("Badge error: %s (code: %s)\n", badgeErr.Message, badgeErr.Code)
        }
    }
    
    fmt.Printf("Trust Level: %s\n", result.Claims.TrustLevel())
}

3. Validation Engine (Compliance)

import (
    "github.com/capiscio/capiscio-core/v2/pkg/agentcard"
    "github.com/capiscio/capiscio-core/v2/pkg/scoring"
)

func main() {
    engine := scoring.NewEngine(nil)
    card := &agentcard.AgentCard{...}

    result, err := engine.Validate(context.Background(), card, true)
    if err != nil {
        panic(err)
    }

    fmt.Printf("Compliance Score: %.2f\n", result.TrustScore)
}

📦 Packages

Package	Description
pkg/badge	Trust Badge issuance, verification, and error handling
pkg/did	did:web parsing and construction
pkg/trust	Local trust store for CA keys
pkg/revocation	Revocation list caching
pkg/registry	Registry interface (Local, Cloud)
pkg/gateway	HTTP Gateway middleware
pkg/agentcard	Agent Card schema and validation
pkg/scoring	Trust scoring engine
pkg/crypto	JWKS fetching and key utilities

CLI Reference

badge issue

Issue a new Trust Badge.

capiscio badge issue --self-sign --level 2 --domain example.com

Flags:

• --self-sign: Self-sign for development (explicit flag required).
• --level: Trust level: 1 (DV), 2 (OV), or 3 (EV). Default: 1.
• --domain: Agent domain. Default: example.com.
• --sub: Subject DID (did:web format).
• --aud: Audience (comma-separated URLs).
• --exp: Expiration duration. Default: 5m (per RFC-002).
• --key: Path to private key file (JWK).
• --iss: Issuer URL.

badge verify

Verify a Trust Badge.

capiscio badge verify "$TOKEN" --offline

Flags:

• --offline: Offline mode (uses trust store).
• --key: Path to public key file (JWK).
• --trusted-issuers: Comma-separated list of trusted issuer URLs.
• --audience: Verifier's identity for audience validation.
• --skip-revocation: Skip revocation check (testing only).
• --skip-agent-status: Skip agent status check (testing only).

badge keep

Run a daemon to keep a badge automatically renewed.

capiscio badge keep --key private.jwk --sub "did:web:registry.capisc.io:agents:my-agent" --out badge.jwt --exp 5m --renew-before 1m

Flags:

• --key: Path to private key file (JWK).
• --sub: Subject DID.
• --out: Output file path for the badge.
• --exp: Badge expiration duration. Default: 5m.
• --renew-before: Renew this duration before expiration. Default: 1m.
• --ca-url: CA URL for requesting new badges (optional).

gateway start

Start the CapiscIO Gateway reverse proxy.

capiscio gateway start --port 8080 --target http://localhost:3000 --local-key public.jwk

Flags:

• --port: Gateway listen port. Default: 8080.
• --target: Backend agent URL.
• --local-key: Path to local public key file (for local mode).
• --registry-url: Registry URL (for cloud mode).

rpc

Start the gRPC server for SDK integration.

capiscio rpc
capiscio rpc --socket /tmp/capiscio.sock
capiscio rpc --address localhost:50051

Flags:

• --socket: Unix socket path (default: ~/.capiscio/rpc.sock).
• --address: TCP address to listen on (e.g., localhost:50051).

key gen

Generate a new cryptographic key pair.

capiscio key gen --out-priv private.jwk --out-pub public.jwk

Flags:

• --out-priv: Output path for private key (JWK format). Default: private.jwk.
• --out-pub: Output path for public key (JWK format). Default: public.jwk.

trust

Manage the local trust store.

capiscio trust add --from-jwks https://registry.capisc.io/.well-known/jwks.json
capiscio trust list
capiscio trust remove <kid>

validate

Validates an Agent Card file or URL.

capiscio validate ./agent-card.json

Flags:

• --json: Output results as JSON.
• --strict: Enable strict validation mode (fails on warnings).
• --test-live: Perform live availability checks.
• --skip-signature: Skip JWS signature verification.
• --schema-only: Validate schema only, skip endpoint testing.
• --errors-only: Show only errors and warnings.
• --timeout: Request timeout (default 10s).

Development

Prerequisites

• Go 1.25+

Testing

go test ./pkg/...

Building

go build ./cmd/capiscio

Working with capiscio-server

If you're developing capiscio-core alongside capiscio-server, use Go workspaces:

# In capiscio-server directory, create go.work (gitignored)
cd ../capiscio-server
cat > go.work << 'EOF'
go 1.25.9

use .
use ../capiscio-core
EOF

This allows capiscio-server to use your local capiscio-core changes without publishing.

Publishing a Release

When your changes are ready for capiscio-server CI/CD:

# 1. Commit your changes
git add -A && git commit -m "feat: your changes"

# 2. Tag with semantic version
git tag v2.2.4

# 3. Push commit and tag
git push origin main v2.2.4

# 4. Update capiscio-server to use the new version
cd ../capiscio-server
go get github.com/capiscio/capiscio-core/[email protected]

Version Guidelines:

• Patch (v2.2.x): Bug fixes, internal refactors
• Minor (v2.x.0): New features, backward-compatible API additions
• Major (vX.0.0): Breaking API changes (requires updating import path)

Related Packages

Package	What it does	Install
Agent Guard	Runtime trust verification for A2A agents (Python)	pip install capiscio-sdk
MCP Guard	Trust enforcement for MCP tool servers (Python)	pip install capiscio-mcp
CapiscIO CLI	Python wrapper for this binary	pip install capiscio

Documentation · Website · Platform

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.