ucn 5.0.3 → 5.0.5

package/.claude/skills/ucn/SKILL.md

@@ -30,12 +30,14 @@ The release board independently cross-checks overlapping stable-handle answers f
 Publish-blocking semantic gates also compare stratified samples from pinned real repositories with independent language-native oracles: ts-morph, Pyright, gopls, rust-analyzer, JDT LS, clangd, and Roslyn. This validates the measured static evidence classes; it does not turn dynamic dispatch, generated code, reflection, or external dependencies into complete runtime knowledge.
 
 MCP keeps its process and project index warm across calls. CLI and MCP share
-the same text budget: targeted commands default to 10K output characters,
-broad commands to 3K, with a 100K hard ceiling. Use CLI `--max-chars`, MCP
-`max_chars`, a narrower file/directory scope, or a smaller section projection
-when necessary. Truncation must retain the accounting/contract lines needed to
-interpret the answer, and the requested limit includes both the notice and the
-preserved metadata.
+the same text budget: broad sweep commands (`repo`, `entrypoints`,
+`endpoints`, `deadcode`, `deps`, `check`, `audit-async`) default to 3K output
+characters, all other commands to 10K, with a 100K hard ceiling. Use CLI
+`--max-chars`, MCP `max_chars`, a narrower file/directory scope, or a smaller
+section projection when necessary. Truncated output keeps the head of the
+answer, a notice stating the full size and limit, and the accounting/contract
+lines needed to interpret what remains; the requested limit includes all
+three. The text block is the whole response on every surface.
 
 Persistent indexes live in a per-user, project-keyed cache rather than the analyzed repository. Set `UCN_CACHE_DIR` to override the cache root; CLI `--no-cache` bypasses persistence and `--clear-cache` removes the current project's cache. Legacy `<project>/.ucn-cache` directories are migrated on first use.
 

package/core/registry.js

@@ -153,10 +153,12 @@ const FLAG_APPLICABILITY = {
     auditAsync:   ['file', 'exclude', 'limit'],
 };
 
-// Commands whose output is project-wide — truncation means you need a filter, not more text.
-// Used by MCP server for tighter default output limits.
+// Project/change-wide sweep commands with no required symbol argument —
+// truncation means you need a filter, not more text. Drives the shared
+// CLI/MCP output budget: broad commands default to 3K chars, everything
+// else (symbol-targeted commands like usages/tests included) to 10K.
 const BROAD_COMMANDS = new Set([
-    'repo', 'entrypoints', 'endpoints', 'tests', 'deadcode', 'usages',
+    'repo', 'entrypoints', 'endpoints', 'deadcode',
     'deps', 'check', 'auditAsync',
 ]);
 

package/core/shared.js

@@ -2,9 +2,37 @@
  * core/shared.js - Shared utility functions used by both CLI and MCP server
  */
 
+const fs = require('fs');
+const path = require('path');
 const { isTestFile } = require('./discovery');
 const { detectLanguage } = require('./parser');
 
+/**
+ * Security containment check (fix #285): is `candidate` inside `root`?
+ *
+ * UCN only ever reads files it discovered under the project root. Any code
+ * path that resolves a caller-supplied path string (stack traces, handles)
+ * must gate the read on this before touching disk, or a crafted input like
+ * `File "/etc/passwd"` or `../../secret` exfiltrates arbitrary files through
+ * the tool surface (CLI and, more dangerously, the MCP tool agents call).
+ *
+ * Symlinks are followed via realpath so a link INSIDE the project cannot
+ * resolve to a target outside it. Non-existent candidates fall back to a
+ * lexical resolve — the caller still gates the read on existence.
+ * Comparison is boundary-correct: a sibling directory whose name merely
+ * shares the root's prefix (`/a/b` vs `/a/bee`) is not "inside".
+ */
+function isPathInsideRoot(root, candidate) {
+    if (!root || !candidate) return false;
+    let realRoot;
+    try { realRoot = fs.realpathSync(root); } catch { realRoot = path.resolve(root); }
+    let realCandidate;
+    try { realCandidate = fs.realpathSync(candidate); } catch { realCandidate = path.resolve(candidate); }
+    const rel = path.relative(realRoot, realCandidate);
+    return rel === '' ||
+        (rel !== '..' && !rel.startsWith('..' + path.sep) && !path.isAbsolute(rel));
+}
+
 /**
  * Code-unit string comparison (rule 11 / fix #227): output ordering is part
  * of the public contract and must be byte-identical across machines —
@@ -453,4 +481,5 @@ module.exports = {
     isOverrideMarked,
     hasTextBlindspots,
     countTextBlindspots,
+    isPathInsideRoot,
 };

package/core/stacktrace.js

@@ -7,6 +7,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { isPathInsideRoot } = require('./shared');
 
 /**
  * Calculate path similarity score between two file paths
@@ -85,9 +86,14 @@ function findBestMatchingFile(index, filePath, funcName, lineNum) {
     }
 
     if (candidates.length === 0) {
-        // Try absolute path
-        const absPath = path.isAbsolute(filePath) ? filePath : path.join(index.root, filePath);
-        if (fs.existsSync(absPath)) {
+        // A frame that matched no indexed file may still point at a real file
+        // inside the project the walker skipped (a build artifact, an ignored
+        // path). Resolve it and show it — but ONLY inside the project root.
+        // The frame path is caller-supplied and untrusted; without this gate
+        // `File "/etc/passwd"` or `../../secret` would exfiltrate arbitrary
+        // files through the tool surface (fix #285 — GHSA/issue #4).
+        const absPath = path.resolve(index.root, filePath);
+        if (isPathInsideRoot(index.root, absPath) && fs.existsSync(absPath)) {
             return {
                 path: absPath,
                 relativePath: path.relative(index.root, absPath),
@@ -160,6 +166,16 @@ function createStackFrame(index, filePath, lineNum, funcName, col, rawLine) {
     // Find the best matching file using improved algorithm
     const match = findBestMatchingFile(index, filePath, funcName, lineNum);
 
+    if (match && !isPathInsideRoot(index.root, match.path)) {
+        // Defense in depth: never read outside the project root even if a
+        // future matcher change returns such a path (fix #285). The frame is
+        // reported as located-but-unreadable rather than leaking content.
+        frame.matchedFile = match.relativePath;
+        frame.confidence = match.confidence;
+        frame.error = 'resolved outside project root; not read';
+        return frame;
+    }
+
     if (match) {
         const resolvedPath = match.path;
         frame.found = true;

package/mcp/server.js

@@ -133,17 +133,12 @@ function toolResult(text, command, maxChars, suffixNote, params = {}) {
         surface: 'mcp',
         params,
     });
-    const response = { content: [{ type: 'text', text: budget.text + suffix }] };
-    if (budget.truncated) {
-        response.structuredContent = {
-            truncated: true,
-            fullChars: budget.fullChars,
-            requestedLimit: budget.requestedLimit,
-            contractMetadata: budget.contractMetadata,
-            contractMetadataComplete: budget.contractMetadataComplete,
-        };
-    }
-    return response;
+    // The text block is the ONLY payload channel. Truncation facts live in the
+    // text itself (the OUTPUT TRUNCATED notice carries full size, limit, and
+    // narrowing hints; preserved contract lines follow). A structuredContent
+    // side-channel is rendered INSTEAD of content by MCP clients that prefer
+    // structured results, which discards the entire answer (fix #284).
+    return { content: [{ type: 'text', text: budget.text + suffix }] };
 }
 
 function toolError(message) {
@@ -324,7 +319,7 @@ server.registerTool(
             line: z.number().int().positive().optional().describe('Definition line pin. Resolves the symbol defined at this exact line (the middle component of a file:line:name handle). Disambiguates same-file same-name definitions.'),
             limit: z.number().int().positive().max(1000000).optional().describe('Max results to return (default: 500). Caps find, usages, search, deadcode, api, and repo files. Must be a positive integer.'),
             max_files: z.number().int().positive().max(10000000).optional().describe('Max files to index (default: 10000). Use for very large codebases. Must be a positive integer.'),
-            max_chars: z.number().int().positive().max(100000).optional().describe('Max output chars before truncation. Targeted commands default to 10K; broad commands default to 3K. Maximum: 100K. all=true lifts formatter caps but keeps the 100K transport ceiling.'),
+            max_chars: z.number().int().positive().max(100000).optional().describe('Max output chars before truncation. Broad sweep commands (repo, entrypoints, endpoints, deadcode, deps, check, audit_async) default to 3K; all other commands default to 10K. Maximum: 100K. all=true lifts formatter caps but keeps the 100K transport ceiling.'),
             // Structural search flags (search command)
             type: z.string().optional().describe('Symbol type filter for structural search: function, class, call, method, type, state, field, constant, macro. Triggers index-based search.'),
             param: z.string().optional().describe('Filter by parameter name or type (structural search). E.g. "Request", "ctx".'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "5.0.3",
+  "version": "5.0.5",
   "mcpName": "io.github.mleoca/ucn",
   "description": "Auditable AST code intelligence for AI agents: 18 task-oriented commands through one MCP tool, CLI, or agent skill. Supports JS/TS, Python, Go, Rust, Java, C, C++, C#, and HTML.",
   "main": "index.js",