@vincemakes/kiso-tools-node 0.39.1 → 0.40.0

package/dist/index.d.ts

@@ -127,6 +127,15 @@ export interface WorkspaceToolsOptions {
      * read.
      */
     readonly excludeRoots?: readonly string[];
+    /**
+     * ACCESS, where excludeRoots is discovery: files kiso NEVER serves to a
+     * model, however they are named (protected.ts) — read_file, edit_file
+     * and write_file refuse them, search_text never returns a line from
+     * them. The CLI passes its own credential store (and a user's own
+     * `protectedPaths`). A protected file's name-suffixed siblings (the
+     * writer's temp file and lock) share the protection.
+     */
+    readonly protectedFiles?: readonly string[];
     readonly limits?: {
         /** search_text: skip a file larger than this (default 1 MiB). */
         readonly searchMaxFileBytes?: number;
@@ -174,6 +183,11 @@ export declare function editFileTool(opts: WorkspaceToolsOptions): Tool<{
     expectedRevision?: string;
 }>;
 export { SHELL_STRIP_EXACT, strippedShellEnv } from "./secret-env.js";
+export { PROTECTED_REFUSAL, diskPath, isProtectedPath, protectedIdentity, protectedRefusalText, readUnlessProtected, type ProtectedIdentity } from "./protected.js";
+/** The search corpus's credential rule, by name — exported so the CLI's
+ *  read-only shell allow holds a shell read to the same definition rather
+ *  than a copy of it. */
+export { isCredentialName } from "./corpus.js";
 export declare function shellTool(opts: WorkspaceToolsOptions): Tool<{
     command: string;
     timeoutMs?: number;

package/dist/index.js

@@ -19,7 +19,7 @@
  */
 import { execFile, execFileSync, spawn } from "node:child_process";
 import { promisify } from "node:util";
-import { appendFileSync, chmodSync, existsSync, linkSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { appendFileSync, chmodSync, existsSync, linkSync, mkdirSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { Worker } from "node:worker_threads";
 import { fileURLToPath } from "node:url";
 import { createHash } from "node:crypto";
@@ -29,6 +29,7 @@ import { defineTool } from "@vincemakes/kiso-core";
 // WR-1/WR-1A — the revision-guard primitives (unit-tested in wr1a-coda):
 import { strippedShellEnv } from "./secret-env.js";
 import { contentRevision, normalizeRevision, postEffectEscape, precondition, publishNewFile, revalidateBeforeRename } from "./wr1.js";
+import { isProtectedPath, protectedIdentity, protectedRefusalText, readUnlessProtected } from "./protected.js";
 import { CORPUS_MAX_DEPTH, globToRegExp, walkCorpus } from "./corpus.js";
 import { describeSearchMiss } from "./search-miss.js";
 /**
@@ -353,6 +354,11 @@ export function readFileTool(opts) {
             const maxReadBytes = opts.limits?.readMaxFileBytes ?? READ_MAX_FILE_BYTES;
             try {
                 const full = resolveWithinRoot(opts.workspaceRoot, path);
+                // the credential store is never served (protected.ts) — checked
+                // by the disk's own resolution and by inode, before any read
+                const guard = protectedIdentity(opts.protectedFiles);
+                if (isProtectedPath(full, guard))
+                    return precondition(protectedRefusalText("read_file", path));
                 const denied = await inodeReadPolicy(opts.workspaceRoot, full);
                 if (denied !== null)
                     return escapeResult(denied);
@@ -388,7 +394,10 @@ export function readFileTool(opts) {
                 // 64 MiB read — about 100 ms, measured — against the 180+
                 // seconds this finding is named for. Determinism is worth
                 // more than that hitch.
-                const bytes = readFileSync(full);
+                // one descriptor, compared by inode before a byte is read
+                const bytes = readUnlessProtected(full, guard);
+                if (bytes === null)
+                    return precondition(protectedRefusalText("read_file", path));
                 const content = bytes.toString("utf8");
                 // The lines the file DISPLAYS: a trailing newline's empty split
                 // element is not a line. Line k = split[k-1], 1-based.
@@ -737,7 +746,7 @@ export function searchTextTool(opts) {
             // root uses: `full` is walked from a realpath'd root, and making
             // a path relative between a resolved and an unresolved base
             // yields `../..` the moment a symlink sits between them.
-            { token: 0, root: searchRootReal, workspaceRoot: realOrSelf(opts.workspaceRoot), single, pattern, flags, excluded, maxFileBytes, maxFiles, deadline, maxMatches: MAX_SEARCH_MATCHES, sniffBytes: BINARY_SNIFF_BYTES }, deadline, ctx.signal);
+            { token: 0, root: searchRootReal, workspaceRoot: realOrSelf(opts.workspaceRoot), single, pattern, flags, excluded, protectedIdentity: protectedIdentity(opts.protectedFiles), maxFileBytes, maxFiles, deadline, maxMatches: MAX_SEARCH_MATCHES, sniffBytes: BINARY_SNIFF_BYTES }, deadline, ctx.signal);
             if (outcome.kind === "aborted")
                 return { content: "search_text aborted", isError: true, errorKind: "fatal" };
             if (outcome.kind === "error")
@@ -807,6 +816,9 @@ export function writeFileTool(opts) {
                     return escapeResult(err.message);
                 throw err;
             }
+            const guard = protectedIdentity(opts.protectedFiles);
+            if (isProtectedPath(full, guard))
+                return precondition(protectedRefusalText("write_file", path));
             // WR-1 — the observed-revision stale-write guard. The decision
             // lattice runs BEFORE any bytes move; every refusal is a
             // precondition with one actionable sentence. What it proves:
@@ -843,7 +855,10 @@ export function writeFileTool(opts) {
                 if (wSize > maxReadBytes) {
                     return precondition(`write_file: ${path} is ${mib(wSize)} — too large to read (ceiling ${mib(maxReadBytes)}); use shell with sed/head to take a range`);
                 }
-                const current = contentRevision(readFileSync(full));
+                const held = readUnlessProtected(full, guard);
+                if (held === null)
+                    return precondition(protectedRefusalText("write_file", path));
+                const current = contentRevision(held);
                 if (current !== expectedRevision) {
                     return precondition(`write_file: ${path} changed since ${expectedRevision} — read it again and cite its [rev:…] line, then re-apply the change`);
                 }
@@ -1022,6 +1037,9 @@ export function editFileTool(opts) {
                     return escapeResult(err.message);
                 throw err;
             }
+            const guard = protectedIdentity(opts.protectedFiles);
+            if (isProtectedPath(full, guard))
+                return precondition(protectedRefusalText("edit_file", path));
             // WR-1: edits always target an existing file — the revision is
             // not optional here, and the refusal teaches the protocol.
             if (expectedRevision === undefined) {
@@ -1054,7 +1072,9 @@ export function editFileTool(opts) {
                 if (eSize > maxReadBytes) {
                     return precondition(`edit_file: ${path} is ${mib(eSize)} — too large to read (ceiling ${mib(maxReadBytes)}); use shell with sed/head to take a range`);
                 }
-                const bytes = readFileSync(full);
+                const bytes = readUnlessProtected(full, guard);
+                if (bytes === null)
+                    return precondition(protectedRefusalText("edit_file", path));
                 const current = contentRevision(bytes);
                 if (current !== expectedRevision) {
                     return precondition(`edit_file: ${path} changed since ${expectedRevision} — read it again and cite its [rev:…] line, then re-apply the change`);
@@ -1145,6 +1165,11 @@ export function editFileTool(opts) {
 // with a hand-kept copy over there; the copy never learned the
 // declared names, which is how MCP children kept leaking.
 export { SHELL_STRIP_EXACT, strippedShellEnv } from "./secret-env.js";
+export { PROTECTED_REFUSAL, diskPath, isProtectedPath, protectedIdentity, protectedRefusalText, readUnlessProtected } from "./protected.js";
+/** The search corpus's credential rule, by name — exported so the CLI's
+ *  read-only shell allow holds a shell read to the same definition rather
+ *  than a copy of it. */
+export { isCredentialName } from "./corpus.js";
 export function shellTool(opts) {
     return defineTool({
         name: "shell",

package/dist/protected.d.ts

@@ -0,0 +1,50 @@
+/**
+ * kiso never serves its own credential store to a model.
+ *
+ * The 2026-09-14 incident: a session with its cwd at home called `read_file
+ * .kiso/auth.json` in default mode. The read was auto-allowed, and the
+ * store's API key and OAuth tokens went to the provider as conversation
+ * context. `excludeRoots` could not have stopped it — it governs what a walk
+ * DISCOVERS, not what a named path may ACCESS (its own header says so).
+ *
+ * This is the access rule, for the files the host names (`protectedFiles`):
+ * the credential store and its name-suffixed siblings (the writer's temp
+ * file and lock), plus whatever a user lists in their own config. A path is
+ * protected when the DISK resolves it to one of them — `realpath.native` of
+ * the longest existing prefix, so a symlink, a `..` through a symlink and a
+ * case variant all reach the same file — or when it is the same INODE (a
+ * hard link under another name).
+ *
+ * This module imports nothing beyond node itself, as secret-env.ts does:
+ * the same rule is read by the search worker and by the CLI's shell check.
+ */
+export declare const PROTECTED_REFUSAL = "kiso never serves its own credential store to a model";
+/** The path as the disk resolves it: realpath.native of the longest
+ *  existing prefix, then the tail that does not exist yet. */
+export declare function diskPath(p: string): string;
+export interface ProtectedIdentity {
+    /** the protected files as the disk spells them */
+    readonly paths: readonly string[];
+    /** `dev:ino` of each protected file that exists — a hard link is the same file */
+    readonly inodes: readonly string[];
+}
+/** Resolve the protected list once; the per-path checks compare against it. */
+export declare function protectedIdentity(files?: readonly string[]): ProtectedIdentity;
+/** Whether a disk-resolved path is a protected file or one of its
+ *  name-suffixed siblings (`auth.json.tmp-<pid>`, `auth.json.lock/…`). */
+export declare function isProtectedDiskPath(d: string, id: ProtectedIdentity): boolean;
+/** The whole question for one path: by where the disk resolves it, and by
+ *  inode when it exists. */
+export declare function isProtectedPath(p: string, id: ProtectedIdentity): boolean;
+/**
+ * Read a file through ONE descriptor, and refuse it when that descriptor
+ * is a protected file. The path check before it judges a NAME, and a name
+ * can be swapped for a symlink between the check and the read; the
+ * descriptor is the file actually opened. Returns null when it is
+ * protected. (The sandbox is the guarantee; this closes the file tools'
+ * own check-then-use window.)
+ */
+export declare function readUnlessProtected(full: string, id: ProtectedIdentity): Buffer | null;
+/** The refusal a tool returns — a precondition (refused, never attempted),
+ *  stated as permanent so a model does not retry it under another name. */
+export declare function protectedRefusalText(tool: string, path: string): string;

package/dist/protected.js

@@ -0,0 +1,106 @@
+/**
+ * kiso never serves its own credential store to a model.
+ *
+ * The 2026-09-14 incident: a session with its cwd at home called `read_file
+ * .kiso/auth.json` in default mode. The read was auto-allowed, and the
+ * store's API key and OAuth tokens went to the provider as conversation
+ * context. `excludeRoots` could not have stopped it — it governs what a walk
+ * DISCOVERS, not what a named path may ACCESS (its own header says so).
+ *
+ * This is the access rule, for the files the host names (`protectedFiles`):
+ * the credential store and its name-suffixed siblings (the writer's temp
+ * file and lock), plus whatever a user lists in their own config. A path is
+ * protected when the DISK resolves it to one of them — `realpath.native` of
+ * the longest existing prefix, so a symlink, a `..` through a symlink and a
+ * case variant all reach the same file — or when it is the same INODE (a
+ * hard link under another name).
+ *
+ * This module imports nothing beyond node itself, as secret-env.ts does:
+ * the same rule is read by the search worker and by the CLI's shell check.
+ */
+import { basename, dirname, join } from "node:path";
+import { closeSync, fstatSync, openSync, readFileSync, realpathSync, statSync } from "node:fs";
+export const PROTECTED_REFUSAL = "kiso never serves its own credential store to a model";
+/** The path as the disk resolves it: realpath.native of the longest
+ *  existing prefix, then the tail that does not exist yet. */
+export function diskPath(p) {
+    let head = p;
+    const tail = [];
+    for (;;) {
+        try {
+            const real = realpathSync.native(head);
+            return tail.length > 0 ? join(real, ...tail) : real;
+        }
+        catch {
+            const parent = dirname(head);
+            if (parent === head)
+                return p;
+            tail.unshift(basename(head));
+            head = parent;
+        }
+    }
+}
+/** Resolve the protected list once; the per-path checks compare against it. */
+export function protectedIdentity(files = []) {
+    const paths = files.map(diskPath);
+    const inodes = [];
+    for (const p of paths) {
+        try {
+            const st = statSync(p);
+            if (st.isFile())
+                inodes.push(`${st.dev}:${st.ino}`);
+        }
+        catch {
+            // not there yet — the path rule still holds
+        }
+    }
+    return { paths, inodes };
+}
+/** Whether a disk-resolved path is a protected file or one of its
+ *  name-suffixed siblings (`auth.json.tmp-<pid>`, `auth.json.lock/…`). */
+export function isProtectedDiskPath(d, id) {
+    return id.paths.some((pf) => d === pf || d.startsWith(`${pf}.`));
+}
+/** The whole question for one path: by where the disk resolves it, and by
+ *  inode when it exists. */
+export function isProtectedPath(p, id) {
+    if (id.paths.length === 0)
+        return false;
+    const d = diskPath(p);
+    if (isProtectedDiskPath(d, id))
+        return true;
+    if (id.inodes.length === 0)
+        return false;
+    try {
+        const st = statSync(d);
+        return st.isFile() && id.inodes.includes(`${st.dev}:${st.ino}`);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read a file through ONE descriptor, and refuse it when that descriptor
+ * is a protected file. The path check before it judges a NAME, and a name
+ * can be swapped for a symlink between the check and the read; the
+ * descriptor is the file actually opened. Returns null when it is
+ * protected. (The sandbox is the guarantee; this closes the file tools'
+ * own check-then-use window.)
+ */
+export function readUnlessProtected(full, id) {
+    const fd = openSync(full, "r");
+    try {
+        const st = fstatSync(fd);
+        if (id.inodes.includes(`${st.dev}:${st.ino}`))
+            return null;
+        return readFileSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** The refusal a tool returns — a precondition (refused, never attempted),
+ *  stated as permanent so a model does not retry it under another name. */
+export function protectedRefusalText(tool, path) {
+    return `${tool}: ${path} — ${PROTECTED_REFUSAL}. This is permanent: do not retry it, under this path or another.`;
+}

package/dist/search-worker.d.ts

@@ -15,6 +15,7 @@
  * one `SearchReply` and exits. A call token rides both ways so a late
  * message from a superseded worker is ignored.
  */
+import { type ProtectedIdentity } from "./protected.js";
 export interface SearchRequest {
     readonly token: number;
     readonly root: string;
@@ -29,6 +30,10 @@ export interface SearchRequest {
     readonly pattern: string;
     readonly flags: string;
     readonly excluded: readonly string[];
+    /** files never searched: kiso's credential store (protected.ts) — skipped
+     *  without a hit, matched by inode and, for a protected name, by the
+     *  disk's own resolution */
+    readonly protectedIdentity?: ProtectedIdentity;
     readonly maxFileBytes: number;
     readonly maxFiles: number;
     /** the call's wall-clock deadline (epoch ms): the walk stops COOPERATIVELY

package/dist/search-worker.js

@@ -19,6 +19,19 @@ import { open, readdir } from "node:fs/promises";
 import { basename, join, relative } from "node:path";
 import { corpusSkips, layersEntering, readLayer } from "./corpus.js";
 import { isMainThread, parentPort } from "node:worker_threads";
+import { diskPath, isProtectedDiskPath } from "./protected.js";
+/** A scanned file is protected by inode (the store itself, under any name
+ *  or case), or — for a name that starts like a protected one, the writer's
+ *  temp file and lock — by the disk's own resolution. The resolution runs
+ *  only for such a name, so an ordinary search pays nothing for it. */
+function isProtectedScan(full, st, id) {
+    if (id.inodes.includes(`${st.dev}:${st.ino}`))
+        return true;
+    const name = basename(full).toLowerCase();
+    if (!id.paths.some((p) => name.startsWith(basename(p).toLowerCase())))
+        return false;
+    return isProtectedDiskPath(diskPath(full), id);
+}
 /** ACI-5 — the excerpt WINDOWS THE MATCH instead of taking the line's head.
  *
  *  `line.trim().slice(0, 160)` answers "what does this line start with",
@@ -77,6 +90,8 @@ export async function runSearch(req) {
             let text;
             try {
                 const st = await fh.stat();
+                if (req.protectedIdentity !== undefined && isProtectedScan(full, st, req.protectedIdentity))
+                    return;
                 if (st.nlink > 1) {
                     multiLink += 1;
                     return;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-tools-node",
-	"version": "0.39.1",
+	"version": "0.40.0",
 	"description": "kiso coding tools for Node hosts \u2014 read file, list directory, search text, write/edit file, shell command.",
 	"type": "module",
 	"license": "MIT",
@@ -25,7 +25,7 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@vincemakes/kiso-core": "0.39.1",
+		"@vincemakes/kiso-core": "0.40.0",
 		"ignore": "^7.0.9"
 	},
 	"devDependencies": {