import type { Plugin } from "@opencode-ai/plugin"; import { tool } from "@opencode-ai/plugin/tool"; import { EnvSitter, annotateEnvFile, copyEnvFileKeys, formatEnvFile, validateEnvFile } from "envsitter"; import path from "node:path"; function normalizePath(input: string): string { return input.replace(/\\/g, "/"); } function isDotEnvExamplePath(input: string): boolean { return /(^|\/)\.env\.example$/.test(normalizePath(input)); } function isSensitiveDotEnvPath(input: string): boolean { const normalized = normalizePath(input); if (isDotEnvExamplePath(normalized)) return false; return /(^|\/)\.env($|\.)/.test(normalized); } function isDotEnvishPath(input: string): boolean { const normalized = normalizePath(input); return isDotEnvExamplePath(normalized) || isSensitiveDotEnvPath(normalized); } function isEnvSitterPepperPath(input: string): boolean { const normalized = normalizePath(input); return /(^|\/)\.envsitter\/pepper$/.test(normalized); } 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; const candidates: Array = [record.filePath, record.path, record.file_path]; const found = candidates.find((value) => typeof value === "string") as string | undefined; return found ? stripAtPrefix(found) : undefined; } function resolveDotEnvPath(params: { worktree: string; directory: string; filePath: string; }): { absolutePath: string; displayPath: string } { const normalized = normalizePath(params.filePath); if (isEnvSitterPepperPath(normalized)) { throw new Error("Access to `.envsitter/pepper` is blocked."); } if (!isDotEnvishPath(normalized)) { throw new Error("Only `.env`-style paths are allowed (e.g. `.env`, `.env.local`, `.env.example`)."); } const absolutePath = path.resolve(params.directory, normalized); const relativeToWorktree = path.relative(params.worktree, absolutePath); if (relativeToWorktree.startsWith("..") || path.isAbsolute(relativeToWorktree)) { throw new Error("EnvSitter tools only operate on files inside the current project."); } return { absolutePath, displayPath: relativeToWorktree }; } 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; lastToastAt = now; await client.tui.showToast({ body: { title: "Blocked sensitive .env access", variant: "warning", message: `${action} of \`.env*\` is blocked to prevent secret leaks. ` + "Use EnvSitter tools instead (never prints values): envsitter_keys, envsitter_fingerprint, envsitter_match, envsitter_scan, envsitter_validate, envsitter_format, envsitter_annotate, envsitter_copy.", }, }); } return { tool: { envsitter_keys: tool({ 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({ worktree, directory, filePath: args.filePath ?? ".env", }); const es = EnvSitter.fromDotenvFile(resolved.absolutePath); const keys = await es.listKeys( args.filterRegex ? { filter: parseUserRegExp(args.filterRegex), } : undefined, ); return JSON.stringify({ file: resolved.displayPath, keys }, null, 2); }, }), envsitter_fingerprint: tool({ description: "Compute a deterministic fingerprint for a single key (never returns the value).", args: { filePath: tool.schema.string().optional(), key: tool.schema.string(), }, async execute(args) { const resolved = resolveDotEnvPath({ worktree, directory, filePath: args.filePath ?? ".env", }); const es = EnvSitter.fromDotenvFile(resolved.absolutePath); const result = await es.fingerprintKey(args.key); 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); let isEqualCandidate: string | undefined; 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") { isEqualCandidate = candidate; 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 = matcher.op === "is_equal" && typeof isEqualCandidate === "string" ? await es.matchCandidate(key, isEqualCandidate) : 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 = matcher.op === "is_equal" && typeof isEqualCandidate === "string" ? await es.matchCandidateBulk(keys, isEqualCandidate) : await es.matchKeyBulk(keys, matcher); return JSON.stringify({ file: resolved.displayPath, op: matcher.op, matches }, null, 2); } const matches = matcher.op === "is_equal" && typeof isEqualCandidate === "string" ? await es.matchCandidateAll(isEqualCandidate) : 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); }, }), envsitter_validate: tool({ description: "Validate dotenv syntax (never returns values).", args: { filePath: tool.schema.string().optional(), }, async execute(args) { const resolved = resolveDotEnvPath({ worktree, directory, filePath: args.filePath ?? ".env", }); const result = await validateEnvFile(resolved.absolutePath); return JSON.stringify({ file: resolved.displayPath, ok: result.ok, issues: result.issues }, null, 2); }, }), envsitter_copy: tool({ description: "Copy keys between dotenv files safely (no values in output). Dry-run unless `write: true`.", args: { from: tool.schema.string(), to: tool.schema.string(), keys: tool.schema.array(tool.schema.string()).optional(), includeRegex: tool.schema.string().optional(), excludeRegex: tool.schema.string().optional(), rename: tool.schema.string().optional(), onConflict: tool.schema.enum(["error", "skip", "overwrite"] as const).optional(), write: tool.schema.boolean().optional(), }, async execute(args) { const resolvedFrom = resolveDotEnvPath({ worktree, directory, filePath: args.from, }); const resolvedTo = resolveDotEnvPath({ worktree, directory, filePath: args.to, }); if (typeof args.rename === "string" && args.rename.trim().length === 0) { throw new Error("Invalid `rename`; expected a non-empty string like `A=B,C=D`. "); } const result = await copyEnvFileKeys({ from: resolvedFrom.absolutePath, to: resolvedTo.absolutePath, keys: Array.isArray(args.keys) && args.keys.length > 0 ? args.keys : undefined, include: args.includeRegex ? parseUserRegExp(args.includeRegex) : undefined, exclude: args.excludeRegex ? parseUserRegExp(args.excludeRegex) : undefined, rename: args.rename, onConflict: args.onConflict, write: args.write === true, }); return JSON.stringify( { from: resolvedFrom.displayPath, to: resolvedTo.displayPath, onConflict: result.onConflict, willWrite: result.willWrite, wrote: result.wrote, hasChanges: result.hasChanges, issues: result.issues, plan: result.plan, }, null, 2, ); }, }), envsitter_format: tool({ description: "Format/reorder a dotenv file (no values in output). Dry-run unless `write: true`.", args: { filePath: tool.schema.string().optional(), mode: tool.schema.enum(["sections", "global"] as const).optional(), sort: tool.schema.enum(["alpha", "none"] as const).optional(), write: tool.schema.boolean().optional(), }, async execute(args) { const resolved = resolveDotEnvPath({ worktree, directory, filePath: args.filePath ?? ".env", }); const result = await formatEnvFile({ file: resolved.absolutePath, mode: args.mode, sort: args.sort, write: args.write === true, }); return JSON.stringify( { file: resolved.displayPath, mode: result.mode, sort: result.sort, willWrite: result.willWrite, wrote: result.wrote, hasChanges: result.hasChanges, issues: result.issues, }, null, 2, ); }, }), envsitter_reorder: tool({ description: "Alias for envsitter_format.", args: { filePath: tool.schema.string().optional(), mode: tool.schema.enum(["sections", "global"] as const).optional(), sort: tool.schema.enum(["alpha", "none"] as const).optional(), write: tool.schema.boolean().optional(), }, async execute(args) { const resolved = resolveDotEnvPath({ worktree, directory, filePath: args.filePath ?? ".env", }); const result = await formatEnvFile({ file: resolved.absolutePath, mode: args.mode, sort: args.sort, write: args.write === true, }); return JSON.stringify( { file: resolved.displayPath, mode: result.mode, sort: result.sort, willWrite: result.willWrite, wrote: result.wrote, hasChanges: result.hasChanges, issues: result.issues, }, null, 2, ); }, }), envsitter_annotate: tool({ description: "Annotate a dotenv key with a comment (no values in output). Dry-run unless `write: true`.", args: { filePath: tool.schema.string().optional(), key: tool.schema.string(), comment: tool.schema.string(), line: tool.schema.number().int().optional(), write: tool.schema.boolean().optional(), }, async execute(args) { const resolved = resolveDotEnvPath({ worktree, directory, filePath: args.filePath ?? ".env", }); if (args.comment.trim().length === 0) { throw new Error("Comment must be a non-empty string."); } const result = await annotateEnvFile({ file: resolved.absolutePath, key: args.key, comment: args.comment, line: args.line, write: args.write === true, }); return JSON.stringify( { file: resolved.displayPath, key: result.key, willWrite: result.willWrite, wrote: result.wrote, hasChanges: result.hasChanges, issues: result.issues, plan: result.plan, }, null, 2, ); }, }), }, "tool.execute.before": async (input, output) => { const filePath = getFilePathFromArgs(output.args); if (!filePath) return; if (!isSensitiveDotEnvPath(filePath) && !isEnvSitterPepperPath(filePath)) return; if (input.tool === "read") { await notifyBlocked("Reading"); throw new Error( "Reading `.env*` is blocked. Use EnvSitter tools instead: envsitter_keys / envsitter_fingerprint (never prints values)." ); } if (input.tool === "edit" || input.tool === "write" || input.tool === "patch" || input.tool === "multiedit") { await notifyBlocked("Editing"); throw new Error("Editing `.env*` and `.envsitter/pepper` via tools is blocked."); } }, }; }; export default EnvSitterGuard;