openbadgeslib 3.14.0__tar.gz → 4.0.0__tar.gz

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

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

{openbadgeslib-3.14.0 → openbadgeslib-4.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openbadgeslib
-Version: 3.14.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.18; 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
 

{openbadgeslib-3.14.0 → openbadgeslib-4.0.0}/openbadgeslib/__init__.py

@@ -23,6 +23,13 @@
 
 from typing import Any
 
+# ── Submodule entry points ───────────────────────────────────────────────────
+# Bind ob2 / ob3 / errors as attributes so they are part of the explicit public
+# surface (and `from openbadgeslib import *`): ob2 (strict OB 2.0), ob3 (OB 3.0,
+# incl. ob3.eudi and ob3.OB3Ldp*), and the errors hierarchy rooted at
+# LibOpenBadgesException.
+from . import ob2, ob3, errors  # noqa: F401
+
 # ── OpenBadges 2.0 (strict) ──────────────────────────────────────────────────
 from .ob2 import (  # noqa: F401
     OB2Signer, OB2Verifier, OB2VerificationError,
@@ -35,17 +42,26 @@ from .ob3 import (  # noqa: F401
 )
 
 # ── Shared utilities ────────────────────────────────────────────────────────────
-from .keys import KeyFactory, KeyRSA, KeyECC  # noqa: F401
+# KeyEd25519 is the recommended key type for OB 3.0 / LDP (eddsa-rdfc-2022).
+from .keys import KeyFactory, KeyRSA, KeyECC, KeyEd25519  # noqa: F401
 from .util import __version__  # noqa: F401
 
+# The OB1 legacy name table, shared with openbadgeslib.ob1 (single source,
+# #235). Importing it is cheap and does not pull in the ob1 subpackage, so a
+# bare `import openbadgeslib` stays ob1-free (see __getattr__ below).
+from ._ob1_api import OB1_API as _OB1_API  # 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')
+# ── Issuance / verification API ──────────────────────────────────────────────
+# "Issue badge X to Y per config" / "verify this badge" as library calls — the
+# orchestration the CLIs wrap, returning a SignResult / VerifyResult instead of
+# doing I/O (openbadgeslib.issue, openbadgeslib.verify). Resolved lazily (PEP
+# 562, below) so a bare `import openbadgeslib` stays lightweight;
+# `from openbadgeslib.issue import ...` / `.verify import ...` work directly.
+_ISSUE_API = {
+    'IssuanceError': 'issue', 'SignResult': 'issue', 'issue_from_conf': 'issue',
+    'verify_badge': 'verify',
+}
 
 
 # ── OpenBadges 1.0 (legacy) ──────────────────────────────────────────────────
@@ -54,22 +70,17 @@ _ISSUE_API = ('IssuanceError', 'SignResult', 'issue_from_conf')
 # 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',
-    'BadgeStatus': 'badge', 'BadgeImgType': 'badge', 'BadgeType': 'badge',
-    'extract_svg_assertion': 'badge', 'extract_png_assertion': 'badge',
-}
+# 562) using the shared _OB1_API table imported above, so a bare
+# `import openbadgeslib` neither warns nor drags in the ob1 package.
 
 
 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).
+        # The modern issuance / verification API — lazy so a bare import stays
+        # lightweight, but warning-free (unlike the OB1 names below).
         import importlib
-        return getattr(importlib.import_module('.issue', __name__), name)
+        return getattr(
+            importlib.import_module('.' + _ISSUE_API[name], __name__), name)
     module = _OB1_API.get(name)
     if module is None:
         raise AttributeError(
@@ -83,3 +94,24 @@ def __getattr__(name: str) -> Any:
         'the "OpenBadges 1.0 lifecycle" wiki page.' % name,
         DeprecationWarning, stacklevel=2)
     return getattr(importlib.import_module('.ob1.' + module, __name__), name)
+
+
+# The stable, supported top-level surface (the "public contract" — see the
+# "Stable API vs internals" wiki/doc page). Everything else (the ob1.* legacy
+# names resolved lazily above, and any underscore-prefixed name) is internal.
+# The issuance/verification facades are resolved lazily by __getattr__ but are
+# part of the contract, so they are listed here for pdoc and `import *`.
+__all__ = [
+    '__version__',
+    # Subpackage entry points.
+    'ob2', 'ob3', 'errors',
+    # OpenBadges 2.0 (strict).
+    'OB2Signer', 'OB2Verifier', 'OB2VerificationError',
+    # OpenBadges 3.0.
+    'OB3Signer', 'OB3Verifier', 'OB3VerificationError',
+    'OpenBadgeCredential', 'Achievement', 'Issuer',
+    # Keys (KeyEd25519 is the recommended OB 3.0 / LDP key type).
+    'KeyFactory', 'KeyRSA', 'KeyECC', 'KeyEd25519',
+    # Programmatic issue / verify facades (resolved lazily).
+    'issue_from_conf', 'verify_badge', 'IssuanceError', 'SignResult',
+]

openbadgeslib-4.0.0/openbadgeslib/_jsonmodel.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""
+        OpenBadges Library
+
+        Copyright (c) 2014-2026, Luis González Fernández, luisgf@luisgf.es
+        Copyright (c) 2014-2026, Jesús Cea Avión, jcea@jcea.es
+
+        All rights reserved.
+
+        This library is free software; you can redistribute it and/or
+        modify it under the terms of the GNU Lesser General Public
+        License as published by the Free Software Foundation; either
+        version 3.0 of the License, or (at your option) any later version.
+
+        This library is distributed in the hope that it will be useful,
+        but WITHOUT ANY WARRANTY; without even the implied warranty of
+        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+        Lesser General Public License for more details.
+
+        You should have received a copy of the GNU Lesser General Public
+        License along with this library.
+"""
+
+# Shared JSON <-> dataclass helpers for the OB2 and OB3 models. These lived in
+# duplicate in openbadgeslib.ob2.models and openbadgeslib.ob3.credential and had
+# drifted: the OB2 copy of ``_iso`` ran ``astimezone`` on a *naive* datetime,
+# which Python interprets as **local** time — so the same value serialised to a
+# different instant in OB2 than in OB3 (which anchors naive datetimes to UTC).
+# This module keeps the OB3 semantics (naive => UTC) as the single source of
+# truth, matching ob3.status_registry._iso_z and the JWT nbf/exp claims.
+
+from datetime import datetime, timezone
+from typing import Any
+
+
+def _iso(dt: datetime) -> str:
+    """Return a datetime as an ISO 8601 string with a ``Z`` (UTC) suffix.
+
+    A naive datetime is assumed to be UTC (not local time), so validFrom/
+    validUntil and OB2 issuedOn/expires never silently shift by the host's
+    offset and stay consistent with the JWT nbf/exp claims.
+    """
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _parse_iso(value: Any, where: str = 'date') -> datetime:
+    """Parse an ISO 8601 timestamp (with a UTC offset or trailing ``Z``).
+
+    A non-string (e.g. a bare Unix timestamp, the legacy OB 1.0 shape) is
+    rejected, as is a naive timestamp with no offset — verify() always compares
+    against an aware ``datetime.now(timezone.utc)``, so only unambiguously
+    anchored timestamps are accepted. Raises ValueError otherwise, naming
+    *where* the bad value came from.
+    """
+    if not isinstance(value, str):
+        raise ValueError("%s must be an ISO 8601 string, got %r" % (where, value))
+    try:
+        dt = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError as exc:
+        raise ValueError("invalid ISO 8601 date in %s: %r" % (where, value)) from exc
+    if dt.tzinfo is None:
+        raise ValueError("%s is missing a UTC offset: %r" % (where, value))
+    return dt
+
+
+def _as_dict(value: Any, where: str) -> dict[str, Any]:
+    """Return *value* if it is a dict, else raise a clear ValueError."""
+    if not isinstance(value, dict):
+        raise ValueError("%s must be a JSON object" % where)
+    return value
+
+
+def _require(data: dict[str, Any], key: str, where: str) -> str:
+    """Return ``data[key]`` as a non-empty string, raising a clear ValueError if
+    it is missing, empty, or not a string. All fields validated here are
+    identifiers consumed as strings downstream (e.g. recipient binding calls
+    ``.lower()``), so a non-string value must be rejected rather than crash
+    later."""
+    value = data.get(key)
+    if value is None or value == "":
+        raise ValueError("missing required field %s.%s" % (where, key))
+    if not isinstance(value, str):
+        raise ValueError("field %s.%s must be a string" % (where, key))
+    return value

{openbadgeslib-3.14.0 → openbadgeslib-4.0.0}/openbadgeslib/_jws/__init__.py

@@ -8,9 +8,46 @@ from .exceptions import SignatureError, MissingKey, MissingSigner, MissingVerifi
 from jwt.algorithms import RSAAlgorithm, ECAlgorithm, OKPAlgorithm
 from jwt.exceptions import InvalidKeyError
 
+from cryptography.hazmat.primitives.asymmetric import ec, rsa
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey, Ed25519PublicKey)
+
 from ..keys import KeyType, detect_key_type, key_to_pem
 from ..errors import UnknownKeyType
 
+# Key objects PyJWT's ``prepare_key`` accepts as-is (its own supported backends).
+# A live one of these can be handed straight to prepare_key, skipping a PEM
+# round-trip; a PEM str/bytes passes through too. Anything else falls to
+# key_to_pem, which since 4.0.0 accepts only cryptography objects and PEM and so
+# rejects it (UnknownKeyType) — including the pycryptodome / python-ecdsa
+# objects PyJWT never recognised.
+_CRYPTOGRAPHY_KEY_TYPES = (
+    rsa.RSAPrivateKey, rsa.RSAPublicKey,
+    ec.EllipticCurvePrivateKey, ec.EllipticCurvePublicKey,
+    Ed25519PrivateKey, Ed25519PublicKey,
+)
+
+
+def _prepare_key_arg(key: Any) -> Any:
+    """Return the value to feed a PyJWT algorithm's ``prepare_key``.
+
+    ``prepare_key`` accepts a PEM (str/bytes) *and* a live ``cryptography`` key
+    object directly, returning the latter untouched. Passing an already-loaded
+    object straight through skips a ``key_to_pem`` re-serialisation plus a
+    ``load_pem_private_key`` re-parse on every sign: the OB1 path hands in
+    ``Badge.priv_key`` — a cryptography object loaded once at construction — so
+    round-tripping it back to a PEM here only to re-parse it wasted ~45 ms per
+    RSA badge (#215). A PEM str/bytes passes through unchanged; anything else
+    falls to ``key_to_pem``, which since 4.0.0 accepts only cryptography objects
+    and PEM (a live pycryptodome/python-ecdsa object now raises UnknownKeyType).
+    """
+    if isinstance(key, (bytes, str)):
+        return key
+    if isinstance(key, _CRYPTOGRAPHY_KEY_TYPES):
+        return key
+    return key_to_pem(key)
+
+
 # Each entry is (algorithm class, hash id). EdDSA's OKPAlgorithm takes no hash
 # argument — its hash id is None and _algo_for constructs it with no args.
 _ALGORITHMS = {
@@ -65,7 +102,7 @@ def sign(header_dict: Dict[str, Any], payload_dict: Dict[str, Any], key: Any) ->
     signing_input = utils.encode(header_dict) + b'.' + utils.encode(payload_dict)
     algo = _algo_for(alg_name)
     try:
-        prepared = algo.prepare_key(key_to_pem(key))
+        prepared = algo.prepare_key(_prepare_key_arg(key))
         return cast(bytes, algo.sign(signing_input, prepared))
     except (InvalidKeyError, ValueError) as exc:
         raise SignatureError(str(exc)) from exc
@@ -121,7 +158,7 @@ def verify_block(msg: Union[str, bytes], key: Optional[Any] = None) -> bool:
 
     algo = _algo_for(alg_name)
     try:
-        prepared = algo.prepare_key(key_to_pem(key))
+        prepared = algo.prepare_key(_prepare_key_arg(key))
         valid = algo.verify(signing_input, prepared, raw_sig)
     except (InvalidKeyError, ValueError, AttributeError, TypeError) as exc:
         # A private key served where a public key is expected reaches