matrix-org / matrix-org/matrix-spec
Application Service API does not specify a `401` for missing or invalid access tokens for HS->AS requests
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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