Clarify and align normative language

This commit resolves inconsistencies in the use of RFC 2119 keywords
across the draft, including inappropriate uses of "REQUIRED" and
"RECOMMENDED", which have been replaced with "MUST" and "SHOULD"
as per BCP 14.

Key changes:
- Upgraded certain "SHOULD" statements to "MUST" for security, reliability, and interoperability
- Harmonized conflicting statements on resource discovery and identifier uniqueness
- Added clarifications for "sensitive data", "standard authentication protocol", and error formatting
- Reduced redundancy in API exposure requirements

These adjustments improve internal consistency and remove ambiguity for implementers ahead of IETF 123.

Closes: #206

Author: mickenordin

IETF-RFC.md

@@ -44,8 +44,8 @@ Open Cloud Mesh only handles the necessary interactions up to the point where th
 --- middle
 
 # Terms
-The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
-NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
+The key words "MUST", "MUST NOT", "MUST", "SHALL", "SHALL
+NOT", "SHOULD", "SHOULD NOT", "SHOULD",  "MAY", and
 "OPTIONAL" in this document are to be interpreted as described in
 RFC 2119.
 
@@ -139,11 +139,11 @@ Whereas the precise syntax of the Invite Message and the Invite Acceptance Gestu
 * to the `/invite-accepted` path in the Invite Sender OCM Server's OCM API
 * using `application/json` as the `Content-Type` HTTP request header
 * its request body containing a JSON document representing an object with the following string fields:
-  * REQUIRED: `recipientProvider` - FQDN of the Invite Receiver OCM Server
-  * REQUIRED: `token` - the Invite Token. The Invite Sender OCM Server SHOULD recall which Invite Sender OCM Address this token was linked to
-  * REQUIRED: `userID` - the Invite Receiver's identifier at their OCM Server
-  * REQUIRED: `email` - non-normative / informational; an email address for the Invite Receiver. Not necessarily at the same FQDN as their OCM Server
-  * REQUIRED: `name` - human-readable name of the Invite Receiver, as a suggestion for display in the Invite Sender's address book
+  * MUST: `recipientProvider` - FQDN of the Invite Receiver OCM Server
+  * MUST: `token` - the Invite Token. The Invite Sender OCM Server SHOULD recall which Invite Sender OCM Address this token was linked to
+  * MUST: `userID` - the Invite Receiver's identifier at their OCM Server
+  * MUST: `email` - non-normative / informational; an email address for the Invite Receiver. Not necessarily at the same FQDN as their OCM Server
+  * MUST: `name` - human-readable name of the Invite Receiver, as a suggestion for display in the Invite Sender's address book
 * using TLS
 * using [httpsig](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12)
 
@@ -163,9 +163,9 @@ The Invite Acceptance Response SHOULD be a HTTP response:
 * in response to the Invite Acceptance Request
 * using `application/json` as the `Content-Type` HTTP response header
 * its response body containing a JSON document representing an object with the following string fields:
-  * REQUIRED: `userID` - the Invite Sender's identifier at their OCM Server
-  * REQUIRED: `email` - non-normative / informational; an email address for the Invite Sender. Not necessarily at the same FQDN as their OCM Server
-  * REQUIRED: `name` - human-readable name of the Invite Sender, as a suggestion for display in the Invite Receiver's address book
+  * MUST: `userID` - the Invite Sender's identifier at their OCM Server
+  * MUST: `email` - non-normative / informational; an email address for the Invite Sender. Not necessarily at the same FQDN as their OCM Server
+  * MUST: `name` - human-readable name of the Invite Sender, as a suggestion for display in the Invite Receiver's address book
 
 A 200 response status means the Invite Acceptance Request was successful.
 A 400 response status means the Invite Token is invalid or does not exist.
@@ -239,11 +239,11 @@ Step 7: The JSON response body is the data that was discovered.
 ## Fields
 The JSON response body offered by the Discoverable Server SHOULD contain the following information about its OCM API:
 
-* REQUIRED: enabled (boolean) - Whether the OCM service is enabled at this endpoint
-* REQUIRED: apiVersion (string) - The OCM API version this endpoint supports. Example: `"1.2.0"`
-* REQUIRED: endPoint (string) - The URI of the OCM API available at this endpoint. Example: `"https://my-cloud-storage.org/ocm"`
+* MUST: enabled (boolean) - Whether the OCM service is enabled at this endpoint
+* MUST: apiVersion (string) - The OCM API version this endpoint supports. Example: `"1.2.0"`
+* MUST: endPoint (string) - The URI of the OCM API available at this endpoint. Example: `"https://my-cloud-storage.org/ocm"`
 * OPTIONAL: provider (string) - A friendly branding name of this endpoint. Example: `"MyCloudStorage"`
-* REQUIRED: resourceTypes (array) - A list of all resource types this server supports in both the Sending Server role and the Receiving Server role, with their access protocols. Each item in this list should
+* MUST: resourceTypes (array) - A list of all resource types this server supports in both the Sending Server role and the Receiving Server role, with their access protocols. Each item in this list should
 itself be an object containing the following fields:
   * name (string) -  A supported resource type (file, folder, calendar, contact, ...).
                 Implementations MUST offer support for at least one resource type, where `file` is the commonly supported one. Each resource type is identified by its `name`:
@@ -301,10 +301,10 @@ itself be an object containing the following fields:
 * OPTIONAL: publicKey (object) - The signatory used to sign outgoing request to confirm its origin. The 
           signatory is optional, but if present, it MUST contain two string fields, `id` and `publicKeyPem`.
         properties:
-  * REQUIRED keyId (string) unique id of the key in URI format. The hostname set the origin of the 
+  * MUST keyId (string) unique id of the key in URI format. The hostname set the origin of the 
               request and MUST be identical to the current discovery endpoint.
             Example: https://my-cloud-storage.org/ocm#signature
-  * REQUIRED publicKeyPem (string) - PEM-encoded version of the public key.
+  * MUST publicKeyPem (string) - PEM-encoded version of the public key.
             Example: "-----BEGIN PUBLIC KEY-----\nMII...QDD\n-----END PUBLIC KEY-----\n"
 * OPTIONAL: inviteAcceptDialog (string) - URL path of a web page where a user can accept an invite, when query parameters `"token"` and `"providerDomain"` are provided. Implementations that offer the `"invites"` capability SHOULD provide this URL as well in order to enhance the UX of the Invite Flow. If for example `"/index.php/apps/sciencemesh/accept"` is specified here then a WAYF Page SHOULD redirect the end-user to `/index.php/apps/sciencemesh/accept?token=zi5kooKu3ivohr9a&providerDomain=example.com`.
 
@@ -319,28 +319,28 @@ To create a Share, the Sending Server SHOULD make a HTTP POST request
 
 ## Fields
 
-* REQUIRED shareWith (string)
+* MUST shareWith (string)
           Consumer specific identifier of the user, group or federation the provider
           wants to share the resource with. This is known in advance.
           Please note that the consumer service endpoint is known in advance
           as well, so this is no part of the request body.
         Example: "[email protected]"
-* REQUIRED name (string)
+* MUST name (string)
        Name of the resource (file or folder).
         Example: "resource.txt"
 * OPTIONAL description (string)
         Optional description of the resource (file or folder).
         Example: "This is the Open API Specification file (in YAML format) of the Open
           Cloud Mesh API."
-* REQUIRED providerId (string)
+* MUST providerId (string)
           Identifier to identify the shared resource at the provider side. This is
           unique per provider such that if the same resource is shared twice,
           this providerId will not be repeated.
         Example: 7c084226-d9a1-11e6-bf26-cec0c932ce01
-* REQUIRED owner (string) -
+* MUST owner (string) -
           Provider specific identifier of the user who owns the resource.
         Example: "[email protected]"
-* REQUIRED sender (string) -
+* MUST sender (string) -
           Provider specific identifier of the user that wants to share the
           resource. Please note that the requesting provider is being
           identified on a higher level, so the former `remote` property
@@ -352,20 +352,20 @@ To create a Share, the Sending Server SHOULD make a HTTP POST request
 * OPTIONAL senderDisplayName (string)
           Display name of the user that wants to share the resource
         Example: "John Doe"
-* REQUIRED shareType (string)
+* MUST shareType (string)
         SHOULD have a value of "user", "group", or "federation", to indicated that the first part
         of the `shareWith` OCM Address refers to a Receiving Party who is a single user of the Receiving Server,
         a group of users at the Receiving Servers, or a group of users that is spread out over various servers,
         including at least one user at the Receiving Server.
-* REQUIRED resourceType (string)
+* MUST resourceType (string)
           Resource type (file, folder, calendar, contact, ...)
 * OPTIONAL expiration (integer)
           The expiration time for the OCM share, in seconds
           of UTC time since Unix epoch. If omitted, it is assumed
           that the share does not expire.
 * OPTIONAL code (string)
           A nonce to be exchanged for a (potentially short-lived) bearer token at the Sending Server's /token endpoint.
-* REQUIRED protocol (object)
+* MUST protocol (object)
           JSON object with specific options for each protocol.
           The supported protocols are:
           - `webdav`, to access the data
@@ -401,7 +401,7 @@ If `multi` is given, one or more protocol
                 only support `webdav`.
 
    * Protocol details for `webdav` MAY contain:
-     * REQUIRED uri (string)
+     * MUST uri (string)
                     An URI to access the remote resource. The URI SHOULD be relative,
                     in which case the prefix exposed by the `/.well-known/ocm` endpoint MUST
                     be used. Absolute URIs are deprecated.
@@ -422,12 +422,12 @@ If `multi` is given, one or more protocol
                         signed HTTPS request. This MAY be used if the recipient provider exposes
                         the `receive-code` capability.
    * Protocol details for `webapp` MAY contain:
-     * REQUIRED uri (string)
+     * MUST uri (string)
                     An URI to a client-browsable view of the shared resource, such that
                     users may use the web applications available at the site. The URI SHOULD
                     be relative, in which case the prefix exposed by the `/.well-known/ocm`
                     endpoint MUST be used. Absolute URIs are deprecated.
-     * REQUIRED viewMode (string)
+     * MUST viewMode (string)
                     The permissions granted to the sharee. A subset of:
                     - `view` allows access to the web app in view-only mode.
                     - `read` allows read and download access via the web app.
@@ -436,7 +436,7 @@ If `multi` is given, one or more protocol
                     An optional secret to be used to access the remote web app,
                     for example in the form of a bearer token.
    * Protocol details for `datatx` MAY contain:
-     * REQUIRED srcUri (string)
+     * MUST srcUri (string)
                     An URI to access the remote resource. The URI SHOULD be relative,
                     in which case the prefix exposed by the `/.well-known/ocm` endpoint MUST
                     be used. Absolute URIs are deprecated.
@@ -481,10 +481,10 @@ make a HTTP POST request
 
 ## Fields
 
-* REQUIRED notificationType (string) - in a Share Acceptance Notification it SHOULD be one of:
+* MUST notificationType (string) - in a Share Acceptance Notification it SHOULD be one of:
   * 'SHARE_ACCEPTED'
   * 'SHARE_DECLINED'
-* REQUIRED providerId (string) - copied from the Share Creation Notification for the Share this notification is about
+* MUST providerId (string) - copied from the Share Creation Notification for the Share this notification is about
 * OPTIONAL resourceType (string) - copied from the Share Creation Notification for the Share this notification is about
 * OPTIONAL notification (object) - optional additional parameters, depending on the notification and the resource type
 
@@ -627,10 +627,10 @@ As an example, if the payload is about initiating a new share the file owner has
 # Appendix C: Directory Service
 
 A third-party Directory Service is a back-end service used to federate multiple OCM Servers and facilitate the Invite flow. It is expected to expose, via anonymous HTTP GET, a JSON document with the following format:
-  * REQUIRED: `federation` - a human-readable name for the list of OCM Servers exposed by the Directory Service
-  * REQUIRED: `servers` - a JSON array of objects to describe the list of OCM Servers with the following string fields:
-    * REQUIRED: `url` - the OCM Server's FQDN
-    * REQUIRED: `displayName` - a human-readable name for the OCM Server
+  * MUST: `federation` - a human-readable name for the list of OCM Servers exposed by the Directory Service
+  * MUST: `servers` - a JSON array of objects to describe the list of OCM Servers with the following string fields:
+    * MUST: `url` - the OCM Server's FQDN
+    * MUST: `displayName` - a human-readable name for the OCM Server
   Example:
   ```json
   {