Unify Error Handling

[Wind4Greg]

Similar to issue w3c/vc-di-ecdsa#63. To unify error handling language across this specification and other cryptosuite specifications I'd recommend:

1. Use appropriate error handling language as in DI specification, e.g., "an error MUST be raised and SHOULD convey an error type of ERROR_CODE_NAME." where ERROR_CODE_NAME is defined in the DI specification.
2. Use standardized error codes from DI Specification, and if needed add new codes to DI specification
3. Check for non-rigorous error handling language and if it needs to be updated (errors without codes that need codes)

Below I show codes used but not in the DI specification. I didn't find any error conditions without codes that should have them. Thoughts/Opinions?

Error Codes Used but Not in DI Spec

Error codes: PROOF_TRANSFORMATION_ERROR, INVALID_PROOF_CONFIGURATION, INVALID_PROOF_DATETIME, MALFORMED_PROOF_ERROR,

• line 635: "If options.type is not set to the string DataIntegrityProof and options.cryptosuite is not set to the string eddsa-rdfc-2022 then a PROOF_TRANSFORMATION_ERROR MUST be raised." In section Transformation (eddsa-rdfc-2022).
• line 724: "If options.type is not set to DataIntegrityProof and proofConfig.cryptosuite is not set to eddsa-rdfc-2022, an INVALID_PROOF_CONFIGURATION error MUST be raised."
• line 730: "If the value is not a valid [[XMLSCHEMA11-2]] datetime, an INVALID_PROOF_DATETIME error MUST be raised."
• line 1005: "If options.type is not set to the string DataIntegrityProof and options.cryptosuite is not set to the string eddsa-jcs-2022 then an error MUST be raised that SHOULD use the MALFORMED_PROOF_ERROR error code."
• line 1085: "If options.type is not set to DataIntegrityProof and proofConfig.cryptosuite is not set to eddsa-jcs-2022, an INVALID_PROOF_CONFIGURATION error MUST be raised."
• line 1090: "Set proofConfig.created to options.created. If the value is not a valid [[XMLSCHEMA11-2]] datetime, an INVALID_PROOF_DATETIME error MUST be raised."
• line 2017: "If options.type is not set to the string Ed25519Signature2020, then a PROOF_TRANSFORMATION_ERROR MUST be raised."
• line 2114: "If options.type is not set to Ed25519Signature2020, an INVALID_PROOF_CONFIGURATION error MUST be raised."
• line 2119: "If the value is not a valid [[XMLSCHEMA11-2]] datetime, an INVALID_PROOF_DATETIME error MUST be raised."

[Wind4Greg]

Analysis: PROOF_TRANSFORMATION_ERROR and INVALID_PROOF_CONFIGURATION are thrown under the same condition but from two different places and used consistently here and in the ECDSA spec. MALFORMED_PROOF_ERROR really should be a PROOF_TRANSFORMATION_ERROR for consistency with the rest of the document.

Recommend adding PROOF_TRANSFORMATION_ERROR, INVALID_PROOF_CONFIGURATION, and INVALID_PROOF_DATETIME errors to the VC-DI specification since they are used in this spec, ECDSA, and BBS specs.

• line 635: "If options.type is not set to the string DataIntegrityProof and options.cryptosuite is not set to the string eddsa-rdfc-2022 then a PROOF_TRANSFORMATION_ERROR MUST be raised." In section Transformation (eddsa-rdfc-2022).
• line 724: "If options.type is not set to DataIntegrityProof and proofConfig.cryptosuite is not set to eddsa-rdfc-2022, an INVALID_PROOF_CONFIGURATION error MUST be raised." In section Proof Configuration (eddsa-rdfc-2022)
• line 730: "If the value is not a valid [[XMLSCHEMA11-2]] datetime, an INVALID_PROOF_DATETIME error MUST be raised." In section Proof Configuration (eddsa-rdfc-2022).
• line 1005: "If options.type is not set to the string DataIntegrityProof and options.cryptosuite is not set to the string eddsa-jcs-2022 then an error MUST be raised that SHOULD use the MALFORMED_PROOF_ERROR error code." In section Transformation (eddsa-jcs-2022). This is inconsistent with rest of document.
• line 1085: "If options.type is not set to DataIntegrityProof and proofConfig.cryptosuite is not set to eddsa-jcs-2022, an INVALID_PROOF_CONFIGURATION error MUST be raised." In section Proof Configuration (eddsa-jcs-2022)
• line 1090: "Set proofConfig.created to options.created. If the value is not a valid [[XMLSCHEMA11-2]] datetime, an INVALID_PROOF_DATETIME error MUST be raised." In section Proof Configuration (eddsa-jcs-2022).
• line 2017: "If options.type is not set to the string Ed25519Signature2020, then a PROOF_TRANSFORMATION_ERROR MUST be raised." In section Transformation (Ed25519Signature2020).
• line 2114: "If options.type is not set to Ed25519Signature2020, an INVALID_PROOF_CONFIGURATION error MUST be raised." In section Proof Configuration (Ed25519Signature2020).
• line 2119: "If the value is not a valid [[XMLSCHEMA11-2]] datetime, an INVALID_PROOF_DATETIME error MUST be raised." In section Proof Configuration (Ed25519Signature2020).

[dlongley]

line 635: "If options.type is not set to the string DataIntegrityProof and options.cryptosuite is not set to the string eddsa-rdfc-2022 then a PROOF_TRANSFORMATION_ERROR MUST be raised." In section Transformation (eddsa-rdfc-2022).
line 724: "If options.type is not set to DataIntegrityProof and proofConfig.cryptosuite is not set to eddsa-rdfc-2022, an INVALID_PROOF_CONFIGURATION error MUST be raised." In section Proof Configuration (eddsa-rdfc-2022)

These strike me as the same kind of error -- and that the difference in error code isn't very helpful. They are really about the wrong configuration / proof information, not about transformation. They might both fit under MALFORMED_PROOF_ERROR without the need for an additional error code.

line 730: "If the value is not a valid [[XMLSCHEMA11-2]] datetime, an INVALID_PROOF_DATETIME error MUST be raised." In section Proof Configuration (eddsa-rdfc-2022).

This seems like another MALFORMED_PROOF_ERROR to me. It's just that the particular part that is malformed is the datetime.

I would expect that either we would have very specific error codes for every possible field that could be malformed (requiring us to add something like MALFORMED_CRYPTOSUITE_IDENTIFIER_ERROR and a number of others) -- or we'd have a single MALFORMED_PROOF_ERROR code with additional details about what is malformed. I would not expect that type of error to be recoverable in software, so I don't see there being much value in having additional error codes vs. just including error details (such as the message) specific to the type of error. I think using fewer error codes makes software more reusable and extensibility easier.

The other quoted lines also seem to be MALFORMED_PROOF_ERROR errors to me as well.

[Wind4Greg]

@dlongley I like the idea of a big category for all these errors too. Both on generation and verification side. MALFORMED_PROOF_ERROR can work for me. Other thoughts? Then we'd just add this one new code to the VC-DI spec. Implementations can report as much or as little additional details as they like.

[dlongley]

@Wind4Greg,

MALFORMED_PROOF_ERROR is already present :), so it's all ready to be used:

https://w3c.github.io/vc-data-integrity/#MALFORMED_PROOF_ERROR

[Wind4Greg]

@dlongley That's great! If we can get a bit more feedback. I'd be happy to roll out the PRs.

[Wind4Greg]

Hi @dlongley and @msporny based on some off line conversations it may be difficult to reduce all the previously discussed to a "MALFORMED_PROOF_ERROR". The transformation process occurs during proof generation and verification and in two of the specs (EdDSA and ECDSA) the actual procedure is reused. Hence for general categories of errors that match the overall DI processing model we could have: PROOF_TRANSFORMATION_ERROR, PROOF_GENERATION_ERROR, and PROOF_VERIFICATION_ERROR.

See below for proposed update to DI spec errors and how they could be used in the cryptosuite specs.

Error Codes in Data Integrity Spec and Suggestions

• PROOF_GENERATION_ERROR (-16): A request to generate a proof failed. See Section 4.3 Add Proof, and Section 4.4 Add Proof Set/Chain. Notes: This could subsume the INVALID_PROOF_CONFIGURATION, INVALID_PROOF_DATETIME errors from EdDSA, ECDSA, and BBS specs.
• MALFORMED_PROOF_ERROR (-17): A proof that is malformed was detected. See Section 4.5 Verify Proof. ==> Propose to change this to the more general PROOF_VERIFICATION_ERROR: An error was encountered during proof verification...
• Propose PROOF_TRANSFORMATION_ERROR (number TBA): An error was encountered during the transformation process. Note: transformation occurs during generation and verification of proofs. Notes: This is currently used in EdDSA and ECDSA specs.
• MISMATCHED_PROOF_PURPOSE_ERROR (-18): The proofPurpose value in a proof did not match the expected value. See Section 4.5 Verify Proof. ==> Propose to subsume this into PROOF_VERIFICATION_ERROR?

Would not change any of the following:

• INVALID_DOMAIN_ERROR (-19): The domain value in a proof did not match the expected value. See Section 4.5 Verify Proof.
• INVALID_CHALLENGE_ERROR (-20): The challenge value in a proof did not match the expected value. See Section 4.5 Verify Proof.
• INVALID_VERIFICATION_METHOD_URL (-21): The verificationMethod value in a proof was malformed. See Section 4.7 Retrieve Verification Method.
• INVALID_CONTROLLER_DOCUMENT_ID (-22): The id value in a controller document was malformed. See Section 4.7 Retrieve Verification Method.
• INVALID_CONTROLLER_DOCUMENT (-23): The controller document was malformed. See Section 4.7 Retrieve Verification Method.
• INVALID_VERIFICATION_METHOD (-24): The verification method in a controller document was malformed. See Section 4.7 Retrieve Verification Method.
• INVALID_PROOF_PURPOSE_FOR_VERIFICATION_METHOD (-25): The verification method in a controller document was not associated using the expected verification relationship as expressed in the proofPurpose property in the proof. See Section 4.7 Retrieve Verification Method.

[msporny]

PR w3c/vc-data-integrity#274 and #84 were raised to address this issue, and have been merged, closing.