Feat: add support for ssh

IETF-RFC.md

@@ -74,7 +74,7 @@ thing.  This is achieved by providing a protocol that abstracts away
 security and authentication details from the users to the servers acting
 on behalf of the users.  Another important point of the protocol is the
 invitation mechanism that lets users connect over established human
-relationships and uses those connections to establish contact between
+relationships and use those connections to establish contact between
 their respective OCM servers.
 
 # Terms
@@ -607,22 +607,23 @@ contain the following information about its OCM API:
     support at least `webdav`,
     any other combination of Resources and protocols is
     optional.  Example:
-    `json
+    ```json
             {
               "webdav": "/remote/dav/ocm/",
               "webapp": "/app/ocm/",
               "talk": "/apps/spreed/api/"
             }
-            `
+    ```
     Fields:
     - webdav (string) - The top-level WebDAV [RFC4918] path at this
       endpoint.  In order to access a Remote Resource, implementations
-      MAY use this path as a prefix, or as the full path (see sharing
-      examples).
+      SHOULD use this path as a prefix (see sharing examples).
     - webapp (string) - The top-level path for web apps at this
-      endpoint.  This value is provided for documentation
-      purposes, and it SHOULD NOT be intended as a prefix
-      for share requests.
+      endpoint.  In order to access a remote web app, implementations
+      SHOULD use this path as a prefix (see sharing examples).
+    - 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.
     - 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.
@@ -770,7 +771,8 @@ To create a Share, the Sending Server SHOULD make a HTTP POST request
 * REQUIRED protocol (object)
   JSON object with specific options for each protocol.
   The supported protocols are: - `webdav`, to access the data -
-  `webapp`, to access remote web applications.
+  `webapp`, to access remote web applications - `ssh`, to access
+  the data via a public/private key pair.
   Other custom protocols might be added in the future.
   In case a single protocol is offered, there are three ways to
   specify this object:
@@ -854,6 +856,46 @@ To create a Share, the Sending Server SHOULD make a HTTP POST request
   - OPTIONAL sharedSecret (string)
     An optional secret to be used to access the remote
     web app, for example in the form of a bearer token.
+* Protocol details for `ssh` MAY contain:
+  - OPTIONAL accessType (array of strings) - The type of access
+    being granted to the remote resource.  If omitted, it defaults to
+    `['remote']`.  A subset of: - `remote` signals the recipient that
+    the resource is available for remote access, e.g. via sshfs.
+    - `datatx` signals the recipient to transfer the resource
+    from the given URI via scp.  The recipient MAY delegate a
+    third-party service to execute the data transfer on their behalf.
+  - REQUIRED uri (string)
+    The full address to be used for ssh or scp access, in the form
+    `[email protected]:port/resource/path`, where the `username` is
+    chosen by the Sending Server and does not necessarily need to match
+    the recipient's OCM Address.  Authentication is expected to take
+    place via public/private key: the Receiving Server MUST reply to
+    such a Share Creation Notification by sending back their public
+    key, for the Sender Server to authorize access to the Resource.
+
+## Response
+
+The Share Creation Notification Response SHOULD be a HTTP response:
+
+* in response to the Share Creation Notification Request
+* using `application/json` as the `Content-Type` HTTP response header
+
+A 201 response status means the Share Creation Notification Request was
+successful.  In this case, the response body MUST contain a JSON
+document representing an object with the following string fields:
+  - REQUIRED: `recipientDisplayName` - the Recipient's display name.
+  - OPTIONAL: `recipientPublicKey` - the Recipient's public key.
+    This property MUST be returned when the protocol of the incoming
+    share was `ssh`.
+A 400 response status means some parameters were invalid or missing.
+A 401 response status means the Sender cannot be authenticated as
+a trusted service.
+A 403 response status means the Sender is not authorized to create
+shares.
+A 501 response status means either the Receiver does not support
+incoming external shares, or the share type or the resource type
+are not supported.
+A 503 response status means that the Receiver is temporary unavailable.
 
 ## Decision to Discard
 
@@ -880,7 +922,7 @@ following hold true:
 * an initial check shows that the Resource cannot successfully be
   accessed through (any of) the protocol(s) listed
 
-# Receiving Party Notification
+## Receiving Party Notification
 
 If the Share Creation Notification is not discarded by the Receiving
 Server, they MAY notify the Receiving Party passively by adding the
@@ -891,6 +933,7 @@ They could give the Receiving Party the option to accept or reject the
 share, or add the share automatically and only send an informational
 notification that this happened.
 
+
 # Share Acceptance Notification
 
 In response to a Share Creation Notification, the Receiving Server MAY
@@ -937,17 +980,6 @@ of the notification.  Receiving Servers SHOULD decline notifications
 from Sending Servers without httpsig as it can't identify where the 
 notification is coming from.
 
-### Receiving Party Notification
-
-If the Share Creation Notification is not discarded by the Receiving
-Server, they MAY notify the Receiving Party passively by adding the
-Share to some inbox list, and MAY also notify them actively through for
-instance a push notification or an email message.
-
-They could give the Receiving Party the option to accept or reject the
-Share, or add the Share automatically and only send an informational
-notification that this happened.
-
 # Resource Access
 
 To access the Resource, the Receiving Server MAY use multiple ways,

spec.yaml

@@ -72,8 +72,14 @@ paths:
                 properties:
                   recipientDisplayName:
                     type: string
-                    description: display name of the recipient
+                    description: >
+                      Display name of the recipient
                     example: John Doe
+                  recipientPublicKey:
+                    type: string
+                    description: >
+                      The public key of the recipient. This value MUST be provided
+                      in case the Share Creation Notification includes the `ssh` protocol.
         "400":
           description: >
             Bad request due to invalid parameters, e.g. when `shareWith` is not
@@ -83,26 +89,26 @@ paths:
               schema:
                 $ref: "#/components/schemas/400"
         "401":
-          description: Client cannot be authenticated as a trusted service.
+          description: Sender cannot be authenticated as a trusted service.
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
         "403":
-          description: Trusted service is not authorized to create shares.
+          description: Sender is not authorized to create shares.
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
         "501":
-          description: The consumer doesn't support incoming external shares, the share
+          description: The Receiver doesn't support incoming external shares, the share
             type or the resource type is not supported.
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
         "503":
-          description: The consumer is temporary unavailable (e.g. due to planned
+          description: The Receiver is temporary unavailable (e.g. due to planned
             maintenance).
           headers:
             Retry-After:
@@ -388,6 +394,12 @@ components:
                       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).
+                  ssh:
+                    type: string
+                    description: >
+                      The top-level address in the form `host:port` of an endpoint
+                      that supports ssh and scp with a public/private key based
+                      authentication.
                 additionalProperties:
                     type: string
                     description: >
@@ -688,7 +700,30 @@ components:
                     in any URI.  In a multi-protocol share scenario with WebDAV, the
                     access requirements provided in the `webdav` part MUST apply for
                     `webapp` accesses as well.
-
+            ssh:
+              type: object
+              properties:
+                accessType:
+                  type: array
+                  description: >
+                    The type of access being granted to the remote resource.
+                    If omitted, it defaults to `['remote']`.
+                    - `remote` signals the recipient that the resource is available
+                      for remote access, e.g. via sshfs.
+                    - `datatx` signals the recipient to transfer the resource from
+                      the given URI via scp. The recipient MAY delegate a third-party
+                      service to execute the data transfer on their behalf.
+                  items:
+                    type: string
+                    enum:
+                      - remote
+                      - datatx
+                uri:
+                  type: string
+                  description: >
+                    The full address to be used for ssh or scp access, in the form
+                    `[email protected]:port/resource/path`, where authentication is
+                    expected to take place via public/private key.
           additionalProperties:
             type: object
             description: >
@@ -724,6 +759,9 @@ components:
                 uri: 7c084226-d9a1-11e6-bf26-cec0c932ce01
                 sharedSecret: hfiuhworzwnur98d3wjiwhr
                 viewMode: read
+              ssh:
+                accessType: ['datatx']
+                uri: [email protected]:/7c084226-d9a1-11e6-bf26-cec0c932ce01
     NewNotification:
       type: object
       required: