matrix-org / matrix-org/matrix-spec

Confusing cycle: S-S API -> room version auth rules -> S-S api auth events selection

Open
#1,046 1 comment 0 reactions 0 assignees View on GitHub
clarification
Dominant language
HTML
Stars
330
Forks
150
Avg merge
2h 21m
Merged PRs (30d)
3

Description

To find out what checks need to be made of incoming PDUs, one must consult [the server-server API](https://spec.matrix.org/v1.2/server-server-api/#checks-performed-on-receipt-of-a-pdu). For checking the `auth_events` in particular, we learn [here](https://spec.matrix.org/v1.2/server-server-api/#authorization-rules) that tells you that the rules depend on the room version.

Each individual room version has the following as step 2:

> 2. Reject if event has auth_events that:
> 1. have duplicate entries for a given type and state_key pair
> 2. have entries whose type and state_key don’t match those specified by the [auth events selection](https://spec.matrix.org/v1.2/server-server-api#auth-events-selection) algorithm described in the server specification.

Following that link takes you back to the server-server API. I found that confusing. Then for steps 3 onward you switch back to the room version document.

It might be clearer to make the auth event selection rules part of the room version itself---particularly if we might want to change those rules in the future?

Contributor guide

Open the contributing guide

Research direction

Start by comparing the server-server API sections on checks performed on receipt of a PDU, authorization rules, and auth events selection with the individual room version documents. Determine where the auth event selection rules should live so readers do not loop between documents; done means the specification presents a clear, consistent path for checking auth_events.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.