Skip to content

Commit a014938

Browse files
leifjleifj
committed
feat: add pre-flight CS-007 — Credential Presentation via DC API
Pre-flight conformance specification for credential presentation using the W3C Digital Credentials API (navigator.identity.get with OpenID4VP). - Complements CS-002 by defining DC API as invocation/transport layer - Normative requirements for wallet units and verifiers - Platform support considerations: browser extension polyfill (wallet-side) and verifier-side polyfill (JS/WASM) for fallback to direct OpenID4VP - References W3C DC API, OpenID4VP, and OpenID4VP-over-DC-API specs - Updates README with CS-007 in the under-development table
1 parent e86c986 commit a014938

2 files changed

Lines changed: 214 additions & 1 deletion

File tree

‎conformance-specs/README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@ graph TB
6262
| **WBCS #** | **WBCS Title** |
6363
| -------- | ------------ |
6464
| CS-005 | [European Business Wallet Unit Attestation (BWUA) Lifecycle](https://github.com/webuild-consortium/wp4-architecture/issues/177) |
65-
| CS-006 | [Issuance of Relying Party Access and Registration Certificates](https://github.com/webuild-consortium/wp4-architecture/issues/190) |
65+
| CS-006 | [Issuance of Relying Party Access and Registration Certificates](https://github.com/webuild-consortium/wp4-architecture/issues/190) |
66+
| CS-007 | [Credential Presentation via the Digital Credentials API (Pre-flight)](cs-07-credential-presentation-dc-api.md) |
6667

6768

‎conformance-specs/cs-07-credential-presentation-dc-api.md‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
# WE BUILD - Pre-flight Conformance Specification: Credential Presentation via the Digital Credentials API
2+
3+
Version 0.1 / Pre-flight Draft
4+
Date: 4 July 2026
5+
6+
**Authors**: WP4 Architecture
7+
8+
* Leif Johansson <leifj@siros.org>
9+
10+
Table Of Contents
11+
12+
- [1. Introduction](#1-introduction)
13+
- [2. Scope](#2-scope)
14+
- [3. Normative Language](#3-normative-language)
15+
- [4. Roles and Components](#4-roles-and-components)
16+
- [5. Protocol Overview](#5-protocol-overview)
17+
- [6. High-level Flows](#6-high-level-flows)
18+
- [6.1 Same-device Presentation via DC API](#61-same-device-presentation-via-dc-api)
19+
- [7. Normative Requirements](#7-normative-requirements)
20+
- [7.1 Wallet Unit Requirements](#71-wallet-unit-requirements)
21+
- [7.2 Verifier Requirements](#72-verifier-requirements)
22+
- [8. Platform and Browser Support Considerations](#8-platform-and-browser-support-considerations)
23+
- [8.1 Browser Extension Polyfill (Wallet-side)](#81-browser-extension-polyfill-wallet-side)
24+
- [8.2 Verifier-side Polyfill](#82-verifier-side-polyfill)
25+
- [9. Conformance](#9-conformance)
26+
- [References](#references)
27+
28+
# 1. Introduction
29+
30+
This document is a **pre-flight conformance specification** as defined in the [Pre-flight CS ADR](../adr/pre-flight-CS.md). It is intended to enable early testing of credential presentation using the W3C Digital Credentials API (DC API) [1] within the WE BUILD ecosystem. The goal is to gather implementation experience and testing feedback that will inform a future full conformance specification.
31+
32+
The Digital Credentials API provides a browser-native mechanism for verifiers to request credential presentations from wallet units. This removes the need for custom protocol schemes (such as `openid4vp://`) for same-device web flows and integrates credential presentation into the browser's security model.
33+
34+
This specification complements **CS-002 (Credential Presentation)** [2] by defining how the same OpenID4VP-based presentation protocol operates when the browser's DC API serves as the invocation and transport layer, rather than custom URL schemes or redirect flows.
35+
36+
# 2. Scope
37+
38+
This specification defines the conformance expectations for credential presentation using the Digital Credentials API:
39+
40+
* **In scope:**
41+
* Same-device web presentation flows using `navigator.identity.get()` with the `"digital-credentials"` provider
42+
* Integration of OpenID4VP request/response with the DC API transport
43+
* Verifier-side JavaScript API usage
44+
* Wallet unit registration and response handling via the DC API
45+
* Limitations of web-based wallet units and known mitigations
46+
47+
* **Out of scope:**
48+
* Cross-device presentation flows (covered by CS-002)
49+
* Proximity-based presentation (e.g. ISO 18013-5 / BLE)
50+
* Credential issuance (covered by CS-001)
51+
* Detailed trust evaluation and trust list resolution (covered by other WE BUILD specifications)
52+
53+
# 3. Normative Language
54+
55+
The keywords **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL** are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).
56+
57+
> **Note:** As a pre-flight specification, the normative requirements herein are preliminary and subject to revision based on testing feedback.
58+
59+
# 4. Roles and Components
60+
61+
| Role | Description |
62+
|------|-------------|
63+
| **Wallet Unit (WU)** | A native application or web application acting on behalf of the Holder, registered with the platform as a digital credential provider. |
64+
| **Holder** | The person controlling the Wallet Unit. |
65+
| **Verifier (Relying Party)** | A web application that requests credential presentations via the DC API. |
66+
| **User Agent (Browser)** | The browser mediating the DC API interaction between the Verifier and the Wallet Unit. |
67+
| **Wallet Companion** | A browser extension that bridges the DC API to web-based wallet units that cannot natively register as credential providers (see §8.1). |
68+
69+
# 5. Protocol Overview
70+
71+
The Digital Credentials API [1] extends the W3C Credential Management API [3] to support digital identity credentials. A verifier calls `navigator.identity.get()` with a request containing an OpenID4VP presentation request. The browser mediates the interaction:
72+
73+
1. The verifier constructs an OpenID4VP request object and passes it to the DC API.
74+
2. The browser identifies registered wallet units capable of fulfilling the request.
75+
3. The browser presents a wallet selection UI to the user (if multiple wallets are available).
76+
4. The selected wallet unit receives the request, processes it, obtains holder consent, and returns the presentation response.
77+
5. The browser delivers the response back to the verifier's JavaScript context.
78+
79+
This flow keeps the OpenID4VP request/response semantics from CS-002 intact while replacing the invocation and transport mechanism with the browser-native DC API.
80+
81+
The key specification governing this interaction is the **W3C Digital Credentials API** [1], which at the time of writing is a Working Draft. Browser support is available in Chrome 128+ (Android) and is progressing in other browsers.
82+
83+
# 6. High-level Flows
84+
85+
## 6.1 Same-device Presentation via DC API
86+
87+
This flow describes how a verifier web application requests a credential presentation from a wallet unit using the Digital Credentials API.
88+
89+
### 6.1.1 Verifier Constructs Presentation Request
90+
91+
The verifier constructs an OpenID4VP authorization request as specified in CS-002 §6.1.1. The request is encoded as a JSON object suitable for the DC API.
92+
93+
### 6.1.2 DC API Invocation
94+
95+
The verifier invokes the DC API:
96+
97+
```javascript
98+
const presentationResponse = await navigator.identity.get({
99+
digital: {
100+
providers: [{
101+
protocol: "openid4vp",
102+
request: JSON.stringify(openid4vpRequest)
103+
}]
104+
}
105+
});
106+
```
107+
108+
The `protocol` field MUST be set to `"openid4vp"`. The `request` field contains the serialized OpenID4VP authorization request.
109+
110+
### 6.1.3 Browser Mediation
111+
112+
The browser:
113+
1. Identifies installed wallet units registered for the `"openid4vp"` protocol.
114+
2. Presents a selection UI to the user if multiple wallets are available.
115+
3. Forwards the request to the selected wallet unit.
116+
117+
### 6.1.4 Wallet Processing and Holder Consent
118+
119+
The wallet unit:
120+
1. Parses and validates the OpenID4VP request as specified in CS-002 §6.1.3.
121+
2. Identifies matching credentials.
122+
3. Presents a consent screen to the holder, showing the requested attributes and the verifier's identity.
123+
4. Upon consent, generates the verifiable presentation with selective disclosure as appropriate.
124+
125+
### 6.1.5 Response Delivery
126+
127+
The wallet unit returns the OpenID4VP response via the DC API. The browser delivers the response to the verifier's JavaScript context as the resolved value of the `navigator.identity.get()` promise.
128+
129+
### 6.1.6 Verifier Validation
130+
131+
The verifier validates the presentation response as specified in CS-002 §6.1.7, including:
132+
- Signature verification
133+
- Credential status checks
134+
- Trust chain validation
135+
136+
# 7. Normative Requirements
137+
138+
## 7.1 Wallet Unit Requirements
139+
140+
| ID | Requirement | Reference |
141+
|----|-------------|-----------|
142+
| WU-DC-01 | The WU MUST register itself with the platform as a digital credential provider for the `"openid4vp"` protocol. | [1] §3.1 |
143+
| WU-DC-02 | The WU MUST accept OpenID4VP authorization requests received via the DC API. | [1], [4] |
144+
| WU-DC-03 | The WU MUST return OpenID4VP authorization responses via the DC API response mechanism. | [1], [4] |
145+
| WU-DC-04 | The WU MUST support the same credential formats and selective disclosure mechanisms as required by CS-002 §7.1. | [2] |
146+
| WU-DC-05 | The WU SHOULD support both DC API and `openid4vp://` invocation to ensure backward compatibility. | [2], [4] |
147+
148+
## 7.2 Verifier Requirements
149+
150+
| ID | Requirement | Reference |
151+
|----|-------------|-----------|
152+
| VP-DC-01 | The Verifier MUST use `navigator.identity.get()` with the `"digital-credentials"` provider type when the DC API is available. | [1] |
153+
| VP-DC-02 | The Verifier MUST set the `protocol` field to `"openid4vp"` in the DC API request. | [1], [5] |
154+
| VP-DC-03 | The Verifier MUST construct a valid OpenID4VP authorization request as specified in CS-002 §7.2. | [2], [4] |
155+
| VP-DC-04 | The Verifier SHOULD implement fallback to `openid4vp://` custom URL scheme or cross-device flow when the DC API is not available. | [2] |
156+
| VP-DC-05 | The Verifier MUST call the DC API from a [secure context](https://w3c.github.io/webappsec-secure-contexts/) and in response to a user activation event. | [1] §2.1 |
157+
158+
# 8. Platform and Browser Support Considerations
159+
160+
The DC API is not yet universally supported across browsers and platforms. At the time of writing, presentation support is available in Chrome 141+ on Android, macOS, and desktop platforms, with other browsers at various stages of development [6]. Verifiers and wallet providers MUST plan for environments where the DC API is absent or where the `"openid4vp"` protocol is not natively supported.
161+
162+
Two complementary polyfill strategies exist to bridge these gaps. They address different sides of the interaction and MAY be deployed independently or together.
163+
164+
## 8.1 Browser Extension Polyfill (Wallet-side)
165+
166+
The DC API requires wallet units to register as credential providers at the OS or browser level. Web-based wallet units — running as ordinary web applications or PWAs — cannot do this because the registration path requires native platform integration (e.g. Android CredentialManager, iOS AuthenticationServices).
167+
168+
A **browser extension** can act as a polyfill on the wallet side by:
169+
170+
1. Registering itself as a credential provider proxy with the browser.
171+
2. Intercepting DC API requests issued by verifiers via `navigator.identity.get()`.
172+
3. Routing the OpenID4VP request to a web-based wallet that has registered with the extension.
173+
4. Returning the wallet's OpenID4VP response back through the DC API to the verifier.
174+
175+
This approach is transparent to verifiers: they use the standard DC API and are unaware that the response originates from a web wallet via the extension rather than a native wallet. The trade-off is that the user must install the extension.
176+
177+
This pattern enables web wallets to participate in DC API flows on platforms where native wallet registration is not possible.
178+
179+
## 8.2 Verifier-side Polyfill
180+
181+
When the DC API is not available in the browser at all — because the browser does not implement it, or because no wallet (native or extension-based) supports the `"openid4vp"` protocol — the verifier must fall back to invoking OpenID4VP directly, as specified in CS-002.
182+
183+
A **verifier-side polyfill** (implemented as a JavaScript library or WebAssembly module) can bridge this gap by:
184+
185+
1. Detecting whether the DC API is available and whether a compatible wallet is registered.
186+
2. If the DC API is available, using it as the primary invocation path (this specification).
187+
3. If the DC API is unavailable or the request fails with a `NotSupportedError`, falling back to:
188+
- **Same-device flow:** Redirecting to an `openid4vp://` custom URL scheme with the authorization request (CS-002 §6.1).
189+
- **Cross-device flow:** Displaying a QR code encoding the OpenID4VP request URI for scanning by a mobile wallet (CS-002 §6.2).
190+
191+
This approach is transparent to the wallet: it receives a standard OpenID4VP request regardless of whether the verifier used the DC API or a direct invocation. The trade-off is that the verifier takes on responsibility for wallet invocation, transport, and response handling that the DC API would otherwise mediate.
192+
193+
Verifier-side polyfill libraries SHOULD present a unified API to the verifier application, abstracting the detection and fallback logic so that application code does not need to manage multiple invocation paths directly.
194+
195+
# 9. Conformance
196+
197+
A **Verifier** conforms to this specification if it satisfies all requirements in §7.2.
198+
199+
A **Wallet Unit** conforms to this specification if it satisfies all requirements in §7.1.
200+
201+
Conformance testing for this pre-flight specification will be defined as part of the feedback process described in the [Pre-flight CS ADR](../adr/pre-flight-CS.md). Implementers are encouraged to report their testing experience to inform the development of a full conformance specification.
202+
203+
# References
204+
205+
| # | Reference |
206+
|---|-----------|
207+
| [1] | W3C, "Digital Credentials API", W3C Working Draft, https://wicg.github.io/digital-credentials/ |
208+
| [2] | WE BUILD, "Conformance Specification: Credential Presentation v1.1 (CS-002)", 2026 |
209+
| [3] | W3C, "Credential Management Level 1", W3C Recommendation, https://www.w3.org/TR/credential-management-1/ |
210+
| [4] | OpenID Foundation, "OpenID for Verifiable Presentations (OpenID4VP) 1.0", https://openid.net/specs/openid-4-verifiable-presentations-1_0.html |
211+
| [5] | OpenID Foundation, "OpenID4VP over the W3C Digital Credentials API", https://openid.net/specs/openid-4-verifiable-presentations-1_0-dc-api.html |
212+
| [6] | W3C Web Identity & Credentials Adoption CG, "Digital Credentials API Ecosystem Support", https://digitalcredentials.dev/ecosystem-support |

0 commit comments

Comments
 (0)