Native wallets

[BigBlueHat]

Continuing from #25, but now with wallet docs split in two pages and based on latest 11ty code.

TODO:

We should be clear that there are two ways to receive requests from CHAPI, one is via CHAPI events and the other via URLs (which can be deep / "app" links). Your credential handler registers to work with just one of these mechanisms, not both. https://github.com/credential-handler/chapi.io/pull/25#pullrequestreview-1587821284

[BigBlueHat]

@brianorwhatever feel free to fork and work from this branch as/if/when needed.

[BigBlueHat]

@dlongley per your earlier comment...

We should be clear that there are two ways to receive requests from CHAPI, one is via CHAPI events and the other via URLs (which can be deep / "app" links). Your credential handler registers to work with just one of these mechanisms, not both. https://github.com/credential-handler/chapi.io/pull/25#pullrequestreview-1587821284

This is what's stated via acceptedInput in the manifest.json, correct? And is it true that Web Wallets always use the eventing mechanism, but Native Wallets may use either?

We also currently have this text in the native wallets content:

The acceptedInput property is what tells CHAPI that the wallet receives data through URL and query parameters rather than events like a web wallet does.

[dlongley]

@BigBlueHat,

@dlongley per your earlier comment...

We should be clear that there are two ways to receive requests from CHAPI, one is via CHAPI events and the other via URLs (which can be deep / "app" links). Your credential handler registers to work with just one of these mechanisms, not both. #25 (review)

This is what's stated via acceptedInput in the manifest.json, correct?

Yes, the default for acceptedInput is event and the other option is url. Credential handlers can receive a CHAPI request via an event or via a url.

And is it true that Web Wallets always use the eventing mechanism, but Native Wallets may use either?

No, the reverse. Web Wallets can use either, but Native Wallets always use the URL mechanism. Notably, a Native Wallet that is also a cloud wallet or "Web-based" could also use either, perhaps opting to use the event mechanism because they want to keep the user in their Web browser when handling CHAPI requests. I would expect this to be a better UX for Native Wallets that are "packaged Web apps".

We also currently have this text in the native wallets content:

The acceptedInput property is what tells CHAPI that the wallet receives data through URL and query parameters rather than events like a web wallet does.

Perhaps tweak this: "like most web wallets do"?

[BigBlueHat]

@dlongley is there a narrow enum set for these values?

    "acceptedProtocols": [
      "OID4VCI",
      "OID4VP",
      "vcapi"
    ]

i.e. how do folks know what's possible there? And what effect does it have practically?

[BigBlueHat]

@dlongley @brianorwhatever

When the application lands on the page specified in the url property of the credential_handler in the manifest.json file...

What are the scenarios under which this happens?

[dlongley]

@BigBlueHat,

@dlongley is there a narrow enum set for these values?

    "acceptedProtocols": [
      "OID4VCI",
      "OID4VP",
      "vcapi"
    ]

i.e. how do folks know what's possible there? And what effect does it have practically?

Right now, those are the only three that have seen any use. However, it's fully extensible such that people could create and use whatever protocols they want -- and potentially create conflicts too. THIS IS TEH WEB :)

[dlongley]

@BigBlueHat,

@dlongley @brianorwhatever

When the application lands on the page specified in the url property of the credential_handler in the manifest.json file...

What are the scenarios under which this happens?

When the user selects a credential handler (wallet) that has indicated it accepts requests via URL (credential_handler.acceptedInput: 'url'), the CHAPI mediator will open a popup to the URL specified in the credential_handler.url property. If that URL has been registered as a deep or app link, no window is expected to be opened, but instead, the mobile OS will open the user's native app that is registered to handle that link. If no deep or app link is registered for that URL, then a new window will be opened in the user's browser to the URL. The URL will include a request parameter with a URI-encoded JSON.stringified() request object as its value. The request object will include credentialRequestOrigin and protocols.

Note: If the credential handler indicated it accepts requests via events (credential_handler.acceptedInput: 'event' or default of omitted credential_handler.acceptedInput) then when the user selects the credential handler, a window (iframe or popup depending on the browser) will be opened to the credential handler URL -- and a Web event (via postMessage) will be sent to the page with the CHAPI request in it.

[BigBlueHat]

@dlongley that was a great write-up about acceptInput. I think the most recent two commits hopefully explain that well for the url option. I'll try to cover them both on the Web Wallet side soon (when I rework that text).

For now, this is ready for review! 🕺

[BigBlueHat]

@brianorwhatever I know you saw most of this when we reviewed it earlier, but if you wouldn't mind giving it another go through, that'd be super. Thanks!

[BigBlueHat]

@dlongley @brianorwhatever I've brought in those changes and fixed the URLs/JSON examples. I'm merging this as is, and we can handle further feedback in issues.

Thanks! 🎩