@openeudi/openid4vp 0.5.0 → 0.7.0

package/README.md

@@ -116,12 +116,104 @@ if (result.valid) {
 } else {
   console.warn("mismatch reasons:", result.match.unmatched);
   // each entry: { queryId, reason, detail? }
-  // reason ∈ { format_mismatch, vct_mismatch, doctype_mismatch, missing_claims, trusted_authority_mismatch, no_credential_found }
+  // reason ∈ { format_mismatch, vct_mismatch, doctype_mismatch, missing_claims, value_mismatch, trusted_authority_mismatch, no_credential_found /* only when the candidate list is empty */ }
 }
 ```
 
 Mismatches return `valid: false` — they do not throw. Only crypto/structural failures (malformed VP tokens, invalid signatures, expired credentials) and malformed DCQL queries throw exceptions.
 
+> **Privacy — diagnostics are verifier-internal.** `match.unmatched[].reason` and `detail` (including `value_mismatch`) are intended for verifier-side logging, debugging, and admin UIs. OpenID4VP §11 warns that per-claim verification outcomes can reveal wallet contents to observers. Do NOT echo these diagnostics into the OpenID4VP wire response sent back to the wallet, into end-user-visible error messages that another party could correlate, or into public analytics/third-party logs. The protocol's own error codes are the public interface; these fields are your internal instrumentation.
+
+## Signed authorization requests (x509_san_dns)
+
+For flows that require a signed request object (JAR) per OpenID4VP 1.0 §5.10, use `createSignedAuthorizationRequest`:
+
+```ts
+import { createSignedAuthorizationRequest } from "@openeudi/openid4vp";
+
+const req = await createSignedAuthorizationRequest({
+  hostname: "verifier.example.com",
+  requestUri: "https://verifier.example.com/request.jwt",
+  responseUri: "https://verifier.example.com/response",
+  nonce,
+  signer: verifierKeyPair,          // CryptoKeyPair with public+private
+  certificateChain: [leafCertDer],  // DER-encoded, leaf SAN DNSName must equal hostname
+  encryptionKey: {
+    publicJwk: encryptionPublicJwk, // must include alg, e.g. "ECDH-ES"
+  },
+  vpFormatsSupported: {
+    "dc+sd-jwt": { "sd-jwt_alg_values": ["ES256"] },
+  },
+}, dcqlQuery);
+
+// req.uri — the short URI to hand to the wallet
+// req.requestObject — the JWS the verifier must host at requestUri
+//                     (Content-Type: application/oauth-authz-req+jwt)
+```
+
+The caller hosts `req.requestObject` at `requestUri` (the library does not host HTTP). The library verifies that the signing key's public SPKI matches the leaf certificate's public key — an attempt to sign with a mismatched key fails with `SignedRequestBuildError: signing_key_cert_mismatch`.
+
+## Authorization responses (direct_post and direct_post.jwt)
+
+Wallets POST the Authorization Response to your `responseUri`. The library is stateless — you MUST compare the envelope's `state` against the value you issued before treating the response as trustworthy. The recommended pattern differs slightly between the unencrypted and encrypted modes.
+
+### Unencrypted (`direct_post`)
+
+The envelope arrives as form-encoded JSON; parse it, check `state`, then verify:
+
+```ts
+import { verifyAuthorizationResponse } from "@openeudi/openid4vp";
+
+const envelope = parsedVpTokenObject; // { vp_token, state, ... }
+
+if (envelope.state !== submittedState) {
+  throw new Error("state mismatch — possible CSRF / replay");
+}
+
+const result = await verifyAuthorizationResponse(envelope, dcqlQuery, {
+  trustedCertificates: [issuerCertDer],
+  nonce,
+});
+```
+
+### Encrypted (`direct_post.jwt`)
+
+The wallet wraps the envelope in a JWE. Decrypt explicitly so you can check `state` against the decrypted envelope **before** verification runs:
+
+```ts
+import {
+  decryptAuthorizationResponse,
+  verifyAuthorizationResponse,
+} from "@openeudi/openid4vp";
+
+const decrypted = await decryptAuthorizationResponse(
+  form.get("response"), // the JWE string
+  verifierEncryptionPrivateKey,
+);
+
+if (decrypted.state !== submittedState) {
+  throw new Error("state mismatch — possible CSRF / replay");
+}
+
+const result = await verifyAuthorizationResponse(decrypted, dcqlQuery, {
+  trustedCertificates: [issuerCertDer],
+  nonce,
+});
+```
+
+`verifyAuthorizationResponse` also accepts the JWE directly via `{ response: jwe }` together with `options.decryptionKey` — but that path makes the `state` check easy to skip, since the caller never holds the decrypted envelope. Prefer the explicit two-step pattern above.
+
+`verifyAuthorizationResponse` accepts the OpenID4VP 1.0 §8.1 envelope shape: `vp_token` is always an object keyed by DCQL credential query id, with arrays of presentations. This release supports **single-credential single-presentation only** — multi-credential queries or multi-presentation arrays throw `MultipleCredentialsNotSupportedError`.
+
+### Supported JWE algorithms
+
+`direct_post.jwt` decryption supports:
+
+- `alg`: `ECDH-ES` (driven by the encryption JWK's `alg` parameter)
+- `enc`: `A128GCM`, `A256GCM` (HAIP requires both)
+
+Other algorithms throw `UnsupportedJweError`.
+
 ### ParseOptions / VerifyOptions
 
 Both `parsePresentation` and `verifyPresentation` accept: