agent

Documentation

Overview

Package agent provides a high-level DIDComm agent implementation.

The Agent is the main entry point for DIDComm messaging. It coordinates:

• Message creation and sending
• Message receiving and processing
• Protocol dispatching
• Key management integration

Basic Usage

// Create an agent
agent, err := agent.New(
	agent.WithDID("did:example:alice"),
	agent.WithResolver(resolver),
	agent.WithKeyStore(keyStore),
)

// Send a message
response, err := agent.Send(ctx, "did:example:bob", message)

// Register protocol handlers
agent.RegisterHandler("https://didcomm.org/trust-ping/2.0/ping", pingHandler)

Processing Incoming Messages

// Use the agent as an HTTP handler
http.Handle("/didcomm", agent.HTTPHandler())

Protocol Support

The agent includes built-in support for:

• Trust Ping (connectivity testing)
• Discover Features (capability discovery)
• Out-of-Band (connection bootstrapping)

Index

• Variables
• type Agent
  • func New(opts ...Option) (*Agent, error)
  • func (a *Agent) DID() string
  • func (a *Agent) DiscoverFeatures(ctx context.Context, to string, pattern string) (*discoverfeatures.DiscloseBody, error)
  • func (a *Agent) HTTPHandler() http.Handler
  • func (a *Agent) ProcessMessage(ctx context.Context, data []byte, mediaType string) ([]byte, string, error)
  • func (a *Agent) RegisterHandler(messageType string, handler MessageHandler)
  • func (a *Agent) RegisterProtocol(uri string, roles ...string)
  • func (a *Agent) Send(ctx context.Context, to string, msg *message.Message) (*message.Message, error)
  • func (a *Agent) SendTrustPing(ctx context.Context, to string, responseRequested bool) (*message.Message, error)
• type EndpointResolver
• type KeyResolver
• type KeyStore
• type MessageHandler
• type Option
  • func WithDID(did string) Option
  • func WithEndpointResolver(er EndpointResolver) Option
  • func WithHTTPClient(client *transport.HTTPClient) Option
  • func WithKeyResolver(kr KeyResolver) Option
  • func WithKeyStore(ks KeyStore) Option

Variables

var (
	// ErrAgentNotInitialized indicates the agent is not properly initialized.
	ErrAgentNotInitialized = errors.New("didcomm/agent: not initialized")

	// ErrNoPrivateKey indicates no private key is available for signing/decryption.
	ErrNoPrivateKey = errors.New("didcomm/agent: no private key available")

	// ErrNoDID indicates no DID is configured.
	ErrNoDID = errors.New("didcomm/agent: no DID configured")

	// ErrNoResolver indicates no resolver is configured.
	ErrNoResolver = errors.New("didcomm/agent: no resolver configured")

	// ErrNoEndpoint indicates no endpoint could be found for the recipient.
	ErrNoEndpoint = errors.New("didcomm/agent: no endpoint found for recipient")

	// ErrNoHandler indicates no handler is registered for the message type.
	ErrNoHandler = errors.New("didcomm/agent: no handler for message type")

	// ErrProcessingFailed indicates message processing failed.
	ErrProcessingFailed = errors.New("didcomm/agent: processing failed")
)

Agent errors

Types

type Agent

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

Agent is a high-level DIDComm messaging agent.

func New

func New(opts ...Option) (*Agent, error)

New creates a new DIDComm agent.

func (*Agent) DID

func (a *Agent) DID() string

DID returns the agent's DID.

func (*Agent) DiscoverFeatures

func (a *Agent) DiscoverFeatures(ctx context.Context, to string, pattern string) (*discoverfeatures.DiscloseBody, error)

DiscoverFeatures queries the recipient for supported features.

func (*Agent) HTTPHandler

func (a *Agent) HTTPHandler() http.Handler

HTTPHandler returns an HTTP handler for receiving messages.

func (*Agent) ProcessMessage

func (a *Agent) ProcessMessage(ctx context.Context, data []byte, mediaType string) ([]byte, string, error)

ProcessMessage processes an incoming message.

func (*Agent) RegisterHandler

func (a *Agent) RegisterHandler(messageType string, handler MessageHandler)

RegisterHandler registers a handler for a message type.

func (*Agent) RegisterProtocol

func (a *Agent) RegisterProtocol(uri string, roles ...string)

RegisterProtocol registers a protocol for feature discovery.

func (*Agent) Send

func (a *Agent) Send(ctx context.Context, to string, msg *message.Message) (*message.Message, error)

Send sends a message to the recipient.

func (*Agent) SendTrustPing

func (a *Agent) SendTrustPing(ctx context.Context, to string, responseRequested bool) (*message.Message, error)

SendTrustPing sends a trust ping to the recipient.

type EndpointResolver

type EndpointResolver interface {
	// ResolveEndpoint returns the DIDComm service endpoint for a DID.
	ResolveEndpoint(ctx context.Context, did string) (string, error)
}

EndpointResolver resolves DID service endpoints.

type KeyResolver

type KeyResolver interface {
	// ResolveKeyAgreement returns key agreement keys for encryption.
	ResolveKeyAgreement(ctx context.Context, did string) ([]jwk.Key, error)

	// ResolveVerification returns verification keys for signature verification.
	ResolveVerification(ctx context.Context, did string) ([]jwk.Key, error)
}

KeyResolver resolves public keys for a DID.

type KeyStore

type KeyStore interface {
	// GetPrivateKey returns the private key for the given key ID.
	GetPrivateKey(ctx context.Context, kid string) (jwk.Key, error)
}

KeyStore provides access to private keys.

type MessageHandler

type MessageHandler func(ctx context.Context, msg *message.Message) (*message.Message, error)

MessageHandler handles incoming DIDComm messages.

type Option

type Option func(*Agent)

Option configures the agent.

func WithDID

func WithDID(did string) Option

WithDID sets the agent's DID.

func WithEndpointResolver

func WithEndpointResolver(er EndpointResolver) Option

WithEndpointResolver sets the endpoint resolver.

func WithHTTPClient

func WithHTTPClient(client *transport.HTTPClient) Option

WithHTTPClient sets the HTTP client for sending messages.

func WithKeyResolver

func WithKeyResolver(kr KeyResolver) Option

WithKeyResolver sets the key resolver for public keys.

func WithKeyStore

func WithKeyStore(ks KeyStore) Option

WithKeyStore sets the key store for private key access.