doc: add arc42 documentation (eclipse-tractusx#51)

* add docu

* added runtime

* updated README

README.md

@@ -70,6 +70,10 @@ checkout the [Chart README](charts/bdrs-server/README.md)
     --wait-for-jobs --timeout=120s --dependency-update
   ```
 
+## Further documentation
+
+please refer to the [docs](docs) folder for further documentation.
+
 ## License
 
 Distributed under the Apache 2.0 License.

charts/bdrs-server/templates/deployment.yaml

@@ -146,7 +146,7 @@ spec:
             # API #
             #######
             - name: "EDC_API_AUTH_KEY_ALIAS"
-              value: {{ .Values.server.endpoints.management.authKeyAlias | required ".Values.runtime.endpoints.management.authKeyAlias is required" | quote }}
+              value: {{ .Values.server.endpoints.management.authKeyAlias | required ".Values.server.endpoints.management.authKeyAlias is required" | quote }}
             - name: "WEB_HTTP_PORT"
               value: {{ .Values.server.endpoints.default.port | quote }}
             - name: "WEB_HTTP_PATH"

docs/architecture/1_introduction.md

@@ -0,0 +1,9 @@
+# Introduction
+
+In a Tractus-X dataspace participants use Business Partner Numbers (BPNs) as stable identifiers for any data exchange.
+However, the identity protocol uses Decentralized Identifiers (DIDs) as identifiers.
+
+The BPN-DID-Resolution-Service is a core component of the Tractus-X landscape, which binds BPNs to DIDs and provides a
+lookup API for participants.
+
+Its [directory API](./4_runtime.md) must be accessible to every participant in the dataspace.

docs/architecture/2_constraints.md

@@ -0,0 +1,3 @@
+# Constraints
+
+TBD

docs/architecture/3_deployment.md

@@ -0,0 +1,101 @@
+# Deployment
+
+## Using the official Helm chart
+
+The official Helm chart should be used, its documentation can be obtained
+from [here](https://github.com/eclipse-tractusx/bpn-did-resolution-service/blob/main/charts/bdrs-server/README.md).
+
+_Any other deployment scenarios, e.g. running it as plain Docker image, or as Java process are neither recommended nor
+supported!_
+
+## Preconditions
+
+### Postgres Database
+
+If a dedicated Postgres database is used (i.e. `install.postgresql` in the chart config is set to `false`), a DB user
+must be created that has privileges to execute DDL and DML statements, as BDRS will perform migrations on boot-up.
+
+The DB username and password must be stored as secrets in Hashicorp vault, see the [vault section](#hashicorp-vault) for
+details.
+
+## Necessary Configuration
+
+When deploying BDRS using the official Helm chart, the following configuration values are **mandatory**:
+
+- `server.endpoints.default.[port|path]`: the port and base path for the Observability API. This API is **not** supposed
+  to be reachable
+  via the internet!
+- `server.endpoints.management.[port|path]`: the port and base path for the Management API. This API is **not** supposed
+  to be reachable
+  via the internet!
+- `server.endpoints.directory.[port|path]`: the port and base path for the Directory API. This API is supposed to be
+  internet-facing.
+- `server.trustedIssuers` this must be a YAML array containing the DIDs of all trusted credential issuers, for example:
+  ```yaml
+  server:
+    trustedIssuers:
+      - "did:web:tractusx-issuer1"
+      - "did:web:tractusx-issuer2"
+  ```
+- `server.endpoints.management.authKeyAlias`: the alias under which the API key is stored in the Vault
+- `postgresql.jdbcUrl`: the JDBC url including the DB name of the Postgres database
+- `vault.hashicorp.url`: the URL where Hashicorp Vault is reachable
+- `vault.hashicorp.token`: the token which BDRS uses to authenticate against Hashicorp Vault
+- `vault.hashicorp.paths.secret`: the root path in the vault where all [secrets](#hashicorp-vault) are stored.
+
+## The Directory API
+
+The Directory API is supposed to provide the mapping information to dataspace participants. While it provides
+application-layer security through a bearer token, deployment engineers should take appropriate measures such as
+SSL/TLS termination, load-balancing, request throttling, creating an audit log, monitoring, etc.
+
+The Directory API **must** be accessible from the internet, e.g. through a Kubernetes Ingress or LoadBalancer.
+
+## The Management API
+
+The Management API's purpose is to give administrators a way to add, update, remove mapping entries. It has some basic
+security built-in via an API token, but additional layers of security are **absolutely necessary**. These include - but
+are not limited to - using an API gateway or similar infrastructure that performs the following tasks:
+
+- authentication/authorization: only privileged users ("Admins") should be allowed to access the Management API
+- request tracing: every request that hits the Management API should be logged including the user information
+- limiting network access: it may be advisable to restrict access to the Management API on a network level, e.g. with a
+  VPN
+
+The API Key of the Management API must be stored in Hashicorp Vault. The alias is configured using the Helm
+value `server.endpoints.management.authKeyAlias` (default is `"mgmt-api-key"`). The API key must be stored in the Vault
+using the alias, see the [vault section](#hashicorp-vault) for details.
+
+## Hashicorp Vault
+
+If a dedicated Hashicorp Vault is used (i.e. `install.vault` in the chart config is set to `false`), a user with write
+permissions must exist for that vault, so that secrets can be created.
+
+BDRS requires the following secrets to be present **before application startup**.
+
+### Management API Key
+
+The API key must be stored in the vault using an alias (defaulting to `"mgmt-api-key"`) that contains a single element
+
+```json
+{
+  "content": "super-secret-api-key"
+}
+```
+
+### Postgres credentials
+
+Access credentials for Postgres are stored in the Vault using the following hard-coded secret names:
+
+- `edc.datasource.didentry.user`: must contain a single item
+  ```json
+  {
+    "content": "super-secret-username"
+  }
+  ```
+- `edc.datasource.didentry.password` must contain a single item
+  ```json
+  {
+    "content": "super-secret-password"
+  }
+  ```

docs/architecture/4_runtime.md

@@ -0,0 +1,52 @@
+# BDRS at runtime
+
+## Accessing the Directory API
+
+This public-facing API is accessed by clients to obtain a list BPN-to-DID mappings, which they use to resolve the DID
+for a particular BPN,
+see [API documentation](https://eclipse-tractusx.github.io/bpn-did-resolution-service/openapi/directory-api/).
+It is protected with a bearer token in JWT format that has to be attached to the `Authorization` header of the request.
+
+The bearer token must be a VerifiablePresentation in JWT format, that contains the
+client's [MembershipCredential](https://github.com/eclipse-tractusx/tractusx-profiles/blob/main/cx/credentials/schema/credentials/membership.credential.schema.json),
+typically also in JWT format. The VerifiablePresentation must be signed with the client's private key and contain in
+its `kid` header a URI referencing the client's public key, e.g. using a DID: `"did:web:client1#key-1"`.
+
+The VerifiablePresentation JWT must also have the following properties:
+
+- `iss` claim must be identical to the `holder` property
+- `kid` header contains the `iss`, e.g. `kid: did:web:client1#key-1` and `iss: did:web:client1`
+- `holder` value must be identical to the MembershipCredential's `credentialSubject.id` value
+
+Upon successful evaluation, the BDRS Directory API response with a GZipped binary stream that contains a JSON array
+containing BPN - DID mappings similar to:
+
+```json
+[
+  {
+    "bpn": "BPN123",
+    "did": "did:web:localhost:member1"
+  },
+  {
+    "bpn": "BPN789",
+    "did": "did:web:anotherhost:member2"
+  }
+]
+```
+
+## Client implementation considerations
+
+The Directory API does **not** provide any 1:1 lookup. That means it is **not** possible to query explicitly for a
+particular BPN. Instead, clients are supposed to query the entire list and cache it locally for an appropriate amount of
+time. BPN resolution requests should **always hit the local cache**!
+
+This was done to avoid high request loads on the BDRS server and to further decentralize the system as much as possible
+to avoid bottlenecks and single-points-of-failure.
+
+## Accessing the Management API
+
+_The Management API should only b accessed by authorized users/applications - appropriate hardening measures **must** be
+employed._
+
+In all other respects please refer to
+the [Management API documentation](https://eclipse-tractusx.github.io/bpn-did-resolution-service/openapi/management-api/).