Skip to content
6 changes: 6 additions & 0 deletions docs/guides/testing-on-device.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,12 @@ Digital Credentials API needs it), the demo credentials + trust lists from
**[Trusted demo credentials](trusted-demo-credentials.md)**, and a phone on USB with
`adb devices` showing it authorized.

> **Signing a spending grant?** That uses a different card than the sections below: the
> SD-JWT "Payment card" from the official issuer, and a Multipaz Wallet development build (no
> released wallet signs a grant yet). Follow the three steps in the
> [gate README, "Device-signed grants"](../../packages/credentagent-gate/README.md#device-signed-grants--the-wallet-signs-the-grant-first-spec-012).
> The `.mpzpass` import below is for the age, loyalty and checkout ceremonies.

## 1. Import trust first (VICAL + RICAL)

Do this **before** importing credentials, so cards land already-trusted.
Expand Down
8 changes: 5 additions & 3 deletions examples/quickstart/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,13 +108,15 @@ trust anchor yet** — a self-crafted credential would pass. This quickstart dem
*flow*; do not present the age gate as a real safety control until issuer-verified trust
lands ([roadmap](../../ROADMAP.md)).

**Spending grants need a wallet no store ships yet.** Since 0.6.0, approving a grant on the phone
**Spending grants need a wallet development build.** Since 0.6.0, approving a grant on the phone
(`signing: "device"`, the default) asks the wallet for an SD-JWT payment credential (`vct`
`urn:emvco:dpc:card:1` or `com.emvco.dpc`) and AP2's `delegate` request, which **no released wallet
supports yet**. A wallet set up for 0.5.0's mdoc `org.multipaz.payment.sca.1` can't sign one. So on
this quickstart and on the hosted demo (`credentagent.ai/marketplace`), `create-spending-grant`
returns an approve page, but phone approval only completes with a wallet holding a demo DPC
credential (`node tools/demo-pki/mint/mint-dpc-sdjwt.mjs --mpzpass` from the repo root mints one).
returns an approve page, but phone approval only completes with a Multipaz Wallet development
build (from [multipaz-wallet#48](https://github.com/openwallet-foundation/multipaz-wallet/pull/48)) holding
the SD-JWT "Payment card" from the official issuer. The steps are in the
[gate README](../../packages/credentagent-gate/README.md#device-signed-grants--the-wallet-signs-the-grant-first-spec-012).
To demo a grant without a wallet, pass `signing: "page"` to `create-spending-grant`: the human
approves with a click on the page instead of a wallet signature. Checkout, the age gate and the
loyalty discount are unaffected. In tests, use `devSimulateWalletSignature`.
Expand Down
5 changes: 3 additions & 2 deletions examples/quickstart/server.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -81,8 +81,9 @@ const store = createStorefront({
baseUrl: deployedOrigin, // local stays unset → checkout links derive from each request's origin
// Grant records + the delegated ledger live in THIS process's memory: on a multi-instance
// deploy a grant made on one instance is invisible to its siblings. Fine for this demo;
// the durable, cross-instance grant store is issue #152. Approving a grant on a phone needs an
// SD-JWT payment credential that no released wallet signs yet (0.6.0; README "Honest status").
// the durable, cross-instance grant store is issue #152. Approving a grant on a phone needs the
// official SD-JWT Payment card and a Multipaz Wallet development build (no released wallet signs
// yet; gate README, "Device-signed grants").
grants: credentagent.grants, // human-NOT-present: adds create/get/spend/revoke grant tools
merchant: "Utopia", // the merchant a created grant is sealed + audited as
});
Expand Down
36 changes: 27 additions & 9 deletions packages/credentagent-gate/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -895,15 +895,33 @@ is the fast-follow, and the gate **relays** that level verbatim with the attesto
Test the whole flow **with no phone** using the exported simulated wallet — see
[`examples/device-signed-grants.mjs`](https://github.com/openmobilehub/credentagent/blob/main/examples/device-signed-grants.mjs)
(`devSimulateWalletSignature` produces a real device signature the way Stripe's test cards stand in
for a real card). **That is the way to test today.** Signing on a real phone needs a wallet that
supports AP2's `delegate` request, and **no released wallet does yet**: the Multipaz change
([openwallet-foundation/multipaz#2011](https://github.com/openwallet-foundation/multipaz/pull/2011))
was closed without merging, and a released Multipaz wallet rejects the request. With a patched
wallet build, the grant asks for an **SD-JWT** payment credential (`vct` `urn:emvco:dpc:card:1` or
`com.emvco.dpc`); from a clone of this repo, mint one with
[`node tools/demo-pki/mint/mint-dpc-sdjwt.mjs --mpzpass`](https://github.com/openmobilehub/credentagent/blob/main/tools/demo-pki/mint/mint-dpc-sdjwt.mjs),
which writes `tools/demo-pki/keys/dpc.mpzpass` to import into that build. The mdoc
`payment.mpzpass` from the demo set no longer matches.
for a real card). **That is the way to test in CI.**

**Sign a grant on your phone, in three steps:**

1. Install a Multipaz Wallet **development build** that supports AP2's `delegate` request: the
wallet from [multipaz-wallet#48](https://github.com/openwallet-foundation/multipaz-wallet/pull/48),
built on [multipaz#2178](https://github.com/openwallet-foundation/multipaz/pull/2178) (both
still open). **No released wallet signs a grant yet**; a released one rejects the request.
Once a release includes those changes, install the release instead.
2. In the wallet, add the **Payment card** from the official issuer at
[`issuer.multipaz.org`](https://issuer.multipaz.org/issuer/?config_id=payment_sca_sd_jwt)
(credential configuration `payment_sca_sd_jwt`). The issuer lists **two** cards both named
"Payment card"; the grant needs the **SD-JWT** one, because AP2's `delegate` request exists only
for SD-JWT. The mdoc one (`payment_sca_mdoc`) won't match, and the phone says "Your info wasn't found".
3. Open the approve link, press "Sign with your wallet", scan the QR code, and approve.
Comment thread
TheBlackBit marked this conversation as resolved.
Resolved

The grant asks for an SD-JWT payment credential (`vct` `urn:emvco:dpc:card:1` or `com.emvco.dpc`)
that discloses `credential_id` (the official card) or `payment_instrument_id` (the repo's test
card, below). This was run on an Android phone against the hosted dev store and ended with the
grant `authorized` ([issue #466](https://github.com/openmobilehub/credentagent/issues/466)). The
wallet shows the requester as unknown, because the server does not sign its request with a verifier
identity. The gate does **not** check who issued the card, so a grant it verifies stays
Comment thread
TheBlackBit marked this conversation as resolved.
Resolved
`device-signed`, not `issuer-verified`.

The repo's own test card, `node tools/demo-pki/mint/mint-dpc-sdjwt.mjs --mpzpass`, is a **test
fixture** for this repo's tests, not the way to try the product. It has not been tried on a phone
with the current request.
Comment thread
TheBlackBit marked this conversation as resolved.
Resolved

### Credentials on a grant — presented before you authorize, or not at all

Expand Down
9 changes: 6 additions & 3 deletions tools/demo-pki/mint/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,10 @@ that is the device step (#51).

## The SD-JWT payment credential (`mint-dpc-sdjwt.mjs`)

> **A test fixture for this repo's own tests, not the way to try the product.** To sign a
> spending grant on a phone, add the Payment card the official Multipaz issuer offers (see the
> gate README, "Device-signed grants"). Nothing here is issued by Multipaz or checked against it.

Everything above mints **ISO mdoc** credentials. `mint-dpc-sdjwt.mjs` mints the payment
credential in the **other** format — an SD-JWT VC (`dc+sd-jwt`) — because AP2's delegation
mechanism is specified for SD-JWT only. Its chain serialization is SD-JWT syntax, and mdoc
Expand Down Expand Up @@ -138,6 +142,5 @@ name is refused. That last one is verified load-bearing — deleting the key-bin
fails it. Run it with the **root** `npm test` (this file is outside both workspaces, #184).

**Unverified:** whether the installed Multipaz app can *provision* an SD-JWT credential as
easily as it imports an mdoc `.mpzpass`. The Multipaz library supports SD-JWT VC
presentation (spec 012 `research.md`); the app's import path has not been checked. That is
the first thing to establish on the device.
easily as it imports an mdoc `.mpzpass`, and whether this card matches the grant request as it
is today. A grant was signed on a phone with the official issuer's card, not with this one.
Loading