Skip to content

Let transaction types control their SD-JWT response - #2224

Draft
TheBlackBit wants to merge 1 commit into
openwallet-foundation:mainfrom
TheBlackBit:feat/transaction-data-hooks
Draft

TheBlackBit wants to merge 1 commit into
openwallet-foundation:mainfrom
TheBlackBit:feat/transaction-data-hooks

Conversation

@TheBlackBit

@TheBlackBit TheBlackBit commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Part of #2010

No-Issue: part of #2010, which #2196 closes

Why

Some transaction data types need more than the built-in handling can do. They may need a different key binding type, return extra disclosures after the Key Binding JWT, or refuse a request before the person is asked. Today a type can do none of this, so core has to be changed for each new protocol.

This PR adds the hooks and nothing else. No type uses them yet, and every default leaves existing types working as before. The first user is the AP2 type in #2178. The rule that a type's data must be shown by a renderer is in #2225; the two don't depend on each other.

What changes in multipaz

  • nestSdJwtResponseClaims: a type can put its claims at the top level of the Key Binding JWT instead of nesting them. Arrays from several items are combined. A claim that would overwrite one of the Key Binding JWT's own claims, or another type's, is refused.
  • sdJwtKbType(): the typ of the Key Binding JWT, decided over all of a type's items. SdJwtKb.verify() takes the typ it expects, kb+jwt by default.
  • generateSdJwtResponse() and SdJwt.presentWithKbDisclosures(): a type can return disclosures that follow the Key Binding JWT, as <SD-JWT>~~<KB-JWT>~<Disclosure>~. This works over OpenID4VP only; the ISO/IEC 18013-5 path refuses them.
  • validateTogether() (and isApplicable() throwing for malformed data): a type can refuse a request before the consent prompt, with its reason, instead of failing after the person approved.
  • @Throws on the overridable functions, so Kotlin/Native overrides compile.

Testing

  • ./gradlew :multipaz:jvmTest: 1894 tests, 0 failures. New tests cover the Key Binding JWT type, disclosures after it, claim collisions and validateTogether().

  • :multipaz:compileTestKotlinIosSimulatorArm64 and detektMetadataCommonMain pass.

  • Tests pass

  • Appropriate changes to README are included in PR (none needed)

@TheBlackBit
TheBlackBit marked this pull request as draft November 20, 2026 22:08
@TheBlackBit
TheBlackBit force-pushed the feat/transaction-data-hooks branch from fd6339c to 169fdc6 Compare November 20, 2026 22:24
@TheBlackBit TheBlackBit changed the title Let transaction types control SD-JWT responses and consent rendering Let transaction types control their SD-JWT response Nov 20, 2026
Add the generic hooks a transaction type needs to answer an OpenID4VP
request that carries more than a plain key binding, without core knowing
anything about the type. Every default leaves existing types unchanged.

- `TransactionType.nestSdJwtResponseClaims`, default `true`. When `false`,
  a type's response claims are merged into the Key Binding JWT verbatim
  instead of being nested under `kbJwtResponseClaimName`, and arrays
  accumulate across items of the same type instead of the last item
  overwriting the others. `OpenID4VP.processTransactions()` now refuses a
  type that sets one of the Key Binding JWT's own claims (`iat`, `aud`,
  `nonce`, `sd_hash`, `transaction_data_hashes`,
  `transaction_data_hashes_alg`), a claim another type sets, or a value
  another item of its type sets differently, instead of letting one
  silently replace the other.
- `TransactionType.sdJwtKbType()` gives the `typ` header of the Key
  Binding JWT, `null` (the ordinary `kb+jwt`) unless a type overrides it.
  A type decides it over all of its items at once, and the internal
  `TransactionData.sdJwtKbType()` refuses two types that ask for different
  values. `SdJwtKb.verify()` takes the expected type, still defaulting to
  `kb+jwt`.
- `TransactionType.generateSdJwtResponse()` returns the Key Binding JWT
  claims together with disclosures that follow it, as
  `SdJwtTransactionResponse`. By default it returns the claims of
  `generateSdJwtResponseClaims()` and no disclosures. When a type returns
  disclosures, the OpenID4VP path presents through
  `SdJwt.presentWithKbDisclosures()`, which builds the same Key Binding
  JWT as `present()` and returns `<SD-JWT>~~<KB-JWT>~<Disclosure>~`; its
  `type` is required, as such a Key Binding JWT is never the ordinary
  `kb+jwt`. The ISO mdoc path only reads the new response type and refuses
  disclosures and a Key Binding JWT type other than `kb+jwt`, naming the
  types, since ISO/IEC 18013-5 has no place for them. A type that
  returns disclosures without overriding `sdJwtKbType()`, or two items
  that return the same disclosure, are refused with a message naming the
  hooks instead of failing in the presentation code.
- `TransactionType.validateTogether()` lets a type refuse, before the
  consent prompt, a combination of its own items that one response
  answers together. `OpenID4VP` calls it for each credential right after
  parsing, inside the existing handling that reports a problem with the
  transaction data. `isApplicable()` may likewise throw
  `IllegalArgumentException` for malformed data and is reported with its
  reason: `DcqlQuery` translates only that call, so an unrelated
  `IllegalArgumentException` while matching credentials keeps its own
  message. Types that ask for different Key Binding JWT types are
  refused at the same point.
- The overridable functions declare `@Throws`, so Kotlin/Native
  overrides do not hit a filter mismatch. The `TransactionType` KDoc
  gains a usage example and says which hooks apply to OpenID4VP only.

Test: ./gradlew :multipaz:jvmTest (1897 tests, 0 failures), including the
new SdJwtTest cases, TransactionDataSdJwtKbTypeTest,
TransactionDataValidateTogetherTest and the unnested array, claim
collision, Key Binding JWT disclosure, validateTogether() refusal and
isApplicable() refusal cases in DigitalCredentialsPresentmentTest; ./gradlew
:multipaz:compileTestKotlinIosSimulatorArm64; ./gradlew
detektMetadataCommonMain.

Signed-off-by: Ever Morales <ever.morales@koombea.com>
@TheBlackBit
TheBlackBit force-pushed the feat/transaction-data-hooks branch from 169fdc6 to 5800379 Compare November 21, 2026 01:08

This branch has not been deployed

No deployments
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.

1 participant