diff --git a/docs/guides/Flows/basics.md b/docs/guides/Flows/basics.md new file mode 100755 index 0000000..3a64757 --- /dev/null +++ b/docs/guides/Flows/basics.md @@ -0,0 +1,72 @@ +--- +title: Basics +order: 10 +--- + + +Here we explain the *Basics* on how the Credential Issuance and Verification flow, defining the basic concepts and components you will work with. + +## Templates + +The templates contain the core logic that govern the issuance and verification flows. + +- **What is a template?** + > [!IMPORTANT] + > Templates contain (re-usable) business logic for issuance and verification flow. Templates are scripted in *Zencode* executed by Zenroom and Slangroom, check the [🏗️ Core Technologies](/core-technologies) to know more. + +- **Where and how do I use a template?** + + Templates are used in *issuance Flows* and *Verification Flows*. When editing a flow, you can select the desired template from a dropdown. + +- **How do edit a template?** + Inside the Template editor, in the DIDroom Dashboard. If you want to test the code, you may want to use the [Slangroom editor](https://dyne.org/slangroom/) or [Apiroom](https://apiroom.net/). + +- **Where are templates executed?** + Depending if it's an *Authorization*, *Issuance* or *Verification*, the templates are executed inside a Microservice, inside the Wallet or inside the Verifier App [more about this later]. + + +## Issuance and Verification Flows + +Flows define the full behaviour of credential issuance and verification. While the Template define the Flow's core business logic, you define in the Flow parameters such as the duration of a credential, the cryptography and protocols to be used, the Microservices it should run on, as well as the data that is visible by the user (name, description, logo) as well as the machine-readable data used in the communication protocols (e.g. OpenID4VCI and OpenID4VP). + +- **TLDR: what is actually Flow in DIDroom?** + > [!NOTE] + > Imagine a Flow as a shell of extra parameters that surround a template. Imagine that you are offering the same credentials, once with a 1 day expiration and once with a 1 month expiration: the templates used will typically be the same, while the Flow configurations will change. + + + +## Microservices + +Credential Issuance and Verification are (partly) executed in Microservices. The Microservices are configured in the Dashboard, the Dashboard also provides you with the actuall Microservices code, with different deployment possibilities. + + +## Toolchain and components + +The Issuance and Verification is implemented using our in-house built components, including: + +- NCR (no-code room): REST API server for Zencode scripts, single binary, doesn't require su privildges, includes OpenAPI and automagic GUI for REST APIs see + + -> Repo: https://github.com/ForkbombEu/ncr + +- DIDroom Microservices: OpenID4VCI and OpenID4VP compatible Microservices, highly customizable, implemented in Zencode (with some JS). This is where the server-side of new protocols and new cryptography is implemented. + + -> Repo: https://github.com/ForkbombEu/DIDroom_microservices + +- Zencode client: all the Zencode needed in the Wallet, Verifier and in the Dashboard. This is where the client-side of new protocols and new cryptography is implemented. + + -> Repo: https://github.com/ForkbombEu/client_zencode + +- Ghisa: minimalist 0-security proxy, saves you from (some) CORS errors. + + -> Repo: https://github.com/ForkbombEu/ghisa + + +- Zenroom: Cryptographic virtual machine, powers all (almost) the cryptogrphy in DIDroom. Ultra portable, runs on server/mobile/browser/IoT. + + -> Repo: https://dev.zenroom.org/ + +- Slangroom: Extension to Zenroom, for networking, database, file management. See: + + -> Repo: https://dyne.org/slangroom/ + + diff --git a/docs/guides/Flows/flows.md b/docs/guides/Flows/flows.md new file mode 100755 index 0000000..10923ae --- /dev/null +++ b/docs/guides/Flows/flows.md @@ -0,0 +1,25 @@ +--- +title: Flows +order: 30 +--- + + + +Flows define the full behaviour of credential issuance and verification. While the Template define the Flow's core business logic, you define in the Flow parameters such as the duration of a credential, the cryptography and protocols to be used, the Microservices it should run on, as well as the data that is visible by the user (name, description, logo) as well as the machine-readable data used in the communication protocols (e.g. OpenID4VCI and OpenID4VP). + +- **TLDR: what is actually Flow in DIDroom?** + > [!NOTE] + > Imagine a Flow as a shell of extra parameters that surround a template. Imagine that you are offering the same credentials, once with a 1 day expiration and once with a 1 month expiration: the templates used will typically be the same, while the Flow configurations will change. + + +## Parameters + +When editing the a Flow, you're editing several parameters, some of them are machine-readable, some are human readable, some have impact on the credentials that will be issued (*Cryptography* type and *Expiration*), some impact the deployment (the *Microservices* section). + +| Dashboard Flow Editor | +|--| +| dashboard-flow-editor | + + + + diff --git a/docs/guides/Flows/index.md b/docs/guides/Flows/index.md new file mode 100755 index 0000000..f3b085a --- /dev/null +++ b/docs/guides/Flows/index.md @@ -0,0 +1,5 @@ +--- +title: 🧩 Issuance/Verification +order: 25 +--- + diff --git a/docs/guides/Flows/microservices.md b/docs/guides/Flows/microservices.md new file mode 100755 index 0000000..6ff011a --- /dev/null +++ b/docs/guides/Flows/microservices.md @@ -0,0 +1,66 @@ +--- +title: Microservices +order: 40 +--- + +Credential Issuance and Verification are (partly) executed in Microservices. The Microservices are configured in the Dashboard, the Dashboard also provides you with the actuall Microservices code, with different deployment possibilities. + + +## Configuration + +You can create a new Microservice or edit it, by giving it a *Name* and an *Endpoint*, the *Port* is initially selected randomly but can be edited. + +| Microservices setup | +|--| +| microservices-setup | + +## Deployment + +Once you are happy with the Templated and Flows you created, you can start deploying them. You that by: + +1. Downloading the provisioned Microservices by pressing the *Dowload microservices* button. +1. Upload the download .zip to the server where the Microservices will deployed, which responds to the Endpoint you previously configured. +1. Use the docker-compose file (typically doing + +```bash +docker-compose up +``` + +---- + +See below the *Home > Organization > Microservices* page: + + +| Microservices list and Deployment | +|--| +| microservices-manual-deployment-small | + + + +## Extendability + +DIDroom Microservices are implemented and deployed using: + + +- NCR (no-code room): REST API server for Zencode scripts, single binary, doesn't require su privildges, includes OpenAPI and automagic GUI for REST APIs see + + -> Repo: https://github.com/ForkbombEu/ncr + +- DIDroom Microservices: OpenID4VCI and OpenID4VP compatible Microservices, highly customizable, implemented in Zencode (with some JS). This is where the server-side of new protocols and new cryptography is implemented. + + -> Repo: https://github.com/ForkbombEu/DIDroom_microservices + +- Ghisa: minimalist 0-security proxy, saves you from (some) CORS errors. + + -> Repo: https://github.com/ForkbombEu/ghisa + + +- Zenroom: Cryptographic virtual machine, powers all (almost) the cryptogrphy in DIDroom. Ultra portable, runs on server/mobile/browser/IoT. + + -> Repo: https://dev.zenroom.org/ + +- Slangroom: Extension to Zenroom, for networking, database, file management. See: + + -> Repo: https://dyne.org/slangroom/ + + diff --git a/docs/guides/Flows/templates.md b/docs/guides/Flows/templates.md new file mode 100755 index 0000000..4431098 --- /dev/null +++ b/docs/guides/Flows/templates.md @@ -0,0 +1,74 @@ +--- +title: 🧩 Templates +order: 20 +--- + +Here we describe the Templates: here lives the customizable and re-usable business logic of Credential Issuance and verification + +## Intro + +- **What is a template?** + > [!IMPORTANT] + > Templates contain (re-usable) business logic for issuance and verification flow. Templates are scripted in *Zencode* executed by Zenroom and Slangroom, check the [🏗️ Core Technologies](/core-technologies) to know more. + +- **Where and how do I use a template?** + + Templates are used in *issuance Flows* and *Verification Flows*. When editing a flow, you can select the desired template from a dropdown. + +- **How do edit a template?** + Inside the Template editor, in the DIDroom Dashboard. If you want to test the code, you may want to use the [Slangroom editor](https://dyne.org/slangroom/) or [Apiroom](https://apiroom.net/). + +- **Where are templates executed?** + Depending if it's an *Authorization*, *Issuance* or *Verification*, the templates are executed inside a Microservice, inside the Wallet or inside the Verifier App [more about this later]. + + +## Authorization, Issuance and Verification Templates + +There are 3 types of Template, they are visible in *Organization > Home* and in the *Templates* section. + + +| Templates in *Organization > Home* | +|--| +| templates-list-small | + +| *Templates* section | +|--| +| templates-list-large | + + +## Parameters and presets + +Based on the type, each Template has a different set of Parameters. Templates are typically built from **Presets**. + +### Form structure + +It define here the Parameters that Flow (using this Template) will receive as input, specifically, + + -> **Authorization Template**: the parameters in the form will be input by the user in the Wallet app and processed by the *Authorization Server*. + + -> **Issuance Template**: this time the parameters in the form will be passed by the *Authorization Server* and processed by the *Credential Issuer*. + + -> **Verification Template**: the parameters in the form will be read inside the *Verifiable Presentation* produced by the *Wallet App* and processed by the *Verifier App*. + +### Custom Code + +This contains the core logic of the Template. The Custom code can: + + - Read and process the input coming from the parameters in the "Form structure" + - Read and process parameters in the "Zencode data" + - Create and process data on the fly + - Return the processed data: some types of Template, have a certain return data format (e.g. Authorization Template must return a JSON object named "data") but each template can send the output to a REST API or write it into a Database. The parameters relevant to REST APIs and Parameters must be loaded from "Zencode data" (see Presets for examples). + +| Templates Editor | +|--| +| template-editor | + +## Toolchain + +Templates are programmed in Zencode and Slangroom and can be tested in the Slangroom Editor, see: https://dyne.org/slangroom/ + +| Slangroom Editor | +|--| +|[![Slangroom-Editor](../images/dashboard/slangroom-editor.png)](https://dyne.org/slangroom/) | + + diff --git a/docs/guides/Flows/toolchain.md.unused b/docs/guides/Flows/toolchain.md.unused new file mode 100755 index 0000000..ff4b026 --- /dev/null +++ b/docs/guides/Flows/toolchain.md.unused @@ -0,0 +1,16 @@ +--- +title: 🧩 Toolchain +order: 40 +--- + +# Basics + + +# Technology + + +# Toolchain + + +# Extendability + diff --git a/docs/guides/Wallet/wallet.md b/docs/guides/Wallet/wallet.md index 485b9ac..c042a9c 100755 --- a/docs/guides/Wallet/wallet.md +++ b/docs/guides/Wallet/wallet.md @@ -8,6 +8,14 @@ The [Wallet App](https://github.com/ForkbombEu/wallet) is an Android/iOS mobile The Wallet App allows the user to creat an account and the same account can be used to login onto the [DIDroom Dashboard](https://dashboard.didroom.com/). +| Wallet App screenshot | +|--| +| wallet-android-credlist | + + + + + ## Install the app The app can be installed from the Android and iOS stores: @@ -25,3 +33,25 @@ Once you login, you can: - Scan a QR code to receive a credential - Scan a QR code (from the Verifier App) to present a credential. + +## Test on the web + +The Wallet can also be deployed as a web application, offering most of the app functionalities and ideal for testing and debugging. You can deploy your own instance by following the [instructions](https://github.com/ForkbombEu/wallet?tab=readme-ov-file#installation) or test our (manually updated) web deployment at [wallet.didroom.com](https://wallet.didroom.com/). + +| Wallet App deployed on web | +|--| +| wallet-web | + + +## White-labeling + +The Wallet (and Verifier) App are built with white-labeling in mind> + +1. The mobile apps take load ALL the UX from [didroom-copmponents](https://github.com/forkbombeu/didroom-components) which is packaged into [NPM +package](https://www.npmjs.com/package/@didroom/components) via CI. +1. The whole deployment of the mobile apps on the Android/iOS stores is done via CI,see for example the Android production deployment [CI script](https://github.com/ForkbombEu/wallet/actions/workflows/publish_on_production.yml). +1. See below DIDroom-components [Storybook](https://forkbombeu.github.io/didroom-components/?path=/docs/colors--docs). + +| | +|--| +|[![Storybook](../images/wallet/didroom-components-storybook.png)](https://forkbombeu.github.io/didroom-components/) | \ No newline at end of file diff --git a/docs/guides/images/dashboard/flow-editor.png b/docs/guides/images/dashboard/flow-editor.png new file mode 100755 index 0000000..a09e9b5 Binary files /dev/null and b/docs/guides/images/dashboard/flow-editor.png differ diff --git a/docs/guides/images/dashboard/microservices-manual-deployment-small.png b/docs/guides/images/dashboard/microservices-manual-deployment-small.png new file mode 100755 index 0000000..f410f20 Binary files /dev/null and b/docs/guides/images/dashboard/microservices-manual-deployment-small.png differ diff --git a/docs/guides/images/microservices/microservices-manual-deployment.png b/docs/guides/images/dashboard/microservices-manual-deployment.png similarity index 100% rename from docs/guides/images/microservices/microservices-manual-deployment.png rename to docs/guides/images/dashboard/microservices-manual-deployment.png diff --git a/docs/guides/images/dashboard/microservices-setup.png b/docs/guides/images/dashboard/microservices-setup.png new file mode 100755 index 0000000..1659f8d Binary files /dev/null and b/docs/guides/images/dashboard/microservices-setup.png differ diff --git a/docs/guides/images/dashboard/microservices.zip b/docs/guides/images/dashboard/microservices.zip new file mode 100755 index 0000000..c19e201 Binary files /dev/null and b/docs/guides/images/dashboard/microservices.zip differ diff --git a/docs/guides/images/dashboard/slangroom-editor.png b/docs/guides/images/dashboard/slangroom-editor.png new file mode 100755 index 0000000..b11800c Binary files /dev/null and b/docs/guides/images/dashboard/slangroom-editor.png differ diff --git a/docs/guides/images/dashboard/template-editor-long.png b/docs/guides/images/dashboard/template-editor-long.png new file mode 100755 index 0000000..eeaa2d5 Binary files /dev/null and b/docs/guides/images/dashboard/template-editor-long.png differ diff --git a/docs/guides/images/dashboard/template-editor.png b/docs/guides/images/dashboard/template-editor.png new file mode 100755 index 0000000..55ce2dc Binary files /dev/null and b/docs/guides/images/dashboard/template-editor.png differ diff --git a/docs/guides/images/dashboard/templates-list-large.png b/docs/guides/images/dashboard/templates-list-large.png new file mode 100755 index 0000000..dea25bb Binary files /dev/null and b/docs/guides/images/dashboard/templates-list-large.png differ diff --git a/docs/guides/images/dashboard/templates-list-small.png b/docs/guides/images/dashboard/templates-list-small.png new file mode 100755 index 0000000..d543bc6 Binary files /dev/null and b/docs/guides/images/dashboard/templates-list-small.png differ diff --git a/docs/guides/images/wallet/didroom-components-storybook.png b/docs/guides/images/wallet/didroom-components-storybook.png new file mode 100755 index 0000000..9249187 Binary files /dev/null and b/docs/guides/images/wallet/didroom-components-storybook.png differ diff --git a/docs/guides/images/wallet/wallet-android-credlist.jpg b/docs/guides/images/wallet/wallet-android-credlist.jpg new file mode 100755 index 0000000..07ca8a3 Binary files /dev/null and b/docs/guides/images/wallet/wallet-android-credlist.jpg differ diff --git a/docs/guides/images/wallet/wallet-web.png b/docs/guides/images/wallet/wallet-web.png new file mode 100755 index 0000000..44be8c4 Binary files /dev/null and b/docs/guides/images/wallet/wallet-web.png differ