​
The PEX Library supports the following actions:

  • Creating a presentation definition / request
  • Validating a presentation definition / conforming to the specifications v1 and v2
  • Creating a Presentation
  • Creating a Verifiable Presentation using a callback function
  • Validating a presentation (submission) when received
  • Input evaluations: Verification of presentation submissions conforming to the presentation definition
  • Utilities: to build and use different models compliant with the DIF Presentation Exchange v2.0.0 specification.
  • Support for DIF Presentation Exchange v1.0.0 specification.

Stateful storage, signature support or credential management should be implemented in separate libraries/modules that make use of this library. By keeping these separate, the PEX library will stay platform-agnostic and lean with respect to dependencies.

​
For PEX Users

This project has been created using:

  • yarn version 1.22.5
  • node version >= 16

Follow these steps to install and run @sphereon/pex on your operating system:

How to install: Install @sphereon/pex:

The core functionality of the DIF Presentation Exchange can be outlined as follows:

​
Verifier: Create a Presentation Definition object:

Presentation Definitions are objects that articulate what proofs a Verifier requires. These help the Verifier to decide how or whether to interact with a Holder. Presentation Definitions are composed of inputs, which describe the forms and details of the proofs they require, and optional sets of selection rules, to allow Holders flexibility in cases where different types of proofs may satisfy an input requirement. PEX library supports two versions of presentation_definition object. The details of it can be found in @spehereon/pex-models below you can find some tips about querying via a presentation_definition object:

  • Using the constraint field:
    • You can use the constraint field for creating your query:
constraints: {
  fields: [
    {
      path: ['$.credentialSubject.role'],
      filter: {
        type: 'string',
        const: 'admin'
      }
    }
  ];
}
  • for special cases, like querying fields that start with @ you can use the following syntax:
    • You can use the following syntax, PEX will change it to correct query itself:
path: ['$.@context', '$.vc.@context']

For querying the arrays, right now we don’t support the json-schema fully, but we do support the following syntax:

  • using [*] like:
{
  fields: [
    {
      path: [
        '$.type.[*]'
      ],
      filter: {
        type: 'string',
        pattern: 'AlumniCredential'
      }
    }
  ]
}
  • using .* like:
{
  fields: [
    {
      path: [
        '$.type.*'
      ],
      filter: {
        type: 'string',
        pattern: 'AlumniCredential'
      }
    }
  ]
}
  • using type: array and contains keyword. PEX currently doesn’t support this syntax fully, but if you don’t rely on our versionDiscovery functionality and call the specific version of PEX (PEXv1 or PEXv2) yourself, you can use this syntax as well.
{
  "fields": [
    {
      "path": [
        "$.type"
      ],
      "filter": {
        "type": "array",
        "contains": {
          "enum": [
            "https://example.com/type"
          ]
        }
      }
    }
  ]
}

​
Verifier: Input Evaluation

Input evaluation is the primary mechanism by which a verifier determines whether a Verifiable Presentation and Presentation Submission from a holder matches the requested presentation definition from the request. Obviously a holder/wallet could also use the method to verify whether its submission would be valid, before contacting the verifier.

import { PEX } from '@sphereon/pex';

const pex: PEX = new PEX();

// Example of Presentation Definition V1 (notice the required schema for V1)
const presentationDefinitionV1 = {
  "id": "32f54163-7166-48f1-93d8-ff217bdb0653",
  "input_descriptors": [
    {
      "id": "wa_driver_license",
      "name": "Washington State Business License",
      "purpose": "We can only allow licensed Washington State business representatives into the WA Business Conference",
      "schema": [{
        "uri": "https://licenses.example.com/business-license.json"
      }]
    }
  ]
};

// Example of Presentation Definition V2
const presentationDefinitionV2 = {
  "id": "32f54163-7166-48f1-93d8-ff217bdb0653",
  "input_descriptors": [
    {
      "id": "wa_driver_license",
      "name": "Washington State Business License",
      "purpose": "We can only allow licensed Washington State business representatives into the WA Business Conference"
    }
  ]
};

const verifiablePresentation = {
  '@context': [
    "https://www.w3.org/2018/credentials/v1",
    "https://identity.foundation/presentation-exchange/submission/v1"
  ],
  type: [
    "VerifiablePresentation",
    "PresentationSubmission"
  ],
  presentation_submission: { ... },
  verifiableCredential: [...],
  proof: { ... }
}

// We are using the PEX class, to automatically detect the definition version. PEXv1 and PEXv2 are also available to use fixed PEX versions
const { value, warnings, errors } = pex.evaluatePresentation(presentationDefinitionV2, verifiablePresentation);

​
Holder: Credential Query

A credential query allows holders to filter their set of credentials for matches to a given presentation definition. This filters out any non-matching Credentials that are passed in. Please note that multiple credentials could be satisfying the definition.

import { PEX } from '@sphereon/pex';
import { IVerifiableCredential } from "./SSI.types";

const pex: PEX = new PEX();

// Definition from verifier request
const presentationDefinition = {
  ...
};
// Finding out which version presentationDefinition is this:
// The result is either 'v1', 'v2' or an error
// You only have to do this if you want to apply some custom logic. The PEX class uses feature detection on the definition to determine whether it is v1 or v2 internally
const result = PEX.definitionVersionDiscovery(pdSchema);

// Example for loading credentials from your secure storage
const credentials: IVerifiableCredential[] = await secureStore.getCredentials();

// Find matching credentials
const srMatches = pex.selectFrom(presentationDefinition, credentials, { holderDIDs: [holderDID] });

// An example that selects the first 'count' credentials from
// the matches. in a real scenario, the user has to select which
// credentials to use. PEX did the first filtering,
// but there still could be multiple credentials satisfying a presentation definition
const selectedCredentials = srMatches.map(
  ({ matches, count }) => matches.slice(0, count)
).flat();

​
Holder: Presentation creation (non-verifiable)

To create a Presentation without Proof (for Proofs, see Verifiable Presentation below) you have to pass in the Presentation Definition, selected Verifiable Credentials and an optional holder (DID). The result will be a Verifiable Presentation, without proofs, so actually a Presentation. It also contains the presentation submission data that the verifier can use.

It is left up to you to sign the Presentation and adding the proof and make it a truly Verifiable Presentation. There are different libraries that allow you to do this. You can also use the callback integration mentioned in the next chapter for this.

import { PEX, IPresentation, PresentationResult } from '@sphereon/pex';

const pex: PEX = new PEX();

// Construct presentation from selected credentials
const presentationResult: PresentationResult = pex.presentationFrom(presentationDefinition, selectedCredentials, { holderDIDs: [holderDID] });
const presentation = presentationResult.presentation
/** presentation object:
 *
 *   {
 *     "@context": [
 *       "https://www.w3.org/2018/credentials/v1",
 *       "https://identity.foundation/presentation-exchange/submission/v1"
 *     ],
 *     "type": [
 *       "VerifiablePresentation",
 *       "PresentationSubmission"
 *     ],
 *     presentation_submission: presentationSubmission,
 *     verifiableCredential: selectedCredentials
 *   };
 */
// Presentation would need to be signed and sent to verifier

​
Holder: Verifiable Presentation with callback

NOTE: PEX does not support the creation of signatures by itself. That has to do with the fact that we didn’t want to rely on all kinds of signature suites and libraries. PEX has minimal dependencies currently, so that it can be used in all kinds of scenarios.

How did we solve this? We have created a callback mechanism, allowing you to supply a callback function that gets all input allowing you to use your library of choice to create the signature. The callback needs to accept a PresentationSignCallBackParams object.

NOTE: The method verifiablePresentationFrom accepts the presentation definition and selected Verifiable Credentials as the first two arguments, just like the presentationFrom method. Next it accepts the callback function as argument and a VerifiablePresentationFromOpts object as last argument. The sign callback params, allow you to control the signature process. You will have access in the callback to these params as well.

Before calling your callback function a few things happen. First, just like the presentationFrom method, it will evaluate whether the supplied credentials conform to the supplied presentation definition. Then it creates a presentation, just like presentationFrom. This presentation is provided for your convenience and can be used in your callback for simple use cases. In more elaborate cases, like for instance with more complex signature suites and/or selective disclosure, you will probably not use the IPresentation directly and make use of other arguments passed into the callback, like the EvaluationResults, PresentationSubmission and Partial<IProof>.

The proofOptions and signatureOptions, allow you to populate proof values directly. in which case the Partial<IProof> will have all fields filled to just add it as a proof to the presentation in your callback. This does mean you would have to create the IPresentation first and sign that, which means you probably have no use for the callback. If you do not provide these values, the Partial<IProof>, will still be populated without the proofValue and jws, based upon your options.

​
Presentation Sign Options

The options accepted by the verifiablePresentationFrom are:

interface VerifiablePresentationFromOpts {
  /**
   * The optional holderDID of the presentation
   */
  holderDID?: string;

  /**
   * The presentation submission data location.
   *
   * Can be External, which means it is only returned and not embedded into the VP,
   * or Presentation, which means it will become part of the VP
   */
  presentationSubmissionLocation?: PresentationSubmissionLocation;

  /**
   * A base presentation payload. Can be used to provide default values. Be aware that any verifiable credential will always be overwritten
   */
  basePresentationPayload?: IPresentation;

  /**
   * IProof options
   */
  proofOptions?: ProofOptions;

  /**
   * The signature options
   */
  signatureOptions?: SignatureOptions;
}

interface ProofOptions {
  /**
   * The signature type. For instance RsaSignature2018
   */
  type?: ProofType | string;

  /**
   * Type supports selective disclosure?
   */
  typeSupportsSelectiveDisclosure?: boolean;

  /**
   * A challenge protecting against replay attacks
   */
  challenge?: string;

  /**
   * A domain protecting against replay attacks
   */
  domain?: string;

  /**
   * The purpose of this proof, for instance assertionMethod or authentication, see https://www.w3.org/TR/vc-data-model/#proofs-signatures-0
   */
  proofPurpose?: ProofPurpose | string;

  /**
   * The ISO8601 date-time string for creation. You can update the IProof value later in the callback. If not supplied the current date/time will be used
   */
  created?: string;

  /**
   * Similar to challenge. A nonce to protect against replay attacks, used in some ZKP proofs
   */
  nonce?: string;
}

interface SignatureOptions {
  /**
   * The private key
   */
  privateKey?: string;

  /**
   * Key encoding
   */
  keyEncoding?: KeyEncoding;

  /**
   * The verification method value
   */
  verificationMethod?: string;

  /**
   * Can be used if you want to provide the Json-ld proof value directly without relying on the callback function generating it
   */
  proofValue?: string; // One of any number of valid representations of proof values

  /**
   * Can be used if you want to provide the JSW proof value directly without relying on the callback function generating it
   */
  jws?: string; // JWS based proof
}

These options are available in your callback function by accessing the options field in the PresentationSignCallBackParams.

​
Callback params object

The callback params gets supplied as the single argument to your callback function. It contains the Presentation, a partial ‘Proof’ typically missing the proofValue/jws signature. It also contains the initially supplied Verifiable Credentials and Presentation Definition as well as your supplied options.

If contains the Presentation Submission object, which is also found in the presentation. You can use this to create your own IPresentation object if you want. Lastly it contains the evaluation results, which includes the mappings and logs about the evaluation.

You can either choose to use the Presentation and partial Proof together with the options, or in more elaborate use cases opt to use the PresentationSubmission, EvaluationResults and the options for instance.

export interface PresentationSignCallBackParams {
  /**
   * The originally supplied presentation sign options
   */
  options: VerifiablePresentationFromOpts;

  /**
   * The presentation definition
   */
  presentationDefinition: PresentationDefinition;

  /**
   * The selected credentials to include in the eventual VP as determined by PEX and/or user
   */
  selectedCredentials: (IVerifiableCredential | JwtWrappedVerifiableCredential | string)[];

  /**
   * The presentation object created from the definition and verifiable credentials.
   * Can be used directly or in more complex situations can be discarded by using the definition, credentials, proof options, submission and evaluation results
   */
  presentation: IPresentation;

  /**
   * A partial proof value the callback can use to complete. If proofValue or JWS was supplied the proof could be complete already
   */
  proof: Partial<IProof>;

  /**
   * The presentation submission data, which can also be found in the presentation itself
   */
  presentationSubmission: PresentationSubmission;

  /**
   * The evaluation results, which the callback function could use to create a VP using the proof(s) using the supplied credentials
   */
  evaluationResults: EvaluationResults;
}

​
Simple example of the callback function

A simple use case using your library of choice for non-selective disclosure using an ed25519 key and signature.

import {
  PEX,
  IProof,
  ProofPurpose,
  ProofType,
  IVerifiablePresentation,
  PresentationSignOptions,
  KeyEncoding,
} from '@sphereon/pex';

const pex: PEX = new PEX();

const params: VerifiablePresentationFromOpts = {
  holderDID: 'did:example:1234....',
  proofOptions: {
    type: ProofType.Ed25519Signature2018,
    proofPurpose: ProofPurpose.assertionMethod,
  },
  signatureOptions: {
    verificationMethod: 'did:example:"1234......#key',
    keyEncoding: KeyEncoding.Base58,
    privateKey: 'base58 (key encoding type) key here',
  },
};

const vp = await pex.verifiablePresentationFrom(
  presentationDefinition,
  selectedCredentials,
  simpleSignedProofCallback,
  params
);

function simpleSignedProofCallback(callBackParams: PresentationSignCallBackParams): IVerifiablePresentation {
  // Prereq is properly filled out `proofOptions` and `signatureOptions`, together with a `proofValue` or `jws` value.
  // And thus a generated signature
  const { presentation, proof, options } = callBackParams; // The created partial proof and presentation, as well as original supplied options
  const { signatureOptions, proofOptions } = options; // extract the orignially supploed signature and proof Options
  const privateKeyBase58 = signatureOptions.privateKey; // Please check keyEncoding from signatureOptions first!

  /**
   * IProof looks like this:
   * {
   *    type: 'Ed25519Signature2018',
   *    created: '2021-12-01T20:10:45.000Z',
   *    proofPurpose: 'assertionMethod',
   *    verificationMethod: 'did:example:"1234......#key',
   *    .....
   * }
   */

    // Just an example. Obviously your lib will have a different method signature
  const vp = myVPSignLibrary(presentation, { ...proof, privateKeyBase58 });

  return vp;
}

​
Utilities

In addition to the core functionality above, the underlying validation methods are exposed as low-level helper functions.

import { PEX } from '@sphereon/pex';

const presentationDefinition = {
  ...
};

const result = PEX.definitionVersionDiscovery(presentationDefinition);
const { warnings: pdWarnings, errors: pdErrors } = PEX.validateDefinition(presentationDefinition);

const presentationSubmission = {
  ...
};

const { warnings: psWarnings, errors: psErrors } = PEX.validateSubmission(presentationSubmission);

​
For PEX developers

This project has been created using:

  • yarn version 1.22.5
  • node version >= 16

​
Install

yarn install

​
Build

yarn build

​
Test

The test command runs:

  • eslint
  • prettier
  • unit

You can also run only a single section of these tests, using for example yarn test:unit.

yarn test

​
Utility scripts

There are several other utility scripts that help with development.

  • yarn fix - runs eslint --fix as well as prettier to fix code style
  • yarn cov - generates code coverage report
From V1 to V2Api