feat: expose envsitter match and scan tools

Adds safe matching/scanning endpoints so workflows can validate secrets without reading .env files.

CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## Unreleased
+
+### Added
+
+- `envsitter_match`: safe boolean matching for `.env` keys (single key, bulk keys, or all keys) with support for the EnvSitter match operators.
+- `envsitter_match_by_key`: safe candidates-by-key matching (returns booleans only).
+- `envsitter_scan`: safe shape scanning (`jwt`, `url`, `base64`) without returning values.
+- `envsitter_keys.filterRegex`: optional regex filter for key listing.
+
+### Changed
+
+- Bumped `envsitter` dependency to `^0.0.2`.

index.ts

@@ -31,6 +31,51 @@ function stripAtPrefix(input: string): string {
     return input.trim().replace(/^@+/, "");
 }
 
+function parseUserRegExp(input: string): RegExp {
+    const trimmed = input.trim();
+    if (!trimmed.startsWith("/")) return new RegExp(trimmed);
+
+    let lastSlashIndex = -1;
+    for (let i = trimmed.length - 1; i >= 1; i -= 1) {
+        if (trimmed[i] !== "/") continue;
+
+        let backslashCount = 0;
+        for (let j = i - 1; j >= 0 && trimmed[j] === "\\"; j -= 1) {
+            backslashCount += 1;
+        }
+
+        const isEscaped = backslashCount % 2 === 1;
+        if (!isEscaped) {
+            lastSlashIndex = i;
+            break;
+        }
+    }
+
+    if (lastSlashIndex === -1) {
+        throw new Error("Invalid regex literal; expected a closing `/`.");
+    }
+
+    const body = trimmed.slice(1, lastSlashIndex);
+    const flags = trimmed.slice(lastSlashIndex + 1);
+    if (!/^[a-z]*$/.test(flags)) {
+        throw new Error("Invalid regex literal flags; expected only letters (e.g. `/abc/i`).");
+    }
+
+    return new RegExp(body, flags);
+}
+
+function resolveCandidate(params: { candidate?: string; candidateEnvVar?: string }): string {
+    if (typeof params.candidate === "string" && params.candidate.length > 0) return params.candidate;
+
+    if (typeof params.candidateEnvVar === "string" && params.candidateEnvVar.length > 0) {
+        const value = process.env[params.candidateEnvVar];
+        if (typeof value === "string" && value.length > 0) return value;
+        throw new Error(`Env var \`${params.candidateEnvVar}\` was not set.`);
+    }
+
+    throw new Error("Candidate is required for this operation. Provide `candidate` or `candidateEnvVar`.");
+}
+
 function getFilePathFromArgs(args: unknown): string | undefined {
     if (!args || typeof args !== "object") return;
     const record = args as Record<string, unknown>;
@@ -68,6 +113,20 @@ function resolveDotEnvPath(params: {
 export const EnvSitterGuard: Plugin = async ({ client, directory, worktree }) => {
     let lastToastAt = 0;
 
+    const matchOps = [
+        "exists",
+        "is_empty",
+        "is_equal",
+        "partial_match_prefix",
+        "partial_match_suffix",
+        "partial_match_regex",
+        "is_number",
+        "is_boolean",
+        "is_string",
+    ] as const;
+
+    const scanDetections = ["jwt", "url", "base64"] as const;
+
     async function notifyBlocked(action: string): Promise<void> {
         const now = Date.now();
         if (now - lastToastAt < 5000) return;
@@ -81,6 +140,8 @@ export const EnvSitterGuard: Plugin = async ({ client, directory, worktree }) =>
                     `${action} of sensitive env files is blocked. Use EnvSitter instead (never prints values):\n` +
                     "- envsitter_keys { filePath: '.env' }\n" +
                     "- envsitter_fingerprint { filePath: '.env', key: 'SOME_KEY' }\n" +
+                    "- envsitter_match { filePath: '.env', key: 'SOME_KEY', op: 'exists' }\n" +
+                    "- envsitter_scan { filePath: '.env', detect: ['jwt','url'] }\n" +
                     "(CLI: `npx envsitter keys --file .env`) ",
             },
         });
@@ -98,6 +159,7 @@ export const EnvSitterGuard: Plugin = async ({ client, directory, worktree }) =>
                 description: "List keys in a .env file (never returns values).",
                 args: {
                     filePath: tool.schema.string().optional(),
+                    filterRegex: tool.schema.string().optional(),
                 },
                 async execute(args) {
                     const resolved = resolveDotEnvPath({
@@ -107,7 +169,13 @@ export const EnvSitterGuard: Plugin = async ({ client, directory, worktree }) =>
                     });
 
                     const es = EnvSitter.fromDotenvFile(resolved.absolutePath);
-                    const keys = await es.listKeys();
+                    const keys = await es.listKeys(
+                        args.filterRegex
+                            ? {
+                                  filter: parseUserRegExp(args.filterRegex),
+                              }
+                            : undefined,
+                    );
 
                     return JSON.stringify({ file: resolved.displayPath, keys }, null, 2);
                 },
@@ -131,6 +199,175 @@ export const EnvSitterGuard: Plugin = async ({ client, directory, worktree }) =>
                     return JSON.stringify({ file: resolved.displayPath, key: args.key, result }, null, 2);
                 },
             }),
+            envsitter_match: tool({
+                description:
+                    "Match key values without printing them. Supports existence/shape checks and outside-in candidate matching.",
+                args: {
+                    filePath: tool.schema.string().optional(),
+                    op: tool.schema.enum(matchOps).optional(),
+                    key: tool.schema.string().optional(),
+                    keys: tool.schema.array(tool.schema.string()).optional(),
+                    allKeys: tool.schema.boolean().optional(),
+                    candidate: tool.schema.string().optional(),
+                    candidateEnvVar: tool.schema.string().optional(),
+                },
+                async execute(args) {
+                    const resolved = resolveDotEnvPath({
+                        worktree,
+                        directory,
+                        filePath: args.filePath ?? ".env",
+                    });
+
+                    const op = args.op ?? "is_equal";
+                    const es = EnvSitter.fromDotenvFile(resolved.absolutePath);
+
+                    const matcher = (() => {
+                        if (op === "exists") return { op } as const;
+                        if (op === "is_empty") return { op } as const;
+                        if (op === "is_number") return { op } as const;
+                        if (op === "is_boolean") return { op } as const;
+                        if (op === "is_string") return { op } as const;
+
+                        const candidate = resolveCandidate({
+                            candidate: args.candidate,
+                            candidateEnvVar: args.candidateEnvVar,
+                        });
+
+                        if (op === "is_equal") {
+                            return { op, candidate } as const;
+                        }
+
+                        if (op === "partial_match_prefix") {
+                            return { op, prefix: candidate } as const;
+                        }
+
+                        if (op === "partial_match_suffix") {
+                            return { op, suffix: candidate } as const;
+                        }
+
+                        if (op === "partial_match_regex") {
+                            return { op, regex: parseUserRegExp(candidate) } as const;
+                        }
+
+                        throw new Error(`Unsupported op: ${op}`);
+                    })();
+
+                    const key = args.key;
+                    const keys = args.keys;
+                    const allKeys = args.allKeys === true;
+
+                    const selectorCount =
+                        Number(typeof key === "string") + Number(Array.isArray(keys) && keys.length > 0) + Number(allKeys);
+                    if (selectorCount !== 1) {
+                        throw new Error("Provide exactly one of: `key`, `keys`, or `allKeys: true`. ");
+                    }
+
+                    if (typeof key === "string") {
+                        const match = await es.matchKey(key, matcher);
+                        return JSON.stringify({ file: resolved.displayPath, key, op: matcher.op, match }, null, 2);
+                    }
+
+                    if (Array.isArray(keys) && keys.length > 0) {
+                        const matches = await es.matchKeyBulk(keys, matcher);
+                        return JSON.stringify({ file: resolved.displayPath, op: matcher.op, matches }, null, 2);
+                    }
+
+                    const matches = await es.matchKeyAll(matcher);
+                    return JSON.stringify({ file: resolved.displayPath, op: matcher.op, matches }, null, 2);
+                },
+            }),
+            envsitter_match_by_key: tool({
+                description: "Bulk match candidates-by-key without printing values (returns booleans only).",
+                args: {
+                    filePath: tool.schema.string().optional(),
+                    candidatesByKey: tool.schema.record(tool.schema.string(), tool.schema.string()).optional(),
+                    candidatesByKeyJson: tool.schema.string().optional(),
+                    candidatesByKeyEnvVar: tool.schema.string().optional(),
+                },
+                async execute(args) {
+                    const resolved = resolveDotEnvPath({
+                        worktree,
+                        directory,
+                        filePath: args.filePath ?? ".env",
+                    });
+
+                    const fromRecord = args.candidatesByKey;
+                    const fromJson = args.candidatesByKeyJson;
+                    const fromEnvVar = args.candidatesByKeyEnvVar;
+
+                    const selectorCount = Number(!!fromRecord) + Number(!!fromJson) + Number(!!fromEnvVar);
+                    if (selectorCount !== 1) {
+                        throw new Error(
+                            "Provide exactly one of: `candidatesByKey`, `candidatesByKeyJson`, or `candidatesByKeyEnvVar`.",
+                        );
+                    }
+
+                    let candidatesByKey: Record<string, string>;
+
+                    if (fromRecord) {
+                        candidatesByKey = fromRecord;
+                    } else {
+                        const json =
+                            typeof fromJson === "string"
+                                ? fromJson
+                                : (() => {
+                                      const envVarName = fromEnvVar as string;
+                                      const value = process.env[envVarName];
+                                      if (typeof value !== "string") throw new Error(`Env var \`${envVarName}\` was not set.`);
+                                      return value;
+                                  })();
+
+                        let parsed: unknown;
+                        try {
+                            parsed = JSON.parse(json);
+                        } catch {
+                            throw new Error("Invalid candidates JSON; expected an object mapping key -> candidate string.");
+                        }
+
+                        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                            throw new Error("Invalid candidates JSON; expected an object mapping key -> candidate string.");
+                        }
+
+                        const record = parsed as Record<string, unknown>;
+                        const normalized: Record<string, string> = {};
+                        for (const [key, value] of Object.entries(record)) {
+                            if (typeof value !== "string") {
+                                throw new Error("Invalid candidates JSON; expected every value to be a string.");
+                            }
+                            normalized[key] = value;
+                        }
+                        candidatesByKey = normalized;
+                    }
+
+                    const es = EnvSitter.fromDotenvFile(resolved.absolutePath);
+                    const matches = await es.matchCandidatesByKey(candidatesByKey);
+
+                    return JSON.stringify({ file: resolved.displayPath, matches }, null, 2);
+                },
+            }),
+            envsitter_scan: tool({
+                description: "Scan value shapes (jwt/url/base64) without printing values.",
+                args: {
+                    filePath: tool.schema.string().optional(),
+                    detect: tool.schema.array(tool.schema.enum(scanDetections)).optional(),
+                    keysFilterRegex: tool.schema.string().optional(),
+                },
+                async execute(args) {
+                    const resolved = resolveDotEnvPath({
+                        worktree,
+                        directory,
+                        filePath: args.filePath ?? ".env",
+                    });
+
+                    const es = EnvSitter.fromDotenvFile(resolved.absolutePath);
+                    const findings = await es.scan({
+                        detect: args.detect,
+                        keysFilter: args.keysFilterRegex ? parseUserRegExp(args.keysFilterRegex) : undefined,
+                    });
+
+                    return JSON.stringify({ file: resolved.displayPath, findings }, null, 2);
+                },
+            }),
         },
         "tool.execute.before": async (input, output) => {
             const filePath = getFilePathFromArgs(output.args);

package-lock.json

@@ -7,11 +7,12 @@
     "": {
       "name": "envsitter-guard",
       "version": "0.0.1",
+      "license": "MIT",
       "dependencies": {
-        "envsitter": "*"
+        "@opencode-ai/plugin": "^1.1.14",
+        "envsitter": "^0.0.2"
       },
       "devDependencies": {
-        "@opencode-ai/plugin": "*",
         "@types/node": "*",
         "husky": "^9.1.7",
         "typescript": "*"
@@ -21,7 +22,6 @@
       "version": "1.1.14",
       "resolved": "https://registry.npmjs.org/@opencode-ai/plugin/-/plugin-1.1.14.tgz",
       "integrity": "sha512-tfF4bEjeF7Gm0W0ViQUhzy77AaZfRxQ/kcPa7/Bc/YM9HddzjEqz0wOJ6ePG8UdUYc0dkKSJOJVhapUbAn/tOw==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@opencode-ai/sdk": "1.1.14",
@@ -32,7 +32,6 @@
       "version": "1.1.14",
       "resolved": "https://registry.npmjs.org/@opencode-ai/sdk/-/sdk-1.1.14.tgz",
       "integrity": "sha512-PJFu2QPxnOk0VZzlPm+IxhD1wSA41PJyCG6gkxAMI767gfAO96A0ukJJN7VK/gO6MbxLF5oTFaxBX5rAGcBRVw==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/@types/node": {
@@ -46,9 +45,9 @@
       }
     },
     "node_modules/envsitter": {
-      "version": "0.0.1",
-      "resolved": "https://registry.npmjs.org/envsitter/-/envsitter-0.0.1.tgz",
-      "integrity": "sha512-gDJ/ZMjD0z31MSpj88IiaHNdJVfzWpXANm4uLwUD1ScKtt3LaKZYir2nY+peJOBjZM9579d5y+rTIQD+kU4lIA==",
+      "version": "0.0.2",
+      "resolved": "https://registry.npmjs.org/envsitter/-/envsitter-0.0.2.tgz",
+      "integrity": "sha512-2rVcSQnRrDqk//2XM5c+M85YkNc6ljFgfMC4gBTvA/U21OUGB53zfANIEZZXfOcSVNmoRHVCGcogFHLHsBjd1w==",
       "license": "MIT",
       "bin": {
         "envsitter": "dist/cli.js"
@@ -95,7 +94,6 @@
       "version": "4.1.8",
       "resolved": "https://registry.npmjs.org/zod/-/zod-4.1.8.tgz",
       "integrity": "sha512-5R1P+WwQqmmMIEACyzSvo4JXHY5WiAFHRMg+zBZKgKS+Q1viRa0C1hmUKtHltoIFKtIdki3pRxkmpP74jnNYHQ==",
-      "dev": true,
       "license": "MIT",
       "funding": {
         "url": "https://github.com/sponsors/colinhacks"

package.json

@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@opencode-ai/plugin": "^1.1.14",
-    "envsitter": "^0.0.1"
+    "envsitter": "^0.0.2"
   },
   "devDependencies": {
     "@types/node": "*",

test/envsitter-guard.tools.test.ts

@@ -8,13 +8,48 @@ import type { PluginInput } from "@opencode-ai/plugin";
 
 import EnvSitterGuard from "../index.js";
 
+type MatchOp =
+    | "exists"
+    | "is_empty"
+    | "is_equal"
+    | "partial_match_prefix"
+    | "partial_match_suffix"
+    | "partial_match_regex"
+    | "is_number"
+    | "is_boolean"
+    | "is_string";
+
+type ScanDetection = "jwt" | "url" | "base64";
+
 type ToolApi = {
     envsitter_keys: {
-        execute: (args: { filePath?: string }) => Promise<string>;
+        execute: (args: { filePath?: string; filterRegex?: string }) => Promise<string>;
     };
     envsitter_fingerprint: {
         execute: (args: { filePath?: string; key: string }) => Promise<string>;
     };
+    envsitter_match: {
+        execute: (args: {
+            filePath?: string;
+            op?: MatchOp;
+            key?: string;
+            keys?: string[];
+            allKeys?: boolean;
+            candidate?: string;
+            candidateEnvVar?: string;
+        }) => Promise<string>;
+    };
+    envsitter_match_by_key: {
+        execute: (args: {
+            filePath?: string;
+            candidatesByKey?: Record<string, string>;
+            candidatesByKeyJson?: string;
+            candidatesByKeyEnvVar?: string;
+        }) => Promise<string>;
+    };
+    envsitter_scan: {
+        execute: (args: { filePath?: string; detect?: ScanDetection[]; keysFilterRegex?: string }) => Promise<string>;
+    };
 };
 
 async function createTmpDir(): Promise<string> {
@@ -22,6 +57,25 @@ async function createTmpDir(): Promise<string> {
     return dir;
 }
 
+async function withEnvVar<T>(name: string, value: string, fn: () => Promise<T>): Promise<T> {
+    const previous = process.env[name];
+    process.env[name] = value;
+
+    try {
+        return await fn();
+    } finally {
+        if (previous === undefined) {
+            delete process.env[name];
+        } else {
+            process.env[name] = previous;
+        }
+    }
+}
+
+async function withPepper<T>(fn: () => Promise<T>): Promise<T> {
+    return withEnvVar("ENVSITTER_PEPPER", "test-pepper", fn);
+}
+
 function createMinimalClient(): PluginInput["client"] {
     return {
         tui: {
@@ -51,6 +105,7 @@ async function getTools(params: { directory: string; worktree: string }): Promis
 }
 
 test("envsitter_keys lists keys without values", async () => {
+    await withPepper(async () => {
         const worktree = await createTmpDir();
         await fs.writeFile(path.join(worktree, ".env"), "FOO=bar\nBAZ=qux\n");
 
@@ -64,8 +119,23 @@ test("envsitter_keys lists keys without values", async () => {
         assert.equal(parsed.file, ".env");
         assert.deepEqual(parsed.keys.sort(), ["BAZ", "FOO"].sort());
     });
+});
+
+test("envsitter_keys supports filterRegex", async () => {
+    await withPepper(async () => {
+        const worktree = await createTmpDir();
+        await fs.writeFile(path.join(worktree, ".env"), "FOO=bar\nBAZ=qux\n");
+
+        const tools = await getTools({ directory: worktree, worktree });
+        const out = await tools.envsitter_keys.execute({ filePath: ".env", filterRegex: "/^FOO$/" });
+
+        const parsed = JSON.parse(out) as { keys: string[] };
+        assert.deepEqual(parsed.keys, ["FOO"]);
+    });
+});
 
 test("envsitter_fingerprint is deterministic and does not leak values", async () => {
+    await withPepper(async () => {
         const worktree = await createTmpDir();
         await fs.writeFile(path.join(worktree, ".env"), "DATABASE_URL=postgres://user:pass@host/db\n");
 
@@ -80,6 +150,113 @@ test("envsitter_fingerprint is deterministic and does not leak values", async ()
         assert.equal(parsed.file, ".env");
         assert.equal(parsed.key, "DATABASE_URL");
     });
+});
+
+test("envsitter_match supports exists", async () => {
+    await withPepper(async () => {
+        const worktree = await createTmpDir();
+        await fs.writeFile(path.join(worktree, ".env"), "FOO=bar\n");
+
+        const tools = await getTools({ directory: worktree, worktree });
+        const out = await tools.envsitter_match.execute({ filePath: ".env", key: "FOO", op: "exists" });
+
+        const parsed = JSON.parse(out) as { key: string; match: boolean };
+        assert.equal(parsed.key, "FOO");
+        assert.equal(parsed.match, true);
+    });
+});
+
+test("envsitter_match supports is_equal via candidateEnvVar", async () => {
+    await withPepper(async () => {
+        const worktree = await createTmpDir();
+        await fs.writeFile(path.join(worktree, ".env"), "FOO=bar\n");
+
+        await withEnvVar("ENVSITTER_TEST_CANDIDATE", "bar", async () => {
+            const tools = await getTools({ directory: worktree, worktree });
+            const out = await tools.envsitter_match.execute({
+                filePath: ".env",
+                key: "FOO",
+                op: "is_equal",
+                candidateEnvVar: "ENVSITTER_TEST_CANDIDATE",
+            });
+
+            assert.ok(!out.includes("bar"));
+
+            const parsed = JSON.parse(out) as { match: boolean };
+            assert.equal(parsed.match, true);
+        });
+    });
+});
+
+test("envsitter_match supports bulk keys", async () => {
+    await withPepper(async () => {
+        const worktree = await createTmpDir();
+        await fs.writeFile(path.join(worktree, ".env"), "FOO=bar\n");
+
+        const tools = await getTools({ directory: worktree, worktree });
+        const out = await tools.envsitter_match.execute({ filePath: ".env", keys: ["FOO", "BAZ"], op: "exists" });
+
+        const parsed = JSON.parse(out) as { matches: Array<{ key: string; match: boolean }> };
+        const byKey = new Map(parsed.matches.map((entry) => [entry.key, entry.match]));
+        assert.equal(byKey.get("FOO"), true);
+        assert.equal(byKey.get("BAZ"), false);
+    });
+});
+
+test("envsitter_match_by_key matches candidates without leaking values", async () => {
+    await withPepper(async () => {
+        const worktree = await createTmpDir();
+        await fs.writeFile(path.join(worktree, ".env"), "FOO=bar\nBAZ=qux\n");
+
+        const tools = await getTools({ directory: worktree, worktree });
+        const out = await tools.envsitter_match_by_key.execute({
+            filePath: ".env",
+            candidatesByKey: {
+                FOO: "bar",
+                BAZ: "nope",
+            },
+        });
+
+        assert.ok(!out.includes("bar"));
+        assert.ok(!out.includes("qux"));
+
+        const parsed = JSON.parse(out) as { matches: Array<{ key: string; match: boolean }> };
+        const byKey = new Map(parsed.matches.map((entry) => [entry.key, entry.match]));
+        assert.equal(byKey.get("FOO"), true);
+        assert.equal(byKey.get("BAZ"), false);
+    });
+});
+
+test("envsitter_scan detects shapes without leaking values", async () => {
+    await withPepper(async () => {
+        const worktree = await createTmpDir();
+        const jwt =
+            "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c";
+
+        await fs.writeFile(
+            path.join(worktree, ".env"),
+            [
+                `JWT_TOKEN=${jwt}`,
+                "SOME_URL=https://example.com",
+                "SOME_BASE64=SGVsbG8=",
+                "PLAIN=hello",
+            ].join("\n") + "\n",
+        );
+
+        const tools = await getTools({ directory: worktree, worktree });
+        const out = await tools.envsitter_scan.execute({ filePath: ".env", detect: ["jwt", "url", "base64"] });
+
+        assert.ok(!out.includes(jwt));
+        assert.ok(!out.includes("https://example.com"));
+
+        const parsed = JSON.parse(out) as { findings: Array<{ key: string; detections: string[] }> };
+        const byKey = new Map(parsed.findings.map((finding) => [finding.key, finding.detections]));
+
+        assert.ok(byKey.get("JWT_TOKEN")?.includes("jwt"));
+        assert.ok(byKey.get("SOME_URL")?.includes("url"));
+        assert.ok(byKey.get("SOME_BASE64")?.includes("base64"));
+    });
+});
 
 test("tool execution rejects paths outside worktree", async () => {
     const worktree = await createTmpDir();