docs: add architecture and technical documentation (#18)

Refs: #17
Co-authored-by: Evelyn Gurschler <[email protected]>
Reviewed-by: Evelyn Gurschler <[email protected]>

README.md

@@ -2,9 +2,13 @@
 
 This repository contains the backend code for the SSI Authority & Schema Registry written in C#.
 
+For **information about the SSI Authority & Schema Registry**, please refer to the documentation, especially the context and scope section in the [architecture documentation](./docs/architecture).
+
+For **installation** details, please refer to the [README.md](./charts/ssi-authority-schema-registry/README.md) of the provided helm chart.
+
 ## How to build and run
 
-Install [the .NET 8.0 SDK](https://www.microsoft.com/net/download).
+Install the [.NET 8.0 SDK](https://www.microsoft.com/net/download).
 
 Run the following command from the CLI:
 
@@ -19,7 +23,20 @@ Run the following command from the CLI in the directory of the service you want
 dotnet run
 ```
 
+## Notice for Docker image
+
+This application provides container images for demonstration purposes.
+
+See Docker notice files for more information:
+
+- [ssi-authority-schema-registry-service](./docker//notice-registry-service.md)
+- [ssi-authority-schema-registry-migrations](./docker/notice-registry-migrations.md)
+
+## Contributing
+
+See [Contribution details](/docs/technical-documentation/dev-process/How%20to%20contribute.md).
+
 ## License
 
 Distributed under the Apache 2.0 License.
-See [LICENSE](./LICENSE) for more information
+See [LICENSE](./LICENSE) for more information

docs/architecture/Architecture Constraints.md

@@ -0,0 +1,58 @@
+# Architecture Constraints Documentation
+
+## Overview
+
+The following document outlines the architecture constraints for the SSI Authority & Schema Registry App. This App serves as a central point to provide information about which credentials are provided by which authority. The constraints outlined in this document are intended to guide the development and deployment of the system to ensure it meets the specified requirements and adheres to the defined standards.
+
+## General Constraints
+
+### System Purpose
+
+- **Authority Information**: The SSI Authority & Schema Registry App is designed to offer details on credential types and the authorities that issue them.
+- **Credential Validation**: The app provides information on the validity of credentials based on their schemas.
+- **No User Interface (UI)**: The current development plan does not include the implementation of a user interface. However an user interface interaction got implemented as part of the portal project.
+
+### Deployment
+
+- **Run Anywhere**: The system is designed to be containerized and deployable as a Docker image. This ensures it can run on various platforms, including cloud environments, on-premises infrastructure, or locally.
+- **Platform-Independent**: The application is platform-independent, capable of running on Kubernetes or similar orchestration platforms.
+
+## Developer Constraints
+
+### Open Source Software
+
+- **FOSS Licenses**: All software used must be open-source, with licenses approved by the Eclipse Foundation. These licenses form the initial set agreed upon by the CX community to regulate content contributions.
+- **Apache License 2.0**: The Apache License 2.0 is selected as the approved license to respect and guarantee intellectual property rights.
+
+### Development Standards
+
+- **Coding Guidelines**: Defined coding guidelines for the development must be followed for all registry developments.
+- **Consistency Enforcement**: Code analysis tools, linters, and code coverage metrics are used to enforce coding standards and maintain a consistent style. These standards are enforced through the Continuous Integration (CI) process to prevent the merging of non-compliant code.
+
+## Code Analysis and Security
+
+To ensure code quality and security, the following analyses and checks are performed during standard reviews:
+
+### Code Quality Checks
+
+- **SonarCloud Code Analysis**: Automated code review tool to detect code quality issues.
+- **Code Linting**: Tools to enforce coding style and detect syntax errors.
+- **Code Coverage**: Metrics to ensure a sufficient percentage of the codebase is covered by automated tests.
+
+### Security Checks
+
+- **Thread Modelling Analysis**: Assessment of potential security threats and vulnerabilities.
+- **Static Application Security Testing (SAST)**: Analysis of source code for security vulnerabilities.
+- **Dynamic Application Security Testing (DAST)**: Testing of the application in its running state to find security vulnerabilities.
+- **Secret Scans**: Detection of sensitive information such as passwords or API keys in the codebase.
+- **Software Composition Analysis (SCA)**: Evaluation of open-source components for security risks.
+- **Container Scans**: Analysis of Docker container images for vulnerabilities.
+- **Infrastructure as Code (IaC)**: Analysis of infrastructure definitions for security and compliance.
+
+## NOTICE
+
+This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).
+
+- SPDX-License-Identifier: Apache-2.0
+- SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
+- Source URL: https://github.com/eclipse-tractusx/ssi-authority-schema-registry

docs/architecture/Context and scope.md

@@ -0,0 +1,21 @@
+# Content and Scope
+
+## Business Context
+
+The Self-Sovereign Identity (SSI) credential issuer core purpose is to facilitate seamless communication with digital wallets, which are essential tools for managing digital identities. Being responsible for the critical functions of creating, revoking, and managing the expiry of credentials. This ensures that issuers maintain control over their issues digital identities.
+
+To further enhance the user experience, the SSI Authority & Schema Registry provides users with a comprehensive overview of available use case credentials. By doing so, it empowers users to make informed decisions about which credentials to acquire and use. The business context of the SSI Authority & Schema Registry is thus centered around providing a robust, user-friendly, and secure mechanism for identity management.
+
+## Technical Context
+
+From a technical standpoint, the SSI Authority & Schema Registry is built on a foundation that promotes interaction, monitoring, and a host of other functionalities that are crucial for maintaining a secure and reliable identity management system.
+
+A key aspect of the technical context is the commitment to open-source principles. The SSI Authority & Schema Registry is constructed with open-source components to the greatest extent possible, fostering a collaborative and transparent development environment. Moreover, the entire codebase of the SSI Authority & Schema Registry is open-sourced, reflecting a 100% commitment to the open-source community.
+
+## NOTICE
+
+This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).
+
+- SPDX-License-Identifier: Apache-2.0
+- SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
+- Source URL: https://github.com/eclipse-tractusx/ssi-authority-schema-registry

docs/architecture/Development Concept.md

@@ -0,0 +1,131 @@
+# Development Concept
+
+## Build, test, deploy
+
+Details to the build, test and deploy process can get found under the following md file: [Release Process](/docs/technical-documentation/release-process/Release%20Process.md)
+
+## Development Guidelines
+
+The SSI Authority & Schema Registry is using following key frameworks:
+
+- .Net
+- Entity Framework
+
+### Swagger
+
+The API uses OpenAPI annotations to describe the endpoints with all necessary information. The annotations are then used to automatically generate the OpenAPI specification file, which can be viewed in the Swagger UI that is deployed with the application.
+
+#### API Dev Guidelines
+
+##### Validate all requests
+
+As mentioned, sometimes requests from perfectly valid sources may be hacking attempts. Therefore, APIs need rules to determine whether a request is friendly, friendly but invalid, or harmful, like an attempt to inject harmful code.
+
+An API request is only processed once its contents pass a thorough validation check — otherwise, the request should never reach the application data layer.
+
+Validation also includes sanity checks: Define sensible value ranges for the parameters a user provides. This especially is valid for the size of the request and the response. APIs should limit the possible number of records to process in order to prevent intentional or unintentional overloads of the system.
+
+##### Encrypt all requests and responses
+
+To prevent MITM attacks, any data transfer from the user to the API server or vice versa must be properly encrypted. This way, any intercepted requests or responses are useless to the intruder without the right decryption method.
+
+Since REST APIs use HTTP, encryption can be achieved by using the Transport Layer Security (TLS) protocol or Secure Sockets Layer (SSL) protocol. These protocols supply the S in “HTTPS” (“S” meaning “secure'') and are the standard for encrypting web pages and REST API communications.
+
+TLS/SSL only encrypts data when that data is being transferred. It doesn’t encrypt data sitting behind your API, which is why sensitive data should also be encrypted in the database layer as well.
+
+##### Only include necessary information in responses
+
+Like you might unintentionally let a secret slip when telling a story to a friend, it’s possible for an API response to expose information hackers can use. To prevent this, all responses sent to the end-user should include only the information to communicate the success or failure of the request, the resource requested (if any), and any other information directly related to these resources.
+
+In other words, avoid “oversharing” data — the response is a chance for you to inadvertently expose private data, either through the returned resources or verbose status messages.
+
+=> in the ownership of every API Developer
+
+##### Throttle API requests and establish quotas
+
+To prevent brute-force attacks like DDoS, an API can impose rate-limiting, a way to control the number of requests to the API server at any given time.
+
+There are two main ways to rate-limit API requests, quotas and throttling. Quotas limit the number of requests allowed from a user over a span of time, while throttling slows a user’s connection while still allowing them to use your API.
+
+Both methods should allow normal API requests but prevent floods of traffic intended to disrupt, as well as unexpected request spikes in general.
+
+##### Log API activity
+
+Logging API activities is extremely important when it comes to tracing user activity and in worst case hack activity.
+
+###### Conduct security tests
+
+=> see [Test Section](#tests) below
+
+##### Error Handling
+
+The simplest way we handle errors is to respond with an appropriate status code.
+
+Common agreed response codes:
+
+- 400 Bad Request – client sent an invalid request, such as lacking required request body or parameter.
+  Example: The same constraint has been configured multiple times in the request
+- 401 Unauthorized – user authenticated but doesn't have permission to access the requested resource.
+  Example: User token doesn't have the access on the resource.
+- 403 Forbidden – client failed to authenticate with the server.
+  Example: token expired oder invalid login.
+- 404 Not Found – the requested resource does not exist.
+  Example: A specific credential was requested which does not exist in the database.
+- 500 Internal Server Error – a generic error occurred in the internal system logic.
+  Example: Unexpected server-side issue during credential validation.
+  Additionally to the generic error code, a detailed message/error is needed to ensure that the issue can get validated and resolved quickly.
+
+##### Repository Pattern
+
+The repositories are used via the Factory RegistryRepository, which ensures that the same database instance is used for all repositories.
+
+Furthermore, it provides an implicit transaction functionality.
+
+The repositories themselves must not be registered for dependency injection in the corresponding startup; the method RegistryRepository.GetInstance<RepositoryType> provides the instance of a requested repository.
+
+#### Tests
+
+##### User Authentication Test
+
+If authentication mechanisms are implemented incorrectly, attackers can compromise authentication tokens or exploit implementation flaws to assume other users’ identities and gain access to your API’s endpoints.
+
+To test your authentication mechanisms, try sending API requests without proper authentication (either no tokens or credentials, or incorrect ones) and see if your API responds with the correct error and messaging.
+
+##### Parameter Tampering Test
+
+To run a parameter tampering test, try various combinations of invalid query parameters in your API requests and see if it responds with the correct error codes. If not, then your API likely has some backend validation errors that need to be resolved.
+
+##### Injection Test
+
+To test if your API is vulnerable to injections, try injecting SQL, NoSQL, LDAP, OS, or other commands in API inputs and see if your API executes them. These commands should be harmless, like reboot commands or cat commands.
+
+##### Unhandled HTTP Methods Test
+
+Most APIs have various HTTP methods that are used to retrieve, store, or delete data. Sometimes web servers will give access to unsupported HTTP methods by default, which makes your API vulnerable.
+
+To test for this vulnerability, you should try all the common HTTP methods (POST, GET, PUT, PATCH, and DELETE) as well as a few uncommon ones. TRY sending an API request with the HEAD verb instead of GET, for example, or a request with an arbitrary method like FOO. You should get an error code, but if you get a 200 OK response, then your API has a vulnerability.
+
+##### Load Test
+
+Load testing should be one of the last steps of your API security auditing process. This type is pushing the API to its limits in order to discover any functional or security issues that have yet to be revealed.
+
+To achieve this, send a large number of randomized requests, including SQL queries, system commands, arbitrary numbers, and other non-text characters, and see if your API responds with errors, processes any of these inputs incorrectly, or crashes. This type of testing will mimic Overflow and DDoS attacks.
+
+An API manager or gateway tool will handle or help address the API security guidelines described above (including testing).
+
+## Migration
+
+To run the SSI Authority & Schema Registry, migrations are needed to load the initial data inside the SSI Authority & Schema Registry db to enable the SSI Authority & Schema Registry to work.
+The migration will consist of an initial migration as well as delta migration files with future releases. As part of a new release, a migration file (if applicable) will get released and can get loaded via a delta load.
+
+## Configurability
+
+SSI Authority & Schema Registry configuration is mainly possible via the appsettings files as well as the static data migration files.
+
+## NOTICE
+
+This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).
+
+- SPDX-License-Identifier: Apache-2.0
+- SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
+- Source URL: https://github.com/eclipse-tractusx/ssi-authority-schema-registry

docs/architecture/Operational Concept.md

@@ -0,0 +1,47 @@
+# Operational concepts
+
+## SSI Authority & Schema Registry Services
+
+### Configuration
+
+The SSI Authority & Schema Registry services can be configured using two methods:
+
+### appsettings.json
+
+If you build the SSI Authority & Schema Registry, you can modify the appsettings.json for each backend service, to individually configure to a certain extend. This file contains all possible config entries for the application.
+
+### Helm Chart
+
+The most relevant config properties are exposed as environment variables and must be set in the Helm chart so the application can run at all. Check the SSI Authority & Schema Registry Helm chart in Git for all available variables.
+
+### DB Migration File
+
+Static Data migration files provide a certain configuration possibility by adding or deleting static data records before the deployment. Be aware that touching static data files will always impact the application business process. It is suggested to always test the application with the planned changes carefully in INT before releasing to a productive env.
+
+## Disaster-Recovery
+
+Note: will be added soon
+
+## Scaling
+
+If the number of consumers raises, the IRS can be scaled up by using more resources for the Deployment Pod. Those resources can be used to utilize more parallel threads to handle Job execution.
+
+## Clustering
+
+Note: will be added soon
+
+## Monitoring
+
+Currently all backend services write log entries as structural data in json format. These logs can easily be monitored. There are several options to provide a stable monitoring solution, one of them is to setup loki and grafana. In this solution loki is used as a datasource and custom dashboards can be setup in grafana to monitor the services. Some general Properties to query with grafana are:
+
+- StatusCode - contains the status code of the response
+- Elapsed - contains the time a endpoint took to response in milliseconds
+- RenderedMessage - contains the log message with possible errors
+
+## NOTICE
+
+This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).
+
+- SPDX-License-Identifier: Apache-2.0
+- SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
+- Source URL: https://github.com/eclipse-tractusx/ssi-authority-schema-registry