yerd-platform
yerd-platform is Yerd's OS abstraction layer. It is the single place where the rest of the workspace touches platform-specific behaviour - trust stores, DNS resolver redirection, privileged-port binding, filesystem layout, and process metrics. Everything above it (the daemon, the CLI, yerd-tls, yerd-dns, yerd-doctor) consumes the traits defined here and never reaches for #[cfg(target_os = ...)] itself.
The crate has three jobs and keeps them strictly separated:
- Define the traits - one trait per platform concern, with typed error and result types.
- Implement them once per OS, selected at compile time, exposed through
Active*aliases so callers name the concrete impl without acfg. - Keep all decision logic pure in the
puremodule so it is unit-tested in-memory with no I/O, clock, environment, or async runtime.
A fourth, cross-cutting responsibility is the privilege boundary: this crate is unprivileged library code and never spawns the helper. See Cross-Platform Model and Elevation & Privileges for the wider picture.
Source
crates/yerd-platform. The crate is #![forbid(unsafe_code)].
Module map
src/
lib.rs re-exports the traits, types, and Active* aliases
detect.rs ProjectSignalSource trait + gather_project_signals (web-root signals)
error.rs PlatformError + typed reason enums + ops:: tag constants
helper.rs HelperInvocation (typed) + to_argv / from_argv wire contract
ide.rs IdeLauncher trait + DetectedIde / LaunchTarget + FakeIdeLauncher
lan_ip.rs LanIpProvider trait + FakeLanIpProvider
metrics.rs SystemMetrics trait (Option-returning, best-effort)
opener.rs SystemOpener trait + FakeSystemOpener
paths.rs Paths trait + PlatformDirs struct
port_binder.rs PortBinder trait + BoundPort / PortPair
port_redirect.rs PortRedirector trait + loopback_port_reachable / loopback_redirect_reaches_proxy
process_table.rs ProcessTable trait (best-effort) + FakeProcessTable
resolver.rs ResolverInstaller trait
system_proxy.rs SystemProxySource trait + FakeSystemProxySource
terminal.rs TerminalLauncher trait
tool_root.rs single_top_level_dir (the one top-level dir of an unpacked tool)
trust_store.rs TrustStore trait + CaFingerprint + NssOutcome / NssFailure
os/
mod.rs cfg-selects exactly one impl; exposes `active` aliases
unix.rs executable_in_directories + spawn_and_check + process-group signalling (Linux + macOS)
linux.rs Linux* impls
macos.rs Macos* impls (+ security-framework)
unsupported.rs Unsupported* stubs (Windows, Phase 1)
pure/
mod.rs
firefox.rs parse_profiles_ini
ide_spec.rs IDE_SPECS table (id, display_name, rank) + name/id/exec matchers
opener_spec.rs ordered system-opener candidates per desktop
launchd_ports.rs compose/parse macOS launchd port-forwarder plists, labels, paths
pem_match.rs find_by_fingerprint, sha256, der_to_pem
pf_anchor.rs legacy macOS pf redirect: detection, removal, release gate
port_plan.rs classify_desired / classify_fallback
proc_metrics.rs parse_vmrss_bytes / parse_loadavg (Linux /proc)
ps_metrics.rs parse_ps_rss_bytes (macOS `ps`)
process_signal.rs signal_target (pid guard) + decode_proc_cmdline / decode_ps_command
resolv_conf.rs select supported Linux resolver backend
networkmanager_dnsmasq.rs compose/match NetworkManager snippets
dns_probe.rs compose/validate the loopback DNS probe
resolved_drop_in.rs compose/parse systemd-resolved drop-in
resolver_file.rs compose/parse macOS /etc/resolver/<tld>
system_proxy.rs parse_gsettings / parse_scutil_proxy + MacProxySettings
terminal_spec.rs TERMINAL_SPECS probe tableRuntime dependencies are deliberately tiny: thiserror, directories, sha2, hex, pem, serde_json (only to read composer.json during signal gathering), plus yerd-tls and yerd-core (for the ProjectSignals / Detection types the detector feeds), with security-framework gated to macOS only and nix (signals) gated to unix. A test (tests/no_runtime_deps.rs) walks the resolved dependency graph (scoped with --filter-platform so cfg gates apply) and asserts that tokio, anyhow, reqwest, openssl, openssl-sys, and native-tls never appear in the normal-kind runtime graph - none of which serde_json or yerd-core pull in.
The core traits
Each trait is intentionally narrow. With one exception, fallible methods return Result<_, PlatformError>.
Paths
pub trait Paths {
fn resolve(&self) -> Result<PlatformDirs, PlatformError>;
}resolve returns a PlatformDirs with five directories. Existence is not guaranteed - callers are responsible for create_dir_all before writing.
| Field | Meaning | Linux | macOS |
|---|---|---|---|
config | User config | ~/.config/yerd | macOS config dir |
data | Persistent data (CA + leaf certs) | XDG data home | macOS data dir |
state | Long-lived state | XDG_STATE_HOME (distinct from data) | collapses to data |
cache | Logs, downloads | XDG cache home | macOS cache dir |
runtime | IPC socket + PID file | XDG_RUNTIME_DIR/yerd, else /tmp/yerd-$UID | /tmp/yerd-$UID |
The Linux impl uses the directories crate, falling back to reading the real UID from /proc/self/status when XDG_RUNTIME_DIR is unset. macOS uses ProjectDirs::from("io", "yerd", "Yerd") and deliberately chooses a deterministic, uid-derived /tmp/yerd-$UID for runtime rather than std::env::temp_dir() (the per-session /var/folders/… path). Determinism is load-bearing: yerd elevate, running as root under osascript/sudo, must reconstruct the socket path from SUDO_UID alone without privileged FFI.
runtime is security-sensitive
When the /tmp/yerd-$UID fallback is used, the caller must mkdir(mode=0o700) and, if the directory already exists, verify ownership (uid == geteuid()) and mode (0o700) before using it. yerd-platform deliberately does not do this - it only computes the path; the daemon's secure_fs owns the fail-closed creation.
TrustStore
pub trait TrustStore {
fn install_system(&self, ca_pem: &str, fp: &CaFingerprint) -> Result<(), PlatformError>;
fn uninstall_system(&self, fp: &CaFingerprint) -> Result<(), PlatformError>;
fn is_present_system(&self, fp: &CaFingerprint) -> Result<bool, PlatformError>;
// Effectively *trusted* for SSL, not merely present. Defaulted to
// `Unsupported` (the only defaulted method); macOS uses `security
// verify-cert`, Linux delegates to `is_present_system`.
fn is_trusted(&self, ca_path: &Path, fp: &CaFingerprint) -> Result<bool, PlatformError>;
fn install_firefox_nss(&self, ca_path: &Path) -> Result<NssOutcome, PlatformError>;
fn uninstall_firefox_nss(&self) -> Result<NssOutcome, PlatformError>;
// Whether the per-user *browser* NSS stores trust the CA. Defaulted to
// `Unsupported`; macOS + Linux override.
fn browser_ca_trust(&self, fp: &CaFingerprint) -> Result<BrowserCaTrust, PlatformError>;
}The CA is identified by a CaFingerprint - a newtype around [u8; 32] (SHA-256 over the cert's DER body) with a private field, so callers cannot construct an unchecked fingerprint. Its canonical wire form is 64 lowercase hex characters; from_hex strictly rejects uppercase, wrong length, and non-hex so the form stays byte-stable across the helper argv boundary.
install_system/uninstall_systemalways returnErr(PlatformError::NeedsHelper { .. })in Phase 1. They are write operations against a root-owned store, so the daemon materialises the matchingHelperInvocationand runsyerd-helper.is_present_systemis a read-only, unprivileged presence probe. It reports whether a CA matching the fingerprint is in the store - not whether it is trusted for SSL by every consumer. On macOS it enumerates/Library/Keychains/System.keychainviasecurity-frameworkand hashes each cert's DER; on Linux it iterates the distro's anchor directory and hashes each PEM block (the candidate directories are/usr/local/share/ca-certificates,/etc/pki/ca-trust/source/anchors, and/etc/ca-certificates/trust-source/anchors).install_firefox_nss/uninstall_firefox_nss/browser_ca_trustare the trust operations that run per-user and unprivileged. On Linux, Chromium-family browsers (Brave/Chrome/Chromium/Edge) and Firefox ignore the system store and read their own per-user NSS database -~/.pki/nssdb(shared by Chromium-family) and onecert9.dbper Firefox profile, including Snap (~/snap/<app>/{common,current}/...) and Flatpak (~/.var/app/<id>/...) copies. Path derivation and thecertutilargv are pure (pure::nss); the discover→run→aggregate orchestration is behind injected seams (nss_exec) so it is unit-tested in-memory.certutil(fromlibnss3-tools) missing is a first-class outcome (certutil_missing/BrowserCaTrust::ToolMissing), not an error.install_firefox_nsstakes the CA path (read-ibycertutil), creating and initialising~/.pki/nssdbif absent. It is best-effort and returnsOk(NssOutcome)even on partial failure:
pub struct NssOutcome {
pub profiles_attempted: usize,
pub profiles_succeeded: usize,
pub failures: Vec<(PathBuf, NssFailure)>, // per-profile, in attempt order
pub certutil_missing: bool,
}
pub enum NssFailure { CertutilMissing, CertutilExit(i32), DbMissing }On macOS the same path runs for Firefox, which keeps its own NSS store there too; Chromium-family browsers on macOS read the system keychain instead, so they need nothing extra.
certutil itself is resolved to an absolute path, once, by resolve_certutil: the per-OS candidate list (pure::nss::certutil_candidates_linux / _macos) is probed first, and only then certutil under each $PATH directory. The candidate list wins because a service manager hands the daemon a stripped PATH - a launchd LaunchAgent gets PATH=/usr/bin:/bin:/usr/sbin:/sbin, which never contains the Homebrew or MacPorts prefixes where macOS's certutil actually lives, so a $PATH-only lookup silently reported the tool as missing. (/usr/bin is deliberately absent from the macOS list: macOS ships certtool there, never certutil.) It mirrors the /usr/bin/id / /bin/ps precedent elsewhere in this crate. The existence probe is injected, so the walk is unit-tested against the real candidate lists on any host without touching the filesystem.
The caller decides whether to surface the degraded outcome. See HTTPS & Certificates for the user-facing story.
ResolverInstaller
pub trait ResolverInstaller {
fn install(&self, tld: &str, addr: SocketAddr) -> Result<(), PlatformError>;
fn uninstall(&self, tld: &str) -> Result<(), PlatformError>;
fn is_installed(&self, tld: &str, addr: SocketAddr) -> Result<bool, PlatformError>;
}addr is the IP+port the OS resolver should forward .test lookups to. The Phase-1 daemon always passes 127.0.0.1:<port>, but the trait takes a full SocketAddr so a future version can move the DNS responder without a breaking change. install/uninstall return NeedsHelper; is_installed reads public config and is unprivileged. Both uninstall and is_installed are idempotent for an absent TLD (Ok(()) / Ok(false)).
is_installed must verify the on-disk config points at this addr - a stale file aimed elsewhere (e.g. a Valet/Herd leftover on :53) must report false so the redirect gets re-installed. See DNS & .test Domains.
PortBinder
pub trait PortBinder {
fn bind(&self, port: u16) -> Result<BoundPort, PlatformError>;
fn bind_pair(&self, desired: (u16, u16), fallback: (u16, u16))
-> Result<PortPair, PlatformError>;
}BoundPort wraps a plain std::net::TcpListener (not the tokio variant) so yerd-platform keeps tokio out of its public surface; yerd-proxy converts via tokio::net::TcpListener::from_std. BoundPort::port() reads the resolved port from local_addr(), so it is correct even when binding 0.
bind_pair binds HTTP+HTTPS atomically with a fallback. It attempts the desired pair, then:
- both succeed → keep them;
- one fails with a retry-trigger kind (
PermissionDenied,AddrInUse,AddrNotAvailable) → drop any partial listener and retry the fallback pair; - one fails with any other kind → surface
PlatformError::Bindimmediately without trying the fallback.
If both pairs fail, the error is PlatformError::BindPair carrying all four io::ErrorKinds, so the daemon can tell "setcap missing" (PermissionDenied everywhere) from "port already in use" (AddrInUse on the desired pair) and message the user accordingly. The classification itself is pure - see port_plan.
PortRedirector
pub trait PortRedirector {
fn is_active(&self) -> Option<bool>;
fn foreign_web_listener(&self) -> Option<bool>; // default impl, cross-platform
}On macOS the unprivileged daemon cannot bind 80/443, so yerd elevate ports installs launchd socket-activated port forwarders (yerd-forward) that relay to its rootless ports. Because the daemon still binds the high ports, StatusReport.http.fell_back stays true even when the redirect works - the doctor needs an independent signal that 80/443 are actually reachable. is_active is therefore an active, unprivileged check, and it goes further than "something answers": it speaks HTTP to loopback and requires the proxy's Server marker (yerd_core::PROXY_SERVER_ID) on the reply, so a foreign listener can't read as a live Yerd redirect. MacosPortRedirector learns the forward targets from the forwarder plists (launchd_ports::parse_forwarder_target), falling back to the legacy pf anchor files on machines that haven't re-elevated since upgrading. legacy_pf_redirect reports whether any legacy pf boot job or anchor file is still on disk (an unprivileged existence check), which the doctor turns into a LegacyPortRedirect nudge; Linux and unsupported platforms return None.
// Bare reachability: does *anything* answer?
pub fn loopback_port_reachable(port: u16) -> bool { /* TCP connect, 250ms */ }
// Identity-confirming: is the answer *this* daemon's proxy? (Server: yerd marker)
pub fn loopback_redirect_reaches_proxy(port: u16) -> bool { /* HTTP probe */ }is_active returns None on Linux (it binds the privileged ports directly after setcap). foreign_web_listener is the inverse, useful signal and is cross-platform: a default trait method that returns Some(true) when a privileged web port answers but the Yerd proxy marker is absent (a non-Yerd process squatting 80/443), Some(false) otherwise. The daemon surfaces it as StatusReport.foreign_web_listener, and yerd-doctor raises ForeignWebListener from it. The unsupported stub overrides it back to None.
SystemMetrics
pub trait SystemMetrics {
fn rss_bytes(&self, pid: u32) -> Option<u64>;
fn load_average(&self) -> Option<[f64; 3]>;
}Unlike every other trait here, metrics return Option, not Result. None collapses two cases - "OS unsupported" and "transient read failed" - because the only caller (yerd status) treats both identically: show nothing. The OS impls do only the file read / subprocess; the actual decoding lives in the table-tested proc_metrics / ps_metrics parsers.
ProcessTable
pub trait ProcessTable {
fn command_line(&self, pid: u32) -> Option<String>;
fn signal_group(&self, pid: u32, force: bool);
fn is_alive(&self, pid: u32) -> bool;
}Best-effort process inspection and signalling, used by the daemon to reap a cloudflared orphaned by a previous daemon crash (see yerd-tunnel). Like SystemMetrics it is sync and infallible at the type level: a process that is gone or unreadable simply reads as absent, and signal failures are ignored. The trait only reads and signals; the caller decides which PIDs are safe to touch (the daemon requires both cloudflared and its own tunnel data path in the command line, which guards against PID reuse).
command_linereturns the arguments joined by single spaces.signal_groupsends SIGTERM (or SIGKILL whenforce) to the process group led bypid, falling back to the single process. It refuses pid 0, pid 1, and any pid that overflowsi32before signalling anything; that guard is the table-testedpure::process_signal::signal_target.is_aliveis a signal-0 probe (EPERMcounts as alive).
Per OS (ActiveProcessTable):
- Linux reads
/proc/<pid>/cmdline(NUL-separated, decoded bydecode_proc_cmdline) and signals throughnix::sys::signal::killpg. - macOS runs
/bin/ps -ww -o command= -p <pid>(absolute path, untruncated) decoded bydecode_ps_command, and signals throughkillpg. - Unsupported returns
Nonefromcommand_line,falsefromis_alive, and does nothing onsignal_group. Unlike theResult-returning traits it does not returnPlatformError::Unsupported: the table is best-effort, and an unsupported OS simply has no orphans to reap.
FakeProcessTable is a fixed table of command lines that records every signal (RecordedSignal { pid, force }). A process dies on its first signal unless it was added with with_stubborn_process, in which case it survives SIGTERM and only dies on a forced signal, so a caller's escalation path can be tested.
IdeLauncher
pub trait IdeLauncher {
fn detect(&self) -> Vec<DetectedIde>;
fn launch(&self, ide: &DetectedIde, path: &Path) -> Result<(), PlatformError>;
}Detection resolves the launch target once and launching consumes it, so no code path scans the filesystem twice for the same click. DetectedIde carries the id, the display name, and a LaunchTarget that is either Cli(PathBuf) (a binary found on PATH or in the per-OS candidate directories) or Application(PathBuf) (the OS's indirect handle: a .desktop entry on Linux, a .app bundle on macOS). Two variants keep every adapter's launch total without a dead arm.
Editor identity is a &'static str id from the IDE_SPECS table rather than an enum, following terminal_spec.rs: adding an editor is a one-row table diff, and the id is the value persisted by the GUI, so a future custom-command escape hatch is not a breaking change. The table's rank column (lower = preferred) is what "auto-detect" resolves against, and detect returns rank-sorted results.
LaunchTarget holds a resolved filesystem path, so it never crosses the webview boundary: the GUI sends an id, and the Tauri layer maps it back through its own cache.
SystemOpener
pub trait SystemOpener {
fn open_path(&self, path: &Path) -> Result<(), PlatformError>;
}Opens a directory with the desktop's default handler - the fallback when no editor is detected or the user picks "System default". Candidate ordering per desktop lives in the table-tested pure/opener_spec.rs.
Both traits ship public fakes (FakeIdeLauncher, FakeSystemOpener), following FakeLanIpProvider: each records its calls and takes an optional forced error, so callers can test the seam without touching the host.
TerminalLauncher
pub trait TerminalLauncher {
fn open_terminal(&self, path: &Path) -> Result<(), PlatformError>;
}Opens a terminal with path as its working directory - what the Sites inspector's Terminal button drives. macOS is one line (/usr/bin/open -a Terminal <path>); Linux is where the work is, and its decision half lives in the table-tested pure/terminal_spec.rs.
TERMINAL_SPECS pairs each terminal we know how to launch with the flags that set its working directory (gnome-terminal --working-directory, konsole --workdir, kitty --directory, wezterm start --cwd, …). Two matching rules matter:
- Lookups match the program's file name, not the whole string. KDE stores
TerminalApplicationinkdeglobalsas either a bare name (konsole) or an absolute path (/usr/bin/konsole), and both must resolve to the same flags or the terminal opens in the wrong directory. - A trailing
.wrapperis stripped first. Debian'sx-terminal-emulatoralternative points atgnome-terminal.wrapper, which forwards its arguments tognome-terminaland so takes the same flags.
x-terminal-emulator itself is deliberately absent from the table: it is an alternatives symlink rather than a terminal, so it carries no flags of its own. The Linux impl probes it separately and resolves the link before looking flags up. An unrecognised program returns None, and the caller falls back to the spawned child inheriting the current directory.
SystemProxySource
kind() -> ProxySource and read() -> Option<SystemProxy>: the OS proxy settings the daemon's outbound-proxy System mode falls back to after its own environment. macOS runs scutil --proxy (the SCDynamicStore proxy dictionary; the safe Core Foundation bindings can't read its ExceptionsList without unsafe), Linux runs gsettings list-recursively org.gnome.system.proxy; both are bounded by a 3 s timeout and parsed by the pure pure::system_proxy helpers. A missing tool, non-GNOME desktop, or timeout reads as None; the unsupported stub always returns None. FakeSystemProxySource { reading, kind } serves tests.
single_top_level_dir
Returns the single child directory of an unpacked tool archive (Node, pnpm, Bun), or a RootDirError. The daemon uses it when linking {data}/bin and the CLI's tool shims use it at run time, so both always agree on the target.
OS implementations and the Active* aliases
os/mod.rs compiles exactly one of linux, macos, or unsupported per build and re-exports it under uniform aliases:
pub(crate) mod active {
#[cfg(target_os = "linux")]
pub use super::linux::{
LinuxPaths as ActivePaths, LinuxPortBinder as ActivePortBinder,
LinuxPortRedirector as ActivePortRedirector,
LinuxResolverInstaller as ActiveResolverInstaller,
LinuxSystemMetrics as ActiveSystemMetrics, LinuxTrustStore as ActiveTrustStore,
};
// macos / unsupported arms are symmetric
}lib.rs re-exports these, so callers write ActiveTrustStore, ActivePaths, etc. and the right concrete type is selected at compile time - no cfg leaks into consumer crates.
The unsupported stub (Windows in Phase 1) implements every trait so cargo check --workspace stays green on any host. Every fallible method returns Err(PlatformError::Unsupported { operation }); SystemMetrics returns None; PortRedirector returns None; ProcessTable reads every process as absent. tests/unsupported.rs (gated to non-Linux/non-macOS targets) asserts each method returns Unsupported.
The pure module
Every function in pure is sync, runtime-free, and free of I/O, clock reads, and environment lookups. The OS impls do the reads/writes and call into pure for the decision; pure is table-tested in isolation.
firefox
parse_profiles_ini(text) -> Vec<Profile> parses Firefox profiles.ini. It returns each [Profile<N>] section's Name, Path, IsRelative, and Default, silently ignoring [General]/[Install…] sections, comments, and profiles with no Path. Output path is raw - the caller joins relative paths against the profiles.ini parent, which pure does not know about.
pem_match
find_by_fingerprint(blobs: &[(PathBuf, Vec<u8>)], fp: &[u8;32]) -> Result<Option<PemMatch>, PathBuf> searches pre-read PEM blobs (the caller does the I/O) for the first CERTIFICATE block whose DER body hashes to fp, returning the matching path and 0-based block index. Err(path) signals a blob that failed PEM parsing, which the OS layer translates to TrustStoreErrorReason::AnchorPemInvalid. A blob with no certificate blocks (e.g. a README in an anchor dir) is Ok(None), not an error. Also exports sha256, der_to_pem, and fingerprint_of_first_cert_in_pem.
launchd_ports
Composes and parses the macOS port-forwarder LaunchDaemons. Labels: PORTS_HTTP_LABEL = "dev.yerd.ports.http", PORTS_HTTPS_LABEL = "dev.yerd.ports.https", LAN_PORTS_HTTP_LABEL = "dev.yerd.lan.ports.http", LAN_PORTS_HTTPS_LABEL = "dev.yerd.lan.ports.https", each with a matching /Library/LaunchDaemons/<label>.plist path constant. FORWARDER_BIN = "yerd-forward" is the sibling of yerd-helper the plist runs.
compose_forwarder_plist(scope, label, forwarder, user, from, to) emits a plist whose Sockets make launchd bind scope.node():from (127.0.0.1 for Scope::Loopback, 0.0.0.0 for Scope::Lan) and, on the first connection, spawn yerd-forward --scope <scope> --to <to> as UserName with inetdCompatibility Wait = true, which passes the listening socket on stdin. There is deliberately no RunAtLoad or KeepAlive: launchd holds the socket from load (and every boot) and spawns the forwarder on demand. ProcessType Interactive stops launchd throttling it. Every interpolated value is XML-escaped.
parse_forwarder_target reads the --to port back for MacosPortRedirector. is_persistent_forwarder_path rejects relative paths, anything under AppTranslocation (a randomised read-only mount that is gone after reboot), and anything under /Volumes (an app run from its disk image). Scope::jobs() lists the two Jobs (label, plist path, role) for a scope.
The plist lives in root-owned /Library/LaunchDaemons (root:wheel 0644), so only root can change UserName or ProgramArguments. See yerd-forward for the threat model.
pf_anchor
Legacy only. Older Yerd served 80/443 on macOS through pf rdr rules in its own anchors (dev.yerd, dev.yerd.lan), hooked into /etc/pf.conf by # yerd-managed / # yerd-lan-managed lines and re-applied at boot by dev.yerd.pf.plist / dev.yerd.lan.pf.plist. The module now exists only to detect and remove that state: is_installed / is_lan_installed, remove_anchor_refs / remove_lan_anchor_refs / remove_all_refs, and parse_anchor_targets (stale detection on un-migrated machines still reads the anchor files).
Removal must not switch pf off for other software (VPN kill switches and firewalls enable pf through pfctl too, and their references look identical to Yerd's). parse_pf_references parses pfctl -s References, yerd_owned_tokens picks every token taken by a process named pfctl (references don't record which tool took them, so this can include another tool's) (returning None if any isn't a plain decimal, so nothing unvalidated reaches pfctl -X), and only_apple_and_yerd_pf_state is the fail-closed gate: it returns true only when every loaded anchor is in an exact Apple allowlist (com.apple and its 200.AirDrop and 250.ApplicationFirewall sub-anchors) or is a Yerd anchor, and every main-ruleset line is a com.apple/* or Yerd anchor hook. Anything unrecognised returns false, and the only cost is that pf stays enabled until the next reboot. The com.apple.internet-sharing anchors (added once Internet Sharing or a VM network such as OrbStack's has run) are deliberately not allowlisted: Internet Sharing needs pf enabled, and its reference can't be told apart from Yerd's.
port_plan
The pure classifier behind PortBinder::bind_pair:
pub fn classify_desired(http: BindOutcome, https: BindOutcome) -> DesiredPairAction; // KeepDesired | UseFallback | HardFail(ErrorKind)
pub fn classify_fallback(http: BindOutcome, https: BindOutcome) -> FallbackPairAction; // KeepFallback | BothFailed
pub fn is_retry_kind(kind: ErrorKind) -> bool; // PermissionDenied | AddrInUse | AddrNotAvailableThe precedence is pinned by tests: a hard (non-retry) kind always beats a retry kind, and on the desired pair, http is inspected before https.
resolv_conf, networkmanager_dnsmasq, dns_probe, resolved_drop_in, resolver_file (DNS)
resolv_confprefers systemd-resolved, selects NetworkManager only from its positive/etc/resolv.confgenerator marker, and otherwise returns unsupported. It also validates NetworkManager's post-reload127.0.0.1dnsmasq nameserver.networkmanager_dnsmasqcomposes and strictly matches the[main] dns=dnsmasqoverride and per-TLDserver=/test/127.0.0.1#1053rule.dns_probe::compose_query(tld)builds the A query foryerd-resolver-probe.<tld>that the helper sends to127.0.0.1:53after a NetworkManager reload;response_has_loopback_achecks the reply carries our transaction ID,NOERROR, and anA 127.0.0.1record. Keeping the packet bytes pure means the post-condition is table-testable without a socket.resolved_drop_in::compose(tld, addr)emits the Linux drop-in[Resolve]\nDNS=<addr>\nDomains=~<tld>\n(/etc/systemd/resolved.conf.d/yerd-<tld>.conf);parse/matchestolerate comments and extra keys so theis_installedprobe is robust against operator edits.resolver_file::compose(addr)emits the macOS/etc/resolver/<tld>bodynameserver <ip>\nport <port>\n;parse/matchesignore comments and ordering, defaulting a missingportto53perresolver(5).restorable(text)(=parse(text).is_some()) is the pure guard the helper uses before writing a backup back over/etc/resolver/<tld>onunelevate resolver, so an empty/garbage backup is never restored.backup_filename/parse_backup_secs/latest_backupare the path-logic for the timestamped backups (<tld>-<unixsecs>.conf); the macOS helper restores the newest and clears the rest, the daemon reads the newest to reportResolverBackupSaved.
proc_metrics, ps_metrics
proc_metrics::parse_vmrss_bytes(status)reads theVmRSS:line of/proc/<pid>/status(kibibytes → bytes);parse_loadavg(text)reads the first three figures of/proc/loadavg. UsingVmRSSavoids needing_SC_PAGESIZE, keeping the parserunsafe-free.ps_metrics::parse_ps_rss_bytes(stdout)parses the headerless first token ofps -o rss= -p <pid>(kibibytes → bytes) on macOS, which has no cheapunsafe-free per-process RSS source instd. All three returnNoneon malformed input - metrics are best-effort.
process_signal
signal_target(pid)maps a PID to thei32passed tokillpg/kill, orNonefor pid 0, pid 1, and anything that overflowsi32, so a bad pidfile can never signal the daemon's own process group,init/launchd, or (through a wrapped negative value) an arbitrary group.decode_proc_cmdline(raw)turns Linux's NUL-separated/proc/<pid>/cmdlineinto a space-joined string;decode_ps_command(stdout)trims macOSpsoutput. Both returnNonefor empty input.
Web-root signal gathering (detect)
detect.rs is the I/O half of web-root detection - the decision half is the pure yerd_core::detect. Gathering reads a project directory and produces an in-memory yerd_core::ProjectSignals; the daemon then calls yerd_core::detect on it to pick the served subdirectory.
Per the crate's "side effects behind traits" rule, gathering is exposed through a trait so callers can inject a fake:
pub trait ProjectSignalSource {
fn gather(&self, project_root: &Path) -> ProjectSignals;
}
#[derive(Debug, Default, Clone, Copy)]
pub struct FsSignalSource; // the real, filesystem-backed impl
pub fn gather_project_signals(project_root: &Path) -> ProjectSignals;gather_project_signals is best-effort and infallible - a missing or malformed composer.json, an unreadable directory, etc. simply contribute fewer signals. It reads only the project root and the immediate candidate web dirs (yerd_core::detect::WEB_DIR_CANDIDATES), never recursively: it parses composer.json's require/require-dev package names (lowercased), stats the ROOT_MARKERS (file or dir presence), and checks each candidate dir for an index.php front controller. Tempdir fixture tests (Laravel-like, WordPress-like, plain, empty, malformed-JSON) pin the gather→detect pipeline end to end.
This is the only place in the crate that touches a non-config filesystem path, and it is not OS-gated - the conventions are the same on every platform.
The privilege boundary
This is the crate's most important invariant. yerd-platform is unprivileged. Any operation that needs root does not perform it - it returns PlatformError::NeedsHelper { operation }, where operation is one of the &'static str tags in error::ops (the single source of truth for these strings, also used as the leading argv element).
pub enum PlatformError {
NeedsHelper { operation: &'static str },
Unsupported { operation: &'static str },
MissingHomeDir,
TrustStore { reason: TrustStoreErrorReason },
Resolver { reason: ResolverErrorReason },
Bind { port: u16, source: std::io::Error },
BindPair { reason: BindPairErrorReason },
Io { path: PathBuf, source: std::io::Error },
MissingTool { tool: &'static str, install_hint: Option<&'static str> },
}PlatformError is #[non_exhaustive], as are its reason sub-enums, so adding variants is semver-compatible. It is intentionally not Clone + Eq because two variants wrap std::io::Error.
When the daemon sees NeedsHelper, it builds a typed HelperInvocation and hands it to its subprocess spawner. Values stay typed all the way until to_argv serialises them at the spawn site - there is no Vec<String> round-trip in between.
pub enum HelperInvocation {
InstallCa { ca_pem_path: PathBuf, fp: CaFingerprint },
UninstallCa { fp: CaFingerprint },
InstallResolver { tld: String, addr: SocketAddr },
UninstallResolver { tld: String },
Setcap { daemon_binary: PathBuf },
InstallPortRedirect { http_from: u16, http_to: u16, https_from: u16, https_to: u16 },
UninstallPortRedirect,
}This crate never spawns the helper
The OS impls never call Command::new(...) for a privileged operation. A privileged caller owns the spawn: the daemon for its own setup, or yerd elevate running under sudo. yerd-platform only computes what should happen and serialises the request. See yerd-helper and Elevation & Privileges.
HelperInvocation::to_argv / from_argv are a wire contract with the yerd-helper binary, pinned by tests/helper_argv_shape.rs (frozen golden vectors) and round-trip tested in the unit suite. The first element is always the op tag; subsequent elements alternate --flag and a single typed value:
install-ca --pem /run/user/1000/yerd/ca.pem --fingerprint <64-hex>
uninstall-ca --fingerprint <64-hex>
install-resolver --tld test --addr 127.0.0.1:5353
uninstall-resolver --tld test
setcap --binary /usr/bin/yerdd
install-port-redirect --http-from 80 --http-to 8080 --https-from 443 --https-to 8443
uninstall-port-redirectfrom_argv is strict: unknown ops, unknown/missing flags, missing values, bad fingerprints (rejects uppercase/short), bad socket addresses, bad ports, non-UTF-8 values, and trailing argv each map to a typed ArgvParseError. Adding a field, reordering, or renaming a flag trips the golden test - which is exactly the point.
Design invariants summary
| Invariant | Enforced by |
|---|---|
No tokio/anyhow/reqwest/OpenSSL in the runtime graph | tests/no_runtime_deps.rs |
| Helper argv shape is frozen | tests/helper_argv_shape.rs + round-trip unit tests |
| Fingerprint wire form is 64 lowercase hex | CaFingerprint::from_hex + tests |
Every trait method on unsupported OSes returns Unsupported | tests/unsupported.rs |
bind_pair fallback/precedence rules | pure::port_plan tests |
| All decision logic is pure and I/O-free | pure module + per-submodule tests |
#![forbid(unsafe_code)] | compiler |
Related pages
- Cross-Platform Model - how the cfg-gated layout and helper boundary fit together.
- Crates Overview - where
yerd-platformsits in the workspace. - yerd-tls and yerd-dns - primary consumers of
TrustStoreandResolverInstaller. - yerd-helper (privileged) - the binary that executes a
HelperInvocation. - Elevation & Privileges - the user-facing view of the privilege boundary.