wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge branch 'master' into travis/clarification/lowercasing

Browse source
This commit is contained in:
Travis Ralston 2021-05-18 09:55:57 -06:00 • committed by Richard van der Hoff
commit 21a132d3a5
21 changed files with 661 additions and 1380 deletions
Download patch file Download diff file Expand all files Collapse all files

37
content/appendices.md
View file

@ -590,32 +590,6 @@ Event IDs and Room IDs are case-sensitive. They are not meant to be
human-readable. They are intended to be treated as fully opaque strings
by clients.
#### Group Identifiers
Groups within Matrix are uniquely identified by their group ID. The
group ID is namespaced to the group server which hosts this group and
has the form:
+localpart:domain
The `localpart` of a group ID is an opaque identifier for that group. It
MUST NOT be empty, and MUST contain only the characters `a-z`, `0-9`,
`.`, `_`, `=`, `-`, and `/`.
The `domain` of a group ID is the [server name](#server-name) of the
group server which hosts this group.
The length of a group ID, including the `+` sigil and the domain, MUST
NOT exceed 255 characters.
The complete grammar for a legal group ID is:
group_id = "+" group_id_localpart ":" server_name
group_id_localpart = 1*group_id_char
group_id_char = DIGIT
/ %x61-7A ; a-z
/ "-" / "." / "=" / "_" / "/"
#### Room Aliases
A room may have zero or more aliases. A room alias has the format:
@ -674,7 +648,6 @@ Examples of matrix.to URIs are:
- Permalink by room alias:
`https://matrix.to/#/%23somewhere:example.org/%24event%3Aexample.org`
- User: `https://matrix.to/#/%40alice%3Aexample.org`
- Group: `https://matrix.to/#/%2Bexample%3Aexample.org`
{{% boxes/note %}}
Historically, clients have not produced URIs which are fully encoded.
@ -690,6 +663,16 @@ versions](/#room-versions). These slashes should normally be
encoded when producing matrix.to URIs, however.
{{% /boxes/note %}}
{{% boxes/note %}}
<!-- TODO: @@TravisR: Make "Spaces" a link when that specification exists -->
In prior versions of this specification, a concept of "groups" were mentioned
to organize rooms. This functionality did not properly get introduced into
the specification and is subsequently replaced with "Spaces". Historical
matrix.to URIs pointing to groups might still exist: they take the form
`https://matrix.to/#/%2Bexample%3Aexample.org` (where the `+` sigil may or
may not be encoded).
{{% /boxes/note %}}
##### Routing
Room IDs are not routable on their own as there is no reliable domain to

2
content/client-server-api/_index.md
View file

@ -297,7 +297,7 @@ specify parameter values. The flow for this method is as follows:
6. If the `m.identity_server` property is present, extract the
`base_url` value for use as the base URL of the identity server.
Validation for this URL is done as in the step above, but using
`/_matrix/identity/api/v1` as the endpoint to connect to. If the
`/_matrix/identity/v2` as the endpoint to connect to. If the
`m.identity_server` property is present, but does not have a
`base_url` value, then `FAIL_PROMPT`.

75
content/identity-service-api.md
View file

@ -59,48 +59,48 @@ the keys `error` and `errcode` MUST always be present.
Some standard error codes are below:
`M_NOT_FOUND`
`M_NOT_FOUND`
The resource requested could not be located.
`M_MISSING_PARAMS`
`M_MISSING_PARAMS`
The request was missing one or more parameters.
`M_INVALID_PARAM`
`M_INVALID_PARAM`
The request contained one or more invalid parameters.
`M_SESSION_NOT_VALIDATED`
`M_SESSION_NOT_VALIDATED`
The session has not been validated.
`M_NO_VALID_SESSION`
`M_NO_VALID_SESSION`
A session could not be located for the given parameters.
`M_SESSION_EXPIRED`
`M_SESSION_EXPIRED`
The session has expired and must be renewed.
`M_INVALID_EMAIL`
`M_INVALID_EMAIL`
The email address provided was not valid.
`M_EMAIL_SEND_ERROR`
`M_EMAIL_SEND_ERROR`
There was an error sending an email. Typically seen when attempting to
verify ownership of a given email address.
`M_INVALID_ADDRESS`
`M_INVALID_ADDRESS`
The provided third party address was not valid.
`M_SEND_ERROR`
`M_SEND_ERROR`
There was an error sending a notification. Typically seen when
attempting to verify ownership of a given third party address.
`M_UNRECOGNIZED`
`M_UNRECOGNIZED`
The request contained an unrecognised value, such as an unknown token or
medium.
`M_THREEPID_IN_USE`
`M_THREEPID_IN_USE`
The third party identifier is already in use by another user. Typically
this error will have an additional `mxid` property to indicate who owns
the third party identifier.
`M_UNKNOWN`
`M_UNKNOWN`
An unknown error has occurred.
{{% http-api spec="identity" api="versions" %}}
@ -116,22 +116,6 @@ Matrix user identity, but not in the other direction (i.e. one should
not be able to get all 3PIDs associated with a Matrix user ID, or get
all 3PIDs associated with a 3PID).
## Version 1 API deprecation
As described on each of the version 1 endpoints, the v1 API is
deprecated in favour of the v2 API described here. The major difference,
with the exception of a few isolated cases, is that the v2 API requires
authentication to ensure the user has given permission for the identity
server to operate on their data.
The v1 API is planned to be removed from the specification in a future
version.
Clients SHOULD attempt the v2 endpoints first, and if they receive a
`404`, `400`, or similar error they should try the v1 endpoint or fail
the operation. Clients are strongly encouraged to warn the user of the
risks in using the v1 API, if they are planning on using it.
## Web browser clients
It is realistic to expect that some clients will be written to be run
@ -149,12 +133,9 @@ recommended CORS headers to be returned by servers on all requests are:
## Authentication
Most `v2` endpoints in the Identity Service API require authentication
Most endpoints in the Identity Service API require authentication
in order to ensure that the requesting user has accepted all relevant
policies and is otherwise permitted to make the request. The `v1` API
(currently deprecated) does not require this authentication, however
using `v1` is strongly discouraged as it will be removed in a future
release.
policies and is otherwise permitted to make the request.
Identity Servers use a scheme similar to the Client-Server API's concept
of access tokens to authenticate users. The access tokens provided by an
@ -204,8 +185,6 @@ has just accepted are appended to `m.accepted_terms`.
## Status check
{{% http-api spec="identity" api="ping" %}}
{{% http-api spec="identity" api="v2_ping" %}}
## Key management
@ -219,23 +198,14 @@ The identity server may also keep track of some short-term
public-private keypairs, which may have different usage and lifetime
characteristics than the service's long-term keys.
{{% http-api spec="identity" api="pubkey" %}}
{{% http-api spec="identity" api="v2_pubkey" %}}
## Association lookup
{{% http-api spec="identity" api="lookup" %}}
{{% http-api spec="identity" api="v2_lookup" %}}
### Client behaviour
{{% boxes/note %}}
This section only covers the v2 lookup endpoint. The v1 endpoint is
described in isolation above.
{{% /boxes/note %}}
Prior to performing a lookup clients SHOULD make a request to the
`/hash_details` endpoint to determine what algorithms the server
supports (described in more detail below). The client then uses this
@ -246,11 +216,6 @@ Clients MUST support at least the `sha256` algorithm.
### Server behaviour
{{% boxes/note %}}
This section only covers the v2 lookup endpoint. The v1 endpoint is
described in isolation above.
{{% /boxes/note %}}
Servers, upon receipt of a `/lookup` request, will compare the query
against known bindings it has, hashing the identifiers it knows about as
needed to verify exact matches to the request.
@ -400,20 +365,14 @@ through without modification.
### Email associations
{{% http-api spec="identity" api="email_associations" %}}
{{% http-api spec="identity" api="v2_email_associations" %}}
### Phone number associations
{{% http-api spec="identity" api="phone_associations" %}}
{{% http-api spec="identity" api="v2_phone_associations" %}}
### General
{{% http-api spec="identity" api="associations" %}}
{{% http-api spec="identity" api="v2_associations" %}}
## Invitation storage
@ -429,8 +388,6 @@ the Matrix user's homeserver via the
endpoint. The request MUST be signed with a long-term private key for
the identity server.
{{% http-api spec="identity" api="store_invite" %}}
{{% http-api spec="identity" api="v2_store_invite" %}}
## Ephemeral invitation signing
@ -440,6 +397,4 @@ identity server offers some crypto functionality to help in accepting
invitations. This is less secure than the client doing it itself, but
may be useful where this isn't possible.
{{% http-api spec="identity" api="invitation_signing" %}}
{{% http-api spec="identity" api="v2_invitation_signing" %}}

50
content/proposals.md
View file

@ -245,10 +245,13 @@ is as follows:
75% of the members of the Spec Core Team agree on its outcome, and
all existing concerns have been resolved.
- The FCP will then begin and last for 5 days, giving anyone else some
time to speak up before it concludes. On its conclusion, the
disposition of the FCP will be carried out. If sufficient reasoning
against the disposition is raised, the FCP can be cancelled and the
MSC will continue to evolve accordingly.
time to speak up before it concludes. If sufficient reasoning
against the disposition is provided, a member of the Spec Core Team can
raise a concern and block FCP from completing. This will not reset or
pause the 5 day FCP timer, but FCP will not conclude until all concerns have
been resolved. If sufficient change in the MSC is required to resolve those
concerns, FCP might be cancelled and reproposed. Once FCP has concluded,
the disposition of the FCP will be carried out.
- Once the proposal has been accepted and merged, it is time to submit
the actual change to the Specification that your proposal reasoned
about. This is known as a spec PR. However in order for the spec PR
@ -259,7 +262,7 @@ is as follows:
will warrant another MSC. Any minor, non-fundamental changes are
allowed but **must** be documented in the original proposal
document. This ensures that someone reading a proposal in the future
doesn't assume old information wasn't merged into the spec.
doesn't assume old information that wasn't merged into the spec.
- Similar to the proposal PR, please sign off the spec PR as per
the guidelines on
[CONTRIBUTING.rst](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst).
@ -373,7 +376,7 @@ be merged without the Spec Core Team focusing on them specifically.
## Implementing a proposal
As part of the proposal process the spec core team will require evidence
As part of the proposal process the Spec Core Team will require evidence
of the MSC working in order for it to move into FCP. This can usually be
a branch/pull request to whichever implementation of choice that proves
the MSC works in practice, though in some cases the MSC itself will be
@ -388,13 +391,11 @@ release, implementations are required to use the following process to
ensure that the official Matrix namespace is not cluttered with
development or testing data.
Note
Unreleased implementations (including proofs-of-concept demonstrating
**Note:** Unreleased implementations (including proofs-of-concept demonstrating
that a particular MSC works) do not have to follow this process.
1. Have an idea for a feature.
2. Implement the feature using unstable endpoints, vendor prefixes, and
1. Implement the feature using unstable endpoints, vendor prefixes, and
unstable feature flags as appropriate.
- When using unstable endpoints, they MUST include a vendor
prefix. For example:
@ -429,22 +430,25 @@ that a particular MSC works) do not have to follow this process.
- If at any point after early release, the idea changes in a
backwards-incompatible way, the feature flag should also change
so that implementations can adapt as needed.
3. In parallel, or ahead of implementation, open an MSC and solicit
1. In parallel, or ahead of implementation, open an MSC and solicit
review per above.
4. Before FCP can be called, the Spec Core Team will require evidence
1. Before FCP can be called, the Spec Core Team will require evidence
of the MSC working as proposed. A typical example of this is an
implementation of the MSC, though the implementation does not need
to be shipped anywhere and can therefore avoid the
forwards/backwards compatibility concerns mentioned here.
5. The FCP process is completed, and assuming nothing is flagged the
1. The FCP process is completed, and assuming nothing is flagged the
MSC lands.
6. A spec PR is written to incorporate the changes into Matrix.
7. A spec release happens.
8. Implementations switch to using stable prefixes (e.g.: `/r0`) if the
server supports the specification version released. If the server
doesn't advertise the specification version, but does have the
feature flag, unstable prefixes should still be used.
9. A transition period of about 2 months starts immediately after the
1. Implementations can now switch to using stable prefixes
(for example, for an endpoint, moving from
`/unstable/org.matrix.mscxxxx/frobnicate`
to `/v1/frobnicate`), assuming that the change
is backwards compatible with older implementations. In the rare occasion
where backwards compatibility is not possible without a new spec release,
implementations should continue to use unstable prefixes.
1. A spec PR is written to incorporate the changes into Matrix.
1. A spec release happens.
1. A transition period of about 2 months starts immediately after the
spec release, before implementations start to encourage other
implementations to switch to stable endpoints. For example, a server
implementation should start asking client implementations to support
@ -463,9 +467,9 @@ com.example/new/endpoint`.
In summary:
- Implementations MUST NOT use stable endpoints before the MSC is in
the spec. This includes NOT using stable endpoints in the period
between completion of FCP and release of the spec. passed.
- Implementations MUST NOT use stable endpoints before the MSC has
completed FCP. Once that has occurred, implementations are allowed
to use stable endpoints, but are not required to.
- Implementations are able to ship features that are exposed to users
by default before an MSC has been merged to the spec, provided they
follow the process above.