From ef97538b61a16cef1aa5109fc2584daf525f0887 Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Mon, 1 Sep 2025 12:39:50 +0100 Subject: [PATCH 1/3] Initial draft of "MSC4336: Appservice API to suppliment user profiles" --- proposals/4336-as-profile-suppliments.md | 147 +++++++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 proposals/4336-as-profile-suppliments.md diff --git a/proposals/4336-as-profile-suppliments.md b/proposals/4336-as-profile-suppliments.md new file mode 100644 index 00000000000..1021eedc124 --- /dev/null +++ b/proposals/4336-as-profile-suppliments.md @@ -0,0 +1,147 @@ +# MSC4336: Appservice API to suppliment user profiles + +User profiles in Matrix are currently largely stored on the homeserver statically. Clients can +update the static information as often as they like, but it's expected that the homeserver +maintains a copy in it's datastore. This means that having dynamic profile values that may change +depending on a user's status (e.g. "In a meeting") or profiles that may change depending on the +requestor are hard to achieve. + +This proposal extends the appservice API to offer a new route to suppliment a user's profile with +additional fields, or to replace existing ones. + +## Proposal + +A new route is introduced on the Application Service API: + +`GET /_matrix/app/v1/profile/{userId}/{key}` + +This API is authenticated as with the rest of the application service APIs, and takes two additional +*optional* query parameters: + + - `origin_server` The server name of the server requesting the profile, *if* the profile is requested + over federation. Otherwise, omit. + - `from_user_id` The user MxID of the user requesting the profile, *if* the requesting user is known. + Otherwise, omit. + +The path parameters match the C-S API `/profile` GET paramters, where `userId` is the user profile to be +fetched and `key` is an optional field on the profile. If the `key` is ommited, the full profile should be returned. + +The response to the API should be an object representing the profile. Homeservers should call this API +whenever a user's profile is requested by a client or a federated service, and the appservice should return +a profile object. If a `key` is specified then an object should be returned only containing the value for `key`. + +### Examples + +`GET /_matrix/app/v1/profile/@alice:example.org` would return + +```json +{ + "displayName": "Alice S.", + "org.example.holiday": true +} +``` + +and + +`GET /_matrix/app/v1/profile/@alice:example.org/org.example.holiday` would return + +```json +{ + "org.example.holiday": true +} +``` + +### Merging behaviour + +The homeserver should *always* request the profile from the application service even if the `key` is already +present in the user's stored profile. For instance, given a profile of: + +```json +{ + "displayName": "Bob", + "avatar_url": "mxc://foo/bar" +} +``` + +and an appservice response of: + +```json +{ + "displayName": "Alice S.", + "org.example.holiday": true +} +``` + +then the resulting profile for the user will be: + +```json +{ + "avatar_url": "mxc://foo/bar", + "displayName": "Alice S.", + "org.example.holiday": true +} +``` + +### Error codes + +Application services may respond with a `404` `M_NOT_FOUND` if they do not provide any information +for the given `userId`. They may also choose to do this if they do not want to divulge information +about a given user to another user or service. + + +### Caching + +Homeservers should not cache responses to this endpoint as the values may change dynamically. + +TODO: Should we introduce a ETag-like system here so homeservers can cache? + +### Application service selection + +Any homeserver with a matching `namespaces.users` field for the requested `userId` should be used +when querying the profile. The resulting profile should be merged together. The order of application services +here is **NOT** stable, and so if multiple application services set the same field on the same user +then there is potential for instability. Server admins should take care not to register multiple application +services with overlapping namespaces, if they may both alter the profile. + +Implementations MAY choose to specify a guaranteed ordering for application service queries but this is out +of scope for the spec. + +The registration file **MUST** contain `supports_profile_lookup: true` to be considered for profile queries +to reduce the number of requests made to appservices not supporting this feature. + +## Potential issues + +### Performance + +This can place additional delay on the profile endpoint, as now an additional HTTP hit will need to be made. A sensible +maximum response time should probably be specified to reduce the risk of a profile endpoint timing out. Additionally, +the timeout should not prevent a client from reading the resulting profile, without the missing application service response. + +### Instability + +As per the previous section, application service querying is not inheriently stable across homeserver implementations +so overlaps in profiles may lead to unpredicatable results. + +## Alternatives + +Application services already can modify profiles, albeit with no controls over who can view them and with the added +cost of these profiles being stored in the homeserver. There is also no way to update on-demand to reduce the amount +of changes needed to be made to the homeservers stores. + +## Security considerations + +The most obvious security risk is that this MSC opens up the ability to do authed profile requests and alter the response +depending on the requestor. The application service and the homeserver must ensure not to cache these responses globally, +and be careful when validating the requestor. + +TODO: There must be more things that can go wrong here. + +## Unstable prefix + +While this MSC is not considered stable: + - the endpoint will be `/_matrix/app/v1/profile/@alice:example.org` + - the registration file flag will be `msc4336_supports_profile_lookup` + +## Dependencies + +None. \ No newline at end of file From 3b8ce575fb1c71f9edf1485db8a4d6bf323668c4 Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Mon, 1 Sep 2025 12:41:14 +0100 Subject: [PATCH 2/3] too slow -> 4337 --- ...rofile-suppliments.md => 4337-as-profile-suppliments.md} | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) rename proposals/{4336-as-profile-suppliments.md => 4337-as-profile-suppliments.md} (96%) diff --git a/proposals/4336-as-profile-suppliments.md b/proposals/4337-as-profile-suppliments.md similarity index 96% rename from proposals/4336-as-profile-suppliments.md rename to proposals/4337-as-profile-suppliments.md index 1021eedc124..641bda4d282 100644 --- a/proposals/4336-as-profile-suppliments.md +++ b/proposals/4337-as-profile-suppliments.md @@ -1,4 +1,4 @@ -# MSC4336: Appservice API to suppliment user profiles +# MSC4337: Appservice API to suppliment user profiles User profiles in Matrix are currently largely stored on the homeserver statically. Clients can update the static information as often as they like, but it's expected that the homeserver @@ -139,8 +139,8 @@ TODO: There must be more things that can go wrong here. ## Unstable prefix While this MSC is not considered stable: - - the endpoint will be `/_matrix/app/v1/profile/@alice:example.org` - - the registration file flag will be `msc4336_supports_profile_lookup` + - the endpoint will be `/_matrix/app/uk.half-shot.msc4337/profile/@alice:example.org` + - the registration file flag will be `msc4337_supports_profile_lookup` ## Dependencies From 340b30e9231fb74a7a87c3fae70a7308e1622f09 Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Mon, 1 Sep 2025 12:44:05 +0100 Subject: [PATCH 3/3] spelling --- proposals/4337-as-profile-suppliments.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/proposals/4337-as-profile-suppliments.md b/proposals/4337-as-profile-suppliments.md index 641bda4d282..bea258c858f 100644 --- a/proposals/4337-as-profile-suppliments.md +++ b/proposals/4337-as-profile-suppliments.md @@ -1,12 +1,12 @@ -# MSC4337: Appservice API to suppliment user profiles +# MSC4337: Appservice API to supplement user profiles User profiles in Matrix are currently largely stored on the homeserver statically. Clients can update the static information as often as they like, but it's expected that the homeserver maintains a copy in it's datastore. This means that having dynamic profile values that may change depending on a user's status (e.g. "In a meeting") or profiles that may change depending on the -requestor are hard to achieve. +requester are hard to achieve. -This proposal extends the appservice API to offer a new route to suppliment a user's profile with +This proposal extends the appservice API to offer a new route to supplement a user's profile with additional fields, or to replace existing ones. ## Proposal @@ -23,8 +23,8 @@ This API is authenticated as with the rest of the application service APIs, and - `from_user_id` The user MxID of the user requesting the profile, *if* the requesting user is known. Otherwise, omit. -The path parameters match the C-S API `/profile` GET paramters, where `userId` is the user profile to be -fetched and `key` is an optional field on the profile. If the `key` is ommited, the full profile should be returned. +The path parameters match the C-S API `/profile` GET parameters, where `userId` is the user profile to be +fetched and `key` is an optional field on the profile. If the `key` is omitted, the full profile should be returned. The response to the API should be an object representing the profile. Homeservers should call this API whenever a user's profile is requested by a client or a federated service, and the appservice should return @@ -120,7 +120,7 @@ the timeout should not prevent a client from reading the resulting profile, with ### Instability As per the previous section, application service querying is not inheriently stable across homeserver implementations -so overlaps in profiles may lead to unpredicatable results. +so overlaps in profiles may lead to unpredictable results. ## Alternatives @@ -131,8 +131,8 @@ of changes needed to be made to the homeservers stores. ## Security considerations The most obvious security risk is that this MSC opens up the ability to do authed profile requests and alter the response -depending on the requestor. The application service and the homeserver must ensure not to cache these responses globally, -and be careful when validating the requestor. +depending on the requester. The application service and the homeserver must ensure not to cache these responses globally, +and be careful when validating the requester. TODO: There must be more things that can go wrong here.