openbadgeslib 3.8.0__tar.gz → 3.10.0__tar.gz

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

@@ -4,6 +4,135 @@ OpenBadgesLib - Changelog
 Newest first. Dates are ISO 8601 (YYYY-MM-DD).
 
 
+* v3.10.0 - 2026-07-08
+
+  - feat(publish): `openbadges-publish -V 3 --check-live` completes #164. After
+    (re)publishing, it downloads each written artifact — `did.json`, the signed
+    status lists, `verify.pem` — from `publish_url` and byte-compares it against
+    the local copy, turning the "re-upload so the change takes effect" reminder
+    into a verifiable guarantee. Exit 2 (`--json`, listed in `live_check.stale`)
+    or 1 (human) if any artifact is stale or missing on the server. The rest of
+    #164 (status-list `validUntil` + opt-in list-proof verification + issuer
+    binding) shipped in v3.8.0. (Closes #164)
+
+  - docs(examples): #168 library integration tutorial + runnable examples. New
+    `examples/` scripts — issue+verify an OB 3.0 JWT-VC, issue with a Data
+    Integrity (LDP) proof, and issue from a config section via the high-level API
+    (single + batch) — each self-contained and executed in CI (`test_examples.py`,
+    anti-drift, same philosophy as `test_docs.py`). Two new wiki pages: the
+    "Library Integration Tutorial" narrating them end to end (issue → sign →
+    publish → revoke → verify) and a "Certification Cookbook" on passing the
+    official 1EdTech OB 3.0 conformance tests without the paid membership.
+    (Closes #168)
+
+  - test(coverage): #169 targeted-coverage round. New dedicated suites for the
+    shared token carrier (`test_baking.py` — embed/extract round-trips per
+    format, compression and malformed-iTXt edges), mail (`test_mail.py` — SMTP
+    mocked) and the key helpers (`test_keys.py`), plus error-branch coverage for
+    the OB2 signer/verifier, the OB3 Data Integrity (LDP) path and the verifier
+    CLI (`openbadges_verifier.py` 74% → 95%). Total coverage crosses 93% and the
+    enforced `fail_under` floor is raised from 91 to 93. An opt-in OB2
+    **SignedBadge** conformance case joins the existing hosted one (the
+    crypto-sensitive path, Docker-gated). (Closes #169)
+
+  - docs(ob1): OpenBadges 1.0 is reclassified from "deprecated, removal in
+    4.0.0" to a **supported legacy surface with no removal planned**. Removing a
+    working, dependency-free legacy path (OB1 has carried no unique dependencies
+    since #167) was judged excessive; OB1 stays fully functional and maintained,
+    simply superseded by OB 2.0/3.0 for new work. The library
+    `DeprecationWarning`s and the `-V 1` CLI notices are reworded to steer new
+    work to OB2/OB3 without promising removal, and the "OpenBadges 1.0
+    lifecycle" wiki page records the policy — including why a `[legacy]`/`[ob1]`
+    install extra stays rejected: a Python extra gates *dependencies*, not code,
+    and OB1 has none to gate (it would install the same bytes). Reverses the
+    removal side of #159/#170.
+
+  - feat(cli): batch issuance — `openbadges-signer` now issues to many recipients
+    in one run. Repeat `-r EMAIL`, or pass `--recipients-file FILE` (one email per
+    line or comma-separated; blank lines and `#`-comments ignored); a single `-r`
+    keeps the historical single-badge behaviour byte-for-byte. For a revocable OB3
+    badge every status-list index is allocated in a SINGLE registry transaction
+    (load once, allocate N, save once) rather than N load/save cycles — the piece
+    that makes thousands-scale issuance practical. An already-existing output file
+    is skipped (batch) or aborts (single) unless the new `--force`/`--overwrite`
+    overwrites it, and one bad recipient does not abort the rest. `--json` emits a
+    per-recipient summary `{signed, skipped, failed}` under the shared exit
+    contract (0 all signed, 2 some skipped/failed, 1 a batch-level error). The
+    library entry point is `openbadgeslib.issue.issue_batch_from_conf`, returning
+    one `BatchResult` per recipient. (Closes #165)
+
+  - feat(api): extract the issuance orchestration from the CLI into a reusable
+    library API — the single biggest adoption gap. `openbadgeslib.issue` exposes
+    `issue_from_conf(conf, badge, recipient, ob_version, ...)` (also re-exported
+    as `openbadgeslib.issue_from_conf`), returning a `SignResult` dataclass with
+    the signed badge bytes and metadata and doing no user-facing I/O — no
+    prints, no sys.exit, no file write; a config or policy problem raises
+    `IssuanceError`. The ~230 lines of business logic that lived in
+    openbadges-signer (credential construction from config, salt generation, the
+    OB2 hosted-vs-signed decision, the OB3 status-registry→sign transactional
+    order and the Data Integrity verificationMethod policy — did:web trusted vs
+    a derived self-asserted did:key) now live there and are unit-tested
+    directly, not only reachable by driving the CLI. The signer entrypoints are
+    reduced to flag parsing, I/O and display over that API; behaviour — including
+    the historical per-version exit conventions — is unchanged. Prerequisite for
+    batch signing (#165) and any unified CLI. OpenBadges 1.0 issuance stays
+    CLI-only (it is deprecated). (Closes #160)
+
+  - feat(ob3): complete the broadened OB 3.0 credential model started in
+    v3.9.0 — closing the remaining data-model gap versus the spec. New `Result`
+    (a measured outcome: value, status, achievedLevel and the linked
+    resultDescription), `ResultDescription` (an achievement's possible results:
+    resultType, allowedValue, valueMin/valueMax, requiredValue/requiredLevel)
+    and `IdentityObject` (a hashed or plaintext `credentialSubject.identifier`,
+    the alternative to `credentialSubject.id`) dataclasses, plus `creditsEarned`
+    on the subject and a `resultDescription` list on `Achievement`. All follow
+    the house style (dataclasses + mypy, no Pydantic), parse from a verified
+    credential, round-trip through `to_vc`, and satisfy the offline conformance
+    schema — a fully-populated credential (identifier-only subject, result +
+    linked resultDescription, alignment, credits) validates against 1EdTech's
+    AchievementCredential schema. `openbadges-verifier` now surfaces the
+    broadened fields — achievementType, creditsAvailable/creditsEarned and the
+    alignment/result/identifier counts — in both `--json` and `--show`. Two
+    round-trip fixes fall out: a subject conveying identity solely through
+    `identifier` now re-serialises with it (the identifier was silently dropped
+    on parse before), and a lone `alignment` object not wrapped in an array is
+    no longer discarded. (Closes #162)
+
+  - fix(cli): `openbadges-publish -V 1/-V 2` now exits with a clear message when
+    the `[issuer]` section is missing `publish_url` or `revocationList`, instead
+    of raising a raw `KeyError` traceback partway through — after the output
+    directory had already been created. The OB3 path already validated this; the
+    hosted OB1/OB2 paths now share the same guard. Last item of the quick-fix
+    round. (Closes #156)
+
+
+* 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.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openbadgeslib
-Version: 3.8.0
+Version: 3.10.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.10.0}/openbadgeslib/__init__.py

@@ -39,13 +39,23 @@ from .keys import KeyFactory, KeyRSA, KeyECC  # noqa: F401
 from .util import __version__  # noqa: F401
 
 
+# ── Issuance API ─────────────────────────────────────────────────────────────
+# "Issue badge X to Y per config" as a library call — the orchestration the CLI
+# wraps, returning a SignResult instead of writing files (openbadgeslib.issue).
+# Resolved lazily (PEP 562, below) because openbadgeslib.issue pulls in the
+# shared Badge model from the ob1 leaf module; a bare `import openbadgeslib`
+# must not drag that in. `from openbadgeslib.issue import ...` works directly.
+_ISSUE_API = ('IssuanceError', 'SignResult', 'issue_from_conf')
+
+
 # ── OpenBadges 1.0 (legacy) ──────────────────────────────────────────────────
 # The unprefixed OB1 names (Signer, Verifier, Badge, …) stay importable from
-# the top-level package for backward compatibility, but they are the legacy
-# OpenBadges 1.0 surface: accessing one now emits a DeprecationWarning
-# (removal in 4.0.0). Modern code uses openbadgeslib.ob2 / openbadgeslib.ob3.
-# They are resolved lazily from the ob1 leaf modules (PEP 562), so a bare
-# `import openbadgeslib` neither warns nor drags in the ob1 package.
+# the top-level package for backward compatibility. They are the legacy
+# OpenBadges 1.0 surface: accessing one emits a DeprecationWarning steering new
+# work to openbadgeslib.ob2 / openbadgeslib.ob3. OB 1.0 itself remains supported
+# (no removal planned). They are resolved lazily from the ob1 leaf modules (PEP
+# 562), so a bare `import openbadgeslib` neither warns nor drags in the ob1
+# package.
 _OB1_API = {
     'Signer': 'signer', 'Verifier': 'verifier', 'VerifyInfo': 'verifier',
     'Badge': 'badge', 'BadgeSigned': 'badge', 'Assertion': 'badge',
@@ -55,6 +65,11 @@ _OB1_API = {
 
 
 def __getattr__(name: str) -> Any:
+    if name in _ISSUE_API:
+        # The modern issuance API — lazy so a bare import stays ob1-free, but
+        # warning-free (unlike the OB1 names below).
+        import importlib
+        return getattr(importlib.import_module('.issue', __name__), name)
     module = _OB1_API.get(name)
     if module is None:
         raise AttributeError(
@@ -62,9 +77,9 @@ def __getattr__(name: str) -> Any:
     import importlib
     import warnings
     warnings.warn(
-        'openbadgeslib.%s is the legacy OpenBadges 1.0 API and is deprecated; '
-        'it will be removed in openbadgeslib 4.0.0. Use openbadgeslib.ob2 '
-        '(strict OB 2.0) or openbadgeslib.ob3 (OB 3.0). See the "OpenBadges '
-        '1.0 lifecycle" wiki page.' % name,
+        'openbadgeslib.%s is the legacy OpenBadges 1.0 API; prefer '
+        'openbadgeslib.ob2 (strict OB 2.0) or openbadgeslib.ob3 (OB 3.0) for '
+        'new work. OpenBadges 1.0 remains supported (no removal planned). See '
+        'the "OpenBadges 1.0 lifecycle" wiki page.' % name,
         DeprecationWarning, stacklevel=2)
     return getattr(importlib.import_module('.ob1.' + module, __name__), name)

{openbadgeslib-3.8.0 → openbadgeslib-3.10.0}/openbadgeslib/badge.py

@@ -8,10 +8,10 @@ from .ob1.badge import (
 )
 
 warnings.warn(
-    'openbadgeslib.badge is a legacy OpenBadges 1.0 compatibility shim and is '
-    'deprecated; it will be removed in openbadgeslib 4.0.0. Import from '
-    'openbadgeslib.ob2 (strict OB 2.0) or openbadgeslib.ob3 (OB 3.0) instead. '
-    'See the "OpenBadges 1.0 lifecycle" wiki page.',
+    'openbadgeslib.badge is a legacy OpenBadges 1.0 compatibility shim; prefer '
+    'openbadgeslib.ob2 (strict OB 2.0) or openbadgeslib.ob3 (OB 3.0) for new '
+    'work. OpenBadges 1.0 remains supported (no removal planned). See the '
+    '"OpenBadges 1.0 lifecycle" wiki page.',
     DeprecationWarning, stacklevel=2)
 
 __all__ = [