{"slug": "give-your-local-ai-agent-a-read-only-file-manifest-not-your-home-directory", "title": "Give Your Local AI Agent a Read-Only File Manifest, Not Your Home Directory", "summary": "A tutorial published for Node.js 20 or newer shows developers how to give a local AI agent a read-only manifest of pre-approved file snapshots instead of access to an entire home directory, so the model can request entries only by ID such as file-2 and never by filesystem path. The manifest.mjs script rejects lexical '..' segments, checks every path component with lstat for symlinks, resolves the final path and verifies it stays below the project root, then stores each approved file's text with a SHA-256 hash and capture timestamp. The author cautions the checks are not atomic — a time-of-check-to-time-of-use race lets another process with write access swap a component between lstat or realpath and readFile — and that hostile, concurrently writable directories require OS-level isolation or no-follow directory-handle APIs, since portable Node.js path helpers alone provide no security boundary.", "body_md": "# Give Your Local AI Agent a Read-Only File Manifest, Not Your Home Directory\n\nAn agent that can read your entire home directory has more context than it needs and more access than you can easily review. A denylist of sensitive filenames helps, but it grows by exception: .env, .ssh, browser profiles, cloud credentials, and the next file you forgot existed. A smaller interface\n\nis easier to reason about: choose the files yourself, read them once, and hand the model an immutable manifest of text snapshots. The model can request only entries in that manifest. It cannot ask your tool to open a new path. The Node.js process still runs with your operating-system permissions.\n\nThis design does not sandbox it: another tool or a bug could still give it access to other files. For one task, define a short list such as README.md, src/config.ts, and src/routes.ts. At setup time, the host reads each approved file and stores its text and metadata in memory. Later model requests use an ID like file-2, never a path.\n\nThat gives the task a stable view: if a file changes after snapshotting, the model continues to see the captured text. Each task gets a known set of captured text. Include a content hash and capture timestamp so you can identify the bytes used in that task, even after the source file changes. Prerequisite: Node.js 20 or newer and a directory containing the files you intend to expose.\n\nSave this as manifest.mjs; pass the project root as the first argument. Edit approved before running it. import fs from 'node:fs/promises'; import path from 'node:path'; import { createHash } from 'node:crypto'; const root = await fs.realpath(process.argv[2] ?? '.'); const approved = ['README.md', 'src/config.ts']; const manifest = []; for (const [index, relative] of approved.entries()) { if (path.isAbsolute(relative) || relative.split(/[\\\\/]/).includes('..')) { throw new Error(`Rejected path: ${relative}`); } const parts = relative.split(/[\\\\/]/).filter(Boolean); let cursor = root; for (const part of parts) { cursor = path.join(cursor, part); const info = await fs.lstat(cursor); if (info.isSymbolicLink()) throw new Error(`Symlink rejected: ${relative}`); } const resolved = await fs.realpath(cursor); const rel = path.relative(root, resolved); if (rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) { throw new Error(` Escapes root: ${relative}`); } const info = await fs.stat(resolved); if (!info.isFile()) throw new Error(`Not a regular file: ${relative}`); const bytes = await fs.readFile(resolved); manifest.push(Object.freeze({ id: `file-${index + 1}`, path: relative, sha256: createHash('sha256').update(bytes).digest('hex'), text: bytes.toString('utf8'), })); } const snapshot = Object.freeze(manifest); console.log(JSON.stringify(snapshot, null, 2)); Run node manifest.mjs /path/to/project.\n\nThe JSON is the complete handoff for this exercise; in an agent host, keep snapshot in memory and expose a lookup by id. Validate the ID against the manifest and return only its stored text. Never turn a model-supplied string into a filesystem path. The code rejects lexical .., checks every component with lstat, resolves the final path, and verifies it remains below the root.\n\nThese checks help with an ordinary, stable directory tree. They are not atomic. Between lstat or realpath and readFile, another process with write access could replace a component or file. That is a time-of-check-to-time-of-use (TOCTOU) race.\n\nAn attacker able to mutate the tree at the same time may exploit it. For a hostile, concurrently writable directory, use OS-level isolation or platform APIs that open files relative to a trusted directory handle with no-follow semantics. Portable Node.js path helpers alone do not provide that security boundary. A read-only container mount can reduce what the process may change, but it is a separate control to configure and verify.\n\nUTF-8 decoding can replace invalid byte sequences, and an approved file can contain prompt injection. Reject binary content and treat file text as untrusted data in the prompt. A content hash identifies the bytes; it says nothing about whether the text is safe to follow. Cap the number of entries, reject files above a byte ceiling before reading them, and keep a total snapshot-size budget.\n\nA manifest of hundreds of approved files can quietly become a whole-repository dump. If a file is too large, split it deliberately or leave it out and tell the agent that it was omitted. Fail visibly on unreadable or invalid text so a partial snapshot cannot pass for a complete one. Keep the manifest with the task record.\n\nWhen a summary refers to an outdated setting in src/config.ts, its snapshot ID and hash let you check exactly which version the model read. References: Node.js file system APIs document lstat, realpath, and file reads; Node.js path APIs document path resolution and platform-specific behavior.\n\n## Key Takeaways\n\n- •The model can request only entries in that manifest.\n- •This story was reported by **Dev.to** , covering developments in the**dev** space.\n- •AI advancements continue to reshape industries — read the full article on Dev.to for complete coverage.\n\n📖 Continue reading the full article:\n\n[Read Full Article on Dev.to →](https://dev.to/pavelespitia/give-your-local-ai-agent-a-read-only-file-manifest-not-your-home-directory-40o0)", "url": "https://wpnews.pro/news/give-your-local-ai-agent-a-read-only-file-manifest-not-your-home-directory", "canonical_source": "https://ainexusdaily.vercel.app/article/2026-11-17-give-your-local-ai-agent-a-read-only-file-manifest-not-your-home-directory", "published_at": "2026-11-17 15:17:35+00:00", "updated_at": "2026-11-17 19:47:36.400779+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "ai-safety", "developer-tools"], "entities": ["Node.js", "manifest.mjs", "lstat", "realpath", "SHA-256"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/give-your-local-ai-agent-a-read-only-file-manifest-not-your-home-directory", "markdown": "https://wpnews.pro/news/give-your-local-ai-agent-a-read-only-file-manifest-not-your-home-directory.md", "text": "https://wpnews.pro/news/give-your-local-ai-agent-a-read-only-file-manifest-not-your-home-directory.txt", "jsonld": "https://wpnews.pro/news/give-your-local-ai-agent-a-read-only-file-manifest-not-your-home-directory.jsonld"}}