From 5287f4415302187ec09785bc7fe2e830ae803741 Mon Sep 17 00:00:00 2001 From: William Kray Date: Tue, 14 Nov 2023 08:00:09 -0800 Subject: [PATCH 01/17] propose a server defined html landing page for use by clients --- .../xxxx-client-server-landing-page-html.md | 61 +++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 proposals/xxxx-client-server-landing-page-html.md diff --git a/proposals/xxxx-client-server-landing-page-html.md b/proposals/xxxx-client-server-landing-page-html.md new file mode 100644 index 00000000000..a8a5fd27519 --- /dev/null +++ b/proposals/xxxx-client-server-landing-page-html.md @@ -0,0 +1,61 @@ +# Server-Defined User Home Pages + +## Abstract +This proposal extends the Matrix protocol to allow servers to define custom HTML-formatted documents that can be rendered by clients as a user home page. This feature introduces a non-intrusive yet flexible manner to communicate server-specific information such as donation requests, scheduled maintenance, updates, new features, and changelogs. + +## Background +Currently, there is no standardized method in Matrix for server admins to communicate information directly within user clients. While rooms can serve this purpose, they lack the persistence and prime visibility that many server administrators desire. + +## Proposal +Introduce an optional configuration for matrix servers that allows them to specify an HTML-formatted document, adhering to the current subset of HTML utilized for message formatting. Clients can render this document in a dedicated "home" view or as a placeholder page when no active conversations are selected. + +## Use Cases + + - Server administrators want to communicate an upcoming maintenance window without emailing all users. + - A non-profit Matrix server could display donation information on the home page to encourage support from its users. + - Announcement of new features or user guides following an update can be nicely formatted and made readily available upon client login. + - Changelogs for server updates can be displayed, helping users to understand recent changes without external navigation. + - Links to other supported clients may be supplied in case users are looking for alternative interfaces. + +## Specification + + - A new optional field will be defined within the well-known Matrix configuration for clients: user_home_page. + - The user_home_page field can be defined by either in-line HTML content or a fully-qualified domain name and path to an HTML document. + - The HTML content will be sanitized by the client and restricted to the subset of HTML currently allowed for messages. + - This field can be queried by clients during the login process or refreshed periodically. + - Clients may choose to implement this feature as a "home" button or as default content in the main view when no conversation is active. + +Example formatting using a file URI: + +``` +{ + "m.user_home_page": { + "html_url": "https://your.website/user_home.html" + } +} +``` + +Example formatting using in-line HTML: + +``` +{ + "m.user_home_page": { + "html_inline": "

Welcome to our Matrix Homeserver!

Visit our website to make a donation.

" + } +} +``` + +## Security Considerations +To mitigate any potential security risks from malicious content: + + - Clients MUST sanitize the HTML content according to the existing rules for message content sanitation. + - External resources (e.g., images, stylesheets) MUST NOT be fetched by default to avoid privacy leaks and must be explicitly allowed by the client. + +## Privacy Considerations +As this feature may potentially be used to track user interaction with the home page content, it's important to: + + - Provide clients the ability to disable external resource fetching. + - Ensure that user privacy preferences are respected when displaying this content. + +## Conclusion +This spec change proposal seeks to empower server administrators with the ability to directly communicate important information to their users within the Matrix client, enhancing the user experience by providing relevant and timely information while respecting user privacy and security. From f25be009959e7cf0d13c4d8f0e57d463bdd59a2c Mon Sep 17 00:00:00 2001 From: William Kray Date: Tue, 14 Nov 2023 08:03:02 -0800 Subject: [PATCH 02/17] update pr number --- .../xxxx-client-server-landing-page-html.md | 61 ------------------- 1 file changed, 61 deletions(-) delete mode 100644 proposals/xxxx-client-server-landing-page-html.md diff --git a/proposals/xxxx-client-server-landing-page-html.md b/proposals/xxxx-client-server-landing-page-html.md deleted file mode 100644 index a8a5fd27519..00000000000 --- a/proposals/xxxx-client-server-landing-page-html.md +++ /dev/null @@ -1,61 +0,0 @@ -# Server-Defined User Home Pages - -## Abstract -This proposal extends the Matrix protocol to allow servers to define custom HTML-formatted documents that can be rendered by clients as a user home page. This feature introduces a non-intrusive yet flexible manner to communicate server-specific information such as donation requests, scheduled maintenance, updates, new features, and changelogs. - -## Background -Currently, there is no standardized method in Matrix for server admins to communicate information directly within user clients. While rooms can serve this purpose, they lack the persistence and prime visibility that many server administrators desire. - -## Proposal -Introduce an optional configuration for matrix servers that allows them to specify an HTML-formatted document, adhering to the current subset of HTML utilized for message formatting. Clients can render this document in a dedicated "home" view or as a placeholder page when no active conversations are selected. - -## Use Cases - - - Server administrators want to communicate an upcoming maintenance window without emailing all users. - - A non-profit Matrix server could display donation information on the home page to encourage support from its users. - - Announcement of new features or user guides following an update can be nicely formatted and made readily available upon client login. - - Changelogs for server updates can be displayed, helping users to understand recent changes without external navigation. - - Links to other supported clients may be supplied in case users are looking for alternative interfaces. - -## Specification - - - A new optional field will be defined within the well-known Matrix configuration for clients: user_home_page. - - The user_home_page field can be defined by either in-line HTML content or a fully-qualified domain name and path to an HTML document. - - The HTML content will be sanitized by the client and restricted to the subset of HTML currently allowed for messages. - - This field can be queried by clients during the login process or refreshed periodically. - - Clients may choose to implement this feature as a "home" button or as default content in the main view when no conversation is active. - -Example formatting using a file URI: - -``` -{ - "m.user_home_page": { - "html_url": "https://your.website/user_home.html" - } -} -``` - -Example formatting using in-line HTML: - -``` -{ - "m.user_home_page": { - "html_inline": "

Welcome to our Matrix Homeserver!

Visit our website to make a donation.

" - } -} -``` - -## Security Considerations -To mitigate any potential security risks from malicious content: - - - Clients MUST sanitize the HTML content according to the existing rules for message content sanitation. - - External resources (e.g., images, stylesheets) MUST NOT be fetched by default to avoid privacy leaks and must be explicitly allowed by the client. - -## Privacy Considerations -As this feature may potentially be used to track user interaction with the home page content, it's important to: - - - Provide clients the ability to disable external resource fetching. - - Ensure that user privacy preferences are respected when displaying this content. - -## Conclusion -This spec change proposal seeks to empower server administrators with the ability to directly communicate important information to their users within the Matrix client, enhancing the user experience by providing relevant and timely information while respecting user privacy and security. From 10c74905192cbb2f0a0de579b16ce8f26b78fa77 Mon Sep 17 00:00:00 2001 From: William Kray Date: Tue, 14 Nov 2023 08:04:00 -0800 Subject: [PATCH 03/17] update pr number --- .../4079-client-server-landing-page-html.md | 61 +++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 proposals/4079-client-server-landing-page-html.md diff --git a/proposals/4079-client-server-landing-page-html.md b/proposals/4079-client-server-landing-page-html.md new file mode 100644 index 00000000000..a8a5fd27519 --- /dev/null +++ b/proposals/4079-client-server-landing-page-html.md @@ -0,0 +1,61 @@ +# Server-Defined User Home Pages + +## Abstract +This proposal extends the Matrix protocol to allow servers to define custom HTML-formatted documents that can be rendered by clients as a user home page. This feature introduces a non-intrusive yet flexible manner to communicate server-specific information such as donation requests, scheduled maintenance, updates, new features, and changelogs. + +## Background +Currently, there is no standardized method in Matrix for server admins to communicate information directly within user clients. While rooms can serve this purpose, they lack the persistence and prime visibility that many server administrators desire. + +## Proposal +Introduce an optional configuration for matrix servers that allows them to specify an HTML-formatted document, adhering to the current subset of HTML utilized for message formatting. Clients can render this document in a dedicated "home" view or as a placeholder page when no active conversations are selected. + +## Use Cases + + - Server administrators want to communicate an upcoming maintenance window without emailing all users. + - A non-profit Matrix server could display donation information on the home page to encourage support from its users. + - Announcement of new features or user guides following an update can be nicely formatted and made readily available upon client login. + - Changelogs for server updates can be displayed, helping users to understand recent changes without external navigation. + - Links to other supported clients may be supplied in case users are looking for alternative interfaces. + +## Specification + + - A new optional field will be defined within the well-known Matrix configuration for clients: user_home_page. + - The user_home_page field can be defined by either in-line HTML content or a fully-qualified domain name and path to an HTML document. + - The HTML content will be sanitized by the client and restricted to the subset of HTML currently allowed for messages. + - This field can be queried by clients during the login process or refreshed periodically. + - Clients may choose to implement this feature as a "home" button or as default content in the main view when no conversation is active. + +Example formatting using a file URI: + +``` +{ + "m.user_home_page": { + "html_url": "https://your.website/user_home.html" + } +} +``` + +Example formatting using in-line HTML: + +``` +{ + "m.user_home_page": { + "html_inline": "

Welcome to our Matrix Homeserver!

Visit our website to make a donation.

" + } +} +``` + +## Security Considerations +To mitigate any potential security risks from malicious content: + + - Clients MUST sanitize the HTML content according to the existing rules for message content sanitation. + - External resources (e.g., images, stylesheets) MUST NOT be fetched by default to avoid privacy leaks and must be explicitly allowed by the client. + +## Privacy Considerations +As this feature may potentially be used to track user interaction with the home page content, it's important to: + + - Provide clients the ability to disable external resource fetching. + - Ensure that user privacy preferences are respected when displaying this content. + +## Conclusion +This spec change proposal seeks to empower server administrators with the ability to directly communicate important information to their users within the Matrix client, enhancing the user experience by providing relevant and timely information while respecting user privacy and security. From 56687caca879199fc5213c320d262eb923f54066 Mon Sep 17 00:00:00 2001 From: William Kray Date: Tue, 14 Nov 2023 08:10:31 -0800 Subject: [PATCH 04/17] update json format --- .../4079-client-server-landing-page-html.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/proposals/4079-client-server-landing-page-html.md b/proposals/4079-client-server-landing-page-html.md index a8a5fd27519..23de6b82060 100644 --- a/proposals/4079-client-server-landing-page-html.md +++ b/proposals/4079-client-server-landing-page-html.md @@ -25,12 +25,17 @@ Introduce an optional configuration for matrix servers that allows them to speci - This field can be queried by clients during the login process or refreshed periodically. - Clients may choose to implement this feature as a "home" button or as default content in the main view when no conversation is active. +## Examples + +Advertisement of the content for clients to use would be done via `/.well-known/matrix/client` within the existing +`m.homeserver` object. + Example formatting using a file URI: ``` { - "m.user_home_page": { - "html_url": "https://your.website/user_home.html" + "m.homeserver": { + "user_home_page_uri": "https://your.website/user_home.html" } } ``` @@ -39,12 +44,15 @@ Example formatting using in-line HTML: ``` { - "m.user_home_page": { - "html_inline": "

Welcome to our Matrix Homeserver!

Visit our website to make a donation.

" + "m.homeserver": { + "user_home_page_html": "

Welcome to our Matrix Homeserver!

Visit our website to make a donation.

" } } ``` +Only one value is needed. If both in-line and URI definitions are defined, clients will prioritize the in-line HTML. + + ## Security Considerations To mitigate any potential security risks from malicious content: From 71210b41c401514b2cdc0a8bb334cc736b3304e8 Mon Sep 17 00:00:00 2001 From: William Kray Date: Tue, 14 Nov 2023 08:15:14 -0800 Subject: [PATCH 05/17] fix line wrapping --- .../4079-client-server-landing-page-html.md | 78 +++++++++---------- 1 file changed, 38 insertions(+), 40 deletions(-) diff --git a/proposals/4079-client-server-landing-page-html.md b/proposals/4079-client-server-landing-page-html.md index 23de6b82060..2007317ab20 100644 --- a/proposals/4079-client-server-landing-page-html.md +++ b/proposals/4079-client-server-landing-page-html.md @@ -1,29 +1,37 @@ # Server-Defined User Home Pages -## Abstract -This proposal extends the Matrix protocol to allow servers to define custom HTML-formatted documents that can be rendered by clients as a user home page. This feature introduces a non-intrusive yet flexible manner to communicate server-specific information such as donation requests, scheduled maintenance, updates, new features, and changelogs. +## Abstract This proposal extends the Matrix protocol to allow servers to define custom HTML-formatted documents that +can be rendered by clients as a user home page. This feature introduces a non-intrusive yet flexible manner to +communicate server-specific information such as donation requests, scheduled maintenance, updates, new features, and +changelogs. -## Background -Currently, there is no standardized method in Matrix for server admins to communicate information directly within user clients. While rooms can serve this purpose, they lack the persistence and prime visibility that many server administrators desire. +## Background Currently, there is no standardized method in Matrix for server admins to communicate information directly +within user clients. While rooms can serve this purpose, they lack the persistence and prime visibility that many server +administrators desire. -## Proposal -Introduce an optional configuration for matrix servers that allows them to specify an HTML-formatted document, adhering to the current subset of HTML utilized for message formatting. Clients can render this document in a dedicated "home" view or as a placeholder page when no active conversations are selected. +## Proposal Introduce an optional configuration for matrix servers that allows them to specify an HTML-formatted +document, adhering to the current subset of HTML utilized for message formatting. Clients can render this document in a +dedicated "home" view or as a placeholder page when no active conversations are selected. ## Use Cases - - Server administrators want to communicate an upcoming maintenance window without emailing all users. - - A non-profit Matrix server could display donation information on the home page to encourage support from its users. - - Announcement of new features or user guides following an update can be nicely formatted and made readily available upon client login. - - Changelogs for server updates can be displayed, helping users to understand recent changes without external navigation. - - Links to other supported clients may be supplied in case users are looking for alternative interfaces. +- Server administrators want to communicate an upcoming maintenance window without emailing all users. +- A non-profit Matrix server could display donation information on the home page to encourage support from its users. +- Announcement of new features or user guides following an update can be nicely formatted and made readily available + upon client login. +- Changelogs for server updates can be displayed, helping users to understand recent changes without external + navigation. +- Links to other supported clients may be supplied in case users are looking for alternative interfaces. ## Specification - - A new optional field will be defined within the well-known Matrix configuration for clients: user_home_page. - - The user_home_page field can be defined by either in-line HTML content or a fully-qualified domain name and path to an HTML document. - - The HTML content will be sanitized by the client and restricted to the subset of HTML currently allowed for messages. - - This field can be queried by clients during the login process or refreshed periodically. - - Clients may choose to implement this feature as a "home" button or as default content in the main view when no conversation is active. +- A new optional field will be defined within the well-known Matrix configuration for clients: user_home_page. +- The user_home_page field can be defined by either in-line HTML content or a fully-qualified domain name and path to an + HTML document. +- The HTML content will be sanitized by the client and restricted to the subset of HTML currently allowed for messages. +- This field can be queried by clients during the login process or refreshed periodically. +- Clients may choose to implement this feature as a "home" button or as default content in the main view when no + conversation is active. ## Examples @@ -32,38 +40,28 @@ Advertisement of the content for clients to use would be done via `/.well-known/ Example formatting using a file URI: -``` -{ - "m.homeserver": { - "user_home_page_uri": "https://your.website/user_home.html" - } -} -``` +``` { "m.homeserver": { "user_home_page_uri": "https://your.website/user_home.html" } } ``` Example formatting using in-line HTML: -``` -{ - "m.homeserver": { - "user_home_page_html": "

Welcome to our Matrix Homeserver!

Visit our website to make a donation.

" - } -} -``` +``` { "m.homeserver": { "user_home_page_html": "

Welcome to our Matrix Homeserver!

Visit our website to make a +donation.

" } } ``` Only one value is needed. If both in-line and URI definitions are defined, clients will prioritize the in-line HTML. -## Security Considerations -To mitigate any potential security risks from malicious content: +## Security Considerations To mitigate any potential security risks from malicious content: - - Clients MUST sanitize the HTML content according to the existing rules for message content sanitation. - - External resources (e.g., images, stylesheets) MUST NOT be fetched by default to avoid privacy leaks and must be explicitly allowed by the client. +- Clients MUST sanitize the HTML content according to the existing rules for message content sanitation. +- External resources (e.g., images, stylesheets) MUST NOT be fetched by default to avoid privacy leaks and must be + explicitly allowed by the client. -## Privacy Considerations -As this feature may potentially be used to track user interaction with the home page content, it's important to: +## Privacy Considerations As this feature may potentially be used to track user interaction with the home page content, +it's important to: - - Provide clients the ability to disable external resource fetching. - - Ensure that user privacy preferences are respected when displaying this content. +- Provide clients the ability to disable external resource fetching. +- Ensure that user privacy preferences are respected when displaying this content. -## Conclusion -This spec change proposal seeks to empower server administrators with the ability to directly communicate important information to their users within the Matrix client, enhancing the user experience by providing relevant and timely information while respecting user privacy and security. +## Conclusion This spec change proposal seeks to empower server administrators with the ability to directly communicate +important information to their users within the Matrix client, enhancing the user experience by providing relevant and +timely information while respecting user privacy and security. From 3d116a46dfb860caec0cef20e4f341c104e0faaf Mon Sep 17 00:00:00 2001 From: William Kray Date: Tue, 14 Nov 2023 08:19:49 -0800 Subject: [PATCH 06/17] one more update to shrink line-length a bit --- .../4079-client-server-landing-page-html.md | 81 ++++++++++--------- 1 file changed, 45 insertions(+), 36 deletions(-) diff --git a/proposals/4079-client-server-landing-page-html.md b/proposals/4079-client-server-landing-page-html.md index 2007317ab20..011262c7c2b 100644 --- a/proposals/4079-client-server-landing-page-html.md +++ b/proposals/4079-client-server-landing-page-html.md @@ -1,42 +1,48 @@ # Server-Defined User Home Pages -## Abstract This proposal extends the Matrix protocol to allow servers to define custom HTML-formatted documents that -can be rendered by clients as a user home page. This feature introduces a non-intrusive yet flexible manner to -communicate server-specific information such as donation requests, scheduled maintenance, updates, new features, and -changelogs. +## Abstract This proposal extends the Matrix protocol to allow servers to define custom +HTML-formatted documents that can be rendered by clients as a user home page. This feature +introduces a non-intrusive yet flexible manner to communicate server-specific information such as +donation requests, scheduled maintenance, updates, new features, and changelogs. -## Background Currently, there is no standardized method in Matrix for server admins to communicate information directly -within user clients. While rooms can serve this purpose, they lack the persistence and prime visibility that many server -administrators desire. +## Background Currently, there is no standardized method in Matrix for server admins to communicate +information directly within user clients. While rooms can serve this purpose, they lack the +persistence and prime visibility that many server administrators desire. -## Proposal Introduce an optional configuration for matrix servers that allows them to specify an HTML-formatted -document, adhering to the current subset of HTML utilized for message formatting. Clients can render this document in a -dedicated "home" view or as a placeholder page when no active conversations are selected. +## Proposal Introduce an optional configuration for matrix servers that allows them to specify an +HTML-formatted document, adhering to the current subset of HTML utilized for message formatting. +Clients can render this document in a dedicated "home" view or as a placeholder page when no active +conversations are selected. ## Use Cases -- Server administrators want to communicate an upcoming maintenance window without emailing all users. -- A non-profit Matrix server could display donation information on the home page to encourage support from its users. -- Announcement of new features or user guides following an update can be nicely formatted and made readily available - upon client login. -- Changelogs for server updates can be displayed, helping users to understand recent changes without external - navigation. -- Links to other supported clients may be supplied in case users are looking for alternative interfaces. +- Server administrators want to communicate an upcoming maintenance window without emailing all + users. +- A non-profit Matrix server could display donation information on the home page to encourage + support from its users. +- Announcement of new features or user guides following an update can be nicely formatted and made + readily available upon client login. +- Changelogs for server updates can be displayed, helping users to understand recent changes without + external navigation. +- Links to other supported clients may be supplied in case users are looking for alternative + interfaces. ## Specification -- A new optional field will be defined within the well-known Matrix configuration for clients: user_home_page. -- The user_home_page field can be defined by either in-line HTML content or a fully-qualified domain name and path to an - HTML document. -- The HTML content will be sanitized by the client and restricted to the subset of HTML currently allowed for messages. +- A new optional field will be defined within the well-known Matrix configuration for clients: + user_home_page. +- The user_home_page field can be defined by either in-line HTML content or a fully-qualified domain + name and path to an HTML document. +- The HTML content will be sanitized by the client and restricted to the subset of HTML currently + allowed for messages. - This field can be queried by clients during the login process or refreshed periodically. -- Clients may choose to implement this feature as a "home" button or as default content in the main view when no - conversation is active. +- Clients may choose to implement this feature as a "home" button or as default content in the main + view when no conversation is active. ## Examples -Advertisement of the content for clients to use would be done via `/.well-known/matrix/client` within the existing -`m.homeserver` object. +Advertisement of the content for clients to use would be done via `/.well-known/matrix/client` +within the existing `m.homeserver` object. Example formatting using a file URI: @@ -44,24 +50,27 @@ Example formatting using a file URI: Example formatting using in-line HTML: -``` { "m.homeserver": { "user_home_page_html": "

Welcome to our Matrix Homeserver!

Visit our website to make a -donation.

" } } ``` +``` { "m.homeserver": { "user_home_page_html": "

Welcome to our Matrix Homeserver!

Visit +our website to make a donation.

" } } ``` -Only one value is needed. If both in-line and URI definitions are defined, clients will prioritize the in-line HTML. +Only one value is needed. If both in-line and URI definitions are defined, clients will prioritize +the in-line HTML. ## Security Considerations To mitigate any potential security risks from malicious content: -- Clients MUST sanitize the HTML content according to the existing rules for message content sanitation. -- External resources (e.g., images, stylesheets) MUST NOT be fetched by default to avoid privacy leaks and must be - explicitly allowed by the client. +- Clients MUST sanitize the HTML content according to the existing rules for message content + sanitation. +- External resources (e.g., images, stylesheets) MUST NOT be fetched by default to avoid privacy + leaks and must be explicitly allowed by the client. -## Privacy Considerations As this feature may potentially be used to track user interaction with the home page content, -it's important to: +## Privacy Considerations As this feature may potentially be used to track user interaction with the +home page content, it's important to: - Provide clients the ability to disable external resource fetching. - Ensure that user privacy preferences are respected when displaying this content. -## Conclusion This spec change proposal seeks to empower server administrators with the ability to directly communicate -important information to their users within the Matrix client, enhancing the user experience by providing relevant and -timely information while respecting user privacy and security. +## Conclusion This spec change proposal seeks to empower server administrators with the ability to +directly communicate important information to their users within the Matrix client, enhancing the +user experience by providing relevant and timely information while respecting user privacy and +security. From 5f15664d88ba5e75f6e5ef06d36eb9cccd596a23 Mon Sep 17 00:00:00 2001 From: William Kray Date: Tue, 14 Nov 2023 08:29:18 -0800 Subject: [PATCH 07/17] fix formatting again and include more realistic refresh times --- .../4079-client-server-landing-page-html.md | 20 +++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/proposals/4079-client-server-landing-page-html.md b/proposals/4079-client-server-landing-page-html.md index 011262c7c2b..dded512c362 100644 --- a/proposals/4079-client-server-landing-page-html.md +++ b/proposals/4079-client-server-landing-page-html.md @@ -35,7 +35,8 @@ conversations are selected. name and path to an HTML document. - The HTML content will be sanitized by the client and restricted to the subset of HTML currently allowed for messages. -- This field can be queried by clients during the login process or refreshed periodically. +- This field can be queried by clients during the login or initial loading process, and refreshed at + least once every 12 hours if the client has been open the entire time. - Clients may choose to implement this feature as a "home" button or as default content in the main view when no conversation is active. @@ -46,12 +47,23 @@ within the existing `m.homeserver` object. Example formatting using a file URI: -``` { "m.homeserver": { "user_home_page_uri": "https://your.website/user_home.html" } } ``` +``` +{ + "m.homeserver": { + "user_home_page_uri": "https://your.website/user_home.html" + } +} +``` Example formatting using in-line HTML: -``` { "m.homeserver": { "user_home_page_html": "

Welcome to our Matrix Homeserver!

Visit -our website to make a donation.

" } } ``` +``` +{ + "m.homeserver": { + "user_home_page_html": "

Welcome to our Matrix Homeserver!

Visit our website to make a donation.

" + } +} +``` Only one value is needed. If both in-line and URI definitions are defined, clients will prioritize the in-line HTML. From fdf133b1218c55135508955e1ccb4a78d92adf61 Mon Sep 17 00:00:00 2001 From: William Kray Date: Tue, 14 Nov 2023 08:30:49 -0800 Subject: [PATCH 08/17] omg more formatting, sorry im multitasking --- .../4079-client-server-landing-page-html.md | 24 ++++++++++++++----- 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/proposals/4079-client-server-landing-page-html.md b/proposals/4079-client-server-landing-page-html.md index dded512c362..23cc5692936 100644 --- a/proposals/4079-client-server-landing-page-html.md +++ b/proposals/4079-client-server-landing-page-html.md @@ -1,15 +1,21 @@ # Server-Defined User Home Pages -## Abstract This proposal extends the Matrix protocol to allow servers to define custom +## Abstract + +This proposal extends the Matrix protocol to allow servers to define custom HTML-formatted documents that can be rendered by clients as a user home page. This feature introduces a non-intrusive yet flexible manner to communicate server-specific information such as donation requests, scheduled maintenance, updates, new features, and changelogs. -## Background Currently, there is no standardized method in Matrix for server admins to communicate +## Background + +Currently, there is no standardized method in Matrix for server admins to communicate information directly within user clients. While rooms can serve this purpose, they lack the persistence and prime visibility that many server administrators desire. -## Proposal Introduce an optional configuration for matrix servers that allows them to specify an +## Proposal + +Introduce an optional configuration for matrix servers that allows them to specify an HTML-formatted document, adhering to the current subset of HTML utilized for message formatting. Clients can render this document in a dedicated "home" view or as a placeholder page when no active conversations are selected. @@ -69,20 +75,26 @@ Only one value is needed. If both in-line and URI definitions are defined, clien the in-line HTML. -## Security Considerations To mitigate any potential security risks from malicious content: +## Security Considerations + +To mitigate any potential security risks from malicious content: - Clients MUST sanitize the HTML content according to the existing rules for message content sanitation. - External resources (e.g., images, stylesheets) MUST NOT be fetched by default to avoid privacy leaks and must be explicitly allowed by the client. -## Privacy Considerations As this feature may potentially be used to track user interaction with the +## Privacy Considerations + +As this feature may potentially be used to track user interaction with the home page content, it's important to: - Provide clients the ability to disable external resource fetching. - Ensure that user privacy preferences are respected when displaying this content. -## Conclusion This spec change proposal seeks to empower server administrators with the ability to +## Conclusion + +This spec change proposal seeks to empower server administrators with the ability to directly communicate important information to their users within the Matrix client, enhancing the user experience by providing relevant and timely information while respecting user privacy and security. From 514079f5be25879ea1c10dfbbe5e754f3951c349 Mon Sep 17 00:00:00 2001 From: William Kray Date: Tue, 14 Nov 2023 08:34:02 -0800 Subject: [PATCH 09/17] Update proposals/4079-client-server-landing-page-html.md Co-authored-by: Hubert Chathi --- proposals/4079-client-server-landing-page-html.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4079-client-server-landing-page-html.md b/proposals/4079-client-server-landing-page-html.md index 23cc5692936..cdef349ec59 100644 --- a/proposals/4079-client-server-landing-page-html.md +++ b/proposals/4079-client-server-landing-page-html.md @@ -1,4 +1,4 @@ -# Server-Defined User Home Pages +# MSC4079: Server-Defined User Home Pages ## Abstract From 15187c6e421594e542ff8111ff4638c948a0893b Mon Sep 17 00:00:00 2001 From: William Kray Date: Tue, 14 Nov 2023 08:36:26 -0800 Subject: [PATCH 10/17] update intro to comment on server notices --- proposals/4079-client-server-landing-page-html.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/proposals/4079-client-server-landing-page-html.md b/proposals/4079-client-server-landing-page-html.md index cdef349ec59..c93f7977762 100644 --- a/proposals/4079-client-server-landing-page-html.md +++ b/proposals/4079-client-server-landing-page-html.md @@ -9,9 +9,11 @@ donation requests, scheduled maintenance, updates, new features, and changelogs. ## Background -Currently, there is no standardized method in Matrix for server admins to communicate -information directly within user clients. While rooms can serve this purpose, they lack the -persistence and prime visibility that many server administrators desire. +Currently, there is no standardized method in Matrix for server admins to communicate information +directly within user clients in a passive way. While rooms can serve this purpose, they lack the +persistence and prime visibility that many server administrators desire. Similarly, server-notices +are aggressive notifications to users that can cause unnecessary noise, and are implemented as +rooms. ## Proposal From 7b54dd8535435bae995c1f55606d246664f7849a Mon Sep 17 00:00:00 2001 From: William Kray Date: Tue, 14 Nov 2023 09:23:45 -0800 Subject: [PATCH 11/17] allow mxc media --- proposals/4079-client-server-landing-page-html.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/proposals/4079-client-server-landing-page-html.md b/proposals/4079-client-server-landing-page-html.md index c93f7977762..00d024bc556 100644 --- a/proposals/4079-client-server-landing-page-html.md +++ b/proposals/4079-client-server-landing-page-html.md @@ -83,8 +83,9 @@ To mitigate any potential security risks from malicious content: - Clients MUST sanitize the HTML content according to the existing rules for message content sanitation. -- External resources (e.g., images, stylesheets) MUST NOT be fetched by default to avoid privacy - leaks and must be explicitly allowed by the client. +- External resources (e.g., scripts, stylesheets) MUST NOT be fetched by default to avoid privacy + leaks and must be explicitly allowed by the client. Images or files may be rendered and linked + using mxc URIs for native matrix media serving. ## Privacy Considerations From 8d0344a757ededc287cf659afcc9cba30d80d448 Mon Sep 17 00:00:00 2001 From: William Kray Date: Tue, 14 Nov 2023 10:20:08 -0800 Subject: [PATCH 12/17] attempt to make compatible with extensible events --- .../4079-client-server-landing-page-html.md | 39 ++++++++++++++----- 1 file changed, 30 insertions(+), 9 deletions(-) diff --git a/proposals/4079-client-server-landing-page-html.md b/proposals/4079-client-server-landing-page-html.md index 00d024bc556..34386a99ed8 100644 --- a/proposals/4079-client-server-landing-page-html.md +++ b/proposals/4079-client-server-landing-page-html.md @@ -39,9 +39,12 @@ conversations are selected. - A new optional field will be defined within the well-known Matrix configuration for clients: user_home_page. -- The user_home_page field can be defined by either in-line HTML content or a fully-qualified domain - name and path to an HTML document. -- The HTML content will be sanitized by the client and restricted to the subset of HTML currently +- The user_home_page field can be defined as a list of formats following the [Extensible Event +MSC](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/1767-extensible-events.md), + allowing clients which do not render a specific format to fall back to other message types. HTML + is supported as either in-line, or by pointing to an html file at an accessible http(s) endpoint + reachable by the client. +- HTML content will be sanitized by the client and restricted to the subset of HTML currently allowed for messages. - This field can be queried by clients during the login or initial loading process, and refreshed at least once every 12 hours if the client has been open the entire time. @@ -58,7 +61,16 @@ Example formatting using a file URI: ``` { "m.homeserver": { - "user_home_page_uri": "https://your.website/user_home.html" + "user_home_page": [ + { + "mimetype": "text/plain", + "body": "# Visit https://your.domain/user-home.html for the latest server announcements." + }, + { + "mimetype": "text/html", + "body": "https://your.domain/user-home.html" + } + ] } } ``` @@ -68,14 +80,23 @@ Example formatting using in-line HTML: ``` { "m.homeserver": { - "user_home_page_html": "

Welcome to our Matrix Homeserver!

Visit our website to make a donation.

" - } + "user_home_page": [ + { + "mimetype": "text/plain", + "body": "# Welcome to our Matrix Homeserver!\nVisit our website to make a donation." + }, + { + "mimetype": "text/html", + "body": "

Welcome to our Matrix Homeserver!

Visit our website to make a donation.

" + } + ] + } } ``` -Only one value is needed. If both in-line and URI definitions are defined, clients will prioritize -the in-line HTML. - +Only one value is needed for clients to serve the content. If more than one is presented, the same +standards used the the [Extensible Event +MSC](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/1767-extensible-events.md) are used to choose a format to render. ## Security Considerations From 4f4a81e8d506dccf217af9556e7906ab150b744f Mon Sep 17 00:00:00 2001 From: William Kray Date: Tue, 14 Nov 2023 11:31:09 -0800 Subject: [PATCH 13/17] couple more tweaks to make html more optional --- proposals/4079-client-server-landing-page-html.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/4079-client-server-landing-page-html.md b/proposals/4079-client-server-landing-page-html.md index 34386a99ed8..a3eea7d7b36 100644 --- a/proposals/4079-client-server-landing-page-html.md +++ b/proposals/4079-client-server-landing-page-html.md @@ -3,7 +3,7 @@ ## Abstract This proposal extends the Matrix protocol to allow servers to define custom -HTML-formatted documents that can be rendered by clients as a user home page. This feature +formatted documents that can be rendered by clients as a user home page. This feature introduces a non-intrusive yet flexible manner to communicate server-specific information such as donation requests, scheduled maintenance, updates, new features, and changelogs. @@ -17,7 +17,7 @@ rooms. ## Proposal -Introduce an optional configuration for matrix servers that allows them to specify an +Introduce an optional configuration for matrix servers that allows them to specify an optionally HTML-formatted document, adhering to the current subset of HTML utilized for message formatting. Clients can render this document in a dedicated "home" view or as a placeholder page when no active conversations are selected. From 8d53f93b71d8cf91392f59dd59939f9e717011ff Mon Sep 17 00:00:00 2001 From: William Kray Date: Wed, 15 Nov 2023 07:30:05 -0800 Subject: [PATCH 14/17] rename field landing page, clarify reload timing more --- proposals/4079-client-server-landing-page-html.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/proposals/4079-client-server-landing-page-html.md b/proposals/4079-client-server-landing-page-html.md index a3eea7d7b36..1100eb3104a 100644 --- a/proposals/4079-client-server-landing-page-html.md +++ b/proposals/4079-client-server-landing-page-html.md @@ -3,7 +3,7 @@ ## Abstract This proposal extends the Matrix protocol to allow servers to define custom -formatted documents that can be rendered by clients as a user home page. This feature +formatted documents that can be rendered by clients as a homeserver landing page. This feature introduces a non-intrusive yet flexible manner to communicate server-specific information such as donation requests, scheduled maintenance, updates, new features, and changelogs. @@ -38,8 +38,8 @@ conversations are selected. ## Specification - A new optional field will be defined within the well-known Matrix configuration for clients: - user_home_page. -- The user_home_page field can be defined as a list of formats following the [Extensible Event + landing_page. This is nested within the `m.homeserver` object. +- The landing_page field can be defined as a list of formats following the [Extensible Event MSC](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/1767-extensible-events.md), allowing clients which do not render a specific format to fall back to other message types. HTML is supported as either in-line, or by pointing to an html file at an accessible http(s) endpoint @@ -47,7 +47,8 @@ MSC](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/176 - HTML content will be sanitized by the client and restricted to the subset of HTML currently allowed for messages. - This field can be queried by clients during the login or initial loading process, and refreshed at - least once every 12 hours if the client has been open the entire time. + least once every 12 hours if the client has been open the entire time. These are minimums, and + clients may choose to load and reload this content more frequently. - Clients may choose to implement this feature as a "home" button or as default content in the main view when no conversation is active. @@ -61,7 +62,7 @@ Example formatting using a file URI: ``` { "m.homeserver": { - "user_home_page": [ + "landing_page": [ { "mimetype": "text/plain", "body": "# Visit https://your.domain/user-home.html for the latest server announcements." @@ -80,7 +81,7 @@ Example formatting using in-line HTML: ``` { "m.homeserver": { - "user_home_page": [ + "landing_page": [ { "mimetype": "text/plain", "body": "# Welcome to our Matrix Homeserver!\nVisit our website to make a donation." From b032ae9d9efb5333823a17071b30914298bc2f75 Mon Sep 17 00:00:00 2001 From: William Kray Date: Fri, 17 Nov 2023 07:59:07 -0800 Subject: [PATCH 15/17] update file uri example to use the right mimetype --- proposals/4079-client-server-landing-page-html.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4079-client-server-landing-page-html.md b/proposals/4079-client-server-landing-page-html.md index 1100eb3104a..a03c1c01fd6 100644 --- a/proposals/4079-client-server-landing-page-html.md +++ b/proposals/4079-client-server-landing-page-html.md @@ -68,7 +68,7 @@ Example formatting using a file URI: "body": "# Visit https://your.domain/user-home.html for the latest server announcements." }, { - "mimetype": "text/html", + "mimetype": "application/http", "body": "https://your.domain/user-home.html" } ] From 0184f3095b0b95dd7703ccf4b8a02fd6e938ca86 Mon Sep 17 00:00:00 2001 From: William Kray Date: Fri, 17 Nov 2023 11:33:00 -0800 Subject: [PATCH 16/17] update title to avoid confusion as this is not for user-specific data --- proposals/4079-client-server-landing-page-html.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4079-client-server-landing-page-html.md b/proposals/4079-client-server-landing-page-html.md index a03c1c01fd6..5f875964025 100644 --- a/proposals/4079-client-server-landing-page-html.md +++ b/proposals/4079-client-server-landing-page-html.md @@ -1,4 +1,4 @@ -# MSC4079: Server-Defined User Home Pages +# MSC4079: Server-Defined Client Landing Pages ## Abstract From bf22ba84a7b3da0a47bb936f3848411eba2add9f Mon Sep 17 00:00:00 2001 From: William Kray Date: Mon, 20 Nov 2023 08:10:53 -0800 Subject: [PATCH 17/17] make minimum support threshold more clear --- proposals/4079-client-server-landing-page-html.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/proposals/4079-client-server-landing-page-html.md b/proposals/4079-client-server-landing-page-html.md index 5f875964025..f56663f285b 100644 --- a/proposals/4079-client-server-landing-page-html.md +++ b/proposals/4079-client-server-landing-page-html.md @@ -51,6 +51,9 @@ MSC](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/176 clients may choose to load and reload this content more frequently. - Clients may choose to implement this feature as a "home" button or as default content in the main view when no conversation is active. +- Clients that support this functionality must at minimum support a plaintext formatting for minimum + functionality. Additional formats and mimetypes are optional but may provide a superior user + experience. ## Examples