openbadgeslib 4.1.0__tar.gz → 4.2.0__tar.gz

{openbadgeslib-4.1.0 → openbadgeslib-4.2.0}/Changelog.txt

@@ -4,6 +4,29 @@ OpenBadgesLib - Changelog
 Newest first. Dates are ISO 8601 (YYYY-MM-DD).
 
 
+* v4.2.0 - 2026-07-29
+
+  The OpenID4VCI credential configuration an issuer advertises can now declare
+  the key attestation it requires from a wallet — opt-in, because the spec makes
+  the field's mere presence a demand.
+
+  - 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

{openbadgeslib-4.1.0 → openbadgeslib-4.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openbadgeslib
-Version: 4.1.0
+Version: 4.2.0
 Summary: Production-ready Python library & CLI for Open Badges 3.0 (W3C Verifiable Credentials): issue, verify, and revoke JWT-VC credentials with Bitstring Status Lists and did:web — plus strict OB 2.0 and legacy OB 1.0.
 Author-email: Luis González Fernández <luisgf@luisgf.es>, Jesús Cea Avión <jcea@jcea.es>
 License: LGPLv3

{openbadgeslib-4.1.0 → openbadgeslib-4.2.0}/openbadgeslib/ob3/eudi.py

@@ -275,12 +275,61 @@ _CLAIM_DISPLAY_NAMES: dict[tuple[str, ...], str] = {
     ("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}]),

{openbadgeslib-4.1.0 → openbadgeslib-4.2.0}/openbadgeslib/util.py

@@ -21,7 +21,7 @@
         License along with this library.
 """
 
-__version__ = '4.1.0'
+__version__ = '4.2.0'
 
 import contextlib
 import hashlib

{openbadgeslib-4.1.0 → openbadgeslib-4.2.0}/openbadgeslib.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openbadgeslib
-Version: 4.1.0
+Version: 4.2.0
 Summary: Production-ready Python library & CLI for Open Badges 3.0 (W3C Verifiable Credentials): issue, verify, and revoke JWT-VC credentials with Bitstring Status Lists and did:web — plus strict OB 2.0 and legacy OB 1.0.
 Author-email: Luis González Fernández <luisgf@luisgf.es>, Jesús Cea Avión <jcea@jcea.es>
 License: LGPLv3

{openbadgeslib-4.1.0 → openbadgeslib-4.2.0}/tests/test_ob3_eudi_oid4vci.py

@@ -12,6 +12,7 @@ from openbadgeslib.ob3.eudi import (
     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 @@ class TestCredentialConfigurationShape:
             "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 @@ class TestCredentialConfigurationShape:
         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