As far as I can tell, these header files only encourage people to create
badly-formatted PRs.
Also we only have one template so let's give it the default name.
Also, some other editorial improvements, including factoring out our two definitions of the same key encoding algorithm.
Co-authored-by: Travis Ralston <travisr@matrix.org>
This was commented prior to the
port to OpenAPI 3.1 for technical reasons (#1127).
Now we can use it just fine.
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
Previously, titles would appear that do not link to a subchema definition.
It would also mean that named subschemas would appear without being clearly referenced.
Now, the type clearly shows the nesting of objects
and subschema definitions should be clearly referenced.
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
Otherwise the version might change depending on the runner.
We just use the same version as other jobs.
This removes a GitHub warning.
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
* Upgrade version of Hugo used to build the spec in CI
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
* Escape HTML manually in property-type partial
The behavior of `delimit` changed,
so Hugo doesn't recognize "safe" HTML passed to it anymore, so it escapes nested HTML links.
To fix that we escape the schema data manually
and consider the output of the partial as "safe".
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
* Add changelog
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---------
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
Makes it easier to use, like resolve-refs. It just needs to be called once.
Fixes an issue with m.call.* events not displaying the common fields
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Since we already have three of these, and I'm about to add a fourth, let's pull
it out to a common definition.
We could, of course, keep defining the grammar each time it's used, but
defining it in an appendix helps us be consistent for future API design.
The split was not clear between property-type and type-or-title,
so it was not obvious which partial should be called for recursion.
That resulted in an error where type-or-title was only called for objects and array items, even if it also resolves
arrays of types.
This makes the split clearer. property-type must be called for any schema,
and object-type-or-title is only called for object schemas.
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
* Use the resolve-refs partial as soon as possible
Call it right after accessing the site.Data,
since it is recursing it will solve all references in the tree.
That way we don't need to wonder where to call it,
we trust the validators that the refs will be used in the right place.
* Enable strict $ref rule in OpenAPI validator
* Document use of $ref to compose examples
* Fix schema path in event-fields shortcode
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
* Fix `v` tag_name prefix sneaking into npm version
* Fix `yarn version` failing in CI due to no git global ident name
* Add changelog
* Rename 1765.misc to 1765.clarification
* Break out non-JSON request/response content types as tables
Currently we display this as a table like "image/png|image/jpeg" and description on a single line, but we're using a table. This breaks the join out to individual rows.
* changelog
It was not enabled before the docsy update and it messes with
the TOC highlighting during the transition.
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
* Deprecate the `font` HTML tag
Rationale:
MSC4077 allows to deprecate HTML tags
that are deprecated in the WHATWG standard,
if they can be replaced by tags with the same feature.
`font` is deprecated and can be replaced by `span`
with the `data-mx-bg-color` and `data-mx-color` attributes.
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
* Add changelog
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
* Add deprecation info box
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---------
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
* Spec for MSC3981
This writes up https://github.com/matrix-org/matrix-spec-proposals/pull/3981
Hopefully this is relatively straightforward, apart from having to add
the parameters and response field in all three places. I tried to factor
these out but it seems references just aren't supported in the right
places currently (see https://github.com/matrix-org/matrix-spec/pull/1745
for my efforts). Path parameters can't be optional, so it can't be done
that way either.
* Missed schemas
* newsfile
* Actually it clearly isn't going to support markdown, is it?
* grammar
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
* grammar
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
* Clarity
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
* Clarity
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
* Typo
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
* More clarity.
Note this is counter what the MSC actually proposed to add, but
I think it's clear that this is what it meant.
---------
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
* clarification around implementation requirement, and mention new label
* add changelog
* fix typo
* Fix typos
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
---------
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
* Add missing 'in' in SSO specification
Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>
* Use standard changelog entry for typos
---------
Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>
Co-authored-by: Hubert Chathi <hubert@uhoreg.ca>
* Convert m.call.candidates schema to YAML
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
* Clarify that sdpMid and sdpMLineIndex are not required in `m.call.candidates`
MSC2746, merged in v1.17,
introduced the end-of-candidates candidate,
where only the `candidate` property is set to an empty string.
Besides, the [WebRTC specification](https://www.w3.org/TR/webrtc/)
says that only one of those fields is required in a normal candidate.
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
* Add changelog
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
* Link to the "End-of-candidates" section, and clarify what "empty" means
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---------
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
* Disambiguate uses of PublicRoomsChunk
Make sure that different objects don't share the same title.
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
* Clarify that extra fields of space hierarchy children are not required
There is no `children_state` field,
the `room_type` is only set for spaces
and the description of `allowed_room_ids` says that the field can be omitted.
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
* Use `body` field as media caption
As per MSC2530.
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
* Add changelog
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
* Use `s` HTML tag in example
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
* Move changed-in annotation
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---------
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
* clarify otk and fallback key types in examples
- remove unsigned curve25519 keys from examples because we don't use those for
otks and fallback keys
- add missing `device_unused_fallback_key_types` property, which is required
* add changelog
* Clarify that the key backup MAC is implemented incorrectly
Due to a bug in libolm, all implementations of the
m.megolm_backup.v1.curve25519-aes-sha2 key backup algorithm incorrectly
pass an empty string through HMAC-SHA-256 to generate the `mac` property
of the `session_data`.
It was intended for the entire raw encrypted data to be passed through
HMAC-SHA-256, but the issue was caught too late in the process, and thus
we are stuck with this until a new key backup algorithm is introduced.
This commit clarifies the real-world behavior of all current
implementations.
Signed-off-by: Sumner Evans <sumner@beeper.com>
Clarify that the `event` field of the `/v2/send_join` response is only required when `join_authorised_via_users_server` was present in the `content` field of the request.
<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
### Client-Server API
**Backwards Compatible Changes**
- Allow `/versions` to optionally accept authentication, as per [MSC4026](https://github.com/matrix-org/matrix-spec-proposals/pull/4026). ([#1728](https://github.com/matrix-org/matrix-spec/issues/1728))
- Add local erasure requests, as per [MSC4025](https://github.com/matrix-org/matrix-spec-proposals/pull/4025). ([#1730](https://github.com/matrix-org/matrix-spec/issues/1730))
- Use the `body` field as optional media caption, as per [MSC2530](https://github.com/matrix-org/matrix-spec-proposals/pull/2530). ([#1731](https://github.com/matrix-org/matrix-spec/issues/1731))
- Add server support discovery endpoint, as per [MSC1929](https://github.com/matrix-org/matrix-spec-proposals/pull/1929). ([#1733](https://github.com/matrix-org/matrix-spec/issues/1733))
- Add support for multi-stream VoIP, as per [MSC3077](https://github.com/matrix-org/matrix-spec-proposals/pull/3077). ([#1735](https://github.com/matrix-org/matrix-spec/issues/1735))
- Specify that the `Retry-After` header may be used to rate-limit a client, as per [MSC4041](https://github.com/matrix-org/matrix-spec-proposals/pull/4041). ([#1737](https://github.com/matrix-org/matrix-spec/issues/1737))
- Add support for recursion on the `GET /relations` endpoints, as per [MSC3981](https://github.com/matrix-org/matrix-spec-proposals/pull/3981). ([#1746](https://github.com/matrix-org/matrix-spec/issues/1746))
**Spec Clarifications**
- The [strike](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/strike) element is deprecated in the HTML spec. Clients should prefer [s](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/s) instead. ([#1629](https://github.com/matrix-org/matrix-spec/issues/1629))
- Clarify that read receipts should be batched by thread as well as by room. ([#1685](https://github.com/matrix-org/matrix-spec/issues/1685))
- Clarify that threads can be created based on replies. ([#1687](https://github.com/matrix-org/matrix-spec/issues/1687))
- Clarify in the reply fallbacks example that the prefix sequence should be repeated for each line. ([#1690](https://github.com/matrix-org/matrix-spec/issues/1690))
- Clarify the format of account data objects for secret storage. ([#1695](https://github.com/matrix-org/matrix-spec/issues/1695), [#1734](https://github.com/matrix-org/matrix-spec/issues/1734))
- Clarify that the key backup MAC is implemented incorrectly and does not pass the ciphertext through HMAC-SHA-256. ([#1712](https://github.com/matrix-org/matrix-spec/issues/1712))
- Clarify one-time key and fallback key types in examples. ([#1715](https://github.com/matrix-org/matrix-spec/issues/1715))
- Clarify that the HKDF calculation for SAS uses base64-encoded keys rather than the raw key bytes. ([#1719](https://github.com/matrix-org/matrix-spec/issues/1719))
- Clarify how to perform the ECDH exchange in step 12 of the SAS process. ([#1720](https://github.com/matrix-org/matrix-spec/issues/1720))
- Document the deprecation policy of HTML tags, as per [MSC4077](https://github.com/matrix-org/matrix-spec-proposals/pull/4077). ([#1732](https://github.com/matrix-org/matrix-spec/issues/1732))
- The [font](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/font) element is deprecated in the HTML spec. Clients should prefer [span](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span) with the `data-mx-bg-color` and `data-mx-color` attributes instead. ([#1739](https://github.com/matrix-org/matrix-spec/issues/1739))
- Disambiguate uses of `PublicRoomsChunk` in the `GET /hierarchy` endpoint. ([#1740](https://github.com/matrix-org/matrix-spec/issues/1740))
- Clarify that `sdpMid` and `sdpMLineIndex` are not required in `m.call.candidates`. ([#1742](https://github.com/matrix-org/matrix-spec/issues/1742))
- Fix various typos throughout the specification. ([#1748](https://github.com/matrix-org/matrix-spec/issues/1748))
- Clearly indicate that each `Content-Type` may have distinct behaviour on non-JSON requests/responses. ([#1756](https://github.com/matrix-org/matrix-spec/issues/1756))
- Clarify that the `m.push_rules` account data type cannot be set using the `/account_data` API, as per [MSC4010](https://github.com/matrix-org/matrix-spec-proposals/pull/4010). ([#1763](https://github.com/matrix-org/matrix-spec/issues/1763))
### Server-Server API
**Spec Clarifications**
- Clarify Server-Server API request signing example by using the `POST` HTTP method, as `GET` requests don't have request bodies. ([#1721](https://github.com/matrix-org/matrix-spec/issues/1721))
- Disambiguate uses of `PublicRoomsChunk` in the `GET /hierarchy` endpoint. ([#1740](https://github.com/matrix-org/matrix-spec/issues/1740))
- Clarify that the `children_state`, `room_type` and `allowed_room_ids` properties in the items of the `children` array of the response of the `GET /hierarchy` endpoint are not required. ([#1741](https://github.com/matrix-org/matrix-spec/issues/1741))
### Application Service API
**Spec Clarifications**
- Clarify that the `/login` and `/register` endpoints should fail when using the `m.login.application_service` login type without a valid `as_token`. ([#1744](https://github.com/matrix-org/matrix-spec/issues/1744))
### Identity Service API
No significant changes.
### Push Gateway API
No significant changes.
### Room Versions
**Spec Clarifications**
- For room versions 7 through 11: Clarify that `invite->knock` is not a legal transition. ([#1717](https://github.com/matrix-org/matrix-spec/issues/1717))
### Appendices
No significant changes.
### Internal Changes/Tooling
**Spec Clarifications**
- Update the spec release process. ([#1680](https://github.com/matrix-org/matrix-spec/issues/1680))
- Minor clarifications to the contributing guide. ([#1697](https://github.com/matrix-org/matrix-spec/issues/1697))
- Update Docsy to v0.8.0. ([#1699](https://github.com/matrix-org/matrix-spec/issues/1699), [#1762](https://github.com/matrix-org/matrix-spec/issues/1762))
- Fix npm release script for `@matrix-org/spec`. ([#1713](https://github.com/matrix-org/matrix-spec/issues/1713))
- Add some clarifications around implementation requirements for MSCs. ([#1718](https://github.com/matrix-org/matrix-spec/issues/1718))
- Update HTML templates to include links to object schema definitions. ([#1724](https://github.com/matrix-org/matrix-spec/issues/1724))
- Factor out all the common parameters of the various `/relations` apis. ([#1745](https://github.com/matrix-org/matrix-spec/issues/1745))
- Add support for `$ref` URIs containing fragments in OpenAPI definitions and JSON schemas. ([#1751](https://github.com/matrix-org/matrix-spec/issues/1751), [#1754](https://github.com/matrix-org/matrix-spec/issues/1754))
| name | string | Optional. The name of the key. |
| algorithm | string | **Required.** The encryption algorithm to be used for this key: `m.secret_storage.v1.aes-hmac-sha2`. |
| passphrase | object | See [deriving keys from passphrases](#deriving-keys-from-passphrases) section for a description of this property. |
| iv | string | Optional. The 16-byte initialization vector for the validation check, encoded as base64. |
| mac | string | Optional. The MAC of the result of encrypting 32 bytes of 0, encoded as base64. |
For example, it could look like:
```json
{
"name": "m.default",
"algorithm": "m.secret_storage.v1.aes-hmac-sha2",
"iv": "random+data",
"mac": "mac+of+encrypted+zeros"
}
```
##### Secret storage
##### Secret storage
Encrypted data is stored in the user's account data using the event
Encrypted data is stored in the user's account data using the event
@ -82,7 +146,7 @@ of the data.
| Parameter | Type | Description |
| Parameter | Type | Description |
|-----------|------------------|-------------|
|-----------|------------------|-------------|
| encrypted | {string: object} | **Required.** Map from key ID the encrypted data. The exact format for the encrypted data is dependent on the key algorithm. See the definition of `AesHmacSha2EncryptedData` in the [m.secret_storage.v1.aes-hmac-sha2](#msecret_storagev1aes-hmac-sha2) section. |
| encrypted | {string: object} | **Required.** Map from key ID the encrypted data. The exact format for the encrypted data is dependent on the key algorithm. See the definition of `AesHmacSha2EncryptedData` in the [m.secret_storage.v1.aes-hmac-sha2](#msecret_storagev1aes-hmac-sha2-1) section. |
Example:
Example:
@ -147,58 +211,41 @@ HMAC-SHA-256. The secret is encrypted as follows:
1. Given the secret storage key, generate 64 bytes by performing an
1. Given the secret storage key, generate 64 bytes by performing an
HKDF with SHA-256 as the hash, a salt of 32 bytes of 0, and with the
HKDF with SHA-256 as the hash, a salt of 32 bytes of 0, and with the
secret name as the info. The first 32 bytes are used as the AES key,
secret name as the info. The first 32 bytes are used as the AES key,
and the next 32 bytes are used as the MAC key
and the next 32 bytes are used as the MAC key.
2. Generate 16 random bytes, set bit 63 to 0 (in order to work around
2. Generate 16 random bytes, set bit 63 to 0 (in order to work around
differences in AES-CTR implementations), and use this as the AES
differences in AES-CTR implementations), and use this as the AES
initialization vector. This becomes the `iv` property, encoded using
initialization vector (IV).
base64.
3. Encrypt the data using AES-CTR-256 using the AES key generated
above. This encrypted data, encoded using base64, becomes the
`ciphertext` property.
4. Pass the raw encrypted data (prior to base64 encoding) through
HMAC-SHA-256 using the MAC key generated above. The resulting MAC is
base64-encoded and becomes the `mac` property.
`AesHmacSha2EncryptedData`
3. Encrypt the data using AES-CTR-256 using the AES key and IV generated
above.
| Parameter | Type | Description
4. Pass the raw encrypted data through HMAC-SHA-256 using the MAC key
| name | string | Optional. The name of the key. |
| algorithm | string | **Required.** The encryption algorithm to be used for this key. Currently, only `m.secret_storage.v1.aes-hmac-sha2` is supported. |
| passphrase | object | See [deriving keys from passphrases](#deriving-keys-from-passphrases) section for a description of this property. |
| iv | string | The 16-byte initialization vector, encoded as base64. |
| mac | string | The MAC of the result of encrypting 32 bytes of 0, encoded as base64. |
For example, the `m.secret_storage.key.key_id` for a key using this