diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..746bedc --- /dev/null +++ b/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`. diff --git a/index.ts b/index.ts index ad27605..a952f3b 100644 --- a/index.ts +++ b/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; @@ -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 { 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; + + 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; + const normalized: Record = {}; + 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); diff --git a/package-lock.json b/package-lock.json index 4b17cc9..06d4b93 100644 --- a/package-lock.json +++ b/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" diff --git a/package.json b/package.json index 7d2da0b..47bc33a 100644 --- a/package.json +++ b/package.json @@ -27,7 +27,7 @@ }, "dependencies": { "@opencode-ai/plugin": "^1.1.14", - "envsitter": "^0.0.1" + "envsitter": "^0.0.2" }, "devDependencies": { "@types/node": "*", diff --git a/test/envsitter-guard.tools.test.ts b/test/envsitter-guard.tools.test.ts index 2a663cf..99c4764 100644 --- a/test/envsitter-guard.tools.test.ts +++ b/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; + execute: (args: { filePath?: string; filterRegex?: string }) => Promise; }; envsitter_fingerprint: { execute: (args: { filePath?: string; key: string }) => Promise; }; + envsitter_match: { + execute: (args: { + filePath?: string; + op?: MatchOp; + key?: string; + keys?: string[]; + allKeys?: boolean; + candidate?: string; + candidateEnvVar?: string; + }) => Promise; + }; + envsitter_match_by_key: { + execute: (args: { + filePath?: string; + candidatesByKey?: Record; + candidatesByKeyJson?: string; + candidatesByKeyEnvVar?: string; + }) => Promise; + }; + envsitter_scan: { + execute: (args: { filePath?: string; detect?: ScanDetection[]; keysFilterRegex?: string }) => Promise; + }; }; async function createTmpDir(): Promise { @@ -22,6 +57,25 @@ async function createTmpDir(): Promise { return dir; } +async function withEnvVar(name: string, value: string, fn: () => Promise): Promise { + 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(fn: () => Promise): Promise { + 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 () => {