Skip to content

Go API Reference

Auto-generated Documentation

This API reference is automatically generated from the Go source code in capiscio-core using gomarkdoc.

Regenerate: gomarkdoc ./pkg/... > docs/reference/go-api.md

Package: agentcard

import "github.com/capiscio/capiscio-core/pkg/agentcard"

Package agentcard defines the data structures for the A2A Agent Card.

Index

type AgentCapabilities

AgentCapabilities defines the capabilities supported by the agent.

type AgentCapabilities struct {
    Streaming              bool `json:"streaming,omitempty"`
    PushNotifications      bool `json:"pushNotifications,omitempty"`
    StateTransitionHistory bool `json:"stateTransitionHistory,omitempty"`
}

type AgentCard

AgentCard represents the A2A Agent Card structure based on v0.3.0 specification.

type AgentCard struct {
    ProtocolVersion                   string                    `json:"protocolVersion"`
    Name                              string                    `json:"name"`
    Description                       string                    `json:"description"`
    URL                               string                    `json:"url"`
    PreferredTransport                TransportProtocol         `json:"preferredTransport,omitempty"`
    AdditionalInterfaces              []AgentInterface          `json:"additionalInterfaces,omitempty"`
    Provider                          *AgentProvider            `json:"provider,omitempty"`
    IconURL                           string                    `json:"iconUrl,omitempty"`
    Version                           string                    `json:"version"`
    DocumentationURL                  string                    `json:"documentationUrl,omitempty"`
    Capabilities                      AgentCapabilities         `json:"capabilities"`
    SecuritySchemes                   map[string]SecurityScheme `json:"securitySchemes,omitempty"`
    Security                          []map[string][]string     `json:"security,omitempty"`
    DefaultInputModes                 []string                  `json:"defaultInputModes"`
    DefaultOutputModes                []string                  `json:"defaultOutputModes"`
    Skills                            []AgentSkill              `json:"skills"`
    SupportsAuthenticatedExtendedCard bool                      `json:"supportsAuthenticatedExtendedCard,omitempty"`
    Signatures                        []Signature               `json:"signatures,omitempty"`
    Extensions                        []AgentExtension          `json:"extensions,omitempty"`
}

type AgentExtension

AgentExtension defines an extension supported by the agent.

type AgentExtension struct {
    Name        string `json:"name"`
    Version     string `json:"version"`
    Description string `json:"description,omitempty"`
}

type AgentInterface

AgentInterface defines additional interfaces for the agent.

type AgentInterface struct {
    URL       string            `json:"url"`
    Transport TransportProtocol `json:"transport"`
}

type AgentProvider

AgentProvider contains information about the agent's provider.

type AgentProvider struct {
    Organization string `json:"organization"`
    URL          string `json:"url"`
}

type AgentSkill

AgentSkill defines a skill provided by the agent.

type AgentSkill struct {
    ID          string   `json:"id"`
    Name        string   `json:"name"`
    Description string   `json:"description"`
    Tags        []string `json:"tags"`
    Examples    []string `json:"examples,omitempty"`
    InputModes  []string `json:"inputModes,omitempty"`
    OutputModes []string `json:"outputModes,omitempty"`
}

type SecurityScheme

SecurityScheme defines the security schemes used by the agent.

type SecurityScheme struct {
    Type             string      `json:"type"`
    Scheme           string      `json:"scheme,omitempty"`
    BearerFormat     string      `json:"bearerFormat,omitempty"`
    OpenIDConnectURL string      `json:"openIdConnectUrl,omitempty"`
    Flows            interface{} `json:"flows,omitempty"` // Using interface{} as 'any'
}

type Signature

Signature represents a JWS signature on the Agent Card.

type Signature struct {
    Protected string `json:"protected"`
    Signature string `json:"signature"`
}

type TransportProtocol

TransportProtocol defines the supported transport protocols for A2A agents.

type TransportProtocol string

Supported Transport Protocols.

const (
    TransportJSONRPC  TransportProtocol = "JSONRPC"
    TransportGRPC     TransportProtocol = "GRPC"
    TransportHTTPJSON TransportProtocol = "HTTP+JSON"
)

badge

import "github.com/capiscio/capiscio-core/pkg/badge"

Package badge provides functionality for issuing and verifying Trust Badges.

Index

func SignBadge

func SignBadge(claims *Claims, privateKey crypto.PrivateKey) (string, error)

SignBadge creates a signed JWS token from the given claims using the private key. It defaults to EdDSA \(Ed25519\) signing.

type Claims

Claims represents the JWT claims payload for a CapiscIO Trust Badge. It follows the structure defined in the Minimal Authority Stack plan.

type Claims struct {
    // Issuer is the entity that issued the badge (e.g., "https://registry.capisc.io").
    Issuer string `json:"iss"`

    // Subject is the unique identifier of the Agent (e.g., "did:capiscio:agent:12345").
    Subject string `json:"sub"`

    // IssuedAt is the timestamp when the badge was issued (Unix timestamp).
    IssuedAt int64 `json:"iat"`

    // Expiry is the timestamp when the badge expires (Unix timestamp).
    Expiry int64 `json:"exp"`

    // Key is the public key of the subject, embedded for offline verification.
    Key *jose.JSONWebKey `json:"key,omitempty"`

    // VC contains the Verifiable Credential data.
    VC  VerifiableCredential `json:"vc"`
}

type CredentialSubject

CredentialSubject contains the specific claims.

type CredentialSubject struct {
    // Domain is the security domain of the agent (e.g., "finance.internal").
    Domain string `json:"domain,omitempty"`

    // Level indicates the trust level (e.g., "1" = Domain Validated).
    Level string `json:"level,omitempty"`
}

type Keeper

Keeper manages the lifecycle of a Trust Badge file.

type Keeper struct {
    // contains filtered or unexported fields
}

func NewKeeper

func NewKeeper(config KeeperConfig) *Keeper

NewKeeper creates a new Keeper.

func \(\*Keeper\) CheckAndRenew

func (k *Keeper) CheckAndRenew() error

CheckAndRenew checks if the badge needs renewal and renews it if necessary.

func \(\*Keeper\) Renew

func (k *Keeper) Renew() error

Renew generates a new badge and writes it to disk.

func \(\*Keeper\) Run

func (k *Keeper) Run(ctx context.Context) error

Run starts the keeper loop.

type KeeperConfig

KeeperConfig holds configuration for the Badge Keeper.

type KeeperConfig struct {
    PrivateKey    crypto.PrivateKey
    Claims        Claims
    OutputFile    string
    Expiry        time.Duration
    RenewBefore   time.Duration
    CheckInterval time.Duration
}

type VerifiableCredential

VerifiableCredential represents the simplified VC object.

type VerifiableCredential struct {
    // Type is the JSON-LD type(s) of the credential.
    Type []string `json:"type"`

    // CredentialSubject contains the claims about the subject.
    CredentialSubject CredentialSubject `json:"credentialSubject"`
}

type Verifier

Verifier validates TrustBadges.

type Verifier struct {
    // contains filtered or unexported fields
}

func NewVerifier

func NewVerifier(reg registry.Registry) *Verifier

NewVerifier creates a new Badge Verifier.

func \(\*Verifier\) Verify

func (v *Verifier) Verify(ctx context.Context, token string) (*Claims, error)

Verify checks the validity of a TrustBadge JWS token.

crypto

import "github.com/capiscio/capiscio-core/pkg/crypto"

Package crypto provides cryptographic utilities for CapiscIO.

Index

func CreateCanonicalJSON

func CreateCanonicalJSON(card *agentcard.AgentCard) ([]byte, error)

CreateCanonicalJSON creates a canonical JSON representation of the Agent Card for signature verification. It removes the "signatures" field and ensures keys are sorted \(which encoding/json does by default\).

type DefaultJWKSFetcher

DefaultJWKSFetcher is the default implementation of JWKSFetcher.

type DefaultJWKSFetcher struct {
    // contains filtered or unexported fields
}

func NewDefaultJWKSFetcher

func NewDefaultJWKSFetcher() *DefaultJWKSFetcher

NewDefaultJWKSFetcher creates a new fetcher with a default HTTP client and 1 hour cache TTL.

func \(\*DefaultJWKSFetcher\) Fetch

func (f *DefaultJWKSFetcher) Fetch(ctx context.Context, url string) (*jose.JSONWebKeySet, error)

Fetch retrieves the JWKS from the specified URL, using cache if available.

func \(\*DefaultJWKSFetcher\) FlushCache

func (f *DefaultJWKSFetcher) FlushCache()

FlushCache clears all cached JWKS entries.

func \(\*DefaultJWKSFetcher\) SetTTL

func (f *DefaultJWKSFetcher) SetTTL(ttl time.Duration)

SetTTL configures the cache time-to-live.

type JWKSFetcher

JWKSFetcher handles fetching and caching of JSON Web Key Sets.

type JWKSFetcher interface {
    Fetch(ctx context.Context, url string) (*jose.JSONWebKeySet, error)
}

type SignatureResult

SignatureResult holds the details of a single signature verification.

type SignatureResult struct {
    Index     int
    Valid     bool
    Algorithm string
    KeyID     string
    Issuer    string
    JWKSUri   string
    Error     string
}

type SignatureVerificationResult

SignatureVerificationResult contains the result of verifying all signatures.

type SignatureVerificationResult struct {
    Valid      bool
    Signatures []SignatureResult
    Summary    VerificationSummary
}

type VerificationSummary

VerificationSummary summarizes the results of all signature verifications.

type VerificationSummary struct {
    Total  int
    Valid  int
    Failed int
    Errors []string
}

type Verifier

Verifier handles Agent Card signature verification.

type Verifier struct {
    // contains filtered or unexported fields
}

func NewVerifier

func NewVerifier() *Verifier

NewVerifier creates a new Verifier with the default JWKS fetcher.

func NewVerifierWithFetcher

func NewVerifierWithFetcher(fetcher JWKSFetcher) *Verifier

NewVerifierWithFetcher creates a new Verifier with a custom JWKS fetcher.

func \(\*Verifier\) VerifyAgentCardSignatures

func (v *Verifier) VerifyAgentCardSignatures(ctx context.Context, card *agentcard.AgentCard) (*SignatureVerificationResult, error)

VerifyAgentCardSignatures verifies all signatures in an Agent Card.

gateway

import "github.com/capiscio/capiscio-core/pkg/gateway"

Package gateway provides the HTTP middleware for the CapiscIO Security Sidecar.

Index

func ExtractBadge

func ExtractBadge(r *http.Request) string

ExtractBadge retrieves the badge from headers.

func NewAuthMiddleware

func NewAuthMiddleware(verifier *badge.Verifier, next http.Handler) http.Handler

NewAuthMiddleware creates a middleware that enforces Badge validity.

protocol

import "github.com/capiscio/capiscio-core/pkg/protocol"

Package protocol defines the interfaces and implementations for communicating with A2A agents.

Index

type Client

Client defines the interface for an A2A protocol client.

type Client interface {
    // Ping checks if the agent is reachable and responsive.
    // Returns the latency and any error encountered.
    Ping(ctx context.Context) (time.Duration, error)

    // Close cleans up any resources used by the client.
    Close() error
}

type HTTPClient

HTTPClient implements the Client interface for HTTP+JSON transport.

type HTTPClient struct {
    // contains filtered or unexported fields
}

func NewHTTPClient

func NewHTTPClient(url string) *HTTPClient

NewHTTPClient creates a new HTTPClient.

func \(\*HTTPClient\) Close

func (c *HTTPClient) Close() error

Close cleans up resources.

func \(\*HTTPClient\) Ping

func (c *HTTPClient) Ping(ctx context.Context) (time.Duration, error)

Ping performs a simple GET request to the agent URL to check availability. It attempts to call 'GET /tasks' which is a standard v0.3.0 endpoint.

type JSONRPCClient

JSONRPCClient implements the Client interface for JSON-RPC transport over HTTP.

type JSONRPCClient struct {
    // contains filtered or unexported fields
}

func NewJSONRPCClient

func NewJSONRPCClient(url string) *JSONRPCClient

NewJSONRPCClient creates a new JSONRPCClient.

func \(\*JSONRPCClient\) Close

func (c *JSONRPCClient) Close() error

Close cleans up resources.

func \(\*JSONRPCClient\) Ping

func (c *JSONRPCClient) Ping(ctx context.Context) (time.Duration, error)

Ping sends a standard JSON-RPC request to check availability. It attempts to call 'tasks/list' which is a standard v0.3.0 method. Even if the method returns an empty list or an error \(e.g. auth\), a valid JSON-RPC response indicates the agent is alive.

registry

import "github.com/capiscio/capiscio-core/pkg/registry"

Package registry implements the Trust Registry interface for key retrieval.

Index

type CloudRegistry

CloudRegistry implements Registry by fetching keys from a URL.

type CloudRegistry struct {
    RegistryURL string
    Client      *http.Client
    // contains filtered or unexported fields
}

func NewCloudRegistry

func NewCloudRegistry(url string) *CloudRegistry

NewCloudRegistry creates a new CloudRegistry.

func \(\*CloudRegistry\) GetPublicKey

func (r *CloudRegistry) GetPublicKey(ctx context.Context, issuer string) (crypto.PublicKey, error)

GetPublicKey fetches the key from the Registry URL. It assumes the URL returns a single JWK for now \(MVP\).

func \(\*CloudRegistry\) IsRevoked

func (r *CloudRegistry) IsRevoked(_ context.Context, _ string) (bool, error)

IsRevoked checks revocation \(not implemented for MVP\).

type LocalRegistry

LocalRegistry implements Registry using a local file.

type LocalRegistry struct {
    KeyPath string
    // contains filtered or unexported fields
}

func NewLocalRegistry

func NewLocalRegistry(path string) *LocalRegistry

NewLocalRegistry creates a new LocalRegistry.

func \(\*LocalRegistry\) GetPublicKey

func (r *LocalRegistry) GetPublicKey(_ context.Context, _ string) (crypto.PublicKey, error)

GetPublicKey reads the key from the local file. It ignores the issuer argument for the MVP \(trusts the local key for all\).

func \(\*LocalRegistry\) IsRevoked

func (r *LocalRegistry) IsRevoked(_ context.Context, _ string) (bool, error)

IsRevoked checks if the ID is in the local blocklist \(not implemented yet\).

type Registry

Registry defines the interface for the CapiscIO Trust Registry. It is responsible for resolving trusted public keys for Issuers.

type Registry interface {
    // GetPublicKey fetches the public key for a given Issuer DID/URI.
    // Returns the public key and any error encountered.
    GetPublicKey(ctx context.Context, issuerDID string) (crypto.PublicKey, error)

    // IsRevoked checks if a specific Badge ID (or Subject) has been revoked.
    IsRevoked(ctx context.Context, badgeID string) (bool, error)
}

report

import "github.com/capiscio/capiscio-core/pkg/report"

Package report defines the structures for validation and scoring reports.

Index

type AvailabilityResult

AvailabilityResult contains the results of availability testing.

type AvailabilityResult struct {
    Score       float64 `json:"score"`
    Tested      bool    `json:"tested"`
    EndpointURL string  `json:"endpointUrl,omitempty"`
    LatencyMS   int64   `json:"latencyMs,omitempty"`
    Error       string  `json:"error,omitempty"`
}

type ValidationIssue

ValidationIssue represents a specific problem found during validation.

type ValidationIssue struct {
    Code     string `json:"code"`
    Message  string `json:"message"`
    Severity string `json:"severity"` // "error", "warning", "info"
    Field    string `json:"field,omitempty"`
}

type ValidationResult

ValidationResult contains the complete results of an Agent Card validation.

type ValidationResult struct {
    Success         bool                                `json:"success"`
    ComplianceScore float64                             `json:"complianceScore"`
    TrustScore      float64                             `json:"trustScore"`
    Availability    AvailabilityResult                  `json:"availability"`
    Issues          []ValidationIssue                   `json:"issues"`
    Signatures      *crypto.SignatureVerificationResult `json:"signatures,omitempty"`
}

func \(\*ValidationResult\) AddError

func (r *ValidationResult) AddError(code, message, field string)

AddError adds an error issue to the result.

func \(\*ValidationResult\) AddWarning

func (r *ValidationResult) AddWarning(code, message, field string)

AddWarning adds a warning issue to the result.

scoring

import "github.com/capiscio/capiscio-core/pkg/scoring"

Package scoring implements the validation and scoring logic for Agent Cards.

Index

type AvailabilityScorer

AvailabilityScorer evaluates the operational status of the agent.

type AvailabilityScorer struct {
    // contains filtered or unexported fields
}

func NewAvailabilityScorer

func NewAvailabilityScorer(timeout time.Duration) *AvailabilityScorer

NewAvailabilityScorer creates a new AvailabilityScorer.

func \(\*AvailabilityScorer\) Score

func (s *AvailabilityScorer) Score(ctx context.Context, card *agentcard.AgentCard) report.AvailabilityResult

Score checks the agent's endpoint and calculates an availability score.

type ComplianceConfig

ComplianceConfig holds configuration for the ComplianceScorer.

type ComplianceConfig struct {
    AllowPrivateIPs bool
}

type ComplianceScorer

ComplianceScorer evaluates how well the Agent Card adheres to the A2A specification.

type ComplianceScorer struct {
    // contains filtered or unexported fields
}

func NewComplianceScorer

func NewComplianceScorer(config *ComplianceConfig) *ComplianceScorer

NewComplianceScorer creates a new ComplianceScorer.

func \(\*ComplianceScorer\) Score

func (s *ComplianceScorer) Score(card *agentcard.AgentCard) (float64, []report.ValidationIssue)

Score calculates the compliance score \(0\-100\) and identifies issues.

type Engine

Engine is the main entry point for scoring and validation.

type Engine struct {
    // contains filtered or unexported fields
}

func NewEngine

func NewEngine(config *EngineConfig) *Engine

NewEngine creates a new scoring Engine with the provided configuration. If config is nil, default configuration is used.

func \(\*Engine\) Validate

func (e *Engine) Validate(ctx context.Context, card *agentcard.AgentCard, checkAvailability bool) (*report.ValidationResult, error)

Validate performs a full validation of the Agent Card.

type EngineConfig

EngineConfig holds configuration for the scoring Engine.

type EngineConfig struct {
    // TrustedIssuers is a list of trusted JWKS URIs or Issuer IDs.
    // If empty, all valid signatures are considered "trusted" (low security mode).
    TrustedIssuers []string

    // JWKSCacheTTL is the time-to-live for cached JWKS. Default: 1 hour.
    JWKSCacheTTL time.Duration

    // HTTPTimeout is the timeout for availability checks. Default: 5 seconds.
    HTTPTimeout time.Duration

    // Mode determines the validation strictness. Default: ModeProgressive.
    Mode ValidationMode

    // SkipSignatureVerification disables JWS signature verification.
    SkipSignatureVerification bool

    // SchemaOnly skips logic and network checks, validating only the JSON structure.
    SchemaOnly bool

    // RegistryReady enables additional checks required for registry submission.
    RegistryReady bool

    // AllowPrivateIPs allows URLs to resolve to private IP addresses.
    AllowPrivateIPs bool
}

func DefaultEngineConfig

func DefaultEngineConfig() *EngineConfig

DefaultEngineConfig returns a default configuration.

type TrustScorer

TrustScorer evaluates the trustworthiness of the Agent Card.

type TrustScorer struct {
    // contains filtered or unexported fields
}

func NewTrustScorer

func NewTrustScorer(trustedIssuers []string) *TrustScorer

NewTrustScorer creates a new TrustScorer with optional trusted issuers.

func \(\*TrustScorer\) Score

func (s *TrustScorer) Score(sigResult *crypto.SignatureVerificationResult) (float64, []report.ValidationIssue)

Score calculates the trust score \(0\-100\) based on signatures and other factors.

type URLValidator

URLValidator validates URLs for security and compliance.

type URLValidator struct {
    AllowPrivateIPs bool
}

func NewURLValidator

func NewURLValidator(allowPrivateIPs bool) *URLValidator

NewURLValidator creates a new URLValidator.

func \(\*URLValidator\) Validate

func (v *URLValidator) Validate(rawURL string, fieldName string) []report.ValidationIssue

Validate checks if a URL is valid and secure.

type ValidationMode

ValidationMode determines the strictness of the validation.

type ValidationMode string


const (
    // ModeProgressive is the default mode. Standard checks, allows some warnings.
    ModeProgressive ValidationMode = "progressive"
    // ModeStrict fails on ANY warning or error.
    ModeStrict ValidationMode = "strict"
)

Generated by gomarkdoc