docs: add DID management documentation

Justfile

@@ -42,6 +42,7 @@ dev: githooks generate-owner-key
     $env.DWS_BACKEND = file
     $env.DWS_OWNER = (didkit key-to-did -k owner.jwk)
     $env.DWS_LOG_LEVEL = normal
+    # $env.DWS_TLS = '{certs="localhost.pem",key="localhost-key.pem"}'
     cargo watch -w src -x run
 
 # Fast check to verify that the codes still compiles
@@ -158,7 +159,7 @@ release LEVEL="patch" NEW_VERSION="":
     cargo update $manifest.name; git add Cargo.lock
     open README.md | str replace -a $current_version $new_version | save _README.md; mv _README.md README.md; git add README.md
     open -r ./docs/public/openapi.yaml | str replace -a $"version: \"($current_version)\"" $"version: \"($new_version)\"" | save ./docs/public/_openapi.yaml; mv ./docs/public/_openapi.yaml ./docs/public/openapi.yaml; git add ./docs/public/openapi.yaml
-    open -r ./docs/src/content/docs/getting-started.md | str replace -a $"identinet/did-web-server:($current_version)" $"identinet/did-web-server:($new_version)" | save ./docs/src/content/docs/_getting-started.md; mv ./docs/src/content/docs/_getting-started.md ./docs/src/content/docs/getting-started.md; git add ./docs/src/content/docs/getting-started.md
+    sed -i -e $"s,identinet/did-web-server:($current_version),identinet/did-web-server:($new_version),g" docs/src/**/*.md; git add docs/src/**/*.md
     git cliff -t $new_version -o CHANGELOG.md; git add CHANGELOG.md
     git commit -n -m $"Release version ($new_version)"
     just docker-build

docs/astro.config.mjs

@@ -61,10 +61,10 @@ export default defineConfig({
 					label: 'Deployment',
 					autogenerate: { directory: 'deployment' },
 				},
-				// {
-				// 	label: 'DID Management',
-				// 	autogenerate: { directory: 'did-management' },
-				// },
+				{
+					label: 'DID Management',
+					autogenerate: { directory: 'did-management' },
+				},
 				{ label: 'Congratulations', link: '/congratulations' },
 				...openAPISidebarGroups
 			],

docs/src/content/docs/deployment/local-test-server.md

@@ -2,6 +2,7 @@
 title: Local Test Server
 sidebar:
   order: 1
+  hidden: true
 ---
 
 First, follow the instructions in the [Getting Started Guide](/getting-started). Then continue with this guide.
@@ -37,19 +38,13 @@ Ensure that the previous command completed successfully before proceeding to the
 To issue the certificate for the test server, first switch to the directory in which you created the server's
 configuration (see [Getting Started Guide](/getting-started)). Then follow these step to issue and use the certificate:
 
-1. Issue certificate:
+1. Create private key and issue certificate:
 
 ```bash
 mkcert localhost
 ```
 
-2. Two new files have been generated, `localhost.pem` and `localhost-key.pem`. They need to be combined into one file:
-
-```bash
-cat localhost.pem localhost-key.pem > cert.pem
-```
-
-3. Now, let's enable the certificate in the configuration:
+2. Now, let's enable the certificate in the configuration:
 
 ```bash title=".env" {7}
 # Put the created or an existing DID here.
@@ -64,7 +59,7 @@ DWS_BACKEND=file
 DWS_BACKEND_FILE_STORE=/run/dws/did_store
 DWS_LOG_LEVEL=normal
 # For compatibilty with DID resolvers, a certificate is required. It will be added later.
-DWS_TLS=/run/dws/cert.pem
+DWS_TLS={certs="localhost.pem",key="localhost-key.pem"}
 ```
 
 4. With the updated configuration in place, let's restart the server:

docs/src/content/docs/deployment/self-hosting.md

@@ -2,5 +2,79 @@
 title: Self-Hosting
 sidebar:
   order: 2
-  hidden: true
 ---
+
+First, follow the instructions in the [Getting Started guide](/getting-started). Then continue with this guide.
+
+## Add TLS certificate
+
+With the completion of the [Getting Started guide](/getting-started), the server is functional to create, update and
+delete DIDs. However, when operating did-web-server under a DNS name other than `localhost` the did:web specification
+**requires resolvers to _only_ accept encrypted traffic**. Therefore, a certificate needs to be added to the server.
+
+If possible, obtain a valid certificate from a known Certificate Authority (CA) like Let's Encrypt and continue with
+section [Install Certifcation](#install-certificate). If this is not possible,
+[create a local CA](#create-local-certificate-authority) and with a self-issued certificate.
+
+### Create local Certificate Authority
+
+The excellent [mkcert](https://github.com/FiloSottile/mkcert) tool simplifies the creation and operating system
+integration of a local Certificate Authority. Follow these steps to set up the Certificate Authority:
+
+1. Install mkcert following the instructions on
+   [https://github.com/FiloSottile/mkcert](https://github.com/FiloSottile/mkcert)
+2. Setup and install local CA:
+
+```bash
+mkcert -install
+```
+
+Ensure that the previous command completed successfully before proceeding to the next step.
+
+### Issue self-signed Certificate for Server
+
+To issue the certificate, first determine the DNS name of the server. `example.com` is assumed in the following steps.
+
+Create private key and issue certificate:
+
+```bash
+mkcert example.com
+```
+
+### Install Certificate
+
+1. Now, let's enable the certificate in the configuration:
+
+```bash title=".env" {7}
+# Put the created or an existing DID here.
+DWS_OWNER=did:key:xxxx
+# Set DWS_ADDRESS to bind to all IPv4 and IPv6 addresses so the service can be exposed to the local computer.
+DWS_ADDRESS=::
+# Hostname and port determine the DIDs that are managed by this server, e.g. did:web:id.localhost%3A8000:xyz.
+DWS_EXTERNAL_HOSTNAME=example.com
+# Store DIDs on the local file system.
+DWS_BACKEND=file
+# DIDs will be stored in the `dids` folder below your current directory.
+DWS_BACKEND_FILE_STORE=/run/dws/did_store
+DWS_LOG_LEVEL=normal
+# For compatibilty with DID resolvers, a certificate is required. It will be added later.
+DWS_TLS={certs="example.com.pem",key="example.com-key.pem"}
+```
+
+2. With the updated configuration in place, let's restart the server:
+
+```bash
+docker run -it --rm -p 8000:443 --env-file .env -u "$(id -u):$(id -g)" -v "$PWD:/run/dws" identinet/did-web-server:0.2.0
+```
+
+### Test Functionality
+
+The validity of the test server's certificate can be tested by either visiting
+[https://example.com/person/did.json](https://example.com/person/did.json) in the browser or running the following
+command:
+
+```bash
+curl --fail-with-body https://example.com/person/did.json
+```
+
+Congratulations, you have a fully operational did-web-server instance! 🎉

docs/src/content/docs/did-management/deactivate-did.md

@@ -0,0 +1,115 @@
+---
+title: Deactivate DID
+sidebar:
+  order: 4
+---
+
+Deactivating a DID is a resverved operation for the server's owner. The steps for registering a DID are described in the
+[Getting Started guide](/getting-started).
+
+## Deactivate did:web DID
+
+did-web-server uses DIDs, Verifiable Credentials (VCs) and Verfiable Presentations (VPs) to verify access and encode
+data. The following diagram depicts the preparation process for removing a DID document from the server:
+
+1. The DID document is reqiured and can be fetched from the server.
+2. A Verifiable Credential is created that includes the DID document. The VC is signed by an authorized key.
+3. A Verifiable Presentation is created that includes the VC. The VP is signed by an authorized key. To mitigate replay
+   attacks, the VP must also contain specific proof parameters that can be retrieved from did-web-server.
+4. If the submitted VP and VC are successfully verfied, the included DID document is removed from the server.
+
+![Component diagram for creating and updating a DID document](/figures/did-creation-components.svg)
+
+### Retrieve DID document
+
+Execute the following command to create the DID document that includes both public keys:
+
+```bash title="person-did.json"
+curl --fail-with-body -o person-did.json http://localhost:8000/person/did.json
+```
+
+### Place DID document in Verifiable Credential
+
+Since did-web-server uses Verifiable Credentials for authentication and authorization, and DID documents as data, the
+created DID document needs to be placed within a Verifiable Credential. Execute the following command to create and sign
+the credential:
+
+```bash title="person-vc-did.json"
+cat > person-vc-did.json <<EOF
+{
+  "@context": [
+    "https://www.w3.org/2018/credentials/v1"
+  ],
+  "id": "uuid:49387f58-c0d9-4b14-a4f4-bc31a021d925",
+  "type": ["VerifiableCredential"],
+  "issuer": "$(cat owner.did)",
+  "issuanceDate": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "credentialSubject": $(cat person-did.json)
+}
+EOF
+```
+
+Sign credential:
+
+```bash title="person-vc-did-signed.json"
+VERIFICATION_METHOD="$(docker run --rm --network=host identinet/didkit-cli:0.3.2-4 did resolve "$(cat owner.did)" | jq -r '.assertionMethod.[0]')"
+docker run -i --rm -u "$(id -u):$(id -g)" -v "$PWD:/run/didkit" --network=host identinet/didkit-cli:0.3.2-4 credential issue \
+  -k owner.jwk -p assertionMethod -t Ed25519Signature2018 -v "$VERIFICATION_METHOD" < person-vc-did.json > person-vc-did-signed.json
+```
+
+### Place Verifiable Credential in Verifiable Presentation
+
+The last step in preparing the data for submission is to place the signed Verifiable Credential within a Verifiable
+Presentation and secure the registration against replay attacks. did-web-server prevents reply attacks i.e. the
+observation and resubmission of a valid presentation with the goal of overwriting the current configuration of the DID,
+by expecting the hash of the current DID document to be present as a
+[challenge](https://www.w3.org/TR/vc-data-integrity/#proofs) in the proof section of the Verifiable Presentation,
+alongside other parameters.
+
+The first step of placing the Verifiable Credential inside a Verifiable Presentation is to retrieve the proof parameters
+for the DID:
+
+```bash title="person-vp-proof-parameters.json"
+curl --fail-with-body -o person-vp-proof-parameters.json http://localhost:8000/person/did.json?proofParameters
+```
+
+With the proof parameters in place, the next step is to create the presentation:
+
+```bash title="person-vp.json"
+cat > person-vp.json <<EOF
+{
+  "@context": "https://www.w3.org/2018/credentials/v1",
+  "type": ["VerifiablePresentation"],
+  "holder": "$(cat owner.did)",
+  "verifiableCredential": $(cat person-vc-did-signed.json)
+}
+EOF
+```
+
+Finally, sign the presentation with the correct proof parameters:
+
+```bash title="person-vp-did-signed.json"
+VERIFICATION_METHOD="$(docker run --rm --network=host identinet/didkit-cli:0.3.2-4 did resolve "$(cat owner.did)" | jq -r '.assertionMethod.[0]')"
+DOMAIN="$(jq -r .domain person-vp-proof-parameters.json)"
+CHALLENGE="$(jq -r .challenge person-vp-proof-parameters.json)"
+PROOF_PURPOSE="$(jq -r .proof_purpose person-vp-proof-parameters.json)"
+docker run -i --rm -u "$(id -u):$(id -g)" -v "$PWD:/run/didkit" --network=host identinet/didkit-cli:0.3.2-4 presentation issue \
+  -k owner.jwk -p "$PROOF_PURPOSE" -t Ed25519Signature2018 -v "$VERIFICATION_METHOD" -d "$DOMAIN" -C "$CHALLENGE" \
+< person-vp.json > person-vp-signed.json
+```
+
+### Deactivate DID on server
+
+The last step is to submit the signed presentation to the server:
+
+```bash
+curl --fail-with-body -X DELETE -d @person-vp-signed.json http://localhost:8000/person/did.json
+```
+
+Let's verify that the DID document doesn't exist anymore:
+
+```bash
+curl --fail-with-body http://localhost:8000/person/did.json
+```
+
+Congratulations, you've deleted the DID document! 🎉

docs/src/content/docs/did-management/register-did.md

@@ -0,0 +1,11 @@
+---
+title: Register DID
+sidebar:
+  order: 2
+---
+
+Registering a DID is a resverved operation for the server's owner. The steps for registering a DID are described in the
+[Getting Started guide](/getting-started).
+
+DID controllers are only permitted to [update](/did-management/update-did) their DID or
+[resolve](/did-management/resolve-did) DIDs.

docs/src/content/docs/did-management/resolve-did.md

@@ -0,0 +1,17 @@
+---
+title: Resolve DID
+sidebar:
+  order: 1
+---
+
+Resolve a DID is an operation available without prior authentication. did-web-server implements the
+[did:web method specification](https://w3c-ccg.github.io/did-method-web/) for resolving DIDs.
+
+Example:
+
+- Given DID `did:web:localhost#3A8000:person`
+- Execute this command to resolve it:
+
+```bash
+curl --fail-with-body http://localhost:8000/person/did.json | jq
+```