Skip to content

Commit 03e9355

Browse files
committed
feat(foundation): classify indexing roots by breadth and sensitivity
Adds cbm_workspace_classify_root, the breadth half of the workspace boundary. It answers "is this path obviously too broad or too sensitive to index as one root", not "is this caller allowed to index it" — that second question needs the user-level grant store, since it is the only input a caller cannot write. The header says so, because a reader who mistakes one for the other would draw the wrong conclusion about what is enforced. Three rules, each doing what the others cannot: - Depth below the volume. Two components on POSIX refuses every top-level tree in one rule with no list to maintain. Windows and UNC count drive/share-relative and require one, because there the first component is already user space ("D:/repos") — the system trees that sit at the same depth ("C:/Windows") are covered by name instead, which is tractable because that set is small and stable. - The home directory itself, which is two deep on macOS and Linux and so is invisible to depth. - Credential directory names, matched against every component so both "…/.ssh" and "…/.ssh/keys" are refused. This list is deliberately additive so extending it needs no design authority. A path that is or contains the cache directory is refused outright: indexing such a tree would pull every other project's graph database into this project's index. Classification order is load-bearing and commented as such. The home directory normally contains the cache directory, so testing the cache first reported every home as "holds the cache" and made it non-overridable, which contradicts the intent that a person may override it. Depth precedes the cache test for the same reason: "/Users" satisfies both and "too broad" is the reason that helps the reader. Takes home and cache as parameters rather than reading the environment, so the policy is a pure function and the tests need no filesystem. Twelve table tests; three of them failed on the first implementation and drove the ordering fix above. Not yet wired to any caller — deliberately, so the policy can be reviewed on its own. Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
1 parent 886a885 commit 03e9355

5 files changed

Lines changed: 485 additions & 0 deletions

File tree

‎Makefile.cbm‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -188,6 +188,7 @@ FOUNDATION_SRCS = \
188188
src/foundation/str_intern.c \
189189
src/foundation/log.c \
190190
src/foundation/str_util.c \
191+
src/foundation/workspace.c \
191192
src/foundation/platform.c \
192193
src/foundation/system_info.c \
193194
src/foundation/slab_alloc.c \
@@ -453,6 +454,7 @@ TEST_FOUNDATION_SRCS = \
453454
tests/test_str_intern.c \
454455
tests/test_log.c \
455456
tests/test_str_util.c \
457+
tests/test_workspace.c \
456458
tests/test_platform.c \
457459
tests/test_diagnostics.c \
458460
tests/test_dump_verify.c \

‎src/foundation/workspace.c‎

Lines changed: 265 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,265 @@
1+
/*
2+
* workspace.c — workspace boundary policy. See workspace.h for the contract and
3+
* for why this is only the breadth half of the boundary.
4+
*/
5+
#include "foundation/workspace.h"
6+
7+
#include <string.h>
8+
9+
enum {
10+
/* POSIX: two components, so every top-level tree is refused in one rule with
11+
* no list to maintain — "/etc", "/home", "/Users", "/var", "/opt", "/srv".
12+
* Depth alone cannot do this on Windows, where the equivalent system trees
13+
* and a perfectly ordinary workspace are both one component below the drive
14+
* ("C:/Windows" and "D:/repos"), so Windows uses one component plus the
15+
* named system directories below. Windows' top-level set is small and stable
16+
* enough for a list; POSIX's is not. */
17+
WS_MIN_DEPTH_POSIX = 2,
18+
WS_MIN_DEPTH_WINDOWS = 1,
19+
};
20+
21+
static bool ws_is_sep(char c) {
22+
return c == '/' || c == '\\';
23+
}
24+
25+
/* Length of the volume prefix: "/" on POSIX, "C:/" for a drive, "//srv/share"
26+
* for a UNC share. Returns 0 when the path is not absolute. */
27+
static size_t ws_volume_prefix_len(const char *path) {
28+
if (!path || !path[0]) {
29+
return 0;
30+
}
31+
/* UNC: two separators, a host, then a share. */
32+
if (ws_is_sep(path[0]) && ws_is_sep(path[1])) {
33+
size_t i = 2;
34+
while (path[i] && !ws_is_sep(path[i])) { /* host */
35+
i++;
36+
}
37+
while (ws_is_sep(path[i])) {
38+
i++;
39+
}
40+
while (path[i] && !ws_is_sep(path[i])) { /* share */
41+
i++;
42+
}
43+
return i;
44+
}
45+
if (ws_is_sep(path[0])) {
46+
return 1;
47+
}
48+
/* Drive-letter root, with or without a trailing separator. */
49+
if (path[1] == ':' &&
50+
((path[0] >= 'A' && path[0] <= 'Z') || (path[0] >= 'a' && path[0] <= 'z'))) {
51+
return ws_is_sep(path[2]) ? 3 : 2;
52+
}
53+
return 0;
54+
}
55+
56+
static bool ws_is_unc(const char *path) {
57+
return path && ws_is_sep(path[0]) && ws_is_sep(path[1]);
58+
}
59+
60+
static bool ws_is_windows_style(const char *path) {
61+
if (!path || !path[0]) {
62+
return false;
63+
}
64+
return path[1] == ':' &&
65+
((path[0] >= 'A' && path[0] <= 'Z') || (path[0] >= 'a' && path[0] <= 'z'));
66+
}
67+
68+
int cbm_workspace_path_depth(const char *canonical_path) {
69+
size_t prefix = ws_volume_prefix_len(canonical_path);
70+
if (prefix == 0) {
71+
return 0;
72+
}
73+
int depth = 0;
74+
const char *p = canonical_path + prefix;
75+
while (*p) {
76+
while (ws_is_sep(*p)) {
77+
p++;
78+
}
79+
if (!*p) {
80+
break;
81+
}
82+
depth++;
83+
while (*p && !ws_is_sep(*p)) {
84+
p++;
85+
}
86+
}
87+
return depth;
88+
}
89+
90+
/* Case-insensitive on Windows-style paths, exact elsewhere: NTFS is
91+
* case-insensitive, so ".SSH" must not slip past a case-sensitive compare. */
92+
static bool ws_component_equals(const char *component, size_t len, const char *name,
93+
bool fold_case) {
94+
if (strlen(name) != len) {
95+
return false;
96+
}
97+
for (size_t i = 0; i < len; i++) {
98+
char a = component[i];
99+
char b = name[i];
100+
if (fold_case) {
101+
if (a >= 'A' && a <= 'Z') {
102+
a = (char)(a - 'A' + 'a');
103+
}
104+
if (b >= 'A' && b <= 'Z') {
105+
b = (char)(b - 'A' + 'a');
106+
}
107+
}
108+
if (a != b) {
109+
return false;
110+
}
111+
}
112+
return true;
113+
}
114+
115+
/* Directory and file names that carry credentials. Matched against every
116+
* component, so both "…/.ssh" and "…/.ssh/sub" are refused. Additive by design:
117+
* a pull request appending a name here needs no design authority. */
118+
static const char *const WS_CREDENTIAL_NAMES[] = {
119+
".ssh",
120+
".aws",
121+
".gnupg",
122+
".gpg",
123+
".kube",
124+
".docker",
125+
".netrc",
126+
"_netrc",
127+
".git-credentials",
128+
".azure",
129+
".gcloud",
130+
"Keychains",
131+
".password-store",
132+
".authinfo",
133+
};
134+
135+
/* Windows top-level trees below the drive. Small and stable enough to list,
136+
* which is what lets Windows use a shallower depth minimum. */
137+
static const char *const WS_WINDOWS_SYSTEM_DIRS[] = {
138+
"Windows", "Users", "ProgramData", "Program Files", "Program Files (x86)",
139+
};
140+
141+
static bool ws_any_component_matches(const char *path, const char *const *names, size_t count,
142+
bool fold_case) {
143+
size_t prefix = ws_volume_prefix_len(path);
144+
const char *p = path + prefix;
145+
while (*p) {
146+
while (ws_is_sep(*p)) {
147+
p++;
148+
}
149+
if (!*p) {
150+
break;
151+
}
152+
const char *start = p;
153+
while (*p && !ws_is_sep(*p)) {
154+
p++;
155+
}
156+
size_t len = (size_t)(p - start);
157+
for (size_t i = 0; i < count; i++) {
158+
if (ws_component_equals(start, len, names[i], fold_case)) {
159+
return true;
160+
}
161+
}
162+
}
163+
return false;
164+
}
165+
166+
/* True when b is a or lives under a. Compares on a separator boundary so
167+
* "/a/bc" is not treated as living under "/a/b". */
168+
static bool ws_is_ancestor_or_equal(const char *a, const char *b) {
169+
if (!a || !b || !a[0] || !b[0]) {
170+
return false;
171+
}
172+
size_t la = strlen(a);
173+
while (la > 1 && ws_is_sep(a[la - 1])) {
174+
la--;
175+
}
176+
if (strncmp(a, b, la) != 0) {
177+
return false;
178+
}
179+
return b[la] == '\0' || ws_is_sep(b[la]);
180+
}
181+
182+
static bool ws_paths_equal(const char *a, const char *b) {
183+
return ws_is_ancestor_or_equal(a, b) && ws_is_ancestor_or_equal(b, a);
184+
}
185+
186+
cbm_ws_verdict_t cbm_workspace_classify_root(const char *canonical_path, const char *home_dir,
187+
const char *cache_dir) {
188+
if (!canonical_path || !canonical_path[0] || ws_volume_prefix_len(canonical_path) == 0) {
189+
/* A relative or empty path is not a usable root; refuse it the same way
190+
* as a volume root rather than letting it fall through as allowed. */
191+
return CBM_WS_DENY_ABSOLUTE;
192+
}
193+
194+
bool windows_style = ws_is_windows_style(canonical_path);
195+
int depth = cbm_workspace_path_depth(canonical_path);
196+
197+
/* A volume, drive or share root, whatever the platform. */
198+
if (depth == 0) {
199+
return CBM_WS_DENY_ABSOLUTE;
200+
}
201+
202+
/* Order matters below, and not for cosmetic reasons.
203+
*
204+
* The home directory normally CONTAINS the cache directory, so testing the
205+
* cache first would report every $HOME as "holds the cache" — and, worse,
206+
* would make it absolutely denied when the design says a person may override
207+
* it. Home is therefore classified first.
208+
*
209+
* Depth comes before the cache test for the same kind of reason: "/Users" is
210+
* both too broad and an ancestor of the cache, and "too broad, name a
211+
* project directory below it" is the reason that actually helps the reader. */
212+
if (home_dir && home_dir[0] && ws_paths_equal(canonical_path, home_dir)) {
213+
return CBM_WS_DENY_SENSITIVE;
214+
}
215+
216+
/* Below a drive or a UNC share the first component is already user space
217+
* ("D:/repos", "//srv/share/proj"), so one component is enough there. Below a
218+
* POSIX root it is a system tree, so require two. */
219+
int min_depth =
220+
(windows_style || ws_is_unc(canonical_path)) ? WS_MIN_DEPTH_WINDOWS : WS_MIN_DEPTH_POSIX;
221+
if (depth < min_depth) {
222+
return CBM_WS_DENY_TOO_SHALLOW;
223+
}
224+
225+
/* Indexing a tree that holds the cache would pull every other project's
226+
* graph database into this project's index. Never overridable. */
227+
if (cache_dir && cache_dir[0] && ws_is_ancestor_or_equal(canonical_path, cache_dir)) {
228+
return CBM_WS_DENY_ABSOLUTE;
229+
}
230+
231+
if (ws_any_component_matches(canonical_path, WS_CREDENTIAL_NAMES,
232+
sizeof(WS_CREDENTIAL_NAMES) / sizeof(WS_CREDENTIAL_NAMES[0]),
233+
windows_style)) {
234+
return CBM_WS_DENY_SENSITIVE;
235+
}
236+
237+
if (windows_style &&
238+
ws_any_component_matches(canonical_path, WS_WINDOWS_SYSTEM_DIRS,
239+
sizeof(WS_WINDOWS_SYSTEM_DIRS) / sizeof(WS_WINDOWS_SYSTEM_DIRS[0]),
240+
true)) {
241+
return CBM_WS_DENY_SENSITIVE;
242+
}
243+
244+
return CBM_WS_ALLOW;
245+
}
246+
247+
const char *cbm_workspace_verdict_reason(cbm_ws_verdict_t verdict) {
248+
switch (verdict) {
249+
case CBM_WS_ALLOW:
250+
return "allowed";
251+
case CBM_WS_DENY_TOO_SHALLOW:
252+
return "path is too broad to index as one root; name a project directory below it";
253+
case CBM_WS_DENY_ABSOLUTE:
254+
return "path is a volume root or holds the codebase-memory cache; it cannot be indexed";
255+
case CBM_WS_DENY_SENSITIVE:
256+
return "path is a home or credential directory";
257+
default:
258+
break;
259+
}
260+
return "refused";
261+
}
262+
263+
bool cbm_workspace_verdict_is_overridable(cbm_ws_verdict_t verdict) {
264+
return verdict == CBM_WS_DENY_SENSITIVE;
265+
}

‎src/foundation/workspace.h‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
#ifndef CBM_FOUNDATION_WORKSPACE_H
2+
#define CBM_FOUNDATION_WORKSPACE_H
3+
4+
#include <stdbool.h>
5+
#include <stddef.h>
6+
7+
/*
8+
* Workspace boundary policy — classify a directory as an indexing root.
9+
*
10+
* This is the breadth half of the boundary: it rejects roots that are too broad
11+
* or too sensitive to be indexed as a unit. It is NOT the authorization half.
12+
* Whether a caller may index a given tree at all is answered by the user-level
13+
* grant store, because that is the only input a caller cannot write. A verdict
14+
* of CBM_WS_ALLOW here means "this path is not obviously too broad", never
15+
* "this path is authorized".
16+
*
17+
* Every function takes an ALREADY-CANONICALIZED absolute path. Classifying
18+
* before symlink resolution lets `/a/b/c/d/e/link -> /` present as a deep path
19+
* and launder straight through, so callers must resolve first.
20+
*
21+
* home_dir and cache_dir are passed in rather than read from the environment so
22+
* the policy is a pure function and can be tested without touching the host.
23+
* Either may be NULL, which disables the checks that depend on it.
24+
*/
25+
26+
typedef enum {
27+
CBM_WS_ALLOW = 0,
28+
/* Fewer path components than the platform minimum — e.g. "/etc", "/home". */
29+
CBM_WS_DENY_TOO_SHALLOW,
30+
/* A filesystem root, a drive root, a UNC share root, or a path that is or
31+
* contains the cbm cache directory. Never overridable. */
32+
CBM_WS_DENY_ABSOLUTE,
33+
/* The home directory itself, or a credential/system directory. Overridable
34+
* by an explicit human action, never by a manifest or a tool call. */
35+
CBM_WS_DENY_SENSITIVE,
36+
} cbm_ws_verdict_t;
37+
38+
/* Classify canonical_path as a candidate indexing root. */
39+
cbm_ws_verdict_t cbm_workspace_classify_root(const char *canonical_path, const char *home_dir,
40+
const char *cache_dir);
41+
42+
/* Stable, human-facing reason for a verdict. Never NULL. */
43+
const char *cbm_workspace_verdict_reason(cbm_ws_verdict_t verdict);
44+
45+
/* True when an explicit human action may override this verdict. Absolute denials
46+
* and shallow paths are never overridable; sensitive ones are. */
47+
bool cbm_workspace_verdict_is_overridable(cbm_ws_verdict_t verdict);
48+
49+
/* Number of path components below the volume root, ignoring repeated and
50+
* trailing separators. "/" is 0, "/etc" is 1, "C:/repos" is 1, "//srv/share" is
51+
* 0 (the share root itself). Exposed for tests. */
52+
int cbm_workspace_path_depth(const char *canonical_path);
53+
54+
#endif /* CBM_FOUNDATION_WORKSPACE_H */

‎tests/test_main.c‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -603,6 +603,7 @@ extern void suite_dyn_array(void);
603603
extern void suite_str_intern(void);
604604
extern void suite_log(void);
605605
extern void suite_str_util(void);
606+
extern void suite_workspace(void);
606607
extern void suite_platform(void);
607608
extern void suite_diagnostics(void);
608609
extern void suite_subprocess(void);
@@ -848,6 +849,7 @@ int main(int argc, char **argv) {
848849
RUN_SELECTED_SUITE(str_intern);
849850
RUN_SELECTED_SUITE(log);
850851
RUN_SELECTED_SUITE(str_util);
852+
RUN_SELECTED_SUITE(workspace);
851853
RUN_SELECTED_SUITE(platform);
852854
RUN_SELECTED_SUITE(diagnostics);
853855
RUN_SELECTED_SUITE(subprocess);

0 commit comments

Comments
 (0)