diff --git a/IETF-RFC.md b/IETF-RFC.md index 1c2896d..e3e1444 100644 --- a/IETF-RFC.md +++ b/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,59 @@ 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. + - 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 +1228,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 +1569,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 +1992,6 @@ that section. | - ... | | - invites | | +------------------+ | - notifications | | | | - protocol-object| | - | | - webdav-uri | | | | - ... | | | +------------------+ | | | @@ -1928,8 +2015,11 @@ that section. | Protocols | +------------------+ | - ssh | +| - ssh-receive | | - webapp | +| - webapp-receive | | - webdav | +| - webdav-receive | | - ... | +------------------+ ~~~ diff --git a/schemas/ocm-discovery.json b/schemas/ocm-discovery.json index ad0cfec..5662e2c 100644 --- a/schemas/ocm-discovery.json +++ b/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": { diff --git a/spec.yaml b/spec.yaml index 189d8e5..4caa07b 100644 --- a/spec.yaml +++ b/spec.yaml @@ -409,27 +409,85 @@ components: The top-level WebDAV path at this endpoint. In order to access a remote shared resource, implementations SHOULD use this path as a prefix (see sharing examples). + webdav-receive: + type: object + required: + - uri + description: > + Implementations that support receiving WebDAV shares SHOULD + advertise them here. Note though that older implementations MAY + not support this property. + properties: + uri: + type: string + description: > + This property signals that this endpoint is capable of + receiving `webdav` shares with the given URI format. + The value MUST be either `"absolute"` or `"relative"`. + enum: + - absolute + - relative webapp: - type: string + type: object description: > - 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). + Implementations that support sending WebApp shares MUST advertise + them here, with an empty object as value. + webapp-receive: + type: object + required: + - targets + description: > + Implementations that support receiving WebApp shares MUST + advertise them here. + properties: + targets: + type: array + minItems: 1 + description: > + The ways this endpoint is able to present a webapp + share to the user when acting as receiver. + - "blank" signals that this endpoint supports opening + the URI in a new window or tab, or doing a full page + redirect to the URI. + - "iframe" signals that this endpoint supports + embedding the URI in an iframe within its own UI, + when the Sending Server allows framing by this + receiver. + items: + type: string + enum: + - blank + - iframe 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. + ssh-receive: + type: object + description: > + Implementations that support receiving SSH shares MUST + advertise them here, with an empty object as value. additionalProperties: - type: string + oneOf: + - type: string + - type: object description: > - Any additional protocol supported for this resource type MAY + Any additional protocol supported for this resource type SHOULD be advertised here, where the value MAY correspond to a top-level - URI to be used for that protocol. + URI to be used for that protocol, or any other relevant + attribute required for that protocol. Similarly, additional + receiving capabilities for custom protocols SHOULD be advertised. example: webdav: /remote/dav/ocm/ - webapp: /apps/ocm/ + webdav-receive: { + "uri": "absolute" + } + webapp: {} + webapp-receive: { + "targets": ["blank", "iframe"] + } talk: /apps/spreed/api/ capabilities: type: array @@ -446,10 +504,9 @@ components: - invite-wayf - notifications - protocol-object - - webdav-uri example: - - webdav-uri - protocol-object + - invites - http-sig criteria: type: array @@ -645,6 +702,7 @@ components: type: object required: - uri + - sharedSecret - permissions properties: accessTypes: @@ -665,12 +723,12 @@ components: uri: type: string description: > - An URI to access the remote resource. The URI SHOULD be relative, + An 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. The latter is deprecated. + 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 SHOULD + as the root path, such that other files located within it MUST be accessible by appending their relative path to that URI. sharedSecret: type: string @@ -720,38 +778,108 @@ components: in case of `datatx` access type. webapp: type: object + required: + - uri + - sharedSecret + - targets + - permissions + - requirements properties: uri: type: string description: > An URI to a client-browsable view of the remote resource, such that users may use a web application available at the sender site. - The URI SHOULD 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. - Similar considerations as for the `webdav` case apply here. - In all cases, for a `folder` resource, the composed URI acts - as the root path, such that other files located within SHOULD - be accessible by appending their relative path to that URI. - viewMode: - type: string - description: | - The permissions granted to the sharee. + 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. + targets: + type: array + minItems: 1 + description: > + How the recipient should present the URI to the user. + This array is REQUIRED and MUST NOT be empty: a webapp + share without a target is invalid. + - "blank" signals the recipient to open the URI in a new window or + tab, or do a full page redirect. + - "iframe" signals the recipient to embed the URI in an iframe within + its own UI, when the Sending Server allows framing by the recipient. + items: + type: string + enum: + - blank + - iframe + permissions: + type: array + minItems: 1 + description: > + The permissions granted to the sharee. This array is + REQUIRED and MUST NOT be empty. - `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 + - `share` allows re-share rights on the resource. This only + applies to web apps that provide a mechanism for re-sharing. + items: + type: string + enum: + - view + - read + - write + - share + requirements: + type: array + minItems: 1 + description: > + The requirements that the sharee MUST fulfill to access the + resource. This array is REQUIRED and MUST at least include + `must-exchange-token`. If multiple protocols are present in + the share payload, the requirements for the different + protocols MUST agree. + - `must-use-mfa` requires the user accessing the resource to be + MFA-authenticated. This requirement MAY be used if the + recipient provider exposes the `enforce-mfa` capability. + - `must-exchange-token` requires the recipient to exchange the given + `sharedSecret` via a signed HTTPS request to tokenEndPoint at the + Sending Server, in order to get a short-lived token to be used + for subsequent access [RFC6749]. + items: + type: string + enum: + - must-use-mfa + - must-exchange-token sharedSecret: type: string description: > - An optional secret to be used to access the remote web app, such as - a bearer token. To prevent leaking it in logs it MUST NOT appear - 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. + 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`, along with another form + field named `expired_session_redirect_uri` that represents the + location where the receiving server can handle refresh of tokens. + The shared secret MUST + NOT be exposed to the browser and MUST NOT appear 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. + appIconHint: + type: string + description: > + An optional 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. + appName: + type: string + description: > + An optional human-friendly name of the web application to be used + in user interfaces when referring to this share. + mediaTypes: + type: array + description: > + An optional array that describes the media (MIME) types that the + webapp server can handle. ssh: type: object properties: @@ -801,16 +929,25 @@ components: name: multi webdav: accessTypes: ['remote', 'datatx'] - uri: 7c084226-d9a1-11e6-bf26-cec0c932ce01 + uri: https://cloud.example.org/remote/dav/ocm/7c084226-d9a1-11e6-bf26-cec0c932ce01 sharedSecret: hfiuhworzwnur98d3wjiwhr permissions: - read requirements: - must-use-mfa + - must-exchange-token webapp: - uri: 7c084226-d9a1-11e6-bf26-cec0c932ce01 + uri: https://apps.example.org/hedgedoc/7c084226-d9a1-11e6-bf26-cec0c932ce01 sharedSecret: hfiuhworzwnur98d3wjiwhr - viewMode: read + targets: + - blank + permissions: + - read + requirements: + - must-use-mfa + - must-exchange-token + appName: HedgeDoc + appIconHint: text/markdown ssh: accessTypes: ['datatx'] uri: extuser@cloud.example.org:/7c084226-d9a1-11e6-bf26-cec0c932ce01