diff --git a/blog/2021-04-27-new-release.md b/blog/2021-04-27-new-release.md index 6fc2f980..2b93b9b8 100644 --- a/blog/2021-04-27-new-release.md +++ b/blog/2021-04-27-new-release.md @@ -40,7 +40,7 @@ those for best compatibility. ## Some changes to the CLI configuration There are some slight changes to the `@veramo/cli` configuration, mostly around the `veramo server`. options. Check out -the [veramo docs](https://veramo.io/docs/veramo_agent/configuration_internals) to see how the CLI configuration file +the [veramo docs](../docs/veramo_agent/configuration_internals.md) to see how the CLI configuration file works. ### Ngrok is no longer included diff --git a/blog/2021-07-14-veramo-2.0-release.md b/blog/2021-07-14-veramo-2.0-release.md index 270aaba7..0d11d4ad 100644 --- a/blog/2021-07-14-veramo-2.0-release.md +++ b/blog/2021-07-14-veramo-2.0-release.md @@ -22,10 +22,10 @@ using `Veramo` you might be impacted by some breaking changes that had to be add Our `@veramo/did-comm` package got a boost of functionality with new support for DIDComm v2 over HTTP. This plugin now exports 3 new methods: -- [`packDIDCommMessage()`](/docs/api/did-comm.didcomm.packdidcommmessage.md) - encrypt and/or sign a message for +- [`packDIDCommMessage()`](../docs/api/did-comm.didcomm.packdidcommmessage) - encrypt and/or sign a message for sending. -- [`sendDIDCommMessage()`](/docs/api/did-comm.didcomm.senddidcommmessage.md) - send a packed message to a recipient DID. -- [`unpackDIDCommMessage()`](/docs/api/did-comm.didcomm.unpackdidcommmessage.md) - decode stored messages. +- [`sendDIDCommMessage()`](../docs/api/did-comm.didcomm.senddidcommmessage) - send a packed message to a recipient DID. +- [`unpackDIDCommMessage()`](../docs/api/did-comm.didcomm.unpackdidcommmessage) - decode stored messages. As you may have guessed, the existing `sendMessageDIDCommAlpha1()` method should no longer be used. We hope that the name of the method already suggested instability. This will be removed in Veramo 4.x. @@ -80,16 +80,16 @@ stores, or find DIDs by keys or by .well-known/did-config matches... you name it The `@veramo/key-manager` now exports 2 new methods: -- [`keyManagerSign()`](/docs/api/key-manager.keymanager.keymanagersign.md) - support all signing algorithms that lower +- [`keyManagerSign()`](../docs/api/key-manager.keymanager.keymanagersign.md) - support all signing algorithms that lower level key management systems provide. -- [`keyManagerSharedSecret()`](/docs/api/key-manager.abstractkeymanagementsystem.sharedsecret.md) - compute shared +- [`keyManagerSharedSecret()`](../docs/api/key-manager.abstractkeymanagementsystem.sharedsecret.md) - compute shared secrets between a locally managed secret key and an external public key. These are supposed to start phasing out the previous methods `keyManagerSignJWT()`, `keyManagerSignEthTX()` and `keyManagerEncryptJWE()`/`keyManagerDecryptJWE()`. The new signer can accommodate multiple algorithms implemented by -your [`AbstractKeyManagementSystem`](/docs/api/kms-local.md) implementations: +your [`AbstractKeyManagementSystem`](../docs/api/kms-local.md) implementations: Example 1. signing JWT: @@ -123,8 +123,8 @@ const rawTx = await agent.keyManagerSign({ ## Get `DIDComm v2` out of the box with `@veramo/remote-server` & `did:web` -If you are using [`@veramo/remote-server#WebDidDocRouter`](/docs/api/remote-server.webdiddocrouter.md) -and [`@veramo/did-provider-web`](/docs/api/did-provider-web.md) it is now easier than ever to receive DIDComm messages. +If you are using [`@veramo/remote-server#WebDidDocRouter`](../docs/api/remote-server.webdiddocrouter.md) +and [`@veramo/did-provider-web`](../docs/api/did-provider-web.md) it is now easier than ever to receive DIDComm messages. The `did-provider-web` bootstraps your new `did:web` with Ed25519 and X25519 keys to be used for `keyAgreement` as well as listing an HTTP `DIDCommMessaging` endpoint by default. @@ -136,7 +136,7 @@ identifiers. `@veramo/kms-local-react-native` is not needed any more. It is now replaced by `@veramo/kms-local` which can be used in all environments. Some extra ceremony is still needed on react-native but the overall experience should be simpler. -Take a look at the [React-native tutorial](/docs/react_native_tutorials/react_native_setup_identifiers.md) to see how to +Take a look at the [React-native tutorial](../docs/react_native_tutorials/react_native_setup_identifiers.md) to see how to set that up. --- diff --git a/docs/basics/identifiers.md b/docs/basics/identifiers.md index 7a8cad5c..dce04c89 100644 --- a/docs/basics/identifiers.md +++ b/docs/basics/identifiers.md @@ -3,11 +3,17 @@ id: identifiers title: Identifiers --- -`Decentralized Identifier` or `DID` is a critical component of verifiable data. A `DID` is a new type of unique identifier which can be created independent of a central authority and that is designed to prove control over the DID using cryptographic proofs. In a verifiable data context, a DID can be used to verify the provenance and ownership of attested data by verifying the proof that is attached to the assertion. +`Decentralized Identifier` or `DID` is a critical component of verifiable data. A `DID` is a new type of unique +identifier which can be created independent of a central authority and that is designed to prove control over the DID +using cryptographic proofs. In a verifiable data context, a DID can be used to verify the provenance and ownership of +attested data by verifying the proof that is attached to the assertion. ## Decentralized Identifier -Different flavors of `DIDs` exist today. The flavor of a `DID` or more accurately the `DID Method` defines how CRUD operations for a DID of that `DID Method` are executed. Each `DID Method` has different tradeoffs in specific use cases. For example, a web DID can be created without a Blockchain but `DID Methods` exist that have a dependency on a Blockchain. All of them are valid `DIDs` but have different guaranteees. +Different flavors of `DIDs` exist today. The flavor of a `DID` or more accurately the `DID Method` defines how CRUD +operations for a DID of that `DID Method` are executed. Each `DID Method` has different tradeoffs in specific use cases. +For example, a web DID can be created without a Blockchain but `DID Methods` exist that have a dependency on a +Blockchain. All of them are valid `DIDs` but have different guaranteees. The example below shows how a web DID for veramo.dev might look like. @@ -17,15 +23,21 @@ did:web:veramo.dev ### DID Creation -When a `DID` is created, it is typically associated with a private and public key pair. The public key will be visible in the `DID Document`. This allows the controller/subject of the `DID` to generate proofs that are verifiable by anyone that has the corresponding `DID Document` for that `DID`. The process of retrieving the `DID Document` from a `DID` is called `DID Resolution`. +When a `DID` is created, it is typically associated with a private and public key pair. The public key will be visible +in the `DID Document`. This allows the controller/subject of the `DID` to generate proofs that are verifiable by anyone +that has the corresponding `DID Document` for that `DID`. The process of retrieving the `DID Document` from a `DID` is +called `DID Resolution`. ### DID Resolution -A `DID Resolver` can take `DID` as input and resolve the `DID Document`. This is an important concept in how data flows in verifiable data systems. +A `DID Resolver` can take `DID` as input and resolve the `DID Document`. This is an important concept in how data flows +in verifiable data systems. ### DID Document -Every `DID` has a `DID Document` that describes the `DID` subject. In the case of `did:web` the `DID Document` is hosted on the website in the following format. It contains essential cryptographic information and also services that the `DID` has available. This is the foundation of how `DIDs` can start to communicate with each other. +Every `DID` has a `DID Document` that describes the `DID` subject. In the case of `did:web` the `DID Document` is hosted +on the website in the following format. It contains essential cryptographic information and also services that the `DID` +has available. This is the foundation of how `DIDs` can start to communicate with each other. ```json // 20201110152830 @@ -61,4 +73,4 @@ Every `DID` has a `DID Document` that describes the `DID` subject. In the case o ### DID Methods -Explainer on what a DID method is and links to supported [DID Methods](/docs/veramo_agent/did_methods) page +Explainer on what a DID method is and links to supported [DID Methods](../veramo_agent/did_methods.md) page diff --git a/docs/basics/introduction.md b/docs/basics/introduction.md index 92fdccd2..d5f1a174 100644 --- a/docs/basics/introduction.md +++ b/docs/basics/introduction.md @@ -6,34 +6,55 @@ sidebar_label: Introduction :::info -Veramo is in a public beta. There will be some breaking changes in the coming months, and we endeavor to communicate these in advance via our blog. However, we expect the core APIs to remain relatively stable. You can keep up to date here and get involved in our growing community. We are excited to see what you build with Veramo! +Veramo is in a public beta. There will be some breaking changes in the coming months, and we endeavor to communicate +these in advance via our blog. However, we expect the core APIs to remain relatively stable. You can keep up to date +here and get involved in our growing community. We are excited to see what you build with Veramo! ::: -Veramo is a JavaScript framework that makes it easy for anyone to use cryptographically verifiable data in their applications. It was designed to make it easy for developers who want to use DIDs, verifiable credentials, and data-centric protocols to bring next-generation features to their users. +Veramo is a JavaScript framework that makes it easy for anyone to use cryptographically verifiable data in their +applications. It was designed to make it easy for developers who want to use DIDs, verifiable credentials, and +data-centric protocols to bring next-generation features to their users. -These docs are written for anyone wishing to learn more about the grounding principles behind verifiable data and develop a deeper understanding of the Veramo framework to build next-generation apps that leverage the many benefits of trust networks. +These docs are written for anyone wishing to learn more about the grounding principles behind verifiable data and +develop a deeper understanding of the Veramo framework to build next-generation apps that leverage the many benefits of +trust networks. ### How to use these docs -If you are new to the concept of verifiable data, it would be best to read the fundamentals section linearly as each section builds on knowledge and terminology gained in the previous. +If you are new to the concept of verifiable data, it would be best to read the fundamentals section linearly as each +section builds on knowledge and terminology gained in the previous. -If you are more experienced with verifiable data concepts and/or development in general, you can dive into the architecture section where more specifics of how the internals work is covered. You can also jump over to the [API reference](/docs/api/core) section. Links and more info about these packages can also be found in the [Plugins](/docs/veramo_agent/plugins) section. +If you are more experienced with verifiable data concepts and/or development in general, you can dive into the +architecture section where more specifics of how the internals work is covered. You can also jump over to +the [API reference](../api/index.md) section. Links and more info about these packages can also be found in +the [Plugins](../veramo_agent/plugins.md) section. ### Mission > Our mission is to empower developers to build better trust layers in their applications. -We obsess over standards and interop so developers and product owners can focus on building their next-generation applications that leverage verifiable data and their decentralized verification benefits. +We obsess over standards and interop so developers and product owners can focus on building their next-generation +applications that leverage verifiable data and their decentralized verification benefits. ### Why Veramo? -The verifiable data landscape has grown exponentially in the past few years and continues to grow at an accelerated rate. Where you have accelerated innovation, you will also have a lot of competing standards. This anomaly makes interoperability challenging. Veramo was designed to be flexible, modular, and scalable. It allows developers to orchestrate a custom system from a growing list of standards without worrying about interoperability and fast-changing specs. +The verifiable data landscape has grown exponentially in the past few years and continues to grow at an accelerated +rate. Where you have accelerated innovation, you will also have a lot of competing standards. This anomaly makes +interoperability challenging. Veramo was designed to be flexible, modular, and scalable. It allows developers to +orchestrate a custom system from a growing list of standards without worrying about interoperability and fast-changing +specs. -Competing standards can create an unnecessary burden and confusion for product owners and developers who prefer not to be tied to a specific vendor or invest too much building on standards that will most likely change. There is a complex [dependency tree](/docs/advanced/data_flow) per platform on top of changing standards that requires considerable effort to manage. +Competing standards can create an unnecessary burden and confusion for product owners and developers who prefer not to +be tied to a specific vendor or invest too much building on standards that will most likely change. There is a complex +dependency tree per platform on top of changing standards that requires considerable effort to manage. -However, this should not prevent businesses from bringing the immense value of verifiable data to their users. We envision an ecosystem of interoperable functionality made possible through specialized community plugins that respect open standards. +However, this should not prevent businesses from bringing the immense value of verifiable data to their users. We +envision an ecosystem of interoperable functionality made possible through specialized community plugins that respect +open standards. -At Veramo, we work closely with the [W3C](https://www.w3.org/) and [DIF](https://identity.foundation/) to build compatibility across many projects and initiatives in the space. +At Veramo, we work closely with the [W3C](https://www.w3.org/) and [DIF](https://identity.foundation/) to build +compatibility across many projects and initiatives in the space. -Using Veramo, you can design your agent how you want it by using the [core plugins](/docs/veramo_agent/plugins). We have plugins for DID Methods, Messaging Protocols, Storage, Key Management, Authentication, and many more. +Using Veramo, you can design your agent how you want it by using the [core plugins](../veramo_agent/plugins.md). We have +plugins for DID Methods, Messaging Protocols, Storage, Key Management, Authentication, and many more. diff --git a/docs/basics/signing_keys.md b/docs/basics/signing_keys.md index 32af6ebf..c2b3af81 100644 --- a/docs/basics/signing_keys.md +++ b/docs/basics/signing_keys.md @@ -3,7 +3,8 @@ id: signing_keys title: Signing & Keys --- -To understand how verifiable data works it is important to have an understanding public keys and signing. The following videos provide an excellent overview. +To understand how verifiable data works it is important to have an understanding public keys and signing. The following +videos provide an excellent overview. Robert Miles PhD Student at University of Nottingham diff --git a/docs/basics/verifiable_data.md b/docs/basics/verifiable_data.md index dbcb47bc..6e5fd47a 100644 --- a/docs/basics/verifiable_data.md +++ b/docs/basics/verifiable_data.md @@ -3,30 +3,48 @@ id: verifiable_data title: Verifiable Data --- -Verifiable data is simply data that has been digitally signed using a cryptographic algorithm. If data has been signed in this way, someone can verify the signature. Here we can look a the most common standard of verifiable data - Verifiable Credentials. +Verifiable data is simply data that has been digitally signed using a cryptographic algorithm. If data has been signed +in this way, someone can verify the signature. Here we can look a the most common standard of verifiable data - +Verifiable Credentials. ### W3C Verifiable Credential -To summarise the W3C definition of a [Verifiable Credential](https://www.w3.org/TR/vc-data-model/#what-is-a-verifiable-credential), it is a piece of data that conforms to the `VerifiableCredential` type. It has attributes such as issuer, subject, proofs, and data being made verifiable. Like a physical credential, a verifiable credential is issued from one entity known as the `issuer` to another entity, the `subject`. +To summarise the W3C definition of +a [Verifiable Credential](https://www.w3.org/TR/vc-data-model/#what-is-a-verifiable-credential), it is a piece of data +that conforms to the `VerifiableCredential` type. It has attributes such as issuer, subject, proofs, and data being made +verifiable. Like a physical credential, a verifiable credential is issued from one entity known as the `issuer` to +another entity, the `subject`. -Let's imagine a physical document such as a passport or driver's license; these documents can be issued by the government that asserts your personal information and 'permissions' such as the type of vehicle you can drive or if you can vote. A physical credential has encoded watermarks, which can be scanned to prove that the issuer is who is stated on the document. To trust the document, you would need to trust the issuer of the document. Some facilities will have the ability to scan these documents to verify the authenticity of the document. This would be considered a 'trust network'. +Let's imagine a physical document such as a passport or driver's license; these documents can be issued by the +government that asserts your personal information and 'permissions' such as the type of vehicle you can drive or if you +can vote. A physical credential has encoded watermarks, which can be scanned to prove that the issuer is who is stated +on the document. To trust the document, you would need to trust the issuer of the document. Some facilities will have +the ability to scan these documents to verify the authenticity of the document. This would be considered a 'trust +network'. -You trust the government and the scanner they approve; therefore, you will trust the person whose document is verified by the scanner. The same model exists here, except the verification or proof is purely digital and cryptographic. Also, it should be noted when anything moves from analog to digital, it usually has more applications outside of the traditional analog version. +You trust the government and the scanner they approve; therefore, you will trust the person whose document is verified +by the scanner. The same model exists here, except the verification or proof is purely digital and cryptographic. Also, +it should be noted when anything moves from analog to digital, it usually has more applications outside of the +traditional analog version. This is the current v1 format for a W3C compliant Verifiable Credential: ```json { "@context": [ - "https://www.w3.org/2018/credentials/v1", + "https://www.w3.org/2018/credentials/v1" ], - "type": ["VerifiableCredential"], - "issuer": {"id": "did:web:veramo.dev"}, + "type": [ + "VerifiableCredential" + ], + "issuer": { + "id": "did:web:veramo.dev" + }, "issuanceDate": "2010-01-01T19:73:24Z", "credentialSubject": { "id": "did:example:user", "community": { - "rank": "rockstar" + "rank": "rockstar" } }, "proof": { @@ -35,9 +53,10 @@ This is the current v1 format for a W3C compliant Verifiable Credential: "proofPurpose": "assertionMethod", "verificationMethod": "https://example.edu/issuers/keys/1", "jws": "eyJhbGciOiJSUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..TCYt5X - sITJX1CxPCT8yAV-TVkIEq_PbChOMqsLfRoPsnsgw5WEuts01mq-pQy7UJiN5mgRxD-WUc - X16dUEMGlv50aqzpqh4Qktb3rk-BuQy72IFLOqV0G_zS245-kronKb78cPN25DGlcTwLtj - PAYuNzVBAh4vGHSrQyHUdBBPM" + sITJX1CxPCT8yAV-TVkIEq_PbChOMqsLfRoPsnsgw5WEuts01mq-pQy7UJiN5mgRxD-WUc + X16dUEMGlv50aqzpqh4Qktb3rk-BuQy72IFLOqV0G_zS245-kronKb78cPN25DGlcTwLtj + PAYuNzVBAh4vGHSrQyHUdBBPM + " } } ``` diff --git a/docs/cli_tutorials/cli_create_vc.md b/docs/cli_tutorials/cli_create_vc.md index 30a50f33..5247d0f0 100644 --- a/docs/cli_tutorials/cli_create_vc.md +++ b/docs/cli_tutorials/cli_create_vc.md @@ -4,7 +4,9 @@ title: Create Credential sidebar_label: Create Credential --- -This guide will walk you through the basic functions to get you started with the Veramo CLI by learning the basic commands and issuing a credential. The core API of Veramo is exposed by the CLI tool. Learn more about [installing and configuring the Veramo CLI](/docs/veramo_agent/cli_tool.md). +This guide will walk you through the basic functions to get you started with the Veramo CLI by learning the basic +commands and issuing a credential. The core API of Veramo is exposed by the CLI tool. Learn more +about [installing and configuring the Veramo CLI](../veramo_agent/cli_tool.md). Now, let's create an identifier, a credential, and learn where everything is stored. @@ -16,7 +18,8 @@ veramo config create ### Create a DID -The first thing you will want to do is create an identifier using the `did create` command. This command will create a DID and store the keys in a local database. +The first thing you will want to do is create an identifier using the `did create` command. This command will create a +DID and store the keys in a local database. ```bash veramo did create @@ -60,7 +63,8 @@ _Output:_ ### Create a verifiable credential -Now let's create your first credential with Veramo using the DID you just created as both **issuer** and **subject**. This will be a _self-signed_ credential. Follow the command prompt after running: +Now let's create your first credential with Veramo using the DID you just created as both **issuer** and **subject**. +This will be a _self-signed_ credential. Follow the command prompt after running: ```bash veramo credential create diff --git a/docs/deployment_tutorials/deployment_aws.md b/docs/deployment_tutorials/deployment_aws.md index 984281c6..5a62b9fe 100644 --- a/docs/deployment_tutorials/deployment_aws.md +++ b/docs/deployment_tutorials/deployment_aws.md @@ -4,7 +4,10 @@ title: AWS Deployment sidebar_label: AWS Deployment --- -This guide covers the deployment of a [Veramo Cloud Agent](https://github.com/uport-project/veramo-agent-deploy) to AWS using Elastic Container Registry (ECR), Elastic Container Service (ECS), and Relational Database Service (RDS). We will also show how to use a GitHub action to automate building an image, pushing to your container repository, and deploying to the ECS cluster. This setup can be done either through the AWS Console UI or through the CLI +This guide covers the deployment of a [Veramo Cloud Agent](https://github.com/uport-project/veramo-agent-deploy) to AWS +using Elastic Container Registry (ECR), Elastic Container Service (ECS), and Relational Database Service (RDS). We will +also show how to use a GitHub action to automate building an image, pushing to your container repository, and deploying +to the ECS cluster. This setup can be done either through the AWS Console UI or through the CLI ### Prerequisites @@ -48,7 +51,8 @@ Which should output something like this: ### Push the image to ECR -The following steps can also be found in the AWS Console under "View Push Commands", and those will already have the correct region and URL values for your registry. The commands below will need to be updated with your own values. +The following steps can also be found in the AWS Console under "View Push Commands", and those will already have the +correct region and URL values for your registry. The commands below will need to be updated with your own values. - Retrieve an authentication token and authenticate your Docker client to your registry. @@ -76,7 +80,8 @@ docker push ############.dkr.ecr..amazonaws.com/veramo-ecr:latest ### Create the database -Next, go to the [RDS console](https://console.aws.amazon.com/rds/home?region=us-east-1#) for your region to create the Postgres database that we'll be connecting to. +Next, go to the [RDS console](https://console.aws.amazon.com/rds/home?region=us-east-1#) for your region to create the +Postgres database that we'll be connecting to. - Choose Postgres for the Database type - Take note of the user/pass combo you enter - we'll need that later on. @@ -110,7 +115,8 @@ Once that is done, click "View Cluster". We'll need to get the public URL for ou - Add container ![Container Configuration](../../static/img/guides/aws_deployment/ecs-task-container-config.png) -c. Pay special attention to the environment variables section. This is where important details are passed to the container. Also note that if the DB username or password contain special characters, they will need to be URL encoded. +c. Pay special attention to the environment variables section. This is where important details are passed to the +container. Also note that if the DB username or password contain special characters, they will need to be URL encoded. ### Create ECS Service @@ -118,12 +124,17 @@ With the cluster defined, and the task definition configured, the last step is t - Go to the cluster and click Create under the Services tab: ![Create Service](../../static/img/guides/aws_deployment/ecs-create-service.png) -- In the next screen, give your service a name, and for simplicity, choose Daemon for the service type which will make it easier to update the service with a GitHub Action. +- In the next screen, give your service a name, and for simplicity, choose Daemon for the service type which will make + it easier to update the service with a GitHub Action. ![Service Configuration](../../static/img/guides/aws_deployment/ecs-service-config.png) -Note: Adding a load balancer is optional, but not necessary. The aim for this guide was to keep things fairly simple, but you can add a load balancer here if that fits your project's requirements. +Note: Adding a load balancer is optional, but not necessary. The aim for this guide was to keep things fairly simple, +but you can add a load balancer here if that fits your project's requirements. -Once the service is running, go to the URL for your instance and you should see the default Veramo page containing links to the DID doc, API Docs, and API Schema. Congrats! You're up and running. +Once the service is running, go to the URL for your instance and you should see the default Veramo page containing links +to the DID doc, API Docs, and API Schema. Congrats! You're up and running. -One advantage of using ECS is that is quite straightforward to trigger an update using a Github Action and following [these steps](https://docs.github.com/en/actions/guides/deploying-to-amazon-elastic-container-service), beginning with 3: Store your Amazon ECS task definition as a JSON file in your GitHub repository. +One advantage of using ECS is that is quite straightforward to trigger an update using a Github Action and +following [these steps](https://docs.github.com/en/actions/guides/deploying-to-amazon-elastic-container-service), +beginning with 3: Store your Amazon ECS task definition as a JSON file in your GitHub repository. diff --git a/docs/dev_tools/agent_explorer.md b/docs/dev_tools/agent_explorer.md index 233c9131..bf9b35a1 100644 --- a/docs/dev_tools/agent_explorer.md +++ b/docs/dev_tools/agent_explorer.md @@ -3,19 +3,31 @@ id: agent_explorer title: Agent Explorer --- -Agent explorer makes it easy to browse and interact with multiple agents while developing apps on Veramo. At it's most basic it is a dashboard but could also be considered a front-end for a credential wallet. +Agent explorer makes it easy to browse and interact with multiple agents while developing apps on Veramo. At it's most +basic it is a dashboard but could also be considered a front-end for a credential wallet. ## Motivation -Throughout the development cycle of Veramo from its early alpha days as DAF, we have always had some form of user interface to help build and test features. The first UI was a React Native mobile application called daf-mobile which has since been deprecated. +Throughout the development cycle of Veramo from its early alpha days as DAF, we have always had some form of user +interface to help build and test features. The first UI was a React Native mobile application called daf-mobile which +has since been deprecated. -Out of necessity for a fully working UI that makes working with agents easier and helps validate Veramo APIs among many other use-cases we created a simple dashboard called Agent Explorer. +Out of necessity for a fully working UI that makes working with agents easier and helps validate Veramo APIs among many +other use-cases we created a simple dashboard called Agent Explorer. -As the Agent Explorer is a developer dashboard, the design was to be kept minimal and unobtrusive while surfacing the very pieces of technical information that would normally be hidden for non-developers. We also wanted this UI to be modular and flexible as Veramo is. We have implemented a widget based approach that allows developers to create their own dashboard widgets while developing features for Veramo perhaps in another codebase. And finally the explorer provides a quick and simple way to see what’s going on in your agents and can assist in interacting and quickly generating bulk data for research and experiments. +As the Agent Explorer is a developer dashboard, the design was to be kept minimal and unobtrusive while surfacing the +very pieces of technical information that would normally be hidden for non-developers. We also wanted this UI to be +modular and flexible as Veramo is. We have implemented a widget based approach that allows developers to create their +own dashboard widgets while developing features for Veramo perhaps in another codebase. And finally the explorer +provides a quick and simple way to see what’s going on in your agents and can assist in interacting and quickly +generating bulk data for research and experiments. ## Install -After you have deployed an agent using our [1 button Heroku deploy](https://github.com/uport-project/veramo-agent-deploy) for example. In your heroku settings you will find the API key for your agent. Using this API key you can connect this agent and others to an instance of the explorer. +After you have deployed an agent using +our [1 button Heroku deploy](https://github.com/uport-project/veramo-agent-deploy) for example. In your heroku settings +you will find the API key for your agent. Using this API key you can connect this agent and others to an instance of the +explorer. ### Run locally using `npx` diff --git a/docs/dev_tools/introduction.md b/docs/dev_tools/introduction.md index 7b9357c0..31d374a2 100644 --- a/docs/dev_tools/introduction.md +++ b/docs/dev_tools/introduction.md @@ -5,4 +5,6 @@ title: Introduction Our developer tools make building apps with Veramo a breeze. The current core tools are -[![veramo-devtool](../../static/img/devtool_veramo_cli.svg)](/docs/dev_tools/veramo_cli) [![veramo-devtool](../../static/img/devtool_veramo_react.svg)](/docs/dev_tools/veramo_react) [![veramo-devtool](../../static/img/devtool_veramo_agent_explorer.svg)](/docs/dev_tools/agent_explorer) +[![veramo-devtool](../../static/img/devtool_veramo_cli.svg)](./veramo_cli.md) +[![veramo-devtool](../../static/img/devtool_veramo_react.svg)](./veramo_react.md) +[![veramo-devtool](../../static/img/devtool_veramo_agent_explorer.svg)](./agent_explorer.md) diff --git a/docs/dev_tools/veramo_cli.md b/docs/dev_tools/veramo_cli.md index 4f2a2fa8..1f73e0aa 100644 --- a/docs/dev_tools/veramo_cli.md +++ b/docs/dev_tools/veramo_cli.md @@ -5,5 +5,5 @@ title: Veramo CLI Read these to learn about our CLI tool: -- [CLI Tool](/docs/veramo_agent/cli_tool.md) -- [YAML Configuration](/docs/veramo_agent/configuration.md) +- [CLI Tool](../veramo_agent/cli_tool.md) +- [YAML Configuration](../veramo_agent/configuration.md) diff --git a/docs/dev_tools/veramo_react.md b/docs/dev_tools/veramo_react.md index 590d0c24..8d0f9bec 100644 --- a/docs/dev_tools/veramo_react.md +++ b/docs/dev_tools/veramo_react.md @@ -7,7 +7,9 @@ Veramo React makes it easy to interact with multiple agents in React Application ## Motivation -When using veramo in your front end React apps you may need to manage the state of multiple remote and local agents. Veramo React makes it easy to manage agents without needing to write or maintain boilerplate code. It also enables making new features available to front-end stacks without developers needing to implement them manually. +When using veramo in your front end React apps you may need to manage the state of multiple remote and local agents. +Veramo React makes it easy to manage agents without needing to write or maintain boilerplate code. It also enables +making new features available to front-end stacks without developers needing to implement them manually. When you add an agent configuration it is persisted to local storage. A randomly generated ID is assigned to each agent. @@ -19,9 +21,12 @@ yarn add @veramo-community/veramo-react **_NOTE:_** Veramo React depends on the `@next` versions of `@veramo` -Installation includes `@veramo/core@next` and `@veramo/remote-client@next`. You will **NOT** need to add additional `@veramo` dependencies to your app if you are just working with remote agents. +Installation includes `@veramo/core@next` and `@veramo/remote-client@next`. You will **NOT** need to add +additional `@veramo` dependencies to your app if you are just working with remote agents. -The following sippet is a simplified extract from [Veramo Agent Explorer](https://github.com/veramolabs/agent-explorer) that uses [React Query](https://github.com/tannerlinsley/react-query) ontop of `Veramo React` to manage the data layer including caching and global data syncing. +The following sippet is a simplified extract from [Veramo Agent Explorer](https://github.com/veramolabs/agent-explorer) +that uses [React Query](https://github.com/tannerlinsley/react-query) ontop of `Veramo React` to manage the data layer +including caching and global data syncing. ```tsx import React from 'react' @@ -75,7 +80,8 @@ export const agent = createAgent({ }) ``` -In the provider setup above, add the following to bootstrap the local agent. You can also call [addAgent](#addagent) to add while your application is running. +In the provider setup above, add the following to bootstrap the local agent. You can also call [addAgent](#addagent) to +add while your application is running. ```tsx import {agent} from '../veramo' @@ -85,7 +91,8 @@ import {agent} from '../veramo' ## `useVeramo hook` -The primary hook that provides the following API to your app. The below syntax uses React Query to fetch the data and uses the cache key of `credentials + agentID` to identify the data to your app. +The primary hook that provides the following API to your app. The below syntax uses React Query to fetch the data and +uses the cache key of `credentials + agentID` to identify the data to your app. ```tsx import { useVeramo } from '@veramo-community/veramo-react' @@ -109,7 +116,8 @@ export default = () => { } ``` -If you are not using React Query you can just call `agent?.dataStoreORMGetVerifiableCredentials()` and manage the data like any async data source. +If you are not using React Query you can just call `agent?.dataStoreORMGetVerifiableCredentials()` and manage the data +like any async data source. ## API diff --git a/docs/node_tutorials/node_setup_identifiers.md b/docs/node_tutorials/node_setup_identifiers.md index d2dc2637..d91f7372 100644 --- a/docs/node_tutorials/node_setup_identifiers.md +++ b/docs/node_tutorials/node_setup_identifiers.md @@ -8,7 +8,8 @@ This guide covers setting up an agent and creating identifiers in Node. ### Prerequisites -You need to have Node v12 or later installed. In this example, we use yarn as the package manager, but you can also use npm. +You need to have Node v12 or later installed. In this example, we use yarn as the package manager, but you can also use +npm. Start by creating a directory for our project and initializing the npm package. @@ -53,7 +54,8 @@ Add a tsconfig.json to your project ## Bootstrap Veramo -We bootstrap Veramo by creating a setup file and initializing the agent. Create a setup file in `src/veramo/setup.ts` and import the following dependencies: +We bootstrap Veramo by creating a setup file and initializing the agent. Create a setup file in `src/veramo/setup.ts` +and import the following dependencies: ```typescript // Core interfaces diff --git a/docs/react_native_tutorials/react_native_setup_identifiers.md b/docs/react_native_tutorials/react_native_setup_identifiers.md index 5003c664..26a8c071 100644 --- a/docs/react_native_tutorials/react_native_setup_identifiers.md +++ b/docs/react_native_tutorials/react_native_setup_identifiers.md @@ -4,11 +4,17 @@ title: React Native Setup & Identifiers sidebar_label: Setup & Identifiers --- -This guide will walk you through setting up Veramo on React Native. You should have a good understanding of React Native and have your environment set up correctly to build iOS and Android apps. Check out the [React Native](https://reactnative.dev/docs/environment-setup) docs to learn more. Node v12 or later is required to run Veramo. +This guide will walk you through setting up Veramo on React Native. You should have a good understanding of React Native +and have your environment set up correctly to build iOS and Android apps. Check out +the [React Native](https://reactnative.dev/docs/environment-setup) docs to learn more. Node v12 or later is required to +run Veramo. ## Introduction -Let's set up Veramo to run locally on the device and use `sqlite` to store data, identities, and keys. Our identity provider will be `ethr-did`. Initially, we will set up the [agent](../veramo_agent/introduction.md) in the most basic config and add more plugins for additional functionality as we go. Right now we just want to create an [identifer](../basics/identifiers.md). +Let's set up Veramo to run locally on the device and use `sqlite` to store data, identities, and keys. Our identity +provider will be `ethr-did`. Initially, we will set up the [agent](../veramo_agent/introduction.md) in the most basic +config and add more plugins for additional functionality as we go. Right now we just want to create +an [identifier](../basics/identifiers.md). ## Bootstrap React Native @@ -30,13 +36,15 @@ We need to set up some native dependencies and shims that Veramo plugins will us yarn add @veramo/kms-local react-native-sqlite-storage ``` -Next, add the shim from `@ethersproject/shims` and the polyfill for strong random values following the recommendation [here](https://docs.ethers.io/v5/cookbook/react-native/#cookbook-reactnative-security). +Next, add the shim from `@ethersproject/shims` and the polyfill for strong random values following the +recommendation [here](https://docs.ethers.io/v5/cookbook/react-native/#cookbook-reactnative-security). ```bash yarn add @ethersproject/shims react-native-get-random-values ``` -To access node methods we need to install [rn-nodeify](https://www.npmjs.com/package/rn-nodeify) to our dev dependencies. +To access node methods we need to install [rn-nodeify](https://www.npmjs.com/package/rn-nodeify) to our dev +dependencies. ```bash yarn add rn-nodeify --dev @@ -46,14 +54,15 @@ Add the following snippets to your package.json file ```json { - "scripts": { + "scripts": { ... - "postinstall": "rn-nodeify --install assert,buffer,process,crypto,stream,vm --hack" - } + "postinstall": "rn-nodeify --install assert,buffer,process,crypto,stream,vm --hack" + } } ``` -Import `shim.js` (created by rn-nodify),`react-native-get-random-values`, and `@ethersproject/shims` into the top of `index.js`. +Import `shim.js` (created by rn-nodify),`react-native-get-random-values`, and `@ethersproject/shims` into the top +of `index.js`. ```ts import './shim' @@ -78,17 +87,20 @@ npx pod-install ### Veramo -Now let's install Veramo Core and some plugins. Don't worry; we will walk through what each of these plugins does in the next section. +Now let's install Veramo Core and some plugins. Don't worry; we will walk through what each of these plugins does in the +next section. ```bash yarn add @veramo/core @veramo/did-manager @veramo/kms-local @veramo/did-provider-ethr @veramo/key-manager @veramo/did-resolver @veramo/data-store @veramo/credential-w3c ethr-did-resolver web-did-resolver ``` -Close the React native packager, clean the project, and rerun your app. If everything is okay, you should see the default React Native screen as before. +Close the React native packager, clean the project, and rerun your app. If everything is okay, you should see the +default React Native screen as before. ## Bootstrap Veramo -We bootstrap Veramo by creating a setup file and initializing the agent. Create a setup file in `src/veramo/setup.ts` and import the following dependencies: +We bootstrap Veramo by creating a setup file and initializing the agent. Create a setup file in `src/veramo/setup.ts` +and import the following dependencies: ```tsx // Core interfaces @@ -179,10 +191,12 @@ Awesome! That's the basic agent configured and ready to use. Let's try it out :r ## Basic User Interface -Now that the agent has been created and configured with plugins, we can create some identifiers. For this, we will need some basic UI. +Now that the agent has been created and configured with plugins, we can create some identifiers. For this, we will need +some basic UI. -:::note -Veramo does not impose decisions on how you manage state in your app and will work alongside any existing architecture like Redux or Mobx etc. For brevity, we use `useState` in this example, but you can treat Veramo like you would any async data source. +:::note Veramo does not impose decisions on how you manage state in your app and will work alongside any existing +architecture like Redux or Mobx etc. For brevity, we use `useState` in this example, but you can treat Veramo like you +would any async data source. ::: Open `App.tsx` and delete all the contents and add the following code: @@ -246,4 +260,5 @@ const App = () => { export default App ``` -Close the packager and rebuild the app. Once loaded hit the **Create identifier** button a few times and you should see your identifiers being created! +Close the packager and rebuild the app. Once loaded hit the **Create identifier** button a few times and you should see +your identifiers being created! diff --git a/docs/react_tutorials/react_setup_resolver.md b/docs/react_tutorials/react_setup_resolver.md index 6185278c..70a0ca4e 100644 --- a/docs/react_tutorials/react_setup_resolver.md +++ b/docs/react_tutorials/react_setup_resolver.md @@ -4,7 +4,9 @@ title: React Setup & Resolver sidebar_label: Setup & Resolver --- -Veramo core runs natively in the browser. The plugins you use also need to be browser compatible. This guide will set up a DID resolver to work in a standard [Create React App](https://create-react-app.dev/) setup. It is possible to add your own identity, key management, and storage plugins that are browser compatible. +Veramo core runs natively in the browser. The plugins you use also need to be browser compatible. This guide will set up +a DID resolver to work in a standard [Create React App](https://create-react-app.dev/) setup. It is possible to add your +own identity, key management, and storage plugins that are browser compatible. ### Initialize app @@ -21,7 +23,8 @@ Install veramo core, DIDResolver plugin and dependencies yarn add @veramo/core @veramo/did-resolver ethr-did-resolver web-did-resolver did-resolver ``` -Create a setup file in `src/veramo/setup.ts` and add the following code, replacing the `INFURA_PROJECT_ID` with your own. +Create a setup file in `src/veramo/setup.ts` and add the following code, replacing the `INFURA_PROJECT_ID` with your +own. ```ts import { createAgent, IResolver } from '@veramo/core' @@ -111,4 +114,6 @@ Please note that global installs of create-react-app are no longer supported. You can fix this by running npm uninstall -g create-react-app or yarn global remove create-react-app before using create-react-app again. ``` -Be sure to follow the instructions in that message, and then run the `npx` command again. If you still the message, [this answer may help](https://stackoverflow.com/questions/59188624/template-not-provided-using-create-react-app). +Be sure to follow the instructions in that message, and then run the `npx` command again. If you still the +message, [this answer may help](https://stackoverflow.com/questions/59188624/template-not-provided-using-create-react-app) +. diff --git a/docs/veramo_agent/cli_tool.md b/docs/veramo_agent/cli_tool.md index d18fbd45..764f509a 100644 --- a/docs/veramo_agent/cli_tool.md +++ b/docs/veramo_agent/cli_tool.md @@ -4,8 +4,8 @@ title: CLI Tool sidebar_label: CLI Tool --- -:::important -Ensure you have Node v12 or later installed. The CLI tool is currently only supported on MACOS and Linux systems. Windows support is coming soon. +:::important Ensure you have Node v12 or later installed. The CLI tool is currently only supported on MACOS and Linux +systems. Windows support is coming soon. ::: The Veramo CLI exposes a configurable agent and includes an express server, open-api and swagger docs. @@ -58,10 +58,11 @@ Commands: ## Create configuration -You can use a per-project configuration or specify a configuration file with each command. -If the current folder contains an `agent.yml` configuration file, for every command. +You can use a per-project configuration or specify a configuration file with each command. If the current folder +contains an `agent.yml` configuration file, for every command. -Alternatively, you can specify a config file with each command using the `--config /path/to/your/config.yml` option. This will be used instead of a per-project configuration file. +Alternatively, you can specify a config file with each command using the `--config /path/to/your/config.yml` option. +This will be used instead of a per-project configuration file. You can create a configuration file in the current folder by running: @@ -69,8 +70,8 @@ You can create a configuration file in the current folder by running: veramo config create ``` -This will create an `agent.yml` file that will get used next time you invoke a CLI command in this folder. -By default, the database files are created in the same folder as the config file. +This will create an `agent.yml` file that will get used next time you invoke a CLI command in this folder. By default, +the database files are created in the same folder as the config file. If you want to connect to a hosted veramo instance you can create a configuration file by running: diff --git a/docs/veramo_agent/configuration.md b/docs/veramo_agent/configuration.md index 27c28824..1d1a9f39 100644 --- a/docs/veramo_agent/configuration.md +++ b/docs/veramo_agent/configuration.md @@ -3,16 +3,19 @@ id: configuration title: Configuration --- -Adding plugins to Veramo Agent will configure how the agent works and dictate what platform it can run on. Veramo Server & Veramo Client are the 2 loose categories of configuration available. +Adding plugins to Veramo Agent will configure how the agent works and dictate what platform it can run on. Veramo Server +& Veramo Client are the 2 loose categories of configuration available. ### Veramo Server Config diagram here, links to deployments etc -Veramo Server has plugins that run on the server and includes `@veramo/remote-server` which contains an express server and exposes Veramo Agent methods over REST. +Veramo Server has plugins that run on the server and includes `@veramo/remote-server` which contains an express server +and exposes Veramo Agent methods over REST. ### Veramo Client Config diagram here, links to veramo react etc -Veramo Client has plugins that run on clients such as browser and mobile. Veramo Clients can manage their own data and can also be configured to act as a client to an instance of Veramo Server or a Web3 provider. +Veramo Client has plugins that run on clients such as browser and mobile. Veramo Clients can manage their own data and +can also be configured to act as a client to an instance of Veramo Server or a Web3 provider. diff --git a/docs/veramo_agent/configuration_internals.md b/docs/veramo_agent/configuration_internals.md index 70d764a9..1911fe35 100644 --- a/docs/veramo_agent/configuration_internals.md +++ b/docs/veramo_agent/configuration_internals.md @@ -4,9 +4,13 @@ title: YAML Configuration sidebar_label: YAML Configuration --- -The CLI uses a YAML file for configuration. This is a deep dive into the internals and how the yaml is converted into executable code. +The CLI uses a YAML file for configuration. This is a deep dive into the internals and how the yaml is converted into +executable code. -Objects are created by a helper function [createObjects](https://github.com/uport-project/veramo/blob/faa7940c515bbd65dfaf9370594794f627099a38/packages/cli/src/lib/objectCreator.ts#L5), which recursively mutates the configuration object that was parsed from a YAML file and applies custom rules for objects containing: +Objects are created by a helper +function [createObjects](https://github.com/uport-project/veramo/blob/faa7940c515bbd65dfaf9370594794f627099a38/packages/cli/src/lib/objectCreator.ts#L5) +, which recursively mutates the configuration object that was parsed from a YAML file and applies custom rules for +objects containing: - Module imports @@ -129,7 +133,8 @@ agent: - $ref: /didComm ``` -By referencing objects you can ensure that only one copy of the object is created in memory and can be shared by different modules. For example the same database connection used by different plugins: +By referencing objects you can ensure that only one copy of the object is created in memory and can be shared by +different modules. For example the same database connection used by different plugins: ```yaml dbConnection: diff --git a/docs/veramo_agent/did_methods.md b/docs/veramo_agent/did_methods.md index fafb9677..c75d5754 100644 --- a/docs/veramo_agent/did_methods.md +++ b/docs/veramo_agent/did_methods.md @@ -21,7 +21,7 @@ did:ethr:0xc530503a148babcaca68565cfa576d6f43427a2d ``` [did:ethr Spec](https://github.com/decentralized-identity/ethr-did-resolver/blob/master/doc/did-method-spec.md) -• [Veramo did:ethr provider API](/docs/api/did-provider-ethr.md) +• [Veramo did:ethr provider API](../api/did-provider-ethr.md) Ethr-DID provides a scalable identity method for Ethereum addresses that gives any Ethereum address the ability to collect on-chain and off-chain data. Because Ethr-DID allows any Ethereum key pair to become an identity, it is more @@ -40,7 +40,7 @@ the [ethr-did-resolver](https://github.com/decentralized-identity/ethr-did-resol did:web:veramo-agent.herokuapp.com ``` -[did:web Spec](https://w3c-ccg.github.io/did-method-web/) • [Veramo did:web provider API](/docs/api/did-provider-web.md) +[did:web Spec](https://w3c-ccg.github.io/did-method-web/) • [Veramo did:web provider API](../api/did-provider-web.md) Web-DID leverages the domain name system that allows the owner of a web origin to turn it into a DID. Creating a Web-DID is as easy as creating a DID Document and hosting it under a well-known URL. The DID Document must be available through @@ -59,7 +59,7 @@ their DID, it is has some drawbacks related to security and privacy (e.g., track did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH ``` -[did:key Spec](https://w3c-ccg.github.io/did-method-key/) • [Veramo did:key provider API](/docs/api/did-provider-key.md) +[did:key Spec](https://w3c-ccg.github.io/did-method-key/) • [Veramo did:key provider API](../api/did-provider-key.md) Key-DID represents a very light-weight self-certifying DID method which does not require any external utility such as a Blockchain. A Key-DID is created by generating a cryptographic key pair (e.g., Curve25519). Using Curve25519 will add diff --git a/docs/veramo_agent/event_system.md b/docs/veramo_agent/event_system.md index 3e8886bf..b2353506 100644 --- a/docs/veramo_agent/event_system.md +++ b/docs/veramo_agent/event_system.md @@ -4,7 +4,8 @@ title: Event System sidebar_label: Event System --- -The event system provides a way for components to interact in a decoupled way. Veramo agents provide a simple event system where events can be emitted by application code or plugin and consumed asynchronously by event listeners. +The event system provides a way for components to interact in a decoupled way. Veramo agents provide a simple event +system where events can be emitted by application code or plugin and consumed asynchronously by event listeners. ### Emitting an event @@ -16,7 +17,8 @@ agent.emit(type, data) Usually events are follow the fire-and-forget pattern. -However, there may be situations where an application may need to make sure all events are consumed before exiting, or that some state change has been performed by an event listener before going forward. +However, there may be situations where an application may need to make sure all events are consumed before exiting, or +that some state change has been performed by an event listener before going forward. For this situation, there is another pattern that can be used: @@ -26,8 +28,9 @@ await agent.emit(type, data) ### Listening for events -Listeners are registered at the time of agent creation, and are declared alongside the plugin array. In fact, agent plugins can also behave as event listeners. -A listener must declare `eventTypes` that it can handle and an async `onEvent({type, data}, context)` method that will be called when an event is fired. +Listeners are registered at the time of agent creation, and are declared alongside the plugin array. In fact, agent +plugins can also behave as event listeners. A listener must declare `eventTypes` that it can handle and an +async `onEvent({type, data}, context)` method that will be called when an event is fired. ```ts const fooEventLogger: IEventListener { @@ -42,8 +45,9 @@ const agent = new Agent({ ### Listening for multiple event types -Event listeners can register for multiple event types by using multiple entries in the eventTypes array. -The same `onEvent` method will be called for all types, so it is up to the listener implementation to differentiate between the events if necessary. +Event listeners can register for multiple event types by using multiple entries in the eventTypes array. The +same `onEvent` method will be called for all types, so it is up to the listener implementation to differentiate between +the events if necessary. ```ts const foobarPlugin: IEventListener = { @@ -62,8 +66,8 @@ const foobarPlugin: IEventListener = { ### Error handling -In case an Error is thrown during the processing of an event, the error is emitted as a new event of type "error" with the Error instance as the event data. -Handling errors, therefore means registering an error listener on the agent. +In case an Error is thrown during the processing of an event, the error is emitted as a new event of type "error" with +the Error instance as the event data. Handling errors, therefore means registering an error listener on the agent. ```ts const faultyListener: IEventListener { diff --git a/docs/veramo_agent/introduction.md b/docs/veramo_agent/introduction.md index 34e0d7dd..06d9af97 100644 --- a/docs/veramo_agent/introduction.md +++ b/docs/veramo_agent/introduction.md @@ -4,7 +4,10 @@ title: Veramo Agent sidebar_label: Introduction --- -The **Veramo DID Agent** is the entry point into the Veramo framework. A Veramo Agent is an implementation of an **Agent** using a plugin architecture. This architecture allows Veramo to be modular, scale well and play nicely with the vast array of standards in the verifiable data space. Veramo is opinionated when it comes to standards compliance but not when it comes to how you build your application layers. +The **Veramo DID Agent** is the entry point into the Veramo framework. A Veramo Agent is an implementation of an ** +Agent** using a plugin architecture. This architecture allows Veramo to be modular, scale well and play nicely with the +vast array of standards in the verifiable data space. Veramo is opinionated when it comes to standards compliance but +not when it comes to how you build your application layers. ![img](../../static/img/diagrams/veramo_agent_simple.svg) @@ -17,9 +20,12 @@ Veramo Agent is responsibe for but not limited to: - Credential Exchange - Secret Application Hot Sauce -On it's own the Veramo Agent provides a common interface for plugins to expand it's functionality. The Agent is the main class and when instantiated, orchestrates both core and custom plugins and manages the core event system. +On it's own the Veramo Agent provides a common interface for plugins to expand it's functionality. The Agent is the main +class and when instantiated, orchestrates both core and custom plugins and manages the core event system. -Veramo was written in TypeScript so it runs natively in Node, Browsers and React Native. Some plugins may be platform specific and have platform alternatives. [TypeScript](https://www.typescriptlang.org/) is a very accessible and easy language for most developers to get started quickly building on Veramo. +Veramo was written in TypeScript so it runs natively in Node, Browsers and React Native. Some plugins may be platform +specific and have platform alternatives. [TypeScript](https://www.typescriptlang.org/) is a very accessible and easy +language for most developers to get started quickly building on Veramo. Methods defined in plugins are available on the agent instance eg: diff --git a/docs/veramo_agent/message_handlers.md b/docs/veramo_agent/message_handlers.md index 27ebdeb8..fd033029 100644 --- a/docs/veramo_agent/message_handlers.md +++ b/docs/veramo_agent/message_handlers.md @@ -3,7 +3,8 @@ id: message_handlers title: Message Handlers --- -Message handlers implement the AbstractMessageHandler interface and are instantiated as a chain by the Message Handler plugin. Veramo includes a number of message handlers for you to use in your apps. +Message handlers implement the AbstractMessageHandler interface and are instantiated as a chain by the Message Handler +plugin. Veramo includes a number of message handlers for you to use in your apps. ## Core Supported Message Handlers @@ -11,15 +12,16 @@ The following plugins export a message handling method. ### `did-comm` -[did-comm](/docs/api/did-comm.md) • [DIDCommMessageHandler](/docs/api/did-comm.didcommmessagehandler.md) +[did-comm](../api/did-comm.md) • [DIDCommMessageHandler](../api/did-comm.didcommmessagehandler.md) -DIDCommMessageHandler decrypts incoming messages using the private key of the recipient. The decrypted jwt is passed along to the JWT Message Handler. +DIDCommMessageHandler decrypts incoming messages using the private key of the recipient. The decrypted jwt is passed +along to the JWT Message Handler. ![img](../../static/img/diagrams/message_didcomm.svg) ### `did-jwt` -[did-jwt](/docs/api/did-jwt.md) • [JWTMessageHandler](/docs/api/did-jwt.jwtmessagehandler.md) +[did-jwt](../api/did-jwt.md) • [JWTMessageHandler](../api/did-jwt.jwtmessagehandler.md) JWTMessageHandler takes a JWT and creates a message object. @@ -27,16 +29,19 @@ JWTMessageHandler takes a JWT and creates a message object. ### `credential-w3c` -[credential-w3c](/docs/api/credential-w3c.md) • [W3CMessageHandler](/docs/api/credential-w3c.w3cmessagehandler.md) +[credential-w3c](../api/credential-w3c.md) • [W3CMessageHandler](../api/credential-w3c.w3cmessagehandler.md) -W3CMessageHandler checks the message payload for Verifiable Credentials and Verifiable Presentations and formats the message object accordingly. +W3CMessageHandler checks the message payload for Verifiable Credentials and Verifiable Presentations and formats the +message object accordingly. ![img](../../static/img/diagrams/message_w3c.svg) ### `selective-disclosure` -[selective-disclosure](/docs/api/selective-disclosure.md) • [SDRMessageHandler](/docs/api/selective-disclosure.sdrmessagehandler.md) +[selective-disclosure](../api/selective-disclosure.md) +• [SDRMessageHandler](../api/selective-disclosure.sdrmessagehandler.md) -SDRMessageHandler checks the message payload for Selective Disclosure Request formats the message object accordingly. Learn more about selective disclosure requests in the next section. +SDRMessageHandler checks the message payload for Selective Disclosure Request formats the message object accordingly. +Learn more about selective disclosure requests in the next section. ![img](../../static/img/diagrams/message_sdr.svg) diff --git a/docs/veramo_agent/messages.md b/docs/veramo_agent/messages.md index 55bd04a4..65d0c97e 100644 --- a/docs/veramo_agent/messages.md +++ b/docs/veramo_agent/messages.md @@ -3,13 +3,18 @@ id: messages title: Messages --- -Veramo can communicate with other systems using it's messaging system. The messaging system is comprised of a Message Type, a MessageHandler interface, a MessageHandler plugin that accepts multiple message parsers plugins that implement AbstractMessageHandler You can create custom message handling plugins to add new message types for your agent. +Veramo can communicate with other systems using it's messaging system. The messaging system is comprised of a Message +Type, a MessageHandler interface, a MessageHandler plugin that accepts multiple message parsers plugins that implement +AbstractMessageHandler You can create custom message handling plugins to add new message types for your agent. ![img](../../static/img/diagrams/veramo_message_handler_simple.svg) ### Handling Messages -A message can be introduced to the Agent in a number of ways including via REST endpoint if you are using Veramo Server or by scanning a QR code if you are using Veramo Client on mobile. The MessageHandler's main responsibility is to try to convert incoming messages to the correct data model so they can be understood by Veramo and optionally be stored for later use. +A message can be introduced to the Agent in a number of ways including via REST endpoint if you are using Veramo Server +or by scanning a QR code if you are using Veramo Client on mobile. The MessageHandler's main responsibility is to try to +convert incoming messages to the correct data model so they can be understood by Veramo and optionally be stored for +later use. When you bootstrap a Veramo Agent you will have something that looks like this: @@ -28,14 +33,20 @@ const agent = new Agent({ }) ``` -The MessageHandler handler plugin is instantiated with message parsers. These parsers implement the AbstractMessageHandler interface. The MessageHandler plugin adds a `handleMessage` method to the agent and can be invoked by calling `agent.handleMessage()`. Regardless of what configuration your agent is in this method is the entry-point for all messages. +The MessageHandler handler plugin is instantiated with message parsers. These parsers implement the +AbstractMessageHandler interface. The MessageHandler plugin adds a `handleMessage` method to the agent and can be +invoked by calling `agent.handleMessage()`. Regardless of what configuration your agent is in this method is the +entry-point for all messages. -When the MessageHandler is instantiated it creates a chain of message parsers (AbstractMessageHandler) in the exact order specified in the configuration. +When the MessageHandler is instantiated it creates a chain of message parsers (AbstractMessageHandler) in the exact +order specified in the configuration. The above example would look like this: ![img](../../static/img/diagrams/veramo_message_handler_chain.svg) -Each parser will try to read the message and return a message object by examining the payload/type and deciding if it can do the job or if it should pass it onto the next parser in the chain if one exists. Once a message can be interpreted a message object is constructed, it is returned and optionally saved. +Each parser will try to read the message and return a message object by examining the payload/type and deciding if it +can do the job or if it should pass it onto the next parser in the chain if one exists. Once a message can be +interpreted a message object is constructed, it is returned and optionally saved. You can learn more about how each message handler parses messages in the next section. diff --git a/docs/veramo_agent/plugins.md b/docs/veramo_agent/plugins.md new file mode 100644 index 00000000..efcf91f1 --- /dev/null +++ b/docs/veramo_agent/plugins.md @@ -0,0 +1,86 @@ +--- +id: plugins +title: Plugins +sidebar_label: Plugins +--- + +Functionality in Veramo is added to the agent via the plugin system. Writing and configuring plugins is where almost all +the custom work will happen when building applications on Veramo. Your custom plugins can just live in a directory, +private repository or on npm where they can be shared with others. We encourage developers to follow some best practices +when writing plugins to ensure we have an ecosystem of highly interoperable functions. + +## Plugins Architecture + +This diagram shows the high level relationship between the core agent, interfaces, plugins and external protocols. This +is one simple configuration of many. + +![img](../../static/img/diagrams/veramo_plugins_simple.svg) + +## Core Plugins + +### `@veramo/did-manager` + +[API Reference](../api/did-manager.md) + +### `@veramo/did-provider-ethr` + +[API Reference](../api/did-provider-ethr.md) + +### `@veramo/did-provider-web` + +[API Reference](../api/did-provider-web.md) + +### `@veramo/did-provider-key` + +[API Reference](../api/did-provider-key.md) + +### `@veramo/key-manager` + +[API Reference](../api/key-manager.md) + +### `@veramo/kms-local` + +[API Reference](../api/kms-local.md) + +### `@veramo/did-resolver` + +[API Reference](../api/did-resolver.md) + +### `@veramo/did-comm` + +[API Reference](../api/did-comm.md) + +This plugin provides a method of creating an encrypted message according to the initial DIDComm-js implementation. See +the [API Reference](../api/did-comm.md) for more info. + +### `@veramo/did-jwt` + +[API Reference](../api/did-jwt.md) + +### `@veramo/message-handler` + +[API Reference](../api/message-handler.md) + +### `@veramo/url-handler` + +[API Reference](../api/url-handler.md) + +### `@veramo/selective-disclosure` + +[API Reference](../api/selective-disclosure.md) + +### `@veramo/credential-w3c` + +[API Reference](../api/credential-w3c.md) + +### `@veramo/remote-server` + +[API Reference](../api/remote-server.md) + +### `@veramo/data-store` + +[API Reference](../api/data-store.md) + +### `@veramo/remote-client` + +[API Reference](../api/remote-client.md) diff --git a/docs/veramo_agent/plugins.md.md b/docs/veramo_agent/plugins.md.md deleted file mode 100644 index 0df2e78a..00000000 --- a/docs/veramo_agent/plugins.md.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -id: plugins -title: Plugins -sidebar_label: Plugins ---- - -Functionality in Veramo is added to the agent via the plugin system. Writing and configuring plugins is where almost all of the custom work will happen when building applications on Veramo. Your custom plugins can just live in a directory, private repository or on npm where they can be shared with others. We encourage developers to follow some best practices when writing plugins to ensure we have an ecosystem of highly interoperable functions. - -## Plugins Architecture - -This diagram shows the high level relationship between the core agent, interfaces, plugins and external protocols. This is one simple configuration of many. - -![img](../../static/img/diagrams/veramo_plugins_simple.svg) - -## Core Plugins - -### `@veramo/did-manager` - -[API Reference](/docs/api/did-manager) - -### `@veramo/did-provider-ethr` - -[API Reference](/docs/api/did-provider-ethr) - -### `@veramo/did-provider-web` - -[API Reference](/docs/api/did-provider-web) - -### `@veramo/did-provider-key` - -[API Reference](/docs/api/did-provider-key) - -### `@veramo/key-manager` - -[API Reference](/docs/api/key-manager) - -### `@veramo/kms-local` - -[API Reference](/docs/api/kms-local) - -### `@veramo/did-resolver` - -[API Reference](/docs/api/did-resolver) - -### `@veramo/did-comm` - -[API Reference](/docs/api/did-comm) - -This plugin provides a method of creating an encrypted message according to the initial DIDComm-js implementation. See the [API Reference](/docs/api/did-comm) for more info. - -### `@veramo/did-jwt` - -[API Reference](/docs/api/did-jwt) - -### `@veramo/message-handler` - -[API Reference](/docs/api/message-handler) - -### `@veramo/url-handler` - -[API Reference](/docs/api/url-handler) - -### `@veramo/selective-disclosure` - -[API Reference](/docs/api/selective-disclosure) - -### `@veramo/credential-w3c` - -[API Reference](/docs/api/credential-w3c) - -### `@veramo/remote-server` - -[API Reference](/docs/api/remote-server) - -### `@veramo/data-store` - -[API Reference](/docs/api/data-store) - -### `@veramo/remote-client` - -[API Reference](/docs/api/remote-client) diff --git a/docs/veramo_agent/sdr_request.md b/docs/veramo_agent/sdr_request.md index e3a05131..1ecdc53c 100644 --- a/docs/veramo_agent/sdr_request.md +++ b/docs/veramo_agent/sdr_request.md @@ -3,8 +3,16 @@ id: sdr_request title: Selective Disclosure Request --- -Users being at the centre of information systems is one of the foundational concepts behind Self Sovereign Identity or SSI. When users or individuals are placed at the centre of information systems they need a way to share their information selectively. This is referred to a selective disclosure. The concept is to encourage and promote privacy and data control for the subjects. There are many use cases documented for this but the simple examples are KYC compliance, legal age requirements and or banking credit history. If we take the legal age example, a subject may wish to share that they are of legal age to access a service but should not have to share their actual date of birth, home address, contact number and other personally identifying information (PII). +Users being at the centre of information systems is one of the foundational concepts behind Self Sovereign Identity or +SSI. When users or individuals are placed at the centre of information systems they need a way to share their +information selectively. This is referred to a selective disclosure. The concept is to encourage and promote privacy and +data control for the subjects. There are many use cases documented for this but the simple examples are KYC compliance, +legal age requirements and or banking credit history. If we take the legal age example, a subject may wish to share that +they are of legal age to access a service but should not have to share their actual date of birth, home address, contact +number and other personally identifying information (PII). ![img](../../static/img/diagrams/sdr_request_flow.svg) -A Selective Disclosure Request is a Veramo message type that is created and signed by a DID. It contains a request for specific Verifiable Credential claims and can specify the issuer(s) of those credentials along with other criteria. The subject of the request can respond by creating and signing a Verifiable Presentation to include the requested claims. +A Selective Disclosure Request is a Veramo message type that is created and signed by a DID. It contains a request for +specific Verifiable Credential claims and can specify the issuer(s) of those credentials along with other criteria. The +subject of the request can respond by creating and signing a Verifiable Presentation to include the requested claims. diff --git a/docs/veramo_agent/versioning.md b/docs/veramo_agent/versioning.md index 94075529..d0069461 100644 --- a/docs/veramo_agent/versioning.md +++ b/docs/veramo_agent/versioning.md @@ -4,9 +4,10 @@ title: Versioning sidebar_label: Versioning --- -Veramo is currently in public beta but we want to make sure that the road is smooth as possible for anyone starting to +Veramo is currently in public beta, but we want to make sure that the road is smooth as possible for anyone starting to build applications on Veramo with a view to deploying in production. If you are planning on deploying an application in -production within the next year please [contact us here](/docs/) and talk with us about your plans. +production within the next year please [contact us here](https://github.com/uport-project/veramo/discussions) and talk +with us about your plans. Veramo packages are released under multiple tags to allow usage of the cutting edge or experimental features alongside official releases. The default tag is `@latest` diff --git a/docusaurus.config.js b/docusaurus.config.js index bb68ff5c..cbfbb656 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -41,7 +41,7 @@ module.exports = { position: 'right', }, { - to: 'docs/api/core', + to: 'docs/api/index', activeBasePath: 'docs', label: 'API', position: 'right',