Clarify how access happens for shares without absolute URIs

[glpatcern]

As we are implementing OCM 1.2 in Reva, we realized that full URIs in new share payloads are:

1. Not less trustworthy than any other metadata a receiver can use to establish the sender's address.
2. Actually required if we want to support deployments that make use of reverse proxies (such as CERNBox), where the receiver has no other way than contacting the sender at their advertised URI (typically different from the sender's address). Edit: if the owner's OCM address is provided, then full URIs are not required.

See cs3org/reva#5076 (comment) for more details.

With this PR, we are "un-deprecating" the full URI concept in new share payloads we make the OCM address' FQDN mandatory.

Additionally, some fixes and a re-harmonization of the IETF text have been included, most notably:

• The webdav.uri property is REQUIRED, not OPTIONAL
• Use of the /.well-known/ocm discovery endpoint
• No secret hashes in URIs
• uriTemplate was renamed to uri

[mickenordin]

I think I am missing something. Why is it not possible to use the endpoint designated in the discovery endpoint when using a reverse proxy?

Is it not the job of the reverse proxy to proxy the request to the correct backend server? It is not intended that the communication bypass the reverse proxy and go directly to the backend, right?

[michielbdejong]

I don't think I understand what the problem is. The way I understand the flow is:

• [email protected] shares "files/bla.txt" with [email protected]
• server1.com does a lookup of server2.com/.well-known/ocm
• the Share Creation Notification is POSTed. This may go through proxies, doesn't matter. The important part here is part after the @ symbol in the sender field, so in our API docs example that would be apiwise.nl instead of server1.com.
• server2.com retrieves server1.com/.well-known/ocm
• checks whether it thinks this spam or not. It can do so for instance by checking the request headers against the pubkey announced there, or by checking whether the share is actually accessible at the announced WebDAV API of server1 (see next step).
• it uses the base path from resourceTypes[0].protocols.webdav to find the webdav base URL, in our API docs example that would be /remote/dav/ocm/ but this can also be an absolute URL at https://storage.server1.com or https://proxy.sever1.com or similar.
• It adds the relative path of the share to the WebDAV base URL to get (in this example) https://apiwise.nl/remote/dav/ocm/files/bla.txt as the WebDAV URL.

Which part of this is made impossible by the use of (reverse) proxies?

[glpatcern]

OK, now I understand what you (both) meant: the key is all in The important part here is part after the @ symbol in the sender field. So effectively the spec says to use an information that is part of the payload, not in the request header / remote address (which cannot be trusted, that was the whole point).

I must say that I have missed that, I'll try and spell it out explicitly in the discovery section even if it's explained in the Invite flow section.

At this point, no need to "un-deprecate" the full URL in the payload, on the basis that the payload MUST contain the server in the owner field. I will amend this PR to just leave the other corrections.

[glpatcern]

Reviewing myself, I believe this is the only significant change, all the rest being a matter of better phrasing and realigning of the IETF text to the spec.

I believe we have to force a MUST here, otherwise my argument of un-deprecating full URIs in share payloads remains valid. Otherwise, if a share payload does not contain a usable owner, and the URI is relative, how can a receiver contact the sender, assuming that its remote address may not be valid?

[michielbdejong]

I think this "doesn't have to be" phrase refers to the fact we are allowing the OCM API (i.e. where POST ./shares and other endpoints live) as advertised in /.well-known/ocm to be on a different server than /.well-known/ocm itself, right?

[glpatcern]

Ah, my interpretation was that the /.well-known/ocm must be on the same server as the owner's (or recipient's) OCM address that is sent by a POST ./shares