Egonex file-content.json Endpoint Security Model: Token Authentication and Path Allow-Lists

TLDR: The /file-content.json endpoint in the Egonex Understand-Anything dashboard implements a dual-layer security model that validates short-lived JWT access tokens against a graph-derived path allow-list, returning 403 Forbidden if either authentication fails or the requested file path falls outside the analyzed project scope.

The Egonex Understand-Anything repository provides a code analysis dashboard that exposes file contents through a secure development server endpoint. Located at /file-content.json, this endpoint protects sensitive source code access through a two-phase authorization system that combines cryptographic token validation with filesystem path restrictions derived from the knowledge graph.

Dual-Layer Security Architecture

The security model operates on two independent validation layers that must both pass before file contents are served.

Token-Based Authentication

The endpoint accepts short-lived access tokens generated during the /understand command execution. These tokens—typically JWTs with a 10-minute expiration—can be transmitted either as a query-string parameter (token=) or via the Authorization: Bearer header. The server validates the token's signature and expiry before proceeding to path verification.

Graph-Derived Path Allow-Lists

Beyond authentication, the system implements path-based authorization using an allow-list generated from the knowledge graph. When the analysis runs, the system constructs a set of permitted filesystem paths representing the analyzed project. The endpoint compares the requested file path against this allow-list, rejecting any attempts to access files outside the project scope with a 403 Forbidden response.

Server-Side Implementation in vite.config.ts

The authorization logic resides in the Vite development server configuration at understand-anything-plugin/packages/dashboard/vite.config.ts. The request handler implements sequential validation checks before filesystem access:

// vite.config.ts – dev server handler
if (pathname === "/file-content.json") {
  // 1️⃣ Verify the access token (decoded, checked for expiry, etc.)
  const token = request.headers.get("authorization")?.split(" ")[1];
  if (!isValidToken(token)) {
    return new Response("Invalid token", { status: 403 });
  }

  // 2️⃣ Parse the desired file path from the query string
  const filePath = new URL(request.url).searchParams.get("path");
  // 3️⃣ Check the path against the allow‑list generated by the graph
  if (!allowedPaths.has(filePath)) {
    return new Response("Path not allowed", { status: 403 });
  }

  // 4️⃣ If everything checks out, read the file from the filesystem
  const fileContent = await readFile(filePath, "utf‑8");
  return new Response(JSON.stringify({ content: fileContent }), {
    headers: { "Content-Type": "application/json" },
  });
}

Client-Side Request Construction

The React component at understand-anything-plugin/packages/dashboard/src/components/CodeViewer.tsx constructs authenticated requests by appending both the access token and the target file path as query parameters:

// CodeViewer.tsx – constructs the URL for the dev server
const params = new URLSearchParams({
  token: accessToken,               // the token obtained from /understand
  path: selectedFilePath,           // graph‑derived, already validated path
});
const url = `/file-content.json?${params.toString()}`;

Practical Implementation Examples

Fetching File Content in a React Component

When building a custom file viewer, include both the token and path in the request URL:

import { useEffect, useState } from "react";

function FileViewer({ filePath, token }) {
  const [content, setContent] = useState("");

  useEffect(() => {
    const params = new URLSearchParams({ token, path: filePath });
    fetch(`/file-content.json?${params}`)
      .then((r) => {
        if (!r.ok) throw new Error(`HTTP ${r.status}`);
        return r.json();
      })
      .then((data) => setContent(data.content))
      .catch((e) => console.error("Failed to load file:", e));
  }, [filePath, token]);

  return <pre>{content}</pre>;
}

Generating Session Tokens

On the server side, generate short-lived tokens when the analysis completes:

import { sign } from "jsonwebtoken";

// When the `/understand` command finishes, create a short‑lived JWT
export function generateAccessToken(userId: string) {
  return sign({ sub: userId }, process.env.SECRET_KEY!, {
    expiresIn: "10m", // token lives only for the dashboard session
  });
}

Security Guarantees and Attack Prevention

This dual-layer model provides defense in depth against common attack vectors:

• Token theft protection: Even if an attacker obtains a valid token, they cannot access arbitrary files outside the analyzed project directory because of the path allow-list validation.
• Path traversal mitigation: The explicit allow-list check prevents directory traversal attacks that might otherwise exploit relative path sequences (../) to access sensitive system files.
• Session limitation: The 10-minute token expiration limits the window of vulnerability if a token is intercepted during transmission.

Summary

• The /file-content.json endpoint requires both a valid JWT access token and a permitted file path to serve content.
• Token validation occurs first in the Vite dev server handler at understand-anything-plugin/packages/dashboard/vite.config.ts, rejecting requests with 403 Forbidden if the token is missing, malformed, or expired.
• Path authorization uses a graph-derived allow-list created during the /understand command execution, ensuring only files within the analyzed project scope are accessible.
• The client components in CodeViewer.tsx construct requests by appending both the token and path as query parameters.
• Failed validation at either layer immediately returns a 403 Forbidden response without exposing filesystem information.

Frequently Asked Questions

How does the file-content.json endpoint validate access tokens?

The endpoint extracts the token from either the Authorization: Bearer header or the token query parameter, then validates the JWT signature and expiration timestamp. Invalid or expired tokens trigger an immediate 403 Forbidden response before any filesystem operations occur.

What prevents the endpoint from serving arbitrary files outside the project?

The system maintains an allowedPaths Set derived from the knowledge graph generated during analysis. Before reading any file, the handler checks if the requested path exists in this allow-list. Paths not present in the graph result in a 403 Forbidden response, blocking directory traversal and unauthorized file access.

How long are access tokens valid for the file-content.json endpoint?

Access tokens are short-lived JWTs typically configured with a 10-minute expiration via the expiresIn: "10m" option during generation. This limits the session duration and reduces risk if tokens are compromised.

Where is the security logic implemented in the Egonex Understand-Anything repository?

The server-side validation logic resides in understand-anything-plugin/packages/dashboard/vite.config.ts, while the client-side request construction is handled in understand-anything-plugin/packages/dashboard/src/components/CodeViewer.tsx. These files implement the dual-layer security model for the development server environment.

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