openbadgeslib 4.2.0__tar.gz → 4.3.1__tar.gz

{openbadgeslib-4.2.0 → openbadgeslib-4.3.1}/Changelog.txt

@@ -4,6 +4,131 @@ OpenBadgesLib - Changelog
 Newest first. Dates are ISO 8601 (YYYY-MM-DD).
 
 
+* v4.3.1 - 2026-08-02
+
+  Audit hardening: security fixes in the JWS engine and keygenerator, CLI
+  contract repairs, and documentation that matches the code.
+
+  - security(jws): bind ES* algorithms to their NIST curves (ES256→P-256,
+    ES384→P-384, ES512→P-521) so `verify_block` no longer accepts an ES256
+    header with a P-384/P-521 key (#284).
+  - security(jws): reject a JWS whose header carries `crit` (RFC 7515 §4.1.11);
+    this library understands no critical extensions (#292).
+  - security(cli): write key PEMs with `fchmod` on the open descriptor (no
+    path-based chmod TOCTOU) and map write OSError to a clean CLI exit (#289).
+  - fix(cli): `openbadges-verifier --json` emits a single JSON object when
+    trusted-key/config resolution fails, not a bare `[!]` line (#285).
+  - fix(cli): reject OB3-only verifier flags (`--check-status`,
+    `--no-verify-status-list`, `--resolve-did`) on `-V 1`/`-V 2` instead of
+    silently ignoring them (#286).
+  - fix(cli): ensure the signer `-o` directory exists and is writable before
+    allocating OB3 status indices, so a bad output path does not orphan
+    registry slots (#282).
+  - fix(ob1): map assertion body decode failures to `AssertionFormatIncorrect`
+    (#281); map `OSError`/`TimeoutError` during status checks to a `VerifyInfo`
+    verdict (#283); allow offline verification when a trusted key is supplied
+    even if the badge-declared key URL is dark (#290).
+  - fix(jws): map `TypeError` from `prepare_key` in `sign()` to
+    `SignatureError` (live wrong-family key on the OB1 path) (#288).
+  - fix(ob3): map an unparseable SD-JWT signing key to `EudiError` (#287).
+  - fix(oid4vci): `SqliteOID4VCIStore.close()` closes every per-thread
+    connection (was only the calling thread), clearing the bulk of
+    `ResourceWarning: unclosed database` under `--cov` (#301).
+  - fix(keys): drop the unused module logger and never-raised KeyGen exception
+    classes; PEM loads already map to `*ReadError` (#291).
+  - docs: correct `--check-status` status-list signature wording, Upgrading-to-4.0
+    exit codes, PyJWT floor ≥2.13, openbadges-init argparse docs, six CLI entry
+    points, publish `--json` `no_validity_bound`, and CachingDownloader
+    `max_entries` memory wording (#293–#300).
+
+
+* v4.3.0 - 2026-08-01
+
+  Issue a badge straight to a wallet, over OpenID4VCI.
+
+  - feat(oid4vci): issue badges to a wallet over OpenID for Verifiable
+    Credential Issuance 1.0, pre-authorized code flow. New `openbadgeslib.
+    oid4vci` package: Credential Offers, the issuer and RFC 8414 discovery
+    documents, and handlers for the token, nonce and credential endpoints. It
+    ships NO web server — the handlers return response bodies and the
+    integrator mounts the routes — which keeps the boundary openbadges-publish
+    already has (it writes files to serve, it does not serve them). The wallet
+    key-proof cryptography is delegated to openvc-core's `openvc.openid4vci`
+    behind a new `[oid4vci]` extra; the state that openvc refuses to hold —
+    codes, tokens, nonces, grants and their lifetimes — lives here, and with it
+    the "no wrong-issue" property. Formats: `jwt_vc_json` (revocable) and
+    `vc+sd-jwt` (the EUDI track, irrevocable per #226).
+    NOT HAIP-conformant and nothing built on it may claim to be: no DPoP, no
+    verified key attestations, no client authentication, no authorization code
+    flow. See wiki/Issuing-to-Wallets-with-OID4VCI.md and the new Security
+    Model section for the full list of what is and is not defended.
+    The state store is an interface with two backends: in-memory for a single
+    process, and SQLite for the threads and processes of one host. Single-use is
+    settled in the database rather than in Python — burning a nonce and claiming
+    an issuance are INSERTs under BEGIN IMMEDIATE — so exactly one caller wins
+    no matter how many workers race. Secrets are stored as digests, the file is
+    0600 in a 0700 directory, and an unknown schema version is refused.
+  - feat(issue): `issue_credential_from_conf()` issues an OB 3.0 credential as
+    a TOKEN rather than a baked badge image, returning a `CredentialResult`.
+    The existing `issue_from_conf` always bakes a PNG/SVG, which is wasted work
+    (and the wrong deliverable) when the credential goes to a wallet, an LMS
+    API or an email — reaching the raw token previously meant baking an SVG and
+    extracting it again. Takes an optional `holder_jwk` to bind the credential
+    to a wallet key: for `jwt_vc_json` the subject id becomes that key's
+    `did:jwk` and the recipient moves to a salted `credentialSubject.
+    identifier` hash, so the badge stays attributable to a person without
+    publishing their address; for `vc+sd-jwt` the key goes into `cnf`.
+  - feat(ob3): `did_jwk_from_jwk()` derives a did:jwk from a public JWK, and
+    `IdentityObject.create()` builds a salted-hash identifier (the OB 3.0
+    mirror of the OB 2.0 constructor). Both refuse JWKs carrying private key
+    material.
+  - feat(ob3): the status registry gains reservations (schema version 2).
+    An OID4VCI offer reserves its revocation slot when the offer is built, not
+    when the wallet claims — deciding it at claim time would put the registry's
+    exclusive lock and full-file rewrite inside a concurrent HTTP path, on a
+    lock that is a no-op where fcntl is missing. Reserved entries show as
+    `reserved` in `--list`; `openbadges-publish -V 3 --reclaim-unclaimed`
+    frees the ones whose offer lapsed, refusing to touch any slot the registry
+    and the OID4VCI store do not both agree was never issued against. Schema
+    version 1 files load unchanged, and a registry with no reservations
+    serialises byte-identically to before.
+  - fix(oid4vci): the SQLite store's opportunistic garbage collection takes an
+    injectable clock. It ran on wall-clock time while every query takes an
+    explicit `now=`, so a write collected the very rows a caller had just
+    written against a frozen instant — which made the store's own test suite
+    pass on the day it was written and fail a week later on the calendar
+    rather than on a code change.
+  - security(verifier): `openbadges-verifier -V 1` no longer reports
+    `trusted: true` for a badge that FAILED verification (#278). The OB 1.0 path
+    set the trust flag before the valid/invalid branch, so a tampered badge
+    checked against an operator-supplied key (-k/--local) emitted
+    `{valid: false, trusted: true, status: SIGNATURE_ERROR}` — contradicting the
+    invariant the OB 2.0 and OB 3.0 paths already honoured (#258) and that a
+    consumer reading the JSON object, rather than the exit status, relies on.
+    Exit codes are unchanged: such a badge already exited 1.
+  - fix(cli): `openbadges-signer` maps a misconfigured badge section to a clean
+    `[!]` error instead of a raw traceback (#279). It built the badge model
+    without the mapper that turns a missing config key or an unreadable
+    key/image into an IssuanceError, so the most likely first-run mistake — a
+    section missing `private_key`, or keys not generated yet — ended in a
+    KeyError traceback in human mode (`--json` was already covered).
+  - fix(errors): the documented exception tree no longer misfiles
+    `AmbiguousCredential` (#280). `openbadgeslib.errors` carried a dead
+    `AmbiguousCredential(StatusError)` that was never raised, while the one
+    actually raised and exported is `ob3.publish.AmbiguousCredential`, a
+    `PublishError` — so `except StatusError` around a publish/revoke call, as
+    the tree in the docstring and the wiki instructed, did not catch it. The
+    dead class is gone and the `PublishError` family (with `CredentialNotFound`)
+    is documented in both places.
+  - build(deps): the openvc-core floors move to >=1.24 across `[eudi]`,
+    `[ldp-sd]` and `[oid4vci]`, which is the release the suite is actually
+    tested against — the rule the extras already documented, applied uniformly
+    (`[ldp-sd]` had been left behind at >=1.21). Substantively 1.23 still
+    suffices for the OpenID4VCI key proof and 1.22 for the Token Status List;
+    1.24 is additive over both (`ResolveProofKey` is unchanged and not
+    deprecated), so an install already on 1.24 sees no behaviour change.
+
+
 * v4.2.0 - 2026-07-29
 
   The OpenID4VCI credential configuration an issuer advertises can now declare

{openbadgeslib-4.2.0 → openbadgeslib-4.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openbadgeslib
-Version: 4.2.0
+Version: 4.3.1
 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
@@ -36,9 +36,11 @@ 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.23; extra == "eudi"
+Requires-Dist: openvc-core<2,>=1.24; extra == "eudi"
 Provides-Extra: ldp-sd
-Requires-Dist: openvc-core[data-integrity]<2,>=1.21; extra == "ldp-sd"
+Requires-Dist: openvc-core[data-integrity]<2,>=1.24; extra == "ldp-sd"
+Provides-Extra: oid4vci
+Requires-Dist: openvc-core<2,>=1.24; extra == "oid4vci"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-cov>=5.0; extra == "dev"
@@ -83,7 +85,7 @@ legacy format, selected with `-V {1,2,3}` (default `3`).
 - Issue and verify badges as EUDI **SD-JWT VC** (the EU wallet / ARF format)
   with selective disclosure, via the optional `[eudi]` extra
 - did:web issuer identity: `did.json` generation and DID resolution
-- Five command-line tools included
+- Six command-line entry points: the unified `openbadges` front-end plus five `openbadges-*` aliases
 
 ## Why openbadgeslib
 
@@ -119,7 +121,7 @@ additive EUDI SD-JWT VC wallet track.
 | Revocation / suspension | ✅ W3C Bitstring Status List | hosted check | `1EdTechRevocationList` | ad-hoc flag | — |
 | `did:web` (generate + resolve) | ✅ | — | — | — | resolve only |
 | Image baking (SVG + PNG) | ✅ | unbake only | ✅ | — | — |
-| Form factor | library + 5 CLI tools | library + CLI | Django server | library | binding |
+| Form factor | library + CLI (`openbadges` + 5 aliases) | library + CLI | Django server | library | binding |
 | Typing / CI | `mypy --strict`, CI 3.10–3.14 | — | — | Pydantic | — |
 | License | LGPLv3 / BSD-2 | Apache-2.0 | AGPL-3.0 | MIT/LGPL | Apache-2.0 |
 
@@ -141,7 +143,7 @@ all three OB versions.
 
 - Python >= 3.10 (tested on 3.10–3.14)
 - [pypng](https://pypi.org/project/pypng/) >= 0.20220715.0
-- [PyJWT[crypto]](https://pypi.org/project/PyJWT/) >= 2.8
+- [PyJWT[crypto]](https://pypi.org/project/PyJWT/) >= 2.13
 - [cryptography](https://pypi.org/project/cryptography/) >= 42
 - [defusedxml](https://pypi.org/project/defusedxml/) >= 0.7
 

{openbadgeslib-4.2.0 → openbadgeslib-4.3.1}/README.md

@@ -30,7 +30,7 @@ legacy format, selected with `-V {1,2,3}` (default `3`).
 - Issue and verify badges as EUDI **SD-JWT VC** (the EU wallet / ARF format)
   with selective disclosure, via the optional `[eudi]` extra
 - did:web issuer identity: `did.json` generation and DID resolution
-- Five command-line tools included
+- Six command-line entry points: the unified `openbadges` front-end plus five `openbadges-*` aliases
 
 ## Why openbadgeslib
 
@@ -66,7 +66,7 @@ additive EUDI SD-JWT VC wallet track.
 | Revocation / suspension | ✅ W3C Bitstring Status List | hosted check | `1EdTechRevocationList` | ad-hoc flag | — |
 | `did:web` (generate + resolve) | ✅ | — | — | — | resolve only |
 | Image baking (SVG + PNG) | ✅ | unbake only | ✅ | — | — |
-| Form factor | library + 5 CLI tools | library + CLI | Django server | library | binding |
+| Form factor | library + CLI (`openbadges` + 5 aliases) | library + CLI | Django server | library | binding |
 | Typing / CI | `mypy --strict`, CI 3.10–3.14 | — | — | Pydantic | — |
 | License | LGPLv3 / BSD-2 | Apache-2.0 | AGPL-3.0 | MIT/LGPL | Apache-2.0 |
 
@@ -88,7 +88,7 @@ all three OB versions.
 
 - Python >= 3.10 (tested on 3.10–3.14)
 - [pypng](https://pypi.org/project/pypng/) >= 0.20220715.0
-- [PyJWT[crypto]](https://pypi.org/project/PyJWT/) >= 2.8
+- [PyJWT[crypto]](https://pypi.org/project/PyJWT/) >= 2.13
 - [cryptography](https://pypi.org/project/cryptography/) >= 42
 - [defusedxml](https://pypi.org/project/defusedxml/) >= 0.7
 

{openbadgeslib-4.2.0 → openbadgeslib-4.3.1}/openbadgeslib/__init__.py

@@ -66,7 +66,8 @@ from ._ob1_api import OB1_API as _OB1_API  # noqa: F401
 # (hence cryptography) — inside the run-to-run noise — so the documentation of
 # the recommended modern API is worth more than it.
 from .issue import (  # noqa: F401
-    IssuanceError, SignResult, issue_from_conf,
+    CredentialResult, IssuanceError, SignResult, issue_credential_from_conf,
+    issue_from_conf,
 )
 from .verify import verify_badge  # noqa: F401
 
@@ -113,6 +114,9 @@ __all__ = [
     'OpenBadgeCredential', 'Achievement', 'Issuer',
     # Keys (KeyEd25519 is the recommended OB 3.0 / LDP key type).
     'KeyFactory', 'KeyRSA', 'KeyECC', 'KeyEd25519',
-    # Programmatic issue / verify facades.
-    'issue_from_conf', 'verify_badge', 'IssuanceError', 'SignResult',
+    # Programmatic issue / verify facades. issue_credential_from_conf is the
+    # token-returning sibling of issue_from_conf, for delivering a credential
+    # over a digital channel (a wallet, an API) rather than as a badge image.
+    'issue_from_conf', 'issue_credential_from_conf', 'verify_badge',
+    'IssuanceError', 'SignResult', 'CredentialResult',
 ]

{openbadgeslib-4.2.0 → openbadgeslib-4.3.1}/openbadgeslib/_jws/__init__.py

@@ -48,16 +48,23 @@ def _prepare_key_arg(key: Any) -> Any:
     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.
+# Each entry is (algorithm class, hash id, expected_curve). EdDSA's
+# OKPAlgorithm takes no hash or curve — both are None and _algo_for constructs
+# it with no args. RSA has no curve. EC algorithms bind the NIST curve that
+# RFC 7518 §3.4 pairs with each ES* alg (ES256→P-256, ES384→P-384, ES512→P-521)
+# so a P-521 key cannot "verify" an ES256 header and a P-256 key cannot sign
+# ES512 — the same defence jwt.decode() gets from PyJWT's default registry
+# (#284). Without expected_curve, ECAlgorithm accepts any EC key for any ES*
+# hash, which is a lost defence-in-depth layer and an interop asymmetry with
+# conformant verifiers.
 _ALGORITHMS = {
-    'RS256': (RSAAlgorithm, RSAAlgorithm.SHA256),
-    'RS384': (RSAAlgorithm, RSAAlgorithm.SHA384),
-    'RS512': (RSAAlgorithm, RSAAlgorithm.SHA512),
-    'ES256': (ECAlgorithm,  ECAlgorithm.SHA256),
-    'ES384': (ECAlgorithm,  ECAlgorithm.SHA384),
-    'ES512': (ECAlgorithm,  ECAlgorithm.SHA512),
-    'EdDSA': (OKPAlgorithm,  None),
+    'RS256': (RSAAlgorithm, RSAAlgorithm.SHA256, None),
+    'RS384': (RSAAlgorithm, RSAAlgorithm.SHA384, None),
+    'RS512': (RSAAlgorithm, RSAAlgorithm.SHA512, None),
+    'ES256': (ECAlgorithm,  ECAlgorithm.SHA256,  ec.SECP256R1),
+    'ES384': (ECAlgorithm,  ECAlgorithm.SHA384,  ec.SECP384R1),
+    'ES512': (ECAlgorithm,  ECAlgorithm.SHA512,  ec.SECP521R1),
+    'EdDSA': (OKPAlgorithm,  None,               None),
 }
 
 
@@ -65,9 +72,11 @@ def _algo_for(alg_name: str) -> Any:
     entry = _ALGORITHMS.get(alg_name)
     if entry is None:
         raise RouteMissingError(f"Algorithm {alg_name!r} is not supported")
-    cls, hash_id = entry
+    cls, hash_id, expected_curve = entry
     if hash_id is None:
         return cls()
+    if expected_curve is not None:
+        return cls(hash_id, expected_curve)
     return cls(hash_id)
 
 
@@ -104,7 +113,13 @@ def sign(header_dict: Dict[str, Any], payload_dict: Dict[str, Any], key: Any) ->
     try:
         prepared = algo.prepare_key(_prepare_key_arg(key))
         return cast(bytes, algo.sign(signing_input, prepared))
-    except (InvalidKeyError, ValueError) as exc:
+    except (InvalidKeyError, ValueError, TypeError, AttributeError) as exc:
+        # prepare_key raises a bare TypeError ("Expecting a PEM-formatted key.")
+        # when handed a live cryptography object of the wrong family — the OB1
+        # path passes Badge.priv_key as a live object via _prepare_key_arg
+        # (#215). Mirror verify_block's except tuple so a mismatched key family
+        # surfaces as SignatureError, not a raw traceback out of the signer
+        # (#288).
         raise SignatureError(str(exc)) from exc
 
 
@@ -150,6 +165,16 @@ def verify_block(msg: Union[str, bytes], key: Optional[Any] = None) -> bool:
             "Algorithm %r in JWS header is not allowed for this key type"
             % alg_name)
 
+    # RFC 7515 §4.1.11: a verifier MUST reject a JWS whose 'crit' header names
+    # extensions it does not understand. This library understands none, so any
+    # present 'crit' (even an empty list — non-conformant but still a signal the
+    # issuer intended critical processing) fails closed rather than silently
+    # dropping the constraint while a conformant verifier would reject (#292).
+    if 'crit' in header:
+        raise SignatureError(
+            "JWS header requires unsupported 'crit' extensions: %r"
+            % (header.get('crit'),))
+
     signing_input = head_b64 + b'.' + payload_b64
     try:
         raw_sig = utils.from_base64(sig_b64)

{openbadgeslib-4.2.0 → openbadgeslib-4.3.1}/openbadgeslib/config.ini.example

@@ -52,6 +52,45 @@ revocationList = revoked.json
 ; imsglobal vct.
 ;sd_jwt_vct     = ${publish_url}vct/openbadge
 
+; OpenID for Verifiable Credential Issuance (OID4VCI), issuer side. Optional and
+; entirely opt-in: without this section nothing changes, and a badge is only
+; offered over OID4VCI if its own 'oid4vci_formats' key says so.
+;
+; This library does NOT run the endpoints. It builds the offers, verifies the
+; wallet's key proof (via openvc-core, the [oid4vci] extra) and issues the
+; credential; you mount the routes in your own web framework at the URLs below.
+;
+; NOT a HAIP-conformant issuer: no DPoP, no key attestation checking, no client
+; authentication and no authorization code flow. Pre-authorized code only.
+;[oid4vci]
+; The Credential Issuer Identifier: the https base URL where you serve
+; /.well-known/openid-credential-issuer. Every wallet key proof binds its 'aud'
+; to this exact string, so it must match what you actually serve. Default:
+; [issuer] publish_url.
+;credential_issuer   = https://openbadges.issuer.badge/issuer/
+; The three endpoints you mount. Default: derived from credential_issuer.
+;credential_endpoint = https://openbadges.issuer.badge/issuer/credential
+;nonce_endpoint      = https://openbadges.issuer.badge/issuer/nonce
+;token_endpoint      = https://openbadges.issuer.badge/issuer/token
+; Where the flow's short-lived state lives (pre-authorized codes, access tokens,
+; spent nonces). SQLite, single host: NOT on NFS/SMB, where its locking breaks.
+; The directory is created 0700 and holds recipient PII — do not back it up.
+; Default: ${paths:base}/oid4vci.sqlite3
+;store_path          = ${paths:base}/oid4vci.sqlite3
+; Lifetimes, in seconds. The offer TTL bounds how long a QR code stays
+; redeemable; keep it short, it is a bearer secret.
+;offer_ttl_s         = 600
+;nonce_ttl_s         = 120
+;token_ttl_s         = 300
+; How stale a wallet's key proof may be before it is refused.
+;proof_max_age_s     = 300
+; Credentials one Credential Request may claim. Leave at 1 unless you have a
+; reason: a batch mints one credential per key proof off a single grant.
+;batch_size          = 1
+; The out-of-band PIN, when an offer asks for one. 'numeric' or 'text'.
+;tx_code_length      = 6
+;tx_code_input_mode  = numeric
+
 ;Badge configuration sections.
 [badge_1]
 name        = Badge 1
@@ -98,6 +137,12 @@ key_type    = RSA
 ; lapses; pick a cadence you can sustain (e.g. 7 => weekly). Unset = no bound
 ; (offline-friendly, but publishes a loud warning).
 ;status_validity_days = 7
+; OID4VCI opt-in for this badge (comma-separated subset of: jwt_vc_json,
+; vc+sd-jwt). Unset means the badge is not published in the issuer metadata and
+; cannot be offered to a wallet. jwt_vc_json is revocable via the status lists
+; above; vc+sd-jwt is the EUDI track and is IRREVOCABLE, so it cannot be
+; combined with status_lists. vc+sd-jwt also needs key_type = ED25519 or ECC.
+;oid4vci_formats  = jwt_vc_json
 ;mail        = ${paths:base}/badge_1_mail.txt
 
 [badge_2]

{openbadgeslib-4.2.0 → openbadgeslib-4.3.1}/openbadgeslib/confparser.py

@@ -23,7 +23,7 @@
 
 from configparser import ConfigParser, ExtendedInterpolation, Error as ConfigParserError
 from dataclasses import dataclass
-from typing import Dict, List, Optional, TYPE_CHECKING
+from typing import Dict, List, Optional, Tuple, TYPE_CHECKING
 import os
 import sys
 import logging
@@ -197,6 +197,189 @@ def ob3_status_config(conf: ConfigParser,
                            validity_days=validity_days)
 
 
+# ── OID4VCI (OpenID for Verifiable Credential Issuance) ──────────────────────
+# Issuing to a wallet inverts the library's usual direction: instead of the
+# issuer pushing a badge to a known recipient, the wallet claims it against an
+# offer and proves possession of its own key. That needs a handful of
+# deployment values the rest of the config has no reason to carry — the public
+# identifier the wallet's key proofs bind to, and the lifetimes of the
+# short-lived secrets the flow mints.
+#
+# The whole section is optional: without it, nothing else in the library
+# changes behaviour.
+
+#: How long a Credential Offer's pre-authorized code stays redeemable. Short by
+#: default: it is a bearer secret that travels in a QR code or a link.
+DEFAULT_OFFER_TTL_S = 600
+
+#: Lifetime of a c_nonce handed out by the nonce endpoint.
+DEFAULT_NONCE_TTL_S = 120
+
+#: Lifetime of an access token minted at the token endpoint. It only has to
+#: survive the wallet's immediate follow-up call to the credential endpoint.
+DEFAULT_TOKEN_TTL_S = 300
+
+#: How stale a wallet key proof's `iat` may be (openvc's max_age_s).
+DEFAULT_PROOF_MAX_AGE_S = 300
+
+#: Digits in a numeric tx_code, and the input modes OID4VCI 1.0 defines.
+DEFAULT_TX_CODE_LENGTH = 6
+TX_CODE_INPUT_MODES = ('numeric', 'text')
+
+
+@dataclass
+class OID4VCIConfig:
+    """Resolved [oid4vci] section: the issuer identifier, the endpoint URLs and
+    the lifetimes of the flow's short-lived secrets.
+
+    ``credential_issuer`` is load-bearing beyond being an identifier: it is the
+    value every wallet key proof must name in its ``aud``, so it has to match
+    byte for byte what is actually served at
+    ``<credential_issuer>/.well-known/openid-credential-issuer``."""
+
+    credential_issuer: str
+    credential_endpoint: str
+    nonce_endpoint: str
+    token_endpoint: str
+    store_path: str
+    offer_ttl_s: int = DEFAULT_OFFER_TTL_S
+    nonce_ttl_s: int = DEFAULT_NONCE_TTL_S
+    token_ttl_s: int = DEFAULT_TOKEN_TTL_S
+    proof_max_age_s: int = DEFAULT_PROOF_MAX_AGE_S
+    batch_size: int = 1
+    tx_code_length: int = DEFAULT_TX_CODE_LENGTH
+    tx_code_input_mode: str = 'numeric'
+
+
+def _positive_int(conf: ConfigParser, section: str, key: str,
+                  default: int) -> int:
+    """Read a positive integer config key, or its default when unset."""
+    raw = (conf[section].get(key) or '').strip() if section in conf else ''
+    if not raw:
+        return default
+    try:
+        value = int(raw)
+    except ValueError:
+        raise ConfigError("[%s] %s must be an integer, got %r"
+                          % (section, key, raw)) from None
+    if value <= 0:
+        raise ConfigError("[%s] %s must be positive" % (section, key))
+    return value
+
+
+def oid4vci_config(conf: ConfigParser) -> OID4VCIConfig:
+    """Resolve the optional [oid4vci] section.
+
+    Every key has a default, so a typical deployment writes none of them: the
+    issuer identifier falls back to ``[issuer] publish_url`` and the three
+    endpoints are derived from it. Raises :class:`ConfigError` when there is no
+    base to derive an issuer identifier from, when it is not https, or when a
+    lifetime is not a positive integer.
+
+    ``https`` is required rather than encouraged. A key proof's ``aud`` binds
+    the wallet's signature to this exact string; over plaintext http an attacker
+    who can rewrite the metadata response also chooses what the wallet signs
+    for, which makes the binding decorative.
+    """
+    from urllib.parse import urljoin
+
+    section = conf['oid4vci'] if 'oid4vci' in conf else None
+    base = (section.get('credential_issuer') if section else None) or \
+        conf['issuer'].get('publish_url') or ''
+    base = base.strip()
+    if not base:
+        raise ConfigError(
+            "[oid4vci] needs a credential_issuer (or an [issuer] publish_url "
+            "to derive it from): it is the identifier wallet key proofs bind "
+            "their 'aud' to")
+    if not base.startswith('https://'):
+        raise ConfigError(
+            "[oid4vci] credential_issuer must be an https URL, got %r — a "
+            "wallet key proof's audience binding is meaningless over plaintext"
+            % base)
+    # A trailing slash makes urljoin append rather than replace the last path
+    # segment; without it, an issuer at https://host/issuer would derive
+    # https://host/credential.
+    endpoint_base = base if base.endswith('/') else base + '/'
+
+    def endpoint(key: str, default_path: str) -> str:
+        explicit = (section.get(key) or '').strip() if section else ''
+        return explicit or urljoin(endpoint_base, default_path)
+
+    store_path = (section.get('store_path') if section else None) or \
+        os.path.join(conf['paths']['base'], 'oid4vci.sqlite3')
+
+    input_mode = ((section.get('tx_code_input_mode') if section else None)
+                  or 'numeric').strip()
+    if input_mode not in TX_CODE_INPUT_MODES:
+        raise ConfigError("[oid4vci] tx_code_input_mode must be one of %s, "
+                          "got %r" % (', '.join(TX_CODE_INPUT_MODES),
+                                      input_mode))
+
+    return OID4VCIConfig(
+        credential_issuer=base,
+        credential_endpoint=endpoint('credential_endpoint', 'credential'),
+        nonce_endpoint=endpoint('nonce_endpoint', 'nonce'),
+        token_endpoint=endpoint('token_endpoint', 'token'),
+        store_path=store_path,
+        offer_ttl_s=_positive_int(conf, 'oid4vci', 'offer_ttl_s',
+                                  DEFAULT_OFFER_TTL_S),
+        nonce_ttl_s=_positive_int(conf, 'oid4vci', 'nonce_ttl_s',
+                                  DEFAULT_NONCE_TTL_S),
+        token_ttl_s=_positive_int(conf, 'oid4vci', 'token_ttl_s',
+                                  DEFAULT_TOKEN_TTL_S),
+        proof_max_age_s=_positive_int(conf, 'oid4vci', 'proof_max_age_s',
+                                      DEFAULT_PROOF_MAX_AGE_S),
+        batch_size=_positive_int(conf, 'oid4vci', 'batch_size', 1),
+        tx_code_length=_positive_int(conf, 'oid4vci', 'tx_code_length',
+                                     DEFAULT_TX_CODE_LENGTH),
+        tx_code_input_mode=input_mode,
+    )
+
+
+def oid4vci_formats(conf: ConfigParser, badge_section: str) -> Tuple[str, ...]:
+    """The OID4VCI credential formats a badge section opts into, in order.
+
+    Returns an empty tuple when the badge does not opt in (no
+    ``oid4vci_formats`` key), which callers treat as "this badge is not offered
+    over OID4VCI" — the same contract as :func:`ob3_status_config` returning
+    None. Opt-in rather than opt-out because listing a badge in the issuer
+    metadata publishes its existence and makes it claimable.
+
+    Raises :class:`ConfigError` for an unknown format, or for ``vc+sd-jwt`` on a
+    section with ``key_type = RSA``: SD-JWT VC has no RSA algorithm profile, so
+    that pairing could never issue and the operator should learn about it when
+    the config loads, not when a wallet is waiting.
+    """
+    from .keys import KeyType
+    from .oid4vci.formats import EC_ONLY_FORMATS, OID4VCI_FORMATS
+
+    raw = conf[badge_section].get('oid4vci_formats', '')
+    formats: List[str] = []
+    for piece in raw.split(','):
+        fmt = piece.strip()
+        if not fmt:
+            continue
+        if fmt not in OID4VCI_FORMATS:
+            raise ConfigError(
+                "[%s] oid4vci_formats: unknown format %r (choose from %s)"
+                % (badge_section, fmt, ', '.join(OID4VCI_FORMATS)))
+        if fmt not in formats:
+            formats.append(fmt)
+    if not formats:
+        return ()
+
+    key_type = resolve_key_type(conf[badge_section].get('key_type'))
+    if key_type is KeyType.RSA:
+        rsa_incapable = [f for f in formats if f in EC_ONLY_FORMATS]
+        if rsa_incapable:
+            raise ConfigError(
+                "[%s] oid4vci_formats includes %s, which cannot be signed with "
+                "an RSA key — use key_type = ED25519 or ECC, or drop that "
+                "format" % (badge_section, ', '.join(rsa_incapable)))
+    return tuple(formats)
+
+
 # ── centralized config defaults ──────────────────────────────────────────────
 # One inventory for the accepted-key defaults, so each lives in a single place
 # rather than being re-spelled at every read site. (The status-list defaults —
@@ -285,7 +468,9 @@ def badge_section_config(conf: ConfigParser,
 #: Sections whose values are the *public* identifiers of a deployment, checked
 #: by :func:`reject_url_userinfo`. [smtp] is deliberately excluded: its
 #: username/password are credentials that stay on the issuer's machine.
-_PUBLIC_URL_SECTIONS = ('issuer',)
+#: [oid4vci] belongs here because its credential_issuer and endpoint URLs are
+#: published in the issuer metadata and handed to every wallet that reads it.
+_PUBLIC_URL_SECTIONS = ('issuer', 'oid4vci')
 _PUBLIC_URL_SECTION_PREFIX = 'badge_'
 
 

{openbadgeslib-4.2.0 → openbadgeslib-4.3.1}/openbadgeslib/errors.py

@@ -31,8 +31,7 @@ class LibOpenBadgesException(Exception):
 
         LibOpenBadgesException
         ├── KeyGenExceptions          (alias: KeyGenException)
-        │   ├── GenPrivateKeyError / GenPublicKeyError
-        │   ├── PrivateKeySaveError / PublicKeySaveError
+        │   ├── GenPrivateKeyError
         │   ├── PrivateKeyReadError / PublicKeyReadError
         │   └── UnknownKeyType
         ├── SignerExceptions          (alias: SignerException)
@@ -47,9 +46,10 @@ class LibOpenBadgesException(Exception):
         ├── IssuanceError
         ├── DecompressionLimitExceeded
         ├── StatusError               (issuer-side revocation)
-        │   └── StatusListFull / UnknownCredential / AmbiguousCredential
-        │       / AlreadyRevoked / AlreadySuspended / NotSuspended
-        │       / RegistryCorrupt
+        │   └── StatusListFull / UnknownCredential / AlreadyRevoked
+        │       / AlreadySuspended / NotSuspended / RegistryCorrupt
+        ├── PublishError              (openbadgeslib.ob3.publish)
+        │   └── CredentialNotFound / AmbiguousCredential
         ├── OB2VerificationError      (openbadgeslib.ob2.verifier)
         └── OB3VerificationError      (openbadgeslib.ob3.verifier)
 
@@ -89,18 +89,6 @@ class GenPrivateKeyError(KeyGenExceptions):
     pass
 
 
-class GenPublicKeyError(KeyGenExceptions):
-    pass
-
-
-class PrivateKeySaveError(KeyGenExceptions):
-    pass
-
-
-class PublicKeySaveError(KeyGenExceptions):
-    pass
-
-
 class PrivateKeyReadError(KeyGenExceptions):
     pass
 
@@ -201,10 +189,6 @@ class UnknownCredential(StatusError):
     pass
 
 
-class AmbiguousCredential(StatusError):
-    pass
-
-
 class AlreadyRevoked(StatusError):
     pass