From afae1083aa62b414782b52e1a7968b2480ce1c72 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 8 Mar 2023 08:06:06 -0500 Subject: [PATCH] Clarify what key content-specific rules match against. (#1441) --- .../newsfragments/1441.clarification | 1 + content/appendices.md | 8 ++++++++ .../modules/moderation_policies.md | 4 ++-- content/client-server-api/modules/push.md | 15 +++++++-------- .../client-server/definitions/push_condition.yaml | 4 ++-- data/api/client-server/definitions/push_rule.yaml | 4 ++-- data/event-schemas/schema/m.room.server_acl.yaml | 10 ++++------ 7 files changed, 26 insertions(+), 20 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1441.clarification diff --git a/changelogs/client_server/newsfragments/1441.clarification b/changelogs/client_server/newsfragments/1441.clarification new file mode 100644 index 00000000..f03519b8 --- /dev/null +++ b/changelogs/client_server/newsfragments/1441.clarification @@ -0,0 +1 @@ +Clarify what event property the content-specific push rules match against. diff --git a/content/appendices.md b/content/appendices.md index 72bda5e9..dc3ced66 100644 --- a/content/appendices.md +++ b/content/appendices.md @@ -934,6 +934,14 @@ The `address` is the telephone number represented as a MSISDN (Mobile Station International Subscriber Directory Number) as defined by the E.164 numbering plan. Note that MSISDNs do not include a leading '+'. +## Glob-style matching + +It is useful to match strings via globbing in some situations. Globbing in Matrix +uses the following rules: + +* The character `*` matches zero or more characters. +* `?` matches exactly one character. + ## Security Threat Model ### Denial of Service diff --git a/content/client-server-api/modules/moderation_policies.md b/content/client-server-api/modules/moderation_policies.md index 910df6a0..82a05963 100644 --- a/content/client-server-api/modules/moderation_policies.md +++ b/content/client-server-api/modules/moderation_policies.md @@ -75,8 +75,8 @@ technique for receiving updates to the policy's rules. #### Events -The `entity` described by the state events can contain `*` and `?` to -match zero or more characters and exactly one character respectively. Note that +The `entity` described by the state events is interpreted as a +[glob-style pattern](/appendices#glob-style-matching). Note that rules against rooms can describe a room ID or room alias - the subscriber is responsible for resolving the alias to a room ID if desired. diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md index 0a104bc1..9c8d0adf 100644 --- a/content/client-server-api/modules/push.md +++ b/content/client-server-api/modules/push.md @@ -155,8 +155,12 @@ The different `kind`s of rule, in the order that they are checked, are: 1. **Content-specific rules (`content`).** These configure behaviour for (unencrypted) messages that match certain patterns. Content rules take one parameter: `pattern`, that gives the - glob pattern to match against. This is treated in the same way as - `pattern` for `event_match`. + [glob-style pattern](/appendices#glob-style-matching) to match against. + The match is performed case-insensitively, and must match any substring of + the `content.body` property which starts and ends at a word boundary. A word + boundary is defined as the start or end of the value, or any character not + in the sets `[A-Z]`, `[a-z]`, `[0-9]` or `_`.The exact meaning of + "case insensitive" is defined by the implementation of the homeserver. 1. **Room-specific rules (`room`).** These rules change the behaviour of all messages for a given room. The @@ -264,18 +268,13 @@ This is a glob pattern match on a field of the event. Parameters: - `key`: The dot-separated path of the property of the event to match, e.g. `content.body`. -- `pattern`: The glob-style pattern to match against. +- `pattern`: The [glob-style pattern](/appendices#glob-style-matching) to match against. The match is performed case-insensitively, and must match the entire value of the event field given by `key` (though see below regarding `content.body`). The exact meaning of "case insensitive" is defined by the implementation of the homeserver. -Within `pattern`: - - * The character `*` matches zero or more characters. - * `?` matches exactly one character. - If the property specified by `key` is completely absent from the event, or does not have a string value, then the condition will not match, even if `pattern` is `*`. diff --git a/data/api/client-server/definitions/push_condition.yaml b/data/api/client-server/definitions/push_condition.yaml index 044f8627..4f2fe472 100644 --- a/data/api/client-server/definitions/push_condition.yaml +++ b/data/api/client-server/definitions/push_condition.yaml @@ -34,8 +34,8 @@ properties: pattern: type: string description: |- - Required for `event_match` conditions. The glob-style pattern to - match against. + Required for `event_match` conditions. The [glob-style pattern](/appendices#glob-style-matching) + to match against. is: type: string description: |- diff --git a/data/api/client-server/definitions/push_rule.yaml b/data/api/client-server/definitions/push_rule.yaml index 19ec89d5..94a9d320 100644 --- a/data/api/client-server/definitions/push_rule.yaml +++ b/data/api/client-server/definitions/push_rule.yaml @@ -46,8 +46,8 @@ properties: pattern: type: string description: |- - The glob-style pattern to match against. Only applicable to `content` - rules. + The [glob-style pattern](/appendices#glob-style-matching) to match against. + Only applicable to `content` rules. required: - actions - default diff --git a/data/event-schemas/schema/m.room.server_acl.yaml b/data/event-schemas/schema/m.room.server_acl.yaml index 744e5231..c7a26c33 100644 --- a/data/event-schemas/schema/m.room.server_acl.yaml +++ b/data/event-schemas/schema/m.room.server_acl.yaml @@ -7,8 +7,8 @@ description: |- server ACL. Servers that do not uphold the ACLs MUST be added to the denied hosts list in order for the ACLs to remain effective. - The `allow` and `deny` lists are lists of globs supporting `?` and `*` - as wildcards. When comparing against the server ACLs, the suspect server's port + The `allow` and `deny` lists are lists of [glob-style patterns](/appendices#glob-style-matching). + When comparing against the server ACLs, the suspect server's port number must not be considered. Therefore `evil.com`, `evil.com:8448`, and `evil.com:1234` would all match rules that apply to `evil.com`, for example. @@ -61,8 +61,7 @@ properties: type: array description: |- The server names to allow in the room, excluding any port information. - Wildcards may be used to cover a wider range of hosts, where `*` - matches zero or more characters and `?` matches exactly one character. + Each entry is interpreted as a [glob-style pattern](/appendices#glob-style-matching). **This defaults to an empty list when not provided, effectively disallowing every server.** @@ -72,8 +71,7 @@ properties: type: array description: |- The server names to disallow in the room, excluding any port information. - Wildcards may be used to cover a wider range of hosts, where `*` - matches zero or more characters and `?` matches exactly one character. + Each entry is interpreted as a [glob-style pattern](/appendices#glob-style-matching). This defaults to an empty list when not provided. items: