openbadgeslib 3.7.0__tar.gz → 3.8.0__tar.gz

{openbadgeslib-3.7.0 → openbadgeslib-3.8.0}/Changelog.txt

@@ -4,6 +4,24 @@ OpenBadgesLib - Changelog
 Newest first. Dates are ISO 8601 (YYYY-MM-DD).
 
 
+* v3.8.0 - 2026-07-08
+
+  - security(ob3): status lists gain replay protection and opt-in proof
+    verification, closing two documented trust gaps. (1) A per-badge
+    `status_validity_days` makes published lists carry a `validUntil`, and the
+    reader now enforces the list's validFrom/validUntil window — a lapsed
+    (replayed, or no-longer-republished) `revocation.jwt` is rejected instead
+    of silently resurrecting a revoked badge. (2)
+    `check_credential_status(..., verify_list=True)` (and
+    `OB3Verifier.check_status(..., verify_list=True)`) additionally verifies
+    the status list credential's own JWT-VC proof and binds its issuer to the
+    badge's, so a compromised status host cannot serve a validly-shaped list
+    that silently un-revokes. The list is signed with the badge key, so that
+    same key (reused automatically) verifies it; a did:web/did:key issuer is
+    resolved otherwise. Both are opt-in — the default stays a single
+    offline-friendly fetch, no behaviour break. (#164)
+
+
 * v3.7.0 - 2026-07-08
 
   - security(deps): `keys.py` (and the OB1 key-loading path) are ported to

{openbadgeslib-3.7.0/openbadgeslib.egg-info → openbadgeslib-3.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openbadgeslib
-Version: 3.7.0
+Version: 3.8.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.7.0 → openbadgeslib-3.8.0}/openbadgeslib/confparser.py

@@ -105,6 +105,7 @@ class OB3StatusConfig:
     size_bits: int
     registry_path: str            # private index registry JSON
     list_urls: Dict[str, str]     # purpose -> public status list URL
+    validity_days: Optional[int] = None   # validUntil horizon; None => no bound
 
 
 def ob3_status_config(conf: ConfigParser,
@@ -140,6 +141,22 @@ def ob3_status_config(conf: ConfigParser,
         raise ValueError("[%s] status_size_bits must be an integer"
                          % badge_section) from None
 
+    # Optional validUntil horizon: when set, published status lists carry a
+    # validUntil = now + N days, and a verifier rejects a stale copy (replay
+    # protection). Unset => no bound (offline-friendly default). The issuer
+    # must republish within the window (see the wiki).
+    validity_raw = (conf[badge_section].get('status_validity_days') or '').strip()
+    validity_days: Optional[int] = None
+    if validity_raw:
+        try:
+            validity_days = int(validity_raw)
+        except ValueError:
+            raise ValueError("[%s] status_validity_days must be an integer"
+                             % badge_section) from None
+        if validity_days <= 0:
+            raise ValueError("[%s] status_validity_days must be positive"
+                             % badge_section)
+
     base_status = conf['paths'].get('base_status') or \
         os.path.join(conf['paths']['base'], 'status')
     registry_path = os.path.join(base_status, badge_section + '.json')
@@ -151,7 +168,8 @@ def ob3_status_config(conf: ConfigParser,
     list_urls = {p: urljoin(status_base, p + '.jwt') for p in purposes}
 
     return OB3StatusConfig(purposes=purposes, size_bits=size_bits,
-                           registry_path=registry_path, list_urls=list_urls)
+                           registry_path=registry_path, list_urls=list_urls,
+                           validity_days=validity_days)
 
 
 class ConfParser():

{openbadgeslib-3.7.0 → openbadgeslib-3.8.0}/openbadgeslib/ob3/status.py

@@ -27,18 +27,22 @@
 # Credentials data model. This is the OB3 counterpart of OB2's revocation-list
 # check: without it, an issuer's revocation has no effect on the verdict.
 #
-# Trust note: this checks the *published* status bit only. It does NOT verify
-# the status-list credential's own proof/signature — that is a separate trust
-# chain (often a different key). A caller needing that guarantee must verify
-# the status-list credential independently.
+# Trust note: by default this checks the *published* status bit and the list's
+# validFrom/validUntil window (a lapsed list is rejected, so a replayed old
+# copy cannot resurrect a revoked badge). It does NOT, by default, verify the
+# status-list credential's own proof/signature — that is a separate trust
+# chain. Pass verify_list=True (with the issuer's key or a DID issuer) to also
+# verify the list's JWT-VC proof and bind its issuer to the badge's, closing
+# the gap where a compromised status host could silently un-revoke.
 
 import base64
 import json
 import zlib
 
-from typing import Any, Callable, List, Optional
+from datetime import datetime, timezone
+from typing import Any, Callable, List, Optional, Union
 
-from .credential import OpenBadgeCredential
+from .credential import OpenBadgeCredential, _parse_iso
 from .verifier import OB3VerificationError
 from ..util import download_file
 
@@ -53,20 +57,36 @@ MAX_STATUS_LIST_BYTES = 5 * 1024 * 1024  # 5 MiB
 
 def check_credential_status(
         credential: OpenBadgeCredential,
-        download: Optional[Callable[[str], bytes]] = None) -> None:
+        download: Optional[Callable[[str], bytes]] = None,
+        *,
+        verify_list: bool = False,
+        list_pubkey_pem: Optional[Union[str, bytes]] = None) -> None:
     """Check every credentialStatus entry, raising OB3VerificationError if the
     credential is revoked/suspended or if its status cannot be determined.
 
     Fail-closed: a fetch or parse failure raises rather than silently passing.
     A credential with no credentialStatus is a no-op. ``download`` defaults to
     util.download_file (HTTPS-only, size-capped); it is injectable for testing.
+
+    The list's ``validFrom``/``validUntil`` window is always enforced (a lapsed
+    or not-yet-valid list is rejected). Pass ``verify_list=True`` to also verify
+    the status-list credential's own JWT-VC proof and require its issuer to
+    equal the badge's issuer — supply ``list_pubkey_pem`` (the issuer's public
+    key, e.g. the one that verified the badge), or rely on DID resolution when
+    the badge issuer is a ``did:web``/``did:key``. Off by default so a status
+    check stays a single offline-friendly fetch.
     """
     fetch = download if download is not None else download_file
+    badge_issuer = credential.issuer.id if credential.issuer else None
     for entry in credential.credential_status:
-        _check_entry(entry, fetch)
+        _check_entry(entry, fetch, badge_issuer=badge_issuer,
+                     verify_list=verify_list, list_pubkey_pem=list_pubkey_pem)
 
 
-def _check_entry(entry: dict[str, Any], download: Callable[[str], bytes]) -> None:
+def _check_entry(entry: dict[str, Any], download: Callable[[str], bytes],
+                 *, badge_issuer: Optional[str] = None,
+                 verify_list: bool = False,
+                 list_pubkey_pem: Optional[Union[str, bytes]] = None) -> None:
     types = set(_as_list(entry.get("type")))
     if not (types & _SUPPORTED_ENTRY_TYPES):
         raise OB3VerificationError(
@@ -87,7 +107,8 @@ def _check_entry(entry: dict[str, Any], download: Callable[[str], bytes]) -> Non
             "could not fetch status list %s: %s" % (list_url, exc)) from exc
 
     try:
-        subject = _status_list_subject(raw)
+        doc = _status_list_document(raw)
+        subject = _subject_of(doc)
         # 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
@@ -113,6 +134,16 @@ def _check_entry(entry: dict[str, Any], download: Callable[[str], bytes]) -> Non
         raise OB3VerificationError(
             "malformed status list %s: %s" % (list_url, exc)) from exc
 
+    # Reject a stale (or not-yet-valid) list so a replayed old copy cannot
+    # resurrect a revoked badge. A list with no validUntil is not expired.
+    _check_list_window(doc, list_url)
+
+    # Opt-in: verify the list credential's OWN proof and bind its issuer to the
+    # badge's, so a compromised status host cannot silently un-revoke.
+    if verify_list:
+        _verify_list_proof(raw, doc, list_url, badge_issuer, download,
+                           list_pubkey_pem)
+
     # 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:
@@ -145,9 +176,9 @@ def _parse_index(value: Any) -> int:
         raise OB3VerificationError("invalid statusListIndex: %r" % (value,)) from None
 
 
-def _status_list_subject(raw: bytes) -> dict[str, Any]:
-    """Return the credentialSubject of a status-list credential served either as
-    a JSON-LD VC document or as a compact JWT-VC string."""
+def _status_list_document(raw: bytes) -> dict[str, Any]:
+    """Return the status-list credential document (its top-level claims) served
+    either as a JSON-LD VC document or as a compact JWT-VC string."""
     text = raw.decode('utf-8').strip()
 
     if text.startswith('{'):
@@ -164,6 +195,10 @@ def _status_list_subject(raw: bytes) -> dict[str, Any]:
 
     if not isinstance(doc, dict):
         raise OB3VerificationError("status list credential is not an object")
+    return doc
+
+
+def _subject_of(doc: dict[str, Any]) -> dict[str, Any]:
     subject = doc.get("credentialSubject")
     if isinstance(subject, list):
         subject = subject[0] if subject else None
@@ -173,6 +208,97 @@ def _status_list_subject(raw: bytes) -> dict[str, Any]:
     return subject
 
 
+def _issuer_id(issuer: Any) -> Optional[str]:
+    """The issuer identifier of a VC, whether given as a bare IRI or an object
+    with an ``id`` (matches OpenBadgeCredential's issuer handling)."""
+    if isinstance(issuer, str):
+        return issuer
+    if isinstance(issuer, dict):
+        value = issuer.get("id")
+        return value if isinstance(value, str) else None
+    return None
+
+
+def _check_list_window(doc: dict[str, Any], list_url: str) -> None:
+    """Enforce the status list's validFrom/validUntil against wall-clock time.
+
+    A ``validUntil`` in the past means the served list is stale — an issuer that
+    stopped republishing, or a replayed old copy — so it is rejected rather than
+    trusted (an old revocation.jwt would otherwise silently un-revoke). A
+    ``validFrom`` in the future is likewise rejected. Absent bounds are fine.
+    """
+    now = datetime.now(timezone.utc)
+    valid_until = doc.get("validUntil")
+    if isinstance(valid_until, str):
+        try:
+            expires = _parse_iso(valid_until)
+        except Exception as exc:
+            raise OB3VerificationError(
+                "status list %s has an invalid validUntil %r: %s"
+                % (list_url, valid_until, exc)) from exc
+        if expires < now:
+            raise OB3VerificationError(
+                "status list %s expired (validUntil %s); the issuer must "
+                "republish it" % (list_url, valid_until))
+    valid_from = doc.get("validFrom")
+    if isinstance(valid_from, str):
+        try:
+            starts = _parse_iso(valid_from)
+        except Exception as exc:
+            raise OB3VerificationError(
+                "status list %s has an invalid validFrom %r: %s"
+                % (list_url, valid_from, exc)) from exc
+        if starts > now:
+            raise OB3VerificationError(
+                "status list %s is not yet valid (validFrom %s)"
+                % (list_url, valid_from))
+
+
+def _verify_list_proof(raw: bytes, doc: dict[str, Any], list_url: str,
+                       badge_issuer: Optional[str],
+                       download: Callable[[str], bytes],
+                       list_pubkey_pem: Optional[Union[str, bytes]]) -> None:
+    """Verify a status list credential's own JWT-VC proof and bind its issuer.
+
+    Two checks: (1) the list's ``issuer`` must equal the badge's issuer — a
+    list published by anyone else is not authoritative for this badge; (2) the
+    list's JWT signature must verify under the issuer's key (``list_pubkey_pem``
+    if given, else resolved from a ``did:web``/``did:key`` issuer). Fails closed.
+    """
+    from .verifier import OB3Verifier
+
+    list_issuer = _issuer_id(doc.get("issuer"))
+    if badge_issuer is not None and list_issuer != badge_issuer:
+        raise OB3VerificationError(
+            "status list %s issuer %r does not match the badge issuer %r"
+            % (list_url, list_issuer, badge_issuer))
+
+    text = raw.decode('utf-8').strip()
+    if text.count('.') != 2 or text.startswith('{'):
+        raise OB3VerificationError(
+            "status list %s is not a signed JWT-VC, so its proof cannot be "
+            "verified (verify_list=True requires a signed list)" % list_url)
+
+    if list_pubkey_pem is not None:
+        verifier = OB3Verifier(pubkey_pem=list_pubkey_pem)
+    elif isinstance(list_issuer, str) and list_issuer.startswith('did:'):
+        verifier = OB3Verifier.for_issuer_did(list_issuer, download=download)
+    else:
+        raise OB3VerificationError(
+            "cannot verify status list %s: its issuer %r is not a DID — pass "
+            "list_pubkey_pem" % (list_url, list_issuer))
+
+    # _decode_payload verifies the signature with the algorithm pinned to the
+    # key type; it does not enforce OB3 credential *types* (this is a
+    # BitstringStatusListCredential, not an OpenBadgeCredential), which is
+    # exactly what we want here. The issuer binding above is the trust anchor.
+    try:
+        verifier._decode_payload(text)
+    except OB3VerificationError as exc:
+        raise OB3VerificationError(
+            "status list %s proof is invalid: %s" % (list_url, exc)) from exc
+
+
 def _b64url_decode(value: str) -> bytes:
     value += '=' * (-len(value) % 4)
     return base64.urlsafe_b64decode(value)

{openbadgeslib-3.7.0 → openbadgeslib-3.8.0}/openbadgeslib/ob3/status_list.py

@@ -77,18 +77,25 @@ def encode_bitstring(set_indices: Iterable[int],
 def build_status_list_credential(issuer_id: str, url: str, purpose: str,
                                  set_indices: Iterable[int],
                                  size_bits: int = DEFAULT_SIZE_BITS,
-                                 issued: Optional[datetime] = None) -> dict[str, Any]:
+                                 issued: Optional[datetime] = None,
+                                 valid_until: Optional[datetime] = None
+                                 ) -> dict[str, Any]:
     """Build an (unsigned) BitstringStatusListCredential document.
 
     *url* is the public HTTPS URL the list will be served from — it becomes
     the credential ``id`` and must match the ``statusListCredential`` of the
     entries that point at it (see :func:`status_entry`). ``statusSize`` is
     omitted: entries are single-bit, the only size the verifier accepts.
+
+    *valid_until*, when given, adds a ``validUntil`` bound: a reader
+    (ob3.status) then rejects a stale copy served past that instant, so a
+    replayed old ``revocation.jwt`` cannot silently resurrect a revoked badge.
+    The issuer must republish the list before it lapses (see the wiki).
     """
     if purpose not in STATUS_PURPOSES:
         raise ValueError("statusPurpose must be one of %r, got %r"
                          % (STATUS_PURPOSES, purpose))
-    return {
+    vc: dict[str, Any] = {
         "@context": [_VC2_CONTEXT],
         "id": url,
         "type": ["VerifiableCredential", "BitstringStatusListCredential"],
@@ -102,6 +109,9 @@ def build_status_list_credential(issuer_id: str, url: str, purpose: str,
             "encodedList": encode_bitstring(set_indices, size_bits),
         },
     }
+    if valid_until is not None:
+        vc["validUntil"] = _iso(valid_until)
+    return vc
 
 
 def sign_status_list_credential(vc: dict[str, Any], privkey_pem: Any,

{openbadgeslib-3.7.0 → openbadgeslib-3.8.0}/openbadgeslib/ob3/verifier.py

@@ -245,17 +245,26 @@ class OB3Verifier:
 
         return credential
 
-    def check_status(self, credential: OpenBadgeCredential) -> None:
+    def check_status(self, credential: OpenBadgeCredential,
+                     *, verify_list: bool = False) -> None:
         """Check the credential's ``credentialStatus`` (revocation) over the
         network, raising :class:`OB3VerificationError` if it is revoked/
         suspended or if the status cannot be determined (fail-closed). A
-        credential carrying no credentialStatus is a no-op.
+        credential carrying no credentialStatus is a no-op. The status list's
+        validFrom/validUntil window is always enforced.
+
+        Pass ``verify_list=True`` to also verify each status list credential's
+        own JWT-VC proof and bind its issuer to the badge's — this verifier's
+        key is reused, since ``openbadges-publish`` signs the list with the same
+        badge key that signed the credential.
 
         Imported lazily so the (network-touching) status module is only pulled
         in when a caller actually opts into status checking.
         """
         from .status import check_credential_status
-        check_credential_status(credential)
+        check_credential_status(
+            credential, verify_list=verify_list,
+            list_pubkey_pem=self.pubkey_pem if verify_list else None)
 
     def _key_for_token(
             self, header: dict[str, Any]) -> tuple[Union[str, bytes], list[str]]:

{openbadgeslib-3.7.0 → openbadgeslib-3.8.0}/openbadgeslib/openbadges_publish.py

@@ -322,7 +322,7 @@ def _publish_ob3(args: argparse.Namespace,
     every status change is the normal workflow, and the managed files are
     replaced atomically.
     """
-    from datetime import datetime, timezone
+    from datetime import datetime, timedelta, timezone
     from .confparser import ob3_issuer_id, ob3_status_config
     from .errors import LibOpenBadgesException, StatusError
     from .keys import alg_for_key_type, detect_key_type, public_jwk_from_pem
@@ -481,6 +481,11 @@ def _publish_ob3(args: argparse.Namespace,
                 continue
             algorithm = alg_for_key_type(detect_key_type(priv_pem))
 
+            valid_until = None
+            if status_conf.validity_days is not None:
+                valid_until = (datetime.now(tz=timezone.utc)
+                               + timedelta(days=status_conf.validity_days))
+
             badge_dir = os.path.join(args.output, name)
             os.makedirs(badge_dir, exist_ok=True)
             for purpose in status_conf.purposes:
@@ -488,7 +493,7 @@ def _publish_ob3(args: argparse.Namespace,
                     else registry.suspended_indices()
                 vc = build_status_list_credential(
                     issuer_id, status_conf.list_urls[purpose], purpose,
-                    indices, registry.size_bits)
+                    indices, registry.size_bits, valid_until=valid_until)
                 token = sign_status_list_credential(vc, priv_pem, algorithm)
                 _write_atomic(os.path.join(badge_dir, purpose + '.jwt'), token)
                 files_written.append(os.path.join(name, purpose + '.jwt'))

{openbadgeslib-3.7.0 → openbadgeslib-3.8.0}/openbadgeslib/util.py

@@ -21,7 +21,7 @@
         License along with this library.
 """
 
-__version__ = '3.7.0'
+__version__ = '3.8.0'
 
 import contextlib
 import hashlib

{openbadgeslib-3.7.0 → openbadgeslib-3.8.0/openbadgeslib.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openbadgeslib
-Version: 3.7.0
+Version: 3.8.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.7.0 → openbadgeslib-3.8.0}/tests/test_ob3_publish_cli.py

@@ -585,3 +585,58 @@ class TestPublishJson:
         with patch.object(sys, 'argv', argv):
             with pytest.raises(SystemExit, match='-V 3'):
                 openbadges_publish.main()
+
+
+# ── #164: status list validUntil + opt-in proof verification ─────────────────
+
+class TestPublishValidUntil:
+    def test_validuntil_emitted_when_configured(self, tmp_path):
+        import jwt as pyjwt
+        cfg = _write_config(tmp_path, status_lists='revocation')
+        with cfg.open('a') as f:
+            f.write('status_validity_days = 7\n')
+        _sign(tmp_path, cfg)
+        pub = _publish(tmp_path, cfg)
+        token = (pub / 'badge_1' / 'revocation.jwt').read_text()
+        payload = pyjwt.decode(token, options={'verify_signature': False})
+        assert 'validUntil' in payload and 'validFrom' in payload
+
+    def test_no_validuntil_by_default(self, tmp_path):
+        import jwt as pyjwt
+        cfg = _write_config(tmp_path, status_lists='revocation')
+        _sign(tmp_path, cfg)
+        pub = _publish(tmp_path, cfg)
+        token = (pub / 'badge_1' / 'revocation.jwt').read_text()
+        payload = pyjwt.decode(token, options={'verify_signature': False})
+        assert 'validUntil' not in payload
+
+    def test_invalid_validity_days_exits_cleanly(self, tmp_path, capsys):
+        cfg = _write_config(tmp_path, status_lists='revocation')
+        with cfg.open('a') as f:
+            f.write('status_validity_days = soon\n')
+        with pytest.raises(SystemExit):
+            _publish(tmp_path, cfg)
+        assert 'status_validity_days' in capsys.readouterr().out
+
+
+class TestPublishVerifyList:
+    def test_verify_list_proof_end_to_end(self, tmp_path, rsa_pub_pem):
+        # The published list is signed with the badge key and its issuer is the
+        # badge issuer, so verify_list=True (with that key) passes.
+        from openbadgeslib.ob3 import check_credential_status
+        cfg = _write_config(tmp_path, status_lists='revocation')
+        badge_file = _sign(tmp_path, cfg)
+        pub = _publish(tmp_path, cfg)
+        credential = _credential_from(badge_file, rsa_pub_pem)
+        check_credential_status(credential, download=_served_from(pub),
+                                verify_list=True, list_pubkey_pem=rsa_pub_pem)
+
+    def test_verify_list_wrong_key_fails(self, tmp_path, rsa_pub_pem, ecc_pub_pem):
+        from openbadgeslib.ob3 import check_credential_status, OB3VerificationError
+        cfg = _write_config(tmp_path, status_lists='revocation')
+        badge_file = _sign(tmp_path, cfg)
+        pub = _publish(tmp_path, cfg)
+        credential = _credential_from(badge_file, rsa_pub_pem)
+        with pytest.raises(OB3VerificationError, match='proof is invalid'):
+            check_credential_status(credential, download=_served_from(pub),
+                                    verify_list=True, list_pubkey_pem=ecc_pub_pem)

{openbadgeslib-3.7.0 → openbadgeslib-3.8.0}/tests/test_ob3_status.py

@@ -249,3 +249,126 @@ class TestVerifyWithStatus:
         monkeypatch.setattr(status_mod, 'download_file', _fail)
         token = self._sign(ob3_rsa_signer, [_status_entry(94)])
         assert ob3_rsa_verifier.verify(token) is not None
+
+
+# ── #164: validFrom/validUntil window + opt-in proof verification ────────────
+
+def _iso(dt):
+    return dt.isoformat(timespec='seconds').replace('+00:00', 'Z')
+
+
+def _served_token(token):
+    data = token.encode('utf-8') if isinstance(token, str) else token
+
+    def _dl(url):
+        assert url == LIST_URL
+        return data
+    return _dl
+
+
+class TestStatusListWindow:
+    def _doc(self, **extra):
+        doc = _status_list_doc([])           # empty list: no bit set
+        doc['issuer'] = 'https://issuer.example'
+        doc.update(extra)
+        return doc
+
+    def test_no_validuntil_never_expires(self):
+        # Backward compatible: a list without validUntil is accepted.
+        check_credential_status(_credential([_status_entry(5)]),
+                                download=_downloader(self._doc()))
+
+    def test_future_validuntil_accepted(self):
+        from datetime import datetime, timedelta, timezone
+        doc = self._doc(validUntil=_iso(datetime.now(timezone.utc)
+                                        + timedelta(days=7)))
+        check_credential_status(_credential([_status_entry(5)]),
+                                download=_downloader(doc))
+
+    def test_expired_validuntil_rejected(self):
+        from datetime import datetime, timedelta, timezone
+        doc = self._doc(validUntil=_iso(datetime.now(timezone.utc)
+                                        - timedelta(days=1)))
+        with pytest.raises(OB3VerificationError, match='expired'):
+            check_credential_status(_credential([_status_entry(5)]),
+                                    download=_downloader(doc))
+
+    def test_not_yet_valid_validfrom_rejected(self):
+        from datetime import datetime, timedelta, timezone
+        doc = self._doc(validFrom=_iso(datetime.now(timezone.utc)
+                                       + timedelta(days=1)))
+        with pytest.raises(OB3VerificationError, match='not yet valid'):
+            check_credential_status(_credential([_status_entry(5)]),
+                                    download=_downloader(doc))
+
+    def test_malformed_validuntil_rejected(self):
+        with pytest.raises(OB3VerificationError, match='invalid validUntil'):
+            check_credential_status(
+                _credential([_status_entry(5)]),
+                download=_downloader(self._doc(validUntil='not-a-date')))
+
+
+class TestVerifyListProof:
+    def _signed(self, priv_pem, issuer_id, indices=()):
+        from openbadgeslib.ob3.status_list import (
+            build_status_list_credential, sign_status_list_credential)
+        vc = build_status_list_credential(issuer_id, LIST_URL, 'revocation',
+                                          indices)
+        return sign_status_list_credential(vc, priv_pem, 'EdDSA')
+
+    def _cred(self, issuer_id, entries):
+        from openbadgeslib.ob3 import Achievement, Issuer
+        return OpenBadgeCredential(
+            id='urn:uuid:00000000-0000-0000-0000-0000000000ab',
+            issuer=Issuer(id=issuer_id, name='I'),
+            recipient_id='mailto:r@example.com',
+            achievement=Achievement(id='https://a.example/1', name='A',
+                                    description='d', criteria_narrative='c'),
+            credential_status=entries)
+
+    def test_verify_with_pubkey_passes(self, ed25519_keypair):
+        priv, pub = ed25519_keypair
+        token = self._signed(priv, 'https://issuer.example')
+        check_credential_status(
+            self._cred('https://issuer.example', [_status_entry(5)]),
+            download=_served_token(token), verify_list=True, list_pubkey_pem=pub)
+
+    def test_issuer_mismatch_fails(self, ed25519_keypair):
+        priv, pub = ed25519_keypair
+        token = self._signed(priv, 'https://attacker.example')
+        with pytest.raises(OB3VerificationError,
+                           match='does not match the badge issuer'):
+            check_credential_status(
+                self._cred('https://issuer.example', [_status_entry(5)]),
+                download=_served_token(token), verify_list=True,
+                list_pubkey_pem=pub)
+
+    def test_bad_signature_fails(self, ed25519_keypair):
+        from openbadgeslib.keys import KeyEd25519
+        priv, _pub = ed25519_keypair
+        _priv2, wrong_pub = KeyEd25519().generate_keypair()
+        token = self._signed(priv, 'https://issuer.example')
+        with pytest.raises(OB3VerificationError, match='proof is invalid'):
+            check_credential_status(
+                self._cred('https://issuer.example', [_status_entry(5)]),
+                download=_served_token(token), verify_list=True,
+                list_pubkey_pem=wrong_pub)
+
+    def test_verify_via_did_key_resolution(self, ed25519_keypair):
+        # No list_pubkey_pem: the issuer DID (did:key, offline) is resolved.
+        from openbadgeslib.ob3.did import did_key_from_pem
+        priv, pub = ed25519_keypair
+        did = did_key_from_pem(pub)
+        token = self._signed(priv, did)
+        check_credential_status(self._cred(did, [_status_entry(5)]),
+                                download=_served_token(token), verify_list=True)
+
+    def test_unsigned_list_rejected_when_verify_requested(self):
+        # verify_list=True on a plain JSON (unsigned) list fails closed.
+        doc = _status_list_doc([])
+        doc['issuer'] = 'https://issuer.example'
+        with pytest.raises(OB3VerificationError, match='not a signed JWT-VC'):
+            check_credential_status(
+                self._cred('https://issuer.example', [_status_entry(5)]),
+                download=_downloader(doc), verify_list=True,
+                list_pubkey_pem=b'unused')