toolstile 0.1.0 → 0.1.2

package/README.md

@@ -15,19 +15,21 @@ Windsurf, Gemini CLI and Cline and grades them for:
 | Remote servers reached over plain `http://` | high |
 | Containers run with `--privileged` or the Docker socket | high |
 | The same credential pasted into several clients' configs | medium |
-| Config files holding secrets that other users can read | medium |
+| Config files holding secrets that other accounts can reach (file and folder permissions) | medium |
 | `npx`, `uvx` and `docker` servers that run whatever version is newest | medium |
 | Filesystem servers that can read your whole home folder or disk | medium |
 | Permission rules that approve every tool of a server without asking | medium |
 | Tools on a client's auto-approve list | low |
-| The same server set up separately in several clients | low |
+
+It also lists servers set up separately in several clients. That is context, not
+scored: remote servers need an entry per client.
 
 ```text
 toolstile audit · local MCP config check · nothing leaves this machine
 
 Scanned 4 files from Claude Code, Cursor, Codex: 10 MCP servers.
 
-  Grade C  67/100   1 high · 2 medium · 3 low
+  Grade B  77/100   1 high · 1 medium · 1 low
 
 HIGH   Plaintext secret in github (Cursor)
        A GitHub token is written directly into the config file. Anything that can
@@ -42,7 +44,9 @@ HIGH   Plaintext secret in github (Cursor)
 - Makes no network requests and collects no telemetry.
 - Never prints, stores or sends secret values. Findings name the file and key,
   for example `mcpServers.github.env.GITHUB_TOKEN`, and the kind of secret.
-- About 1,100 lines of TypeScript with one runtime dependency
+- Never quotes a config file: one that cannot be read or parsed is listed with a
+  reason and position only, for example `invalid TOML at line 3, column 12`.
+- About 1,400 lines of TypeScript with one runtime dependency
   ([smol-toml](https://github.com/squirrelchat/smol-toml), for Codex's TOML
   config) and an optional one ([resvg-js](https://github.com/thx/resvg-js), only
   to render `--card` as PNG). Read it before you run it.
@@ -53,6 +57,7 @@ HIGH   Plaintext secret in github (Cursor)
 --json              Print results as JSON
 --card [file]       Write a shareable grade card (default toolstile-audit.png;
                     use a .svg name for SVG). Contains only the grade and counts.
+--redact            Hide your home folder and project paths, for posting the output
 --project <dir>     Also scan project configs in <dir> (default: current directory)
 --no-project        Scan only user-level configs
 --fail-on <level>   Exit with code 1 if any finding is at or above high, medium or low
@@ -61,6 +66,23 @@ HIGH   Plaintext secret in github (Cursor)
 `--fail-on high` makes it usable in CI or a pre-commit hook for repositories that
 check in `.mcp.json`, `.cursor/mcp.json` or `.vscode/mcp.json`.
 
+Exit codes:
+
+| Code | Meaning |
+| --- | --- |
+| 0 | The audit ran, and no finding reached the `--fail-on` level (or `--fail-on` was not set) |
+| 1 | A finding is at or above the `--fail-on` level |
+| 2 | Invalid options, or the audit itself failed |
+
+## Scoring
+
+Each distinct problem has a weight: 10 for a leaked secret, plain-http remote or
+privileged container; 4 for readable secret files, unpinned packages, broad
+filesystem access and whole-server auto-approval; 2 for each copied secret; 1 for
+auto-approved tools. A secret pasted into several files counts as one leak. The
+score is `100 / (1 + weight / 50)`: one leaked secret scores 83 (B), four score
+about 56 (D). Grades: A 90+, B 75+, C 60+, D 40+, F below 40.
+
 ## Share your grade
 
 ```sh
@@ -68,7 +90,8 @@ npx toolstile audit --card
 ```
 
 writes a 1200×630 image with your grade and counts (no server names, paths or
-values) and prints a ready-to-post link.
+values) and prints a ready-to-post link. To post the text report instead, add
+`--redact` so it shows `~` and `<project>` in place of your folders.
 
 ## Files it reads
 
@@ -100,6 +123,12 @@ The audit works on its own and does not require a Toolstile account.
 
 Questions and reports: support@toolstile.com.
 
+## Releases
+
+The npm package is published by [GitHub Actions](.github/workflows/publish.yml)
+with npm trusted publishing and provenance, so each release links back to the
+commit and workflow that built it. No npm token is stored anywhere.
+
 ## License
 
 [MIT](LICENSE)

package/dist/checks.d.ts

@@ -4,13 +4,22 @@ interface Package {
     registry: "npm" | "pypi" | "docker";
     name: string;
     version: string | null;
+    /** Index of the package in the unwrapped words. */
+    wordIndex: number;
+    /** Index of the package in `args`, or -1 when it is inside `command`. */
     argIndex: number;
 }
 /** Finds the package a launcher such as npx, uvx or docker runs. */
 export declare function packageOf(s: ServerEntry): Package | null;
 /** A stable identity for the same server configured in several places. */
 export declare function identityOf(s: ServerEntry): string | null;
+/** A path for a shell command: `~/...` under the home folder, single-quoted when needed. */
+export declare function shellPath(path: string, home: string): string;
 export declare function runChecks(d: Discovery, home: string): Finding[];
+/**
+ * 100 / (1 + weight / 50): one leaked secret (10) scores 83, four score about 50, and the score
+ * keeps separating bad setups from worse ones instead of bottoming out at zero.
+ */
 export declare function score(findings: Finding[]): {
     score: number;
     grade: string;

package/dist/checks.js

@@ -41,20 +41,67 @@ const LAUNCHERS = {
     pnpx: "npm",
     uvx: "pypi",
 };
-/** Splits `command` and `args` into words, handling configs that put the whole command in one string. */
+const base = (p) => win32.basename(posix.basename(p)).replace(/\.(cmd|exe)$/i, "");
+const split = (text) => text.trim().split(/\s+/).filter(Boolean);
+/** WSL options that take a value. */
+const WSL_VALUED = new Set(["-d", "--distribution", "--distribution-id", "-u", "--user", "--cd", "--shell-type"]);
+/** Index of the first word after a `cmd /c` or `wsl` wrapper at `start`, or `start` when there is none. */
+function afterWrapper(list, start) {
+    const name = base(list[start] ?? "").toLowerCase();
+    let j = start + 1;
+    if (name === "cmd") {
+        // cmd [/d] [/s] [/q] … /c|/k command
+        while (j < list.length && /^\/[a-z]$/i.test(list[j]) && !/^\/[ck]$/i.test(list[j]))
+            j++;
+        return /^\/[ck]$/i.test(list[j] ?? "") ? j + 1 : start;
+    }
+    if (name === "wsl") {
+        while (j < list.length) {
+            const a = list[j];
+            if (WSL_VALUED.has(a))
+                j += 2;
+            else if (a === "-e" || a === "--exec" || a === "--")
+                return j + 1;
+            else if (a.startsWith("-"))
+                j++;
+            else
+                break;
+        }
+        return j;
+    }
+    return start;
+}
+/**
+ * Splits `command` and `args` into words, handling configs that put the whole command in one string,
+ * and skips Windows wrappers (`cmd /c npx …`, `wsl npx …`) so the real launcher comes first.
+ */
 function words(s) {
     if (!s.command)
-        return [];
-    const command = s.args.length === 0 && /\s/.test(s.command.trim()) ? s.command.trim().split(/\s+/) : [s.command];
-    return [...command, ...s.args];
+        return { list: [], arg: [] };
+    const oneString = s.args.length === 0 && /\s/.test(s.command.trim());
+    let list = oneString ? split(s.command) : [s.command, ...s.args];
+    let arg = oneString ? list.map(() => -1) : list.map((_, i) => i - 1);
+    for (;;) {
+        const start = afterWrapper(list, 0);
+        if (start === 0 || start >= list.length)
+            break;
+        list = list.slice(start);
+        arg = arg.slice(start);
+        // `cmd /c "npx -y pkg"` passes the inner command as one argument.
+        if (list.length === 1 && /\s/.test(list[0].trim())) {
+            const from = arg[0];
+            list = split(list[0]);
+            arg = list.map(() => from);
+        }
+    }
+    return { list, arg };
 }
-const base = (p) => win32.basename(posix.basename(p)).replace(/\.(cmd|exe)$/i, "");
 /** Finds the package a launcher such as npx, uvx or docker runs. */
 export function packageOf(s) {
-    const w = words(s);
+    const { list: w, arg } = words(s);
     if (w.length === 0)
         return null;
-    const cmd = base(w[0]);
+    const cmd = base(w[0]).toLowerCase();
     const sub = w.slice(1);
     let registry = LAUNCHERS[cmd];
     let skip = 0;
@@ -74,6 +121,7 @@ export function packageOf(s) {
         return null;
     const rest = sub.slice(skip);
     const offset = 1 + skip;
+    const at = (spec, i) => parsePackage(registry, spec, i, arg[i] ?? -1);
     // Flags that take a value; their value is not the package.
     const valued = new Set(["-p", "--package", "--from", "--with", "-e", "--env", "-v", "--volume", "--name", "--network", "--mount", "--env-file", "-w", "--workdir", "--entrypoint", "-u", "--user", "--python"]);
     for (let i = 0; i < rest.length; i++) {
@@ -83,41 +131,42 @@ export function packageOf(s) {
         if (a.startsWith("-")) {
             if (valued.has(a)) {
                 if ((a === "--package" || a === "-p" || a === "--from") && registry !== "docker") {
-                    return parsePackage(registry, rest[i + 1] ?? "", offset + i + 1);
+                    return at(rest[i + 1] ?? "", offset + i + 1);
                 }
                 i++;
             }
             continue;
         }
-        return parsePackage(registry, a, offset + i);
+        return at(a, offset + i);
     }
     return null;
 }
-function parsePackage(registry, spec, argIndex) {
+function parsePackage(registry, spec, wordIndex, argIndex) {
     if (!spec)
         return null;
+    const where = { wordIndex, argIndex };
     if (registry === "docker") {
         const at = spec.indexOf("@sha256:");
         if (at > 0)
-            return { registry, name: spec.slice(0, at), version: spec.slice(at + 1), argIndex };
+            return { registry, name: spec.slice(0, at), version: spec.slice(at + 1), ...where };
         const slash = spec.lastIndexOf("/");
         const colon = spec.lastIndexOf(":");
         return colon > slash
-            ? { registry, name: spec.slice(0, colon), version: spec.slice(colon + 1), argIndex }
-            : { registry, name: spec, version: null, argIndex };
+            ? { registry, name: spec.slice(0, colon), version: spec.slice(colon + 1), ...where }
+            : { registry, name: spec, version: null, ...where };
     }
     if (registry === "pypi") {
         const m = /^([A-Za-z0-9._\-[\],]+?)(?:(==|@|>=|~=)(.+))?$/.exec(spec);
         if (!m)
             return null;
-        return { registry, name: m[1], version: m[2] === "==" || m[2] === "@" ? m[3] : null, argIndex };
+        return { registry, name: m[1], version: m[2] === "==" || m[2] === "@" ? m[3] : null, ...where };
     }
     if (/^(https?:|git\+|file:|\.|\/)/.test(spec))
         return null;
     const at = spec.indexOf("@", spec.startsWith("@") ? 1 : 0);
     return at > 0
-        ? { registry, name: spec.slice(0, at), version: spec.slice(at + 1), argIndex }
-        : { registry, name: spec, version: null, argIndex };
+        ? { registry, name: spec.slice(0, at), version: spec.slice(at + 1), ...where }
+        : { registry, name: spec, version: null, ...where };
 }
 const isPinned = (p) => p.version !== null &&
     p.version !== "latest" &&
@@ -138,7 +187,7 @@ export function identityOf(s) {
     const pkg = packageOf(s);
     if (pkg)
         return `${pkg.registry}:${pkg.name.toLowerCase()}`;
-    const w = words(s);
+    const w = words(s).list;
     return w.length ? `cmd:${w.join(" ")}` : null;
 }
 const LOOPBACK = /^(localhost|127\.\d+\.\d+\.\d+|\[::1\]|0\.0\.0\.0)$/i;
@@ -149,10 +198,17 @@ function broadRoots(s, home) {
         return [];
     const homes = new Set([home, home.replace(/\/+$/, ""), "~", "~/", "$HOME", "${HOME}", "%USERPROFILE%"]);
     return words(s)
-        .slice(pkg.argIndex + 1)
+        .list.slice(pkg.wordIndex + 1)
         .filter((a) => a === "/" || /^[A-Za-z]:\\?$/.test(a) || homes.has(a) || homes.has(a.replace(/\/+$/, "")));
 }
-const SEVERITY_ORDER = { high: 0, medium: 1, low: 2 };
+const SEVERITY_ORDER = { high: 0, medium: 1, low: 2, info: 3 };
+/** Toolstile's own gateway is meant to be added to every client. */
+const TOOLSTILE = /^url:([a-z0-9-]+\.)*toolstile\.com\//i;
+/** A path for a shell command: `~/...` under the home folder, single-quoted when needed. */
+export function shellPath(path, home) {
+    const quote = (p) => (/^[\w@%+=:,./-]+$/.test(p) ? p : `'${p.replace(/'/g, "'\\''")}'`);
+    return home && path.startsWith(home + "/") ? `~/${quote(path.slice(home.length + 1))}` : quote(path);
+}
 export function runChecks(d, home) {
     const findings = [];
     const secrets = d.servers.flatMap(secretsOf);
@@ -160,7 +216,10 @@ export function runChecks(d, home) {
     const byServer = new Map();
     for (const s of secrets)
         byServer.set(s.server, [...(byServer.get(s.server) ?? []), s]);
+    const counted = new Set();
     for (const [server, list] of byServer) {
+        const fresh = new Set(list.map((s) => s.hash).filter((h) => !counted.has(h)));
+        fresh.forEach((h) => counted.add(h));
         const kinds = [...new Set(list.map((s) => s.kind))].join(", ");
         const one = list.length === 1;
         const what = one ? `${/^[aeiou]/i.test(kinds) ? "An" : "A"} ${kinds} is` : `${list.length} secrets (${kinds}) are`;
@@ -171,6 +230,8 @@ export function runChecks(d, home) {
             detail: `${what} written directly into the config file. Anything that can read the file, including backups, dotfile syncs and other tools, can use ${one ? "it" : "them"}.`,
             fix: "Reference an environment variable instead (for example ${API_TOKEN}, or \"Bearer ${API_TOKEN}\" in a header), or use the server's OAuth sign-in. Rotate the secret if the file was ever shared or synced.",
             locations: list.map((s) => s.location),
+            // A secret pasted into several files is one leak; the copies are scored by copied-secret.
+            weight: 10 * fresh.size,
         });
     }
     // The same secret copied into several files.
@@ -188,20 +249,23 @@ export function runChecks(d, home) {
             detail: `One credential is pasted into ${files.size} separate config files (${[...new Set(list.map((s) => CLIENT_NAMES[s.server.client]))].join(", ")}). Rotating or revoking it means finding every copy.`,
             fix: "Keep one copy in your environment or keychain and reference it from each client, or route the clients through one gateway.",
             locations: list.map((s) => s.location),
+            weight: 2,
         });
     }
-    // Config files that hold secrets but are readable by other users.
+    // Config files that hold secrets and that other accounts on the machine can actually reach.
     const secretFiles = new Set(secrets.map((s) => s.location.file));
     for (const f of d.files) {
-        if (f.mode === undefined || !secretFiles.has(f.path) || (f.mode & 0o077) === 0)
+        if (f.mode === undefined || !f.exposure || !secretFiles.has(f.path))
             continue;
+        const [open, who] = f.exposure === "others" ? ["everyone", "every account on this machine"] : ["its group", "other accounts in that group"];
         findings.push({
             rule: "readable-config",
             severity: "medium",
-            title: "Config file with secrets is readable by other users",
-            detail: `This file contains plaintext secrets and has permissions ${f.mode.toString(8).padStart(3, "0")}.`,
-            fix: `Restrict it to your user: chmod 600 "${f.path}"`,
+            title: "Config file with secrets is readable by other accounts",
+            detail: `This file holds plaintext secrets and has permissions ${f.mode.toString(8).padStart(3, "0")}, and every folder above it is open to ${open}, so ${who} can read it.`,
+            fix: `Restrict it to your user: chmod 600 ${shellPath(f.path, home)}`,
             locations: [{ file: f.path, pointer: "(file permissions)" }],
+            weight: 4,
         });
     }
     for (const s of d.servers) {
@@ -216,6 +280,7 @@ export function runChecks(d, home) {
                         detail: `${u.host} is reached over plain http://, so requests, tool results and any credentials travel unencrypted.`,
                         fix: "Use the server's https:// endpoint.",
                         locations: [at(s, "url")],
+                        weight: 10,
                     });
                 }
             }
@@ -234,10 +299,11 @@ export function runChecks(d, home) {
                 fix: pkg.registry === "docker"
                     ? `Pin an image digest or exact tag, for example ${pkg.name}:<version>.`
                     : `Pin an exact version, for example ${pkg.name}${pkg.registry === "pypi" ? "==" : "@"}<version>.`,
-                locations: [at(s, "args", String(Math.max(0, pkg.argIndex - 1)))],
+                locations: [pkg.argIndex >= 0 ? at(s, "args", String(pkg.argIndex)) : at(s, "command")],
+                weight: 4,
             });
         }
-        const w = words(s);
+        const w = words(s).list;
         if (pkg?.registry === "docker") {
             const risky = w.filter((a) => a === "--privileged" || /\/var\/run\/docker\.sock/.test(a) || a === "--net=host" || a === "--network=host");
             if (risky.length) {
@@ -248,6 +314,7 @@ export function runChecks(d, home) {
                     detail: `The server runs with ${[...new Set(risky)].join(", ")}, which gives it effective control of the host.`,
                     fix: "Remove --privileged and the Docker socket mount unless the server truly needs them.",
                     locations: [at(s, "args")],
+                    weight: 10,
                 });
             }
         }
@@ -260,6 +327,7 @@ export function runChecks(d, home) {
                 detail: `Allowed root ${roots.join(", ")} includes SSH keys, cloud credentials and every other config file.`,
                 fix: "Allow only the project folders the agent needs.",
                 locations: [at(s, "args")],
+                weight: 4,
             });
         }
         if (s.autoApproved.length) {
@@ -270,6 +338,7 @@ export function runChecks(d, home) {
                 detail: `Auto-approved: ${s.autoApproved.slice(0, 6).join(", ")}${s.autoApproved.length > 6 ? ", …" : ""}. A prompt injection in any content the agent reads can call these.`,
                 fix: "Keep auto-approval to read-only tools.",
                 locations: [at(s)],
+                weight: 1,
             });
         }
     }
@@ -284,13 +353,15 @@ export function runChecks(d, home) {
             detail: `Permission rule ${a.subject} skips the confirmation prompt, including for write and delete tools. A prompt injection in a web page, issue or email the agent reads can call them.`,
             fix: "Allow specific read-only tools (mcp__server__tool) instead of whole servers.",
             locations: [a.location],
+            weight: 4,
         });
     }
-    // The same server configured separately in several clients.
+    // The same server configured separately in several clients. Context only: remote servers need an
+    // entry per client, and copies that carry credentials are already scored by copied-secret.
     const byIdentity = new Map();
     for (const s of d.servers) {
         const id = identityOf(s);
-        if (id)
+        if (id && !TOOLSTILE.test(id))
             byIdentity.set(id, [...(byIdentity.get(id) ?? []), s]);
     }
     for (const list of byIdentity.values()) {
@@ -299,24 +370,23 @@ export function runChecks(d, home) {
             continue;
         findings.push({
             rule: "duplicated-server",
-            severity: "low",
+            severity: "info",
             title: `${list[0].name} is set up separately in ${clients.length} clients`,
-            detail: `Configured in ${clients.map((c) => CLIENT_NAMES[c]).join(", ")}. Each copy has its own credentials and settings to keep in sync, rotate and revoke.`,
-            fix: "Configure it once and share it across agents.",
+            detail: `Configured in ${clients.map((c) => CLIENT_NAMES[c]).join(", ")}. Each copy has its own settings and sign-in to keep in sync and revoke.`,
+            fix: "Nothing to fix; listed so you know where each copy lives.",
             locations: list.map((s) => at(s)),
+            weight: 0,
         });
     }
     return findings.sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity]);
 }
-const PENALTY = { high: 15, medium: 6, low: 2 };
-const CAP = { high: 60, medium: 30, low: 10 };
+/**
+ * 100 / (1 + weight / 50): one leaked secret (10) scores 83, four score about 50, and the score
+ * keeps separating bad setups from worse ones instead of bottoming out at zero.
+ */
 export function score(findings) {
-    let total = 100;
-    for (const sev of ["high", "medium", "low"]) {
-        const n = findings.filter((f) => f.severity === sev).length;
-        total -= Math.min(n * PENALTY[sev], CAP[sev]);
-    }
-    total = Math.max(0, total);
-    const grade = total >= 90 ? "A" : total >= 80 ? "B" : total >= 65 ? "C" : total >= 50 ? "D" : "F";
+    const weight = findings.reduce((n, f) => n + f.weight, 0);
+    const total = Math.round(100 / (1 + weight / 50));
+    const grade = total >= 90 ? "A" : total >= 75 ? "B" : total >= 60 ? "C" : total >= 40 ? "D" : "F";
     return { score: total, grade };
 }

package/dist/cli.js

@@ -4,7 +4,7 @@ import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { renderCard, shareText, shareUrl } from "./card.js";
 import { audit } from "./index.js";
-import { renderJson, renderReport, style } from "./report.js";
+import { redact, renderJson, renderReport, style } from "./report.js";
 const HELP = `toolstile: audit the MCP server configs your AI agents use
 
 Usage
@@ -22,6 +22,7 @@ Options
   --json              Print results as JSON
   --card [file]       Write a shareable grade card (default toolstile-audit.png;
                       use a .svg name for SVG). Contains only the grade and counts.
+  --redact            Hide your home folder and project paths, for posting the output
   --project <dir>     Also scan project configs in <dir> (default: current directory)
   --no-project        Scan only user-level configs
   --fail-on <level>   Exit with code 1 if any finding is at or above high, medium or low
@@ -33,7 +34,7 @@ function version() {
     return pkg.version;
 }
 function parseArgs(argv) {
-    const args = { json: false, card: null, project: process.cwd(), failOn: null };
+    const args = { json: false, redact: false, card: null, project: process.cwd(), failOn: null };
     const rest = [...argv];
     if (rest[0] === "audit")
         rest.shift();
@@ -57,6 +58,9 @@ function parseArgs(argv) {
             case "--json":
                 args.json = true;
                 break;
+            case "--redact":
+                args.redact = true;
+                break;
             case "--card": {
                 const next = inline ?? rest[i + 1];
                 if (next !== undefined && !next.startsWith("-")) {
@@ -106,7 +110,7 @@ async function writeCard(path, svg) {
         return fallback;
     }
 }
-const RANK = { high: 3, medium: 2, low: 1 };
+const RANK = { high: 3, medium: 2, low: 1, info: 0 };
 async function main() {
     let args;
     try {
@@ -125,13 +129,14 @@ async function main() {
         return 0;
     }
     const home = homedir();
-    const result = audit({ home, cwd: args.project });
+    const raw = audit({ home, cwd: args.project });
+    const result = args.redact ? redact(raw, home, args.project) : raw;
     const color = !args.json && process.stdout.isTTY === true && !process.env.NO_COLOR;
     const s = style(color);
     if (args.json)
         process.stdout.write(renderJson(result));
     else
-        process.stdout.write(renderReport(result, home, s));
+        process.stdout.write(renderReport(result, home, s, args.redact));
     if (args.card) {
         if (result.grade === null) {
             process.stderr.write("No MCP servers found, so there is no grade to put on a card.\n");

package/dist/parse.d.ts

@@ -1,3 +1,17 @@
-/** Parses JSON that may contain comments and trailing commas (VS Code style). */
+/**
+ * A config file that could not be parsed. The message is fixed text plus a position: parser
+ * messages quote the offending source line, which can hold a secret, so they are never kept.
+ */
+export declare class ConfigParseError extends Error {
+    readonly format: "JSON" | "TOML";
+    readonly line?: number | undefined;
+    readonly column?: number | undefined;
+    constructor(format: "JSON" | "TOML", line?: number | undefined, column?: number | undefined);
+}
+/**
+ * Parses JSON that may contain comments and trailing commas (VS Code style). Comments and
+ * trailing commas become spaces so parser positions still match the original text.
+ */
 export declare function parseJsonc(text: string): unknown;
+/** Parses a config file. Throws only {@link ConfigParseError}, whose message never contains file text. */
 export declare function parseConfig(path: string, text: string): unknown;

package/dist/parse.js

@@ -1,5 +1,24 @@
-import { parse as parseToml } from "smol-toml";
-/** Parses JSON that may contain comments and trailing commas (VS Code style). */
+import { parse as parseToml, TomlError } from "smol-toml";
+/**
+ * A config file that could not be parsed. The message is fixed text plus a position: parser
+ * messages quote the offending source line, which can hold a secret, so they are never kept.
+ */
+export class ConfigParseError extends Error {
+    format;
+    line;
+    column;
+    constructor(format, line, column) {
+        super(`invalid ${format}${line ? ` at line ${line}${column ? `, column ${column}` : ""}` : ""}`);
+        this.format = format;
+        this.line = line;
+        this.column = column;
+        this.name = "ConfigParseError";
+    }
+}
+/**
+ * Parses JSON that may contain comments and trailing commas (VS Code style). Comments and
+ * trailing commas become spaces so parser positions still match the original text.
+ */
 export function parseJsonc(text) {
     let out = "";
     let inString = false;
@@ -22,15 +41,19 @@ export function parseJsonc(text) {
             out += ch;
         }
         else if (ch === "/" && next === "/") {
-            while (i < text.length && text[i] !== "\n")
+            while (i < text.length && text[i] !== "\n") {
+                out += blank(text[i]);
                 i++;
-            out += "\n";
+            }
+            if (i < text.length)
+                out += "\n";
         }
         else if (ch === "/" && next === "*") {
-            i += 2;
-            while (i < text.length && !(text[i] === "*" && text[i + 1] === "/"))
-                i++;
-            i++;
+            const end = text.indexOf("*/", i + 2);
+            const stop = end === -1 ? text.length : end + 2;
+            for (; i < stop; i++)
+                out += blank(text[i]);
+            i--;
         }
         else {
             out += ch;
@@ -38,6 +61,8 @@ export function parseJsonc(text) {
     }
     return JSON.parse(stripTrailingCommas(out));
 }
+/** Keeps line breaks so line numbers survive; everything else becomes a space. */
+const blank = (ch) => (ch === "\n" || ch === "\r" ? ch : " ");
 function stripTrailingCommas(text) {
     let out = "";
     let inString = false;
@@ -60,17 +85,51 @@ function stripTrailingCommas(text) {
             let j = i + 1;
             while (j < text.length && /\s/.test(text[j]))
                 j++;
-            if (text[j] === "}" || text[j] === "]")
+            if (text[j] === "}" || text[j] === "]") {
+                out += " ";
                 continue;
+            }
         }
         out += ch;
     }
     return out;
 }
+/** 1-based line and column of a character offset. */
+function lineColumn(text, offset) {
+    const before = text.slice(0, Math.min(Math.max(offset, 0), text.length));
+    const lastBreak = before.lastIndexOf("\n");
+    return { line: before.split("\n").length, column: offset - lastBreak };
+}
+/** Reads only the position from a V8 JSON error; the rest of its message may quote the file. */
+function jsonPosition(error, text) {
+    const message = error instanceof Error ? error.message : "";
+    const at = /\bposition (\d+)/.exec(message);
+    if (at)
+        return lineColumn(text, Number(at[1]));
+    if (/Unexpected end of JSON input/.test(message))
+        return lineColumn(text, text.length);
+    return {};
+}
+/** Parses a config file. Throws only {@link ConfigParseError}, whose message never contains file text. */
 export function parseConfig(path, text) {
-    if (path.endsWith(".toml"))
-        return parseToml(text);
-    if (text.trim() === "")
+    const body = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+    if (path.endsWith(".toml")) {
+        try {
+            return parseToml(body);
+        }
+        catch (error) {
+            if (error instanceof TomlError)
+                throw new ConfigParseError("TOML", error.line, error.column);
+            throw new ConfigParseError("TOML");
+        }
+    }
+    if (body.trim() === "")
         return {};
-    return parseJsonc(text);
+    try {
+        return parseJsonc(body);
+    }
+    catch (error) {
+        const { line, column } = jsonPosition(error, body);
+        throw new ConfigParseError("JSON", line, column);
+    }
 }

package/dist/report.d.ts

@@ -11,8 +11,14 @@ export declare function counts(findings: Finding[]): {
     high: number;
     medium: number;
     low: number;
+    info: number;
     secrets: number;
 };
-export declare function renderReport(r: AuditResult, home: string, s: Style): string;
-/** JSON output for scripts. Paths are included; secret values never are. */
+/**
+ * Returns a copy safe to post publicly: the home folder becomes `~`, the scanned project folder
+ * becomes `<project>`, and project paths inside pointers (Claude Code's `projects["/path"]`) are hidden.
+ */
+export declare function redact(r: AuditResult, home: string, project: string | null): AuditResult;
+export declare function renderReport(r: AuditResult, home: string, s: Style, redacted?: boolean): string;
+/** JSON output for scripts. Paths are included unless redacted; secret values never are. */
 export declare function renderJson(r: AuditResult): string;

package/dist/report.js

@@ -5,10 +5,11 @@ export function style(color) {
     const yellow = wrap(33, 39);
     const blue = wrap(34, 39);
     const green = wrap(32, 39);
+    const dim = wrap(2, 22);
     return {
         bold: wrap(1, 22),
-        dim: wrap(2, 22),
-        sev: (sev, s) => (sev === "high" ? red(s) : sev === "medium" ? yellow(s) : blue(s)),
+        dim,
+        sev: (sev, s) => (sev === "high" ? red(s) : sev === "medium" ? yellow(s) : sev === "low" ? blue(s) : dim(s)),
         grade: (g, s) => (g === "A" || g === "B" ? green(s) : g === "C" ? yellow(s) : red(s)),
     };
 }
@@ -19,10 +20,37 @@ export function counts(findings) {
         high: findings.filter((f) => f.severity === "high").length,
         medium: findings.filter((f) => f.severity === "medium").length,
         low: findings.filter((f) => f.severity === "low").length,
+        info: findings.filter((f) => f.severity === "info").length,
         secrets: findings.filter((f) => f.rule === "plaintext-secret").reduce((n, f) => n + f.locations.length, 0),
     };
 }
-export function renderReport(r, home, s) {
+/**
+ * Returns a copy safe to post publicly: the home folder becomes `~`, the scanned project folder
+ * becomes `<project>`, and project paths inside pointers (Claude Code's `projects["/path"]`) are hidden.
+ */
+export function redact(r, home, project) {
+    const scrub = (text) => {
+        let out = text.replace(/projects\["(?:[^"\\]|\\.)*"\]/g, 'projects["…"]');
+        if (project)
+            out = out.split(project).join("<project>");
+        if (home)
+            out = out.split(home).join("~");
+        return out;
+    };
+    return {
+        ...r,
+        files: r.files.map((f) => ({ ...f, path: scrub(f.path) })),
+        unreadable: r.unreadable.map((u) => ({ ...u, path: scrub(u.path), error: scrub(u.error) })),
+        findings: r.findings.map((f) => ({
+            ...f,
+            title: scrub(f.title),
+            detail: scrub(f.detail),
+            fix: scrub(f.fix),
+            locations: f.locations.map((l) => ({ file: scrub(l.file), pointer: scrub(l.pointer) })),
+        })),
+    };
+}
+export function renderReport(r, home, s, redacted = false) {
     const lines = [];
     lines.push("", `${s.bold("toolstile audit")} ${s.dim("· local MCP config check · nothing leaves this machine")}`, "");
     if (r.files.length === 0 && r.unreadable.length === 0) {
@@ -32,19 +60,22 @@ export function renderReport(r, home, s) {
     const clientList = r.clients.map((c) => CLIENT_NAMES[c]).join(", ");
     lines.push(`Scanned ${plural(r.files.length, "file")} from ${clientList}: ${plural(r.servers, "MCP server")}.`);
     for (const u of r.unreadable) {
-        lines.push(s.dim(`Skipped ${tildify(u.path, home)} (${CLIENT_NAMES[u.client]}): could not parse it.`));
+        lines.push(s.dim(`Skipped ${tildify(u.path, home)} (${CLIENT_NAMES[u.client]}): ${u.error}.`));
     }
     lines.push("");
     if (r.grade !== null) {
         const c = counts(r.findings);
-        const summary = r.findings.length
-            ? [c.high && s.sev("high", `${c.high} high`), c.medium && s.sev("medium", `${c.medium} medium`), c.low && s.sev("low", `${c.low} low`)]
-                .filter(Boolean)
-                .join(s.dim(" · "))
-            : "no issues found";
+        const parts = [
+            c.high && s.sev("high", `${c.high} high`),
+            c.medium && s.sev("medium", `${c.medium} medium`),
+            c.low && s.sev("low", `${c.low} low`),
+        ].filter(Boolean);
+        const summary = parts.length ? parts.join(s.dim(" · ")) : "no issues found";
         lines.push(`  ${s.bold(s.grade(r.grade, `Grade ${r.grade}`))}  ${s.dim(`${r.score}/100`)}   ${summary}`, "");
     }
-    for (const f of r.findings) {
+    const issues = r.findings.filter((f) => f.severity !== "info");
+    const info = r.findings.filter((f) => f.severity === "info");
+    for (const f of issues) {
         const tag = s.sev(f.severity, f.severity.toUpperCase().padEnd(6));
         lines.push(`${tag} ${s.bold(f.title)}`);
         lines.push(`       ${f.detail}`);
@@ -55,10 +86,21 @@ export function renderReport(r, home, s) {
             lines.push(s.dim(`       … and ${f.locations.length - shown.length} more`));
         lines.push(`       ${s.dim("Fix:")} ${f.fix}`, "");
     }
-    lines.push(s.dim("Secret values are never printed. Share your grade (no secrets, no paths): npx toolstile audit --card"), s.dim("Keep credentials off your machines and control each agent's tools: https://toolstile.com/?ref=cli"), "");
+    if (info.length) {
+        lines.push(s.dim("Also set up in more than one client (not scored):"));
+        for (const f of info)
+            lines.push(s.dim(`  ${f.title.replace(/ is set up separately in (\d+) clients$/, "")}: ${f.detail.split(".")[0].replace(/^Configured in /, "")}`));
+        lines.push("");
+    }
+    lines.push(s.dim("Secret values are never printed."));
+    if (!redacted)
+        lines.push(s.dim("Posting this? Run with --redact to hide your paths, or --card for an image with only the grade."));
+    else
+        lines.push(s.dim("Share an image with only the grade: npx toolstile audit --card"));
+    lines.push(s.dim("Keep credentials off your machines and control each agent's tools: https://toolstile.com/?ref=cli"), "");
     return lines.join("\n");
 }
-/** JSON output for scripts. Paths are included; secret values never are. */
+/** JSON output for scripts. Paths are included unless redacted; secret values never are. */
 export function renderJson(r) {
     return JSON.stringify(r, null, 2) + "\n";
 }

package/dist/secrets.js

@@ -28,9 +28,9 @@ const PATTERNS = [
     [/\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/, "JWT"],
     [/\b[a-z][a-z0-9+.-]*:\/\/[^\s:/@]+:[^\s@/]{3,}@/i, "password in connection string"],
 ];
-const SECRET_KEY = /(token|secret|passw(or)?d|passwd|api[_-]?key|apikey|access[_-]?key|private[_-]?key|client[_-]?secret|credential|auth|bearer|session|cookie|\bpat\b|_pat$|^pat_)/i;
-/** Key suffixes that name configuration about a secret rather than the secret itself. */
-const NOT_SECRET_KEY = /(url|uri|endpoint|host|port|path|file|dir|type|mode|enabled|header|name|user(name)?|id|region|scope|scopes|method|env_var|_var)$/i;
+const SECRET_KEY = /(token|secret|passw(or)?d|passwd|api[_-]?key|apikey|access[_-]?key|private[_-]?key|client[_-]?secret|credential|auth|bearer|session|cookie|\bpat\b|_pat$|^pat_|(^|[_-])key$)/i;
+/** Key suffixes that name configuration about a secret, or a public half, rather than the secret itself. */
+const NOT_SECRET_KEY = /(url|uri|endpoint|host|port|path|file|dir|type|mode|enabled|header|name|user(name)?|id|region|scope|scopes|method|env_var|_var|public[_-]?key)$/i;
 const PLACEHOLDER = /^(<.*>|\{.*\}|\[.*\]|x{4,}|\*{3,}|\.{3,}|your[-_ ].*|change[-_ ]?me|todo|placeholder|example|redacted|none|null|undefined|true|false|test|secret|token)$/i;
 /** True for `${VAR}`, `${env:VAR}`, `$VAR`, `%VAR%` and `{env:VAR}` references. */
 export function isReference(value) {

package/dist/sources.d.ts

@@ -9,6 +9,11 @@ export interface ScanOptions {
 export declare const CLIENT_NAMES: Record<ClientId, string>;
 /** Appends a key to a pointer, quoting keys that are not plain identifiers. */
 export declare function pointerJoin(base: string, key: string): string;
+/**
+ * Who besides the owner can read a file, given its mode and the modes of every folder above it.
+ * A group or other user needs read on the file and execute (traverse) on each folder.
+ */
+export declare function exposureOf(fileMode: number, ancestorModes: number[]): "group" | "others" | null;
 export interface Discovery {
     files: ConfigFile[];
     unreadable: {

package/dist/sources.js

@@ -1,6 +1,6 @@
 import { readFileSync, statSync } from "node:fs";
-import { join, resolve } from "node:path";
-import { parseConfig } from "./parse.js";
+import { dirname, join, resolve } from "node:path";
+import { ConfigParseError, parseConfig } from "./parse.js";
 export const CLIENT_NAMES = {
     "claude-code": "Claude Code",
     "claude-desktop": "Claude Desktop",
@@ -121,6 +121,42 @@ function claudeApprovals(file) {
     });
     return out;
 }
+/**
+ * Who besides the owner can read a file, given its mode and the modes of every folder above it.
+ * A group or other user needs read on the file and execute (traverse) on each folder.
+ */
+export function exposureOf(fileMode, ancestorModes) {
+    if (fileMode & 0o004 && ancestorModes.every((m) => m & 0o001))
+        return "others";
+    if (fileMode & 0o040 && ancestorModes.every((m) => m & 0o010))
+        return "group";
+    return null;
+}
+function ancestorModes(path) {
+    const modes = [];
+    let dir = dirname(path);
+    for (;;) {
+        try {
+            modes.push(statSync(dir).mode & 0o777);
+        }
+        catch {
+            // An unreadable folder is not traversable by us either; treat it as closed.
+            modes.push(0);
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return modes;
+        dir = parent;
+    }
+}
+/** A fixed description of a read failure; system messages are not passed through. */
+function readError(code) {
+    if (code === "EACCES" || code === "EPERM")
+        return "permission denied";
+    if (code === "EISDIR")
+        return "is a directory";
+    return code && /^E[A-Z]+$/.test(code) ? `could not read it (${code})` : "could not read it";
+}
 export function discover(opts) {
     const result = { files: [], unreadable: [], servers: [], approvals: [] };
     for (const c of candidates(opts)) {
@@ -133,7 +169,12 @@ export function discover(opts) {
             mode = opts.platform === "win32" ? undefined : stat.mode & 0o777;
             text = readFileSync(c.path, "utf8");
         }
-        catch {
+        catch (error) {
+            const code = error.code;
+            // Absent files are normal; anything else means a config exists that we could not check.
+            if (code !== "ENOENT" && code !== "ENOTDIR") {
+                result.unreadable.push({ client: c.client, path: c.path, error: readError(code) });
+            }
             continue;
         }
         let data;
@@ -141,10 +182,13 @@ export function discover(opts) {
             data = parseConfig(c.path, text);
         }
         catch (error) {
-            result.unreadable.push({ client: c.client, path: c.path, error: error.message });
+            // parseConfig's messages are fixed text plus a position, never file contents.
+            const message = error instanceof ConfigParseError ? error.message : "could not parse it";
+            result.unreadable.push({ client: c.client, path: c.path, error: message });
             continue;
         }
-        const file = { client: c.client, path: c.path, data, mode };
+        const exposure = mode === undefined ? undefined : exposureOf(mode, ancestorModes(c.path));
+        const file = { client: c.client, path: c.path, data, mode, exposure };
         result.files.push(file);
         if (!isObject(data))
             continue;

package/dist/types.d.ts

@@ -1,4 +1,5 @@
-export type Severity = "high" | "medium" | "low";
+/** `info` findings are context only and do not affect the score. */
+export type Severity = "high" | "medium" | "low" | "info";
 export type ClientId = "claude-code" | "claude-desktop" | "cursor" | "codex" | "vscode" | "windsurf" | "gemini" | "cline";
 export interface Location {
     /** Absolute path of the config file. */
@@ -13,6 +14,8 @@ export interface ConfigFile {
     data: unknown;
     /** Unix permission bits, when available. */
     mode?: number;
+    /** Who besides the owner can read the file, counting the folders above it. */
+    exposure?: "group" | "others" | null;
 }
 export interface ServerEntry {
     client: ClientId;
@@ -44,13 +47,18 @@ export interface Finding {
     detail: string;
     fix: string;
     locations: Location[];
+    /** Points this finding takes off the score; repeats of one root cause count once. */
+    weight: number;
 }
 export interface AuditResult {
     files: {
         client: ClientId;
         path: string;
     }[];
-    /** Files that exist but could not be parsed. */
+    /**
+     * Files that exist but could not be read or parsed. `error` is a fixed description with at most
+     * a line and column, for example `invalid TOML at line 3, column 12`; it never quotes the file.
+     */
     unreadable: {
         client: ClientId;
         path: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolstile",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Audit the MCP server configs your AI agents use for plaintext secrets, unpinned packages, auto-approved tools and duplicated setups. Local and read-only.",
   "keywords": [
     "mcp",
@@ -37,8 +37,8 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json && chmod +x dist/cli.js",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "prepublishOnly": "pnpm typecheck && pnpm build && pnpm test"
+    "test": "pnpm build && vitest run",
+    "prepublishOnly": "pnpm typecheck && pnpm test"
   },
   "dependencies": {
     "smol-toml": "^1.9.1"