openbadgeslib 4.4.4__tar.gz → 4.6.0__tar.gz

{openbadgeslib-4.4.4 → openbadgeslib-4.6.0}/CONTRIBUTING.md

@@ -34,7 +34,7 @@ pip install -e ".[dev]"          # add ,ldp and ,eudi to exercise those tracks
 
 ## The checks a pull request must pass
 
-CI runs these on Python 3.10–3.14; run them locally before opening a PR (via
+CI runs these on Python 3.10–3.15; run them locally before opening a PR (via
 your `.venv`):
 
 ```sh
@@ -73,14 +73,21 @@ page for the full convention.
 openbadgeslib supports **every CPython release that is not end-of-life**. The
 policy is deliberately simple and predictable:
 
+- A version is **deprecated** once it is in its final months before
+  end-of-life (or past it): importing openbadgeslib on it emits a
+  `DeprecationWarning`, and `Changelog.txt` announces the major that drops it.
+  It stays fully supported — `requires-python`, classifier and CI leg
+  unchanged — until that major.
 - A version is **dropped** — from `requires-python`, the classifiers, and the CI
-  matrix — at the next **major** release after it reaches end-of-life. For
-  example, Python **3.10 (EOL 2026-10)** stays supported through 4.x and is
-  dropped at the next major after that EOL (5.0). Grouping drops into majors
-  keeps breaking changes rare.
-- A new CPython minor is **added** to the CI matrix once it has a stable
-  (non-pre) release, so downstreams can adopt it early.
-- The current matrix is **3.10–3.14**, and `requires-python = ">=3.10"`.
+  matrix — at the next **major** release after it reaches end-of-life (for
+  example, 3.10 in 5.0; see below). Grouping drops into majors keeps breaking
+  changes rare.
+- A new CPython minor is **added** to the CI matrix and the classifiers once it
+  has a stable (non-pre) release, so downstreams can adopt it early.
+- The current matrix is **3.10–3.15**, and `requires-python = ">=3.10"`.
+  Python **3.10 is deprecated** since 4.6.0 (EOL 2026-10-31) and is dropped in
+  5.0, which will require Python 3.11+
+  ([#242](https://github.com/luisgf/openbadgeslib/issues/242)).
 
 Security fixes always target the latest release only (see
 [SECURITY.md](SECURITY.md)).

{openbadgeslib-4.4.4 → openbadgeslib-4.6.0}/Changelog.txt

@@ -4,6 +4,95 @@ OpenBadgesLib - Changelog
 Newest first. Dates are ISO 8601 (YYYY-MM-DD).
 
 
+* v4.6.0 - 2026-10-13
+
+  - feat: Python 3.15 is officially supported (#243). It joins the
+    publish-gating CI test matrix (lint + mypy + the full suite with every
+    optional extra now run on 3.10–3.15) and gets its trove classifier, so it
+    shows as supported on PyPI. Until now 3.15 only ran as an advisory,
+    non-gating pre-release job, which is retired.
+
+  - feat: Python 3.10 is deprecated (CPython end of life: 2026-10-31).
+    Importing openbadgeslib on 3.10 now emits a `DeprecationWarning` (shown
+    by default only for scripts and the installed `openbadges*` console
+    tools, once, on stderr). Nothing else changes in 4.x: `requires-python`,
+    the 3.10 classifier and CI leg stay. 5.0 drops 3.10 and requires Python
+    3.11+ (#242). To silence it, including in a test suite run with
+    `filterwarnings = error`, which otherwise fails at import, add the
+    message filter
+    `ignore:Python 3.10 is deprecated in openbadgeslib:DeprecationWarning`
+    (a module-based filter does not match; details on the Installation
+    wiki page).
+
+  - fix: configuration files and mail templates are read as UTF-8 (a leading
+    BOM is skipped) and `signer.log` is written as UTF-8 on every platform,
+    instead of in the locale encoding. Python 3.15 made UTF-8 the default
+    (PEP 686), so on Windows the same non-ASCII config used to be read
+    differently (and baked into badges garbled) on 3.10–3.14; a config that
+    is not valid UTF-8 now fails on every version with a `ConfigError` that
+    says so, and such a mail template makes `-M` report a mail error naming
+    the file. `--recipients-file`, already read as UTF-8, now also skips a
+    BOM (it used to stick to the first recipient) and reports a file that is
+    not valid UTF-8 instead of failing with a traceback.
+
+  - fix(oid4vci): `SqliteOID4VCIStore` closes the SQLite connection it opened
+    when configuring or migrating it fails (e.g. an unknown schema version),
+    instead of leaking the handle until garbage collection.
+
+  - fix: `download_file` closes the response held by an `HTTPError` before
+    re-raising it, so a caller that tolerates a failed fetch (the OB1 key and
+    revocation lookups) no longer leaves the socket to garbage collection
+    (a `ResourceWarning` on recent Pythons). The error's body is therefore
+    no longer readable once it propagates; its `.code`, `.headers` and
+    message are unaffected.
+
+  - security(jws): base64url is decoded strictly and canonically (RFC 4648
+    §5): the URL-safe alphabet, then no `=` padding or exactly the canonical
+    amount, with zero unused trailing bits (§3.5). `urlsafe_b64decode`
+    dropped characters outside the alphabet, took `+`/`/` for `-`/`_` and
+    ignored extra `=` and the trailing bits, so the bytes of one signature
+    had many accepted encodings. A JWS (OB1, OB2) whose signature segment is
+    spelled any other way no longer verifies; whitespace around the whole
+    token, such as a trailing newline, is ignored, but not inside a segment.
+    The library's other base64url decode sites reject the same input as
+    malformed: a status list's JWT payload or multibase (`u`) `encodedList`,
+    the SD-JWT VC issuer header read to route `x5c` (`EudiError`), and an
+    OID4VCI `c_nonce` (invalid, not spent). A bare StatusList2021
+    `encodedList` in the standard base64 alphabet (`+`, `/`, `=`), which
+    that spec allows, still decodes. OB3 JWT-VC tokens and status-list
+    proofs are verified by PyJWT and are unchanged. Prompted by Python 3.15,
+    whose `urlsafe_b64decode` warns (`FutureWarning`) that a future version
+    will discard `+` and `/`, so the same input would decode differently
+    across Python versions.
+
+
+* v4.5.0 - 2026-09-12
+
+  - feat(ob3): public `decode_encoded_list(encoded) -> bytes` and
+    `set_indices(bitstring) -> frozenset[int]` for a published Bitstring
+    Status List `encodedList` (#322). Same multibase `u` / base64url /
+    bounded-gzip (5 MiB) / MSB-first decode the verifier already uses;
+    the private `_decode_encoded_list` name remains as a thin alias.
+
+  - feat(ob3): `build_status_list_credential(..., ttl=)` writes Bitstring
+    Status List §2.2 `ttl` (milliseconds) on `credentialSubject`, never at
+    the top level — `ttl` is a JSON-LD term scoped to `BitstringStatusList`,
+    so a top-level copy would not be signed (#321). Negative values raise
+    `ValueError`.
+
+  - feat(ob3): native CLR 2.0 `ClrCredential` builder (`build_clr_credential`,
+    `sign_clr_credential`) with the versioned `context-2.0.1.json` bundled
+    and hash-pinned (`CLR_CONTEXT_SHA256`) (#323). Identifier objects and
+    member credentials are copied as given — email hashing and member-count
+    caps stay downstream. Signing injects the pinned context via
+    `extra_contexts` (requires `[ldp]`).
+
+  - feat(ob2): `OB2Verifier.verify_hosted(document)` verifies a hosted
+    assertion JSON document (dict or JSON string) without synthesizing a
+    dummy JWS. The HTTPS fetcher is injectable via
+    `OB2Verifier(..., download=)`.
+
+
 * v4.4.4 - 2026-09-10
 
   - security(baking): SVG baking strips ``<script>`` / ``foreignObject`` /

{openbadgeslib-4.4.4 → openbadgeslib-4.6.0}/GOVERNANCE.md

@@ -25,7 +25,7 @@ Releases are **CI-driven and credential-less to publish**:
 
 - The version is single-sourced in `openbadgeslib/util.py`; a pushed `vX.Y.Z`
   tag triggers the CI workflow, which runs the full test matrix (Python
-  3.10–3.14) and then publishes to
+  3.10–3.15) and then publishes to
   [PyPI](https://pypi.org/project/openbadgeslib/).
 - Publishing uses **PyPI Trusted Publishing (OIDC)** — there is **no long-lived
   PyPI API token** stored anywhere. The publish job authenticates to PyPI from

{openbadgeslib-4.4.4 → openbadgeslib-4.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openbadgeslib
-Version: 4.4.4
+Version: 4.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
@@ -22,6 +22,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Natural Language :: English
 Classifier: Natural Language :: Spanish
@@ -57,7 +58,7 @@ Dynamic: license-file
 
 [![CI](https://github.com/luisgf/openbadgeslib/actions/workflows/ci.yml/badge.svg)](https://github.com/luisgf/openbadgeslib/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/openbadgeslib.svg)](https://pypi.org/project/openbadgeslib/)
-[![Python](https://img.shields.io/badge/python-3.10%E2%80%933.14-blue.svg)](https://github.com/luisgf/openbadgeslib/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.10%E2%80%933.15-blue.svg)](https://github.com/luisgf/openbadgeslib/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-LGPLv3%20%2F%20BSD-blue.svg)](#license)
 
 **A production-ready Python library & CLI for the full Open Badges 3.0 issuer
@@ -68,7 +69,7 @@ with W3C Bitstring Status Lists and `did:web`. It also ships strict
 **OpenBadges 2.0** (JWS / hosted assertions) and a frozen **OpenBadges 1.0**
 legacy format, selected with `-V {1,2,3}` (default `3`).
 
-> **4.0.0 is released** (2026-07-22). It groups the breaking changes so upgrades stay rare: every CLI unifies on one `0/1/2` exit-code contract (a valid-but-untrusted badge now exits `2`, and the 255s are gone), and the legacy pycryptodome/python-ecdsa compat shim is removed — a live key **object** from either is no longer accepted, though key *files* are plain PEM and round-trip unchanged. OpenBadges 1.0 and the `openbadges-<command>` scripts stay, and a new unified `openbadges <command>` front-end joins them. **Python 3.10 is still supported** (`requires-python >= 3.10`, tested in CI on 3.10–3.14); dropping it is deferred to its end of life. See **[Upgrading to 4.0](https://github.com/luisgf/openbadgeslib/wiki/Upgrading-to-4.0)** before pinning a major.
+> **4.0.0 is released** (2026-07-22). It groups the breaking changes so upgrades stay rare: every CLI unifies on one `0/1/2` exit-code contract (a valid-but-untrusted badge now exits `2`, and the 255s are gone), and the legacy pycryptodome/python-ecdsa compat shim is removed — a live key **object** from either is no longer accepted, though key *files* are plain PEM and round-trip unchanged. OpenBadges 1.0 and the `openbadges-<command>` scripts stay, and a new unified `openbadges <command>` front-end joins them. **Python 3.10 stays supported throughout 4.x** (`requires-python >= 3.10`; CI tests 3.10–3.15) but is deprecated since 4.6.0, ahead of its 2026-10-31 end of life; 5.0 drops it and requires Python 3.11+. See **[Upgrading to 4.0](https://github.com/luisgf/openbadgeslib/wiki/Upgrading-to-4.0)** before pinning a major.
 
 ## Features
 
@@ -96,7 +97,7 @@ legacy format, selected with `-V {1,2,3}` (default `3`).
   (EdDSA) — *plus* native **W3C Data Integrity / LDP** signing
   (`eddsa-rdfc-2022`, Ed25519, optional `[ldp]` extra). Both proof formats
   issue *and* verify offline, no external service.
-- **Lean and typed** — `mypy --strict`, CI on Python 3.10–3.14, a small
+- **Lean and typed** — `mypy --strict`, CI on Python 3.10–3.15, a small
   dependency set, dataclasses + explicit validation (no Pydantic).
 - **Dual-licensed** LGPLv3 (library) / BSD-2-Clause (CLI tools).
 
@@ -122,7 +123,7 @@ additive EUDI SD-JWT VC wallet track.
 | `did:web` (generate + resolve) | ✅ | — | — | — | resolve only |
 | Image baking (SVG + PNG) | ✅ | unbake only | ✅ | — | — |
 | Form factor | library + CLI (`openbadges` + 5 aliases) | library + CLI | Django server | library | binding |
-| Typing / CI | `mypy --strict`, CI 3.10–3.14 | — | — | Pydantic | — |
+| Typing / CI | `mypy --strict`, CI 3.10–3.15 | — | — | Pydantic | — |
 | License | LGPLv3 / BSD-2 | Apache-2.0 | AGPL-3.0 | MIT/LGPL | Apache-2.0 |
 
 (a) The actively-maintained community fork (open-educational-badges): it
@@ -141,7 +142,10 @@ all three OB versions.
 
 ## Requirements
 
-- Python >= 3.10 (tested on 3.10–3.14)
+- Python >= 3.10 (tested on 3.10–3.15). Python 3.10 is deprecated since
+  4.6.0 — importing openbadgeslib on it emits a `DeprecationWarning` — and
+  openbadgeslib 5.0 will require Python 3.11 or newer
+  ([#242](https://github.com/luisgf/openbadgeslib/issues/242)).
 - [pypng](https://pypi.org/project/pypng/) >= 0.20220715.0
 - [PyJWT[crypto]](https://pypi.org/project/PyJWT/) >= 2.13
 - [cryptography](https://pypi.org/project/cryptography/) >= 45

{openbadgeslib-4.4.4 → openbadgeslib-4.6.0}/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/luisgf/openbadgeslib/actions/workflows/ci.yml/badge.svg)](https://github.com/luisgf/openbadgeslib/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/openbadgeslib.svg)](https://pypi.org/project/openbadgeslib/)
-[![Python](https://img.shields.io/badge/python-3.10%E2%80%933.14-blue.svg)](https://github.com/luisgf/openbadgeslib/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.10%E2%80%933.15-blue.svg)](https://github.com/luisgf/openbadgeslib/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-LGPLv3%20%2F%20BSD-blue.svg)](#license)
 
 **A production-ready Python library & CLI for the full Open Badges 3.0 issuer
@@ -13,7 +13,7 @@ with W3C Bitstring Status Lists and `did:web`. It also ships strict
 **OpenBadges 2.0** (JWS / hosted assertions) and a frozen **OpenBadges 1.0**
 legacy format, selected with `-V {1,2,3}` (default `3`).
 
-> **4.0.0 is released** (2026-07-22). It groups the breaking changes so upgrades stay rare: every CLI unifies on one `0/1/2` exit-code contract (a valid-but-untrusted badge now exits `2`, and the 255s are gone), and the legacy pycryptodome/python-ecdsa compat shim is removed — a live key **object** from either is no longer accepted, though key *files* are plain PEM and round-trip unchanged. OpenBadges 1.0 and the `openbadges-<command>` scripts stay, and a new unified `openbadges <command>` front-end joins them. **Python 3.10 is still supported** (`requires-python >= 3.10`, tested in CI on 3.10–3.14); dropping it is deferred to its end of life. See **[Upgrading to 4.0](https://github.com/luisgf/openbadgeslib/wiki/Upgrading-to-4.0)** before pinning a major.
+> **4.0.0 is released** (2026-07-22). It groups the breaking changes so upgrades stay rare: every CLI unifies on one `0/1/2` exit-code contract (a valid-but-untrusted badge now exits `2`, and the 255s are gone), and the legacy pycryptodome/python-ecdsa compat shim is removed — a live key **object** from either is no longer accepted, though key *files* are plain PEM and round-trip unchanged. OpenBadges 1.0 and the `openbadges-<command>` scripts stay, and a new unified `openbadges <command>` front-end joins them. **Python 3.10 stays supported throughout 4.x** (`requires-python >= 3.10`; CI tests 3.10–3.15) but is deprecated since 4.6.0, ahead of its 2026-10-31 end of life; 5.0 drops it and requires Python 3.11+. See **[Upgrading to 4.0](https://github.com/luisgf/openbadgeslib/wiki/Upgrading-to-4.0)** before pinning a major.
 
 ## Features
 
@@ -41,7 +41,7 @@ legacy format, selected with `-V {1,2,3}` (default `3`).
   (EdDSA) — *plus* native **W3C Data Integrity / LDP** signing
   (`eddsa-rdfc-2022`, Ed25519, optional `[ldp]` extra). Both proof formats
   issue *and* verify offline, no external service.
-- **Lean and typed** — `mypy --strict`, CI on Python 3.10–3.14, a small
+- **Lean and typed** — `mypy --strict`, CI on Python 3.10–3.15, a small
   dependency set, dataclasses + explicit validation (no Pydantic).
 - **Dual-licensed** LGPLv3 (library) / BSD-2-Clause (CLI tools).
 
@@ -67,7 +67,7 @@ additive EUDI SD-JWT VC wallet track.
 | `did:web` (generate + resolve) | ✅ | — | — | — | resolve only |
 | Image baking (SVG + PNG) | ✅ | unbake only | ✅ | — | — |
 | Form factor | library + CLI (`openbadges` + 5 aliases) | library + CLI | Django server | library | binding |
-| Typing / CI | `mypy --strict`, CI 3.10–3.14 | — | — | Pydantic | — |
+| Typing / CI | `mypy --strict`, CI 3.10–3.15 | — | — | Pydantic | — |
 | License | LGPLv3 / BSD-2 | Apache-2.0 | AGPL-3.0 | MIT/LGPL | Apache-2.0 |
 
 (a) The actively-maintained community fork (open-educational-badges): it
@@ -86,7 +86,10 @@ all three OB versions.
 
 ## Requirements
 
-- Python >= 3.10 (tested on 3.10–3.14)
+- Python >= 3.10 (tested on 3.10–3.15). Python 3.10 is deprecated since
+  4.6.0 — importing openbadgeslib on it emits a `DeprecationWarning` — and
+  openbadgeslib 5.0 will require Python 3.11 or newer
+  ([#242](https://github.com/luisgf/openbadgeslib/issues/242)).
 - [pypng](https://pypi.org/project/pypng/) >= 0.20220715.0
 - [PyJWT[crypto]](https://pypi.org/project/PyJWT/) >= 2.13
 - [cryptography](https://pypi.org/project/cryptography/) >= 45

{openbadgeslib-4.4.4 → openbadgeslib-4.6.0}/openbadgeslib/__init__.py

@@ -72,6 +72,19 @@ from .issue import (  # noqa: F401
 from .verify import verify_badge  # noqa: F401
 
 
+# ── Supported Python versions ────────────────────────────────────────────────
+# On a deprecated CPython (3.10, dropped in 5.0 — #242) the package's first
+# import emits a DeprecationWarning, whichever entry point triggers it (import
+# openbadgeslib, a submodule, an installed console script). PEP 565 shows it by
+# default only when __main__ is the importer: a script or a console script,
+# not `python -m openbadgeslib.<tool>` or an importlib-based loader (attributed
+# to runpy/importlib, so hidden unless warnings are enabled: -W, -X dev,
+# pytest). It runs after the imports above because a call placed before them
+# would trip flake8's E402.
+from . import _python_support
+_python_support.warn_if_deprecated()
+
+
 # ── OpenBadges 1.0 (legacy) ──────────────────────────────────────────────────
 # The unprefixed OB1 names (Signer, Verifier, Badge, …) stay importable from
 # the top-level package for backward compatibility. They are the legacy

{openbadgeslib-4.4.4 → openbadgeslib-4.6.0}/openbadgeslib/_jws/__init__.py

@@ -127,6 +127,10 @@ def verify_block(msg: Union[str, bytes], key: Optional[Any] = None) -> bool:
     """Verify a JWS compact serialization (bytes or str). Returns True or raises SignatureError."""
     if isinstance(msg, str):
         msg = msg.encode('utf-8')
+    # Transport whitespace around the whole token (a trailing newline from a
+    # file or a third-party baker) is not part of any signed segment; inside
+    # a segment it still fails the strict base64url decode.
+    msg = msg.strip()
 
     try:
         head_b64, payload_b64, sig_b64 = msg.split(b'.')

openbadgeslib-4.6.0/openbadgeslib/_jws/utils.py

@@ -0,0 +1,57 @@
+import base64
+import binascii
+import json
+import re
+
+from typing import Any, Union
+
+_B64URL_ALPHABET = re.compile(rb'[A-Za-z0-9_-]*')
+
+
+def base64url_decode(data: Union[str, bytes]) -> bytes:
+    # Strict, canonical RFC 4648 §5: the URL-safe alphabet, then either no
+    # padding (JWS/JWT strip it) or exactly the canonical (-len) % 4 '='
+    # characters, with zero unused trailing bits (§3.5). urlsafe_b64decode()
+    # silently drops other characters, takes '+'/'/' as aliases of '-'/'_'
+    # (Python 3.15 warns that this will change), and ignores extra '=' and
+    # the trailing bits, so the same bytes had many accepted encodings. Every
+    # caller feeds it untrusted input, so anything else raises binascii.Error
+    # (a ValueError); a non-str/bytes argument raises TypeError.
+    if isinstance(data, str):
+        if not data.isascii():
+            raise binascii.Error('base64url data must be ASCII')
+        data = data.encode('ascii')
+    elif isinstance(data, (bytearray, memoryview)):
+        data = bytes(data)
+    elif not isinstance(data, bytes):
+        raise TypeError('base64url data must be str or bytes, not %s'
+                        % type(data).__name__)
+    stripped = data.rstrip(b'=')
+    pad = -len(stripped) % 4
+    if (not _B64URL_ALPHABET.fullmatch(stripped) or len(stripped) % 4 == 1
+            or len(data) - len(stripped) not in (0, pad)):
+        raise binascii.Error('invalid base64url data')
+    raw = base64.urlsafe_b64decode(stripped + b'=' * pad)
+    if base64.urlsafe_b64encode(raw).rstrip(b'=') != stripped:
+        raise binascii.Error('non-canonical base64url data (non-zero pad bits)')
+    return raw
+
+
+def base64url_encode(input: bytes) -> bytes:
+    return base64.urlsafe_b64encode(input).replace(b'=', b'')
+
+
+def to_json(a: Any) -> bytes:
+    return json.dumps(a).encode('utf-8')
+
+
+def from_json(a: Union[str, bytes]) -> Any:
+    if isinstance(a, (bytes, bytearray)):
+        a = a.decode('utf-8')
+    return json.loads(a)
+
+
+def to_base64(a: bytes) -> bytes: return base64url_encode(a)
+def from_base64(a: bytes) -> bytes: return base64url_decode(a)
+def encode(a: Any) -> bytes: return to_base64(to_json(a))
+def decode(a: bytes) -> Any: return from_json(from_base64(a))

openbadgeslib-4.6.0/openbadgeslib/_python_support.py

@@ -0,0 +1,54 @@
+"""
+        OpenBadges Library
+
+        Copyright (c) 2014-2026, Luis González Fernández, luisgf@luisgf.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.
+"""
+
+# The runtime side of the "Supported Python versions" policy (CONTRIBUTING.md):
+# a CPython that is still supported but nearing (or past) end of life is
+# deprecated — importing openbadgeslib on it emits a DeprecationWarning — and
+# is dropped only at the next major release.
+#
+# Python 3.10 is deprecated since 4.6.0 and dropped in 5.0 (#242). That drop
+# raises requires-python, the mypy python_version and DEPRECATED_BELOW together,
+# rewording DEPRECATION_MESSAGE for the next deprecated version — or deletes
+# this module (and its call in __init__) if none is pending removal.
+
+import sys
+import warnings
+from typing import Tuple
+
+#: Importing openbadgeslib on a Python older than this emits the warning below.
+DEPRECATED_BELOW = (3, 11)
+
+DEPRECATION_MESSAGE = (
+    'Python 3.10 is deprecated in openbadgeslib (CPython end of life: '
+    '2026-10-31); openbadgeslib 5.0 will require Python 3.11 or newer.')
+
+
+def warn_if_deprecated(version_info: Tuple[object, ...] = sys.version_info) -> None:
+    """Emit DEPRECATION_MESSAGE if *version_info* is a deprecated Python.
+
+    Called once from the package ``__init__``; tests pass a fake version.
+    """
+    if version_info < DEPRECATED_BELOW:
+        # stacklevel=3 skips this helper and the package __init__ (warnings
+        # also skips importlib's bootstrap frames, bpo-24305), so the warning
+        # is attributed to the code that imported openbadgeslib: PEP 565 then
+        # shows it for a script (__main__) and hides it for a library import.
+        warnings.warn(DEPRECATION_MESSAGE, DeprecationWarning, stacklevel=3)

{openbadgeslib-4.4.4 → openbadgeslib-4.6.0}/openbadgeslib/confparser.py

@@ -593,11 +593,14 @@ class ConfParser():
         self.parser = ConfigParser(interpolation=ExtendedInterpolation())
 
         try:
-            self.parser.read(self.config_file)
-        except UnicodeDecodeError:
-            # We should raise an UnicodeDecodeError, but the error message is too cryptic.#
-            raise ConfigError("The encoding of the configuration file and the default encoding of "
-                              "the operating system mismatch") from None
+            # Always UTF-8 (a BOM, as some Windows editors write, is skipped):
+            # the locale encoding would make the same file read differently
+            # across platforms and across 3.10-3.15 (PEP 686).
+            self.parser.read(self.config_file, encoding='utf-8-sig')
+        except UnicodeDecodeError as exc:
+            # The raw UnicodeDecodeError message is too cryptic.
+            raise ConfigError("Configuration file %s is not valid UTF-8: %s"
+                              % (self.config_file, exc)) from None
         except ConfigParserError as exc:
             # Malformed INI syntax (duplicate section/option, a value line
             # with no section header before it, ...) raises directly from

{openbadgeslib-4.4.4 → openbadgeslib-4.6.0}/openbadgeslib/mail.py

@@ -126,8 +126,15 @@ class BadgeMail():
         """ Return the Subject and Body of the Email. The first line of the file
         is used as Subject """
 
-        with open(file, 'r') as f:
-            data = f.readlines()
+        # UTF-8 on every platform and Python (PEP 686); a BOM is skipped so it
+        # cannot end up in the Subject.
+        try:
+            with open(file, 'r', encoding='utf-8-sig') as f:
+                data = f.readlines()
+        except UnicodeDecodeError as exc:
+            # Name the file: the bare codec message does not say what failed.
+            raise ValueError('Mail template %s is not valid UTF-8: %s'
+                             % (file, exc)) from exc
 
         if data:
             return data[0].strip('\n'), ''.join(data[1:])

{openbadgeslib-4.4.4 → openbadgeslib-4.6.0}/openbadgeslib/ob1/badge.py

@@ -65,7 +65,8 @@ class Assertion():
     @staticmethod
     def decode(data: bytes) -> 'Assertion':
         try:
-            header, body, signature = data.split(b'.')
+            # Whitespace around the token is transport noise (see verify_block).
+            header, body, signature = data.strip().split(b'.')
             return Assertion(header, body, signature)
         except Exception:
             raise AssertionFormatIncorrect()

{openbadgeslib-4.4.4 → openbadgeslib-4.6.0}/openbadgeslib/ob2/verifier.py

@@ -22,7 +22,7 @@
 
 import logging
 from datetime import datetime, timezone
-from typing import Any, List, Optional, Union
+from typing import Any, Callable, List, Optional, Union
 from urllib.parse import urlparse
 
 from .models import Assertion, CryptographicKey, hash_identity, _parse_iso
@@ -67,10 +67,16 @@ class OB2Verifier:
         pubkey_pem: Optional PEM-encoded trusted public key. When supplied it is
                     used to verify SignedBadge assertions and skips resolving the
                     badge-declared key.
+        download: Optional ``url -> bytes`` fetcher used by hosted verification
+                  (assertion id, BadgeClass, issuer Profile, revocation list).
+                  Defaults to :func:`download_file` (HTTPS-only, size-capped).
     """
 
-    def __init__(self, pubkey_pem: Optional[Any] = None) -> None:
+    def __init__(self, pubkey_pem: Optional[Any] = None, *,
+                 download: Optional[Callable[[str], bytes]] = None) -> None:
         self.trusted_pubkey_pem: Optional[Union[str, bytes]] = None
+        self._download: Callable[[str], bytes] = (
+            download if download is not None else download_file)
         if pubkey_pem is not None:
             pem = key_to_pem(pubkey_pem)
             try:
@@ -122,6 +128,67 @@ class OB2Verifier:
 
         return assertion
 
+    def verify_hosted(self, document: Union[str, dict[str, Any]], *,
+                      expected_recipient: Optional[str] = None,
+                      check_revocation: bool = False) -> Assertion:
+        """Verify a hosted OB 2.0 assertion JSON document (not a compact JWS).
+
+        *document* is the assertion as a dict or a JSON string. The hosted
+        model is fetch-from-id: the copy served at ``assertion.id`` is the
+        trust anchor (scoped to the issuer Profile), so this does not
+        synthesize a dummy JWS. Defence-in-depth JWS verification inside
+        :meth:`_verify_hosted` is skipped when there is no token.
+
+        ``expected_recipient`` and ``check_revocation`` behave as in
+        :meth:`verify`. Raises :class:`OB2VerificationError` if the document
+        is not a HostedBadge assertion or if any check fails.
+        """
+        parsed = self._hosted_document(document)
+        try:
+            assertion = Assertion.from_dict(parsed)
+        except ValueError as exc:
+            raise OB2VerificationError(
+                "Malformed OB 2.0 assertion: %s" % exc) from exc
+        if assertion.verification.type != "HostedBadge":
+            raise OB2VerificationError(
+                "verify_hosted() requires verification.type HostedBadge, got %r"
+                % assertion.verification.type)
+
+        assertion = self._verify_hosted(assertion, "")
+
+        self._check_expiration(assertion)
+
+        if expected_recipient is not None:
+            self._check_identity(assertion, expected_recipient)
+
+        if check_revocation:
+            self._check_revocation(assertion)
+
+        return assertion
+
+    @staticmethod
+    def _hosted_document(document: Union[str, dict[str, Any]]) -> dict[str, Any]:
+        """Parse a hosted assertion from a dict or JSON string (never a JWS)."""
+        if isinstance(document, str):
+            text = document.strip()
+            if text.count('.') == 2 and not text.startswith('{'):
+                raise OB2VerificationError(
+                    "verify_hosted() expects a hosted assertion JSON document, "
+                    "not a compact JWS; use verify() for SignedBadge tokens")
+            try:
+                parsed = jws_utils.from_json(text)
+            except Exception as exc:
+                raise OB2VerificationError(
+                    "hosted assertion is not valid JSON: %s" % exc) from exc
+        elif isinstance(document, dict):
+            parsed = document
+        else:
+            raise OB2VerificationError(
+                "hosted assertion must be a dict or JSON string")
+        if not isinstance(parsed, dict):
+            raise OB2VerificationError("hosted assertion is not a JSON object")
+        return parsed
+
     # ── signed path ──────────────────────────────────────────────────────────────
 
     def _verify_signed(self, assertion: Assertion, token: str) -> None:
@@ -255,16 +322,18 @@ class OB2Verifier:
         # verify it, but never fail the hosted verdict on it (a hosted badge is
         # not required to be signed at all). The creator comes from the
         # authoritative copy, so this never dereferences a holder-chosen URL.
-        try:
-            if self.trusted_pubkey_pem is not None:
-                self._verify_jws(token, self.trusted_pubkey_pem)
-            elif authoritative.verification.creator:
-                key = self._resolve_creator(authoritative.verification.creator)
-                self._verify_jws(token, key.public_key_pem.encode('utf-8'))
-        except OB2VerificationError as exc:
-            logger.debug("Hosted assertion %s: baked JWS did not verify (%s); "
-                         "hosted trust comes from the HTTPS fetch, not the signature.",
-                         assertion.id, exc)
+        # verify_hosted() passes an empty token (there is no JWS); skip then.
+        if token:
+            try:
+                if self.trusted_pubkey_pem is not None:
+                    self._verify_jws(token, self.trusted_pubkey_pem)
+                elif authoritative.verification.creator:
+                    key = self._resolve_creator(authoritative.verification.creator)
+                    self._verify_jws(token, key.public_key_pem.encode('utf-8'))
+            except OB2VerificationError as exc:
+                logger.debug("Hosted assertion %s: baked JWS did not verify (%s); "
+                             "hosted trust comes from the HTTPS fetch, not the signature.",
+                             assertion.id, exc)
         return authoritative
 
     def _check_hosted_scope(self, assertion_id: str, issuer: dict[str, Any]) -> None:
@@ -373,7 +442,7 @@ class OB2Verifier:
 
     def _fetch_json(self, url: str, where: str) -> dict[str, Any]:
         try:
-            raw = download_file(url)
+            raw = self._download(url)
         except Exception as exc:
             raise OB2VerificationError(
                 "Could not fetch %s at %s: %s" % (where, url, exc)) from exc

{openbadgeslib-4.4.4 → openbadgeslib-4.6.0}/openbadgeslib/ob3/__init__.py

@@ -27,9 +27,12 @@ from .verifier import (OB3VerificationError, OB3Verifier,
                        verify_endorsement_jwt)
 from .ldp import (OB3LdpSigner, OB3LdpVerifier, add_data_integrity_proof,
                   verify_data_integrity_proof)
-from .status import check_credential_status
+from .status import check_credential_status, decode_encoded_list, set_indices
 from .status_list import (build_status_list_credential, encode_bitstring,
                           sign_status_list_credential, status_entry)
+from .clr import (CLR_CONTEXT_SHA256, CLR_CONTEXT_URL, OB_V3_CONTEXT,
+                  VCDM_V2_CONTEXT, build_clr_credential, bundled_clr_contexts,
+                  sign_clr_credential)
 from .status_registry import StatusRegistry
 from .did import (build_did_document, did_jwk_from_jwk, did_key_from_pem,
                   did_web_from_url, multikey_from_pem, resolve_did,
@@ -68,16 +71,25 @@ __all__ = [
     'verify_data_integrity_proof',
     'StatusRegistry',
     'build_did_document',
+    'build_clr_credential',
     'build_status_list_credential',
+    'bundled_clr_contexts',
     'check_credential_status',
+    'CLR_CONTEXT_SHA256',
+    'CLR_CONTEXT_URL',
+    'decode_encoded_list',
     'did_jwk_from_jwk',
     'did_key_from_pem',
     'did_web_from_url',
     'encode_bitstring',
     'multikey_from_pem',
+    'OB_V3_CONTEXT',
     'resolve_did',
     'resolve_verification_method',
+    'set_indices',
+    'sign_clr_credential',
     'sign_status_list_credential',
     'status_entry',
+    'VCDM_V2_CONTEXT',
     'verify_endorsement_jwt',
 ]