How the /file-content.json Endpoint is Secured in Understand-Anything

The /file-content.json endpoint is protected by a one-time secret token, multi-stage path validation to prevent directory traversal, and a strict whitelist that only permits access to files indexed in the knowledge graph.

The Understand-Anything dashboard, implemented as a Vite development server in understand-anything-plugin/packages/dashboard/vite.config.ts, exposes sensitive source code previews through JSON endpoints. To secure the /file-content.json endpoint against unauthorized access and path traversal attacks while maintaining a seamless local development experience, the implementation employs a defense-in-depth strategy with three distinct security layers.

Layer 1: Token-Based Authentication

Every request to /file-content.json must include a valid one-time secret token generated when the server starts. According to the source code in vite.config.ts, the token is created using Node.js crypto at line 12:

// understand-anything-plugin/packages/dashboard/vite.config.ts
const ACCESS_TOKEN = process.env.UNDERSTAND_ACCESS_TOKEN
    || crypto.randomBytes(16).toString("hex");

The server prints this token to the console and embeds it in the dashboard URL (http://127.0.0.1:5173/?token=<token>). The authentication check occurs at lines 265-267 before any file handling logic:

if (url.searchParams.get("token") !== ACCESS_TOKEN) {
    sendJson(res, 403, { error: "Forbidden: missing or invalid token" });
    return;
}

The sendJson helper (lines 4-8) consistently serializes JSON responses. Requests without the correct token query parameter immediately receive a 403 Forbidden response, preventing unauthenticated access to source files.

Layer 2: Path Validation and Directory Traversal Protection

Once authenticated, requests undergo rigorous path sanitization within the readSourceFile function (lines 14-78). This implementation blocks multiple attack vectors through sequential validation checks.

Null Byte and Absolute Path Rejection

The function first rejects requests containing null bytes or absolute paths at lines 16-18:

if (!requestedPath) return rejectFileRequest("Missing path");
if (requestedPath.includes("\0")) return rejectFileRequest("Invalid path");
if (path.isAbsolute(requestedPath)) return rejectFileRequest("Absolute paths not allowed");

Normalization and Traversal Detection

After normalization, the code explicitly forbids directory traversal attacks at lines 22-27:

const normalizedPath = path.normalize(requestedPath);
if (normalizedPath === "." || normalizedPath.startsWith(`..${path.sep}`) || normalizedPath.startsWith("..")) {
    return rejectFileRequest("Path traversal detected");
}

These checks ensure the path parameter cannot escape the project root via sequences like ../../../etc/passwd.

Layer 3: Knowledge Graph Whitelist and Content Restrictions

Even valid relative paths face additional authorization barriers before content retrieval.

Graph Membership Verification

The endpoint maintains a whitelist of files analyzed and indexed in the knowledge graph. The graphFilePathSet function (lines 55-66) builds this set, and readSourceFile validates against it at line 48:

if (!graphFilePathSet(graphFile, projectRoot).has(safeRelativePath)) {
    return rejectFileRequest("File is not in the knowledge graph");
}

This ensures only source files explicitly processed by Understand-Anything are accessible, preventing access to configuration files or other project assets outside the analysis scope.

Size and Binary File Detection

Final content filters prevent serving binary files or excessively large sources at lines 59-65:

if (stat.size > MAX_SOURCE_FILE_BYTES) {
    return rejectFileRequest("File too large", 413);
}
if (buffer.includes(0)) {
    return rejectFileRequest("Binary files not supported", 415);
}

The 1 MiB size limit and null byte detection ensure the endpoint only returns reasonably sized text files, returning 413 Payload Too Large or 415 Unsupported Media Type for violations.

Practical Usage Examples

Starting the Dashboard

When launching the development server, the access token prints automatically:

pnpm dev:dashboard

# Output: 🔑  Dashboard URL: http://127.0.0.1:5173/?token=ab12cd34ef56...

Fetching File Content

Use the token to authenticate requests for specific files:

curl "http://127.0.0.1:5173/file-content.json?token=ab12cd34ef56&path=src/utils/helpers.ts"

A successful response includes metadata and content:

{
  "path": "src/utils/helpers.ts",
  "language": "typescript",
  "content": "export function foo() { return 'bar'; }",
  "sizeBytes": 42,
  "lineCount": 1
}

Error Responses

Invalid tokens return 403 Forbidden:

{
  "error": "Forbidden: missing or invalid token"
}

Requests for files outside the knowledge graph return 404 Not Found:

{
  "error": "File is not in the knowledge graph"
}

Summary

• One-time secret token: Generated at startup via crypto.randomBytes(16).toString("hex") and required as a query parameter on every request to /file-content.json.
• Strict path validation: The readSourceFile function blocks absolute paths, null bytes, and directory traversal attempts at lines 14-27 in vite.config.ts.
• Knowledge graph whitelist: Only files indexed in the graph can be accessed, enforced via graphFilePathSet validation at line 48.
• Content safety limits: Files over 1 MiB or containing binary data are rejected with 413 or 415 status codes.

Frequently Asked Questions

What happens if I access /file-content.json without a token?

The server returns a 403 Forbidden error with the message "Forbidden: missing or invalid token". The token validation occurs in vite.config.ts at lines 265-267 before any file system operations, ensuring unauthenticated requests cannot probe for file existence or path vulnerabilities.

Can the endpoint be exploited to read arbitrary files outside the project?

No. The implementation uses multiple defenses: absolute paths are rejected, paths containing .. sequences are blocked after normalization, and the graphFilePathSet whitelist ensures only analyzed files are served. Even with a valid token, an attacker cannot traverse to /etc/passwd or other sensitive system files.

Why does the endpoint restrict access to knowledge graph files only?

The whitelist approach ensures that only source code explicitly processed and indexed by Understand-Anything is exposed. This prevents accidental leakage of configuration files, environment variables, or other project files that might contain secrets but are not part of the code analysis scope.

What file types will trigger a 415 Unsupported Media Type error?

Any file detected as binary will return this error. The readSourceFile function checks for null bytes in the file buffer at line 65, which reliably identifies binary content. This prevents the dashboard from attempting to display compiled binaries, images, or other non-textual data.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}