Architecture
Overview
This section provides an overview of the Verification SDK's architecture, including its components and interactions.
Architecture Diagram
Explanation
Provider App & Beneficiary App: These applications interact with the Verification SDK to verify documents.
Verification SDK: Acts as the core component, exposing a REST API for verification.
Verification Service: Processes the verification requests and returns results.
Fastify Framework: Provides the underlying infrastructure for the REST API.
Sequence Diagram
Explanation
Request Verification: Both apps send verification requests to the SDK.
Process Verification: The SDK processes these requests through the Verification Service.
Return Result: Results are returned to the apps, with error handling and logging.
Data Flow Diagram
Explanation
Input: Credential JSON and configuration data are input into the Verification Service.
Processing: Data undergoes verification logic and validation.
Output: The final output is the verification result.
API Reference
The Verification SDK exposes the /verification API endpoint for credential verification.
Below are the request and response details.
Request Body
credential (object, required): The credential JSON to verify.
config (object, required): Configuration object for verification.
method (string, required): The verification method to use:
"online": Verifies using a named online verifier (requiresissuerName)."offline": Planned feature (to be implemented).
issuerName (string, required if
methodis"online"): Name of the verifier to use. Currently supports"dhiway".
Example Request
Example Response (Success)
{
"success": true,
"message": "Credential verified successfully."
}Example Response (Failure)
{
"success": false,
"message": "Credential verification failed.",
"errors": [
{
"error": "Some information in the credential couldn't be verified. Please ensure the credential is complete and hasn't been modified.",
"raw": "Error verifyDisclosedAttributes"
}
]
}Error Response (Bad Request)
{
"error": "Missing or empty required parameter: credential"
}Core Components
The SDK uses a modular, extensible architecture for credential verification, centered around the src/services directory:
verificationService.js: Main entry point for verification logic. It receives the payload, selects the appropriate verifier, and returns the result.verifiers/VerifierFactory.js: Factory class that selects and instantiates the correct verifier based on theconfig(e.g.,methodandissuerName).verifiers/VerifierInterface.js: Abstract base class. All verifiers must extend this and implement theverify(credential)method.Online Verifiers: Implemented in
verifiers/online-verifiers/. Example:DhiwayVerifier.jsOffline Verifiers: Implemented in
verifiers/offline-verifier/. Example:SignatureVerifier.js
How to Add a New Verifier
Create a New Verifier Class:
Extend
VerifierInterface.Implement the
verify(credential)method with your logic.Place your file in the appropriate folder (
online-verifiersoroffline-verifier).
Naming Convention:
Name your class as
<ProviderName>Verifier(e.g.,AcmeVerifier).The filename should match the class name (e.g.,
AcmeVerifier.js).
Update Configuration:
To use your verifier, set
methodandissuerNamein the request config:{ "credential": { /* ... */ }, "config": { "method": "online", "issuerName": "acme" } }The factory will automatically load your verifier if the naming matches.
(Optional) Add Error Translation:
For online verifiers, you can add custom error translation logic as shown in
DhiwayVerifier.js.
Example: Adding a New Online Verifier
Create
src/services/verifiers/online-verifiers/AcmeVerifier.js:const VerifierInterface = require('../VerifierInterface'); class AcmeVerifier extends VerifierInterface { async verify(credential) { // Your verification logic here return { success: true, message: 'Verified by Acme.' }; } } module.exports = AcmeVerifier;Use it in your API request:
{ "credential": { /* ... */ }, "config": { "method": "online", "issuerName": "acme" } }
Tip: No changes to the factory or service are needed if you follow the naming and folder conventions.
For more details, see the code in src/services.
Note: This SDK is designed to enable interoperable, extensible, and standards-based credential verification. To support new providers or offline verification, simply add a new class implementing the required logic and register it with the verification service.
Last updated