Initial commit

valyu-network · Apr 21, 2024 · d3c497f · d3c497f
commit d3c497f
Show file tree

Hide file tree

Showing 19 changed files with 18,411 additions and 0 deletions.
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,9 @@
+node_modules/
+dist/
+.env*.local
+.DS_Store
+coverage/
+*.log
+.env*
+.env
+valyuDID.sqlite
diff --git a/DDOC.md b/DDOC.md
@@ -0,0 +1,169 @@
+# The VALYU DID Method Specification 1.0
+### Abstract
+The `did:valyu` DID method [DID-CORE](https://did-dht.com/#ref:DID-CORE) provides a standardised format for representing both data and users within the Valyu ecosystem. By leveraging the decentralised nature of DIDs, Valyu ensures a robust, tamper-resistant, and universally verifiable system of identification. Whether you're a user contributing to the decentralised data economy or a piece of data being accessed by authorized entities, the Valyu DID is your passport in this new world of ethical data exchange. This document elaborates on the syntax, operations, and the security framework integral to the Valyu DID.
+
+### Valyu DID Format
+The valyu DID method shall be identified by the method name `valyu` in lower case and follow the below given format:
+```
+<did-value> ::= "did:valyu:" <did-type> ":" <valyu-id>
+<did-type> ::= "user" | "data"
+<valyu-id> ::= <chain-id> ":" <ethereum-address>
+<chain-id> ::= <HEXDIG>
+<ethereum-address> ::= "0x" <40HEXDIG>
+
+<HEXDIG> ::= [0-9A-F]
+<40HEXDIG> ::= <HEXDIG> <39HEXDIG> | <HEXDIG>
+<39HEXDIG> ::= <HEXDIG> <38HEXDIG> | <HEXDIG>
+<38HEXDIG> ::= <HEXDIG> <37HEXDIG> | <HEXDIG>
+...
+<1HEXDIG> ::= <HEXDIG>
+```
+
+### Status of the document
+This document is a draft version and the initial iteration of the Valyu DID specification, subject to refinement and expansion in subsequent releases to address broader use cases and integrate learned lessons.
+
+### Valyu DID Document Example
+Example of a user DID Document:
+```
+{
+	"@context": "https://www.w3.org/ns/did/v1",
+	"id": "did:valyu:user:{valyu-id}",
+	"controller": "did:valyu:user:{valyu-id}",
+	"verificationMethod": [
+		{
+		  "id": "did:valyu:user:{valyu-id}#pk1"
+		  "type": "Secp256k1VerificationKey2018",
+		  "controller": "did:valyu:user:{valyu-id}",
+		  "publicKeyHex": "[YOUR PUBLIC KEY IN HEX FORMAT HERE]"
+		}
+	],
+	"authentication: [
+		{
+		  "did:valyu:user:{valyu-id}#pk1"
+		}
+	],
+	"assertionMethod": [ 
+		{
+		   "did:valyu:user:{valyu-id}#pk1"
+		}
+	],
+	"keyAgreement": [
+		{
+		  "id": "did:valyu:user:{valyu-id}#ka1",
+		  "type": "X25519KeyAgreementKey2019",
+		  "controller": "did:valyu:user:{valyu-id}",
+		  "publicKeyHex": "[YOUR PUBLIC KEY IN HEX FORMAT HERE]"
+		}
+	]
+}
+```
+The DID Document represents a user in the valyu network identified by did:valyu:user:{valyu-id}.
+
+- **Controller**: The controller of this DID might be the user themselves or another entity, such as a parent or guardian in cases where the user might not have full control or autonomy over their data.
+- **Verification Method**: The document specifies a Secp256k1VerificationKey2018 as its verification method, with the public key provided in hex format. This key is under the control of the user's DID.
+- **Authentication**: Utilizing the aforementioned verification key (#pk1), this section ensures the user can be cryptographically verified when accessing their data within the valyu network.
+- **Assertion Method**: The user DID uses the verification key (#pk1) for generating zk-proofs.
+- **Key Agreement**: The document establishes a key agreement protocol using the X25519KeyAgreementKey2019. The public key for this protocol is also provided in hex format. This mechanism ensures secure communications and encrypted exchanges between the user and other entities on the valyu network.
+
+---
+An example of a data DID Document:
+```
+{ 
+	"@context": "https://www.w3.org/ns/did/v1",
+	"id": "did:valyu:data:{valyu-id}",
+	"controller": "did:valyu:data:{valyu-id}",
+	"verificationMethod": [
+		{
+		  "id": "did:valyu:user:{valyu-id}#pk1"
+		  "type": "Secp256k1",
+		  "controller": "did:valyu:user:{valyu-id}",
+		  "publicKeyJwt": ""
+		}
+	],
+	"assertionMethod": [ 
+		{
+		   "did:valyu:data:{valyu-id}#pk1"
+		}
+	],
+	"keyAgreement": [
+		{
+		  "id": "did:valyu:user:{valyu-id}#ka1",
+		  "type": "X25519",
+		  "controller": "did:valyu:user:{valyu-id}",
+		  "publicKeyHex": ""
+		}
+	],
+	"service": [
+		{
+		  "id": "#access",
+		  "type": "access",
+		  "serviceEndpoint": "dataservice.valyu.network/{...}"
+		},
+		{
+		  "id": "#compute",
+		  "type": "compute",
+		  "serviceEndpoint" : "dataservice.valyu.network/{...}"
+		}
+	]
+}
+```
+
+The DID Document represents a data object in the valyu network with the identifier did:valyu:data:{valyu-id}.
+
+- **Controller**: The data object is self-sovereign, signified by the controller being the data DID itself.
+- **Verification Method**: It incorporates a verification method with a key using the Secp256k1 elliptic curve. The controller for this verification key is associated with a user DID in the valyu ecosystem.
+- **Assertion Method**: This DID Document uses the previously mentioned verification method (#pk1) for generating zero-knowledge proofs on the data, ensuring data integrity and privacy without revealing the actual content.
+- **Key Agreement**: An X25519 key agreement mechanism is set up, pointing again to a user DID, meant for the data access layer. This ensures secure, encrypted access and exchange of data between parties.
+- **Services**:
+	1. **Access Service**: Offers a direct link for accessing the data on the valyu network via a specific access key.
+	2. **Compute Service**: Provides a computing endpoint, facilitating operations or transformations on the data using a specific compute key.
+
+### Operations
+
+This following section outlines the DID operations for the `did:valyu` method
+#### Create
+##### DID creation algorithm
+###### Overview
+To create a `did:valyu`, use the DID creation service provided as part of the open-source Valyu-DID software (available in the following Github repository: www.github/valyu-networl/ValyuDID). This repository is well documented on the key generation process, and leverages Veramo.io. The process is as follows:
+###### Prerequisites
+- Docker installed on your machine. If Docker is not installed, follow the Docker installation guide.
+###### Steps
+1. Pull the Valyu DID docker image from the dockerhub registry (details on how to do this are provided in: www.github/valyu-networl/ValyuDID)
+2. Run docker container
+3. Once the container is running, you can create a Valyu User or Data DID by calling the /createDID endpoint 
+
+**Note:** The API endpoints have thorough documentation, you can find the Postman collection in the Github repository under the /postman directory
+##### Document creation algorithm
+The DID creation process automatically creates a DID Document for each new DID created
+
+#### Read
+###### Overview
+To read/resolve a `did:valyu` value, use the DID resolution service provided as part of the open-source Valyu-DID software (available in the following Github repository: www.github/valyu-networl/ValyuDID)
+###### Prerequisites
+- Refer to prerequisites described in /DID-creation-algorithm
+###### Steps
+1. Follow steps 1 and 2 described in /DID-creation-algorithm
+2. Once the container is running, you can resolve a `did:valyu` value into it's corresponding DID Document by calling the /resolveDID endpoint
+
+**Note:** The API endpoints have thorough documentation, you can find the Postman collection here: https://api.postman.com/collections/30064176-1c83c789-8580-47d4-8778-1f110f370423?access_key=PMAT-01HW1BWC7376NQYN8CMKZ1VV7G, or in the Github repository under the /postman directory
+
+#### Update
+This method does not *currently* support updating the DID document
+
+#### Deactivate
+This method does not support deactivating the DID document
+
+### Security and Privacy Considerations
+When implementing and using the `did:valyu` method, there are several security and privacy considerations to be aware of to ensure expected and legitimate behaviour.
+###### Single DID restriction
+The Valyu DID specification mandates a one-to-one mapping between a single Ethereum address and a Valyu DID. This constraint ensures that each Ethereum address is uniquely associated with only one Valyu DID, enhancing the clarity and integrity of identity management within the Valyu ecosystem.
+###### Personal identity information
+The Valyu DID method specification does not store any Personal Identifiable Information (PII) within DID documents. This policy ensures compliance with privacy regulations and reduces the risk of sensitive data exposure.
+###### Cryptographic risk
+The security of the Valyu DID system, which utilizes cryptographic keys based on the Secp256k1 and X25519 algorithms as outlined in SEC1 and RFC7748 respectively, is inherently tied to the cryptographic strength of these keys and their underlying algorithms. Should vulnerabilities be discovered in either Secp256k1 or X25519, or if advancements in quantum computing render these cryptographic foundations obsolete, the Valyu DID method could face significant security challenges. To mitigate these risks, ongoing evaluation and potential adaptation of emerging cryptographic techniques will be essential to maintain the robustness and security of the Valyu DID system.
+###### Self or Delegated Control
+The Valyu DID specification accommodates diverse control structures by allowing the controller of a DID to be either the user directly or a delegated authority, such as an organisation or legal guardian. This flexibility is crucial for maintaining user autonomy and ensuring data sovereignty across varied legal and operational contexts.
+
+### References
+###### DID-CORE
+- [Decentralized Identifiers (DIDs) v1.0](https://www.w3.org/TR/did-core/). Drummond Reed; Manu Sporny; Markus Sabadello; Dave Longley; Christopher Allen; Jonathan Holt; 2020-09-07. Status: WD.
diff --git a/Dockerfile b/Dockerfile
@@ -0,0 +1,23 @@
+# Use an official Node.js runtime as the base image
+FROM node:18
+
+# Set the working directory in the container to /app
+WORKDIR /app
+
+# Copy the package.json and package-lock.json files to the container
+COPY package*.json ./
+
+# Install the project dependencies in the container
+RUN npm install
+
+# Copy the rest of the application code to the container
+COPY . .
+
+# Expose the port the app runs on
+EXPOSE 3000
+
+# Define the command to run the app
+CMD ["npm", "start"]
+
+# Set environment variable for node to production
+ENV NODE_ENV=production 
diff --git a/README.md b/README.md
@@ -0,0 +1,121 @@
+# ValyuDID
+
+Welcome to the ValyuDID repository! This project acts as an implementation of the Valyu DID method specification (outlined in DDOC.md), and facilitates the creation and resolution of Valyu DIDs using RESTful APIs, and a simple SQL database.
+
+## Overview 📖
+
+ValyuDID provides a suite of endpoints to manage DIDs, enabling interactions such as creating new DIDs for users and data, and resolving existing DIDs through a custom-built Veramo-based resolver.
+
+## Getting Started 🚀
+
+### Prerequisites 📋
+
+- Node.js (v18 or higher)
+- npm (v8 or higher)
+- Access to `.env` configurations (see example below)
+
+### Setting Up the Environment 🛠️
+
+**Clone the Repository:**
+
+```bash
+git clone https://github.com/valyu-network/valyu-did.git
+cd valyu-did
+```
+
+**Install Dependencies:**
+
+```bash
+npm install
+```
+
+### Configuration 🛠️
+
+**Environment Variables:**
+
+Create a `.env` file in the root directory and populate it with the necessary secrets:
+
+```plaintext
+KMS_SECRET_KEY=<Your_Secret_Key>
+```
+
+The KMS_SECRET_KEY can be any string, like a password. It's used for key management operations within Veramo.
+
+### Running the Project 🌐
+
+Start the server locally with:
+
+```bash
+npm start
+```
+
+This will run the project at `http://localhost:3000`.
+
+## Usage 🛠️
+
+The server exposes three primary endpoints:
+
+- `POST /createUserDID` - Create a new user DID.
+- `POST /createDataDID` - Create a new data DID.
+- `POST /resolveDID` - Resolve an existing DID.
+
+These endpoints allow you to interact with the blockchain and manage DIDs efficiently.
+
+## Postman API Documentation 📚
+
+For comprehensive API testing and documentation, access our Postman collection:
+
+[Valyu-DID Postman Collection](https://api.postman.com/collections/30064176-1c83c789-8580-47d4-8778-1f110f370423?access_key=PMAT-01HW1BWC7376NQYN8CMKZ1VV7G)
+
+This collection includes detailed requests and responses for each endpoint, helping you to effectively integrate and test the Valyu-DID APIs.
+
+### Docker Image 🐳
+
+For those interested in deploying using Docker, the Valyu-DID Docker image is available on DockerHub:
+
+[DockerHub: yorkeccak/valyu-did](https://hub.docker.com/repository/docker/yorkeccak/valyu-did/general)
+
+### APIs Included in the Collection:
+
+- **Create Data DID (POST /createDataDID)**: Create a new data DID.
+  - Request Body: `alias`, `dataTokenAddress`, `chainId`, `accessEndpoint`.
+  - Success Response: Returns a DID document for the registered data asset.
+
+- **Create User DID (POST /createUserDID)**: Create a new user DID.
+  - Request Body: `alias` (required).
+  - Success Response: Returns a DID document for the newly created user identity.
+
+- **Resolve DID (POST /resolveDID)**: Resolve a DID and retrieve the associated DID document.
+  - Request Body: `did` (required).
+  - Success Response: Returns the resolved DID document.
+
+## Contributing 🤝
+
+We welcome contributions from the community! Please follow these steps:
+
+- Fork the repository.
+- Create a new branch for your feature.
+- Commit your changes.
+- Push to the branch.
+- Submit a pull request.
+
+### Conventions
+
+- Use camelCase for variable names and function names.
+- Keep functions small and focused.
+- Document your code where necessary.
+
+## Docker Deployment 🐳
+
+This project includes a Dockerfile for building and running the app in a containerized environment. To build and run the Docker container, use:
+
+```bash
+docker build -t valyudid .
+docker run -p 3000:3000 valyudid
+```
+
+This will expose the application on port 3000, accessible via `http://localhost:3000`.
+
+## License 📄
+
+This project is currently unlicensed and proprietary. Please contact us for any inquiries regarding usage or licensing.