From 8a0c568ad1b772e959678dc4dd4399e6c164dcdb Mon Sep 17 00:00:00 2001 From: Dmitri Zagidulin Date: Mon, 1 Sep 2025 16:01:32 -0400 Subject: [PATCH 1/5] Add a Wallet Integration / Getting VCs into wallet section. Signed-off-by: Dmitri Zagidulin --- wallet/README.md | 63 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 wallet/README.md diff --git a/wallet/README.md b/wallet/README.md new file mode 100644 index 0000000..0c5adae --- /dev/null +++ b/wallet/README.md @@ -0,0 +1,63 @@ +# Wallet Integration Guide + +## Table of Contents + +* [Getting credentials into the wallet](#getting-credentials-into-the-wallet) + +## Getting credentials into the wallet + +### Opening a Deep Link / Universal App Link (From Outside) + +Deep links are useful because they allow users to interact with the wallet +from the outside (while they're not in the wallet app itself), but instead +are clicking on a link in a mobile web browser, opening a link pasted to them +in a chat app, or scanning a URL QR code with the general mobile camera. + +### Pasting a Deep Link (While In Wallet) + +Same as above; you should be able to paste a deep link into the 'Add Credential' +screen textbox, or scan a QR code containing a deep link _while inside the +wallet app_. + +### Pasting Raw VC or VP JSON Into Wallet Textbox + +On the 'Add Credential' screen, you can paste the full JSON representation +of a VC that you've copied into your clipboard (such as from a website with VC +examples). + +### Scanning Raw VC/VP JSON QR Code (While In Wallet) + +(Same as previous item) +While inside the wallet, you can use the 'Scan QR Code' button on the 'Add +Credential' screen to read a QR code that contains (as text) the raw JSON +of a VC or a VP. + +### Pasting a URL to a Statically Hosted VC/VP + +If a VC or VP is hosted on some website (like github pages or Google Drive), +you can just copy and paste the URL to it into the textbox on the 'Add Credential' +screen. + +NOTE: May need the require the use of a CORS proxy (double check on this). + +### Scanning a URL to a Statically Hosted VC/VP (While In Wallet) + +Same as above, but instead of copying and pasting, you can use the 'Scan QR Code' +button from inside the wallet, and it will fetch and store the VC on the other +end. (Same deal, re CORS proxy) + +### Upload VC from File + +You can also add a VC you have stored as a file by going to 'Add Credential' +screen and clicking on 'Add from file' button. +Note that this includes both files stored locally on the device, but also +many mobile OSs also add other file storage services (like Google Drive, Dropbox, +etc) to this screen. + +### Restore VCs from Backup + +If you have a previous wallet backup (from the Settings > Backup Wallet screen), +if you go to Settings > Restore wallet, any VCs from that backup (that don't +already exist in your wallet) are also added. + + From f133362f7c233b949790ea6533eeae6e9682bb66 Mon Sep 17 00:00:00 2001 From: Dmitri Zagidulin Date: Mon, 1 Sep 2025 16:08:53 -0400 Subject: [PATCH 2/5] Add section on Share Intent. Signed-off-by: Dmitri Zagidulin --- wallet/README.md | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/wallet/README.md b/wallet/README.md index 0c5adae..088737d 100644 --- a/wallet/README.md +++ b/wallet/README.md @@ -2,9 +2,9 @@ ## Table of Contents -* [Getting credentials into the wallet](#getting-credentials-into-the-wallet) +* [Getting Credentials Into the Wallet](#getting-credentials-into-the-wallet) -## Getting credentials into the wallet +## Getting Credentials Into the Wallet ### Opening a Deep Link / Universal App Link (From Outside) @@ -19,6 +19,10 @@ Same as above; you should be able to paste a deep link into the 'Add Credential' screen textbox, or scan a QR code containing a deep link _while inside the wallet app_. +### Scanning an Interaction URL (While In Wallet) + +Not currently supported, see issue https://github.com/openwallet-foundation-labs/learner-credential-wallet/issues/764 + ### Pasting Raw VC or VP JSON Into Wallet Textbox On the 'Add Credential' screen, you can paste the full JSON representation @@ -60,4 +64,15 @@ If you have a previous wallet backup (from the Settings > Backup Wallet screen), if you go to Settings > Restore wallet, any VCs from that backup (that don't already exist in your wallet) are also added. +### Receive a Share Intent from Another App + +NOTE: We used to support this in previous LCW versions, but it was disabled +due to extra complexity, and no apps were sharing VCs at the time. + +for iOS, see: +* ShareKit and App Extensions https://developer.apple.com/library/archive/documentation/General/Conceptual/ExtensibilityPG/index.html +* App Intents https://developer.apple.com/documentation/appintents/ + +for Android, see: +* Sharesheet docs https://developer.android.com/training/sharing/send From c2cc2804e1e913342dd0c4013c7fefb81fd37cb5 Mon Sep 17 00:00:00 2001 From: Dmitri Zagidulin Date: Mon, 1 Sep 2025 16:35:44 -0400 Subject: [PATCH 3/5] Add dev notes. Signed-off-by: Dmitri Zagidulin --- wallet/README.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/wallet/README.md b/wallet/README.md index 088737d..eb7c9d2 100644 --- a/wallet/README.md +++ b/wallet/README.md @@ -19,16 +19,25 @@ Same as above; you should be able to paste a deep link into the 'Add Credential' screen textbox, or scan a QR code containing a deep link _while inside the wallet app_. +**Dev note:** See `/app/screens/AddScreen/AddScreen.tsx > addCredentialsFrom()` +for how deep links are handled. + ### Scanning an Interaction URL (While In Wallet) Not currently supported, see issue https://github.com/openwallet-foundation-labs/learner-credential-wallet/issues/764 +**Dev note:** Support for this would have to be added to +`/app/screens/AddScreen/AddScreen.tsx > onReadQRCode()` + ### Pasting Raw VC or VP JSON Into Wallet Textbox On the 'Add Credential' screen, you can paste the full JSON representation of a VC that you've copied into your clipboard (such as from a website with VC examples). +**Dev note:** See `/app/screens/AddScreen/AddScreen.tsx > addCredentialsFrom()` +for how deep links are handled. + ### Scanning Raw VC/VP JSON QR Code (While In Wallet) (Same as previous item) @@ -36,13 +45,19 @@ While inside the wallet, you can use the 'Scan QR Code' button on the 'Add Credential' screen to read a QR code that contains (as text) the raw JSON of a VC or a VP. +**Dev note:** See `/app/screens/AddScreen/AddScreen.tsx > onReadQRCode()` +which calls `/app/lib/decode.ts > credentialsFrom` + ### Pasting a URL to a Statically Hosted VC/VP If a VC or VP is hosted on some website (like github pages or Google Drive), you can just copy and paste the URL to it into the textbox on the 'Add Credential' screen. -NOTE: May need the require the use of a CORS proxy (double check on this). +**Dev note:** See `/app/screens/AddScreen/AddScreen.tsx > addCredentialsFrom()` +which calls `/app/lib/decode.ts > credentialsFrom` + +TODO: Add the ability to fetch URLs through a CORS proxy. ### Scanning a URL to a Statically Hosted VC/VP (While In Wallet) @@ -50,6 +65,12 @@ Same as above, but instead of copying and pasting, you can use the 'Scan QR Code button from inside the wallet, and it will fetch and store the VC on the other end. (Same deal, re CORS proxy) +**Dev note:** See `/app/screens/AddScreen/AddScreen.tsx > onReadQRCode()` +which calls `/app/lib/decode.ts > credentialsFrom` + +TODO: This does mean that scanning a deep link (while inside the wallet) +is not currently supported. + ### Upload VC from File You can also add a VC you have stored as a file by going to 'Add Credential' @@ -58,6 +79,9 @@ Note that this includes both files stored locally on the device, but also many mobile OSs also add other file storage services (like Google Drive, Dropbox, etc) to this screen. +**Dev note:** See `/app/screens/AddScreen/AddScreen.tsx > addFromFile()` +for more details. + ### Restore VCs from Backup If you have a previous wallet backup (from the Settings > Backup Wallet screen), From 795200de0c4e2fe5fb1871a131bd209b8017fba5 Mon Sep 17 00:00:00 2001 From: Dmitri Zagidulin Date: Wed, 3 Sep 2025 13:19:19 -0400 Subject: [PATCH 4/5] Update, add code samples. Signed-off-by: Dmitri Zagidulin --- wallet/README.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/wallet/README.md b/wallet/README.md index eb7c9d2..a6dd1f2 100644 --- a/wallet/README.md +++ b/wallet/README.md @@ -13,6 +13,19 @@ from the outside (while they're not in the wallet app itself), but instead are clicking on a link in a mobile web browser, opening a link pasted to them in a chat app, or scanning a URL QR code with the general mobile camera. +**Dev note:** +The custom protocols for deep links as well as universal app links are configured +in `app.conf.js`: + +* in the `LinkConfig.schemes` constant +* but also in `expo.ios.associatedDomains` and `CFBundleURLSchemes` +* also in `expo.android.intentFilters` + +see https://docs.expo.dev/linking/into-your-app/ +and https://docs.expo.dev/linking/overview/#universal-linking + +The actual link router is set up in `/app/lib/deepLink.ts > deepLinkConfigFor()` + ### Pasting a Deep Link (While In Wallet) Same as above; you should be able to paste a deep link into the 'Add Credential' @@ -100,3 +113,24 @@ for iOS, see: for Android, see: * Sharesheet docs https://developer.android.com/training/sharing/send +## Example Requests + +### Request a VC + +``` +https://lcw.app/request?request=%7B%22credentialRequestOrigin%22:%22https://interop-alliance.github.io/wallet-to-webapp-demo%22,%22protocols%22:%7B%22vcapi%22:%22https://verifierplus.org/api/exchanges/42cb7245-a732-409f-8182-1db416a793f7%22%7D%7D +``` + +```json +{ + "credentialRequestOrigin": "https://interop-alliance.github.io/wallet-to-webapp-demo", + "protocols": { + "vcapi": "https://verifierplus.org/api/exchanges/42cb7245-a732-409f-8182-1db416a793f7" + } +} +``` + +leads to: Exchange Credentials Request popup. +"An organization would like to exchange credentials with you." + +Select credentials, wallet POSTS a VP to the interact endpoint. From a1bd1c5868b7e38286f61ddfe5b193aac75dd8b0 Mon Sep 17 00:00:00 2001 From: Dmitri Zagidulin Date: Wed, 24 Sep 2025 15:00:38 -0400 Subject: [PATCH 5/5] Add a Testing section. Signed-off-by: Dmitri Zagidulin --- wallet/README.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/wallet/README.md b/wallet/README.md index a6dd1f2..978dd63 100644 --- a/wallet/README.md +++ b/wallet/README.md @@ -134,3 +134,38 @@ leads to: Exchange Credentials Request popup. "An organization would like to exchange credentials with you." Select credentials, wallet POSTS a VP to the interact endpoint. + +## Testing + +### 1) Test Legacy Credential Request flow (DCC Admin Dashboard Issuing) + +Make sure the [Legacy Credential Request flow](https://github.com/digitalcredentials/docs/blob/main/request/credential_request.md), +that is, picking up credentials via the DCC issuer's Admin Dashboard is working. + +https://badging.dcconsortium.org/lcw-experience-badge + +Example legacy deep link: + +``` +https://lcw.app/request.html?issuer=issuer.example.com&auth_type=bearer&challenge=7f4a278e...&vc_request_url=https://issuer.dcconsortium.org/exchange/7bad4b... +``` + +Test in both modes (they result in slightly different code paths in the app): + +* "cold start" - LCW is closed (not running in the background), and you click on + the 'Add to LCW' button on the pickup page or scan the QR code. +* "warm start" - same as above, but LCW is running in the background + +### 2) Test Legacy Credential Request Link by pasting it into 'Add Credential' Textbox + +Similar to the previous item, but you're going to paste the legacy deep link +directly into the 'Add Credential' screen's text box. +To get the link - go to the LCW Experience Badge pickup page (from your email), +click on the 'Add to LCW' button, and then copy the redirected request, +looks like this: + +``` +dccrequest://request?issuer=issuer.example.com&auth_type=bearer&challenge=7f4a278e...&vc_request_url=https://issuer.dcconsortium.org/exchange/7bad4bee... +``` +Open the app manually, and paste that URL into the 'Add Credential' screen textbox. +