hive-priv: point at the socket-dir rationale instead of restating it

`docs/trust-boundary/boundary.md` § *the per-agent socket dir* already
explains why write permission on a directory confers the right to unlink
its entries and why the sticky bit does not restrain that. This comment
said the same thing in the same words, which is the "restating facts all
over" case rather than two independent explanations.

Measured rather than eyeballed, since "these look similar" is not a
finding: 6-gram intersection between this file's comments and that doc
went 36 -> 14. What remains is short shared phrasing — the
socket-activation sentence, which already carries its own pointer, and
the principals table, which is call-site material.

Kept at the call site, because a reader editing this line needs it and a
pointer alone would not stop the change:

  * that 0751 is deliberate and security-relevant, with the consequence
    named in one line;
  * that `d` re-applies on every sync, so an external chown does not
    survive the next agent's spawn.

That second one used to be written as history — a tug-of-war with a
`ChownSocketDir` unit that no longer exists. The constraint it carried is
still live, so it is stated in the present tense instead of as a story
about a removed mechanism.

Comments only; no behaviour change. Refs #3901.
This commit is contained in:
atlas 2026-09-02 05:20:46 +02:00 committed by mara
commit 0ec8a7d2f9

View file

@ -2974,17 +2974,14 @@ async fn sync_agent_tmpfiles(agents: &[AgentTmpfilesEntry]) -> Result<(String, S
// (dials web.sock, and has all of /run/hive-agent bind-mounted in). // (dials web.sock, and has all of /run/hive-agent bind-mounted in).
// Both sockets are 0666, so traversal is all they need. // Both sockets are 0666, so traversal is all they need.
// //
// 0751 rather than the historical 0777 is a fix, not a tidy-up: // ⚠️ 0751 is load-bearing, not tidiness. A world-writable socket dir
// write permission on a *directory* is what confers the right to // lets anything that can reach the path unlink an agent's socket and
// unlink its entries, whoever owns them — the sticky bit is the only // bind its own, receiving that agent's todos. Why directory-write
// thing that would restrain that, and it was never set here. So the // confers that and the sticky bit does not save it:
// old world-writable mode let anything able to reach the path delete // `docs/trust-boundary/boundary.md::the per-agent socket dir`.
// an agent's socket, bind its own, and receive that agent's todos. //
// Dropping `o=w` removes that permission outright rather than // The owner is declared here because `d` re-applies on every sync, so
// qualifying it. Declaring the owner here also ends the tug-of-war // a chown made anywhere else does not survive the next agent's spawn.
// with the
// old ChownSocketDir: `d` re-applies on every sync, so a chown made
// afterwards was reset by the next agent's spawn.
if let (Some(uid), Some(gid)) = (entry.uid, entry.gid) { if let (Some(uid), Some(gid)) = (entry.uid, entry.gid) {
writeln!(content, "d {SOCKET_DIR_ROOT}/{name} 0751 {uid} {gid} -").ok(); writeln!(content, "d {SOCKET_DIR_ROOT}/{name} 0751 {uid} {gid} -").ok();
} else { } else {