openbadgeslib 3.13.0__tar.gz → 4.0.0__tar.gz

openbadgeslib-4.0.0/CONTRIBUTING.md

@@ -0,0 +1,93 @@
+# Contributing to openbadgeslib
+
+Thanks for your interest in improving **openbadgeslib** — a library and CLI for
+issuing and verifying OpenBadges 2.0 and 3.0 credentials. This page is the quick
+entry point; the full developer guide lives in the wiki
+([Contributing](https://github.com/luisgf/openbadgeslib/wiki/Contributing),
+[Releasing](https://github.com/luisgf/openbadgeslib/wiki/Releasing)).
+
+## Reporting bugs and requesting capabilities
+
+- **Bugs:** open a [Bug report](https://github.com/luisgf/openbadgeslib/issues/new/choose).
+  Include the openbadgeslib version, your Python version, and a minimal
+  reproduction.
+- **Capabilities / features:** open a
+  [Capability request](https://github.com/luisgf/openbadgeslib/issues/new/choose).
+  This is also the **demand signal** the roadmap runs on — several planned items
+  are deliberately *built when someone asks for them with a concrete use case*,
+  so a well-described request genuinely moves them forward.
+- **Security vulnerabilities:** do **not** open a public issue. Follow
+  [SECURITY.md](SECURITY.md) (private GitHub advisory or email).
+
+## Development setup
+
+Requires a supported Python (see below). Everything runs from an editable
+virtual environment:
+
+```sh
+git clone https://github.com/luisgf/openbadgeslib
+cd openbadgeslib
+python3 -m venv .venv && source .venv/bin/activate
+pip install --upgrade pip
+pip install -e ".[dev]"          # add ,ldp and ,eudi to exercise those tracks
+```
+
+## The checks a pull request must pass
+
+CI runs these on Python 3.10–3.14; run them locally before opening a PR (via
+your `.venv`):
+
+```sh
+flake8 openbadgeslib tests       # style (max-line-length = 120, see setup.cfg)
+mypy                             # types (config in pyproject.toml)
+pytest                           # the suite; install [ldp]/[eudi] so their
+                                 # tests actually run instead of skipping
+```
+
+The Data Integrity (LDP) tests need the `[ldp]` extra (pyld) and the EUDI
+SD-JWT / X.509 tests need `[eudi]` — without them those tests silently
+`importorskip`, so install the extras when touching those areas. Coverage is
+enforced at a floor (currently 93%).
+
+## Commit messages
+
+Commits follow a [Conventional Commits](https://www.conventionalcommits.org/)
+style so the history is machine-readable and the changelog can be drafted from
+it — CI's `gitlint` check enforces the title format. The shape is
+`type(optional-scope)!: imperative summary` (≤ 80 chars), with the vocabulary:
+
+| Type | For | Changelog |
+| --- | --- | --- |
+| `feat` / `fix` / `security` / `perf` | user-facing change | **yes** |
+| `docs` / `test` / `refactor` / `chore` / `ci` / `build` / `style` | internal, no user-visible effect | no |
+| `release` | the version-bump/changelog commit | no |
+
+A `!` (or a `BREAKING CHANGE:` body trailer) marks a breaking change. A
+user-facing `feat`/`fix`/`security`/`perf` should add its `Changelog.txt` entry
+in the same commit (newest-first, under a `* vX.Y.Z - unreleased` header). See
+the wiki [Contributing](https://github.com/luisgf/openbadgeslib/wiki/Contributing)
+page for the full convention.
+
+## Supported Python versions
+
+openbadgeslib supports **every CPython release that is not end-of-life**. The
+policy is deliberately simple and predictable:
+
+- A version is **dropped** — from `requires-python`, the classifiers, and the CI
+  matrix — at the next **major** release after it reaches end-of-life. For
+  example, Python **3.10 (EOL 2026-10)** is dropped in **4.0.0**; until then it
+  stays supported. Grouping drops into majors keeps breaking changes rare.
+- A new CPython minor is **added** to the CI matrix once it has a stable
+  (non-pre) release, so downstreams can adopt it early.
+- The current matrix is **3.10–3.14**, and `requires-python = ">=3.10"`.
+
+Security fixes always target the latest release only (see
+[SECURITY.md](SECURITY.md)).
+
+## Governance and licensing
+
+Project governance, the release process, and the maintenance/continuity plan are
+in [GOVERNANCE.md](GOVERNANCE.md). The library is licensed under the LGPLv3 and
+the CLI entry points under BSD-2-Clause (see
+[LICENSE.txt](LICENSE.txt)); by contributing you agree your contribution is
+provided under those same terms.

{openbadgeslib-3.13.0 → openbadgeslib-4.0.0}/Changelog.txt

@@ -4,6 +4,372 @@ OpenBadgesLib - Changelog
 Newest first. Dates are ISO 8601 (YYYY-MM-DD).
 
 
+* v4.0.0 - 2026-07-22
+
+  Grouped breaking release (#170) — freeze the declared public contract and
+  unify the CLIs — shipped together with the Round-2 roadmap work: close the
+  revocation/trust gaps the deep-logic analysis surfaced, test the fail-closed
+  guards, and speed up batch issuance and verification. Breaking changes first,
+  then the rest of the cycle.
+
+  - fix(cli)!: unify every console tool on the 0/1/2 exit-code contract (#233).
+    The 19 `sys.exit(-1)` sites (which exited 255) now exit 1, and the verifier
+    applies the same status in human mode as under --json: 1 on any failure, 2
+    when the signature is valid but the issuer is not anchored (an OB2
+    badge-embedded key or a self-asserted did:key), and 0 only when the badge is
+    valid AND trusted. A partial batch sign or publish, and a stale/missing
+    artifact under `publish --check-live`, now exit 2 in human mode too (they
+    exited 1 before). BREAKING: a wrapper that keyed on 255, or that treated a
+    valid-but-untrusted badge's exit 0 as success, must be updated.
+  - feat(cli): add a unified `openbadges <command>` front-end and centralise the
+    shared flags (#234). A new `openbadgeslib/cli_common.py` provides argparse
+    parent parsers for -c/--config, -d/--debug, --json and -v/--version, which
+    all five build_parser()s now compose — so the flags are defined once with
+    consistent help. openbadges-publish gains -d/--debug (it had none) and
+    openbadges-init gains argparse (hence -v/--version, and -h now exits 0 via
+    argparse). The new `openbadges` entry point dispatches to init/keygen/sign/
+    verify/publish, each of which stays installed under its own openbadges-<name>
+    script; a command owns everything after its name, so `openbadges sign ...`
+    behaves exactly like `openbadges-signer ...`. Minor breaking: openbadges-init
+    with a bad/missing argument now exits 2 (argparse), not 1.
+  - feat(cli): add `openbadges status [ID]`, the sixth subcommand promised by
+    the unified front-end (#170). It is the read-only registry query that until
+    now was reachable only as `openbadges-publish -V 3 --list/--status`: with no
+    ID it tabulates every issued OB3 credential and its state, with one (a jti
+    or a recipient email) it prints that credential's full record including the
+    revocation reason. Auditing a credential is a read, so it no longer requires
+    typing a publish verb, nor `-V 3` — status lists are OB3-only by
+    construction. The query itself is not duplicated: the command and publish's
+    flags both call the shared `query_ob3()`, which now takes plain arguments
+    instead of a parsed argparse Namespace. `--list`/`--status` keep working
+    unchanged. Unlike the other five commands this one has no standalone
+    `openbadges-status` script — those aliases exist only because they predate
+    the front-end.
+  - refactor(ob1)!: consolidate the OB1 compatibility surface (#235). The OB1
+    legacy name table (11 names -> leaf module) is single-sourced in
+    openbadgeslib/_ob1_api.py instead of being duplicated between the top-level
+    package and openbadgeslib.ob1. The three top-level shim modules —
+    openbadgeslib.badge, openbadgeslib.signer and openbadgeslib.verifier — are
+    removed. OpenBadges 1.0 stays fully supported and reachable via
+    openbadgeslib.ob1.* (e.g. `from openbadgeslib.ob1 import Signer`) and the
+    unprefixed openbadgeslib.Signer / .Badge / … re-exports, both of which still
+    emit the steering DeprecationWarning. BREAKING: `from openbadgeslib.badge
+    import ...` (and .signer/.verifier) no longer resolve — repoint them to
+    `openbadgeslib.ob1.<module>`.
+  - refactor(keys)!: drop the last pycryptodome / python-ecdsa soft-import
+    (#170). Both libraries stopped being dependencies in the 3.7 port (#167),
+    but `key_to_pem` kept a soft-import shim that still accepted a *live*
+    pycryptodome RSA or python-ecdsa key object. That shim (`_legacy_key_to_pem`)
+    is removed, along with the `Crypto.*`/`ecdsa.*` mypy overrides: `key_to_pem`
+    now takes only `cryptography` key objects and PEM bytes/str, raising
+    `UnknownKeyType` otherwise. Key *files* are unaffected — they were already
+    plain PEM and round-trip unchanged. BREAKING: pass a `cryptography` key
+    object or PEM instead of a live pycryptodome/python-ecdsa object.
+
+  - fix(ob3): bundle and reference the OB v3p0 extensions context so the
+    `credentialSchema` type (`1EdTechJsonSchemaValidator2019`, emitted since
+    v3.6.0) resolves to a defined JSON-LD term. Without it the term was
+    undefined: the official 1EdTech OB3 validator rejected every issued
+    credential ("Undefined JSON-LD term") and canonicalization mapped the type
+    to a base-relative IRI, so the Data Integrity proof no longer verified. The
+    offline JSON-Schema gate did not catch this (it checks the string, not
+    JSON-LD term resolution). Issued credentials now carry a third `@context`
+    entry (the official schema pins only the first two and allows extras); the
+    context is pinned in the fail-closed allowlist and covered by the drift
+    watchdog (#239).
+  - security(config): close the bypass in the userinfo guard below: checking
+    `urlsplit(...).netloc` only catches a credential whose `@` lands inside the
+    authority, and a password holding a `/`, `?` or `#` pushes it out. Both
+    layers accepted `https://user:12345/x@host/` — which `did_web_from_url`
+    then turned into the issuer id `did:web:user%3A12345:x%40host`, carried by
+    every signed credential — and `https://user:secret/x@host/`, which surfaced
+    the password through urllib's own `Port could not be cast to integer value
+    as 'secret'` (a message the redaction added below could not reach, since
+    urllib raises it). Both layers now refuse an `@` or `%40` *anywhere* in a
+    URL-shaped value, and `did_web_from_url` wraps the port parse and quotes
+    nothing at all. Values with no authority — `[issuer] email`, local paths —
+    still accept an `@`. BREAKING (narrow): a `publish_url` whose path contains
+    an `@`, e.g. `https://host/@name/`, is now refused; once parsed it is
+    indistinguishable from one hiding a credential (#255).
+  - security(config): reject a `[issuer]` / `[badge_*]` URL that embeds
+    userinfo (`https://user:password@host/`) when the config is loaded. Those
+    URLs are public identifiers: `publish_url` is printed by every publish
+    command, `urljoin`ed into the ids written to the publicly served
+    organization.json / badge.json / key.json (urljoin preserves the
+    `user:pass@`), turned into the issuer's did:web, and used to build the
+    `credentialStatus` list URLs signed into every OB3 credential — so a
+    password there leaked into user-visible output, files served on the open
+    web and the badges delivered to recipients alike. Only one narrow path
+    guarded against it (did:web derivation, reached solely by
+    `[issuer] did = auto`), and that guard echoed the password back in its own
+    error for a non-https URL. The check now lives once in
+    `ConfParser.read_conf()` — after `${...}` interpolation, so a reference
+    cannot smuggle a credential past it — and every consumer (OB1/OB2/OB3
+    publishing, DID derivation, status lists) inherits it; the ConfigError
+    names the offending section and key but never the value. `did_web_from_url`
+    keeps its own guard as defence in depth, with the userinfo check moved
+    ahead of the scheme and host checks and their messages redacted. Behaviour
+    change: a config that protected a staging host with credentials in a
+    published URL no longer loads — drop the userinfo and use an allow-list or
+    a token the library never sees. `[smtp] username` / `password` are
+    untouched; they never leave the issuer's machine (#252).
+  - security(eudi): document and pin the X.509 / eIDAS trust boundary for
+    SD-JWT VC verification. All x5c chain validation is delegated to openvc-core
+    (path building, temporal validity, SAN<->iss binding); openbadgeslib only
+    guarantees the envelope (the x5c header is present, so the anchors are never
+    bypassed by a DID fallback — fail-closed). Crucially, certificate revocation
+    (CRL/OCSP) is NOT checked by either layer — a revoked-but-unexpired leaf
+    still verifies — so a deployment must apply revocation out of band. The
+    division of responsibility is spelled out on `verify_badge_sd_jwt` and the
+    Security Model wiki page; new boundary tests assert openvc-core rejects an
+    expired/not-yet-valid leaf and pin the revocation gap, and the eudi
+    floor/latest CI job now runs them so a drift in the delegate's behaviour
+    turns the build red (#236).
+  - security(ob3): with `--check-status`, verify the status list's OWN JWT-VC
+    signature by default and bind its issuer to the badge's, so a compromised
+    status host can no longer silently un-revoke a credential. The badge's
+    verification key is reused (publish signs the list with it), or the issuer
+    DID is resolved. `verify(check_status=True)` gains `verify_status_list=True`
+    by default; the verifier CLI gains `--no-verify-status-list` to opt out for
+    issuers that serve an unsigned list (#213).
+  - security(ob3): `OB3LdpVerifier` fails closed when it has no pinned key and
+    the credential's issuer is not a DID — the proof's `verificationMethod`
+    cannot be bound to a non-DID issuer, so resolving and trusting it would
+    prove internal consistency, not identity (#214).
+  - security(ob3): the endorsement validity window fails closed on a malformed
+    `validFrom`/`validUntil` (it previously swallowed the parse error and
+    accepted the endorsement, unlike every other window) (#218).
+  - fix(ob2, ob3): apply a 60-second clock-skew leeway to every validity window
+    (vc `validFrom`/`validUntil`, the status list window, OB2 `issuedOn`/
+    `expires`), so a slightly-fast issuer clock no longer false-rejects a
+    freshly issued credential (#217).
+  - perf(ob3, ob1): load the private-key object once per signer instead of
+    re-parsing the PEM on every signature (twice per badge on the JWT-VC path).
+    An RSA batch of 1000 badges drops from ~86 s to ~1.5 s; the OB1/OB2 JWS
+    path reuses the already-loaded key too (#215).
+  - perf(baking): build the baked PNG with a single `b''.join` instead of
+    quadratic `bytes` concatenation — ~200x faster on images written with many
+    small IDAT chunks (Photoshop/libpng), e.g. ~100 ms -> ~0.5 ms for 6.6 MB
+    (#216).
+  - test: add negative tests for the fail-closed rejection guards that had none
+    — OB2 hosted `startsWith`/`allowedOrigins` reject sides, the OB3 status
+    anti-gzip-bomb cap and negative index, the LDP verificationMethod binding,
+    and a future JWT `nbf` (#219).
+  - ci: the nightly conformance job now fails if a 1EdTech validator does not
+    come up or if no conformance test actually ran (all-skipped), instead of
+    reporting green, and files (or updates) an issue on a scheduled failure
+    (#220).
+  - ci: install the `[ldp-sd]` extra explicitly and turn the ecdsa-sd-2023
+    selective-disclosure test skip into a hard failure under CI, so an
+    openvc-core packaging change can no longer silently disable that suite
+    (#221).
+  - perf(ob3): add an opt-in `CachingDownloader` so verifying a batch of
+    credentials from one issuer fetches each did:web document and status list
+    once rather than per credential. `OB3LdpVerifier` also memoizes each
+    resolved `verificationMethod` per instance, and `OB3Verifier.verify` /
+    `check_status` accept a `download=` fetcher to thread it through (#228).
+  - perf(ob3): tag the bundled JSON-LD `@context`s `static` in the pyld
+    document loader, priming pyld's process-global resolved-context cache so
+    term definitions are not rebuilt on every canonicalization (~1.6x faster
+    Data Integrity sign/verify); per-call `extra_contexts` stay untagged so a
+    changing context is never served stale (#229).
+  - feat: extract a programmatic verification facade — `openbadgeslib.verify`
+    with `verify_badge(data, ob_version, *, pubkey_pem | resolve_did,
+    expected_recipient, check_status, …) -> VerifyResult` (fields `valid`,
+    `trusted`, and the decoded `credential`/`assertion`). It runs the whole
+    verification — token extraction, JWT-VC/LDP auto-detection, issuer-DID
+    resolution, trust classification, signature/status — doing no I/O; an
+    invalid badge is a result, not an exception. `openbadges-verifier` is now a
+    thin presenter over it (byte-identical output). Part of #222.
+  - feat: extract a programmatic publication facade —
+    `openbadgeslib.ob3.publish_ob3(conf, output, *, revoke | suspend |
+    unsuspend, reason, badge, check_live) -> PublishResult`. It runs the OB3
+    issuer-artefact regeneration (the did:web document, the signed Bitstring
+    Status List credentials, the opt-in SD-JWT VC Type Metadata) and the
+    status-registry revoke/suspend/unsuspend transaction — writing the
+    artefacts but doing no printing — and raises `PublishError` /
+    `CredentialNotFound` / `AmbiguousCredential` instead of exiting.
+    `openbadges-publish -V 3` is now a thin presenter over it (byte-identical
+    output). Completes #222.
+  - fix(issue): move the version-neutral badge config model (`Badge`,
+    `BadgeImgType`) out of the legacy `ob1` package into
+    `openbadgeslib.badge_model` (re-exported from `ob1.badge` for
+    compatibility). `create_from_conf` now reads the OpenBadges 1.0-only
+    `verify_key`/`criteria` keys optionally, so issuing an OB3 badge that omits
+    them no longer blows up with a raw `KeyError('verify_key')`; a missing
+    required key surfaces as `IssuanceError` through the `issue_*` entry points,
+    and a missing image raises a typed error instead of `print` + bare
+    `IOError` (#223).
+  - refactor(errors): consolidate the exception hierarchy so a single
+    `except LibOpenBadgesException` traps every library error. `IssuanceError`
+    and `DecompressionLimitExceeded` are re-anchored under the root (still
+    importable from `openbadgeslib.issue` / `openbadgeslib.baking`); the config
+    helpers' bare `ValueError`s become a new `ConfigError` and the signers'
+    unsupported-algorithm error becomes `UnsupportedAlgorithm` — both also
+    subclass `ValueError` so `except ValueError` callers keep working.
+    `_write_badge_and_log` reads the `[logs]` path inside its `try`, so a missing
+    `[logs]` section is reported instead of crashing with a traceback after the
+    badge is already on disk. Adds singular aliases (`KeyGenException`,
+    `SignerException`, `VerifierException`) for the plural base families (#224).
+  - refactor(ob2, ob3): deduplicate the shared JSON helpers (`_iso`,
+    `_parse_iso`, `_as_dict`, `_require`) into an internal
+    `openbadgeslib._jsonmodel`. The two copies had drifted: OB2's `_iso`
+    serialised a naive datetime as *local* time (`astimezone` on a naive value)
+    while OB3 anchored it to UTC, so the same timestamp emitted a different
+    instant in OB2 than in OB3; the single implementation keeps OB3's
+    naive=>UTC rule (#225).
+  - feat(confparser): resolve config through typed dataclasses with centralized
+    defaults. `load_config(path) -> ConfigParser` is the library entry point
+    (raises `ConfigError`); `read_config_or_exit` is now a thin CLI wrapper over
+    it (and the flagship example uses `load_config`). New `IssuerConfig` /
+    `BadgeSectionConfig` dataclasses (extending the `OB3StatusConfig` pattern)
+    resolve the `[issuer]` and badge sections and their defaults once (issuer id,
+    `criteria_narrative`->`criteria` fallback, hosted-assertions base), and a
+    single `DEFAULT_KEY_TYPE` + `resolve_key_type()` centralises the key_type
+    name->KeyType mapping the keygenerator used to inline (#225).
+  - security(ob3): warn loudly when `openbadges-publish -V 3` regenerates a
+    revocable badge's status lists without a `validUntil` bound (no
+    `status_validity_days` set). An unbounded list has no anti-replay freshness —
+    an authentic older copy with fewer revocations passes the window unchecked,
+    so a revoked credential could be silently resurrected. `PublishResult` gains
+    a `no_validity_bound` list (surfaced in the CLI's human output and `--json`),
+    and the config example documents the republication cadence (#227).
+  - security(ob3): SD-JWT VC (EUDI) issuance no longer silently drops a
+    credential's `credentialStatus`. Because SD-JWT VC status carriage/checking
+    is not wired yet (both verify paths hard-set `require_status=False`), an
+    SD-JWT VC badge is irrevocable; `issue_badge_sd_jwt` now rejects a credential
+    that carries a `credentialStatus` with a clear `EudiError` (before requiring
+    the [eudi] extra) rather than issue a badge the issuer believes is revocable.
+    `badge_to_sd_jwt_claims` also carries `credentialSubject.identifier` (the
+    hashed recipient identities), so a badge whose subject travelled via
+    `identifier` (no `id`) keeps a checkable recipient. The irrevocability is
+    documented prominently on the issue/verify docstrings (#226).
+  - security(util): pin the SSRF-validated IP on the HTTPS connection to defeat
+    DNS rebinding. `_assert_public_host` validated the resolved IPs, but
+    `opener.open` then re-resolved on its own, so a hostile DNS (TTL 0) could
+    answer public during the check and internal (169.254.169.254 / loopback /
+    RFC1918) at the real connect. A new `_PinnedHTTPSConnection` re-resolves,
+    re-validates and dials the validated IP in one step (keeping the hostname
+    for TLS SNI / certificate verification and the Host header) — for the initial
+    request and every redirect. Also adds a wall-clock download budget
+    (`MAX_DOWNLOAD_SECONDS`, 60 s), since the per-socket `timeout=30` bounds each
+    read but not a slow-drip response's total time (#231).
+  - ci: harden the release-critical workflows. SHA-pin the actions that run with
+    `id-token: write` — `pypa/gh-action-pypi-publish` (PyPI Trusted Publishing)
+    and the GitHub Pages `upload-pages-artifact` / `deploy-pages` — so a
+    compromised upstream tag cannot publish or deploy under our OIDC identity
+    (Dependabot already tracks github-actions and bumps the pins). Add a
+    least-privilege `permissions: contents: read` to commit-lint.yml. Add a
+    `windows-latest` CI leg plus a monkeypatched test of the `fcntl=None`
+    StatusRegistry lock fallback, so the "OS Independent" classifier is actually
+    exercised on the non-POSIX path. The leg immediately caught a real
+    portability bug it fixes: `openbadges-publish` now records `files_written`
+    with forward slashes (a Windows `\` would have broken the artefact URLs built
+    via `urljoin`); the POSIX file-mode assertions skip on Windows and the
+    ldp-sd hard-fail guard keys on an explicit `OPENBADGES_REQUIRE_LDP_SD` flag
+    (set by the main test job) so the core-only Windows leg skips it (#230).
+  - refactor: declare the stable public surface (freeze prep for v4). The root
+    package gains an explicit `__all__` (the "public contract"), re-exports
+    `KeyEd25519` (the recommended OB 3.0 / LDP key) alongside `KeyRSA`/`KeyECC`,
+    and exposes the `ob2`/`ob3`/`errors` subpackages and the
+    `issue_from_conf`/`verify_badge` facades by name. `openbadgeslib.ob3`
+    re-exports the `eudi` SD-JWT VC track (its heavy imports stay lazy).
+    `SignResult.credential`/`.assertion` and the `_Ob3Context` fields are typed
+    with `TYPE_CHECKING` forward refs instead of `Any` (zero runtime cost,
+    correct autocompletion / pdoc). Adds a "Stable API" wiki page documenting
+    the stable-vs-internal boundary (#232).
+  - build(deps): the [dev] extra depends on gitlint-core instead of the gitlint
+    meta-package, so it stops installing vulnerable pins. `gitlint` is an empty
+    shim for `gitlint-core[trusted-deps]`, and that extra hard-pins click==8.1.3
+    and sh==1.14.3 — PYSEC-2026-2132 (command injection in `click.edit()`, fixed
+    in 8.3.3) and CVE-2026-54552 (incomplete privilege drop in sh's `_uid`, fixed
+    in 2.2.4), which had been failing the weekly Audit job. Neither is reachable
+    here — gitlint never calls `click.edit()`, and it does not import `sh` at all
+    unless GITLINT_USE_SH_LIB=1, which this repo never sets — but upstream has
+    been dormant since 2023, so the pins would keep the audit red indefinitely.
+    gitlint-core declares the same dependencies loosely and provides the same
+    `gitlint` console script; the [dev] extra now floors `click>=8.3.3` and
+    `sh>=2.2.4` (keeping gitlint-core's non-Windows marker for sh) and caps both
+    below the next major. No pip-audit ignores were added: the advisories are
+    resolved by upgrading, not suppressed. Library users are unaffected — click
+    and sh were only ever development dependencies.
+  - build(deps)!: raise the PyJWT floor to >=2.13 and the openvc-core floors to
+    >=1.21. The OB3 JWT-VC verifier decodes an untrusted badge with a
+    signature-verifying `jwt.decode()`, so the PyJWT 2.12/2.13 advisory batch is
+    on a reachable path: RFC 7515 §4.1.11 `crit` validation (2.12.0,
+    CVE-2026-32597) and the b64=false unencoded-payload DoS (2.13.0,
+    CVE-2026-48525), plus JWK/alg-binding hardening; 2.13.0 is the minimal floor
+    carrying all of them. Installing [eudi]/[ldp-sd] already pulled a safe PyJWT
+    transitively via openvc-core (whose own floor is >=2.13), so this closes the
+    gap for a base, extras-free install. The native `_jws` engine is structurally
+    immune (it never calls `jwt.decode`). The [eudi]/[ldp-sd] openvc-core floors
+    move from >=1.18 / >=1.13 to >=1.21 per the pin's stated policy (floor at the
+    version the suite is tested against): 1.21 keeps in-floor the delegated
+    SD-JWT fixes openbadgeslib relies on — the key-binding replay fix that now
+    requires a nonce AND audience (1.19.3) and unknown-`crit` rejection on the
+    SD-JWT lane (1.20.4). No openbadgeslib code changed: openvc's new typed
+    ecdsa-sd errors (ProofValueMalformed/ProofMalformed) subclass ProofError, so
+    the existing `except ProofError` in ob3/ldp.py still catches them; the full
+    suite passes against openvc-core 1.21.0. BREAKING only for a caller that
+    pinned PyJWT <2.13 or openvc-core <1.21 alongside openbadgeslib.
+  - security(cli): `openbadges-init` creates config.ini owner-only (0600). It
+    is the file that goes on to hold the SMTP password and the paths to the
+    private keys, but the copy ran outside the umask block that hardens the
+    directories, so it inherited the caller's umask — 0644 on a default shell.
+    The 0700 parent contained it; this is the second lock, matching the one
+    the keygenerator puts on the private key.
+
+
+* v3.14.0 - 2026-07-10
+
+  A security & correctness hardening pass (audit-bot). Highlights:
+
+  - security(eudi): reject an X.509-anchored SD-JWT verification whose issuer
+    JWT carries no `x5c` chain, so openvc-core cannot fall back to DID /
+    issuer-URL key resolution and bypass the EU trust anchors (#186).
+  - security(ob3): reject a Data Integrity credential carrying the unsigned VC
+    1.1 aliases `expirationDate`/`issuanceDate` or a legacy `StatusList2021Entry`
+    status — the RDF-canonicalized proof cannot cover them, so a holder could
+    otherwise un-expire / un-revoke a signed credential (#205).
+  - security(ob2): reconcile a hosted badge's `expires` against the authoritative
+    fetched copy, so a stripped/extended local `expires` no longer defeats the
+    expiration check (#187).
+  - security(ob3): read `statusSize` from the BitstringStatusListEntry and fail
+    closed on a multi-bit entry, so a revoked/suspended multi-bit credential is
+    no longer misreported as valid (#188).
+  - security(mail): give `SMTP_SSL` a validating TLS context (check_hostname +
+    CERT_REQUIRED), so the badge-delivery client no longer exposes its SMTP AUTH
+    credentials to an on-path attacker (#203).
+  - fix(cli): `openbadges-verifier` exits non-zero in human mode when an OB1/OB2
+    badge is invalid (was exit 0), matching OB3 and `--json` (#189).
+  - fix(cli): `openbadges-signer` surfaces a partial-batch exit code in human
+    mode (#191); `-H/--hosted` is rejected outside `-V 2` (#206); a badge section
+    missing `private_key`/`public_key` yields a clean error (#210).
+  - fix(cli): `openbadges-init -h/--help` prints usage and exits 0 instead of
+    creating a directory named `--help` (#207).
+  - fix(issue): a baking failure surfaces as `IssuanceError` on the vc-jwt/OB2
+    paths (#190), and a missing `[issuer]`/config key does too (#208).
+  - fix(publish): isolate a per-badge key failure in status-list regeneration so
+    one bad badge no longer aborts the whole publish (#192).
+  - fix(ob3): a non-string Data Integrity `proof.created`/`expires` raises
+    `OB3VerificationError` instead of a raw `AttributeError` (#193).
+  - fix(ob2): accept an embedded `CryptographicKey` object in a Profile's
+    `publicKey` (#194).
+  - fix(confparser): reject a `status_size_bits` that is not a positive multiple
+    of 8 as a clean config error (#204).
+  - fix(keygenerator): switch on debug logging at the start of the run, so `-d`
+    also covers config reading and validation — not just the tail of key
+    generation, where `enable_debug_logging` used to sit.
+  - docs: announce the 4.0.0 deprecation window ahead of the release — a new
+    "Upgrading to 4.0" wiki page (dropped Python 3.10, the unified 0/1/2
+    exit-code contract, the removed pycryptodome/python-ecdsa compat) linked
+    from the sidebar, plus a README heads-up.
+  - feat(eudi): `issue_badge_sd_jwt` can embed an `x5c` certificate chain, so a
+    badge SD-JWT VC is issued anchored on X.509 and verified in one call with
+    `verify_badge_sd_jwt(..., x5c_trust_anchors=[…])` — the issue-side
+    counterpart of the verify-side x5c trust (#178), for eIDAS / EU Trusted
+    List anchoring. Raises the [eudi] openvc-core floor to >=1.18.
+
 * v3.13.0 - 2026-07-09
 
   - feat(eudi): **opt-in X.509 / EU Trusted List trust for received SD-JWT

openbadgeslib-4.0.0/GOVERNANCE.md

@@ -0,0 +1,72 @@
+# Governance
+
+How **openbadgeslib** is maintained, released, and kept available. It is a small
+project with a clear, lightweight process — written down here because third
+parties already depend on it to *verify* credentials, so continuity matters.
+
+## Maintainership
+
+openbadgeslib is actively maintained by **Luis González Fernández**
+(`luisgf@luisgf.es`), the single active maintainer, who decides on scope,
+roadmap, and releases. The project has a historical co-author, Jesús Cea Avión,
+credited in the copyright headers and
+[Authors, License and FAQ](https://github.com/luisgf/openbadgeslib/wiki/Authors-License-and-FAQ);
+active maintenance today is solo.
+
+Decision-making is lightweight: the roadmap is tracked as GitHub issues (label
+`roadmap`, tracking issue
+[#175](https://github.com/luisgf/openbadgeslib/issues/175)), and several items
+are built on demand — a [capability request](CONTRIBUTING.md) with a concrete
+use case is how they get prioritised.
+
+## Releasing and publishing
+
+Releases are **CI-driven and credential-less to publish**:
+
+- The version is single-sourced in `openbadgeslib/util.py`; a pushed `vX.Y.Z`
+  tag triggers the CI workflow, which runs the full test matrix (Python
+  3.10–3.14) and then publishes to
+  [PyPI](https://pypi.org/project/openbadgeslib/).
+- Publishing uses **PyPI Trusted Publishing (OIDC)** — there is **no long-lived
+  PyPI API token** stored anywhere. The publish job authenticates to PyPI from
+  GitHub Actions via a short-lived OIDC token, so there is no release secret to
+  leak, rotate, or lose.
+- Each release is announced as a **GitHub Release** with curated notes drawn
+  from `Changelog.txt`; the Release is the canonical announcement channel.
+- The **human fallback** (a maintainer cutting a release by hand) is fully
+  documented in the wiki
+  [Releasing](https://github.com/luisgf/openbadgeslib/wiki/Releasing) runbook —
+  it needs only repository write access plus the CI pipeline, no personal
+  credentials.
+
+## Bus factor and continuity
+
+A single active maintainer is a real risk for a library others verify with. The
+mitigations are deliberate:
+
+1. **No secret is a single point of failure.** Trusted Publishing means losing
+   access to a token cannot happen — there isn't one. Publishing is bound to the
+   GitHub repository's identity, not a person's stored key.
+2. **The whole release process is documented and automated** (the wiki Releasing
+   runbook and the `release` skill), so anyone with repository access can ship a
+   fix without tribal knowledge.
+3. **Handover requirements are explicit.** Taking over maintenance needs two
+   grants: **GitHub** repository admin, and **PyPI** owner/maintainer on the
+   [`openbadgeslib` project](https://pypi.org/project/openbadgeslib/) plus the
+   configured Trusted Publisher. A new maintainer with both can release
+   immediately.
+
+**Recommended hardening (maintainer action):** add a second **PyPI project
+owner** and a backup **GitHub admin** so a bus event does not strand the
+project. Until then, note that everything published stays available on PyPI
+indefinitely, and the LGPLv3 permits anyone to fork and continue the work.
+
+If the project were to become unmaintained, the last release remains installable
+from PyPI, and this document plus the wiki are enough for a fork to pick it up.
+
+## Reporting and contact
+
+- Bugs and capability requests: GitHub issues (see [CONTRIBUTING.md](CONTRIBUTING.md)).
+- Security vulnerabilities: **privately**, per [SECURITY.md](SECURITY.md) — never
+  a public issue.
+- General contact: `luisgf@luisgf.es`.

{openbadgeslib-3.13.0/openbadgeslib.egg-info → openbadgeslib-4.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openbadgeslib
-Version: 3.13.0
+Version: 4.0.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
@@ -30,22 +30,24 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
 Requires-Dist: pypng>=0.20220715.0
-Requires-Dist: PyJWT[crypto]>=2.8
+Requires-Dist: PyJWT[crypto]>=2.13
 Requires-Dist: cryptography>=42
 Requires-Dist: defusedxml>=0.7
 Provides-Extra: ldp
 Requires-Dist: pyld>=2.0.4; extra == "ldp"
 Provides-Extra: eudi
-Requires-Dist: openvc-core<2,>=1.13; extra == "eudi"
+Requires-Dist: openvc-core<2,>=1.21; extra == "eudi"
 Provides-Extra: ldp-sd
-Requires-Dist: openvc-core[data-integrity]<2,>=1.13; extra == "ldp-sd"
+Requires-Dist: openvc-core[data-integrity]<2,>=1.21; extra == "ldp-sd"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-cov>=5.0; extra == "dev"
 Requires-Dist: flake8>=7.0; extra == "dev"
 Requires-Dist: pdoc>=14; extra == "dev"
 Requires-Dist: mypy>=1.8; extra == "dev"
-Requires-Dist: gitlint>=0.19; extra == "dev"
+Requires-Dist: gitlint-core>=0.19; extra == "dev"
+Requires-Dist: click<9,>=8.3.3; extra == "dev"
+Requires-Dist: sh<3,>=2.2.4; sys_platform != "win32" and extra == "dev"
 Requires-Dist: jsonschema[format-nongpl]>=4.20; extra == "dev"
 Dynamic: license-file
 
@@ -64,6 +66,8 @@ with W3C Bitstring Status Lists and `did:web`. It also ships strict
 **OpenBadges 2.0** (JWS / hosted assertions) and a frozen **OpenBadges 1.0**
 legacy format, selected with `-V {1,2,3}` (default `3`).
 
+> **Heads-up — 4.0.0 is coming.** Timed to Python 3.10's end of life (2026-10), the next major groups a few breaking changes: Python 3.10 is dropped (`requires-python >= 3.11`), the CLIs unify on one `0/1/2` exit-code contract, and the legacy pycryptodome/python-ecdsa compat shim is removed. OpenBadges 1.0 and the `openbadges-<command>` scripts stay. See **[Upgrading to 4.0](https://github.com/luisgf/openbadgeslib/wiki/Upgrading-to-4.0)** before pinning a major.
+
 ## Features
 
 - Sign badge images (SVG and PNG) as strict OB 2.0 JWS / hosted assertions (with a frozen OB 1.0 legacy format)
@@ -348,6 +352,16 @@ flake8 openbadgeslib tests      # lint
 mypy                            # type check (config in pyproject.toml)
 ```
 
+## Contributing
+
+Bug reports,
+[capability requests](https://github.com/luisgf/openbadgeslib/issues/new/choose)
+(the roadmap's demand signal), and pull requests are welcome — see
+[`CONTRIBUTING.md`](CONTRIBUTING.md) for the workflow and the supported-Python
+policy, and [`GOVERNANCE.md`](GOVERNANCE.md) for maintenance and release
+governance. Security issues go through [`SECURITY.md`](SECURITY.md), never a
+public issue.
+
 ## Changelog
 
 See [`Changelog.txt`](Changelog.txt) for the full history, and the

{openbadgeslib-3.13.0 → openbadgeslib-4.0.0}/README.md

@@ -13,6 +13,8 @@ with W3C Bitstring Status Lists and `did:web`. It also ships strict
 **OpenBadges 2.0** (JWS / hosted assertions) and a frozen **OpenBadges 1.0**
 legacy format, selected with `-V {1,2,3}` (default `3`).
 
+> **Heads-up — 4.0.0 is coming.** Timed to Python 3.10's end of life (2026-10), the next major groups a few breaking changes: Python 3.10 is dropped (`requires-python >= 3.11`), the CLIs unify on one `0/1/2` exit-code contract, and the legacy pycryptodome/python-ecdsa compat shim is removed. OpenBadges 1.0 and the `openbadges-<command>` scripts stay. See **[Upgrading to 4.0](https://github.com/luisgf/openbadgeslib/wiki/Upgrading-to-4.0)** before pinning a major.
+
 ## Features
 
 - Sign badge images (SVG and PNG) as strict OB 2.0 JWS / hosted assertions (with a frozen OB 1.0 legacy format)
@@ -297,6 +299,16 @@ flake8 openbadgeslib tests      # lint
 mypy                            # type check (config in pyproject.toml)
 ```
 
+## Contributing
+
+Bug reports,
+[capability requests](https://github.com/luisgf/openbadgeslib/issues/new/choose)
+(the roadmap's demand signal), and pull requests are welcome — see
+[`CONTRIBUTING.md`](CONTRIBUTING.md) for the workflow and the supported-Python
+policy, and [`GOVERNANCE.md`](GOVERNANCE.md) for maintenance and release
+governance. Security issues go through [`SECURITY.md`](SECURITY.md), never a
+public issue.
+
 ## Changelog
 
 See [`Changelog.txt`](Changelog.txt) for the full history, and the