matrix-org / matrix-org/matrix-spec
Unsuccessful response format of `/keys/signatures/upload` is poorly specified
Nobody has claimed this yet.
- Dominant language
- HTML
- Stars
- 330
- Forks
- 150
- Avg merge
- 2h 21m
- Merged PRs (30d)
- 3
Description
Link to problem area:
https://spec.matrix.org/v1.7/client-server-api/#post_matrixclientv3keyssignaturesupload
Issue
The response format for this is specced as failures | {string: {string: Error}} but doesn't really say what shape an Error is. The example implies it should be a standard error response, but neither the spec wording nor the openapi spec actually say so.
In practice, synapse returns a structure like this:
{
"status": 400,
"errcode": "M_INVALID_SIGNATURE",
"message": "400: Invalid signature"
}
... which, other than an errcode, is nothing like a standard error response.
MSC1756, which introduced this endpoint, says simply "if a signature is not valid, the homeserver should set the corresponding entry in failures to a JSON object with the errcode property set to M_INVALID_SIGNATURE."
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
Start with the linked Matrix Client-Server API section for POST /keys/signatures/upload, then compare its response wording with cross_signing.yaml and MSC1756. Document the shape of each failures entry consistently across the prose, example, and OpenAPI specification, including what the Error object contains.
Written by the indexing model from the issue text.
Assessment
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 35/100