From 09c4b3fed9b537006dd9e5a48441066170624e51 Mon Sep 17 00:00:00 2001 From: Gerard Snaauw <33763579+gerardsn@users.noreply.github.com> Date: Mon, 4 Nov 2024 16:09:13 +0100 Subject: [PATCH] Several doc fixes (#3537) --- docs/pages/deployment/discovery.rst | 1 + docs/pages/deployment/migration.rst | 2 +- docs/pages/deployment/oauth.rst | 14 ++++++++++++-- docs/pages/deployment/recommended-deployment.rst | 2 +- docs/pages/development/2-releasing.rst | 1 + docs/pages/integrating/api-authentication.rst | 2 +- docs/pages/integrating/vc.rst | 3 +++ 7 files changed, 20 insertions(+), 5 deletions(-) diff --git a/docs/pages/deployment/discovery.rst b/docs/pages/deployment/discovery.rst index b6d1104b5b..fc7b4d0494 100644 --- a/docs/pages/deployment/discovery.rst +++ b/docs/pages/deployment/discovery.rst @@ -176,6 +176,7 @@ Service definitions 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 diff --git a/docs/pages/deployment/migration.rst b/docs/pages/deployment/migration.rst index 6734b695d6..437071e888 100644 --- a/docs/pages/deployment/migration.rst +++ b/docs/pages/deployment/migration.rst @@ -13,7 +13,7 @@ Nuts node v6 runs several migrations on startup for DID documents that are manag Requires ``didmethods`` to contain ``nuts``. Previously, DID documents could either by under self-control or under control of another DID as was recommended for vendor and care organisation, respectively. -In the new situation a user manages ``subject``s, and the node manages all DIDs under the ``subject``. +In the new situation a user manages ``subjects``, and the node manages all DIDs under the ``subject``. To reduce complexity and allow future adoption of other did methods, all documents will be under self-control from v6. **Migration: convert did:nuts to subject** diff --git a/docs/pages/deployment/oauth.rst b/docs/pages/deployment/oauth.rst index cb4e54c718..61891dae61 100644 --- a/docs/pages/deployment/oauth.rst +++ b/docs/pages/deployment/oauth.rst @@ -14,6 +14,7 @@ The Nuts node implements (parts of) the following RFCs: - `RFC 9449 `_ - OAuth 2.0 Demonstrating Proof of Possession (DPoP) - `Nuts RFC021 `_ - RFC021 VP Token Grant Type - `OpenID4VP `_ - OpenID for Verifiable Presentations - draft 20 +- `StatusList2021 `_ - Status List 2021 - `Presentation Exchange `_ - Presentation Exchange @@ -58,5 +59,14 @@ A resources server must check the type of access token used to request data. If The Nuts node provides a convenience API to do this for you. Some of the calls to the Nuts node are required because it handles key material for the DPoP Proof. The keys used for the DPoP headers are taken from the DID Document of a tenant. More information can be found on the `API documentation `_ page. The relevant API's are: -- ``POST /internal/auth/v2/{did}/dpop`` -- ``POST /internal/auth/v2/dpop_validate`` \ No newline at end of file + +- ``POST /internal/auth/v2/dpop/{kid}`` +- ``POST /internal/auth/v2/dpop/validate`` + +StatusList2021 +************** + +The revocation status of presented Verifiable Credentials that contain a ``credentialStatus`` with type ``StatusList2021Entry`` will automatically be validated. +To issue a Verifiable Credential that can be revoked, see ``POST /internal/vcr/v2/issuer/vc`` in the `API documentation `_. +Be aware that the Nuts-node hosts a ``StatusList2021Credential`` with the revocation status of all issued credentials. +This endpoint MUST be available for some time after the last VC on the list has been revoked, or until all VCs on the list have expired. \ No newline at end of file diff --git a/docs/pages/deployment/recommended-deployment.rst b/docs/pages/deployment/recommended-deployment.rst index f371d377b8..be64ab4cff 100644 --- a/docs/pages/deployment/recommended-deployment.rst +++ b/docs/pages/deployment/recommended-deployment.rst @@ -180,7 +180,7 @@ Below is a list of items that should be addressed when running a node in product - Reverse proxy - Use a proxy in front of the node which terminates TLS - - Make sure the reverse proxy sends the ``X-Forwarded-For`` header to log correct IP addresses + - Make sure the reverse proxy sets the header configured in ``http.clientipheader`` (default ``X-Forwarded-For``) to log correct IP addresses - Backup Management - Make sure data is backed up (data stored in SQL and private keys) - Have a tested backup/restore procedure diff --git a/docs/pages/development/2-releasing.rst b/docs/pages/development/2-releasing.rst index 5bdbac7b48..3c7573eec3 100644 --- a/docs/pages/development/2-releasing.rst +++ b/docs/pages/development/2-releasing.rst @@ -6,6 +6,7 @@ Releasing Nuts Node Nuts Node and auxiliary tools/applications follow a semantic versioning scheme (``..(-rc.)``): Given a version number MAJOR.MINOR.PATCH, increment the: + 1. MAJOR version when you make incompatible API changes, 2. MINOR version when you add functionality in a backwards compatible manner, and 3. PATCH version when you make backwards compatible bug fixes. diff --git a/docs/pages/integrating/api-authentication.rst b/docs/pages/integrating/api-authentication.rst index df15b7d285..d0e95d89f8 100644 --- a/docs/pages/integrating/api-authentication.rst +++ b/docs/pages/integrating/api-authentication.rst @@ -131,7 +131,7 @@ To generate the SSH fingerprint of a key (for specifying as ``kid`` field) using nuts-jwt-generator -i /path/to/keyfile -export-ssh-fingerprint -The ``ssh-keygen``` command unfortunately fails for Ed25519 PEM keys at the time of this writing due to a `bug `_ and poor recent support for Ed25519 in libcrypto packages. +The ``ssh-keygen`` command unfortunately fails for Ed25519 PEM keys at the time of this writing due to a `bug `_ and poor recent support for Ed25519 in libcrypto packages. You can use the nuts-jwt-generator until this bug is fixed for keys of this type. Generating keys diff --git a/docs/pages/integrating/vc.rst b/docs/pages/integrating/vc.rst index 800da6905b..9cc1dc7f33 100644 --- a/docs/pages/integrating/vc.rst +++ b/docs/pages/integrating/vc.rst @@ -71,6 +71,7 @@ Will be expanded by the node to: } 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``. @@ -126,8 +127,10 @@ The following query does not return all `NutsOrganizationCredential` but **all** To find certain credentials, you'll need to add fields that are required to exist in the desired credential. By default, matching is exact: it only returns the result when the given value exactly matches. There are 2 other matchers for strings: + - ``"*"`` to match credential fields that contain the field (non-empty) - ``*`` as postfix to match credential fields that start with the given string, e.g. ``Hospital Amst*`` + When ``*`` is used anywhere else in the string it won't be interpreted as wildcard and matched as-is. Wildcards are not supported for other types than strings.