matrix-org / matrix-org/matrix-spec

Unsuccessful response format of `/keys/signatures/upload` is poorly specified

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

Nobody has claimed this yet.

clarification
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

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.