Skip to content

fix(docs): prevent path traversal in /docs static handler #80

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pescn wants to merge 1 commit into
base: main
Choose a base branch
from
Open

fix(docs): prevent path traversal in /docs static handler #80

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 16 additions & 4 deletions backend/src/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ async function exists(path: string): Promise<boolean> {
}
}
import { join } from "node:path";
import { resolvePathWithinBase } from "@/utils/safePath";
import { routes } from "@/api";
import { metricsApi } from "@/api/metrics";
import { loggerPlugin } from "@/plugins/loggerPlugin";
Expand Down Expand Up @@ -91,7 +92,12 @@ async function docsPlugin(dir: string) {
// Handle TanStack Start's __tsr static server function cache requests
// These are requested from root path, not /docs/
.get("/__tsr/*", async ({ path, status }) => {
const response = await serveStaticFile(join(dir, path));
const filePath = resolvePathWithinBase(dir, path);
if (!filePath) {
return status(404);
}

const response = await serveStaticFile(filePath);
return response || status(404);
})
.get("/docs", ({ status }) => {
Expand All @@ -107,7 +113,10 @@ async function docsPlugin(dir: string) {
return status(404);
}
const subPath = path.replace("/docs", "");
const exactPath = join(dir, subPath);
const exactPath = resolvePathWithinBase(dir, subPath);
if (!exactPath) {
return status(404);
}

// Try to serve as static file
const staticResponse = await serveStaticFile(exactPath);
Expand All @@ -116,8 +125,11 @@ async function docsPlugin(dir: string) {
}

// Check if there's a specific HTML file for this path (directory with index.html)
const specificHtmlPath = join(dir, subPath, "index.html");
if (await exists(specificHtmlPath)) {
const specificHtmlPath = resolvePathWithinBase(
dir,
join(subPath, "index.html"),
);
if (specificHtmlPath && (await exists(specificHtmlPath))) {
const html = await readFile(specificHtmlPath, "utf-8");
return new Response(html, {
headers: { "Content-Type": "text/html" },
Expand Down
27 changes: 27 additions & 0 deletions backend/src/utils/safePath.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
import { describe, expect, test } from "bun:test";
import { resolve } from "node:path";
import { resolvePathWithinBase } from "./safePath";

describe("resolvePathWithinBase", () => {
const baseDir = resolve("/tmp/docs-base");

test("resolves nested relative paths inside the base directory", () => {
expect(resolvePathWithinBase(baseDir, "/assets/app.js")).toBe(
resolve(baseDir, "assets/app.js"),
);
});

test("keeps base directory requests inside the base directory", () => {
expect(resolvePathWithinBase(baseDir, "/")).toBe(baseDir);
});

test("rejects traversal outside the base directory", () => {
expect(resolvePathWithinBase(baseDir, "/../../etc/passwd")).toBeNull();
});

test("contains repeated leading slashes within the base directory", () => {
expect(resolvePathWithinBase(baseDir, "//etc/passwd")).toBe(
resolve(baseDir, "etc/passwd"),
);
});
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Mar 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

To complement the suggested change in safePath.ts, it would be beneficial to add a test case that verifies that valid paths containing .. which resolve within the base directory are handled correctly.

    );
  });

  test("resolves valid paths with '..' segments that stay within the base directory", () => {
    expect(
      resolvePathWithinBase(baseDir, "/assets/css/../js/app.js"),
    ).toBe(resolve(baseDir, "assets/js/app.js"));
  });

});
18 changes: 18 additions & 0 deletions backend/src/utils/safePath.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
import { resolve } from "node:path";

export function resolvePathWithinBase(
baseDir: string,
requestPath: string,
): string | null {
const normalizedRequestPath = requestPath.replaceAll("\\", "/");
const pathSegments = normalizedRequestPath
.replace(/^\/+/, "")
.split("/")
.filter(Boolean);

if (pathSegments.includes("..")) {
return null;
}

return resolve(baseDir, ...pathSegments);
}
Comment on lines +1 to +18
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Mar 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

security-medium medium

The current implementation is a bit too restrictive as it rejects any path containing .., even if it resolves to a path still within the base directory (e.g., /foo/../bar). A more robust approach is to resolve the path first and then verify that it is still within the intended base directory. This allows for valid relative paths while still preventing directory traversal attacks. I've also added a check for null byte injection as an extra precaution.

import { isAbsolute, relative, resolve } from "node:path";

export function resolvePathWithinBase(
  baseDir: string,
  requestPath: string,
): string | null {
  // Prevent null byte injection.
  if (requestPath.includes("\u0000")) {
    return null;
  }

  // Resolve the path. This will process '..', '.', etc.
  // We must treat requestPath as relative to baseDir, so we remove leading slashes.
  const resolvedPath = resolve(baseDir, requestPath.replace(/^\/+/, ""));

  // Check if the resolved path is a sub-path of baseDir.
  const relation = relative(baseDir, resolvedPath);

  // If `relation` is empty, it's the base directory itself.
  // If it starts with '..', it has escaped the base directory.
  // An absolute path as `relation` is also an escape.
  if (relation.startsWith("..") || isAbsolute(relation)) {
    return null;
  }

  return resolvedPath;
}

Loading