add oauth2 example

Signed-off-by: F-Node-Karlsruhe <christian.fries@eecc.de>

Author: F-Node-Karlsruhe

.cursor/notes/index.md

@@ -18,7 +18,6 @@ oid4vp/
 │   ├── oid4vp-core/                  # Framework-neutral library (artifact: oid4vp)
 │   ├── oid4vp-spring/                # Spring Boot auto-configuration
 │   └── oid4vp-spring-boot-starter/   # Starter dependency aggregator
-├── docs/API_INTEGRATION_ROADMAP.md   # Embedding / discovery-service integration plan
 ├── scripts/release.js
 ├── CHANGELOG.md
 └── README.md
@@ -30,7 +29,7 @@ See [module-layout.md](module-layout.md) for embedding patterns, pluggable depen
 
 - **Presentation request generation** via `Oid4Vp.generatePresentationRequest()`
 - **Wallet URL building** with inline or `request_uri` transport
-- **Direct post handling** with optional `response_code` (`DirectPostResult`)
+- **Direct post handling** with optional `response_code` (`DirectPostResult`) — OAuth2 login completion documented in `README.md`
 - **Pluggable** repository and verifier; `Oid4Vp.builder()` for tests and host wiring
 - **DCQL query models**, GS1 template, `PresentationParser`, `PresentationClaims` extraction via `PresentationRequestDefinition`, sealed `Oid4VpError`
 
@@ -47,5 +46,4 @@ Release: `npm run release minor` (from repo root). Version lives in parent `oid4
 ## Important Files
 
 - `oid4vp-java/oid4vp-core/src/main/java/de/eecc/oid4vc/oid4vp/api/Oid4Vp.java` — main entry point
-- `docs/API_INTEGRATION_ROADMAP.md` — full refactor rationale and discovery-service notes
 - `CHANGELOG.md` — version history

.cursor/notes/module-layout.md

@@ -17,6 +17,7 @@
 - `DirectPostHandler` → `DirectPostResult` — post-verification outcome (`ISSUE_RESPONSE_CODE`, `COMPLETE`, `CUSTOM`)
 - `GenerateRequestOptions.builderSupplier` + `beforeSave` — set app fields before `save()`
 - `PollStatusResolver` — override poll UX; default handles `response_code`, `completed`, verification errors
+- OAuth2 login: `issueResponseCode` → poll or redirect → redeem `state`+`response_code` at token endpoint → `invalidateResponseCode`
 - `Oid4VpError` sealed hierarchy — map errors without parsing HTTP status from messages
 - `PresentationRequestDefinition.extractPresentationClaims` + `Oid4Vp.extractPresentationClaims` — template-driven claim extraction from stored `vp_token`
 

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Documented OAuth 2.0 login completion via `response_code` in `README.md`
+
 ## [0.5.0] - 2026-06-15
 
 ### Added

README.md

@@ -98,6 +98,58 @@ PresentationClaims claims = oid4Vp.extractPresentationClaims(Gs1LicenseRequest.I
 List<String> gcps = claims.values();
 ```
 
+### OAuth 2.0 login completion (`response_code`)
+
+After the wallet delivers a verified presentation via `direct_post`, a one-time `response_code` bridges the
+OpenID4VP step to your OAuth 2.0 token endpoint.
+
+**Flow**
+
+1. The wallet POSTs `vp_token` and `state` to your `response_uri`.
+2. You call `oid4Vp.processDirectPost(vpToken, state, handler)`; the library verifies presentations and invokes your handler.
+3. For login flows, return `DirectPostResult.issueResponseCode()` from the handler. The library stores the verified session and issues a single-use `response_code`.
+4. The frontend obtains that code in one of two ways:
+   - **Wallet redirect** (`redirect(true)`): the wallet redirects the user agent to `redirect_uri#response_code=…`.
+   - **QR / poll** (`redirect(false)`): the frontend polls `GET …/response/{state}` until it receives `{ "response_code": "…" }` (204 while pending).
+5. The frontend exchanges `state` + `response_code` at your OAuth 2.0 token endpoint (for example `POST …/token`).
+6. You resolve the stored presentation by `response_code`, validate it matches `state`, extract claims, issue access/refresh tokens, and call `oid4Vp.invalidateResponseCode(request)` so the code cannot be reused.
+
+Non-login flows (for example “add credential without signing in”) can return `DirectPostResult.complete()` instead; polling then returns `{ "completed": true }` with no `response_code`.
+
+**Server-side example** (adapt paths and token issuance to your application):
+
+```java
+import com.fasterxml.jackson.databind.JsonNode;
+import de.eecc.oid4vc.oid4vp.PresentationClaims;
+import de.eecc.oid4vc.oid4vp.VpTokenResponse;
+import de.eecc.oid4vc.oid4vp.api.DirectPostResult;
+
+import java.util.Optional;
+
+// Wallet direct_post → POST /api/auth/oid4vp/response
+VpTokenResponse.DirectPostResponse directPostResponse =
+        oid4Vp.processDirectPost(vpToken, state, (LoginPresentationRequest request, JsonNode vpTokenNode) -> {
+            PresentationClaims claims = oid4Vp.extractPresentationClaims(myDefinition, vpTokenNode);
+            // persist claims on request if needed for token redemption
+            return DirectPostResult.issueResponseCode();
+        });
+
+// QR poll → GET /api/auth/oid4vp/response/{state}  (204 until ready)
+Optional<VpTokenResponse.PollResponse> poll = oid4Vp.pollPresentationStatus(state);
+
+// Token endpoint → POST /api/auth/oid4vp/token  (state + response_code)
+LoginPresentationRequest stored = oid4Vp
+        .findPresentationRequestByResponseCode(responseCode, LoginPresentationRequest.class)
+        .orElseThrow(() -> new BadRequestException("Unknown or expired response_code"));
+if (!stored.getState().equals(state)) {
+    throw new BadRequestException("response_code does not match state");
+}
+PresentationClaims claims = oid4Vp.extractPresentationClaims(myDefinition, stored);
+TokenResult tokens = issueSessionTokens(claims); // your JWT / OAuth2 issuance
+oid4Vp.invalidateResponseCode(stored);
+```
+
+
 Lower-level access: `definition.extractPresentationClaims(vpTokenNode)` or `PresentationParser` for format-specific parsing.
 
 #### Built-in template: GS1 License Presentation

oid4vp-java/oid4vp-core/pom.xml

@@ -7,7 +7,7 @@
     <parent>
         <groupId>de.eecc.oid4vc</groupId>
         <artifactId>oid4vp-parent</artifactId>
-        <version>0.5.1-SNAPSHOT</version>
+        <version>0.5.0</version>
     </parent>
 
     <artifactId>oid4vp</artifactId>

oid4vp-java/oid4vp-core/src/main/java/de/eecc/oid4vc/oid4vp/api/GenerateRequestOptions.java

@@ -16,9 +16,9 @@
  *
  * <pre>{@code
  * oid4Vp.generatePresentationRequest(
- *     GenerateRequestOptions.<DiscoveryPresentationRequest>builder(Gs1LicenseRequest.INSTANCE)
+ *     GenerateRequestOptions.<ExtendedPresentationRequest>builder(Gs1LicenseRequest.INSTANCE)
  *         .redirect(false)
- *         .builderSupplier(() -> DiscoveryPresentationRequest.builder()
+ *         .builderSupplier(() -> ExtendedPresentationRequest.builder()
  *             .purpose(Oid4VpPurpose.ADD_ORG_GCPS)
  *             .organizationId(orgId))
  *         .build());

oid4vp-java/oid4vp-spring-boot-starter/pom.xml

@@ -7,7 +7,7 @@
     <parent>
         <groupId>de.eecc.oid4vc</groupId>
         <artifactId>oid4vp-parent</artifactId>
-        <version>0.5.1-SNAPSHOT</version>
+        <version>0.5.0</version>
     </parent>
 
     <artifactId>oid4vp-spring-boot-starter</artifactId>

oid4vp-java/oid4vp-spring/pom.xml

@@ -7,7 +7,7 @@
     <parent>
         <groupId>de.eecc.oid4vc</groupId>
         <artifactId>oid4vp-parent</artifactId>
-        <version>0.5.1-SNAPSHOT</version>
+        <version>0.5.0</version>
     </parent>
 
     <artifactId>oid4vp-spring</artifactId>

oid4vp-java/pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>de.eecc.oid4vc</groupId>
     <artifactId>oid4vp-parent</artifactId>
-    <version>0.5.1-SNAPSHOT</version>
+    <version>0.5.0</version>
     <packaging>pom</packaging>
 
     <name>oid4vp-parent</name>