substrate_kit/socket.rs
1//! `socket` — Socket-hardening: AF_UNIX permission and namespace isolation for services running on the substrate.
2//!
3//! **Status: stub. Nothing here is implemented.**
4//!
5//! ## Design note: what a service on the box needs from this module
6//!
7//! A typical local-admin service binds its AF_UNIX socket with a bare
8//! `UnixListener::bind` and then `chmod 0600`s it afterwards. That leaves four
9//! gaps this module should close once, for every AF_UNIX service on the box:
10//!
11//! 1. **Private bind.** A `bind_private(path, mode)` that never exposes the
12//! socket at the umask default, even for an instant: create it under a
13//! restrictive umask (or bind to a temporary name in a 0700 directory and
14//! `rename`), then set the final mode. Today there is a window between
15//! `bind` and `chmod`.
16//! 2. **Safe path and stale-socket handling.** Refuse a path whose parent is
17//! world-writable (for example under `/tmp`) or is a symlink; create the
18//! parent `0700` under `$XDG_RUNTIME_DIR` by default; remove a stale file
19//! only if it is a *socket* owned by the caller and no listener answers on
20//! it (an unconditional `remove_file` is the common mistake).
21//! 3. **Peer credentials.** Expose the connecting peer's `(uid, gid, pid)`
22//! (`SO_PEERCRED`, via `tokio::net::UnixStream::peer_cred`) as a plain
23//! fact, so a service can *decide* on it. Mechanics only: this crate never
24//! makes the allow/deny decision (see `principal.rs`'s hard constraint; that
25//! belongs to identity-kit).
26//! 4. **Socket activation (systemd).** Adopt a listener passed as
27//! `LISTEN_FDS`/`LISTEN_PID` (fd 3+, `sd_listen_fds` semantics, `FD_CLOEXEC`
28//! set, env vars unset after reading) so a user unit can start the service
29//! on first connection.
30//!
31//! **Not in scope here:** passing file descriptors over a connection
32//! (`SCM_RIGHTS`/UDS fd passing). Nobody has asked for it, and it widens the
33//! trust surface; add it only against a named consumer.
34//!
35//! **Why it is not implemented:** items 1-3 are a permissions/trust boundary
36//! (the exact modes, the stale-socket rule and the peer-credential contract
37//! need a security review first), and item 4 has an unresolved scope
38//! question. Nothing else in this crate depends on it.