Address feedback from Guiseppe

Co-authored-by: Giuseppe Lo Presti <[email protected]>

Author: mickenordin

IETF-RFC.md

@@ -94,7 +94,7 @@ have separate implementations for different functions.
 ### OCM Provider
 
 An OCM Provider is an entity that can take on the two _roles_ of a
-_Sending Server_ and a _Receiving Server_. An OCM Provider MUST be a
+_Sending Server_ and a _Receiving Server_.  An OCM Provider MUST be a
 _Discoverable Server_ and SHOULD be able to receive _Notifications_.
 
 ### OCM Directory Service
@@ -111,10 +111,10 @@ take on: the _Sending Server_ role and the _Receiving Server_ role.
 
 A Sending Server is an OCM Provider that holds Resources and exposes
 APIs to allow access to them.  It allows its users to create _Shares_
-to give other users access to those Resources. A Sending Server MAY
+to give other users access to those Resources.  A Sending Server MAY
 provide its users with the ability to generate _Invites_ to establish
-contact with other users on other OCM Providers. When doing so it MAY
-provide a _WAYF Page_ to facilitate the Invite Flow. The WAYF page MAY
+contact with other users on other OCM Providers.  When doing so it MAY
+provide a _WAYF Page_ to facilitate the Invite Flow.  The WAYF page MAY
 be limited to a set of trusted OCM Providers, for instance those in the
 same _Federation_.
 
@@ -124,7 +124,7 @@ same _Federation_.
 A Receiving Server is an OCM Provider that receives _Share_ Creation
 Notifications from Sending Servers, notifies its users about incoming
 _Shares_, and acts as an API client to allow its users to access Remote
-Resources. It MAY provide it's users with an _Address Book_ of
+Resources.  It MAY provide its users with an _Address Book_ of
 _Contacts_ and the ability to accept _Invites_.
 
 
@@ -139,7 +139,7 @@ elsewhere:
 * __Discoverable Server__ - A server that tries to supply information in
   OCM API Discovery.
 * __Federation__ - A group of OCM Providers that have established
-  mutual trust and agree on certain policies for interaction. A
+  mutual trust and agree on certain policies for interaction.  A
   Federation MAY be facilitated by a Directory Service.
 * __FQDN__ - Fully Qualified Domain Name, such as `"cloud.example.com"`.
 * __Invite Acceptance Gesture__ - Gesture from the Invite Receiver to
@@ -177,19 +177,19 @@ elsewhere:
   Invite Sender's OCM Address.
 * __OCM Address__ - identifies a user or group "at" an OCM Server.
 The OCM Address contains a server specific Party identifier, a host
-locating the OCM Server and an optional port. The OCM Address is not a
+locating the OCM Server and an optional port.  The OCM Address is not a
 URI as it does not have scheme and the identifier may contain reserved
 characters.
 
         ocm-address = identifier "@" host [ ":" port]
 
-    The identifier is an opaque, case-sensitive UTF-8 string. It is 
-    separated from the host by the last "@" in the OCM Address. It is
-    possible to have multiple @-signs in a OCM-address, e.g. when an 
-    email address is the local part of the address like 
+    The identifier is an opaque, case-sensitive UTF-8 string.  It is
+    separated from the host by the last "@" in the OCM Address.  It is
+    possible to have multiple @-signs in a OCM-address, e.g. when an
+    email address is the local part of the address like
     `[email protected]@ocm.example.org`.
 
-    host is an IP literal encapsulated within square brackets, an IPv4 
+    host is an IP literal encapsulated within square brackets, an IPv4
     address in dotted decimal form, or a registered name as described in
     [RFC3986].
 
@@ -198,8 +198,8 @@ characters.
     The optional port subcomponent can be used to specify a port to use
     for discovery (see Discovery Process).
 
-    The OCM Server MUST be discoverable at the given host and optional 
-    port via the Well-Known [RFC8615] path `/.well-known/ocm`. The OCM 
+    The OCM Server MUST be discoverable at the given host and optional
+    port via the Well-Known [RFC8615] path `/.well-known/ocm`.  The OCM
     Address MUST NOT contain a path.
 
 * __OCM API Discovery__ - Process of evaluating properties of a Remote
@@ -262,15 +262,15 @@ characters.
     another OCM Server, based on out-of-band information, federation
     membership or prior interactions, SHOULD be recorded in an internal
     registry of trusted servers, that SHOULD be updated over time based
-    on new information. The registry SHOULD include the FQDN of the 
-    trusted server and the Public Key used for HTTP Signatures. It MAY
+    on new information.  The registry SHOULD include the FQDN of the
+    trusted server and the Public Key used for HTTP Signatures.  It MAY
     also include additional metadata such as the inviteAcceptDialog URL
     or supported capabilities.
 * __WAYF Page__ - A Where-Are-You-From page is a discovery service used
   to identify the OCM Server of an Invite Receiver.
 
 In Appendix D, an object model is presented as a non-normative guide for
-implementators to understand the relationships between these terms.
+implementers to understand the relationships between these terms.
 
 # General Flow
 
@@ -476,11 +476,11 @@ time without notifying them.
 
 ### Invite format
 To accept an invite, two pieces of information are required: a `token`
-and a `provider`. There are two recognized formats:
+and a `provider`.  There are two recognized formats:
 
 * **Invite string format:**
   A base64-encoded string containing the token and the provider’s FQDN,
-  joined by an `@` sign. Example:
+  joined by an `@` sign.  Example:
 
   If the `token` is `a55a966e-15c1-4cb9-a39d-4e4c54399baf` and the
   `provider` is `my-cloud-storage.org`, the combined string is
@@ -495,7 +495,7 @@ and a `provider`. There are two recognized formats:
 
 * **Link format:**
   If the inviting OCM Server supports a WAYF page, the invite may be
-  provided as a link with the token as a request parameter. Example:
+  provided as a link with the token as a request parameter.  Example:
 
   `https://my-cloud-storage.org/wayf?token=
   a55a966e-15c1-4cb9-a39d-4e4c54399baf`
@@ -611,7 +611,7 @@ Step 4: If not, try a HTTP GET with `https://<fqdn>/ocm-provider` as
 the URL instead.
 Step 5: If that results in a valid HTTP response with a valid JSON
 response body within reasonable time, go to step 7.
-Step 6: If not, fail. Implementations MAY fallback to HTTP instead
+Step 6: If not, fail.  Implementations MAY fallback to HTTP instead
 of HTTPS in testing setups and retry steps 2-5, in particular when
 an optional port is given in the address.
 Step 7: The JSON response body is the data that was discovered.
@@ -988,7 +988,7 @@ with any related share.
 Notifications from Sending Server to Receiving Server SHOULD use
 httpsig [RFC9421] so the Receiving Server can authenticate the origin
 of the notification.  Receiving Servers SHOULD decline notifications
-from Sending Servers without httpsig as it can't identify where the 
+from Sending Servers without httpsig as it can't identify where the
 notification is coming from.
 
 ### Receiving Party Notification
@@ -1076,7 +1076,7 @@ Date: Wed, 05 Nov 2025 14:00:00 GMT
 Content-Type: application/x-www-form-urlencoded
 Digest: SHA-256=ok6mQ3WZzKc8nb7s/Jt2yY1uK7d2n8Zq7dhl3Q0s1xk=
 Content-Length: 101
-Signature-Input: 
+Signature-Input:
     sig1=("@method" "@target-uri" "content-digest" "date"); \
     created=1730815200; keyid="receiver.example.org#2025"; \
     alg="rsa-sha256"
@@ -1207,7 +1207,7 @@ Implementers SHOULD NOT use it and prefer short-lived tokens instead.
 ##  Code Flow
 
 All `{tokenEndPoint}` requests MUST be transmitted over HTTPS and
-signed using HTTP Signatures.  Bearer tokens MUST be treated as 
+signed using HTTP Signatures.  Bearer tokens MUST be treated as
 confidential and never logged, persisted beyond their lifetime, or
 transmitted over unsecured channels.
 
@@ -1231,14 +1231,14 @@ Key Words](https://datatracker.ietf.org/html/rfc8174)", May 2017.
 [RFC9421] Backman, A., Richer, J. and Sporny, M. "[HTTP Message
 Signatures](https://tools.ietf.org/html/rfc9421)", February 2024.
 
-[RFC3986] Berners-Lee, T., Fielding, R. and Masinter, L. 
+[RFC3986] Berners-Lee, T., Fielding, R. and Masinter, L.
 "[Uniform Resource Identifier (URI): Generic Syntax
 ](https://datatracker.ietf.org/doc/html/rfc3986)", January 2005
 
 [RFC6749] Hardt, D. (ed), "[The OAuth 2.0 Authorization Framework](
 https://datatracker.ietf.org/html/rfc6749)", October 2012.
 
-[RFC8615] Nottingham, M. "[Well-Known Uniform Resource Identifiers 
+[RFC8615] Nottingham, M. "[Well-Known Uniform Resource Identifiers
 (URIs)](https://datatracker.ietf.org/doc/html/rfc8615)", May 2019
 
 
@@ -1444,7 +1444,7 @@ format:
 
 An implementor of OCM MAY choose any internal object model to represent
 an _Address Book_, a _Contact_, an _Invite_, a _Provider_, a _Share_,
-and  a _User_.  However, the following diagrams are provided to clarify
+and a _User_.  The following diagrams are provided to clarify
 the concepts and their relationships, as a guide for implementors.
 
 ## Address Book
@@ -1456,12 +1456,12 @@ the Sending Server's database from the selection of the _Receiving
 Party_ in preparation for Share Creation.
 
 The Address Book entity maintains a collection of contacts for a user
-within the OCM provider. It serves as the primary mechanism for managing
-federated relationships between users across different OCM Servers.
-_Contacts_ may be added to the Address Book through the Invite flow or
-direct entry. It provides a convenient way for users to organize and
-access their federated contacts, and MAY allow users to generate
-_Invites_.
+within the OCM provider.  It serves as the primary mechanism for
+managing federated relationships between users across different OCM
+Servers. _Contacts_ may be added to the Address Book through the Invite
+flow or direct entry.  It provides a convenient way for users to
+organize and access their federated contacts, and MAY allow users to
+generate _Invites_.
 
 ```
 +-----------------+
@@ -1491,8 +1491,8 @@ _Invites_.
 
 ## Contact
 A Contact represents a federated user relationship established through
-the OCM protocol. Contacts are stored in _Address Books_ and may be
-created through the Invite process or via direct entry. A Contact MAY
+the OCM protocol.  Contacts are stored in _Address Books_ and may be
+created through the Invite process or via direct entry.  A Contact MAY
 of course contain much more detailed information about the referenced
 user such as if it was added via _Invites_ or direct entry.
 
@@ -1528,7 +1528,7 @@ user such as if it was added via _Invites_ or direct entry.
 ## Invite
 
 The Invite entity represents the bidirectional trust establishment
-mechanism in OCM. It facilitates secure contact exchange between users
+mechanism in OCM.  It facilitates secure contact exchange between users
 on different OCM Servers.
 
 ```
@@ -1564,7 +1564,7 @@ on different OCM Servers.
 ## Provider
 
 The Provider entity represents an OCM Server's capabilities and
-configuration as discovered through the OCM API Discovery process. It
+configuration as discovered through the OCM API Discovery process.  It
 represents both the Sending Server and Receiving Server roles, and an
 implementor might find it useful to have a Provider object model to
 store the discovered information about federation peers or other remote
@@ -1588,19 +1588,19 @@ OCM Providers.
                    |
          +---------+---------+----------------------+
          |                   |                      |
-         v                   v                      v                   
-+------------------+  +------------------+   +------------------+       
-| ResourceTypes[]  |  | Capabilities[]   |   |    Criteria[]    |       
+         v                   v                      v
++------------------+  +------------------+   +------------------+
+| ResourceTypes[]  |  | Capabilities[]   |   |    Criteria[]    |
 +------------------+  +------------------+   +------------------+
 | - name           |  | - enforce-mfa    |   | - allowlist      |
 | - shareTypes[]   |  | - exchange-token |   | - denylist       |
 | - protocols{}    |  | - invite-wayf    |   | - http-signatures|
 +------------------+  | - invites        |   | - invite         |
        |              | - webdav-uri     |   | - token-exchange |
        |              +------------------+   +------------------+
-       | supports                            
-       v                                     
-+------------------+                         
+       | supports
+       v
++------------------+
 |   Protocols      |
 +------------------+
 | - datatx         |
@@ -1634,10 +1634,10 @@ from a Sending Party to a Receiving Party.
        |                                        |
        | creates                                | accesses
        v                                        v
-+------------------+     notification    +------------------+ 
++------------------+     notification    +------------------+
 |     Share        |-------------------->| Receiving Server |
 +------------------+                     +------------------+
-| - expiration     |                            | 
+| - expiration     |                            |
 | - name           |                            | mediates access to
 | - owner          |                            v
 | - protocol       |                     +------------------+
@@ -1736,8 +1736,8 @@ Shares and Invites and manage Contacts, and interact with Resources.
 ## Resource
 
 The Resource entity represents the data or service being shared between
-OCM Providers. It is the target of Shares and is accessed by the
-Receiving Party through the Sending Server's API. In general a Resource
+OCM Providers.  It is the target of Shares and is accessed by the
+Receiving Party through the Sending Server's API.  In general a Resource
 is a much more complex entity, but for the purpose of OCM we only need
 to model a few key properties.