openbadgeslib 1.3.0__tar.gz → 2.0.0__tar.gz

{openbadgeslib-1.3.0 → openbadgeslib-2.0.0}/Changelog.txt

@@ -4,6 +4,36 @@ OpenBadgesLib - Changelog
 Newest first. Dates are ISO 8601 (YYYY-MM-DD).
 
 
+* v2.0.0 - 2026-07-01
+
+  - BREAKING (OB3): OpenBadges 3.0 credentials are now secured with the native
+    OB 3.0 VC-JWT (spec §8.2): the JWT payload IS the credential (its members at
+    the top level, no 'vc' claim wrapper), validFrom maps to 'nbf' (there is no
+    'iat'), and the JOSE header carries the issuer's public key as a 'jwk'.
+    Tokens issued by 1.x (the VCDM-1.1-style 'vc'-wrapper) are NOT compatible.
+
+  - BREAKING (OB3): baked images use the OB 3.0 document-format identifiers —
+    the PNG iTXt keyword 'openbadgecredential' and the SVG element
+    <openbadges:credential> (namespace https://purl.imsglobal.org/ob/v3p0). OB3
+    images baked by 1.x (OB2 identifiers) are not read by this verifier.
+
+  - OB3 verifier now accepts credentials that are valid per the spec schema but
+    were previously rejected: the AchievementCredential type alias, an issuer
+    given as a string IRI (not only a Profile object), and a credentialSubject
+    without an 'id' (identity conveyed via 'identifier').
+
+  - OB3 verifier now enforces required structure it previously ignored: the
+    @context (VC 2.0 + OB v3p0 pair) is validated, and the registered claims
+    'iss' and 'nbf' are required (with 'sub' required when the subject has an id).
+
+  - OB3 credentialStatus now honors statusPurpose: 'suspension' is reported
+    distinctly from 'revocation', a non-revocation/suspension purpose (e.g.
+    'message') no longer fails verification, and the entry's purpose is
+    cross-checked against the fetched status list's declared purpose.
+
+  - OpenBadges 2.0 is unchanged; only the OB3 path is affected.
+
+
 * v1.3.0 - 2026-07-01
 
   - SECURITY: download_file() now blocks server-side request forgery. The URLs

{openbadgeslib-1.3.0/openbadgeslib.egg-info → openbadgeslib-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openbadgeslib
-Version: 1.3.0
+Version: 2.0.0
 Summary: A library to sign and verify OpenBadges
 Author-email: Luis González Fernández <luisgf@luisgf.es>, Jesús Cea Avión <jcea@jcea.es>
 License: LGPLv3

{openbadgeslib-1.3.0 → openbadgeslib-2.0.0}/openbadgeslib/baking.py

@@ -34,8 +34,16 @@ from typing import List, Optional, Tuple, Union
 from defusedxml.minidom import parseString
 from png import Reader, signature as _png_signature
 
+# OB 2.0 document-format identifiers.
 ITXT_KEYWORD = b'openbadges'
 SVG_ELEMENT = 'openbadges:assertion'
+SVG_NS = 'http://openbadges.org'
+
+# OB 3.0 document-format identifiers (differ from OB 2.0). Selected via the
+# keyword-only args below so OB2 and OB3 bake/extract their own carriers.
+ITXT_KEYWORD_OB3 = b'openbadgecredential'
+SVG_ELEMENT_OB3 = 'openbadges:credential'
+SVG_NS_OB3 = 'https://purl.imsglobal.org/ob/v3p0'
 
 # Maximum bytes a compressed iTXt token is allowed to inflate to. A JWS/JWT-VC
 # is a few KB; this cap stops a crafted zlib bomb from exhausting memory during
@@ -47,9 +55,9 @@ class DecompressionLimitExceeded(Exception):
     """Raised when a compressed iTXt token inflates beyond the allowed size."""
 
 
-def _split_openbadges_itxt(data: bytes) -> Optional[bytes]:
-    keyword, sep, rest = data.partition(b'\x00')
-    if sep != b'\x00' or keyword != ITXT_KEYWORD or len(rest) < 2:
+def _split_openbadges_itxt(data: bytes, keyword: bytes = ITXT_KEYWORD) -> Optional[bytes]:
+    chunk_keyword, sep, rest = data.partition(b'\x00')
+    if sep != b'\x00' or chunk_keyword != keyword or len(rest) < 2:
         return None
     return rest
 
@@ -66,14 +74,16 @@ def _bounded_inflate(data: bytes, limit: int = MAX_ITXT_DECOMPRESSED) -> bytes:
 
 # ── SVG ─────────────────────────────────────────────────────────────────────
 
-def bake_svg(image_bytes: bytes, token: str, comment: Optional[str] = None) -> bytes:
-    """Return *image_bytes* with an ``<openbadges:assertion verify=token>``
-    element (and an optional XML comment) appended to the root ``<svg>``."""
+def bake_svg(image_bytes: bytes, token: str, comment: Optional[str] = None, *,
+             element: str = SVG_ELEMENT, namespace: str = SVG_NS) -> bytes:
+    """Return *image_bytes* with an ``<element verify=token>`` node (and an
+    optional XML comment) appended to the root ``<svg>``. *element*/*namespace*
+    default to the OB 2.0 identifiers; OB 3.0 passes its own."""
     svg_doc = parseString(image_bytes)
     try:
         svg_tag = svg_doc.getElementsByTagName('svg').item(0)
-        node = svg_doc.createElement(SVG_ELEMENT)
-        node.attributes['xmlns:openbadges'] = 'http://openbadges.org'
+        node = svg_doc.createElement(element)
+        node.attributes['xmlns:openbadges'] = namespace
         node.attributes['verify'] = token
         svg_tag.appendChild(node)
         if comment:
@@ -83,24 +93,24 @@ def bake_svg(image_bytes: bytes, token: str, comment: Optional[str] = None) -> b
         svg_doc.unlink()
 
 
-def has_svg(image_bytes: bytes) -> bool:
-    """Return True if *image_bytes* already carries an OpenBadges assertion."""
+def has_svg(image_bytes: bytes, *, element: str = SVG_ELEMENT) -> bool:
+    """Return True if *image_bytes* already carries an *element* node."""
     svg_doc = parseString(image_bytes)
     try:
-        return bool(svg_doc.getElementsByTagName(SVG_ELEMENT))
+        return bool(svg_doc.getElementsByTagName(element))
     finally:
         svg_doc.unlink()
 
 
-def extract_svg(image_bytes: bytes) -> Optional[str]:
-    """Return the embedded token string, or None if there is no assertion node.
+def extract_svg(image_bytes: bytes, *, element: str = SVG_ELEMENT) -> Optional[str]:
+    """Return the embedded token string, or None if there is no *element* node.
 
     Raises on malformed XML (left to the caller to map to its own error type).
     """
     svg_doc = None
     try:
         svg_doc = parseString(image_bytes)
-        nodes = svg_doc.getElementsByTagName(SVG_ELEMENT)
+        nodes = svg_doc.getElementsByTagName(element)
         if not nodes:
             return None
         return nodes[0].attributes['verify'].nodeValue
@@ -124,28 +134,31 @@ def _serialize_png(chunks: List[Tuple[Union[str, bytes], bytes]]) -> bytes:
     return out
 
 
-def bake_png(image_bytes: bytes, token: str, text_comment: Optional[str] = None) -> bytes:
-    """Return *image_bytes* with the token stored in an ``openbadges`` iTXt
-    chunk (and an optional ``tEXt`` comment chunk) inserted before IEND."""
+def bake_png(image_bytes: bytes, token: str, text_comment: Optional[str] = None, *,
+             keyword: bytes = ITXT_KEYWORD) -> bytes:
+    """Return *image_bytes* with the token stored in a *keyword* iTXt chunk (and
+    an optional ``tEXt`` comment chunk) inserted before IEND. *keyword* defaults
+    to the OB 2.0 identifier; OB 3.0 passes ``openbadgecredential``."""
     chunks = list(Reader(bytes=image_bytes).chunks())
-    itxt_data = ITXT_KEYWORD + pack('BBBBB', 0, 0, 0, 0, 0) + token.encode('utf-8')
+    itxt_data = keyword + pack('BBBBB', 0, 0, 0, 0, 0) + token.encode('utf-8')
     chunks.insert(len(chunks) - 1, ('iTXt', itxt_data))
     if text_comment:
         chunks.insert(len(chunks) - 1, ('tEXt', text_comment.encode('utf-8')))
     return _serialize_png(chunks)
 
 
-def has_png(image_bytes: bytes) -> bool:
-    """Return True if *image_bytes* already carries an OpenBadges iTXt chunk."""
+def has_png(image_bytes: bytes, *, keyword: bytes = ITXT_KEYWORD) -> bool:
+    """Return True if *image_bytes* already carries a *keyword* iTXt chunk."""
     for tag, data in Reader(bytes=image_bytes).chunks():
         tag_str = tag.decode('ascii') if isinstance(tag, bytes) else tag
-        if tag_str == 'iTXt' and _split_openbadges_itxt(data) is not None:
+        if tag_str == 'iTXt' and _split_openbadges_itxt(data, keyword) is not None:
             return True
     return False
 
 
-def extract_png(image_bytes: bytes, max_decompressed: int = MAX_ITXT_DECOMPRESSED) -> Optional[str]:
-    """Return the embedded token string, or None if there is no openbadges
+def extract_png(image_bytes: bytes, max_decompressed: int = MAX_ITXT_DECOMPRESSED, *,
+                keyword: bytes = ITXT_KEYWORD) -> Optional[str]:
+    """Return the embedded token string, or None if there is no *keyword*
     iTXt chunk.
 
     Parses the iTXt structure (keyword, compression flag/method, language tag,
@@ -159,7 +172,7 @@ def extract_png(image_bytes: bytes, max_decompressed: int = MAX_ITXT_DECOMPRESSE
         if tag_str != 'iTXt':
             continue
 
-        rest = _split_openbadges_itxt(data)
+        rest = _split_openbadges_itxt(data, keyword)
         if rest is None:
             continue
         compression_flag = rest[0]

{openbadgeslib-1.3.0 → openbadgeslib-2.0.0}/openbadgeslib/ob3/credential.py

@@ -20,19 +20,41 @@
         License along with this library.
 """
 
+import re
 import uuid
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from typing import Any, List, Optional
 
+_VC2_CONTEXT = "https://www.w3.org/ns/credentials/v2"
+
 OB3_CONTEXT = [
-    "https://www.w3.org/ns/credentials/v2",
+    _VC2_CONTEXT,
     "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json",
 ]
 
+# The OB v3p0 context URI, optionally version-pinned (…/context-3.0.3.json),
+# mirroring the JSON Schema's @context[1] pattern.
+_OB_CONTEXT_RE = re.compile(
+    r'^https://purl\.imsglobal\.org/spec/ob/v3p0/context(-\d+\.\d+\.\d+)?\.json$')
+
 _SUPPORTED_ALGORITHMS = {'RS256', 'RS384', 'RS512', 'ES256', 'ES384', 'ES512', 'EdDSA'}
 
 
+def _validate_context(ctx: Any) -> None:
+    """Validate an OpenBadgeCredential ``@context`` per the schema: an array
+    whose first item is the VC 2.0 context and whose second is the OB v3p0
+    context; extra items may follow. Raises ValueError otherwise."""
+    if not isinstance(ctx, list) or len(ctx) < 2:
+        raise ValueError(
+            "@context must be an array with the VC 2.0 and OB v3p0 contexts")
+    if ctx[0] != _VC2_CONTEXT:
+        raise ValueError("@context[0] must be %r" % (_VC2_CONTEXT,))
+    if not (isinstance(ctx[1], str) and _OB_CONTEXT_RE.match(ctx[1])):
+        raise ValueError(
+            "@context[1] must be the OB v3p0 context URI, got %r" % (ctx[1],))
+
+
 def _iso(dt: datetime) -> str:
     """Return a datetime as an ISO 8601 string with Z suffix."""
     return dt.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
@@ -90,7 +112,9 @@ class OpenBadgeCredential:
     """An OpenBadges 3.0 credential (W3C Verifiable Credential)."""
 
     issuer: Issuer
-    recipient_id: str          # 'mailto:email@example.com' or a DID
+    # 'mailto:email@example.com' or a DID; Optional because OB3 makes
+    # credentialSubject.id optional (identity may travel via 'identifier').
+    recipient_id: Optional[str]
     achievement: Achievement
     id: Optional[str] = None   # auto-generated as 'urn:uuid:…' if absent
     name: Optional[str] = None  # defaults to achievement.name
@@ -124,11 +148,13 @@ class OpenBadgeCredential:
             "issuer": self.issuer.to_dict(),
             "validFrom": _iso(self.issuance_date),
             "credentialSubject": {
-                "id": self.recipient_id,
                 "type": ["AchievementSubject"],
                 "achievement": self.achievement.to_dict(),
             },
         }
+        # credentialSubject.id is optional; emit it only when present.
+        if self.recipient_id is not None:
+            vc["credentialSubject"]["id"] = self.recipient_id
         if self.expiration_date:
             vc["validUntil"] = _iso(self.expiration_date)
         if self.evidence_url:
@@ -140,16 +166,23 @@ class OpenBadgeCredential:
         return vc
 
     def to_jwt_payload(self) -> dict:
-        """Return the JWT payload for a JWT-VC signed credential."""
+        """Return the JWT payload for a JWT-VC signed credential.
+
+        OB 3.0 §8.2.4.1 (native VC-JWT): the JWT payload **is** the
+        OpenBadgeCredential — its members sit at the top level of the payload,
+        not nested under a ``vc`` claim — with the registered claims alongside:
+        ``iss`` (issuer id), ``sub`` (credentialSubject id), ``jti`` (credential
+        id) and ``nbf`` (validFrom). ``exp`` mirrors validUntil when present.
+        There is deliberately no ``iat`` claim (the spec maps issuance to nbf).
+        """
         # __post_init__ guarantees issuance_date is set.
         assert self.issuance_date is not None
-        payload: dict = {
-            "iss": self.issuer.id,
-            "sub": self.recipient_id,
-            "jti": self.id,
-            "iat": int(self.issuance_date.timestamp()),
-            "vc":  self.to_vc(),
-        }
+        payload: dict = dict(self.to_vc())   # credential at the payload top level
+        payload["iss"] = self.issuer.id
+        if self.recipient_id is not None:
+            payload["sub"] = self.recipient_id
+        payload["jti"] = self.id
+        payload["nbf"] = int(self.issuance_date.timestamp())
         if self.expiration_date:
             payload["exp"] = int(self.expiration_date.timestamp())
         return payload
@@ -160,21 +193,33 @@ class OpenBadgeCredential:
     def from_jwt_payload(cls, payload: dict) -> "OpenBadgeCredential":
         """Reconstruct an OpenBadgeCredential from a decoded JWT payload.
 
-        The ``vc`` claim is untrusted input, so its structure is validated
-        explicitly: every required object/field is checked and a clear
-        ``ValueError`` is raised on anything missing or malformed (the OB3
-        verifier wraps these as ``OB3VerificationError``).
+        OB 3.0 native VC-JWT: the payload IS the credential (its members at the
+        top level), so ``payload`` is read directly as the credential body. It
+        is untrusted input, so its structure is validated explicitly: every
+        required object/field is checked and a clear ``ValueError`` is raised on
+        anything missing or malformed (the OB3 verifier wraps these as
+        ``OB3VerificationError``). The registered claims (iss/sub/jti/nbf/exp)
+        coexist at the top level and are simply ignored by the field reads here.
         """
-        vc = _as_dict(payload.get("vc"), "vc")
-
-        issuer_data = _as_dict(vc.get("issuer"), "vc.issuer")
-        issuer = Issuer(
-            id=_require(issuer_data, "id", "vc.issuer"),
-            name=issuer_data.get("name", ""),
-            url=issuer_data.get("url"),
-            email=issuer_data.get("email"),
-            image_url=_as_dict_or_empty(issuer_data.get("image")).get("id"),
-        )
+        vc = _as_dict(payload, "credential")
+
+        _validate_context(vc.get("@context"))
+
+        # issuer may be a Profile object or a bare string IRI (both schema-valid).
+        issuer_raw = vc.get("issuer")
+        if isinstance(issuer_raw, str):
+            if not issuer_raw:
+                raise ValueError("field vc.issuer must not be empty")
+            issuer = Issuer(id=issuer_raw, name="")
+        else:
+            issuer_data = _as_dict(issuer_raw, "vc.issuer")
+            issuer = Issuer(
+                id=_require(issuer_data, "id", "vc.issuer"),
+                name=issuer_data.get("name", ""),
+                url=issuer_data.get("url"),
+                email=issuer_data.get("email"),
+                image_url=_as_dict_or_empty(issuer_data.get("image")).get("id"),
+            )
 
         # credentialSubject may be a single object or a (non-empty) array.
         subj_raw = vc.get("credentialSubject")
@@ -219,10 +264,23 @@ class OpenBadgeCredential:
         else:
             credential_status = []
 
+        # credentialSubject.id is optional (schema); identity may instead be
+        # conveyed via one or more 'identifier' objects. Reject only when BOTH
+        # are absent — a subject with no identity at all is non-conformant.
+        recipient_id = subj.get("id")
+        if recipient_id is not None and not isinstance(recipient_id, str):
+            raise ValueError("field vc.credentialSubject.id must be a string")
+        if not recipient_id:                        # None or empty string
+            identifiers = subj.get("identifier")
+            if not (isinstance(identifiers, list) and identifiers):
+                raise ValueError(
+                    "vc.credentialSubject must have an 'id' or an 'identifier'")
+            recipient_id = None
+
         return cls(
             id=_require(vc, "id", "vc"),
             issuer=issuer,
-            recipient_id=_require(subj, "id", "vc.credentialSubject"),
+            recipient_id=recipient_id,
             achievement=achievement,
             name=vc.get("name"),
             issuance_date=issuance_date,

{openbadgeslib-1.3.0 → openbadgeslib-2.0.0}/openbadgeslib/ob3/signer.py

@@ -20,6 +20,8 @@
         License along with this library.
 """
 
+import json
+
 from typing import Any
 
 import jwt
@@ -55,39 +57,69 @@ class OB3Signer:
     # ── core signing ───────────────────────────────────────────────────────────
 
     def sign(self, credential: OpenBadgeCredential) -> str:
-        """Sign a credential and return a compact JWT-VC string."""
+        """Sign a credential and return a compact JWT-VC string.
+
+        OB 3.0 §8.2.3 requires the JOSE header to convey the verification key
+        via ``kid`` or ``jwk``; this embeds the issuer's public key as a ``jwk``
+        (public parameters only — never the private ``d``).
+        """
         payload = credential.to_jwt_payload()
+        headers = {"jwk": self._public_jwk()}
         try:
-            return jwt.encode(payload, self.privkey_pem, algorithm=self.algorithm)
+            return jwt.encode(payload, self.privkey_pem, algorithm=self.algorithm,
+                              headers=headers)
         except jwt.exceptions.PyJWTError as exc:
             raise ErrorSigningFile(
                 "Could not sign credential with algorithm %s: %s" % (self.algorithm, exc)) from exc
 
+    def _public_jwk(self) -> dict:
+        """Return the public JWK for the JOSE header, derived from the signing
+        key. Loaded via ``cryptography`` (which reads the RSA/EC/Ed25519 PEMs
+        this library produces) and serialised with PyJWT's algorithm; only
+        public parameters are included."""
+        from cryptography.hazmat.primitives import serialization as _ser
+        from jwt.algorithms import RSAAlgorithm, ECAlgorithm, OKPAlgorithm
+        pem = self.privkey_pem.encode('utf-8') if isinstance(self.privkey_pem, str) \
+            else self.privkey_pem
+        try:
+            # public_key() is a broad union; we dispatch on self.algorithm, so
+            # the concrete type matches the chosen to_jwk. Treat as Any for mypy.
+            pub: Any = _ser.load_pem_private_key(pem, password=None).public_key()
+            if self.algorithm.startswith('RS'):
+                jwk_json = RSAAlgorithm.to_jwk(pub)
+            elif self.algorithm.startswith('ES'):
+                jwk_json = ECAlgorithm.to_jwk(pub)
+            else:   # EdDSA / Ed25519
+                jwk_json = OKPAlgorithm.to_jwk(pub)
+        except Exception as exc:
+            raise ErrorSigningFile("Could not derive the public JWK: %s" % exc) from exc
+        return json.loads(jwk_json)
+
     # ── image baking ───────────────────────────────────────────────────────────
 
     def sign_into_svg(self, credential: OpenBadgeCredential, svg_bytes: bytes) -> bytes:
         """Embed a signed credential into an SVG badge image.
 
-        The JWT-VC is stored in an ``<openbadges:assertion verify="…"/>``
-        element, matching the OB 2.0 baking format so that existing badge
-        viewers can extract the token regardless of version.
+        The JWT-VC is stored in the OB 3.0 ``<openbadges:credential verify="…"/>``
+        element (namespace ``https://purl.imsglobal.org/ob/v3p0``).
         """
         token = self.sign(credential)
         try:
             return baking.bake_svg(
                 svg_bytes, token,
-                comment=' Signed with OpenBadgesLib %s (OB 3.0 JWT-VC) ' % __version__)
+                comment=' Signed with OpenBadgesLib %s (OB 3.0 JWT-VC) ' % __version__,
+                element=baking.SVG_ELEMENT_OB3, namespace=baking.SVG_NS_OB3)
         except Exception as exc:
-            raise ErrorSigningFile('Unable to bake SVG assertion: %s' % exc) from exc
+            raise ErrorSigningFile('Unable to bake SVG credential: %s' % exc) from exc
 
     def sign_into_png(self, credential: OpenBadgeCredential, png_bytes: bytes) -> bytes:
         """Embed a signed credential into a PNG badge image.
 
-        The JWT-VC is stored in an ``iTXt`` chunk with keyword ``openbadges``,
-        matching the OB 2.0 baking format.
+        The JWT-VC is stored in an ``iTXt`` chunk with the OB 3.0 keyword
+        ``openbadgecredential``.
         """
         token = self.sign(credential)
         try:
-            return baking.bake_png(png_bytes, token)
+            return baking.bake_png(png_bytes, token, keyword=baking.ITXT_KEYWORD_OB3)
         except Exception as exc:
-            raise ErrorSigningFile('Unable to bake PNG assertion: %s' % exc) from exc
+            raise ErrorSigningFile('Unable to bake PNG credential: %s' % exc) from exc

{openbadgeslib-1.3.0 → openbadgeslib-2.0.0}/openbadgeslib/ob3/status.py

@@ -106,15 +106,29 @@ def _check_entry(entry: dict, download: Callable[[str], bytes]) -> None:
         if not isinstance(encoded, str) or not encoded:
             raise OB3VerificationError("status list credential has no encodedList")
         bitstring = _decode_encoded_list(encoded)
+        list_purposes = set(_as_list(subject.get("statusPurpose")))
     except OB3VerificationError:
         raise
     except Exception as exc:
         raise OB3VerificationError(
             "malformed status list %s: %s" % (list_url, exc)) from exc
 
-    if _bit_set(bitstring, index):
+    # The entry's statusPurpose MUST be one the fetched status list declares,
+    # otherwise the entry points at the wrong list (fail closed).
+    if purpose not in list_purposes:
         raise OB3VerificationError(
-            "Credential status is set (%s) at index %d in %s"
+            "credentialStatus statusPurpose %r is not declared by the status list "
+            "%s (declares %r)" % (purpose, list_url, subject.get("statusPurpose")))
+
+    if not _bit_set(bitstring, index):
+        return
+
+    # A set bit only invalidates the credential for revocation/suspension.
+    # Any other purpose (e.g. 'message') is informational and MUST NOT fail
+    # verification — statusPurpose decides the meaning of the bit.
+    if purpose in ("revocation", "suspension"):
+        raise OB3VerificationError(
+            "Credential status '%s' is set at index %d in %s"
             % (purpose, index, list_url))
 
 

{openbadgeslib-1.3.0 → openbadgeslib-2.0.0}/openbadgeslib/ob3/verifier.py

@@ -51,6 +51,8 @@ def _claim_object_id(value: Any) -> Any:
     fail the comparison rather than raising a raw AttributeError on, e.g.,
     ``[ {…} ].get("id")``.
     """
+    if isinstance(value, str):
+        return value                     # issuer/subject given as a bare IRI
     if isinstance(value, list):
         value = value[0] if value else None
     if isinstance(value, dict):
@@ -222,27 +224,34 @@ class OB3Verifier:
 
     @staticmethod
     def _build_credential(payload: dict) -> OpenBadgeCredential:
-        """Validate the vc structure and registered claims, returning the
-        reconstructed credential."""
-        if "vc" not in payload:
-            raise OB3VerificationError(
-                "JWT payload does not contain a 'vc' claim — "
-                "this may be an OB 2.0 JWS token, not an OB 3.0 JWT-VC"
-            )
+        """Validate the credential structure and registered claims, returning
+        the reconstructed credential.
 
-        vc = payload["vc"]
-        if not isinstance(vc, dict):
+        OB 3.0 native VC-JWT (§8.2.4.1): the JWT payload IS the credential, so
+        it is read directly — there is no ``vc`` claim wrapper.
+        """
+        if not isinstance(payload, dict):
             raise OB3VerificationError(
-                "JWT 'vc' claim must be an object, got %s" % type(vc).__name__)
+                "JWT payload must be a JSON object, got %s" % type(payload).__name__)
+        vc = payload   # native: the payload is the credential body
 
         vc_types = vc.get("type", [])
         if isinstance(vc_types, str):
             vc_types = [vc_types]
         elif not isinstance(vc_types, list):
             vc_types = []
-        if "OpenBadgeCredential" not in vc_types:
+        # OpenBadgeCredential and AchievementCredential are aliases in the OB v3
+        # context; accept either. VerifiableCredential must also be present.
+        if not ({"OpenBadgeCredential", "AchievementCredential"} & set(vc_types)):
             raise OB3VerificationError(
-                "JWT 'vc' claim is not an OpenBadgeCredential (type=%r)" % (vc_types,)
+                "JWT payload is not an OpenBadgeCredential/AchievementCredential "
+                "(type=%r) — this may be an OB 2.0 JWS token, not an OB 3.0 JWT-VC"
+                % (vc_types,)
+            )
+        if "VerifiableCredential" not in vc_types:
+            raise OB3VerificationError(
+                "JWT payload type must include 'VerifiableCredential' (type=%r)"
+                % (vc_types,)
             )
 
         try:
@@ -250,17 +259,23 @@ class OB3Verifier:
         except (KeyError, ValueError, TypeError) as exc:
             raise OB3VerificationError(f"Malformed credential payload: {exc}") from exc
 
-        # Cross-check the JWT registered claims against the vc body (when the
-        # token carries them) so a verified signature cannot pair an iss/sub
-        # with a mismatched credential issuer/subject.
+        # OB3 §8.2.6.1: iss and nbf are REQUIRED registered claims, and iss MUST
+        # equal the credential issuer id. sub is required (and must match) when
+        # the subject carries an id. Enforcing presence — not only cross-checking
+        # when present — stops a token that omits these claims from verifying.
         iss = payload.get("iss")
-        if iss is not None and iss != _claim_object_id(vc.get("issuer")):
-            raise OB3VerificationError(
-                "JWT 'iss' does not match the credential issuer")
+        if iss is None:
+            raise OB3VerificationError("JWT payload is missing the required 'iss' claim")
+        if iss != _claim_object_id(vc.get("issuer")):
+            raise OB3VerificationError("JWT 'iss' does not match the credential issuer")
+        if payload.get("nbf") is None:
+            raise OB3VerificationError("JWT payload is missing the required 'nbf' claim")
         sub = payload.get("sub")
-        if sub is not None and sub != _claim_object_id(vc.get("credentialSubject")):
-            raise OB3VerificationError(
-                "JWT 'sub' does not match the credentialSubject id")
+        subject_id = _claim_object_id(vc.get("credentialSubject"))
+        if subject_id is not None and sub is None:
+            raise OB3VerificationError("JWT payload is missing the required 'sub' claim")
+        if sub is not None and sub != subject_id:
+            raise OB3VerificationError("JWT 'sub' does not match the credentialSubject id")
 
         return credential
 
@@ -270,11 +285,11 @@ class OB3Verifier:
     def extract_token_from_svg(svg_bytes: bytes) -> str:
         """Extract the JWT-VC token embedded in a baked SVG badge."""
         try:
-            token = baking.extract_svg(svg_bytes)
+            token = baking.extract_svg(svg_bytes, element=baking.SVG_ELEMENT_OB3)
         except Exception as exc:
             raise ErrorParsingFile(f"Could not parse SVG: {exc}") from exc
         if token is None:
-            raise OB3VerificationError("No openbadges:assertion element found in SVG")
+            raise OB3VerificationError("No openbadges:credential element found in SVG")
         return token
 
     @staticmethod
@@ -287,11 +302,11 @@ class OB3Verifier:
         a non-empty language tag or compressed text — are also recovered.
         """
         try:
-            token = baking.extract_png(png_bytes)
+            token = baking.extract_png(png_bytes, keyword=baking.ITXT_KEYWORD_OB3)
         except baking.DecompressionLimitExceeded as exc:
             raise OB3VerificationError(str(exc)) from exc
         except Exception as exc:
             raise ErrorParsingFile(f"Could not parse PNG: {exc}") from exc
         if token is None:
-            raise OB3VerificationError("No openbadges iTXt chunk found in PNG")
+            raise OB3VerificationError("No openbadgecredential iTXt chunk found in PNG")
         return token

{openbadgeslib-1.3.0 → openbadgeslib-2.0.0}/openbadgeslib/util.py

@@ -21,7 +21,7 @@
         License along with this library.
 """
 
-__version__ = '1.3.0'
+__version__ = '2.0.0'
 
 import hashlib
 import ipaddress

{openbadgeslib-1.3.0 → openbadgeslib-2.0.0/openbadgeslib.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openbadgeslib
-Version: 1.3.0
+Version: 2.0.0
 Summary: A library to sign and verify OpenBadges
 Author-email: Luis González Fernández <luisgf@luisgf.es>, Jesús Cea Avión <jcea@jcea.es>
 License: LGPLv3