Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

MSC2233: Unauthenticated Capabilities API #2233

Closed
wants to merge 6 commits into from
Closed

MSC2233: Unauthenticated Capabilities API #2233

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
e51634a
MSC2233: init commit
anoadragon453 Aug 15, 2019
2c222fd
wip
anoadragon453 Aug 15, 2019
f147b90
Change to unauthed capabilities
anoadragon453 Aug 16, 2019
9b7d8c2
Update proposals/2233-unauthed-capabilities-endpoint.md
anoadragon453 Aug 16, 2019
56af944
Talk about why we didn't just add auth/noauth to capabilities
anoadragon453 Aug 16, 2019
d46cf44
Merge branch 'anoa/msc2233' of github.com:matrix-org/matrix-doc into …
anoadragon453 Aug 16, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 66 additions & 0 deletions proposals/2233-unauthed-capabilities-endpoint.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
# Unauthenticated Capabilities API
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm a bit concerned about the proliferation of 'features' endpoints (/versions, /_matrix/client/r0/capabilities/server, /_matrix/client/r0/capabilities/user, /_matrix/media/r0/config): the main concern being that it's not obvious what goes where.

Indeed, ISTR the main driver for /_matrix/client/r0/capabilities as opposed to /versions was that it required authentication...

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was going to say that putting feature capabilities on /versions doesn't make sense given the name, but then I realized we're already doing that :|

image

These things could be added to /versions then if we think that that's not too weird.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with @richvdh that we have far too many endpoints for similar things, although I was never really onboard with putting features inside /versions.

To be honest I wish we had just named them something like /_matrix/${apiname}/config/ so it was at least consistent.

If we could go back in time, I wish we hadn't polluted /versions.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/versions features an unstable_features key which is supposed to be used for additional features that the server supported which are not included in the spec. The examples described in this MSC do not fit these terms.

We could add another key, like config, which would be general enough to hold random public configuration values the server has decided to set up.

Or we can move it to its own API. With regards to this MSC, I think it'd be easy enough to say whether information should go in /versions, /_matrix/client/r0/capabilities/*, or /_matrix/media/r0/config.

And then deciding between capabilities/server and capabilities/user would just be "does this information need to either rely on a user, or is potentially sensitive"? Then it goes in /user, otherwise /server.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we actually have a strong use case for this MSC at all? If this MSC also had a capability it wanted to add then we could discuss the merits of that capability in the context of a new API vs some other solution. Without an example, the distinction between the endpoints is unclear and seems to be building a framework for a feature we don't know if we even want.

If we don't have an example for this API, this MSC should be put on the backburner or closed until we need it imo. I also have general concerns with an unauthenticated version of the endpoint because the cases presented thus far are better solved in other ways.


## Introduction

The existing [Capabilities
API](https://matrix.org/docs/spec/client_server/r0.5.0#get-matrix-client-r0-capabilities)
is an authenticated endpoint that allows a Matrix server to advertise which
services it does and does not provide. The authentication is due to the
possibility of suggesting that some capabilities are supported for some
users, while the same may not be supported for others (imagine a regular user
querying this endpoint, and then an application service doing the same).

While the ability to scope the capabilities to the requesting user is very
useful, there are use cases that could benefit from this API being called
from an unauthenticated user as well. For instance, information that a user
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not convinced that any of the examples that follow need a capabilities endpoint.

  • "We process your data" -> Terms of service acceptance. Could have additional flows for informational things, but this would likely be better served at an advertising page before registration.
  • "We disallow key backup" -> Advertising for the server before the registration page (it'd be a feature of the service and not something we need to care about in the spec, imo)
  • Other information at registration time -> UIA while using params to send data along.
  • Server listing sites -> MSC2063, MSC1929, and/or https://talk.feneas.org/t/serverinfo-specification-for-server-metadata/99

would like to know about a server before they sign up, such as whether the
server sends message content through a media-scanner, or whether the server
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sends message content through a media-scanner

is this really a thing that is better exposed over an API than described in a policy document for a human to read?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can still see a usecase for values that sites may want to pull and present their own filtering for.

allows E2EE session key backup. A client could query this information before
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

allows E2EE session key backup

surely this should be under /versions ?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Discussed in #2233 (comment)

they sign up. Another usecase is websites that lists public Matrix servers
could automatically query whether each server supports features that may be
important to users, without having to authenticate to the server to do so.


## Proposal

Add two new API endpoints:

* `GET /_matrix/client/r0/capabilities/server`
* `GET /_matrix/client/r0/capabilities/user`

`/capabilities/user` would be exactly the same as the existing
`/capabilities` endpoint, which requires authentication as what it returns is
scoped to the user making the request.

`/capabilities/server` would not require authentication and should return
information about the server's capabilities that would be pertinent to
non-authenticated users.

The existing `/capabilities` API would be replaced by `/capabilities/user`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Due to the backwards compatibility section below, it should be deprecated with intent to replace, not replaced.


## Backwards compatibility

Servers supporting older versions of the Client Server API should continue to
answer `/capabilities` requests as if they were `/capabilities/user`. They
MUST NOT redirect the request to `/capabilities/user`, as this may confuse
older clients.

## Tradeoffs
anoadragon453 marked this conversation as resolved.
Show resolved Hide resolved

The various features could have their own unauthenticated endpoints to check
whether or not the server supports them, but consolidating them into a single
API potentially reduces our API surface significantly.

Another solution to this problem is to have the existing `/capabilities`
endpoint return public information when no authentication is attempted, and
user-specific information when authentication is provided. This is certainly
functionally valid, however conceptually it's a little complicated to have an
API return different success states based on whether you've authenticated
yourself or not. In addition, none of the rest of the Matrix API currently
does this, so it may not be the best idea to introduce here.

## Conclusion

Adding an unauthenticated version of the `/capabilities` API gives servers
the flexibility to inform the general public about what features they
support, rather than only those that already have an account with them.