@vincemakes/kiso-code 0.39.2 → 0.40.0

package/dist/protected-shell.js

@@ -0,0 +1,406 @@
+/**
+ * kiso never serves its own credential store to a model — the SHELL half.
+ * The file tools refuse in tools-node, whose protected.ts holds the rule
+ * (what is protected, and how a path is matched to it).
+ *
+ * A chain member at the head, beside the floor, in EVERY mode including
+ * bypass: any word of any command in the line that resolves to a protected
+ * file DENIES. The `!` gesture runs the same check before it runs a line,
+ * because `!cmd` sends that line's output to the model.
+ *
+ * THIS IS A READING, NOT A GUARANTEE. It reads the line as the floor does:
+ * the loose reader, `cd` followed, subshells and `sh -c`/`eval` inner lines
+ * read, `~`, `$HOME` and `$KISO_HOME` expanded, `--opt=path` split, and the
+ * words the floor drops kept — a redirection's target, an assignment's
+ * value. A word is resolved by the KERNEL, as the command would open it:
+ * one `stat` of the directory it runs in joined to the word, compared by
+ * inode — so a symlink, a `..` through one, a case variant and a hard link
+ * under another name all reach the same file. A protected path that does
+ * not exist yet has no inode: until the file is created it is matched by
+ * its spelling, resolved against the directory the word runs in (so is a
+ * name-suffixed sibling, the writer's temp file). A glob is matched against
+ * the protected files themselves, and only when its literal directory
+ * holds one. A word it cannot resolve (a variable, a substitution, another
+ * user's `~name`), or a relative word read after a `cd` it could not
+ * follow, denies when it still contains a protected file's name. So does a
+ * command that names a directory holding a protected file AND that file's
+ * name, in two words (`find ~/.kiso -name auth.json`). A line it cannot
+ * read to the end — nested too deep, or past its budget of disk reads —
+ * denies.
+ *
+ * Its blind spots are stated, not hidden: a path assembled at run time
+ * (`base64 -d`, string slicing), a copy under another name made in an
+ * earlier call, a script that reads the file, a recursive walk over a
+ * directory that holds it without naming it (`grep -r x ~`). The
+ * guarantee is the sandbox, which stays post-launch.
+ */
+import { readdirSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { protectedIdentity, PROTECTED_REFUSAL } from "@vincemakes/kiso-tools-node";
+import { innerLines, unwrap } from "./floor.js";
+import { parseShellLooseChecked } from "./shell-words.js";
+const ABSTAIN = { action: "abstain" };
+/** How deep `sh -c`/`eval` lines are followed, and how many are read. */
+const MAX_INNER_DEPTH = 16;
+const MAX_INNER_LINES = 256;
+/** Past this many candidate directories the walk stops tracking them one
+ *  by one and falls back to the name check (`cd a; cd b; …` doubles). */
+const MAX_CWDS = 32;
+/** A directory spelled longer than any system opens is not a directory
+ *  a command can run in. */
+const MAX_PATH = 4096;
+/** Path readings per line — one word from one candidate directory: at
+ *  most one `stat` each. A line a person or a model writes needs a few
+ *  hundred; 8,000 bounds the hostile ones to ~15 ms on a laptop, and under
+ *  100 ms on a loaded 2-core CI runner, where 20,000 measured 139 ms. A
+ *  line that needs more is not read to the end, and a line not read to
+ *  the end denies. */
+const MAX_READINGS = 8_000;
+/** Directory changes per line the check follows. Each one respells every
+ *  candidate directory, so an unbounded run of `cd a;` is quadratic; a
+ *  line a person or a model writes changes directory a handful of times. */
+const MAX_CDS = 64;
+export const NESTED_TOO_DEEP = "the line is nested deeper than the check reads";
+export const TOO_LONG = "the line names more paths than the check reads";
+export const TOO_MANY_CDS = "the line changes directory more times than the check follows";
+class Unread extends Error {
+}
+const child = (s) => ({ cwds: s.cwds, lossy: s.lossy, pending: s.pending });
+function cap(s, list) {
+    const fit = list.filter((d) => d.length <= MAX_PATH);
+    if (fit.length < list.length)
+        s.lossy = true;
+    const unique = [...new Set(fit)];
+    if (unique.length <= MAX_CWDS)
+        return unique;
+    s.lossy = true;
+    return unique.slice(0, MAX_CWDS);
+}
+const inode = (st) => `${st.dev}:${st.ino}`;
+/** A shell glob as a whole-path test. `*` and `?` are taken to match a
+ *  leading dot too — looser than the shell's default, on purpose: a
+ *  line can turn `dotglob` on. */
+function globRegex(glob) {
+    let re = "";
+    for (let i = 0; i < glob.length; i += 1) {
+        const c = glob[i];
+        if (c === "*")
+            re += "[^/]*";
+        else if (c === "?")
+            re += "[^/]";
+        else if (c === "[") {
+            const close = glob.indexOf("]", i + 2);
+            if (close < 0)
+                re += "\\[";
+            else {
+                const body = glob.slice(i + 1, close).replace(/^!/, "^").replace(/\\/g, "\\\\");
+                re += `[${body}]`;
+                i = close;
+            }
+        }
+        else
+            re += c.replace(/[.+^${}()|\\/]/g, "\\$&");
+    }
+    // case-folded: on a disk that folds case, `.KISO/*` is the same directory
+    return new RegExp(`^${re}$`, "i");
+}
+function probeFor(id) {
+    const files = new Set();
+    const dirs = new Set();
+    const targets = [];
+    for (const pf of id.paths) {
+        const dir = dirname(pf);
+        const base = basename(pf);
+        targets.push(pf);
+        try {
+            for (const name of readdirSync(dir))
+                if (name.startsWith(`${base}.`))
+                    targets.push(`${dir}/${name}`);
+        }
+        catch {
+            // no directory yet — nothing in it to serve
+        }
+        for (let d = dir;; d = dirname(d)) {
+            const st = statSync(d, { throwIfNoEntry: false });
+            if (st?.isDirectory() === true)
+                dirs.add(inode(st));
+            if (dirname(d) === d)
+                break;
+        }
+    }
+    for (const t of targets) {
+        const st = statSync(t, { throwIfNoEntry: false });
+        if (st?.isFile() === true)
+            files.add(inode(st));
+    }
+    return { files, dirs, targets };
+}
+/** The pure check: does any word of the line name a protected file? */
+export function protectedShellCheck(line, workspaceRoot, id, env) {
+    if (id.paths.length === 0)
+        return { hit: false };
+    const probe = probeFor(id);
+    const names = id.paths.map((p) => basename(p).toLowerCase());
+    const paths = id.paths.map((p) => p.toLowerCase());
+    const namesProtected = (t) => {
+        const low = t.toLowerCase();
+        return names.some((n) => low.includes(n));
+    };
+    let readings = 0;
+    const charge = () => {
+        if (++readings > MAX_READINGS)
+            throw new Unread(TOO_LONG);
+    };
+    const seenStat = new Map();
+    /** The kernel's answer for a path, as a command would open it: `..`
+     *  after a symlink is the symlink target's parent, because the string
+     *  is never normalized before the kernel reads it. */
+    const statAt = (p) => {
+        if (seenStat.has(p))
+            return seenStat.get(p);
+        let st;
+        try {
+            st = statSync(p, { throwIfNoEntry: false });
+        }
+        catch {
+            st = undefined; // too long, not a directory, no permission: nothing it opens
+        }
+        seenStat.set(p, st);
+        return st;
+    };
+    const at = (cwd, t) => (t.startsWith("/") ? t : `${cwd}/${t}`);
+    const regexes = new Map();
+    const realOf = new Map();
+    /** Whether a word's last component is a protected file's name, or one
+     *  of its name-suffixed siblings'. */
+    const named = (t) => {
+        const leaf = t.slice(t.lastIndexOf("/") + 1).toLowerCase();
+        return names.some((n) => leaf === n || leaf.startsWith(`${n}.`));
+    };
+    const expand = (t, tilde) => {
+        let out = tilde && (t === "~" || t.startsWith("~/")) ? env.home + t.slice(1) : t;
+        out = out.replace(/\$\{HOME\}|\$HOME(?![A-Za-z0-9_])/g, env.home);
+        return out.replace(/\$\{KISO_HOME\}|\$KISO_HOME(?![A-Za-z0-9_])/g, env.kisoHome);
+    };
+    /** One literal-or-glob path text, read from each candidate directory. */
+    const pathHits = (t, s) => {
+        if (t === "")
+            return false;
+        if (/[$`]/.test(t))
+            return namesProtected(t);
+        if (s.lossy && !t.startsWith("/") && namesProtected(t))
+            return true;
+        const glob = /[*?[]/.test(t);
+        for (const cwd of s.cwds) {
+            charge();
+            if (!glob) {
+                // by spelling first, which needs no disk (a sibling that does
+                // not exist yet) — only when the last component could be the
+                // file's name — then by inode
+                if (named(t)) {
+                    const spelled = resolve(cwd, t).toLowerCase();
+                    if (paths.some((pf) => spelled === pf || spelled.startsWith(`${pf}.`)))
+                        return true;
+                }
+                const st = statAt(at(cwd, t));
+                if (st?.isFile() === true && probe.files.has(inode(st)))
+                    return true;
+                continue;
+            }
+            const g = t.search(/[*?[]/);
+            const cut = t.lastIndexOf("/", g);
+            const rest = t.slice(cut + 1);
+            // only where the literal directory HOLDS a protected file — a glob
+            // anywhere else is never expanded, and the disk is never walked
+            const dirText = cut < 0 ? cwd : at(cwd, t.slice(0, cut + 1));
+            const dst = statAt(dirText);
+            if (dst?.isDirectory() !== true || !probe.dirs.has(inode(dst)))
+                continue;
+            // a `..` after the glob walks out of what the pattern can say
+            if (/(^|\/)\.\.(\/|$)/.test(rest)) {
+                if (namesProtected(t))
+                    return true;
+                continue;
+            }
+            let real = realOf.get(dirText);
+            if (real === undefined) {
+                try {
+                    real = realpathSync.native(dirText);
+                }
+                catch {
+                    continue;
+                }
+                realOf.set(dirText, real);
+            }
+            const pattern = `${real.endsWith("/") ? real : `${real}/`}${rest}`;
+            let re = regexes.get(pattern);
+            if (re === undefined)
+                regexes.set(pattern, (re = globRegex(pattern)));
+            if (probe.targets.some((p) => re.test(p)))
+                return true;
+        }
+        return false;
+    };
+    const wordHits = (w, s) => {
+        // `~name/…` is another account's home — or this one's, by name
+        if (w.tilde && /^~[^/]/.test(w.text))
+            return namesProtected(w.text);
+        const t = expand(w.text, w.tilde);
+        if (pathHits(t, s))
+            return true;
+        // `--config=path`, `if=path`, `X=path`: the value is a path too
+        const eq = t.indexOf("=");
+        return eq > 0 && pathHits(expand(t.slice(eq + 1), t[eq + 1] === "~"), s);
+    };
+    /** A directory holding a protected file — the file's own, or any
+     *  directory above it — by inode. */
+    const holds = (w, s) => {
+        const t = expand(w.text, w.tilde);
+        if (t === "" || /[$`*?[]/.test(t) || (w.tilde && /^~[^/]/.test(w.text)))
+            return false;
+        return s.cwds.some((cwd) => {
+            charge();
+            const st = statAt(at(cwd, t));
+            return st?.isDirectory() === true && probe.dirs.has(inode(st));
+        });
+    };
+    /** One command naming a directory that holds a protected file AND that
+     *  file's name, in two words: `find ~/.kiso -name auth.json`. */
+    const dirAndName = (words, s) => {
+        const named = words.find((w) => namesProtected(w.text));
+        return named !== undefined && words.some((w) => w !== named && holds(w, s)) ? named.text : null;
+    };
+    const seen = new Set();
+    let cds = 0;
+    // a nest past what the check follows is thrown, not returned: it ends
+    // the whole read, and must never read as a word
+    const walk = (nodes, s, depth) => {
+        for (const node of nodes) {
+            // after `cd x`: `&&` runs in x, `||` where it was, `;` in either
+            if (s.pending !== null) {
+                s.cwds = cap(s, node.joinedBy === "&&" ? s.pending : node.joinedBy === "||" ? s.cwds : [...s.pending, ...s.cwds]);
+                if (node.joinedBy !== "&&")
+                    s.pending = null;
+            }
+            if (node.kind === "group") {
+                // a subshell: its cd does not move the shell around it
+                const hit = walk(node.items, child(s), depth);
+                if (hit !== null)
+                    return hit;
+                continue;
+            }
+            // every word the command names, its own name included, and the
+            // words the floor drops (`< file`, `2> file`, `X=file`)
+            const words = [...node.argv, ...(node.dropped ?? [])];
+            for (const w of words)
+                if (wordHits(w, s))
+                    return w.text;
+            const pair = dirAndName(words, s);
+            if (pair !== null)
+                return pair;
+            const argv = unwrap(node.argv);
+            if (argv.length === 0)
+                continue;
+            const inner = innerLines(argv, env.home);
+            if (inner !== null) {
+                if (depth >= MAX_INNER_DEPTH)
+                    throw new Unread(NESTED_TOO_DEEP);
+                for (const l of inner.lines) {
+                    if (seen.has(l))
+                        continue;
+                    if (seen.size >= MAX_INNER_LINES)
+                        throw new Unread(NESTED_TOO_DEEP);
+                    seen.add(l);
+                    const read = parseShellLooseChecked(l, { keepDropped: true });
+                    if (read.truncated)
+                        throw new Unread(NESTED_TOO_DEEP);
+                    // `sh -c` is a child shell; eval runs here, and its cd moves this one
+                    const hit = walk(read.nodes, inner.subshell ? child(s) : s, depth + 1);
+                    if (hit !== null)
+                        return hit;
+                }
+                continue;
+            }
+            const name = basename(argv[0].text);
+            if (name === "cd" || name === "pushd" || name === "popd") {
+                if (++cds > MAX_CDS)
+                    throw new Unread(TOO_MANY_CDS);
+                const to = argv.slice(1).find((a) => !["--", "-P", "-L", "-e", "-@"].includes(a.text));
+                if (name === "popd" || to?.text === "-") {
+                    // back to somewhere the check does not track
+                    s.lossy = true;
+                    s.pending = cap(s, [...s.cwds, env.home, workspaceRoot]);
+                }
+                else if (to === undefined)
+                    s.pending = [env.home];
+                else {
+                    const t = expand(to.text, to.tilde);
+                    if (/[$`*?[]/.test(t) || (to.tilde && /^~[^/]/.test(to.text))) {
+                        s.lossy = true;
+                        s.pending = cap(s, [env.home, ...s.cwds]);
+                    }
+                    else
+                        s.pending = cap(s, s.cwds.map((c) => at(c, t)));
+                }
+            }
+        }
+        return null;
+    };
+    const top = parseShellLooseChecked(line, { keepDropped: true });
+    if (top.truncated)
+        return { hit: true, why: NESTED_TOO_DEEP, unread: true };
+    try {
+        const hit = walk(top.nodes, { cwds: [workspaceRoot], lossy: false, pending: null }, 0);
+        return hit === null ? { hit: false } : { hit: true, why: hit, unread: false };
+    }
+    catch (err) {
+        if (err instanceof Unread)
+            return { hit: true, why: err.message, unread: true };
+        throw err;
+    }
+}
+/** The refusal the MODEL reads. Permanent, as the file tools say it, so
+ *  it does not retry under another spelling. */
+export function protectedShellReason(v) {
+    if (v.unread)
+        return `${PROTECTED_REFUSAL}: ${v.why}, so kiso does not run it, in any mode.`;
+    return `${PROTECTED_REFUSAL}: ${v.why} names a protected file. This is permanent, in every mode: do not retry it, under this path or another.`;
+}
+/** The refusal the PERSON reads, for their own `!` line: what to do
+ *  instead. */
+export function protectedBangReason(v) {
+    return `not run — ${v.unread ? v.why : `${v.why} names a protected file`}. Run it in your own terminal: kiso never puts its credential store on a path to a model.`;
+}
+/** The whole question for one line, as both callers ask it. A line the
+ *  check throws on is refused: a line it could not read is not a line it
+ *  may let through. */
+export function protectedShellVerdict(line, workspaceRoot, files, env, check = protectedShellCheck) {
+    if (files.length === 0)
+        return { refused: false };
+    try {
+        const v = check(line, workspaceRoot, protectedIdentity(files), env);
+        return v.hit ? { refused: true, why: v.why, unread: v.unread } : { refused: false };
+    }
+    catch (err) {
+        return { refused: true, why: `the check could not read this line (${err instanceof Error ? err.name : "error"})`, unread: true };
+    }
+}
+/** The chain member: deny-or-abstain, every mode. */
+export function protectedShellExtension(opts) {
+    return {
+        name: "protected-files",
+        approvals: [
+            {
+                decide: (call) => {
+                    if (call.name !== "shell")
+                        return ABSTAIN;
+                    const command = call.input.command;
+                    if (typeof command !== "string")
+                        return ABSTAIN;
+                    const v = protectedShellVerdict(command, opts.workspaceRoot(), opts.files(), opts.env(), opts.check);
+                    return v.refused ? { action: "deny", reason: protectedShellReason(v) } : ABSTAIN;
+                },
+            },
+        ],
+    };
+}

package/dist/protected-writes.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 0.40.0 — writes into `.git/**` and `.kiso/**` always ask (lead's ruling on
+ * the read-only shell plan, 2026-09-18).
+ *
+ * Both directories hold configuration that RUNS. git executes commands its
+ * repository config names — `core.fsmonitor` on `git status`,
+ * `diff.external` and textconv on `git diff` — and a project's `.kiso/`
+ * holds extensions and config. Under accept-edits a model could write
+ * either unasked, and with the read-only shell allow a following
+ * `git status` would run what it wrote without a person seeing any of it.
+ *
+ * So a write_file or edit_file whose path — as written, or once symlinks
+ * are followed — passes through a `.git` or `.kiso` directory asks in
+ * every asking tier: accept-edits' allow does not cover it, and neither
+ * does a saved allow. dontAsk therefore denies it; plan denies it anyway;
+ * bypass runs it, as bypass's shell could.
+ */
+import type { PolicyCall } from "@vincemakes/kiso-core";
+import type { KisoExtension } from "@vincemakes/kiso-runtime";
+export declare function isProtectedWrite(call: PolicyCall, workspaceRoot: string): boolean;
+/**
+ * A saved allow ("yes, don't ask again for <tool>") allows by TOOL, so on
+ * its own it would carry every later call of that tool — including the
+ * ones kiso has decided must always reach a person. Wrapped wherever it
+ * enters the chain, it ABSTAINS for those, and the tier's ask stands.
+ * Everything else it decided, it still decides; its live `rules` handle
+ * (the grant path mutates it) is the same object.
+ */
+export declare function guardSavedAllow(ext: KisoExtension, neverInherited: (call: PolicyCall) => boolean): KisoExtension;

package/dist/protected-writes.js

@@ -0,0 +1,54 @@
+/**
+ * 0.40.0 — writes into `.git/**` and `.kiso/**` always ask (lead's ruling on
+ * the read-only shell plan, 2026-09-18).
+ *
+ * Both directories hold configuration that RUNS. git executes commands its
+ * repository config names — `core.fsmonitor` on `git status`,
+ * `diff.external` and textconv on `git diff` — and a project's `.kiso/`
+ * holds extensions and config. Under accept-edits a model could write
+ * either unasked, and with the read-only shell allow a following
+ * `git status` would run what it wrote without a person seeing any of it.
+ *
+ * So a write_file or edit_file whose path — as written, or once symlinks
+ * are followed — passes through a `.git` or `.kiso` directory asks in
+ * every asking tier: accept-edits' allow does not cover it, and neither
+ * does a saved allow. dontAsk therefore denies it; plan denies it anyway;
+ * bypass runs it, as bypass's shell could.
+ */
+import { relative, sep } from "node:path";
+import { resolveShellPath } from "./shell-words.js";
+const PROTECTED = new Set([".git", ".kiso"]);
+const WRITERS = new Set(["write_file", "edit_file"]);
+export function isProtectedWrite(call, workspaceRoot) {
+    if (!WRITERS.has(call.name))
+        return false;
+    const path = call.input.path;
+    if (typeof path !== "string")
+        return false;
+    // case folded: on a case-insensitive disk `.GIT/config` IS .git/config
+    if (path.split(/[\\/]/).some((seg) => PROTECTED.has(seg.toLowerCase())))
+        return true;
+    const { canonical } = resolveShellPath(workspaceRoot, workspaceRoot, path);
+    return relative(resolveShellPath(workspaceRoot, workspaceRoot, ".").canonical, canonical)
+        .split(sep)
+        .some((seg) => PROTECTED.has(seg.toLowerCase()));
+}
+const ABSTAIN = { action: "abstain" };
+/**
+ * A saved allow ("yes, don't ask again for <tool>") allows by TOOL, so on
+ * its own it would carry every later call of that tool — including the
+ * ones kiso has decided must always reach a person. Wrapped wherever it
+ * enters the chain, it ABSTAINS for those, and the tier's ask stands.
+ * Everything else it decided, it still decides; its live `rules` handle
+ * (the grant path mutates it) is the same object.
+ */
+export function guardSavedAllow(ext, neverInherited) {
+    if (ext.name !== "dont-ask-again" || ext.approvals === undefined)
+        return ext;
+    return {
+        ...ext,
+        approvals: ext.approvals.map((p) => ({
+            decide: (call, ctx) => (neverInherited(call) ? ABSTAIN : p.decide(call, ctx)),
+        })),
+    };
+}

package/dist/readonly-shell.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 0.40.0 — the read-only shell allow (launch-weekend plan §3; the design
+ * is kiso-doc plan-readonly-shell-2026-09-18).
+ *
+ * A shell call that can be PROVEN read-only runs without asking in the
+ * asking modes. "Proven" is the whole contract: this module answers
+ * `allow` only for a command line it has read completely — every segment
+ * of every pipeline a command on the table below, every flag on that
+ * command's list, every path inside the workspace, every redirection one
+ * of the few that write nothing — and `abstain` for everything else. It
+ * never asks and never denies, so anything it does not understand meets
+ * exactly the approval it met before this module existed.
+ *
+ * Flags are ALLOW-listed per command. A deny-list of the dangerous ones
+ * would be a list of the dangerous ones known on the day it was written:
+ * rg grew `--hostname-bin` (which runs a program) long after `--pre`.
+ *
+ * Two path predicates, one resolver (`resolveShellPath`, shared with the
+ * floor):
+ *  - SCOPE, for every path: the canonical path — symlinks followed — is
+ *    the workspace or under it, read_file's rule;
+ *  - CONTENT, for a path whose bytes the command prints: scope, and not a
+ *    credential by name (`isCredentialName`, the search corpus's rule).
+ *    Stricter than read_file, which reads `.env` on purpose; a shell read
+ *    of one asks.
+ *
+ * Recursive search is deliberately NOT on the table (grep -r, rg over a
+ * directory). search_text is allowed unasked BECAUSE its walk skips
+ * credential files; rg skips hidden files but reads `id_rsa` and `*.pem`,
+ * and grep -r reads everything, so an unasked search for "KEY" would hand
+ * a private key to the provider. The model has search_text for that.
+ */
+import type { KisoExtension } from "@vincemakes/kiso-runtime";
+export type ReadOnlyVerdict = {
+    readonly allow: true;
+} | {
+    readonly allow: false;
+    readonly why: string;
+};
+/** The table's commands — the gate that every one has a case reads this. */
+export declare const READ_ONLY_COMMANDS: readonly string[];
+/**
+ * Is this command line read-only, provably? `workspaceRoot` is the
+ * shell's working directory (the shell tool runs every command there);
+ * nothing under `protectedRoots` is read unasked.
+ */
+export declare function classifyReadOnly(commandLine: string, workspaceRoot: string, protectedRoots?: readonly string[]): ReadOnlyVerdict;
+/**
+ * The chain member. ALLOW or ABSTAIN, never anything else: an allow here
+ * outranks the tier's ask (deny > allow > ask) and is recorded as
+ * `decidedBy: "read-only-shell"`, so the audit says why a shell call ran
+ * unasked; a deny anywhere — plan's, the breaker's, a user extension's —
+ * still wins over it.
+ */
+export declare function readOnlyShellExtension(roots: () => {
+    readonly workspaceRoot: string;
+    readonly excludeRoots: readonly string[];
+}): KisoExtension;