Skip to content

Draw AP2 spending permissions with default renderers in the SDK. - #2196

Draft
TheBlackBit wants to merge 4 commits into
openwallet-foundation:mainfrom
TheBlackBit:feat/ap2-delegate-renderer
Draft

TheBlackBit wants to merge 4 commits into
openwallet-foundation:mainfrom
TheBlackBit:feat/ap2-delegate-renderer

Conversation

@TheBlackBit

@TheBlackBit TheBlackBit commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Fixes #2010

Builds on #2178, which adds DelegateTransaction, and on #2224 and #2225, which add the core hooks; until those are merged, this PR also shows their commits.

Summary

Asked for in the review of openwallet-foundation/multipaz-wallet#48: the AP2 spending permission screen was written twice in the wallet, once per platform, and nothing in it was wallet-specific. It now ships in the SDK as the default renderer for delegate, so a wallet only registers it.

Changes

  • DelegateTransactionRendererCompose (multipaz-compose) and DelegateTransactionRendererSwiftUi (multipaz-swiftui): limits set large, then merchant, payee, items, expiry and agent; the details page lists every mandate in full. If the mandates can't be read, it shows an error instead of an empty block.
  • DelegateMandateText: each summary row has a Kind, so icons no longer depend on English labels. It also holds the screen's strings, shared by both platforms, and describeMandates() for the details page.
  • addDelegateTransactionType(): registers the type. Swift can't call addTransactionType() with it, since there it takes a TransactionType<AnyObject>.
  • Testapp: registers the type and renderer, provisions an SD-JWT payment card with the test documents, and adds an "AP2: let an agent spend up to 400 USD" request. The SwiftTestApp registers the SwiftUI renderer, and its Xcode project compiles the new file.

Testing

  • :multipaz-utopia:jvmTest (73), :multipaz-compose:testDebugUnitTest with a new consent golden (ap2_delegate_default_renderer), the testapp's Android build and unit tests, and detektMetadataCommonMain.

  • The wallet builds and passes its tests against this branch, with its renderer reduced to registering this one.

  • iOS: my Xcode is 27.2, without the iOS 27.3 SDK that SwiftBridge needs. With that code disabled locally (not in this PR), the iOS framework builds and swiftc type-checks the SwiftUI renderer and the SwiftTestApp registration against it, with no errors or warnings. The SwiftTestApp wasn't run, and there is no SwiftUI golden yet.

  • In the testapp, the verifier side doesn't read the <SD-JWT>~~<KB-JWT>~… response yet, so it reports an error after the consent screen.

  • Tests pass (JVM and Android; iOS type-checked only)

  • Appropriate changes to README are included in PR (golden catalog)

Ever Morales added 4 commits November 20, 2026 16:24
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, since ISO/IEC 18013-5 has no place for them.
- `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.
- The overridable functions declare `@Throws`, so Kotlin/Native
  overrides do not hit a filter mismatch.

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

Signed-off-by: Ever Morales <ever.morales@koombea.com>
The built-in consent rendering of transaction data shows only a heading.
For a type whose data the person must read to give informed consent, such
as a spending permission, that is not enough: it would be approved blind.
Let such a type say so, and refuse the prompt when it cannot be drawn.

- `TransactionType.requiresRenderer`, default `false`, says a type's data
  must be shown by a renderer made for the UI toolkit in use. Existing
  types are unchanged.
- `requestConsent()` throws `TransactionDataRendererNotAvailableException`,
  naming the type, before showing anything when the transaction data holds
  such a type and no renderer is registered for it or no repository was
  passed.
- The Compose and SwiftUI consent dialogs refuse the same way when the
  registered renderer is made for the other toolkit, which counts as no
  renderer. `missingTransactionDataRenderer()` holds the shared check and
  takes what the toolkit can draw.
- `PresentmentData.allTransactionData` lists every item of every match, so
  a prompt can find out which renderers it needs before it is shown.

Test: ./gradlew :multipaz:jvmTest (1885 tests, 0 failures), including the
new TransactionDataRendererRequirementTest; ./gradlew
:multipaz-compose:compileKotlinIosSimulatorArm64
:multipaz:compileTestKotlinIosSimulatorArm64
:multipaz-compose:compileDebugKotlinAndroid. The SwiftUI guard is not
compiled, as the host lacks the iOS SDK it needs.

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.

It builds on the generic hooks of `TransactionType` added in the two previous
commits (`sdJwtKbType()`, `generateSdJwtResponse()`, `validateTogether()` and
`nestSdJwtResponseClaims`, then `requiresRenderer`); nothing in `multipaz` is
specific to this protocol.

`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 detektMetadataCommonMain. The iOS simulator targets of
multipaz-utopia and its tests 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.

Signed-off-by: Ever Morales <ever.morales@koombea.com>
An AP2 `delegate` request asks the holder to let an agent spend for them
later. Each wallet had to write the consent screen for it, on Android and
iOS, and match its rows by their English labels to pick an icon. The SDK
now ships that screen as the default renderer for the type:

  * `DelegateTransactionRendererCompose` in `multipaz-compose` and
    `DelegateTransactionRendererSwiftUi` in `multipaz-swiftui`. The prompt
    shows the spending limits set large, then the merchant, who is paid,
    the items, the expiry and the agent, one row each. The details page
    lists every mandate in full, as it will be signed, with the origin or
    app that asked. If the mandates can't be read, an error is shown
    instead of an empty block.
  * `DelegateMandateText` gives each summary row a `Kind` (merchant,
    payee, items, expiry, agent, other), so a screen picks the icon
    without reading the label. It also holds the screen's strings, shared
    by both renderers, and `mandateDetails()` for the details page, one
    `MandateDetails` per mandate.

`addUtopiaTypes()` still does not register `DelegateTransaction`. An app
adds it with the new `addDelegateTransactionType()`, together with the
renderer or its own. Swift needs that helper: there
`addTransactionType()` takes a `TransactionType<AnyObject>`, which
`DelegateTransaction` is not, and a cast to it fails.

The testapp registers both, provisions an SD-JWT payment card with the
test documents, and offers an "AP2: let an agent spend up to 400 USD"
request, so the consent screen can be tried on a device. The SwiftTestApp
registers the SwiftUI renderer, and its Xcode project now compiles the new
file. A Compose consent golden covers the summary and the details page.

Test: ./gradlew :multipaz-utopia:jvmTest (103 tests),
:multipaz-compose:testDebugUnitTest (consent goldens, with the new
ap2_delegate_default_renderer scenario), :multipaz-compose:
compileKotlinIosSimulatorArm64 and detektMetadataCommonMain. The testapp and
SwiftTestApp were not rebuilt after rebasing onto the mandate changes. On iOS,
this host's Xcode 27.2 lacks the iOS 27.3 SDK that SwiftBridge and some
multipaz-swiftui files need, so the SwiftUI renderer was not built or run and
there is no SwiftUI golden for it yet.

Signed-off-by: Ever Morales <ever.morales@koombea.com>

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.

OpenID4VP: an AP2 mandate cannot be delegated — the delegate transaction type is unregistered

1 participant