@empe/verifier-common

A core library for working with Verifiable Presentations (VPs) and Presentation Definitions in the OIDC4VP (OpenID Connect for Verifiable Presentations) protocol. This package implements utilities for verifiable credential matching, presentation definition building, and credential validation within the Empe SSI ecosystem.

Table of Contents

1. Installation
2. Key Features
3. Usage
   • Building Presentation Definitions
   • Matching Credentials
   • Creating Presentation Submissions
   • Validating Verifiable Presentations
4. Types
5. Error Handling
6. Advanced Filtering
7. Integration with Verifier Service

Installation

npm install @empe/verifier-common
# or
yarn add @empe/verifier-common

Key Features

• Presentation Definition Building: Create standardized presentation definitions for verifier requests
• Credential Matching: Match verifiable credentials against presentation definitions using JSONPath expressions
• Validation: Validate verifiable presentations, definitions, and submissions
• JSON Schema Filtering: Apply complex filters to credential fields using JSON Schema validation

Usage

Building Presentation Definitions

Creating a presentation definition to request specific credential types:

import { buildPresentationDefinition, VPQueryParams } from '@empe/verifier-common';

// Simple request for a credential containing "ProofOfIdentity" in its type array
const simpleRequest: VPQueryParams[] = [
    {
        fields: [
            {
                path: ['$.type'],
                filter: {
                    type: 'array',
                    contains: { const: 'ProofOfIdentity' },
                },
            },
        ],
    },
];

// Create the presentation definition
const presentationDefinition = buildPresentationDefinition(simpleRequest);

console.log(presentationDefinition);
// Output:
// {
//   id: "1a2b3c...",  // auto-generated nanoid
//   input_descriptors: [
//     {
//       id: "descriptor-0",
//       constraints: {
//         limit_disclosure: "required",
//         fields: [
//           {
//             path: ["$.type"],
//             filter: { type: "array", contains: { const: "ProofOfIdentity" } }
//           }
//         ]
//       }
//     }
//   ]
// }

Matching Credentials

Match verifiable credentials against a presentation definition:

import { matchCredentialsToDefinition, buildPresentationDefinition } from '@empe/verifier-common';
import { VC } from '@empe/identity';

// Your array of verifiable credentials to match against
const userCredentials: VC[] = [
    /* ... */
];

// Create a presentation definition that requires credentials with nationality "Germany"
const presentationDefinition = buildPresentationDefinition([
    {
        fields: [
            {
                path: ['$.credentialSubject.nationality'],
                filter: {
                    type: 'string',
                    const: 'Germany',
                },
            },
        ],
    },
]);

// Match credentials against the definition
const matchedCredentials = matchCredentialsToDefinition(userCredentials, presentationDefinition);

console.log(`Found ${matchedCredentials.length} matching credentials`);

Creating Presentation Submissions

Create a presentation submission from a presentation definition:

import { createPresentationSubmission, buildPresentationDefinition } from '@empe/verifier-common';

// First, create a presentation definition
const presentationDefinition = buildPresentationDefinition([
    /* ... */
]);

// Then create a submission for it
const presentationSubmission = createPresentationSubmission(presentationDefinition);

console.log(presentationSubmission);
// Output:
// {
//   id: "submission-1a2b3c...",  // auto-generated ID
//   definition_id: "1a2b3c...",   // matches the presentation definition ID
//   descriptor_map: [
//     {
//       id: "descriptor-0",
//       path: "$.verifiableCredential[0]",
//       format: "jwt_vc"  // or other appropriate format
//     }
//   ]
// }

Validating Verifiable Presentations

Validate that a verifiable presentation meets a presentation definition:

import {
    validateVerifiablePresentation,
    buildPresentationDefinition,
    createPresentationSubmission,
    VP,
} from '@empe/verifier-common';

// Your verifiable presentation
const verifiablePresentation: VP = {
    /* ... */
};

// Create a presentation definition
const presentationDefinition = buildPresentationDefinition([
    /* ... */
]);

// Create a presentation submission
const presentationSubmission = createPresentationSubmission(presentationDefinition);

// Validate the presentation against the definition and submission
try {
    const isValid = validateVerifiablePresentation(
        presentationDefinition,
        verifiablePresentation,
        presentationSubmission
    );

    console.log('Presentation is valid:', isValid);
} catch (error) {
    console.error('Validation failed:', error.message);
}

Types

The package exports several TypeScript types:

// Definition of what credentials are being requested
type VPQueryParams = {
    fields: InputDescriptorField[];
};

// Field specification with JSONPath and optional filter
type InputDescriptorField = {
    path: string[];
    filter?: JSONSchema7; // JSON Schema for validation
};

// Structure describing requested credentials
type PresentationDefinition = {
    id: string;
    input_descriptors: InputDescriptor[];
};

// Mapping between the presentation definition and the actual credentials
type PresentationSubmission = {
    id: string;
    definition_id: string;
    descriptor_map: DescriptorMap[];
};

// Verifiable Presentation structure
type VP = {
    '@context': string[] | string;
    type: string | string[];
    verifiableCredential: VC[];
    id?: string;
    holder: string | { id: string };
    proof?: Proof;
};

Error handling example:

import { validatePresentationDefinition, PresentationDefinitionError } from '@empe/verifier-common';

try {
    validatePresentationDefinition(presentationDefinition);
} catch (error) {
    if (error instanceof PresentationDefinitionError) {
        console.error('Definition validation failed:', error.message);
        // Handle the specific error
    } else {
        // Handle other errors
        console.error('Unexpected error:', error);
    }
}

Advanced Filtering

The package supports complex JSON Schema-based filtering:

// Example: Request a credential where:
// - type array contains "ProofOfIdentity"
// - nationality is "Germany"
// - age is greater than 18
const complexFilter = buildPresentationDefinition([
    {
        fields: [
            {
                path: ['$.type'],
                filter: {
                    type: 'array',
                    contains: { const: 'ProofOfIdentity' },
                },
            },
            {
                path: ['$.credentialSubject.nationality'],
                filter: {
                    type: 'string',
                    const: 'Germany',
                },
            },
            {
                path: ['$.credentialSubject.age'],
                filter: {
                    type: 'number',
                    minimum: 18,
                },
            },
        ],
    },
]);

Integration with Verifier Client

This package forms the foundation for the @empe/verifier-client package, providing core functionality for credential verification. To implement a complete verifier service, you typically:

1. Use this package to define what credentials you need to verify
2. Generate a QR code for wallet scanning (via verifier-client)
3. Match the presented credentials against your requirements
4. Process the verification results in your application

See the @empe/verifier-client package documentation for complete implementation examples.

License

MIT