openbadgeslib 4.2.0__tar.gz → 4.3.0__tar.gz

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

@@ -4,6 +4,93 @@ OpenBadgesLib - Changelog
 Newest first. Dates are ISO 8601 (YYYY-MM-DD).
 
 
+* 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.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openbadgeslib
-Version: 4.2.0
+Version: 4.3.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
@@ -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"

{openbadgeslib-4.2.0 → openbadgeslib-4.3.0}/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.0}/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.0}/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.0}/openbadgeslib/errors.py

@@ -47,9 +47,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)
 
@@ -201,10 +202,6 @@ class UnknownCredential(StatusError):
     pass
 
 
-class AmbiguousCredential(StatusError):
-    pass
-
-
 class AlreadyRevoked(StatusError):
     pass
 

{openbadgeslib-4.2.0 → openbadgeslib-4.3.0}/openbadgeslib/issue.py

@@ -371,13 +371,19 @@ def _ob3_setup(conf: configparser.ConfigParser, badge: str, badge_obj: Badge,
 
 def _build_ob3_credential(ctx: _Ob3Context, recipient: str,
                           evidence: Optional[str],
-                          expires: Optional[int]) -> Any:
-    """Build one OpenBadgeCredential from the shared context (no status yet)."""
+                          expires: Optional[int],
+                          credential_id: Optional[str] = None) -> Any:
+    """Build one OpenBadgeCredential from the shared context (no status yet).
+
+    ``credential_id`` pins the credential's id instead of letting the model
+    mint one, for a flow that had to know the id before signing — a reserved
+    status-list slot is recorded against it."""
     from .ob3 import OpenBadgeCredential
     expiration_date = None
     if expires:
         expiration_date = datetime.now(tz=timezone.utc) + timedelta(days=expires)
     return OpenBadgeCredential(
+        id=credential_id,
         issuer=ctx.issuer,
         recipient_id=normalize_recipient_id(recipient),
         achievement=ctx.achievement,
@@ -413,6 +419,185 @@ def _sign_ob3_credential(badge: str, credential: Any, badge_obj: Badge,
         raise IssuanceError(str(exc)) from exc
 
 
+@dataclass
+class CredentialResult:
+    """One OB 3.0 credential issued as a TOKEN rather than baked into an image.
+
+    The counterpart of :class:`SignResult` for callers that deliver a credential
+    over a digital channel — a wallet claiming it over OID4VCI, an LMS API, an
+    email carrying the JWT — where a PNG is not the deliverable and baking one
+    is wasted work.
+
+    ``credential_format`` is the OID4VCI vocabulary (``jwt_vc_json`` /
+    ``vc+sd-jwt``), which is a different axis from the badge section's
+    ``proof_format``: that one governs the baked-image path only."""
+
+    credential_format: str
+    token: str
+    credential: 'OpenBadgeCredential'
+    jti: Optional[str] = None
+    status_index: Optional[int] = None
+    holder_did: Optional[str] = None    # did:jwk of the bound holder, if any
+    notices: List[str] = field(default_factory=list)
+
+
+def _bind_holder(credential: Any, recipient: str,
+                 holder_jwk: dict[str, Any]) -> str:
+    """Rebind a credential's subject to a wallet key, keeping the recipient.
+
+    ``credentialSubject.id`` becomes the holder's did:jwk — the key that proved
+    possession — and the recipient's address moves to
+    ``credentialSubject.identifier`` as a salted hash. Both matter: without the
+    first the credential is not bound to the wallet at all, and without the
+    second the badge stops being attributable to a person, since the holder key
+    is an opaque blob nobody can match to a learner.
+
+    The salt is fresh per credential, so the same address hashed for two badges
+    does not correlate them. Returns the did:jwk.
+    """
+    from .ob3 import IdentityObject
+    from .ob3.did import did_jwk_from_jwk
+
+    try:
+        holder_did = did_jwk_from_jwk(holder_jwk)
+    except ValueError as exc:
+        raise IssuanceError('invalid holder key: %s' % exc) from exc
+    credential.recipient_id = holder_did
+    credential.identifiers = [
+        IdentityObject.create(recipient, salt=os.urandom(16).hex())]
+    return holder_did
+
+
+def _stamp_status(credential: Any, status_conf: Any, index: int) -> None:
+    """Attach credentialStatus entries for an ALREADY allocated index.
+
+    The split from :func:`_allocate_status_batch` exists because OID4VCI
+    allocates at offer time and signs later, when the wallet claims: the index
+    is decided in the issuer's own control path, and the request path only
+    stamps it. Reserving an index inside the credential endpoint instead would
+    put a registry write — an exclusive lock plus a full-file rewrite, and a
+    no-op lock on platforms without fcntl — into a concurrent HTTP path."""
+    from .ob3.status_list import status_entry
+    credential.credential_status = [
+        status_entry(status_conf.list_urls[p], p, index)
+        for p in status_conf.purposes]
+
+
+def issue_credential_from_conf(conf: configparser.ConfigParser, badge: str,
+                               recipient: str, *,
+                               credential_format: str = 'jwt_vc_json',
+                               holder_jwk: Optional[dict[str, Any]] = None,
+                               evidence: Optional[str] = None,
+                               expires: Optional[int] = None,
+                               status_index: Optional[int] = None,
+                               credential_id: Optional[str] = None
+                               ) -> CredentialResult:
+    """Issue an OB 3.0 credential as a token, without baking it into an image.
+
+    ``credential_format`` is ``jwt_vc_json`` (a compact JWT-VC, revocable) or
+    ``vc+sd-jwt`` (an SD-JWT VC, the EUDI track). ``ldp`` has no equivalent
+    here: a document carrying an embedded proof is not a token.
+
+    Pass ``holder_jwk`` — the public key a wallet's OID4VCI key proof
+    demonstrated possession of — to bind the credential to that holder. For
+    ``jwt_vc_json`` the subject id becomes the key's did:jwk and the recipient
+    moves to a salted ``identifier`` hash; for ``vc+sd-jwt`` the key goes into
+    ``cnf``. Without it the subject is the normalised recipient, as in
+    :func:`issue_from_conf`.
+
+    ``status_index`` uses an index reserved earlier instead of allocating one,
+    for a flow that decides revocability before it knows whether the credential
+    will ever be claimed. Passing it for a badge with no status list configured
+    is an error rather than a silent no-op. Pass ``credential_id`` alongside it
+    with the id that reservation was recorded under, or the registry will name
+    a credential that was never issued and the delivered one will be
+    unrevocable.
+
+    Returns a :class:`CredentialResult`; raises :class:`IssuanceError`.
+    """
+    from .oid4vci.formats import (FORMAT_JWT_VC_JSON, FORMAT_SD_JWT_VC,
+                                  OID4VCI_FORMATS, REVOCABLE_FORMATS)
+
+    if credential_format not in OID4VCI_FORMATS:
+        raise IssuanceError(
+            "credential_format must be one of %s, got %r"
+            % (', '.join(OID4VCI_FORMATS), credential_format))
+
+    badge_obj = _badge_from_conf(conf, badge)
+    # Pin the proof format to vc-jwt: the badge section's own setting governs
+    # the baked-image path, and a section configured for ldp must not divert
+    # this one into a Data Integrity document.
+    ctx = _ob3_setup(conf, badge, badge_obj, 'vc-jwt')
+
+    if ctx.status_conf is not None and credential_format not in REVOCABLE_FORMATS:
+        # Refuse rather than drop the status: issuing a credential the issuer
+        # believes is revocable, and which silently is not, is the failure mode
+        # #226 already closed on the SD-JWT path. Catch it here so the caller
+        # learns before a wallet is waiting.
+        raise IssuanceError(
+            "[%s] configures status_lists, but %s cannot carry credential "
+            "status, so the badge would be irrevocable. Issue it as %s, or "
+            "drop status_lists from that section."
+            % (badge, credential_format, FORMAT_JWT_VC_JSON))
+    if status_index is not None and ctx.status_conf is None:
+        raise IssuanceError(
+            "a status_index was reserved for [%s], but that section configures "
+            "no status_lists" % badge)
+
+    credential = _build_ob3_credential(ctx, recipient, evidence, expires,
+                                       credential_id)
+    holder_did = None
+    if holder_jwk is not None:
+        holder_did = _bind_holder(credential, recipient, holder_jwk)
+
+    if status_index is not None:
+        _stamp_status(credential, ctx.status_conf, status_index)
+    else:
+        status_index = _allocate_status_batch([credential], ctx.status_conf)[0]
+
+    assert badge_obj.privkey_pem is not None
+    notices: List[str] = []
+    if credential_format == FORMAT_SD_JWT_VC:
+        token = _issue_sd_jwt_token(conf, credential, badge_obj, holder_jwk)
+    else:
+        token = _issue_jwt_vc_token(credential, badge_obj, ctx)
+
+    return CredentialResult(
+        credential_format=credential_format, token=token,
+        credential=credential, jti=credential.id, status_index=status_index,
+        holder_did=holder_did, notices=notices)
+
+
+def _issue_jwt_vc_token(credential: Any, badge_obj: Badge,
+                        ctx: _Ob3Context) -> str:
+    """Sign a credential into a compact JWT-VC (OID4VCI ``jwt_vc_json``)."""
+    from .ob3 import OB3Signer
+    algorithm = alg_for_key_type(ctx.key_type)
+    signer = OB3Signer(privkey_pem=badge_obj.privkey_pem, algorithm=algorithm)
+    try:
+        return signer.sign(credential)
+    except ErrorSigningFile as exc:
+        raise IssuanceError(str(exc)) from exc
+
+
+def _issue_sd_jwt_token(conf: configparser.ConfigParser, credential: Any,
+                        badge_obj: Badge,
+                        holder_jwk: Optional[dict[str, Any]]) -> str:
+    """Issue a credential as an SD-JWT VC (OID4VCI ``vc+sd-jwt``).
+
+    Uses the issuer's own ``[issuer] sd_jwt_vct`` when configured — the vct
+    whose Type Metadata openbadges-publish writes — so a wallet resolving the
+    type reaches this issuer's document rather than the generic imsglobal one.
+    """
+    from .ob3.eudi import OB3_SD_JWT_VCT, EudiError, issue_badge_sd_jwt
+    vct = (conf['issuer'].get('sd_jwt_vct') or '').strip() or OB3_SD_JWT_VCT
+    try:
+        return issue_badge_sd_jwt(credential, privkey_pem=badge_obj.privkey_pem,
+                                  holder_jwk=holder_jwk, vct=vct)
+    except EudiError as exc:
+        raise IssuanceError(str(exc)) from exc
+
+
 def _issue_ob3(conf: configparser.ConfigParser, badge: str, recipient: str,
                badge_obj: Badge, evidence: Optional[str], expires: Optional[int],
                proof_format: Optional[str]) -> SignResult:

{openbadgeslib-4.2.0 → openbadgeslib-4.3.0}/openbadgeslib/ob3/__init__.py

@@ -31,8 +31,9 @@ from .status import check_credential_status
 from .status_list import (build_status_list_credential, encode_bitstring,
                           sign_status_list_credential, status_entry)
 from .status_registry import StatusRegistry
-from .did import (build_did_document, did_key_from_pem, did_web_from_url,
-                  multikey_from_pem, resolve_did, resolve_verification_method)
+from .did import (build_did_document, did_jwk_from_jwk, did_key_from_pem,
+                  did_web_from_url, multikey_from_pem, resolve_did,
+                  resolve_verification_method)
 from .publish import (AmbiguousCredential, CredentialNotFound, PublishError,
                       PublishResult, StatusOperation, publish_ob3)
 from ..util import CachingDownloader
@@ -69,6 +70,7 @@ __all__ = [
     'build_did_document',
     'build_status_list_credential',
     'check_credential_status',
+    'did_jwk_from_jwk',
     'did_key_from_pem',
     'did_web_from_url',
     'encode_bitstring',