polaris-oid4vp

An OpenID4VP 1.0 verifier under the High Assurance Interoperability Profile. It checks a presentation from a wallet that has never heard of Polaris: an SD-JWT VC signed with ES256, with holder key binding, delivered over direct_post.jwt.

OpenID® Certified™ by Egor Khaklin to the OpenID4VP 1.0 + HAIP 1.0 Verifier profile. polaris-oid4vp 1.0.0rc7 finished all eleven modules of the Foundation's hosted oid4vp-1final-verifier-haip-test-plan (sd_jwt_vc, direct_post.jwt) without failure, and the OpenID Foundation lists the certification (2026-09-24). It covers that version in that role: not an endorsement, not an audit, and not other versions. OpenID® and OpenID® Certified™ are trademarks of the OpenID Foundation, used under its certification terms.

Status: 1.0.0rc16, a release candidate, not certified: it carries the fixes made since 1.0.0rc7. Outside results: the Foundation's hosted suite (0.1.0, then 1.0.0rc7 for certification) and the implementations in the table below, re-run weekly. No operator other than the author has run it and no independent security review exists. Details: the scoreboard.

Try it in ten minutes, without cloning anything: the stranger's path takes a clean machine with Docker, this package and an unmodified walt.id wallet to an accepted presentation. If it fails for you, please open an issue.

Tested against

Outside OpenID4VP implementations present to this verifier, each unmodified unless its row says otherwise: configuration only (trust anchors, TLS roots). Every walk also sends controls that must be refused, because a verifier that accepts everything prints the same success line; among them a wrong issuer key under the same kid, the answered request again, a mismatched client_id, a key the wallet does not hold and an untrusted CA. A weekly canary re-runs the walks against the newest release on PyPI.

The author drove every walk: interoperability with those implementations, not use by their maintainers. Each walk is one script you can run against your own copy; to test your wallet, point it at polaris-oid4vp serve as below.

Install and run

pip install --pre polaris-oid4vp
polaris-oid4vp keygen --out ./pki --host verifier.example
polaris-oid4vp serve  --pki ./pki --port 9443 --issuer-jwks issuers.json

• keygen makes a CA, a leaf it signs and a listener certificate, and prints the client_id and the anchor a counterparty registers. The profile rejects a self-signed leaf and a trust anchor inside the chain; keygen avoids both. The CA and the leaf carry the key identifiers RFC 5280 asks for, which some wallets find a CA by. The listener certificate is marked for server authentication, which Apple's TLS policy requires even of a certificate a client trusts by name. Its keys are for testing.
• A wallet that fetches the request object by POST and asks for it encrypted (its wallet_metadata lists ECDH-ES in request_object_encryption_alg_values_supported, an enc this package produces, A128GCM or A256GCM, and a P-256 key in jwks) gets the signed object encrypted to that key, as the EUDI iOS wallet kit requires. A wallet that asks for nothing, or for something this cannot produce, gets the signed object.
• --verifier-info FILE puts attestations about the verifier into the request object, such as the registration certificate a registrar issues: a JSON array as OpenID4VP 1.0 section 5.1 has it, or one object, {"format": "registration_cert", "data": "<JWT>"}, as the German EUDI Wallet guide and its testing tool read it. The German ecosystem requires one for a PID request. This package carries it as given and does not check it.
• serve --issuer-trust-anchor ca.pem trusts an issuer that signs with its certificate in x5c, as HAIP issuers do (repeatable; each file may hold several PEM certificates). The leaf must chain to an anchor, directly or through the CA certificates the x5c sends after it (at most three, in order, each certifying the one before it; each a CA allowed to sign certificates, inside its validity period and its path length, with no critical extension this does not read, and none of them the anchor itself). The leaf must be inside its validity period and, when it states a key usage, include digitalSignature; one that states extended key usages must name one an issuer may hold (ISO 18013-5's document signer, as EUDI issuers use, or client auth, code signing or email protection). A leaf that states no key usage is not restricted by one. An iss must be a name the leaf gives: a URI subjectAltName exactly, or, for a leaf naming only DNS hosts, an https URL on one. Without iss, the certificate's subject is the issuer.
• --issuer-jwks trusts every key it lists for every iss, except one whose use, key_ops or alg says it is not for ES256 signatures; list one issuer's keys per verifier.
• --public-base-url https://verifier.example sets the HTTPS origin a wallet reaches this verifier by when it runs behind a reverse proxy or a tunnel, where the public URL differs from the local --bind/--port. It is used for the request_uri and response_uri; without it they are https://<--host>:<--port>.
• --no-local-tls serves the local listener over plain HTTP, for when that proxy or tunnel terminates TLS and provides the public HTTPS. The listener still binds --bind (localhost by default); pair it with --public-base-url, which is then the HTTPS request_uri a wallet uses.
• --claim names a claim to ask for (repeatable; without it, given_name and family_name): a name, a dotted path of object keys, or a JSON array of keys, optionally =VALUE (JSON) for the value it must have. A path asks for one member of a nested claim and nothing around it: --claim age_equal_or_over.18=true asks an EUDI PID whether its holder is 18 or over and nothing else, where --claim age_equal_or_over would ask for every age statement it holds. A presentation that withholds a claim, or discloses it with another value or type (1 is not true), is refused (claims). Array indices are not accepted: an undisclosed element is left out of the disclosed claims, so a position counted afterwards is not the one the issuer signed. --vct (repeatable) names the credential types to accept; without it, urn:eudi:pid:1. Verifier(claims=..., vct_values=...) takes the same, a claim as a name, a list of keys, or {"path": [...], "values": [...]}.
• serve with neither --issuer-jwks nor --issuer-trust-anchor refuses every presentation (issuer_key) and says so on stderr. An --issuer-jwks file it cannot read, or none of whose keys can verify ES256 when no anchor is given, stops serve before it listens (exit 2).
• The CLI is a test harness. A deployment embeds Verifier (it needs your status policy; see Revocation).

This is a separate package from polaris-verify because it listens on a socket and depends on cryptography; polaris-verify does neither.

Verifying a presentation

from polaris_oid4vp.sdjwt import verify_presentation

verdict = verify_presentation(
    presentation,                     # the ~-separated string the wallet sent
    expected_nonce=request_nonce,     # what YOUR request asked for
    expected_audience=client_id,
    trust_anchors=[anchor],           # or issuer_jwks=[...]
    expected_vct="urn:eudi:pid:1",    # the credential type you asked for
)
verdict.authentic, verdict.code, verdict.reason, verdict.claims

expected_nonce and expected_audience are required: reading them from the presentation would make every presentation replayable. sdjwt.py touches no socket and reads no configuration.

Recursive disclosures (SD-JWT 4.2.4.1) are supported.

Refusal codes are for the operator and never go on the wire. Every refused presentation gets one constant body, so the verifier is not a per-check oracle:

{"error": "invalid_request", "error_description": "the presentation was not accepted"}

Open: response timing still differs by which check refused; this is not measured.

The response JWE (jwe.py) accepts only ECDH-ES over P-256 with A128GCM or A256GCM, with a fresh encryption key per request. The listener (verifier.py, serve.py) is standard library only.

Revocation

verdict.revocation is one of seven states:

• A checked status that is not VALID is refused: with a resolver, Verifier answers a credential whose status list value is not 0 with the same 400 as any refusal (revoked). The other states are not facts about the credential and stay in the verdict for your policy.
• Opt-in: pass status_resolver= to Verifier(...) or verify_presentation. Without one nothing is fetched and the state is not_evaluated.
• status.py decides a Token Status List (draft-ietf-oauth-status-list) without opening a socket; decide_by_fetching takes your fetch callable.
• Who may publish status for whom is stated, not inferred: StatedAuthority records that a named key may publish for a named issuer at a named URI. Anything else is no_authority, and no request is sent to a URI an unvetted credential names.

Conformance run

git clone --depth 1 https://gitlab.com/openid/conformance-suite.git
cd conformance-suite && docker compose -f docker-compose-prebuilt.yml up -d
python3 scripts/polaris-oid4vp-conformance-drill.py

Seven negative modules PASS; four positive modules end in REVIEW (the suite wants a screenshot of a displayed result). The drill carries two negative controls: a verifier that refuses everything must fail the positive modules, and one that accepts everything must fail all seven negative ones.

The wallet canary runs the drill weekly against the newest release on PyPI, with the suite's prebuilt images at their newest (POLARIS_OID4VP_INSTALLED=1 makes it import the installed package instead of the tree). A run is not a certification.

Tests

cd packages/polaris-oid4vp && python3 -m unittest test_sdjwt test_jwe test_verifier \
    test_serve test_cli test_conformance_capture test_status

• 422 tests in seven files. test_conformance_capture replays a real direct_post.jwt response built by the OpenID Foundation suite's wallet (Nimbus JOSE), so this package's ECDH-ES, KDF, AAD binding and digests are checked against an independent implementation.
• scripts/polaris-oid4vp-mutation-drill.py makes each of the 120 refusals accept and requires a test to fail: 116 are caught, and the 4 survivors are declared with their reasons (measured 2026-10-01, after the day's review fixes; CI runs it on every push).
• Held-out boundary mutations (off-by-one windows, header binding, listener routing) each have a dedicated test class.