removed incorrect stuff from docs for v6 release. added discovery examples

docs/_static/auth/v2.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.0
 info:
   title: Auth v2 API (experimental)
-  version: 0.0.0
+  version: 2.0.0
 servers:
   - url: http://localhost:8081
     description: For internal-facing endpoints.
@@ -175,7 +175,7 @@ paths:
       operationId: createDPoPProof
       summary: Create a DPoP proof as specified by RFC9449 for a given access token. It is to be used as HTTP header when accessing resources.
       tags:
-        - oauth2
+        - auth
       parameters:
         - name: kid
           in: path
@@ -217,7 +217,7 @@ paths:
         * The ath field in the DPoP proof matches the hash of the access token
         * The jti field in the DPoP proof is unique
       tags:
-        - oauth2
+        - auth
       requestBody:
         required: true
         content:

docs/pages/contribute.rst

@@ -3,23 +3,3 @@ Contribute
 ##########
 
 If you want to contribute to any of the nuts foundation projects or to this documentation, please fork the correct project from `Github <https://github.com/nuts-foundation>`_ and create a pull-request.
-
-***************************
-Documentation contributions
-***************************
-
-Documentation is written in Restructured Text. A CheatSheet can be found `here <https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html>`_.
-
-You can test your documentation by installing the required components.
-
-****************************
-Documentation initialisation
-****************************
-
-When starting a new project, the documentation can be initialised using::
-
-    sphinx-quickstart docs
-
-This will start the interactive setup of sphinx with a document root at *docs*. For Nuts projects we use that specific directory for documentation in a code project. You might have noticed that the *nuts-documentation* repo uses the root directory as documentation root.
-
-Most defaults will do, although we use intersphinx to go back-and-forth between the different sub-projects.

docs/pages/deployment/discovery.rst

@@ -35,17 +35,31 @@ If multiple query parameters are specified, all of them must match a single Veri
 Registration
 ============
 
-To register a DID on a Discovery Service, the DID must be activated for the service.
-The Nuts node will then register a Verifiable Presentation of the DID on the service, and periodically refresh it.
-E.g., for service ``coffeecorner`` and DID ``did:web:example.com``:
+To register a subject on a Discovery Service, the subject must be activated for the service.
+The Nuts node will then register a Verifiable Presentation for all subject DIDs on the service, and periodically refresh it.
+E.g., for service ``coffeecorner`` and subject ``example``:
 
 .. code-block:: text
 
-    POST /internal/discovery/v1/coffeecorner/did:web:example.com
+    POST /internal/discovery/v1/coffeecorner/example
 
 The DID's wallet must contain the Verifiable Credential(s) that are required by the service definition,
 otherwise registration will fail. If the wallet does not contain the credentials,
-the Nuts node will retry registration periodically.
+the Nuts node will retry registration periodically for all DIDs of a subject.
+
+Optionally, a POST body can be provided with registration parameters, e.g.:
+
+.. code-block:: json
+
+    {
+      "registrationParameters": {
+        "endpoint": "https://api.example.com",
+        "contact": "alice@example.com"
+      }
+    }
+
+This can be used to provide additional information. All registration parameters are returned by the search API.
+The ``authServerURL`` is added automatically by the Nuts node. It's constructed as ``https://<config.url>/oauth2/<subject_id>``.
 
 Servers
 *******
@@ -68,4 +82,73 @@ The endpoint for a Discovery Service MUST be in the following form (unless mappe
 
     https://<host>/discovery/<service_id>
 
-Where ``<service_id>`` is the ID of the service, e.g.: ``/discovery/coffeecorner``.
+Where ``<service_id>`` is the ID of the service, e.g.: ``/discovery/coffeecorner``.
+
+Service definitions
+*******************
+
+.. code-block:: json
+
+   {
+      "id": "coffeecorner",
+      "did_methods": ["web", "nuts"],
+      "endpoint": "https://example.com/discovery/coffeecorner",
+      "presentation_max_validity": 36000,
+      "presentation_definition": {
+        "id": "coffeecorner2024",
+        "format": {
+          "ldp_vc": {
+            "proof_type": [
+              "JsonWebSignature2020"
+            ]
+          },
+          "jwt_vp": {
+            "alg": ["ES256"]
+          }
+        },
+        "input_descriptors": [
+          {
+            "id": "NutsOrganizationCredential",
+            "constraints": {
+              "fields": [
+                {
+                  "path": [
+                    "$.type"
+                  ],
+                  "filter": {
+                    "type": "string",
+                    "const": "NutsOrganizationCredential"
+                  }
+                },
+                {
+                  "path": [
+                    "$.credentialSubject.organization.name"
+                  ],
+                  "filter": {
+                    "type": "string"
+                  }
+                },
+                {
+                  "path": [
+                    "$.credentialSubject.organization.city"
+                  ],
+                  "filter": {
+                    "type": "string"
+                  }
+                }
+              ]
+            }
+          }
+        ]
+      }
+    }
+
+
+A service definition consists of:
+- ``id``: the unique identifier of the service
+- ``did_methods``: the DID methods that are allowed (optional)
+- ``endpoint``: the URL of the service
+- ``presentation_max_validity``: the maximum validity of the Verifiable Presentation in seconds
+- ``presentation_definition``: the presentation definition that specifies the required Verifiable Credentials (see `Presentation Definitions <https://identity.foundation/presentation-exchange/>`_)
+
+For details see `Nuts RFC022 <https://nuts-foundation.gitbook.io/drafts/rfc/rfc022-discovery-service>`_.

docs/pages/deployment/docker.rst

@@ -50,8 +50,8 @@ Start the service:
     If your use case makes use of ``did:nuts`` DIDs, you also need to export port ``5555``, which is used for gRPC traffic by the Nuts network,
     and add a volume mount for data on ``/nuts/data`` (see below).
 
-You can test whether your Nuts Node is running properly by visiting ``http://localhost:8081/status/diagnostics``. It should
-display diagnostic information about the state of the node.
+You can test whether your Nuts Node is running properly by visiting ``http://localhost:8081/health``. It should
+display health information about the state of the node.
 
 User
 ****

docs/pages/deployment/key-rotation.rst

@@ -5,18 +5,15 @@ Key rotation procedure
 
 To minimize the impact of stolen/leaked keys, private keys should be rotated at a regular, scheduled interval.
 This applies to any private key used for a longer period of time.
-The node aids this procedure by supporting operations to add and remove keys from DID documents.
-
-Removal of old keys from the DID document should only be done if there are no verifiable credentials still active.
-To ensure this, all verifiable credentials should set a validity period.
+The node aids this procedure by supporting operations to add to DID documents.
+Removal of keys is currently not supported. Newer keys are automatically used for cryptographic operations.
 
 Procedure
 *********
 
 The procedure to rotate a key is two fold. The two procedures can be performed independently.
 
 Given a period of time, eg. every month when issuing a lot of credentials or every year when issuing only a few, a new key should be added to the DID document.
-To remove old keys from the DID document, you need to ensure that all verifiable credentials have expired.
 
 .. note::
 
@@ -30,17 +27,6 @@ Then, you add a new key which generates a new key pair in your crypto storage an
 
 .. code-block:: shell
 
-    POST /internal/vdr/v2/did/{did}/verificationmethod
-
-When successful, it returns the verification method that was added to the DID document.
-
-2. Remove a key
-===============
-
-To remove a key from the DID document.
-
-.. code-block:: shell
-
-    DELETE /internal/vdr/v2/did/{did}/verificationmethod/{kid}
+    POST /internal/vdr/v2/subject/{id}/verificationmethod
 
-When successful, it returns with a ``204`` tatus code
+When successful, it returns the verification method(s) that were added to the DID document(s).

docs/pages/deployment/logging.rst

@@ -26,4 +26,6 @@ The following fields are always available:
 - ``module``: the module that logged the message, e.g. ``VDR`` or `Auth``
 - ``level``: the level of the log message, e.g. ``info`` or ``error``
 - ``time``: the timestamp of the log message, e.g. ``2023-01-14T07:34:16+01:00``
-- ``msg``: the actual log message
+- ``msg``: the actual log message
+
+Operations that manipulate or use private keys directly will generate a log with ``level`` set to ``audit``.

docs/pages/deployment/monitoring.rst

@@ -84,7 +84,8 @@ Basic diagnostics
 
 .. note::
 
-    this page is intended to be read by humans, not machines
+    this page is intended to be read by humans, not machines.
+    all but the ``status`` entry are related to V5 functionality (gRPC network, VDRv1 and VCRv1 APIs).
 
 Returns the status of the various services in ``yaml`` format:
 

docs/pages/deployment/storage.rst

@@ -7,12 +7,12 @@ The Nuts node supports different backends for storage. This page describes the p
 
 .. note::
 
-    This page does not describe how to configure storage when using ``did:nuts`` DIDs and/or the Nuts gRPC network,
+    This page does not describe how to configure storage when using ``did:nuts`` DIDs and the Nuts gRPC network,
     which require specific storage configuration. If your use case require these features, refer to the v5 documentation for configuration storage.
 
 The Nuts node uses two types of storage:
 
-- SQL database for storing (``did:web``) DID documents and Verifiable Credentials.
+- SQL database for storing DID documents and Verifiable Credentials.
 - Private key storage for securely storing cryptographic private keys.
 
 The Nuts node does not backup your data, remember to backup the data in these storages regularly.
@@ -60,9 +60,9 @@ Microsoft Azure Key Vault
 This storage backend uses Microsoft Azure's Key Vault. It authenticates to the Azure Key Vault at the configured URL using the default credential,
 typically an Azure Managed Identity. Refer to the `Azure SDK for Go documentation <https://github.com/Azure/azure-sdk-for-go/wiki/Set-up-Your-Environment-for-Authentication>`_ for more information.
 
-- Azure Key Vault storage can't be used for nodes that produce ``did:nuts`` DIDs or for data encryption.
 - To store private keys in an Azure Key Vault HSM, set ``crypto.azurekv.hsm`` to ``true``.
 - Keys created through this storage backend are marked as non-exportable.
+- Azure Key Vault storage can't be used for encrypting ``did:nuts`` private credentials or for data encryption.
 
 HashiCorp Vault
 ===============
@@ -72,7 +72,7 @@ The path prefix defaults to ``kv`` and can be configured using the ``crypto.vaul
 There needs to be a KV Secrets Engine (v1) enabled under this prefix path.
 
 All private keys are stored under the path ``<prefix>/nuts-private-keys/*``.
-Each key is stored under the kid, resulting in a full key path like ``kv/nuts-private-keys/did:nuts:123#abc``.
+Each key is stored under a UUID, resulting in a full key path like ``kv/nuts-private-keys/bfedb25f-a218-4687-9acf-29a263ed4c50`` (old keys are stored under the kid).
 A Vault token must be provided by either configuring it using the config ``crypto.vault.token`` or setting the VAULT_TOKEN environment variable.
 The token must have a vault policy which has READ and WRITES rights on the path. In addition it needs to READ the token information "auth/token/lookup-self" which should be part of the default policy.
 

docs/pages/deployment/verifiable-credentials.rst

@@ -6,39 +6,6 @@ Verifiable Credentials
 One of the most important features of the Nuts node is handling Verifiable Credentials.
 This chapter describes the various configuration aspects of credentials in the Nuts node.
 
-Issuing and receiving over OpenID4VCI
-*************************************
-
-The Nuts node supports issuing and receiving credentials over OpenID Connect for `Verifiable Credential Issuance (OpenID4VCI) <https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html>`_.
-Discovery of issuer and wallets is done by looking up metadata on well-known endpoints.
-To allow discovery of an issuer or wallet, its DID document must contain a service of type `node-http-services-baseurl`,
-that specifies the HTTPS base URL of the `/n2n` interface of the node, excluding the latter.
-E.g., when the node's `/n2n` interface is available on `https://example.com/n2n`, the endpoint to be registered is `https://example.com`.
-As always, DID documents may reference the service in another DID document for easier administration.
-
-Auto-registration
-^^^^^^^^^^^^^^^^^
-
-If the `node-http-services-baseurl` service is not registered for the DIDs managed by the local node, it will automatically try to register it.
-For DID documents, which have a `NutsComm` service that isn't a reference,
-the node will inspect its TLS certificate's SANs and try to resolve its OpenID4VCI issuer metadata using a HTTP HEAD request.
-E.g., give the SAN `nuts.example.com` and DID `did:nuts:2nQtiQG6Cgm1GYTBaaKAgr76uY7iSexUkqX`, it will attempt the following request:
-
-```http
-HEAD https://nuts.example.com/n2n/identity/did:nuts:2nQtiQG6Cgm1GYTBaaKAgr76uY7iSexUkqX/.well-known/openid-configuration
-```
-
-When the endpoint responds with `200 OK` and `Content-Type: application/json`,
-the node will register the base URL (`https://nuts.example.com`) as `node-http-services-baseurl` service.
-
-If the DID document contains a `NutsComm` service that refers to another DID document,
-it will register a service reference the other DID document. But only if that DID document contains the `node-http-services-baseurl` service.
-
-After the auto-registration succeeds the node's OpenID4VCI wallet is discoverable for other nodes,
-and it can receive credentials from other nodes over OpenID4VCI.
-
-If you want to disable auto-registration, set `goldenhammer.enabled` to `false`.
-
 Custom Credential Configuration
 *******************************
 
@@ -47,7 +14,7 @@ This section describes how to configure your Nuts node to handle custom credenti
 Introduction
 ^^^^^^^^^^^^
 
-The Nuts node by default is configured to handle a set of Nuts credentials, such as `NutsAuthorizationCredential` and `NutsOrganizationCredential`. These credentials are accepted and indexed automatically. If you want to use custom credentials for your use-case, you have to tell your Nuts node how they are structured.
+The Nuts node by default is configured to handle a set of Nuts credentials, such as `NutsOrganizationCredential` and `NutsEmployeeCredential`. These credentials are accepted and indexed automatically. If you want to use custom credentials for your use-case, you have to tell your Nuts node how they are structured.
 A Verifiable Credential is structured as a JSON-LD document. Adding extra fields to a JSON-LD document requires adding an extra `@context`-definition which describes these fields.
 
 To configure your Nuts node to recognise these extra fields and custom types, you have to overwrite the JSON-LD configuration. This can be done using the `jsonld.contexts` config. More information about configuration options and its default values can be found at the :ref:`config documentation <nuts-node-config>`.

docs/pages/development/3-api.rst

@@ -63,24 +63,6 @@ To describe error responses, the specific responses need to be added to the API
 Paths
 *****
 
-The API paths are designed so different security schemes can be setup easily.
-
-API paths follow the following pattern:
-
-.. code-block:: text
-
-    /<context>/<engine>/<version>/<action>
-
-All paths start with a security ``<context>``:
+The API paths are designed so it's clear which APIs are to be blocked for external traffic.
 
 - ``/internal/**`` These APIs are meant to be behind a firewall and should only be available to the internal infrastructure.
-  All DID Document manipulation APIs fall under this category.
-- ``/n2n/**`` These APIs must be available to other nodes from the network.
-  This means they must be protected with the required client certificate as specified by `RFC011 <https://nuts-foundation.gitbook.io/drafts/rfc/rfc011-verifiable-credential>`_.
-  The creation of an access token is one example of such an API.
-- ``/public/**`` These APIs must be publicly available on a valid domain. No security must be configured other than a server certificate.
-  These APIs are used by mobile devices.
-
-After the context, the ``<engine>`` is expected. An engine defines a logical unit of functionality.
-Each engine has its own OAS file. Then as discussed earlier, the ``<version>`` is expected.
-The last part is the ``<action>``, this part can be freely chosen in a RESTful manor.

docs/pages/integrating/api-authentication.rst

@@ -17,7 +17,7 @@ an explanation about the failure.
 
 Configuration
 -------------
-Authentication can be enabled by setting ``http.internal.auth.type`` (see example above) to ``token_v2``.
+Authentication can be enabled by setting ``http.internal.auth.type`` (see example below) to ``token_v2``.
 Endpoints under ``/internal`` will then require a JWT signed by an authorized key.
 
 Authorized (public) keys are specified in an ``authorized_keys`` file configured by the ``http.internal.auth.type.authorizedkeyspath`` parameter.

docs/pages/integrating/supported-protocols-formats.rst

@@ -4,6 +4,7 @@ Supported Protocols and Formats
 ===============================
 
 This page documents which cryptographic algorithms, key types and SSI formats and protocols are supported.
+Various protocols have a draft status and success on using them may vary.
 
 Cryptographic Algorithms
 ************************

docs/pages/integrating/vc.rst

@@ -33,7 +33,9 @@ Calling `/internal/vcr/v2/issuer/vc` with
                 "city": "IJbergen"
             }
         },
-        "visibility": "public"
+        "visibility": "public",
+        "format": "ldp_vc",
+        "publishToNetwork": false
     }
 
 Will be expanded by the node to:
@@ -68,10 +70,11 @@ Will be expanded by the node to:
       ]
     }
 
-The `visibility` property indicates the contents of the VC are published on the network, so it can be read by everyone.
-
-By default, the node will create credentials in JSON-LD format.
-You can specify the format by passing the `format` parameter (``jwt_vc`` or ``ldp_vc``).
+There are three parameters that can be passed:
+- `format` (optional): The format of the VC. Can be ``ldp_vc`` or ``jwt_vc``. Default is ``ldp_vc``.
+- `publishToNetwork` (did:nuts only, optional): Whether the VC should be published on the network. Default is ``true``.
+- `visibility` (did:nuts only, optional): The visibility of the VC. Can be ``public`` or ``private``. Default is ``private``.
+- `withStatusList2021Revocation` (no did:nuts, optional): Whether the VC should be issued with a status list 2021 revocation. Default is ``false``.
 
 .. _searching-vcs:
 

docs/pages/release_notes.rst

@@ -52,6 +52,7 @@ Changes
 - Documentation of ``did:nuts``-related features have been removed (refer to v5 documentation).
 - Documentation of specific use cases (e.g. health care in general or eOverdracht) has been moved to the `Nuts wiki <https://wiki.nuts.nl>`_.
 - Node can now be run without configuring TLS when the gRPC network isn't used (no bootstrap node configured and no network state), to cater use cases that don't use ``did:nuts``.
+- Crypto backends store keys under a key name and are linked to the kid via the ``key_reference`` SQL table.
 
 The following features have also been changed: