Add MFA capability and permission (#79)

* V1.2.0 proposal, Add MFA capability and permission

This PR is a proposal to add a capability `/mfa-enforcing` as well as
a permission `mfa-enforced` to the specification. The version of the
specification is bumped to 1.2.0.

If an OCM provider has the capability `/mfa-enforcing` it will respond
with a boolean on the endpoint /mfa-enforcing to indicate whether or
not it will try to comply with a MFA requirement set as a permission
on a share. If the sharer OCM provider trusts the sharee OCM provider
the sharer MAY set the permission `mfa-enforced` on a share.

A complient OCM provider that signals mfa-enforcing `true` MUST not
allow access to a resource to a user that has not provided a second
factor to establish the identity of the user with greater confidence.

Since there is no way to guarantee that the sharee OCM provider will
actually enforce the MFA requirement, it is up to the sharer OCM
provider to establish a trust with the OCM sharee provider such that
it is reasonable to assume that the sharee OCM provider will honor the
MFA requirement. This establishment of trust will inevitably be
implementation dependent, and can be done for example using a pre
approved allow list of trusted OCM providers. The procedure of
establishing trust is out of scope for this specification.

* MFA: Address review feedback

This patch adds information about MFA to the readme-file and renames
`mfa-enforcing` to `mfa-capable`. The respons is simplified from a
boolean response on the endpoint to an empty HTTP 200 OK response.

Version is reset to 1.1.0

* MFA: reworked role of the /mfa-enabled endpoint

* Partially reverted previous changes, expanded descriptions for more clarity

* Update spec.yaml

Co-authored-by: Giuseppe Lo Presti <giuseppe.lopresti@cern.ch>

* Update spec.yaml

Co-authored-by: Giuseppe Lo Presti <giuseppe.lopresti@cern.ch>

---------

Co-authored-by: Giuseppe Lo Presti <giuseppe.lopresti@cern.ch>

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "githubPullRequests.ignoredPullRequestBranches": [
+        "develop"
+    ]
+}

README.md

@@ -50,6 +50,8 @@ To access a share, the receiving server MAY use multiple ways, depending on the
 
 In both cases, when the share is a folder and the receiver accesses a resource within the share, it SHOULD append its relative path to that URL.
 
+Additionally, if `protocol.<protocolname>.permissions` include `mfa-enforced`, the receiving host MUST ensure that the user accessing the resource has been authenticated with MFA.
+
 ### Share Deletion
 A `"SHARE_ACCEPTED"` notification followed by a `"SHARE_UNSHARED"` notification is
 equivalent to a `"SHARE_DECLINED"` notification.
@@ -74,6 +76,11 @@ Following this step, both services at `sender.com` and `receiver.com` MAY displa
 
 For further details on this concept, see also [#54](https://github.com/cs3org/OCM-API/pull/54) and related issues. For a discussion about trust policies, see [sciencemesh#196](https://github.com/sciencemesh/sciencemesh/issues/196).
 
+### Multi Factor Authentication
+If an OCM provider exposes the capability `/mfa-capable`, it indicates that it will try and comply with a MFA requirement set as a permission on a share. If the sharer OCM provider trusts the receiver OCM provider, the sharer MAY set the permission `mfa-enforced` on a share, which SHOULD be honored. A compliant OCM provider that signals that it is MFA-capable MUST not allow access to a resource protected with the `mfa-enforced` permission, if the consumer has not provided a second factor to establish their identity with greater confidence.
+
+Since there is no way to guarantee that the sharee OCM provider will actually enforce the MFA requirement, it is up to the sharer OCM provider to establish a trust with the OCM sharee provider such that it is reasonable to assume that the sharee OCM provider will honor the MFA requirement. This establishment of trust will inevitably be implementation dependent, and can be done for example using a pre approved allow list of trusted OCM providers. The procedure of establishing trust is out of scope for this specification: a mechanism similar to the [ScienceMesh](https://sciencemesh.io) integration for the [Invite](#invite) capability may be envisaged.
+
 
 ## Changelog
 

spec.yaml

@@ -108,6 +108,26 @@ paths:
               type: string
           schema:
             $ref: "#/definitions/Error"
+  /mfa-capable:
+    get:
+      summary: Inform the sender that the provider will enforce MFA requirements.
+      description: >
+        Signal that this OCM provider has the capability to enforce MFA when accessing
+        remote shares.
+        A sender MAY set the permission `mfa-enforced` on a share to this provider:
+        when a consumer attempts to access such a share, the consumer server SHOULD
+        enforce, prior to access, that a session exists for the consumer and that
+        it has been authenticated with MFA, or prompt the consumer in order to
+        elevate their session to MFA if that is applicable.
+        Note: there is no guarantee that the consumer service actually enforces any MFA
+        requirements, so a trust must be established before relying on this capability.
+      responses:
+        "200":
+          description: |
+            The provider claims that it is capable of enforcing MFA requirements.
+        "404":
+          description: |
+            The provider does not have the capability to enforce MFA requirements.
   /notifications:
     post:
       summary: Send a notification to a remote party about a previously known entity
@@ -325,7 +345,7 @@ definitions:
           it is not necessary to expose it as a capability.
         items:
           type: string
-          enum: ["/notifications", "/invite-accepted"]
+          enum: ["/notifications", "/invite-accepted", "/mfa-capable"]
         example:
           ["/invite-accepted"]
   NewShare:
@@ -456,7 +476,10 @@ definitions:
                       - `read` allows read-only access including download of a copy.
                       - `write` allows create, update, and delete rights on the resource.
                       - `share` allows re-share rights on the resource.
-                    enum: ["read", "write", "share"]
+                      - `mfa-enforced` requires the user accessing the resource to be
+                        MFA-authenticated. This permission MAY be used if the
+                        provider exposes the `mfa-capable` capability.
+                    enum: ["read", "write", "share", "mfa-enforced"]
                 uri:
                   type: string
                   description: |
@@ -483,7 +506,10 @@ definitions:
                     - `view` allows access to the web app in view-only mode.
                     - `read` allows read and download access via the web app.
                     - `write` allows full editing rights via the web app.
-                  enum: ["view", "read", "write"]
+                    - `mfa-enforced` requires the user accessing the resource to be
+                      MFA-authenticated. This permission MAY be used if the
+                      provider exposes the `mfa-capable` capability.
+                  enum: ["view", "read", "write", "mfa-enforced"]
                 sharedSecret:
                   type: string
                   description: |
@@ -518,13 +544,13 @@ definitions:
               sharedSecret: "hfiuhworzwnur98d3wjiwhr"
             webdav:
               sharedSecret: "hfiuhworzwnur98d3wjiwhr"
-              permissions: ["read"]
+              permissions: ["read", "write"]
               uri: "https://open-cloud-mesh.org/remote/dav/ocm/hfiuhworzwnur98d3wjiwhr/path/to/resource.txt"
           multipleProtocols:
             name: "multi"
             options:
             webdav:
-              permissions: ["read"]
+              permissions: ["read", "mfa-enforced"]
               uri: "https://open-cloud-mesh.org/remote/dav/ocm/hfiuhworzwnur98d3wjiwhr/path/to/resource.txt"
             webapp:
               uriTemplate: "https://open-cloud-mesh.org/app/ocm/hfiuhworzwnur98d3wjiwhr/{relative-path-to-shared-resource}"