From d0b48b9ec9fb7c4ea308c3aefee1231e6e58b180 Mon Sep 17 00:00:00 2001
From: Patrick Cloke <clokep@users.noreply.github.com>
Date: Tue, 7 Mar 2023 11:19:27 -0500
Subject: [PATCH] MSC3966: `event_property_contains` push rule condition
 (#3966)

* Add proposal for exact_event_property_contains push condition.

* Fix incorrect word.

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* Fix broken link.

* Fix typo.

Co-authored-by: Hubert Chathi <hubertc@matrix.org>

* Update condition name.

---------

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Co-authored-by: Hubert Chathi <hubertc@matrix.org>
---
 ...-event-property-contains-push-condition.md | 65 +++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 proposals/3966-exact-event-property-contains-push-condition.md

diff --git a/proposals/3966-exact-event-property-contains-push-condition.md b/proposals/3966-exact-event-property-contains-push-condition.md
new file mode 100644
index 00000000..2619a2a8
--- /dev/null
+++ b/proposals/3966-exact-event-property-contains-push-condition.md
@@ -0,0 +1,65 @@
+# MSC3966: `event_property_contains` push rule condition
+
+[MSC3952](https://github.com/matrix-org/matrix-spec-proposals/pull/3952):
+Intentional mentions requires a way for a push rule condition to search
+for a value in a JSON array of values. This proposes implementing it in a
+generic fashion for re-use with other push rules.
+
+## Proposal
+
+A new push rule condition `event_property_contains` is added which acts like
+[`event_match`](https://spec.matrix.org/v1.5/client-server-api/#conditions-1),
+but searches an array for an exact value. The values must match exactly and be a
+non-compound JSON type allowed by [canonical JSON](https://spec.matrix.org/v1.5/appendices/#canonical-json):
+i.e. strings, `null`, `true`, `false` and integers.
+
+An example condition would look like:
+
+```json
+{
+  "kind": "event_property_contains",
+  "key": "content.my_array",
+  "value": "foo"
+}
+```
+
+This would match an event with content:
+
+```json
+{
+  "content": {
+    "my_array": ["foo", true]
+  }
+}
+```
+
+And it would not match if `my_array` was empty or did not exist.
+
+## Potential issues
+
+None foreseen.
+
+## Alternatives
+
+[MSC3887](https://github.com/matrix-org/matrix-spec-proposals/pull/3887) is an
+unfinished alternative which suggests allowing [`event_match`](https://spec.matrix.org/v1.5/client-server-api/#conditions-1)
+to search in arrays without other changes.
+
+## Security considerations
+
+It is possible for the event content to contain very large arrays (the
+[maximum event size](https://spec.matrix.org/v1.5/client-server-api/#size-limits)
+is 65,536 bytes, if most of that contains an array of empty strings you get
+somewhere around 20,000 entries). Iterating through arrays of this size should
+not be a problem for modern computers, especially since the push rule searches
+for *exact* matches.
+
+## Unstable prefix
+
+During development `org.matrix.msc3966.exact_event_property_contains` shall be
+used in place of `event_property_contains`.
+
+## Dependencies
+
+This MSC has similar semantics to [MSC3758](https://github.com/matrix-org/matrix-spec-proposals/pull/3758)
+(and the implementation builds on that), but it does not strictly depend on it.