matrix-org / matrix-org/matrix-spec

Application Service API does not specify a `401` for missing or invalid access tokens for HS->AS requests

Open
#1,528 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-Application-Services clarification
Dominant language
HTML
Stars
330
Forks
150
Avg merge
2h 21m
Merged PRs (30d)
3

Description

The Application Service API has an [Authorization section](https://spec.matrix.org/v1.6/application-service-api/#authorization) to specify what an application service should return when a homeserver:

* fails to supply a `hs_token` parameter
* supplies an `hs_token` that is unknown to the application service.

Currently the section states the following:

> Homeservers MUST include an `Authorization` header, containing the `hs_token`
> from the application service's registration, when making requests to the
> application service. Application services MUST verify that the provided
> `Bearer` token matches their known `hs_token`, failing the request with
> an `M_FORBIDDEN` error if it does not match.

which implies that in both of the above cases, the application service should return a `M_FORBIDDEN` errcode. It does not state what HTTP status code should be returned.

It would be nice to update this section to reflect both [web standards](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses) and the [existing semantics](https://spec.matrix.org/v1.6/client-server-api/#using-access-tokens) of the Client-Server API. In the above cases, application services could instead:

* return a `401` / `M_MISSING_TOKEN` in the case of the homeserver failing to supply an `hs_token` in an `Authorization` request header.
* return a `401` / `M_UNKNOWN_TOKEN` in the case of the homeserver supplying a token that does not match the `hs_token` in the application service's registration file.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Open the Application Service API Authorization section and compare its token-error behavior with the Client-Server API access-token semantics and the linked HTTP status guidance. Update the specification to define the status and errcode for missing and unknown homeserver tokens, then verify the section clearly covers both cases.

Written by the indexing model from the issue text.

Assessment

Domain
api, authentication, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.