@sudoplatform-labs/sudo-di-cloud-agent
v0.10.1
Published
Decentralized Identity Cloud Agent SDK
Downloads
389
Keywords
Readme
Sudo Decentralized Identity Cloud Agent SDK
Overview
The Decentralized Identity Cloud Agent SDK provides a set of Typescript APIs enabling applications to implement decentralized identity functionality. Decentralized Identity Cloud Agent SDK is based around Anonyomes fork of Hyperledger Aries Cloud Agent Python.
Key Features
Typescript SDK wrappers to access all the functionality provided by Anonyomes fork of Hyperledger Aries Cloud Agent Python.
- Ability to create Decentralized Identifiers, Schemas and Credential Definitions on the Local Ledger
- Ability to Issue, Hold and Verify Credentials based on Credential Definitions
- Ability to revoke issued credentials
Quickly setup and takedown a local Decentralized Identity development environment using docker-compose (currently only MacOS). There are currently two playground modes supported :
Standalone Endorser Mode (Legacy and Default mode)
This mode creates the following local docker environment
- A running 4 Node Indy Decentralized Ledger
- A Decentralized Identity Cloud Agent with write permissions to the Indy Ledger
- A configured and running Tails File Server to support revocable credentials
- A mockserver agent to display webhook callbacks and provide configurable forwarding of callbacks as the controller is developed
Author Automatic, Endorser Automatic Mode (playgroundMode=author_auto_endorser_auto)
This mode is intended to allow local controller development of more complex scenarios. In this scenario, ledger transactions are created by an Author agent which are automatically forwarded to an Endorser for signing before being written to a Ledger (ie. Authors and Endorsers have different Ledger permissions through their DID). This playground mode allows development of both Author and Endorser controllers by creating the following local docker environment
- A running 4 Node Indy Decentralized Ledger
- A configured and running Tails File Server to support revocable credentials
- A Decentralized Identity Cloud Agent with endorser permissions on the Indy Ledger, configured to automatically action ALL Endorsement signing requests received over DIDComm connections.
- An Endorser mockserver agent to display webhook callbacks and provide configurable forwarding of callbacks as the Endorser controller is developed
- A Decentralized Identity Cloud Agent with user permissions on the Indy Ledger, configured to create a DIDComm connection to the Endorser and use that Endorser agent for signing Ledger transactions
- An Author mockserver agent to display webhook callbacks and provide configurable forwarding of callbacks as the Author controller is developed
Version Support
| Technology | Supported version | | -------------- | ----------------- | | docker desktop | 4.11.0 | | docker compose | 2.7.0 | | yarn | 1.22.17 |
Integration Instructions
To use the Decentralized Identity Cloud Agent SDK in a Web or Node.js project you
must add @sudoplatform-labs/sudo-di-cloud-agent
as a dependency to your project.
yarn add '@sudoplatform-labs/sudo-di-cloud-agent'
# or
npm install --save '@sudoplatform-labs/sudo-di-cloud-agent'
You will need to have docker desktop installed on your machine to run the ledger, agent, mockserver and tails file server, images.
NOTE: Make sure Use Docker Compose V2
is set in the Docker Desktop preferences since the container naming scheme is different between Docker Compose V1 and V2.
Public Interfaces
Local Development Environment Overview
To create and destroy a local standalone agent development environment (currently MacOS only), run the di-env utility.
yarn di-env up -s <your 32 character standalone agent secret wallet seed>
yarn di-env down
Other options can be seen with yarn di-env
You must specify the 32 byte secret seed used to create the wallet on the up
command or in a acapy.conf
configuration file. Since the seed should never be exposed to the public, a default is never provided by di-env
.
Standalone endorser mode, detailed usage examples
Setup for a new React Controller App
yarn global add create-react-app
create-react-app <app-name>
cd <app-name>
yarn add @sudoplatform-labs/sudo-di-cloud-agent
cp node_modules/@sudoplatform-labs/sudo-di-cloud-agent/bin/acapy.json <your apps root location>
- Edit acapy.json and add element
"endorserSeed": “<32 byte seed>”,
yarn di-env up -c <absolute path to acapy.json>
Accessing the local Cloud Agent and VON Development Ledger Directly
After the yarn di-env up
command has completed :
- The Cloud Agent swagger interface can be accessed at the
endorserAcapyAdminUri
field location specified in theacapy.json
config file (e.g. http://localhost:8201) - The VON Ledger web UI can be accessed on http://localhost:9000
Seeing container log output
- To see the logs for Cloud Agent, Tails File Server and MockServer webhook handler run
yarn di-env logs
- The level of logging defaults to INFO but can be set using the
-v
switch todi-env up
Using MockServer to develop webhook handlers
After the yarn di-env up
command has completed :
- The mockserver dashboard can be accessed at http://localhost:1080/mockserver/dashboard. This dashboard will display all the webhook callback information received from the running Cloud Agent.
- The configuration for mockserver is initialised from a file during the
di-env up
command. The absolute path for a custom initialisation file can be specifed either using theendorserMockServerConfigFile
field inacapy.json
or via the-m
switch to thedi-env up
command. If neither is specified a default initialisation is used. - The mockserver website contains details on how to write configuration to forward specific routes on to your controller as development progresses.
Providing a Public Cloud Agent Endpoint via ngrok to interact with Mobile/External Agents
- Download and unpack the ngrok free version
- In a terminal where you unpacked ngrok run
ngrok http <acapy.json "endorserAcapyInboundPort" value >
- Save the URL printed out by ngrok (i.e. it will be something like
http://0e51393f5372.ngrok.io
)
- Start the environment specifying the -e switch and the URL from ngrok along with the -c config file path
yarn di-env up -e <ngrok provided public endpoint> -c <absolute path to acapy.json>
Using a Public Ledger for testing (e.g Sovrin BuilderNet)
IMPORTANT : When using a public test ledger, information written is persistent and immutable. Personally Identifiable Information (PII) MUST NOT be written and is a major reason why the Transaction Authors Agreement (TAA) must be signed in the acceptance/setup process. It is recommended that as much development activity as possible is performed with the local VON Ledger before using a Public ledger.
di-env up -l -c <absolute path to acapy.json> -g <url to genesis file for ledger>
- As an example you could use the Sovrin BuilderNet Genesis URL or Sovrin StagingNet Genesis URL
- The genesis file URL can also be placed in the acapy.json config file using the
ledgerGenesisURL
key.
- Obtain the did created from the seed at startup via the swagger interface at http://localhost:8201/api/doc#/wallet/get_wallet_did
- Use the did and verkey returned to create an endorser DID on the appropriate public test ledger (e.g for Sovrin test networks go here)
- Extract the ledger taa
text
field from the output returned by the following commandcurl -X GET "http://localhost:8201/ledger/taa" -H "accept: application/json"
- Use the taa accept swagger interface at
http://localhost:8201/api/doc#/ledger/post_ledger_taa_accept
- Choose an appropriate
mechanism
value returned from step 4 in theaml_record->aml
object (e.gfor_session
) - Use the
taa_record-> text
field EXACTLY as returned in step 4 (i.e. this will have a\ufeff
value at the beginning which is not captured if you use the swagger ui in step 4 and will fail later when you try and write something to the ledger) - Use the
taa_record->version
field returned in step 4 (e.g. currently 2.0)
- Choose an appropriate
- Once this has been done it is possible to write new DIDs and Schemas/Credential Definitions to the Public Ledger using the relevant Swagger APIs or Typescript library provided by the SDK.
SDK Class and Method Documentation
The Decentralized Identity Cloud Agent SDK installs local typedoc
generated, HTML documentation. This will be located in the
@sudoplatform-labs/sudo-di-cloud-agent/docs
directory under the
relevent node_modules
install location. The latest version of
documentation can also be found online at Github
Questions and Support
File any issues you find on the project's GitHub repository. Be careful not to share any Personally Identifiable Information (PII) or sensitive account information (API keys, credentials, etc.) when reporting an issue.
For general inquiries related to the Sudo Platform, please contact [email protected]