boxpositron/envsitter-guard
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: expose envsitter match and scan tools

Browse Source 
Adds safe matching/scanning endpoints so workflows can validate secrets without reading .env files.
This commit is contained in:
David Ibia
2026-01-12 19:28:58 +01:00
parent 6020518fc7
commit b21d63cb7c
5 changed files with 456 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

217
test/envsitter-guard.tools.test.ts
View File

@@ -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,34 +105,157 @@ async function getTools(params: { directory: string; worktree: string }): Promis
}
test("envsitter_keys lists keys without values", async () => {
const worktree = await createTmpDir();
await fs.writeFile(path.join(worktree, ".env"), "FOO=bar\nBAZ=qux\n");
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" });
const tools = await getTools({ directory: worktree, worktree });
const out = await tools.envsitter_keys.execute({ filePath: ".env" });
assert.ok(!out.includes("bar"));
assert.ok(!out.includes("qux"));
assert.ok(!out.includes("bar"));
assert.ok(!out.includes("qux"));
const parsed = JSON.parse(out) as { file: string; keys: string[] };
assert.equal(parsed.file, ".env");
assert.deepEqual(parsed.keys.sort(), ["BAZ", "FOO"].sort());
const parsed = JSON.parse(out) as { file: string; keys: string[] };
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 () => {
const worktree = await createTmpDir();
await fs.writeFile(path.join(worktree, ".env"), "DATABASE_URL=postgres://user:pass@host/db\n");
await withPepper(async () => {
const worktree = await createTmpDir();
await fs.writeFile(path.join(worktree, ".env"), "DATABASE_URL=postgres://user:pass@host/db\n");
const tools = await getTools({ directory: worktree, worktree });
const out1 = await tools.envsitter_fingerprint.execute({ filePath: ".env", key: "DATABASE_URL" });
const out2 = await tools.envsitter_fingerprint.execute({ filePath: ".env", key: "DATABASE_URL" });
const tools = await getTools({ directory: worktree, worktree });
const out1 = await tools.envsitter_fingerprint.execute({ filePath: ".env", key: "DATABASE_URL" });
const out2 = await tools.envsitter_fingerprint.execute({ filePath: ".env", key: "DATABASE_URL" });
assert.ok(!out1.includes("postgres://"));
assert.equal(out1, out2);
assert.ok(!out1.includes("postgres://"));
assert.equal(out1, out2);
const parsed = JSON.parse(out1) as { file: string; key: string; result: unknown };
assert.equal(parsed.file, ".env");
assert.equal(parsed.key, "DATABASE_URL");
const parsed = JSON.parse(out1) as { file: string; key: string; result: unknown };
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 () => {