From 0566f0011925018a8f9d70ccaf3dacf7067c9179 Mon Sep 17 00:00:00 2001 From: viktor Date: Wed, 9 Oct 2024 16:59:48 +0200 Subject: [PATCH] incorporation of feedback and added elements --- docs/elements/role-details.md | 98 ++++++++++++++++++++++++++++++++ docs/elements/roles-for-agent.md | 98 ++++++++++++++++++++++++++++++++ docs/hc_progenitor.md | 4 +- docs/index.md | 2 +- docs/overview.md | 38 ++++++------- 5 files changed, 217 insertions(+), 23 deletions(-) create mode 100644 docs/elements/role-details.md create mode 100644 docs/elements/roles-for-agent.md diff --git a/docs/elements/role-details.md b/docs/elements/role-details.md new file mode 100644 index 000000000..e364b0872 --- /dev/null +++ b/docs/elements/role-details.md @@ -0,0 +1,98 @@ +# `` + +## Usage + +0. If you haven't already, [go through the setup for the module](/setup). + +1. Import the `` element somewhere in the javascript side of your web-app like this: + +```js +import '@darksoil-studio/roles/dist/elements/role-detail.js' +``` + +2. Use it in the html side of your web-app like this: + +```html + + +``` + +> [!WARNING] +> Like all the elements in this module, `` needs to be placed inside an initialized ``. + +## Demo + +Here is an interactive demo of the element: + + + + + + + + +## API Reference + +`` is a [custom element](https://web.dev/articles/custom-elements-v1), which means that it can be used in any web app or website. Here is the reference for its API: + + + diff --git a/docs/elements/roles-for-agent.md b/docs/elements/roles-for-agent.md new file mode 100644 index 000000000..036cbf9e7 --- /dev/null +++ b/docs/elements/roles-for-agent.md @@ -0,0 +1,98 @@ +# `` + +## Usage + +0. If you haven't already, [go through the setup for the module](/setup). + +1. Import the `` element somewhere in the javascript side of your web-app like this: + +```js +import '@darksoil-studio/roles/dist/elements/roles-for-agent.js' +``` + +2. Use it in the html side of your web-app like this: + +```html + + +``` + +> [!WARNING] +> Like all the elements in this module, `` needs to be placed inside an initialized ``. + +## Demo + +Here is an interactive demo of the element: + + + + + + + + +## API Reference + +`` is a [custom element](https://web.dev/articles/custom-elements-v1), which means that it can be used in any web app or website. Here is the reference for its API: + + + diff --git a/docs/hc_progenitor.md b/docs/hc_progenitor.md index 0fe4f614e..9238602e1 100644 --- a/docs/hc_progenitor.md +++ b/docs/hc_progenitor.md @@ -1,7 +1,7 @@ # hc progenitor ## Why -The hc progenitor exists in order for developers to able to instansiate apps with an initial admin inscribed in the happ DNA. +The hc progenitor exists in order for developers to able to instansiate apps in a test environment. ## Using hc progenitor -hc progenitor is using tauri... +hc progenitor is using [tauri](https://tauri.app). diff --git a/docs/index.md b/docs/index.md index 62470b527..33fa6e8ba 100644 --- a/docs/index.md +++ b/docs/index.md @@ -36,4 +36,4 @@ features: This module gives your apps the power of **role management**. -It uses a *progenitor* as initial admin and allows consuming applications to create arbitrary roles and bind the possibility of preforming actions to those roles. \ No newline at end of file +It uses a list of *progenitors* as initial admins and allows consuming applications to create arbitrary roles and bind the possibility of preforming actions to those roles. \ No newline at end of file diff --git a/docs/overview.md b/docs/overview.md index cec3db03b..7ca09e1ea 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -10,40 +10,38 @@ To integrate this module into your application: ## Module design -Creating roles in fully peer-to-peer systems can be tricky. There is no node in the network that by default is able to administer the system. In order to introduce rolebased management on Holochain, someone needs to be written into the app as it is generated as the agent that has special rights, this will then be part of the rules of the app that everyone plays by (the DNA). +Creating roles in fully peer-to-peer systems can be tricky. There is no node in the network that by default is able to administer the system. In order to introduce role based management on Holochain, someone needs to be written into the app as it is generated as the agent that has special rights, this will then be part of the rules of the app that everyone plays by (the DNA). -The pattern we are using in this module is the progenitor pattern. This means that the agent that instansiates the DNA writes themselves into the DNA as the original admin. Once an original admin is created, this administrator is able to generate further roles including additional administrators. Administrators are also able to remove all of the roles from Agents (including the Admin role of the progenitor). Below you will find graphical representations of how the module works. +The pattern we are using in this module is the progenitor pattern. This means that the agent that instantiates the DNA writes themselves into the DNA as the original admin. Once an original admin is created, this administrator is able to generate further roles including additional administrators. Administrators are also able to remove all of the roles from Agents (including the Admin role of the progenitor). Below you will find graphical representations of how the module works. -**This pattern creates the requirement of a layer outside the app (like a lobby) where a user is able to create the instanciation of the app so that the public key (AgentPubKey) associated with the original user is encoded into the DNA as it is being created. Read more about this in the implementation considerations section below.** +**This pattern creates the requirement of a layer outside the app (like a lobby) where a user is able to create the instantiation of the app so that the public key (AgentPubKey) associated with the original user is encoded into the DNA as it is being created. Read more about this in the implementation considerations section below.** ### Original administrator (progenitor) In order to create an initial admin for the app, we are using the progenitor pattern. This means, the creator of the app (of the DNA actually) is the one who is the original admin. More admins can be added like adding any other roles by the progenitor. - ```mermaid -graph TD; - Agent --has--> AgentPubKey - Agent --creates--> hApp_DNA - AgentPubKey --included when creating--> hApp_DNA - Agent --joins -->hApp_DNA - Agent --claims--> ADMIN_ROLE - hApp_DNA --validates--> ADMIN_ROLE - +sequenceDiagram +Alice ->> Alice: creates new DNA instance (inserting AgentPubKey in DNA details) +create participant happDNA +Alice ->> happDNA: joins app +Alice ->> Alice: claims ADMIN_ROLE at init (creates RoleClaim entry) +happDNA ->> Alice: validates claim (compares Alice to progenitor) ``` ### Role assignment In the diagram below Alice is the progenitor and is therefore granted ADMIN_ROLE when entering the DNA. ```mermaid -graph TD; - Alice -- claims on init --> ADMIN_ROLE - Alice -- creates for Caroline --> admin_role_assignment - Caroline -- uses assignment to claim --> ADMIN_ROLE - Caroline -- (now admin) creates for David --> editor_role_assignment - David -- uses assignment to claim --> EDITOR_ROLE - +sequenceDiagram +Alice ->> Alice: claim ADMIN_ROLE on init
(create RoleClaim entry) +create participant Bob +Alice ->> Bob: assign ADMIN_ROLE
(create roleToAsignee link) +Bob ->>Bob: claim ADMIN:ROLE
(create RoleClaim entry) +create participant Caroline +Bob ->> Caroline: assign EDITOR_ROLE
(create roleToAsignee link) +Caroline ->> Caroline: claim EDITOR_ROLE
(create RoleClaim entry) ``` ## Design considerations @@ -52,4 +50,4 @@ The possibility of actually using the capacities that an app developer is connec It is implemented in this way in order to be sure that when someone is evaluating if an action is allowed (through a role) from an Agent, that enabling role claim must be found earlier in the source chain of that Agent to become deterministic. ## Implementation considerations -It is very important to understand that if you want to use this module, the instansiators AgentPubKey needs to be inserted into the [DNA properties](https://docs.rs/holochain_types/0.5.0-dev.0/holochain_types/prelude/struct.DnaModifiers.html#structfield.properties). This means that you need to have a running conductor that has access to an AgentPubKey that can be insterted into the app. \ No newline at end of file +It is very important to understand that if you want to use this module, the instantiator's AgentPubKey needs to be inserted into the [DNA properties](https://docs.rs/holochain_types/0.5.0-dev.0/holochain_types/prelude/struct.DnaModifiers.html#structfield.properties). This means that you need to have a running conductor that has access to an AgentPubKey that can be insterted into the app. \ No newline at end of file