diff --git a/drafts/as-http-api.rst b/drafts/as-http-api.rst index 59d5a3e4..fd0b302e 100644 --- a/drafts/as-http-api.rst +++ b/drafts/as-http-api.rst @@ -13,7 +13,8 @@ Registration API ``[Draft]`` .. NOTE:: - Do we really have to use regex for this? Can't we do this a nicer way? -This API registers the application service with its host homeserver to offer its services. +This API registers the application service with its host homeserver to offer its +services. Inputs: - Credentials (e.g. some kind of string token) @@ -21,7 +22,8 @@ Inputs: - Namespace[room aliases] - URL base to receive inbound comms Output: - - The credentials the HS will use to query the AS with in return. (e.g. some kind of string token) + - The credentials the HS will use to query the AS with in return. (e.g. some + kind of string token) Side effects: - The HS will start delivering events to the URL base specified if this 200s. API called when: @@ -76,7 +78,8 @@ Inputs: Output: - None. Side effects: - - The HS will stop delivering events to the URL base specified for this AS if this 200s. + - The HS will stop delivering events to the URL base specified for this AS if + this 200s. API called when: - The application service wants to stop receiving all events from the HS. @@ -97,7 +100,8 @@ This contains application service APIs which are used by the home server. User Query ``[Draft]`` ~~~~~~~~~~~~~~~~~~~~~~ -This API is called by the HS to query the existence of a user on the Application Service's namespace. +This API is called by the HS to query the existence of a user on the Application +Service's namespace. Inputs: - User ID @@ -131,109 +135,84 @@ Notes: } } -Room Alias Query ``[TODO]`` +Room Alias Query ``[Draft]`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This API is called by the HS to query the existence of a room alias on the Application -Service's namespace. +This API is called by the HS to query the existence of a room alias on the +Application Service's namespace. +Inputs: + - Room alias + - HS Credentials +Output: + - The current state events for the room if any. + - The message events for the room if any. +Side effects: + - A new room will be created with the alias input if this response 200s. +API called when: + - HS receives an event to join a room alias in the AS's namespace. +Notes: + - This can be thought of as an ``initialSync`` but for a 3P networked room, + which is lazily loaded when a matrix user tries to join the room. + +:: + + GET /rooms/$room_alias?access_token=$hs_token + + Returns: + 200 : Room is recognised. + 404 : Room not found. + 401 : Credentials need to be supplied. + 403 : HS credentials rejected. + + + 200 OK response format + + { + events: [ + { + content: { + ... + }, + user_id: "string", + origin_server_ts: integer, // massaged timestamps + type: "string" + }, + ... + ], + state: [ + { + content: { + ... + }, + user_id: "string(virtual user id)", + origin_server_ts: integer, + state_key: "string", + type: "string" // e.g. m.room.name + }, + ... + ] + } Pushing ``[TODO]`` ~~~~~~~~~~~~~~~~~~ -This API is called by the HS when the HS wants to push an event (or batch of events) to the AS. +This API is called by the HS when the HS wants to push an event (or batch of +events) to the AS. - Retry semantics - Ordering - -Client -> Server -> Application Service ---------------------------------------- -This contains home server APIs which are used by the client, to communicate with -the application service. - -Linking ``[Draft]`` -~~~~~~~~~~~~~~~~~~ -.. NOTE:: - - How does the application service know that the matrix user really is the virtual - user they claim to be? If we force an IS lookup, then this would resolve on its - own as anyone who wants to talk to the virtual user will do a lookup before trying - the application service... - - In other words, what is preventing ``@bob:matrix.org`` masquerading as - ``@.irc.freenode.alice:matrix.org``? - -Clients may want to link their matrix user ID to their virtual user ID. This -API allows the AS to do this, so messages sent from the AS are sent as the client's -user ID, instead of the virtual user ID. - -This is not achieved using OAuth2 or similar because the trust relationships are -different. The application service already has a huge amount of trust from the -home server, unlike a random third-party web app. As a result, the data flow is -different because the third-party (the application service) is trusted by the -authorisation entity (the home server). Furthermore, it is desirable to not have -the clients communicate directly with the application service in order to -decrease the complexity of AS design. - -To grant permission for an application service to masquerade as a user: - -Inputs: - - Credentials of user (e.g. ``access_token``) - - The user ID within an application service's namespace to claim. - - Restrictions if any (e.g. only for rooms X,Y,Z. Only for 10 hours. etc) -Output: - - None. -Side effects: - - The home server will generate an ``access_token`` and push it to the - application service along with both user IDs if this response 200s. -Notes: - - Repeated calls to this API should invalidate any existing token for this - user ID / application service combo and provision a new token which is then - pushed. - - The generated access token MUST honour the restrictions laid out by the - client. - -:: - - PUT /appservices/$virtual_user_id?access_token=$token - - Request format - { - restrictions: { - expires_in: 3600, - rooms: [ - "!fl3rwfehw:matrix.org", - "!fwet2yugs:matrix.org" - ] - } - } - -To revoke permission for an application service to masquerade as a user: - -Inputs: - - Credentials of user (e.g. ``access_token``) - - The user ID within an application service's namespace to revoke. If blank, - revokes all virtual user IDs linked to this matrix user ID. -Output: - - None. -Side effects: - - The home server invalidate all access tokens for this user ID / AS combo - and push this invalidation to the application service if this response 200s. - -:: - - DELETE /appservices/$virtual_user_id?access_token=$token - - Client-Server v2 API Extensions ------------------------------- Identity assertion ~~~~~~~~~~~~~~~~~~ -The client-server API infers the user ID from the ``access_token`` provided in every -request. It would be an annoying amount of book-keeping to maintain tokens for every -virtual user. It would be preferable if the application service could use the CS API -with its own ``as_token`` instead, and specify the virtual user they wish to be -acting on behalf of. For real users, this would require additional permissions (see -"C-AS Linking"). +The client-server API infers the user ID from the ``access_token`` provided in +every request. It would be an annoying amount of book-keeping to maintain tokens +for every virtual user. It would be preferable if the application service could +use the CS API with its own ``as_token`` instead, and specify the virtual user +they wish to be acting on behalf of. For real users, this would require +additional permissions (see "C-AS Linking"). Inputs: - Application service token (``access_token``) @@ -243,9 +222,9 @@ Inputs: - OAuth2 token of real user (which may end up being an access token) Notes: - This will apply on all aspects of the CS API, except for Account Management. - - The ``as_token`` is inserted into ``access_token`` which is usually where the client - token is. This is done on purpose to allow application services to reuse client - SDKs. + - The ``as_token`` is inserted into ``access_token`` which is usually where the + client token is. This is done on purpose to allow application services to + reuse client SDKs. :: @@ -288,3 +267,15 @@ namespace, both for users and for room aliases. This means that the AS should be able to create/edit/delete any room alias in its namespace, as well as create/delete any user in its namespace. This does not require any additional public APIs. + + +ID conventions +-------------- +This concerns the well-defined conventions for mapping 3P network IDs to matrix +IDs, which we expect clients to be able to do by themselves. + +- What do user IDs look like? Butchered URIs? Can all 3P network IDs be + reasonably expressed as URIs? (e.g. tel, email, irc, xmpp, ...) +- What do room aliases look like? Some cases are clear (e.g. IRC) but others + are a lot more fiddly (e.g. email? You don't want to share a room with + everyone who has ever sent an email to ``bob@gmail.com``)... \ No newline at end of file