Skip to content

fix(oid4vp): build the JARM vp_token in the DCQL object form (OpenID4VP 1.0 §8.1) - #460

Open
leifj wants to merge 3 commits into
release/sirosidfrom
fix/jarm-vp-token-dcql-object
Open

leifj wants to merge 3 commits into
release/sirosidfrom
fix/jarm-vp-token-dcql-object

Conversation

@leifj

@leifj leifj commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

What

The client-held direct_post.jwt / dc_api.jwt responses put the sign handler's bare vp_token string into the plaintext verbatim. OpenID4VP 1.0 §8.1 requires vp_token to be a JSON object with one member per Credential Query — the key the query's id, the value an array of that query's presentations. Verifiers enforcing the final shape reject the bare-string form with malformed / invalid response.

The change

The §8.1 restructure lives in a shared restructureDcqlVpToken (mirroring the engine's own buildDCQLVPToken: newline-split, count-checked, a repeated query id collected in order) and is applied at every client response site:

  • buildJarmResponse (the WebSocket transport's JARM path): takes credentialQueryIds from the sign request's credentialsToInclude[].credentialQueryId and restructures before encrypting.
  • The DC-API companion path (useOID4VPFlow.sendDCAPIResponse): the callback page opened by a QR/link runs this path; it previously handed JSON.parse(vpToken) to the session — a JSON-quoted single token parses to a bare string at runtime (the Record<> type is decorative in JS). It now wraps with the selection's own credential query ids, unwrapping a quoted token first.

An already-object response passes through unchanged at both sites.

Provenance

Found live in the SIROS WRPAC drill (sirosid-dev feat/wrpac-environment), against siros-verifier-core v0.1.4: the JWE envelope itself verified clean (alg/enc/kid, the AES-GCM unseal, the state binding), but the plaintext's vp_token was the bare string. A direct probe confirmed the shape is the only gap: an object-form JWE passes the envelope and fails later at the (deliberately dummy) token's signature — 'jose' instead of 'malformed'. The first fix covered the transport path; the live drill then exposed the companion path as a second, duplicated site (the chunk map shows the two encryption sites in different bundles).

The engine-side builders (go-wallet-backend's buildDCQLVPToken, siros-wallet-core's build_dcql_vp_token) already do exactly this — the client-held paths are the only ones that bypassed them.

Spec: OpenID4VP 1.0 final §8 — "vp_token: REQUIRED. This is a JSON-encoded object containing entries where the key is the id value used for a Credential Query in the DCQL query", with the response example {"vp_token": {"example_credential_id": ["eyJ..."]}}.

…VP 1.0 §8.1)

The client-held direct_post.jwt response relayed the sign handler's bare
vp_token string through verbatim. The final spec requires vp_token to be
a JSON object with one member per Credential Query - the key the query's
id, the value an array of its presentations - and verifiers enforcing
that shape reject the bare string with malformed/invalid response (found
live in the WRPAC drill: every cross-device presentation against
siros-verifier-core v0.1.4 failed at this last hop, after the JWE
envelope itself verified clean).

A bare token is now restructured under the sign request's
credentialsToInclude credential query ids, mirroring the engine's own
non-encrypted builder exactly (newline-split, count-checked, a repeated
query id collected in order) - the builder direct_post.jwt bypasses by
relaying this JWE verbatim. An already-object response passes through.
@leifj
leifj requested a review from a team as a code owner November 16, 2026 10:42
@changeset-bot

changeset-bot Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 1557111

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
wallet-frontend Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

The §8.1 object-form fix landed only in the JARM builder the WebSocket
transport uses. The phone's QR/link flow takes another path: the
callback page opens as a companion window (window.opener), answers the
sign handler, and hands JSON.parse(vpToken) to DCAPISession - a
JSON-quoted single token parses to a bare string at runtime (the
Record<> type is decorative in JS), so the DC-API path still encrypted
the bare string and final-spec verifiers kept rejecting it.

Extract the restructure into a shared restructureDcqlVpToken (the
JARM builder delegates to it) and wrap at the DC-API caller with the
selection's own credential query ids. A JSON-quoted token now unwraps
to the token itself before the object form is built.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Valid query IDs such as constructor collide with inherited object properties, causing .push() to throw and preventing the presentation response from being sent.

1 open issue
What changed in this PR

This PR updates client-held OpenID4VP responses to use the required DCQL vp_token object format, addressing verifier rejection of bare-string tokens.

Changes:

  • Adds shared token restructuring with query-ID grouping, count checks, and existing-object passthrough.
  • Applies restructuring to WebSocket JARM and DC-API companion responses.
  • Adds regression tests and a patch release note.
File Description
src/​lib/​openid-flow/​transports/​OIDFlowWebSocketTransport.ts Supplies credential query IDs to the JARM builder.
src/​lib/​openid-flow/​encryption/​response-jwe.ts Adds shared restructuring and uses it before JARM encryption.
src/​lib/​openid-flow/​encryption/​response-jwe.test.ts Tests token wrapping, grouping, count mismatches, and passthrough.
src/​lib/​openid-flow/​encryption/​index.ts Exports the shared restructuring helper.
src/​hooks/​useOID4VPFlow.ts Restructures tokens before sending DC-API companion responses.
.changeset/​wrpac-jarm-vp-token-object.md Documents the JARM response-format fix for a patch release.

Review effort: Balanced

`DCQL vp_token has ${tokens.length} tokens but ${ids.length} credentials selected`,
);
}
const byQueryId: Record<string, string[]> = {};

@smncd smncd left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If I understand correctly the goal is to get the correct response structure for direct_post.jwt, but I don't see that this is being checked in the PR? For normal direct_post we want to keep the previous response structure I think?

Also, the PR keeps referencing § 8.1 of OID4VP, but I see this mentioned only in § 8.3.1. this needs to be corrected.

Comment on lines +5 to +16
Fix the client-held `direct_post.jwt` (JARM) response to carry `vp_token` in the
OpenID4VP 1.0 §8.1 object form: a JSON object with one member per Credential
Query, the key the query's `id`, the value an array of that query's
presentations. A bare vp_token string is now restructured under the sign
request's `credentialsToInclude` credential query ids — the same newline-split,
count-checked, in-order restructure the engine's own non-encrypted path
performs (go-wallet-backend's `buildDCQLVPToken`, which direct_post.jwt
bypasses by relaying the client's JWE verbatim). Verifiers enforcing the final
shape (including the OIDF conformance suite's own client) reject the previous
bare-string form with `malformed`/`invalid response` — found live in the SIROS
WRPAC drill, where every cross-device presentation against
siros-verifier-core v0.1.4 failed at this last hop.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changesets are meant to be a short summary, not a detailed one. Summarise what the PR does, and if necessary, add more than one changeset.

…umented

- The spec reference is §8.3.1 (the Encrypted Responses section), not
  §8.1 — corrected in the code and the comments.
- The restructure's scope is already correct: the WS transport's
  restructure only fires when responseEncryption is present (only for
  direct_post.jwt), and the DC-API path feeds DCAPISession.sendResponse
  which declares Record<string, string[]> — the sign handler previously
  passed a bare string to that API (a runtime type violation, not a
  behavior choice). The comments now state this explicitly.
- The changeset trimmed to a short summary.
@sonarqubecloud

Copy link
Copy Markdown

@leifj
leifj requested review from smncd and a balanced review from Copilot November 18, 2026 10:40

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

The bare-token path uses a plain-object dictionary whose inherited keys, such as constructor, cause .push() to throw and prevent presentation responses for valid query IDs.

1 open issue

Review effort: Balanced

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants