Add cross references throughout the spec

Co-authored-by: Kévin Commaille <76261501+zecakeh@users.noreply.github.com>
Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>

content/client-server-api/modules/policy_servers.md

@@ -17,8 +17,8 @@ for added protection.
 {{% /boxes/note %}}
 
 A room's Policy Server is designated by the [`m.room.policy`](#mroompolicy) state
-event described below. If the state event is not set in the room or is incomplete,
+event described below. If the state event is not set in the room or is missing
-the room does *not* use a Policy Server. Similarly, if the server name in the state
+required fields, the room does *not* use a Policy Server. Similarly, if the server name in the state
 event has zero joined users in the room, the room also does *not* use a Policy
 Server.
 

content/server-server-api.md

@@ -473,6 +473,9 @@ server must ensure that the event:
     otherwise it is rejected.
 6.  Passes authorization rules based on the current state of the room,
     otherwise it is "soft failed".
+7. {{% added-in v="1.18" %}} Is [validated](#validating-policy-server-signatures)
+   by the Policy Server, if the room is [using a Policy Server](#determining-if-a-policy-server-is-enabled-in-a-room),
+   otherwise it is "soft failed".
 
 Further details of these checks, and how to handle failures, are
 described below.
@@ -689,6 +692,11 @@ then any new event `D'` will not reference `C`:
     |
     D'
 
+{{% boxes/note %}}
+{{% added-in v="1.18" %}}
+Events can also be soft failed if they fail [Policy Server checks](#validating-policy-server-signatures).
+{{% /boxes/note %}}
+
 #### Retrieving event authorization information
 
 The homeserver may be missing event authorization information, or wish
@@ -1277,10 +1285,10 @@ endpoint MUST be protected as follows:
         room ID MUST be ignored if the sending server is denied access to
         the room identified by that ID.
 
-{{< added-in v="1.18" >}} The following endpoints MAY be protected:
+The following endpoints MAY be protected:
 
--   [`/_matrix/policy/v1/sign`](#post_matrixpolicyv1sign) - Protected if the server
+-   [`/_matrix/policy/v1/sign`](#post_matrixpolicyv1sign) - {{< added-in v="1.18" >}}
-    is tracking the DAG and chooses to enforce the ACL.
+    Protected if the server is tracking the DAG and chooses to enforce the ACL.
 
 
 ## Policy Servers
@@ -1396,7 +1404,7 @@ allow rooms to revoke the Policy Server's key without cooperation of the Policy
 Server.
 
 If the Policy Server is acting as a normal homeserver and attempting to send an
-event, that event will require the a signature from the server's published signing
+event, that event will require a signature from the server's published signing
 key alongside the Policy Server signature described in this section.
 {{% /boxes/warning %}}
 
@@ -1465,6 +1473,12 @@ The signature is then copied back to the original event object.
 For an example of a signed event, see the [room version
 specification](/rooms).
 
+{{% boxes/note %}}
+{{% added-in v="1.18" %}}
+Events sent in rooms with [Policy Servers](#policy-servers) MUST [ask](#asking-for-a-policy-server-signature-on-an-event)
+the Policy Server for a signature too.
+{{% /boxes/note %}}
+
 ### Validating hashes and signatures on received events
 
 When a server receives an event over federation from another server, the
@@ -1499,6 +1513,12 @@ only been given a redacted version of the event. To enforce this, the
 receiving server should use the redacted copy it calculated rather than
 the full copy it received.
 
+{{% boxes/note %}}
+{{% added-in v="1.18" %}}
+Events sent in rooms with [Policy Servers](#policy-servers) have [additional](#validating-policy-server-signatures)
+signature validation requirements.
+{{% /boxes/note %}}
+
 ### Calculating the reference hash for an event
 
 The *reference hash* of an event covers the essential fields of an

data/api/client-server/policy_server.yaml

@@ -24,7 +24,7 @@ paths:
 
         {{% boxes/note %}}
         Like the [well-known discovery URI](/client-server-api/#well-known-uris),
-        this endpoint should be accessed with the hostname of the homeserver's
+        this endpoint should be accessed with the hostname of the Policy Server's
         [server name](/appendices/#server-name) by making a
         GET request to `https://hostname/.well-known/matrix/policy_server`.
         {{% /boxes/note %}}
@@ -48,6 +48,11 @@ paths:
                     description: |-
                       The unpadded base64-encoded public keys for the Policy Server. MUST contain
                       at least `ed25519`.
+                    properties:
+                      ed25519:
+                        type: string
+                        description: The unpadded base64-encoded ed25519 public key for the Policy Server.
+                    required: ['ed25519']
                     additionalProperties:
                       type: string
                       description: The unpadded base64-encoded public key for the key algorithm.

data/event-schemas/schema/m.room.policy.yaml

@@ -19,6 +19,11 @@ properties:
           The unpadded base64-encoded public keys for the Policy Server. MUST contain at
           least `ed25519`.
         type: object
+        properties:
+          ed25519:
+            type: string
+            description: The unpadded base64-encoded ed25519 public key for the Policy Server.
+        required: ['ed25519']
         additionalProperties:
           description: The unpadded base64-encoded public key for the key algorithm.
           type: string