fix(security): enforce max-bytes cap on /api/file + MCP read_file (RAN-9) (#67)

Without a size guard, /api/file and the read_file MCP tool loaded entire
files into the JVM heap before the optional line slice was applied. A
multi-GB file in an indexed codebase trivially OOM'd the serving process,
giving anyone with HTTP access a DoS lever against the read-only API and
MCP endpoints.

Adds a configurable cap (default 5 MiB, key: serving.max_file_bytes) and
routes both entry points through a single SafeFileReader:

- No line range → check on-disk size first; reject before reading.
- With a line range → stream via BufferedReader, apply start/end filter,
  and track accumulated UTF-8 byte count against the cap.

REST returns HTTP 413 (CONTENT_TOO_LARGE); MCP returns the usual JSON
{\"error\": ...} payload. Both emit a message shaped like
\"File exceeds max size: N bytes (max M bytes)\".

Config is plumbed end-to-end through the unified config stack:
ServingConfig.maxFileBytes, ConfigDefaults.builtIn() (5 MiB),
ConfigMerger, EnvVarOverlay (CODEIQ_SERVING_MAXFILEBYTES), snake_case
YAML key with camelCase alias, UnifiedConfigAdapter → legacy
CodeIqConfig.maxFileBytes (with a >=1 clamp in the setter).

Tests added:
- SafeFileReaderTest: whole-file reject, line-range streaming, line-range
  reject mid-stream, negative startLine clamping.
- GraphControllerTest: 413 on oversize whole-file read, 200 on narrow
  line range when the whole file exceeds cap.
- McpToolsTest: \"exceeds max size\" error for oversize read, line-range
  passthrough, line-range reject.
- UnifiedConfigAdapterTest: explicit maxFileBytes overrides default;
  absent value falls back to CodeIqConfig default (5 MiB).
- ConfigResolverTest / ConfigValidatorTest / ConfigExplainSubcommandTest:
  updated for the new ServingConfig record shape.

Default documented in docs/codeiq.yml.example.

Co-authored-by: Paperclip <noreply@paperclip.ing>

Author: aksOps

docs/codeiq.yml.example

@@ -54,6 +54,7 @@ serving:
   port: 8080                    # HTTP port for REST + MCP + UI
   bind_address: 0.0.0.0         # interface to bind; 127.0.0.1 for localhost-only
   read_only: false              # must be false in non-prod; CI gate enforces this
+  max_file_bytes: 5242880       # cap on /api/file + MCP read_file (bytes); 5 MiB default — rejects with HTTP 413
   neo4j:
     dir: .codeiq/graph/graph.db    # embedded Neo4j data directory
     page_cache_mb: 256             # Neo4j page cache (MB)

src/main/java/io/github/randomcodespace/iq/api/GraphController.java

@@ -17,7 +17,6 @@
 import io.github.randomcodespace.iq.model.NodeKind;
 
 import java.io.IOException;
-import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.NoSuchFileException;
 import java.nio.file.Path;
@@ -291,23 +290,14 @@ public ResponseEntity<String> readFile(
             return ResponseEntity.notFound().build();
         }
         try {
-            String content = Files.readString(resolvedReal, StandardCharsets.UTF_8);
-            if (startLine != null || endLine != null) {
-                String[] lines = content.split("\n", -1);
-                int start = (startLine != null ? startLine : 1);
-                int end = (endLine != null ? endLine : lines.length);
-                start = Math.max(1, Math.min(start, lines.length));
-                end = Math.max(start, Math.min(end, lines.length));
-                StringBuilder sb = new StringBuilder();
-                for (int i = start - 1; i < end; i++) {
-                    if (i > start - 1) sb.append('\n');
-                    sb.append(lines[i]);
-                }
-                content = sb.toString();
-            }
+            String content = SafeFileReader.read(resolvedReal, startLine, endLine, config.getMaxFileBytes());
             return ResponseEntity.ok()
                     .contentType(MediaType.TEXT_PLAIN)
                     .body(content);
+        } catch (SafeFileReader.FileTooLargeException tooLarge) {
+            return ResponseEntity.status(HttpStatus.CONTENT_TOO_LARGE)
+                    .contentType(MediaType.TEXT_PLAIN)
+                    .body(tooLarge.getMessage());
         } catch (IOException e) {
             return ResponseEntity.status(500)
                     .contentType(MediaType.TEXT_PLAIN)

src/main/java/io/github/randomcodespace/iq/api/SafeFileReader.java

@@ -0,0 +1,77 @@
+package io.github.randomcodespace.iq.api;
+
+import java.io.BufferedReader;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+/**
+ * Reads files for the read-only serving layer with a hard byte cap.
+ *
+ * <p>The two entry points that surface repo content over HTTP — {@code GET /api/file}
+ * and the {@code read_file} MCP tool — must never load unbounded content into the JVM
+ * heap; a multi-GB file would OOM the serving process and become a trivial DoS vector.
+ *
+ * <p>Behaviour:
+ * <ul>
+ *   <li>Without a line range, the file's on-disk size is checked first and the read
+ *       is rejected if it exceeds the cap.</li>
+ *   <li>With a {@code startLine}/{@code endLine} range, the file is read line-by-line
+ *       via a {@link BufferedReader}; only lines in range are retained and the
+ *       accumulated UTF-8 byte count is capped the same way.</li>
+ * </ul>
+ */
+public final class SafeFileReader {
+
+    public static final class FileTooLargeException extends RuntimeException {
+        private final long size;
+        private final long max;
+
+        public FileTooLargeException(long size, long max) {
+            super("File exceeds max size: " + size + " bytes (max " + max + " bytes)");
+            this.size = size;
+            this.max = max;
+        }
+
+        public long size() { return size; }
+        public long max()  { return max; }
+    }
+
+    private SafeFileReader() {}
+
+    public static String read(Path path, Integer startLine, Integer endLine, long maxBytes)
+            throws IOException {
+        if (startLine == null && endLine == null) {
+            long size = Files.size(path);
+            if (size > maxBytes) {
+                throw new FileTooLargeException(size, maxBytes);
+            }
+            return Files.readString(path, StandardCharsets.UTF_8);
+        }
+        int start = Math.max(1, startLine != null ? startLine : 1);
+        int end = endLine != null ? Math.max(start, endLine) : Integer.MAX_VALUE;
+        StringBuilder sb = new StringBuilder();
+        long accumulated = 0;
+        boolean first = true;
+        try (BufferedReader reader = Files.newBufferedReader(path, StandardCharsets.UTF_8)) {
+            String line;
+            int idx = 0;
+            while ((line = reader.readLine()) != null) {
+                idx++;
+                if (idx < start) continue;
+                if (idx > end) break;
+                long lineBytes = line.getBytes(StandardCharsets.UTF_8).length;
+                long add = lineBytes + (first ? 0L : 1L);
+                if (accumulated + add > maxBytes) {
+                    throw new FileTooLargeException(accumulated + add, maxBytes);
+                }
+                if (!first) sb.append('\n');
+                sb.append(line);
+                accumulated += add;
+                first = false;
+            }
+        }
+        return sb.toString();
+    }
+}

src/main/java/io/github/randomcodespace/iq/config/CodeIqConfig.java

@@ -50,6 +50,9 @@ public class CodeIqConfig {
     /** Maximum lines per snippet returned in evidence packs (default 50). */
     private int maxSnippetLines = 50;
 
+    /** Maximum bytes read by the serving layer's /api/file and MCP read_file (default 5 MiB). */
+    private long maxFileBytes = 5L * 1024L * 1024L;
+
     public static class Graph {
         private String path = ".codeiq/graph/graph.db";
 
@@ -152,4 +155,12 @@ public int getMaxSnippetLines() {
     void setMaxSnippetLines(int maxSnippetLines) {
         this.maxSnippetLines = Math.max(1, maxSnippetLines);
     }
+
+    public long getMaxFileBytes() {
+        return maxFileBytes;
+    }
+
+    void setMaxFileBytes(long maxFileBytes) {
+        this.maxFileBytes = Math.max(1L, maxFileBytes);
+    }
 }

src/main/java/io/github/randomcodespace/iq/config/UnifiedConfigAdapter.java

@@ -58,6 +58,9 @@ public static CodeIqConfig toCodeIqConfig(CodeIqUnifiedConfig u) {
             if (u.serving().readOnly() != null) {
                 c.setReadOnly(u.serving().readOnly());
             }
+            if (u.serving().maxFileBytes() != null) {
+                c.setMaxFileBytes(u.serving().maxFileBytes());
+            }
             if (u.serving().neo4j() != null && u.serving().neo4j().dir() != null) {
                 CodeIqConfig.Graph graph = new CodeIqConfig.Graph();
                 graph.setPath(u.serving().neo4j().dir());

src/main/java/io/github/randomcodespace/iq/config/unified/ConfigDefaults.java

@@ -30,6 +30,7 @@ public static CodeIqUnifiedConfig builtIn() {
                         8080,
                         "0.0.0.0",
                         false,
+                        5L * 1024L * 1024L, // maxFileBytes — 5 MiB cap on /api/file + read_file
                         new Neo4jConfig(
                                 ".codeiq/graph/graph.db",
                                 256, 256, 1024

src/main/java/io/github/randomcodespace/iq/config/unified/ConfigMerger.java

@@ -66,9 +66,10 @@ private IndexingConfig mergeIndexing(IndexingConfig lo, IndexingConfig hi, Input
 
     private ServingConfig mergeServing(ServingConfig lo, ServingConfig hi, Input l, Map<String,ConfigProvenance> p) {
         return new ServingConfig(
-                take("serving.port",         lo.port(),        hi.port(),        l, p),
-                take("serving.bind_address", lo.bindAddress(), hi.bindAddress(), l, p),
-                take("serving.read_only",    lo.readOnly(),    hi.readOnly(),    l, p),
+                take("serving.port",           lo.port(),         hi.port(),         l, p),
+                take("serving.bind_address",   lo.bindAddress(),  hi.bindAddress(),  l, p),
+                take("serving.read_only",      lo.readOnly(),     hi.readOnly(),     l, p),
+                take("serving.max_file_bytes", lo.maxFileBytes(), hi.maxFileBytes(), l, p),
                 new Neo4jConfig(
                         take("serving.neo4j.dir",             lo.neo4j().dir(),            hi.neo4j().dir(),            l, p),
                         take("serving.neo4j.page_cache_mb",   lo.neo4j().pageCacheMb(),    hi.neo4j().pageCacheMb(),    l, p),

src/main/java/io/github/randomcodespace/iq/config/unified/EnvVarOverlay.java

@@ -21,7 +21,7 @@ public static CodeIqUnifiedConfig from(Map<String, String> env) {
                 pageMb = null, heapInit = null, heapMax = null,
                 maxDepth = null, maxRadius = null, maxFiles = null, maxSnippetLines = null,
                 parallelism = null;
-        Long maxPayload = null;
+        Long maxPayload = null, servingMaxFileBytes = null;
         Boolean readOnly = null, incremental = null, metrics = null, tracing = null, mcpEnabled = null;
         String cacheDir = null, bindAddr = null, projectName = null, projectRoot = null,
                 projectServiceName = null,
@@ -56,6 +56,7 @@ public static CodeIqUnifiedConfig from(Map<String, String> env) {
                     case "SERVING_PORT" -> port = Integer.parseInt(v);
                     case "SERVING_BINDADDRESS" -> bindAddr = v;
                     case "SERVING_READONLY" -> readOnly = Boolean.parseBoolean(v);
+                    case "SERVING_MAXFILEBYTES" -> servingMaxFileBytes = Long.parseLong(v);
                     case "SERVING_NEO4J_DIR" -> neo4jDir = v;
                     case "SERVING_NEO4J_PAGECACHEMB" -> pageMb = Integer.parseInt(v);
                     case "SERVING_NEO4J_HEAPINITIALMB" -> heapInit = Integer.parseInt(v);
@@ -90,7 +91,7 @@ public static CodeIqUnifiedConfig from(Map<String, String> env) {
                 new ProjectConfig(projectName, projectRoot, projectServiceName, List.of()),
                 new IndexingConfig(languages, include, exclude, incremental, cacheDir, parallelism, batch,
                         maxDepth, maxRadius, maxFiles, maxSnippetLines, parsers),
-                new ServingConfig(port, bindAddr, readOnly,
+                new ServingConfig(port, bindAddr, readOnly, servingMaxFileBytes,
                         new Neo4jConfig(neo4jDir, pageMb, heapInit, heapMax)),
                 new McpConfig(mcpEnabled, mcpTransport, mcpBasePath,
                         new McpAuthConfig(mcpMode, mcpTokenEnv),

src/main/java/io/github/randomcodespace/iq/config/unified/ServingConfig.java

@@ -1,4 +1,4 @@
 package io.github.randomcodespace.iq.config.unified;
-public record ServingConfig(Integer port, String bindAddress, Boolean readOnly, Neo4jConfig neo4j) {
-    public static ServingConfig empty() { return new ServingConfig(null, null, null, Neo4jConfig.empty()); }
+public record ServingConfig(Integer port, String bindAddress, Boolean readOnly, Long maxFileBytes, Neo4jConfig neo4j) {
+    public static ServingConfig empty() { return new ServingConfig(null, null, null, null, Neo4jConfig.empty()); }
 }

src/main/java/io/github/randomcodespace/iq/config/unified/UnifiedConfigLoader.java

@@ -126,6 +126,8 @@ private static ServingConfig servingFrom(Map<String, Object> m, Path path, Set<S
                 requireIntOrNull(m.get("port"), path, "serving.port"),
                 (String) pick(m, "serving", "bind_address", "bindAddress", path, warned),
                 (Boolean) pick(m, "serving", "read_only", "readOnly", path, warned),
+                requireLongOrNull(pick(m, "serving", "max_file_bytes", "maxFileBytes", path, warned),
+                        path, "serving.max_file_bytes"),
                 n4j);
     }