@@ -4,6 +4,27 @@ OpenBadgesLib - Changelog
 Newest first. Dates are ISO 8601 (YYYY-MM-DD).
 
 
+* v4.2.0 - unreleased
+
+  The OpenID4VCI credential configuration can declare key attestations.
+
+  - feat(eudi): `badge_credential_configuration()` takes
+    `key_attestations_required=`, so an issuer that requires a wallet key
+    attestation can advertise it — `{}` for "required, no additional
+    constraints", or the OpenID4VCI 1.0 D.2 resistance values it accepts under
+    `key_storage` / `user_authentication`. The default stays **omitted**, and
+    that default is normative rather than conservative: §12.2.4 says the
+    parameter "MUST NOT be present in the metadata" unless the issuer requires an
+    attestation, and an empty object is not a neutral placeholder but the
+    positive claim that one is needed — emitting it unasked would have every
+    badge issuer demand a hardware-backed attestation and lock out the software
+    wallets that cannot produce one. Callers who pass nothing get the same bytes
+    as before. The shape is validated (`EudiError` on an unknown key, an empty
+    array where the spec says non-empty, a bare string where an array belongs, or
+    a non-string level) and defensively copied; the resistance values are not
+    checked, since D.2 lets each ecosystem define its own (#276).
+
+
 * v4.1.0 - 2026-07-27
 
   The EUDI SD-JWT VC track becomes revocable (IETF Token Status List) and
 
@@ -275,12 +275,61 @@ def _status_claim(status: Mapping[str, Any]) -> dict[str, Any]:
     ("credentialSubject",): "Recipient",
 }
 
+# The only two constraints OpenID4VCI 1.0 Appendix D.2 defines inside
+# ``key_attestations_required``. The *values* are deliberately extensible there
+# ("ecosystems may define their own values"), so only the shape is checked here,
+# never the level strings themselves.
+_KEY_ATTESTATION_CONSTRAINTS = ("key_storage", "user_authentication")
+
+
+def _key_attestations_required(value: Mapping[str, Any]) -> dict[str, Any]:
+    """Validate and copy a ``key_attestations_required`` object.
+
+    Empty is legal and meaningful — OpenID4VCI 1.0 §12.2.4: with both
+    ``key_storage`` and ``user_authentication`` absent the object indicates "a key
+    attestation is needed without additional constraints". What is rejected is the
+    shape a wallet cannot act on: an unknown key, an empty array where the spec
+    says non-empty, or a bare string where an array belongs — that last one is
+    silent otherwise, since ``list("iso_18045_moderate")`` is a list of letters.
+    """
+    if not isinstance(value, Mapping):
+        raise EudiError(
+            "key_attestations_required must be a mapping (use {} for 'required, "
+            "no additional constraints'), got %s" % type(value).__name__)
+    unknown = sorted(k for k in value if k not in _KEY_ATTESTATION_CONSTRAINTS)
+    if unknown:
+        raise EudiError(
+            "unknown key_attestations_required key(s) %s; OpenID4VCI 1.0 D.2 "
+            "defines only %s" % (", ".join(unknown),
+                                 ", ".join(_KEY_ATTESTATION_CONSTRAINTS)))
+    required: dict[str, Any] = {}
+    for name in _KEY_ATTESTATION_CONSTRAINTS:
+        if name not in value:
+            continue
+        levels = value[name]
+        if isinstance(levels, (str, bytes)) or not isinstance(levels, (list, tuple)):
+            raise EudiError(
+                "key_attestations_required.%s must be a list of attack potential "
+                "resistance values, got %s" % (name, type(levels).__name__))
+        if not levels:
+            raise EudiError(
+                "key_attestations_required.%s must be a non-empty array; omit the "
+                "key entirely to leave it unconstrained" % name)
+        for level in levels:
+            if not isinstance(level, str):
+                raise EudiError(
+                    "key_attestations_required.%s values must be strings, got %s"
+                    % (name, type(level).__name__))
+        required[name] = list(levels)
+    return required
+
 
 def badge_credential_configuration(
     *,
     vct: str = OB3_SD_JWT_VCT,
     signing_alg_values: Iterable[str] = ("ES256",),
     proof_signing_alg_values: Optional[Iterable[str]] = None,
+    key_attestations_required: Optional[Mapping[str, Any]] = None,
     cryptographic_binding_methods: Iterable[str] = ("jwk",),
     display: Optional[Iterable[Mapping[str, Any]]] = None,
     scope: Optional[str] = None,
@@ -293,7 +342,8 @@ def badge_credential_configuration(
     ``credential_signing_alg_values_supported``,
     ``cryptographic_binding_methods_supported``, ``proof_types_supported``
     (``jwt``, whose ``proof_signing_alg_values_supported`` defaults to
-    *signing_alg_values*), ``claims`` and ``display``, plus ``scope`` when given.
+    *signing_alg_values*), ``claims`` and ``display``, plus ``scope`` and the
+    proof type's ``key_attestations_required`` when given.
     Put it in your metadata document under the ``credential_configuration_id`` you
     want wallets to request::
 
@@ -313,6 +363,18 @@ def badge_credential_configuration(
     passes its own name, logo and locales. *signing_alg_values* defaults to
     ``ES256``, the algorithm HAIP pins for EUDI wallets.
 
+    *key_attestations_required* is omitted by default, and that default is
+    normative rather than conservative: OpenID4VCI 1.0 §12.2.4 says the parameter
+    "MUST NOT be present in the metadata" unless the issuer requires a key
+    attestation, and an **empty** object is not a neutral placeholder — it is the
+    positive claim "a key attestation is needed without additional constraints".
+    Emitting it unasked would have every badge issuer demand a hardware-backed
+    attestation from every holder and lock out software wallets. An issuer that
+    does require one passes ``{}``, or ``{"key_storage": [...],
+    "user_authentication": [...]}`` with the Appendix D.2 resistance values it
+    accepts; the shape is validated (:class:`EudiError`), the values are not —
+    D.2 lets each ecosystem define its own.
+
     Two things this deliberately does NOT do. It does not build the enclosing
     ``/.well-known/openid-credential-issuer`` document — ``credential_issuer``,
     the endpoints, the authorization servers and per-tenant display are
@@ -329,6 +391,10 @@ def badge_credential_configuration(
     """
     algs = list(signing_alg_values)
     proof_algs = list(proof_signing_alg_values) if proof_signing_alg_values is not None else algs
+    proof_jwt: dict[str, Any] = {"proof_signing_alg_values_supported": proof_algs}
+    if key_attestations_required is not None:
+        proof_jwt["key_attestations_required"] = _key_attestations_required(
+            key_attestations_required)
     claims: list[dict[str, Any]] = []
     for claim in badge_type_metadata(vct)["claims"]:
         path = list(claim["path"])
@@ -345,9 +411,7 @@ def badge_credential_configuration(
         "vct": vct,
         "credential_signing_alg_values_supported": algs,
         "cryptographic_binding_methods_supported": list(cryptographic_binding_methods),
-        "proof_types_supported": {
-            "jwt": {"proof_signing_alg_values_supported": proof_algs},
-        },
+        "proof_types_supported": {"jwt": proof_jwt},
         "claims": claims,
         "display": ([dict(d) for d in display] if display is not None
                     else [{"name": "Open Badge 3.0", "locale": locale}]),
 
@@ -12,6 +12,7 @@
     DEFAULT_DISCLOSABLE,
     OB3_SD_JWT_FORMAT,
     OB3_SD_JWT_VCT,
+    EudiError,
     badge_credential_configuration,
     badge_to_sd_jwt_claims,
     badge_type_metadata,
@@ -29,6 +30,8 @@ def test_defaults(self):
             "proof_signing_alg_values_supported"] == ["ES256"]
         assert cfg["display"] == [{"name": "Open Badge 3.0", "locale": "en"}]
         assert "scope" not in cfg                    # only when asked for
+        assert "key_attestations_required" not in cfg[
+            "proof_types_supported"]["jwt"]          # ditto — see below
 
     def test_caller_overrides(self):
         cfg = badge_credential_configuration(
@@ -57,6 +60,74 @@ def test_is_json_serializable(self):
         json.loads(json.dumps(badge_credential_configuration()))
 
 
+class TestKeyAttestationsRequired:
+    """An empty ``key_attestations_required`` is not a placeholder: OpenID4VCI
+    1.0 §12.2.4 makes it the claim "a key attestation is needed without
+    additional constraints", and says the parameter MUST NOT be present at all
+    unless the issuer requires one. So the default is absence, and asking for it
+    is explicit."""
+
+    def _jwt(self, **kwargs):
+        return badge_credential_configuration(**kwargs)["proof_types_supported"]["jwt"]
+
+    def test_absent_by_default(self):
+        # Do not "fix" a strict wallet by emitting {} here: that would declare
+        # every badge issuer demands a key attestation, locking out the software
+        # wallets that cannot produce one.
+        assert "key_attestations_required" not in self._jwt()
+
+    def test_empty_object_means_required_without_constraints(self):
+        assert self._jwt(key_attestations_required={})[
+            "key_attestations_required"] == {}
+
+    def test_constraints_are_emitted(self):
+        jwt = self._jwt(key_attestations_required={
+            "key_storage": ["iso_18045_moderate"],
+            "user_authentication": ["iso_18045_moderate", "iso_18045_high"]})
+        assert jwt["key_attestations_required"] == {
+            "key_storage": ["iso_18045_moderate"],
+            "user_authentication": ["iso_18045_moderate", "iso_18045_high"]}
+        assert jwt["proof_signing_alg_values_supported"] == ["ES256"]
+
+    def test_is_copied_not_aliased(self):
+        mine = {"key_storage": ["iso_18045_moderate"]}
+        emitted = self._jwt(key_attestations_required=mine)[
+            "key_attestations_required"]
+        emitted["user_authentication"] = ["iso_18045_high"]
+        emitted["key_storage"].append("iso_18045_basic")
+        assert mine == {"key_storage": ["iso_18045_moderate"]}
+
+    def test_is_json_serializable(self):
+        import json
+        json.loads(json.dumps(badge_credential_configuration(
+            key_attestations_required={"key_storage": ["iso_18045_moderate"]})))
+
+    def test_unknown_key_is_rejected(self):
+        with pytest.raises(EudiError):
+            self._jwt(key_attestations_required={
+                "key_storag": ["iso_18045_moderate"]})
+
+    def test_empty_array_is_rejected(self):
+        # The spec says "non-empty array"; omitting the key is how you say
+        # "unconstrained".
+        with pytest.raises(EudiError):
+            self._jwt(key_attestations_required={"key_storage": []})
+
+    def test_bare_string_is_rejected(self):
+        # Left alone this would be emitted as a list of single letters.
+        with pytest.raises(EudiError):
+            self._jwt(key_attestations_required={
+                "user_authentication": "iso_18045_moderate"})
+
+    def test_non_string_level_is_rejected(self):
+        with pytest.raises(EudiError):
+            self._jwt(key_attestations_required={"key_storage": [4]})
+
+    def test_non_mapping_is_rejected(self):
+        with pytest.raises(EudiError):
+            self._jwt(key_attestations_required=["iso_18045_moderate"])
+
+
 class TestNoDrift:
     """The reason this function exists: a hand-written copy gets the vct and the
     claim set wrong, and a wallet then either rejects the credential or displays
 
@@ -374,6 +374,23 @@ metadata = {                                    # your document, your policy
 
 The entry's `vct` is the one `issue_badge_sd_jwt()` actually stamps and its `claims` are derived from the same `badge_type_metadata()` document you serve at that `vct` — the two artifacts cannot drift, which is the failure this prevents (a wallet that rejects the credential, or displays nothing). `credential_signing_alg_values_supported` defaults to `ES256`, the HAIP algorithm for EUDI wallets; `cryptographic_binding_methods_supported` to `jwk`, matching the `holder_jwk=` key binding above. Pure-Python: no `[eudi]` extra needed.
 
+#### Key attestations
+
+The `jwt` proof type can also declare `key_attestations_required` — what the issuer expects a wallet to prove about where it keeps the holder's key. It is **omitted by default, and that is the normative default**, not a conservative one. OpenID4VCI 1.0 §12.2.4: *"If the Credential Issuer does not require a key attestation, this parameter MUST NOT be present in the metadata."* An empty object is not a neutral placeholder either — it is the positive claim *"a key attestation is needed without additional constraints"*. So do not add it to satisfy a strict wallet parser: you would be telling every holder that your badge demands a hardware-backed attestation, and the software wallets that cannot produce one would be locked out of an ordinary Open Badge.
+
+An issuer that genuinely requires one asks for it, either bare or with the Appendix D.2 resistance values it accepts:
+
+```python
+badge_credential_configuration(key_attestations_required={})   # required, unconstrained
+
+badge_credential_configuration(key_attestations_required={
+    'key_storage': ['iso_18045_moderate'],
+    'user_authentication': ['iso_18045_moderate'],
+})
+```
+
+The shape is validated — an unknown key, an empty array (the spec says *non-empty*), a bare string where an array belongs, or a non-string level all raise `EudiError` at build time rather than at a holder's wallet. The resistance *values* are not checked: D.2 defines `iso_18045_high` / `iso_18045_moderate` / `iso_18045_enhanced-basic` / `iso_18045_basic` but lets each ecosystem define its own. Note that HAIP requires *wallets* to support key attestations (§4.5.1); it does not require issuers to demand them.
+
 **Out of scope on purpose:** the enclosing `/.well-known/openid-credential-issuer` document (endpoints, authorization servers, per-tenant display — deployment policy, and one document per tenant in a multi-tenant issuer), the Credential Offer, the Credential Response and the nonce store. The protocol endpoints are the application's; this library supplies the format knowledge. Note that OpenID4VCI 1.0 Final carries `claims`/`display` at the top level of the configuration, which is what this emits; the EU reference issuer nests them under `credential_metadata` — nest them yourself if you must match that deployment.
 
 ### Verifying a third-party badge via eIDAS X.509 / EU Trusted Lists