Merge pull request #69 from nqminds/add_to_architecture

Add to architecture

packages/docusaurus/docs/CAHN/50-architecture/20-claim-system-design.md

@@ -2,14 +2,12 @@
 title: Claim Cascade Design
 ---
 
-## Generation and storage of key-pairs for Signing of VCs
+## Signing of VCs
 
 The claim cascade system is designed such that users or automated agents may sign claims with their private key (stored locally or stored on a remote server which for signs the claims on the user's behalf), the only requirement for the VC to be verifiable is that public key paired with the private key which was used to perform the signing will need to be securely shared in a trusted way with the system, such that the public key can be tied to a particular user's identity. 
 
 This will be achieved by utilising an authentication server which can be sent a request to generate a VC binding a public key to a user's identity, this request will contain the public key and a users credentials, in the most simple case, an email address. These credentials will then be verified, for example in the case of email; the user will receive an email which contains a link they must click to prove their identity, once that is completed the authentication server will sign a VC with it's own private key, which is trusted bt the system, binding the user's identity to that public key. This can be submitted to the system by the user to allow them to submit further VCs signed with their private key.
 
-The management of their keys then becomes an implementation detail which can be specified by the user, private-public key pairs may be ephemeral and generated 
-
 ## Receipt of VCs
 
 VCs will be submitted to a particular Claim Cascade node (running on a router / access point for example) through a HTTPS REST API endpoint. The VC will then be stored in an append only return as a received VC on that node using an Event Sourcing pattern. This means that once received a record of all the VCs received will be maintained and if our trust basis or verification basis changes one could regenerate the entire state of the system from the received VCs.
@@ -33,4 +31,20 @@ The VCs which are trusted are then passed to a utility which generates the code
 - retraction - a statement that a user retracts a previously submitted fact, used to retract falsely submitted information
 - rule - this defines a rule, which defines the logic used for inference, for example a rule may be that a device is not allowed to connect to this wifi router if it has a vulnerability with a score higher than a certain threshold. 
 
-Using these building blocks one may build any general inferencing system.
+Using these building blocks one may build any general inferencing system.
+
+## Querying the system
+
+When an external process needs to query the system, this query will take the form of a VC, the verification step will check the query is from the the VC issuer, and the trust engine will check that the VC issuer has the rights to perform that query and access the data required to fulfil the query.
+
+## Databots
+
+In order to perform more complex or numerical analytics which cannot be simply performed with a prolog query, for example generating some computed analytical artifact by analysing the data about device behaviour the analytics will be performed by a process set up to run on configurable inputs by a configurable trigger, which we call a databot. Upon a trigger being triggered, the trigger will receive any inputs which need to be configured at run-time and the process will run for those inputs, retrieve any data required for the analytics from the system by means of a query VC submitted to the system, and once it's computation is complete, send its output data into the system by means of a VC. These triggers can be triggered at query time if the information for a query result is not already present in the system, or is in need of update.
+
+## System Diagram
+
+Below is a diagram showing the components of the system. The components in the Claim Handling System box will be installed on a node of the system, inside a router or network element. The databots may be installed locally on the node, or run on a remote server. The authentication server, likewise could sit locally on the node, or run on a remote server. 
+
+Any process or app which wants to submit VCs to the system must generate a key pair and have it's public key bound to an identity which is verified through the authentication server. The process may submit VCs signed with it's private key and once the public key has been bound, those VC which have been submitted, or will be submitted, will be verified as being issued by their issuer and may proceed to be entered into the knowledge base held in the inference engine, depending on if the issuer is trusted by the trust engine or not.
+
+![image](./CAHN_Claim_Cascade_System_Design.png)

packages/nist_brski_schemas/README.md

@@ -0,0 +1,53 @@
+# Schemas directory
+
+Schemas for VCs (Verifiable Credentials) to be used for the NIST BRSKI demonstrator, used to securely communicate information to the registrar. These schemas should be instantiated on a volt running on the registrar using [the VC toolchain](https://github.com/nqminds/vc-toolchain).
+
+## To populate a volt with the schemas and set it up for the VC toolchain
+
+### Step 0 
+
+### `npm i -g @nqminds/verifiable-schemas-toolchain`
+This installs the VC toolchain utilities from https://github.com/nqminds/vc-toolchain such that they may be used globally on the command line.
+
+### Install volt cmd line interface and fusebox from https://docs.tdxvolt.com/en/getting-started/quick-start
+
+### Step 1 - `npm run prepare` 
+This runs the command `schemaTools parse-yaml-files ./src`. This validates the yaml schemas for the VCs in the src directory and generates the required documentatation & json files in the `./output` directory.
+
+The directory structure should now look like so:
+![Alt text](output_file_structure.png)
+
+### Step 2 - `schemaTools init --config volt.config.json`
+Where the volt.config.json is a volt config file exported for a user on a volt, this initialises the volt connection & builds the schema directory.
+
+![Alt text](volt_export_client_config.png)
+
+### Step 3 - `volt up ./output/* schemas`
+This uploads the output files to the schema directory, the structure in the volt should look like so:
+
+![Alt text](volt_schema_structure.png)
+
+## To create new schemas
+
+To create a new schema run, navigate to src and run:
+```bash
+  schemaTools new-schema <schema_name>
+```
+
+This will create a blank schema.yaml for you to edit:
+
+```yaml
+$id: SCHEMA_ID                                          # Typically the URL (in github of where this schema is - it will need to be unique)
+$schema: https://json-schema.org/draft/2019-09/schema
+title: SCHEMA_TITLE                                     # The title of your schema
+description: SCHEMA_DESCRIPTION                         # Schema description
+type: object
+properties:                                             # Define schema properties here
+  FIELD: 
+    type: FIELD_TYPE
+    description: FIELD_DESCRIPTION
+required:
+  - PROPERTY_ID                                         # Required fields
+examples:
+  - EXAMPLE: EXAMPLE_DATA                               # Example data
+```

packages/nist_brski_schemas/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@nqminds/nist-brski-schemas",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "prepare": "schemaTools parse-yaml-files ./src"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC"
+}

packages/schemas/README.md

@@ -1,35 +1,6 @@
 # Schemas directory
 
-Schemas for VCs (Verifiable Credentials) to be used for the NIST BRSKI demonstrator, used to securely communicate information to the registrar. These schemas should be instantiated on a volt running on the registrar using [the VC toolchain](https://github.com/nqminds/vc-toolchain).
-
-## To populate a volt with the schemas and set it up for the VC toolchain
-
-### Step 0 
-
-### `npm i -g @nqminds/verifiable-schemas-toolchain`
-This installs the VC toolchain utilities from https://github.com/nqminds/vc-toolchain such that they may be used globally on the command line.
-
-### Install volt cmd line interface and fusebox from https://docs.tdxvolt.com/en/getting-started/quick-start
-
-### Step 1 - `npm run prepare` 
-This runs the command `schemaTools parse-yaml-files ./src`. This validates the yaml schemas for the VCs in the src directory and generates the required documentatation & json files in the `./output` directory.
-
-The directory structure should now look like so:
-![Alt text](output_file_structure.png)
-
-### Step 2 - `schemaTools init --config volt.config.json`
-Where the volt.config.json is a volt config file exported for a user on a volt, this initialises the volt connection & builds the schema directory.
-
-![Alt text](volt_export_client_config.png)
-
-### Step 3 - `volt up ./output/* schemas`
-This uploads the output files to the schema directory, the structure in the volt should look like so:
-
-![Alt text](volt_schema_structure.png)
-
-## To create new schemas
-
-To create a new schema run, navigate to src and run:
+To create a new schema run, navigate to `/src` and run:
 ```bash
   schemaTools new-schema <schema_name>
 ```
@@ -50,4 +21,4 @@ required:
   - PROPERTY_ID                                         # Required fields
 examples:
   - EXAMPLE: EXAMPLE_DATA                               # Example data
-```
+```

packages/schemas/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@nqminds/nist-brski-schemas",
+  "name": "@nqinds/cahn-schemas",
   "version": "1.0.0",
   "description": "",
   "main": "index.js",
@@ -8,5 +8,8 @@
   },
   "keywords": [],
   "author": "",
-  "license": "ISC"
+  "license": "ISC",
+  "dependencies": {
+    "@nqminds/verifiable-schemas-toolchain": "^2.0.1"
+  }
 }

packages/schemas/src/allow_to_connect.yaml

@@ -0,0 +1,19 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://github.com/nqminds/CAHN/blob/main/packages/schemas/src/allow_to_connect.v.1.0.0.schema.yaml
+title: Allow to connect
+description: A giving of connection rights from an authorising user to a device
+type: object
+properties:
+  device_id:
+    description: id of the device receiving connection rights
+    type: string
+  authoriser_id:
+    description: id of the authorising user
+    type: string
+  created_at:
+    description: timestamp at which connection rights were given in milliseconds
+    type: integer
+required:
+  - device_id
+  - authoriser_id
+  - created_at

packages/schemas/src/device.yaml

@@ -0,0 +1,27 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://github.com/nqminds/CAHN/blob/main/packages/schemas/src/device.v.1.0.0.schema.yaml
+title: device
+description: A device
+type: object
+properties:
+  id:
+    description: id of the device
+    type: string
+  name:
+    description: user friendly name of the device
+    type: string
+  idevid:
+    description: IDevID  of the device
+    type: string
+  created_at:
+    description: timestamp at which device was created in milliseconds
+    type: integer
+required:
+  - id
+  - name
+  - idevid
+  - created_at
+uniqueKeys:
+  - id
+  - name
+  - idevid

packages/schemas/src/device_type.yaml

@@ -0,0 +1,22 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://github.com/nqminds/CAHN/blob/main/packages/schemas/src/device_type.v.1.0.0.schema.yaml
+title: device type
+description: A device type
+type: object
+properties:
+  id:
+    description: id of the device type
+    type: string
+  name:
+    description: user friendly name of the device type
+    type: string
+  created_at:
+    description: timestamp at which device type was created in milliseconds
+    type: integer
+required:
+  - id
+  - name
+  - created_at
+uniqueKeys:
+  - id
+  - name

packages/schemas/src/gives_connection_rights.yaml

@@ -0,0 +1,19 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://github.com/nqminds/CAHN/blob/main/packages/schemas/src/gives_connection_rights.v.1.0.0.schema.yaml
+title: Gives connection rights
+description: A giving of connection rights from an authorising user to a recipient user
+type: object
+properties:
+  recipient_id:
+    description: id of the user receiving connection rights
+    type: string
+  authoriser_id:
+    description: id of the authorising user
+    type: string
+  created_at:
+    description: timestamp at which connection rights were given in milliseconds
+    type: integer
+required:
+  - recipient_id
+  - authoriser_id
+  - created_at

packages/schemas/src/gives_purchase_rights.yaml

@@ -0,0 +1,19 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://github.com/nqminds/CAHN/blob/main/packages/schemas/src/gives_purchase_rights.v.1.0.0.schema.yaml
+title: Gives purchase rights
+description: A giving of purchase rights from an authorising user to a recipient user
+type: object
+properties:
+  recipient_id:
+    description: id of the user receiving purchase rights
+    type: string
+  authoriser_id:
+    description: id of the authorising user
+    type: string
+  created_at:
+    description: timestamp at which purchase rights were given in milliseconds
+    type: integer
+required:
+  - recipient_id
+  - authoriser_id
+  - created_at

packages/schemas/src/has_mud.yaml

@@ -0,0 +1,19 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://github.com/nqminds/CAHN/blob/main/packages/schemas/src/has_mud.v.1.0.0.schema.yaml
+title: has mud
+description: Binding between a device type and MUD (Manufacturer Usage Description)
+type: object
+properties:
+  mud_id:
+    description: id of the mud
+    type: string
+  device_type_id:
+    description: id of the device type to which the mud applies
+    type: string
+  created_at:
+    description: timestamp at which mud-device binding was created in milliseconds
+    type: integer
+required:
+  - mud_id
+  - device_type_id
+  - created_at

packages/schemas/src/has_sbom.yaml

@@ -0,0 +1,19 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://github.com/nqminds/CAHN/blob/main/packages/schemas/src/has_sbom.v.1.0.0.schema.yaml
+title: has sbom
+description: Binding between a device type and SBOM (Software Bill Of Materials)
+type: object
+properties:
+  sbom_id:
+    description: id of the sbom
+    type: string
+  device_type_id:
+    description: id of the device type to which the sbom applies
+    type: string
+  created_at:
+    description: timestamp at which sbom-device binding was created in milliseconds
+    type: integer
+required:
+  - sbom_id
+  - device_type_id
+  - created_at

packages/schemas/src/is_of_device_type.yaml

@@ -0,0 +1,19 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://github.com/nqminds/CAHN/blob/main/packages/schemas/src/is_of_device_type.v.1.0.0.schema.yaml
+title: is of device type
+description: Binds a device instance to a device type
+type: object
+properties:
+  device_id:
+    description: id of the device
+    type: string
+  device_type_id:
+    description: id of the device type of the device
+    type: string
+  created_at:
+    description: timestamp at which device type binding was created in milliseconds
+    type: integer
+required:
+  - device_id
+  - device_type_id
+  - created_at

packages/schemas/src/manufactured.yaml

@@ -0,0 +1,19 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://github.com/nqminds/CAHN/blob/main/packages/schemas/src/manufactured.v.1.0.0.schema.yaml
+title: manufactured
+description: A manufactured relationship between a device and a manufacturer
+type: object
+properties:
+  device_id:
+    description: id of the device manufactured by the manufacturer
+    type: string
+  manufacturer_id:
+    description: id of the manufacturer of the device
+    type: string
+  created_at:
+    description: timestamp at which manufactured relationship was created in milliseconds
+    type: integer
+required:
+  - device_id
+  - manufacturer_id
+  - created_at

packages/schemas/src/manufacturer.yaml

@@ -0,0 +1,22 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://github.com/nqminds/CAHN/blob/main/packages/schemas/src/manufacturer.v.1.0.0.schema.yaml
+title: manufacturer
+description: A manufacturer
+type: object
+properties:
+  id:
+    description: id of the manufacturer
+    type: string
+  name:
+    description: name of the manufacturer
+    type: string
+  created_at:
+    description: timestamp at which manufacturer was created in milliseconds
+    type: integer
+required:
+  - id
+  - name
+  - created_at
+uniqueKeys:
+  - id
+  - name