docs: add and improve documentation (#377)

* docs: add and improve documentation

* DEPENDENCIES

.github/workflows/verify.yaml

@@ -42,21 +42,13 @@ jobs:
       - name: 'Build Docker image'
         run: docker build -t identity-hub ./launcher
 
-      - name: 'Create public key file'
-        run: |
-          mkdir -p keys
-          openssl req -newkey rsa:2048 -new -nodes -x509 -days 3650 -keyout keys/key.pem -out keys/cert.pem -subj="/CN=www.foo.bar"
-
       - name: 'Start Identity Hub'
         run: |
           docker run -d --rm --name identity-hub \
-            -v $(pwd)/keys:/opt/keys \
-            -e "EDC_IH_IAM_PUBLICKEY_PATH=/opt/keys/key.pem" \
-            -e "EDC_IH_IAM_ID=did:web:test" \
             -e "WEB_HTTP_IDENTITY_PORT=8182" \
             -e "WEB_HTTP_IDENTITY_PATH=/api/identity" \
             -e "WEB_HTTP_RESOLUTION_PORT=10001" \
-            -e "WEB_HTTP_RESOLUTION_PATH=/api/v1/resolution/" \
+            -e "WEB_HTTP_RESOLUTION_PATH=/api/resolution" \
             identity-hub:latest
 
       - name: 'Wait for Identity Hub to be healthy'

DEPENDENCIES

@@ -75,7 +75,6 @@ maven/mavencentral/com.jcraft/jzlib/1.1.3, BSD-2-Clause, approved, CQ6218
 maven/mavencentral/com.lmax/disruptor/3.4.4, Apache-2.0, approved, clearlydefined
 maven/mavencentral/com.networknt/json-schema-validator/1.0.76, Apache-2.0, approved, CQ22638
 maven/mavencentral/com.nimbusds/nimbus-jose-jwt/9.28, Apache-2.0, approved, clearlydefined
-maven/mavencentral/com.nimbusds/nimbus-jose-jwt/9.39.3, Apache-2.0, approved, #14830
 maven/mavencentral/com.nimbusds/nimbus-jose-jwt/9.40, , restricted, clearlydefined
 maven/mavencentral/com.puppycrawl.tools/checkstyle/10.17.0, LGPL-2.1-or-later AND (Apache-2.0 AND LGPL-2.1-or-later) AND Apache-2.0, approved, #15077
 maven/mavencentral/com.samskivert/jmustache/1.15, BSD-2-Clause, approved, clearlydefined

README.md

@@ -1,21 +1,52 @@
 # Identity Hub
 
-This repository contains an implementation for a Decentralized Web Node such as defined by the
-[Decentralized Identity Fundation](https://identity.foundation/decentralized-web-node/spec/).
+This repository contains an implementation for
+the [Decentralized Claims Protocol (DCP) specification](https://projects.eclipse.org/projects/technology.dataspace-dcp).
+In short, IdentityHub contains multiple VerifiableCredentials and
+makes them available to authorized parties as VerifiablePresentations. It also receives VerifiableCredentials issued by
+an issuer and stores them. Convenience features like automatic credential renewal and re-issuance are also included.
+This functionality is sometimes referred to as "wallet".
 
-See also the main [project page on Github](https://github.com/eclipse-dataspaceconnector/DataSpaceConnector).
+IdentityHub makes heavy use of EDC components for core functionality, specifically those of
+the [connector](https://github.com/eclipse-edc/Connector) for extension loading, runtime bootstrap, configuration, API
+handling etc., while adding specific functionality using the EDC
+extensibility mechanism.
+
+Here, developers find everything necessary to build and run a basic "vanilla" version of IdentityHub.
 
 ## Quick start
 
-A basic launcher configured with in-memory stores (i.e. no persistent storage) is provider [here](launcher). You
-can run it as a Docker container by following the steps below.
+A basic launcher configured with in-memory stores (i.e. no persistent storage) can be found [here](launcher/). There are
+two ways of running IdentityHub:
+
+1. As native Java process
+2. Inside a Docker image
 
-### Build the `.jar`
+### Build the `*.jar` file
 
 ```bash
 ./gradlew :launcher:shadowJar
 ```
 
+### Start IdentityHub as Java process
+
+Once the jar file is built, IdentityHub can be launched using this shell command:
+
+```bash
+java -Dweb.http.resolution.port=10001 \
+     -Dweb.http.resolution.path="/api/resolution" \
+     -Dweb.http.port=8181 \
+     -Dweb.http.path="/api" \
+     -Dweb.http.identity.port=8182 \
+     -Dweb.http.identity.path="/api/identity" \
+     -Dedc.ih.api.superuser.key="c3VwZXItdXNlcgo=c3VwZXItc2VjcmV0Cg==" \
+     -jar launcher/build/libs/identity-hub.jar
+```
+
+this will expose the Presentation API at `http://localhost:10001/api/resolution` and the Identity API
+at `http://localhost:8191/api/identity`. More information about IdentityHub's APIs can be
+found [here](docs/developer/architecture/identityhub-apis.md)
+
 ### Create the Docker image
 
 ```bash
@@ -25,15 +56,53 @@ docker build -t identity-hub ./launcher
 ### Start the Identity Hub
 
 ```bash
-docker run -d --rm --name identity-hub -p 8188:8188 identity-hub
+docker run --rm --name identity-hub \
+            -e "WEB_HTTP_RESOLUTION_PORT=10001" \
+            -e "WEB_HTTP_RESOLUTION_PATH=/api/resolution/" \
+            -e "EDC_HTTP_PATH=/api" \
+            -e "EDC_HTTP_PORT=8181" \
+            -e "WEB_HTTP_IDENTITY_PORT=8182" \
+            -e "WEB_HTTP_IDENTITY_PATH=/api/identity" \
+            -e "EDC_IH_API_SUPERUSER_KEY=c3VwZXItdXNlcgo=c3VwZXItc2VjcmV0Cg==" \
+            identity-hub:latest
 ```
 
-## Documentation
+## Architectural concepts of IdentityHub
+
+Key architectural concepts are
+outlined [here](docs/developer/architecture/identity-trust-protocol/identity.hub.architecture.md).
+
+## Module structure of IdentityHub
+
+IdentityHub's module structure and key SPIs is
+described [here](docs/developer/architecture/identity-trust-protocol/identity-hub-modules.md).
+
+_Please note that some classes or functionalities mentioned there may not yet have been implemented, for example
+automatic credential renewal._
+
+## API overview of IdentityHub
+
+IdentityHub exposes several APIs that are described in more
+detail [here](docs/developer/architecture/identityhub-apis.md).
+
+## Future work
+
+- Implementation of the Credential Issuance Protocol
+- Support for VC Presentation Definition
+- Support for VC Data Model 2.0
+
+
+## Other documentation
 
 Developer documentation can be found under [docs/developer](docs/developer), where the main concepts and decisions are
 captured as [decision records](docs/developer/decision-records).
 
+## References
+
+- Decentralized Claims Protocol (DCP): https://projects.eclipse.org/projects/technology.dataspace-dcp
+- VerifiableCredentials Data Model: https://www.w3.org/TR/vc-data-model/ (currently supported) and https://www.w3.org/TR/vc-data-model-2.0/ (planned)
+- EDC Connector: https://github.com/eclipse-edc/Connector
+
 ## Contributing
 
-See [how to contribute](https://github.com/eclipse-dataspaceconnector/DataSpaceConnector/blob/main/CONTRIBUTING.md) for
-details.
+See [how to contribute](https://github.com/eclipse-edc/docs/blob/main/CONTRIBUTING.md) for details.

docs/developer/architecture/mgmt-api.security.md → docs/developer/architecture/identity-api.security.md

@@ -18,7 +18,7 @@
   resources. Also referred to as: mgmt api
 - API Key: a secret string that is used to authenticate/authorize a request and that is typically sent in the HTTP
   header. Also referred to as: API token, API secret, credential
-- Super-user: service principal with pre-definted roles that grant elevated access permissions. Also referred to as:
+- Super-user: service principal with pre-defined roles that grant elevated access permissions. Also referred to as:
   admin, root user
 
 ## 2. Requirements

docs/developer/architecture/identity-trust-protocol/identity-and-trust-modules.md → docs/developer/architecture/identity-trust-protocol/identity-hub-modules.md

@@ -2,9 +2,9 @@
 
 ![module-overview](./identity.hub.modules.png)
 
-## VC Module
+## VC Module (`:core:lib:verifiable-presentations-lib`)
 
-Contains the `VerifiablePresentationService` and a `CredentialManager`.<br/>
+Contains the `VerifiablePresentationService` implementation.<br/>
 Its job is to
 
 - generate and serve VPs (through the [Hub API](#hub-api))
@@ -14,33 +14,33 @@ Its job is to
 - exchanges protocol messages with the Issuer, e.g. in response to a credential-offer
 
 `VerifiableCredentialManager`: it can be configured whether credentials are auto-renewed (default is `true`). Once a
-renewal
-is triggered , it moves into the `REISSUE_REQUESTING` state. Generally, renewals can be triggered by three events:
+renewal is triggered , it moves into the `REISSUE_REQUESTING` state. Generally, renewals can be triggered by three
+events:
 
 1. an incoming credential offer
 2. the state machine detects a nearing expiry (if auto-renewal is active)
 3. a manual action via the Identity API
 
-## DID Module
+## DID Module (`:core:identity-hub-did`)
 
-Contains the `DidResourceManager`. Its job is to
+Contains the `DidDocumentService` implementation. Its job is to
 
 - create/read/update(/delete) DID resources in the `DidResourceStore`
 - publish/overwrite DID documents using the publishers
 - react to key rotation events from the [KeyPair module](#keypair-module): adds new keys to the DID, removes old ones,
   etc.
 - react to manual action via the Identity API
 
-## KeyPair Module
+## KeyPair Module (`:core:identity-hub-keypairs`)
 
-Contains the `KeyPairStateMachine`. Its job is to
+Contains the `KeyPairService` implementation. Its job is to
 
 - generate and maintain key pairs using a state machine
 - check for automatic renewal, e.g. if keys are configured with a max lifetime
 - send out events when a key is rotated
 - react to manual action via the Identity API
 
-## Auth/Permission Module
+## Auth/Permission Modules (`:core:lib`)
 
 Parses and validates tokens created by the STS:
 
@@ -57,9 +57,9 @@ Parses and validates tokens created by the STS:
 
 Handles transactions and combines the results of various lower-level services
 
-## Participant Context Module
+## Participant Context Module (`:core:identity-hub-participants`)
 
-Contains the `ParticipantRecordStore`, CRUDs participant entries ("records"). Mutating requests are only allowed for the
+Contains the `ParticipantContextStore`, CRUDs participant entries. Mutating requests are only allowed for the
 super-user (i.e. a technical user for some onboarding portal). The client only has read-access to its participant
 context.
 
@@ -72,7 +72,7 @@ against the Hub's APIs.
 
 all SPIs that are relevant here.
 
-## Hub API
+## Hub API (`:core:presentation-api`)
 
 This module contains implementations for
 the [Resolution API](https://github.com/eclipse-tractusx/identity-trust/blob/main/specifications/M1/verifiable.presentation.protocol.md#4-resolution-api)
@@ -81,7 +81,7 @@ the [Storage API](https://github.com/eclipse-tractusx/identity-trust/blob/main/s
 Is
 contains model classes, validators and JSON-LD-transformers.
 
-## Identity API
+## Identity API (`:extensions:api:identity-api`)
 
 This module contains implementations to maintain internal data structures, such as:
 
@@ -92,4 +92,4 @@ This module contains implementations to maintain internal data structures, such
 
 ## Not in the IdentityHub repo
 
-`CredentialVerificationService`
+modules to verify and validate VerifiableCredentials and VerifiablePresentations

docs/developer/architecture/identityhub-apis.md

@@ -0,0 +1,47 @@
+# APIs of the IdentityHub
+
+## Hub API
+
+This refers to a group of endpoints that implement functionality which is defined in
+the  [Decentralized Claims Protocol (DCP) specification](https://projects.eclipse.org/projects/technology.dataspace-dcp).
+These APIs is intended to be exposed to the internet.
+
+### Presentation API
+
+This API allows clients to request credentials in the form of a VerifiablePresentation. It is part of the Verifiable
+Credential Presentation protocol of the DCP specification.
+
+Please refer to the [API documentation](https://eclipse-edc.github.io/IdentityHub/openapi/ih-resolution-api) for more
+details.
+
+### Storage API
+
+This API offers endpoints to credentials issuers to store newly issued credentials in IdentityHub's persistent storage.
+
+> not yet implemented
+
+## Identity API
+
+IdentityHub's Identity API is used to manipulate information that pertain to a participant's identity. Specifically, DID
+documents, VerifiableCredentials and key pairs. Authorized clients can CRUD that information, for example adding
+a `service` to a DID document, or rotating or revoking a key pair.
+
+All endpoints of this API require authorization - every participant is only allowed to modify their own information. For
+details about IdentityHub's security and RBAC concept, please refer to [this document](./identity-api.security.md).
+
+The Identity API is not intended to be exposed to the internet without additional network infrastructure, such as API
+gateways. Please refer to
+the [EDC Best Practices](https://github.com/eclipse-edc/docs/blob/main/developer/best-practices.md) for more
+information.
+
+For more information please refer to
+the [API documentation](https://eclipse-edc.github.io/IdentityHub/openapi/identity-api).
+
+> Please note that this API is explicitly _not_ intended to store or update VerifiableCredentials. This process is
+> defined in the DCP specification and must be done via the Storage API.
+
+## Observability API
+
+The Observability API is intended to provide information about the application health to the Docker daemon via Docker
+health checks and the Kubernetes control plane via Kubernetes Readiness Probes. It is not intended to be reachable
+from outside the container as it lacks access control.