openbadgeslib 1.2.0__tar.gz → 1.3.0__tar.gz

{openbadgeslib-1.2.0 → openbadgeslib-1.3.0}/Changelog.txt

@@ -4,6 +4,52 @@ OpenBadgesLib - Changelog
 Newest first. Dates are ISO 8601 (YYYY-MM-DD).
 
 
+* v1.3.0 - 2026-07-01
+
+  - SECURITY: download_file() now blocks server-side request forgery. The URLs
+    it fetches are attacker-influenced (an OB2 badge/issuer/revocationList URL,
+    an OB3 did:web host, an OB3 credentialStatus list), so it now resolves the
+    destination host and refuses any private, loopback, link-local, reserved,
+    multicast, unspecified or carrier-grade-NAT (100.64/10) address; the check
+    is re-applied to redirect targets. Previously a crafted badge could steer a
+    verifier into GETting cloud-metadata endpoints or internal hosts. An
+    allow_private=True opt-out is available for private deployments.
+
+  - SECURITY: OB3Verifier.for_issuer_did() now binds the credential to the
+    anchored DID — verify() requires the credential's issuer id to equal the
+    DID whose key was resolved. did:web is not self-certifying, so without this
+    a credential signed by the resolved key could claim a different (trusted)
+    issuer and be accepted. Verifiers built directly from a public key are
+    unchanged (the caller vouches for the key).
+
+  - SECURITY: openbadges-verifier --json exit status now reflects issuer trust,
+    not just signature validity: 0 = valid AND issuer-trusted, 2 = valid
+    signature but untrusted issuer (an OB2 badge-embedded key or a self-asserted
+    did:key), 1 = failure. In 1.2.0 a valid-but-untrusted badge exited 0, so CI
+    gating on the exit code accepted signatures that do not prove issuer
+    identity. NOTE: this changes the exit code for the valid-but-untrusted case
+    from 0 to 2; the JSON body (valid/trusted/reason) is unchanged.
+
+  - SECURITY: OB3 --resolve-did on a self-asserted did:key is now reported
+    trusted:false (with a warning), mirroring OB2's badge-embedded-key case;
+    only an operator-supplied key or a DNS/TLS-anchored did:web is trusted.
+
+  - fix: an OB3 Bitstring Status List with statusSize > 1 (multi-bit entries)
+    now fails closed instead of reading the wrong bit, which could have
+    reported a revoked credential as valid.
+
+  - fix: confparser now resolves a relative [paths] base against the directory
+    containing the config file (not the process CWD). Previously only a bare
+    '.' was handled and its value replaced wholesale, silently dropping the
+    suffix of './data' or '../shared' and misplacing key/log/image trees. A '$'
+    in the config directory path is handled correctly.
+
+  - docs: Ed25519 (EdDSA) support is now documented across README and the wiki
+    (key types, algorithms, keygenerator key_type, config example); the --json
+    exit-status scheme is documented; and stale/inaccurate crypto-library and
+    dependency notes were corrected.
+
+
 * v1.2.0 - 2026-07-01
 
   - feat: openbadges-verifier gained a --json flag for machine-readable output.

{openbadgeslib-1.2.0/openbadgeslib.egg-info → openbadgeslib-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openbadgeslib
-Version: 1.2.0
+Version: 1.3.0
 Summary: A library to sign and verify OpenBadges
 Author-email: Luis González Fernández <luisgf@luisgf.es>, Jesús Cea Avión <jcea@jcea.es>
 License: LGPLv3
@@ -56,7 +56,7 @@ serialisation) and **OpenBadges 3.0** (W3C Verifiable Credentials / JWT-VC).
 - Sign badge images (SVG and PNG) with a JWS assertion (OB 2.0)
 - Issue and verify OpenBadges 3.0 JWT-VC credentials
 - Bake OB 3.0 JWT tokens into SVG and PNG badge images
-- RSA 2048-bit (RS256) and ECC NIST P-256 (ES256) key support
+- RSA 2048-bit (RS256), ECC NIST P-256 (ES256), and Ed25519 (EdDSA) key support
 - SHA-256 hashed recipient identity with salt (OB 2.0)
 - Expiration and revocation checking
 - Five command-line tools included
@@ -68,6 +68,7 @@ serialisation) and **OpenBadges 3.0** (W3C Verifiable Credentials / JWT-VC).
 - [ecdsa](https://pypi.org/project/ecdsa/) >= 0.19
 - [pypng](https://pypi.org/project/pypng/) >= 0.20220715.0
 - [PyJWT[crypto]](https://pypi.org/project/PyJWT/) >= 2.8
+- [cryptography](https://pypi.org/project/cryptography/) >= 42
 - [defusedxml](https://pypi.org/project/defusedxml/) >= 0.7
 
 ## Installation

{openbadgeslib-1.2.0 → openbadgeslib-1.3.0}/README.md

@@ -15,7 +15,7 @@ serialisation) and **OpenBadges 3.0** (W3C Verifiable Credentials / JWT-VC).
 - Sign badge images (SVG and PNG) with a JWS assertion (OB 2.0)
 - Issue and verify OpenBadges 3.0 JWT-VC credentials
 - Bake OB 3.0 JWT tokens into SVG and PNG badge images
-- RSA 2048-bit (RS256) and ECC NIST P-256 (ES256) key support
+- RSA 2048-bit (RS256), ECC NIST P-256 (ES256), and Ed25519 (EdDSA) key support
 - SHA-256 hashed recipient identity with salt (OB 2.0)
 - Expiration and revocation checking
 - Five command-line tools included
@@ -27,6 +27,7 @@ serialisation) and **OpenBadges 3.0** (W3C Verifiable Credentials / JWT-VC).
 - [ecdsa](https://pypi.org/project/ecdsa/) >= 0.19
 - [pypng](https://pypi.org/project/pypng/) >= 0.20220715.0
 - [PyJWT[crypto]](https://pypi.org/project/PyJWT/) >= 2.8
+- [cryptography](https://pypi.org/project/cryptography/) >= 42
 - [defusedxml](https://pypi.org/project/defusedxml/) >= 0.7
 
 ## Installation

{openbadgeslib-1.2.0 → openbadgeslib-1.3.0}/openbadgeslib/config.ini.example

@@ -44,7 +44,7 @@ verify_key  = https://www.issuer.badge/issuer/badge_1/verify_rsa_key.pem
 badge       = https://www.issuer.badge/issuer/badge_1/badge.json
 private_key = ${paths:base_key}/sign_rsa_key_1.pem
 public_key  = ${paths:base_key}/verify_rsa_key_1.pem
-; key_type selects the algorithm for openbadges-keygenerator: RSA (default) or ECC
+; key_type selects the algorithm for openbadges-keygenerator: RSA (default), ECC, or ED25519
 key_type    = RSA
 ;alignement  =
 ;tags        =

{openbadgeslib-1.2.0 → openbadgeslib-1.3.0}/openbadgeslib/confparser.py

@@ -87,10 +87,22 @@ class ConfParser():
             raise ValueError(
                 "Configuration file %s has an empty [paths] 'base' value" % self.config_file)
 
-        if base[0] == '.':
-            abs_path = os.path.dirname(self.config_file)
-            full_path = os.path.abspath(abs_path)
-            self.parser['paths']['base'] = full_path
+        # A relative base is resolved against the directory that contains the
+        # config file (not the process CWD), so ${base}/... paths land where the
+        # operator expects no matter where the tool is launched from. The old
+        # check only matched a bare '.' and replaced the *whole* value with the
+        # config dir — silently dropping the suffix of './data' or '../shared'
+        # (and mis-handling a real '.hidden' dir), which could redirect private
+        # keys and logs to the wrong tree with no error.
+        if not os.path.isabs(base):
+            base_dir = os.path.dirname(self.config_file)
+            resolved = os.path.abspath(os.path.join(base_dir, base))
+            # Writing back through the parser runs the value through
+            # ExtendedInterpolation, which treats '$' specially: a config
+            # directory whose absolute path contains a literal '$' would raise a
+            # raw configparser error (or silently collapse '$$' to '$'). Escape
+            # '$' -> '$$' so the path round-trips to its original form on read.
+            self.parser['paths']['base'] = resolved.replace('$', '$$')
 
         # ExtendedInterpolation resolves ${...} references lazily, only when a
         # value is actually read — a bad reference anywhere in the file would

{openbadgeslib-1.2.0 → openbadgeslib-1.3.0}/openbadgeslib/ob3/status.py

@@ -88,6 +88,20 @@ def _check_entry(entry: dict, download: Callable[[str], bytes]) -> None:
 
     try:
         subject = _status_list_subject(raw)
+        # 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
+        # revoked credential as valid. Fail closed on an unsupported size rather
+        # than silently returning the wrong verdict. Absent/1 keeps 1-bit logic.
+        status_size = subject.get("statusSize", 1)
+        try:
+            status_size = int(status_size)
+        except (TypeError, ValueError):
+            raise OB3VerificationError("invalid statusSize: %r" % (status_size,))
+        if status_size != 1:
+            raise OB3VerificationError(
+                "unsupported statusSize %d: only single-bit status entries are "
+                "supported" % status_size)
         encoded = subject.get("encodedList")
         if not isinstance(encoded, str) or not encoded:
             raise OB3VerificationError("status list credential has no encodedList")

{openbadgeslib-1.2.0 → openbadgeslib-1.3.0}/openbadgeslib/ob3/verifier.py

@@ -74,8 +74,11 @@ class OB3Verifier:
                     ecdsa key object).
     """
 
-    def __init__(self, pubkey_pem: Any) -> None:
+    def __init__(self, pubkey_pem: Any, issuer_did: Optional[str] = None) -> None:
         self.pubkey_pem = key_to_pem(pubkey_pem)
+        # When the key was obtained by resolving a DID, remember that DID so
+        # verify() can bind the credential's stated issuer to it (see verify()).
+        self._anchored_did = issuer_did
         # Pin the accepted algorithms to this key's type so the token header
         # cannot dictate the algorithm (alg:none / HMAC downgrade / cross-type
         # confusion are all rejected up front rather than trusted).
@@ -94,9 +97,16 @@ class OB3Verifier:
         OB3VerificationError for an unsupported method or a resolution failure.
         Imported lazily so DID resolution (and its network path) is only pulled
         in when a caller actually anchors trust on a DID.
+
+        The resulting verifier is anchored to ``did``: verify() additionally
+        requires the credential's own issuer id to equal ``did``, so a token
+        signed by the resolved key but *claiming* a different issuer is
+        rejected. For did:key this is implied by the key being the identifier;
+        for did:web (not self-certifying) it is the check that stops an issuer
+        from being spoofed once its document has been fetched.
         """
         from .did import resolve_did
-        return cls(pubkey_pem=resolve_did(did, download=download))
+        return cls(pubkey_pem=resolve_did(did, download=download), issuer_did=did)
 
     # ── verification ───────────────────────────────────────────────────────────
 
@@ -116,6 +126,12 @@ class OB3Verifier:
         ``credentialSubject.id`` matches; otherwise the caller MUST compare
         ``credential.recipient_id`` itself.
 
+        Issuer binding: when this verifier was built via ``for_issuer_did``, the
+        credential's issuer id is additionally required to equal the anchored
+        DID, so a token signed by the resolved key but claiming a different
+        issuer is rejected. A verifier built directly from a public key performs
+        no issuer binding — the caller vouches for the key's owner.
+
         Pass ``check_status=True`` to also check the credential's
         ``credentialStatus`` (revocation) — this performs an HTTPS fetch of the
         referenced status list and fails closed if the credential is revoked or
@@ -125,6 +141,16 @@ class OB3Verifier:
         payload = self._decode_payload(token)
         credential = self._build_credential(payload)
 
+        # Bind the credential to the DID this verifier was anchored to (if any).
+        # for_issuer_did resolves a DID to a key; without this check verify()
+        # would accept a token signed by that key even when the credential
+        # claims a *different* issuer (a did:web is not self-certifying, so its
+        # fetched key is otherwise decoupled from the credential's issuer id).
+        if self._anchored_did is not None and credential.issuer.id != self._anchored_did:
+            raise OB3VerificationError(
+                "Credential issuer %r does not match the DID the verifier was "
+                "anchored to (%r)" % (credential.issuer.id, self._anchored_did))
+
         # The JWT 'exp'/'iat' claims (checked above by PyJWT) are attacker-
         # supplied and can be decoupled from vc.validUntil/validFrom, which is
         # what downstream consumers actually read. Re-validate the vc-level

{openbadgeslib-1.2.0 → openbadgeslib-1.3.0}/openbadgeslib/openbadges_verifier.py

@@ -99,7 +99,9 @@ def build_parser() -> argparse.ArgumentParser:
                         help='OpenBadges specification version: 2 (default, JWS) or 3 (JWT-VC).')
     parser.add_argument('--json', action='store_true',
                         help='Emit a machine-readable JSON result instead of the human '
-                             'output. Exits 0 when valid, non-zero otherwise.')
+                             'output. Exit status: 0 when the badge is valid AND the '
+                             'issuer is trusted; 2 when the signature is valid but the '
+                             'issuer is not anchored (untrusted); 1 on any failure.')
     parser.add_argument('-d', '--debug', action='store_true',
                         help='Show debug messages at runtime.')
     parser.add_argument('-v', '--version', action='version',
@@ -110,14 +112,21 @@ def build_parser() -> argparse.ArgumentParser:
 def _finish(args: argparse.Namespace, result: Dict[str, Any]) -> None:
     """Emit the verification result and set the process exit status.
 
-    In --json mode a single JSON object is printed and the process exits 0 when
-    valid, non-zero otherwise. Without --json the human lines have already been
+    In --json mode a single JSON object is printed and the process exit status
+    reflects issuer trust, not merely signature validity: 0 when the badge is
+    valid AND trusted, 2 when the signature is valid but the issuer is not
+    anchored (an OB2 badge-embedded key or a self-asserted did:key), and 1 on
+    any failure. Collapsing 'valid but untrusted' into an exit-0 success would
+    let automation gate on a signature that only proves internal consistency,
+    not who issued the badge. Without --json the human lines have already been
     printed; the historical exit behaviour is preserved via result['_exit']
     (None means return without exiting, i.e. a normal exit 0)."""
     if args.json:
         payload = {k: v for k, v in result.items() if not k.startswith('_')}
         print(json.dumps(payload))
-        sys.exit(0 if result.get('valid') else 1)
+        if not result.get('valid'):
+            sys.exit(1)
+        sys.exit(0 if result.get('trusted') else 2)
     code = result.get('_exit')
     if code is not None:
         sys.exit(code)
@@ -278,6 +287,12 @@ def _verify_ob3(args: argparse.Namespace) -> None:
         else:
             issuer_did = _issuer_did_from_token(token)
             result['issuer_did'] = issuer_did
+            # The DID is read from the untrusted token itself. A did:key IS the
+            # presenter's chosen key, so resolving it proves only internal
+            # consistency, not issuer identity — mark it untrusted, mirroring
+            # OB2's badge-embedded-key case. did:web is anchored on the issuer's
+            # DNS + TLS, so it stays trusted.
+            result['trusted'] = issuer_did.startswith('did:web:')
             if not args.json:
                 print('[*] Resolving issuer DID %s' % issuer_did)
             verifier = OB3Verifier.for_issuer_did(issuer_did)
@@ -291,7 +306,6 @@ def _verify_ob3(args: argparse.Namespace) -> None:
         return
 
     result['valid'] = True
-    result['reason'] = None
     result['_exit'] = None
     result['issuer'] = credential.issuer.name
     result['achievement'] = credential.achievement.name
@@ -310,8 +324,20 @@ def _verify_ob3(args: argparse.Namespace) -> None:
         if credential.evidence_url:
             print('[+] Evidence           : %s' % credential.evidence_url)
 
-    if not args.json:
-        print('[+] OB3 signature is valid for the identity %s' % args.receptor)
+    if result['trusted']:
+        result['reason'] = None
+        if not args.json:
+            print('[+] OB3 signature is valid for the identity %s' % args.receptor)
+    else:
+        result['reason'] = ('signature is valid but verified against a key resolved '
+                            'from the credential\'s own did:key (self-asserted), not a '
+                            'trusted issuer key')
+        if not args.json:
+            print('[~] OB3 signature is internally consistent for %s, but it was '
+                  'verified against a key resolved from the credential\'s own '
+                  'did:key. This does NOT prove issuer identity. Supply --pubkey '
+                  'FILE / --local BADGE, or anchor a did:web issuer, to establish '
+                  'trust.' % args.receptor)
 
     _finish(args, result)
 

{openbadgeslib-1.2.0 → openbadgeslib-1.3.0}/openbadgeslib/util.py

@@ -21,10 +21,12 @@
         License along with this library.
 """
 
-__version__ = '1.2.0'
+__version__ = '1.3.0'
 
 import hashlib
-from typing import Any, Optional, Union, overload
+import ipaddress
+import socket
+from typing import Any, List, Optional, Union, overload
 from urllib import request
 from urllib.parse import urlparse
 
@@ -99,17 +101,88 @@ def hash_email(email: StrOrBytes, salt: StrOrBytes) -> bytes:
     return sha256_string(email + salt)
 
 
+def _resolve_host(host: str, port: int) -> List[str]:
+    """Resolve *host* to a list of IP-address strings.
+
+    A thin wrapper over socket.getaddrinfo, kept as the single dependency seam
+    the SSRF host check uses so tests can patch resolution without the network.
+    """
+    infos = socket.getaddrinfo(host, port, proto=socket.IPPROTO_TCP)
+    # sockaddr[0] is the address; getaddrinfo's sockaddr is typed as a tuple
+    # union (str | int), so coerce to str for the annotated return type.
+    return [str(info[4][0]) for info in infos]
+
+
+# RFC 6598 carrier-grade NAT shared address space. Python's ipaddress does not
+# flag it as private/reserved, but it is not globally routable and commonly
+# fronts internal ISP/cloud infrastructure, so it is a valid SSRF target.
+_CGNAT_V4 = ipaddress.ip_network('100.64.0.0/10')
+
+
+def _ip_is_blocked(ip_str: str) -> bool:
+    """True if *ip_str* is a loopback/private/link-local/reserved/CGNAT address
+    a verifier must never be steered into fetching (an SSRF sink)."""
+    try:
+        ip = ipaddress.ip_address(ip_str)
+    except ValueError:
+        return True  # unparseable address: fail closed
+    # An IPv4-mapped IPv6 address (::ffff:127.0.0.1) must be judged by its
+    # embedded IPv4 address, not the v6 wrapper, or the loopback slips through.
+    if ip.version == 6 and ip.ipv4_mapped is not None:
+        ip = ip.ipv4_mapped
+    if ip.version == 4 and ip in _CGNAT_V4:
+        return True
+    return (ip.is_private or ip.is_loopback or ip.is_link_local
+            or ip.is_reserved or ip.is_multicast or ip.is_unspecified)
+
+
+def _assert_public_host(url: str) -> None:
+    """Raise ValueError if *url*'s host resolves to any non-public address.
+
+    download_file is called with fully attacker-controlled URLs: a did:web
+    host, a credentialStatus list, and the OB2 badge/issuer/revocationList URLs
+    all come from untrusted badge data. Without this check a verifier can be
+    steered into GETting cloud-metadata endpoints (169.254.169.254), loopback
+    admin interfaces, or RFC1918 internal hosts (SSRF). Every resolved address
+    is checked, and the check is re-applied to redirect targets in
+    _HTTPSOnlyRedirectHandler (a public host can 30x to an internal address).
+
+    This is a pre-connection check; it does not on its own defeat DNS rebinding
+    (a name that resolves public here but private at connect time), which would
+    require pinning the socket to the validated address.
+    """
+    parts = urlparse(url)
+    host = parts.hostname
+    if not host:
+        raise ValueError('Refusing to download %s: URL has no host' % url)
+    try:
+        addrs = _resolve_host(host, parts.port or 443)
+    except OSError as exc:
+        raise ValueError(
+            'Could not resolve host %r for %s: %s' % (host, url, exc)) from exc
+    if not addrs:
+        raise ValueError('Could not resolve host %r for %s' % (host, url))
+    for ip_str in addrs:
+        if _ip_is_blocked(ip_str):
+            raise ValueError(
+                'Refusing to download %s: host %r resolves to non-public address '
+                '%s (possible SSRF). Pass allow_private=True to override.'
+                % (url, host, ip_str))
+
+
 class _HTTPSOnlyRedirectHandler(request.HTTPRedirectHandler):
-    """Reject any redirect whose target is not HTTPS.
+    """Reject any redirect whose target is not HTTPS or resolves to a
+    non-public host.
 
     Plain ``urlopen()`` follows redirects with the default HTTPRedirectHandler,
-    which never re-checks scheme: an https:// URL that 302s to http:// (or to
-    an attacker-chosen insecure origin) would be followed transparently,
-    defeating the HTTPS-only check below.
+    which never re-checks scheme or host: an https:// URL that 302s to http://
+    (or to an attacker-chosen insecure/internal origin) would be followed
+    transparently, defeating the HTTPS-only and public-host checks below.
     """
 
-    def __init__(self, allow_insecure: bool) -> None:
+    def __init__(self, allow_insecure: bool, allow_private: bool = False) -> None:
         self._allow_insecure = allow_insecure
+        self._allow_private = allow_private
 
     def redirect_request(self, req: Any, fp: Any, code: int, msg: str, headers: Any,
                          newurl: str) -> Any:
@@ -119,6 +192,8 @@ class _HTTPSOnlyRedirectHandler(request.HTTPRedirectHandler):
                 'Refusing to follow redirect to %s over insecure %r scheme; HTTPS is '
                 'required (pass allow_insecure=True to override).'
                 % (newurl, new_scheme))
+        if not self._allow_private:
+            _assert_public_host(newurl)
         return super().redirect_request(req, fp, code, msg, headers, newurl)
 
 
@@ -128,15 +203,23 @@ class _HTTPSOnlyRedirectHandler(request.HTTPRedirectHandler):
 MAX_DOWNLOAD_SIZE = 5 * 1024 * 1024  # 5 MiB
 
 
-def download_file(url: str, allow_insecure: bool = False) -> bytes:
+def download_file(url: str, allow_insecure: bool = False,
+                  allow_private: bool = False) -> bytes:
     """Download a file over HTTPS using urllib's default TLS validation.
 
     Non-HTTPS URLs are rejected by default: the verification key is the
     OpenBadges 2.0 root of trust, so fetching it over an unauthenticated
     channel would let an active network attacker substitute their own key and
     forge badges. Pass ``allow_insecure=True`` to explicitly permit plain HTTP.
-    A redirect to a non-HTTPS target is rejected the same way. The response
-    body is bounded to MAX_DOWNLOAD_SIZE to limit memory use.
+    A redirect to a non-HTTPS target is rejected the same way.
+
+    The destination host is also required to resolve to a public address:
+    because the URL is attacker-influenced (a did:web host, a credentialStatus
+    list, an OB2 badge/issuer/revocationList URL), fetching a private/loopback/
+    link-local target would be a server-side request forgery (SSRF) sink. Pass
+    ``allow_private=True`` to permit internal hosts (e.g. a private deployment).
+    The check is re-applied to redirect targets. The response body is bounded to
+    MAX_DOWNLOAD_SIZE to limit memory use.
     """
     u = urlparse(url)
 
@@ -148,7 +231,11 @@ def download_file(url: str, allow_insecure: bool = False) -> bytes:
                 % (url, u.scheme))
         print('Warning! %s does not use TLS.' % url)
 
-    opener = request.build_opener(_HTTPSOnlyRedirectHandler(allow_insecure))
+    if not allow_private:
+        _assert_public_host(url)
+
+    opener = request.build_opener(
+        _HTTPSOnlyRedirectHandler(allow_insecure, allow_private))
     with opener.open(url, timeout=30) as response:
         chunks = []
         total = 0

{openbadgeslib-1.2.0 → openbadgeslib-1.3.0/openbadgeslib.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openbadgeslib
-Version: 1.2.0
+Version: 1.3.0
 Summary: A library to sign and verify OpenBadges
 Author-email: Luis González Fernández <luisgf@luisgf.es>, Jesús Cea Avión <jcea@jcea.es>
 License: LGPLv3
@@ -56,7 +56,7 @@ serialisation) and **OpenBadges 3.0** (W3C Verifiable Credentials / JWT-VC).
 - Sign badge images (SVG and PNG) with a JWS assertion (OB 2.0)
 - Issue and verify OpenBadges 3.0 JWT-VC credentials
 - Bake OB 3.0 JWT tokens into SVG and PNG badge images
-- RSA 2048-bit (RS256) and ECC NIST P-256 (ES256) key support
+- RSA 2048-bit (RS256), ECC NIST P-256 (ES256), and Ed25519 (EdDSA) key support
 - SHA-256 hashed recipient identity with salt (OB 2.0)
 - Expiration and revocation checking
 - Five command-line tools included
@@ -68,6 +68,7 @@ serialisation) and **OpenBadges 3.0** (W3C Verifiable Credentials / JWT-VC).
 - [ecdsa](https://pypi.org/project/ecdsa/) >= 0.19
 - [pypng](https://pypi.org/project/pypng/) >= 0.20220715.0
 - [PyJWT[crypto]](https://pypi.org/project/PyJWT/) >= 2.8
+- [cryptography](https://pypi.org/project/cryptography/) >= 42
 - [defusedxml](https://pypi.org/project/defusedxml/) >= 0.7
 
 ## Installation

{openbadgeslib-1.2.0 → openbadgeslib-1.3.0}/tests/test_cli_json.py

@@ -82,6 +82,86 @@ def test_ob3_no_key_json(tmp_path, rsa_priv_pem, svg_image, capsys):
     assert 'requires' in result['reason']
 
 
+# ── OB3 --resolve-did trust semantics ─────────────────────────────────────────
+
+_B58 = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'
+
+
+def _b58encode(data: bytes) -> str:
+    n = int.from_bytes(data, 'big')
+    out = ''
+    while n > 0:
+        n, r = divmod(n, 58)
+        out = _B58[r] + out
+    pad = len(data) - len(data.lstrip(b'\x00'))
+    return '1' * pad + out
+
+
+def _did_key_ed25519(pub) -> str:
+    from cryptography.hazmat.primitives import serialization as ser
+    raw = pub.public_bytes(ser.Encoding.Raw, ser.PublicFormat.Raw)
+    return 'did:key:z' + _b58encode(b'\xed\x01' + raw)
+
+
+def _ob3_did_badge(tmp_path, ed25519_priv_pem, svg_image, issuer_did):
+    from openbadgeslib.ob3 import OB3Signer, Issuer, Achievement, OpenBadgeCredential
+    signer = OB3Signer(privkey_pem=ed25519_priv_pem, algorithm='EdDSA')
+    cred = OpenBadgeCredential(
+        issuer=Issuer(id=issuer_did, name='Self Issuer'),
+        recipient_id='mailto:recipient@example.com',
+        achievement=Achievement(id='https://example.com/a', name='A',
+                                description='d', criteria_narrative='c'),
+    )
+    badge_file = tmp_path / 'badge.svg'
+    badge_file.write_bytes(signer.sign_into_svg(cred, svg_image))
+    return badge_file
+
+
+def test_ob3_resolve_did_key_is_untrusted_json(
+    tmp_path, ed25519_priv_pem, ed25519_pub_pem, svg_image, capsys
+):
+    # --resolve-did on a did:key reads the verification key from the token
+    # itself: the signature is valid but self-asserted (the presenter chose the
+    # key), so it must report trusted:false and exit 2 — never an exit-0
+    # "verified", mirroring the OB2 badge-embedded-key case.
+    from cryptography.hazmat.primitives import serialization as ser
+    did = _did_key_ed25519(ser.load_pem_public_key(ed25519_pub_pem))
+    badge = _ob3_did_badge(tmp_path, ed25519_priv_pem, svg_image, did)
+    argv = ['openbadges-verifier', '-i', str(badge), '-r', 'recipient@example.com',
+            '-V', '3', '--resolve-did', '--json']
+    code, result = _run(argv, capsys)
+    assert code == 2
+    assert result['valid'] is True
+    assert result['trusted'] is False
+    assert result['issuer_did'] == did
+
+
+def test_ob3_resolve_did_web_is_trusted_json(
+    tmp_path, ed25519_priv_pem, ed25519_pub_pem, svg_image, capsys
+):
+    # A did:web issuer is anchored on DNS + TLS, so a resolved-and-verified
+    # credential is trusted:true and exits 0.
+    import base64
+    from cryptography.hazmat.primitives import serialization as ser
+    pub = ser.load_pem_public_key(ed25519_pub_pem)
+    raw = pub.public_bytes(ser.Encoding.Raw, ser.PublicFormat.Raw)
+    x = base64.urlsafe_b64encode(raw).decode('ascii').rstrip('=')
+    did = 'did:web:issuer.example'
+    doc = {"id": did, "verificationMethod": [
+        {"id": did + "#k", "type": "JsonWebKey2020", "controller": did,
+         "publicKeyJwk": {"kty": "OKP", "crv": "Ed25519", "x": x}}]}
+    badge = _ob3_did_badge(tmp_path, ed25519_priv_pem, svg_image, did)
+    argv = ['openbadges-verifier', '-i', str(badge), '-r', 'recipient@example.com',
+            '-V', '3', '--resolve-did', '--json']
+    code, result = _run(argv, capsys, extra_patches=(
+        patch('openbadgeslib.ob3.did.download_file',
+              return_value=json.dumps(doc).encode('utf-8')),
+    ))
+    assert code == 0
+    assert result['valid'] is True
+    assert result['trusted'] is True
+
+
 # ── OB2 ──────────────────────────────────────────────────────────────────────
 
 def _make_signed_ob2_svg(tmp_path, badge, identity='recipient@example.com'):
@@ -112,6 +192,11 @@ def test_ob2_valid_trusted_json(tmp_path, svg_rsa_badge, rsa_pub_pem, capsys):
 
 
 def test_ob2_untrusted_is_valid_but_not_trusted_json(tmp_path, svg_rsa_badge, rsa_pub_pem, capsys):
+    # Verified against the badge-embedded key (no --local/--pubkey): the
+    # signature is internally consistent but the issuer is not anchored, so the
+    # process must NOT exit 0 (which automation reads as "verified"). Exit 2
+    # signals "valid signature, untrusted issuer"; the JSON still reports the
+    # detail. Exit 0 here would let a self-signed forgery pass a CI gate.
     badge_file = _make_signed_ob2_svg(tmp_path, svg_rsa_badge)
     argv = ['openbadges-verifier', '-i', str(badge_file), '-r', 'recipient@example.com',
             '-V', '2', '--json']
@@ -119,7 +204,7 @@ def test_ob2_untrusted_is_valid_but_not_trusted_json(tmp_path, svg_rsa_badge, rs
         patch('openbadgeslib.ob2.badge.download_file', return_value=rsa_pub_pem),
         patch('openbadgeslib.ob2.verifier.download_file', side_effect=_fake_revocation_download),
     ))
-    assert code == 0
+    assert code == 2
     assert result['valid'] is True
     assert result['trusted'] is False
 

{openbadgeslib-1.2.0 → openbadgeslib-1.3.0}/tests/test_confparser.py

@@ -31,6 +31,56 @@ class TestReadConfBaseValidation:
         conf = ConfParser(path).read_conf()
         assert conf['paths']['base'] == str(tmp_path)
 
+    def test_relative_base_with_suffix_keeps_suffix(self, tmp_path):
+        # './data' must resolve to <config_dir>/data, not be truncated to
+        # <config_dir> (which would silently misplace keys/logs/images).
+        import os
+        path = _write(tmp_path, '[paths]\nbase = ./data\n')
+        conf = ConfParser(path).read_conf()
+        assert conf['paths']['base'] == os.path.join(str(tmp_path), 'data')
+
+    def test_parent_relative_base_is_resolved(self, tmp_path):
+        import os
+        path = _write(tmp_path, '[paths]\nbase = ../shared\n')
+        conf = ConfParser(path).read_conf()
+        assert conf['paths']['base'] == os.path.abspath(
+            os.path.join(str(tmp_path), '..', 'shared'))
+
+    def test_plain_relative_base_anchored_to_config_dir(self, tmp_path):
+        # A relative base with no leading dot is anchored to the config-file
+        # directory, not left relative to the process CWD.
+        import os
+        path = _write(tmp_path, '[paths]\nbase = badgedata\n')
+        conf = ConfParser(path).read_conf()
+        assert conf['paths']['base'] == os.path.join(str(tmp_path), 'badgedata')
+
+    def test_hidden_dir_base_is_not_truncated(self, tmp_path):
+        # A directory literally named '.hidden' must be kept, not dropped by the
+        # old base[0] == '.' shortcut.
+        import os
+        path = _write(tmp_path, '[paths]\nbase = .hidden\n')
+        conf = ConfParser(path).read_conf()
+        assert conf['paths']['base'] == os.path.join(str(tmp_path), '.hidden')
+
+    def test_absolute_base_is_left_unchanged(self, tmp_path):
+        abs_base = str(tmp_path / 'keys')
+        path = _write(tmp_path, '[paths]\nbase = %s\n' % abs_base)
+        conf = ConfParser(path).read_conf()
+        assert conf['paths']['base'] == abs_base
+
+    def test_config_dir_with_dollar_sign_round_trips(self, tmp_path):
+        # A config directory whose path contains a literal '$' must not raise
+        # (ExtendedInterpolation escaping) and must resolve back to the original
+        # path, including through a ${base} reference.
+        import os
+        d = tmp_path / 'a$b'
+        d.mkdir()
+        p = d / 'config.ini'
+        p.write_text('[paths]\nbase = data\nbase_key = ${base}/keys\n')
+        conf = ConfParser(str(p)).read_conf()
+        assert conf['paths']['base'] == os.path.join(str(d), 'data')
+        assert conf['paths']['base_key'] == os.path.join(str(d), 'data', 'keys')
+
     def test_nonexistent_file_returns_none(self, tmp_path):
         assert ConfParser(str(tmp_path / 'missing.ini')).read_conf() is None
 

{openbadgeslib-1.2.0 → openbadgeslib-1.3.0}/tests/test_ob3_did.py

@@ -189,3 +189,72 @@ class TestForIssuerDid:
         verifier = OB3Verifier.for_issuer_did(wrong_did)
         with pytest.raises(OB3VerificationError):
             verifier.verify(token)
+
+    def _did_web_key_doc(self, ed25519_pub_pem, did):
+        pub = ser.load_pem_public_key(ed25519_pub_pem)
+        raw = pub.public_bytes(ser.Encoding.Raw, ser.PublicFormat.Raw)
+        jwk = {"kty": "OKP", "crv": "Ed25519", "x": _b64url(raw)}
+        return {
+            "id": did,
+            "verificationMethod": [
+                {"id": did + "#key-1", "type": "JsonWebKey2020",
+                 "controller": did, "publicKeyJwk": jwk},
+            ],
+        }
+
+    def test_did_web_issuer_spoofing_rejected(self, ed25519_priv_pem, ed25519_pub_pem):
+        # did:web is NOT self-certifying: an attacker who controls
+        # did:web:attacker.example (and its key) signs a credential that CLAIMS
+        # a trusted issuer. Anchoring on the attacker DID resolves their key and
+        # the signature is valid, so binding the credential's issuer id to the
+        # anchored DID is the only thing that rejects the forgery.
+        from openbadgeslib.ob3 import OB3Signer, Achievement, Issuer, OpenBadgeCredential
+        attacker_did = 'did:web:attacker.example'
+        doc = self._did_web_key_doc(ed25519_pub_pem, attacker_did)
+        credential = OpenBadgeCredential(
+            id='urn:uuid:00000000-0000-0000-0000-0000000000ce',
+            issuer=Issuer(id='did:web:trusted-university.example', name='Trusted'),
+            recipient_id='mailto:r@example.com',
+            achievement=Achievement(id='https://a.example/1', name='A',
+                                    description='d', criteria_narrative='c'),
+        )
+        token = OB3Signer(privkey_pem=ed25519_priv_pem, algorithm='EdDSA').sign(credential)
+        verifier = OB3Verifier.for_issuer_did(
+            attacker_did, download=lambda url: json.dumps(doc).encode('utf-8'))
+        with pytest.raises(OB3VerificationError, match='issuer'):
+            verifier.verify(token)
+
+    def test_did_web_matching_issuer_verifies(self, ed25519_priv_pem, ed25519_pub_pem):
+        # The honest case: the credential's issuer id equals the anchored DID.
+        from openbadgeslib.ob3 import OB3Signer, Achievement, Issuer, OpenBadgeCredential
+        did = 'did:web:issuer.example'
+        doc = self._did_web_key_doc(ed25519_pub_pem, did)
+        credential = OpenBadgeCredential(
+            id='urn:uuid:00000000-0000-0000-0000-0000000000cf',
+            issuer=Issuer(id=did, name='Issuer'),
+            recipient_id='mailto:r@example.com',
+            achievement=Achievement(id='https://a.example/1', name='A',
+                                    description='d', criteria_narrative='c'),
+        )
+        token = OB3Signer(privkey_pem=ed25519_priv_pem, algorithm='EdDSA').sign(credential)
+        verifier = OB3Verifier.for_issuer_did(
+            did, download=lambda url: json.dumps(doc).encode('utf-8'))
+        cred = verifier.verify(token)
+        assert cred.issuer.id == did
+
+    def test_direct_pubkey_verifier_does_not_bind_issuer(
+        self, ed25519_priv_pem, ed25519_pub_pem
+    ):
+        # A verifier built straight from a key (no DID anchor) performs no
+        # issuer binding — the caller vouches for the key's owner.
+        from openbadgeslib.ob3 import OB3Signer, Achievement, Issuer, OpenBadgeCredential
+        credential = OpenBadgeCredential(
+            id='urn:uuid:00000000-0000-0000-0000-0000000000d0',
+            issuer=Issuer(id='did:web:anything.example', name='Whoever'),
+            recipient_id='mailto:r@example.com',
+            achievement=Achievement(id='https://a.example/1', name='A',
+                                    description='d', criteria_narrative='c'),
+        )
+        token = OB3Signer(privkey_pem=ed25519_priv_pem, algorithm='EdDSA').sign(credential)
+        cred = OB3Verifier(pubkey_pem=ed25519_pub_pem).verify(token)
+        assert cred.issuer.id == 'did:web:anything.example'

{openbadgeslib-1.2.0 → openbadgeslib-1.3.0}/tests/test_ob3_status.py

@@ -104,6 +104,23 @@ class TestCheckCredentialStatus:
         with pytest.raises(OB3VerificationError):
             check_credential_status(cred, download=lambda url: jwt_like.encode('ascii'))
 
+    def test_multibit_statussize_is_rejected(self):
+        # statusSize > 1 (multi-bit entries) is not supported: _bit_set assumes
+        # one bit per entry, so honouring it would read the wrong bits. Fail
+        # closed rather than misreport a revoked credential as valid.
+        doc = _status_list_doc(set_indices=[7])
+        doc['credentialSubject']['statusSize'] = 2
+        cred = _credential([_status_entry(94)])
+        with pytest.raises(OB3VerificationError, match='statusSize'):
+            check_credential_status(cred, download=_downloader(doc))
+
+    def test_explicit_statussize_one_is_accepted(self):
+        # An explicit statusSize of 1 is the default single-bit case.
+        doc = _status_list_doc(set_indices=[7])
+        doc['credentialSubject']['statusSize'] = 1
+        cred = _credential([_status_entry(94)])  # index 94 unset -> not revoked
+        check_credential_status(cred, download=_downloader(doc))
+
     # ── fail-closed paths ────────────────────────────────────────────────────
 
     def test_fetch_error_fails_closed(self):

{openbadgeslib-1.2.0 → openbadgeslib-1.3.0}/tests/test_util.py

@@ -98,6 +98,14 @@ def _mock_opener(content=b'file content', open_side_effect=None):
 
 
 class TestDownloadFile:
+    @pytest.fixture(autouse=True)
+    def _public_resolver(self):
+        # download_file now resolves the host and rejects non-public IPs. Pin
+        # resolution to a fixed public address so these behavioural tests stay
+        # hermetic (no DNS) — SSRF blocking is covered by TestSSRFProtection.
+        with patch('openbadgeslib.util._resolve_host', return_value=['93.184.216.34']):
+            yield
+
     def test_returns_bytes_on_success(self):
         with patch('openbadgeslib.util.request.build_opener', return_value=_mock_opener()):
             result = download_file('https://example.com/file.pem')
@@ -159,6 +167,13 @@ class TestDownloadFile:
 class TestHTTPSOnlyRedirectHandler:
     """Regression coverage for the redirect scheme-downgrade fix."""
 
+    @pytest.fixture(autouse=True)
+    def _public_resolver(self):
+        # The redirect handler now also rejects a redirect to a non-public host;
+        # pin resolution so the "allowed" redirect cases stay hermetic.
+        with patch('openbadgeslib.util._resolve_host', return_value=['93.184.216.34']):
+            yield
+
     def _handler(self, allow_insecure=False):
         from openbadgeslib.util import _HTTPSOnlyRedirectHandler
         return _HTTPSOnlyRedirectHandler(allow_insecure)
@@ -203,6 +218,67 @@ class TestHTTPSOnlyRedirectHandler:
         assert isinstance(handler, _HTTPSOnlyRedirectHandler)
 
 
+class TestSSRFProtection:
+    """download_file must refuse attacker-controlled URLs that resolve to
+    non-public hosts (cloud metadata, loopback, RFC1918)."""
+
+    @pytest.mark.parametrize('ip', [
+        '127.0.0.1', '169.254.169.254', '10.0.0.5', '192.168.1.1',
+        '172.16.0.1', '0.0.0.0', '::1', 'fe80::1', 'fc00::1',
+        '::ffff:127.0.0.1',
+        # RFC 6598 carrier-grade NAT: not is_private, but not globally routable.
+        '100.64.0.1', '100.127.255.255',
+    ])
+    def test_private_host_rejected(self, ip):
+        with patch('openbadgeslib.util._resolve_host', return_value=[ip]):
+            with pytest.raises(ValueError):
+                download_file('https://internal.example/x')
+
+    def test_literal_metadata_ip_rejected(self):
+        # A literal IP needs no DNS: getaddrinfo returns it directly, so this
+        # exercises the real resolver + classifier without touching the network.
+        with pytest.raises(ValueError):
+            download_file('https://169.254.169.254/latest/meta-data/')
+
+    def test_literal_loopback_ipv6_rejected(self):
+        with pytest.raises(ValueError):
+            download_file('https://[::1]:8080/admin')
+
+    def test_percent_encoded_localhost_port_rejected(self):
+        # Mirrors a did:web:localhost%3A8080 URL after unquoting.
+        with pytest.raises(ValueError):
+            download_file('https://localhost:8080/issuer/did.json')
+
+    def test_public_host_allowed(self):
+        with patch('openbadgeslib.util._resolve_host', return_value=['93.184.216.34']), \
+                patch('openbadgeslib.util.request.build_opener', return_value=_mock_opener()):
+            assert download_file('https://example.com/f') == b'file content'
+
+    def test_any_private_address_in_set_rejects(self):
+        # A mixed public+private resolution (round-robin / rebinding) is refused.
+        with patch('openbadgeslib.util._resolve_host',
+                   return_value=['93.184.216.34', '127.0.0.1']):
+            with pytest.raises(ValueError):
+                download_file('https://example.com/f')
+
+    def test_allow_private_opt_out(self):
+        with patch('openbadgeslib.util._resolve_host', return_value=['127.0.0.1']), \
+                patch('openbadgeslib.util.request.build_opener', return_value=_mock_opener()):
+            assert download_file('https://localhost/f', allow_private=True) == b'file content'
+
+    def test_redirect_to_private_host_rejected(self):
+        from openbadgeslib.util import _HTTPSOnlyRedirectHandler
+        req = MagicMock()
+        req.get_method.return_value = 'GET'
+        req.get_full_url.return_value = 'https://example.com/original'
+        req.unredirected_hdrs = {}
+        req.headers = {}
+        with patch('openbadgeslib.util._resolve_host', return_value=['169.254.169.254']):
+            with pytest.raises(ValueError):
+                _HTTPSOnlyRedirectHandler(allow_insecure=False).redirect_request(
+                    req, None, 302, 'Found', {}, 'https://evil.example/x')
+
+
 class TestMisc:
     def test_show_ecc_disclaimer_does_not_raise(self, capsys):
         show_ecc_disclaimer()