docs: README claims verify-build covers "nothing the build did not write", which is broader than what is enforced #331

New Issue

2026-08-20T14:25:07+02:00

clawbot commented

2026-08-20 14:25:07 +02:00

Found by the review of #330 (#330 (comment)). Documentation precision on a security control, which is why it is in the milestone despite being a one-paragraph change.

check_dist_tree in script/verify-build walks -type f -o -type l only. A fifo, socket, device node, or empty directory added to dist/ after the build therefore passes verification. The exclusion is deliberate and correct — the script explains it, and grep on a fifo would hang — and none of those can carry a shippable payload.

The problem is only that README.md states the guarantee as "nothing under dist/ that the build did not write", which is broader than what the code enforces. #309 exists because this control was trusted beyond what it actually checked; restating it slightly too broadly is the same mistake in miniature. Everything else in the PR's claim was verified as exactly bounded.

Definition of done

README.md states the enforced guarantee precisely: regular files and symlinks under dist/ are covered; fifos, sockets, device nodes and empty directories are not, and why.
The same wording appears wherever script/verify-build describes itself, so the code and the docs cannot drift.
No behaviour change — this is a documentation fix, not a widening of the walk.
make check green.

Found by the review of https://git.eeqj.de/sneak/AutistMask/pulls/330 (https://git.eeqj.de/sneak/AutistMask/pulls/330#issuecomment-67589). Documentation precision on a security control, which is why it is in the milestone despite being a one-paragraph change. `check_dist_tree` in `script/verify-build` walks `-type f -o -type l` only. A fifo, socket, device node, or empty directory added to `dist/` after the build therefore passes verification. **The exclusion is deliberate and correct** — the script explains it, and grep on a fifo would hang — and none of those can carry a shippable payload. The problem is only that `README.md` states the guarantee as "nothing under `dist/` that the build did not write", which is broader than what the code enforces. https://git.eeqj.de/sneak/AutistMask/issues/309 exists because this control was trusted beyond what it actually checked; restating it slightly too broadly is the same mistake in miniature. Everything else in the PR's claim was verified as exactly bounded. ## Definition of done - [ ] `README.md` states the enforced guarantee precisely: regular files and symlinks under `dist/` are covered; fifos, sockets, device nodes and empty directories are not, and why. - [ ] The same wording appears wherever `script/verify-build` describes itself, so the code and the docs cannot drift. - [ ] No behaviour change — this is a documentation fix, not a widening of the walk. - [ ] `make check` green.

clawbot added this to the 1.0.0 milestone 2026-08-20 14:25:07 +02:00

clawbot referenced this issue

2026-08-20 14:26:18 +02:00

pre-1.0 security review: key handling, DEBUG-mode policy, RPC input validation #303

clawbot referenced this issue from a commit

2026-08-23 15:15:40 +02:00

docs: state verify-build's dist/ guarantee at the width it enforces (closes #331)

clawbot referenced a pull request that will close this issue

2026-08-23 15:15:54 +02:00

docs: state verify-build's dist/ guarantee at the width it enforces (closes #331) #338

clawbot referenced this issue

2026-08-23 15:21:54 +02:00