Skip to content

feature: managed settings. - #10589

Draft
camilasan wants to merge 47 commits into
masterfrom
feature/5497/mdm
Draft

feature: managed settings.#10589
camilasan wants to merge 47 commits into
masterfrom
feature/5497/mdm

Conversation

@camilasan

@camilasan camilasan commented Aug 12, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Resolves

#5497

This PR is branched off #9191.

Managed settings for the desktop client

Adds a managed settings subsystem so an administrator can set or enforce client settings from three inputs, resolved through one precedence hierarchy: device policy (Windows registry, macOS managed preferences), server delivered values (via the support app capability), and the user config.

Design and resolution flow are documented in src/libsync/settings/README.md.

What it does

  • A ManagedSettings resolver that ranks sources by enforcement state and priority, converts the resolved value to the type declared in the schema, and reports the winning source plus whether it is enforced.
  • Device sources: Windows Software\Policies and Software hives, macOS forced preferences via CFPreferencesAppValueIsForced, Linux conf.
  • Server delivery: parses support.desktopClient from the capabilities, sanitizes it against a client allow list, caches the parsed values in a thread safe ManagedConfig service, and persists them for offline use.
  • One read gateway, ConfigFile::getConfig plus the getConfig<T> template, so callers resolve through the hierarchy instead of reading the config directly. setConfig refuses to overwrite an enforced value.
  • UI: enforced controls are disabled and labelled, never hidden. The update check control shows "Managed by your system administrator" or "Managed by your organization" depending on the source.

Security

  • The server may only default the update and proxy keys, never enforce them. Only device policy can enforce those, so a server cannot disable updates or reroute traffic. This holds on both sides as defense in depth: the support app drops those keys from the enforced map, and the client drops them again from what it accepts.
  • Delivered values are filtered against the client allow list before they reach the resolver.

Scope

Update settings (skipUpdateCheck, autoUpdateCheck) are wired end to end. The remaining allow listed keys (virtual files mode, proxy, folder limits) are accepted and cached but not yet consumed by their accessors; that is a tracked follow up.

Tests

Unit tests cover resolution precedence, type conversion, the getConfig gateway, setConfig refusal when enforced, server caching and persistence, and allow list sanitization including the dropped server enforced update and proxy keys.

Server side

Delivery depends on the support app change (separate repo and PR) exposing support.desktopClient in the capabilities, gated on an enterprise subscription.

Checklist

AI (if applicable)

@camilasan camilasan added this to the 35.0.0 milestone Aug 12, 2026
@camilasan camilasan mentioned this pull request Aug 12, 2026
Open
@camilasan camilasan changed the title Feature/5497/mdm feature: managed settings. Aug 12, 2026
@camilasan
refactor(migration): move migration logic into OCC::Migration
ab34609 
Move phase, version and legacy discovery out of ConfigFile, Application,
AccountManager, AccountState and FolderMan into src/libsync/settings.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
test(migration): add migration unit tests
00dff2a 
Cover the phase lifecycle, version comparison and legacy discovery.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
docs(migration): document the config migration flow
9dcb234 
Add MIGRATION.md next to the sources.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
camilasan force-pushed the feature/5497/mdm branch 3 times, most recently from 6e21f30 to 99cd928 Compare September 7, 2026 13:35
@camilasan
feat(settings): add ManagedSettings resolver and settings schema.
58f5459 
Resolves the effective value of a setting from a set of injectable sources
and returns metadata (winning source, default or locked). Precedence: locked
policy, then user config, then the highest default, then the builtin settings.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
feat(settings): add user config and platform device setting source
0751241 
Native registry, plist and conf adapters plus buildDeviceSources, replicating
the app name selection of ConfigFile::getValue and getPolicySetting. The OS
adapters are not unit tested on the Linux build; only the factory is smoke tested.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
refactor(settings): resolve update settings through the managed setti…
21994da 
…ngs resolver

skipUpdateCheck and autoUpdateCheck now go through ManagedSettings with the
device sources and the user config, preserving the precedence policy over user
over OS default over builtin. The user source carries the connection group so a
locked policy still overrides a group scoped user value.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
feat(settings): add resolveAll for managed settings diagnostics
66f1ce6 
Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
feat(settings): enforce macOS forced managed preferences
7764551 
Add ForcedPreferenceSource, a locked platform policy source that contributes a
value only when an administrator forces the key. MacForcedPreferenceSource
implements it with CFPreferencesAppValueIsForced and CFPreferencesCopyAppValue,
so host and per user managed preferences are honored. buildDeviceSources now
uses it on macOS instead of reading the managed preferences plist as a file.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
feat(settings): add server managed settings sources and allow list
4ff1411 
Add ServerManagedSettings, parsing and an allow list sanitizer for the values
the server delivers through the support.desktopClient capability. Only allow
listed keys pass, and only server lockable keys stay locked.
ServerSettingsSource and buildServerSources expose them as ServerDefault
(priority 30) and ServerLocked (priority 100), so device policy still wins.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
docs(settings): add managed settings flow diagrams
f459d67 
Add the end to end resolution flow above ManagedSettings and the server
delivery flow above ServerManagedSettings, in the same in header style as
Migration.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
refactor(settings): rename locked to enforced
69585cf 
An admin enforces settings, so LockState, enforceable, the ServerLocked source
kind, and the wire and config keys become EnforcementState, enforceable,
ServerEnforced, and enforced. ForcedPreferenceSource keeps Apple's forced term.

Also shorten comments.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
feat(settings): add getConfig gateway resolving through the hierarchy
b6d020a 
getConfig resolves a setting name across the enforcement hierarchy and returns
the value with its source and enforcement. getConfigBool/Int/String, setConfig
(refused when the value is enforced), isEnforced and sourceOf build on it.
skipUpdateCheck and autoUpdateCheck now use it; resolveManagedBool is removed.

Also document managed config getConfig gateway design.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
perf(settings): cache server managed settings in a ManagedConfig service
dada113 
getConfig parsed the server settings JSON from the config file on every call.
ManagedConfig caches the parsed settings, keyed by config path and guarded by a
read write lock, refreshed on write. ConfigFile serverManagedSettings and
setServerManagedSettings delegate to it. Reads stay live for the user and device
layers.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
feat(settings): disable the auto update check control when enforced
b28c403 
When autoUpdateCheck is enforced by device policy or the server, the checkbox is
disabled and its tooltip names who manages it. Populating it does not write the
value back, and the toggle saves through setConfig, which refuses an enforced
value. skipUpdateCheck still hides the whole updater section.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
refactor(settings): make update and proxy server default only
3ea9ec6 
A trusted server can suggest but not enforce skipUpdateCheck, autoUpdateCheck
and the proxy keys; only device policy enforces them, so a server cannot disable
updates or reroute traffic. sanitizeServerManagedSettings drops them from a
server enforced payload. Virtual files and folder limits stay server enforceable.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
docs(settings): move managed config design next to the settings code
87b9d2c 
Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
fix(settings): use Q_SLOTS in the managed settings test
d0dd68e 
Test targets compile with QT_NO_KEYWORDS, so the slots keyword does not
resolve. Use Q_SLOTS.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
chore(settings): rename SettingSourceKind to SettingSourceType.
6e9ea45 
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
refactor(settings): resolve by source priority only
13e0980 
The source priority numbers already encode the full precedence, so the
separate tier ranking was redundant. Rank on priority alone and drop
tierOf.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
refactor(settings): rename winner to best in resolve
8b39fcf 
Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
chore(settings): rename SettingSourceKind to SettingSourceType.
a4c16ca 
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
refactor(settings): remove QSinalBlocker.
74fae4d 
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
fix(settings): refresh managed settings when capabilities change
0ad5b22 
updateServerManagedSettings ran only on account add and remove, so a
policy delivered or changed after login stayed stale. Connect it to
capabilitiesChanged so the merged settings are re-persisted.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
fix(settings): route update setters through setConfig
4e72aa8 
setSkipUpdateCheck and setAutoUpdateCheck wrote QSettings directly,
bypassing the enforcement guard. Delegate to setConfig so an enforced
value is never overwritten.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
fix(settings): guard forced preferences with Q_OS_MACOS
9c4a91d 
Match the guard the rest of the repo uses. Q_OS_MAC also covers iOS.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
chore(settings): rename bestValue to settingValue.
7b0daf3 
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
fix(settings): write the update setting only on user interaction
10b62b3 
Repopulating the update checkbox called setChecked, which fired toggled
and wrote the resolved value back as a user override, so a server default
got frozen as a user value. Connect to clicked, which fires only on user
action.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
fix(settings): propagate schemaVersion when merging server settings
231ea18 
The merged set left schemaVersion at 0. Carry the highest version from the
subscribed accounts.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
fix(settings): disable update button when setting is server enforced.
46008c1 
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
feature(settings): display message to user when setting is enforced.
e68d864 
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
feat(settings): validate the server folder size limit
3aa015c 
Drop a negative newBigFolderSizeLimit before it reaches the resolver.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
feat(settings): add schema specs for folder limit keys
f438e4f 
Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
feat(settings): resolve folder limit settings through getConfig
a41977d 
Route the folder limit getters and setters through getConfig and setConfig so
device policy and server values take effect and an enforced value is not
overwritten. getConfig also reads legacy top level values at a lower priority.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
feat(settings): disable enforced folder limit controls
d6accbb 
Disable each enforced control in the advanced settings and show a managed label.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
docs(settings): document folder limit keys and defer proxy
923c0de 
Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
feat(settings): resolve managed proxy settings
976a07f 
Resolve proxy type, host and port together through getConfig and apply
the managed value at account load and in the global Qt proxy. Only
managed fields replace values and an enforced write is refused.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
feat(settings): disable enforced proxy editor
716e126 
Disable the network proxy editor and show a managed label when the proxy
is enforced by device policy.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
docs(settings): document managed proxy policy
92ff141 
Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
feat(settings): resolve managed virtual files mode
5cfcea8 
Resolve virtualFilesMode through getConfig so a server or device policy
can set or enforce it.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
feat(settings): apply managed virtual files mode in wizards
ff7d39b 
Preselect or force the virtual files choice in the add folder wizard and
the account setup wizard from the managed policy, and disable it when
enforced.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
docs(settings): document managed virtual files mode
393dcde 
Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
docs(settings): update readme to the current managed state
9e1bb3c 
Refresh the principle, scope and testing sections to match the shipped
folder limit, proxy and virtual files wiring.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
feat(settings): validate and declare virtual files mode
0092da7 
Drop an invalid virtualFilesMode server value in sanitize and add the key
to the managed settings schema.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
docs(settings): clarify proxy policy overlay and value validation
136bcd2 
Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
test(settings): cover managed virtual files mode and proxy
51888af 
Add tests for virtualFilesMode sanitize validation, schema, and
managedVirtualFilesMode resolution, plus proxy per field merge and the
global proxy honoring a managed default. Update existing placeholder mode
strings to valid values now that sanitize validates virtualFilesMode.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
docs(settings): document no-subscription behavior and mark follow ups…
82e5fa9 
… optional

Add a section on how the client behaves without an enterprise subscription
and reframe the remaining scope items as optional, since the wired keys are
complete. Update the testing section to the tests that landed.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
@camilasan
docs(settings): explain the schema, sources and resolver with code sn…
b3aafd4 
…ippets

Add a schema section covering SettingSpec, the enforceable gate, the builtin
default type coercion and the synthesized fallback, and a sources section
covering SettingSource, the device and server source factories and how
getConfig builds the stack and resolves.

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: Camila Ayres <hello@camilasan.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@i2h3 i2h3 Awaiting requested review from i2h3 i2h3 will be requested when the pull request is marked ready for review i2h3 is a code owner
@mgallien mgallien Awaiting requested review from mgallien mgallien will be requested when the pull request is marked ready for review mgallien is a code owner
@nilsding nilsding Awaiting requested review from nilsding nilsding will be requested when the pull request is marked ready for review nilsding is a code owner
@claucambra claucambra Awaiting requested review from claucambra claucambra will be requested when the pull request is marked ready for review claucambra is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

35.0.0

Development

Successfully merging this pull request may close these issues.

1 participant

@camilasan