openbadgeslib 1.2.0__tar.gz → 2.0.0__tar.gz

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

@@ -4,6 +4,82 @@ 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
+    it fetches are attacker-influenced (an OB2 badge/issuer/revocationList URL,
+    an OB3 did:web host, an OB3 credentialStatus list), so it now resolves the
+    destination host and refuses any private, loopback, link-local, reserved,
+    multicast, unspecified or carrier-grade-NAT (100.64/10) address; the check
+    is re-applied to redirect targets. Previously a crafted badge could steer a
+    verifier into GETting cloud-metadata endpoints or internal hosts. An
+    allow_private=True opt-out is available for private deployments.
+
+  - SECURITY: OB3Verifier.for_issuer_did() now binds the credential to the
+    anchored DID — verify() requires the credential's issuer id to equal the
+    DID whose key was resolved. did:web is not self-certifying, so without this
+    a credential signed by the resolved key could claim a different (trusted)
+    issuer and be accepted. Verifiers built directly from a public key are
+    unchanged (the caller vouches for the key).
+
+  - SECURITY: openbadges-verifier --json exit status now reflects issuer trust,
+    not just signature validity: 0 = valid AND issuer-trusted, 2 = valid
+    signature but untrusted issuer (an OB2 badge-embedded key or a self-asserted
+    did:key), 1 = failure. In 1.2.0 a valid-but-untrusted badge exited 0, so CI
+    gating on the exit code accepted signatures that do not prove issuer
+    identity. NOTE: this changes the exit code for the valid-but-untrusted case
+    from 0 to 2; the JSON body (valid/trusted/reason) is unchanged.
+
+  - SECURITY: OB3 --resolve-did on a self-asserted did:key is now reported
+    trusted:false (with a warning), mirroring OB2's badge-embedded-key case;
+    only an operator-supplied key or a DNS/TLS-anchored did:web is trusted.
+
+  - fix: an OB3 Bitstring Status List with statusSize > 1 (multi-bit entries)
+    now fails closed instead of reading the wrong bit, which could have
+    reported a revoked credential as valid.
+
+  - fix: confparser now resolves a relative [paths] base against the directory
+    containing the config file (not the process CWD). Previously only a bare
+    '.' was handled and its value replaced wholesale, silently dropping the
+    suffix of './data' or '../shared' and misplacing key/log/image trees. A '$'
+    in the config directory path is handled correctly.
+
+  - docs: Ed25519 (EdDSA) support is now documented across README and the wiki
+    (key types, algorithms, keygenerator key_type, config example); the --json
+    exit-status scheme is documented; and stale/inaccurate crypto-library and
+    dependency notes were corrected.
+
+
 * v1.2.0 - 2026-07-01
 
   - feat: openbadges-verifier gained a --json flag for machine-readable output.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openbadgeslib
-Version: 1.2.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
@@ -56,7 +56,7 @@ serialisation) and **OpenBadges 3.0** (W3C Verifiable Credentials / JWT-VC).
 - Sign badge images (SVG and PNG) with a JWS assertion (OB 2.0)
 - Issue and verify OpenBadges 3.0 JWT-VC credentials
 - Bake OB 3.0 JWT tokens into SVG and PNG badge images
-- RSA 2048-bit (RS256) and ECC NIST P-256 (ES256) key support
+- RSA 2048-bit (RS256), ECC NIST P-256 (ES256), and Ed25519 (EdDSA) key support
 - SHA-256 hashed recipient identity with salt (OB 2.0)
 - Expiration and revocation checking
 - Five command-line tools included
@@ -68,6 +68,7 @@ serialisation) and **OpenBadges 3.0** (W3C Verifiable Credentials / JWT-VC).
 - [ecdsa](https://pypi.org/project/ecdsa/) >= 0.19
 - [pypng](https://pypi.org/project/pypng/) >= 0.20220715.0
 - [PyJWT[crypto]](https://pypi.org/project/PyJWT/) >= 2.8
+- [cryptography](https://pypi.org/project/cryptography/) >= 42
 - [defusedxml](https://pypi.org/project/defusedxml/) >= 0.7
 
 ## Installation

{openbadgeslib-1.2.0 → openbadgeslib-2.0.0}/README.md

@@ -15,7 +15,7 @@ serialisation) and **OpenBadges 3.0** (W3C Verifiable Credentials / JWT-VC).
 - Sign badge images (SVG and PNG) with a JWS assertion (OB 2.0)
 - Issue and verify OpenBadges 3.0 JWT-VC credentials
 - Bake OB 3.0 JWT tokens into SVG and PNG badge images
-- RSA 2048-bit (RS256) and ECC NIST P-256 (ES256) key support
+- RSA 2048-bit (RS256), ECC NIST P-256 (ES256), and Ed25519 (EdDSA) key support
 - SHA-256 hashed recipient identity with salt (OB 2.0)
 - Expiration and revocation checking
 - Five command-line tools included
@@ -27,6 +27,7 @@ serialisation) and **OpenBadges 3.0** (W3C Verifiable Credentials / JWT-VC).
 - [ecdsa](https://pypi.org/project/ecdsa/) >= 0.19
 - [pypng](https://pypi.org/project/pypng/) >= 0.20220715.0
 - [PyJWT[crypto]](https://pypi.org/project/PyJWT/) >= 2.8
+- [cryptography](https://pypi.org/project/cryptography/) >= 42
 - [defusedxml](https://pypi.org/project/defusedxml/) >= 0.7
 
 ## Installation

{openbadgeslib-1.2.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.2.0 → openbadgeslib-2.0.0}/openbadgeslib/config.ini.example

@@ -44,7 +44,7 @@ verify_key  = https://www.issuer.badge/issuer/badge_1/verify_rsa_key.pem
 badge       = https://www.issuer.badge/issuer/badge_1/badge.json
 private_key = ${paths:base_key}/sign_rsa_key_1.pem
 public_key  = ${paths:base_key}/verify_rsa_key_1.pem
-; key_type selects the algorithm for openbadges-keygenerator: RSA (default) or ECC
+; key_type selects the algorithm for openbadges-keygenerator: RSA (default), ECC, or ED25519
 key_type    = RSA
 ;alignement  =
 ;tags        =

{openbadgeslib-1.2.0 → openbadgeslib-2.0.0}/openbadgeslib/confparser.py

@@ -87,10 +87,22 @@ class ConfParser():
             raise ValueError(
                 "Configuration file %s has an empty [paths] 'base' value" % self.config_file)
 
-        if base[0] == '.':
-            abs_path = os.path.dirname(self.config_file)
-            full_path = os.path.abspath(abs_path)
-            self.parser['paths']['base'] = full_path
+        # A relative base is resolved against the directory that contains the
+        # config file (not the process CWD), so ${base}/... paths land where the
+        # operator expects no matter where the tool is launched from. The old
+        # check only matched a bare '.' and replaced the *whole* value with the
+        # config dir — silently dropping the suffix of './data' or '../shared'
+        # (and mis-handling a real '.hidden' dir), which could redirect private
+        # keys and logs to the wrong tree with no error.
+        if not os.path.isabs(base):
+            base_dir = os.path.dirname(self.config_file)
+            resolved = os.path.abspath(os.path.join(base_dir, base))
+            # Writing back through the parser runs the value through
+            # ExtendedInterpolation, which treats '$' specially: a config
+            # directory whose absolute path contains a literal '$' would raise a
+            # raw configparser error (or silently collapse '$$' to '$'). Escape
+            # '$' -> '$$' so the path round-trips to its original form on read.
+            self.parser['paths']['base'] = resolved.replace('$', '$$')
 
         # ExtendedInterpolation resolves ${...} references lazily, only when a
         # value is actually read — a bad reference anywhere in the file would

{openbadgeslib-1.2.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.2.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.2.0 → openbadgeslib-2.0.0}/openbadgeslib/ob3/status.py

@@ -88,19 +88,47 @@ def _check_entry(entry: dict, download: Callable[[str], bytes]) -> None:
 
     try:
         subject = _status_list_subject(raw)
+        # Bitstring Status List v1.0 allows statusSize > 1 (multi-bit entries).
+        # _bit_set below assumes exactly one bit per entry, so honouring a
+        # larger statusSize would read the wrong bits and could misreport a
+        # revoked credential as valid. Fail closed on an unsupported size rather
+        # than silently returning the wrong verdict. Absent/1 keeps 1-bit logic.
+        status_size = subject.get("statusSize", 1)
+        try:
+            status_size = int(status_size)
+        except (TypeError, ValueError):
+            raise OB3VerificationError("invalid statusSize: %r" % (status_size,))
+        if status_size != 1:
+            raise OB3VerificationError(
+                "unsupported statusSize %d: only single-bit status entries are "
+                "supported" % status_size)
         encoded = subject.get("encodedList")
         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))