Add MFA capability and permission

.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
@@ -321,7 +341,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:
@@ -452,7 +472,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: |
@@ -479,7 +502,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: |
@@ -514,14 +540,14 @@ definitions:
               sharedSecret: "hfiuhworzwnur98d3wjiwhr"
             webdav:
               sharedSecret: "hfiuhworzwnur98d3wjiwhr"
-              permissions: ["read"]
-              uri: "https://open-cloud-mesh.org/remote/dav/ocm/hfiuhworzwnur98d3wjiwhr/path/to/resource.txt"
+              permissions: ["read", "write"]
+              uri: "https://open-cloud-mesh.org/remote.php/webdav/share-secret/path/to/resource.txt"
           multipleProtocols:
             name: "multi"
             options:
             webdav:
-              permissions: ["read"]
-              uri: "https://open-cloud-mesh.org/remote/dav/ocm/hfiuhworzwnur98d3wjiwhr/path/to/resource.txt"
+              permissions: ["read", "mfa-enforced"]
+              uri: "https://open-cloud-mesh.org/remote.php/webdav/share-secret/path/to/resource.txt"
             webapp:
               uriTemplate: "https://open-cloud-mesh.org/app/ocm/hfiuhworzwnur98d3wjiwhr/{relative-path-to-shared-resource}"
               viewMode: "read"