openbadgeslib 3.8.0__tar.gz → 3.9.0__tar.gz

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

@@ -4,6 +4,33 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openbadgeslib
-Version: 3.8.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.8.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.8.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.8.0 → openbadgeslib-3.9.0}/openbadgeslib/ob3/verifier.py

@@ -26,7 +26,7 @@ from typing import Any, Optional, Union
 import jwt
 import jwt.exceptions
 
-from .credential import OpenBadgeCredential
+from .credential import OpenBadgeCredential, _parse_iso
 from ..errors import ErrorParsingFile, UnknownKeyType, LibOpenBadgesException
 from ..keys import KeyType, detect_key_type, key_to_pem
 from ..util import normalize_recipient_id, recipient_ids_match
@@ -382,6 +382,19 @@ class OB3Verifier:
 
     # ── token extraction ───────────────────────────────────────────────────────
 
+    @staticmethod
+    def _decode_unverified(token: str) -> dict[str, Any]:
+        """Decode a JWT payload without checking the signature (to read the
+        issuer before the key is resolved). Raises OB3VerificationError on a
+        malformed token."""
+        try:
+            payload = jwt.decode(token, options={"verify_signature": False})
+        except jwt.exceptions.DecodeError as exc:
+            raise OB3VerificationError("malformed JWT: %s" % exc) from exc
+        if not isinstance(payload, dict):
+            raise OB3VerificationError("JWT payload is not an object")
+        return payload
+
     @staticmethod
     def extract_token_from_svg(svg_bytes: bytes) -> str:
         """Extract the embedded credential from a baked SVG badge.
@@ -418,3 +431,88 @@ class OB3Verifier:
         if token is None:
             raise OB3VerificationError("No openbadgecredential iTXt chunk found in PNG")
         return token
+
+
+# ── endorsements (OB 3.0 endorsementJwt, errata v1.6) ────────────────────────
+
+def verify_endorsement_jwt(token: str, download: Any = None,
+                           endorser_pubkey_pem: Any = None) -> dict[str, Any]:
+    """Verify a compact EndorsementCredential JWT (OB 3.0 ``endorsementJwt``).
+
+    An endorsement is a Verifiable Credential a **third party** (the endorser,
+    not the badge issuer) signs to vouch for an achievement, issuer or
+    credential. This verifies its signature under the endorser's key — resolved
+    from the endorsement's own issuer DID (``did:web``/``did:key``), or
+    ``endorser_pubkey_pem`` when the endorser is not a DID — checks it is an
+    ``EndorsementCredential`` whose validFrom/validUntil window is current, and
+    returns ``{id, issuer, endorses, comment}``.
+
+    Raises :class:`OB3VerificationError` on any failure (malformed token, bad
+    signature, wrong type, expired, or an endorser that is neither a DID nor
+    covered by ``endorser_pubkey_pem``). The verifier machinery is reused, but
+    OB3Verifier.verify() cannot: an EndorsementCredential is not an
+    OpenBadgeCredential, so its type check would reject it.
+    """
+    if not isinstance(token, str) or token.lstrip().startswith('{'):
+        raise OB3VerificationError(
+            "endorsementJwt must be a compact JWT string")
+
+    unverified = OB3Verifier._decode_unverified(token)
+    endorser = _claim_object_id(unverified.get("issuer")) or unverified.get("iss")
+
+    if endorser_pubkey_pem is not None:
+        verifier = OB3Verifier(pubkey_pem=endorser_pubkey_pem)
+    elif isinstance(endorser, str) and endorser.startswith("did:"):
+        verifier = OB3Verifier.for_issuer_did(endorser, download=download)
+    else:
+        raise OB3VerificationError(
+            "cannot verify endorsement: its issuer %r is not a DID — pass "
+            "endorser_pubkey_pem" % (endorser,))
+
+    payload = verifier._decode_payload(token)     # signature + algorithm pin
+
+    types = payload.get("type", [])
+    if isinstance(types, str):
+        types = [types]
+    if "EndorsementCredential" not in (types if isinstance(types, list) else []):
+        raise OB3VerificationError(
+            "not an EndorsementCredential (type=%r)" % (payload.get("type"),))
+
+    _check_endorsement_window(payload)
+
+    subject = payload.get("credentialSubject")
+    if isinstance(subject, list):
+        subject = subject[0] if subject else {}
+    if not isinstance(subject, dict):
+        subject = {}
+    return {
+        "id": payload.get("id"),
+        "issuer": endorser,
+        "endorses": subject.get("id"),
+        "comment": subject.get("endorsementComment"),
+    }
+
+
+def _check_endorsement_window(vc: dict[str, Any]) -> None:
+    """Reject an endorsement whose validFrom/validUntil window is not current
+    (the JWT exp is also checked in _decode_payload, but a producer may set a
+    vc-level bound without the registered claim)."""
+    now = datetime.now(timezone.utc)
+    valid_until = vc.get("validUntil")
+    if isinstance(valid_until, str):
+        try:
+            expires = _parse_iso(valid_until)
+        except Exception:
+            expires = None
+        if expires is not None and expires < now:
+            raise OB3VerificationError(
+                "endorsement expired (validUntil %s)" % valid_until)
+    valid_from = vc.get("validFrom")
+    if isinstance(valid_from, str):
+        try:
+            starts = _parse_iso(valid_from)
+        except Exception:
+            starts = None
+        if starts is not None and starts > now:
+            raise OB3VerificationError(
+                "endorsement is not yet valid (validFrom %s)" % valid_from)

{openbadgeslib-3.8.0 → openbadgeslib-3.9.0}/openbadgeslib/openbadges_verifier.py

@@ -435,6 +435,11 @@ def _verify_ob3(args: argparse.Namespace) -> None:
     result['expires'] = (credential.expiration_date.isoformat()
                          if credential.expiration_date else None)
     result['evidence'] = credential.evidence_url
+    # Surface how many EndorsementCredential JWTs the credential carries (on
+    # itself, its issuer or its achievement) so they are no longer invisible.
+    # They are third-party VCs; verify each with ob3.verify_endorsement_jwt.
+    endorsement_jwts = credential.all_endorsement_jwts()
+    result['endorsements'] = len(endorsement_jwts)
 
     if args.show and not args.json:
         print('[+] Credential issuer  : %s' % credential.issuer.name)
@@ -445,6 +450,9 @@ def _verify_ob3(args: argparse.Namespace) -> None:
             print('[+] Expires            : %s' % credential.expiration_date.isoformat())
         if credential.evidence_url:
             print('[+] Evidence           : %s' % credential.evidence_url)
+        if endorsement_jwts:
+            print('[+] Endorsements       : %d (verify with '
+                  'ob3.verify_endorsement_jwt)' % len(endorsement_jwts))
 
     if result['trusted']:
         result['reason'] = None

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openbadgeslib
-Version: 3.8.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.8.0 → openbadgeslib-3.9.0}/openbadgeslib.egg-info/SOURCES.txt

@@ -83,6 +83,7 @@ tests/test_ob3_contexts.py
 tests/test_ob3_credential.py
 tests/test_ob3_did.py
 tests/test_ob3_did_doc.py
+tests/test_ob3_endorsement.py
 tests/test_ob3_eudi_sd_jwt.py
 tests/test_ob3_ldp.py
 tests/test_ob3_ldp_cli.py

{openbadgeslib-3.8.0 → openbadgeslib-3.9.0}/tests/test_ob3_credential.py

@@ -330,3 +330,121 @@ class TestNaiveDatetimeAssumedUtc:
         cred = _make_credential(expiration_date=datetime(2030, 6, 1, 0, 0, 0))
         assert cred.expiration_date.tzinfo is not None
         assert cred.to_vc()['validUntil'] == '2030-06-01T00:00:00Z'
+
+
+# ── #162: broadened model — Evidence, Alignment, achievementType, credits ────
+
+from openbadgeslib.ob3.credential import Alignment, Evidence  # noqa: E402
+
+
+class TestBroadenedModel:
+    def _credential(self, **achievement_kw):
+        return OpenBadgeCredential(
+            issuer=Issuer(id='https://issuer.example', name='I'),
+            recipient_id='mailto:r@example.com',
+            achievement=Achievement(id='https://a.example/1', name='A',
+                                    description='d', criteria_narrative='c',
+                                    **achievement_kw))
+
+    def test_alignment_round_trip(self):
+        cred = self._credential(alignments=[
+            Alignment(target_name='Competency X',
+                      target_url='https://framework.example/x',
+                      target_framework='EU Framework', target_code='X.1'),
+        ])
+        vc = cred.to_vc()
+        assert vc['credentialSubject']['achievement']['alignment'] == [{
+            'type': ['Alignment'],
+            'targetName': 'Competency X',
+            'targetUrl': 'https://framework.example/x',
+            'targetFramework': 'EU Framework',
+            'targetCode': 'X.1',
+        }]
+        again = OpenBadgeCredential.from_vc_document(vc)
+        assert again.achievement.alignments[0].target_name == 'Competency X'
+        assert again.achievement.alignments[0].target_code == 'X.1'
+
+    def test_achievement_type_and_credits_round_trip(self):
+        cred = self._credential(achievement_type='Competency',
+                                credits_available=3.5)
+        ach = cred.to_vc()['credentialSubject']['achievement']
+        assert ach['achievementType'] == 'Competency'
+        assert ach['creditsAvailable'] == 3.5
+        again = OpenBadgeCredential.from_vc_document(cred.to_vc())
+        assert again.achievement.achievement_type == 'Competency'
+        assert again.achievement.credits_available == 3.5
+
+    def test_evidence_list_round_trip(self):
+        cred = OpenBadgeCredential(
+            issuer=Issuer(id='https://issuer.example', name='I'),
+            recipient_id='mailto:r@example.com',
+            achievement=Achievement(id='https://a.example/1', name='A',
+                                    description='d', criteria_narrative='c'),
+            evidence=[
+                Evidence(id='https://ev.example/1', narrative='Did the thing',
+                         name='Project'),
+                Evidence(narrative='No URL, just a narrative'),
+            ])
+        vc = cred.to_vc()
+        assert len(vc['evidence']) == 2
+        assert vc['evidence'][0] == {
+            'type': ['Evidence'], 'id': 'https://ev.example/1',
+            'narrative': 'Did the thing', 'name': 'Project'}
+        assert vc['evidence'][1] == {
+            'type': ['Evidence'], 'narrative': 'No URL, just a narrative'}
+        again = OpenBadgeCredential.from_vc_document(vc)
+        assert [e.narrative for e in again.evidence] == \
+            ['Did the thing', 'No URL, just a narrative']
+        # backward-compatible convenience: first evidence URL
+        assert again.evidence_url == 'https://ev.example/1'
+
+    def test_evidence_url_still_works(self):
+        # The single-URL convenience keeps issuing one Evidence object.
+        cred = self._credential()
+        cred.evidence_url = 'https://ev.example/only'
+        vc = cred.to_vc()
+        assert vc['evidence'] == [
+            {'type': ['Evidence'], 'id': 'https://ev.example/only'}]
+
+    def test_parse_from_raw_vc(self):
+        vc = {
+            '@context': OB3_CONTEXT,
+            'id': 'urn:uuid:00000000-0000-0000-0000-0000000000f1',
+            'type': ['VerifiableCredential', 'OpenBadgeCredential'],
+            'issuer': 'https://issuer.example',
+            'validFrom': '2024-01-01T00:00:00Z',
+            'credentialSubject': {
+                'id': 'mailto:r@example.com',
+                'type': ['AchievementSubject'],
+                'achievement': {
+                    'id': 'https://a.example/1', 'type': ['Achievement'],
+                    'name': 'A', 'description': 'd',
+                    'criteria': {'narrative': 'c'},
+                    'achievementType': 'Certificate',
+                    'creditsAvailable': 2,
+                    'alignment': [{'type': ['Alignment'],
+                                   'targetName': 'C', 'targetUrl': 'https://f/x'}],
+                },
+            },
+            'evidence': [{'type': ['Evidence'], 'id': 'https://ev/1',
+                          'narrative': 'n'}],
+        }
+        cred = OpenBadgeCredential.from_vc_document(vc)
+        assert cred.achievement.achievement_type == 'Certificate'
+        assert cred.achievement.credits_available == 2.0
+        assert cred.achievement.alignments[0].target_url == 'https://f/x'
+        assert cred.evidence[0].narrative == 'n'
+
+    def test_signed_credential_preserves_new_fields(self, rsa_priv_pem,
+                                                    rsa_pub_pem):
+        # End-to-end: the fields survive signing and verification.
+        from openbadgeslib.ob3 import OB3Signer, OB3Verifier
+        cred = self._credential(achievement_type='Competency',
+                                credits_available=1.0,
+                                alignments=[Alignment(
+                                    target_name='Skill',
+                                    target_url='https://f/skill')])
+        token = OB3Signer(privkey_pem=rsa_priv_pem, algorithm='RS256').sign(cred)
+        verified = OB3Verifier(pubkey_pem=rsa_pub_pem).verify(token)
+        assert verified.achievement.achievement_type == 'Competency'
+        assert verified.achievement.alignments[0].target_name == 'Skill'