Skip to content
8 changes: 7 additions & 1 deletion 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 Expand Up @@ -94,7 +100,7 @@ warnings** appear — issuer (via the imported **VICAL**) *and* verifier (via th
| Symptom | Cause / fix |
| :-- | :-- |
| "Import pass from file" greys the file out | Expected (SAF MIME filter). Use the open-intent (step 2) or a hosted link. Don't fight the button. |
| "Your info wasn't found" at presentation | The requested credential isn't in *this* wallet (wrong device, or not imported). Re-check step 2 on the presenting device. |
| "Your info wasn't found" at presentation | The requested credential isn't in *this* wallet (wrong device, or not imported). Re-check step 2 on the presenting device. For a **spending grant** it also means the wrong card: the issuer lists two "Payment card" entries, and only the SD-JWT one matches (gate README, "Device-signed grants"). |
| Red "untrusted issuer" warning **when sideloading a card** | The VICAL isn't imported, or the wallet doesn't trust the signer. Import the VICAL (step 1), then re-open the pass. NOTE: this is a *wallet-hold* check at import — the **gate does not verify the issuer yet** (`presence-only-demo`; issuer/device verification is [#14](https://github.com/openmobilehub/credentagent/issues/14)). Removing the VICAL *after* a card is imported does **not** re-flag the held card, and no gate ceremony consults the VICAL today. |
| Red "unknown website / unknown verifier" **even though a RICAL is already imported** | **Stale RICAL** — the device holds an *older* `utopia.rical` (from a prior `gen-pki` run) whose reader cert no longer matches what the gate presents. **Re-import the current `utopia.rical`** (Settings → Trusted verifiers → Import RICAL). Trust shows immediately: presentment reads *"The website requesting this data is trusted"* and names the reader. Note: `verify-reader-trust.mjs` validates the **repo's** `out/utopia.rical` and can't see a stale device copy, so a green tool run + red on-device warning ⇒ suspect the device import first. |
| "Unknown verifier" warning (no RICAL imported) | Import the RICAL (step 1) so the gate's reader identity (#84) matches. |
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
53 changes: 41 additions & 12 deletions packages/credentagent-gate/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -628,8 +628,8 @@ Honesty is carried in the **types**, not prose (Principle VII):
signing: "device" })`, below). Here the gate **does** verify the wallet's signature over the
grant's exact bounds — an SD-JWT VC Key Binding JWT carrying the AP2 Mandate Content, checked
against the key the credential names in `cnf`, with every revealed claim checked against the
issuer-signed `_sd` digests — a real holder-of-key binding, one step past presence-only. What is still demo is only the trust **anchor**: the payment credential is a
self-minted demo credential with no issuer/VICAL check (that is the roadmap `issuer-verified`
issuer-signed `_sd` digests — a real holder-of-key binding, one step past presence-only. What is still demo is only the trust **anchor**: the gate does not
check who issued the payment credential (no issuer/VICAL check; that is the roadmap `issuer-verified`
line, issue #14), so a self-crafted device key would still pass. The signature is real; the
anchor is not — the page and the type both say exactly that, and the gate never claims
`issuer-verified` for the in-gate check.
Expand Down Expand Up @@ -885,7 +885,7 @@ that was never device-signed can never spend; a spend always traces to the exact
**real** — the gate verifies the holder's Key Binding JWT against the key the credential names in
`cnf`, checks the `sd_hash` that binds it to the disclosures presented, and rebuilds the Mandate
Content from its own grant record to require the wallet signed those exact terms. What is **still
demo** is the trust **anchor**: the payment credential is self-minted with **no issuer check** (that
demo** is the trust **anchor**: the gate does **not** check who issued the payment credential (that
hardening is issue #14), so a self-crafted credential would pass. The
verify runs through a **seam** — the in-gate backend attests `device-signed` / `verifiedBy: "gate"`;
wiring an external verifier (the `DelegatedVerifier` seam) that reports a stronger, issuer-backed level
Expand All @@ -895,15 +895,44 @@ 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. It comes
from pull requests that are still open ([multipaz-wallet#48](https://github.com/openwallet-foundation/multipaz-wallet/pull/48),
[multipaz#2178](https://github.com/openwallet-foundation/multipaz/pull/2178) and
[multipaz#2196](https://github.com/openwallet-foundation/multipaz/pull/2196)), so there is no
release yet. Download the [debug APK](https://drive.google.com/file/d/13NRT4uTDY4DZT6NMYmq-x2ABMY9eOR5j/view?usp=share_link)
Comment thread
TheBlackBit marked this conversation as resolved.
Resolved
that signed the grant in [issue #466](https://github.com/openmobilehub/credentagent/issues/466)
(a debug build that reports the version `2026.W46.0-pr-48-176-git-55db8c2-dirty`, SHA-256
`fc36639981b13b74ececdc156253811f516f365c45dd7467270c7c3e1d9bcc8d`: check it before you install, with `shasum -a 256 <file>` on macOS, `sha256sum <file>` on Linux or
`certutil -hashfile <file> SHA256` on Windows). It is an earlier version of multipaz-wallet#48 plus one fix, built from the branch
[`build/466-recorded-wallet`](https://github.com/TheBlackBit/multipaz-wallet/tree/build/466-recorded-wallet).
**No released wallet signs a grant yet**; a released one rejects the request. When a release
includes those changes, this link is replaced by it (tracked in issue #472).
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" (seen
on a phone, [issue #466](https://github.com/openmobilehub/credentagent/issues/466)). Nor will the
repo's mdoc `payment.mpzpass`: the request is SD-JWT only.
3. Open the approve link and press "Sign with your wallet". On a computer, scan the QR code with the
phone. Then approve in the wallet.

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: unless the host passes a `readerIdentity`, the server signs
its request with a self-signed certificate that no reader trust list (RICAL) in the wallet lists (see
[Presenting a stable reader identity](#presenting-a-stable-reader-identity-optional)). 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