openbadgeslib 3.5.1__tar.gz → 3.6.0__tar.gz

{openbadgeslib-3.5.1 → openbadgeslib-3.6.0}/Changelog.txt

@@ -4,6 +4,29 @@ OpenBadgesLib - Changelog
 Newest first. Dates are ISO 8601 (YYYY-MM-DD).
 
 
+* v3.6.0 - 2026-07-08
+
+  - feat(ob3): the verifier now exposes the raw, already-validated VC document
+    on the returned credential (`credential.raw`) — on both the JWT-VC and the
+    Data Integrity path — so an integrator can read spec fields the dataclass
+    does not map (alignment, results, multiple evidence, endorsements, …)
+    without re-parsing the token. It is None for an in-memory credential built
+    to issue, and excluded from equality/repr so it never affects comparisons.
+
+  - feat(ob3): issued OB 3.0 credentials now carry a `credentialSchema` entry
+    (`1EdTechJsonSchemaValidator2019`) pointing at 1EdTech's published
+    AchievementCredential JSON Schema, so validators and wallets can
+    self-check them. The offline conformance gate proves our issued
+    credentials satisfy that exact schema.
+
+  - refactor(typing): the library now type-checks clean under `mypy --strict`
+    (73 bare `dict` annotations parameterised as `dict[str, Any]`, 20 Any
+    returns narrowed with `typing.cast`), and `strict = true` is enabled in
+    the mypy config so CI enforces it. This makes the README's long-standing
+    `mypy --strict` claim true and improves the shipped `py.typed` annotations
+    for downstream type-checkers. Annotations only — no runtime change.
+
+
 * v3.5.1 - 2026-07-07
 
   - fix(ob3): a naive datetime passed as the issuance/expiration date is now

{openbadgeslib-3.5.1/openbadgeslib.egg-info → openbadgeslib-3.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openbadgeslib
-Version: 3.5.1
+Version: 3.6.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-3.6.0/SECURITY.md

@@ -0,0 +1,54 @@
+# Security Policy
+
+`openbadgeslib` issues and verifies cryptographically-signed credentials, so we
+take reports seriously and aim to respond quickly.
+
+## Supported versions
+
+Security fixes land in a new release on the latest minor line and are published
+to [PyPI](https://pypi.org/project/openbadgeslib/). Always run the latest
+release; older versions are not patched in place.
+
+| Version        | Supported                     |
+| -------------- | ----------------------------- |
+| Latest release | ✅ security fixes              |
+| Older releases | ❌ upgrade to the latest       |
+
+## Reporting a vulnerability
+
+**Please do not open a public issue for a suspected vulnerability.** Report it
+privately instead:
+
+- **Preferred:** GitHub private vulnerability reporting — the **“Report a
+  vulnerability”** button under this repository’s
+  [Security tab](https://github.com/luisgf/openbadgeslib/security/advisories).
+- **Email:** `luisgf@luisgf.es` (you may encrypt to the same address’s public
+  key if you have it).
+
+Please include enough to reproduce: the affected version, a minimal example or
+proof of concept, and the impact you observed. If it touches signature
+verification, revocation, DID/key resolution, or the handling of untrusted
+input (downloaded documents, baked images, status lists), say so — those are the
+highest-priority areas.
+
+## What to expect
+
+- Acknowledgement of your report, normally within a few days.
+- An assessment of severity and scope, and a fix or mitigation plan.
+- Coordinated disclosure: we will agree a timeline with you and credit you in
+  the release notes and advisory unless you prefer to stay anonymous.
+- A patched release on PyPI and a published GitHub Security Advisory once the
+  fix is available.
+
+## Scope and threat model
+
+What the library defends against, and what it delegates to the operator (key
+custody, DNS/TLS for `did:web`, hosting of published documents), is documented
+in the [Security Model](https://github.com/luisgf/openbadgeslib/wiki/Security-Model)
+wiki page. Reports that fall within that model — a bypass of algorithm pinning,
+signature or recipient-binding verification, the SSRF/decompression guards, the
+context allowlist, or the status-list checks — are especially welcome.
+
+Out of scope: issues that require the operator’s own private keys or config to
+already be compromised, and hardening we already document as a deliberate,
+human-owned decision (for example, passphrase-encrypted private keys at rest).

{openbadgeslib-3.5.1 → openbadgeslib-3.6.0}/openbadgeslib/_jws/__init__.py

@@ -1,6 +1,6 @@
 """JWS sign/verify backed by PyJWT algorithm implementations (RS256/384/512, ES256/384/512)."""
 
-from typing import Any, Dict, Optional, Set, Union
+from typing import Any, Dict, Optional, Set, Union, cast
 
 from . import utils
 from .exceptions import SignatureError, MissingKey, MissingSigner, MissingVerifier, RouteMissingError
@@ -66,7 +66,7 @@ def sign(header_dict: Dict[str, Any], payload_dict: Dict[str, Any], key: Any) ->
     algo = _algo_for(alg_name)
     try:
         prepared = algo.prepare_key(key_to_pem(key))
-        return algo.sign(signing_input, prepared)
+        return cast(bytes, algo.sign(signing_input, prepared))
     except (InvalidKeyError, ValueError) as exc:
         raise SignatureError(str(exc)) from exc
 

{openbadgeslib-3.5.1 → openbadgeslib-3.6.0}/openbadgeslib/baking.py

@@ -29,7 +29,7 @@
 from struct import pack
 from zlib import crc32
 
-from typing import List, Optional, Tuple, Union
+from typing import List, Optional, Tuple, Union, cast
 
 from defusedxml.minidom import parseString
 from png import Reader, signature as _png_signature
@@ -98,7 +98,7 @@ def bake_svg(image_bytes: bytes, token: str, comment: Optional[str] = None, *,
         svg_tag.appendChild(node)
         if comment:
             svg_tag.appendChild(svg_doc.createComment(comment))
-        return svg_doc.toxml().encode('utf-8')
+        return cast(bytes, svg_doc.toxml().encode('utf-8'))
     finally:
         svg_doc.unlink()
 
@@ -133,7 +133,7 @@ def extract_svg(image_bytes: bytes, *, element: str = SVG_ELEMENT,
             return None
         attrs = nodes[0].attributes
         if 'verify' in attrs:
-            return attrs['verify'].nodeValue
+            return cast(Optional[str], attrs['verify'].nodeValue)
         if not text_fallback:
             return None
         text = ''.join(
@@ -158,7 +158,7 @@ def _serialize_png(chunks: List[Tuple[Union[str, bytes], bytes]]) -> bytes:
         checksum = crc32(tag)
         checksum = crc32(data, checksum) & 0xFFFFFFFF
         out += pack("!I", checksum)
-    return out
+    return cast(bytes, out)
 
 
 def bake_png(image_bytes: bytes, token: str, text_comment: Optional[str] = None, *,

{openbadgeslib-3.5.1 → openbadgeslib-3.6.0}/openbadgeslib/keys.py

@@ -21,7 +21,7 @@
         License along with this library.
 """
 
-from typing import Any, Optional, Tuple, Union
+from typing import Any, Optional, Tuple, Union, cast
 from .errors import PublicKeyReadError, UnknownKeyType
 from ecdsa import SigningKey, VerifyingKey, NIST256p
 from Crypto.PublicKey import RSA
@@ -91,10 +91,10 @@ class KeyRSA(KeyBase):
         self.pub_key = RSA.import_key(key_pem)
 
     def get_priv_key_pem(self) -> bytes:
-        return self.priv_key.export_key('PEM')
+        return cast(bytes, self.priv_key.export_key('PEM'))
 
     def get_pub_key_pem(self) -> bytes:
-        return self.pub_key.export_key('PEM')
+        return cast(bytes, self.pub_key.export_key('PEM'))
 
 
 class KeyECC(KeyBase):
@@ -126,10 +126,10 @@ class KeyECC(KeyBase):
         self.pub_key = VerifyingKey.from_pem(key_pem)
 
     def get_priv_key_pem(self) -> bytes:
-        return self.priv_key.to_pem()
+        return cast(bytes, self.priv_key.to_pem())
 
     def get_pub_key_pem(self) -> bytes:
-        return self.pub_key.to_pem()
+        return cast(bytes, self.pub_key.to_pem())
 
 
 def _pem_bytes(key_pem: Union[str, bytes]) -> bytes:
@@ -177,15 +177,15 @@ class KeyEd25519(KeyBase):
         self.pub_key = _load_ed25519_public_key(key_pem)
 
     def get_priv_key_pem(self) -> bytes:
-        return self.priv_key.private_bytes(
+        return cast(bytes, self.priv_key.private_bytes(
             _crypto_serialization.Encoding.PEM,
             _crypto_serialization.PrivateFormat.PKCS8,
-            _crypto_serialization.NoEncryption())
+            _crypto_serialization.NoEncryption()))
 
     def get_pub_key_pem(self) -> bytes:
-        return self.pub_key.public_bytes(
+        return cast(bytes, self.pub_key.public_bytes(
             _crypto_serialization.Encoding.PEM,
-            _crypto_serialization.PublicFormat.SubjectPublicKeyInfo)
+            _crypto_serialization.PublicFormat.SubjectPublicKeyInfo))
 
 
 def alg_for_key_type(key_type: 'KeyType') -> str:
@@ -209,7 +209,7 @@ def key_to_pem(key: Any) -> Union[str, bytes]:
     if isinstance(key, RSA.RsaKey):
         return key.export_key('PEM')
     if isinstance(key, (SigningKey, VerifyingKey)):
-        return key.to_pem()
+        return cast(Union[str, bytes], key.to_pem())
     if isinstance(key, Ed25519PrivateKey):
         return key.private_bytes(
             _crypto_serialization.Encoding.PEM,
@@ -224,7 +224,7 @@ def key_to_pem(key: Any) -> Union[str, bytes]:
     raise UnknownKeyType('Unsupported key object type: %r' % type(key))
 
 
-def public_jwk_from_pem(pubkey_pem: Union[str, bytes]) -> dict:
+def public_jwk_from_pem(pubkey_pem: Union[str, bytes]) -> dict[str, Any]:
     """Serialise a public key PEM as a public JWK dict.
 
     Counterpart of the OB3 signer's private-key-based JWK derivation, for
@@ -250,7 +250,7 @@ def public_jwk_from_pem(pubkey_pem: Union[str, bytes]) -> dict:
     except Exception as exc:
         raise PublicKeyReadError(
             'could not read public key PEM: %s' % exc) from exc
-    return json.loads(jwk_json)
+    return cast(dict[str, Any], json.loads(jwk_json))
 
 
 def ec_curve_from_pem(pem_data: Union[str, bytes]) -> Optional[str]:

{openbadgeslib-3.5.1 → openbadgeslib-3.6.0}/openbadgeslib/ob1/badge.py

@@ -23,7 +23,7 @@
 
 import os
 from enum import Enum
-from typing import Any, Optional, Union
+from typing import Any, Optional, Union, cast
 
 from Crypto.PublicKey import RSA
 from ecdsa import SigningKey, VerifyingKey
@@ -78,7 +78,7 @@ class Assertion():
         return jws_utils.decode(self.body)
 
     def get_assertion(self) -> bytes:
-        return self.header + b'.' + self.body + b'.' + self.signature
+        return cast(bytes, self.header + b'.' + self.body + b'.' + self.signature)
 
     def encode_header(self, header: Any) -> None:
         self.header = jws_utils.encode(header)
@@ -350,13 +350,13 @@ class BadgeSigned():
         self.file_out = file_name
 
     def get_identity(self) -> str:
-        return self.identity.decode('utf-8')
+        return cast(str, self.identity.decode('utf-8'))
 
     def get_identity_hashed(self) -> str:
         return (b'sha256$' + hash_email(self.identity, self.salt)).decode('utf-8')
 
     def get_salt(self) -> str:
-        return self.salt.decode('utf-8')
+        return cast(str, self.salt.decode('utf-8'))
 
     def get_assertion(self) -> Optional[str]:
         if self.assertion:
@@ -380,7 +380,7 @@ class BadgeSigned():
     def get_signkey_pem(self) -> Union[str, bytes]:
         """ Return the public key pem used to sign the openbadge """
 
-        return self.source.pubkey_pem
+        return cast(Union[str, bytes], self.source.pubkey_pem)
 
 
 def extract_svg_assertion(file_data: bytes) -> Assertion:

{openbadgeslib-3.5.1 → openbadgeslib-3.6.0}/openbadgeslib/ob1/verifier.py

@@ -21,7 +21,7 @@
         License along with this library.
 """
 
-from typing import Any, Optional
+from typing import Any, Optional, cast
 
 from .badge import BadgeStatus
 from ..util import hash_email, download_file, show_ecc_disclaimer
@@ -225,7 +225,7 @@ class Verifier():
             email_salt = badge.salt if badge.salt else b''
             email_hashed = b'sha256$' + hash_email(self.identity, email_salt)
 
-            return email_hashed == badge.identity
+            return cast(bool, email_hashed == badge.identity)
         except Exception:
             raise NotIdentityInAssertion('The assertion doesn\'t have an identify ')
 

{openbadgeslib-3.5.1 → openbadgeslib-3.6.0}/openbadgeslib/ob2/models.py

@@ -95,13 +95,13 @@ def _validate_type(value: Any, expected: str, where: str) -> None:
         raise ValueError("%s.type must include %r, got %r" % (where, expected, value))
 
 
-def _as_dict(value: Any, where: str) -> dict:
+def _as_dict(value: Any, where: str) -> dict[str, Any]:
     if not isinstance(value, dict):
         raise ValueError("%s must be a JSON object" % where)
     return value
 
 
-def _require(data: dict, key: str, where: str) -> str:
+def _require(data: dict[str, Any], key: str, where: str) -> str:
     """Return ``data[key]`` as a non-empty string, else raise a clear error."""
     value = data.get(key)
     if value is None or value == "":
@@ -162,8 +162,8 @@ class IdentityObject:
         """Build a hashed email IdentityObject from a plaintext email + salt."""
         return cls(identity=hash_identity(email, salt), hashed=True, salt=salt, type="email")
 
-    def to_dict(self) -> dict:
-        d: dict = {"type": self.type, "hashed": self.hashed, "identity": self.identity}
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {"type": self.type, "hashed": self.hashed, "identity": self.identity}
         if self.salt is not None:
             d["salt"] = self.salt
         return d
@@ -193,8 +193,8 @@ class Verification:
     type: str                       # "SignedBadge" or "HostedBadge"
     creator: Optional[str] = None   # IRI of the issuer's CryptographicKey (signed)
 
-    def to_dict(self) -> dict:
-        d: dict = {"type": self.type}
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {"type": self.type}
         if self.creator:
             d["creator"] = self.creator
         return d
@@ -237,9 +237,9 @@ class Assertion:
         if self.issued_on is None:
             self.issued_on = datetime.now(timezone.utc)
 
-    def to_dict(self) -> dict:
+    def to_dict(self) -> dict[str, Any]:
         assert self.issued_on is not None   # set by __post_init__
-        d: dict = {
+        d: dict[str, Any] = {
             "@context": OB2_CONTEXT,
             "type": "Assertion",
             "id": self.id,
@@ -297,7 +297,7 @@ class CryptographicKey:
     owner: str                # IRI of the owning issuer Profile (bidirectional)
     public_key_pem: str
 
-    def to_dict(self) -> dict:
+    def to_dict(self) -> dict[str, Any]:
         return {
             "@context": OB2_CONTEXT,
             "type": "CryptographicKey",
@@ -329,8 +329,8 @@ class Profile:
     public_key: List[str] = field(default_factory=list)   # CryptographicKey IRIs
     revocation_list: Optional[str] = None
 
-    def to_dict(self) -> dict:
-        d: dict = {
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
             "@context": OB2_CONTEXT,
             "type": "Issuer",
             "id": self.id,
@@ -361,8 +361,8 @@ class BadgeClass:
     issuer: str              # issuer Profile IRI
     tags: List[str] = field(default_factory=list)
 
-    def to_dict(self) -> dict:
-        d: dict = {
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
             "@context": OB2_CONTEXT,
             "type": "BadgeClass",
             "id": self.id,
@@ -385,7 +385,7 @@ class RevocationList:
     issuer: str
     revoked_assertions: List[Any] = field(default_factory=list)
 
-    def to_dict(self) -> dict:
+    def to_dict(self) -> dict[str, Any]:
         return {
             "@context": OB2_CONTEXT,
             "type": "RevocationList",

{openbadgeslib-3.5.1 → openbadgeslib-3.6.0}/openbadgeslib/ob2/verifier.py

@@ -215,7 +215,7 @@ class OB2Verifier:
                          "hosted trust comes from the HTTPS fetch, not the signature.",
                          assertion.id, exc)
 
-    def _check_hosted_scope(self, assertion_id: str, issuer: dict) -> None:
+    def _check_hosted_scope(self, assertion_id: str, issuer: dict[str, Any]) -> None:
         """Enforce the OB 2.0 hosted-verification scope for ``assertion_id``."""
         verification = issuer.get("verification")
         if isinstance(verification, dict):
@@ -287,7 +287,7 @@ class OB2Verifier:
 
     # ── network / decode helpers ─────────────────────────────────────────────────
 
-    def _fetch_issuer(self, assertion: Assertion) -> dict:
+    def _fetch_issuer(self, assertion: Assertion) -> dict[str, Any]:
         """Resolve the issuer Profile via the assertion's BadgeClass ``badge`` URL."""
         badge = self._fetch_json(assertion.badge, "BadgeClass")
         issuer_url = badge.get("issuer")
@@ -299,7 +299,7 @@ class OB2Verifier:
                 "BadgeClass at %s has no valid 'issuer'" % assertion.badge)
         return self._fetch_json(issuer_url, "issuer Profile")
 
-    def _fetch_json(self, url: str, where: str) -> dict:
+    def _fetch_json(self, url: str, where: str) -> dict[str, Any]:
         try:
             raw = download_file(url)
         except Exception as exc:

{openbadgeslib-3.5.1 → openbadgeslib-3.6.0}/openbadgeslib/ob3/contexts/__init__.py

@@ -79,7 +79,11 @@ _URL_TO_RESOURCE: Dict[str, str] = {
         'ob-v3p0-context-3.0.2.json',
     'https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json':
         'ob-v3p0-context-3.0.3.json',
-    # The unversioned OB3 context URL serves the latest published revision.
+    # The unversioned OB3 context URL is an internal alias to our latest
+    # bundled revision (3.0.3). We deliberately pin it here rather than mirror
+    # 1EdTech's moving unversioned endpoint (which currently serves an older
+    # revision matching none we ship); the context-drift check skips it for
+    # that reason.
     'https://purl.imsglobal.org/spec/ob/v3p0/context.json':
         'ob-v3p0-context-3.0.3.json',
     'https://w3id.org/security/data-integrity/v2':
@@ -89,7 +93,7 @@ _URL_TO_RESOURCE: Dict[str, str] = {
 
 
 @functools.lru_cache(maxsize=None)
-def load_context(url: str) -> dict:
+def load_context(url: str) -> dict[str, Any]:
     """Return the bundled JSON-LD context document for an allowlisted URL.
 
     Raises UnknownContextError for any URL outside the allowlist — the match
@@ -109,8 +113,8 @@ def load_context(url: str) -> dict:
 
 
 def document_loader(
-        extra_contexts: Optional[Mapping[str, dict]] = None,
-) -> Callable[[str, Any], dict]:
+        extra_contexts: Optional[Mapping[str, dict[str, Any]]] = None,
+) -> Callable[[str, Any], dict[str, Any]]:
     """Build a static documentLoader in the shape pyld expects.
 
     *extra_contexts* extends the allowlist for one loader instance (e.g. a
@@ -118,9 +122,9 @@ def document_loader(
     global allowlist. Every other URL raises UnknownContextError, which the
     Data Integrity verifier surfaces as a clean verification failure.
     """
-    extras: Dict[str, dict] = dict(extra_contexts) if extra_contexts else {}
+    extras: Dict[str, dict[str, Any]] = dict(extra_contexts) if extra_contexts else {}
 
-    def _loader(url: str, options: Any = None) -> dict:
+    def _loader(url: str, options: Any = None) -> dict[str, Any]:
         document = extras[url] if url in extras else load_context(url)
         return {'contextUrl': None, 'documentUrl': url, 'document': document}
 

{openbadgeslib-3.5.1 → openbadgeslib-3.6.0}/openbadgeslib/ob3/credential.py

@@ -40,6 +40,16 @@ _OB_CONTEXT_RE = re.compile(
 
 _SUPPORTED_ALGORITHMS = {'RS256', 'RS384', 'RS512', 'ES256', 'ES384', 'ES512', 'EdDSA'}
 
+# 1EdTech's published JSON Schema for an AchievementCredential. Issued badges
+# carry a credentialSchema pointing at it (§8, 1EdTechJsonSchemaValidator2019),
+# so validators and wallets can self-check them; the offline conformance gate
+# proves our credentials satisfy this exact schema.
+_OB3_CREDENTIAL_SCHEMA = {
+    "id": "https://purl.imsglobal.org/spec/ob/v3p0/schema/json/"
+          "ob_v3p0_achievementcredential_schema.json",
+    "type": "1EdTechJsonSchemaValidator2019",
+}
+
 
 def _validate_context(ctx: Any) -> None:
     """Validate an OpenBadgeCredential ``@context`` per the schema: an array
@@ -77,8 +87,8 @@ class Issuer:
     email: Optional[str] = None
     image_url: Optional[str] = None
 
-    def to_dict(self) -> dict:
-        d: dict = {"id": self.id, "type": ["Profile"], "name": self.name}
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {"id": self.id, "type": ["Profile"], "name": self.name}
         if self.url:
             d["url"] = self.url
         if self.email:
@@ -99,8 +109,8 @@ class Achievement:
     image_url: Optional[str] = None
     tags: List[str] = field(default_factory=list)
 
-    def to_dict(self) -> dict:
-        d: dict = {
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
             "id": self.id,
             "type": ["Achievement"],
             "name": self.name,
@@ -131,7 +141,19 @@ class OpenBadgeCredential:
     # Raw credentialStatus entries (Bitstring Status List / StatusList2021),
     # normalised to a list of objects. Consumed by ob3.status to check
     # revocation; empty when the credential carries no status.
-    credential_status: List[dict] = field(default_factory=list)
+    credential_status: List[dict[str, Any]] = field(default_factory=list)
+    # A read-only view of the already-validated document this credential was
+    # parsed from (set by the verifiers via _from_vc); None when built in-memory
+    # to issue. Lets a caller read spec fields the model does not map —
+    # alignment, results, multiple evidence, endorsements, … — without
+    # re-parsing the token. Do NOT mutate it: on the from_*() classmethods it
+    # may alias the caller-supplied dict. Its shape is the document as parsed,
+    # so it reflects parse time (not later edits to the model fields) and is
+    # path-dependent — the JWT-VC payload (with the registered iss/sub/jti/nbf/
+    # exp claims alongside) or the Data Integrity document (with its proof).
+    # Excluded from equality/repr so it never affects comparisons.
+    raw: Optional[dict[str, Any]] = field(default=None, compare=False,
+                                          repr=False)
 
     def __post_init__(self) -> None:
         if self.id is None:
@@ -151,11 +173,11 @@ class OpenBadgeCredential:
 
     # ── serialisation ──────────────────────────────────────────────────────────
 
-    def to_vc(self) -> dict:
+    def to_vc(self) -> dict[str, Any]:
         """Return the Verifiable Credential JSON object (no JWT wrapper)."""
         # __post_init__ guarantees issuance_date is set.
         assert self.issuance_date is not None
-        vc: dict = {
+        vc: dict[str, Any] = {
             "@context": OB3_CONTEXT,
             "id": self.id,
             "type": ["VerifiableCredential", "OpenBadgeCredential"],
@@ -166,6 +188,7 @@ class OpenBadgeCredential:
                 "type": ["AchievementSubject"],
                 "achievement": self.achievement.to_dict(),
             },
+            "credentialSchema": [dict(_OB3_CREDENTIAL_SCHEMA)],
         }
         # credentialSubject.id is optional; emit it only when present.
         if self.recipient_id is not None:
@@ -180,7 +203,7 @@ class OpenBadgeCredential:
                 else self.credential_status)
         return vc
 
-    def to_jwt_payload(self) -> dict:
+    def to_jwt_payload(self) -> dict[str, Any]:
         """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
@@ -192,7 +215,7 @@ class OpenBadgeCredential:
         """
         # __post_init__ guarantees issuance_date is set.
         assert self.issuance_date is not None
-        payload: dict = dict(self.to_vc())   # credential at the payload top level
+        payload: dict[str, Any] = 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
@@ -205,7 +228,7 @@ class OpenBadgeCredential:
     # ── deserialisation ────────────────────────────────────────────────────────
 
     @classmethod
-    def from_jwt_payload(cls, payload: dict) -> "OpenBadgeCredential":
+    def from_jwt_payload(cls, payload: dict[str, Any]) -> "OpenBadgeCredential":
         """Reconstruct an OpenBadgeCredential from a decoded JWT payload.
 
         OB 3.0 native VC-JWT: the payload IS the credential (its members at the
@@ -216,7 +239,7 @@ class OpenBadgeCredential:
         return cls._from_vc(payload)
 
     @classmethod
-    def from_vc_document(cls, document: dict) -> "OpenBadgeCredential":
+    def from_vc_document(cls, document: dict[str, Any]) -> "OpenBadgeCredential":
         """Reconstruct an OpenBadgeCredential from a JSON-LD VC document.
 
         The shape a credential secured with an embedded Data Integrity proof
@@ -227,7 +250,7 @@ class OpenBadgeCredential:
         return cls._from_vc(document)
 
     @classmethod
-    def _from_vc(cls, payload: dict) -> "OpenBadgeCredential":
+    def _from_vc(cls, payload: dict[str, Any]) -> "OpenBadgeCredential":
         """Shared constructor from an untrusted credential body.
 
         Every required object/field is checked and a clear ``ValueError`` is
@@ -311,7 +334,7 @@ class OpenBadgeCredential:
                     "vc.credentialSubject must have an 'id' or an 'identifier'")
             recipient_id = None
 
-        return cls(
+        credential = cls(
             id=_require(vc, "id", "vc"),
             issuer=issuer,
             recipient_id=recipient_id,
@@ -322,21 +345,26 @@ class OpenBadgeCredential:
             evidence_url=evidence_url,
             credential_status=credential_status,
         )
+        # Keep the validated document so the caller can read fields the model
+        # does not map (see the ``raw`` field). This is the JWT-VC payload or
+        # the Data Integrity document, exactly as verified.
+        credential.raw = vc
+        return credential
 
 
-def _as_dict(value: Any, where: str) -> dict:
+def _as_dict(value: Any, where: str) -> dict[str, Any]:
     """Return value if it is a dict, else raise a clear ValueError."""
     if not isinstance(value, dict):
         raise ValueError("%s must be a JSON object" % where)
     return value
 
 
-def _as_dict_or_empty(value: Any) -> dict:
+def _as_dict_or_empty(value: Any) -> dict[str, Any]:
     """Return value if it is a dict, else an empty dict (optional sub-objects)."""
     return value if isinstance(value, dict) else {}
 
 
-def _require(data: dict, key: str, where: str) -> str:
+def _require(data: dict[str, Any], key: str, where: str) -> str:
     """Return data[key] as a string, raising a clear ValueError if missing,
     empty, or not a string. All fields validated here (id/name) are identifiers
     consumed as strings downstream (e.g. recipient binding calls .lower()), so a

{openbadgeslib-3.5.1 → openbadgeslib-3.6.0}/openbadgeslib/ob3/did.py

@@ -36,7 +36,7 @@
 
 import json
 
-from typing import Any, Sequence, Tuple
+from typing import Any, Sequence, Tuple, cast
 
 from cryptography.hazmat.primitives import serialization as _serialization
 from cryptography.hazmat.primitives.asymmetric import ec
@@ -189,7 +189,7 @@ def _resolve_did_web(did: str, fetch: Any) -> bytes:
     return _pem_from_did_document(_fetch_did_web_document(did, fetch))
 
 
-def _fetch_did_web_document(did: str, fetch: Any) -> dict:
+def _fetch_did_web_document(did: str, fetch: Any) -> dict[str, Any]:
     """Fetch and parse the DID document a did:web identifier resolves to."""
     from urllib.parse import unquote
     ident = did[len('did:web:'):]
@@ -290,8 +290,8 @@ def did_web_from_url(url: str) -> str:
 
 
 def build_did_document(did: str,
-                       verification_methods: Sequence[Tuple[str, dict]]
-                       ) -> dict:
+                       verification_methods: Sequence[Tuple[str, dict[str, Any]]]
+                       ) -> dict[str, Any]:
     """Build a DID document publishing *verification_methods*, given as
     ``(fragment, public JWK)`` pairs (see keys.public_jwk_from_pem).
 
@@ -344,7 +344,7 @@ def _pem_from_vm(vm: Any) -> bytes:
         "(publicKeyJwk or z-base58 publicKeyMultibase)")
 
 
-def _jwk_to_pem(jwk: dict) -> bytes:
+def _jwk_to_pem(jwk: dict[str, Any]) -> bytes:
     kty = jwk.get('kty')
     jwk_json = json.dumps(jwk)
     key: Any
@@ -368,6 +368,6 @@ def _jwk_to_pem(jwk: dict) -> bytes:
 
 
 def _public_key_to_pem(key: Any) -> bytes:
-    return key.public_bytes(
+    return cast(bytes, key.public_bytes(
         _serialization.Encoding.PEM,
-        _serialization.PublicFormat.SubjectPublicKeyInfo)
+        _serialization.PublicFormat.SubjectPublicKeyInfo))