Restrict the UDS mirror sockets directory to its owner and publish mirror metadata atomically

[kriszyp]

Restricts the TLS unix-domain-socket mirrors' sockets directory to its owner (mode 0700) at every mirror creator, publishes each mirror's metadata .yaml by atomic rename, and stops an isolated application's worker from reporting ready without a bound mirror.

⊙ Problem

The TLS unix-domain-socket mirrors skip TLS and trust the PROXY v2 identity a fronting proxy passes, so the sockets directory (<hdbBase>/sockets) is their only access gate. It is created with the default mode, 0755 under a typical umask, so other local users can traverse it. Separately, writeUdsMetadata rewrote the mirror's .yaml in place, so a concurrent reader or an overlapping worker could observe a truncated file.

Background: fix: make UDS mirror cleanup ownership-aware, not path-based (#2035) deferred the atomic write, and Keep per-worker UDS mirror sockets alive across an overlapping HTTP worker restart (#2964) covered restart survival.

❓ Your call: Is owner-only access warranted on every install? I judged yes: the mirror's trust comes from an identity the proxy asserts, and the directory is the portable boundary. On Linux, connecting also needs write permission on the socket file (unix(7)), so 0755 alone does not show that another user can connect. The alternative, trusting the parent directory's mode, is rejected below.

💡 Solution

• Every mirror creator calls ensureSocketsDirectory() before it publishes or binds a mirror. It creates the directory with mode 0700, or tightens an existing one whose mode differs, logging a warning with the previous mode. Creators: the native HTTP/1.1, HTTP/2 and uWS mirrors in server/http.ts, and the Bun and raw TLS mirrors in server/threads/threadServer.js.
• A worker that cannot secure the directory logs an error and skips its mirror. Its TLS listener is unaffected. An isolated application's worker is reachable only through its mirror, so it does not report ready without a bound one.
• The mirror metadata .yaml is published with atomicWriteFile: a temp file in the same directory, then a rename. A reader sees the previous complete file or the new complete file, never a truncated one.

After upgrade, an existing <hdbBase>/sockets directory is tightened to 0700 on the first secure-port start.

❓ Your call: Forcing 0700 removes group and other traversal. A fronting proxy that runs as a different non-root UID, or relies on a group-shared directory, stops reaching the mirrors after upgrade. Shared workers then serve without mirrors and log the error. Fabric is unaffected on a source-level read: Central Manager's host provisioning runs the host-manager service as root, and host-manager spawns symphony with no UID or GID override, so symphony runs as root too. This was not checked on a live host. Self-hosted operators need a release-note line. Restoring group access needs a config option; this PR adds none.

❓ Your call: Symlinks and foreign ownership are not checked. mkdir, stat and chmod follow a sockets symlink, and the owner is not compared to the Harper UID. I did not add an lstat owner check: an operator can legitimately symlink sockets to another volume, and planting either case needs write access to the Harper root, which already holds the config and keys.

⚠️ Look hardest: the readiness refusal in startServers. It is the only thing that stops an isolated worker from reporting ready with no ingress, and it counts bound mirrors through hasUdsMirror.

⚖️ Alternatives

Framing-Verdict: better-alternative-exists (53cba34eac9d)

❓ Your call: the planning review returned better-alternative-exists, and the implementation adopted its alternative in full rather than overruling it. The review found three gaps in the original plan: it enforced the directory only at the native HTTP creator, though Bun and raw TLS create the directory on their own; it hand-rolled a temp-file-and-rename writer although atomicWriteFile already exists; and propagating an enforcement error would leave the server cached and registered without its handlers. The shipped design is the one the review proposed: one helper called at all three creators, atomicWriteFile(…, { maxRetries: 0 }), and log-and-skip the mirror while the TLS listener stays up. The design was not re-submitted for a clearing verdict after adoption.

• Set process.umask(0o077) at boot: rejected. The umask is process-wide, so it changes the mode of every file Harper creates, including databases and logs, and it cannot tighten an existing directory.
• Move the mirrors to a per-user runtime directory (XDG_RUNTIME_DIR): rejected. Fronting proxies discover mirrors at <hdbBase>/sockets, so this changes that contract.
• Rely on the parent directory's mode: rejected. mountHdb creates a fresh root with HDB_FILE_PERMISSIONS (0700), but it does not repair an existing or widened root, so the invariant would still fail on upgraded installs.
• Hand-roll a temp file and rename in writeUdsMetadata: rejected in favor of the existing atomicWriteFile in config/configUtils.ts, which names a unique sibling, renames, and removes the temp file on either failure. One atomic-write implementation, not two.
• Keep the default rename retries: rejected. atomicWriteFile retries with Atomics.wait on the calling thread, and maxRetries: 0 keeps a serving worker from blocking during a certificate reload.

🔧 Changes

• server/http.ts: ensureSocketsDirectory creates or tightens the directory and logs the warning and the error path, returning the path or undefined. writeUdsMetadata publishes through atomicWriteFile. hasUdsMirror counts only mirrors that did not fail to bind. The native mirror calls the helper.
• server/threads/threadServer.js: the Bun mirror and the raw TLS mirror call the helper in place of their own mkdirSync; the old import is removed. startServers refuses ready for an isolated worker with no bound mirror.
• server/DESIGN.md: the UDS symbol row records the directory as the mirror access gate, the enforcement at each creator, and the readiness rule.
• unitTests/server/udsMirrorDirectory.test.js: a new suite for the helper and the publication path. It sits outside udsMirror.test.js, which the Windows gate excludes.
• integrationTests/server/uds-mirror-overlapping-restart.test.ts: asserts the 0700 mode after startup, and that replacement workers re-tighten a directory widened to 0755 before the restart.

✅ Verification

• npm run test:unit:main at 1d0366f: 6447 passing, 202 pending, 1 failing. The failure is nonInteractiveSpawn git credential scoping in unitTests/components/gitCredentials.test.js. It inherits the dispatch worker's GIT_* environment, and with those variables unset the file passes 19/19.
• npm run test:unit:resources at 1d0366f: 3951 passing, 54 pending, 0 failing.
• npm run test:integration:all at 1d0366f: 2296 passing, 0 failing, 18 skipped, 6 cancelled. All 6 cancellations are in the OllamaBackend suite, which needs Ollama models this machine does not have.
• npx mocha unitTests/server/udsMirrorDirectory.test.js at 4bdde9a: 10 passing. The suite proves that creation yields 0700, that a rename replaces the yaml (the inode changes), that an open descriptor keeps the previous complete generation, and that a non-empty directory at the yaml path does not throw or leave a temp file. The same file also covers tightening a pre-created 0755 directory, restoring an owner-unusable 0500 directory, idempotence, a regular file occupying the path, and a failed temp write keeping the previous yaml (non-root POSIX).
• npm run test:integration -- integrationTests/server/uds-mirror-overlapping-restart.test.ts and integrationTests/components/isolated-application.test.ts: 8/8 passing with the readiness check in place. The overlapping-restart test asserts 0700 after startup; it would fail on base, where the default mkdir mode is 0755.
• npm run lint:required, prettier --check on the changed files, and npm run check:design-docs: pass.

Not verified:

• The Bun and raw TLS mirror creators are not run by any test here; this environment has no Bun.
• The isolated-worker refusal is not exercised end to end. A sockets path occupied by a regular file would show it.
• A proxy running under another UID, and a proxy's behavior when the yaml is replaced by rename on certificate reload: no reader of this file exists in this repo. A source-level read of host-manager shows it watches the sockets directory itself (so a rename keeps firing events), re-reads each -<port>.yaml by path after a 500 ms debounce, and its -<port>.yaml filename filter skips the .tmp sibling. Not exercised live.

_{🤖 Generated by Claude Sonnet 5 (Claude Code); posted via @kriszyp.}

Related PRs: #372 independent (same files, different concern), #562 independent (adds no non-erasable TypeScript syntax), #2532 independent, #2763 independent, #2946 independent, #2956 overlaps (same http.ts area; merged cleanly through this rebase, no conflict), #2981 independent (its admission flow runs before this gate in threadServer.js; no duplication), #3029 independent (no overlapping behavior), #3035 independent (merged; its ownership gates are preserved, this PR is additional), #3069 independent (different DESIGN.md section)
Complexity: complicated

_{Review-Coverage: authored=claude; ran=gemini,codex; adjudicated=domain; declined=cursor-grok,cursor-composer,cursor-kimi,cursor-muse; rounds=14; full=4 @ b7f9179}

_{Review-Attention: study ~9m (hot: http.ts, threadServer.js; decisions: exact-0700, pool-degrade-vs-fail, gate-placement, any-vs-all-mirrors) @ b7f9179}

[github-actions]

Release cherry-pick v5.3: conflict

Cherry-pick onto v5.3 produced conflicts on commit(s): 396ab5ffcf7f78578407e9c2054e31a50d0440f5 7b26d4c87cce258c6751000dfcd4d98f62f9f564 5970700ab02021422d756102d2cf3a715022ceae cd6eff0e64b401bc0385967634ecd19683f9b638

The conflict markers are committed on branch cherry-pick/v5.3/pr-3019.
Integration tests are not running until conflicts are resolved.

@claude please review branch cherry-pick/v5.3/pr-3019 and suggest a patch that resolves the conflict markers (<<<<<<< / ======= / >>>>>>>) introduced by cherry-picking PR #3019 onto v5.3. Post the suggested patch as a comment on this PR — do not push.

[gemini-code-assist]

Code Review

This pull request enhances the security of Unix Domain Socket (UDS) mirrors by ensuring the sockets directory is restricted to owner-only access (0o700) across all worker environments. It introduces the ensureSocketsDirectory helper to enforce these permissions, updates metadata writing to be atomic, and adds comprehensive integration and unit tests. The review feedback correctly identifies a style guide violation in the new unit test file, recommending that Node built-in modules use the node: prefix for imports.