Support Multiple Wallets via $HealthWallet

[madaster97]

Support Multiple Wallets (Multi-Device and Multi-App)

I think EHR-Issuers and their Patients will want to support multiple wallets per Patient, just having multiple DIDs linked to an account.

To support this, the EHR will need to know which Holder a VC is being issued for, since this will determine what DID document/JWE encryption key is used by the issuer.

This is easy enough to support for download of fhir-backed-vc files, since the issuer portal can just ask the patient which wallet the file is destined for. The portal could also try and be smart about this, where it can sense what device the user is logged in with and only show wallets that it knows came from that device (maybe registering an IP address for the device during the SIOP flow).

For supporting this with $HealthWallet resources, the best answer would be to include a holderDid parameter in the POST /Patient/:id/$HealthWallet.issueVc API call.

Here's an example payload:

{
    "resourceType": "Parameters",
    "parameter": [{
        "name": "credentialType",
        "valueUri": "https://healthwallet.cards#covid19"
    },
    {
        "name": "holderDid",
        "valueUri": "did:ion:<<identifer for holder>>"
    }]
}

Note this also covers the niche scenario of a patient having the same wallet installed on multiple devices. Those wallets will have the same client_id, BUT have separate DIDs (unless they're sharing private keys, but that seems out-of-scope). Without this parameter, EHRs wouldn't be able to recognize the difference between these two wallets issuing a $HealthWallet.issueVc call.

Originally posted by @madaster97 in #21 (comment)

[madaster97]

Also, the presentationContext parameter is said to be required, but isn't in the example requests.

See the $HealthWallet.issueVc operation definition:

The credentialType and presentationContext parameters are both required. By default, the issuer will decide which identity claims to include based on the requested presentationContext.

I'm planning to edit this section in a PR anyway to address the above issue, so I can work on this as well. Is there an example I can use (with maybe more explanation) OR is this not actually a defined field?

[madaster97]

Making a note here on how I think we should define a wallet.

Defining a "Wallet"

To clear up terminology, let's define a "Wallet" as an entity on a device that has private keys (and therefore a unique Long-Form DID).

This definition covers the following use cases:

1. User has the same app installed on several devices - Reasonably expect each app to have separate private keys (if they are stored locally, otherwise that's out of scope). Note this relies on including the wallet's DID in a $HealthWallet.connect call, since havnig the same client_id (same app) makes it ambiguous which wallet is which (given assumptions below on only calling connect ONCE). See issue Support Multiple Wallets via $HealthWallet #34 I reference/created above
2. User has multiple apps installed on the same device - Definitely have separate private keys, since they are separate apps

The expectation should be that patients/users can have multiple wallets connected to the same issuer/lab account. There isn't anything in the spec that explicitly prohibits that.

Note on Sharing Wallets

Note a user might have multiple lab accounts (Read: Shares their phone/wallet with another person), and connect them all to the same "Wallet". Issuers should handle having the same DID attached to multiple distinct users (note multiple users doesn't 100% correspond to multiple fhirUser resource representations, since multiple RelatedPerson users could be the same user in the Issuer's system).

Note on Linking Individual Patients

For the workflow of user/patient being different, issuers will need to be prepared to support some sort of granular user-wallet-patient scoping (note the order there). Here's how that might look:

1. A given user may have generic access to 2 patients (maybe including themselves), Patients A and B
2. The user conducts a SMART on FHIR launch with their wallet, and logs in with Patient A in context (launch/patient scope)
3. The wallet calls the $HealthWallet.connect operation behind Patient A's Patient/:id path
4. The issuer (if it verifies the request) does the following:
   • Links that wallet generically to the logged in user's account
   • Specifically links that wallet only to Patient A, which would give this wallet authorization to receive VCs for Patient A
5. Later on the user launches the same wallet from the context of Patient B
6. The wallet attempts to call $HealthWallet.issueVc without calling connect
7. In response, the request should fail, most appropriately with the no-did-bound error code
8. In a correct workflow, the wallet would call $HealthWallet.connect operation behind Patient B's Patient/:id path, and the issuer may potentially have special handling to say "Hey I know this DID for this user, let's just edit the existing permissions for that DID instead of making a brand new link."

[jmandel]

I'm planning to edit this section in a PR anyway to address the above issue, so I can work on this as well. Is there an example I can use (with maybe more explanation) OR is this not actually a defined field?

presentationContext is something we've stripped away for now. (The idea was to define different contexts with different minimum data sets required -- and I think eventually we might want to do this, but to start, it's better to focus on "store a health card, share a health card".) If it's still mentioned in the spec, it's an error.

[jmandel]

"Hey I know this DID for this user, let's just edit the existing permissions for that DID instead of making a brand new link."

I'm not sure what this implies; how is the process or outcome for "edit[ing] the existing permissions" different than "making a brand-new link"?

[jmandel]

As noted at #21 (comment), I'm happy with these changes as long as we make it clear that it's OK for issuers to only support a single link for each Patient ID, clearing out previous links when connect is called on a given Patient ID.

[jmandel]

Wallet binding is no longer part of the spec since #64 .