Merge pull request #28 from Indicio-tech/fix/mdoc-issuance-error-handling

fix: validate mandatory mDL fields early with clear error messages

Author: burdettadam

oid4vc/integration/conformance/setup_acapy.py

@@ -237,16 +237,19 @@ async def create_credential_offer(
     credential_config_id: str,
     issuer_did: str,
     pin: str | None = None,
+    credential_subject: dict | None = None,
 ) -> dict:
     """Create a pre-authorized credential offer and return offer details."""
-    exchange_body: dict[str, Any] = {
-        "supported_cred_id": credential_config_id,
-        "credential_subject": {
+    if credential_subject is None:
+        credential_subject = {
             "given_name": "Alice",
             "family_name": "Smith",
             "email": "alice@example.com",
             "birthdate": "1990-01-15",
-        },
+        }
+    exchange_body: dict[str, Any] = {
+        "supported_cred_id": credential_config_id,
+        "credential_subject": credential_subject,
         # verification_method format: {did}#0  (selects the first key on the DID)
         "verification_method": f"{issuer_did}#0",
     }
@@ -773,6 +776,19 @@ async def main() -> None:
             ISSUER_ADMIN_URL,
             mdoc_config["supported_cred_id"],
             p256_did,
+            credential_subject={
+                "family_name": "Smith",
+                "given_name": "Alice",
+                "birth_date": "1990-01-15",
+                "issue_date": "2024-01-01",
+                "expiry_date": "2029-01-01",
+                "issuing_country": "US",
+                "issuing_authority": "US DMV",
+                "document_number": "DL-12345678",
+                "portrait": "bXVzdGFjaGlv",
+                "driving_privileges": [],
+                "un_distinguishing_sign": "USA",
+            },
         )
 
         setup_output["issuer"] = {

oid4vc/integration/tests/helpers/constants.py

@@ -107,14 +107,16 @@ class ENDPOINTS:
 
 # ISO 18013-5 mDL mandatory fields required by create_and_sign_mdl
 # All mandatory fields per ISO 18013-5 OrgIso1801351 struct:
-# family_name, given_name, birth_date are provided by each test individually.
-# The remaining 8 mandatory fields are collected here.
+# family_name, given_name are provided by each test individually.
+# All remaining mandatory fields are collected here (including birth_date).
 MDL_PORTRAIT: Final[str] = "SGVsbG8gV29ybGQ="  # base64("Hello World") placeholder
 MDL_DRIVING_PRIVILEGES: Final[list] = []
 MDL_UN_DISTINGUISHING_SIGN: Final[str] = "USA"
 
-# Merge these into any mDL credential_subject["org.iso.18013.5.1"] dict
+# Merge these into any mDL credential_subject["org.iso.18013.5.1"] dict.
+# Tests that need a dynamic birth_date should override it after spreading.
 MDL_MANDATORY_FIELDS: Final[dict] = {
+    "birth_date": "1990-01-15",
     "issue_date": "2024-01-01",
     "expiry_date": "2029-01-01",
     "issuing_country": "US",

oid4vc/integration/tests/mdoc/test_mdoc_age_predicates.py

@@ -19,6 +19,8 @@
 
 import pytest
 
+from tests.helpers.constants import MDL_MANDATORY_FIELDS
+
 LOGGER = logging.getLogger(__name__)
 
 
@@ -97,7 +99,8 @@ async def test_age_over_18_with_birth_date(
             "org.iso.18013.5.1": {
                 "given_name": "Alice",
                 "family_name": "Smith",
-                "birth_date": birth_date,
+                **MDL_MANDATORY_FIELDS,
+                "birth_date": birth_date,  # override with computed age-based date
                 "age_over_18": True,
                 "age_over_21": True,
             }

oid4vc/mso_mdoc/cred_processor.py

@@ -27,7 +27,7 @@
 from oid4vc.pop_result import PopResult
 
 from .key_generation import generate_self_signed_certificate, pem_from_jwk, pem_to_jwk  # noqa: F401
-from .mdoc.issuer import isomdl_mdoc_sign
+from .mdoc.issuer import MDL_MANDATORY_FIELDS, isomdl_mdoc_sign
 from .mdoc.cred_verifier import MsoMdocCredVerifier
 from .mdoc.pres_verifier import MsoMdocPresVerifier
 from .mdoc.trust_store import WalletTrustStore
@@ -524,6 +524,26 @@ def validate_credential_subject(self, supported: SupportedCredential, subject: d
         if not isinstance(subject, dict):
             raise CredProcessorError("Credential subject must be a dictionary")
 
+        # For mDL doctypes, validate mandatory ISO 18013-5 fields early so
+        # that the API caller gets an actionable error at exchange-creation
+        # time rather than an opaque FFI error at issuance time.
+        doctype = (supported.format_data or {}).get("doctype", "")
+        if doctype == "org.iso.18013.5.1.mDL":
+            # The subject may be namespace-wrapped or flat.
+            claims = subject.get("org.iso.18013.5.1", subject)
+            # driving_privileges defaults to [] at issuance time, so
+            # exclude it from the early check.
+            missing = [
+                f
+                for f in MDL_MANDATORY_FIELDS
+                if f != "driving_privileges" and f not in claims
+            ]
+            if missing:
+                raise CredProcessorError(
+                    f"mDL credential_subject is missing mandatory ISO 18013-5 "
+                    f"data element(s): {', '.join(missing)}"
+                )
+
         return True
 
     def validate_supported_credential(self, supported: SupportedCredential):

oid4vc/mso_mdoc/mdoc/__init__.py

@@ -1,10 +1,11 @@
 """MDoc module."""
 
-from .issuer import isomdl_mdoc_sign, parse_mdoc
+from .issuer import MDL_MANDATORY_FIELDS, isomdl_mdoc_sign, parse_mdoc
 from .mdoc_verify import MdocVerifyResult, mdoc_verify
 from .utils import extract_signing_cert, flatten_trust_anchors, split_pem_chain
 
 __all__ = [
+    "MDL_MANDATORY_FIELDS",
     "isomdl_mdoc_sign",
     "parse_mdoc",
     "mdoc_verify",

oid4vc/mso_mdoc/mdoc/issuer.py

@@ -39,6 +39,24 @@
 LOGGER = logging.getLogger(__name__)
 
 
+# ISO 18013-5 mandatory data elements for the org.iso.18013.5.1 namespace.
+# These are non-Option fields in the upstream isomdl OrgIso1801351 struct;
+# omitting any of them causes a GeneralConstructionError from the Rust FFI.
+MDL_MANDATORY_FIELDS = (
+    "family_name",
+    "given_name",
+    "birth_date",
+    "issue_date",
+    "expiry_date",
+    "issuing_country",
+    "issuing_authority",
+    "document_number",
+    "portrait",
+    "driving_privileges",
+    "un_distinguishing_sign",
+)
+
+
 def _prepare_mdl_namespaces(
     payload: Mapping[str, Any],
 ) -> tuple[str, Optional[str]]:
@@ -51,6 +69,9 @@ def _prepare_mdl_namespaces(
         Tuple of (mdl_items_json, aamva_items_json) where aamva_items_json
         may be None. Both are JSON-serialized dicts; isomdl-uniffi handles
         CBOR encoding internally.
+
+    Raises:
+        ValueError: If any ISO 18013-5 mandatory data element is missing.
     """
     mdl_payload = payload.get("org.iso.18013.5.1", payload)
     mdl_items = {k: v for k, v in mdl_payload.items() if k != "org.iso.18013.5.1.aamva"}
@@ -60,6 +81,16 @@ def _prepare_mdl_namespaces(
     # the field don't hit a GeneralConstructionError.
     mdl_items.setdefault("driving_privileges", [])
 
+    # Validate mandatory fields before calling into the Rust FFI so that
+    # callers get a clear error message instead of an opaque
+    # GeneralConstructionError.
+    missing = [f for f in MDL_MANDATORY_FIELDS if f not in mdl_items]
+    if missing:
+        raise ValueError(
+            f"mDL credential_subject is missing mandatory ISO 18013-5 "
+            f"data element(s): {', '.join(missing)}"
+        )
+
     aamva_payload = payload.get("org.iso.18013.5.1.aamva")
     aamva_items_json = json.dumps(aamva_payload) if aamva_payload else None