1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
// Copyright (c) 2026 Erik Lening (hollowpointer) and Contributors
//
// This file is part of Zond Engine, licensed under the GNU Affero General
// Public License, version 3 or later. See the LICENSE file for details, or
// <https://www.gnu.org/licenses/agpl-3.0.html>.
//
// SPDX-License-Identifier: AGPL-3.0-or-later
//! # Where a settings file lives
//!
//! Pure computation. Every function here reads environment variables, and under
//! `sudo` the password database, and returns a path; none of them opens
//! anything, checks whether anything exists, or creates anything. A caller can
//! ask where its settings would be without the asking having a side effect, and
//! the engine never touches a filesystem it was not pointed at.
//!
//! ## The locations
//!
//! | | User | System |
//! |---|---|---|
//! | Unix | `$XDG_CONFIG_HOME/zond/engine.toml`, else `~/.config/zond/engine.toml` | `/etc/zond/engine.toml` |
//! | Windows | `%APPDATA%\zond\engine.toml` | `%PROGRAMDATA%\zond\engine.toml` |
//!
//! `zond/` rather than `zond-engine/` because the engine is not the only thing
//! that will want a file there: a front end belongs beside it as `cli.toml` or
//! whatever it calls itself, in one directory a user can find and back up.
//!
//! macOS follows the Unix path rather than `~/Library/Application Support`. The
//! people who write these files reach for `~/.config`, and a scanner's
//! configuration sitting where every other command-line tool's sits is worth more
//! than matching a convention aimed at bundled applications.
//!
//! ## Under `sudo`, the settings are the invoking user's
//!
//! `~` is the home of the user a run is on behalf of. Most scans need root and
//! so run under `sudo`, which on Linux points `HOME` at root's home, and a
//! missing settings file is not an error: every exclusion and profile the user
//! wrote would vanish without a word. So an elevated process whose environment
//! names the user who invoked it reads that user's file, found the way
//! `journal::paths` finds that user's journals, from `SUDO_UID` and the
//! password database, and for the same reasons. The two would otherwise
//! disagree about whose run it is.
//!
//! Root reading a file its invoking user can write hands that user nothing the
//! command line did not already give them. The file's vocabulary names no path
//! and no command, and `sudo` sets `SUDO_UID` itself, so a user cannot point an
//! elevated run at somebody else's file.
//!
//! A configuration root that survived into the elevated process still leads, as
//! it does for the journal: somebody kept it on purpose, and it is what an
//! unelevated run reads too.
//!
//! ## `$XDG_CONFIG_HOME` is only honoured when it is absolute
//!
//! The specification requires it, and it matters more here than elsewhere. A
//! relative value would put a settings file under whatever directory the process
//! happens to be running in, which for a tool run with `sudo` from an arbitrary
//! shell is not a location anybody chose.
use PathBuf;
use FILE_NAME;
/// The directory this crate's configuration lives in, under whatever
/// configuration root applies.
const DIRECTORY: &str = "zond";
/// Where this user's settings file would be.
///
/// `None` when the environment names no home at all, which happens in a
/// container or a daemon with a cleared environment. A caller getting `None`
/// should carry on without a settings file rather than invent a location.
/// Where this user's settings *directory* would be.
///
/// `%APPDATA%` is the roaming one: settings are what a person chose and should
/// follow them between machines on a domain, unlike the journal in
/// `%LOCALAPPDATA%`, which is a record of what one machine did.
///
/// Written as two whole functions rather than one with two `cfg` blocks, for the
/// reason `journal::paths::state_root` gives.
/// Where this user's settings *directory* would be: `$XDG_CONFIG_HOME/zond`
/// where that variable names an absolute path, and `.config/zond` under the
/// home directory otherwise: the invoking user's under `sudo`, as the module
/// note explains, and `$HOME` for anything else.
///
/// `None` when no home can be found, which is what a container or a daemon with
/// a cleared environment looks like. macOS lands here rather than under
/// `~/Library/Application Support`; the module note says why.
/// [`user_directory`]'s choice, from values rather than the environment, so a
/// test can put it under `sudo`.
/// Where a host-wide settings file would be.
///
/// Read before the user's, so an administrator can set a floor that a user then
/// adjusts. `None` on a platform with no such location named in the
/// environment.
/// Where a host-wide settings file would be: `/etc/zond/engine.toml`.
///
/// Read before the user's file, so an administrator can set a floor a user then
/// adjusts. Never `None` here; the [`Option`] is for Windows, where the
/// location comes from `%PROGRAMDATA%` and that can be unset.
/// Every settings file that may apply, in the order they layer.
///
/// System first, user second, so the user's file has the last word. Paths that
/// could not be computed are absent; nothing here says whether any of them
/// exists.
// ╔════════════════════════════════════════════╗
// ║ ████████╗███████╗███████╗████████╗███████╗ ║
// ║ ╚══██╔══╝██╔════╝██╔════╝╚══██╔══╝██╔════╝ ║
// ║ ██║ █████╗ ███████╗ ██║ ███████╗ ║
// ║ ██║ ██╔══╝ ╚════██║ ██║ ╚════██║ ║
// ║ ██║ ███████╗███████║ ██║ ███████║ ║
// ║ ╚═╝ ╚══════╝╚══════╝ ╚═╝ ╚══════╝ ║
// ╚════════════════════════════════════════════╝