trustapi

Documentation

Overview

Package trustapi provides common interfaces and types for trust evaluation.

This package defines the contract between trust evaluation consumers (verifiers, issuers, wallets) and providers (go-trust PDP, local trust anchors). It does not include implementations - those live in the consuming applications.

Key concepts:

• TrustEvaluator: Evaluates whether a name-to-key binding is trusted
• KeyResolver: Resolves public keys from identifiers (DIDs, URLs)
• EvaluationRequest: Contains subject, key, and optional role/context
• TrustDecision: The evaluation result with reason and metadata

This package is intentionally minimal to avoid coupling go-trust to specific credential formats or application concerns.

Index

• type CombinedTrustService
• type EvaluationRequest
• type KeyResolver
• type KeyType
• type Role
• type TrustDecision
• type TrustEvaluator
• type TrustOptions
• type X5CCertChain
  • func (c X5CCertChain) GetLeafCert() *x509.Certificate
  • func (c X5CCertChain) GetRootCert() *x509.Certificate
  • func (c X5CCertChain) GetSubjectID() string
  • func (c X5CCertChain) ToBase64Strings() []string

Types

type CombinedTrustService

type CombinedTrustService interface {
	TrustEvaluator
	KeyResolver
}

CombinedTrustService combines evaluation and resolution capabilities. This is the full interface for trust management across all credential formats.

type EvaluationRequest

type EvaluationRequest struct {
	// SubjectID is the identifier of the entity (DID, issuer URL, etc.).
	SubjectID string

	// KeyType indicates the format of the key.
	KeyType KeyType

	// Key is the public key to validate. Can be:
	//   - map[string]any for JWK
	//   - []*x509.Certificate for x5c
	//   - crypto.PublicKey for raw keys
	Key any

	// Role is the expected role (optional). Implementations may map this
	// to action.name when using AuthZEN, enabling policy-based routing.
	Role Role

	// Action is an explicit policy name to use (optional).
	// If set, this takes precedence over Role.
	Action string

	// CredentialType is the type of credential (e.g., "PID", "mDL", "VerifiableCredential").
	// This can influence policy selection when combined with Role.
	CredentialType string

	// DocType is the ISO mDOC document type (for mDOC credentials).
	DocType string

	// Options contains additional trust evaluation options.
	Options *TrustOptions
}

EvaluationRequest contains the parameters for a trust evaluation.

type KeyResolver

type KeyResolver interface {
	// ResolveKey retrieves the public key for the given verification method.
	// The verificationMethod is typically a DID URL (e.g., "did:web:example.com#key-1").
	ResolveKey(ctx context.Context, verificationMethod string) (crypto.PublicKey, error)
}

KeyResolver resolves public keys from identifiers. This is used when the key needs to be fetched (DID-based credentials).

type KeyType

type KeyType string

KeyType indicates the format of the public key being validated.

const (
	// KeyTypeJWK indicates a JWK (JSON Web Key) format key.
	KeyTypeJWK KeyType = "jwk"
	// KeyTypeX5C indicates an X.509 certificate chain.
	KeyTypeX5C KeyType = "x5c"
)

type Role

type Role string

Role represents the expected role of the key holder. These are common roles; applications may define additional roles.

const (
	// RoleIssuer indicates the key should be authorized for credential issuance.
	RoleIssuer Role = "issuer"
	// RoleVerifier indicates the key should be authorized for credential verification.
	RoleVerifier Role = "verifier"
	// RoleWalletProvider indicates the key is for a wallet provider.
	RoleWalletProvider Role = "wallet_provider"
	// RolePIDProvider indicates the key is for a PID (Person Identification Data) provider.
	RolePIDProvider Role = "pid-provider"
	// RoleCredentialIssuer indicates an OpenID4VCI credential issuer.
	RoleCredentialIssuer Role = "credential-issuer"
	// RoleCredentialVerifier indicates an OpenID4VP credential verifier.
	RoleCredentialVerifier Role = "credential-verifier"
	// RoleAny indicates no specific role constraint.
	RoleAny Role = ""
)

type TrustDecision

type TrustDecision struct {
	// Trusted indicates whether the name-to-key binding is authorized.
	Trusted bool

	// Reason provides explanation for the decision.
	Reason string

	// TrustFramework identifies which trust framework was used (e.g., "eudi", "openid_federation").
	TrustFramework string

	// Metadata contains additional trust metadata (e.g., DID document, entity configuration).
	Metadata any
}

TrustDecision represents the result of a trust evaluation.

type TrustEvaluator

type TrustEvaluator interface {
	// Evaluate checks if the given key is trusted for the specified subject and role.
	// Returns a TrustDecision indicating whether the binding is trusted.
	// Should not return an error for "not trusted" cases; use Trusted=false.
	Evaluate(ctx context.Context, req *EvaluationRequest) (*TrustDecision, error)

	// SupportsKeyType returns true if this evaluator can handle the given key type.
	SupportsKeyType(kt KeyType) bool

	// Name returns a human-readable name for this evaluator.
	Name() string

	// Healthy returns true if the evaluator is operational.
	// For remote evaluators, this indicates connectivity to the backend.
	Healthy() bool
}

TrustEvaluator evaluates whether a name-to-key binding is trusted.

Implementations can use:

• go-trust AuthZEN client (for federation/trust framework queries)
• Local trust lists (for offline validation against configured anchors)
• Composite evaluators (try multiple sources)

This interface supports validation scenarios where the key is already known (SD-JWT x5c, mDOC certificates). For DID-based credentials where the key must be fetched, use KeyResolver.

type TrustOptions

type TrustOptions struct {
	// IncludeTrustChain requests the full trust chain in the response.
	IncludeTrustChain bool

	// IncludeCertificates requests X.509 certificates in the response.
	IncludeCertificates bool

	// BypassCache requests that cached results be bypassed.
	BypassCache bool
}

TrustOptions contains additional options for trust evaluation.

type X5CCertChain

type X5CCertChain []*x509.Certificate

X5CCertChain is a helper type for x5c certificate chains.

func (X5CCertChain) GetLeafCert

func (c X5CCertChain) GetLeafCert() *x509.Certificate

GetLeafCert returns the end-entity certificate (first in chain).

func (X5CCertChain) GetRootCert

func (c X5CCertChain) GetRootCert() *x509.Certificate

GetRootCert returns the root certificate (last in chain).

func (X5CCertChain) GetSubjectID

func (c X5CCertChain) GetSubjectID() string

GetSubjectID extracts a subject identifier from the leaf certificate. Returns the Subject CN or the first SAN URI/DNS name.

func (X5CCertChain) ToBase64Strings

func (c X5CCertChain) ToBase64Strings() []string

ToBase64Strings converts the certificate chain to base64-encoded DER strings. This is the format expected by JWK x5c arrays and AuthZEN x5c resources.