Revamped and enhanced webapp protocol in I-D and spec.yaml

IETF-RFC.md

@@ -692,31 +692,57 @@ contain the following information about its OCM API:
     ~~~
             {
               "webdav": "/remote/dav/ocm/",
-              "webapp": "/app/ocm/",
+              "webdav-receive": { "uri": "absolute" },
+              "webapp": {},
+              "webapp-receive": { "targets": ["blank", "iframe"] },
               "talk": "/apps/spreed/api/"
             }
     ~~~
     {: type="json"}
 
+    The `protocols` object distinguishes a server's role for each
+    protocol: a property named after the protocol (e.g. `webdav`,
+    `webapp`, `ssh`) advertises support for acting as a Sending
+    Server, while a property suffixed with `-receive` (e.g.
+    `webdav-receive`, `webapp-receive`, `ssh-receive`) advertises
+    support for acting as a Receiving Server.
+
     Fields:
     - webdav (string) - The top-level WebDAV [RFC4918] path at this
       endpoint.  In order to access a Remote Resource, implementations
       SHOULD use this path as a prefix (see sharing examples).
-    - webapp (string) - The top-level path for web apps at this
-      endpoint.  In order to access a remote web app, implementations
-      SHOULD use this path as a prefix (see sharing examples).
+    - webdav-receive (object) - Advertised by implementations that
+      support receiving WebDAV shares.  It contains a `uri` property
+      whose value MUST be either `"absolute"` or `"relative"`,
+      signalling the URI format this endpoint accepts.  Note that
+      older implementations MAY not support this property.
+    - webapp (object) - Advertised, as an empty object, by
+      implementations that support sending WebApp shares.
+    - webapp-receive (object) - Advertised by implementations that
+      support receiving WebApp shares.  It contains a `targets`
+      array listing the ways this endpoint is able to present a
+      WebApp share to the user.  A subset of:
+      - `blank` - the endpoint can open the URI in a new window or
+        tab, or do a full page redirect.
+      - `iframe` - the endpoint can embed the URI in an iframe
+        within its own UI, when the Sending Server allows framing
+        by this receiver.
     - ssh (string) - The top-level address in the form `host:port`
       of an endpoint that supports ssh and scp with a public/private
       key based authentication.
+    - ssh-receive (object) - Advertised, as an empty object, by
+      implementations that support receiving SSH shares.
     - Any additional protocol supported for this Resource type MAY be
       advertised here, where the value MAY correspond to
-      a top-level URI to be used for that protocol.
+      a top-level URI to be used for that protocol.  Similarly,
+      additional receiving capabilities for custom protocols SHOULD
+      be advertised using a `-receive` suffixed property.
 * OPTIONAL: capabilities (array of string) - The optional capabilities
   supported by this OCM Server.
   As implementations MUST accept Share Creation Notifications
   to be compliant, it is not necessary to expose that as a
   capability.
-  Example: `["exchange-token", "webdav-uri"]`.  The array MAY
+  Example: `["exchange-token", "protocol-object"]`.  The array MAY
   include one or more of the following items:
   - `"enforce-mfa"` - to indicate that this OCM Server can apply a
   Sending Server's MFA requirements for a Share on their behalf.
@@ -737,9 +763,6 @@ contain the following information about its OCM API:
   notifications to exchange updates on shares and invites.
   - `"invite-wayf"` - to indicate that this OCM Server exposes a WAYF
   Page to facilitate the Invite flow.
-  - `"webdav-uri"` - to indicate that this OCM Server can append a
-  relative URI to the path listed for WebDAV [RFC4918] in the
-  appropriate `resourceTypes` entry
   - `"protocol-object"` - to indicate that this OCM Server can
   receive a Share Creation Notification whose `protocol` object
   contains one property per supported protocol instead of containing
@@ -916,10 +939,13 @@ voluntarily.
     cache operations on the Sending Server.  The recipient MAY delegate
     a third-party service to execute the data transfer on their behalf.
   - REQUIRED uri (string)
-    A 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.
+    A URI to access the Remote Resource.  The URI MAY be relative,
+    such as a key or a UUID, in which case the prefix exposed by the
+    `/.well-known/ocm` endpoint MUST be used to access the Resource,
+    or it MAY be absolute, including a hostname.  In all cases, for a
+    `folder` Resource, the composed URI acts as the root path, such
+    that other files located within it MUST be accessible by
+    appending their relative path to that URI.
   - REQUIRED sharedSecret (string)
     A secret to be used to access the Resource, such as
     a bearer token.  To prevent leaking it in logs it
@@ -947,20 +973,62 @@ voluntarily.
     especially in case of `datatx` access type.
 * Protocol details for `webapp` MAY contain:
   - REQUIRED uri (string)
-    A 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)
-    The permissions granted to the sharee.  A subset of:
+    A URI to a client-browsable view of the Shared Resource, such
+    that users MAY use a web application available at the Sending
+    Server.  The URI MUST be absolute, including a hostname.  In
+    case the underlying Resource is a folder, the URI MUST act as a
+    root path, such that files located within the folder are made
+    accessible in the web app by appending their relative path to
+    the URI.
+  - REQUIRED targets (array of strings) - How the recipient SHOULD
+    present the URI to the user.  The `targets` array MUST NOT be
+    empty.  A subset of:
+    - `blank` signals the recipient to open the URI in a new window
+      or tab.
+    - `iframe` signals the recipient to embed the URI in an iframe
+      within its own UI, when the Sending Server allows framing by
+      this receiver.
+    A Sending Server MUST NOT offer a target that the recipient did
+    not advertise in its `webapp-receive` discovery property.
+  - REQUIRED permissions (array of strings) -
+    The permissions granted to the sharee.  MUST NOT be empty.
+    A subset of:
     - `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.
-  - OPTIONAL sharedSecret (string)
-    An optional secret to be used to access the remote
-    web app, for example in the form of a bearer token.
+    - `share` allows re-share rights on the Resource.  This only
+      applies to web apps that provide a mechanism for re-sharing.
+  - REQUIRED requirements (array of strings) -
+    The requirements that the sharee MUST fulfill to
+    access the Resource.  The requirements MUST at least include
+    `must-exchange-token`.  If multiple protocols are present in the
+    share payload, the requirements for the different protocols MUST
+    agree.  For example, if a webapp share is sent in the same payload
+    as a webdav share, both protocols MUST carry the same
+    requirements, and both requirement arrays MUST include
+    `must-exchange-token`.
+  - REQUIRED sharedSecret (string)
+    A secret for accessing the remote web app.  To give access to the
+    remote app, the receiver MUST first exchange this value at the
+    Sending Server's {tokenEndPoint} using the Code Flow, then perform
+    an HTTP POST request to the given `uri` with the resulting bearer
+    token in a form field named `access_token` (see
+    [Resource Access](#resource-access)).  The shared secret MUST NOT
+    be exposed to the browser and MUST NOT appear in any URI.  In a
+    multi-protocol Share that also offers WebDAV, the access
+    requirements provided in the `webdav` part (such as
+    `must-exchange-token`) MUST apply to `webapp` accesses as well.
+  - OPTIONAL appName (string)
+    A human-friendly name of the web application, to be used in user
+    interfaces when referring to this Share.
+  - OPTIONAL appIconHint (string)
+    A string in the form of a media type (MIME type) that describes the
+    share as a whole, primarily intended as a way for the receiving
+    server to select an appropriate icon for the share. [RFC6838]
+  - OPTIONAL mediaTypes (array of strings)
+    An array of media types (MIME types) the webapp server can handle.
+    This can be any media type entries from the IANA Media Type
+    registry. [RFC6838]
 * Protocol details for `ssh` MAY contain:
   - OPTIONAL accessTypes (array of strings) - The type of access
     being granted to the remote resource.  If omitted, it defaults to
@@ -1163,6 +1231,25 @@ protocol required for access.  The procedure is as follows:
    removed in a future release of the Protocol.  If a secret cannot be
    identified (e.g. because `protocol.options` is undefined), then
    the receiver SHOULD discard the share as invalid.
+6. For the specific case where `protocol.webapp` is available and the
+   receiver wants to use it, the receiver MUST present the web app to
+   the user by opening `protocol.webapp.uri` using a target selected
+   from the intersection of `protocol.webapp.targets` and the targets
+   advertised in the receiver's `webapp-receive` discovery property.
+   If this intersection is empty, the receiver MUST treat the `webapp`
+   option as unusable for this Share.  The receiver MUST NOT place the
+   `protocol.webapp.sharedSecret` in the URI and MUST NOT expose it to
+   the browser.  Instead,
+   the receiver MUST first exchange it at the Sending Server's
+   {tokenEndPoint} using the Code Flow, then deliver the resulting
+   bearer token to the web app via an HTTP POST to
+   `protocol.webapp.uri` with the token carried in a form field named
+   `access_token` along with another form field named
+   `expired_session_redirect_uri` that represents the location where
+   the receiving server can handle refresh of tokens.  This is typically
+   achieved with an auto-submitting HTML form whose `target` attribute
+   selects the chosen presentation (e.g. an iframe name, `_blank`, or
+   `_top`).
 
 In all cases, in case the Shared Resource is a folder and the Receiving
 Server accesses a Resource within that shared folder, it SHOULD append
@@ -1485,6 +1572,10 @@ June 2007.
 [RFC6749] Hardt, D. (ed), "[The OAuth 2.0 Authorization Framework](
 https://datatracker.ietf.org/html/rfc6749)", October 2012.
 
+[RFC6838] Freed, N., Klensin, J., Hansen, T. "[Media Type
+Specifications and Registration Procedures
+](https://datatracker.ietf.org/html/rfc6838)", January 2013.
+
 [RFC7515] Jones, M., Bradley, J., Sakimura, N., "[JSON Web Signature
 (JWS)](https://datatracker.ietf.org/doc/html/rfc7515)", May 2015.
 
@@ -1904,7 +1995,6 @@ that section.
 | - ...            |  | - invites        |          |
 +------------------+  | - notifications  |          |
        |              | - protocol-object|          |
-       |              | - webdav-uri     |          |
        |              | - ...            |          |
        |              +------------------+          |
        |                                            |
@@ -1928,8 +2018,11 @@ that section.
 |   Protocols      |
 +------------------+
 | - ssh            |
+| - ssh-receive    |
 | - webapp         |
+| - webapp-receive |
 | - webdav         |
+| - webdav-receive |
 | - ...            |
 +------------------+
 ~~~

schemas/ocm-discovery.json

@@ -22,7 +22,7 @@
     },
     "capabilities": {
       "type": "array",
-      "description": "Capability values of 'enforce-mfa', 'exchange-token', 'http-sig', 'invites', 'invite-wayf', 'notifications', 'protocol-object', and 'webdav-uri' are defined in the draft",
+      "description": "Capability values of 'enforce-mfa', 'exchange-token', 'http-sig', 'invites', 'invite-wayf', 'notifications', and 'protocol-object' are defined in the draft",
       "items": {
         "type": "string"
       }
@@ -55,6 +55,7 @@
   ],
   "$defs": {
     "resourceType": {
+      "type": "object",
       "properties": {
         "name": {
           "type": "string"
@@ -69,20 +70,53 @@
     "protocols": {
       "type": "object",
       "minProperties": 1,
-      "description": "Additional protocols besides 'webdav', 'webapp' and 'datatx' may be defined.",
+      "description": "Additional protocols besides 'webdav', 'webapp', and 'ssh' may be defined. A property named after the protocol advertises sending support; a property suffixed with '-receive' advertises receiving support.",
       "properties": {
         "webdav": {
           "type": "string",
           "pattern": "^/"
         },
+        "webdav-receive": {
+          "type": "object",
+          "required": ["uri"],
+          "properties": {
+            "uri": { "type": "string", "enum": ["absolute", "relative"] }
+          },
+          "additionalProperties": false
+        },
         "webapp": {
-          "type": "string",
-          "pattern": "^/"
+          "type": "object",
+          "additionalProperties": false
         },
-        "datatx": {
-          "type": "string",
-          "pattern": "^/"
+        "webapp-receive": {
+          "type": "object",
+          "required": ["targets"],
+          "properties": {
+            "targets": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "type": "string",
+                "enum": ["blank", "iframe"]
+              }
+            }
+          },
+          "additionalProperties": false
+        },
+        "ssh": {
+          "type": "string"
+        },
+        "ssh-receive": {
+          "type": "object",
+          "additionalProperties": false
         }
+      },
+      "additionalProperties": {
+        "oneOf": [
+          { "type": "string" },
+          { "type": "object" }
+        ]
       }
     },
     "publicKey": {