├── changelogs ├── client_server │ ├── newsfragments │ │ ├── .gitignore │ │ ├── 2387.new │ │ ├── 2639.clarification │ │ ├── 2592.clarification │ │ ├── 2605.clarification │ │ ├── 2629.clarification │ │ ├── 2594.clarification │ │ ├── 2599.clarification │ │ ├── 2608.clarification │ │ ├── 2653.clarification │ │ ├── 2597.feature │ │ ├── 2634.clarification │ │ ├── 2647.clarification │ │ ├── 2591.clarification │ │ ├── 2669.clarification │ │ └── 2667.clarification │ └── pyproject.toml ├── identity_service │ ├── newsfragments │ │ └── .gitignore │ └── pyproject.toml ├── push_gateway │ ├── newsfragments │ │ └── .gitignore │ └── pyproject.toml ├── server_server │ ├── newsfragments │ │ └── .gitignore │ └── pyproject.toml ├── application_service │ ├── newsfragments │ │ └── .gitignore │ └── pyproject.toml ├── push_gateway.rst └── application_service.rst ├── api ├── client-server │ ├── definitions │ │ ├── event-schemas │ │ ├── security.yaml │ │ ├── event_batch.yaml │ │ ├── errors │ │ │ ├── error.yaml │ │ │ └── rate_limited.yaml │ │ ├── user_identifier.yaml │ │ ├── wellknown │ │ │ ├── homeserver.yaml │ │ │ ├── identity_server.yaml │ │ │ └── full.yaml │ │ ├── room_event_batch.yaml │ │ ├── state_event_batch.yaml │ │ ├── timeline_batch.yaml │ │ ├── auth_data.yaml │ │ ├── room_key_backup.yaml │ │ ├── push_ruleset.yaml │ │ ├── openid_token.yaml │ │ ├── client_device.yaml │ │ ├── request_email_validation.yaml │ │ ├── request_msisdn_validation.yaml │ │ ├── third_party_signed.yaml │ │ ├── request_token_response.yaml │ │ ├── push_rule.yaml │ │ └── key_backup_data.yaml │ └── sso_login_redirect.yaml ├── server-server │ ├── examples │ │ ├── edu.json │ │ ├── unsigned_pdu.json │ │ ├── transaction.json │ │ ├── minimal_pdu.json │ │ ├── pdu_v4.json │ │ ├── server_key_notary_signed.json │ │ ├── pdu.json │ │ ├── pdu_v3.json │ │ ├── server_key.json │ │ └── unsigned_pdu_base.json │ └── definitions │ │ ├── security.yaml │ │ ├── keys_query_response.yaml │ │ ├── edu.yaml │ │ ├── unsigned_pdu.yaml │ │ ├── single_pdu_transaction.yaml │ │ ├── unlimited_pdu_transaction.yaml │ │ └── event-schemas │ │ └── m.typing.yaml ├── README ├── package.json ├── files │ ├── jquery.slideto.min.js │ ├── jquery.wiggle.min.js │ ├── css │ └── reset.css ├── application-service │ └── definitions │ │ ├── user_batch.yaml │ │ ├── location_batch.yaml │ │ ├── security.yaml │ │ ├── location.yaml │ │ └── user.yaml └── identity │ ├── definitions │ ├── security.yaml │ └── sid.yaml │ ├── ping.yaml │ └── v2_ping.yaml ├── .github ├── FUNDING.yml └── PULL_REQUEST_TEMPLATE │ ├── spec-change.md │ ├── ready-proposal.md │ └── wip-proposal.md ├── event-schemas ├── examples │ ├── m.dummy │ ├── core │ │ ├── state_event.json │ │ ├── room_edu.json │ │ ├── event.json │ │ └── room_event.json │ ├── m.identity_server │ ├── m.call.hangup │ ├── m.room.name │ ├── m.room.topic │ ├── m.tag │ ├── m.typing │ ├── m.room.join_rules │ ├── m.room.guest_access │ ├── m.room.redaction │ ├── m.fully_read │ ├── m.room.pinned_events │ ├── m.room.history_visibility │ ├── m.ignored_user_list │ ├── m.room.message.feedback │ ├── m.direct │ ├── m.room_key_request$cancel_request │ ├── m.key.verification.start │ ├── m.room.tombstone │ ├── m.key.verification.cancel │ ├── m.room.server_acl │ ├── m.key.verification.key │ ├── m.accepted_terms │ ├── m.room.encryption │ ├── m.receipt │ ├── m.policy.rule.room │ ├── m.policy.rule.server │ ├── m.policy.rule.user │ ├── m.room.member │ ├── m.room.canonical_alias │ ├── m.key.verification.request │ ├── m.room.message$m.emote │ ├── m.room.message$m.notice │ ├── m.room.message$m.text │ ├── m.call.invite │ ├── m.call.answer │ ├── m.room.avatar │ ├── m.presence │ ├── m.room_key │ ├── m.room.member$invite_room_state │ ├── m.room.create │ ├── m.room.message$m.image │ ├── m.room.message$m.audio │ ├── m.call.candidates │ ├── m.room.message$m.file │ ├── m.room.message$m.server_notice │ ├── m.room.encrypted$megolm │ ├── m.key.verification.mac │ ├── m.room.third_party_invite │ ├── invite_room_state.json │ ├── m.room.encrypted$olm │ ├── m.key.verification.start$m.sas.v1 │ ├── m.room_key_request$request │ ├── m.room.message$m.location │ ├── m.key.verification.accept │ ├── m.room.power_levels │ ├── m.sticker │ ├── m.forwarded_room_key │ ├── m.room.member$third_party_invite │ └── m.room.message$m.video ├── README.md ├── schema │ ├── core-event-schema │ │ ├── state_event.yaml │ │ ├── room_event.yaml │ │ ├── event.yaml │ │ ├── msgtype_infos │ │ │ ├── thumbnail_info.yaml │ │ │ └── image_info.yaml │ │ ├── unsigned_prop.yaml │ │ ├── sync_state_event.yaml │ │ └── sync_room_event.yaml │ ├── m.policy.rule.user │ ├── m.policy.rule.server │ ├── m.policy.rule.room │ ├── m.push_rules │ ├── m.direct │ ├── m.accepted_terms │ ├── m.room.avatar │ ├── m.room.topic │ ├── m.identity_server │ ├── m.room.history_visibility │ ├── m.room.tombstone │ ├── m.ignored_user_list │ ├── m.room.guest_access │ ├── m.key.verification.key │ ├── m.dummy │ ├── m.room.message │ ├── m.typing │ ├── m.room.message$m.text │ ├── m.room.redaction │ ├── m.room.join_rules │ ├── m.room_key │ ├── m.tag │ ├── m.fully_read │ ├── m.room.pinned_events │ ├── m.sticker │ ├── m.room.message.feedback │ ├── m.room.encryption │ ├── m.room.name │ ├── m.room.message$m.emote │ ├── m.room.message$m.server_notice │ ├── m.room.canonical_alias │ ├── m.key.verification.mac │ ├── m.room.message$m.image │ ├── m.room.message$m.notice │ ├── m.key.verification.request │ ├── m.room.create │ ├── m.key.verification.start │ ├── m.call.hangup │ ├── m.room.message$m.location │ ├── m.room.message$m.audio │ ├── stripped_state.yaml │ └── m.call.answer └── moderation_policy_rule.yaml ├── scripts ├── css │ ├── blockquote.css │ ├── tables.css │ └── codehighlight.css ├── templating │ ├── matrix_templates │ │ ├── templates │ │ │ ├── apis.tmpl │ │ │ ├── common-event-fields.tmpl │ │ │ ├── msgtypes.tmpl │ │ │ ├── schema-definition.tmpl │ │ │ └── events.tmpl │ │ └── __init__.py │ └── batesian │ │ └── __init__.py ├── contrib │ └── shell.nix ├── continuserv │ ├── README.md │ └── index.html ├── requirements.txt ├── generate-matrix-org-assets ├── speculator │ └── README └── test-and-build.sh ├── proposals ├── 1501-split-dag.png ├── images │ ├── state-res.png │ ├── 1756-graph1.dot.png │ ├── 1756-graph2.dot.png │ ├── 2010-spoiler-example.gif │ ├── 2244-redaction-spam.png │ ├── state-res-rejected.png │ ├── 1756-graph1.dot │ ├── 1756-graph2.dot │ └── state-res-rejected.dot ├── 1759-rooms-v2.md ├── 1866-invite-unsupported-version-error-code.md ├── 2526-add-delete-backup.md ├── 2077-rooms-v5.md ├── 2175-remove-creator-field.md ├── 2240-rooms-v6.md ├── 1812-federation-make-membership.md ├── 2174-move-redacts-key.md ├── 2334-default-room-version-v5.md ├── 1831-srv-after-wellknown.md ├── 1721-rename-cas-to-sso.md ├── 2284-optional-identity-server-discovery.md ├── 1930-tombstone-notifications.md ├── 2604-login-fallback-device-info.md ├── 1802-standardised-federation-response-format.md └── 1983-leave-reasons.md ├── specification ├── proposals.rst ├── appendices.rst ├── modules │ ├── third_party_networks.rst │ ├── admin.rst │ ├── openid.rst │ ├── event_context.rst │ ├── report_content.rst │ ├── device_management.rst │ └── account_data.rst └── modules.rst ├── .gitignore ├── pyproject.toml ├── .buildkite └── pipeline.yaml ├── schemas └── server-signatures.yaml └── drafts ├── ancient_federated_versioning_design_notes.rst ├── object_model.rst └── model └── protocol_examples.rst /changelogs/client_server/newsfragments/.gitignore: -------------------------------------------------------------------------------- 1 | !.gitignore -------------------------------------------------------------------------------- /changelogs/identity_service/newsfragments/.gitignore: -------------------------------------------------------------------------------- 1 | !.gitignore -------------------------------------------------------------------------------- /changelogs/push_gateway/newsfragments/.gitignore: -------------------------------------------------------------------------------- 1 | !.gitignore -------------------------------------------------------------------------------- /changelogs/server_server/newsfragments/.gitignore: -------------------------------------------------------------------------------- 1 | !.gitignore -------------------------------------------------------------------------------- /api/client-server/definitions/event-schemas: -------------------------------------------------------------------------------- 1 | ../../../event-schemas -------------------------------------------------------------------------------- /changelogs/application_service/newsfragments/.gitignore: -------------------------------------------------------------------------------- 1 | !.gitignore -------------------------------------------------------------------------------- /.github/FUNDING.yml: -------------------------------------------------------------------------------- 1 | patreon: matrixdotorg 2 | liberapay: matrixdotorg 3 | -------------------------------------------------------------------------------- /event-schemas/examples/m.dummy: -------------------------------------------------------------------------------- 1 | { 2 | "content": {}, 3 | "type": "m.dummy" 4 | } 5 | -------------------------------------------------------------------------------- /changelogs/client_server/newsfragments/2387.new: -------------------------------------------------------------------------------- 1 | Add key backup (``/room_keys/*``) endpoints. 2 | -------------------------------------------------------------------------------- /changelogs/client_server/newsfragments/2639.clarification: -------------------------------------------------------------------------------- 1 | Fixed some errors in the key backup spec. -------------------------------------------------------------------------------- /changelogs/client_server/newsfragments/2592.clarification: -------------------------------------------------------------------------------- 1 | Fix definitions for room version capabilities. 2 | -------------------------------------------------------------------------------- /changelogs/client_server/newsfragments/2605.clarification: -------------------------------------------------------------------------------- 1 | Clarify link to OpenID Connect specification. 2 | -------------------------------------------------------------------------------- /changelogs/client_server/newsfragments/2629.clarification: -------------------------------------------------------------------------------- 1 | Remove ``room_id`` from ``/sync`` examples. 2 | -------------------------------------------------------------------------------- /scripts/css/blockquote.css: -------------------------------------------------------------------------------- 1 | blockquote { 2 | margin: 20px 0 30px; 3 | padding-left: 20px; 4 | } 5 | -------------------------------------------------------------------------------- /changelogs/client_server/newsfragments/2594.clarification: -------------------------------------------------------------------------------- 1 | Fix various typos throughout the specification. 2 | -------------------------------------------------------------------------------- /changelogs/client_server/newsfragments/2599.clarification: -------------------------------------------------------------------------------- 1 | Fix various typos throughout the specification. 2 | -------------------------------------------------------------------------------- /changelogs/client_server/newsfragments/2608.clarification: -------------------------------------------------------------------------------- 1 | Clarify the behaviour of SSO login and UI-Auth. 2 | -------------------------------------------------------------------------------- /changelogs/client_server/newsfragments/2653.clarification: -------------------------------------------------------------------------------- 1 | Fix some errors in the end-to-end encryption spec. 2 | -------------------------------------------------------------------------------- /changelogs/client_server/newsfragments/2597.feature: -------------------------------------------------------------------------------- 1 | Document Secure Secret Storage and Sharing (MSC1946/2472). 2 | -------------------------------------------------------------------------------- /changelogs/client_server/newsfragments/2634.clarification: -------------------------------------------------------------------------------- 1 | Minor clarifications to the "Push Notifications" module. 2 | -------------------------------------------------------------------------------- /proposals/1501-split-dag.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/timokoesters/matrix-doc/master/proposals/1501-split-dag.png -------------------------------------------------------------------------------- /changelogs/client_server/newsfragments/2647.clarification: -------------------------------------------------------------------------------- 1 | Improve consistency and clarity of event schema ``title``\ s. 2 | -------------------------------------------------------------------------------- /proposals/images/state-res.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/timokoesters/matrix-doc/master/proposals/images/state-res.png -------------------------------------------------------------------------------- /scripts/css/tables.css: -------------------------------------------------------------------------------- 1 | /* Column with header cells */ 2 | table.docutils tbody th.stub { 3 | background: #eeeeee; 4 | } 5 | -------------------------------------------------------------------------------- /event-schemas/examples/core/state_event.json: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "room_event.json", 3 | "state_key": "ArbitraryString" 4 | } 5 | -------------------------------------------------------------------------------- /proposals/images/1756-graph1.dot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/timokoesters/matrix-doc/master/proposals/images/1756-graph1.dot.png -------------------------------------------------------------------------------- /proposals/images/1756-graph2.dot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/timokoesters/matrix-doc/master/proposals/images/1756-graph2.dot.png -------------------------------------------------------------------------------- /api/server-server/examples/edu.json: -------------------------------------------------------------------------------- 1 | { 2 | "edu_type": "m.presence", 3 | "content": { 4 | "key": "value" 5 | } 6 | } -------------------------------------------------------------------------------- /changelogs/client_server/newsfragments/2591.clarification: -------------------------------------------------------------------------------- 1 | Fix issues with ``age`` and ``unsigned`` being shown in the wrong places. 2 | -------------------------------------------------------------------------------- /changelogs/client_server/newsfragments/2669.clarification: -------------------------------------------------------------------------------- 1 | Fix types of push rules' actions; they can be objects as well as strings. 2 | -------------------------------------------------------------------------------- /event-schemas/examples/core/room_edu.json: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "event.json", 3 | "room_id": "!jEsUZKDJdhlrceRyVU:example.org" 4 | } 5 | -------------------------------------------------------------------------------- /changelogs/client_server/newsfragments/2667.clarification: -------------------------------------------------------------------------------- 1 | Reword "UI Authorization" to "User-Interactive Authentication" to be more clear. 2 | -------------------------------------------------------------------------------- /proposals/images/2010-spoiler-example.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/timokoesters/matrix-doc/master/proposals/images/2010-spoiler-example.gif -------------------------------------------------------------------------------- /proposals/images/2244-redaction-spam.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/timokoesters/matrix-doc/master/proposals/images/2244-redaction-spam.png -------------------------------------------------------------------------------- /proposals/images/state-res-rejected.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/timokoesters/matrix-doc/master/proposals/images/state-res-rejected.png -------------------------------------------------------------------------------- /event-schemas/examples/core/event.json: -------------------------------------------------------------------------------- 1 | { 2 | "content": { 3 | "key": "value" 4 | }, 5 | "type": "org.example.custom.event" 6 | } 7 | -------------------------------------------------------------------------------- /api/README: -------------------------------------------------------------------------------- 1 | This directory contains swagger-compatible representations of our APIs. See 2 | the main README.rst for details on how to make use of them. 3 | -------------------------------------------------------------------------------- /api/server-server/examples/unsigned_pdu.json: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "unsigned_pdu_base.json", 3 | "event_id": "$a4ecee13e2accdadf56c1025:example.com" 4 | } 5 | -------------------------------------------------------------------------------- /scripts/templating/matrix_templates/templates/apis.tmpl: -------------------------------------------------------------------------------- 1 | {% import 'tables.tmpl' as tables -%} 2 | 3 | {{ tables.paramtable(apis.rows, ["API", "Version", "Description"]) }} 4 | 5 | -------------------------------------------------------------------------------- /scripts/contrib/shell.nix: -------------------------------------------------------------------------------- 1 | with import {}; 2 | 3 | (python.buildEnv.override { 4 | extraLibs = with pythonPackages; 5 | [ docutils pyyaml jinja2 pygments ]; 6 | }).env 7 | -------------------------------------------------------------------------------- /event-schemas/README.md: -------------------------------------------------------------------------------- 1 | Checking the event schemas 2 | ========================== 3 | 4 | To validate the event schemas, and check the example events, run 5 | 6 | ./check-examples.py 7 | -------------------------------------------------------------------------------- /event-schemas/examples/m.identity_server: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/event.json", 3 | "type": "m.identity_server", 4 | "content": { 5 | "base_url": "https://example.org" 6 | } 7 | } 8 | -------------------------------------------------------------------------------- /api/server-server/examples/transaction.json: -------------------------------------------------------------------------------- 1 | { 2 | "origin": "matrix.org", 3 | "origin_server_ts": 1234567890, 4 | "pdus": [{ 5 | "$ref": "minimal_pdu.json" 6 | }] 7 | } 8 | -------------------------------------------------------------------------------- /event-schemas/examples/m.call.hangup: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/room_event.json", 3 | "type": "m.call.hangup", 4 | "content": { 5 | "version" : 0, 6 | "call_id": "12345" 7 | } 8 | } 9 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.name: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/state_event.json", 3 | "type": "m.room.name", 4 | "state_key": "", 5 | "content": { 6 | "name": "The room name" 7 | } 8 | } 9 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.topic: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/state_event.json", 3 | "type": "m.room.topic", 4 | "state_key": "", 5 | "content": { 6 | "topic": "A room topic" 7 | } 8 | } 9 | -------------------------------------------------------------------------------- /event-schemas/examples/m.tag: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/event.json", 3 | "type": "m.tag", 4 | "content": { 5 | "tags": { 6 | "u.work": {"order": 0.9} 7 | } 8 | } 9 | } 10 | -------------------------------------------------------------------------------- /event-schemas/examples/m.typing: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/room_edu.json", 3 | "type": "m.typing", 4 | "content": { 5 | "user_ids": ["@alice:matrix.org", "@bob:example.com"] 6 | } 7 | } 8 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.join_rules: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/state_event.json", 3 | "type": "m.room.join_rules", 4 | "state_key": "", 5 | "content": { 6 | "join_rule": "public" 7 | } 8 | } 9 | -------------------------------------------------------------------------------- /scripts/continuserv/README.md: -------------------------------------------------------------------------------- 1 | continuserv proactively re-generates the spec on filesystem changes, and serves 2 | it over HTTP. For notes on using it, see [the main 3 | readme](../../README.rst#continuserv). 4 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.guest_access: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/state_event.json", 3 | "type": "m.room.guest_access", 4 | "state_key": "", 5 | "content": { 6 | "guest_access": "can_join" 7 | } 8 | } 9 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.redaction: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/room_event.json", 3 | "type": "m.room.redaction", 4 | "redacts": "$fukweghifu23:localhost", 5 | "content": { 6 | "reason": "Spamming" 7 | } 8 | } 9 | -------------------------------------------------------------------------------- /event-schemas/examples/m.fully_read: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/event.json", 3 | "type": "m.fully_read", 4 | "room_id": "!somewhere:example.org", 5 | "content": { 6 | "event_id": "$someplace:example.org" 7 | } 8 | } 9 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.pinned_events: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/state_event.json", 3 | "type": "m.room.pinned_events", 4 | "state_key": "", 5 | "content": { 6 | "pinned": ["$someevent:example.org"] 7 | } 8 | } 9 | -------------------------------------------------------------------------------- /event-schemas/schema/core-event-schema/state_event.yaml: -------------------------------------------------------------------------------- 1 | allOf: 2 | - $ref: room_event.yaml 3 | - $ref: sync_state_event.yaml 4 | description: State Events have the following fields. 5 | title: StateEvent 6 | type: object 7 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.history_visibility: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/state_event.json", 3 | "type": "m.room.history_visibility", 4 | "state_key": "", 5 | "content": { 6 | "history_visibility": "shared" 7 | } 8 | } 9 | -------------------------------------------------------------------------------- /event-schemas/examples/m.ignored_user_list: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/event.json", 3 | "type": "m.ignored_user_list", 4 | "content": { 5 | "ignored_users": { 6 | "@someone:example.org": {} 7 | } 8 | } 9 | } 10 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.message.feedback: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/room_event.json", 3 | "type": "m.room.message.feedback", 4 | "content": { 5 | "type": "delivered", 6 | "target_event_id": "$WEIGFHFW:localhost" 7 | } 8 | } 9 | -------------------------------------------------------------------------------- /event-schemas/examples/m.direct: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/event.json", 3 | "type": "m.direct", 4 | "content": { 5 | "@bob:example.com": [ 6 | "!abcdefgh:example.com", 7 | "!hgfedcba:example.com" 8 | ] 9 | } 10 | } 11 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room_key_request$cancel_request: -------------------------------------------------------------------------------- 1 | { 2 | "content": { 3 | "action": "request_cancellation", 4 | "requesting_device_id": "RJYKSTBOIE", 5 | "request_id": "1495474790150.19" 6 | }, 7 | "type": "m.room_key_request" 8 | } 9 | -------------------------------------------------------------------------------- /api/server-server/examples/minimal_pdu.json: -------------------------------------------------------------------------------- 1 | { 2 | "type": "m.room.minimal_pdu", 3 | "room_id": "!somewhere:example.org", 4 | "content": { 5 | "see_room_version_spec": "The event format changes depending on the room version." 6 | } 7 | } 8 | -------------------------------------------------------------------------------- /event-schemas/examples/m.key.verification.start: -------------------------------------------------------------------------------- 1 | { 2 | "type": "m.key.verification.start", 3 | "content": { 4 | "from_device": "BobDevice1", 5 | "transaction_id": "S0meUniqueAndOpaqueString", 6 | "method": "m.sas.v1" 7 | } 8 | } 9 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.tombstone: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/state_event.json", 3 | "type": "m.room.tombstone", 4 | "state_key": "", 5 | "content": { 6 | "body": "This room has been replaced", 7 | "replacement_room": "!newroom:example.org" 8 | } 9 | } 10 | -------------------------------------------------------------------------------- /event-schemas/examples/m.key.verification.cancel: -------------------------------------------------------------------------------- 1 | { 2 | "type": "m.key.verification.cancel", 3 | "content": { 4 | "transaction_id": "S0meUniqueAndOpaqueString", 5 | "code": "m.user", 6 | "reason": "User rejected the key verification request" 7 | } 8 | } 9 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.server_acl: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/state_event.json", 3 | "type": "m.room.server_acl", 4 | "state_key": "", 5 | "content": { 6 | "allow_ip_literals": false, 7 | "allow": ["*"], 8 | "deny": ["*.evil.com", "evil.com"] 9 | } 10 | } 11 | -------------------------------------------------------------------------------- /event-schemas/examples/m.key.verification.key: -------------------------------------------------------------------------------- 1 | { 2 | "type": "m.key.verification.key", 3 | "content": { 4 | "transaction_id": "S0meUniqueAndOpaqueString", 5 | "key": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" 6 | } 7 | } 8 | -------------------------------------------------------------------------------- /specification/proposals.rst: -------------------------------------------------------------------------------- 1 | Tables of Tracked Proposals 2 | --------------------------- 3 | 4 | This file is generated by an automated process on our build server. 5 | 6 | View the current live version `at https://matrix.org/docs/spec/proposals `_. 7 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | /api/node_modules 2 | /assets 3 | /assets.tar.gz 4 | /env* 5 | /scripts/gen 6 | /scripts/continuserv/continuserv 7 | /scripts/speculator/speculator 8 | /scripts/swagger 9 | /scripts/tmp 10 | /templating/out 11 | *.pyc 12 | *.swp 13 | _rendered.rst 14 | /.vscode/ 15 | /.idea/ 16 | -------------------------------------------------------------------------------- /event-schemas/examples/m.accepted_terms: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/event.json", 3 | "type": "m.accepted_terms", 4 | "content": { 5 | "accepted": [ 6 | "https://example.org/somewhere/terms-1.2-en.html", 7 | "https://example.org/somewhere/privacy-1.2-en.html" 8 | ] 9 | } 10 | } 11 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.encryption: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/state_event.json", 3 | "type": "m.room.encryption", 4 | "state_key": "", 5 | "content": { 6 | "algorithm": "m.megolm.v1.aes-sha2", 7 | "rotation_period_ms": 604800000, 8 | "rotation_period_msgs": 100 9 | } 10 | } 11 | -------------------------------------------------------------------------------- /proposals/images/1756-graph1.dot: -------------------------------------------------------------------------------- 1 | graph { 2 | A1 [label="A's PDP-11"] 3 | AV [label="A's virtual device"] 4 | A2 [label="A's Osborne 2"] 5 | B1 [label="B's Dynabook"] 6 | BV [label="B's virtual device"] 7 | B2 [label="B's VAX"] 8 | A1 -- AV 9 | AV -- A2 10 | A2 -- B1 11 | B1 -- BV 12 | BV -- B2 13 | } -------------------------------------------------------------------------------- /event-schemas/examples/m.receipt: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/room_edu.json", 3 | "type": "m.receipt", 4 | "content": { 5 | "$1435641916114394fHBLK:matrix.org": { 6 | "m.read": { 7 | "@rikj:jki.re": { 8 | "ts": 1436451550453 9 | } 10 | } 11 | } 12 | } 13 | } 14 | -------------------------------------------------------------------------------- /event-schemas/examples/m.policy.rule.room: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/state_event.json", 3 | "type": "m.policy.rule.room", 4 | "state_key": "rule:#*:example.org", 5 | "content": { 6 | "entity": "#*:example.org", 7 | "recommendation": "m.ban", 8 | "reason": "undesirable content" 9 | } 10 | } 11 | -------------------------------------------------------------------------------- /event-schemas/examples/m.policy.rule.server: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/state_event.json", 3 | "type": "m.policy.rule.server", 4 | "state_key": "rule:*.example.org", 5 | "content": { 6 | "entity": "*.example.org", 7 | "recommendation": "m.ban", 8 | "reason": "undesirable engagement" 9 | } 10 | } 11 | -------------------------------------------------------------------------------- /event-schemas/examples/m.policy.rule.user: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/state_event.json", 3 | "type": "m.policy.rule.user", 4 | "state_key": "rule:@alice*:example.org", 5 | "content": { 6 | "entity": "@alice*:example.org", 7 | "recommendation": "m.ban", 8 | "reason": "undesirable behaviour" 9 | } 10 | } 11 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.member: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/state_event.json", 3 | "state_key": "@alice:example.org", 4 | "type": "m.room.member", 5 | "content": { 6 | "membership": "join", 7 | "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF", 8 | "displayname": "Alice Margatroid" 9 | } 10 | } 11 | -------------------------------------------------------------------------------- /event-schemas/examples/core/room_event.json: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "event.json", 3 | "event_id": "$143273582443PhrSn:example.org", 4 | "room_id": "!jEsUZKDJdhlrceRyVU:example.org", 5 | "sender": "@example:example.org", 6 | "origin_server_ts": 1432735824653, 7 | "unsigned": { 8 | "age": 1234 9 | } 10 | } 11 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.canonical_alias: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/state_event.json", 3 | "type": "m.room.canonical_alias", 4 | "state_key": "", 5 | "content": { 6 | "alias": "#somewhere:localhost", 7 | "alt_aliases": [ 8 | "#somewhere:example.org", 9 | "#myroom:example.com" 10 | ] 11 | } 12 | } 13 | -------------------------------------------------------------------------------- /pyproject.toml: -------------------------------------------------------------------------------- 1 | [ tool.gilesbot ] 2 | 3 | [ tool.gilesbot.circleci_artifacts.docs ] 4 | url = "gen/index.html" 5 | message = "Click details to preview the HTML documentation." 6 | 7 | [ tool.gilesbot.circleci_artifacts.swagger ] 8 | url = "client-server/index.html" 9 | message = "Click to preview the swagger build." 10 | -------------------------------------------------------------------------------- /event-schemas/examples/m.key.verification.request: -------------------------------------------------------------------------------- 1 | { 2 | "type": "m.key.verification.request", 3 | "content": { 4 | "from_device": "AliceDevice2", 5 | "transaction_id": "S0meUniqueAndOpaqueString", 6 | "methods": [ 7 | "m.sas.v1" 8 | ], 9 | "timestamp": 1559598944869 10 | } 11 | } 12 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.message$m.emote: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/room_event.json", 3 | "type": "m.room.message", 4 | "content": { 5 | "body": "thinks this is an example emote", 6 | "msgtype": "m.emote", 7 | "format": "org.matrix.custom.html", 8 | "formatted_body": "thinks this is an example emote" 9 | } 10 | } 11 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.message$m.notice: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/room_event.json", 3 | "type": "m.room.message", 4 | "content": { 5 | "body": "This is an example notice", 6 | "msgtype": "m.notice", 7 | "format": "org.matrix.custom.html", 8 | "formatted_body": "This is an example notice" 9 | } 10 | } 11 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.message$m.text: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/room_event.json", 3 | "type": "m.room.message", 4 | "content": { 5 | "body": "This is an example text message", 6 | "msgtype": "m.text", 7 | "format": "org.matrix.custom.html", 8 | "formatted_body": "This is an example text message" 9 | } 10 | } 11 | -------------------------------------------------------------------------------- /event-schemas/examples/m.call.invite: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/room_event.json", 3 | "type": "m.call.invite", 4 | "content": { 5 | "version" : 0, 6 | "call_id": "12345", 7 | "lifetime": 60000, 8 | "offer": { 9 | "type" : "offer", 10 | "sdp" : "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]" 11 | } 12 | } 13 | } 14 | -------------------------------------------------------------------------------- /api/server-server/examples/pdu_v4.json: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "pdu_v3.json", 3 | "auth_events": [ 4 | "$urlsafe_base64_encoded_eventid", 5 | "$a-different-event-id" 6 | ], 7 | "prev_events": [ 8 | "$urlsafe_base64_encoded_eventid", 9 | "$a-different-event-id" 10 | ], 11 | "redacts": "$some-old_event" 12 | } 13 | -------------------------------------------------------------------------------- /event-schemas/examples/m.call.answer: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/room_event.json", 3 | "type": "m.call.answer", 4 | "content": { 5 | "version" : 0, 6 | "call_id": "12345", 7 | "lifetime": 60000, 8 | "answer": { 9 | "type" : "answer", 10 | "sdp" : "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]" 11 | } 12 | } 13 | } 14 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.avatar: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/state_event.json", 3 | "type": "m.room.avatar", 4 | "state_key": "", 5 | "content": { 6 | "info": { 7 | "h": 398, 8 | "w": 394, 9 | "mimetype": "image/jpeg", 10 | "size": 31037 11 | }, 12 | "url": "mxc://example.org/JWEIFJgwEIhweiWJE" 13 | } 14 | } 15 | -------------------------------------------------------------------------------- /event-schemas/examples/m.presence: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/event.json", 3 | "sender": "@example:localhost", 4 | "type": "m.presence", 5 | "content": { 6 | "avatar_url": "mxc://localhost:wefuiwegh8742w", 7 | "last_active_ago": 2478593, 8 | "presence": "online", 9 | "currently_active": false, 10 | "status_msg": "Making cupcakes" 11 | } 12 | } 13 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room_key: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/event.json", 3 | "type": "m.room_key", 4 | "content": { 5 | "algorithm": "m.megolm.v1.aes-sha2", 6 | "room_id": "!Cuyf34gef24t:localhost", 7 | "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ", 8 | "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8LlfJL7qNBEY..." 9 | } 10 | } 11 | -------------------------------------------------------------------------------- /api/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "swagger-cli-validator", 3 | "version": "0.0.1", 4 | "description": "", 5 | "main": "validator.js", 6 | "scripts": { 7 | "test": "echo \"Error: no test specified\" && exit 1" 8 | }, 9 | "author": "", 10 | "license": "ISC", 11 | "dependencies": { 12 | "nopt": "^3.0.2", 13 | "swagger-parser": "^3.2.1" 14 | } 15 | } 16 | -------------------------------------------------------------------------------- /api/server-server/examples/server_key_notary_signed.json: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "server_key.json", 3 | "signatures": { 4 | "example.org": { 5 | "ed25519:abc123": "VGhpcyBzaG91bGQgYWN0dWFsbHkgYmUgYSBzaWduYXR1cmU" 6 | }, 7 | "notary.server.com": { 8 | "ed25519:010203": "VGhpcyBpcyBhbm90aGVyIHNpZ25hdHVyZQ" 9 | } 10 | } 11 | } -------------------------------------------------------------------------------- /api/server-server/examples/pdu.json: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "unsigned_pdu.json", 3 | "hashes": { 4 | "sha256": "thishashcoversallfieldsincasethisisredacted" 5 | }, 6 | "signatures": { 7 | "example.com": { 8 | "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus" 9 | } 10 | } 11 | } -------------------------------------------------------------------------------- /api/files/jquery.slideto.min.js: -------------------------------------------------------------------------------- 1 | (function(b){b.fn.slideto=function(a){a=b.extend({slide_duration:"slow",highlight_duration:3E3,highlight:true,highlight_color:"#FFFF99"},a);return this.each(function(){obj=b(this);b("body").animate({scrollTop:obj.offset().top},a.slide_duration,function(){a.highlight&&b.ui.version&&obj.effect("highlight",{color:a.highlight_color},a.highlight_duration)})})}})(jQuery); 2 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.member$invite_room_state: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "m.room.member", 3 | "content": { 4 | "membership": "invite", 5 | "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF", 6 | "displayname": "Alice Margatroid" 7 | }, 8 | "unsigned": { 9 | "age": 1234, 10 | "invite_room_state": { 11 | "$ref": "invite_room_state.json" 12 | } 13 | } 14 | } 15 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.create: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/state_event.json", 3 | "type": "m.room.create", 4 | "state_key": "", 5 | "content": { 6 | "creator": "@example:example.org", 7 | "room_version": "1", 8 | "m.federate": true, 9 | "predecessor": { 10 | "event_id": "$something:example.org", 11 | "room_id": "!oldroom:example.org" 12 | } 13 | } 14 | } 15 | -------------------------------------------------------------------------------- /scripts/templating/matrix_templates/templates/common-event-fields.tmpl: -------------------------------------------------------------------------------- 1 | {% import 'tables.tmpl' as tables -%} 2 | 3 | {{common_event.title}} Fields 4 | {{(7 + common_event.title | length) * title_kind}} 5 | 6 | {{common_event.desc}} 7 | 8 | {% for table in common_event.tables %} 9 | 10 | {{ tables.paramtable(table.rows, ["Key", "Type", "Description"], (table.title or "")) }} 11 | 12 | {% endfor %} 13 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.message$m.image: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/room_event.json", 3 | "type": "m.room.message", 4 | "content": { 5 | "body": "filename.jpg", 6 | "info": { 7 | "h": 398, 8 | "w": 394, 9 | "mimetype": "image/jpeg", 10 | "size": 31037 11 | }, 12 | "url": "mxc://example.org/JWEIFJgwEIhweiWJE", 13 | "msgtype": "m.image" 14 | } 15 | } 16 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.message$m.audio: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/room_event.json", 3 | "type": "m.room.message", 4 | "content": { 5 | "body": "Bee Gees - Stayin' Alive", 6 | "url": "mxc://example.org/ffed755USFFxlgbQYZGtryd", 7 | "info": { 8 | "duration": 2140786, 9 | "size": 1563685, 10 | "mimetype": "audio/mpeg" 11 | }, 12 | "msgtype": "m.audio" 13 | } 14 | } 15 | -------------------------------------------------------------------------------- /scripts/requirements.txt: -------------------------------------------------------------------------------- 1 | # no doubt older versions would be fine for many of these but these were 2 | # current at the time of writing 3 | 4 | docutils >= 0.14 5 | pygments >= 2.2.0 6 | Jinja2 >= 2.9.6 7 | 8 | # jsonschema 3.0.0 objects to the $refs in our schema file. TODO: figure out 9 | # why. 10 | jsonschema >= 2.6.0, < 3.0.0 11 | 12 | PyYAML >= 3.12 13 | requests >= 2.18.4 14 | towncrier == 18.6.0 15 | six >= 1.11.0 16 | -------------------------------------------------------------------------------- /event-schemas/examples/m.call.candidates: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/room_event.json", 3 | "type": "m.call.candidates", 4 | "content": { 5 | "version" : 0, 6 | "call_id": "12345", 7 | "candidates": [ 8 | { 9 | "sdpMid": "audio", 10 | "sdpMLineIndex": 0, 11 | "candidate": "candidate:863018703 1 udp 2122260223 10.9.64.156 43670 typ host generation 0" 12 | } 13 | ] 14 | } 15 | } 16 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.message$m.file: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/room_event.json", 3 | "type": "m.room.message", 4 | "content": { 5 | "body": "something-important.doc", 6 | "filename": "something-important.doc", 7 | "info": { 8 | "mimetype": "application/msword", 9 | "size": 46144 10 | }, 11 | "msgtype": "m.file", 12 | "url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe" 13 | } 14 | } 15 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.message$m.server_notice: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/room_event.json", 3 | "type": "m.room.message", 4 | "content": { 5 | "body": "Human-readable message to explain the notice", 6 | "msgtype": "m.server_notice", 7 | "server_notice_type": "m.server_notice.usage_limit_reached", 8 | "admin_contact": "mailto:server.admin@example.org", 9 | "limit_type": "monthly_active_user" 10 | } 11 | } 12 | -------------------------------------------------------------------------------- /changelogs/push_gateway.rst: -------------------------------------------------------------------------------- 1 | r0.1.1 2 | ====== 3 | 4 | Spec Clarifications 5 | ------------------- 6 | 7 | - Fix ``event_id`` field in push request body. (`#2151 `_) 8 | 9 | 10 | r0.1.0 11 | ====== 12 | 13 | The first release of the Push Gateway specification. This release contains 14 | a single endpoint, ``/notify``, that pushers may use to send push notifications 15 | to clients. 16 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.encrypted$megolm: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/room_event.json", 3 | "type": "m.room.encrypted", 4 | "content": { 5 | "algorithm": "m.megolm.v1.aes-sha2", 6 | "ciphertext": "AwgAEnACgAkLmt6qF84IK++J7UDH2Za1YVchHyprqTqsg...", 7 | "device_id": "RJYKSTBOIE", 8 | "sender_key": "IlRMeOPX2e0MurIyfWEucYBRVOEEUMrOHqn/8mLqMjA", 9 | "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ" 10 | } 11 | } 12 | -------------------------------------------------------------------------------- /event-schemas/examples/m.key.verification.mac: -------------------------------------------------------------------------------- 1 | { 2 | "type": "m.key.verification.mac", 3 | "content": { 4 | "transaction_id": "S0meUniqueAndOpaqueString", 5 | "keys": "2Wptgo4CwmLo/Y8B8qinxApKaCkBG2fjTWB7AbP5Uy+aIbygsSdLOFzvdDjww8zUVKCmI02eP9xtyJxc/cLiBA", 6 | "mac": { 7 | "ed25519:ABCDEF": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" 8 | } 9 | } 10 | } 11 | -------------------------------------------------------------------------------- /event-schemas/schema/m.policy.rule.user: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/state_event.yaml 4 | description: A moderation policy rule which affects users. 5 | properties: 6 | content: 7 | $ref: "../moderation_policy_rule.yaml" 8 | state_key: 9 | description: An arbitrary string decided upon by the sender. 10 | type: string 11 | type: 12 | enum: 13 | - m.policy.rule.user 14 | type: string 15 | type: object 16 | -------------------------------------------------------------------------------- /event-schemas/schema/m.policy.rule.server: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/state_event.yaml 4 | description: A moderation policy rule which affects servers. 5 | properties: 6 | content: 7 | $ref: "../moderation_policy_rule.yaml" 8 | state_key: 9 | description: An arbitrary string decided upon by the sender. 10 | type: string 11 | type: 12 | enum: 13 | - m.policy.rule.server 14 | type: string 15 | type: object 16 | -------------------------------------------------------------------------------- /event-schemas/schema/core-event-schema/room_event.yaml: -------------------------------------------------------------------------------- 1 | allOf: 2 | - $ref: sync_room_event.yaml 3 | description: Room Events have the following fields. 4 | properties: 5 | room_id: 6 | description: |- 7 | The ID of the room associated with this event. Will not be present on events 8 | that arrive through ``/sync``, despite being required everywhere else. 9 | type: string 10 | required: 11 | - room_id 12 | title: RoomEvent 13 | type: object 14 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.third_party_invite: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/state_event.json", 3 | "type": "m.room.third_party_invite", 4 | "state_key": "pc98", 5 | "content": { 6 | "display_name": "Alice Margatroid", 7 | "key_validity_url": "https://magic.forest/verifykey", 8 | "public_key": "abc123", 9 | "public_keys": [{ 10 | "public_key": "def456", 11 | "key_validity_url": "https://magic.forest/verifykey" 12 | }] 13 | } 14 | } 15 | -------------------------------------------------------------------------------- /event-schemas/schema/m.policy.rule.room: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/state_event.yaml 4 | description: A moderation policy rule which affects room IDs and room aliases. 5 | properties: 6 | content: 7 | $ref: "../moderation_policy_rule.yaml" 8 | state_key: 9 | description: An arbitrary string decided upon by the sender. 10 | type: string 11 | type: 12 | enum: 13 | - m.policy.rule.room 14 | type: string 15 | type: object 16 | -------------------------------------------------------------------------------- /scripts/continuserv/index.html: -------------------------------------------------------------------------------- 1 | 2 | 10 | 11 | 15 | 16 | -------------------------------------------------------------------------------- /event-schemas/examples/invite_room_state.json: -------------------------------------------------------------------------------- 1 | [ 2 | { 3 | "type": "m.room.name", 4 | "sender": "@bob:example.org", 5 | "state_key": "", 6 | "content": { 7 | "name": "Example Room" 8 | } 9 | }, 10 | { 11 | "type": "m.room.join_rules", 12 | "sender": "@bob:example.org", 13 | "state_key": "", 14 | "content": { 15 | "join_rule": "invite" 16 | } 17 | } 18 | ] 19 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.encrypted$olm: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/room_event.json", 3 | "type": "m.room.encrypted", 4 | "content": { 5 | "algorithm": "m.olm.v1.curve25519-aes-sha2", 6 | "sender_key": "Szl29ksW/L8yZGWAX+8dY1XyFi+i5wm+DRhTGkbMiwU", 7 | "ciphertext": { 8 | "7qZcfnBmbEGzxxaWfBjElJuvn7BZx+lSz/SvFrDF/z8": { 9 | "type": 0, 10 | "body": "AwogGJJzMhf/S3GQFXAOrCZ3iKyGU5ZScVtjI0KypTYrW..." 11 | } 12 | } 13 | } 14 | } 15 | -------------------------------------------------------------------------------- /scripts/templating/matrix_templates/templates/msgtypes.tmpl: -------------------------------------------------------------------------------- 1 | {% import 'tables.tmpl' as tables -%} 2 | 3 | ``{{event.msgtype}}`` 4 | {{(4 + event.msgtype | length) * title_kind}} 5 | {{event.desc | wrap(80)}} 6 | {% for table in event.content_fields -%} 7 | 8 | {{ tables.paramtable(table.rows, [(table.title or "Content") ~ " Key", "Type", "Description"], (table.title or "")) }} 9 | 10 | {% endfor %} 11 | Example: 12 | 13 | .. code:: json 14 | 15 | {{example | jsonify(4, 4)}} 16 | -------------------------------------------------------------------------------- /event-schemas/examples/m.key.verification.start$m.sas.v1: -------------------------------------------------------------------------------- 1 | { 2 | "type": "m.key.verification.start", 3 | "content": { 4 | "from_device": "BobDevice1", 5 | "transaction_id": "S0meUniqueAndOpaqueString", 6 | "method": "m.sas.v1", 7 | "key_agreement_protocols": ["curve25519"], 8 | "hashes": ["sha256"], 9 | "message_authentication_codes": ["hkdf-hmac-sha256"], 10 | "short_authentication_string": ["decimal", "emoji"] 11 | } 12 | } 13 | -------------------------------------------------------------------------------- /.buildkite/pipeline.yaml: -------------------------------------------------------------------------------- 1 | steps: 2 | - label: ":books: Build spec" 3 | command: 4 | - python3 -m venv env 5 | - env/bin/pip install -r scripts/requirements.txt 6 | - ". env/bin/activate; scripts/generate-matrix-org-assets" 7 | artifact_paths: 8 | - assets.tar.gz 9 | plugins: 10 | - docker#v3.0.1: 11 | image: "python:3.6" 12 | 13 | - label: "rebuild matrix.org" 14 | trigger: "matrix-dot-org" 15 | async: true 16 | branches: "master" 17 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room_key_request$request: -------------------------------------------------------------------------------- 1 | { 2 | "content": { 3 | "body": { 4 | "algorithm": "m.megolm.v1.aes-sha2", 5 | "room_id": "!Cuyf34gef24t:localhost", 6 | "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ", 7 | "sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU" 8 | }, 9 | "action": "request", 10 | "requesting_device_id": "RJYKSTBOIE", 11 | "request_id": "1495474790150.19" 12 | }, 13 | "type": "m.room_key_request" 14 | } 15 | -------------------------------------------------------------------------------- /proposals/1759-rooms-v2.md: -------------------------------------------------------------------------------- 1 | # MSC 1759 - Rooms V2 2 | 3 | This MSC proposes creating a new room version to allow servers and users to opt 4 | in to using the new state resolution algorithm. 5 | 6 | 7 | ## Proposal 8 | 9 | The new room version is called "2". The only difference between v2 and v1 is 10 | that v2 rooms use the v2 state resolution algorithm, as defined in MSC 1442 and 11 | MSC 1693. 12 | 13 | It is not proposed that servers change the default room version used when 14 | creating new rooms. 15 | -------------------------------------------------------------------------------- /proposals/images/1756-graph2.dot: -------------------------------------------------------------------------------- 1 | digraph { 2 | A1 [label="A's PDP-11"] 3 | A2 [label="A's Osborne 2"] 4 | AM [label="A's master key"] 5 | AS [label="A's self-signing key"] 6 | AU [label="A's user-signing key"] 7 | BM [label="B's master key"] 8 | BU [label="B's user-signing key"] 9 | BS [label="B's self-signing key"] 10 | B1 [label="B's Dynabook"] 11 | B2 [label="B's VAX"] 12 | AS -> A1 13 | AS -> A2 14 | AM -> AS 15 | AM -> AU 16 | AU -> BM 17 | BM -> BS 18 | BM -> BU 19 | BU -> AM 20 | BS -> B1 21 | BS -> B2 22 | } 23 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.message$m.location: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/room_event.json", 3 | "type": "m.room.message", 4 | "content": { 5 | "body": "Big Ben, London, UK", 6 | "geo_uri": "geo:51.5008,0.1247", 7 | "info": { 8 | "thumbnail_url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe", 9 | "thumbnail_info": { 10 | "mimetype": "image/jpeg", 11 | "size": 46144, 12 | "w": 300, 13 | "h": 300 14 | } 15 | }, 16 | "msgtype": "m.location" 17 | } 18 | } 19 | -------------------------------------------------------------------------------- /event-schemas/examples/m.key.verification.accept: -------------------------------------------------------------------------------- 1 | { 2 | "type": "m.key.verification.accept", 3 | "content": { 4 | "transaction_id": "S0meUniqueAndOpaqueString", 5 | "method": "m.sas.v1", 6 | "key_agreement_protocol": "curve25519", 7 | "hash": "sha256", 8 | "message_authentication_code": "hkdf-hmac-sha256", 9 | "short_authentication_string": ["decimal", "emoji"], 10 | "commitment": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" 11 | } 12 | } 13 | -------------------------------------------------------------------------------- /event-schemas/schema/m.push_rules: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/event.yaml 4 | description: Describes all push rules for this user. 5 | properties: 6 | content: 7 | properties: 8 | global: 9 | type: object 10 | title: Ruleset 11 | description: The global ruleset 12 | allOf: 13 | - $ref: ../../api/client-server/definitions/push_ruleset.yaml 14 | type: object 15 | type: 16 | enum: 17 | - m.push_rules 18 | type: string 19 | title: Push rules 20 | type: object 21 | 22 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.power_levels: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/state_event.json", 3 | "type": "m.room.power_levels", 4 | "state_key": "", 5 | "content": { 6 | "ban": 50, 7 | "events": { 8 | "m.room.name": 100, 9 | "m.room.power_levels": 100 10 | }, 11 | "events_default": 0, 12 | "invite": 50, 13 | "kick": 50, 14 | "redact": 50, 15 | "state_default": 50, 16 | "users": { 17 | "@example:localhost": 100 18 | }, 19 | "users_default": 0, 20 | "notifications": { 21 | "room": 20 22 | } 23 | } 24 | } 25 | -------------------------------------------------------------------------------- /event-schemas/examples/m.sticker: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/room_event.json", 3 | "type": "m.sticker", 4 | "content": { 5 | "body": "Landing", 6 | "info": { 7 | "mimetype": "image/png", 8 | "thumbnail_info": { 9 | "mimetype": "image/png", 10 | "h": 200, 11 | "w": 140, 12 | "size": 73602 13 | }, 14 | "h": 200, 15 | "thumbnail_url": "mxc://matrix.org/sHhqkFCvSkFwtmvtETOtKnLP", 16 | "w": 140, 17 | "size": 73602 18 | }, 19 | "url": "mxc://matrix.org/sHhqkFCvSkFwtmvtETOtKnLP" 20 | } 21 | } 22 | -------------------------------------------------------------------------------- /event-schemas/schema/core-event-schema/event.yaml: -------------------------------------------------------------------------------- 1 | description: The basic set of fields all events must have. 2 | properties: 3 | content: 4 | description: The fields in this object will vary depending on the type of event. 5 | When interacting with the REST API, this is the HTTP body. 6 | type: object 7 | type: 8 | description: The type of event. This SHOULD be namespaced similar to Java package 9 | naming conventions e.g. 'com.example.subdomain.event.type' 10 | type: string 11 | required: 12 | - type 13 | - content 14 | title: Event 15 | type: object 16 | -------------------------------------------------------------------------------- /event-schemas/examples/m.forwarded_room_key: -------------------------------------------------------------------------------- 1 | { 2 | "content": { 3 | "algorithm": "m.megolm.v1.aes-sha2", 4 | "room_id": "!Cuyf34gef24t:localhost", 5 | "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ", 6 | "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf...", 7 | "sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU", 8 | "sender_claimed_ed25519_key": "aj40p+aw64yPIdsxoog8jhPu9i7l7NcFRecuOQblE3Y", 9 | "forwarding_curve25519_key_chain": [ 10 | "hPQNcabIABgGnx3/ACv/jmMmiQHoeFfuLB17tzWp6Hw" 11 | ] 12 | }, 13 | "type": "m.forwarded_room_key" 14 | } 15 | -------------------------------------------------------------------------------- /proposals/images/state-res-rejected.dot: -------------------------------------------------------------------------------- 1 | digraph Rejected { 2 | rankdir=BT; 3 | 4 | // Events 5 | A[label="A: Alice ops Bob"]; 6 | B[label="B: Alice deops Bob"]; 7 | D[label="D: Bob sets topic"]; 8 | E[label="E: Alice reops Bob"]; 9 | 10 | // Prev events 11 | B -> A; 12 | C -> B; 13 | D -> C; 14 | E -> C; 15 | F -> D; 16 | F -> E; 17 | 18 | // Auth Events 19 | 20 | B -> A [color=blue,style=bold]; 21 | D -> A [color=blue,style=bold]; 22 | E -> B [color=blue,style=bold]; 23 | } 24 | -------------------------------------------------------------------------------- /scripts/templating/matrix_templates/templates/schema-definition.tmpl: -------------------------------------------------------------------------------- 1 | {% import 'tables.tmpl' as tables -%} 2 | 3 | ``{{definition.title}}`` schema 4 | {{(11 + definition.title | length) * title_kind}} 5 | 6 | {% if 'description' in definition %} 7 | {{definition.description}} 8 | {% endif %} 9 | 10 | {% for table in definition.tables -%} 11 | {{"``"+table.title+"``" if table.title else "" }} 12 | {{ tables.paramtable(table.rows) }} 13 | {% endfor %} 14 | 15 | Example{% if examples | length > 1 %}s{% endif %}: 16 | 17 | {% for example in examples %} 18 | .. code:: json 19 | 20 | {{example | jsonify(4, 4)}} 21 | {% endfor %} 22 | -------------------------------------------------------------------------------- /api/server-server/examples/pdu_v3.json: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "unsigned_pdu_base.json", 3 | "hashes": { 4 | "sha256": "thishashcoversallfieldsincasethisisredacted" 5 | }, 6 | "signatures": { 7 | "example.com": { 8 | "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus" 9 | } 10 | }, 11 | "auth_events": [ 12 | "$base64encodedeventid", 13 | "$adifferenteventid" 14 | ], 15 | "prev_events": [ 16 | "$base64encodedeventid", 17 | "$adifferenteventid" 18 | ], 19 | "redacts": "$some/old+event" 20 | } 21 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.member$third_party_invite: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "m.room.member", 3 | "content": { 4 | "membership": "invite", 5 | "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF", 6 | "displayname": "Alice Margatroid", 7 | "third_party_invite": { 8 | "display_name": "alice", 9 | "signed": { 10 | "mxid": "@alice:example.org", 11 | "signatures": { 12 | "magic.forest": { 13 | "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" 14 | } 15 | }, 16 | "token": "abc123" 17 | } 18 | } 19 | } 20 | } 21 | -------------------------------------------------------------------------------- /api/server-server/examples/server_key.json: -------------------------------------------------------------------------------- 1 | { 2 | "server_name": "example.org", 3 | "verify_keys": { 4 | "ed25519:abc123": { 5 | "key": "VGhpcyBzaG91bGQgYmUgYSByZWFsIGVkMjU1MTkgcGF5bG9hZA" 6 | } 7 | }, 8 | "old_verify_keys": { 9 | "ed25519:0ldk3y": { 10 | "expired_ts": 1532645052628, 11 | "key": "VGhpcyBzaG91bGQgYmUgeW91ciBvbGQga2V5J3MgZWQyNTUxOSBwYXlsb2FkLg" 12 | } 13 | }, 14 | "signatures": { 15 | "example.org": { 16 | "ed25519:auto2": "VGhpcyBzaG91bGQgYWN0dWFsbHkgYmUgYSBzaWduYXR1cmU" 17 | } 18 | }, 19 | "valid_until_ts": 1652262000000 20 | } 21 | -------------------------------------------------------------------------------- /event-schemas/examples/m.room.message$m.video: -------------------------------------------------------------------------------- 1 | { 2 | "$ref": "core/room_event.json", 3 | "type": "m.room.message", 4 | "content": { 5 | "body": "Gangnam Style", 6 | "url": "mxc://example.org/a526eYUSFFxlgbQYZmo442", 7 | "info": { 8 | "thumbnail_url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe", 9 | "thumbnail_info": { 10 | "mimetype": "image/jpeg", 11 | "size": 46144, 12 | "w": 300, 13 | "h": 300 14 | }, 15 | "w": 480, 16 | "h": 320, 17 | "duration": 2140786, 18 | "size": 1563685, 19 | "mimetype": "video/mp4" 20 | }, 21 | "msgtype": "m.video" 22 | } 23 | } 24 | -------------------------------------------------------------------------------- /event-schemas/schema/m.direct: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/event.yaml 4 | description: |- 5 | A map of which rooms are considered 'direct' rooms for specific users 6 | is kept in ``account_data`` in an event of type ``m.direct``. The 7 | content of this event is an object where the keys are the user IDs 8 | and values are lists of room ID strings of the 'direct' rooms for 9 | that user ID. 10 | properties: 11 | content: 12 | additionalProperties: 13 | type: array 14 | title: User ID 15 | items: 16 | type: string 17 | type: object 18 | type: 19 | enum: 20 | - m.direct 21 | type: string 22 | title: Direct Chat Mapping 23 | type: object 24 | -------------------------------------------------------------------------------- /event-schemas/schema/m.accepted_terms: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/event.yaml 4 | description: |- 5 | A list of terms URLs the user has previously accepted. Clients SHOULD use this 6 | to avoid presenting the user with terms they have already agreed to. 7 | properties: 8 | content: 9 | type: object 10 | properties: 11 | accepted: 12 | type: array 13 | items: 14 | type: string 15 | description: |- 16 | The list of URLs the user has previously accepted. Should be appended to 17 | when the user agrees to new terms. 18 | type: 19 | enum: 20 | - m.accepted_terms 21 | type: string 22 | title: Accepted Terms of Service URLs 23 | type: object 24 | -------------------------------------------------------------------------------- /scripts/generate-matrix-org-assets: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | # 3 | # generate a tarball of assets suitable for the matrix.org site 4 | 5 | set -e 6 | 7 | cd `dirname $0`/.. 8 | 9 | mkdir -p assets 10 | 11 | if [ "$CIRCLECI" != "true" ] 12 | then 13 | # generate specification/proposals.rst 14 | ./scripts/proposals.py 15 | fi 16 | 17 | # generate the spec docs 18 | ./scripts/gendoc.py -d assets/spec 19 | 20 | # and the swagger 21 | ./scripts/dump-swagger.py -o assets/spec/client_server/unstable.json 22 | 23 | # create a tarball of the assets. Exclude the spec index for now, as 24 | # we want to leave it pointing at the release versions of the specs. 25 | # (XXX: how to maintain this?) 26 | tar -czf assets.tar.gz --exclude="assets/spec/index.html" assets 27 | -------------------------------------------------------------------------------- /api/server-server/examples/unsigned_pdu_base.json: -------------------------------------------------------------------------------- 1 | { 2 | "room_id": "!UcYsUzyxTGDxLBEvLy:example.org", 3 | "sender": "@alice:example.com", 4 | "origin": "example.com", 5 | "origin_server_ts": 1404838188000, 6 | "depth": 12, 7 | "auth_events": [ 8 | [ 9 | "$af232176:example.org", 10 | {"sha256": "abase64encodedsha256hashshouldbe43byteslong"} 11 | ] 12 | ], 13 | "type": "m.room.message", 14 | "prev_events": [ 15 | [ 16 | "$af232176:example.org", 17 | {"sha256": "abase64encodedsha256hashshouldbe43byteslong"} 18 | ] 19 | ], 20 | "content": { 21 | "key": "value" 22 | }, 23 | "unsigned": { 24 | "age": 4612 25 | } 26 | } 27 | -------------------------------------------------------------------------------- /specification/appendices.rst: -------------------------------------------------------------------------------- 1 | .. Copyright 2015 OpenMarket Ltd 2 | .. 3 | .. Licensed under the Apache License, Version 2.0 (the "License"); 4 | .. you may not use this file except in compliance with the License. 5 | .. You may obtain a copy of the License at 6 | .. 7 | .. http://www.apache.org/licenses/LICENSE-2.0 8 | .. 9 | .. Unless required by applicable law or agreed to in writing, software 10 | .. distributed under the License is distributed on an "AS IS" BASIS, 11 | .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | .. See the License for the specific language governing permissions and 13 | .. limitations under the License. 14 | 15 | Appendices 16 | ========== 17 | 18 | .. contents:: Table of Contents 19 | .. sectnum:: 20 | -------------------------------------------------------------------------------- /proposals/1866-invite-unsupported-version-error-code.md: -------------------------------------------------------------------------------- 1 | # MSC 1866 - Unsupported Room Version Error Code for Invites 2 | 3 | It is currently unspecified what error code should be relayed to clients when 4 | they attempt to invite a user on a remote server that does not support the room 5 | version. 6 | 7 | The proposal is to reuse the `M_UNSUPPORTED_ROOM_VERSION` error code that is 8 | currently returned by the create room API. 9 | 10 | Strictly, the error returned by the create room API would mean the local server 11 | didn't support the room version, while for the invite API it would mean the 12 | remote server didn't. However, there is sufficient overlap that it makes sense 13 | to reuse the same error code and rely on the context to differentiate the two 14 | cases. 15 | -------------------------------------------------------------------------------- /.github/PULL_REQUEST_TEMPLATE/spec-change.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Spec clarification/not a proposal 3 | about: A change that's not a spec proposal, such as a clarification to the spec itself. 4 | title: '' 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | ### Pull Request Checklist 11 | 12 | 13 | 14 | * [ ] Pull request includes a [changelog file](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#adding-to-the-changelog) 15 | * [ ] Pull request includes a [sign off](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#sign-off) 16 | * [ ] Pull request is classified as ['other changes'](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#other-changes) 17 | -------------------------------------------------------------------------------- /api/application-service/definitions/user_batch.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2018 New Vector Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | type: array 15 | description: List of matched third party users. 16 | items: 17 | $ref: user.yaml 18 | -------------------------------------------------------------------------------- /scripts/speculator/README: -------------------------------------------------------------------------------- 1 | speculator allows you to preview pull requests to the matrix.org specification. 2 | 3 | It serves the following HTTP endpoints: 4 | - / lists open pull requests 5 | - /spec/123 which renders the spec as html at pull request 123. 6 | - /diff/rst/123 which gives a diff of the spec's rst at pull request 123. 7 | - /diff/html/123 which gives a diff of the spec's HTML at pull request 123. 8 | 9 | The build or run, you need a working `go` installation. 10 | Then fetch dependencies: 11 | ` go get github.com/hashicorp/golang-lru` 12 | 13 | To run it, then run: 14 | `go run main.go` 15 | 16 | To build the binary (which is necessary for deployment to the matrix.org 17 | servers), you must again install `go` and dependencies, and then run: 18 | `go build` 19 | -------------------------------------------------------------------------------- /api/application-service/definitions/location_batch.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2018 New Vector Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | type: array 15 | description: List of matched third party locations. 16 | items: 17 | $ref: location.yaml 18 | -------------------------------------------------------------------------------- /proposals/2526-add-delete-backup.md: -------------------------------------------------------------------------------- 1 | # MSC2526: Add ability to delete key backups 2 | 3 | [MSC1219](https://github.com/matrix-org/matrix-doc/issues/1219) defined a 4 | mechanism for key backups. However, it inadvertently omitted the endpoint to 5 | delete an entire key backup. This proposal adds the endpoint. 6 | 7 | ## Proposal 8 | 9 | An endpoint is added, `DELETE /room_keys/version/{version}`, that deletes a 10 | backup version. Both the information about the key backup, as well as all keys 11 | associated with the backup should be deleted. If the specified version was 12 | previously deleted, the endpoint succeeds, returning an HTTP code of 200. If 13 | the specified version never existed, the endpoint returns an HTTP code of 404 14 | with a Matrix `errcode` of `M_NOT_FOUND`. 15 | -------------------------------------------------------------------------------- /api/files/jquery.wiggle.min.js: -------------------------------------------------------------------------------- 1 | /* 2 | jQuery Wiggle 3 | Author: WonderGroup, Jordan Thomas 4 | URL: http://labs.wondergroup.com/demos/mini-ui/index.html 5 | License: MIT (http://en.wikipedia.org/wiki/MIT_License) 6 | */ 7 | jQuery.fn.wiggle=function(o){var d={speed:50,wiggles:3,travel:5,callback:null};var o=jQuery.extend(d,o);return this.each(function(){var cache=this;var wrap=jQuery(this).wrap('
').css("position","relative");var calls=0;for(i=1;i<=o.wiggles;i++){jQuery(this).animate({left:"-="+o.travel},o.speed).animate({left:"+="+o.travel*2},o.speed*2).animate({left:"-="+o.travel},o.speed,function(){calls++;if(jQuery(cache).parent().hasClass('wiggle-wrap')){jQuery(cache).parent().replaceWith(cache);} 8 | if(calls==o.wiggles&&jQuery.isFunction(o.callback)){o.callback();}});}});}; -------------------------------------------------------------------------------- /event-schemas/schema/core-event-schema/msgtype_infos/thumbnail_info.yaml: -------------------------------------------------------------------------------- 1 | $schema: http://json-schema.org/draft-04/schema# 2 | description: Metadata about a thumbnail image. 3 | properties: 4 | h: 5 | description: |- 6 | The intended display height of the image in pixels. This may 7 | differ from the intrinsic dimensions of the image file. 8 | type: integer 9 | w: 10 | description: |- 11 | The intended display width of the image in pixels. This may 12 | differ from the intrinsic dimensions of the image file. 13 | type: integer 14 | mimetype: 15 | description: The mimetype of the image, e.g. ``image/jpeg``. 16 | type: string 17 | size: 18 | description: Size of the image in bytes. 19 | type: integer 20 | title: ThumbnailInfo 21 | type: object 22 | -------------------------------------------------------------------------------- /event-schemas/schema/m.room.avatar: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/state_event.yaml 4 | description: A picture that is associated with the room. This can be displayed alongside the room information. 5 | properties: 6 | content: 7 | properties: 8 | info: 9 | allOf: 10 | - $ref: core-event-schema/msgtype_infos/image_info.yaml 11 | description: Metadata about the image referred to in ``url``. 12 | url: 13 | description: The URL to the image. 14 | type: string 15 | required: 16 | - url 17 | type: object 18 | state_key: 19 | description: A zero-length string. 20 | pattern: '^$' 21 | type: string 22 | type: 23 | enum: 24 | - m.room.avatar 25 | type: string 26 | title: RoomAvatar 27 | type: object 28 | -------------------------------------------------------------------------------- /event-schemas/schema/m.room.topic: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/state_event.yaml 4 | description: 'A topic is a short message detailing what is currently being discussed in the room. It can also be used as a way to display extra information about the room, which may not be suitable for the room name. The room topic can also be set when creating a room using ``/createRoom`` with the ``topic`` key.' 5 | properties: 6 | content: 7 | properties: 8 | topic: 9 | description: The topic text. 10 | type: string 11 | required: 12 | - topic 13 | type: object 14 | state_key: 15 | description: A zero-length string. 16 | pattern: '^$' 17 | type: string 18 | type: 19 | enum: 20 | - m.room.topic 21 | type: string 22 | title: Topic 23 | type: object 24 | -------------------------------------------------------------------------------- /proposals/2077-rooms-v5.md: -------------------------------------------------------------------------------- 1 | # MSC2077 - Room version 5 2 | 3 | This MSC proposes creating room version 5, which will enforce the signing key 4 | `valid_until_ts` timestamps proposed in 5 | [MSC2076](https://github.com/matrix-org/matrix-doc/issues/2076). 6 | 7 | ## Proposal 8 | 9 | The new room version is called `5`. The only difference between v5 and v4 is 10 | that v5 rooms enforce the `valid_until_ts` timestamp on signing keys as 11 | proposed in [MSC2076](https://github.com/matrix-org/matrix-doc/issues/2076). 12 | 13 | It is not yet proposed to change the default room version to v5. Version 5 will 14 | be considered a "stable" version. 15 | 16 | ## Notes 17 | 18 | See also [MSC2002](./2002-rooms-v4.md), which proposed room v4 but also 19 | mentioned that a v5 was anticipated and gave some context for this change. 20 | -------------------------------------------------------------------------------- /api/client-server/definitions/security.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2016 OpenMarket Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | accessToken: 15 | type: apiKey 16 | description: The access_token returned by a call to ``/login`` or ``/register`` 17 | name: access_token 18 | in: query 19 | -------------------------------------------------------------------------------- /api/identity/definitions/security.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2019 The Matrix.org Foundation C.I.C. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | accessToken: 15 | type: apiKey 16 | description: The access_token returned by a call to ``/register``. 17 | name: access_token 18 | in: query 19 | -------------------------------------------------------------------------------- /event-schemas/schema/m.identity_server: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/event.yaml 4 | description: |- 5 | Persists the user's preferred identity server, or preference to not use 6 | an identity server at all, in the user's account data. 7 | properties: 8 | content: 9 | type: object 10 | properties: 11 | base_url: 12 | type: string 13 | description: |- 14 | The URL of the identity server the user prefers to use, or ``null`` 15 | if the user does not want to use an identity server. This value is 16 | similar in structure to the ``base_url`` for identity servers in the 17 | ``.well-known/matrix/client`` schema. 18 | type: 19 | enum: 20 | - m.identity_server 21 | type: string 22 | title: Identity Server Preference 23 | type: object 24 | -------------------------------------------------------------------------------- /event-schemas/schema/m.room.history_visibility: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/state_event.yaml 4 | description: This event controls whether a user can see the events that happened in a room from before they joined. 5 | properties: 6 | content: 7 | properties: 8 | history_visibility: 9 | description: Who can see the room history. 10 | enum: 11 | - invited 12 | - joined 13 | - shared 14 | - world_readable 15 | type: string 16 | required: 17 | - history_visibility 18 | type: object 19 | state_key: 20 | description: A zero-length string. 21 | pattern: '^$' 22 | type: string 23 | type: 24 | enum: 25 | - m.room.history_visibility 26 | type: string 27 | title: Controls visibility of history. 28 | type: object 29 | -------------------------------------------------------------------------------- /api/application-service/definitions/security.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2018 New Vector Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | homeserverAccessToken: 15 | type: apiKey 16 | description: The ``hs_token`` provided by the application service's registration. 17 | name: access_token 18 | in: query 19 | -------------------------------------------------------------------------------- /event-schemas/schema/m.room.tombstone: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/state_event.yaml 4 | description: 'A state event signifying that a room has been upgraded to a different room version, and that clients should go there.' 5 | properties: 6 | content: 7 | properties: 8 | body: 9 | type: string 10 | description: A server-defined message. 11 | replacement_room: 12 | type: string 13 | description: The new room the client should be visiting. 14 | required: 15 | - replacement_room 16 | - body 17 | type: object 18 | state_key: 19 | description: A zero-length string. 20 | pattern: '^$' 21 | type: string 22 | type: 23 | enum: 24 | - m.room.tombstone 25 | type: string 26 | title: Indication that the room has been upgraded. 27 | type: object 28 | -------------------------------------------------------------------------------- /api/server-server/definitions/security.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2018 New Vector Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | signedRequest: 15 | type: apiKey 16 | description: |- 17 | The ``Authorization`` header defined in the `Authentication`_ section. 18 | name: Authorization 19 | in: header 20 | -------------------------------------------------------------------------------- /event-schemas/schema/m.ignored_user_list: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/event.yaml 4 | description: |- 5 | A map of users which are considered ignored is kept in ``account_data`` 6 | in an event type of ``m.ignored_user_list``. 7 | properties: 8 | content: 9 | type: object 10 | properties: 11 | ignored_users: 12 | type: object 13 | title: "Ignored users" 14 | description: "The map of users to ignore" 15 | patternProperties: 16 | "^@": 17 | type: "object" 18 | title: "Ignored User" 19 | description: "An empty object for future enhancement" 20 | x-pattern: "$USER_ID" 21 | required: 22 | - ignored_users 23 | type: 24 | enum: 25 | - m.ignored_user_list 26 | type: string 27 | title: Ignored User List 28 | type: object 29 | -------------------------------------------------------------------------------- /event-schemas/schema/m.room.guest_access: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/state_event.yaml 4 | description: 'This event controls whether guest users are allowed to join rooms. If this event is absent, servers should act as if it is present and has the guest_access value "forbidden".' 5 | properties: 6 | content: 7 | properties: 8 | guest_access: 9 | description: Whether guests can join the room. 10 | enum: 11 | - can_join 12 | - forbidden 13 | type: string 14 | required: 15 | - guest_access 16 | type: object 17 | state_key: 18 | description: A zero-length string. 19 | pattern: '^$' 20 | type: string 21 | type: 22 | enum: 23 | - m.room.guest_access 24 | type: string 25 | title: Controls whether guest users are allowed to join rooms. 26 | type: object 27 | -------------------------------------------------------------------------------- /event-schemas/schema/m.key.verification.key: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/event.yaml 4 | 5 | description: |- 6 | Sends the ephemeral public key for a device to the partner device. Typically sent as a 7 | `to-device`_ event. 8 | properties: 9 | content: 10 | properties: 11 | transaction_id: 12 | type: string 13 | description: |- 14 | An opaque identifier for the verification process. Must be the same as 15 | the one used for the ``m.key.verification.start`` message. 16 | key: 17 | type: string 18 | description: |- 19 | The device's ephemeral public key, encoded as unpadded base64. 20 | required: 21 | - transaction_id 22 | - key 23 | type: object 24 | type: 25 | enum: 26 | - m.key.verification.key 27 | type: string 28 | type: object 29 | -------------------------------------------------------------------------------- /proposals/2175-remove-creator-field.md: -------------------------------------------------------------------------------- 1 | # MSC2175: Remove the `creator` field from `m.room.create` events 2 | 3 | [`m.room.create`](https://matrix.org/docs/spec/client_server/r0.5.0#m-room-create) 4 | events have a mandatory `creator` property giving the ID of the user who 5 | created the room. This field is redundant as it is always identical to the 6 | `sender` of the create event. 7 | 8 | This MSC proposes that, in a future room version, this field should be removed 9 | and that the `sender` field be used instead. 10 | 11 | Note that `creator` is mentioned in the [auth 12 | rules](https://matrix.org/docs/spec/rooms/v1#authorization-rules). It can 13 | safely be removed. 14 | 15 | `creator` is also mentioned as a key to be preserved during [Event 16 | redaction](https://matrix.org/docs/spec/client_server/r0.5.0#redactions). It 17 | should be removed from that list. 18 | -------------------------------------------------------------------------------- /.github/PULL_REQUEST_TEMPLATE/ready-proposal.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Proposal ready for review 3 | about: A proposal that is ready for review by the core team and community. 4 | title: '' 5 | labels: proposal, proposal-in-review 6 | assignees: '' 7 | 8 | --- 9 | 10 | 11 | 12 | ### Pull Request Checklist 13 | 14 | 15 | 16 | * [ ] Pull request includes a [changelog file](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#adding-to-the-changelog) 17 | * [ ] Pull request includes a [sign off](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#sign-off) 18 | * [ ] Pull request includes ['Rendered' link](https://matrix.org/docs/spec/proposals#process) above. 19 | * [ ] Pull request title and file name include this PR's number as the MSC number. 20 | -------------------------------------------------------------------------------- /api/files/css: -------------------------------------------------------------------------------- 1 | /* latin */ 2 | @font-face { 3 | font-family: 'Droid Sans'; 4 | font-style: normal; 5 | font-weight: 400; 6 | src: local('Droid Sans'), local('DroidSans'), url(http://fonts.gstatic.com/s/droidsans/v5/s-BiyweUPV0v-yRb-cjciPk_vArhqVIZ0nv9q090hN8.woff2), format('woff2'); 7 | unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2212, U+2215, U+E0FF, U+EFFD, U+F000; 8 | } 9 | /* latin */ 10 | @font-face { 11 | font-family: 'Droid Sans'; 12 | font-style: normal; 13 | font-weight: 700; 14 | src: local('Droid Sans Bold'), local('DroidSans-Bold'), url(http://fonts.gstatic.com/s/droidsans/v5/EFpQQyG9GqCrobXxL-KRMYWiMMZ7xLd792ULpGE4W_Y.woff2), format('woff2'); 15 | unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2212, U+2215, U+E0FF, U+EFFD, U+F000; 16 | } 17 | -------------------------------------------------------------------------------- /specification/modules/third_party_networks.rst: -------------------------------------------------------------------------------- 1 | Third Party Networks 2 | ==================== 3 | 4 | .. _module:third-party-networks: 5 | 6 | Application services can provide access to third party networks via bridging. 7 | This allows Matrix users to communicate with users on other communication 8 | platforms, with messages ferried back and forth by the application service. A 9 | single application service may bridge multiple third party networks, and many 10 | individual locations within those networks. A single third party network 11 | location may be bridged to multiple Matrix rooms. 12 | 13 | Third Party Lookups 14 | ------------------- 15 | 16 | A client may wish to provide a rich interface for joining third party 17 | locations and connecting with third party users. Information necessary for 18 | such an interface is provided by third party lookups. 19 | 20 | {{third_party_lookup_cs_http_api}} -------------------------------------------------------------------------------- /proposals/2240-rooms-v6.md: -------------------------------------------------------------------------------- 1 | # MSC2240: Room Version 6 2 | 3 | A new room version, `6`, is proposed using [room version 5](https://matrix.org/docs/spec/rooms/v5.html) as a base 4 | and incorporating the following MSCs: 5 | 6 | * [MSC2209](https://github.com/matrix-org/matrix-doc/pull/2209) - Including notifications in power level auth rules. 7 | * [MSC2432](https://github.com/matrix-org/matrix-doc/pull/2432) - Alias event authorisation and redaction. 8 | * [MSC2540](https://github.com/matrix-org/matrix-doc/pull/2540) - Integers in canonical JSON compliance. 9 | 10 | Though other MSCs are capable of being included in this version, they do not have sufficient implementation to be 11 | considered stable enough for v6 rooms. A future room version may still include them. 12 | 13 | Room version 6 upon being added to the specification shall be considered stable. No other room versions are affected 14 | by this MSC. 15 | -------------------------------------------------------------------------------- /changelogs/application_service.rst: -------------------------------------------------------------------------------- 1 | r0.1.2 2 | ====== 3 | 4 | Spec Clarifications 5 | ------------------- 6 | 7 | - Clearer wording for the legacy routes section. (`#2160 `_) 8 | 9 | 10 | r0.1.1 11 | ====== 12 | 13 | Spec Clarifications 14 | ------------------- 15 | 16 | - Change examples to use example.org instead of a real domain. (`#1650 `_) 17 | - Add missing definition for how appservices verify requests came from a homeserver. (`#2037 `_) 18 | 19 | 20 | r0.1.0 21 | ====== 22 | 23 | This is the first release of the Application Service specification. It 24 | includes support for application services being able to interact with 25 | homeservers and bridge third party networks, such as IRC, over to Matrix 26 | in a standard and accessible way. 27 | -------------------------------------------------------------------------------- /scripts/templating/matrix_templates/templates/events.tmpl: -------------------------------------------------------------------------------- 1 | {% import 'tables.tmpl' as tables -%} 2 | 3 | {% if (event.type_with_msgtype) %} 4 | ``{{event.type_with_msgtype}}`` 5 | {{(4 + event.type_with_msgtype | length) * title_kind}} 6 | {% endif -%} 7 | 8 | {% if (not event.type_with_msgtype) %} 9 | ``{{event.type}}`` 10 | {{(4 + event.type | length) * title_kind}} 11 | {% endif -%} 12 | 13 | {% if (event.typeof | length) %} 14 | *{{event.typeof}}* 15 | {{event.typeof_info | indent_block(4)}} 16 | 17 | {% endif -%} 18 | 19 | {{event.desc}} 20 | 21 | {% for table in event.content_fields %} 22 | 23 | {{ tables.paramtable(table.rows, [(table.title or "Content") ~ " Key", "Type", "Description"], (table.title or "")) }} 24 | 25 | {% endfor %} 26 | Example{% if examples | length > 1 %}s{% endif %}: 27 | 28 | {% for example in examples %} 29 | .. code:: json 30 | 31 | {{example | jsonify(4, 4)}} 32 | {% endfor %} 33 | -------------------------------------------------------------------------------- /event-schemas/schema/m.dummy: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/event.yaml 4 | 5 | description: |- 6 | This event type is used to indicate new Olm sessions for end-to-end encryption. 7 | Typically it is encrypted as an ``m.room.encrypted`` event, then sent as a `to-device`_ 8 | event. 9 | 10 | The event does not have any content associated with it. The sending client is expected 11 | to send a key share request shortly after this message, causing the receiving client to 12 | process this ``m.dummy`` event as the most recent event and using the keyshare request 13 | to set up the session. The keyshare request and ``m.dummy`` combination should result 14 | in the original sending client receiving keys over the newly established session. 15 | properties: 16 | content: 17 | properties: {} 18 | type: object 19 | type: 20 | enum: 21 | - m.dummy 22 | type: string 23 | type: object 24 | -------------------------------------------------------------------------------- /api/client-server/definitions/event_batch.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2016 OpenMarket Ltd 2 | # Copyright 2018 New Vector Ltd 3 | # 4 | # Licensed under the Apache License, Version 2.0 (the "License"); 5 | # you may not use this file except in compliance with the License. 6 | # You may obtain a copy of the License at 7 | # 8 | # http://www.apache.org/licenses/LICENSE-2.0 9 | # 10 | # Unless required by applicable law or agreed to in writing, software 11 | # distributed under the License is distributed on an "AS IS" BASIS, 12 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | # See the License for the specific language governing permissions and 14 | # limitations under the License. 15 | properties: 16 | events: 17 | description: List of events. 18 | items: 19 | allOf: 20 | - $ref: event-schemas/schema/core-event-schema/event.yaml 21 | type: object 22 | type: array 23 | type: object 24 | -------------------------------------------------------------------------------- /scripts/templating/matrix_templates/__init__.py: -------------------------------------------------------------------------------- 1 | # Copyright 2016 OpenMarket Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | from .sections import MatrixSections 15 | from .units import MatrixUnits 16 | import os 17 | 18 | exports = { 19 | "units": MatrixUnits, 20 | "sections": MatrixSections, 21 | "templates": os.path.join(os.path.dirname(os.path.abspath(__file__)), "templates") 22 | } -------------------------------------------------------------------------------- /specification/modules/admin.rst: -------------------------------------------------------------------------------- 1 | .. Copyright 2016 OpenMarket Ltd 2 | .. 3 | .. Licensed under the Apache License, Version 2.0 (the "License"); 4 | .. you may not use this file except in compliance with the License. 5 | .. You may obtain a copy of the License at 6 | .. 7 | .. http://www.apache.org/licenses/LICENSE-2.0 8 | .. 9 | .. Unless required by applicable law or agreed to in writing, software 10 | .. distributed under the License is distributed on an "AS IS" BASIS, 11 | .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | .. See the License for the specific language governing permissions and 13 | .. limitations under the License. 14 | 15 | Server Administration 16 | ===================== 17 | 18 | .. _module:admin: 19 | 20 | This module adds capabilities for server administrators to inspect server state 21 | and data. 22 | 23 | Client Behaviour 24 | ---------------- 25 | 26 | {{admin_cs_http_api}} 27 | -------------------------------------------------------------------------------- /schemas/server-signatures.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2018 New Vector Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | type: object 15 | example: { 16 | "example.com": { 17 | "ed25519:0": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus" 18 | } 19 | } 20 | additionalProperties: 21 | type: object 22 | title: Server Signatures 23 | additionalProperties: 24 | type: string -------------------------------------------------------------------------------- /event-schemas/schema/m.room.message: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/room_event.yaml 4 | description: 'This event is used when sending messages in a room. Messages are not limited to be text. The ``msgtype`` key outlines the type of message, e.g. text, audio, image, video, etc. The ``body`` key is text and MUST be used with every kind of ``msgtype`` as a fallback mechanism for when a client cannot render a message. This allows clients to display *something* even if it is just plain text.' 5 | properties: 6 | content: 7 | properties: 8 | body: 9 | description: The textual representation of this message. 10 | type: string 11 | msgtype: 12 | description: 'The type of message, e.g. ``m.image``, ``m.text``' 13 | type: string 14 | required: 15 | - msgtype 16 | - body 17 | type: object 18 | type: 19 | enum: 20 | - m.room.message 21 | type: string 22 | title: Message 23 | type: object 24 | -------------------------------------------------------------------------------- /proposals/1812-federation-make-membership.md: -------------------------------------------------------------------------------- 1 | # MSC 1813 - Federation Make Membership Room Version 2 | 3 | This proposal adds a new `room_version` field to the responses of `/make_leave` 4 | and `/make_join` APIs. 5 | 6 | ## Motivation 7 | 8 | It is planned for future room versions to be able to change the format of events 9 | in various ways. To support this, all servers must know the room version 10 | whenever they need to parse an event. Currently the `/make_*` APIs do not 11 | include the room version in the response, so the requesting server is unable to 12 | parse the event included in the response body. 13 | 14 | ## Proposal 15 | 16 | Add a new `room_version` field to the response body of the `v1` `/make_join` and 17 | `/make_leave` APIs, which describes the room version. 18 | 19 | For backwards compatibility servers must correctly handle responses that do not 20 | include the new field. In which case the room version is assumed to be one of 21 | either `1` or `2`. 22 | -------------------------------------------------------------------------------- /proposals/2174-move-redacts-key.md: -------------------------------------------------------------------------------- 1 | # MSC2174: move the `redacts` property to `content` 2 | 3 | [`m.room.redaction`](https://matrix.org/docs/spec/client_server/r0.5.0#m-room-redaction) 4 | events currently have an *event-level* property `redacts` which gives the event 5 | ID of the event being redacted. 6 | 7 | The presence of this field at the event level, rather than under the `content` 8 | key, is anomalous. This MSC proposes that, in a future room version, the 9 | `redacts` property be moved under the `content` key. 10 | 11 | For backwards-compatibility with *older* clients, servers should add a `redacts` 12 | property to the top level of `m.room.redaction` events in *newer* room versions 13 | when serving such events over the Client-Server API. 14 | 15 | For improved compatibility with *newer* clients, servers should add a `redacts` 16 | property to the `content` of `m.room.redaction` events in *older* room versions 17 | when serving such events over the Client-Server API. 18 | -------------------------------------------------------------------------------- /api/client-server/definitions/errors/error.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2016 OpenMarket Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | type: object 15 | description: A Matrix-level Error 16 | properties: 17 | errcode: 18 | type: string 19 | description: An error code. 20 | example: M_UNKNOWN 21 | error: 22 | type: string 23 | description: A human-readable error message. 24 | example: An unknown error occurred 25 | required: ["errcode"] -------------------------------------------------------------------------------- /event-schemas/schema/m.typing: -------------------------------------------------------------------------------- 1 | { 2 | "type": "object", 3 | "title": "Typing Event", 4 | "description": "Informs the client of the list of users currently typing.", 5 | "allOf": [{ 6 | "$ref": "core-event-schema/event.yaml" 7 | }], 8 | "properties": { 9 | "content": { 10 | "type": "object", 11 | "properties": { 12 | "user_ids": { 13 | "type": "array", 14 | "items": { 15 | "type": "string" 16 | }, 17 | "description": "The list of user IDs typing in this room, if any." 18 | } 19 | }, 20 | "required": ["user_ids"] 21 | }, 22 | "type": { 23 | "type": "string", 24 | "enum": ["m.typing"] 25 | }, 26 | "room_id": { 27 | "type": "string" 28 | } 29 | }, 30 | "required": ["type", "room_id", "content"] 31 | } 32 | -------------------------------------------------------------------------------- /event-schemas/schema/m.room.message$m.text: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/room_event.yaml 4 | description: This message is the most basic message and is used to represent text. 5 | properties: 6 | content: 7 | properties: 8 | body: 9 | description: The body of the message. 10 | type: string 11 | msgtype: 12 | enum: 13 | - m.text 14 | type: string 15 | format: 16 | description: |- 17 | The format used in the ``formatted_body``. Currently only 18 | ``org.matrix.custom.html`` is supported. 19 | type: string 20 | formatted_body: 21 | description: |- 22 | The formatted version of the ``body``. This is required if ``format`` 23 | is specified. 24 | type: string 25 | required: 26 | - msgtype 27 | - body 28 | type: object 29 | type: 30 | enum: 31 | - m.room.message 32 | type: string 33 | title: TextMessage 34 | type: object 35 | -------------------------------------------------------------------------------- /.github/PULL_REQUEST_TEMPLATE/wip-proposal.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: WIP Proposal 3 | about: A proposal that isn't quite ready for formal review yet. 4 | title: '[WIP] Your Proposal Title' 5 | labels: proposal 6 | assignees: '' 7 | 8 | --- 9 | 10 | 11 | 12 | ### Pull Request Checklist 13 | 14 | 15 | 16 | * [ ] Pull request includes a [changelog file](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#adding-to-the-changelog) 17 | * [ ] Pull request includes a [sign off](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#sign-off) 18 | * [ ] A ['Rendered' link](https://matrix.org/docs/spec/proposals#process) above. 19 | * [ ] Update the title and file name of your proposal to match this PR's number (after opening). 20 | * [ ] Ask in [#matrix-spec:matrix.org](https://matrix.to/#/#matrix-spec:matrix.org) to get this marked as ready for review, once it is ready for review. 21 | -------------------------------------------------------------------------------- /scripts/css/codehighlight.css: -------------------------------------------------------------------------------- 1 | pre.code .comment, code .comment { color: green } 2 | pre.code .keyword, code .keyword { color: darkred; font-weight: bold } 3 | pre.code .name.builtin, code .name.builtin { color: darkred; font-weight: bold } 4 | pre.code .name.tag, code .name.tag { color: darkgreen } 5 | pre.code .literal, code .literal { color: darkblue } 6 | pre.code .literal.number, code .literal.number { color: blue } 7 | 8 | 9 | /* HTTP Methods have class "name function" */ 10 | pre.code.http .name.function, code.http .name.function { color: black; font-weight: bold } 11 | /* HTTP Paths have class "name namespace" */ 12 | pre.code.http .name.namespace, code.http .name.namespace { color: darkgreen } 13 | /* HTTP "HTTP" strings have class "keyword reserved" */ 14 | pre.code.http .keyword.reserved, code.http .keyword.reserved { color: black; font-weight: bold } 15 | /* HTTP Header names have class "name attribute" */ 16 | pre.code.http .name.attribute, code.http .name.attribute { color: black; font-weight: bold } 17 | -------------------------------------------------------------------------------- /api/client-server/definitions/user_identifier.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2018 New Vector Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | title: User identifier 15 | description: |- 16 | Identification information for a user 17 | type: object 18 | properties: 19 | type: 20 | type: string 21 | description: The type of identification. See `Identifier types`_ for supported values and additional property descriptions. 22 | required: 23 | - type 24 | additionalProperties: true 25 | -------------------------------------------------------------------------------- /api/client-server/definitions/wellknown/homeserver.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2018 New Vector Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | title: Homeserver Information 15 | description: |- 16 | Used by clients to discover homeserver information. 17 | type: object 18 | properties: 19 | base_url: 20 | type: string 21 | description: The base URL for the homeserver for client-server connections. 22 | example: https://matrix.example.com 23 | required: 24 | - base_url 25 | -------------------------------------------------------------------------------- /specification/modules/openid.rst: -------------------------------------------------------------------------------- 1 | .. Copyright 2018 New Vector Ltd. 2 | .. 3 | .. Licensed under the Apache License, Version 2.0 (the "License"); 4 | .. you may not use this file except in compliance with the License. 5 | .. You may obtain a copy of the License at 6 | .. 7 | .. http://www.apache.org/licenses/LICENSE-2.0 8 | .. 9 | .. Unless required by applicable law or agreed to in writing, software 10 | .. distributed under the License is distributed on an "AS IS" BASIS, 11 | .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | .. See the License for the specific language governing permissions and 13 | .. limitations under the License. 14 | 15 | OpenID 16 | ====== 17 | 18 | .. _module:openid: 19 | 20 | This module allows users to verify their identity with a third party service. The 21 | third party service does need to be matrix-aware in that it will need to know to 22 | resolve matrix homeservers to exchange the user's token for identity information. 23 | 24 | {{openid_cs_http_api}} 25 | -------------------------------------------------------------------------------- /api/client-server/definitions/room_event_batch.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2018 New Vector Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | properties: 15 | events: 16 | description: List of events. 17 | items: 18 | allOf: 19 | - $ref: event-schemas/schema/core-event-schema/sync_room_event.yaml 20 | type: object 21 | required: 22 | - event_id 23 | #- room_id - Not in /sync 24 | - sender 25 | - origin_server_ts 26 | type: array 27 | type: object 28 | -------------------------------------------------------------------------------- /api/client-server/definitions/wellknown/identity_server.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2018 New Vector Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | title: Identity Server Information 15 | description: |- 16 | Used by clients to discover identity server information. 17 | type: object 18 | properties: 19 | base_url: 20 | type: string 21 | description: The base URL for the identity server for client-server connections. 22 | example: https://identity.example.com 23 | required: 24 | - base_url 25 | -------------------------------------------------------------------------------- /api/server-server/definitions/keys_query_response.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2018 New Vector Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | type: object 15 | description: Server keys 16 | example: { 17 | "server_keys": [{ 18 | $ref: "../examples/server_key_notary_signed.json" 19 | }] 20 | } 21 | properties: 22 | server_keys: 23 | type: array 24 | title: Server Keys 25 | description: The queried server's keys, signed by the notary server. 26 | items: 27 | $ref: "keys.yaml" 28 | -------------------------------------------------------------------------------- /scripts/test-and-build.sh: -------------------------------------------------------------------------------- 1 | #! /bin/bash 2 | 3 | set -ex 4 | 5 | cd `dirname $0`/.. 6 | 7 | virtualenv -p python3 env 8 | . env/bin/activate 9 | 10 | # Print out the python versions for debugging purposes 11 | python --version 12 | pip --version 13 | 14 | pip install -r scripts/requirements.txt 15 | 16 | # do sanity checks on the examples and swagger 17 | (cd event-schemas/ && ./check_examples.py) 18 | (cd api && ./check_examples.py) 19 | (cd api && npm install && node validator.js -s "client-server") 20 | 21 | : ${GOPATH:=${WORKSPACE}/.gopath} 22 | mkdir -p "${GOPATH}" 23 | export GOPATH 24 | go get github.com/hashicorp/golang-lru 25 | go get gopkg.in/fsnotify/fsnotify.v1 26 | 27 | # make sure that the scripts build 28 | (cd scripts/continuserv && go build) 29 | (cd scripts/speculator && go build) 30 | 31 | # build the spec for matrix.org. 32 | # (we don't actually use it on travis, but it's still useful to check we 33 | # can build it. On Buildkite, this is then used to deploy to matrix.org). 34 | ./scripts/generate-matrix-org-assets 35 | -------------------------------------------------------------------------------- /api/identity/definitions/sid.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2018 New Vector Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | type: object 15 | properties: 16 | sid: 17 | type: string 18 | description: | 19 | The session ID. Session IDs are opaque strings generated by the identity 20 | server. They must consist entirely of the characters 21 | ``[0-9a-zA-Z.=_-]``. Their length must not exceed 255 characters and they 22 | must not be empty. 23 | example: "123abc" 24 | required: ['sid'] 25 | -------------------------------------------------------------------------------- /event-schemas/schema/m.room.redaction: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/room_event.yaml 4 | description: 'Events can be redacted by either room or server admins. Redacting an event means that all keys not required by the protocol are stripped off, allowing admins to remove offensive or illegal content that may have been attached to any event. This cannot be undone, allowing server owners to physically delete the offending data. There is also a concept of a moderator hiding a message event, which can be undone, but cannot be applied to state events. The event that has been redacted is specified in the ``redacts`` event level key.' 5 | properties: 6 | content: 7 | properties: 8 | reason: 9 | description: 'The reason for the redaction, if any.' 10 | type: string 11 | type: object 12 | redacts: 13 | description: The event ID that was redacted. 14 | type: string 15 | type: 16 | enum: 17 | - m.room.redaction 18 | type: string 19 | required: 20 | - redacts 21 | title: Redaction 22 | type: object 23 | -------------------------------------------------------------------------------- /api/client-server/definitions/state_event_batch.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2018 New Vector Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | properties: 15 | events: 16 | description: List of events. 17 | items: 18 | allOf: 19 | - $ref: event-schemas/schema/core-event-schema/sync_state_event.yaml 20 | type: object 21 | required: 22 | - event_id 23 | #- room_id - Not in /sync 24 | - sender 25 | - origin_server_ts 26 | - state_key 27 | type: array 28 | type: object 29 | -------------------------------------------------------------------------------- /api/server-server/definitions/edu.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2018 New Vector Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | type: object 16 | title: Ephemeral Data Unit 17 | description: An ephemeral data unit. 18 | example: 19 | $ref: "../examples/edu.json" 20 | properties: 21 | edu_type: 22 | type: string 23 | description: The type of ephemeral message. 24 | example: "m.presence" 25 | content: 26 | type: object 27 | description: The content of the ephemeral message. 28 | required: ['edu_type', 'content'] -------------------------------------------------------------------------------- /event-schemas/schema/m.room.join_rules: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/state_event.yaml 4 | description: 'A room may be ``public`` meaning anyone can join the room without any prior action. Alternatively, it can be ``invite`` meaning that a user who wishes to join the room must first receive an invite to the room from someone already inside of the room. Currently, ``knock`` and ``private`` are reserved keywords which are not implemented.' 5 | properties: 6 | content: 7 | properties: 8 | join_rule: 9 | description: The type of rules used for users wishing to join this room. 10 | enum: 11 | - public 12 | - knock 13 | - invite 14 | - private 15 | type: string 16 | required: 17 | - join_rule 18 | type: object 19 | state_key: 20 | description: A zero-length string. 21 | pattern: '^$' 22 | type: string 23 | type: 24 | enum: 25 | - m.room.join_rules 26 | type: string 27 | title: Describes how users are allowed to join the room. 28 | type: object 29 | -------------------------------------------------------------------------------- /event-schemas/schema/m.room_key: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/event.yaml 4 | 5 | description: |- 6 | This event type is used to exchange keys for end-to-end encryption. Typically 7 | it is encrypted as an ``m.room.encrypted`` event, then sent as a `to-device`_ event. 8 | properties: 9 | content: 10 | properties: 11 | algorithm: 12 | type: string 13 | enum: ["m.megolm.v1.aes-sha2"] 14 | description: |- 15 | The encryption algorithm the key in this event is to be used with. 16 | room_id: 17 | type: string 18 | description: The room where the key is used. 19 | session_id: 20 | type: string 21 | description: The ID of the session that the key is for. 22 | session_key: 23 | type: string 24 | description: The key to be exchanged. 25 | required: 26 | - algorithm 27 | - room_id 28 | - session_id 29 | - session_key 30 | type: object 31 | type: 32 | enum: 33 | - m.room_key 34 | type: string 35 | type: object 36 | -------------------------------------------------------------------------------- /event-schemas/schema/m.tag: -------------------------------------------------------------------------------- 1 | { 2 | "type": "object", 3 | "title": "Tag Event", 4 | "description": "Informs the client of tags on a room.", 5 | "allOf": [{ 6 | "$ref": "core-event-schema/event.yaml" 7 | }], 8 | "properties": { 9 | "type": { 10 | "type": "string", 11 | "enum": ["m.tag"] 12 | }, 13 | "content": { 14 | "type": "object", 15 | "properties": { 16 | "tags": { 17 | "type": "object", 18 | "description": "The tags on the room and their contents.", 19 | "additionalProperties": { 20 | "title": "Tag", 21 | "type": "object", 22 | "properties": { 23 | "order": { 24 | "type": "number", 25 | "format": "float", 26 | "description": 27 | "A number in a range ``[0,1]`` describing a relative position of the room under the given tag." 28 | } 29 | } 30 | } 31 | } 32 | } 33 | } 34 | }, 35 | "required": ["type", "content"] 36 | } 37 | -------------------------------------------------------------------------------- /event-schemas/schema/m.fully_read: -------------------------------------------------------------------------------- 1 | { 2 | "type": "object", 3 | "title": "Read Marker Location Event", 4 | "description": "The current location of the user's read marker in a room. This event appears in the user's room account data for the room the marker is applicable for.", 5 | "allOf": [{ 6 | "$ref": "core-event-schema/event.yaml" 7 | }], 8 | "properties": { 9 | "content": { 10 | "type": "object", 11 | "properties": { 12 | "event_id": { 13 | "type": "string", 14 | "description": "The event the user's read marker is located at in the room." 15 | } 16 | }, 17 | "required": ["event_id"] 18 | }, 19 | "type": { 20 | "type": "string", 21 | "enum": ["m.fully_read"] 22 | }, 23 | "room_id": { 24 | "type": "string", 25 | "description": "The room ID the read marker applies to." 26 | } 27 | }, 28 | "required": ["type", "room_id", "content"] 29 | } 30 | -------------------------------------------------------------------------------- /api/client-server/definitions/timeline_batch.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2016 OpenMarket Ltd 2 | # Copyright 2018 New Vector Ltd 3 | # 4 | # Licensed under the Apache License, Version 2.0 (the "License"); 5 | # you may not use this file except in compliance with the License. 6 | # You may obtain a copy of the License at 7 | # 8 | # http://www.apache.org/licenses/LICENSE-2.0 9 | # 10 | # Unless required by applicable law or agreed to in writing, software 11 | # distributed under the License is distributed on an "AS IS" BASIS, 12 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | # See the License for the specific language governing permissions and 14 | # limitations under the License. 15 | allOf: 16 | - $ref: room_event_batch.yaml 17 | properties: 18 | limited: 19 | description: True if the number of events returned was limited by the ``limit`` 20 | on the filter. 21 | type: boolean 22 | prev_batch: 23 | description: A token that can be supplied to the ``from`` parameter of the 24 | rooms/{roomId}/messages endpoint. 25 | type: string 26 | type: object 27 | -------------------------------------------------------------------------------- /event-schemas/schema/m.room.pinned_events: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/state_event.yaml 4 | description: This event is used to "pin" particular events in a room for other participants to review later. The order of the pinned events is guaranteed and based upon the order supplied in the event. Clients should be aware that the current user may not be able to see some of the events pinned due to visibility settings in the room. Clients are responsible for determining if a particular event in the pinned list is displayable, and have the option to not display it if it cannot be pinned in the client. 5 | properties: 6 | content: 7 | properties: 8 | pinned: 9 | description: An ordered list of event IDs to pin. 10 | items: 11 | type: string 12 | type: array 13 | required: 14 | - pinned 15 | type: object 16 | state_key: 17 | description: A zero-length string. 18 | pattern: '^$' 19 | type: string 20 | type: 21 | enum: 22 | - m.room.pinned_events 23 | type: string 24 | title: Pinned events in a room 25 | type: object 26 | -------------------------------------------------------------------------------- /event-schemas/schema/m.sticker: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/room_event.yaml 4 | description: This message represents a single sticker image. 5 | properties: 6 | content: 7 | properties: 8 | body: 9 | description: |- 10 | A textual representation or associated description of the sticker 11 | image. This could be the alt text of the original image, or a message 12 | to accompany and further describe the sticker. 13 | type: string 14 | info: 15 | allOf: 16 | - $ref: core-event-schema/msgtype_infos/image_info.yaml 17 | description: |- 18 | Metadata about the image referred to in ``url`` including a thumbnail 19 | representation. 20 | url: 21 | description: |- 22 | The URL to the sticker image. This must be a valid ``mxc://`` URI. 23 | type: string 24 | required: 25 | - body 26 | - info 27 | - url 28 | type: object 29 | type: 30 | enum: 31 | - m.sticker 32 | type: string 33 | title: StickerMessage 34 | type: object 35 | -------------------------------------------------------------------------------- /event-schemas/schema/m.room.message.feedback: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/room_event.yaml 4 | description: '**NB: Usage of this event is discouraged in favour of the** `receipts module`_. **Most clients will not recognise this event.** Feedback events are events sent to acknowledge a message in some way. There are two supported acknowledgements: ``delivered`` (sent when the event has been received) and ``read`` (sent when the event has been observed by the end-user). The ``target_event_id`` should reference the ``m.room.message`` event being acknowledged.' 5 | properties: 6 | content: 7 | properties: 8 | target_event_id: 9 | description: The event that this feedback is related to. 10 | type: string 11 | type: 12 | description: The type of feedback. 13 | enum: 14 | - delivered 15 | - read 16 | type: string 17 | required: 18 | - type 19 | - target_event_id 20 | type: object 21 | type: 22 | enum: 23 | - m.room.message.feedback 24 | type: string 25 | title: MessageFeedback 26 | type: object 27 | -------------------------------------------------------------------------------- /changelogs/push_gateway/pyproject.toml: -------------------------------------------------------------------------------- 1 | [tool.towncrier] 2 | filename = "../push_gateway.rst" 3 | directory = "newsfragments" 4 | issue_format = "`#{issue} `_" 5 | title_format = "{version}" 6 | 7 | [[tool.towncrier.type]] 8 | directory = "breaking" 9 | name = "Breaking Changes" 10 | showcontent = true 11 | 12 | [[tool.towncrier.type]] 13 | directory = "deprecation" 14 | name = "Deprecations" 15 | showcontent = true 16 | 17 | [[tool.towncrier.type]] 18 | directory = "new" 19 | name = "New Endpoints" 20 | showcontent = true 21 | 22 | [[tool.towncrier.type]] 23 | directory = "removal" 24 | name = "Removed Endpoints" 25 | showcontent = true 26 | 27 | [[tool.towncrier.type]] 28 | directory = "feature" 29 | name = "Backwards Compatible Changes" 30 | showcontent = true 31 | 32 | [[tool.towncrier.type]] 33 | directory = "clarification" 34 | name = "Spec Clarifications" 35 | showcontent = true 36 | -------------------------------------------------------------------------------- /changelogs/client_server/pyproject.toml: -------------------------------------------------------------------------------- 1 | [tool.towncrier] 2 | filename = "../client_server.rst" 3 | directory = "newsfragments" 4 | issue_format = "`#{issue} `_" 5 | title_format = "{version}" 6 | 7 | [[tool.towncrier.type]] 8 | directory = "breaking" 9 | name = "Breaking Changes" 10 | showcontent = true 11 | 12 | [[tool.towncrier.type]] 13 | directory = "deprecation" 14 | name = "Deprecations" 15 | showcontent = true 16 | 17 | [[tool.towncrier.type]] 18 | directory = "new" 19 | name = "New Endpoints" 20 | showcontent = true 21 | 22 | [[tool.towncrier.type]] 23 | directory = "removal" 24 | name = "Removed Endpoints" 25 | showcontent = true 26 | 27 | [[tool.towncrier.type]] 28 | directory = "feature" 29 | name = "Backwards Compatible Changes" 30 | showcontent = true 31 | 32 | [[tool.towncrier.type]] 33 | directory = "clarification" 34 | name = "Spec Clarifications" 35 | showcontent = true 36 | -------------------------------------------------------------------------------- /changelogs/server_server/pyproject.toml: -------------------------------------------------------------------------------- 1 | [tool.towncrier] 2 | filename = "../server_server.rst" 3 | directory = "newsfragments" 4 | issue_format = "`#{issue} `_" 5 | title_format = "{version}" 6 | 7 | [[tool.towncrier.type]] 8 | directory = "breaking" 9 | name = "Breaking Changes" 10 | showcontent = true 11 | 12 | [[tool.towncrier.type]] 13 | directory = "deprecation" 14 | name = "Deprecations" 15 | showcontent = true 16 | 17 | [[tool.towncrier.type]] 18 | directory = "new" 19 | name = "New Endpoints" 20 | showcontent = true 21 | 22 | [[tool.towncrier.type]] 23 | directory = "removal" 24 | name = "Removed Endpoints" 25 | showcontent = true 26 | 27 | [[tool.towncrier.type]] 28 | directory = "feature" 29 | name = "Backwards Compatible Changes" 30 | showcontent = true 31 | 32 | [[tool.towncrier.type]] 33 | directory = "clarification" 34 | name = "Spec Clarifications" 35 | showcontent = true 36 | -------------------------------------------------------------------------------- /changelogs/identity_service/pyproject.toml: -------------------------------------------------------------------------------- 1 | [tool.towncrier] 2 | filename = "../identity_service.rst" 3 | directory = "newsfragments" 4 | issue_format = "`#{issue} `_" 5 | title_format = "{version}" 6 | 7 | [[tool.towncrier.type]] 8 | directory = "breaking" 9 | name = "Breaking Changes" 10 | showcontent = true 11 | 12 | [[tool.towncrier.type]] 13 | directory = "deprecation" 14 | name = "Deprecations" 15 | showcontent = true 16 | 17 | [[tool.towncrier.type]] 18 | directory = "new" 19 | name = "New Endpoints" 20 | showcontent = true 21 | 22 | [[tool.towncrier.type]] 23 | directory = "removal" 24 | name = "Removed Endpoints" 25 | showcontent = true 26 | 27 | [[tool.towncrier.type]] 28 | directory = "feature" 29 | name = "Backwards Compatible Changes" 30 | showcontent = true 31 | 32 | [[tool.towncrier.type]] 33 | directory = "clarification" 34 | name = "Spec Clarifications" 35 | showcontent = true 36 | -------------------------------------------------------------------------------- /api/server-server/definitions/unsigned_pdu.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2018-2019 New Vector Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | type: object 15 | title: Unsigned Persistent Data Unit 16 | description: An unsigned persistent data unit (event) 17 | example: 18 | $ref: "../examples/unsigned_pdu.json" 19 | allOf: 20 | - $ref: "unsigned_pdu_base.yaml" 21 | - type: object 22 | properties: 23 | event_id: 24 | type: string 25 | description: The event ID for the PDU. 26 | example: "$a4ecee13e2accdadf56c1025:example.com" 27 | required: 28 | - event_id 29 | -------------------------------------------------------------------------------- /changelogs/application_service/pyproject.toml: -------------------------------------------------------------------------------- 1 | [tool.towncrier] 2 | filename = "../application_service.rst" 3 | directory = "newsfragments" 4 | issue_format = "`#{issue} `_" 5 | title_format = "{version}" 6 | 7 | [[tool.towncrier.type]] 8 | directory = "breaking" 9 | name = "Breaking Changes" 10 | showcontent = true 11 | 12 | [[tool.towncrier.type]] 13 | directory = "deprecation" 14 | name = "Deprecations" 15 | showcontent = true 16 | 17 | [[tool.towncrier.type]] 18 | directory = "new" 19 | name = "New Endpoints" 20 | showcontent = true 21 | 22 | [[tool.towncrier.type]] 23 | directory = "removal" 24 | name = "Removed Endpoints" 25 | showcontent = true 26 | 27 | [[tool.towncrier.type]] 28 | directory = "feature" 29 | name = "Backwards Compatible Changes" 30 | showcontent = true 31 | 32 | [[tool.towncrier.type]] 33 | directory = "clarification" 34 | name = "Spec Clarifications" 35 | showcontent = true 36 | -------------------------------------------------------------------------------- /event-schemas/schema/m.room.encryption: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/state_event.yaml 4 | description: Defines how messages sent in this room should be encrypted. 5 | properties: 6 | content: 7 | properties: 8 | algorithm: 9 | type: string 10 | enum: 11 | - "m.megolm.v1.aes-sha2" 12 | description: |- 13 | The encryption algorithm to be used to encrypt messages sent in this 14 | room. 15 | rotation_period_ms: 16 | type: integer 17 | description: |- 18 | How long the session should be used before changing it. ``604800000`` 19 | (a week) is the recommended default. 20 | rotation_period_msgs: 21 | type: integer 22 | description: |- 23 | How many messages should be sent before changing the session. ``100`` is the 24 | recommended default. 25 | required: 26 | - algorithm 27 | type: object 28 | state_key: 29 | description: A zero-length string. 30 | pattern: '^$' 31 | type: string 32 | type: 33 | enum: 34 | - m.room.encryption 35 | type: string 36 | type: object 37 | -------------------------------------------------------------------------------- /event-schemas/schema/m.room.name: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/state_event.yaml 4 | description: |- 5 | A room has an opaque room ID which is not human-friendly to read. A room 6 | alias is human-friendly, but not all rooms have room aliases. The room name 7 | is a human-friendly string designed to be displayed to the end-user. The 8 | room name is not unique, as multiple rooms can have the same room name set. 9 | 10 | A room with an ``m.room.name`` event with an absent, null, or empty 11 | ``name`` field should be treated the same as a room with no ``m.room.name`` 12 | event. 13 | 14 | An event of this type is automatically created when creating a room using 15 | ``/createRoom`` with the ``name`` key. 16 | properties: 17 | content: 18 | properties: 19 | name: 20 | description: The name of the room. This MUST NOT exceed 255 bytes. 21 | type: string 22 | required: 23 | - name 24 | type: object 25 | state_key: 26 | description: A zero-length string. 27 | pattern: '^$' 28 | type: string 29 | type: 30 | enum: 31 | - m.room.name 32 | type: string 33 | title: RoomName 34 | type: object 35 | -------------------------------------------------------------------------------- /specification/modules/event_context.rst: -------------------------------------------------------------------------------- 1 | .. Copyright 2016 OpenMarket Ltd 2 | .. 3 | .. Licensed under the Apache License, Version 2.0 (the "License"); 4 | .. you may not use this file except in compliance with the License. 5 | .. You may obtain a copy of the License at 6 | .. 7 | .. http://www.apache.org/licenses/LICENSE-2.0 8 | .. 9 | .. Unless required by applicable law or agreed to in writing, software 10 | .. distributed under the License is distributed on an "AS IS" BASIS, 11 | .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | .. See the License for the specific language governing permissions and 13 | .. limitations under the License. 14 | 15 | Event Context 16 | ============= 17 | 18 | .. _module:event-context: 19 | 20 | This API returns a number of events that happened just before and after the 21 | specified event. This allows clients to get the context surrounding an event. 22 | 23 | Client behaviour 24 | ---------------- 25 | 26 | There is a single HTTP API for retrieving event context, documented below. 27 | 28 | {{event_context_cs_http_api}} 29 | 30 | Security considerations 31 | ----------------------- 32 | 33 | The server must only return results that the user has permission to see. 34 | -------------------------------------------------------------------------------- /api/application-service/definitions/location.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2018 New Vector Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | properties: 15 | alias: 16 | description: An alias for a matrix room. 17 | type: string 18 | example: "#freenode_#matrix:matrix.org" 19 | protocol: 20 | description: The protocol ID that the third party location is a part of. 21 | type: string 22 | example: "irc" 23 | fields: 24 | description: Information used to identify this third party location. 25 | type: object 26 | example: { 27 | "network": "freenode", 28 | "channel": "#matrix" 29 | } 30 | required: ['alias', 'protocol', 'fields'] 31 | title: Location 32 | type: object -------------------------------------------------------------------------------- /event-schemas/moderation_policy_rule.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2020 The Matrix.org Foundation C.I.C. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | properties: 15 | entity: 16 | description: |- 17 | The entity affected by this rule. Glob characters ``*`` and ``?`` can be used 18 | to match zero or more and one or more characters respectively. 19 | type: string 20 | recommendation: 21 | description: The suggested action to take. Currently only ``m.ban`` is specified. 22 | type: string 23 | reason: 24 | description: The human-readable description for the ``recommendation``. 25 | type: string 26 | type: object 27 | required: 28 | - entity 29 | - recommendation 30 | - reason 31 | -------------------------------------------------------------------------------- /api/client-server/definitions/errors/rate_limited.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2018 New Vector Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | $ref: error.yaml 15 | type: object 16 | description: The rate limit was reached for this request 17 | properties: 18 | errcode: 19 | type: string 20 | description: The M_LIMIT_EXCEEDED error code 21 | example: M_LIMIT_EXCEEDED 22 | error: 23 | type: string 24 | description: A human-readable error message. 25 | example: Too many requests 26 | retry_after_ms: 27 | type: integer 28 | description: |- 29 | The amount of time in milliseconds the client should wait 30 | before trying the request again. 31 | example: 2000 32 | required: ["errcode"] -------------------------------------------------------------------------------- /event-schemas/schema/m.room.message$m.emote: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/room_event.yaml 4 | description: "This message is similar to ``m.text`` except that the sender is 'performing' the action contained in the ``body`` key, similar to ``/me`` in IRC. This message should be prefixed by the name of the sender. This message could also be represented in a different colour to distinguish it from regular ``m.text`` messages." 5 | properties: 6 | content: 7 | properties: 8 | body: 9 | description: The emote action to perform. 10 | type: string 11 | msgtype: 12 | enum: 13 | - m.emote 14 | type: string 15 | format: 16 | description: |- 17 | The format used in the ``formatted_body``. Currently only 18 | ``org.matrix.custom.html`` is supported. 19 | type: string 20 | formatted_body: 21 | description: |- 22 | The formatted version of the ``body``. This is required if ``format`` 23 | is specified. 24 | type: string 25 | required: 26 | - msgtype 27 | - body 28 | type: object 29 | type: 30 | enum: 31 | - m.room.message 32 | type: string 33 | title: EmoteMessage 34 | type: object 35 | -------------------------------------------------------------------------------- /event-schemas/schema/m.room.message$m.server_notice: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/room_event.yaml 4 | description: Represents a server notice for a user. 5 | properties: 6 | content: 7 | properties: 8 | body: 9 | description: A human-readable description of the notice. 10 | type: string 11 | msgtype: 12 | enum: 13 | - m.server_notice 14 | type: string 15 | server_notice_type: 16 | description: |- 17 | The type of notice being represented. 18 | type: string 19 | admin_contact: 20 | description: |- 21 | A URI giving a contact method for the server administrator. Required if the 22 | notice type is ``m.server_notice.usage_limit_reached``. 23 | type: string 24 | limit_type: 25 | description: |- 26 | The kind of usage limit the server has exceeded. Required if the notice type is 27 | ``m.server_notice.usage_limit_reached``. 28 | type: string 29 | required: 30 | - msgtype 31 | - body 32 | - server_notice_type 33 | type: object 34 | type: 35 | enum: 36 | - m.room.message 37 | type: string 38 | title: ServerNoticeMessage 39 | type: object 40 | -------------------------------------------------------------------------------- /event-schemas/schema/m.room.canonical_alias: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/state_event.yaml 4 | description: |- 5 | This event is used to inform the room about which alias should be 6 | considered the canonical one, and which other aliases point to the room. 7 | This could be for display purposes or as suggestion to users which alias 8 | to use to advertise and access the room. 9 | properties: 10 | content: 11 | properties: 12 | alias: 13 | description: | 14 | The canonical alias for the room. If not present, null, or empty the 15 | room should be considered to have no canonical alias. 16 | type: string 17 | alt_aliases: 18 | description: | 19 | Alternative aliases the room advertises. This list can have aliases 20 | despite the ``alias`` field being null, empty, or otherwise not present. 21 | type: array 22 | items: 23 | type: string 24 | type: object 25 | state_key: 26 | description: A zero-length string. 27 | pattern: '^$' 28 | type: string 29 | type: 30 | enum: 31 | - m.room.canonical_alias 32 | type: string 33 | title: Informs the room as to which alias is the canonical one. 34 | type: object 35 | -------------------------------------------------------------------------------- /api/application-service/definitions/user.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2018 New Vector Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | # TODO: Change userid to user_id as a breaking change 16 | properties: 17 | userid: 18 | description: A Matrix User ID represting a third party user. 19 | type: string 20 | example: "@_gitter_jim:matrix.org" 21 | protocol: 22 | description: The protocol ID that the third party location is a part of. 23 | type: string 24 | example: "gitter" 25 | fields: 26 | description: Information used to identify this third party location. 27 | type: object 28 | example: { 29 | "user": "jim" 30 | } 31 | required: ['userid', 'protocol', 'fields'] 32 | title: User 33 | type: object -------------------------------------------------------------------------------- /drafts/ancient_federated_versioning_design_notes.rst: -------------------------------------------------------------------------------- 1 | Versioning is, like, hard for backfilling backwards because of the number of homeservers involved. 2 | 3 | The way we solve this is by doing versioning as an acyclic directed graph of PDUs. For backfilling purposes, this is done on a per context basis. 4 | When we send a PDU we include all PDUs that have been received for that context that hasn't been subsequently listed in a later PDU. The trivial case is a simple list of PDUs, e.g. A <- B <- C. However, if two servers send out a PDU at the same to, both B and C would point at A - a later PDU would then list both B and C. 5 | 6 | Problems with opaque version strings: 7 | - How do you do clustering without mandating that a cluster can only have one transaction in flight to a given remote homeserver at a time. 8 | If you have multiple transactions sent at once, then you might drop one transaction, receive another with a version that is later than the dropped transaction and which point ARGH WE LOST A TRANSACTION. 9 | - How do you do backfilling? A version string defines a point in a stream w.r.t. a single homeserver, not a point in the context. 10 | 11 | We only need to store the ends of the directed graph, we DO NOT need to do the whole one table of nodes and one of edges. 12 | -------------------------------------------------------------------------------- /event-schemas/schema/m.key.verification.mac: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/event.yaml 4 | 5 | description: |- 6 | Sends the MAC of a device's key to the partner device. Typically sent as a 7 | `to-device`_ event. 8 | properties: 9 | content: 10 | properties: 11 | transaction_id: 12 | type: string 13 | description: |- 14 | An opaque identifier for the verification process. Must be the same as 15 | the one used for the ``m.key.verification.start`` message. 16 | mac: 17 | type: object 18 | description: |- 19 | A map of the key ID to the MAC of the key, using the algorithm in the 20 | verification process. The MAC is encoded as unpadded base64. 21 | additionalProperties: 22 | type: string 23 | description: The key's MAC, encoded as unpadded base64. 24 | keys: 25 | type: string 26 | description: |- 27 | The MAC of the comma-separated, sorted, list of key IDs given in the ``mac`` 28 | property, encoded as unpadded base64. 29 | required: 30 | - transaction_id 31 | - mac 32 | - keys 33 | type: object 34 | type: 35 | enum: 36 | - m.key.verification.mac 37 | type: string 38 | type: object 39 | -------------------------------------------------------------------------------- /api/client-server/definitions/auth_data.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2016 OpenMarket Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | title: Authentication Data 15 | description: |- 16 | Used by clients to submit authentication information to the interactive-authentication API 17 | type: object 18 | properties: 19 | type: 20 | description: The login type that the client is attempting to complete. 21 | type: string 22 | session: 23 | description: The value of the session key given by the homeserver. 24 | type: string 25 | additionalProperties: 26 | description: Keys dependent on the login type 27 | type: object 28 | required: 29 | - type 30 | example: 31 | type: "example.type.foo" 32 | session: "xxxxx" 33 | example_credential: "verypoorsharedsecret" 34 | -------------------------------------------------------------------------------- /event-schemas/schema/m.room.message$m.image: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/room_event.yaml 4 | description: This message represents a single image and an optional thumbnail. 5 | properties: 6 | content: 7 | properties: 8 | body: 9 | description: "A textual representation of the image. This could be the alt text of the image, the filename of the image, or some kind of content description for accessibility e.g. 'image attachment'." 10 | type: string 11 | info: 12 | allOf: 13 | - $ref: core-event-schema/msgtype_infos/image_info.yaml 14 | description: Metadata about the image referred to in ``url``. 15 | msgtype: 16 | enum: 17 | - m.image 18 | type: string 19 | url: 20 | description: |- 21 | Required if the file is unencrypted. The URL (typically `MXC URI`_) 22 | to the image. 23 | type: string 24 | file: 25 | description: |- 26 | Required if the file is encrypted. Information on the encrypted 27 | file, as specified in |encrypted_files|_. 28 | title: EncryptedFile 29 | type: object 30 | required: 31 | - msgtype 32 | - body 33 | type: object 34 | type: 35 | enum: 36 | - m.room.message 37 | type: string 38 | title: ImageMessage 39 | type: object 40 | -------------------------------------------------------------------------------- /drafts/object_model.rst: -------------------------------------------------------------------------------- 1 | ..TODO 2 | What are the start & end tokens doing here?! 3 | 4 | :: 5 | 6 | +---------------+ 7 | | Room | 8 | | "Room-ID" | 9 | | {State} | +----------------------+ 10 | | Name------|-------->| Event m.room.name | 11 | | Topic | | "Name" | 12 | | [Aliases] | +----------------------+ +-------------+ 13 | | [Members]-|---+ +----------------------+ <----| Start Token | 14 | | [Messages] | | | Event m.room.member | +-------------+ 15 | | | | | +---->| "invite/join/ban" | 16 | +---------------+ | "User-ID" | 17 | | | +----------------------+ 18 | | | +----------------------+ 19 | | | Message | Event m.room.message | 20 | | +-------------->| {content} |<--+ 21 | | +----------------------+ | 22 | | Comment +----------------------+ | 23 | +------------------>| Event m.room.message | | 24 | | {content} | | 25 | | "relates-to"-------|---+ +-------------+ 26 | +----------------------+ <----| End Token | 27 | +-------------+ 28 | -------------------------------------------------------------------------------- /event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml: -------------------------------------------------------------------------------- 1 | $schema: http://json-schema.org/draft-04/schema# 2 | description: Metadata about an image. 3 | properties: 4 | h: 5 | description: |- 6 | The intended display height of the image in pixels. This may 7 | differ from the intrinsic dimensions of the image file. 8 | type: integer 9 | w: 10 | description: |- 11 | The intended display width of the image in pixels. This may 12 | differ from the intrinsic dimensions of the image file. 13 | type: integer 14 | mimetype: 15 | description: The mimetype of the image, e.g. ``image/jpeg``. 16 | type: string 17 | size: 18 | description: Size of the image in bytes. 19 | type: integer 20 | thumbnail_url: 21 | description: |- 22 | The URL (typically `MXC URI`_) to a thumbnail of the image. 23 | Only present if the thumbnail is unencrypted. 24 | type: string 25 | thumbnail_file: 26 | description: |- 27 | Information on the encrypted thumbnail file, as specified in 28 | |encrypted_files|_. Only present if the thumbnail is encrypted. 29 | title: EncryptedFile 30 | type: object 31 | thumbnail_info: 32 | allOf: 33 | - $ref: thumbnail_info.yaml 34 | description: Metadata about the image referred to in ``thumbnail_url``. 35 | title: ImageInfo 36 | type: object 37 | -------------------------------------------------------------------------------- /event-schemas/schema/m.room.message$m.notice: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/room_event.yaml 4 | description: 'The ``m.notice`` type is primarily intended for responses from automated clients. An ``m.notice`` message must be treated the same way as a regular ``m.text`` message with two exceptions. Firstly, clients should present ``m.notice`` messages to users in a distinct manner, and secondly, ``m.notice`` messages must never be automatically responded to. This helps to prevent infinite-loop situations where two automated clients continuously exchange messages.' 5 | properties: 6 | content: 7 | properties: 8 | body: 9 | description: The notice text to send. 10 | type: string 11 | msgtype: 12 | enum: 13 | - m.notice 14 | type: string 15 | format: 16 | description: |- 17 | The format used in the ``formatted_body``. Currently only 18 | ``org.matrix.custom.html`` is supported. 19 | type: string 20 | formatted_body: 21 | description: |- 22 | The formatted version of the ``body``. This is required if ``format`` 23 | is specified. 24 | type: string 25 | required: 26 | - msgtype 27 | - body 28 | type: object 29 | type: 30 | enum: 31 | - m.room.message 32 | type: string 33 | title: NoticeMessage 34 | type: object 35 | -------------------------------------------------------------------------------- /api/client-server/definitions/room_key_backup.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2020 The Matrix.org Foundation C.I.C. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | type: object 16 | title: RoomKeyBackup 17 | description: "The backed up keys for a room." 18 | properties: 19 | sessions: 20 | type: object 21 | description: "A map of session IDs to key data." 22 | additionalProperties: 23 | allOf: 24 | - $ref: "key_backup_data.yaml" 25 | example: { 26 | "sessionid1": { 27 | "first_message_index": 1, 28 | "forwarded_count": 0, 29 | "is_verified": true, 30 | "session_data": { 31 | "ephemeral": "base64+ephemeral+key", 32 | "ciphertext": "base64+ciphertext+of+JSON+data", 33 | "mac": "base64+mac+of+ciphertext" 34 | } 35 | } 36 | } 37 | required: 38 | - sessions 39 | -------------------------------------------------------------------------------- /scripts/templating/batesian/__init__.py: -------------------------------------------------------------------------------- 1 | # Copyright 2016 OpenMarket Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | 16 | class AccessKeyStore(object): 17 | """Storage for arbitrary data. Monitors get calls so we know if they 18 | were used or not.""" 19 | 20 | def __init__(self, existing_data=None): 21 | if not existing_data: 22 | existing_data = {} 23 | self.data = existing_data 24 | self.accessed_set = set() 25 | 26 | def keys(self): 27 | return self.data.keys() 28 | 29 | def add(self, key, unit_dict): 30 | self.data[key] = unit_dict 31 | 32 | def get(self, key): 33 | self.accessed_set.add(key) 34 | return self.data[key] 35 | 36 | def get_unaccessed_set(self): 37 | data_list = set(self.data.keys()) 38 | return data_list - self.accessed_set -------------------------------------------------------------------------------- /specification/modules.rst: -------------------------------------------------------------------------------- 1 | .. Copyright 2016 OpenMarket Ltd 2 | .. Copyright 2019 The Matrix.org Foundation C.I.C. 3 | .. 4 | .. Licensed under the Apache License, Version 2.0 (the "License"); 5 | .. you may not use this file except in compliance with the License. 6 | .. You may obtain a copy of the License at 7 | .. 8 | .. http://www.apache.org/licenses/LICENSE-2.0 9 | .. 10 | .. Unless required by applicable law or agreed to in writing, software 11 | .. distributed under the License is distributed on an "AS IS" BASIS, 12 | .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | .. See the License for the specific language governing permissions and 14 | .. limitations under the License. 15 | 16 | Modules 17 | ======= 18 | 19 | Modules are parts of the Client-Server API which are not universal to all 20 | endpoints. Modules are strictly defined within this specification and 21 | should not be mistaken for experimental extensions or optional features. 22 | A compliant server implementation MUST support all modules and supporting 23 | specification (unless the implementation only targets clients of certain 24 | profiles, in which case only the required modules for those feature profiles 25 | MUST be implemented). A compliant client implementation MUST support all 26 | the required modules and supporting specification for the `Feature Profile <#feature-profiles>`_ 27 | it targets. 28 | -------------------------------------------------------------------------------- /event-schemas/schema/m.key.verification.request: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/event.yaml 4 | 5 | description: |- 6 | Requests a key verification with another user's devices. Typically sent as a 7 | `to-device`_ event. 8 | properties: 9 | content: 10 | properties: 11 | from_device: 12 | type: string 13 | description: |- 14 | The device ID which is initiating the request. 15 | transaction_id: 16 | type: string 17 | description: |- 18 | An opaque identifier for the verification request. Must be unique 19 | with respect to the devices involved. 20 | methods: 21 | type: array 22 | description: |- 23 | The verification methods supported by the sender. 24 | items: 25 | type: string 26 | timestamp: 27 | type: integer 28 | format: int64 29 | description: |- 30 | The POSIX timestamp in milliseconds for when the request was made. If 31 | the request is in the future by more than 5 minutes or more than 10 32 | minutes in the past, the message should be ignored by the receiver. 33 | required: 34 | - from_device 35 | - transaction_id 36 | - methods 37 | - timestamp 38 | type: object 39 | type: 40 | enum: 41 | - m.key.verification.request 42 | type: string 43 | type: object 44 | -------------------------------------------------------------------------------- /api/server-server/definitions/single_pdu_transaction.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2019 The Matrix.org Foundation C.I.C. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | type: object 15 | allOf: 16 | - $ref: "transaction.yaml" 17 | properties: 18 | pdus: 19 | type: array 20 | description: |- 21 | A single PDU. Note that events have a different format depending on the room 22 | version - check the `room version specification`_ for precise event formats. 23 | items: 24 | type: object 25 | title: PDU 26 | description: |- 27 | The `PDUs <#pdus>`_ contained in the transaction. The event format varies depending 28 | on the room version - check the `room version specification`_ for precise event formats. 29 | properties: [] 30 | example: 31 | $ref: "../examples/minimal_pdu.json" 32 | required: ['origin', 'origin_server_ts', 'pdus'] 33 | -------------------------------------------------------------------------------- /specification/modules/report_content.rst: -------------------------------------------------------------------------------- 1 | .. Copyright 2018 Travis Ralston 2 | .. 3 | .. Licensed under the Apache License, Version 2.0 (the "License"); 4 | .. you may not use this file except in compliance with the License. 5 | .. You may obtain a copy of the License at 6 | .. 7 | .. http://www.apache.org/licenses/LICENSE-2.0 8 | .. 9 | .. Unless required by applicable law or agreed to in writing, software 10 | .. distributed under the License is distributed on an "AS IS" BASIS, 11 | .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | .. See the License for the specific language governing permissions and 13 | .. limitations under the License. 14 | 15 | Reporting Content 16 | ================= 17 | 18 | .. _module:report_content: 19 | 20 | Users may encounter content which they find inappropriate and should be able 21 | to report it to the server administrators or room moderators for review. This 22 | module defines a way for users to report content. 23 | 24 | Content is reported based upon a negative score, where -100 is "most offensive" 25 | and 0 is "inoffensive". 26 | 27 | Client behaviour 28 | ---------------- 29 | {{report_content_cs_http_api}} 30 | 31 | Server behaviour 32 | ---------------- 33 | Servers are free to handle the reported content however they desire. This may 34 | be a dedicated room to alert server administrators to the reported content or 35 | some other mechanism for notifying the appropriate people. 36 | -------------------------------------------------------------------------------- /api/client-server/definitions/push_ruleset.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2016 OpenMarket Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | properties: 15 | content: 16 | items: 17 | allOf: 18 | - $ref: push_rule.yaml 19 | title: PushRule 20 | type: object 21 | type: array 22 | override: 23 | items: 24 | allOf: 25 | - $ref: push_rule.yaml 26 | title: PushRule 27 | type: object 28 | type: array 29 | room: 30 | items: 31 | allOf: 32 | - $ref: push_rule.yaml 33 | title: PushRule 34 | type: object 35 | type: array 36 | sender: 37 | items: 38 | allOf: 39 | - $ref: push_rule.yaml 40 | title: PushRule 41 | type: object 42 | type: array 43 | underride: 44 | items: 45 | allOf: 46 | - $ref: push_rule.yaml 47 | title: PushRule 48 | type: object 49 | type: array 50 | type: object 51 | -------------------------------------------------------------------------------- /api/server-server/definitions/unlimited_pdu_transaction.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2019 The Matrix.org Foundation C.I.C. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | type: object 15 | allOf: 16 | - $ref: "transaction.yaml" 17 | properties: 18 | pdus: 19 | type: array 20 | description: |- 21 | List of persistent updates to rooms. Note that events have a different format 22 | depending on the room version - check the `room version specification`_ for 23 | precise event formats. 24 | items: 25 | type: object 26 | title: PDU 27 | description: |- 28 | The `PDUs <#pdus>`_ contained in the transaction. The event format varies depending 29 | on the room version - check the `room version specification`_ for precise event formats. 30 | properties: [] 31 | example: 32 | $ref: "../examples/minimal_pdu.json" 33 | required: ['origin', 'origin_server_ts', 'pdus'] 34 | -------------------------------------------------------------------------------- /api/client-server/definitions/wellknown/full.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2019 New Vector Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | title: Discovery Information 15 | description: |- 16 | Used by clients to determine the homeserver, identity server, and other 17 | optional components they should be interacting with. 18 | type: object 19 | properties: 20 | "m.homeserver": 21 | $ref: "homeserver.yaml" 22 | "m.identity_server": 23 | $ref: "identity_server.yaml" 24 | additionalProperties: 25 | type: object 26 | description: Application-dependent keys using Java package naming convention. 27 | required: 28 | - m.homeserver 29 | example: { 30 | "m.homeserver": { 31 | "base_url": "https://matrix.example.com" 32 | }, 33 | "m.identity_server": { 34 | "base_url": "https://identity.example.com" 35 | }, 36 | "org.example.custom.property": { 37 | "app_url": "https://custom.app.example.org" 38 | } 39 | } 40 | -------------------------------------------------------------------------------- /proposals/2334-default-room-version-v5.md: -------------------------------------------------------------------------------- 1 | # [MSC2334](https://github.com/matrix-org/matrix-doc/pull/2334) - Change default room version to v5 2 | 3 | This MSC proposes changing the recommended default room version from v4 to v5. 4 | This implements steps 5 and 6 of the plan from 5 | [MSC2002](https://github.com/matrix-org/matrix-doc/issues/2002). 6 | 7 | Room version 5 enforces the `valid_until_ts` timestamp on signing keys as 8 | proposed in [MSC2076](https://github.com/matrix-org/matrix-doc/issues/2076). 9 | 10 | ## Proposal 11 | 12 | When [MSC2077](https://github.com/matrix-org/matrix-doc/issues/2077) proposed 13 | room version 5, the default version continued to be v4 to allow old servers to 14 | continue to chat in newly created rooms. Server-Server API r0.1.2 (which 15 | contains the details on room version 5) and Synapse 1.0.0 (with support for room 16 | version 5) were both released more than 4 months ago which has given people 17 | plenty of time to update. Room version 5 should be the default room version so 18 | that newly created rooms enforce key-validity periods. 19 | 20 | ## Potential issues 21 | 22 | Servers which do not support room version 5 will not be able to participate in 23 | newly created rooms on other servers. Hopefully this will encourage them to 24 | update their server. 25 | 26 | ## Security considerations 27 | 28 | Room version 5 fixes known security vulnerabilities but that doesn't do much 29 | good if newly created rooms aren't using room version 5 by default. -------------------------------------------------------------------------------- /proposals/1831-srv-after-wellknown.md: -------------------------------------------------------------------------------- 1 | # Proposal to do SRV lookups after .well-known to discover homeservers 2 | 3 | Currently there is a logistical error proposed by [MSC1708](https://github.com/matrix-org/matrix-doc/pull/1708) 4 | which results in some homeservers unable to migrate to the new functionality 5 | proposed by [MSC1711](https://github.com/matrix-org/matrix-doc/pull/1711). This 6 | can happen if the delegated homeserver cannot obtain a valid TLS certificate for 7 | the domain, and an SRV record is used for backwards compatibility reasons. 8 | 9 | Specifically, in order to be compatible with requests from both Synapse 0.34 and 1.0, 10 | servers can have both a SRV and a .well-known file, with Synapse presenting a certificate 11 | corresponding to the target of the .well-known. Synapse 0.34 is then happy because it 12 | will follow the SRV (and won't care about the incorrect certificate); Synapse 1.0 is 13 | happy because it will follow the .well-known (and will see the correct cert). 14 | 15 | ## Proposal 16 | 17 | We change the order of operations to perform a .well-known lookup before falling 18 | back to resolving the SRV record. This allows for domains to delegate to other 19 | hostnames and maintains backwards compatibility with older homeservers. 20 | 21 | ## Tradeoffs 22 | 23 | More HTTP hits will be made due to the .well-known lookup being first. This is 24 | somewhat mitigated by servers caching the responses appropriately, and using 25 | connection pools where possible. 26 | -------------------------------------------------------------------------------- /event-schemas/schema/m.room.create: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/state_event.yaml 4 | description: This is the first event in a room and cannot be changed. It acts as the root of all other events. 5 | properties: 6 | content: 7 | properties: 8 | creator: 9 | description: The ``user_id`` of the room creator. This is set by the homeserver. 10 | type: string 11 | m.federate: 12 | description: Whether users on other servers can join this room. Defaults to ``true`` if key does not exist. 13 | type: boolean 14 | room_version: 15 | description: The version of the room. Defaults to ``"1"`` if the key does not exist. 16 | type: string 17 | predecessor: 18 | description: A reference to the room this room replaces, if the previous room was upgraded. 19 | type: object 20 | title: Previous Room 21 | properties: 22 | room_id: 23 | type: string 24 | description: The ID of the old room. 25 | event_id: 26 | type: string 27 | description: The event ID of the last known event in the old room. 28 | required: [room_id, event_id] 29 | required: 30 | - creator 31 | type: object 32 | state_key: 33 | description: A zero-length string. 34 | pattern: '^$' 35 | type: string 36 | type: 37 | enum: 38 | - m.room.create 39 | type: string 40 | title: The first event in the room. 41 | type: object 42 | -------------------------------------------------------------------------------- /drafts/model/protocol_examples.rst: -------------------------------------------------------------------------------- 1 | PUT /send/abc/ HTTP/1.1 2 | Host: ... 3 | Content-Length: ... 4 | Content-Type: application/json 5 | 6 | .. code :: javascript 7 | 8 | { 9 | "origin": "localhost:5000", 10 | "pdus": [ 11 | { 12 | "content": {}, 13 | "context": "tng", 14 | "depth": 12, 15 | "is_state": false, 16 | "origin": "localhost:5000", 17 | "pdu_id": 1404381396854, 18 | "pdu_type": "feedback", 19 | "prev_pdus": [ 20 | [ 21 | "1404381395883", 22 | "localhost:6000" 23 | ] 24 | ], 25 | "ts": 1404381427581 26 | } 27 | ], 28 | "prev_ids": [ 29 | "1404381396852" 30 | ], 31 | "ts": 1404381427823 32 | } 33 | 34 | HTTP/1.1 200 OK 35 | 36 | 37 | ====================================== 38 | 39 | GET /pull/-1/ HTTP/1.1 40 | Host: ... 41 | Content-Length: 0 42 | 43 | HTTP/1.1 200 OK 44 | Content-Length: ... 45 | Content-Type: application/json 46 | 47 | .. code :: javascript 48 | 49 | { 50 | origin: ..., 51 | prev_ids: ..., 52 | data: [ 53 | { 54 | data_id: ..., 55 | prev_pdus: [...], 56 | depth: ..., 57 | ts: ..., 58 | context: ..., 59 | origin: ..., 60 | content: { 61 | ... 62 | } 63 | }, 64 | ..., 65 | ] 66 | } 67 | 68 | 69 | -------------------------------------------------------------------------------- /proposals/1721-rename-cas-to-sso.md: -------------------------------------------------------------------------------- 1 | # MSC1721: Rename `m.login.cas` to `m.login.sso` 2 | 3 | The Matrix Client-Server spec includes a [section on client login using Central 4 | Authentication Service 5 | (CAS)](https://matrix.org/docs/spec/client_server/r0.4.0.html#cas-based-client-login). 6 | 7 | The spec currently fails to mention it, but this process is triggered when [`GET 8 | /login`](https://matrix.org/docs/spec/client_server/r0.4.0.html#get-matrix-client-r0-login) 9 | returns a flow type of `m.login.cas`. 10 | 11 | Nothing in this flow is specific to CAS - it is equally applicable for other 12 | web-based single-sign-on processes, such as SAML. 13 | 14 | Accordingly, we should rename `cas` to `sso`. 15 | 16 | ## Proposal 17 | 18 | 1. `m.login.sso` should be defined as a valid login type for return from `GET 19 | /login`. (We should probably mention `m.login.cas` in the spec while we are 20 | there.) 21 | 22 | 2. When a client wishes to use the SSO login type, it should redirect to 23 | `/_matrix/client/r0/login/sso/redirect` (instead of 24 | `/_matrix/client/r0/login/cas/redirect`). 25 | 26 | 3. Servers should treat `/_matrix/client/r0/login/sso/redirect` identically to 27 | `/_matrix/client/r0/login/cas/redirect`: they should issue a redirect to 28 | their configured single-sign-on system. 29 | 30 | 4. Servers which support `m.login.sso` should make sure they update their [login 31 | fallback page](https://matrix.org/docs/spec/client_server/r0.4.0.html#login-fallback) 32 | to understand the new login type. 33 | -------------------------------------------------------------------------------- /proposals/2284-optional-identity-server-discovery.md: -------------------------------------------------------------------------------- 1 | # MSC2284: Making the identity server optional during discovery 2 | 3 | Currently the specification requires that clients `FAIL_ERROR` (hard failure - do not continue) 4 | when the `.well-known` file for `m.identity_server` points to somewhere invalid or is invalid 5 | itself. This can cause problems for clients if they either don't need an identity server to 6 | function (and are forced to validate it anyways) or the client ends up having to disable all 7 | their login UX because the identity server is misconfigured/down. 8 | 9 | This proposal aims to change that by allowing clients to make a conscious decision to continue 10 | with the invalid identity server configuration, provided the homeserver configuration is valid. 11 | 12 | ## Proposal 13 | 14 | Instead of `FAIL_ERROR` for an invalid `m.identity_server` schema/server, clients are to move 15 | to the `FAIL_PROMPT` (inform the user, ask for input if applicable) state. Clients can decide 16 | to show a warning that the identity server is unavailable and allow the user to continue with 17 | the invalid (or client's default) configuration. 18 | 19 | ## Tradeoffs 20 | 21 | Clients can end up being configured with an invalid or inoperable identity server. This is 22 | considered a feature by this proposal to allow for less intelligent clients to have their 23 | identity server disabled. Intelligent clients could interpret the lack of identity server 24 | as the homeserver/user asking that identity server functionality be disabled in the client. 25 | -------------------------------------------------------------------------------- /api/client-server/definitions/openid_token.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2018 New Vector Ltd 2 | # Copyright 2019 The Matrix.org Foundation C.I.C. 3 | # 4 | # Licensed under the Apache License, Version 2.0 (the "License"); 5 | # you may not use this file except in compliance with the License. 6 | # You may obtain a copy of the License at 7 | # 8 | # http://www.apache.org/licenses/LICENSE-2.0 9 | # 10 | # Unless required by applicable law or agreed to in writing, software 11 | # distributed under the License is distributed on an "AS IS" BASIS, 12 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | # See the License for the specific language governing permissions and 14 | # limitations under the License. 15 | type: object 16 | properties: 17 | access_token: 18 | type: string 19 | description: |- 20 | An access token the consumer may use to verify the identity of 21 | the person who generated the token. This is given to the federation 22 | API ``GET /openid/userinfo`` to verify the user's identity. 23 | token_type: 24 | type: string 25 | description: The string ``Bearer``. 26 | matrix_server_name: 27 | type: string 28 | description: |- 29 | The homeserver domain the consumer should use when attempting to 30 | verify the user's identity. 31 | expires_in: 32 | type: integer 33 | description: |- 34 | The number of seconds before this token expires and a new one must 35 | be generated. 36 | required: ['access_token', 'token_type', 'matrix_server_name', 'expires_in'] 37 | -------------------------------------------------------------------------------- /proposals/1930-tombstone-notifications.md: -------------------------------------------------------------------------------- 1 | # Proposal to add a default push rule for m.room.tombstone events 2 | 3 | Currently users are unaware of when a room becomes upgraded, leaving them potentially in the old room 4 | without knowing until they visit the room again. By having a notification for when the room is upgraded, 5 | users are able to ensure they are able to stay relevant in rooms by joining the upgraded room. 6 | 7 | 8 | ## Proposal 9 | 10 | A new default override rule is to be added which is similar to `@room` notifications: 11 | 12 | ```json 13 | { 14 | "rule_id": ".m.rule.tombstone", 15 | "default": true, 16 | "enabled": true, 17 | "conditions": [ 18 | { 19 | "kind": "event_match", 20 | "key": "type", 21 | "pattern": "m.room.tombstone" 22 | }, 23 | { 24 | "kind": "event_match", 25 | "key": "state_key", 26 | "pattern": "" 27 | } 28 | ], 29 | "actions": [ 30 | "notify", 31 | { 32 | "set_tweak": "highlight", 33 | "value": true 34 | } 35 | ] 36 | } 37 | ``` 38 | 39 | 40 | ## Tradeoffs 41 | 42 | Clients could calculate this on their own and show some sort of "room upgraded" notification instead, 43 | however by doing it this way it means that all clients would need to be aware of room upgrades. Having 44 | a default push rule means that clients get this notification for free. Clients which want a more diverse 45 | UX can still do so by ignoring this push rule locally. 46 | -------------------------------------------------------------------------------- /api/client-server/definitions/client_device.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2016 OpenMarket Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | type: object 16 | description: A client device 17 | title: Device 18 | properties: 19 | device_id: 20 | type: string 21 | description: Identifier of this device. 22 | example: QBUAZIFURK 23 | display_name: 24 | type: string 25 | description: |- 26 | Display name set by the user for this device. Absent if no name has been 27 | set. 28 | example: android 29 | last_seen_ip: 30 | type: string 31 | description: |- 32 | The IP address where this device was last seen. (May be a few minutes out 33 | of date, for efficiency reasons). 34 | example: 1.2.3.4 35 | last_seen_ts: 36 | type: integer 37 | format: int64 38 | description: |- 39 | The timestamp (in milliseconds since the unix epoch) when this devices 40 | was last seen. (May be a few minutes out of date, for efficiency 41 | reasons). 42 | example: 1474491775024 43 | required: 44 | - device_id 45 | -------------------------------------------------------------------------------- /event-schemas/schema/core-event-schema/unsigned_prop.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2020 The Matrix.org Foundation C.I.C. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | title: UnsignedData 16 | type: object 17 | description: Contains optional extra information about the event. 18 | properties: 19 | age: 20 | description: The time in milliseconds that has elapsed since the event was 21 | sent. This field is generated by the local homeserver, and may be incorrect 22 | if the local time on at least one of the two servers is out of sync, which can 23 | cause the age to either be negative or greater than it actually is. 24 | type: integer 25 | redacted_because: 26 | description: The event that redacted this event, if any. 27 | title: Event 28 | type: object 29 | transaction_id: 30 | description: | 31 | The client-supplied transaction ID, for example, provided via 32 | ``PUT /_matrix/client/r0/rooms/{roomId}/send/{eventType}/{txnId}``, 33 | if the client being given the event is the same one which sent it. 34 | type: string 35 | -------------------------------------------------------------------------------- /event-schemas/schema/m.key.verification.start: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/event.yaml 4 | 5 | description: |- 6 | Begins a key verification process. Typically sent as a `to-device`_ event. The ``method`` 7 | field determines the type of verification. The fields in the event will differ depending 8 | on the ``method``. This definition includes fields that are in common among all variants. 9 | properties: 10 | content: 11 | properties: 12 | from_device: 13 | type: string 14 | description: |- 15 | The device ID which is initiating the process. 16 | transaction_id: 17 | type: string 18 | description: |- 19 | An opaque identifier for the verification process. Must be unique 20 | with respect to the devices involved. Must be the same as the 21 | ``transaction_id`` given in the ``m.key.verification.request`` 22 | if this process is originating from a request. 23 | method: 24 | type: string 25 | description: |- 26 | The verification method to use. 27 | next_method: 28 | type: string 29 | description: |- 30 | Optional method to use to verify the other user's key with. Applicable 31 | when the ``method`` chosen only verifies one user's key. This field will 32 | never be present if the ``method`` verifies keys both ways. 33 | required: 34 | - from_device 35 | - transaction_id 36 | - method 37 | type: object 38 | type: 39 | enum: 40 | - m.key.verification.start 41 | type: string 42 | type: object 43 | -------------------------------------------------------------------------------- /event-schemas/schema/m.call.hangup: -------------------------------------------------------------------------------- 1 | { 2 | "type": "object", 3 | "description": "Sent by either party to signal their termination of the call. This can be sent either once the call has has been established or before to abort the call.", 4 | "allOf": [{ 5 | "$ref": "core-event-schema/room_event.yaml" 6 | }], 7 | "properties": { 8 | "content": { 9 | "type": "object", 10 | "properties": { 11 | "call_id": { 12 | "type": "string", 13 | "description": "The ID of the call this event relates to." 14 | }, 15 | "version": { 16 | "type": "integer", 17 | "description": "The version of the VoIP specification this message adheres to. This specification is version 0." 18 | }, 19 | "reason": { 20 | "type": "string", 21 | "description": "Optional error reason for the hangup. This should not be provided when the user naturally ends or rejects the call. When there was an error in the call negotiation, this should be ``ice_failed`` for when ICE negotiation fails or ``invite_timeout`` for when the other party did not answer in time.", 22 | "enum": [ 23 | "ice_failed", 24 | "invite_timeout" 25 | ] 26 | } 27 | }, 28 | "required": ["call_id", "version"] 29 | }, 30 | "type": { 31 | "type": "string", 32 | "enum": ["m.call.hangup"] 33 | } 34 | } 35 | } 36 | -------------------------------------------------------------------------------- /api/client-server/definitions/request_email_validation.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2019 The Matrix.org Foundation C.I.C. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | type: object 15 | allOf: 16 | - $ref: "../../identity/definitions/request_email_validation.yaml" 17 | - type: object 18 | properties: 19 | id_server: 20 | type: string 21 | description: |- 22 | The hostname of the identity server to communicate with. May optionally 23 | include a port. This parameter is ignored when the homeserver handles 24 | 3PID verification. 25 | 26 | This parameter is deprecated with a plan to be removed in a future specification 27 | version for ``/account/password`` and ``/register`` requests. 28 | example: "id.example.com" 29 | id_access_token: 30 | type: string 31 | description: |- 32 | An access token previously registered with the identity server. Servers 33 | can treat this as optional to distinguish between r0.5-compatible clients 34 | and this specification version. 35 | 36 | Required if an ``id_server`` is supplied. 37 | -------------------------------------------------------------------------------- /api/client-server/definitions/request_msisdn_validation.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2019 The Matrix.org Foundation C.I.C. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | type: object 15 | allOf: 16 | - $ref: "../../identity/definitions/request_msisdn_validation.yaml" 17 | - type: object 18 | properties: 19 | id_server: 20 | type: string 21 | description: |- 22 | The hostname of the identity server to communicate with. May optionally 23 | include a port. This parameter is ignored when the homeserver handles 24 | 3PID verification. 25 | 26 | This parameter is deprecated with a plan to be removed in a future specification 27 | version for ``/account/password`` and ``/register`` requests. 28 | example: "id.example.com" 29 | id_access_token: 30 | type: string 31 | description: |- 32 | An access token previously registered with the identity server. Servers 33 | can treat this as optional to distinguish between r0.5-compatible clients 34 | and this specification version. 35 | 36 | Required if an ``id_server`` is supplied. 37 | -------------------------------------------------------------------------------- /event-schemas/schema/m.room.message$m.location: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/room_event.yaml 4 | description: This message represents a real-world location. 5 | properties: 6 | content: 7 | properties: 8 | body: 9 | description: "A description of the location e.g. 'Big Ben, London, UK', or some kind of content description for accessibility e.g. 'location attachment'." 10 | type: string 11 | geo_uri: 12 | description: A geo URI representing this location. 13 | type: string 14 | msgtype: 15 | enum: 16 | - m.location 17 | type: string 18 | info: 19 | type: object 20 | properties: 21 | thumbnail_url: 22 | description: |- 23 | The URL to the thumbnail of the file. Only present if the 24 | thumbnail is unencrypted. 25 | type: string 26 | thumbnail_file: 27 | description: |- 28 | Information on the encrypted thumbnail file, as specified in 29 | |encrypted_files|_. Only present if the thumbnail is encrypted. 30 | title: EncryptedFile 31 | type: object 32 | thumbnail_info: 33 | allOf: 34 | - $ref: core-event-schema/msgtype_infos/thumbnail_info.yaml 35 | description: Metadata about the image referred to in ``thumbnail_url``. 36 | title: LocationInfo 37 | required: 38 | - msgtype 39 | - body 40 | - geo_uri 41 | type: object 42 | type: 43 | enum: 44 | - m.room.message 45 | type: string 46 | title: LocationMessage 47 | type: object 48 | -------------------------------------------------------------------------------- /event-schemas/schema/m.room.message$m.audio: -------------------------------------------------------------------------------- 1 | --- 2 | allOf: 3 | - $ref: core-event-schema/room_event.yaml 4 | description: This message represents a single audio clip. 5 | properties: 6 | content: 7 | properties: 8 | body: 9 | description: "A description of the audio e.g. 'Bee Gees - Stayin' Alive', or some kind of content description for accessibility e.g. 'audio attachment'." 10 | type: string 11 | info: 12 | description: Metadata for the audio clip referred to in ``url``. 13 | properties: 14 | duration: 15 | description: The duration of the audio in milliseconds. 16 | type: integer 17 | mimetype: 18 | description: The mimetype of the audio e.g. ``audio/aac``. 19 | type: string 20 | size: 21 | description: The size of the audio clip in bytes. 22 | type: integer 23 | title: AudioInfo 24 | type: object 25 | msgtype: 26 | enum: 27 | - m.audio 28 | type: string 29 | url: 30 | description: |- 31 | Required if the file is unencrypted. The URL (typically `MXC URI`_) 32 | to the audio clip. 33 | type: string 34 | file: 35 | description: |- 36 | Required if the file is encrypted. Information on the encrypted 37 | file, as specified in |encrypted_files|_. 38 | title: EncryptedFile 39 | type: object 40 | required: 41 | - msgtype 42 | - body 43 | type: object 44 | type: 45 | enum: 46 | - m.room.message 47 | type: string 48 | title: AudioMessage 49 | type: object 50 | -------------------------------------------------------------------------------- /event-schemas/schema/stripped_state.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2019 The Matrix.org Foundation C.I.C. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | # Note: this, and the example, are in the `event-schemas` directory because 16 | # the CS API uses a symlink. In order for the `m.room.member` event to 17 | # reference this, we'd need to use relative pathing. The symlink makes this 18 | # difficult because the schema would be at two different locations, with 19 | # different relative pathing. 20 | 21 | title: StrippedState 22 | type: object 23 | description: |- 24 | A stripped down state event, with only the ``type``, ``state_key``, 25 | ``sender``, and ``content`` keys. 26 | properties: 27 | content: 28 | description: The ``content`` for the event. 29 | title: EventContent 30 | type: object 31 | state_key: 32 | description: The ``state_key`` for the event. 33 | type: string 34 | type: 35 | description: The ``type`` for the event. 36 | type: string 37 | sender: 38 | description: The ``sender`` for the event. 39 | type: string 40 | required: 41 | - type 42 | - state_key 43 | - content 44 | - sender 45 | -------------------------------------------------------------------------------- /event-schemas/schema/m.call.answer: -------------------------------------------------------------------------------- 1 | { 2 | "type": "object", 3 | "description": "This event is sent by the callee when they wish to answer the call.", 4 | "allOf": [{ 5 | "$ref": "core-event-schema/room_event.yaml" 6 | }], 7 | "properties": { 8 | "content": { 9 | "type": "object", 10 | "properties": { 11 | "call_id": { 12 | "type": "string", 13 | "description": "The ID of the call this event relates to." 14 | }, 15 | "answer": { 16 | "type": "object", 17 | "title": "Answer", 18 | "description": "The session description object", 19 | "properties": { 20 | "type": { 21 | "type": "string", 22 | "enum": ["answer"], 23 | "description": "The type of session description." 24 | }, 25 | "sdp": { 26 | "type": "string", 27 | "description": "The SDP text of the session description." 28 | } 29 | }, 30 | "required": ["type", "sdp"] 31 | }, 32 | "version": { 33 | "type": "number", 34 | "description": "" 35 | } 36 | }, 37 | "required": ["call_id", "answer", "version"] 38 | }, 39 | "type": { 40 | "type": "string", 41 | "enum": ["m.call.answer"] 42 | } 43 | } 44 | } 45 | -------------------------------------------------------------------------------- /event-schemas/schema/core-event-schema/sync_state_event.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2018 New Vector Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | # See sync_room_event.yaml for why this file is here. 16 | 17 | allOf: 18 | - $ref: sync_room_event.yaml 19 | description: In addition to the Room Event fields, State Events have the following 20 | additional fields. 21 | properties: 22 | prev_content: 23 | description: Optional. The previous ``content`` for this event. If there is no 24 | previous content, this key will be missing. 25 | title: EventContent 26 | type: object 27 | state_key: 28 | description: A unique key which defines the overwriting semantics for this piece 29 | of room state. This value is often a zero-length string. The presence of this 30 | key makes this event a State Event. 31 | 32 | State keys starting with an ``@`` are reserved for referencing user IDs, such 33 | as room members. With the exception of a few events, state events set with a 34 | given user's ID as the state key MUST only be set by that user. 35 | type: string 36 | required: 37 | - state_key 38 | title: SyncStateEvent 39 | type: object 40 | -------------------------------------------------------------------------------- /api/identity/ping.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2018 Kamax Sàrl 2 | # Copyright 2018 New Vector Ltd 3 | # 4 | # Licensed under the Apache License, Version 2.0 (the "License"); 5 | # you may not use this file except in compliance with the License. 6 | # You may obtain a copy of the License at 7 | # 8 | # http://www.apache.org/licenses/LICENSE-2.0 9 | # 10 | # Unless required by applicable law or agreed to in writing, software 11 | # distributed under the License is distributed on an "AS IS" BASIS, 12 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | # See the License for the specific language governing permissions and 14 | # limitations under the License. 15 | 16 | swagger: "2.0" 17 | info: 18 | title: "Matrix Identity Service Ping API" 19 | version: "1.0.0" 20 | host: localhost:8090 21 | schemes: 22 | - https 23 | basePath: /_matrix/identity 24 | produces: 25 | - application/json 26 | paths: 27 | "/api/v1": 28 | get: 29 | summary: Checks that an identity server is available at this API endpoint. 30 | description: |- 31 | Checks that an identity server is available at this API endpoint. 32 | 33 | To discover that an identity server is available at a specific URL, 34 | this endpoint can be queried and will return an empty object. 35 | 36 | This is primarly used for auto-discovery and health check purposes 37 | by entities acting as a client for the identity server. 38 | operationId: ping 39 | deprecated: true 40 | responses: 41 | 200: 42 | description: An identity server is ready to serve requests. 43 | examples: 44 | application/json: {} 45 | schema: 46 | type: object 47 | -------------------------------------------------------------------------------- /event-schemas/schema/core-event-schema/sync_room_event.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2018 New Vector Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | # Note: this is technically not a core event schema, however it is included here 16 | # to keep things sane. The short story is that /sync doesn't require a room_id to 17 | # be on events, so we give it a whole event structure as a base for room_event. 18 | # This base doesn't declare a room_id, which instead appears in the room_event. 19 | 20 | allOf: 21 | - $ref: event.yaml 22 | description: In addition to the Event fields, Room Events have the following additional 23 | fields. 24 | properties: 25 | event_id: 26 | description: The globally unique event identifier. 27 | type: string 28 | sender: 29 | description: Contains the fully-qualified ID of the user who sent this event. 30 | type: string 31 | origin_server_ts: 32 | description: Timestamp in milliseconds on originating homeserver 33 | when this event was sent. 34 | type: integer 35 | format: int64 36 | unsigned: 37 | $ref: unsigned_prop.yaml 38 | required: 39 | - event_id 40 | - sender 41 | - origin_server_ts 42 | title: SyncRoomEvent 43 | type: object 44 | -------------------------------------------------------------------------------- /specification/modules/device_management.rst: -------------------------------------------------------------------------------- 1 | .. Copyright 2016 OpenMarket Ltd 2 | .. 3 | .. Licensed under the Apache License, Version 2.0 (the "License"); 4 | .. you may not use this file except in compliance with the License. 5 | .. You may obtain a copy of the License at 6 | .. 7 | .. http://www.apache.org/licenses/LICENSE-2.0 8 | .. 9 | .. Unless required by applicable law or agreed to in writing, software 10 | .. distributed under the License is distributed on an "AS IS" BASIS, 11 | .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | .. See the License for the specific language governing permissions and 13 | .. limitations under the License. 14 | 15 | Device Management 16 | ================= 17 | 18 | .. _module:device-management: 19 | 20 | This module provides a means for a user to manage their `devices`_. 21 | 22 | Client behaviour 23 | ---------------- 24 | Clients that implement this module should offer the user a list of registered 25 | devices, as well as the means to update their display names. Clients should 26 | also allow users to delete disused devices. 27 | 28 | {{device_management_cs_http_api}} 29 | 30 | Security considerations 31 | ----------------------- 32 | 33 | Deleting devices has security implications: it invalidates the access_token 34 | assigned to the device, so an attacker could use it to log out the real user 35 | (and do it repeatedly every time the real user tries to log in to block the 36 | attacker). Servers should require additional authentication beyond the access 37 | token when deleting devices (for example, requiring that the user resubmit 38 | their password). 39 | 40 | The display names of devices are publicly visible. Clients should consider 41 | advising the user of this. 42 | -------------------------------------------------------------------------------- /api/identity/v2_ping.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2018 Kamax Sàrl 2 | # Copyright 2018 New Vector Ltd 3 | # Copyright 2019 The Matrix.org Foundation C.I.C. 4 | # 5 | # Licensed under the Apache License, Version 2.0 (the "License"); 6 | # you may not use this file except in compliance with the License. 7 | # You may obtain a copy of the License at 8 | # 9 | # http://www.apache.org/licenses/LICENSE-2.0 10 | # 11 | # Unless required by applicable law or agreed to in writing, software 12 | # distributed under the License is distributed on an "AS IS" BASIS, 13 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 | # See the License for the specific language governing permissions and 15 | # limitations under the License. 16 | 17 | swagger: "2.0" 18 | info: 19 | title: "Matrix Identity Service Ping API" 20 | version: "2.0.0" 21 | host: localhost:8090 22 | schemes: 23 | - https 24 | basePath: /_matrix/identity 25 | produces: 26 | - application/json 27 | paths: 28 | "/v2": 29 | get: 30 | summary: Checks that an identity server is available at this API endpoint. 31 | description: |- 32 | Checks that an identity server is available at this API endpoint. 33 | 34 | To discover that an identity server is available at a specific URL, 35 | this endpoint can be queried and will return an empty object. 36 | 37 | This is primarly used for auto-discovery and health check purposes 38 | by entities acting as a client for the identity server. 39 | operationId: pingV2 40 | responses: 41 | 200: 42 | description: An identity server is ready to serve requests. 43 | examples: 44 | application/json: {} 45 | schema: 46 | type: object 47 | -------------------------------------------------------------------------------- /api/client-server/definitions/third_party_signed.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2019 The Matrix.org Foundation C.I.C. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | type: object 15 | title: Third Party Signed 16 | description: |- 17 | A signature of an ``m.third_party_invite`` token to prove that this user 18 | owns a third party identity which has been invited to the room. 19 | properties: 20 | sender: 21 | type: string 22 | description: The Matrix ID of the user who issued the invite. 23 | example: "@alice:example.org" 24 | mxid: 25 | type: string 26 | description: The Matrix ID of the invitee. 27 | example: "@bob:example.org" 28 | token: 29 | type: string 30 | description: The state key of the m.third_party_invite event. 31 | example: "random8nonce" 32 | signatures: 33 | type: object 34 | description: A signatures object containing a signature of the entire signed object. 35 | title: Signatures 36 | additionalProperties: 37 | type: object 38 | additionalProperties: 39 | type: string 40 | example: { 41 | "example.org": { 42 | "ed25519:0": "some9signature" 43 | } 44 | } 45 | required: ["sender", "mxid", "token", "signatures"] 46 | -------------------------------------------------------------------------------- /api/client-server/sso_login_redirect.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2019 New Vector Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | swagger: '2.0' 15 | info: 16 | title: "Matrix Client-Server SSO Login API" 17 | version: "1.0.0" 18 | host: localhost:8008 19 | schemes: 20 | - https 21 | - http 22 | basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% 23 | paths: 24 | "/login/sso/redirect": 25 | get: 26 | summary: Redirect the user's browser to the SSO interface. 27 | description: |- 28 | A web-based Matrix client should instruct the user's browser to 29 | navigate to this endpoint in order to log in via SSO. 30 | 31 | The server MUST respond with an HTTP redirect to the SSO interface. 32 | operationId: redirectToSSO 33 | parameters: 34 | - in: query 35 | type: string 36 | name: redirectUrl 37 | description: |- 38 | URI to which the user will be redirected after the homeserver has 39 | authenticated the user with SSO. 40 | required: true 41 | responses: 42 | 302: 43 | description: A redirect to the SSO interface. 44 | headers: 45 | Location: 46 | type: "string" 47 | -------------------------------------------------------------------------------- /specification/modules/account_data.rst: -------------------------------------------------------------------------------- 1 | .. Copyright 2016 OpenMarket Ltd 2 | .. 3 | .. Licensed under the Apache License, Version 2.0 (the "License"); 4 | .. you may not use this file except in compliance with the License. 5 | .. You may obtain a copy of the License at 6 | .. 7 | .. http://www.apache.org/licenses/LICENSE-2.0 8 | .. 9 | .. Unless required by applicable law or agreed to in writing, software 10 | .. distributed under the License is distributed on an "AS IS" BASIS, 11 | .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | .. See the License for the specific language governing permissions and 13 | .. limitations under the License. 14 | 15 | Client Config 16 | ============= 17 | 18 | .. _module:account_data: 19 | 20 | Clients can store custom config data for their account on their homeserver. 21 | This account data will be synced between different devices and can persist 22 | across installations on a particular device. Users may only view the account 23 | data for their own account 24 | 25 | The account_data may be either global or scoped to a particular rooms. 26 | 27 | Events 28 | ------ 29 | 30 | The client receives the account data as events in the ``account_data`` sections 31 | of a ``/sync``. 32 | 33 | These events can also be received in a ``/events`` response or in the 34 | ``account_data`` section of a room in ``/sync``. ``m.tag`` 35 | events appearing in ``/events`` will have a ``room_id`` with the room 36 | the tags are for. 37 | 38 | Client Behaviour 39 | ---------------- 40 | 41 | {{account_data_cs_http_api}} 42 | 43 | 44 | Server Behaviour 45 | ---------------- 46 | 47 | Servers MUST reject clients from setting account data for event types that 48 | the server manages. Currently, this only includes `m.fully_read`_. 49 | -------------------------------------------------------------------------------- /api/files/reset.css: -------------------------------------------------------------------------------- 1 | /* http://meyerweb.com/eric/tools/css/reset/ v2.0 | 20110126 */ 2 | html, 3 | body, 4 | div, 5 | span, 6 | applet, 7 | object, 8 | iframe, 9 | h1, 10 | h2, 11 | h3, 12 | h4, 13 | h5, 14 | h6, 15 | p, 16 | blockquote, 17 | pre, 18 | a, 19 | abbr, 20 | acronym, 21 | address, 22 | big, 23 | cite, 24 | code, 25 | del, 26 | dfn, 27 | em, 28 | img, 29 | ins, 30 | kbd, 31 | q, 32 | s, 33 | samp, 34 | small, 35 | strike, 36 | strong, 37 | sub, 38 | sup, 39 | tt, 40 | var, 41 | b, 42 | u, 43 | i, 44 | center, 45 | dl, 46 | dt, 47 | dd, 48 | ol, 49 | ul, 50 | li, 51 | fieldset, 52 | form, 53 | label, 54 | legend, 55 | table, 56 | caption, 57 | tbody, 58 | tfoot, 59 | thead, 60 | tr, 61 | th, 62 | td, 63 | article, 64 | aside, 65 | canvas, 66 | details, 67 | embed, 68 | figure, 69 | figcaption, 70 | footer, 71 | header, 72 | hgroup, 73 | menu, 74 | nav, 75 | output, 76 | ruby, 77 | section, 78 | summary, 79 | time, 80 | mark, 81 | audio, 82 | video { 83 | margin: 0; 84 | padding: 0; 85 | border: 0; 86 | font-size: 100%; 87 | font: inherit; 88 | vertical-align: baseline; 89 | } 90 | /* HTML5 display-role reset for older browsers */ 91 | article, 92 | aside, 93 | details, 94 | figcaption, 95 | figure, 96 | footer, 97 | header, 98 | hgroup, 99 | menu, 100 | nav, 101 | section { 102 | display: block; 103 | } 104 | body { 105 | line-height: 1; 106 | } 107 | ol, 108 | ul { 109 | list-style: none; 110 | } 111 | blockquote, 112 | q { 113 | quotes: none; 114 | } 115 | blockquote:before, 116 | blockquote:after, 117 | q:before, 118 | q:after { 119 | content: ''; 120 | content: none; 121 | } 122 | table { 123 | border-collapse: collapse; 124 | border-spacing: 0; 125 | } 126 | -------------------------------------------------------------------------------- /proposals/2604-login-fallback-device-info.md: -------------------------------------------------------------------------------- 1 | # Parameters for Login Fallback 2 | 3 | The [login fallback](https://matrix.org/docs/spec/client_server/r0.6.1#login-fallback) 4 | API can be used by clients to support logins that they do not recognize. It is 5 | expected to be loaded in a web view and calls a JavaScript function 6 | (`window.onLogin`) when the login process is complete. 7 | 8 | Since the login fallback page does the full login process there is no 9 | opportunity for the application to provide a device ID (to re-authenticate 10 | an expired session in the [case of soft-logout](https://matrix.org/docs/spec/client_server/r0.6.1#soft-logout)) 11 | or an [initial device display name](https://matrix.org/docs/spec/client_server/r0.6.1#post-matrix-client-r0-login) 12 | (in the case of an initial login). This causes a few issues: 13 | 14 | * It can make it difficult for a user to manage their sessions (as additional 15 | sessions get created for each soft-logout). 16 | * Cross-signing information gets reset when a new device ID is returned from the 17 | login process. This results in users needing to re-validate their device. 18 | 19 | ## Proposal 20 | 21 | The login fallback page will accept query parameters for non-credential related 22 | parameters of the login endpoint. These will be forwarded by the login fallback 23 | API to the login API throughout the login process. Currently the following 24 | parameters should be accepted: 25 | 26 | * `device_id` 27 | * `initial_device_display_name` 28 | 29 | 30 | ## Potential issues 31 | 32 | There are no backwards compatibility concerns: if a client provides the query 33 | parameters to a homeserver that does not check for them than the current 34 | behavior will occur. 35 | 36 | 37 | ## Security considerations 38 | 39 | None. 40 | -------------------------------------------------------------------------------- /api/server-server/definitions/event-schemas/m.typing.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2018 New Vector Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | type: object 16 | title: m.typing 17 | description: A typing notification EDU for a user in a room. 18 | allOf: 19 | - $ref: ../edu.yaml 20 | - type: object 21 | properties: 22 | edu_type: 23 | type: enum 24 | enum: ['m.typing'] 25 | description: The string ``m.typing`` 26 | example: "m.typing" 27 | content: 28 | type: object 29 | description: The typing notification. 30 | title: Typing Notification 31 | properties: 32 | room_id: 33 | type: string 34 | description: |- 35 | The room where the user's typing status has been updated. 36 | example: "!somewhere:matrix.org" 37 | user_id: 38 | type: string 39 | description: |- 40 | The user ID that has had their typing status changed. 41 | example: "@john:matrix.org" 42 | typing: 43 | type: boolean 44 | description: Whether the user is typing in the room or not. 45 | example: true 46 | required: ['room_id', 'user_id', 'typing'] 47 | -------------------------------------------------------------------------------- /proposals/1802-standardised-federation-response-format.md: -------------------------------------------------------------------------------- 1 | # Remove the '200' value from some federation responses 2 | 3 | Some responses formats in the federation API specifications use the form `[200, 4 | res]` in which `res` is the JSON object containing the actual response for the 5 | affected endpoints. This was due to a mishap while building synapse's federation 6 | features, and has been left as is because fixing it would induce backward 7 | incompatibility. 8 | 9 | This proposal proposes a backward compatible alternative 10 | 11 | ## Proposal 12 | 13 | Add a new version of the following endpoints under the prefix 14 | `/_matrix/federation/v2`: 15 | 16 | * `PUT /_matrix/federation/v2/send_join/{roomId}/{eventId}` 17 | * `PUT /_matrix/federation/v2/send_leave/{roomId}/{eventId}` 18 | 19 | Which are the exact same endpoints as their equivalents under the `v1` prefix, 20 | except for the response format, which changes from: 21 | 22 | ``` 23 | [ 24 | 200, 25 | res 26 | ] 27 | ``` 28 | 29 | To: 30 | 31 | ``` 32 | res 33 | ``` 34 | 35 | Where `res` is the JSON object containing the response to a request directed at 36 | one of the affected endpoints. 37 | 38 | This proposal doesn't address the `PUT 39 | /_matrix/federation/v1/invite/{roomId}/{eventId}` endpoint since 40 | [MSC1794](https://github.com/matrix-org/matrix-doc/pull/1794) already takes care 41 | of it. 42 | 43 | If a call to any of the `v2` endpoints described in this proposal results in an 44 | unrecognised request exception (i.e. in a response with a 400 or a 404 status 45 | code), then the sending server should retry the request with the `v1` API. 46 | 47 | ## Alternative solutions 48 | 49 | An alternative solution would be to make the change in the `v1` federation API, 50 | but would break backward compatibility, thus would be harder to manage. 51 | -------------------------------------------------------------------------------- /api/client-server/definitions/request_token_response.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2019 The Matrix.org Foundation C.I.C. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | type: object 15 | properties: 16 | sid: 17 | type: string 18 | description: |- 19 | The session ID. Session IDs are opaque strings that must consist entirely 20 | of the characters ``[0-9a-zA-Z.=_-]``. Their length must not exceed 255 21 | characters and they must not be empty. 22 | example: "123abc" 23 | submit_url: 24 | type: string 25 | description: |- 26 | An optional field containing a URL where the client must submit the 27 | validation token to, with identical parameters to the Identity Service 28 | API's ``POST /validate/email/submitToken`` endpoint (without the requirement 29 | for an access token). The homeserver must send this token to the user (if 30 | applicable), who should then be prompted to provide it to the client. 31 | 32 | If this field is not present, the client can assume that verification 33 | will happen without the client's involvement provided the homeserver 34 | advertises this specification version in the ``/versions`` response 35 | (ie: r0.5.0). 36 | example: "https://example.org/path/to/submitToken" 37 | required: ['sid'] 38 | -------------------------------------------------------------------------------- /api/client-server/definitions/push_rule.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2016 OpenMarket Ltd 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | title: PushRule 16 | type: object 17 | properties: 18 | actions: 19 | items: 20 | type: 21 | - object 22 | - string 23 | type: array 24 | description: |- 25 | The actions to perform when this rule is matched. 26 | default: 27 | type: boolean 28 | description: |- 29 | Whether this is a default rule, or has been set explicitly. 30 | enabled: 31 | type: boolean 32 | description: |- 33 | Whether the push rule is enabled or not. 34 | rule_id: 35 | type: string 36 | description: |- 37 | The ID of this rule. 38 | conditions: 39 | type: array 40 | items: 41 | allOf: 42 | - $ref: push_condition.yaml 43 | description: |- 44 | The conditions that must hold true for an event in order for a rule to be 45 | applied to an event. A rule with no conditions always matches. Only 46 | applicable to ``underride`` and ``override`` rules. 47 | pattern: 48 | type: string 49 | description: |- 50 | The glob-style pattern to match against. Only applicable to ``content`` 51 | rules. 52 | required: 53 | - actions 54 | - default 55 | - enabled 56 | - rule_id 57 | -------------------------------------------------------------------------------- /proposals/1983-leave-reasons.md: -------------------------------------------------------------------------------- 1 | # Proposal to add reasons for leaving a room 2 | 3 | This proposal intends to solve [#1295](https://github.com/matrix-org/matrix-doc/issues/1295). Currently 4 | people can be kicked from a room for a human-readable reason, but when voluntarily leaving the `reason` 5 | is not considered. 6 | 7 | ## Proposal 8 | 9 | Like when kicking someone, `m.room.member` events with `membership: leave` can have a string `reason`. 10 | The reason is a human-readable string of text which clients should display to users of the room, providing 11 | users with the ability to leave a room for a reason of their choosing. The field is optional. 12 | 13 | Having such a field gives Matrix better compatibility with other networks such as IRC which use the leave 14 | reason to communicate connection problems ("ping timeout", etc). Although Matrix doesn't have a need for a 15 | persistent connection to remain in the room, having a reason can improve the bridge experience. 16 | 17 | An example of a partial leave event with reason would be: 18 | ```json 19 | { 20 | "type": "m.room.member", 21 | "sender": "@travis:t2l.io", 22 | "state_key": "@travis:t2l.io", 23 | "content": { 24 | "membership": "leave", 25 | "reason": "I'm in too many rooms and never talk here" 26 | } 27 | } 28 | ``` 29 | 30 | 31 | ## Potential issues 32 | 33 | There is a chance that quality of communication may deteriorate as a result of adding this field. Arguments 34 | in rooms may result in the leave reason having personal attacks against other room members or rude remarks. 35 | Moderators would be expected to handle these situations for these cases, including redacting the state event 36 | if needed. 37 | 38 | This also opens up an avenue for spam by having a very large reason for leaving. Clients are encouraged to 39 | trim/hide the reason at a reasonable length. 40 | -------------------------------------------------------------------------------- /api/client-server/definitions/key_backup_data.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2019 The Matrix.org Foundation C.I.C. 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | type: object 16 | title: KeyBackupData 17 | description: "The key data" 18 | properties: 19 | first_message_index: 20 | description: |- 21 | The index of the first message in the session that the key can decrypt. 22 | type: integer 23 | example: 1 24 | forwarded_count: 25 | description: |- 26 | The number of times this key has been forwarded via key-sharing between devices. 27 | type: integer 28 | example: 0 29 | is_verified: 30 | description: |- 31 | Whether the device backing up the key verified the device that the key 32 | is from. 33 | type: boolean 34 | example: false 35 | session_data: 36 | description: |- 37 | Algorithm-dependent data. See the documentation for the backup 38 | algorithms in `Server-side key backups`_ for more information on the 39 | expected format of the data. 40 | type: object 41 | example: { 42 | "ephemeral": "base64+ephemeral+key", 43 | "ciphertext": "base64+ciphertext+of+JSON+data", 44 | "mac": "base64+mac+of+ciphertext" 45 | } 46 | required: 47 | - first_message_index 48 | - forwarded_count 49 | - is_verified 50 | - session_data 51 | --------------------------------------------------------------------------------