Skip to main content

tuwunel_core/config/
profile.rs

1//! Configures profile access, updates, and remote caching.
2//!
3//! Visibility settings distinguish client and federation requests. Field
4//! limits bound cached profiles and requested selections.
5
6use serde::Deserialize;
7use tuwunel_macros::config_example_generator;
8
9use super::true_fn;
10
11/// User profiles
12///
13/// Controls who can read profiles, whether users can change their own
14/// display name and avatar, and how much of a remote profile is cached. By
15/// default the client profile endpoints answer without an access token,
16/// other servers can look up local profiles, and device names are not
17/// shared over federation.
18///
19/// Tips:
20/// - To hide profiles from people outside a user's rooms, set
21///   `require_auth` and `limit_requests_to_users_who_share_rooms` together;
22///   startup and reload refuse the second alone. Requests from other
23///   servers are governed by `allow_inbound_federation_lookups` instead.
24#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
25#[derive(Clone, Copy, Debug, Deserialize)]
26#[config_example_generator(
27	filename = "tuwunel-example.toml",
28	section = "global.profile",
29	group = "true"
30)]
31pub struct Profile {
32	/// Requires authentication on profile retrieval endpoints when enabled.
33	///
34	/// This covers normally unauthenticated GET requests to
35	/// `/_matrix/client/v3/profile/{userId}` and can prevent profile scraping.
36	///
37	/// reloadable: yes
38	/// legacy: require_auth_for_profile_requests
39	#[serde(default)]
40	pub require_auth: bool,
41
42	/// Limits fields retained in a remote user's cached profile.
43	///
44	/// The count includes `displayname` and `avatar_url` and must exceed zero.
45	/// A refresh exceeding it is rejected without changing the cache. Lowering
46	/// the limit leaves existing profiles intact, but subsequent refreshes
47	/// must fit.
48	///
49	/// reloadable: yes
50	/// default: 100
51	/// legacy: max_remote_profile_fields
52	#[serde(default = "default_max_remote_fields")]
53	pub max_remote_fields: usize,
54
55	/// Limits selected profile fields in a sync request or stored filter.
56	///
57	/// This positive limit counts raw selectors before deduplication in
58	/// sliding and legacy sync; requests exceeding it or the 255-byte name
59	/// limit are rejected. Sliding sync retains normalized selections when
60	/// selectors are omitted, so after lowering the limit an oversized
61	/// selection needs replacement or a restarted connection. Unfiltered
62	/// sliding-sync profiles are not limited by this count.
63	///
64	/// reloadable: yes
65	/// default: 64
66	/// legacy: max_profile_fields_per_request
67	#[serde(default = "default_max_fields_per_request")]
68	pub max_fields_per_request: usize,
69
70	/// Allows standard users to set or clear display names through the client
71	/// profile API.
72	///
73	/// Server admins and appservices can always change display names.
74	///
75	/// reloadable: yes
76	/// default: true
77	/// legacy: enable_set_displayname
78	#[serde(default = "true_fn")]
79	pub enable_set_displayname: bool,
80
81	/// Allows standard users to set or clear avatars through the client
82	/// profile API.
83	///
84	/// Server admins and appservices can always change avatars. Unlike
85	/// Synapse's option of the same name, disabling this also stops users
86	/// without an avatar from setting their first one.
87	///
88	/// reloadable: yes
89	/// default: true
90	#[serde(default = "true_fn")]
91	pub enable_set_avatar_url: bool,
92
93	/// Restricts client profile retrieval to the user themselves or users
94	/// sharing a currently joined room.
95	///
96	/// Appservices are exempt; other users receive 403 `M_FORBIDDEN`. Startup
97	/// and configuration reload refuse this setting unless
98	/// `profile.require_auth` is also enabled. Federation profile lookups are
99	/// unaffected and remain controlled by
100	/// `profile.allow_inbound_federation_lookups`.
101	///
102	/// reloadable: yes
103	/// default: false
104	/// legacy: limit_profile_requests_to_users_who_share_rooms
105	#[serde(default)]
106	pub limit_requests_to_users_who_share_rooms: bool,
107
108	/// Preserves per-room profile overrides when no propagation mode is
109	/// supplied to the profile service.
110	///
111	/// For such calls, true, the default, skips display-name or avatar changes
112	/// in rooms where that field differs from the prior global profile,
113	/// preserving overrides such as `/myroomnick`; false applies the new
114	/// global value throughout the joined rooms. The client profile endpoints
115	/// supply an explicit mode and default to `all`, so this setting does not
116	/// protect overrides through those endpoints. Clients can request `all`,
117	/// `unchanged`, or `none` with the
118	/// [MSC4466](https://github.com/matrix-org/matrix-spec-proposals/pull/4466)
119	/// `computer.gingershaped.msc4466.propagate_to` query parameter.
120	///
121	/// reloadable: yes
122	/// default: true
123	/// legacy: preserve_room_profile_overrides
124	#[serde(default = "true_fn")]
125	pub preserve_room_overrides: bool,
126
127	/// Limits the content size of membership events a client sends.
128	///
129	/// A client state event for `m.room.member` whose content exceeds this many
130	/// bytes is refused with `M_BAD_JSON`, unless it restates the sender's own
131	/// current member event unchanged. On a join, only the extra keys the client
132	/// supplies are measured. Events the server builds, including the profile
133	/// changes it propagates into member events, are not limited by this
134	/// setting.
135	///
136	/// reloadable: yes
137	/// default: 4096
138	#[serde(default = "default_member_event_max_bytes")]
139	pub member_event_max_bytes: usize,
140
141	/// Allows device display names to be federated and seen by external users.
142	///
143	/// This is inherently false when `federation.enable` is disabled. Leave
144	/// disabled for privacy.
145	///
146	/// reloadable: yes
147	/// legacy: allow_device_name_federation
148	#[serde(default)]
149	pub allow_device_name_federation: bool,
150
151	/// Allows incoming federation profile lookups for local users.
152	///
153	/// Disabling `/_matrix/federation/v1/query/profile` lookups protects local
154	/// profile information such as display names and can deter scraping, but
155	/// remote users may see a false "this user does not exist" error when
156	/// inviting local users to a room or direct message. This is inherently
157	/// false when `federation.enable` is disabled.
158	///
159	/// reloadable: yes
160	/// legacy: allow_inbound_profile_lookup_federation_requests allow_profile_lookup_federation_requests
161	#[serde(
162		default = "true_fn",
163		alias = "allow_profile_lookup_federation_requests"
164	)]
165	pub allow_inbound_federation_lookups: bool,
166}
167
168impl Default for Profile {
169	fn default() -> Self {
170		Self {
171			require_auth: Default::default(),
172			max_remote_fields: default_max_remote_fields(),
173			max_fields_per_request: default_max_fields_per_request(),
174			enable_set_displayname: true_fn(),
175			enable_set_avatar_url: true_fn(),
176			limit_requests_to_users_who_share_rooms: Default::default(),
177			preserve_room_overrides: true_fn(),
178			member_event_max_bytes: default_member_event_max_bytes(),
179			allow_device_name_federation: Default::default(),
180			allow_inbound_federation_lookups: true_fn(),
181		}
182	}
183}
184
185fn default_max_remote_fields() -> usize { 100 }
186
187fn default_max_fields_per_request() -> usize { 64 }
188
189fn default_member_event_max_bytes() -> usize { 4096 }