pe

package
v1.0.1-0...-649cb91 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 12, 2026 License: GPL-3.0 Imports: 16 Imported by: 0

Documentation

Overview

Package pe stands for Presentation Exchange which includes Presentation Definition and Presentation Submission

Index

Constants

View Source
const (
	// WalletOwnerOrganization is used in a WalletOwnerMapping when the PresentationDefinition is intended for an organization
	WalletOwnerOrganization = WalletOwnerType("organization")
	// WalletOwnerUser is used in a WalletOwnerMapping when the PresentationDefinition is intended for a user
	WalletOwnerUser = WalletOwnerType("user")
)

Variables

View Source
var ErrMultipleCredentials = errors.New("multiple matching credentials")
View Source
var ErrNoCredentials = errors.New("missing credentials")
View Source
var ErrUnsupportedFilter = errors.New("unsupported filter")

ErrUnsupportedFilter is returned when a filter uses unsupported features.

Functions

func ChooseVPFormat

func ChooseVPFormat(formats map[string]map[string][]string) string

ChooseVPFormat determines the format of the Verifiable Presentation based on the authorization server metadata.

func FirstMatchSelector

func FirstMatchSelector(_ InputDescriptor, candidates []vc.VerifiableCredential) (*vc.VerifiableCredential, error)

FirstMatchSelector is the default CredentialSelector that picks the first matching credential. This preserves the existing behavior of matchConstraints.

Types

type Candidate

type Candidate struct {
	InputDescriptor InputDescriptor
	VC              *vc.VerifiableCredential
}

Candidate is a struct that holds the result of a match between an input descriptor and a VC A non-matching VC also leads to a Candidate, but without a VC.

type Constraints

type Constraints struct {
	Fields          []Field             `json:"fields,omitempty"`
	IsHolder        []*IsHolderItems    `json:"is_holder,omitempty"`
	LimitDisclosure string              `json:"limit_disclosure,omitempty"`
	SameSubject     []*SameSubjectItems `json:"same_subject,omitempty"`
	Statuses        *Statuses           `json:"statuses,omitempty"`
	SubjectIsIssuer string              `json:"subject_is_issuer,omitempty"`
}

Constraints

type CredentialSelector

type CredentialSelector func(descriptor InputDescriptor, candidates []vc.VerifiableCredential) (*vc.VerifiableCredential, error)

CredentialSelector picks one credential from a list of candidates that all match a given input descriptor. It is called by matchConstraints after collecting all matching VCs for an input descriptor.

Return values:

  • (*vc, nil): a credential was selected successfully.
  • (nil, nil): no credential was selected. The input descriptor is not fulfilled, which may be acceptable depending on submission requirements (e.g., pick rules with min: 0).
  • (nil, ErrNoCredentials): no candidates matched the selector's criteria. Treated as a soft failure: the input descriptor is not fulfilled, but submission requirements may still accept this (e.g., pick rules with min: 0).
  • (nil, ErrMultipleCredentials): multiple candidates matched but the selector requires exactly one. This is a hard failure — the match is aborted.
  • (nil, other error): any other error is a hard failure.

Selectors that are lenient (like FirstMatchSelector) may return (nil, nil) to let the caller decide.

func NewFieldSelector

func NewFieldSelector(selection map[string]string, pd PresentationDefinition) (CredentialSelector, error)

NewFieldSelector creates a CredentialSelector that filters candidates by matching PD field ID values from the credential_selection parameter. Only constant (equality) matching is supported; pattern-based filters are already evaluated by matchConstraint before the selector runs. Returns (nil, nil) for input descriptors without matching selection keys, signalling the builder to apply its default selector.

type Envelope

type Envelope struct {
	// Presentations contains the Verifiable Presentations that were parsed from the envelope.
	Presentations []vc.VerifiablePresentation
	// contains filtered or unexported fields
}

Envelope is a parsed Presentation Exchange envelope, containing zero or more Verifiable Presentations that are referenced by the Presentation Submission.

func ParseEnvelope

func ParseEnvelope(envelopeBytes []byte) (*Envelope, error)

ParseEnvelope parses a Presentation Exchange envelope, which is a JSON type that encompasses zero or more Verifiable Presentations. It returns the envelope as interface{} for use in PresentationSubmission.Validate() and PresentationSubmission.Resolve(). It also returns the parsed Verifiable Presentations. Parsing is complicated since a Presentation Submission has multiple ways to reference a Verifiable Credential: - single VP as JSON object: $.verifiableCredential - multiple VPs as JSON array (with path_nested): $[0] -> $.verifiableCredential And since JWT VPs aren't JSON objects, we need to parse them separately.

func (Envelope) MarshalJSON

func (e Envelope) MarshalJSON() ([]byte, error)

func (*Envelope) UnmarshalJSON

func (e *Envelope) UnmarshalJSON(bytes []byte) error

type Field

type Field struct {
	Id             *string  `json:"id,omitempty"`
	Optional       *bool    `json:"optional,omitempty"`
	Path           []string `json:"path"`
	Purpose        *string  `json:"purpose,omitempty"`
	Name           *string  `json:"name,omitempty"`
	IntentToRetain *bool    `json:"intent_to_retain,omitempty"`
	Filter         *Filter  `json:"filter,omitempty"`
}

Field describes a constraints field in a presentation definition's input descriptor. The predicate feature is not implemented

type Filter

type Filter struct {
	// Type is the type of field: string, number, boolean, array, object
	Type string `json:"type"`
	// Const is a constant value to match, currently only strings are supported
	Const *string `json:"const,omitempty"`
	// Enum is a list of values to match
	Enum []string `json:"enum,omitempty"`
	// Pattern is a pattern to match according to ECMA-262, section 21.2.1
	Pattern *string `json:"pattern,omitempty"`
}

Filter is a JSON Schema (without nesting)

type Frame

type Frame struct {
	AdditionalProperties map[string]interface{} `json:"-,omitempty"`
}

Frame

type InputDescriptor

type InputDescriptor struct {
	Constraints *Constraints                                   `json:"constraints"`
	Format      *PresentationDefinitionClaimFormatDesignations `json:"format,omitempty"`
	Group       []string                                       `json:"group,omitempty"`
	Id          string                                         `json:"id"`
	Name        string                                         `json:"name,omitempty"`
	Purpose     string                                         `json:"purpose,omitempty"`
}

InputDescriptor

type InputDescriptorMappingObject

type InputDescriptorMappingObject struct {
	Format     string                        `json:"format"`
	Id         string                        `json:"id"`
	Path       string                        `json:"path"`
	PathNested *InputDescriptorMappingObject `json:"path_nested,omitempty"`
}

InputDescriptorMappingObject

type IsHolderItems

type IsHolderItems struct {
	Directive string   `json:"directive"`
	FieldId   []string `json:"field_id"`
}

IsHolderItems

type PresentationContext

type PresentationContext struct {
	Index                  int
	PresentationSubmission *PresentationSubmission
}

PresentationContext is a helper struct to keep track of the index of the VP in the nested paths of a PresentationSubmission.

type PresentationDefinition

type PresentationDefinition struct {
	Format *PresentationDefinitionClaimFormatDesignations `json:"format,omitempty"`
	Frame  *Frame                                         `json:"frame,omitempty"`
	// Id is the id of the presentation definition, it must be unique within the context.
	Id               string             `json:"id"`
	InputDescriptors []*InputDescriptor `json:"input_descriptors"`
	// Name is the name of the presentation definition. Correlates to ID
	Name string `json:"name,omitempty"`
	// Purpose is the purpose of the presentation definition, what is it used for?
	Purpose                *string                  `json:"purpose,omitempty"`
	SubmissionRequirements []*SubmissionRequirement `json:"submission_requirements,omitempty"`
}

PresentationDefinition

func ParsePresentationDefinition

func ParsePresentationDefinition(raw []byte) (*PresentationDefinition, error)

ParsePresentationDefinition validates the given JSON and parses it into a PresentationDefinition. It returns an error if the JSON is invalid or doesn't match the JSON schema for a PresentationDefinition.

func (PresentationDefinition) CredentialsRequired

func (presentationDefinition PresentationDefinition) CredentialsRequired() bool

CredentialsRequired returns true if the presentation definition requires credentials. This is the case if there are any InputDescriptors with constraints and no SubmissionRequirements. Or if there are SubmissionRequirements with an "all" rule or a "pick" rule that requires credentials.

func (PresentationDefinition) Match

Match matches the VCs against the presentation definition. It returns the matching Verifiable Credentials and their mapping to the Presentation Definition. If the given credentials do not match the presentation definition, an error is returned. It implements §5 of the Presentation Exchange specification (v2.x.x pre-Draft, 2023-07-29) (https://identity.foundation/presentation-exchange/#presentation-definition) It supports the following: - ldp_vc format - jwt_vc format - pattern, const and enum only on string fields - number, boolean, array and string JSON schema types - Submission Requirements Feature ErrUnsupportedFilter is returned when a filter uses unsupported features. Other errors can be returned for faulty JSON paths or regex patterns.

func (PresentationDefinition) MatchWithSelector

func (presentationDefinition PresentationDefinition) MatchWithSelector(vcs []vc.VerifiableCredential, selector CredentialSelector) ([]vc.VerifiableCredential, []InputDescriptorMappingObject, error)

MatchWithSelector matches the VCs against the presentation definition using the provided CredentialSelector. The selector is called for each input descriptor with all matching VCs, and must pick one (or return nil).

func (PresentationDefinition) PresentationSubmissionBuilder

func (presentationDefinition PresentationDefinition) PresentationSubmissionBuilder() PresentationSubmissionBuilder

PresentationSubmissionBuilder returns a new PresentationSubmissionBuilder. A PresentationSubmissionBuilder can be used to create a PresentationSubmission with multiple wallets as input.

func (PresentationDefinition) ResolveConstraintsFields

func (presentationDefinition PresentationDefinition) ResolveConstraintsFields(credentialMap map[string]vc.VerifiableCredential) (map[string]interface{}, error)

ResolveConstraintsFields returns a map where each of the InputDescriptor constraints field is mapped, to the corresponding value from the Verifiable Credentials that map to the InputDescriptor. The credentialMap is a map with the InputDescriptor.Id as key and the VerifiableCredential as value. Constraints that contain no ID are ignored.

type PresentationDefinitionClaimFormatDesignations

type PresentationDefinitionClaimFormatDesignations map[string]map[string][]string

PresentationDefinitionClaimFormatDesignations (replaces generated one)

type PresentationSubmission

type PresentationSubmission struct {
	// Id is the id of the presentation submission, which is a UUID
	Id string `json:"id"`
	// DefinitionId is the id of the presentation definition that this submission is for
	DefinitionId string `json:"definition_id"`
	// DescriptorMap is a list of mappings from input descriptors to VCs
	DescriptorMap []InputDescriptorMappingObject `json:"descriptor_map,omitempty"`
}

PresentationSubmission describes how the VCs in the VP match the input descriptors in the PD

func ParsePresentationSubmission

func ParsePresentationSubmission(raw []byte) (*PresentationSubmission, error)

ParsePresentationSubmission validates the given JSON and parses it into a PresentationSubmission. It returns an error if the JSON is invalid or doesn't match the JSON schema for a PresentationSubmission.

func (PresentationSubmission) Resolve

Resolve returns a map where each of the input descriptors is mapped to the corresponding VerifiableCredential. If an input descriptor can't be mapped to a VC, an error is returned. This function is specified by https://identity.foundation/presentation-exchange/#processing-of-submission-entries

func (PresentationSubmission) Validate

Validate validates the Presentation Submission to the Verifiable Presentations and Presentation Definitions and returns the mapped credentials. The credentials will be returned as map with the InputDescriptor.Id as key. The Presentation Definitions are passed in the envelope, as specified by the PEX specification. It assumes credentials of the presentations only map in 1 way to the input descriptors.

type PresentationSubmissionBuilder

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

PresentationSubmissionBuilder is a builder for PresentationSubmissions. Multiple presentation definitions can be added to the builder.

func (*PresentationSubmissionBuilder) AddWallet

AddWallet adds credentials from a wallet that may be used to create the PresentationSubmission.

func (*PresentationSubmissionBuilder) Build

Build creates a PresentationSubmission from the added wallets. The VP format is determined by the given format.

func (*PresentationSubmissionBuilder) SetCredentialSelector

SetCredentialSelector configures a custom CredentialSelector for picking credentials when multiple match an input descriptor. If not set, FirstMatchSelector is used.

type SameSubjectItems

type SameSubjectItems struct {
	Directive string   `json:"directive"`
	FieldId   []string `json:"field_id"`
}

SameSubjectItems

type SignInstruction

type SignInstruction struct {
	// Holder contains the DID of the holder that should sign the VP.
	Holder did.DID
	// VerifiableCredentials contains the VCs that should be included in the VP.
	VerifiableCredentials []vc.VerifiableCredential
	// Mappings contains the Input Descriptor that are mapped by this SignInstruction.
	Mappings []InputDescriptorMappingObject
}

SignInstruction is a list of Holder/VCs combinations that can be used to create a VerifiablePresentation. When using multiple wallets, the outcome of a PresentationSubmission might require multiple VPs.

func (SignInstruction) Empty

func (signInstruction SignInstruction) Empty() bool

Empty returns true if there are no VCs in the SignInstruction.

type SignInstructions

type SignInstructions []SignInstruction

SignInstructions is a list of SignInstruction.

func (SignInstructions) Empty

func (signInstructions SignInstructions) Empty() bool

Empty returns true if all SignInstructions are empty.

type StatusDirective

type StatusDirective struct {
	Directive string   `json:"directive,omitempty"`
	Type      []string `json:"type,omitempty"`
}

StatusDirective

type Statuses

type Statuses struct {
	Active    *StatusDirective `json:"active,omitempty"`
	Revoked   *StatusDirective `json:"revoked,omitempty"`
	Suspended *StatusDirective `json:"suspended,omitempty"`
}

Statuses

type SubmissionRequirement

type SubmissionRequirement struct {
	Count      *int                     `json:"count,omitempty"`
	From       string                   `json:"from,omitempty"`
	FromNested []*SubmissionRequirement `json:"from_nested,omitempty"`
	Max        *int                     `json:"max,omitempty"`
	Min        *int                     `json:"min,omitempty"`
	Name       string                   `json:"name,omitempty"`
	Rule       string                   `json:"rule"`
}

SubmissionRequirement

type WalletOwnerMapping

type WalletOwnerMapping map[WalletOwnerType]PresentationDefinition

WalletOwnerMapping is a map of WalletOwnerType to PresentationDefinition

type WalletOwnerType

type WalletOwnerType string

WalletOwnerType defines the intended audience for a PresentationDefinition

Directories

Path Synopsis
schema module
v2
Package v2 implements v2.0.0 of the Presentation Exchange specification
Package v2 implements v2.0.0 of the Presentation Exchange specification

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL