openbadgeslib 3.5.0__tar.gz → 3.6.0__tar.gz

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

@@ -4,6 +4,70 @@ 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
+    assumed UTC (matching status_registry._iso_z), not local time — so
+    validFrom/validUntil no longer silently shift by the host's offset and
+    stay consistent with the nbf/exp JWT claims.
+
+  - fix(ob3): the JWT verifier now cross-checks the `jti` claim against the
+    credential `id` (OB3 §8.2 binds them). A validly signed token whose jti
+    disagrees with — or omits — the credential id is rejected, alongside the
+    existing iss/nbf/sub checks.
+
+  - fix(ob3): `_b58btc_decode` bounds its input to 128 characters before the
+    O(n^2) base58 decode, so a hostile did:key / publicKeyMultibase in a
+    fetched did:web or Data Integrity document (up to 5 MiB / 256 KiB) can no
+    longer burn CPU. No real multikey exceeds ~70 characters.
+
+  - fix(ob2): an `evidence` array (which OB 2.0 permits) is preserved when
+    parsing an Assertion instead of being silently dropped — `_iri_or_none`
+    returned None for a list. A single value still collapses to its IRI.
+
+  - fix(cli): `openbadges-signer -M/--mail-badge` now prints a clear notice
+    on the default OB3 path (it was a silent no-op there); the stale
+    `openbadges-keygenerator -t ED25519` hint on the LDP path is corrected to
+    the real `key_type = ED25519` config key; and the OB1 mail path reads its
+    `[smtp]` config inside the try, so a missing `[smtp]` section is reported
+    cleanly after signing instead of raising a traceback.
+
+  - fix(publish): `openbadges-publish -V 3` no longer aborts mid-loop when a
+    badge has an unreadable key or corrupt registry — it skips that badge
+    with a notice (like the did.json path already did), regenerates the
+    others, and exits non-zero with a summary. An urgent revocation is no
+    longer masked by an unrelated half-configured badge.
+
+  - refactor(keygen): `openbadges-keygenerator` uses `enable_debug_logging`
+    instead of the legacy `Logger` class (now removed from logs.py), so key
+    generation no longer requires the `[paths]`/`[logs]` config sections just
+    to emit console lines (they raised a raw KeyError/FileNotFoundError), and
+    a missing `[issuer] name` degrades gracefully.
+
+
 * v3.5.0 - 2026-07-07
 
   - fix(status): serialise status-registry writes with an exclusive

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openbadgeslib
-Version: 3.5.0
+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.0 → 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.0 → 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.0 → 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.6.0/openbadgeslib/logs.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+"""
+        OpenBadges Library
+
+        Copyright (c) 2014-2026, Luis González Fernández, luisgf@luisgf.es
+        Copyright (c) 2014-2026, Jesús Cea Avión, jcea@jcea.es
+
+        All rights reserved.
+
+        This library is free software; you can redistribute it and/or
+        modify it under the terms of the GNU Lesser General Public
+        License as published by the Free Software Foundation; either
+        version 3.0 of the License, or (at your option) any later version.
+
+        This library is distributed in the hope that it will be useful,
+        but WITHOUT ANY WARRANTY; without even the implied warranty of
+        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+        Lesser General Public License for more details.
+
+        You should have received a copy of the GNU Lesser General Public
+        License along with this library.
+"""
+
+import logging
+from typing import Any
+
+
+def enable_debug_logging(debug: bool = False) -> None:
+    """Route library log messages to the console for the CLI tools.
+
+    With ``debug=True`` DEBUG-level messages are shown; otherwise only INFO and
+    above. Idempotent — safe to call once per CLI invocation (it will not stack
+    duplicate console handlers).
+    """
+    root = logging.getLogger()
+    if not any(getattr(h, '_obl_console', False) for h in root.handlers):
+        handler: Any = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter("%(levelname)s - %(message)s"))
+        handler._obl_console = True
+        root.addHandler(handler)
+    root.setLevel(logging.DEBUG if debug else logging.INFO)

{openbadgeslib-3.5.0 → 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.0 → 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.0 → openbadgeslib-3.6.0}/openbadgeslib/ob2/models.py

@@ -32,7 +32,7 @@
 import uuid
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
-from typing import Any, List, Optional
+from typing import Any, List, Optional, Union
 
 from ..util import hash_email
 
@@ -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 == "":
@@ -122,6 +122,25 @@ def _iri_or_none(value: Any) -> Optional[str]:
     return None
 
 
+def _iri_or_iris(value: Any) -> Optional[Union[str, List[str]]]:
+    """Like :func:`_iri_or_none`, but keep an array instead of dropping it.
+
+    OB 2.0 lets ``evidence`` be a bare IRI, an object with an ``id``, or an
+    array of either. A single value collapses to its IRI string (unchanged
+    behaviour); an array yields the list of IRIs it carries. None when nothing
+    usable is present — so a conformant multi-evidence assertion is no longer
+    silently discarded on parse.
+    """
+    if isinstance(value, list):
+        iris = []
+        for item in value:
+            iri = _iri_or_none(item)
+            if iri is not None:
+                iris.append(iri)
+        return iris or None
+    return _iri_or_none(value)
+
+
 def hash_identity(email: str, salt: Optional[str]) -> str:
     """Return the ``sha256$<hex>`` IdentityHash for an email plus optional salt."""
     return "sha256$" + hash_email(email, salt if salt is not None else "").decode("ascii")
@@ -143,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
@@ -174,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
@@ -209,7 +228,7 @@ class Assertion:
     issued_on: Optional[datetime] = None   # defaults to now (UTC)
     expires: Optional[datetime] = None
     image: Optional[str] = None
-    evidence: Optional[str] = None
+    evidence: Optional[Union[str, List[str]]] = None
     narrative: Optional[str] = None
 
     def __post_init__(self) -> None:
@@ -218,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,
@@ -265,7 +284,7 @@ class Assertion:
             issued_on=issued_on,
             expires=expires,
             image=_iri_or_none(d.get("image")),
-            evidence=_iri_or_none(d.get("evidence")),
+            evidence=_iri_or_iris(d.get("evidence")),
             narrative=d.get("narrative") if isinstance(d.get("narrative"), str) else None,
         )
 
@@ -278,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",
@@ -310,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,
@@ -342,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,
@@ -366,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.0 → 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.0 → 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}