房间版本 7

本房间版本在 版本 6 的基础上，新增了敲门作为一种可选的加入规则和成员状态。

客户端注意事项

这是首个完全支持敲门（knocking）的房间版本。因此，用户无法在非 v7 版本为基础的房间发起敲门请求。

虽然本房间版本相关的部分没有变动，实现本地化撤回算法的客户端应参考下方的撤回章节了解完整细节。

服务器实现要点

房间版本 7 新增了支持敲门的事件认证规则。房间版本 6 及其所基于的版本中包含了其他认证规则变更的细节。

认证规则

[New in this version] 对于对 m.room.member 事件执行的检查，新增了针对 membership=knock 的处理分支。

事件必须由其 sender 属性所指服务器签名。

影响认证过程的状态事件类型有：

• m.room.create
• m.room.member
• m.room.join_rules
• m.room.power_levels
• m.room.third_party_invite

认证规则如下：

1. 若事件类型为 m.room.create：
   1. 若存在任何 prev_events，拒绝。
   2. 若 room_id 的域名与 sender 域名不一致，拒绝。
   3. 若 content.room_version 存在且不为已知版本，拒绝。
   4. 若 content 无 creator 属性，拒绝。
   5. 其他情况，允许。
2. 针对事件的 auth_events：
   1. 对于任意给定的 type 和 state_key，若有重复条目，拒绝。
   2. 若有 type 和 state_key 不符合认证事件选择算法的条目，拒绝。
   3. 若有条目本身在接收 PDU 时执行的检查中被拒，拒绝。
   4. 若条目中没有 m.room.create 事件，拒绝。
3. 若房间状态中的 m.room.create 事件的 content 存在 m.federate 且为 false，且事件的 sender 域与创建事件的 sender 域不同，拒绝。
4. 若事件类型为 m.room.member：
   1. 若无 state_key 属性，或 content 无 membership 属性，拒绝。
   2. 若 membership 为 join：
      1. 如仅有的上一个事件为 m.room.create 且 state_key 为创建者，允许。
      2. 若 sender 与 state_key 不同，拒绝。
      3. 若 sender 已被禁言（banned），拒绝。
      4. [Changed in this version] 若 join_rule 为 invite 或 knock，则当成员状态为 invite 或 join 时允许。
      5. 若 join_rule 为 public，允许。
      6. 其他情况，拒绝。
   3. 若 membership 为 invite：
      1. 如果 content 有 third_party_invite 属性：
         1. 若目标用户被 ban，拒绝。
         2. 若 content.third_party_invite 无 signed 属性，拒绝。
         3. 若 signed 无 mxid 和 token 属性，拒绝。
         4. 若 mxid 与 state_key 不一致，拒绝。
         5. 若当前房间状态中无 state_key 为 token 的 m.room.third_party_invite 事件，拒绝。
         6. 若 sender 不一致于 m.room.third_party_invite 事件的 sender，拒绝。
         7. 若 signed 中任意签名与 m.room.third_party_invite 事件中的任一公钥匹配，允许。公钥位于 m.room.third_party_invite 事件的 content 中：
            1. public_key 属性中的单个公钥；
            2. public_keys 属性中的公钥列表。
         8. 其他情况，拒绝。
      2. 若 sender 当前成员状态不是 join，拒绝。
      3. 若目标用户当前成员状态为 join 或 ban，拒绝。
      4. 若 sender 权限等级大于等于 invite level，允许。
      5. 其他情况，拒绝。
   4. 若 membership 为 leave：
      1. [Changed in this version] 若 sender 等于 state_key，仅当该用户当前成员状态为 invite、join 或 knock 时允许。
      2. 若 sender 当前成员状态不是 join，拒绝。
      3. 若目标用户当前成员状态为 ban，且 sender 权限小于 ban level，拒绝。
      4. 若 sender 权限等级大于等于 kick level，并且 目标用户 权限低于 sender，允许。
      5. 其他情况，拒绝。
   5. 若 membership 为 ban：
      1. 若 sender 当前成员状态不是 join，拒绝。
      2. 若 sender 权限等级大于等于 ban level，且目标用户权限等级低于 sender，允许。
      3. 其他情况，拒绝。
   6. [New in this version] 若 membership 为 knock：
      1. 若 join_rule 不为 knock，拒绝。
      2. 若 sender 与 state_key 不同，拒绝。
      3. 若 sender 当前成员状态不是 ban、invite 或 join，允许。
      4. 其他情况，拒绝。
   7. 其他未知成员状态，拒绝。
5. 若 sender 当前成员状态不是 join，拒绝。
6. 若事件类型为 m.room.third_party_invite：
   1. 仅当 sender 当前权限等级大于等于 invite level 时允许。
7. 若事件类型所需权限等级大于 sender 的当前权限等级，拒绝。
8. 若事件有以 @ 开头的 state_key 且不等于 sender，拒绝。
9. 若事件类型为 m.room.power_levels：
   1. 若 content 的 users 属性不是仅包含有效用户 ID 的对象，值为整数（或可解释为整数的字符串），拒绝。
   2. 若房间内无之前的 m.room.power_levels 事件，允许。
   3. 对 users_default、events_default、state_default、ban、redact、kick、invite 这些属性，如有新增、变更或移除，逐项检查：
      1. 若当前值高于 sender 的当前权限等级，拒绝。
      2. 若新值高于 sender 当前权限等级，拒绝。
   4. 对 events 或 notifications 属性中被变更或移除的条目逐项检查：
      1. 若当前值高于 sender 当前权限等级，拒绝。
   5. 对 events 或 notifications 属性中被新增或变更的条目逐项检查：
      1. 若新值高于 sender 当前权限等级，拒绝。
   6. 对除 sender 自己以外的、users 属性中被变更或移除的条目逐项检查：
      1. 若当前值大于等于 sender 当前权限等级，拒绝。
   7. 对 users 属性中被新增或变更的条目逐项检查：
      1. 若新值高于 sender 当前权限等级，拒绝。
   8. 其他情况，允许。
10. 其他情况，允许。

与 v6 保持一致的内容

下列章节自 v6 起未做更改，为保障文档完整性此处附上。

撤回

在收到编辑事件时，服务器必须移除不在以下列表中的任何键：

• event_id
• type
• room_id
• sender
• state_key
• content
• hashes
• signatures
• depth
• prev_events
• prev_state
• auth_events
• origin
• origin_server_ts
• membership

content 对象也必须移除除下列情况外的所有键：

• m.room.member 事件类型允许保留 membership 键。
• m.room.create 事件类型允许保留 creator 键。
• m.room.join_rules 事件类型允许保留 join_rule 键。
• m.room.power_levels 事件类型允许保留以下键： ban、events、events_default、kick、redact、state_default、users、 users_default。
• m.room.history_visibility 事件类型允许保留 history_visibility 键。

撤回处理

在房间版本1和2中，清除操作（redactions）明确属于授权规则第11条。自房间版本3起，这些条件不再适用，如本版本的授权规则所示。

尽管清除操作始终被事件的授权规则接受，但只有在清除事件和被清除的事件都已被接收并且能够被验证后，才能将其发送给客户端。如果这两个事件都有效并已被服务器看到，那么在满足以下任一条件时，服务器会应用清除操作：

1. 清除事件的 sender 的权限等级大于或等于清除权限等级（redact level）。
2. 清除事件的 sender 的域名与原事件的 sender 的域名一致。

如果服务器将应用清除操作，则该清除事件也会被发送给客户端。否则，服务器只会等待有效的配对事件到来，届时可以重新检查上述条件。

事件 ID

事件 ID 是事件的参考哈希，其采用一种变体的无填充 Base64 编码，将第 62 和第 63 个字符分别替换为 - 和 _，而不是使用 + 和 /。这与 RFC4648 URL 安全型 base64 的定义一致。

事件 ID 仍以前缀 $ 开头，最终可能类似于 $Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg。

事件格式

本版本中房间内的事件具有以下结构：

{
  "auth_events": [
    "$urlsafe_base64_encoded_eventid",
    "$a-different-event-id"
  ],
  "content": {
    "key": "value"
  },
  "depth": 12,
  "hashes": {
    "sha256": "thishashcoversallfieldsincasethisisredacted"
  },
  "origin_server_ts": 1404838188000,
  "prev_events": [
    "$urlsafe_base64_encoded_eventid",
    "$a-different-event-id"
  ],
  "redacts": "$some-old_event",
  "room_id": "!UcYsUzyxTGDxLBEvLy:example.org",
  "sender": "@alice:example.com",
  "signatures": {
    "example.com": {
      "ed25519:key_version": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
    }
  },
  "type": "m.room.message",
  "unsigned": {
    "age": 4612
  }
}

已弃用事件内容模式

发送到此版本房间中的事件，其格式可能与其常规模式不同。此类情况将在此处进行说明。

m.room.power_levels 事件支持以字符串形式传递数值

为了与早期实现保持向后兼容， m.room.power_levels 事件中的每个整数值属性 都可以被编码为字符串而非整数。这包括 events、notifications 和 users 属性中的嵌套值。例如，以下是在此房间版本中有效的 m.room.power_levels 事件：

{
  "content": {
    "ban": "50",
    "events": {
      "m.room.power_levels": "100"
    },
    "events_default": "0",
    "state_default": "50",
    "users": {
      "@example:localhost": "100"
    },
    "users_default": "0"
  },
  "origin_server_ts": 1432735824653,
  "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
  "sender": "@example:example.org",
  "state_key": "",
  "type": "m.room.power_levels"
}

当该值表示整数时，必须符合以下格式：

• 仅包含一个十进制整数，不允许浮点数或小数点，可以带任意数量的前导零（如 "100"、"000100"）；
• 可选地在整数前面加一个 - 或 + 字符（如 "+100"、"-100"）；
• 可选地在前后添加任意数量的空白字符（如 " 100 "、" 00100 "、" +100 "、" -100 "）。

状态解析

事件 E 之后的房间状态 S′(E) 由事件 E 之前的房间状态 S(E) 定义，并且依赖于 E 是状态事件还是消息事件：

• 如果 E 是一条消息事件，则 S′(E) = S(E)。
• 如果 E 是一条状态事件，则 S′(E) 与 S(E) 相同，除了其与 E 的 event_type 和 state_key 对应的项被 E 的 event_id 替换。

事件 E 之前的房间状态 S(E) 是 prev_event 集合 {E₁, E₂, …} 之后的状态集合 {S′(E₁), S′(E₂), …} 的 合并与决议结果。如何对一组状态进行合并与决议，见下述算法。

定义

版本 2 房间的状态合并算法使用如下定义，并以房间状态集 {S₁, S₂, …} 为输入：

权限事件（Power events）。
权限事件 指具有类型 m.room.power_levels 或 m.room.join_rules 的状态事件，或者类型为 m.room.member 且 membership 字段为 leave 或 ban，且 sender 与 state_key 不一致的状态事件。其核心思想为：权限事件是那些可能移除某人在房间内某项操作权限的事件。

无冲突状态映射与冲突状态集。
状态映射 S_i 的 key 为形如 (event_type, state_key) 的字符串二元组 K，对应的 value V 为一个状态事件。所有 S_i 的 (K, V) 键值对可划分为两个集合：如果给定 key K 在所有 S_i 出现，且值 V 在每个状态映射都一致，则此 (K, V) 属于 无冲突状态映射；否则，V 属于 冲突状态集。

注意，无冲突状态映射每个 key K 只会有一个事件，而冲突状态集可能因同 key 包含多个事件。

鉴权链（Auth chain）。
事件 E 的 鉴权链，是包含 E 的所有鉴权事件（auth events）、所有这些事件的鉴权事件，递归回溯直到房间创建为止的集合。换句话说，就是通过事件的 auth_events 链接遍历可达的所有事件。

鉴权差集（Auth difference）。
鉴权差集 的计算方式如下：首先对每个状态 S_i，计算其完全鉴权链，即该状态中每个事件的鉴权链的并集。然后找出那些未在所有鉴权链中都出现的事件。若 C_i 表示 S_i 的完全鉴权链，则鉴权差集为 ∪ C_i − ∩ C_i。

完整冲突集（Full conflicted set）。
完整冲突集 是冲突状态集与鉴权差集的并集。

逆拓扑权限排序（Reverse topological power ordering）。
一组事件的 逆拓扑权限排序，是按鉴权事件形成的有向无环图（DAG）进行拓扑排序，得到字典序最小的排序，并从最早事件到最晚事件排列。比较两个拓扑排序确定哪一个字典序更小时，事件的比较关系如下：对事件 x 和 y，若

1. x 的发送者的权限级别 高于 y 的发送者（以各自的 auth_event 查得）；或
2. 发送者权限级别相同，但 x 的 origin_server_ts 小于 y；或
3. 权限级别与 origin_server_ts 都相同，但 x 的 event_id 小于 y 的 event_id，

则 x < y。

逆拓扑权限排序可用 Kahn 算法进行拓扑排序，每步从候选顶点中按上述比较关系选择最小顶点。

主链排序（Mainline ordering）。
令 P = P₀ 为某个 m.room.power_levels 事件。从 i = 0 开始，反复获取 P_i+1，即 P_i 的 auth_events 中类型为 m.room.power_levels 的事件。每次自增 i，直到 P_i 的 auth_events 中没有 m.room.power_levels 事件为止。P₀ 的 主链 为 [P₀ , P₁, … , P_n]。

若另有事件 e = e₀（可以是另一个 m.room.power_levels 事件），可以构造类似事件链 [e₁, …, e_m]，其中 e_j+1 为 e_j 的 auth_events 中的 m.room.power_levels 事件，e_m 没有再指向任何 m.room.power_levels 事件。（注意 e₀ 本身不包含在该列表中，也有可能该列表为空，因为 e 可能没有引用过 m.room.power_levels 事件。）

对这两条列表进行如下比较：

• 查找最小的 j ≥ 1，使得 e_j 属于 P 的主链；
• 若存在这样的 j，则 e_j = P_i，且 i 唯一、i ≥ 0；否则令 i = ∞，其中 ∞ 为一个大于任何整数的特殊标记值；
• 无论哪种情况，e 的 主链位置 就是 i。

以 P 计算得主链位置后，基于 P 的主链排序，就是将一组事件按以下比较关系（从小到大）排序：对事件 x 和 y，若

1. x 的主链位置 大于 y（即 x 的鉴权链基于主链上的较早事件）；或
2. 主链位置相同，但 x 的 origin_server_ts 小于 y；或
3. 主链位置、origin_server_ts 都相同，但 x 的 event_id 小于 y，

则 x < y。

迭代鉴权检查（Iterative auth checks）。
迭代鉴权检查算法 的输入是初始房间状态和已排序的状态事件列表。它通过遍历事件列表，将符合授权规则的状态事件依次应用到房间状态上。若某状态事件未通过授权规则，则忽略该事件。如果验证授权规则时缺少某个必须的 (event_type, state_key) key，则用事件 auth_events 中相应的状态事件（若未被拒绝）替代。

算法

一组状态的 合并与决议 按如下步骤执行：

1. 选取出现在 完整冲突集 内的所有权限事件组成集合 X。对于每一个权限事件 P，将 P 的鉴权链中同时属于完整冲突集的事件也加入 X。对 X 按 逆拓扑权限排序 排序为列表。
2. 从 无冲突状态映射 作为起点，对上一步得到的事件列表应用迭代鉴权检查算法，得出部分已决议状态。
3. 将第 1 步未涉及的所有剩余事件按第 2 步已决议状态中的权限等级，用主链排序确定顺序。
4. 对上述部分已决议状态及新排序的事件列表，再次应用迭代鉴权检查算法。
5. 用无冲突状态映射中的相同 key 事件（若存在）替换当前结果中对应事件，得出最终合并决议状态。

被拒绝的事件

由于基于事件当前状态（而非鉴权链）验证授权而被拒绝的事件，除非另有特别说明，在算法中仍按常规方式处理。

注意，那些由于无法通过其鉴权链授权而被拒绝的事件不应出现在此流程中，因为他们不会出现在状态集合之内（本算法只使用状态集中的事件，或状态集中事件的鉴权链中的事件）。

被拒绝的鉴权事件（auth events）故意不参与迭代鉴权检查，因为检查过程中不会对鉴权事件重新授权（但非鉴权事件则会被检查）。

规范化 JSON

服务器必须严格执行 附录 中规定的 JSON 格式。这意味着在大多数端点会返回 400 M_BAD_JSON 错误，或者在联邦通信中丢弃事件。例如，Federation API 的 /send 端点会丢弃该事件，而 Client Server API 的 /send/{eventType} 端点则会返回 M_BAD_JSON 错误。

签名密钥有效期

在验证事件签名时，服务器必须强制要求密钥请求中的 valid_until_ts 属性至少与所验证事件的 origin_server_ts 相同或更大。缺少签名密钥副本的服务器必须尝试通过 GET /_matrix/key/v2/server 或 POST /_matrix/key/v2/query API 获取密钥。当使用 /query 端点时，服务器必须设置 minimum_valid_until_ts 属性，以提示公证服务器在适当情况下尝试刷新密钥。

在确定密钥是否有效时，服务器必须采用 valid_until_ts 和当前时间起未来 7 天中的较小值。这是为了避免攻击者发布一个在较长时间内有效而无法被主服务器所有者撤销的密钥的情况。