@gramota/presentation-exchange

DIF Presentation Exchange v2 — legacy OID4VP 1.0 query format.

Install: pnpm add @gramota/presentation-exchange

Source: github.com/gramota-org/gramota/tree/main/packages/presentation-exchange

Classes

SdJwtVcMatcher

Defined in: @gramota/presentation-exchange/dist/sd-jwt-vc-matcher.d.ts:12

Match SD-JWT-VC credentials against a Presentation Definition descriptor.

Implements

• CredentialMatcher<SdJwtVcCredentialView>

Constructors

Constructor

new SdJwtVcMatcher(): SdJwtVcMatcher;

Returns

SdJwtVcMatcher

Properties

format

readonly format: "vc+sd-jwt" = "vc+sd-jwt";

Defined in: @gramota/presentation-exchange/dist/sd-jwt-vc-matcher.d.ts:13

Stable format identifier (e.g. "vc+sd-jwt").

Implementation of

CredentialMatcher.format

Methods

appliesTo()

appliesTo(descriptor: InputDescriptor): boolean;

Defined in: @gramota/presentation-exchange/dist/sd-jwt-vc-matcher.d.ts:14

Decide whether the descriptor's format/alg constraints apply to this credential type.

Parameters

descriptor

InputDescriptor

Returns

boolean

Implementation of

CredentialMatcher.appliesTo

match()

match(credential: SdJwtVcCredentialView, descriptor: InputDescriptor): MatchResult;

Defined in: @gramota/presentation-exchange/dist/sd-jwt-vc-matcher.d.ts:15

Evaluate the credential against the descriptor. Returns the disclosure names this descriptor would require, or null if no match.

Parameters

credential

SdJwtVcCredentialView

descriptor

InputDescriptor

Returns

MatchResult

Implementation of

CredentialMatcher.match

---

PresentationExchangeError

Defined in: @gramota/presentation-exchange/dist/types.d.ts:113

Extends

• GramotaError

Constructors

Constructor

new PresentationExchangeError(
   code: PresentationExchangeErrorCode, 
   message: string, 
   options?: {
  cause?: unknown;
}): PresentationExchangeError;

Defined in: @gramota/presentation-exchange/dist/types.d.ts:115

Parameters

code

PresentationExchangeErrorCode

message

string

options?

cause?

unknown

Returns

PresentationExchangeError

Overrides

GramotaError.constructor

Properties

cause?

readonly optional cause?: unknown;

Defined in: .pnpm/@gramota+core@0.2.1/node_modules/@gramota/core/dist/error.d.ts:44

Optional original error that caused this one. Always set when the Gramota package is wrapping a thrown exception from a dependency (Web Crypto, JOSE, fetch). Survives JSON.stringify(err) only via the cause property — Node 16.9+ logs it natively.

Inherited from

GramotaError.cause

code

readonly code: PresentationExchangeErrorCode;

Defined in: @gramota/presentation-exchange/dist/types.d.ts:114

Stable string that identifies the failure mode. Subclasses narrow the type; at runtime it's always a string. Use for branching, logs, and metrics labels — never serialize GramotaError.message for that purpose, message strings drift across versions.

Overrides

GramotaError.code

name

name: string;

Defined in: .pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from

GramotaError.name

message

message: string;

Defined in: .pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1077

Inherited from

GramotaError.message

stack?

optional stack?: string;

Defined in: .pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1078

Inherited from

GramotaError.stack

Interfaces

CredentialMatcher

Defined in: @gramota/presentation-exchange/dist/matcher.d.ts:4

A credential matcher per credential format. New formats (W3C VC, mdoc) can plug in new implementations of this interface — Strategy pattern.

Type Parameters

TCredential

TCredential

Properties

format

readonly format: string;

Defined in: @gramota/presentation-exchange/dist/matcher.d.ts:6

Stable format identifier (e.g. "vc+sd-jwt").

Methods

appliesTo()

appliesTo(descriptor: InputDescriptor): boolean;

Defined in: @gramota/presentation-exchange/dist/matcher.d.ts:9

Decide whether the descriptor's format/alg constraints apply to this credential type.

Parameters

descriptor

InputDescriptor

Returns

boolean

match()

match(credential: TCredential, descriptor: InputDescriptor): MatchResult;

Defined in: @gramota/presentation-exchange/dist/matcher.d.ts:12

Evaluate the credential against the descriptor. Returns the disclosure names this descriptor would require, or null if no match.

Parameters

credential

TCredential

descriptor

InputDescriptor

Returns

MatchResult

---

MatchResult

Defined in: @gramota/presentation-exchange/dist/matcher.d.ts:14

Properties

disclose

disclose: readonly string[];

Defined in: @gramota/presentation-exchange/dist/matcher.d.ts:17

Names of selectively-disclosable claims required to satisfy the descriptor. Pass these to holder.present({ disclose: [...] }).

satisfiedFields

satisfiedFields: readonly {
  fieldId: string;
  path: string;
}[];

Defined in: @gramota/presentation-exchange/dist/matcher.d.ts:19

Field-by-field detail, useful for audit logs and debug UIs.

---

SdJwtVcCredentialView

Defined in: @gramota/presentation-exchange/dist/sd-jwt-vc-matcher.d.ts:7

Convenience: a holder-stored credential exposes its parsed form. We accept either the full StoredCredential shape or just the parsed view — keeping the matcher decoupled from @gramota/holder's internals.

Properties

parsed

parsed: ParsedSdJwt;

Defined in: @gramota/presentation-exchange/dist/sd-jwt-vc-matcher.d.ts:8

---

SelectInput

Defined in: @gramota/presentation-exchange/dist/select.d.ts:3

Type Parameters

TCredential

TCredential

Properties

definition

definition: PresentationDefinition;

Defined in: @gramota/presentation-exchange/dist/select.d.ts:4

credentials

credentials: readonly TCredential[];

Defined in: @gramota/presentation-exchange/dist/select.d.ts:5

matchers?

optional matchers?: readonly CredentialMatcher<TCredential>[];

Defined in: @gramota/presentation-exchange/dist/select.d.ts:7

Custom matchers — Strategy pattern; default is SD-JWT-VC.

pickCredential?

optional pickCredential?: (candidates: readonly {
  credential: TCredential;
  result: MatchResult;
}[]) => {
  credential: TCredential;
  result: MatchResult;
};

Defined in: @gramota/presentation-exchange/dist/select.d.ts:10

When multiple credentials satisfy a descriptor, which to pick. Default: the first one.

Parameters

candidates

readonly { credential: TCredential; result: MatchResult; }[]

Returns

{
  credential: TCredential;
  result: MatchResult;
}

credential

credential: TCredential;

result

result: MatchResult;

---

SelectionMatch

Defined in: @gramota/presentation-exchange/dist/select.d.ts:18

Type Parameters

TCredential

TCredential

Properties

descriptor

descriptor: InputDescriptor;

Defined in: @gramota/presentation-exchange/dist/select.d.ts:19

credential

credential: TCredential;

Defined in: @gramota/presentation-exchange/dist/select.d.ts:20

disclose

disclose: readonly string[];

Defined in: @gramota/presentation-exchange/dist/select.d.ts:22

Names of selectively-disclosable claims to disclose.

result

result: MatchResult;

Defined in: @gramota/presentation-exchange/dist/select.d.ts:24

Audit detail.

---

SelectionFailure

Defined in: @gramota/presentation-exchange/dist/select.d.ts:26

Properties

descriptor

descriptor: InputDescriptor;

Defined in: @gramota/presentation-exchange/dist/select.d.ts:27

reason

reason: string;

Defined in: @gramota/presentation-exchange/dist/select.d.ts:28

---

Selection

Defined in: @gramota/presentation-exchange/dist/select.d.ts:30

Type Parameters

TCredential

TCredential

Properties

matches

matches: readonly SelectionMatch<TCredential>[];

Defined in: @gramota/presentation-exchange/dist/select.d.ts:31

unmatched

unmatched: readonly SelectionFailure[];

Defined in: @gramota/presentation-exchange/dist/select.d.ts:32

fullySatisfied

fullySatisfied: boolean;

Defined in: @gramota/presentation-exchange/dist/select.d.ts:33

---

PresentationDefinition

Defined in: @gramota/presentation-exchange/dist/types.d.ts:12

DIF Presentation Exchange v2 types — what the verifier asks for, and how the holder responds.

Spec: https://identity.foundation/presentation-exchange/spec/v2.1.1/

Scope of this package: input_descriptors, fields, format, limit_disclosure. Deferred to v2: submission_requirements, predicate, full filter (JSON Schema), frame.

Properties

id

id: string;

Defined in: @gramota/presentation-exchange/dist/types.d.ts:13

name?

optional name?: string;

Defined in: @gramota/presentation-exchange/dist/types.d.ts:14

purpose?

optional purpose?: string;

Defined in: @gramota/presentation-exchange/dist/types.d.ts:15

format?

optional format?: FormatMap;

Defined in: @gramota/presentation-exchange/dist/types.d.ts:18

Acceptable credential formats and their algorithms, applied at the PD level (overridable per input_descriptor).

input_descriptors

input_descriptors: readonly InputDescriptor[];

Defined in: @gramota/presentation-exchange/dist/types.d.ts:19

---

InputDescriptor

Defined in: @gramota/presentation-exchange/dist/types.d.ts:26

Properties

id

id: string;

Defined in: @gramota/presentation-exchange/dist/types.d.ts:27

name?

optional name?: string;

Defined in: @gramota/presentation-exchange/dist/types.d.ts:28

purpose?

optional purpose?: string;

Defined in: @gramota/presentation-exchange/dist/types.d.ts:29

format?

optional format?: FormatMap;

Defined in: @gramota/presentation-exchange/dist/types.d.ts:31

Per-descriptor format override.

constraints

constraints: Constraints;

Defined in: @gramota/presentation-exchange/dist/types.d.ts:32

---

Constraints

Defined in: @gramota/presentation-exchange/dist/types.d.ts:34

Properties

fields?

optional fields?: readonly Field[];

Defined in: @gramota/presentation-exchange/dist/types.d.ts:35

limit_disclosure?

optional limit_disclosure?: "required" | "preferred";

Defined in: @gramota/presentation-exchange/dist/types.d.ts:38

When "required", the holder MUST limit disclosure to only the requested fields (selective disclosure mandatory). When "preferred", it's a hint.

---

Field

Defined in: @gramota/presentation-exchange/dist/types.d.ts:40

Properties

path

path: readonly string[];

Defined in: @gramota/presentation-exchange/dist/types.d.ts:43

JSONPath expressions; the verifier's query into the credential. The field is satisfied if ANY of the paths match.

id?

optional id?: string;

Defined in: @gramota/presentation-exchange/dist/types.d.ts:45

Optional friendly id for audit logs.

optional?

optional optional?: boolean;

Defined in: @gramota/presentation-exchange/dist/types.d.ts:47

When true, missing field doesn't fail the descriptor.

filter?

optional filter?: {
  type?: "string" | "number" | "boolean" | "integer";
};

Defined in: @gramota/presentation-exchange/dist/types.d.ts:50

JSON Schema fragment to validate the matched value. v1 supports { type: "..." } only.

type?

optional type?: "string" | "number" | "boolean" | "integer";

purpose?

optional purpose?: string;

Defined in: @gramota/presentation-exchange/dist/types.d.ts:53

---

PresentationSubmission

Defined in: @gramota/presentation-exchange/dist/types.d.ts:57

A holder-built mapping of which credentials satisfy which descriptors, per DIF PE §6 — the wallet's response to a Presentation Definition.

Properties

id

id: string;

Defined in: @gramota/presentation-exchange/dist/types.d.ts:58

definition_id

definition_id: string;

Defined in: @gramota/presentation-exchange/dist/types.d.ts:59

descriptor_map

descriptor_map: readonly DescriptorMap[];

Defined in: @gramota/presentation-exchange/dist/types.d.ts:60

---

DescriptorMap

Defined in: @gramota/presentation-exchange/dist/types.d.ts:62

Properties

id

id: string;

Defined in: @gramota/presentation-exchange/dist/types.d.ts:63

format

format: string;

Defined in: @gramota/presentation-exchange/dist/types.d.ts:65

e.g. "vc+sd-jwt", "jwt_vp", "ldp_vp", "mso_mdoc".

path

path: string;

Defined in: @gramota/presentation-exchange/dist/types.d.ts:67

JSONPath into the vp_token ($ for single-credential responses).

path_nested?

optional path_nested?: DescriptorMap;

Defined in: @gramota/presentation-exchange/dist/types.d.ts:68

Type Aliases

JsonPathSegment

type JsonPathSegment = 
  | {
  kind: "property";
  name: string;
}
  | {
  kind: "index";
  index: number;
};

Defined in: @gramota/presentation-exchange/dist/jsonpath.d.ts:20

Minimal JSONPath subset sufficient for SD-JWT-VC presentation queries.

Supported: $ — the root $.foo — property $.foo.bar — nested property $['foo'] — bracket notation $['foo']['bar'] — chained bracket $.foo[0] — array index

NOT supported (v1): $..foo — recursive descent $.foo[*] — wildcards $[?(@.x>0)] — filters

Returns the matched value, or undefined if no match. Throws only on malformed expressions.

---

FormatMap

type FormatMap = Readonly<Record<string, {
  alg?: readonly string[];
}>>;

Defined in: @gramota/presentation-exchange/dist/types.d.ts:23

Maps a credential format identifier (e.g. "vc+sd-jwt") to algorithm constraints. Per DIF PE §5.5.

---

PresentationExchangeErrorCode

type PresentationExchangeErrorCode = 
  | "pe.jsonpath_invalid"
  | "pe.unsatisfiable"
  | "pe.format_unsupported"
  | "pe.invalid_input"
  | "dcql.invalid_query"
  | "dcql.invalid_path";

Defined in: @gramota/presentation-exchange/dist/types.d.ts:71

Stable codes for PresentationExchangeError.

Variables

SD_JWT_VC_FORMAT

const SD_JWT_VC_FORMAT: "vc+sd-jwt" = "vc+sd-jwt";

Defined in: @gramota/presentation-exchange/dist/sd-jwt-vc-matcher.d.ts:10

Functions

parseJsonPath()

function parseJsonPath(expr: string): readonly JsonPathSegment[];

Defined in: @gramota/presentation-exchange/dist/jsonpath.d.ts:27

Parameters

expr

string

Returns

readonly JsonPathSegment[]

---

evaluateJsonPath()

function evaluateJsonPath(expr: string, root: unknown): unknown;

Defined in: @gramota/presentation-exchange/dist/jsonpath.d.ts:29

Evaluate a JSONPath against a value. Returns the matched leaf or undefined.

Parameters

expr

string

root

unknown

Returns

unknown

---

leafClaimName()

function leafClaimName(expr: string): string;

Defined in: @gramota/presentation-exchange/dist/jsonpath.d.ts:33

Return the leaf claim name for a single-segment path like $.given_name, or null for longer or non-property paths. Useful for SD-JWT-VC where a top-level disclosure name == the JSONPath leaf.

Parameters

expr

string

Returns

string

---

selectForDefinition()

function selectForDefinition<TCredential>(input: SelectInput<TCredential>): Selection<TCredential>;

Defined in: @gramota/presentation-exchange/dist/select.d.ts:42

Pick credentials + disclosures that satisfy a Presentation Definition.

Pure function: given a definition and a credential set, return what to present. Caller (the holder) executes the actual presentation building with @gramota/holder.

Type Parameters

TCredential

TCredential

Parameters

input

SelectInput<TCredential>

Returns

Selection<TCredential>

---

buildPresentationSubmission()

function buildPresentationSubmission<TCredential>(
   definition: PresentationDefinition, 
   selection: Selection<TCredential>, 
   options?: {
  id?: string;
}): PresentationSubmission;

Defined in: @gramota/presentation-exchange/dist/select.d.ts:46

Build a Presentation Submission from a Selection. The vp_token paths follow the convention: $ for a single credential, $[0], $[1], ... for arrays.

Type Parameters

TCredential

TCredential

Parameters

definition

PresentationDefinition

selection

Selection<TCredential>

options?

id?

string

Returns

PresentationSubmission