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.

HAIP is what a deployment opts into, not what every configuration gets. Production assurance (AssuranceProduction in issuer, wallet, verifier and mdocdcapi; walletflow without Development) enforces the HAIP requirements that bind any deployment. Package haip gives HAIP's configuration (RecommendedIssuerConfig, RecommendedVerifierConfig, RecommendedWalletConfig, RecommendedAuthorizationServerConfig) and checks an issuer's HAIP-specific profiling (haip.ValidateIssuerConfig, which issuer.New runs when issuer.Config.Profile is haip.IssuerProfile{}). walletflow.ProfileHAIP holds a wallet to HAIP issuers. See ARCHITECTURE.md's "Relationship to FAPIgo" section for HAIP's overrides of FAPI 2.0.

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, identifierlist, certrevocation, 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; verifier.TransactionCodec encodes and seals a transaction for a production store). TransactionsConfig.Status (a verifier.StatusPolicy over a statuslist.Checker) checks each credential's revocation, an mdoc's identifier list included, before Accept runs the Verifier's own checks (verifier.Chain composes several); production requires it, or an explicit NoStatusCheck. The issuer key resolvers' required Revocation (certrevocation.CRLs) checks its issuer certificate's.
• 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, and identifierlist signs (or serves) an mdoc identifier list.
• 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 — or lets verifier.Transactions do both, with TransactionsConfig.Origins listing the pages that may ask (required under production). 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 (with VerifyParams.Origins, required under production), 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/.
• Durable stores — the separate sqlstore module keeps the issuer's, the verifier's and walletflow's stores in PostgreSQL or SQLite through database/sql: versioned migrations, atomic consumes and updates across processes, records optionally sealed, and a Sweep for expired ones. For a whole issuer deployment it shares one database with FAPIgo's fapigo/sqlstore, which keeps the Authorization Server's stores.
• Your own stores and resolvers — issuer/issuertest, verifier/verifiertest and walletflow/storetest hold contract tests to run against them.

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. It wires the production entry points above (verifier.Transactions, issuer.New with haip.IssuerProfile, walletflow), though under development assurance and with in-memory stores by default (-db keeps the issuer's in SQLite, with both sqlstore modules); its README lists those demo-only settings.

The four cmd/conformance-* binaries under conformance/ are test harnesses for the OIDF conformance suite, not models for a deployment. They produced each role's certification results, but they run under development assurance with in-memory stores, trust the suite's throwaway certificates, and drive the lower-level APIs the suite exercises rather than the session-bound ones: the conformance verifier keeps its own session map instead of verifier.Transactions, so it has no same-device response_code bound to the browser, and the conformance wallets skip walletflow. Each conformance/<role>/README.md says what not to copy from its binary.

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. UPGRADING.md says what to change for each release's breaking changes.

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.