openbadgeslib 3.7.0__tar.gz → 3.9.0__tar.gz

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

@@ -4,6 +4,51 @@ OpenBadgesLib - Changelog
 Newest first. Dates are ISO 8601 (YYYY-MM-DD).
 
 
+* v3.9.0 - 2026-07-08
+
+  - feat(ob3): broaden the credential data model toward the OB 3.0 spec — the
+    gap versus the spec was the model, not the crypto. New `Evidence` (the full
+    `evidence` array: narrative, name, description, genre, audience — beyond the
+    single `evidence_url`) and `Alignment` (competency-framework mappings, what
+    LMSes read to map a badge to a competency) dataclasses, plus
+    `achievementType`, `creditsAvailable` and an `alignments` list on
+    `Achievement`. All are validated in the house style (dataclasses + mypy, no
+    Pydantic), parse from a verified credential, round-trip through `to_vc`, and
+    still satisfy the offline conformance schema. (Refs #162 —
+    Result/ResultDescription, IdentityObject and creditsEarned follow.)
+
+  - feat(ob3): support OpenBadges 3.0 `endorsementJwt` (spec errata v1.6, added
+    to context 3.0.3). Third-party endorsement JWTs were passing through as
+    opaque, unmapped fields; the credential model now exposes them at the three
+    levels the spec allows — `credential.endorsement_jwts`,
+    `issuer.endorsement_jwts`, `achievement.endorsement_jwts`, gathered by
+    `credential.all_endorsement_jwts()` — and round-trips them through `to_vc`.
+    A new `ob3.verify_endorsement_jwt(token, download=None,
+    endorser_pubkey_pem=None)` verifies an EndorsementCredential JWT under the
+    *endorser's* key (resolved from its own issuer did:web/did:key, or an
+    explicit key when the endorser is not a DID), checking the
+    EndorsementCredential type and its validFrom/validUntil window.
+    `openbadges-verifier --json` now reports the `endorsements` count. (#161)
+
+
+* 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.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openbadgeslib
-Version: 3.7.0
+Version: 3.9.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.9.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.9.0}/openbadgeslib/ob3/__init__.py

@@ -20,9 +20,11 @@
         License along with this library.
 """
 
-from .credential import Achievement, Issuer, OpenBadgeCredential
+from .credential import (Achievement, Alignment, Evidence, Issuer,
+                         OpenBadgeCredential)
 from .signer import OB3Signer
-from .verifier import OB3VerificationError, OB3Verifier
+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
@@ -34,6 +36,8 @@ from .did import (build_did_document, did_key_from_pem, did_web_from_url,
 
 __all__ = [
     'Achievement',
+    'Alignment',
+    'Evidence',
     'Issuer',
     'OpenBadgeCredential',
     'OB3LdpSigner',
@@ -55,4 +59,5 @@ __all__ = [
     'resolve_verification_method',
     'sign_status_list_credential',
     'status_entry',
+    'verify_endorsement_jwt',
 ]

{openbadgeslib-3.7.0 → openbadgeslib-3.9.0}/openbadgeslib/ob3/credential.py

@@ -86,6 +86,10 @@ class Issuer:
     url: Optional[str] = None
     email: Optional[str] = None
     image_url: Optional[str] = None
+    # Compact EndorsementCredential JWTs vouching for this profile (OB 3.0
+    # `endorsementJwt`, added to context 3.0.3 by errata v1.6). Verifiable with
+    # verify_endorsement_jwt; the endorser is a third party, not this issuer.
+    endorsement_jwts: List[str] = field(default_factory=list)
 
     def to_dict(self) -> dict[str, Any]:
         d: dict[str, Any] = {"id": self.id, "type": ["Profile"], "name": self.name}
@@ -95,9 +99,82 @@ class Issuer:
             d["email"] = self.email
         if self.image_url:
             d["image"] = {"id": self.image_url, "type": "Image"}
+        if self.endorsement_jwts:
+            d["endorsementJwt"] = list(self.endorsement_jwts)
         return d
 
 
+@dataclass
+class Alignment:
+    """Alignment of an achievement to a node in an educational framework
+    (OB 3.0 `alignment`) — what an LMS reads to map a badge to a competency."""
+
+    target_name: str
+    target_url: str
+    target_framework: Optional[str] = None
+    target_code: Optional[str] = None
+    target_description: Optional[str] = None
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "type": ["Alignment"],
+            "targetName": self.target_name,
+            "targetUrl": self.target_url,
+        }
+        if self.target_framework:
+            d["targetFramework"] = self.target_framework
+        if self.target_code:
+            d["targetCode"] = self.target_code
+        if self.target_description:
+            d["targetDescription"] = self.target_description
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Alignment":
+        return cls(
+            target_name=_require(data, "targetName", "alignment"),
+            target_url=_require(data, "targetUrl", "alignment"),
+            target_framework=data.get("targetFramework"),
+            target_code=data.get("targetCode"),
+            target_description=data.get("targetDescription"),
+        )
+
+
+@dataclass
+class Evidence:
+    """A piece of evidence supporting a credential (OB 3.0 `evidence`), richer
+    than a bare URL: an optional narrative and descriptive metadata."""
+
+    id: Optional[str] = None          # dereferenceable URL of the evidence
+    narrative: Optional[str] = None
+    name: Optional[str] = None
+    description: Optional[str] = None
+    genre: Optional[str] = None
+    audience: Optional[str] = None
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {"type": ["Evidence"]}
+        if self.id:
+            d["id"] = self.id
+        for key, value in (("narrative", self.narrative), ("name", self.name),
+                           ("description", self.description),
+                           ("genre", self.genre), ("audience", self.audience)):
+            if value:
+                d[key] = value
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Evidence":
+        return cls(
+            id=data.get("id"),
+            narrative=data.get("narrative"),
+            name=data.get("name"),
+            description=data.get("description"),
+            genre=data.get("genre"),
+            audience=data.get("audience"),
+        )
+
+
 @dataclass
 class Achievement:
     """A badge class / achievement definition."""
@@ -108,6 +185,16 @@ class Achievement:
     criteria_narrative: str
     image_url: Optional[str] = None
     tags: List[str] = field(default_factory=list)
+    # Compact EndorsementCredential JWTs vouching for this achievement
+    # (OB 3.0 `endorsementJwt`). See Issuer.endorsement_jwts.
+    endorsement_jwts: List[str] = field(default_factory=list)
+    # Kind of achievement (OB 3.0 `achievementType`, e.g. 'Badge',
+    # 'Certificate', 'Competency', …) and any academic credit it carries.
+    achievement_type: Optional[str] = None
+    credits_available: Optional[float] = None
+    # Framework alignments (OB 3.0 `alignment`): the competency mappings LMSes
+    # consume. Empty when the achievement declares none.
+    alignments: List[Alignment] = field(default_factory=list)
 
     def to_dict(self) -> dict[str, Any]:
         d: dict[str, Any] = {
@@ -117,10 +204,18 @@ class Achievement:
             "description": self.description,
             "criteria": {"narrative": self.criteria_narrative},
         }
+        if self.achievement_type:
+            d["achievementType"] = self.achievement_type
+        if self.credits_available is not None:
+            d["creditsAvailable"] = self.credits_available
         if self.image_url:
             d["image"] = {"id": self.image_url, "type": "Image"}
         if self.tags:
             d["tag"] = self.tags
+        if self.alignments:
+            d["alignment"] = [a.to_dict() for a in self.alignments]
+        if self.endorsement_jwts:
+            d["endorsementJwt"] = list(self.endorsement_jwts)
         return d
 
 
@@ -137,11 +232,20 @@ class OpenBadgeCredential:
     name: Optional[str] = None  # defaults to achievement.name
     issuance_date: Optional[datetime] = None   # defaults to now (UTC)
     expiration_date: Optional[datetime] = None
+    # Backward-compatible single-URL evidence convenience. For the full OB 3.0
+    # evidence list (narrative, name, …) use `evidence`; when both are set the
+    # list wins. Parsing populates both (evidence_url = evidence[0].id).
     evidence_url: Optional[str] = None
+    evidence: List["Evidence"] = field(default_factory=list)
     # 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[str, Any]] = field(default_factory=list)
+    # Compact EndorsementCredential JWTs vouching for the credential itself
+    # (top-level OB 3.0 `endorsementJwt`). Endorsements attached to the issuer
+    # or the achievement live on those objects; all_endorsement_jwts() gathers
+    # the three. Empty when the credential carries none.
+    endorsement_jwts: List[str] = 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 —
@@ -195,14 +299,27 @@ class OpenBadgeCredential:
             vc["credentialSubject"]["id"] = self.recipient_id
         if self.expiration_date:
             vc["validUntil"] = _iso(self.expiration_date)
-        if self.evidence_url:
-            vc["evidence"] = [{"id": self.evidence_url, "type": ["Evidence"]}]
+        evidence_items = self.evidence or (
+            [Evidence(id=self.evidence_url)] if self.evidence_url else [])
+        if evidence_items:
+            vc["evidence"] = [e.to_dict() for e in evidence_items]
         if self.credential_status:
             vc["credentialStatus"] = (
                 self.credential_status[0] if len(self.credential_status) == 1
                 else self.credential_status)
+        if self.endorsement_jwts:
+            vc["endorsementJwt"] = list(self.endorsement_jwts)
         return vc
 
+    def all_endorsement_jwts(self) -> List[str]:
+        """Every compact EndorsementCredential JWT attached to this credential,
+        gathered from the credential itself and from its issuer and achievement
+        (OB 3.0 allows `endorsementJwt` at all three levels). Verify each with
+        :func:`openbadgeslib.ob3.verify_endorsement_jwt`."""
+        return [*self.endorsement_jwts,
+                *self.issuer.endorsement_jwts,
+                *self.achievement.endorsement_jwts]
+
     def to_jwt_payload(self) -> dict[str, Any]:
         """Return the JWT payload for a JWT-VC signed credential.
 
@@ -276,6 +393,7 @@ class OpenBadgeCredential:
                 url=issuer_data.get("url"),
                 email=issuer_data.get("email"),
                 image_url=_as_dict_or_empty(issuer_data.get("image")).get("id"),
+                endorsement_jwts=_string_list(issuer_data.get("endorsementJwt")),
             )
 
         # credentialSubject may be a single object or a (non-empty) array.
@@ -290,6 +408,10 @@ class OpenBadgeCredential:
                             "vc.credentialSubject.achievement")
         criteria = _as_dict_or_empty(ach_data.get("criteria"))
         image = _as_dict_or_empty(ach_data.get("image"))
+        alignment_raw = ach_data.get("alignment")
+        alignments = [Alignment.from_dict(a) for a in alignment_raw
+                      if isinstance(a, dict)] \
+            if isinstance(alignment_raw, list) else []
         achievement = Achievement(
             id=_require(ach_data, "id", "vc.credentialSubject.achievement"),
             name=_require(ach_data, "name", "vc.credentialSubject.achievement"),
@@ -297,6 +419,10 @@ class OpenBadgeCredential:
             criteria_narrative=criteria.get("narrative", ""),
             image_url=image.get("id"),
             tags=ach_data.get("tag", []),
+            endorsement_jwts=_string_list(ach_data.get("endorsementJwt")),
+            achievement_type=ach_data.get("achievementType"),
+            credits_available=_float_or_none(ach_data.get("creditsAvailable")),
+            alignments=alignments,
         )
 
         # Accept both VC 2.0 (validFrom/validUntil) and VC 1.1
@@ -306,10 +432,16 @@ class OpenBadgeCredential:
         expires = vc.get("validUntil") or vc.get("expirationDate")
         expiration_date = _parse_date(expires, "vc.validUntil") if expires else None
 
-        evidence_url = None
-        evidence = vc.get("evidence")
-        if isinstance(evidence, list) and evidence and isinstance(evidence[0], dict):
-            evidence_url = evidence[0].get("id")
+        evidence_raw = vc.get("evidence")
+        if isinstance(evidence_raw, list):
+            evidence_list = [Evidence.from_dict(e) for e in evidence_raw
+                             if isinstance(e, dict)]
+        elif isinstance(evidence_raw, dict):
+            evidence_list = [Evidence.from_dict(evidence_raw)]
+        else:
+            evidence_list = []
+        # Backward-compatible convenience: the first evidence's URL.
+        evidence_url = evidence_list[0].id if evidence_list else None
 
         # credentialStatus may be a single object or an array; keep only object
         # entries so the status checker can rely on .get() without crashing.
@@ -343,7 +475,9 @@ class OpenBadgeCredential:
             issuance_date=issuance_date,
             expiration_date=expiration_date,
             evidence_url=evidence_url,
+            evidence=evidence_list,
             credential_status=credential_status,
+            endorsement_jwts=_string_list(vc.get("endorsementJwt")),
         )
         # 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
@@ -364,6 +498,27 @@ def _as_dict_or_empty(value: Any) -> dict[str, Any]:
     return value if isinstance(value, dict) else {}
 
 
+def _float_or_none(value: Any) -> Optional[float]:
+    """Coerce a JSON number to float, else None (for optional numeric fields
+    like creditsAvailable). A bool is not a number here."""
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, (int, float)):
+        return float(value)
+    return None
+
+
+def _string_list(value: Any) -> List[str]:
+    """Return the string members of *value* when it is a list, else an empty
+    list. `endorsementJwt` is an array of compact JWT strings; a single string
+    is also accepted (tolerant read of a producer that omitted the array)."""
+    if isinstance(value, str):
+        return [value]
+    if isinstance(value, list):
+        return [item for item in value if isinstance(item, str)]
+    return []
+
+
 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

{openbadgeslib-3.7.0 → openbadgeslib-3.9.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.9.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,