simpleguard

Documentation

Index

• Constants
• Variables
• func Middleware(guard *SimpleGuard) func(http.Handler) http.Handler
• func SubjectFromContext(ctx context.Context) string
• type Claims
  • func ClaimsFromContext(ctx context.Context) *Claims
• type Config
• type SimpleGuard
  • func New(cfg Config) (*SimpleGuard, error)
  • func (g *SimpleGuard) SignOutbound(claims Claims, body []byte) (string, error)
  • func (g *SimpleGuard) VerifyInbound(token string, body []byte) (*Claims, error)

Constants

const (
	ContextKeySubject contextKey = "capiscio-subject"
	ContextKeyClaims  contextKey = "capiscio-claims"
)

const (
	// DefaultMaxTokenAge is the default token validity window (60 seconds).
	// This can be overridden via Config.MaxTokenAge.
	DefaultMaxTokenAge = 60 * time.Second

	// DefaultClockSkewTolerance is the allowed clock drift between parties (5 seconds).
	// This accounts for minor time synchronization differences between systems.
	DefaultClockSkewTolerance = 5 * time.Second

	// DefaultMaxBodySize is the maximum request body size for middleware (10MB).
	// Requests larger than this will be rejected to prevent memory exhaustion.
	DefaultMaxBodySize = 10 << 20 // 10MB
)

Default configuration values.

const MaxTokenAge = 60 * time.Second

MaxTokenAge is kept for backward compatibility. Use Config.MaxTokenAge instead. Deprecated: Use DefaultMaxTokenAge or Config.MaxTokenAge.

Variables

var (
	ErrMissingHeader    = errors.New("missing X-Capiscio-Badge header")
	ErrInvalidToken     = errors.New("invalid token format")
	ErrTokenExpired     = errors.New("token expired")
	ErrTokenFuture      = errors.New("token issued in the future")
	ErrIntegrityFailed  = errors.New("integrity check failed (body hash mismatch)")
	ErrMissingKeyID     = errors.New("missing kid header")
	ErrUntrustedKey     = errors.New("untrusted key ID")
	ErrSignatureInvalid = errors.New("signature verification failed")
)

Functions

func Middleware

func Middleware(guard *SimpleGuard) func(http.Handler) http.Handler

Middleware creates a net/http middleware for SimpleGuard.

func SubjectFromContext

func SubjectFromContext(ctx context.Context) string

SubjectFromContext retrieves the verified subject from the request context. Returns empty string if not found.

Types

type Claims

type Claims struct {
	Subject   string `json:"sub"`
	Issuer    string `json:"iss"`
	IssuedAt  int64  `json:"iat"`
	Expiry    int64  `json:"exp"`
	BodyHash  string `json:"bh,omitempty"`
	MessageID string `json:"jti,omitempty"`
}

Claims represents the JWT claims for SimpleGuard.

func ClaimsFromContext

func ClaimsFromContext(ctx context.Context) *Claims

ClaimsFromContext retrieves the verified claims from the request context. Returns nil if not found.

type Config

type Config struct {
	AgentID    string
	PrivateKey crypto.PrivateKey
	PublicKey  crypto.PublicKey
	KeyID      string // kid for the header
	DevMode    bool   // If true, allows self-signed/generated keys

	// MaxTokenAge is the token validity window. Defaults to DefaultMaxTokenAge (60s).
	MaxTokenAge time.Duration

	// ClockSkewTolerance is the allowed clock drift. Defaults to DefaultClockSkewTolerance (5s).
	ClockSkewTolerance time.Duration

	// MaxBodySize is the maximum request body size for middleware. Defaults to DefaultMaxBodySize (10MB).
	MaxBodySize int64
}

Config holds configuration for SimpleGuard.

type SimpleGuard

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

SimpleGuard handles A2A security enforcement.

func New

func New(cfg Config) (*SimpleGuard, error)

New creates a new SimpleGuard instance.

func (*SimpleGuard) SignOutbound

func (g *SimpleGuard) SignOutbound(claims Claims, body []byte) (string, error)

SignOutbound creates a signed JWS for the given payload and body. It enforces iat and exp to prevent backdating.

func (*SimpleGuard) VerifyInbound

func (g *SimpleGuard) VerifyInbound(token string, body []byte) (*Claims, error)

VerifyInbound validates a received JWS token.