Improve error handling

[antonio-ivanovski]

While using the library there are certain cases where it can be useful to know what issue has caused an error to be thrown. For example in the verify method it can be useful to know if the verification has failed because of invalid signature or maybe missing proof parameter.

Depending on error message is not reliable, especially when some of the error messages are dynamic with parameters inside the message.

[siacomuzzi]

Did you try the onCheck option? Here you can find the default implementation, but you can override it. For example:

const verificationChecksToReview = [];

await verifier.verify(deviceResponse, {
  ephemeralReaderKey,
  encodedSessionTranscript,
  onCheck: (verificationStep) => {
    if (verificationStep.status === 'PASSED') { return; }
    verificationChecksToReview.push(verificationStep);
  },
});

// Given that the `onCheck` callback was overridden, you need to check if the verification was successful
const isValid = verificationChecksToReview.length === 0;
if (!isValid) {
  console.log('VERIFICATION STEPS TO REVIEW', verificationChecksToReview);
}

[siacomuzzi]

Alternatively, throw your own error:

await verifier.verify(deviceResponse, {
  ephemeralReaderKey,
  encodedSessionTranscript,
  onCheck: (verificationStep) => {
    if (verificationStep.status === 'PASSED') { return; }
    throw new MyVerificationError(verificationStep.reason ?? verificationStep.check);
  },
});

[antonio-ivanovski]

@siacomuzzi Thanks for the suggestion. We are using a custom onCheck implementation.

The challenge is that distinct verification failures, such as an invalid issuer signature or an invalid certificate chain, both result in onCheck being invoked with category: 'ISSUER_AUTH' and status: 'FAILED'. To differentiate these cases, we must inspect the verificationStep.check property (e.g., verificationStep.check === 'Issuer signature must be valid').

Relying on this specific string literal for critical error handling introduces fragility. Since this string is not tied to a stable contract (like an enum or defined error code), any change to its wording could break our error handling logic without a clear indication. A more robust mechanism for identifying specific failure reasons is needed.

[siacomuzzi]

Got it, so we could expose a unique ID for each check (ie, verificationStep.id) 👍

[siacomuzzi]

feedback is welcome: #50

cc @antonio-ivanovski

[github-actions]

🎉 This issue has been resolved in version 2.1.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀