# How the Egonex Dashboard Code Viewer Enforces Path Allowlisting from the Knowledge Graph

> Discover how the Egonex dashboard code viewer secures your project by enforcing path allowlisting directly from the knowledge graph, preventing unauthorized file access.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: internals
- Published: 2026-06-21

---

**The Egonex dashboard code viewer enforces strict path allowlisting by validating every file request against a Set of paths extracted directly from the knowledge graph, rejecting any access attempts outside the defined project scope.**

The Egonex Understand-Anything dashboard provides a secure code viewer that only exposes source files explicitly referenced in the project's knowledge graph. This implementation prevents directory traversal attacks and ensures sensitive files outside the analysis scope remain inaccessible, all while delivering syntax-highlighted source code through a React-based interface.

## Building the Allowlist from the Knowledge Graph

The security model begins with a pre-computed allowlist derived from the graph data generated during the project analysis phase.

### Extracting File Paths with graphFilePathSet

When the development server starts, it invokes `graphFilePathSet` to parse the [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/knowledge-graph.json) file and extract every node's `filePath` property. This function creates an in-memory `Set<string>` containing all permissible paths, ensuring O(1) lookup time during request validation.

In [`understand-anything-plugin/packages/dashboard/vite.config.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/dashboard/vite.config.ts), the implementation reads the graph structure and filters for nodes with valid string paths:

```typescript
// vite.config.ts (excerpt)
function graphFilePathSet(graphFile: string, projectRoot: string): Set<string> {
  const allowed = new Set<string>();
  const raw = JSON.parse(fs.readFileSync(graphFile, "utf-8")) as {
    nodes?: Array<Record<string, unknown>>;
  };
  for (const node of raw.nodes ?? []) {
    if (typeof node.filePath !== "string") continue;
    const normalized = normalizeGraphPath(node.filePath, projectRoot);
    if (normalized) allowed.add(normalized);
  }
  return allowed;
}

```

### Normalizing Paths for Cross-Platform Compatibility

Before paths enter the allowlist, `normalizeGraphPath` converts them to a canonical form. This process makes paths relative to the project root and standardizes backslashes to forward slashes, eliminating platform-specific discrepancies that could bypass security checks.

The normalization ensures that paths like `src\components\App.tsx` and [`src/components/App.tsx`](https://github.com/Egonex-AI/Understand-Anything/blob/main/src/components/App.tsx) resolve to identical entries in the allowlist Set.

## Validating File Requests in the Development Server

The development server exposes a single endpoint for file retrieval, implementing multiple layers of validation before serving content.

### The /file-content.json Endpoint

The server middleware in [`vite.config.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/vite.config.ts) handles requests to [`/file-content.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main//file-content.json) by delegating to `readSourceFile`, which orchestrates the security checks:

```typescript
// vite.config.ts (excerpt)
if (pathname === "/file-content.json") {
  const result = readSourceFile(url);
  sendJson(res, result.statusCode, result.payload);
  return;
}

```

### Token and Path Sanitization

The `readSourceFile` function first validates the presence of a one-time token parameter, then sanitizes the `path` query parameter. It rejects requests containing null bytes, absolute paths, or traversal sequences that attempt to escape the project root.

This sanitization produces a `safeRelativePath` that is guaranteed to reside within the project directory structure, neutralizing `..` traversal attempts before they reach the allowlist check.

### Allowlist Enforcement Logic

After sanitization, the server performs the critical allowlist validation. It checks whether the `safeRelativePath` exists in the `graphFilePathSet`. If the path is absent, the server returns an HTTP 404 with the message "File is not in the knowledge graph", preventing access to any file not explicitly modeled in the graph.

```typescript
// vite.config.ts (excerpt)
const graphFile = findGraphFile("knowledge-graph.json");
if (!graphFile) return rejectFileRequest("No knowledge graph found. Run /understand first.", 404);

const projectRoot = projectRootFromGraphFile(graphFile);
// ... sanitization logic ...
const safeRelativePath = relativeToRoot.split(path.sep).join("/");
if (!graphFilePathSet(graphFile, projectRoot).has(safeRelativePath)) {
  return rejectFileRequest("File is not in the knowledge graph", 404);
}

```

Only after passing this check does the server verify the file is not binary and enforce the `MAX_SOURCE_FILE_BYTES` limit (1 MiB).

## Client-Side Implementation

The React component responsible for displaying source code constructs requests URLs that include the required security token and file path.

### Constructing Secure Requests in CodeViewer.tsx

The [`CodeViewer.tsx`](https://github.com/Egonex-AI/Understand-Anything/blob/main/CodeViewer.tsx) component uses `fileContentUrl` to build the request URL, encoding the path and token as query parameters:

```tsx
// CodeViewer.tsx (excerpt)
function fileContentUrl(filePath: string, token: string): string {
  const params = new URLSearchParams({ token, path: filePath });
  return `/file-content.json?${params.toString()}`;
}

```

After fetching the JSON response, the component renders the source with syntax highlighting. Because the server strictly validates every request against the graph-derived allowlist, the UI cannot inadvertently expose files outside the project's analyzed scope, even if the client-side code is compromised.

## Summary

The Egonex dashboard code viewer implements defense-in-depth for source file access:

- **Graph-derived allowlist**: The `graphFilePathSet` function builds a Set of permissible paths exclusively from nodes in [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/knowledge-graph.json)
- **Path normalization**: All paths are converted to relative, forward-slash format to ensure consistent matching across platforms
- **Traversal prevention**: The `readSourceFile` function sanitizes inputs and resolves safe relative paths before allowlist checking
- **Strict enforcement**: Requests for paths not present in the allowlist receive HTTP 404 errors with explicit messaging
- **Size and type limits**: Additional checks prevent binary file exposure and enforce a 1 MiB size cap

## Frequently Asked Questions

### How does the code viewer prevent access to files outside the project directory?

The server rejects any request containing absolute paths or directory traversal sequences (`..`) during the initial sanitization phase in `readSourceFile`. Even if these checks were bypassed, the path must still exist in the `graphFilePathSet` derived from the knowledge graph, which only contains references to files within the analyzed project root.

### What happens if a file is not listed in the knowledge graph?

The server returns an HTTP 404 status code with the message "File is not in the knowledge graph". This occurs in [`vite.config.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/vite.config.ts) when the `safeRelativePath` lookup against the allowlist Set returns false, preventing the file system from being accessed for unlisted paths.

### Why is the allowlist implemented as a Set rather than an array?

The `graphFilePathSet` function returns a `Set<string>` to provide O(1) average-time complexity for membership tests. This is critical for performance when the knowledge graph contains thousands of files, ensuring that request validation remains instantaneous regardless of project size.

### How does the token validation work alongside path allowlisting?

Before checking the path allowlist, `readSourceFile` verifies the presence of a valid one-time token in the request URL. This token acts as a short-lived credential that prevents unauthorized external requests from even reaching the path validation logic, creating a two-layer security barrier for source code access.