Repository navigation
Conversation
AP2 delegates a spending mandate during an ordinary OpenID4VP presentation:
the verifier sends the Mandate Content as a `delegate` transaction data item
and the wallet signs its digest in the Key Binding JWT, as Delegate SD-JWT
section 7.1 describes, then returns the mandate disclosure after the Key
Binding JWT (section 5.1.1). Multipaz rejected such requests with "Unknown
transaction type 'delegate'" and failed the whole presentation.
Core changes, none specific to this protocol:
* `TransactionType.nestSdJwtResponseClaims`, default `true`. When `false`,
a type's response claims are merged into the KB-JWT verbatim instead of
being nested under `kbJwtResponseClaimName`, and arrays accumulate
across items of the same type rather than 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` and `sdJwtKbType()` give the `typ` header
the Key Binding JWT carries, which `SdJwt.present()` used to hardcode as
`kb+jwt`. A type decides it over all of its items at once, since one
KB-JWT signs them all, so the result does not depend on their order.
`TransactionData.sdJwtKbType()` combines the types for `OpenID4VP` and
refuses two types that ask for different values.
* `TransactionType.generateSdJwtResponse()` returns the KB-JWT claims
together with disclosures that follow the KB-JWT, as
`SdJwtTransactionResponse`. By default it returns the claims of
`generateSdJwtResponseClaims()` and no disclosures, so other types are
unchanged. When any type returns disclosures, `OpenID4VP` and the
ISO/IEC 18013-5 SD-JWT path present with the new
`SdJwt.presentWithKbDisclosures()`, which builds the same KB-JWT as
`present()` and returns the Delegated SD-JWT compact serialization
`<SD-JWT>~~<KB-JWT>~<Disclosure>~`. The ISO/IEC 18013-5 path now also
passes the `typ` header.
* Transaction data parsed from OpenID4VP now keeps
`transaction_data_hashes_alg`, so a request asking for SHA-384 is no
longer answered in SHA-256, and a value that is not an array of strings
is refused. The same change is submitted on its own in openwallet-foundation#2186 and leaves
this commit once that is merged.
`DelegateTransaction` lives in `multipaz-utopia`. Its identifier stays
`delegate`, the value AP2 sends on the wire. That name is not
collision-resistant, which is why the type is not in `multipaz-doctypes`; it
will change when the Delegate SD-JWT draft picks a new one. The type:
* applies only to key-bound SD-JWT VC credentials and refuses mandates it
cannot show;
* accepts both request forms, since the documents disagree: section 7.1's
`delegate_payload_disclosure` with a `dSD-JWT` or `dSD-JWT+KB` format,
and AP2's `delegate_payload`, several mandates in the clear with a
`dc+sd-jwt` format, for which it makes each disclosure with a fresh
128-bit salt;
* puts the digest of each mandate's disclosure in the `delegate_payload`
KB-JWT claim, under the algorithm the request names for the transaction
data hashes (SHA-256 by default), and always names that algorithm in
`_sd_alg`;
* returns the mandate disclosures, and any `delegate_disclosures` the
request carried, after the KB-JWT, so a verifier resolves the mandates
from the presentation itself;
* fills in the mandates' selectively disclosable terms from
`delegate_disclosures` and, before the consent prompt, refuses a request
whose digests and disclosures do not match one to one, so nothing is
signed that cannot be shown; `shownMandates()` gives the filled-in
mandates to a consent screen;
* types the key binding `kb+sd-jwt`, or `kb+sd-jwt+kb` when any of the
mandates names a further key in `cnf`.
The consent screen's wording is kept apart, in `DelegateMandateText`, so the
protocol side could later be replaced by an official AP2 library on its own.
Its `describePermission()` words the mandates for a person: the spending
limits ("Per purchase, up to", "In total, up to", or a closed mandate's
"Amount"), the merchant, who is paid when that is someone else, the items,
the expiry and the agent key, with every line still reachable through
`PermissionSummary.details`. Amounts follow AP2's units: `payment.budget`
in major units, other amounts in minor units. `summarize()` renders one
mandate generically and `summarizeGroup()` several. What it recognises by
name, the constraint kinds and their members, the units of each amount, the
merchant and line item members, the mandate types and the date claims, is
kept in tables that a test checks against AP2 v0.2.0's own JSON Schemas,
copied unchanged into the tests, so a protocol change cannot go unnoticed.
The consent prompt is left as it is. Its built-in rendering shows only a
heading for this type, so `addUtopiaTypes()` does not register it: an
application registers it together with a `TransactionDataRenderer` that
draws the mandate, as the type's documentation says.
Test: ./gradlew :multipaz-utopia:jvmTest (68 tests: DelegateTransactionTest,
DelegateMandateTextTest, DelegateMandateSchemaTest, which also failed as
expected when a table was broken on purpose, and DelegateAp2InteropTest, which
runs seven AP2 mandate sets in both request forms, one with selectively
disclosed terms, through a full OpenID4VP presentation, checks the Delegated
SD-JWT shape and that a request missing a disclosure is refused); ./gradlew
:multipaz:jvmTest (1717 tests, including TransactionDataSdJwtKbTypeTest, the
new SdJwtTest cases and the unnested array, claim collision and KB disclosure
cases in DigitalCredentialsPresentmentTest); ./gradlew
detektMetadataCommonMain. The responses DelegateAp2InteropTest exports were
verified with AP2's Python SDK v0.2.0, which returns every mandate, and the
delegate SD-JWT golden vectors proposed to AP2 verify in Multipaz with matching
digests. iOS targets were not built: this host has Xcode 27.1 and SwiftBridge
needs the iOS 27.3 SDK.
Signed-off-by: Ever Morales <ever.morales@koombea.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
AP2 delegates a spending mandate during an ordinary OpenID4VP presentation:
the verifier sends the Mandate Content as a `delegate` transaction data item
and the wallet signs its digest in the Key Binding JWT, as Delegate SD-JWT
section 7.1 describes, then returns the mandate disclosure after the Key
Binding JWT (section 5.1.1). Multipaz rejected such requests with "Unknown
transaction type 'delegate'" and failed the whole presentation.
Core changes, none specific to this protocol:
* `TransactionType.nestSdJwtResponseClaims`, default `true`. When `false`,
a type's response claims are merged into the KB-JWT verbatim instead of
being nested under `kbJwtResponseClaimName`, and arrays accumulate
across items of the same type rather than 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` and `sdJwtKbType()` give the `typ` header
the Key Binding JWT carries, which `SdJwt.present()` used to hardcode as
`kb+jwt`. A type decides it over all of its items at once, since one
KB-JWT signs them all, so the result does not depend on their order.
`TransactionData.sdJwtKbType()` combines the types for `OpenID4VP` and
refuses two types that ask for different values.
`SdJwtKb.verify()` takes the `typ` it expects, `kb+jwt` by default, so
a verifier can check a key binding such as `kb+sd-jwt` only when it
asks for that profile.
* `TransactionType.generateSdJwtResponse()` returns the KB-JWT claims
together with disclosures that follow the KB-JWT, as
`SdJwtTransactionResponse`. By default it returns the claims of
`generateSdJwtResponseClaims()` and no disclosures, so other types are
unchanged. When any type returns disclosures, `OpenID4VP` and the
ISO/IEC 18013-5 SD-JWT path present with the new
`SdJwt.presentWithKbDisclosures()`, which builds the same KB-JWT as
`present()` and returns the Delegated SD-JWT compact serialization
`<SD-JWT>~~<KB-JWT>~<Disclosure>~`. The ISO/IEC 18013-5 path now also
passes the `typ` header.
* Transaction data parsed from OpenID4VP now keeps
`transaction_data_hashes_alg`, so a request asking for SHA-384 is no
longer answered in SHA-256, and a value that is not an array of strings
is refused. The same change is submitted on its own in openwallet-foundation#2186 and leaves
this commit once that is merged.
`DelegateTransaction` lives in `multipaz-utopia`. Its identifier stays
`delegate`, the value AP2 sends on the wire. That name is not
collision-resistant, which is why the type is not in `multipaz-doctypes`; it
will change when the Delegate SD-JWT draft picks a new one. The type:
* applies only to key-bound SD-JWT VC credentials and refuses mandates it
cannot show;
* accepts both request forms, since the documents disagree: section 7.1's
`delegate_payload_disclosure` with a `dSD-JWT` or `dSD-JWT+KB` format,
and AP2's `delegate_payload`, several mandates in the clear with a
`dc+sd-jwt` format, for which it makes each disclosure with a fresh
128-bit salt;
* puts the digest of each mandate's disclosure in the `delegate_payload`
KB-JWT claim, under the algorithm the request names for the transaction
data hashes (SHA-256 by default), and always names that algorithm in
`_sd_alg`;
* returns the mandate disclosures, and any `delegate_disclosures` the
request carried, after the KB-JWT, so a verifier resolves the mandates
from the presentation itself;
* fills in the mandates' selectively disclosable terms from
`delegate_disclosures` and, before the consent prompt, refuses a request
whose digests and disclosures do not match one to one, so nothing is
signed that cannot be shown; `shownMandates()` gives the filled-in
mandates to a consent screen;
* types the key binding `kb+sd-jwt`, or `kb+sd-jwt+kb` when any of the
mandates names a further key in `cnf`.
The consent screen's wording is kept apart, in `DelegateMandateText`, so the
protocol side could later be replaced by an official AP2 library on its own.
Its `describePermission()` words the mandates for a person: the spending
limits ("Per purchase, up to", "In total, up to", or a closed mandate's
"Amount"), the merchant, who is paid when that is someone else, the items,
the expiry and the agent key, with every line still reachable through
`PermissionSummary.details`. Amounts follow AP2's units: `payment.budget`
in major units, other amounts in minor units. `summarize()` renders one
mandate generically and `summarizeGroup()` several. What it recognises by
name, the constraint kinds and their members, the units of each amount, the
merchant and line item members, the mandate types and the date claims, is
kept in tables that a test checks against AP2 v0.2.0's own JSON Schemas,
copied unchanged into the tests, so a protocol change cannot go unnoticed.
The consent prompt is left as it is. Its built-in rendering shows only a
heading for this type, so `addUtopiaTypes()` does not register it: an
application registers it together with a `TransactionDataRenderer` that
draws the mandate, as the type's documentation says.
Test: ./gradlew :multipaz-utopia:jvmTest (68 tests: DelegateTransactionTest,
DelegateMandateTextTest, DelegateMandateSchemaTest, which also failed as
expected when a table was broken on purpose, and DelegateAp2InteropTest, which
runs seven AP2 mandate sets in both request forms, one with selectively
disclosed terms, through a full OpenID4VP presentation, checks the Delegated
SD-JWT shape and that a request missing a disclosure is refused); ./gradlew
:multipaz:jvmTest (1780 tests, including TransactionDataSdJwtKbTypeTest, the
new SdJwtTest cases and the unnested array, claim collision and KB disclosure
cases in DigitalCredentialsPresentmentTest); ./gradlew
detektMetadataCommonMain. The responses DelegateAp2InteropTest exports were
verified with AP2's Python SDK v0.2.0, which returns every mandate, and the
delegate SD-JWT golden vectors proposed to AP2 verify in Multipaz with matching
digests. iOS targets were not built: this host has Xcode 27.2 and SwiftBridge
needs the iOS 27.3 SDK.
Signed-off-by: Ever Morales <ever.morales@koombea.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
dzuluaga
left a comment
There was a problem hiding this comment.
The fix is right and small. The base parseJson() now keeps transaction_data_hashes_alg, which OpenID4VP 1.0 B.3.3.1 requires the wallet to honour ("the hash function MUST be one of its values"), and every refusal it adds is an IllegalArgumentException, which the wallet already catches at OpenID4VP.kt:450. Ready once the issue link is changed. Reviewed at 863c95b.
What a developer writes. A transaction type that doesn't override parseJson() now writes nothing to have the verifier's list honoured. Before, it needed an 11-line override like PaymentTransaction.parseJson(). No type in the repository reaches this path yet; DelegateTransaction in #2178 will be the first.
Before merge
- The first line of the description closes the wrong issue. #2010 is about the unregistered
delegatetype and the wrapping of KB-JWT claims. It doesn't mention hash algorithms, and this PR changes neither of those. Merging would close it while #2178 and #2196, which do address it, are still open. CONTRIBUTING.md asks for a linked issue with a closing keyword, so: open an issue for the droppedtransaction_data_hashes_alg, close that one from here, and mention #2010 without a keyword.
Non-blocking. 6 line comments: 3 suggestions and 3 nits. The one I would take is on the [384] test, which passes with or without the check it is there for.
Scope. One purpose, 24 lines of source. The same change is in #2178 and #2196, so this one should merge first.
Not verified. Nothing was built or run. build_and_test passed on this commit. "4 of the 5 new tests fail without the change" holds by trace only. The 1727 count and the non-JVM targets were not checked.
AP2 delegates a spending mandate during an ordinary OpenID4VP presentation:
the verifier sends the Mandate Content as a `delegate` transaction data item
and the wallet signs its digest in the Key Binding JWT, as Delegate SD-JWT
section 7.1 describes, then returns the mandate disclosure after the Key
Binding JWT (section 5.1.1). Multipaz rejected such requests with "Unknown
transaction type 'delegate'" and failed the whole presentation.
Core changes, none specific to this protocol:
* `TransactionType.nestSdJwtResponseClaims`, default `true`. When `false`,
a type's response claims are merged into the KB-JWT verbatim instead of
being nested under `kbJwtResponseClaimName`, and arrays accumulate
across items of the same type rather than 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` and `sdJwtKbType()` give the `typ` header
the Key Binding JWT carries, which `SdJwt.present()` used to hardcode as
`kb+jwt`. A type decides it over all of its items at once, since one
KB-JWT signs them all, so the result does not depend on their order.
`TransactionData.sdJwtKbType()` combines the types for `OpenID4VP` and
refuses two types that ask for different values.
`SdJwtKb.verify()` takes the `typ` it expects, `kb+jwt` by default, so
a verifier can check a key binding such as `kb+sd-jwt` only when it
asks for that profile.
* `TransactionType.generateSdJwtResponse()` returns the KB-JWT claims
together with disclosures that follow the KB-JWT, as
`SdJwtTransactionResponse`. By default it returns the claims of
`generateSdJwtResponseClaims()` and no disclosures, so other types are
unchanged. When any type returns disclosures, `OpenID4VP` and the
ISO/IEC 18013-5 SD-JWT path present with the new
`SdJwt.presentWithKbDisclosures()`, which builds the same KB-JWT as
`present()` and returns the Delegated SD-JWT compact serialization
`<SD-JWT>~~<KB-JWT>~<Disclosure>~`. The ISO/IEC 18013-5 path now also
passes the `typ` header.
* Transaction data parsed from OpenID4VP now keeps
`transaction_data_hashes_alg`, so a request asking for SHA-384 is no
longer answered in SHA-256, and a value that is not an array of strings
is refused. The same change is submitted on its own in openwallet-foundation#2186 and leaves
this commit once that is merged.
`DelegateTransaction` lives in `multipaz-utopia`. Its identifier stays
`delegate`, the value AP2 sends on the wire. That name is not
collision-resistant, which is why the type is not in `multipaz-doctypes`; it
will change when the Delegate SD-JWT draft picks a new one. The type:
* applies only to key-bound SD-JWT VC credentials and refuses mandates it
cannot show;
* accepts both request forms, since the documents disagree: section 7.1's
`delegate_payload_disclosure` with a `dSD-JWT` or `dSD-JWT+KB` format,
and AP2's `delegate_payload`, several mandates in the clear with a
`dc+sd-jwt` format, for which it makes each disclosure with a fresh
128-bit salt;
* puts the digest of each mandate's disclosure in the `delegate_payload`
KB-JWT claim, under the algorithm the request names for the transaction
data hashes (SHA-256 by default), and always names that algorithm in
`_sd_alg`;
* returns the mandate disclosures, and any `delegate_disclosures` the
request carried, after the KB-JWT, so a verifier resolves the mandates
from the presentation itself;
* fills in the mandates' selectively disclosable terms from
`delegate_disclosures` and, before the consent prompt, refuses a request
whose digests and disclosures do not match one to one, so nothing is
signed that cannot be shown; `shownMandates()` gives the filled-in
mandates to a consent screen;
* types the key binding `kb+sd-jwt`, or `kb+sd-jwt+kb` when any of the
mandates names a further key in `cnf`.
The consent screen's wording is kept apart, in `DelegateMandateText`, so the
protocol side could later be replaced by an official AP2 library on its own.
Its `describePermission()` words the mandates for a person: the spending
limits ("Per purchase, up to", "In total, up to", or a closed mandate's
"Amount"), the merchant, who is paid when that is someone else, the items,
the expiry and the agent key, with every line still reachable through
`PermissionSummary.details`. Amounts follow AP2's units: `payment.budget`
in major units, other amounts in minor units. `summarize()` renders one
mandate generically and `summarizeGroup()` several. What it recognises by
name, the constraint kinds and their members, the units of each amount, the
merchant and line item members, the mandate types and the date claims, is
kept in tables that a test checks against AP2 v0.2.0's own JSON Schemas,
copied unchanged into the tests, so a protocol change cannot go unnoticed.
The consent prompt is left as it is. Its built-in rendering shows only a
heading for this type, so `addUtopiaTypes()` does not register it: an
application registers it together with a `TransactionDataRenderer` that
draws the mandate, as the type's documentation says.
Test: ./gradlew :multipaz-utopia:jvmTest (68 tests: DelegateTransactionTest,
DelegateMandateTextTest, DelegateMandateSchemaTest, which also failed as
expected when a table was broken on purpose, and DelegateAp2InteropTest, which
runs seven AP2 mandate sets in both request forms, one with selectively
disclosed terms, through a full OpenID4VP presentation, checks the Delegated
SD-JWT shape and that a request missing a disclosure is refused); ./gradlew
:multipaz:jvmTest (1780 tests, including TransactionDataSdJwtKbTypeTest, the
new SdJwtTest cases and the unnested array, claim collision and KB disclosure
cases in DigitalCredentialsPresentmentTest); ./gradlew
detektMetadataCommonMain. The responses DelegateAp2InteropTest exports were
verified with AP2's Python SDK v0.2.0, which returns every mandate, and the
delegate SD-JWT golden vectors proposed to AP2 verify in Multipaz with matching
digests. iOS targets were not built: this host has Xcode 27.2 and SwiftBridge
needs the iOS 27.3 SDK.
Signed-off-by: Ever Morales <ever.morales@koombea.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
AP2 delegates a spending mandate during an ordinary OpenID4VP presentation:
the verifier sends the Mandate Content as a `delegate` transaction data item
and the wallet signs its digest in the Key Binding JWT, as Delegate SD-JWT
section 7.1 describes, then returns the mandate disclosure after the Key
Binding JWT (section 5.1.1). Multipaz rejected such requests with "Unknown
transaction type 'delegate'" and failed the whole presentation.
Core changes, none specific to this protocol:
* `TransactionType.nestSdJwtResponseClaims`, default `true`. When `false`,
a type's response claims are merged into the KB-JWT verbatim instead of
being nested under `kbJwtResponseClaimName`, and arrays accumulate
across items of the same type rather than 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` and `sdJwtKbType()` give the `typ` header
the Key Binding JWT carries, which `SdJwt.present()` used to hardcode as
`kb+jwt`. A type decides it over all of its items at once, since one
KB-JWT signs them all, so the result does not depend on their order.
`TransactionData.sdJwtKbType()` combines the types for `OpenID4VP` and
refuses two types that ask for different values.
`SdJwtKb.verify()` takes the `typ` it expects, `kb+jwt` by default, so
a verifier can check a key binding such as `kb+sd-jwt` only when it
asks for that profile.
* `TransactionType.generateSdJwtResponse()` returns the KB-JWT claims
together with disclosures that follow the KB-JWT, as
`SdJwtTransactionResponse`. By default it returns the claims of
`generateSdJwtResponseClaims()` and no disclosures, so other types are
unchanged. When any type returns disclosures, `OpenID4VP` and the
ISO/IEC 18013-5 SD-JWT path present with the new
`SdJwt.presentWithKbDisclosures()`, which builds the same KB-JWT as
`present()` and returns the Delegated SD-JWT compact serialization
`<SD-JWT>~~<KB-JWT>~<Disclosure>~`. The ISO/IEC 18013-5 path now also
passes the `typ` header.
* Transaction data parsed from OpenID4VP now keeps
`transaction_data_hashes_alg`, so a request asking for SHA-384 is no
longer answered in SHA-256, and a value that is not an array of strings
is refused. The same change is submitted on its own in openwallet-foundation#2186 and leaves
this commit once that is merged.
`DelegateTransaction` lives in `multipaz-utopia`. Its identifier stays
`delegate`, the value AP2 sends on the wire. That name is not
collision-resistant, which is why the type is not in `multipaz-doctypes`; it
will change when the Delegate SD-JWT draft picks a new one. The type:
* applies only to key-bound SD-JWT VC credentials and refuses mandates it
cannot show;
* accepts both request forms, since the documents disagree: section 7.1's
`delegate_payload_disclosure` with a `dSD-JWT` or `dSD-JWT+KB` format,
and AP2's `delegate_payload`, several mandates in the clear with a
`dc+sd-jwt` format, for which it makes each disclosure with a fresh
128-bit salt;
* puts the digest of each mandate's disclosure in the `delegate_payload`
KB-JWT claim, under the algorithm the request names for the transaction
data hashes (SHA-256 by default), and always names that algorithm in
`_sd_alg`;
* returns the mandate disclosures, and any `delegate_disclosures` the
request carried, after the KB-JWT, so a verifier resolves the mandates
from the presentation itself;
* fills in the mandates' selectively disclosable terms from
`delegate_disclosures` and, before the consent prompt, refuses a request
whose digests and disclosures do not match one to one, so nothing is
signed that cannot be shown; `shownMandates()` gives the filled-in
mandates to a consent screen;
* types the key binding `kb+sd-jwt`, or `kb+sd-jwt+kb` when any of the
mandates names a further key in `cnf`.
The consent screen's wording is kept apart, in `DelegateMandateText`, so the
protocol side could later be replaced by an official AP2 library on its own.
Its `describePermission()` words the mandates for a person: the spending
limits ("Per purchase, up to", "In total, up to", or a closed mandate's
"Amount"), the merchant, who is paid when that is someone else, the items,
the expiry and the agent key, with every line still reachable through
`PermissionSummary.details`. Amounts follow AP2's units: `payment.budget`
in major units, other amounts in minor units. `summarize()` renders one
mandate generically and `summarizeGroup()` several. What it recognises by
name, the constraint kinds and their members, the units of each amount, the
merchant and line item members, the mandate types and the date claims, is
kept in tables that a test checks against AP2 v0.2.0's own JSON Schemas,
copied unchanged into the tests, so a protocol change cannot go unnoticed.
The consent prompt is left as it is. Its built-in rendering shows only a
heading for this type, so `addUtopiaTypes()` does not register it: an
application registers it together with a `TransactionDataRenderer` that
draws the mandate, as the type's documentation says.
Test: ./gradlew :multipaz-utopia:jvmTest (68 tests: DelegateTransactionTest,
DelegateMandateTextTest, DelegateMandateSchemaTest, which also failed as
expected when a table was broken on purpose, and DelegateAp2InteropTest, which
runs seven AP2 mandate sets in both request forms, one with selectively
disclosed terms, through a full OpenID4VP presentation, checks the Delegated
SD-JWT shape and that a request missing a disclosure is refused); ./gradlew
:multipaz:jvmTest (1780 tests, including TransactionDataSdJwtKbTypeTest, the
new SdJwtTest cases and the unnested array, claim collision and KB disclosure
cases in DigitalCredentialsPresentmentTest); ./gradlew
detektMetadataCommonMain. The responses DelegateAp2InteropTest exports were
verified with AP2's Python SDK v0.2.0, which returns every mandate, and the
delegate SD-JWT golden vectors proposed to AP2 verify in Multipaz with matching
digests. iOS targets were not built: this host has Xcode 27.2 and SwiftBridge
needs the iOS 27.3 SDK.
Signed-off-by: Ever Morales <ever.morales@koombea.com>
AP2 delegates a spending mandate during an ordinary OpenID4VP presentation:
the verifier sends the Mandate Content as a `delegate` transaction data item
and the wallet signs its digest in the Key Binding JWT, as Delegate SD-JWT
section 7.1 describes, then returns the mandate disclosure after the Key
Binding JWT (section 5.1.1). Multipaz rejected such requests with "Unknown
transaction type 'delegate'" and failed the whole presentation.
Core changes, none specific to this protocol:
* `TransactionType.nestSdJwtResponseClaims`, default `true`. When `false`,
a type's response claims are merged into the KB-JWT verbatim instead of
being nested under `kbJwtResponseClaimName`, and arrays accumulate
across items of the same type rather than 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 the Key Binding
JWT carries, `null` (the ordinary `kb+jwt`) unless a type overrides it,
which `SdJwt.present()` used to hardcode. A type decides it over all of
its items at once, since one KB-JWT signs them all, so the result does
not depend on their order. `TransactionData.sdJwtKbType()`, internal,
combines the types and refuses two that ask for different values.
`SdJwtKb.verify()` takes the `typ` it expects, `kb+jwt` by default, so
a verifier can check a key binding such as `kb+sd-jwt` only when it
asks for that profile.
* `TransactionType.generateSdJwtResponse()` returns the KB-JWT claims
together with disclosures that follow the KB-JWT, as
`SdJwtTransactionResponse`. By default it returns the claims of
`generateSdJwtResponseClaims()` and no disclosures, so other types are
unchanged. When any type returns disclosures, `OpenID4VP` presents with
the new `SdJwt.presentWithKbDisclosures()`, which builds the same KB-JWT
as `present()` and returns the Delegated SD-JWT compact serialization
`<SD-JWT>~~<KB-JWT>~<Disclosure>~`; its `type` is required, because a
Key Binding JWT that carries disclosures is never the ordinary `kb+jwt`.
The ISO/IEC 18013-5 path only reads the new response type and refuses
disclosures, which its reader cannot accept.
`TransactionType.isApplicable()` may now throw
`IllegalArgumentException` for transaction data that is malformed, and
`OpenID4VP` reports it with its reason, like a parse failure.
* Transaction data parsed from OpenID4VP now keeps
`transaction_data_hashes_alg`, so a request asking for SHA-384 is no
longer answered in SHA-256, and a value that is not an array of strings
is refused. The same change is submitted on its own in openwallet-foundation#2186 and leaves
this commit once that is merged.
`DelegateTransaction` lives in `multipaz-utopia`. Its identifier stays
`delegate`, the value AP2 sends on the wire. That name is not
collision-resistant, which is why the type is not in `multipaz-doctypes`; it
will change when the Delegate SD-JWT draft picks a new one. The type:
* applies only to key-bound SD-JWT VC credentials and refuses mandates it
cannot show;
* accepts both request forms, since the documents disagree: section 7.1's
`delegate_payload_disclosure` with a `dSD-JWT` or `dSD-JWT+KB` format,
and AP2's `delegate_payload`, several mandates in the clear with a
`dc+sd-jwt` format, for which it makes each disclosure with a fresh
128-bit salt;
* puts the digest of each mandate's disclosure in the `delegate_payload`
KB-JWT claim, under the algorithm the request names for the transaction
data hashes (SHA-256 if offered), and names that algorithm in `_sd_alg`.
Selectively disclosable terms are matched under each mandate's own
`_sd_alg`, SHA-256 when absent (RFC 9901);
* returns the mandate disclosures, and any `delegate_disclosures` the
request carried, after the KB-JWT, so a verifier resolves the mandates
from the presentation itself;
* fills in the mandates' selectively disclosable terms from
`delegate_disclosures` and, before the consent prompt, refuses a request
whose digests and disclosures do not match one to one, so nothing is
signed that cannot be shown, throwing with the reason;
`shownMandates()` gives the filled-in mandates to a consent screen;
* types the key binding `kb+sd-jwt`, or `kb-sd-jwt+kb` when any of the
mandates names a further key in `cnf`, and requires a `cnf` for the
`dSD-JWT+KB` format.
The consent screen's wording is kept apart, in `DelegateMandateText`, so the
protocol side could later be replaced by an official AP2 library on its own.
Its `permissionSummary()` words the mandates for a person: the spending
limits ("Per purchase, up to", "In total, up to", or a closed mandate's
"Amount"), the merchant with its domain and id, who is paid when that is
someone else, the items, the expiry and the agent key, with every line
still reachable through `PermissionSummary.details`; a closed checkout's
`checkout_jwt` is read for what the merchant signed, and the domain is the
host without any userinfo. Amounts follow AP2's units: `payment.budget` in
major units, other amounts in minor units. `detailsOf()` gives one mandate's
heading, type and lines for a details page. What it recognises by name, the
constraint kinds and their members, the units of each amount, the merchant
and line item members, the mandate types and the date claims, is kept in
tables that a test checks against AP2 v0.2.0's own JSON Schemas, copied
unchanged into the tests, so a protocol change cannot go unnoticed.
The consent prompt is left as it is. Its built-in rendering shows only a
heading for this type, so `addUtopiaTypes()` does not register it: an
application registers it together with a `TransactionDataRenderer` that
draws the mandate, as the type's documentation says.
Test: ./gradlew :multipaz-utopia:jvmTest (98 tests: DelegateTransactionTest,
DelegateMandateTextTest, DelegateMandateSchemaTest, which also failed as
expected when a table was broken on purpose, and DelegateAp2InteropTest, which
runs seven AP2 mandate sets in both request forms, one with selectively
disclosed terms and closed checkouts that follow AP2's schema, through a full
OpenID4VP presentation, checks the Delegated SD-JWT shape and that a request
missing a disclosure is refused with its reason); ./gradlew :multipaz:jvmTest
(1872 tests, including TransactionDataSdJwtKbTypeTest, the new SdJwtTest cases
and the unnested array, claim collision and KB disclosure cases in
DigitalCredentialsPresentmentTest); ./gradlew detektMetadataCommonMain. The
responses DelegateAp2InteropTest exports verify with AP2's Python SDK v0.2.0
(b4587ac) through multipaz-utopia/scripts/verify_ap2_interop.py: 7 of 7
scenarios, with the mandates the SDK resolves matching the requested ones; the
script also checks the nonce and audience, which the SDK skips on an
intermediate hop. iOS targets were not built: this host has Xcode 27.2 and
SwiftBridge needs the iOS 27.3 SDK.
Signed-off-by: Ever Morales <ever.morales@koombea.com>
AP2 delegates a spending mandate during an ordinary OpenID4VP presentation:
the verifier sends the Mandate Content as a `delegate` transaction data item
and the wallet signs its digest in the Key Binding JWT, as Delegate SD-JWT
section 7.1 describes, then returns the mandate disclosure after the Key
Binding JWT (section 5.1.1). Multipaz rejected such requests with "Unknown
transaction type 'delegate'" and failed the whole presentation.
Core changes, none specific to this protocol:
* `TransactionType.nestSdJwtResponseClaims`, default `true`. When `false`,
a type's response claims are merged into the KB-JWT verbatim instead of
being nested under `kbJwtResponseClaimName`, and arrays accumulate
across items of the same type rather than 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 the Key Binding
JWT carries, `null` (the ordinary `kb+jwt`) unless a type overrides it,
which `SdJwt.present()` used to hardcode. A type decides it over all of
its items at once, since one KB-JWT signs them all, so the result does
not depend on their order. `TransactionData.sdJwtKbType()`, internal,
combines the types and refuses two that ask for different values.
`SdJwtKb.verify()` takes the `typ` it expects, `kb+jwt` by default, so
a verifier can check a key binding such as `kb+sd-jwt` only when it
asks for that profile.
* `TransactionType.generateSdJwtResponse()` returns the KB-JWT claims
together with disclosures that follow the KB-JWT, as
`SdJwtTransactionResponse`. By default it returns the claims of
`generateSdJwtResponseClaims()` and no disclosures, so other types are
unchanged. When any type returns disclosures, `OpenID4VP` presents with
the new `SdJwt.presentWithKbDisclosures()`, which builds the same KB-JWT
as `present()` and returns the Delegated SD-JWT compact serialization
`<SD-JWT>~~<KB-JWT>~<Disclosure>~`; its `type` is required, because a
Key Binding JWT that carries disclosures is never the ordinary `kb+jwt`.
The ISO/IEC 18013-5 path only reads the new response type and refuses
disclosures, which its reader cannot accept.
`TransactionType.isApplicable()` may now throw
`IllegalArgumentException` for transaction data that is malformed, and
`OpenID4VP` reports it with its reason, like a parse failure. Both it
and `parseOpenId4VpRequest()` declare `@Throws`, as their overrides in
`DelegateTransaction` must on Kotlin/Native.
* Transaction data parsed from OpenID4VP now keeps
`transaction_data_hashes_alg`, so a request asking for SHA-384 is no
longer answered in SHA-256, and a value that is not an array of strings
is refused. The same change is submitted on its own in openwallet-foundation#2186 and leaves
this commit once that is merged.
`DelegateTransaction` lives in `multipaz-utopia`. Its identifier stays
`delegate`, the value AP2 sends on the wire. That name is not
collision-resistant, which is why the type is not in `multipaz-doctypes`; it
will change when the Delegate SD-JWT draft picks a new one. The type:
* applies only to key-bound SD-JWT VC credentials and refuses mandates it
cannot show;
* accepts both request forms, since the documents disagree: section 7.1's
`delegate_payload_disclosure` with a `dSD-JWT` or `dSD-JWT+KB` format,
and AP2's `delegate_payload`, several mandates in the clear with a
`dc+sd-jwt` format, for which it makes each disclosure with a fresh
128-bit salt;
* puts the digest of each mandate's disclosure in the `delegate_payload`
KB-JWT claim, under the algorithm the request names for the transaction
data hashes (SHA-256 if offered), and names that algorithm in `_sd_alg`.
Selectively disclosable terms are matched under each mandate's own
`_sd_alg`, SHA-256 when absent (RFC 9901);
* returns the mandate disclosures, and any `delegate_disclosures` the
request carried, after the KB-JWT, so a verifier resolves the mandates
from the presentation itself;
* fills in the mandates' selectively disclosable terms from
`delegate_disclosures` and, before the consent prompt, refuses a request
whose digests and disclosures do not match one to one, so nothing is
signed that cannot be shown, throwing with the reason;
`shownMandates()` gives the filled-in mandates to a consent screen;
* types the key binding `kb+sd-jwt`, or `kb-sd-jwt+kb` when any of the
mandates names a further key in `cnf`, and requires a `cnf` for the
`dSD-JWT+KB` format.
The consent screen's wording is kept apart, in `DelegateMandateText`, so the
protocol side could later be replaced by an official AP2 library on its own.
Its `permissionSummary()` words the mandates for a person: the spending
limits ("Per purchase, up to", "In total, up to", or a closed mandate's
"Amount"), the merchant with its domain and id, who is paid when that is
someone else, the items, the expiry and the agent key, with every line
still reachable through `PermissionSummary.details`; a closed checkout's
`checkout_jwt` is read for what the merchant signed, and the domain is the
host without any userinfo. Amounts follow AP2's units: `payment.budget` in
major units, other amounts in minor units. `detailsOf()` gives one mandate's
heading, type and lines for a details page. What it recognises by name, the
constraint kinds and their members, the units of each amount, the merchant
and line item members, the mandate types and the date claims, is kept in
tables that a test checks against AP2 v0.2.0's own JSON Schemas, copied
unchanged into the tests, so a protocol change cannot go unnoticed.
The consent prompt is left as it is. Its built-in rendering shows only a
heading for this type, so `addUtopiaTypes()` does not register it: an
application registers it together with a `TransactionDataRenderer` that
draws the mandate, as the type's documentation says.
Test: ./gradlew :multipaz-utopia:jvmTest (98 tests: DelegateTransactionTest,
DelegateMandateTextTest, DelegateMandateSchemaTest, which also failed as
expected when a table was broken on purpose, and DelegateAp2InteropTest, which
runs seven AP2 mandate sets in both request forms, one with selectively
disclosed terms and closed checkouts that follow AP2's schema, through a full
OpenID4VP presentation, checks the Delegated SD-JWT shape and that a request
missing a disclosure is refused with its reason); ./gradlew :multipaz:jvmTest
(1872 tests, including TransactionDataSdJwtKbTypeTest, the new SdJwtTest cases
and the unnested array, claim collision and KB disclosure cases in
DigitalCredentialsPresentmentTest); ./gradlew detektMetadataCommonMain. The
responses DelegateAp2InteropTest exports verify with AP2's Python SDK v0.2.0
(b4587ac) through multipaz-utopia/scripts/verify_ap2_interop.py: 7 of 7
scenarios, with the mandates the SDK resolves matching the requested ones; the
script also checks the nonce and audience, which the SDK skips on an
intermediate hop. iOS targets were not built: this host has Xcode 27.2 and
SwiftBridge needs the iOS 27.3 SDK; the iOS simulator targets of multipaz,
multipaz-utopia and multipaz-doctypes, and their tests, do compile.
Signed-off-by: Ever Morales <ever.morales@koombea.com>
AP2 delegates a spending mandate during an ordinary OpenID4VP presentation:
the verifier sends the Mandate Content as a `delegate` transaction data item
and the wallet signs its digest in the Key Binding JWT, as Delegate SD-JWT
section 7.1 describes, then returns the mandate disclosure after the Key
Binding JWT (section 5.1.1). Multipaz rejected such requests with "Unknown
transaction type 'delegate'" and failed the whole presentation.
Core changes, none specific to this protocol:
* `TransactionType.nestSdJwtResponseClaims`, default `true`. When `false`,
a type's response claims are merged into the KB-JWT verbatim instead of
being nested under `kbJwtResponseClaimName`, and arrays accumulate
across items of the same type rather than 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 the Key Binding
JWT carries, `null` (the ordinary `kb+jwt`) unless a type overrides it,
which `SdJwt.present()` used to hardcode. A type decides it over all of
its items at once, since one KB-JWT signs them all, so the result does
not depend on their order. `TransactionData.sdJwtKbType()`, internal,
combines the types and refuses two that ask for different values.
`SdJwtKb.verify()` takes the `typ` it expects, `kb+jwt` by default, so
a verifier can check a key binding such as `kb+sd-jwt` only when it
asks for that profile.
* `TransactionType.generateSdJwtResponse()` returns the KB-JWT claims
together with disclosures that follow the KB-JWT, as
`SdJwtTransactionResponse`. By default it returns the claims of
`generateSdJwtResponseClaims()` and no disclosures, so other types are
unchanged. When any type returns disclosures, `OpenID4VP` presents with
the new `SdJwt.presentWithKbDisclosures()`, which builds the same KB-JWT
as `present()` and returns the Delegated SD-JWT compact serialization
`<SD-JWT>~~<KB-JWT>~<Disclosure>~`; its `type` is required, because a
Key Binding JWT that carries disclosures is never the ordinary `kb+jwt`.
The ISO/IEC 18013-5 path only reads the new response type and refuses
disclosures, which its reader cannot accept.
`TransactionType.isApplicable()` may now throw
`IllegalArgumentException` for transaction data that is malformed, and
`OpenID4VP` reports it with its reason, like a parse failure. Both it
and `parseOpenId4VpRequest()` declare `@Throws`, as their overrides in
`DelegateTransaction` must on Kotlin/Native.
* `TransactionType.validateTogether()`, which does nothing by default,
lets a type check, before the consent prompt, the items of one
credential that a single response answers together, so a request that
could only fail after the person approved is refused up front with its
reason. `OpenID4VP` calls it when it parses `transaction_data`.
* `TransactionType.requiresRenderer`, default `false`. A type that sets it
cannot be approved with the built-in rendering: `PromptModel
.requestConsent()` throws `TransactionDataRendererNotAvailableException`,
naming the type, when no renderer is registered for it or no repository
was passed, and the Compose and SwiftUI consent dialogs refuse the same
way when the renderer registered is made for the other toolkit.
* Transaction data parsed from OpenID4VP now keeps
`transaction_data_hashes_alg`, so a request asking for SHA-384 is no
longer answered in SHA-256, and a value that is not an array of strings
is refused. The same change is submitted on its own in openwallet-foundation#2186 and leaves
this commit once that is merged.
`DelegateTransaction` lives in `multipaz-utopia`. Its identifier stays
`delegate`, the value AP2 sends on the wire. That name is not
collision-resistant, which is why the type is not in `multipaz-doctypes`; it
will change when the Delegate SD-JWT draft picks a new one. The type:
* applies only to key-bound SD-JWT VC credentials and refuses mandates it
cannot show;
* accepts both request forms, since the documents disagree: section 7.1's
`delegate_payload_disclosure` with a `dSD-JWT` or `dSD-JWT+KB` format,
and AP2's `delegate_payload`, several mandates in the clear with a
`dc+sd-jwt` format, for which it makes each disclosure with a fresh
128-bit salt;
* puts the digest of each mandate's disclosure in the `delegate_payload`
KB-JWT claim, under the algorithm the request names for the transaction
data hashes (SHA-256 if offered), and names that algorithm in `_sd_alg`.
The terms selectively disclosable within a mandate are resolved with
that same algorithm, because AP2's verifier hashes every nested digest
with the KB-JWT's and drops what does not match; a mandate that names
another `_sd_alg` is refused;
* returns the mandate disclosures, and any `delegate_disclosures` the
request carried, after the KB-JWT, so a verifier resolves the mandates
from the presentation itself;
* fills in the mandates' selectively disclosable terms from
`delegate_disclosures` and, before the consent prompt, refuses a request
whose digests and disclosures do not match one to one, so nothing is
signed that cannot be shown, throwing with the reason. A `cnf` behind a
digest, a key it cannot show, and a closed checkout whose
`checkout_hash` is not the hash of its `checkout_jwt` are refused too.
Items that settle on different algorithms, or share a disclosure, are
refused together before the prompt;
* types the key binding `kb+sd-jwt`, or `kb-sd-jwt+kb` when any of the
mandates names a further key in `cnf`, and requires a `cnf` for the
`dSD-JWT+KB` format;
* sets `requiresRenderer`, because its built-in rendering shows only a
heading and a person must not approve a spending permission they were
not shown.
The consent screen's wording is kept apart, in `DelegateMandateText`, so the
protocol side could later be replaced by an official AP2 library on its own.
Its `permissionSummary()` words the mandates for a person: the spending
limits ("Per purchase, up to", "In total, up to", or a closed mandate's
"Amount"), the merchant with its domain and id, who is paid when that is
someone else, the items, the expiry and the agent key, with every line
still reachable through `PermissionSummary.details`, and `mandateDetails()`
gives each mandate's heading, type and lines for a details page. It words
what AP2's SDK v0.2.0 enforces, which differs from its schema in three
places: `payment.budget` is scaled by 100 in every currency, an empty
`acceptable_items` is a wildcard ("Up to 10 × any item"), and a requirement's
quantity is a maximum. Items show their id beside the title, since AP2 matches
on the id; a closed checkout's `checkout_jwt` is read as the UCP checkout the
SDK parses, its amounts in minor units with the checkout's currency, as the
checkout the requester sent, not as signed by the merchant, whose signature
is not verified. What it recognises by name, the constraint kinds and their
members, the units of each amount, the merchant and line item members, the
mandate types and the date claims, is kept in tables that a test checks
against AP2 v0.2.0's own JSON Schemas, copied unchanged into the tests, so a
protocol change cannot go unnoticed.
`addUtopiaTypes()` does not register `DelegateTransaction`: an application
registers it together with a `TransactionDataRenderer` that draws the mandate
from `permissionSummary()` and `mandateDetails()`, and without one the prompt
refuses. Disclosures after the Key Binding JWT work over OpenID4VP only; the
ISO/IEC 18013-5 path refuses them. A Multipaz verifier cannot read a
Delegated SD-JWT yet, and AP2's own example request, whose first item has
type `payment_card`, still fails with an unknown transaction type.
Test: ./gradlew :multipaz-utopia:jvmTest (116 tests: DelegateTransactionTest,
DelegateMandateTextTest, DelegateMandateSchemaTest and
DelegateCheckoutSchemaTest, which check the tables and the checkout fixture
against AP2 v0.2.0's schemas, and DelegateAp2InteropTest, which runs seven AP2 mandate sets in both request
forms, one with selectively disclosed terms and closed checkouts that follow
the UCP schema, through a full OpenID4VP presentation, checks the Delegated
SD-JWT shape and that a request missing a disclosure, or with items on
different algorithms, is refused with its reason); ./gradlew :multipaz:jvmTest
(1879 tests, one skipped before this change, including
TransactionDataSdJwtKbTypeTest, TransactionDataValidateTogetherTest,
TransactionDataRendererRequirementTest, the new SdJwtTest cases and the
unnested array, claim collision and KB disclosure cases in
DigitalCredentialsPresentmentTest); ./gradlew detektMetadataCommonMain. The
iOS simulator targets of multipaz, multipaz-utopia, multipaz-doctypes and
multipaz-compose, and the iOS tests of the first two, compile. The responses
DelegateAp2InteropTest exports verify with AP2's Python SDK v0.2.0 (b4587ac)
through multipaz-utopia/scripts/verify_ap2_interop.py: 7 of 7 scenarios, with
the mandates the SDK resolves matching the requested ones; the script also
checks the nonce and audience, which the SDK skips on an intermediate hop,
and is not run in CI. The SwiftUI dialog change was not built: this host has
Xcode 27.2 and SwiftBridge needs the iOS 27.3 SDK.
Signed-off-by: Ever Morales <ever.morales@koombea.com>
AP2 delegates a spending mandate during an ordinary OpenID4VP presentation:
the verifier sends the Mandate Content as a `delegate` transaction data item
and the wallet signs its digest in the Key Binding JWT, as Delegate SD-JWT
section 7.1 describes, then returns the mandate disclosure after the Key
Binding JWT (section 5.1.1). Multipaz rejected such requests with "Unknown
transaction type 'delegate'" and failed the whole presentation.
Core changes, none specific to this protocol:
* `TransactionType.nestSdJwtResponseClaims`, default `true`. When `false`,
a type's response claims are merged into the KB-JWT verbatim instead of
being nested under `kbJwtResponseClaimName`, and arrays accumulate
across items of the same type rather than 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 the Key Binding
JWT carries, `null` (the ordinary `kb+jwt`) unless a type overrides it,
which `SdJwt.present()` used to hardcode. A type decides it over all of
its items at once, since one KB-JWT signs them all, so the result does
not depend on their order. `TransactionData.sdJwtKbType()`, internal,
combines the types and refuses two that ask for different values.
`SdJwtKb.verify()` takes the `typ` it expects, `kb+jwt` by default, so
a verifier can check a key binding such as `kb+sd-jwt` only when it
asks for that profile.
* `TransactionType.generateSdJwtResponse()` returns the KB-JWT claims
together with disclosures that follow the KB-JWT, as
`SdJwtTransactionResponse`. By default it returns the claims of
`generateSdJwtResponseClaims()` and no disclosures, so other types are
unchanged. When any type returns disclosures, `OpenID4VP` presents with
the new `SdJwt.presentWithKbDisclosures()`, which builds the same KB-JWT
as `present()` and returns the Delegated SD-JWT compact serialization
`<SD-JWT>~~<KB-JWT>~<Disclosure>~`; its `type` is required, because a
Key Binding JWT that carries disclosures is never the ordinary `kb+jwt`.
The ISO/IEC 18013-5 path only reads the new response type and refuses
disclosures, which its reader cannot accept.
`TransactionType.isApplicable()` may now throw
`IllegalArgumentException` for transaction data that is malformed, and
`OpenID4VP` reports it with its reason, like a parse failure. Both it
and `parseOpenId4VpRequest()` declare `@Throws`, as their overrides in
`DelegateTransaction` must on Kotlin/Native.
* `TransactionType.validateTogether()`, which does nothing by default,
lets a type check, before the consent prompt, the items of one
credential that a single response answers together, so a request that
could only fail after the person approved is refused up front with its
reason. `OpenID4VP` calls it when it parses `transaction_data`.
* `TransactionType.requiresRenderer`, default `false`. A type that sets it
cannot be approved with the built-in rendering: `PromptModel
.requestConsent()` throws `TransactionDataRendererNotAvailableException`,
naming the type, when no renderer is registered for it or no repository
was passed, and the Compose and SwiftUI consent dialogs refuse the same
way when the renderer registered is made for the other toolkit.
* Transaction data parsed from OpenID4VP now keeps
`transaction_data_hashes_alg`, so a request asking for SHA-384 is no
longer answered in SHA-256, and a value that is not an array of strings
is refused. The same change is submitted on its own in openwallet-foundation#2186 and leaves
this commit once that is merged.
`DelegateTransaction` lives in `multipaz-utopia`. Its identifier stays
`delegate`, the value AP2 sends on the wire. That name is not
collision-resistant, which is why the type is not in `multipaz-doctypes`; it
will change when the Delegate SD-JWT draft picks a new one. The type:
* applies only to key-bound SD-JWT VC credentials and refuses mandates it
cannot show;
* accepts both request forms, since the documents disagree: section 7.1's
`delegate_payload_disclosure` with a `dSD-JWT` or `dSD-JWT+KB` format,
and AP2's `delegate_payload`, several mandates in the clear with a
`dc+sd-jwt` format, for which it makes each disclosure with a fresh
128-bit salt;
* puts the digest of each mandate's disclosure in the `delegate_payload`
KB-JWT claim, under the algorithm the request names for the transaction
data hashes (SHA-256 if offered), and names that algorithm in `_sd_alg`.
The terms selectively disclosable within a mandate are resolved with
that same algorithm, because AP2's verifier hashes every nested digest
with the KB-JWT's and drops what does not match; a mandate that names
another `_sd_alg` is refused;
* returns the mandate disclosures, and any `delegate_disclosures` the
request carried, after the KB-JWT, so a verifier resolves the mandates
from the presentation itself;
* fills in the mandates' selectively disclosable terms from
`delegate_disclosures` and, before the consent prompt, refuses a request
whose digests and disclosures do not match one to one, so nothing is
signed that cannot be shown, throwing with the reason. A `cnf` behind a
digest, a key it cannot show, and a closed checkout whose
`checkout_hash` is not the hash of its `checkout_jwt` are refused too.
Items that settle on different algorithms, or share a disclosure, are
refused together before the prompt;
* types the key binding `kb+sd-jwt`, or `kb-sd-jwt+kb` when any of the
mandates names a further key in `cnf`, and requires a `cnf` for the
`dSD-JWT+KB` format;
* sets `requiresRenderer`, because its built-in rendering shows only a
heading and a person must not approve a spending permission they were
not shown.
The consent screen's wording is kept apart, in `DelegateMandateText`, so the
protocol side could later be replaced by an official AP2 library on its own.
Its `permissionSummary()` words the mandates for a person: the spending
limits ("Per purchase, up to", "In total, up to", or a closed mandate's
"Amount"), the merchant with its domain and id, who is paid when that is
someone else, the items, the expiry and the agent key, with every line
still reachable through `PermissionSummary.details`, and `mandateDetails()`
gives each mandate's heading, type and lines for a details page. It words
what AP2's SDK v0.2.0 enforces, which differs from its schema in three
places: `payment.budget` is scaled by 100 in every currency, an empty
`acceptable_items` is a wildcard ("Up to 10 × any item"), and a requirement's
quantity is a maximum. Items show their id beside the title, since AP2 matches
on the id; a closed checkout's `checkout_jwt` is read as the UCP checkout the
SDK parses, its amounts in minor units with the checkout's currency, as the
checkout the requester sent, not as signed by the merchant, whose signature
is not verified. What it recognises by name, the constraint kinds and their
members, the units of each amount, the merchant and line item members, the
mandate types and the date claims, is kept in tables that a test checks
against AP2 v0.2.0's own JSON Schemas, copied unchanged into the tests, so a
protocol change cannot go unnoticed.
`addUtopiaTypes()` does not register `DelegateTransaction`: an application
registers it together with a `TransactionDataRenderer` that draws the mandate
from `permissionSummary()` and `mandateDetails()`, and without one the prompt
refuses. Disclosures after the Key Binding JWT work over OpenID4VP only; the
ISO/IEC 18013-5 path refuses them. A Multipaz verifier cannot read a
Delegated SD-JWT yet, and AP2's own example request, whose first item has
type `payment_card`, still fails with an unknown transaction type.
Test: ./gradlew :multipaz-utopia:jvmTest (116 tests: DelegateTransactionTest,
DelegateMandateTextTest, DelegateMandateSchemaTest and
DelegateCheckoutSchemaTest, which check the tables and the checkout fixture
against AP2 v0.2.0's schemas, and DelegateAp2InteropTest, which runs seven AP2
mandate sets in both request forms, one with selectively disclosed terms and
closed checkouts that follow the UCP schema, through a full OpenID4VP presentation, checks the Delegated
SD-JWT shape and that a request missing a disclosure, or with items on
different algorithms, is refused with its reason); ./gradlew :multipaz:jvmTest
(1879 tests, one skipped before this change, including
TransactionDataSdJwtKbTypeTest, TransactionDataValidateTogetherTest,
TransactionDataRendererRequirementTest, the new SdJwtTest cases and the
unnested array, claim collision and KB disclosure cases in
DigitalCredentialsPresentmentTest); ./gradlew detektMetadataCommonMain. The
iOS simulator targets of multipaz, multipaz-utopia, multipaz-doctypes and
multipaz-compose, and the iOS tests of the first two, compile. The responses
DelegateAp2InteropTest exports verify with AP2's Python SDK v0.2.0 (b4587ac)
through multipaz-utopia/scripts/verify_ap2_interop.py: 7 of 7 scenarios, with
the mandates the SDK resolves matching the requested ones; the script also
checks the nonce and audience, which the SDK skips on an intermediate hop,
and is not run in CI. The SwiftUI dialog change was not built: this host has
Xcode 27.2 and SwiftBridge needs the iOS 27.3 SDK.
Signed-off-by: Ever Morales <ever.morales@koombea.com>
AP2 delegates a spending mandate during an ordinary OpenID4VP presentation:
the verifier sends the Mandate Content as a `delegate` transaction data item
and the wallet signs its digest in the Key Binding JWT, as Delegate SD-JWT
section 7.1 describes, then returns the mandate disclosure after the Key
Binding JWT (section 5.1.1). Multipaz rejected such requests with "Unknown
transaction type 'delegate'" and failed the whole presentation.
Core changes, none specific to this protocol:
* `TransactionType.nestSdJwtResponseClaims`, default `true`. When `false`,
a type's response claims are merged into the KB-JWT verbatim instead of
being nested under `kbJwtResponseClaimName`, and arrays accumulate
across items of the same type rather than 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 the Key Binding
JWT carries, `null` (the ordinary `kb+jwt`) unless a type overrides it,
which `SdJwt.present()` used to hardcode. A type decides it over all of
its items at once, since one KB-JWT signs them all, so the result does
not depend on their order. `TransactionData.sdJwtKbType()`, internal,
combines the types and refuses two that ask for different values.
`SdJwtKb.verify()` takes the `typ` it expects, `kb+jwt` by default, so
a verifier can check a key binding such as `kb+sd-jwt` only when it
asks for that profile.
* `TransactionType.generateSdJwtResponse()` returns the KB-JWT claims
together with disclosures that follow the KB-JWT, as
`SdJwtTransactionResponse`. By default it returns the claims of
`generateSdJwtResponseClaims()` and no disclosures, so other types are
unchanged. When any type returns disclosures, `OpenID4VP` presents with
the new `SdJwt.presentWithKbDisclosures()`, which builds the same KB-JWT
as `present()` and returns the Delegated SD-JWT compact serialization
`<SD-JWT>~~<KB-JWT>~<Disclosure>~`; its `type` is required, because a
Key Binding JWT that carries disclosures is never the ordinary `kb+jwt`.
The ISO/IEC 18013-5 path only reads the new response type and refuses
disclosures, which its reader cannot accept.
`TransactionType.isApplicable()` may now throw
`IllegalArgumentException` for transaction data that is malformed, and
`OpenID4VP` reports it with its reason, like a parse failure. Both it
and `parseOpenId4VpRequest()` declare `@Throws`, as their overrides in
`DelegateTransaction` must on Kotlin/Native.
* `TransactionType.validateTogether()`, which does nothing by default,
lets a type check, before the consent prompt, the items of one
credential that a single response answers together, so a request that
could only fail after the person approved is refused up front with its
reason. `OpenID4VP` calls it when it parses `transaction_data`.
* `TransactionType.requiresRenderer`, default `false`. A type that sets it
cannot be approved with the built-in rendering: `PromptModel
.requestConsent()` throws `TransactionDataRendererNotAvailableException`,
naming the type, when no renderer is registered for it or no repository
was passed, and the Compose and SwiftUI consent dialogs refuse the same
way when the renderer registered is made for the other toolkit.
* Transaction data parsed from OpenID4VP now keeps
`transaction_data_hashes_alg`, so a request asking for SHA-384 is no
longer answered in SHA-256, and a value that is not an array of strings
is refused. The same change is submitted on its own in openwallet-foundation#2186 and leaves
this commit once that is merged.
`DelegateTransaction` lives in `multipaz-utopia`. Its identifier stays
`delegate`, the value AP2 sends on the wire. That name is not
collision-resistant, which is why the type is not in `multipaz-doctypes`; it
will change when the Delegate SD-JWT draft picks a new one. The type:
* applies only to key-bound SD-JWT VC credentials and refuses mandates it
cannot show;
* accepts both request forms, since the documents disagree: section 7.1's
`delegate_payload_disclosure` with a `dSD-JWT` or `dSD-JWT+KB` format,
and AP2's `delegate_payload`, several mandates in the clear with a
`dc+sd-jwt` format, for which it makes each disclosure with a fresh
128-bit salt;
* puts the digest of each mandate's disclosure in the `delegate_payload`
KB-JWT claim, under the algorithm the request names for the transaction
data hashes (SHA-256 if offered), and names that algorithm in `_sd_alg`.
The terms selectively disclosable within a mandate are resolved with
that same algorithm, because AP2's verifier hashes every nested digest
with the KB-JWT's and drops what does not match; a mandate that names
another `_sd_alg` is refused;
* returns the mandate disclosures, and any `delegate_disclosures` the
request carried, after the KB-JWT, so a verifier resolves the mandates
from the presentation itself;
* fills in the mandates' selectively disclosable terms from
`delegate_disclosures` and, before the consent prompt, refuses a request
whose digests and disclosures do not match one to one, so nothing is
signed that cannot be shown, throwing with the reason. A `cnf` behind a
digest, a key it cannot show, and a closed checkout whose
`checkout_hash` is not the hash of its `checkout_jwt` are refused too.
Items that settle on different algorithms, or share a disclosure, are
refused together before the prompt;
* types the key binding `kb+sd-jwt`, or `kb-sd-jwt+kb` when any of the
mandates names a further key in `cnf`, and requires a `cnf` for the
`dSD-JWT+KB` format;
* sets `requiresRenderer`, because its built-in rendering shows only a
heading and a person must not approve a spending permission they were
not shown.
The consent screen's wording is kept apart, in `DelegateMandateText`, so the
protocol side could later be replaced by an official AP2 library on its own.
Its `permissionSummary()` words the mandates for a person: the spending
limits ("Per purchase, up to", "In total, up to", or a closed mandate's
"Amount"), the merchant with its domain and id, who is paid when that is
someone else, the items, the expiry and the agent key, with every line
still reachable through `PermissionSummary.details`, and `mandateDetails()`
gives each mandate's heading, type and lines for a details page. It words
what AP2's SDK v0.2.0 enforces, which differs from its schema in three
places: `payment.budget` is scaled by 100 in every currency, an empty
`acceptable_items` is a wildcard ("Up to 10 × any item"), and a requirement's
quantity is a maximum. Items show their id beside the title, since AP2 matches
on the id; a closed checkout's `checkout_jwt` is read as the UCP checkout the
SDK parses, its amounts in minor units with the checkout's currency, as the
checkout the requester sent, not as signed by the merchant, whose signature
is not verified. What it recognises by name, the constraint kinds and their
members, the units of each amount, the merchant and line item members, the
mandate types and the date claims, is kept in tables that a test checks
against AP2 v0.2.0's own JSON Schemas, copied unchanged into the tests, so a
protocol change cannot go unnoticed.
`addUtopiaTypes()` does not register `DelegateTransaction`: an application
registers it together with a `TransactionDataRenderer` that draws the mandate
from `permissionSummary()` and `mandateDetails()`, and without one the prompt
refuses. Disclosures after the Key Binding JWT work over OpenID4VP only; the
ISO/IEC 18013-5 path refuses them. A Multipaz verifier cannot read a
Delegated SD-JWT yet, and AP2's own example request, whose first item has
type `payment_card`, still fails with an unknown transaction type.
Test: ./gradlew :multipaz-utopia:jvmTest (116 tests: DelegateTransactionTest,
DelegateMandateTextTest, DelegateMandateSchemaTest and
DelegateCheckoutSchemaTest, which check the tables and the checkout fixture
against AP2 v0.2.0's schemas, and DelegateAp2InteropTest, which runs seven AP2
mandate sets in both request forms, one with selectively disclosed terms and
closed checkouts that follow the UCP schema, through a full OpenID4VP
presentation, checks the Delegated SD-JWT shape and that a request missing a
disclosure, or with items on different algorithms, is refused with its
reason); ./gradlew :multipaz:jvmTest (1879 tests, one skipped before this
change, including TransactionDataSdJwtKbTypeTest,
TransactionDataValidateTogetherTest, TransactionDataRendererRequirementTest,
the new SdJwtTest cases and the unnested array, claim collision and KB
disclosure cases in DigitalCredentialsPresentmentTest); ./gradlew
detektMetadataCommonMain. The iOS simulator targets of multipaz,
multipaz-utopia, multipaz-doctypes and multipaz-compose, and the iOS tests of
the first two, compile. The responses DelegateAp2InteropTest exports verify
with AP2's Python SDK v0.2.0 (b4587ac) through
multipaz-utopia/scripts/verify_ap2_interop.py: 7 of 7 scenarios, with the
mandates the SDK resolves matching the requested ones; the script also checks
the nonce and audience, which the SDK skips on an intermediate hop, and is not
run in CI. The SwiftUI dialog change was not built: this host has Xcode 27.2
and SwiftBridge needs the iOS 27.3 SDK.
Signed-off-by: Ever Morales <ever.morales@koombea.com>
`TransactionType.parseJson()` read the payload of an OpenID4VP `transaction_data` item but not its `transaction_data_hashes_alg`, so `TransactionData.hashAlgorithms` was always null for a type that does not override it. Such a type hashed the item with SHA-256 even when the verifier asked for another algorithm, and the verifier could not match the hash. `PaymentTransaction` and `PingTransaction` read the list in their own `parseJson()`, so they were not affected. The base `parseJson()` now reads the list with `parseJoseHashAlgorithms()`, as those overrides do: unknown names are skipped and a list naming no known algorithm is refused. A value that is not an array of strings is refused as well, with a message naming `transaction_data_hashes_alg`, instead of being answered in SHA-256. An absent or null value leaves the default. Test: ./gradlew :multipaz:jvmTest, :multipaz-doctypes:jvmTest and detektMetadataCommonMain, run as separate invocations. The new `TransactionTypeParseJsonTest` covers the round trip, absent and null values, unknown and unsupported names, and malformed values, including a number next to a valid name. That last case fails if the per-element type check in `parseJson()` is removed. Signed-off-by: Ever Morales <ever.morales@koombea.com>
863c95b to
6a49d21
Compare
|
@dzuluaga all threads are addressed in 6a49d21, and CI is green. Issue link: the PR now closes openwallet-foundation/multipaz#2214, and #2010 is only mentioned. |
Fixes #2214
Split out of #2178. Related to #2010.
Summary
TransactionType.parseJson()droppedtransaction_data_hashes_alg. A transaction type that doesn't override it hashed its transaction data with SHA-256 even when the verifier asked for another algorithm.PaymentTransactionandPingTransactionread the list in their ownparseJson(), so they weren't affected.The base function now reads it the same way. A value that isn't an array of strings is refused.
Testing
:multipaz:jvmTest(with the newTransactionTypeParseJsonTest),:multipaz-doctypes:jvmTestanddetektMetadataCommonMain, run separately.The mixed-array case fails if the per-element type check is removed.
Tests pass
Appropriate changes to README are included in PR (none needed)