OID4VCgo

OpenID Certified™ OpenID4VCI 1.0 + OpenID4VP 1.0, under the HAIP 1.0 profile, for Go.

OID4VCgo is a sister library to FAPIgo, targeting the full OpenID4VC High Assurance Interoperability Profile (HAIP) 1.0 — the OpenID Foundation's interoperability profile for digital credential issuance and presentation where a high level of security and privacy is required (e.g. mobile driving licences and other government-grade digital identity credentials). HAIP profiles two base specifications — OpenID for Verifiable Credential Issuance 1.0 and OpenID for Verifiable Presentations 1.0 — and requires compliance with the applicable provisions of FAPI 2.0 Security Profile Final, the same security profile FAPIgo implements and is OpenID Certified™ against.

This isn't a generic, profile-agnostic OID4VCI/OID4VP implementation with HAIP as an optional layer on top: HAIP's overrides — DPoP mandatory, Wallet Attestation in place of private_key_jwt/mTLS, HAIP's own algorithm requirements — are unconditional in the issuer/wallet/ verifier packages themselves. See ARCHITECTURE.md's "Relationship to FAPIgo" section for the specific list.

OpenID Certified™ by Oscar Sanderson for all four HAIP roles, as tested for OID4VCgo 0.12.0: OID4VCI 1.0 + HAIP 1.0 Issuer and Wallet, and OID4VP 1.0 + HAIP 1.0 Verifier and Wallet, each for both SD-JWT VC and mdoc credentials. This is a result submitted to and published by the OpenID Foundation, not merely a self-run pass against the live suite. It is a statement of tested conformance, not an OIDF endorsement of OID4VCgo generally. See conformance/README.md#oidf-certification for every certified profile.

⚠ Pre-1.0, APIs may still change. Every package — issuer, wallet, verifier, walletflow, credential/sdjwtvc, credential/mdoc, statuslist, attestation, dcql, oid4vpmdoc, mdocdcapi, proximity, registration, haip, storage — and the separate mobile module are implemented and tested. All four roles were OpenID Certified as 0.12.0 (see above), and every later release is checked against the same OIDF test plans by the daily conformance workflows. The OpenID4VP wallet harness is also run on each pull request, daily, and on each release, against polaris-oid4vp, an independent verifier, with negative controls the OIDF suite lacks. Those certified profiles are the redirect flows: the Digital Credentials API (OpenID4VP's dc_api.jwt and mdocdcapi's org-iso-mdoc) and in-person presentation (proximity) aren't certified. org-iso-mdoc has run in Safari on an iPhone, with the demo iOS wallet as its document provider, and OpenID4VP over the DC API in Chrome on the Android emulator, with the demo Android wallet as its Credential Manager provider; proximity is tested against ISO/IEC 18013-5 Annex D, not yet between two devices. See ARCHITECTURE.md for the full package-by-package status and what, if anything, remains.

See SPECIFICATIONS.md for the exact specification and Internet-Draft versions this project targets — every one of them was verified against the spec's own published/status text and, for drafts, the exact draft-…-NN a Final OIDF spec pins, rather than assumed.

go get github.com/idfoundry/oid4vcgo

(Go module paths are lowercased; the GitHub repository itself is IDFoundry/OID4VCgo.)

Usage

Each role package's own doc comment (go doc github.com/idfoundry/oid4vcgo/issuer, .../wallet, .../verifier, or pkg.go.dev) is the primary API reference — it documents what's implemented, what's deliberately out of scope, and the boundary with fapigo/server/fapigo/client for everything OAuth 2.0/FAPI 2.0-level. Runnable Example functions (e.g. wallet.ExampleWallet_FetchAuthorizationRequest) cover specific gaps between packages — like fetching a Verifier's request_uri before handing it to wallet.ParseAuthorizationRequest — that aren't obvious from either package's own doc comment alone; go test runs and checks these automatically, so they can't silently drift from the real API.

Where to start, by role:

• Verifier — verifier.Transactions runs a presentation session end to end (request object, direct_post.jwt response, same-device response_code bound to the browser), with its RequestObjectHandler and ResponseHandler as ready http.Handlers over a verifier.TransactionStore (storage.NewVerifierTransactionStore for development). VerifiedCredential.StatusListRef plus statuslist.Checker check revocation.
• Wallet — wallet.EncryptionFromMetadata picks credential request/response encryption from the Issuer's metadata; wallet.Respond answers a verified Authorization Request in one call (after showing the holder wallet.PreviewPresentation).
• Issuer — haip.RecommendedAuthorizationServerConfig and haip.RecommendedWalletClient set up FAPIgo's Authorization Server for HAIP; issuer.CredentialHandler serves the Credential Endpoint (with issuer/fapiresource checking access tokens), asking you only what to issue — or to defer (CredentialRequest.Defer, resolved later with IssueDeferredCredential) — and DeferredCredentialHandler/NotificationEndpointHandler serve the other two protected endpoints; issuer.NewError builds an OID4VCI error response (e.g. credential_request_denied); statuslist.Publisher serves a signed Status List Token.
• A browser's Digital Credentials API — the Verifier builds an OpenID4VP request with Verifier.BuildDCAPIAuthorizationRequest and checks the answer with Verifier.VerifyResponse, setting VerifyResponseRequest.Origin to its page's origin and ExpectedOrigins to the request's. A wallet parses the request with wallet.ParseDCAPIRequestData (unsigned, signed or multi-signed). Safari's org-iso-mdoc protocol is package mdocdcapi, both sides: BuildRequest and VerifyResponse for the page, ParseRequest and Incoming.Respond for the wallet.
• In person — package proximity is ISO/IEC 18013-5 over BLE: NewDeviceSession for the holder, NewReaderSession for the reader. The app carries the BLE messages; the package does everything else.
• A wallet app — package walletflow runs issuance and presentation as sessions over keys and stores the app supplies, and a Wallet Provider for issuers that ask for attestations (HAIP 1.0, an opt-in profile): StartIssuance, StartPresentation, StartDCAPIPresentation (OpenID4VP over the DC API), StartMdocPresentation (org-iso-mdoc) and StartProximityPresentation. The separate mobile module binds it for iOS (the OID4VCWallet Swift package) and Android (a Kotlin library), each with its documentation: Swift and Kotlin (guides). See also mobile/MOBILE.md and mobile/.
• Your own stores and resolvers — issuer/issuertest and verifier/verifiertest hold contract tests to run against them.

For a complete, real integration, see the four cmd/conformance-* binaries under conformance/: each pairs this library's own role package (issuer, wallet, verifier) with real HTTP and, where applicable, a real fapigo/server/fapigo/client, and each is the binary that produced its role's OIDF certification results (see ARCHITECTURE.md and each binary's own conformance/<role>/README.md for what was verified). They're a better model for a real deployment's wiring than the package tests alone, which exercise each function in isolation rather than a full request/response cycle over the network. For an end-to-end application — a gmrtd passport turned into both credential formats, a browser and a command-line wallet, and a verifier with revocation — see examples/passport-vdc.

Relevant specifications

• OpenID for Verifiable Credential Issuance 1.0
• OpenID for Verifiable Presentations 1.0
• OpenID4VC High Assurance Interoperability Profile 1.0
• FAPI 2.0 Security Profile

See SPECIFICATIONS.md for the complete list, including the pinned credential-format, attestation, and status-list Internet-Drafts.

Contributing

See CONTRIBUTING.md for the conformance-first development philosophy and pre-PR checklist, and SECURITY.md to report a vulnerability.

License

MIT — see LICENSE.

OpenID®, OpenID Connect™, and OpenID Certified™ are trademarks or registered trademarks of the OpenID Foundation in the United States and other countries. Use of these marks here is limited to the certified conformance statement above, per Section 3(d) of the OpenID Certification Terms and Conditions.