search

digitalcredentials / transaction-service

VC-API Exchange Transaction Manager Service
MIT License
1 stars 1 forks source link

readme

Transaction Manager Service (@digitalcredentials/transaction-manager-service)

Build status

Express app for managing the transactions used in VC-API exchanges.

IMPORTANT NOTE ABOUT VERSIONING: If you are using a Docker Hub image of this repository, make sure you are reading the version of this README that corresponds to your Docker Hub version. If, for example, you are using the image digitalcredentials/transaction-service:0.1.0 then you'll want to use the corresponding tagged repo: https://github.com/digitalcredentials/transaction-service/tree/v0.1.0. If you are new here, then just read on...

Table of Contents

Overview

This is an express app that:

Use as you like, but this is primarily intended to be used to with the DCC Exchange Coordinator to manage the challenges in the Wallet/Issuer DIDAuth exchange.

Especially meant to be used as a service within a Docker compose network, initialized by the coordinator from within the Docker compose network, and then called externally by a wallet like the Leaner Credential Wallet. To that end, a Docker image for this app is published to DockerHub to make it easier to wire this into a Docker compose network.

API

Implements three endpoints:

Initializes the exchange for an array of Verifiable Credentials. Expects an object containing the data that will later be used to issue the credentials, like so:

 {
    exchangeHost: "hostname to use when constructing the exchange endpoints",
    tenantName: "the tenant with which to later sign the credentials",
    data: [
       {
          vc: "an unsigned populated Verifiable Credential",
          retrievalId: "an ID to later use to select the generated VPR/deeplink for this credential"
       },
       {
          vc: "another unsigned populated Verifiable Credential",
          retrievalId: "another ID to later use to select the generated VPR/deeplink for this credential"
       },
        ... however many other credentials to setup an exchange for
    ]
 }

The endpoint stores the data in a key/value store along with newly generated UUIDs for the exchangeId, transactionId and a challenge to be used later for a DIDAuthentication Verifiable Presentation Request.

The endpoint returns an object with two options for opening a wallet: a custom deeplink that will open the Learner Credential Wallet and a [CHAPI}(https://chapi.io) request that can be used to open a [CHAPI}(https://chapi.io) enabled wallet. In both cases the deeplink or chapi request will prompt the wallet to submit a DID Authenticaion to the exchange endpoint, which will return the signed credential.

The object will look something like so:

[
    {
        "retrievalId": "someId",
        "directDeepLink": "https://lcw.app/request.html?issuer=issuer.example.com&auth_type=bearer&challenge=27485032-e0bc-4d74-bb5a-bb778cd7f8e3&vc_request_url=http://localhost:4005/exchange/993cce5e-58a8-41ce-a055-bef4a8253379/27485032-e0bc-4d74-bb5a-bb778cd7f8e3",
        "vprDeepLink": "https://lcw.app/request.html?issuer=issuer.example.com&auth_type=bearer&vc_request_url=http://localhost:4005/exchange/993cce5e-58a8-41ce-a055-bef4a8253379",
        "chapiVPR": {
            "query": {
                "type": "DIDAuthentication"
            },
            "interact": {
                "service": [
                    {
                        "type": "VerifiableCredentialApiExchangeService",
                        "serviceEndpoint": "http://localhost:4005/exchange/993cce5e-58a8-41ce-a055-bef4a8253379/27485032-e0bc-4d74-bb5a-bb778cd7f8e3"
                    },
                    {
                        "type": "CredentialHandlerService"
                    }
                ]
            },
            "challenge": "27485032-e0bc-4d74-bb5a-bb778cd7f8e3",
            "domain": "http://localhost:4005"
        }
    }
]

Called by the wallet to initiate the exchange. Returns a DIDAuthentication Verifiable Presentation Request asking the wallet for a DID Authentication

Called by the wallet to complete the exchange. Receives the requested DID Authentication and returns the signed Verifiable Credential after verifying the DID Authentication.

NOTE: the object returned from the initial setup call to the exchanger returns two deepLinks:

At the moment, the Leaner Credential Wallet only supports the directDeepLink.

Versioning

The transaction-service is primarily intended to run as a docker image within a docker compose network, typically as part of a flow that is orchestrated by the DCC Issuer Coordinator and the DCC Workflow Coordinator.

For convenience we've published the images for the transaction-service and the other services used by the coordinators, as well as for the coordinators themselves, to Docker Hub so that you don't have to build them locally yourself from the github repositories.

The images on Docker Hub will of course at times be updated to add new functionality and fix bugs. Rather than overwrite the default (latest) version on Docker Hub for each update, we've adopted the Semantic Versioning Guidelines with our docker image tags.

We DO NOT provide a latest tag so you must provide a tag name (i.e, the version number) for the images in your docker compose file.

To ensure you've got compatible versions of the services and the coordinator, the major number for each should match. At the time of writing, the versions for each are at 0.1.0, and the major number (the leftmost number) agrees across all three.

If you do ever want to work from the source code in the repository and build your own images, we've tagged the commits in Github that were used to build the corresponding Docker image. So a github tag of v0.1.0 coresponds to a docker image tag of 0.1.0

Development

To install locally (for development):

git clone https://github.com/digitalcredentials/transaction-manager-service.git
cd transaction-manager-service
npm install
npm dev

Contribute

PRs accepted.

If editing the Readme, please conform to the standard-readme specification.

License

MIT License © 2022 Digital Credentials Consortium.