Rephrase, clarify, and add security considerations & dependencies

proposals/4299-trusted-users.md

@@ -1,5 +1,7 @@
 # MS4299: Trusted Users
 
+> TODO: *trusted* is misleading and conflicting
+
 Currently, Matrix has a way to assign specific users as "ignored", declaring to both your client and server that you
 would not like to interact with a given user, and in some situations would not like them to interact with you.
 However, there is no mechanism to do the inverse - assign specific users as "trusted", even more so define what
@@ -10,36 +12,44 @@ expansion in the future as needs of the protocol change.
 
 For clarity's sake, the following words are used with the associated context throughout this proposal:
 
-- Ignored: [users that are ignored OR blocked][4283]
-- Non-trusted: users who are neither trusted nor ignored (the default state)
-- Trusted: users who are explicitly added to the trusted users account data object
+- Entity/Entities: something that matches an entity that can be trusted (i.e. user ID, room ID, server name, glob pattern)
+- Ignored: [entities that are ignored OR blocked][4283]
+- Non-trusted: entities who are neither trusted nor ignored (the default state)
+- Trusted: entities who are explicitly added to the trusted users account data object
+
+> TODO: users -> entities
 
 While this proposal does not aim to tackle what to *do* with user trust (that's for followup MSCs to define), it lays
-the foundations for defining that a user can be "trusted" at all.
+the foundations for defining that an entity can be "trusted" at all.
 
 Currently, we already have [the ignored users list][1], which allows you to define which users you never want to see.
 This proposal introduces a "trusted users list", which behaves semantically similarly to the ignored users list,
 but the inverse. Clients and servers may wish to give "trusted" users special treatment, like they currently do
 with ignored users. Examples include (but are not limited to) servers filtering invites to only allow trusted users to
 send them, clients disabling media previews and only enabling them by default for trusted users, only allowing
-users to initiate calls if the recipient trusts them, and preventing profile fields
-(display name, avatar, custom fields) being sent to non-trusted users.
+users to initiate calls that reach the recipient if the recipient trusts them, and preventing profile fields
+(display name, avatar, custom fields) being sent to non-trusted users. However, these capabilities are not defined in
+this proposal itself.
 
 Clients can create an account data entry with the type `m.trusted_users`, with the following format:
 
-```json
+```json5
 {
     "trusted_users": {
-        "@user1:example.com": {},
-        "@user2:example.com": {}
+        "@user1:example.com": {}, // specific user
+        "@*:example.com": {},  // all users matching the glob pattern
+        "example.com": {},  // all users on the homeserver example.com
+        "!roomid:example.com": {},  // all members of the specified room
     }
 }
 ```
 
-This event's content should be an object, whose keys are fully qualified user IDs.
-Note that here, the objects following the trusted user IDs (hereon referenced as the "trust configuration") are
+> TODO: restrict globs to server names (i.e. wildcard domains) and user IDs?
+
+This event's content should be an object, whose keys are generic strings that are intended to represent an entity.
+Note that here, the objects following the trusted entities (hereon referenced as the "trust configuration") are
 empty objects - this is to allow for namespaced fields to be added by later MSCs to further extend the capabilities
-of trust.
+of trust (such as aforementioned examples).
 
 An **example** of an extended trust configuration could be:
 
@@ -49,7 +59,7 @@ An **example** of an extended trust configuration could be:
         "@user1:example.com": {
             "com.example.allow_custom_colours": true
         },
-        "@user2:example.com": {}
+        "@*:example.com": {}
     }
 }
 ```
@@ -81,6 +91,13 @@ have overlapping entries. As defined above, ignores should take priority over tr
   extensibility that this one aims to provide. Contrarily, 4155 could be used to build on top of this one.
 - Doing away with ignores, and instead only using trusts, and adding the ability to mark a trust as an ignore/untrust,
   or some other semantically similar meaning. This would be complicated and just generally expensive
+  
+## Security Considerations
+
+- Server-side manipulation: a homeserver's administrators are able to modify account data without notice, which could
+  be used to cause unexpected client/server behaviour. The aforementioned URL preview example
+  [was already a CVE in matrix-react-sdk][CVE-2024-42347], so additional care must be taken when considering followup
+  capabilities.
 
 ## Unstable prefix
 
@@ -90,3 +107,8 @@ Until this proposal is accepted, implementations should make use of the account
 [1]: https://spec.matrix.org/unstable/client-server-api/#mignored_user_list
 [4283]: https://github.com/matrix-org/matrix-spec-proposals/pull/4283
 [4155]: https://github.com/matrix-org/matrix-spec-proposals/pull/4155
+[CVE-2024-42347]: https://github.com/matrix-org/matrix-react-sdk/security/advisories/GHSA-f83w-wqhc-cfp4
+
+## Dependencies
+
+None.