Skip to content

Support AP2 spending mandates delegated over OpenID4VP. - #2178

Draft
TheBlackBit wants to merge 3 commits into
openwallet-foundation:mainfrom
TheBlackBit:feat/ap2-delegate-transaction-utopia
Draft

TheBlackBit wants to merge 3 commits into
openwallet-foundation:mainfrom
TheBlackBit:feat/ap2-delegate-transaction-utopia

Conversation

@TheBlackBit

@TheBlackBit TheBlackBit commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Part of #2010

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

Replaces #2011: the type now lives in multipaz-utopia.

Summary

With AP2 a person lets an AI agent buy things for them later, within limits they approve once. The verifier sends the mandates as OpenID4VP transaction_data of type delegate. The wallet signs a digest of each in the Key Binding JWT and returns the mandate disclosures after it, as Delegate SD-JWT describes. Today Multipaz fails with Unknown transaction type 'delegate'.

This PR is the protocol side and the consent wording. It depends on #2224 and #2225. The default screens and the sample-app wiring are in #2196.

Changes

Core (multipaz): none. The generic hooks this type uses are in #2224 (nestSdJwtResponseClaims, sdJwtKbType(), generateSdJwtResponse(), validateTogether()) and #2225 (requiresRenderer), so this PR shows their commits until they are merged.

multipaz-utopia:

  • DelegateTransaction, the protocol: accepts both request forms, AP2's delegate_payload (mandates in the clear; the wallet makes their disclosures) and the draft's delegate_payload_disclosure. Every nested digest resolves with the algorithm the KB-JWT names, as AP2's verifier does. A request whose digests and disclosures don't match one to one, a cnf behind a digest, a closed checkout whose hash isn't the hash of its JWT, or items that settle on different algorithms or share a disclosure, are refused before consent. It sets requiresRenderer. Not registered by addUtopiaTypes().
  • DelegateMandateText, the consent text: permissionSummary() and mandateDetails(). It follows AP2's SDK v0.2.0, which differs from its schema in three places: payment.budget is scaled by 100 in every currency, an empty acceptable_items is a wildcard, and a requirement's quantity is a maximum.

Not in this PR

Testing

  • :multipaz-utopia:jvmTest (116) and detektMetadataCommonMain. The iOS simulator targets of multipaz-utopia and its tests compile. The core tests are in Let transaction types control their SD-JWT response #2224 and Refuse to approve transaction data that no renderer can show #2225.

  • multipaz-utopia/scripts/verify_ap2_interop.py runs the exported responses through AP2's Python SDK v0.2.0 (b4587ac): 7 of 7 scenarios verified, at c2a8ab8. It's the repo's first Python tool and isn't run in CI.

  • DelegateMandateSchemaTest and DelegateCheckoutSchemaTest check what the text recognises, and the checkout fixture, against AP2 v0.2.0's JSON Schemas, copied into the tests.

  • Tests pass

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

@dzuluaga dzuluaga left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

In short: this works and the direction is right. Two bugs to fix first: a spending limit shown 100 times too small, and the wallet signing without showing the mandate. Then four changes so AP2's reference SDK can read what the wallet returns. Details below.

Thanks Ever. On the direction: the type lives in multipaz-utopia, the core changes are small and leave every existing type's output unchanged, and the delegate_payload claim name, the digest computation and sd_hash all match AP2 and CMWallet. Your AP2 issue (google-agentic-commerce/AP2#380) already raised the request-shape mismatch, which is the root of two points below.

Context for this review: we keep building this as a prototype and will align with an official AP2 Kotlin library if one appears. So the bar is what AP2 actually accepts today. I reviewed by reading against the AP2 repo (docs, schemas, Python SDK, Android sample), the Delegate SD-JWT draft and CMWallet's agentic-dpc branch. I did not build your branch. I did run AP2's Python SDK (v0.2; 186 of its 188 tests pass) against tokens hand-built to match what your code emits, so the Python results below are tested and the rest is by reading.

Fix first (plain bugs)

  1. payment.budget.max is shown 100x too small. DelegateTransaction.kt:277 formats it as minor units. AP2 defines it in major units: open_payment_mandate.json types it as a number, the doc example is 1000.00, and the Python SDK does int(max * 100) (constraints.py:307). The test at DelegateTransactionTest.kt:392 pins 40000 as "400.00", which an AP2 verifier would enforce as USD 40,000. Keep minor units only for payment.amount_range and types/amount.json.

  2. The type is registered by default with no renderer. DocumentTypeRepositoryExt.kt:35 adds it to addUtopiaTypes(), but the KDoc at DelegateTransaction.kt:48-52 says the built-in prompt shows only a heading. None ships, so the sample wallets would show "Delegate authorization" and sign. Ship the renderer in the same change, or don't register by default, or fail closed when no renderer is registered.

Needed to interoperate with AP2 today

Tested against AP2's Python verifier: as emitted, the token is accepted but only the root credential comes back; the mandate is never seen. Re-framed as <SD-JWT>~~<KB-JWT>~<mandate disclosure>~, it verifies and returns the mandate, with your digest form and typ unchanged. By reading only: the AP2 Android agent fails with "Missing checkout mandate disclosure" and CMWallet finds no mandate.

  1. The request AP2 and CMWallet send is refused. DelegateTransaction.kt:553-557 throws without delegate_payload_disclosure. AP2 (agent_authorization.md:104-111) requires a delegate_payload array of mandate objects, and that is what the AP2 Android agent and CMWallet build. Your shape matches draft section 7.1, so keep it and accept both.

  2. The response is not a delegated SD-JWT. SdJwt.kt:697 returns <issuer>~<disclosures>~<KB-JWT>. The draft, CMWallet (SdJwt.kt:304-309) and AP2's Python SDK (mandate.py:198 splits on ~~) use <SD-JWT>~~<KB-JWT>~<mandate disclosure>~. This needs the third core hook (disclosures): one call returning the claims and the trailing disclosures together. SdJwtKb.fromCompactSerialization rejects a trailing ~ (SdJwtKb.kt:161), so it likely needs a present method that returns a string.

  3. typ comes from the first item only (OpenID4VP.kt:883). With AP2's own example (checkout mandate with cnf, payment mandate without) the result depends on order. Decide over the whole set. Tested: with [closed, open+cnf] and the first item's kb+sd-jwt, Python rejects with "Terminal KB-SD-JWT MUST NOT carry a 'cnf' claim"; with kb+sd-jwt+kb it verifies.

  4. Mandate digest algorithm. The digest follows transaction_data_hashes_alg (DelegateTransaction.kt:609) and _sd_alg is never emitted. Tested: AP2's Python SDK only supports SHA-256. A SHA-384 digest is silently left unresolved (no mandate returned), and adding _sd_alg: sha-384 is rejected with "Invalid hash algorithm". Use SHA-256 for the mandate digest regardless of transaction_data_hashes_alg, and emit _sd_alg: "sha-256" as the Python SDK does.

Should fix

  • Signed but not shown. delegate_disclosures are parsed (:568) but never resolved or validated, so selectively disclosable terms are missing from the summary. Closed mandates render as raw minor units or an empty summary, and the merchant/payee de-dup (:297) can hide a differing payee.
  • Un-nested claims can overwrite reserved KB-JWT claims (nonce, aud, sd_hash) and each other (OpenID4VP.kt:809). Reject reserved names and collisions.
  • typ spelling. You use kb+sd-jwt+kb; CMWallet uses kb-sd-jwt+kb. Tested: AP2's Python SDK accepts both and emits yours. Leave it as is; it's an open question for the draft authors, not a defect.
  • DelegateTransaction does three jobs. About 420 of 619 lines are English consent text with no production caller. Keeping the wire logic separate from the AP2 rendering will make it much easier to swap in an official library later.

How we show it is correct

  • Use AP2's Python SDK as the reference: a test that drives the type through OpenID4VP to a decoded KB-JWT header, payload and serialization, and vectors exchanged both ways (Python signs and Multipaz verifies, and the reverse). AP2#307 has four golden vectors for the chain layer we can start from.
  • CMWallet's DpcSdJwtMandateTest lists good assertions to mirror (two JWTs in the result, trailing ~, sd_hash, disclosures after the KB-JWT, digest match, typ with and without cnf). Re-create them; don't copy its fixture credential, since that branch has no licence file.
  • Mandate models: generate them from the AP2 JSON schemas instead of matching constraint strings by hand. The schemas are small (six mandate/receipt schemas, seven shared types, one union of eight constraint kinds, five selective-disclosure markers). I have not run a Kotlin generator on them yet.
  • Did you compare your output against the Python SDK at any point? If so, add what you found to the PR description.

Smaller points

  • The base parseJson change for transaction_data_hashes_alg only affects types that don't override parseJson (PaymentTransaction already parses it). Make it its own commit.
  • format is required but any value is accepted (:561).
  • Public KDoc names CredentAgent, and several test comments start with "BYPASS:".
  • formatInstant prints "...Z UTC"; the strings are hard-coded English.

@TheBlackBit

Copy link
Copy Markdown
Contributor Author

@dzuluaga thanks for the review. Everything is addressed, and the description is updated.

  • Fix first: payment.budget is read in major units. addUtopiaTypes() no longer registers the type; an app registers it with its renderer, as Show AP2 spending permissions in the consent prompt. multipaz-wallet#48 does.
  • Interop: both request forms are accepted, the response is <SD-JWT>~~<KB-JWT>~<disclosures>~, and typ is decided over all items. _sd_alg is always present. The digest still follows transaction_data_hashes_alg, as §7.1 allows, and AP2 asks for sha-256, so that's what it gets.
  • Should fix: delegate_disclosures are resolved and checked one to one before consent, and the mandates are shown with those terms, closed amounts and a differing payee. Reserved claims and collisions are refused. typ spelling left as is. Split into DelegateTransaction (protocol) and DelegateMandateText (text).
  • Correctness: AP2's Python SDK v0.2.0 verifies our responses (seven mandate sets, both request forms) and returns every mandate, and Multipaz verifies AP2's proposed golden vectors. DelegateAp2InteropTest re-creates the assertions you listed. Instead of generated models, DelegateMandateSchemaTest checks what the text recognises against AP2 v0.2.0's schemas.
  • Smaller points: the parseJson fix is in Keep the verifier's hash algorithms for every transaction type. #2186. format is validated, KDoc and test comments are cleaned up, and dates no longer print "Z UTC". The strings are still English, all in DelegateMandateText.

@dzuluaga dzuluaga left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

The rule behind this review: the sample app is the measurement. The code a sample app needs in order to use a feature is the code every developer will have to write, so that code comes first and should fit on one screen, about 30 lines. Short is not enough: it should also read top to bottom as what the developer is trying to do, with no plumbing before the point and names that say what they do, the way a Stripe SDK example does. Using this type takes about 590 lines across Compose and SwiftUI in multipaz-wallet#48; the SDK's own sample app draws three transaction types in 126. When the sample app needs that much, the API is not finished, and that is the thing to fix before anything else.

Thanks Ever. The wire format is now right for AP2 and every item from the first review was addressed. Confirmed by reading at 4c4d4fd: both request forms, the <SD-JWT>~~<KB-JWT>~<disclosures>~ response, typ over all items, _sd_alg always present, reserved claims refused, and refusal before consent when digests and disclosures don't match. I have not built the branch. Line-specific points are inline; what follows is what doesn't belong to one line.

The target

documentTypeRepository.addUtopiaTypes()   // includes delegate, with a built-in consent screen

and, only for a custom look, renderers.addRenderer(DelegateTransaction.identifier, myRenderer).

For the rework and for PRs after this one: please write the sample-app code first and send it to me before implementing. If it runs past one screen, raise the API question then.

Before merge

  1. Registering the type must be safe by itself. Today there are three ways to sign after showing only "This Delegate authorization transaction will be approved" (Consent.kt:2186-2193): no renderer, a renderer for the other toolkit (TransactionDataBlocks.kt:40), or the repository not passed (PromptModelExt.kt:110). DelegateAp2InteropTest does the first and gets signatures. Please add a DelegateTransaction branch to DisplayTransactionData in multipaz-compose (Consent.kt:2036, next to Ping and Payment) and to Consent.swift in multipaz-swiftui, moving the screens from multipaz-wallet#48 into the SDK, then register the type in addUtopiaTypes().
  2. Show it in the sample apps. A canned AP2 delegate request in samples/testapp and samples/SwiftTestApp (patterns: TestAppTransactionDataRenderers.kt:34, SwiftTestAppTransactionDataRenderers.swift:53, DcRequestScreen.kt:417-449), and a usage example in DelegateTransaction's KDoc.
  3. Show what is enforced, and fix the typ. See the inline comments on DelegateMandateText.kt and DelegateTransaction.kt.
  4. Make the evidence reproducible. See the inline comments on DelegateAp2InteropTest.kt. Your reply mentions AP2's golden vectors; I found none in the diff.
  5. Repo rules (CODING-STYLE.md): inline for the random source, generic catch and @Throws. Lines over 120: DelegateTransaction.kt:248, :384, :388, :403; DelegateMandateText.kt:351; OpenID4VP.kt:846.

Scope and sequencing

  • I'd split this in three, each mergeable and safe by itself: (1) the core hooks and their tests; (2) the type, its text, the built-in screens and the interop tests; (3) the sample apps, opened alongside the second. The one cut to avoid is the type without its screen.
  • The transaction_data_hashes_alg parsing is also in #2186; land that first.
  • "Fixes #2010" should be "Part of #2010" until a screen ships.
  • AP2's published example also sends a payment_card item (agent_authorization.md:151-153, :179), which Multipaz has no type for yet. Please say in the description where that will land.
  • Multipaz cannot yet verify what this produces (VerificationUtil.kt:1036-1038). Fine as a follow-up if the description says so.

@TheBlackBit TheBlackBit self-assigned this Nov 14, 2026
@dzuluaga dzuluaga removed their assignment Nov 14, 2026
@dzuluaga dzuluaga moved this from In review to In progress in CredentAgent Nov 14, 2026
@TheBlackBit
TheBlackBit force-pushed the feat/ap2-delegate-transaction-utopia branch 3 times, most recently from 2fc0857 to de69c40 Compare November 17, 2026 17:06
@TheBlackBit
TheBlackBit force-pushed the feat/ap2-delegate-transaction-utopia branch from de69c40 to 8773304 Compare November 17, 2026 21:27
@TheBlackBit
TheBlackBit requested a review from dzuluaga November 17, 2026 21:34
@TheBlackBit TheBlackBit assigned dzuluaga and unassigned TheBlackBit Nov 17, 2026
@TheBlackBit TheBlackBit moved this from In progress to In review in CredentAgent Nov 17, 2026
@TheBlackBit TheBlackBit self-assigned this Nov 17, 2026
@TheBlackBit

Copy link
Copy Markdown
Contributor Author

Thanks for the thorough review, @dzuluaga. All the threads are covered, and all your points were valid and helpful.

@TheBlackBit
TheBlackBit force-pushed the feat/ap2-delegate-transaction-utopia branch from 8773304 to 565539e Compare November 17, 2026 21:49

@dzuluaga dzuluaga left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Thanks Ever. The round-2 threads I re-checked at 565539e are addressed, except #19 (below). The wire format matches AP2, and the interop script can be re-run. Not ready to merge yet: what the person sees can still differ from what is signed or enforced, and the description no longer matches the code.

Sample-app measurement. With #2178 alone, a Compose wallet needs about 34 lines plus imports. SwiftUI may not be able to register the type at all (see the question in Also noticed). With #2196 it is two statements per platform, but leaving out the renderer still signs. The target: the SDK's screens from #2196, registered in as few calls as possible, and a library that refuses to sign when the screen is missing.

Before merge

  1. Registration must be safe by itself. Keep the screens in the SDK, as #2196 does, and add a generic guard in core: a type can declare that it needs a renderer, and the prompt refuses when none is registered for the active toolkit. Landing #2196 alone doesn't do this. See DelegateTransaction.kt:44.
  2. Use one hash algorithm for display and signing. See DelegateTransaction.kt:396. My round-2 #9 caused this one.
  3. A cnf behind a digest is signed without being shown. See DelegateTransaction.kt:359.
  4. The summary must show what AP2 enforces. This covers the JPY budget, an empty acceptable_items, checkout totals, and item ids; see the four comments on DelegateMandateText.kt. In three places AP2's schema and its SDK disagree (the budget unit, empty acceptable_items, and the quantity in #12). Please say in the KDoc and the description that you follow the SDK v0.2.0, and file those three upstream.
  5. Bring the description up to date. The counts should be 1872/98, not 1780/68. describePermission() is internal now. Disclosures work in OpenID4VP only; mdocPresentment.kt:489 refuses them. Please name the SHA the AP2 script ran on (8773304 differs from head only by @Throws lines) and say that a Multipaz verifier can't read Delegated SD-JWT yet. Unless the type and its screens land in one PR, also replace "Fixes #2010" with "Part of #2010" plus its own line, No-Issue: part of #2010, which #2196 closes. check-linked-issue fails on "Part of" alone.

Five non-blocking comments are inline.

Split before merge (blocking). Since round 1 this has grown from 681 to 1,735 source lines across 28 files. Please split it as round 2 asked:

  1. The core hooks: the 7 multipaz/ source files and their 3 tests, about 340 lines, plus the renderer guard from item 1. None of it is specific to AP2. Land it with #2186, or after #2186.
  2. DelegateTransaction, its text and its tests, together with #2196's screens and samples.

The screens moving to #2196 is the one cut round 2 asked you to avoid. Items 1–5 above then apply to the PR that holds each part.

Placement: please check with David before you split. Ask him whether the multipaz-utopia module is the right home for the AP2 type and its rule tables, and whether he's happy to have the default screens in multipaz-compose/multipaz-swiftui. Mention that the AP2-specific rules may be replaced by an official AP2 Kotlin library later. If he'd rather AP2 stayed out of this repo, for example in openwallet-foundation/multipaz-utopia, the split changes, so his answer decides where PR 2 goes.

Not verified. I built and ran nothing; the blocking items are code traces. CI stopped at a multipaz-bthci failure that main shares, before the multipaz-utopia tests.

Also noticed

  • suggestion: DelegateTransaction.kt KDoc :22-49 has no usage example. Once item 1 is done, add the one-line example. #2196's testapp/SwiftTestApp wiring belongs with this PR, or land it first.
  • question: can Swift call addTransactionType(DelegateTransaction) at all with #2178 alone? #2196's KDoc says no. Registering inside addUtopiaTypes() makes addDelegateTransactionType() unnecessary.
  • suggestion: AP2's own example request (agent_authorization.md:179) still fails on its first item, "type": "payment_card" (parseJsonTransactions throws "Unknown transaction type"). Say in the description where that will be handled.
  • suggestion: SdJwtKb.kt:177 refuses a string ending in ~, so verify(expectedType) can't be reached for a delegated response except by cutting the string apart (SdJwtTest.kt:3322). VerificationUtil.kt:1127 reports a misleading "cnf … no Key Binding JWT".
  • suggestion: TransactionData.kt:85-89 generateSdJwtResponseClaims has no main-code caller left (only DeviceResponseTest.kt:3550), and for delegate it returns digests without their disclosures. Remove it.
  • suggestion: VerificationUtil.kt:1193 reads every type under kbJwtResponseClaimName, so a flat type's verifySdJwtResponse gets {} without an error. Add one helper that honors nestSdJwtResponseClaims on both sides.
  • suggestion: DelegateMandateText.kt:543-546 formats every numeric member next to a currency as money ("max_uses 0.03 USD"). Format only min/max/amount.
  • suggestion: DelegateMandateText.kt:645-655: permissionSummary is suspend now, so show an RFC 7638 thumbprint for the agent key instead of the x excerpt, and fix the KDoc's reason.
  • suggestion: DelegateMandateText.kt:28: the wording is fixed English. Route the labels through LocalizedStrings, or expose amount, currency and instant on Limit/SummaryLine.
  • suggestion: TransactionType.kt parseJson here and in #2186 (863c95b) have already diverged (@Throws, @throws). Bring #2186 to this text, land it first, then rebase.
  • suggestion: mention in the description that verify_ap2_interop.py is the repo's first Python tool and isn't run in CI.
  • nit: DelegateMandateText.kt:550: show an empty allowed next to other members as allowed (none); an empty allow-list permits nothing.
  • nit: DelegateMandateText.kt:597/618: unknown currency codes get 2 decimals, and CLF/UYW (exponent 4) are missing.
  • nit: SdJwt.kt:725: add require(type != "kb+jwt"); the KDoc at :706-708 already says it's never right.
  • nit: lines over 120 at DelegateTransaction.kt:283, 313, 324, 360, 483, 498; DelegateMandateText.kt:487; OpenID4VP.kt:907.
  • nit: DelegateMandateText.kt:159-176 is describePermission's KDoc but sits above permissionSummary's. Move it to :189.

@TheBlackBit

Copy link
Copy Markdown
Contributor Author

Thanks again for the review, @dzuluaga. All the threads are covered.

@TheBlackBit

TheBlackBit commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

@davidz25 a quick double check before I split this PR.

The AP2 type and its rule tables live in multipaz-utopia, and the default consent screens go in multipaz-compose and multipaz-swiftui (#2196). The AP2-specific rules may be replaced later by an official AP2 Kotlin library.

The plan is two PRs: the generic hooks in multipaz (about 340 lines, none of it AP2-specific), landing with or after #2186, and then the type, its wording and the screens together. Does that placement and split still look right to you?

@davidz25

Copy link
Copy Markdown
Contributor

@davidz25 a quick double check before I split this PR.

The AP2 type and its rule tables live in multipaz-utopia, and the default consent screens go in multipaz-compose and multipaz-swiftui (#2196). The AP2-specific rules may be replaced later by an official AP2 Kotlin library.

The plan is two PRs: the generic hooks in multipaz (about 340 lines, none of it AP2-specific), landing with or after #2186, and then the type, its wording and the screens together. Does that placement and split still look right to you?

SGTM, thank you.

@TheBlackBit
TheBlackBit force-pushed the feat/ap2-delegate-transaction-utopia branch 2 times, most recently from 9590d2d to b5cee92 Compare November 20, 2026 21:55
Ever Morales added 3 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>

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.

3 participants