openvc

A dependency-light, HSM-friendly Verifiable Credentials core for Python: sign and verify W3C VCs in the three mainstream proof formats, resolve issuer keys, check revocation, and verify wallet presentations — fail-closed by default, with private keys that never have to enter the process.

Install

The PyPI distribution is openvc-core (the import package stays openvc):

pip install openvc-core

The core needs only cryptography and pyjwt. Everything heavier is an extra:

Quick start

Issue a VC-JWT and verify it with the one-call pipeline. verify_credential detects the format (VC-JWT / SD-JWT VC / Data Integrity / enveloped), resolves the issuer key, verifies the proof, and applies policy — types, audience, and fail-closed status:

from cryptography.hazmat.primitives.asymmetric import ed25519

from openvc import VerificationPolicy, verify_credential
from openvc.keys import Ed25519SigningKey
from openvc.multibase import encode_multibase
from openvc.proof.vc_jwt import VcJwtProofSuite

# An issuer key addressed by did:key, so the whole flow runs offline.
private_key = ed25519.Ed25519PrivateKey.generate()
public_raw = Ed25519SigningKey(private_key, kid="_").public_key_raw()
mb = encode_multibase(bytes([0xED, 0x01]) + public_raw)   # multicodec ed25519-pub
issuer = Ed25519SigningKey(private_key, kid=f"did:key:{mb}#{mb}")

token = VcJwtProofSuite().sign({
    "@context": ["https://www.w3.org/ns/credentials/v2"],
    "id": "urn:uuid:2f3a-example",
    "type": ["VerifiableCredential", "ExampleCredential"],
    "issuer": f"did:key:{mb}",
    "credentialSubject": {"id": "did:example:alice", "name": "Ada Lovelace"},
}, signing_key=issuer)

result = verify_credential(
    token, policy=VerificationPolicy(expected_types=["ExampleCredential"]))
print(result.format, result.issuer, result.subject)

Selective disclosure with SD-JWT VC — issue, present with a Key Binding JWT, verify; the holder proves possession of the cnf key and the verifier sees only what was disclosed:

from openvc.keys import Ed25519SigningKey
from openvc.proof.sd_jwt import SdJwtVcProofSuite

issuer = Ed25519SigningKey.generate(kid="https://issuer.example#key-1")
holder = Ed25519SigningKey.generate(kid="holder-key-1")
suite = SdJwtVcProofSuite()

sd_jwt = suite.issue(
    {"iss": "https://issuer.example", "given_name": "Ada", "age": 36},
    signing_key=issuer, disclosable=["given_name", "age"],
    holder_jwk=holder.public_jwk(), vct="https://credentials.example/identity")

presentation = suite.create_presentation(
    sd_jwt, holder_key=holder, audience="https://verifier.example", nonce="n-123")

result = suite.verify(
    presentation, public_key_jwk=issuer.public_jwk(),
    audience="https://verifier.example", nonce="n-123", require_key_binding=True,
    expected_vct="https://credentials.example/identity")
print(result.claims["given_name"], result.key_bound)

Every flow — Data Integrity proofs, VP-JWT and OpenID4VP presentations, status lists, remote HSM signing, EU Trusted Lists, EBSI — has a guide in the wiki and a runnable script in examples/.

Why openvc

• HSM-first. Signing goes through the SigningKey protocol (alg / kid / sign), so a PKCS#11, AWS KMS, or Vault Transit backend drops in and the private key never enters the process. ES256 signatures are the correct raw JOSE R‖S form — the classic reason a locally-produced token fails elsewhere.
• Fail-closed by construction. The {ES256, ES384, EdDSA, Ed25519} allow-list runs before any crypto (alg:none, RS*, HS* never reach a verifier); a declared credential status without a resolver rejects; an unparseable timestamp rejects; the JWT envelope is reconciled with the embedded credential.
• Post-quantum ready (experimental). ML-DSA (RFC 9964, ML-DSA-44/65/87) signs and verifies VC-JWT / SD-JWT VC behind an explicit opt-in (allow_pq=True) and the [pq] extra — first-mover space; no maintained Python VC library signs ML-DSA today. Never a default trust path; the allow-list above is unchanged unless you opt in.
• SSRF-guarded network. did:web and /.well-known/jwt-vc-issuer go through an https-only fetch that blocks non-globally-routable addresses, refuses redirects, and pins the connection to the validated IP (no DNS rebinding). Status-list and credentialSchema fetches use the same guard via the blessed defaults in openvc.resolvers; a custom resolver opts out.
• Dependency-light. The core imports cryptography and pyjwt, nothing else; JSON canonicalization (RFC 8785) and the ecdsa-sd-2023 CBOR codec are hand-rolled on the stdlib, and pyld / httpx stay behind extras.
• Conformance pinned by real vectors. eddsa-rdfc-2022 reproduces the official W3C test vector byte-for-byte; ecdsa-rdfc-2019 / ecdsa-sd-2023 verify the official vc-di-ecdsa vectors and match their intermediates; ISO 18013-5 mso_mdoc verifies the Annex D reference DeviceResponse; the OpenID4VCI key-proof verifier verifies the spec's own App. F.1 example against Issuer Metadata and Credential Offers recorded from the EU reference issuer; the EBSI client is verified against recorded pilot responses. Golden fixtures are the drift alarm. Beyond them, a test-only VC-API shim runs openvc through the official W3C suites (vc-data-model-2.0, vc-di-eddsa, vc-di-ecdsa, bitstring-status-list) for third-party conformance reports.

Documentation

• Manual (wiki) — installation, a guide per proof format, presentations & OpenID4VP, issuer-key resolution, status lists, trust (EU Trusted Lists, EBSI), HSM integration, the security model, and the versioning contract.
• API reference — generated from the docstrings, per module.
• examples/ — thirteen runnable, offline scripts covering every flow (they run in CI, so they cannot rot).

Scope

openvc is the generic VC machinery a badge issuer, an EBSI verifier, or a EUDI wallet backend builds on — intentionally not an Open Badges library, a wallet, or a node operator. EBSI support is read-only (resolve did:ebsi, read the trust registries); onboarding/writing is out of scope. The openvc_ebsi plugin depends on openvc, never the reverse.

Three invariants bound everything above: no state, no transport, dependency-light. openvc signs and verifies credentials and validates what a wallet sends, but it runs no HTTP endpoint, holds no session, and persists nothing — where a protocol needs state, the store is injected and openvc keeps none of it. That, not "verify-only", is the boundary; see ADR-0007.

Project

• Changelog — every release, with the spec/security reasoning
• Roadmap
• Versioning & deprecation policy
• Contributing — dev setup, checks, commit convention
• Security policy and the threat model

pip install -e ".[all]"       # from a checkout
pytest                        # offline: deterministic, no network
OPENVC_EBSI_LIVE=1 pytest     # + the opt-in live EBSI smoke test

License

LGPL-3.0-or-later. Copyright © 2026 Luis González Fernández. See COPYING.LESSER and COPYING.