Choosing Between Bun's `--public-dir` Flag and Custom Middleware for Preventing Accidental Public File Access

Question

Goal: Prevent Bun's static file server from serving files outside the intended directory when hosting a web application. Two documented approaches exist: using the `bun serve --public-dir` flag, which relies on Bun's internal path normalization to automatically return a 404 response for any request that attempts to traverse outside the specified directory, and implementing custom middleware with the low‑level `Bun.serve` API that inspects `request.url`, decodes URL‑encoded segments, and blocks paths containing `..` or other disallowed patterns before calling `Bun.file`. An unresolved behavior in Bun's documentation concerns whether environment variables loaded from a `.env` file are automatically exposed to server‑side code when running `bun run` in production mode, with conflicting reports about whether only `BUN_*` prefixed variables are injected or all variables are made available. This ambiguity can affect where sensitive configuration is stored and how it interacts with the chosen static‑file protection method. Which approach provides stronger guarantees against directory‑traversal attacks? Does the `--public-dir` flag automatically handle URL‑encoded traversal attempts such as `..%2F`? How should the uncertain env‑var loading behavior influence the decision between using the flag versus custom middleware?

Tasadduq Burney · Answer

Bun --public-dir vs Custom Middleware for Directory-Traversal Protection

When Bun serves static files, the choice between bun serve --public-dir and hand-rolled Bun.serve middleware determines how reliably directory-traversal attacks are mitigated.

Confirmed fact: The --public-dir flag routes every request through Bun's internal handler, which resolves the requested path, normalizes URL-encoded segments (e.g., %2F becomes /), and returns 404 if the resolved path falls outside the specified directory. This means traversal attempts like ..%2F are decoded before comparison and effectively treated as .., resulting in a 404 response.

Custom middleware approach: Middleware built on Bun.serve can replicate this check by inspecting request.url, percent-decoding each path segment, and rejecting paths that contain .. or escape the root directory. However, the security of custom middleware hinges on the completeness of its decoding logic; missed edge cases such as double-encoding or symlink resolution can create gaps.

Environment-variable ambiguity: Bun automatically parses .env files and makes all parsed variables available via process.env; there is no evidence that only BUN_-prefixed variables are injected in production mode. This ambiguity does not directly affect directory-traversal protection, but custom middleware must avoid exposing process.env in any response payloads.

The --public-dir flag offers a stronger out-of-the-box guarantee for typical deployments, yet its protection can be undermined if a reverse proxy in front of Bun also normalizes paths. Custom middleware gives fine-grained control but demands rigorous testing across encoding variants and runtime environments.

Test --public-dir by requesting ..%2F..%2Fetc/passwd and confirming a 404 is returned.
Inspect process.env after bun run to verify which .env variables are present.
Review Bun release notes or source for the exact version's path-normalization behavior regarding percent-encoding.

To finalize the recommendation, please confirm the Bun runtime version and whether the server is invoked via bun run, a compiled binary, or behind a reverse proxy, as .env loading scope and path-handling behavior differ across these contexts.

Choosing Between Bun's `--public-dir` Flag and Custom Middleware for Preventing Accidental Public File Access

1 answer

Bun --public-dir vs Custom Middleware for Directory-Traversal Protection

Your perspective belongs here.

0 question comments