feat: add structured error codes to WalletError for DCQL query failures

Author: Oleksandr Abakumov

Sources/EudiWalletKit/Models/WalletError.swift

@@ -17,12 +17,34 @@
 import Foundation
 /// Wallet error
 public struct WalletError: LocalizedError {
+	/// Structured error code for programmatic handling
+	public enum Code: String, Sendable {
+		/// The verifier requested a claim that is not present in the credential
+		case claimNotFound
+		/// The verifier requested a credential/document type that is not in the wallet
+		case credentialNotFound
+		/// The verifier requested a claim whose value does not match
+		case claimValueMismatch
+		/// No claim_set option could be satisfied
+		case claimSetNotSatisfied
+		/// A required credential_set cannot be satisfied
+		case credentialSetNotSatisfied
+		/// The DCQL query could not be satisfied (general)
+		case dcqlQueryNotSatisfied
+	}
+
 	public let description: String
 	public let localizationKey: String?
+	/// Structured error code for programmatic handling. `nil` for legacy errors.
+	public let code: Code?
+	/// Additional context about the error (e.g. claim path, docType).
+	public let context: [String: String]
 
-	public init(description: String, localizationKey: String? = nil) {
+	public init(description: String, localizationKey: String? = nil, code: Code? = nil, context: [String: String] = [:]) {
 		self.description = description
 		self.localizationKey = localizationKey
+		self.code = code
+		self.context = context
 	}
 
 	public var errorDescription: String? {

Sources/EudiWalletKit/Services/Openid4VpUtils.swift

@@ -217,7 +217,7 @@ extension OpenId4VpUtils {
 			let format = credQuery.dataFormat
 			// Find matching credentials
 			let matchingCredIds = queryable.getCredentials(docOrVctType: docType, docDataFormat: format)
-			if matchingCredIds.isEmpty, dcql.credentialSets == nil { throw WalletError(description: "Credential with docType \(docType) cannot be found.") }
+			if matchingCredIds.isEmpty, dcql.credentialSets == nil { throw WalletError(description: "Credential with docType \(docType) cannot be found.", code: .credentialNotFound, context: ["docType": docType]) }
 			// Try to find a credential that satisfies the claim requirements
 			for credId in matchingCredIds {
 				do {
@@ -259,7 +259,7 @@ extension OpenId4VpUtils {
 				}
 				let isSetRequired = credSet.required ?? CredentialSetQuery.defaultRequiredValue
 				if isSetRequired, !isSetSatisfied {
-					throw WalletError(description: "Required credential_set \(credSet.options) cannot be satisfied")
+					throw WalletError(description: "Required credential_set \(credSet.options) cannot be satisfied", code: .credentialSetNotSatisfied)
 				}
 			}
 		} else {
@@ -270,7 +270,7 @@ extension OpenId4VpUtils {
 		if result.isEmpty {
 			let notFoundCred = dcql.credentials.first { c in credentialQueryResults[c.id] == nil }
 			if let notFoundCred {logger.warning("No credential found matching docType: \(notFoundCred.docType ?? "") with format: \(notFoundCred.format)")}
-			throw lastError ?? WalletError(description: "DCQL query could not be satisfied")
+			throw lastError ?? WalletError(description: "DCQL query could not be satisfied", code: .dcqlQueryNotSatisfied)
 		}
 		return result
 	}
@@ -315,7 +315,7 @@ extension OpenId4VpUtils {
 			} // next claimSetOption
 			// No claim set option could be satisfied
 			let claimPathStr = firstMissingClaimInOption?.value.map(\.claimName).joined(separator: "/") ?? "unknown"
-			throw WalletError(description: "No claim_set option satisfied. First missing claim: \(claimPathStr)")
+			throw WalletError(description: "No claim_set option satisfied. First missing claim: \(claimPathStr)", code: .claimSetNotSatisfied, context: ["claimPath": claimPathStr])
 		} else {
 			// No claim_sets: all claims must be available
 			var selectedPaths: [ClaimsQuery] = []
@@ -324,11 +324,11 @@ extension OpenId4VpUtils {
 				if let values = claim.values, !values.isEmpty {
 					if !queryable.hasClaimWithValue(id: credId, claimPath: claim.path, values: values) {
 						let claimPathStr = claim.path.value.map(\.claimName).joined(separator: "/")
-						throw WalletError(description: "Claim value mismatch for: \(claimPathStr)")
+						throw WalletError(description: "Claim value mismatch for: \(claimPathStr)", code: .claimValueMismatch, context: ["claimPath": claimPathStr])
 					}
 				} else if !queryable.hasClaim(id: credId, claimPath: claim.path) {
 					let claimPathStr = claim.path.value.map(\.claimName).joined(separator: "/")
-					throw WalletError(description: "Claim not found: \(claimPathStr)")
+					throw WalletError(description: "Claim not found: \(claimPathStr)", code: .claimNotFound, context: ["claimPath": claimPathStr])
 				}
 				selectedPaths.append(claim)
 			}