From 7c40911649526fcbdb1427f8d50689c2135d99b3 Mon Sep 17 00:00:00 2001 From: chendiblessing Date: Fri, 15 Nov 2024 09:21:09 +0100 Subject: [PATCH 01/14] feat: init Architecture doc --- docs/Architecture.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 docs/Architecture.md diff --git a/docs/Architecture.md b/docs/Architecture.md new file mode 100644 index 00000000..1e87058d --- /dev/null +++ b/docs/Architecture.md @@ -0,0 +1,35 @@ +# DIDComm Mediator Architecture Document + +### **Table of Contents** +- [**DIDComm Mediator Architecture Document**](#didcomm-mediator-architecture-document) +- [**Table of Contents**](#table-of-contents) +- [**1. Introduction**](#1-introduction) + - [**1.1 Purpose**](#11-purpose) + - [**1.2 System Overview**](#12-system-overview) + - [**1.3 Scope**](#13-scope) + - [**1.4 Stakeholders**](#14-stakeholders) + - [**1.5 Definitions and Acronyms**](#15-definitions-and-acronyms) +- [**2. Constraints**](#2-constraints) + +## 1. Introduction +### 1.1 Purpose +This document provides a detailed architecture for the DIDComm Mediator, a system designed to mediate communication between decentralized identities (DIDs) using the DIDComm protocol. The document outlines the design decisions, components, and interactions in the system. + +### 1.2 System Overview +The DIDComm Mediator acts as an intermediary that forwards messages between decentralized identifiers (DIDs) while maintaining security, privacy, and scalability. It adheres to the DIDComm messaging protocol, enabling seamless communication between agents. + +### 1.3 Scope +The DIDComm Mediator serves as an intermediary for decentralized communication, supporting DIDComm messages over secure channels, forwarding, and routing messages to the appropriate endpoints + +### 1.4 Stakeholders +Key stakeholders include DATEV, the adorsys development team, and third-party developers + +### 1.5 Definitions and Acronyms +- ***DID(Decentralized Identifier):*** A unique identifier that enables verifiable, self-sovereign identities +- ***DIDComm:*** A secure messaging protocol used to communicate over decentralized networks +- ***Mediator:*** An intermediary service that routes DIDComm messages between agents + +# 2. Constraints +- The project will be implemented in rust so as to take advantage of it's performance and safety features +- Only asynchronous Rust frameworks like tokio, axum, hyper, tracing can be used to ensure non-blocking operations +- The project must adhere to DIDComm V2 specifications \ No newline at end of file From 88f825568a13c540a692c1b941554401bac8274b Mon Sep 17 00:00:00 2001 From: chendiblessing Date: Fri, 15 Nov 2024 09:49:28 +0100 Subject: [PATCH 02/14] updated: the arch doc --- docs/Architecture.md | 32 ++++++++++++++++++++++---------- 1 file changed, 22 insertions(+), 10 deletions(-) diff --git a/docs/Architecture.md b/docs/Architecture.md index 1e87058d..8d36b6dc 100644 --- a/docs/Architecture.md +++ b/docs/Architecture.md @@ -6,10 +6,13 @@ - [**1. Introduction**](#1-introduction) - [**1.1 Purpose**](#11-purpose) - [**1.2 System Overview**](#12-system-overview) - - [**1.3 Scope**](#13-scope) + - [**1.3 Quality Goals**](#13-quality-goals) - [**1.4 Stakeholders**](#14-stakeholders) - - [**1.5 Definitions and Acronyms**](#15-definitions-and-acronyms) - [**2. Constraints**](#2-constraints) +- [**3. System Scope and Context**](#3-system-scope-and-context) + - [**3.1 Business Context**](#31-business-context) + - [**3.2 Technical Context**](#32-technical-context) +- [**12. Glossary**](#12-glossary) ## 1. Introduction ### 1.1 Purpose @@ -18,18 +21,27 @@ This document provides a detailed architecture for the DIDComm Mediator, a syste ### 1.2 System Overview The DIDComm Mediator acts as an intermediary that forwards messages between decentralized identifiers (DIDs) while maintaining security, privacy, and scalability. It adheres to the DIDComm messaging protocol, enabling seamless communication between agents. -### 1.3 Scope -The DIDComm Mediator serves as an intermediary for decentralized communication, supporting DIDComm messages over secure channels, forwarding, and routing messages to the appropriate endpoints +### 1.3 Quality Goals +- ***Security***: End-to-End encryption and authentication. +- ***Scalability***: Handle high message volume efficiently. +- ***Reliability***: Ensure fault tolerance and high availability +- ***Extensibility***: Support future enhancements and additional DID methods ### 1.4 Stakeholders Key stakeholders include DATEV, the adorsys development team, and third-party developers -### 1.5 Definitions and Acronyms -- ***DID(Decentralized Identifier):*** A unique identifier that enables verifiable, self-sovereign identities -- ***DIDComm:*** A secure messaging protocol used to communicate over decentralized networks -- ***Mediator:*** An intermediary service that routes DIDComm messages between agents - # 2. Constraints - The project will be implemented in rust so as to take advantage of it's performance and safety features - Only asynchronous Rust frameworks like tokio, axum, hyper, tracing can be used to ensure non-blocking operations -- The project must adhere to DIDComm V2 specifications \ No newline at end of file +- The project must adhere to DIDComm V2 specifications + +# 3. System Scope and Context +### 3.1 Business Context +The DIDComm Mediator acts as a bridge to enable seemless communication between decentralized agents, ensuring secure and reliable message routing. + +### 3.2 Technical Context + +# 12. Glossary +- ***DID(Decentralized Identifier):*** A unique identifier that enables verifiable, self-sovereign identities +- ***DIDComm:*** A secure messaging protocol used to communicate over decentralized networks +- ***Mediator:*** An intermediary service that routes DIDComm messages between agents From 9f2e3ff3dd0eed6a921c1c827cb1b2993753f23a Mon Sep 17 00:00:00 2001 From: chendiblessing Date: Mon, 18 Nov 2024 10:00:48 +0100 Subject: [PATCH 03/14] updated: with the template of the arch document --- docs/Architecture.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/Architecture.md b/docs/Architecture.md index 8d36b6dc..2fd13f38 100644 --- a/docs/Architecture.md +++ b/docs/Architecture.md @@ -12,6 +12,14 @@ - [**3. System Scope and Context**](#3-system-scope-and-context) - [**3.1 Business Context**](#31-business-context) - [**3.2 Technical Context**](#32-technical-context) +- [**4. Solution Strategy**](#4-solution-strategy) +- [**5. Building Block View**](#5-building-block-view) +- [**6. Runtime View**](#6-runtime-view) +- [**7. Deployment View**](#7-deployment-view) +- [**8. Cross Cutting Concerns**](#8-cross-cutting-concerns) +- [**9. Architectural Decisions**](#9-architectural-decisions) +- [**10. Quality Requirements**](#10-quality-requirements) +- [**11. Risk and Technical Debt**](#11-risk-and-technical-debt) - [**12. Glossary**](#12-glossary) ## 1. Introduction @@ -40,6 +48,23 @@ Key stakeholders include DATEV, the adorsys development team, and third-party de The DIDComm Mediator acts as a bridge to enable seemless communication between decentralized agents, ensuring secure and reliable message routing. ### 3.2 Technical Context +![images](work-flow.png) + +# 4. Solution Strategy + +# 5. Building Block View + +# 6. Runtime View + +# 7. Deployment View + +# 8. Cross Cutting Concerns + +# 9. Architectural Decisions + +# 10. Quality Requirements + +# 11. Risk and Technical Debt # 12. Glossary - ***DID(Decentralized Identifier):*** A unique identifier that enables verifiable, self-sovereign identities From fcfd75662931a6a34dfe27d452c321cb6c7400e3 Mon Sep 17 00:00:00 2001 From: Tekum Emmaanuella Date: Tue, 19 Nov 2024 09:32:06 +0100 Subject: [PATCH 04/14] Added the technical context to. --- docs/Architecture.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/docs/Architecture.md b/docs/Architecture.md index 2fd13f38..d05468e4 100644 --- a/docs/Architecture.md +++ b/docs/Architecture.md @@ -50,6 +50,43 @@ The DIDComm Mediator acts as a bridge to enable seemless communication between d ### 3.2 Technical Context ![images](work-flow.png) +The DIDComm Mediator operates within decentralized identity systems, leveraging the DIDComm protocol and Decentralized Identifiers (DIDs) to provide secure and scalable communication between agents. + +***Key Technical Considerations** +- ***DIDComm Protocol:** Provides secure messaging with end-to-end encryption and authentication, creating a secure communication channel between decentralized agents. +- ***Decentralized Identifiers (DIDs):** Unique identifiers that enable self-sovereign, verifiable identities within the system. +- ***Secure Messaging Mechanisms:** TLS and other mechanisms ensure confidentiality and integrity of messages during transmission. +- ***Asynchronous Rust Frameworks:** Utilizes libraries such as tokio, axum, hyper, and tracing for high-performance, non-blocking operations. +- ***Adherence to Specifications:** The system adheres to the DIDComm V2 specifications for compatibility and standardization. + +***Core Components and Responsibilities** +- ***Mediator Core Module:** The central component responsible for receiving, storing, and routing messages while ensuring DIDComm V2 compliance. +- ***DID Resolver:** Interfaces with decentralized networks/registries to validate and retrieve DID documents, enabling proper routing based on public keys or routing details. +- ***Message Handling and Routing:** Supports various DIDComm message types (e.g., forward messages) and ensures robust routing based on recipient details. +- ***Message Storage** Temporarily stores messages until recipients retrieve them, using optimized storage mechanisms and asynchronous I/O. + +***Key Technical Challenges** +- ***Message Confidentiality and Integrity:** Ensures messages remain secure and tamper-proof with end-to-end encryption and compliance with security standards. +- ***Performance Optimization:** Handles high message volumes using asynchronous Rust frameworks (tokio, hyper) to ensure scalable, non-blocking operations. +- ***Message Routing and Delivery:** Supports various DIDComm message types (e.g., forward messages) and ensures proper routing based on recipient details. + +***External Integrations** +- ***DID Registries and Networks**: Communicates with registries to perform reliable DID resolution. +- ***External Agents and Clients:** Interfaces with clients such as mobile and desktop applications for secure message routing. +- ***Verifiable Credential Systems:** Potentially integrates with credential issuance and verification workflows. + +***System Architecture Considerations** +- ***Security Protocols:** Implements TLS alongside end-to-end encryption within the DIDComm protocol, prioritizing security across all layers. +- ***Asynchronous Communication**: Uses asynchronous programming (via tokio and similar libraries) to manage high throughput without blocking operations. + +***Technology Choices:** +- ***Rust:** Rust language Chosen for memory safety, performance, and strong concurrency support. + +***Key Libraries:** +- ***serde:** For efficient serialization/deserialization. +- ***actix-web / axum:** Handles HTTP requests/web socket connections (based on the preferred framework). +- ***didkit (if applicable):** Supports DID operations, creation, and verification. + # 4. Solution Strategy # 5. Building Block View From fdc1da81dd7fe5ffd7c0c7d0920b708f024a71e9 Mon Sep 17 00:00:00 2001 From: chendiblessing Date: Tue, 19 Nov 2024 10:12:45 +0100 Subject: [PATCH 05/14] added:technological decisions on solution strategy --- docs/Architecture.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/Architecture.md b/docs/Architecture.md index 2fd13f38..50cc85e6 100644 --- a/docs/Architecture.md +++ b/docs/Architecture.md @@ -51,6 +51,12 @@ The DIDComm Mediator acts as a bridge to enable seemless communication between d ![images](work-flow.png) # 4. Solution Strategy +The solution strategy outlines the foundational decisions that guide the system's architecture, aligning with the key quality goals, constraints, and overall system requirements. + +**Technology Decisions** +- **Programming Language**: Rust is chosen for its high performance, memory safety, and strong concurrency support. This decision aligns with the security and scalability goals of the mediator. +- **Cryptographic Libraries:** Askar is selected as the cryptographic library to provide high-level cryptographic functions specifically designed for decentralized identity systems. Askar offers key management, encryption, and decryption capabilities that are essential for DIDComm communication. Its focus on modularity and interoperability with other decentralized identity (DID) systems ensures that the system can evolve and stay secure over time. +- **Database:** MongoDB is selected as the database for its flexibility in handling semi-structured data, scalability, and ease of horizontal scaling. It is ideal for storing DID-related metadata, messages, and other data in a schema-less format that can adapt as the system evolves. # 5. Building Block View From cbb880c8290a2729084fed046ad17adee33b1bd7 Mon Sep 17 00:00:00 2001 From: Tekum Emmaanuella Date: Tue, 19 Nov 2024 12:58:10 +0100 Subject: [PATCH 06/14] Added the technical context to. --- docs/Architecture.md | 68 ++++++++++++++++++++++---------------------- 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/docs/Architecture.md b/docs/Architecture.md index d05468e4..9d71c6b8 100644 --- a/docs/Architecture.md +++ b/docs/Architecture.md @@ -52,40 +52,40 @@ The DIDComm Mediator acts as a bridge to enable seemless communication between d The DIDComm Mediator operates within decentralized identity systems, leveraging the DIDComm protocol and Decentralized Identifiers (DIDs) to provide secure and scalable communication between agents. -***Key Technical Considerations** -- ***DIDComm Protocol:** Provides secure messaging with end-to-end encryption and authentication, creating a secure communication channel between decentralized agents. -- ***Decentralized Identifiers (DIDs):** Unique identifiers that enable self-sovereign, verifiable identities within the system. -- ***Secure Messaging Mechanisms:** TLS and other mechanisms ensure confidentiality and integrity of messages during transmission. -- ***Asynchronous Rust Frameworks:** Utilizes libraries such as tokio, axum, hyper, and tracing for high-performance, non-blocking operations. -- ***Adherence to Specifications:** The system adheres to the DIDComm V2 specifications for compatibility and standardization. - -***Core Components and Responsibilities** -- ***Mediator Core Module:** The central component responsible for receiving, storing, and routing messages while ensuring DIDComm V2 compliance. -- ***DID Resolver:** Interfaces with decentralized networks/registries to validate and retrieve DID documents, enabling proper routing based on public keys or routing details. -- ***Message Handling and Routing:** Supports various DIDComm message types (e.g., forward messages) and ensures robust routing based on recipient details. -- ***Message Storage** Temporarily stores messages until recipients retrieve them, using optimized storage mechanisms and asynchronous I/O. - -***Key Technical Challenges** -- ***Message Confidentiality and Integrity:** Ensures messages remain secure and tamper-proof with end-to-end encryption and compliance with security standards. -- ***Performance Optimization:** Handles high message volumes using asynchronous Rust frameworks (tokio, hyper) to ensure scalable, non-blocking operations. -- ***Message Routing and Delivery:** Supports various DIDComm message types (e.g., forward messages) and ensures proper routing based on recipient details. - -***External Integrations** -- ***DID Registries and Networks**: Communicates with registries to perform reliable DID resolution. -- ***External Agents and Clients:** Interfaces with clients such as mobile and desktop applications for secure message routing. -- ***Verifiable Credential Systems:** Potentially integrates with credential issuance and verification workflows. - -***System Architecture Considerations** -- ***Security Protocols:** Implements TLS alongside end-to-end encryption within the DIDComm protocol, prioritizing security across all layers. -- ***Asynchronous Communication**: Uses asynchronous programming (via tokio and similar libraries) to manage high throughput without blocking operations. - -***Technology Choices:** -- ***Rust:** Rust language Chosen for memory safety, performance, and strong concurrency support. - -***Key Libraries:** -- ***serde:** For efficient serialization/deserialization. -- ***actix-web / axum:** Handles HTTP requests/web socket connections (based on the preferred framework). -- ***didkit (if applicable):** Supports DID operations, creation, and verification. +* **Key Technical Considerations** +- * **DIDComm Protocol:** Provides secure messaging with end-to-end encryption and authentication, creating a secure communication channel between decentralized agents. +- * **Decentralized Identifiers (DIDs):** Unique identifiers that enable self-sovereign, verifiable identities within the system. +- * **Secure Messaging Mechanisms:** TLS and other mechanisms ensure confidentiality and integrity of messages during transmission. +- * **Asynchronous Rust Frameworks:** Utilizes libraries such as tokio, axum, hyper, and tracing for high-performance, non-blocking operations. +- * **Adherence to Specifications:** The system adheres to the DIDComm V2 specifications for compatibility and standardization. + +* **Core Components and Responsibilities** +- * **Mediator Core Module:** The central component responsible for receiving, storing, and routing messages while ensuring DIDComm V2 compliance. +- * **DID Resolver:** Interfaces with decentralized networks/registries to validate and retrieve DID documents, enabling proper routing based on public keys or routing details. +- * **Message Handling and Routing:** Supports various DIDComm message types (e.g., forward messages) and ensures robust routing based on recipient details. +- * **Message Storage** Temporarily stores messages until recipients retrieve them, using optimized storage mechanisms and asynchronous I/O. + +* **Key Technical Challenges** +- * **Message Confidentiality and Integrity:** Ensures messages remain secure and tamper-proof with end-to-end encryption and compliance with security standards. +- * **Performance Optimization:** Handles high message volumes using asynchronous Rust frameworks (tokio, hyper) to ensure scalable, non-blocking operations. +- * **Message Routing and Delivery:** Supports various DIDComm message types (e.g., forward messages) and ensures proper routing based on recipient details. + +* **External Integrations** +- * **DID Registries and Networks**: Communicates with registries to perform reliable DID resolution. +- * **External Agents and Clients:** Interfaces with clients such as mobile and desktop applications for secure message routing. +- * **Verifiable Credential Systems:** Potentially integrates with credential issuance and verification workflows. + +* **System Architecture Considerations** +- * **Security Protocols:** Implements TLS alongside end-to-end encryption within the DIDComm protocol, prioritizing security across all layers. +- * **Asynchronous Communication**: Uses asynchronous programming (via tokio and similar libraries) to manage high throughput without blocking operations. + +* **Technology Choices:** +- * **Rust:** Rust language Chosen for memory safety, performance, and strong concurrency support. + +* **Key Libraries:** +- * **serde:** For efficient serialization/deserialization. +- * **actix-web / axum:** Handles HTTP requests/web socket connections (based on the preferred framework). +- * **didkit (if applicable):** Supports DID operations, creation, and verification. # 4. Solution Strategy From 3b293eec3fc1b286037228d11bfb0c7ac3eba514 Mon Sep 17 00:00:00 2001 From: chendiblessing Date: Tue, 19 Nov 2024 15:22:10 +0100 Subject: [PATCH 07/14] updated:solution strategy --- docs/Architecture.md | 94 +++++++++++++++++++++++--------------------- 1 file changed, 50 insertions(+), 44 deletions(-) diff --git a/docs/Architecture.md b/docs/Architecture.md index 948b4b3f..21d60341 100644 --- a/docs/Architecture.md +++ b/docs/Architecture.md @@ -38,12 +38,12 @@ The DIDComm Mediator acts as an intermediary that forwards messages between dece ### 1.4 Stakeholders Key stakeholders include DATEV, the adorsys development team, and third-party developers -# 2. Constraints +## 2. Constraints - The project will be implemented in rust so as to take advantage of it's performance and safety features - Only asynchronous Rust frameworks like tokio, axum, hyper, tracing can be used to ensure non-blocking operations - The project must adhere to DIDComm V2 specifications -# 3. System Scope and Context +## 3. System Scope and Context ### 3.1 Business Context The DIDComm Mediator acts as a bridge to enable seemless communication between decentralized agents, ensuring secure and reliable message routing. @@ -52,40 +52,40 @@ The DIDComm Mediator acts as a bridge to enable seemless communication between d The DIDComm Mediator operates within decentralized identity systems, leveraging the DIDComm protocol and Decentralized Identifiers (DIDs) to provide secure and scalable communication between agents. -***Key Technical Considerations** -- ***DIDComm Protocol:** Provides secure messaging with end-to-end encryption and authentication, creating a secure communication channel between decentralized agents. -- ***Decentralized Identifiers (DIDs):** Unique identifiers that enable self-sovereign, verifiable identities within the system. -- ***Secure Messaging Mechanisms:** TLS and other mechanisms ensure confidentiality and integrity of messages during transmission. -- ***Asynchronous Rust Frameworks:** Utilizes libraries such as tokio, axum, hyper, and tracing for high-performance, non-blocking operations. -- ***Adherence to Specifications:** The system adheres to the DIDComm V2 specifications for compatibility and standardization. - -***Core Components and Responsibilities** -- ***Mediator Core Module:** The central component responsible for receiving, storing, and routing messages while ensuring DIDComm V2 compliance. -- ***DID Resolver:** Interfaces with decentralized networks/registries to validate and retrieve DID documents, enabling proper routing based on public keys or routing details. -- ***Message Handling and Routing:** Supports various DIDComm message types (e.g., forward messages) and ensures robust routing based on recipient details. -- ***Message Storage** Temporarily stores messages until recipients retrieve them, using optimized storage mechanisms and asynchronous I/O. - -***Key Technical Challenges** -- ***Message Confidentiality and Integrity:** Ensures messages remain secure and tamper-proof with end-to-end encryption and compliance with security standards. -- ***Performance Optimization:** Handles high message volumes using asynchronous Rust frameworks (tokio, hyper) to ensure scalable, non-blocking operations. -- ***Message Routing and Delivery:** Supports various DIDComm message types (e.g., forward messages) and ensures proper routing based on recipient details. - -***External Integrations** -- ***DID Registries and Networks**: Communicates with registries to perform reliable DID resolution. -- ***External Agents and Clients:** Interfaces with clients such as mobile and desktop applications for secure message routing. -- ***Verifiable Credential Systems:** Potentially integrates with credential issuance and verification workflows. - -***System Architecture Considerations** -- ***Security Protocols:** Implements TLS alongside end-to-end encryption within the DIDComm protocol, prioritizing security across all layers. -- ***Asynchronous Communication**: Uses asynchronous programming (via tokio and similar libraries) to manage high throughput without blocking operations. - -***Technology Choices:** -- ***Rust:** Rust language Chosen for memory safety, performance, and strong concurrency support. - -***Key Libraries:** -- ***serde:** For efficient serialization/deserialization. -- ***actix-web / axum:** Handles HTTP requests/web socket connections (based on the preferred framework). -- ***didkit (if applicable):** Supports DID operations, creation, and verification. +**Key Technical Considerations** +- **DIDComm Protocol:** Provides secure messaging with end-to-end encryption and authentication, creating a secure communication channel between decentralized agents. +- **Decentralized Identifiers (DIDs):** Unique identifiers that enable self-sovereign, verifiable identities within the system. +- **Secure Messaging Mechanisms:** TLS and other mechanisms ensure confidentiality and integrity of messages during transmission. +- **Asynchronous Rust Frameworks:** Utilizes libraries such as tokio, axum, hyper, and tracing for high-performance, non-blocking operations. +- **Adherence to Specifications:** The system adheres to the DIDComm V2 specifications for compatibility and standardization. + +**Core Components and Responsibilities** +- **Mediator Core Module:** The central component responsible for receiving, storing, and routing messages while ensuring DIDComm V2 compliance. +- **DID Resolver:** Interfaces with decentralized networks/registries to validate and retrieve DID documents, enabling proper routing based on public keys or routing details. +- **Message Handling and Routing:** Supports various DIDComm message types (e.g., forward messages) and ensures robust routing based on recipient details. +- **Message Storage** Temporarily stores messages until recipients retrieve them, using optimized storage mechanisms and asynchronous I/O. + +**Key Technical Challenges** +- **Message Confidentiality and Integrity:** Ensures messages remain secure and tamper-proof with end-to-end encryption and compliance with security standards. +- **Performance Optimization:** Handles high message volumes using asynchronous Rust frameworks (tokio, hyper) to ensure scalable, non-blocking operations. +- **Message Routing and Delivery:** Supports various DIDComm message types (e.g., forward messages) and ensures proper routing based on recipient details. + +**External Integrations** +- **DID Registries and Networks**: Communicates with registries to perform reliable DID resolution. +- **External Agents and Clients:** Interfaces with clients such as mobile and desktop applications for secure message routing. +- **Verifiable Credential Systems:** Potentially integrates with credential issuance and verification workflows. + +**System Architecture Considerations** +- **Security Protocols:** Implements TLS alongside end-to-end encryption within the DIDComm protocol, prioritizing security across all layers. +- **Asynchronous Communication**: Uses asynchronous programming (via tokio and similar libraries) to manage high throughput without blocking operations. + +**Technology Choices:** +- **Rust:** Rust language Chosen for memory safety, performance, and strong concurrency support. + +**Key Libraries:** +- **serde:** For efficient serialization/deserialization. +- **actix-web / axum:** Handles HTTP requests/web socket connections (based on the preferred framework). +- **didkit (if applicable):** Supports DID operations, creation, and verification. # 4. Solution Strategy The solution strategy outlines the foundational decisions that guide the system's architecture, aligning with the key quality goals, constraints, and overall system requirements. @@ -95,21 +95,27 @@ The solution strategy outlines the foundational decisions that guide the system' - **Cryptographic Libraries:** Askar is selected as the cryptographic library to provide high-level cryptographic functions specifically designed for decentralized identity systems. Askar offers key management, encryption, and decryption capabilities that are essential for DIDComm communication. Its focus on modularity and interoperability with other decentralized identity (DID) systems ensures that the system can evolve and stay secure over time. - **Database:** MongoDB is selected as the database for its flexibility in handling semi-structured data, scalability, and ease of horizontal scaling. It is ideal for storing DID-related metadata, messages, and other data in a schema-less format that can adapt as the system evolves. -# 5. Building Block View +**Organisational Decisions** +- **Development Process:**Agile methodology is adopted to deliver incremental updates and adapt to changing requirements. +- **Task Delegation:** Integration with external DID registries is modularized, enabling future partnerships with third-party providers for registry or DID resolution services. +- **Team Structure:** Assign dedicated team to core components (e.g., Mediator Core, Key Management, Communication Interfaces) for focused development and testing. -# 6. Runtime View -# 7. Deployment View +## 5. Building Block View -# 8. Cross Cutting Concerns +## 6. Runtime View -# 9. Architectural Decisions +## 7. Deployment View -# 10. Quality Requirements +## 8. Cross Cutting Concerns -# 11. Risk and Technical Debt +## 9. Architectural Decisions -# 12. Glossary +## 10. Quality Requirements + +## 11. Risk and Technical Debt + +## 12. Glossary - ***DID(Decentralized Identifier):*** A unique identifier that enables verifiable, self-sovereign identities - ***DIDComm:*** A secure messaging protocol used to communicate over decentralized networks - ***Mediator:*** An intermediary service that routes DIDComm messages between agents From bf501afcc941ac8ef18fcd6ab2913d885e30142d Mon Sep 17 00:00:00 2001 From: Francis Pouatcha Date: Wed, 20 Nov 2024 11:54:41 +0100 Subject: [PATCH 08/14] Initial setup of the architecture document Signed-off-by: Francis Pouatcha --- docs/arc42.md | 558 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 558 insertions(+) create mode 100644 docs/arc42.md diff --git a/docs/arc42.md b/docs/arc42.md new file mode 100644 index 00000000..4ce83521 --- /dev/null +++ b/docs/arc42.md @@ -0,0 +1,558 @@ +Here is an ARC42 architecture document tailored for the Rust-based `didcomm-mediator-rs` project. The document focuses on operational aspects while addressing project-specific nuances. + +--- + +# DIDComm Mediator RS - ARC42 Architecture Documentation + +## Table of Contents +1. [Introduction](#introduction) +2. [Architecture Constraints](#architecture-constraints) +3. [System Scope and Context](#system-scope-and-context) +4. [Solution Strategy](#solution-strategy) +5. [Building Block View](#building-block-view) +6. [Runtime View](#runtime-view) +7. [Deployment View](#deployment-view) +8. [Cross-cutting Concepts](#cross-cutting-concepts) +9. [Architecture Decisions](#architecture-decisions) +10. [Quality Requirements](#quality-requirements) +11. [Risks and Technical Debt](#risks-and-technical-debt) +12. [Product Management](#product-management) +13. [Glossary](#glossary) +14. [Appendix](#appendix) + +--- + +## 1. Introduction + +### 1.1 Document Goals +This document outlines the architecture of the `didcomm-mediator-rs`, a Rust-based implementation of a DIDComm v2 mediator. Its purpose is to ensure secure, efficient, and reliable routing of DIDComm messages while providing clarity to stakeholders, architects, and developers. + +### 1.2 Stakeholders +- **Product Owners**: Define feature requirements. +- **Developers**: Build and maintain the mediator. +- **Operations Team**: Deploy and monitor the mediator in production. +- **Compliance Teams**: Ensure adherence to privacy and security regulations. +- **DIDComm Users**: End-users leveraging decentralized identity systems. + +--- + +## 2. Architecture Constraints + +### 2.1 Technical Constraints +- **Rust Programming Language**: Ensures high performance and memory safety. +- **Transport Agnosticism**: Supports various protocols (HTTP, Bluetooth, etc.). +- **No External State**: Minimal reliance on external systems for scalability. + +### 2.2 Regulatory Constraints +- **Privacy Compliance**: Aligns with GDPR and similar regulations. +- **Decentralized Design**: Eliminates central authority dependencies. + +--- + +## 3. System Scope and Context + +### 3.1 Business Context +The mediator facilitates routing of DIDComm messages for agents unable to maintain direct communication channels. It acts as an intermediary, ensuring reliability and privacy. + +### 3.2 External Components +- **DIDComm Agents**: Sending and receiving agents. +- **Transport Protocols**: Various transport layers, e.g., HTTP or WebSockets. +- **Cloud Infrastructure**: For scalable and fault-tolerant deployments. + +### 3.3 Component Diagram +```mermaid +graph LR + Agent1[Agent 1] --> Transport1 + Transport1 --> Mediator1 + Mediator1 --> Mediator2 + Mediator2 --> Transport2 + Transport2 --> Agent2[Agent 2] +``` + +--- + +## 4. Solution Strategy +A microservices approach ensures modularity and scalability. `didcomm-mediator-rs` employs Rust's async capabilities to handle concurrent message routing efficiently. + +### Key Features: +The `didcomm-mediator-rs` project implements several essential protocols in the DIDComm v2 ecosystem, as outlined below: + +| **Feature** | **Specification Status** | **Implementation Status** | +|-----------------------------------------|---------------------------|----------------------------| +| **Mediator Coordination Protocol** | Adopted | ✅ Implemented | +| **Pickup Protocol** | Adopted | ✅ Implemented | +| **DID Rotation** | Accepted | ✅ Implemented | +| **Cross-Domain Messaging/Routing Protocol** | Adopted | ✅ Implemented | +| **Trust Ping Protocol** | Adopted | ✅ Implemented | +| **Discover Features Protocol** | Adopted | ⚪ In Progress | +| **Out-of-Band Messaging** | Adopted | ⚪ In Progress | +| **Basic Message Protocol** | Adopted | ⚪ In Progress | +| **Acknowledgments (Acks)** | Adopted | ❌ Not Implemented | +| **Present Proof Protocol** | Adopted | ❌ Not Implemented | + +### Key Highlights: +1. **Implemented Protocols**: + - The mediator is fully equipped with foundational protocols like **Mediator Coordination**, **Pickup**, and **DID Rotation**, ensuring secure and reliable DIDComm message handling. + - **Cross-Domain Messaging** facilitates communication across diverse network boundaries, enhancing interoperability. + +2. **In Progress Features**: + - **Discover Features Protocol** and **Out-of-Band Messaging** are under development to expand functionality. + - **Basic Message Protocol** will enable straightforward message exchanges between agents. + +3. **Future Development**: + - Support for **Acknowledgments (Acks)** and the **Present Proof Protocol** is planned, targeting comprehensive compliance with DIDComm standards. + +This modular and extensible implementation ensures the mediator evolves with the SSI ecosystem while maintaining high standards for security and performance. + +--- + +## 5. Building Block View + +### 5.1 Overview + +The `didcomm-mediator-rs` project utilizes a plugin-based architecture, allowing modular and extensible implementation of DIDComm messaging protocols. The architecture is divided into two key plugin layers: + +1. **Web Plugin Layer**: + - Enables plug-and-play of web endpoints. + - Currently used to implement features such as DID endpoints, out-of-band messages, and DIDComm messaging. + +2. **DIDComm Messaging Plugin Layer**: + - Facilitates incremental addition of DIDComm sub-protocols. + - Modular implementation ensures support for future protocols without major refactoring. + +### 5.2 Detailed View + +#### Top-Level Architecture + +At the core is the **Generic Server**, responsible for hosting the overall application and enabling the plugin system. The main components are: + +1. **Dispatcher**: Routes incoming requests to the appropriate web plugin. +2. **Web Plugin Layer**: Hosts modular implementations for endpoint-specific logic (e.g., DID endpoint generation, out-of-band messages). +3. **Common DIDComm Processing**: Handles general DIDComm request/response processing applicable across sub-protocols. + +#### DIDComm Messaging Plugin Layer + +Nested within the DIDComm Messaging endpoint is another plugin system for managing sub-protocols. This includes: + +1. **Forward Protocol**: Handles message routing across agents. +2. **Pickup Protocol**: Manages message retrieval by offline agents. +3. **Mediator Coordination Protocol**: Supports agent registration and mediation setup. +4. **Plugin Utilities**: Shared utilities that facilitate sub-protocol implementations. + +### 5.3 Building Block Diagram + +The following diagram illustrates the layered architecture with the plugin-based system: + +```mermaid +graph TD + GenericServer[Generic Server] --> Dispatcher[Dispatcher] + Dispatcher --> WebPluginLayer[Web Plugin Layer] + WebPluginLayer --> DIDEndpoint[DID Endpoint] + WebPluginLayer --> OOBMessaging[Out-of-Band Messages] + WebPluginLayer --> DIDCommMessaging[DIDComm Messaging Endpoint] + DIDCommMessaging --> CommonProcessing[Common DIDComm Processing] + DIDCommMessaging --> MessagingPlugins[Messaging Plugin Layer] + MessagingPlugins --> Forward[Forward Protocol] + MessagingPlugins --> Pickup[Pickup Protocol] + MessagingPlugins --> Coordination[Mediator Coordination Protocol] + MessagingPlugins --> Trustping[Trust Ping Protocol] +``` + +--- + +### 5.4 Key Advantages of Plugin Architecture + +1. **Modularity**: Each protocol or feature can be independently developed, tested, and deployed. +2. **Extensibility**: New protocols or endpoints can be added without significant architectural changes. +3. **Scalability**: Lightweight plugins ensure efficient handling of additional features and traffic. + +--- + +## 6. Runtime View + +### 6.1 Message Flow +1. Agent sends a message to the mediator. +2. Mediator stores or forwards the message based on the recipient's status. +3. Recipient retrieves the message via the pickup protocol. + +### Sequence Diagram +```mermaid +sequenceDiagram + Agent1->>Mediator: Send Message + Mediator->>Storage: Store Message + Agent2->>Mediator: Pickup Request + Mediator->>Agent2: Deliver Message +``` + +### 6.2 Mediator Coordination Flow +The Mediation Coordination Protocol is a component of the DIDComm framework, facilitating secure and efficient message routing between agents. It enables a recipient agent to request a mediator agent to handle message forwarding on its behalf. + +**Sequence Diagram: Mediation Coordination Protocol** + +```mermaid +sequenceDiagram + participant Recipient + participant Mediator + + Recipient->>Mediator: Mediate Request + alt Mediator Accepts + Mediator-->>Recipient: Mediate Grant + Note right of Mediator: Provides routing information + else Mediator Denies + Mediator-->>Recipient: Mediate Deny + Note right of Mediator: Declines mediation request + end + alt Recipient Registers Key + Recipient->>Mediator: Keylist Update + Mediator-->>Recipient: Keylist Update Response + end +``` + +**Illustration: Runtime Interaction** + +1. **Mediate Request**: The recipient sends a `mediate-request` message to the mediator, initiating the mediation process. + +2. **Mediator's Response**: + - **Grant**: If the mediator agrees, it responds with a `mediate-grant` message, providing necessary routing details. + - **Deny**: If the mediator declines, it sends a `mediate-deny` message. + +3. **Key Registration**: Upon receiving a grant, the recipient registers its keys with the mediator using a `keylist-update` message. The mediator acknowledges with a `keylist-update-response`. + +This interaction ensures that messages intended for the recipient are appropriately routed through the mediator, enhancing communication reliability and security. + +--- + +## 7. Deployment View + +### 7.1 Deployment Strategy + +The deployment of the `didcomm-mediator-rs` project leverages a scalable, distributed architecture designed for high availability, fault tolerance, and efficient message routing. + +--- + +### 7.2 Deployment Models + +#### 1. **Single Instance Deployment (Minimal Setup)** + +**Use Case**: Suitable for development or testing environments. + +- A single mediator instance handles all requests and routing. +- Simplifies deployment but lacks fault tolerance and scalability. + +**Advantages**: +- Minimal resource usage. +- Easy to configure and maintain. + +**Disadvantages**: +- No fault tolerance: if the mediator fails, the service becomes unavailable. +- Limited scalability. + +--- + +#### 2. **Distributed Deployment with Load Balancer (Recommended)** + +**Use Case**: Ideal for production environments requiring high availability and scalability. + +- Multiple mediator instances are deployed behind a load balancer. +- The load balancer distributes requests evenly across mediators, ensuring efficient utilization of resources. +- Supports horizontal scaling by adding more mediator instances as needed. + +**Advantages**: +- High availability: If one mediator instance fails, others continue handling requests. +- Scalable: New instances can be added to handle increased load. +- Efficient routing: Load balancer optimizes resource utilization. + +**Disadvantages**: +- Slightly higher complexity due to additional components (load balancer). + +--- + +### 7.3 Deployment Diagram + +Below is a component diagram showcasing the deployment with multiple mediators and a load balancer: + +```mermaid +graph TD + subgraph Internet + User1[Recipient Agent] + User2[Sender Agent] + end + + User1 --> LB[Load Balancer] + User2 --> LB + + subgraph Mediator Cluster + Mediator1[Mediator Instance 1] + Mediator2[Mediator Instance 2] + end + + LB --> Mediator1 + LB --> Mediator2 + + Mediator1 --> DB1[Message Storage DB] + Mediator2 --> DB1 +``` + +--- + +### 7.4 Deployment Considerations + +#### **Cloud Deployment** + +**Infrastructure**: +- Use cloud platforms like AWS, Azure, or GCP. +- Services like Elastic Load Balancer (AWS), Application Gateway (Azure), or Cloud Load Balancer (GCP) can be employed for load balancing. + +**Scaling**: +- Leverage auto-scaling groups to dynamically scale mediator instances based on traffic. + +**Monitoring**: +- Use monitoring tools (e.g., Prometheus, CloudWatch, or Azure Monitor) to track mediator performance, error rates, and resource usage. + +--- + +#### **On-Premises Deployment** + +**Infrastructure**: +- Deploy mediators on virtual machines or containers (e.g., Docker). +- Use a software-based load balancer (e.g., HAProxy, NGINX) for request distribution. + +**Scaling**: +- Add more mediator instances manually to handle increased traffic. + +**Monitoring**: +- Use tools like Grafana and Prometheus to monitor system health. + +--- + +### 7.5 Benefits of Load Balancer in Deployment + +1. **Fault Tolerance**: + - Ensures service continuity even if one mediator instance fails. + +2. **Scalability**: + - Handles growing traffic by distributing load across multiple instances. + +3. **Optimized Resource Utilization**: + - Prevents overloading a single mediator, ensuring consistent performance. + +4. **Simplified Maintenance**: + - Instances can be updated or replaced without downtime by redirecting traffic. + +This detailed deployment view provides clarity on how the system can be deployed effectively, balancing performance, fault tolerance, and scalability. + +--- + +## 8. Cross-cutting Concepts + +### 8.1 Security + +The security of `didcomm-mediator-rs` integrates both **application-level security** and **secure software development lifecycle (SSDLC) practices** to ensure robust, private, and resilient operations against potential vulnerabilities and attacks. + +--- + +#### 8.1.1 End-to-End Encryption + +DIDComm itself provides robust end-to-end encryption, ensuring that the mediator operates without access to message contents. + +- **Encryption in Transit**: Messages are encrypted using DIDComm standards, safeguarding confidentiality during routing. +- **Confidentiality**: Only the intended recipient can decrypt and access the message content, ensuring data remains private. + +--- + +#### 8.1.2 Authentication and Agent Identity Verification + +Authentication ensures that only legitimate agents interact with the mediator, preventing unauthorized access and spam. + +1. **Authentication During Mediation Coordination**: + - Agents requesting mediation must authenticate using: + - **DID Authentication**: Validates that the DID corresponds to the public key. + - **Signed Credentials**: Ensures requests are cryptographically signed and verifiable. + - **Trust Frameworks**: Optional integration with registries or decentralized credentials to validate agents. + +2. **Anti-Spam Measures**: + - **Rate Limiting**: Restricts the number of requests per agent within a given period. + - **Credential Validation**: Verifies agent credentials or DID associations. + - **Reputation Scoring**: Maintains agent reputation based on past behaviors. + +--- + +#### 8.1.3 Authorization for Message Handling + +The mediator enforces strict access controls to ensure only authorized agents can send and retrieve messages. + +1. **Message Sending**: + - Sender validation ensures: + - The sender provides a cryptographically signed request. + - The recipient's DID document lists the mediator as a valid routing endpoint. + - Access control policies allow communication between the sender and recipient. + +2. **Message Pickup**: + - Before delivering stored messages, the mediator ensures: + - The requesting agent provides a signed pickup request. + - The private key used for signing matches the public DID associated with the mediator. + +--- + +#### 8.1.4 Secure Storage and Key Management + +Protecting private keys and sensitive data is paramount. + +- **Encryption at Rest**: Private keys and secrets are encrypted using secure algorithms. +- **Memory Protections**: Runtime mechanisms prevent sensitive data from being swapped to disk. +- **Key Management**: + - Secure storage mechanisms like HashiCorp Vault or AWS KMS are used. + - Keys are rotated periodically to minimize risks. + +--- + +#### 8.1.5 Traffic Control and Anti-Spam Measures + +To ensure efficient operation and prevent abuse: +- **Rate Limiting and Throttling**: Prevents overloading by limiting agent requests. +- **Reputation-Based Blocking**: Blocks agents with poor reputations based on spam or malicious activity. +- **Audit Trails**: Logs all requests for later analysis and forensic investigation. + +--- + +#### 8.1.6 Secure Logging and Monitoring + +**Log Handling**: +- Sensitive data (e.g., private keys, PII) is redacted from logs. +- Logs are encrypted at rest and in transit. +- Access to logs is restricted to authorized personnel. + +**Monitoring**: +- Tools like Prometheus, Grafana, and ELK Stack are employed to monitor: + - API response times and error rates. + - System performance (e.g., memory and CPU utilization). +- Alerts are configured for anomalies, unauthorized access, and potential attacks. + +--- + +#### 8.1.7 Secure Software Development Lifecycle (SSDLC) + +Incorporating SSDLC practices ensures that vulnerabilities are minimized from inception through deployment. + +1. **Static Application Security Testing (SAST)**: + - Tools like **SonarQube**, **CodeQL**, or **Checkmarx** are used to scan source code for vulnerabilities. + - Integrated into CI/CD pipelines to analyze every commit and pull request. + +2. **Dynamic Application Security Testing (DAST)**: + - Tools like **OWASP ZAP** or **Burp Suite** test the application in running environments. + - Simulates real-world attack scenarios to identify runtime vulnerabilities. + +3. **Dependency Management**: + - Tools like **Snyk**, **OWASP Dependency-Check**, or GitHub Dependabot monitor dependencies for vulnerabilities. + - Enforces strict policies to restrict unverified or malicious modules. + - Locks dependency versions to prevent accidental updates. + +4. **Code and Image Signing**: + - All code artifacts are cryptographically signed to ensure integrity. + - Container images are signed using tools like **Cosign** to verify authenticity before deployment. + +--- + +#### 8.1.8 Continuous Security Assessment + +1. **Penetration Testing**: + - Regular penetration testing by internal and external experts to identify and remediate vulnerabilities. + +2. **Vulnerability Management**: + - Monitor CVEs and apply patches promptly. + - Update dependencies and application components regularly. + +3. **Incident Response**: + - A defined incident response plan ensures quick detection, isolation, and resolution of security breaches. + - Logs and audit trails provide forensic support. + +--- + +#### 8.1.9 Deployment Security + +1. **Immutable Infrastructure**: + - Deployments use containerized environments (e.g., Docker, Kubernetes) for consistency. + - Infrastructure updates are handled via image-based deployments. + +2. **Secure CI/CD Pipelines**: + - Pipelines enforce checks for vulnerabilities, code integrity, and dependency security. + - Deployments use RBAC (Role-Based Access Control) to restrict unauthorized changes. + +3. **Load Balancer Security**: + - Load balancers enforce TLS for secure communication. + - Denial-of-Service (DoS) protections are applied at the load balancer level. + +--- + +#### 8.1.10 Enhancements for Anti-Spam and Traffic Control + +1. **Rate Limiting**: Prevents message flooding by enforcing request caps. +2. **Trust-Based Validation**: Agents are validated using decentralized identity frameworks. +3. **Agent Reputation**: Maintains behavior-based reputation scores to filter malicious agents. + +--- + +#### Summary Table + +| **Aspect** | **Practices** | +|-----------------------------|-----------------------------------------------------------------------------| +| **End-to-End Encryption** | Encrypt messages in transit using DIDComm protocols. | +| **Authentication** | Use DID authentication and signed credentials for agent verification. | +| **Authorization** | Enforce access control policies for sending and retrieving messages. | +| **Secure Logging** | Mask sensitive data, encrypt logs, and restrict access. | +| **Monitoring** | Use tools like Prometheus and Grafana for real-time anomaly detection. | +| **Static Analysis (SAST)** | Integrate SonarQube or CodeQL into CI/CD pipelines. | +| **Dynamic Analysis (DAST)** | Test live environments using OWASP ZAP or Burp Suite. | +| **Dependency Management** | Use Snyk or OWASP Dependency-Check to monitor and secure dependencies. | +| **Code Signing** | Sign all artifacts and verify container images before deployment. | +| **Incident Response** | Have a clear plan for detection, containment, and recovery. | + +--- + +This combination integrates **application security** and **SSDLC best practices**, providing a comprehensive security framework for `didcomm-mediator-rs`. + +### 8.2 Performance +- **Concurrency**: Async Rust handles high message throughput. +- **Caching**: Reduces database queries for frequent operations. + +--- + +## 9. Architecture Decisions +- **Rust for Performance**: Chosen for safety and speed. +- **Transport Agnosticism**: Supports various communication protocols. +- **Cloud-First**: Optimized for deployment in cloud environments. + +--- + +## 10. Quality Requirements + +### Functional +- Reliable message storage and delivery. +- DID rotation support. + +### Non-Functional +- **Scalability**: Supports 10,000+ concurrent connections. +- **Security**: Fully encrypted message routing. + +--- + +## 11. Risks and Technical Debt +- **Risks**: Potential bottlenecks in message pickup under high loads. +- **Debt**: Optimization of transport layer abstraction. + +--- + +## 12. Product Management +- **Tech Stack**: Rust, Actix-web, SQLite, Kubernetes. +- **Versioning**: Semantic versioning for compatibility. + +--- + +## 13. Glossary +- **DID**: Decentralized Identifier. +- **DIDComm**: Messaging protocol for DIDs. +- **Mediator**: Intermediary facilitating message delivery. + +--- + +This document can be extended with implementation-specific details and diagrams as the project evolves. \ No newline at end of file From 466489d87c245e2e718008b5554ea71a9eef5cf1 Mon Sep 17 00:00:00 2001 From: Tekum Emmaanuella Date: Thu, 21 Nov 2024 11:27:24 +0100 Subject: [PATCH 09/14] updated arc doc with Architecture Decisions and Quality Requirements. --- docs/Architecture.md | 121 ------------------------------------------- docs/arc42.md | 93 ++++++++++++++++++++++++++------- 2 files changed, 73 insertions(+), 141 deletions(-) delete mode 100644 docs/Architecture.md diff --git a/docs/Architecture.md b/docs/Architecture.md deleted file mode 100644 index b803b101..00000000 --- a/docs/Architecture.md +++ /dev/null @@ -1,121 +0,0 @@ -# DIDComm Mediator Architecture Document - -### **Table of Contents** -- [**DIDComm Mediator Architecture Document**](#didcomm-mediator-architecture-document) -- [**Table of Contents**](#table-of-contents) -- [**1. Introduction**](#1-introduction) - - [**1.1 Purpose**](#11-purpose) - - [**1.2 System Overview**](#12-system-overview) - - [**1.3 Quality Goals**](#13-quality-goals) - - [**1.4 Stakeholders**](#14-stakeholders) -- [**2. Constraints**](#2-constraints) -- [**3. System Scope and Context**](#3-system-scope-and-context) - - [**3.1 Business Context**](#31-business-context) - - [**3.2 Technical Context**](#32-technical-context) -- [**4. Solution Strategy**](#4-solution-strategy) -- [**5. Building Block View**](#5-building-block-view) -- [**6. Runtime View**](#6-runtime-view) -- [**7. Deployment View**](#7-deployment-view) -- [**8. Cross Cutting Concerns**](#8-cross-cutting-concerns) -- [**9. Architectural Decisions**](#9-architectural-decisions) -- [**10. Quality Requirements**](#10-quality-requirements) -- [**11. Risk and Technical Debt**](#11-risk-and-technical-debt) -- [**12. Glossary**](#12-glossary) - -## 1. Introduction -### 1.1 Purpose -This document provides a detailed architecture for the DIDComm Mediator, a system designed to mediate communication between decentralized identities (DIDs) using the DIDComm protocol. The document outlines the design decisions, components, and interactions in the system. - -### 1.2 System Overview -The DIDComm Mediator acts as an intermediary that forwards messages between decentralized identifiers (DIDs) while maintaining security, privacy, and scalability. It adheres to the DIDComm messaging protocol, enabling seamless communication between agents. - -### 1.3 Quality Goals -- ***Security***: End-to-End encryption and authentication. -- ***Scalability***: Handle high message volume efficiently. -- ***Reliability***: Ensure fault tolerance and high availability -- ***Extensibility***: Support future enhancements and additional DID methods - -### 1.4 Stakeholders -Key stakeholders include DATEV, the adorsys development team, and third-party developers - -## 2. Constraints -- The project will be implemented in rust so as to take advantage of it's performance and safety features -- Only asynchronous Rust frameworks like tokio, axum, hyper, tracing can be used to ensure non-blocking operations -- The project must adhere to DIDComm V2 specifications - -## 3. System Scope and Context -### 3.1 Business Context -The DIDComm Mediator acts as a bridge to enable seemless communication between decentralized agents, ensuring secure and reliable message routing. - -### 3.2 Technical Context -![images](work-flow.png) - -The DIDComm Mediator operates within decentralized identity systems, leveraging the DIDComm protocol and Decentralized Identifiers (DIDs) to provide secure and scalable communication between agents. - -***Key Technical Considerations** -- ***DIDComm Protocol:** Provides secure messaging with end-to-end encryption and authentication, creating a secure communication channel between decentralized agents. -- ***Decentralized Identifiers (DIDs):** Unique identifiers that enable self-sovereign, verifiable identities within the system. -- ***Secure Messaging Mechanisms:** TLS and other mechanisms ensure confidentiality and integrity of messages during transmission. -- ***Asynchronous Rust Frameworks:** Utilizes libraries such as tokio, axum, hyper, and tracing for high-performance, non-blocking operations. -- ***Adherence to Specifications:** The system adheres to the DIDComm V2 specifications for compatibility and standardization. - -***Core Components and Responsibilities** -- ***Mediator Core Module:** The central component responsible for receiving, storing, and routing messages while ensuring DIDComm V2 compliance. -- ***DID Resolver:** Interfaces with decentralized networks/registries to validate and retrieve DID documents, enabling proper routing based on public keys or routing details. -- ***Message Handling and Routing:** Supports various DIDComm message types (e.g., forward messages) and ensures robust routing based on recipient details. -- ***Message Storage** Temporarily stores messages until recipients retrieve them, using optimized storage mechanisms and asynchronous I/O. - -***Key Technical Challenges** -- ***Message Confidentiality and Integrity:** Ensures messages remain secure and tamper-proof with end-to-end encryption and compliance with security standards. -- ***Performance Optimization:** Handles high message volumes using asynchronous Rust frameworks (tokio, hyper) to ensure scalable, non-blocking operations. -- ***Message Routing and Delivery:** Supports various DIDComm message types (e.g., forward messages) and ensures proper routing based on recipient details. - -***External Integrations** -- ***DID Registries and Networks**: Communicates with registries to perform reliable DID resolution. -- ***External Agents and Clients:** Interfaces with clients such as mobile and desktop applications for secure message routing. -- ***Verifiable Credential Systems:** Potentially integrates with credential issuance and verification workflows. - -***System Architecture Considerations** -- ***Security Protocols:** Implements TLS alongside end-to-end encryption within the DIDComm protocol, prioritizing security across all layers. -- ***Asynchronous Communication**: Uses asynchronous programming (via tokio and similar libraries) to manage high throughput without blocking operations. - -***Technology Choices:** -- ***Rust:** Rust language Chosen for memory safety, performance, and strong concurrency support. - -***Key Libraries:** -- ***serde:** For efficient serialization/deserialization. -- ***actix-web / axum:** Handles HTTP requests/web socket connections (based on the preferred framework). -- ***didkit (if applicable):** Supports DID operations, creation, and verification. - -# 4. Solution Strategy -The solution strategy outlines the foundational decisions that guide the system's architecture, aligning with the key quality goals, constraints, and overall system requirements. - -**Technology Decisions** -- **Programming Language**: Rust is chosen for its high performance, memory safety, and strong concurrency support. This decision aligns with the security and scalability goals of the mediator. -- **Cryptographic Libraries:** Askar is selected as the cryptographic library to provide high-level cryptographic functions specifically designed for decentralized identity systems. Askar offers key management, encryption, and decryption capabilities that are essential for DIDComm communication. Its focus on modularity and interoperability with other decentralized identity (DID) systems ensures that the system can evolve and stay secure over time. -- **Database:** MongoDB is selected as the database for its flexibility in handling semi-structured data, scalability, and ease of horizontal scaling. It is ideal for storing DID-related metadata, messages, and other data in a schema-less format that can adapt as the system evolves. - -**Organisational Decisions** -- **Development Process:**Agile methodology is adopted to deliver incremental updates and adapt to changing requirements. -- **Task Delegation:** Integration with external DID registries is modularized, enabling future partnerships with third-party providers for registry or DID resolution services. -- **Team Structure:** Assign dedicated team to core components (e.g., Mediator Core, Key Management, Communication Interfaces) for focused development and testing. - - -## 5. Building Block View - -## 6. Runtime View - -## 7. Deployment View - -## 8. Cross Cutting Concerns - -## 9. Architectural Decisions - -## 10. Quality Requirements - -## 11. Risk and Technical Debt - -## 12. Glossary -- ***DID(Decentralized Identifier):*** A unique identifier that enables verifiable, self-sovereign identities -- ***DIDComm:*** A secure messaging protocol used to communicate over decentralized networks -- ***Mediator:*** An intermediary service that routes DIDComm messages between agents diff --git a/docs/arc42.md b/docs/arc42.md index 4ce83521..d9e82d2d 100644 --- a/docs/arc42.md +++ b/docs/arc42.md @@ -22,7 +22,7 @@ Here is an ARC42 architecture document tailored for the Rust-based `didcomm-medi --- -## 1. Introduction +## 1. [Introduction](#introduction) ### 1.1 Document Goals This document outlines the architecture of the `didcomm-mediator-rs`, a Rust-based implementation of a DIDComm v2 mediator. Its purpose is to ensure secure, efficient, and reliable routing of DIDComm messages while providing clarity to stakeholders, architects, and developers. @@ -36,7 +36,7 @@ This document outlines the architecture of the `didcomm-mediator-rs`, a Rust-bas --- -## 2. Architecture Constraints +## 2. [Architecture Constraints](#architecture-constraints) ### 2.1 Technical Constraints - **Rust Programming Language**: Ensures high performance and memory safety. @@ -49,7 +49,7 @@ This document outlines the architecture of the `didcomm-mediator-rs`, a Rust-bas --- -## 3. System Scope and Context +## 3. [System Scope and Context](#system-scope-and-context) ### 3.1 Business Context The mediator facilitates routing of DIDComm messages for agents unable to maintain direct communication channels. It acts as an intermediary, ensuring reliability and privacy. @@ -71,7 +71,7 @@ graph LR --- -## 4. Solution Strategy +## 4. [Solution Strategy](#solution-strategy) A microservices approach ensures modularity and scalability. `didcomm-mediator-rs` employs Rust's async capabilities to handle concurrent message routing efficiently. ### Key Features: @@ -106,7 +106,7 @@ This modular and extensible implementation ensures the mediator evolves with the --- -## 5. Building Block View +## 5. [Building Block View](#building-block-view) ### 5.1 Overview @@ -168,7 +168,7 @@ graph TD --- -## 6. Runtime View +## 6. [Runtime View](#runtime-view) ### 6.1 Message Flow 1. Agent sends a message to the mediator. @@ -222,7 +222,7 @@ This interaction ensures that messages intended for the recipient are appropriat --- -## 7. Deployment View +## 7. [Deployment View](#deployment-view) ### 7.1 Deployment Strategy @@ -343,7 +343,7 @@ This detailed deployment view provides clarity on how the system can be deployed --- -## 8. Cross-cutting Concepts +## 8. [Cross-cutting Concepts](#cross-cutting-concepts) ### 8.1 Security @@ -517,38 +517,91 @@ This combination integrates **application security** and **SSDLC best practices* --- -## 9. Architecture Decisions -- **Rust for Performance**: Chosen for safety and speed. -- **Transport Agnosticism**: Supports various communication protocols. -- **Cloud-First**: Optimized for deployment in cloud environments. +## 9. [Architecture Decisions](#architecture-decisions) + +### 9.1 Technology Decisions +- **Rust for Performance**: + - Chosen for its memory safety, high-speed execution, and ability to handle concurrent processes efficiently. + - Ensures robust and reliable mediation services in a decentralized environment. + +- **Transport Agnosticism**: + - Supports various communication protocols (e.g., HTTP, WebSocket, and others). + - Designed to integrate seamlessly into diverse ecosystems, enhancing interoperability. + +- **Cloud-First**: + - Optimized for deployment in modern cloud environments. + - Employs containerized solutions (e.g., Docker) and orchestration tools (e.g., Kubernetes) for scalability and ease of maintenance. + + +### 9.2 Architectural Features +- **DIDComm Protocol Implementation**: + - Follows the DIDComm v2 standard for secure and decentralized identity communication. + - Supports encrypted, authenticated, and transport-agnostic messaging. + +- **Scalability and Modularity**: + - Architected to handle growing user and message loads without performance bottlenecks. + - Modular design allows for easy extension of features like advanced message routing or additional protocol support. + +- **Secure Message Mediation**: + - Incorporates robust cryptographic mechanisms to protect sensitive data. + - Ensures confidentiality, integrity, and authenticity in all message exchanges. + +### 9.3 Deployment and Maintenance +- **CI/CD Integration**: + - Automated pipelines for testing, building, and deploying ensure rapid and error-free updates. + +- **On-Premise and Hybrid Support**: + - Though optimized for the cloud, the solution is also adaptable for on-premise deployment. + - Suitable for organizations with strict data sovereignty or privacy requirements. + +- **Logging and Monitoring**: + - Designed to include observability features such as detailed logs and performance monitoring. + - Aids in debugging and enhances operational reliability. + +### 9.4 Future Considerations +- **Additional Protocol Support**: + - Exploring further transport protocols to expand integration capabilities. + +- **Dynamic Scaling**: + - Introducing auto-scaling mechanisms to manage resource usage based on real-time demand. + +- **Advanced Observability**: + - Adding comprehensive monitoring and analytics dashboards to track system performance and detect anomalies. --- -## 10. Quality Requirements + +## 10. [Quality Requirements](#quality-requirements) ### Functional -- Reliable message storage and delivery. -- DID rotation support. +* **Reliable Message Storage and Delivery**: + The system must ensure that messages are stored persistently and delivered reliably to the correct recipient, even in the event of system failures. This includes handling retries, acknowledgments, and maintaining message order. The system should support eventual consistency and be able to recover from intermittent network failures, ensuring that no messages are lost during transmission. + +* **DID Rotation Support**: + The system should support Decentralized Identifier (DID) rotation to ensure secure communication can continue uninterrupted when the keys or identifiers change. This includes the ability to handle key rotation, update trust stores, and ensure that the recipient is aware of the new DID information. Rotation must not disrupt communication, ensuring transparency in key changes and maintaining message integrity through appropriate versioning and key management mechanisms. ### Non-Functional -- **Scalability**: Supports 10,000+ concurrent connections. -- **Security**: Fully encrypted message routing. +* **Scalability**: + The system must be capable of handling a high number of concurrent connections while maintaining performance and reliability. Scalability can be achieved through load balancing, horizontal scaling across multiple servers, and efficient resource management. Techniques such as data partitioning, caching, and asynchronous processing will ensure that the system can handle increased load without performance degradation. + +* **Security**: + All messages must be routed and stored in an encrypted format to ensure the privacy and integrity of the data. The system should comply with established cryptographic standards, using public-key encryption for message transmission and ensuring that keys are securely managed. Additional measures like integrity checks (e.g., HMAC, digital signatures) must be used to protect data from tampering or unauthorized access. The system must also support end-to-end encryption to ensure that only the intended recipients can decrypt the messages, with mechanisms for key revocation and renewal built-in. --- -## 11. Risks and Technical Debt +## 11. [Risks and Technical Debt](#risks-and-technical-debt) - **Risks**: Potential bottlenecks in message pickup under high loads. - **Debt**: Optimization of transport layer abstraction. --- -## 12. Product Management +## 12. [Product Management](#product-management) - **Tech Stack**: Rust, Actix-web, SQLite, Kubernetes. - **Versioning**: Semantic versioning for compatibility. --- -## 13. Glossary +## 13. [Glossary](#glossary) - **DID**: Decentralized Identifier. - **DIDComm**: Messaging protocol for DIDs. - **Mediator**: Intermediary facilitating message delivery. From 82e2805c821cb167cd285cb4c441302b4d688ee0 Mon Sep 17 00:00:00 2001 From: chendiblessing Date: Thu, 21 Nov 2024 13:16:03 +0100 Subject: [PATCH 10/14] updated arc document with risk and technical debt --- docs/arc42.md | 124 ++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 91 insertions(+), 33 deletions(-) diff --git a/docs/arc42.md b/docs/arc42.md index d9e82d2d..3b0e3379 100644 --- a/docs/arc42.md +++ b/docs/arc42.md @@ -5,25 +5,23 @@ Here is an ARC42 architecture document tailored for the Rust-based `didcomm-medi # DIDComm Mediator RS - ARC42 Architecture Documentation ## Table of Contents -1. [Introduction](#introduction) -2. [Architecture Constraints](#architecture-constraints) -3. [System Scope and Context](#system-scope-and-context) -4. [Solution Strategy](#solution-strategy) -5. [Building Block View](#building-block-view) -6. [Runtime View](#runtime-view) -7. [Deployment View](#deployment-view) -8. [Cross-cutting Concepts](#cross-cutting-concepts) -9. [Architecture Decisions](#architecture-decisions) -10. [Quality Requirements](#quality-requirements) -11. [Risks and Technical Debt](#risks-and-technical-debt) -12. [Product Management](#product-management) -13. [Glossary](#glossary) -14. [Appendix](#appendix) - ---- - -## 1. [Introduction](#introduction) - +1. [Introduction](#1-introduction) +2. [Architecture Constraints](#2-architecture-constraints) +3. [System Scope and Context](#3-system-scope-and-context) +4. [Solution Strategy](#4-solution-strategy) +5. [Building Block View](#5-building-block-view) +6. [Runtime View](#6-runtime-view) +7. [Deployment View](#7-deployment-view) +8. [Cross-cutting Concepts](#8-cross-cutting-concepts) +9. [Architecture Decisions](#9-architecture-decisions) +10. [Quality Requirements](#10-quality-requirements) +11. [Risks and Technical Debt](#11-risks-and-technical-debt) +12. [Product Management](#12-product-management) +13. [Glossary](#13-glossary) + +--- + +## 1. Introduction ### 1.1 Document Goals This document outlines the architecture of the `didcomm-mediator-rs`, a Rust-based implementation of a DIDComm v2 mediator. Its purpose is to ensure secure, efficient, and reliable routing of DIDComm messages while providing clarity to stakeholders, architects, and developers. @@ -36,7 +34,7 @@ This document outlines the architecture of the `didcomm-mediator-rs`, a Rust-bas --- -## 2. [Architecture Constraints](#architecture-constraints) +## 2. Architecture Constraints ### 2.1 Technical Constraints - **Rust Programming Language**: Ensures high performance and memory safety. @@ -49,7 +47,7 @@ This document outlines the architecture of the `didcomm-mediator-rs`, a Rust-bas --- -## 3. [System Scope and Context](#system-scope-and-context) +## 3. System Scope and Context ### 3.1 Business Context The mediator facilitates routing of DIDComm messages for agents unable to maintain direct communication channels. It acts as an intermediary, ensuring reliability and privacy. @@ -71,7 +69,7 @@ graph LR --- -## 4. [Solution Strategy](#solution-strategy) +## 4. Solution Strategy A microservices approach ensures modularity and scalability. `didcomm-mediator-rs` employs Rust's async capabilities to handle concurrent message routing efficiently. ### Key Features: @@ -106,7 +104,7 @@ This modular and extensible implementation ensures the mediator evolves with the --- -## 5. [Building Block View](#building-block-view) +## 5. Building Block View ### 5.1 Overview @@ -168,7 +166,7 @@ graph TD --- -## 6. [Runtime View](#runtime-view) +## 6. Runtime View ### 6.1 Message Flow 1. Agent sends a message to the mediator. @@ -222,7 +220,7 @@ This interaction ensures that messages intended for the recipient are appropriat --- -## 7. [Deployment View](#deployment-view) +## 7. Deployment View ### 7.1 Deployment Strategy @@ -343,7 +341,7 @@ This detailed deployment view provides clarity on how the system can be deployed --- -## 8. [Cross-cutting Concepts](#cross-cutting-concepts) +## 8. Cross-cutting Concepts ### 8.1 Security @@ -517,7 +515,7 @@ This combination integrates **application security** and **SSDLC best practices* --- -## 9. [Architecture Decisions](#architecture-decisions) +## 9. Architecture Decisions ### 9.1 Technology Decisions - **Rust for Performance**: @@ -571,7 +569,7 @@ This combination integrates **application security** and **SSDLC best practices* --- -## 10. [Quality Requirements](#quality-requirements) +## 10. Quality Requirements ### Functional * **Reliable Message Storage and Delivery**: @@ -589,19 +587,79 @@ This combination integrates **application security** and **SSDLC best practices* --- -## 11. [Risks and Technical Debt](#risks-and-technical-debt) -- **Risks**: Potential bottlenecks in message pickup under high loads. -- **Debt**: Optimization of transport layer abstraction. +## 11. Risks and Technical Debt +--- + +#### **Risks** +1. **Message Pickup Delays Under High Load:** + - **Cause:** High volume of concurrent requests or uneven workload distribution. + - **Mitigation:** + - Implement rate limiting for individual agents. + - Introduce adaptive queueing mechanisms to prioritize urgent messages. + - Optimize message retrieval with indexed storage and caching. + +2. **Single Point of Failure in Initial Deployments:** + - **Cause:** Lack of redundancy during early development or testing phases. + - **Mitigation:** + - Transition to a distributed deployment model with load balancing. + - Utilize active-passive failover strategies for critical components. + +3. **Transport Layer Compatibility Issues:** + - **Cause:** Incomplete or inconsistent support for diverse transport protocols (e.g., WebSockets, Bluetooth). + - **Mitigation:** + - Expand transport testing suites for edge cases. + - Adopt a common interface for transport abstraction to reduce inconsistencies. + +4. **Encryption Key Management Challenges:** + - **Cause:** Complexities in securely rotating keys and ensuring backward compatibility. + - **Mitigation:** + - Introduce automated key rotation with DIDComm-compliant mechanisms. + - Ensure seamless coordination between mediator and agents for key updates. + +5. **Potential Data Breach via Misconfigured Logs:** + - **Cause:** Insufficient log redaction or improper access controls. + - **Mitigation:** + - Enforce log encryption and access policies during development. + - Integrate log analysis tools that detect and block sensitive data exposure. + +#### **Technical Debt** +1. **Simplified Transport Layer Abstraction:** + - **Impact:** Makes it harder to extend mediator functionality to support new or custom transport protocols. + - **Planned Resolution:** + - Refactor to adopt a modular transport interface. + - Use a factory pattern for transport instantiation. + +2. **Basic Observability Tools:** + - **Impact:** Limited insight into runtime behavior may hinder issue resolution under high traffic. + - **Planned Resolution:** + - Integrate advanced observability solutions like distributed tracing with OpenTelemetry. + +3. **Incomplete Protocol Coverage:** + - **Impact:** Missing implementation of critical protocols (e.g., Discover Features, Present Proof) limits applicability in broader DIDComm ecosystems. + - **Planned Resolution:** + - Prioritize development of high-demand protocols. + - Define a phased approach to protocol implementation. + +4. **Static Resource Allocation:** + - **Impact:** Inefficient use of resources under variable load conditions. + - **Planned Resolution:** + - Introduce auto-scaling mechanisms in Kubernetes to dynamically allocate resources. + +5. **Minimal Failover Testing:** + - **Impact:** Could lead to prolonged downtime or message loss during unexpected failures. + - **Planned Resolution:** + - Conduct chaos testing to validate failover strategies. + - Build automated failover and recovery scenarios into CI/CD pipelines. --- -## 12. [Product Management](#product-management) +## 12. Product Management - **Tech Stack**: Rust, Actix-web, SQLite, Kubernetes. - **Versioning**: Semantic versioning for compatibility. --- -## 13. [Glossary](#glossary) +## 13. Glossary - **DID**: Decentralized Identifier. - **DIDComm**: Messaging protocol for DIDs. - **Mediator**: Intermediary facilitating message delivery. From b73f9172e31060d9976dd2b04b70be0d1d102495 Mon Sep 17 00:00:00 2001 From: chendiblessing Date: Thu, 21 Nov 2024 13:27:27 +0100 Subject: [PATCH 11/14] updated architecture document with the product management section --- docs/arc42.md | 43 ++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 40 insertions(+), 3 deletions(-) diff --git a/docs/arc42.md b/docs/arc42.md index 3b0e3379..c10721de 100644 --- a/docs/arc42.md +++ b/docs/arc42.md @@ -588,7 +588,6 @@ This combination integrates **application security** and **SSDLC best practices* --- ## 11. Risks and Technical Debt ---- #### **Risks** 1. **Message Pickup Delays Under High Load:** @@ -654,8 +653,46 @@ This combination integrates **application security** and **SSDLC best practices* --- ## 12. Product Management -- **Tech Stack**: Rust, Actix-web, SQLite, Kubernetes. -- **Versioning**: Semantic versioning for compatibility. + +#### **Tech Stack** +- **Programming Language:** Rust, chosen for its high performance, memory safety, and robust concurrency support, ensuring efficient and reliable message routing. +- **Web Framework:** Actix-web, selected for its asynchronous capabilities, enabling scalable handling of concurrent DIDComm messages. +- **Database:** MongoDB, a NoSQL database chosen for its: + - **Scalability:** Seamlessly handles large volumes of data with horizontal scaling. + - **Flexibility:** Supports dynamic schema for evolving DIDComm message formats. + - **Fault Tolerance:** Features built-in replication and sharding for high availability and resilience in production deployments. +- **Orchestration and Deployment:** Kubernetes, offering container orchestration for efficient resource utilization and scalability. + - Includes Helm charts for configuration standardization and easy deployments. + +#### **CI/CD Practices** +- **Versioning:** Adheres to semantic versioning for consistent feature progression and backward compatibility. +- **Testing Pipelines:** Comprehensive CI/CD pipelines with automated: + - **Static Code Analysis:** Tools like Clippy and Rustfmt for code quality and style adherence. + - **Unit and Integration Testing:** Focus on protocol compliance and end-to-end functionality validation. + - **Security Testing:** Integrates SAST (e.g., CodeQL) and DAST (e.g., OWASP ZAP) for identifying vulnerabilities. + - **Performance Testing:** Employs tools like Locust or K6 to validate performance under simulated high loads. + +#### **Roadmap and Feature Prioritization** +- **Planned Features:** + - Completion of Discover Features and Out-of-Band Messaging protocols. + - Implementation of Acknowledgments (Acks) and Present Proof Protocol to fully align with DIDComm standards. +- **Backlog Management:** + - Managed using agile methodologies, with tracking in tools like GitHub Projects. + - Prioritization based on end-user requirements, technical feasibility, and feedback from the DIDComm community. + +#### **Monitoring and Metrics** +- **Database Monitoring:** Leverages MongoDB Atlas or Prometheus MongoDB Exporter for tracking query performance, connection pool utilization, and replica set health. +- **System Observability:** Implements Prometheus and Grafana for real-time metrics visualization, including: + - Message throughput (e.g., messages processed per second). + - Latency (e.g., message pickup times). + - System health (e.g., memory, CPU, and disk usage). + +#### **Release and Deployment Strategies** +- **Release Cadence:** + - Regular minor releases for incremental updates. + - Quarterly major releases for architectural improvements or significant feature additions. +- **Blue-Green Deployments:** Ensures minimal disruption during updates by switching traffic between live and staging environments. +- **Rollback Plan:** Supports quick rollback to previous stable versions in case of critical issues during deployment. --- From edfc5ff6e22f231640a18dd34a6df902dbd7f3ba Mon Sep 17 00:00:00 2001 From: Tekum Emmaanuella Date: Thu, 21 Nov 2024 13:37:37 +0100 Subject: [PATCH 12/14] updated arc doc with the glossary composed of key words. --- docs/arc42.md | 111 ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 108 insertions(+), 3 deletions(-) diff --git a/docs/arc42.md b/docs/arc42.md index d9e82d2d..789516c9 100644 --- a/docs/arc42.md +++ b/docs/arc42.md @@ -602,9 +602,114 @@ This combination integrates **application security** and **SSDLC best practices* --- ## 13. [Glossary](#glossary) -- **DID**: Decentralized Identifier. -- **DIDComm**: Messaging protocol for DIDs. -- **Mediator**: Intermediary facilitating message delivery. + +* **DID**: + - **Decentralized Identifier**: A self-sovereign, cryptographically secure identifier independent of centralized authorities. + +* **DIDComm**: + - **Messaging Protocol for DIDs**: A protocol for secure, private communication between entities using DIDs. + +* **Mediator**: + - **Message Intermediary**: A trusted entity that routes messages between parties in DIDComm, often used to bridge communication gaps. + +* **Scalability**: + - The system's ability to handle increasing loads by distributing resources or scaling horizontally. + +* **Security**: + - Protection of data through encryption, ensuring confidentiality, integrity, and authenticity of messages. + +* **Semantic Versioning (SemVer)**: + - A versioning scheme for software that indicates the nature of changes through `MAJOR.MINOR.PATCH`. + +* **Horizontal Scaling**: + - Increasing capacity by adding more instances of servers or resources. + +* **Load Balancing**: + - Distributing network traffic across multiple servers to avoid overloading a single resource. + +* **Kubernetes**: + - A container orchestration platform that automates deployment, scaling, and management of applications. + +* **Rust**: + - A systems programming language known for memory safety, concurrency, and performance. + +* **Actix-web**: + - A Rust-based framework for building fast, asynchronous web applications. + +* **SQLite**: + - A self-contained, serverless database engine used for lightweight, persistent storage. + +* **DID Rotation**: + - Changing a DID’s associated cryptographic keys to enhance security while maintaining continuous communication. + +* **Message Delivery**: + - The reliable transmission of messages from sender to recipient, often involving intermediaries. + +* **Persistent Storage**: + - Data storage that retains information beyond the system’s runtime, ensuring data availability across sessions. + +* **Encryption**: + - The process of securing data to prevent unauthorized access, ensuring privacy and data integrity. + +* **Cloud-First**: + - A strategy where applications are designed to be deployed in the cloud, leveraging cloud services for scalability. + +* **Transport Agnosticism**: + - The capability of a system to support different communication protocols without being reliant on one. + +* **Retry Logic**: + - A mechanism that attempts to resend failed operations or messages to ensure reliability in communication. + +* **Public Key Infrastructure (PKI)**: + - A framework for managing digital keys and certificates for secure communication. + +* **Trust Store**: + - A repository of trusted certificates and keys used to verify the authenticity of communication partners. + +* **Horizontal Load Balancing**: + - Distributing incoming traffic across multiple servers to prevent overloading a single server. + +* **Vertical Scaling**: + - Increasing a system's capacity by adding more resources (e.g., CPU, RAM) to a single server. + +* **TLS (Transport Layer Security)**: + - A cryptographic protocol designed to provide secure communication over a computer network. + +* **REST API**: + - An architectural style for building web services, using HTTP requests to interact with resources (e.g., GET, POST). + +* **WebSocket**: + - A communication protocol that provides full-duplex communication channels over a single TCP connection. + +* **Asynchronous Programming**: + - A programming model that allows tasks to be performed without blocking the main program flow. + +* **Message Acknowledgment**: + - A process where the recipient confirms receipt of a message, often to ensure reliability in communication. + +* **Caching**: + - Storing frequently accessed data in temporary storage for faster retrieval. + +* **Decentralized Identity (DID)**: + - A self-sovereign identity system that allows individuals to own and control their identifiers without depending on a central authority. + +* **Encryption Key Management**: + - The process of handling, storing, and rotating encryption keys to ensure the security of encrypted data. + +* **Zero-Trust Security**: + - A security model that assumes no trust is granted to any entity, even inside the network, and requires continuous verification. + +* **Encryption Algorithm**: + - A mathematical procedure used to encrypt or decrypt data, ensuring confidentiality and security. + +* **Public-Key Cryptography**: + - A cryptographic system that uses a pair of keys: a public key for encryption and a private key for decryption. + +* **Trust Chain**: + - A sequence of certificates that validate the authenticity of a cryptographic key, leading back to a trusted root certificate. + +* **Service Discovery**: + - The process of automatically detecting services in a network, allowing components to find and interact with each other dynamically. --- From 5dd95150caa3aa41fe785eed3e81be3eb592e7d0 Mon Sep 17 00:00:00 2001 From: chendiblessing Date: Thu, 21 Nov 2024 14:03:23 +0100 Subject: [PATCH 13/14] updated architecture document with the product management section --- docs/arc42.md | 116 +++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 106 insertions(+), 10 deletions(-) diff --git a/docs/arc42.md b/docs/arc42.md index 883cacbb..71676eb6 100644 --- a/docs/arc42.md +++ b/docs/arc42.md @@ -586,16 +586,112 @@ This combination integrates **application security** and **SSDLC best practices* All messages must be routed and stored in an encrypted format to ensure the privacy and integrity of the data. The system should comply with established cryptographic standards, using public-key encryption for message transmission and ensuring that keys are securely managed. Additional measures like integrity checks (e.g., HMAC, digital signatures) must be used to protect data from tampering or unauthorized access. The system must also support end-to-end encryption to ensure that only the intended recipients can decrypt the messages, with mechanisms for key revocation and renewal built-in. --- - -## 11. [Risks and Technical Debt](#risks-and-technical-debt) -- **Risks**: Potential bottlenecks in message pickup under high loads. -- **Debt**: Optimization of transport layer abstraction. - ---- - -## 12. [Product Management](#product-management) -- **Tech Stack**: Rust, Actix-web, SQLite, Kubernetes. -- **Versioning**: Semantic versioning for compatibility. +## 11. Risks and Technical Debt + +#### **Risks** +1. **Message Pickup Delays Under High Load:** + - **Cause:** High volume of concurrent requests or uneven workload distribution. + - **Mitigation:** + - Implement rate limiting for individual agents. + - Introduce adaptive queueing mechanisms to prioritize urgent messages. + - Optimize message retrieval with indexed storage and caching. + +2. **Single Point of Failure in Initial Deployments:** + - **Cause:** Lack of redundancy during early development or testing phases. + - **Mitigation:** + - Transition to a distributed deployment model with load balancing. + - Utilize active-passive failover strategies for critical components. + +3. **Transport Layer Compatibility Issues:** + - **Cause:** Incomplete or inconsistent support for diverse transport protocols (e.g., WebSockets, Bluetooth). + - **Mitigation:** + - Expand transport testing suites for edge cases. + - Adopt a common interface for transport abstraction to reduce inconsistencies. + +4. **Encryption Key Management Challenges:** + - **Cause:** Complexities in securely rotating keys and ensuring backward compatibility. + - **Mitigation:** + - Introduce automated key rotation with DIDComm-compliant mechanisms. + - Ensure seamless coordination between mediator and agents for key updates. + +5. **Potential Data Breach via Misconfigured Logs:** + - **Cause:** Insufficient log redaction or improper access controls. + - **Mitigation:** + - Enforce log encryption and access policies during development. + - Integrate log analysis tools that detect and block sensitive data exposure. + +#### **Technical Debt** +1. **Simplified Transport Layer Abstraction:** + - **Impact:** Makes it harder to extend mediator functionality to support new or custom transport protocols. + - **Planned Resolution:** + - Refactor to adopt a modular transport interface. + - Use a factory pattern for transport instantiation. + +2. **Basic Observability Tools:** + - **Impact:** Limited insight into runtime behavior may hinder issue resolution under high traffic. + - **Planned Resolution:** + - Integrate advanced observability solutions like distributed tracing with OpenTelemetry. + +3. **Incomplete Protocol Coverage:** + - **Impact:** Missing implementation of critical protocols (e.g., Discover Features, Present Proof) limits applicability in broader DIDComm ecosystems. + - **Planned Resolution:** + - Prioritize development of high-demand protocols. + - Define a phased approach to protocol implementation. + +4. **Static Resource Allocation:** + - **Impact:** Inefficient use of resources under variable load conditions. + - **Planned Resolution:** + - Introduce auto-scaling mechanisms in Kubernetes to dynamically allocate resources. + +5. **Minimal Failover Testing:** + - **Impact:** Could lead to prolonged downtime or message loss during unexpected failures. + - **Planned Resolution:** + - Conduct chaos testing to validate failover strategies. + - Build automated failover and recovery scenarios into CI/CD pipelines. + +--- + +## 12. Product Management + +#### **Tech Stack** +- **Programming Language:** Rust, chosen for its high performance, memory safety, and robust concurrency support, ensuring efficient and reliable message routing. +- **Web Framework:** Actix-web, selected for its asynchronous capabilities, enabling scalable handling of concurrent DIDComm messages. +- **Database:** MongoDB, a NoSQL database chosen for its: + - **Scalability:** Seamlessly handles large volumes of data with horizontal scaling. + - **Flexibility:** Supports dynamic schema for evolving DIDComm message formats. + - **Fault Tolerance:** Features built-in replication and sharding for high availability and resilience in production deployments. +- **Orchestration and Deployment:** Kubernetes, offering container orchestration for efficient resource utilization and scalability. + - Includes Helm charts for configuration standardization and easy deployments. + +#### **CI/CD Practices** +- **Versioning:** Adheres to semantic versioning for consistent feature progression and backward compatibility. +- **Testing Pipelines:** Comprehensive CI/CD pipelines with automated: + - **Static Code Analysis:** Tools like Clippy and Rustfmt for code quality and style adherence. + - **Unit and Integration Testing:** Focus on protocol compliance and end-to-end functionality validation. + - **Security Testing:** Integrates SAST (e.g., CodeQL) and DAST (e.g., OWASP ZAP) for identifying vulnerabilities. + - **Performance Testing:** Employs tools like Locust or K6 to validate performance under simulated high loads. + +#### **Roadmap and Feature Prioritization** +- **Planned Features:** + - Completion of Discover Features and Out-of-Band Messaging protocols. + - Implementation of Acknowledgments (Acks) and Present Proof Protocol to fully align with DIDComm standards. +- **Backlog Management:** + - Managed using agile methodologies, with tracking in tools like GitHub Projects. + - Prioritization based on end-user requirements, technical feasibility, and feedback from the DIDComm community. + +#### **Monitoring and Metrics** +- **Database Monitoring:** Leverages MongoDB Atlas or Prometheus MongoDB Exporter for tracking query performance, connection pool utilization, and replica set health. +- **System Observability:** Implements Prometheus and Grafana for real-time metrics visualization, including: + - Message throughput (e.g., messages processed per second). + - Latency (e.g., message pickup times). + - System health (e.g., memory, CPU, and disk usage). + +#### **Release and Deployment Strategies** +- **Release Cadence:** + - Regular minor releases for incremental updates. + - Quarterly major releases for architectural improvements or significant feature additions. +- **Blue-Green Deployments:** Ensures minimal disruption during updates by switching traffic between live and staging environments. +- **Rollback Plan:** Supports quick rollback to previous stable versions in case of critical issues during deployment. --- From ebe6b591906ed9cb439ea3d0f3391a3494df358f Mon Sep 17 00:00:00 2001 From: Tekum Emmaanuella Date: Thu, 21 Nov 2024 14:14:38 +0100 Subject: [PATCH 14/14] mordified arc glosssary. --- docs/arc42.md | 149 ++++++++++++++------------------------------------ 1 file changed, 40 insertions(+), 109 deletions(-) diff --git a/docs/arc42.md b/docs/arc42.md index 71676eb6..5a295c5e 100644 --- a/docs/arc42.md +++ b/docs/arc42.md @@ -695,115 +695,46 @@ This combination integrates **application security** and **SSDLC best practices* --- -## 13. [Glossary](#glossary) - -* **DID**: - - **Decentralized Identifier**: A self-sovereign, cryptographically secure identifier independent of centralized authorities. - -* **DIDComm**: - - **Messaging Protocol for DIDs**: A protocol for secure, private communication between entities using DIDs. - -* **Mediator**: - - **Message Intermediary**: A trusted entity that routes messages between parties in DIDComm, often used to bridge communication gaps. - -* **Scalability**: - - The system's ability to handle increasing loads by distributing resources or scaling horizontally. - -* **Security**: - - Protection of data through encryption, ensuring confidentiality, integrity, and authenticity of messages. - -* **Semantic Versioning (SemVer)**: - - A versioning scheme for software that indicates the nature of changes through `MAJOR.MINOR.PATCH`. - -* **Horizontal Scaling**: - - Increasing capacity by adding more instances of servers or resources. - -* **Load Balancing**: - - Distributing network traffic across multiple servers to avoid overloading a single resource. - -* **Kubernetes**: - - A container orchestration platform that automates deployment, scaling, and management of applications. - -* **Rust**: - - A systems programming language known for memory safety, concurrency, and performance. - -* **Actix-web**: - - A Rust-based framework for building fast, asynchronous web applications. - -* **SQLite**: - - A self-contained, serverless database engine used for lightweight, persistent storage. - -* **DID Rotation**: - - Changing a DID’s associated cryptographic keys to enhance security while maintaining continuous communication. - -* **Message Delivery**: - - The reliable transmission of messages from sender to recipient, often involving intermediaries. - -* **Persistent Storage**: - - Data storage that retains information beyond the system’s runtime, ensuring data availability across sessions. - -* **Encryption**: - - The process of securing data to prevent unauthorized access, ensuring privacy and data integrity. - -* **Cloud-First**: - - A strategy where applications are designed to be deployed in the cloud, leveraging cloud services for scalability. - -* **Transport Agnosticism**: - - The capability of a system to support different communication protocols without being reliant on one. - -* **Retry Logic**: - - A mechanism that attempts to resend failed operations or messages to ensure reliability in communication. - -* **Public Key Infrastructure (PKI)**: - - A framework for managing digital keys and certificates for secure communication. - -* **Trust Store**: - - A repository of trusted certificates and keys used to verify the authenticity of communication partners. - -* **Horizontal Load Balancing**: - - Distributing incoming traffic across multiple servers to prevent overloading a single server. - -* **Vertical Scaling**: - - Increasing a system's capacity by adding more resources (e.g., CPU, RAM) to a single server. - -* **TLS (Transport Layer Security)**: - - A cryptographic protocol designed to provide secure communication over a computer network. - -* **REST API**: - - An architectural style for building web services, using HTTP requests to interact with resources (e.g., GET, POST). - -* **WebSocket**: - - A communication protocol that provides full-duplex communication channels over a single TCP connection. - -* **Asynchronous Programming**: - - A programming model that allows tasks to be performed without blocking the main program flow. - -* **Message Acknowledgment**: - - A process where the recipient confirms receipt of a message, often to ensure reliability in communication. - -* **Caching**: - - Storing frequently accessed data in temporary storage for faster retrieval. - -* **Decentralized Identity (DID)**: - - A self-sovereign identity system that allows individuals to own and control their identifiers without depending on a central authority. - -* **Encryption Key Management**: - - The process of handling, storing, and rotating encryption keys to ensure the security of encrypted data. - -* **Zero-Trust Security**: - - A security model that assumes no trust is granted to any entity, even inside the network, and requires continuous verification. - -* **Encryption Algorithm**: - - A mathematical procedure used to encrypt or decrypt data, ensuring confidentiality and security. - -* **Public-Key Cryptography**: - - A cryptographic system that uses a pair of keys: a public key for encryption and a private key for decryption. - -* **Trust Chain**: - - A sequence of certificates that validate the authenticity of a cryptographic key, leading back to a trusted root certificate. - -* **Service Discovery**: - - The process of automatically detecting services in a network, allowing components to find and interact with each other dynamically. +## 13. Glossary + +| **Component** | **Definition** | +|----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| +| **DID** | Decentralized Identifier: A self-sovereign, cryptographically secure identifier independent of centralized authorities. | +| **DIDComm** | Messaging Protocol for DIDs: A protocol for secure, private communication between entities using DIDs. | +| **Mediator** | Message Intermediary: A trusted entity that routes messages between parties in DIDComm, often used to bridge communication gaps. | +| **Scalability** | The system's ability to handle increasing loads by distributing resources or scaling horizontally. | +| **Security** | Protection of data through encryption, ensuring confidentiality, integrity, and authenticity of messages. | +| **Semantic Versioning (SemVer)** | A versioning scheme for software that indicates the nature of changes through `MAJOR.MINOR.PATCH`. | +| **Horizontal Scaling** | Increasing capacity by adding more instances of servers or resources. | +| **Load Balancing** | Distributing network traffic across multiple servers to avoid overloading a single resource. | +| **Kubernetes** | A container orchestration platform that automates deployment, scaling, and management of applications. | +| **Rust** | A systems programming language known for memory safety, concurrency, and performance. | +| **Actix-web** | A Rust-based framework for building fast, asynchronous web applications. | +| **SQLite** | A self-contained, serverless database engine used for lightweight, persistent storage. | +| **DID Rotation** | Changing a DID’s associated cryptographic keys to enhance security while maintaining continuous communication. | +| **Message Delivery** | The reliable transmission of messages from sender to recipient, often involving intermediaries. | +| **Persistent Storage** | Data storage that retains information beyond the system’s runtime, ensuring data availability across sessions. | +| **Encryption** | The process of securing data to prevent unauthorized access, ensuring privacy and data integrity. | +| **Cloud-First** | A strategy where applications are designed to be deployed in the cloud, leveraging cloud services for scalability. | +| **Transport Agnosticism** | The capability of a system to support different communication protocols without being reliant on one. | +| **Retry Logic** | A mechanism that attempts to resend failed operations or messages to ensure reliability in communication. | +| **Public Key Infrastructure (PKI)** | A framework for managing digital keys and certificates for secure communication. | +| **Trust Store** | A repository of trusted certificates and keys used to verify the authenticity of communication partners. | +| **Horizontal Load Balancing** | Distributing incoming traffic across multiple servers to prevent overloading a single server. | +| **Vertical Scaling** | Increasing a system's capacity by adding more resources (e.g., CPU, RAM) to a single server. | +| **TLS (Transport Layer Security)** | A cryptographic protocol designed to provide secure communication over a computer network. | +| **REST API** | An architectural style for building web services, using HTTP requests to interact with resources (e.g., GET, POST). | +| **WebSocket** | A communication protocol that provides full-duplex communication channels over a single TCP connection. | +| **Asynchronous Programming** | A programming model that allows tasks to be performed without blocking the main program flow. | +| **Message Acknowledgment** | A process where the recipient confirms receipt of a message, often to ensure reliability in communication. | +| **Caching** | Storing frequently accessed data in temporary storage for faster retrieval. | +| **Decentralized Identity (DID)** | A self-sovereign identity system that allows individuals to own and control their identifiers without depending on a central authority. | +| **Encryption Key Management** | The process of handling, storing, and rotating encryption keys to ensure the security of encrypted data. | +| **Zero-Trust Security** | A security model that assumes no trust is granted to any entity, even inside the network, and requires continuous verification. | +| **Encryption Algorithm** | A mathematical procedure used to encrypt or decrypt data, ensuring confidentiality and security. | +| **Public-Key Cryptography** | A cryptographic system that uses a pair of keys: a public key for encryption and a private key for decryption. | +| **Trust Chain** | A sequence of certificates that validate the authenticity of a cryptographic key, leading back to a trusted root certificate. | +| **Service Discovery** | The process of automatically detecting services in a network, allowing components to find and interact with each other dynamically. | ---