Identify values which are an OCM Address

[KrausMatthias]

Clarify which values are OCM Addresses, so implementers know which can be used for discovery.

I've tried to guess all usages of OCM Addresses, maybe in some places the explicit mention might be skipped for readability.

[glpatcern]

I have some observations:

1. if we introduce and speak about OCM Addresses, we should define them first.
2. Where field was used, IMHO it is more appropriate than repeating OCM Address

Lastly, a "nitpick": it's should really be its everywhere.

The most important point clearly is 1), I can help if you prefer.

[mickenordin]

Great initiative! If you rebase on develop and fix the things raised by @glpatcern I think we can merge.

[KrausMatthias]

Regarding 2., maybe it would help to mention at least once that field is an OCM Address to make it clear why it has a "FQDN part" and why it may be used for discovery?

[KrausMatthias]

Regarding 1. I would first like to discuss where we want to go before I try to update the definition:

Currently the OCM Address is defined here: https://github.com/cs3org/OCM-API/blob/develop/IETF-RFC.md?plain=1#L103

• OCM Address - a string of the form
  <Receiving Party's identifier>@<fqdn> which can be used to uniquely
  identify a user or group "at" an OCM Server.
  <Receiving Party's identifier> is an opaque string, unique at the
  server. <fqdn> is the Fully Qualified Domain Name by which the server
  is identified. This MUST be the domain at which the /.well-known/ocm
  endpoint of that server is hosted.

• userinfo
  • <Receiving Party's identifier> is wrong as it can also be a Sending Party's identifier
  • mention that the opaque string is case-sensitive? So bob@example.org and BOB@example.org are not the same? This might be surprising to users and implementers as e.g. emails are case-insensitive
  • mention that userinfo may contain reserved characters (e.g. '@', ':'), so the OCM Address isn't a valid URI (https://www.rfc-editor.org/rfc/rfc3986#section-3.2.1) and therefore might fail to be parsed using URI tools from standard libraries
• server-part
  • In my understanding FQDN does exclude IP and Port (which might be helpful for testing), opposed to "host" as specified in https://www.rfc-editor.org/rfc/rfc3986#section-3.2.2
  • FQDN does exclude scheme as used by Nextcloud, their use would therefore be invalid according to the current spec
  • Potential foot-gun for implementations: FQDNs are case insensitive, so bob@example.org is the same as bob@EXAMPLE.org
  • It's hard to pin point an exact spec of "FQDN", best thing I found is https://www.rfc-editor.org/rfc/rfc1123#section-2 and https://datatracker.ietf.org/doc/html/rfc1034#section-3.5

Examples of invalid OCM Addresses as of the current spec as I understand it:

• user@https://example.org
• user@exampe.org:80
• user@127.0.0.1:443
• user@127.0.0.1

Examples of valid but misleading OCM Addresses:

• http://test@example.org -> http:// looks like a scheme that might be used to distinguish if discovery should be done via http or https, but is in fact only part of the "opaque string" (not saying Sending Servers or Sending Parties should be able to downgrade Discovery at the Receiving Server to http by default)
• user:pass@example.org -> the username is "user:pass" not "user". This might lead to issues with implementations using URI tools from standard libraries
• acct://asdf@example.org would actually also be a valid OCM Address according to the current spec

[MahdiBaghbani]

<Receiving Party's identifier> is wrong as it can also be a Sending Party's identifier

Yes, based on the context, it could be any of those.

FQDN does exclude scheme as used by Nextcloud, their use would therefore be invalid according to the current spec

Newer versions of Nextcloud (v29 and later) are using username@fqdn

Potential foot-gun for implementations: FQDNs are case insensitive, so bob@example.org is the same as bob@EXAMPLE.org

Why would this be an issue? the fqdn part is generally used to fetch the OCM discovery endpoint, they both would end up in the same place.

[KrausMatthias]

Newer versions of Nextcloud (v29 and later) are using username@fqdn

Yes, but they do still accept it, effectivly allowing a downgrade of Discovery to http (which I have to admit was convenient for testing)

Potential foot-gun for implementations: FQDNs are case insensitive, so bob@example.org is the same as bob@EXAMPLE.org

Why would this be an issue? the fqdn part is generally used to fetch the OCM discovery endpoint, they both would end up in the same place.

I agree that is not a large problem, I mostly added that for completeness, but might e.g. result in duplicated entries in contact books or issues when naively checking a Directory Service.

Btw. in the Directory Service Spec the "url" is said to be the FQDN of the OCM Server which is contradictory (the example also uses the URL, not the FQDN)

Please tell me if I'm too picky here, I just think being precise would help compatibility.

[MahdiBaghbani]

Yes, but they do still accept it, effectivly allowing a downgrade of Discovery to http

Oh, didn't know they allow it. IMO that's implementation dependent, as long as they support the "Canonical" form and could be able to send/receive from other implementors

result in duplicated entries in contact books or issues when naively checking a Directory Service.

Maybe a quick note about them being same is helpful for implementors reading the I-D

I just think being precise would help compatibility.

I concur

[MahdiBaghbani]

Btw. in the Directory Service Spec the "url" is said to be the FQDN of the OCM Server which is contradictory (the example also uses the URL, not the FQDN)

I came up with a quick edit:

(Also, since it's a URL, we might also address the non-default port and others defined in here
https://datatracker.ietf.org/doc/html/rfc1738#section-5 as well)

A third-party Directory Service is a back-end service used to federate
multiple OCM Servers and facilitate the Invite flow. It is expected to
expose, via anonymous HTTP GET, a JSON document with the following
format:

-   REQUIRED: `federation` - a human-readable name for the list of OCM
    Servers exposed by the Directory Service
-   REQUIRED: `servers` - a JSON array of objects to describe the list
    of OCM Servers with the following string fields:
    -   REQUIRED: `url` - an absolute HTTPS URL identifying the OCM Server. It MUST:
        -   include scheme `https://`
        -   include host (FQDN)
        -   MAY include a non-default port
        -   MUST NOT include a base path (e.g., `/ocm`)
        -   MUST NOT include userinfo, query, or fragment
    -   REQUIRED: `displayName` - a human-readable name for the OCM Server

Example:

{
	"federation": "The ScienceMesh Directory",
	"servers": [
		{
			"url": "https://ocm-server-1.example.org",
			"displayName": "OCM Server 1"
		},
		{
			"url": "https://ocm-server-2.example.org:4443",
			"displayName": "OCM Server 2"
		}
	]
}

What's the opinion on this? 😄

[mickenordin]

What's the opinion on this? 😄

Sounds good!

[glpatcern]

Btw. in the Directory Service Spec the "url" is said to be the FQDN of the OCM Server which is contradictory (the example also uses the URL, not the FQDN)

I came up with a quick edit:

@MahdiBaghbani , please create a PR with that! Indeed, the description was a "quick" text where it was given for granted that the URL should contain the FQDN of the OCM Server, and a better spelling is definitely welcome.

@KrausMatthias thanks for the contribution, I still have to review it but definitely goes in the right direction.

[glpatcern]

I think it's all good here.
What remains (and could go in a separate PR) concerns the definition of OCM Address in the Terms: what I meant in my previous comment was that we could incorporate what an OCM Address can and cannot be, following the examples you discussed. E.g. the former use of Nextcloud with the prefix is not allowed, whereas a FQDN MAY be replaced by an IP - even just for testing purposes, and the port MAY be included as well.

[glpatcern]

Regarding 1. I would first like to discuss where we want to go before I try to update the definition:

Yes, absolutely. I appreciate that you have "fresh eyes" and are not biased as we are (I am at least) ;-)

...

  * mention that the opaque string is case-sensitive? So [bob@example.org](mailto:bob@example.org) and [BOB@example.org](mailto:BOB@example.org) are not the same? This might be surprising to users and implementers as e.g. emails are case-insensitive

We should then mention that the string is case-INsensitive. It would match expectations with how emails etc. are used.

  * mention that userinfo may contain reserved characters (e.g. '@', ':'), so the OCM Address isn't a valid URI (https://www.rfc-editor.org/rfc/rfc3986#section-3.2.1) and therefore might fail to be parsed using URI tools from standard libraries

Yes.

* server-part
  
  * In my understanding FQDN does exclude IP and Port (which might be helpful for testing), opposed to "host" as specified in https://www.rfc-editor.org/rfc/rfc3986#section-3.2.2
  * FQDN does exclude scheme as used by Nextcloud, their use would therefore be invalid according to the current spec
  * Potential foot-gun for implementations: FQDNs are case insensitive, so [bob@example.org](mailto:bob@example.org) is the same as [bob@EXAMPLE.org](mailto:bob@EXAMPLE.org)
  * It's hard to pin point an exact spec of "FQDN", best thing I found is https://www.rfc-editor.org/rfc/rfc1123#section-2 and https://datatracker.ietf.org/doc/html/rfc1034#section-3.5

Then we could go for either a FQDN or IP address, with an optional PORT kind of definition.

Examples of invalid OCM Addresses as of the current spec as I understand it:

* user@https://example.org

* [user@exampe.org](mailto:user@exampe.org):80

* user@127.0.0.1:443

* user@127.0.0.1

The latter two would become valid, and would be useful in a testing scenario.

Examples of valid but misleading OCM Addresses:

* http://test@example.org -> http:// looks like a scheme that might be used to distinguish if discovery should be done via http or https, but is in fact only part of the "opaque string" (not saying Sending Servers or Sending Parties should be able to downgrade Discovery at the Receiving Server to http by default)

IMHO we could recommend SHOULD NOT include a prefix, but not prescrive (MUST NOT) anything. I'd prefer the opaque string to really be opaque, and any assumption made on it is not compliant.

* user:[pass@example.org](mailto:pass@example.org) -> the username is "user:pass" not "user". This might lead to issues with implementations using URI tools from standard libraries

Again the user is opaque, it's not a URI.

* acct://[asdf@example.org](mailto:asdf@example.org) would actually also be a valid OCM Address according to the current spec

Correct, except that acct://user is typically not the way to identify a user at a given cloud storage service.

[mickenordin]

I also approve, but you should also add your name here:

OCM-API/IETF-RFC.md

Lines 1149 to 1152 in 8fb3363

	We would also like to thank Ishank Arora, Gianmaria Del Monte,
	Jörn Friedrich Dreyer, Hugo González Labrador, Maxence Lange,
	Lovisa Lugnegård, Sandro Mesterheide, Antoon Prins and Björn Schießle
	for their direct contributions to the specification.

😃

[KrausMatthias]

Then we could go for either a FQDN or IP address, with an optional PORT kind of definition.

Should this then reference https://www.rfc-editor.org/rfc/rfc3986#section-3.2.2 and https://www.rfc-editor.org/rfc/rfc3986#section-3.2.3?

We should then mention that the string is case-INsensitive. It would match expectations with how emails etc. are used.

I guess that would conflict with it being a opaque string.

Is the opaque string utf-8 or limited to ascii?

I will try to add a proposal for the OCM Address description on friday.

[MahdiBaghbani]

either a FQDN or IP address, with an optional PORT

I have been thinking about this all day, I think this has been overlooked during previous
iterations, a very powerful addition for both testing and implementations.

[glpatcern]

Then we could go for either a FQDN or IP address, with an optional PORT kind of definition.

Should this then reference https://www.rfc-editor.org/rfc/rfc3986#section-3.2.2 and https://www.rfc-editor.org/rfc/rfc3986#section-3.2.3?

Yes, good idea.

We should then mention that the string is case-INsensitive. It would match expectations with how emails etc. are used.

I guess that would conflict with it being a opaque string.

You have a point :-) And I confirm the opaqueness is to be preferred: after all, the rationale here is that the user-identifying string only makes sense within a local system, not for the remote one, and therefore a remote system must treat it as opaque (and case sensitive then). For the charset, to keep maximum flexibility we should consider UTF-8 (I guess it's already the case for Seafile, given that it's commonly deployed in China).

I will try to add a proposal for the OCM Address description on friday.

Very good, looking forward to it.

[glpatcern]

either a FQDN or IP address, with an optional PORT

I have been thinking about this all day, I think this has been overlooked during previous iterations, a very powerful addition for both testing and implementations.

In fact, that was already the case for the unit tests we run in Reva, where we spin off two Reva daemons that invite each other on 127.0.0.1:9143 and 127.0.0.1:9243!

[glpatcern]

@KrausMatthias apologies, with merging another PR there are now a couple of conflicts, could you please resolve them so this can be merged? Feel free to open a separate PR for the "OCM Address definition proposal".

[MahdiBaghbani]

@KrausMatthias, @glpatcern I've got some time, so I tried resolving the conflict.

Also moved Mattias name in contributor names in alphabetical order, please check if I missed anything.

[glpatcern]

Thanks Mahdi