Repository navigation
Draw AP2 spending permissions with default renderers in the SDK. - #2196
Draft
TheBlackBit wants to merge 4 commits into
Draft
TheBlackBit wants to merge 4 commits into
TheBlackBit wants to merge 4 commits into
Conversation
TheBlackBit
force-pushed
the
feat/ap2-delegate-renderer
branch
from
November 14, 2026 01:08
5605ec4 to
a989b9d
Compare
2 tasks done
TheBlackBit
force-pushed
the
feat/ap2-delegate-renderer
branch
from
November 17, 2026 21:51
a989b9d to
cb8058a
Compare
This was referenced Nov 18, 2026
TheBlackBit
force-pushed
the
feat/ap2-delegate-renderer
branch
2 times, most recently
from
November 20, 2026 21:55
a16ef4a to
a9c0fc7
Compare
2 tasks done
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>
TheBlackBit
force-pushed
the
feat/ap2-delegate-renderer
branch
from
November 20, 2026 22:24
a9c0fc7 to
c4806fc
Compare
2 tasks done
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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) andDelegateTransactionRendererSwiftUi(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 aKind, so icons no longer depend on English labels. It also holds the screen's strings, shared by both platforms, anddescribeMandates()for the details page.addDelegateTransactionType(): registers the type. Swift can't calladdTransactionType()with it, since there it takes aTransactionType<AnyObject>.Testing
:multipaz-utopia:jvmTest(73),:multipaz-compose:testDebugUnitTestwith a new consent golden (ap2_delegate_default_renderer), the testapp's Android build and unit tests, anddetektMetadataCommonMain.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
SwiftBridgeneeds. With that code disabled locally (not in this PR), the iOS framework builds andswiftctype-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)