@blogic-cz/agent-tools 1.4.1 → 1.5.0

package/src/config/loader.ts

@@ -11,6 +11,7 @@ const CliToolOverrideSchema = Schema.Struct({
 });
 
 const CredentialGuardConfigSchema = Schema.Struct({
+  allowedEnvironmentVariables: Schema.optionalKey(Schema.Array(Schema.String)),
   additionalBlockedPaths: Schema.optionalKey(Schema.Array(Schema.String)),
   additionalAllowedPaths: Schema.optionalKey(Schema.Array(Schema.String)),
   additionalBlockedCliTools: Schema.optionalKey(Schema.Array(CliToolOverrideSchema)),

package/src/config/types.ts

@@ -185,6 +185,8 @@ export type CliToolOverride = {
 
 /** Credential guard config - merged with built-in defaults */
 export type CredentialGuardConfig = {
+  /** Exact, case-sensitive names approved for static printenv reads. Empty by default. */
+  allowedEnvironmentVariables?: string[];
   additionalBlockedPaths?: string[];
   additionalAllowedPaths?: string[];
   additionalBlockedCliTools?: CliToolOverride[];

package/src/credential-guard/claude-hook.ts

@@ -10,7 +10,9 @@
  *     "command": "bun node_modules/@blogic-cz/agent-tools/src/credential-guard/claude-hook.ts" }] }] } }
  */
 
-import { handleToolExecuteBefore } from "./index";
+import { loadConfig } from "#config/loader";
+
+import { createCredentialGuard } from "./index";
 
 const stdin = await Bun.stdin.text();
 
@@ -20,7 +22,11 @@ try {
     tool_input?: Record<string, unknown>;
   } = JSON.parse(stdin);
 
-  handleToolExecuteBefore({ tool: data.tool_name }, { args: data.tool_input ?? {} });
+  const config = await loadConfig();
+  createCredentialGuard(config?.credentialGuard).handleToolExecuteBefore(
+    { tool: data.tool_name },
+    { args: data.tool_input ?? {} },
+  );
 } catch (error: unknown) {
   const message = error instanceof Error ? error.message : String(error);
   process.stderr.write(message);

package/src/credential-guard/index.ts

@@ -143,8 +143,6 @@ const SECRET_PATTERNS = [
  * Dangerous bash patterns that might expose secrets.
  */
 const DEFAULT_DANGEROUS_BASH_PATTERNS: RegExp[] = [
-  /printenv/i,
-  /(?:^|&&|\||;)\s*env(?:\s|$)/i,
   /\bcat\s+\S*\.env/i,
   /\bcat\s+\S*\.pem/i,
   /\bcat\s+\S*\.key/i,
@@ -245,6 +243,201 @@ function escapeRegex(s: string): string {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+/** Static shell words only. Never expand variables or execute a command. */
+function parseStaticShellCommands(
+  command: string,
+): { pipelines: string[][][] } | "brace-expansion" | undefined {
+  const pipelines: string[][][] = [];
+  let commands: string[][] = [];
+  let argv: string[] = [];
+  let word = "";
+  let started = false;
+  let quote: "'" | '"' | undefined;
+
+  const finishWord = () => {
+    if (started) argv.push(word);
+    word = "";
+    started = false;
+  };
+  const finishCommand = () => {
+    finishWord();
+    if (argv.length) commands.push(argv);
+    argv = [];
+  };
+  const finishPipeline = () => {
+    finishCommand();
+    if (commands.length) pipelines.push(commands);
+    commands = [];
+  };
+
+  for (let i = 0; i < command.length; i++) {
+    const char = command.charAt(i);
+    if (quote === "'") {
+      if (char === quote) quote = undefined;
+      else word += char;
+    } else if (char === "\\") {
+      const next = command[++i];
+      if (next === undefined || next === "\n" || next === "\r") return undefined;
+      if (quote === '"' && !/[\\$`"]/.test(next)) word += "\\";
+      word += next;
+      started = true;
+    } else if (char === "$" || char === "`") {
+      return undefined;
+    } else if (quote === '"') {
+      if (char === quote) quote = undefined;
+      else word += char;
+    } else if (char === "'" || char === '"') {
+      quote = char;
+      started = true;
+    } else if (char === "{" && /^\{[^{}]*(?:,|\.\.)[^{}]*\}/.test(command.slice(i))) {
+      return "brace-expansion";
+    } else if (/[<>()]/.test(char) || (char === "#" && !started)) {
+      return undefined;
+    } else if (char === "|" && command[i - 1] !== "|" && command[i + 1] !== "|") {
+      finishCommand();
+      if (command[i + 1] === "&") i++;
+    } else if (/[;&|\r\n]/.test(char)) {
+      finishPipeline();
+    } else if (/\s/.test(char)) {
+      finishWord();
+    } else {
+      word += char;
+      started = true;
+    }
+  }
+
+  if (quote) return undefined;
+  finishPipeline();
+  return { pipelines };
+}
+
+function mentionsEnvironmentRead(text: string): boolean {
+  return /printenv|\benv\b/i.test(text.replace(/['"\\]/g, ""));
+}
+
+function hasBraceExpansion(text: string): boolean {
+  return /\{[^{}]*(?:,|\.\.)[^{}]*\}/.test(text);
+}
+
+function unwrapStaticCommand(words: string[]): string[] {
+  const argv = [...words];
+  const executable = () => argv[0]?.split("/").at(-1);
+  while (executable() === "rtk" || executable() === "command") {
+    const wrapper = executable();
+    argv.shift();
+    if (wrapper === "rtk" && argv[0] === "proxy") argv.shift();
+    if (wrapper === "command" && argv[0] === "--") argv.shift();
+  }
+  return argv;
+}
+
+function isAllowedEnvironmentRead(argv: string[], allowedNames: Set<string>): boolean {
+  if (argv[0]?.split("/").at(-1) !== "printenv") return false;
+  const args = argv.slice(1);
+  if (args[0] === "--") args.shift();
+  return args.length > 0 && args.every((name) => allowedNames.has(name));
+}
+
+function hasExecutionOption(args: string[], longOptions: string[], shortOption?: string): boolean {
+  return args.some((arg) => {
+    const flag = arg.split("=", 1)[0] ?? "";
+    if (flag.startsWith("--") && flag.length > 2) {
+      // Git supports long-option abbreviations. Refuse ambiguous prefixes too.
+      return longOptions.some((option) => option.startsWith(flag.slice(2)));
+    }
+    return shortOption !== undefined && /^-[^-]/.test(flag) && flag.includes(shortOption);
+  });
+}
+
+function isPassiveTextCommand(argv: string[]): boolean {
+  const name = argv[0]?.split("/").at(-1) ?? "";
+  const args = argv.slice(1);
+  // These commands consume literal text. Execution options are not exceptions.
+  if (["echo", "printf", "grep", "head"].includes(name)) {
+    return true;
+  }
+  if (name === "rg") return !hasExecutionOption(args, ["pre", "hostname-bin"]);
+  return (
+    name === "git" &&
+    args[0] === "grep" &&
+    !hasExecutionOption(args, ["open-files-in-pager", "textconv"], "O")
+  );
+}
+
+function hasStaticEnvironmentRead(argv: string[], allowedNames: Set<string>): boolean {
+  const name = argv[0]?.split("/").at(-1);
+  if (name === "printenv") return !isAllowedEnvironmentRead(argv, allowedNames);
+  if (name === "env") return true;
+  if (isPassiveTextCommand(argv)) return false;
+  if (
+    argv.some((arg) =>
+      ["sh", "bash", "zsh", "dash", "ksh", "fish", "csh", "tcsh", "eval"].includes(
+        arg.split("/").at(-1) ?? "",
+      ),
+    ) &&
+    hasBraceExpansion(argv.slice(1).join(" "))
+  ) {
+    return true;
+  }
+  return mentionsEnvironmentRead(argv.join(" "));
+}
+
+function hasEnvironmentRead(command: string, allowedNames: Set<string>): boolean {
+  if (isLiteralTextWrite(command)) return false;
+  // ponytail: complex shell syntax stays conservative; use a shell AST if more exceptions are needed.
+  const parsed = parseStaticShellCommands(command);
+  if (parsed === "brace-expansion") return true;
+  if (!parsed) return mentionsEnvironmentRead(command) || hasBraceExpansion(command);
+  const pipelines = parsed.pipelines.map((commands) => commands.map(unwrapStaticCommand));
+  const unwrapped = pipelines.flat();
+  if (unwrapped.some((argv) => hasStaticEnvironmentRead(argv, allowedNames))) return true;
+
+  // A literal producer can feed executable text to a shell, xargs, or an unknown consumer.
+  return pipelines.some(
+    (pipeline) =>
+      pipeline.length > 1 &&
+      pipeline.some(
+        (argv) =>
+          isAllowedEnvironmentRead(argv, allowedNames) ||
+          (isPassiveTextCommand(argv) &&
+            (mentionsEnvironmentRead(argv.join(" ")) || hasBraceExpansion(argv.join(" ")))),
+      ) &&
+      pipeline.some(
+        (argv) => !isPassiveTextCommand(argv) && !isAllowedEnvironmentRead(argv, allowedNames),
+      ),
+  );
+}
+
+/** A single literal writer cannot execute its body or feed another command. */
+function isLiteralTextWrite(command: string): boolean {
+  const lines = command.trimEnd().split(/\r?\n/);
+  const heredoc = /^(.*?)<<(-?)[ \t]*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\3[ \t]*$/.exec(lines[0] ?? "");
+  let header = command;
+  let writers = ["echo", "printf"];
+  if (heredoc) {
+    const [, prefix, stripTabs, quote, delimiter] = heredoc;
+    const end = lines.findIndex(
+      (line, index) => index > 0 && (stripTabs ? line.replace(/^\t+/, "") : line) === delimiter,
+    );
+    // Only the first delimiter closes the body. No following commands are exceptions.
+    if (end < 0 || end !== lines.length - 1) return false;
+    const body = lines.slice(1, end).join("\n");
+    if (!quote && /[$`\\]/.test(body)) return false;
+    header = prefix ?? "";
+    writers = ["cat", "tee"];
+  } else if (!command.includes(">")) {
+    return false;
+  }
+
+  // Output redirection does not execute text. Other unsupported syntax still fails parsing.
+  const parsed = parseStaticShellCommands(header.replace(/>/g, " "));
+  if (!parsed || parsed === "brace-expansion" || parsed.pipelines.length !== 1) return false;
+  const pipeline = parsed.pipelines[0];
+  if (pipeline?.length !== 1) return false;
+  const argv = unwrapStaticCommand(pipeline[0] ?? []);
+  return writers.includes(argv[0]?.split("/").at(-1) ?? "");
+}
+
 /** Extract file path from hook arguments. */
 export function extractFilePath(args: Record<string, unknown>): string {
   return (args.filePath as string) || (args.file_path as string) || (args.path as string) || "";
@@ -271,6 +464,19 @@ export function extractCommand(args: Record<string, unknown>): string {
  * @returns Object with all guard functions bound to the merged pattern sets.
  */
 export function createCredentialGuard(config?: CredentialGuardConfig): CredentialGuard {
+  const names = config?.allowedEnvironmentVariables;
+  if (
+    names !== undefined &&
+    (!Array.isArray(names) || names.some((name) => typeof name !== "string"))
+  ) {
+    throw new Error("allowedEnvironmentVariables must be an array of strings");
+  }
+  const allowedEnvironmentVariables = new Set(names ?? []);
+  for (const name of allowedEnvironmentVariables) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+      throw new Error(`Invalid allowed environment variable name: ${JSON.stringify(name)}`);
+    }
+  }
   const blockedPathPatterns = [
     ...DEFAULT_BLOCKED_PATH_PATTERNS,
     ...(config?.additionalBlockedPaths ?? []).map((p) => new RegExp(p)),
@@ -332,7 +538,10 @@ export function createCredentialGuard(config?: CredentialGuardConfig): Credentia
   }
 
   function isDangerousBashCommand(command: string): boolean {
-    return dangerousBashPatterns.some((pattern) => pattern.test(command));
+    return (
+      dangerousBashPatterns.some((pattern) => pattern.test(command)) ||
+      hasEnvironmentRead(command, allowedEnvironmentVariables)
+    );
   }
 
   function isGhCommandAllowed(command: string): boolean {

package/src/db-tool/index.ts

@@ -60,19 +60,19 @@ const resolveEnv = (envOption: Option.Option<string>) =>
 const sqlCommand = Command.make(
   "sql",
   {
-    env: Flag.optional(Flag.string("env")).pipe(
+    env: Flag.optional(Flag.String("env")).pipe(
       Flag.withDescription(
         "Target database environment name (e.g. local, test, prod). Falls back to defaultEnvironment in config.",
       ),
     ),
-    sql: Flag.string("sql").pipe(Flag.withDescription("SQL query to execute")),
-    limit: Flag.optional(Flag.integer("limit")).pipe(
+    sql: Flag.String("sql").pipe(Flag.withDescription("SQL query to execute")),
+    limit: Flag.optional(Flag.Int("limit")).pipe(
       Flag.withDescription(
         "Max rows to return (default 50). Use 0 for no cap. Prefer a SQL LIMIT for large tables.",
       ),
     ),
     format: formatOption,
-    profile: Flag.optional(Flag.string("profile")).pipe(
+    profile: Flag.optional(Flag.String("profile")).pipe(
       Flag.withDescription("Database profile name from agent-tools.json5 (if multiple configured)"),
     ),
   },
@@ -88,22 +88,22 @@ const sqlCommand = Command.make(
 const schemaCommand = Command.make(
   "schema",
   {
-    env: Flag.optional(Flag.string("env")).pipe(
+    env: Flag.optional(Flag.String("env")).pipe(
       Flag.withDescription(
         "Target database environment name (e.g. local, test, prod). Falls back to defaultEnvironment in config.",
       ),
     ),
-    mode: Flag.choice("mode", ["tables", "columns", "full", "relationships"]).pipe(
+    mode: Flag.Literals("mode", ["tables", "columns", "full", "relationships"]).pipe(
       Flag.withDescription(
         "Schema introspection mode: tables (list all), columns (show columns for --table), full (all tables with columns), relationships (foreign keys)",
       ),
     ),
-    table: Flag.string("table").pipe(
+    table: Flag.String("table").pipe(
       Flag.withDescription("Table name (required for --mode columns)"),
       Flag.optional,
     ),
     format: formatOption,
-    profile: Flag.optional(Flag.string("profile")).pipe(
+    profile: Flag.optional(Flag.String("profile")).pipe(
       Flag.withDescription("Database profile name from agent-tools.json5 (if multiple configured)"),
     ),
   },
@@ -124,7 +124,7 @@ const envsCommand = Command.make(
   "envs",
   {
     format: formatOption,
-    profile: Flag.optional(Flag.string("profile")).pipe(
+    profile: Flag.optional(Flag.String("profile")).pipe(
       Flag.withDescription("Database profile name from agent-tools.json5 (if multiple configured)"),
     ),
   },
@@ -179,16 +179,16 @@ const makeDiagnosticCommand = (name: string, description: string, sql: string) =
   Command.make(
     name,
     {
-      env: Flag.optional(Flag.string("env")).pipe(
+      env: Flag.optional(Flag.String("env")).pipe(
         Flag.withDescription(
           "Target database environment name (e.g. local, test, prod). Falls back to defaultEnvironment in config.",
         ),
       ),
-      limit: Flag.optional(Flag.integer("limit")).pipe(
+      limit: Flag.optional(Flag.Int("limit")).pipe(
         Flag.withDescription("Max rows to return (default 50). Use 0 for no cap."),
       ),
       format: formatOption,
-      profile: Flag.optional(Flag.string("profile")).pipe(
+      profile: Flag.optional(Flag.String("profile")).pipe(
         Flag.withDescription(
           "Database profile name from agent-tools.json5 (if multiple configured)",
         ),

package/src/gh-tool/branch.ts

@@ -63,14 +63,14 @@ export const renameBranch = Effect.fn("branch.renameBranch")(function* (opts: {
 export const branchRenameCommand = Command.make(
   "rename",
   {
-    confirm: Flag.boolean("confirm").pipe(
+    confirm: Flag.Boolean("confirm").pipe(
       Flag.withDescription("Actually rename (without this flag, only shows dry-run)"),
       Flag.withDefault(false),
     ),
     format: formatOption,
-    newName: Flag.string("new-name").pipe(Flag.withDescription("New branch name")),
-    oldName: Flag.string("old-name").pipe(Flag.withDescription("Current branch name to rename")),
-    repo: Flag.string("repo").pipe(
+    newName: Flag.String("new-name").pipe(Flag.withDescription("New branch name")),
+    oldName: Flag.String("old-name").pipe(Flag.withDescription("Current branch name to rename")),
+    repo: Flag.String("repo").pipe(
       Flag.withDescription("Target repository (owner/name). Defaults to current repo"),
       Flag.optional,
     ),

package/src/gh-tool/gist.ts

@@ -402,11 +402,11 @@ export const gistListCommand = Command.make(
   "list",
   {
     format: formatOption,
-    limit: Flag.integer("limit").pipe(
+    limit: Flag.Int("limit").pipe(
       Flag.withDescription("Maximum number of gists to return"),
       Flag.withDefault(10),
     ),
-    visibility: Flag.choice("visibility", ["public", "secret"]).pipe(
+    visibility: Flag.Literals("visibility", ["public", "secret"]).pipe(
       Flag.withDescription("Filter by visibility: public or secret"),
       Flag.optional,
     ),
@@ -424,13 +424,13 @@ export const gistListCommand = Command.make(
 export const gistViewCommand = Command.make(
   "view",
   {
-    filename: Flag.string("filename").pipe(
+    filename: Flag.String("filename").pipe(
       Flag.withDescription("Return only this file from the gist"),
       Flag.optional,
     ),
     format: formatOption,
-    id: Flag.string("id").pipe(Flag.withDescription("Gist id or URL")),
-    metadataOnly: Flag.boolean("metadata-only").pipe(
+    id: Flag.String("id").pipe(Flag.withDescription("Gist id or URL")),
+    metadataOnly: Flag.Boolean("metadata-only").pipe(
       Flag.withDescription("Omit file contents"),
       Flag.withDefault(false),
     ),
@@ -450,27 +450,27 @@ export const gistViewCommand = Command.make(
 export const gistCreateCommand = Command.make(
   "create",
   {
-    body: Flag.string("body").pipe(
+    body: Flag.String("body").pipe(
       Flag.withDescription("Inline gist content (requires --filename)"),
       Flag.optional,
     ),
-    bodyFile: Flag.string("body-file").pipe(
+    bodyFile: Flag.String("body-file").pipe(
       Flag.withDescription(
         "Read gist content from a file path or '-' for stdin (requires --filename)",
       ),
       Flag.optional,
     ),
-    desc: Flag.string("desc").pipe(Flag.withDescription("Gist description"), Flag.optional),
-    filename: Flag.string("filename").pipe(
+    desc: Flag.String("desc").pipe(Flag.withDescription("Gist description"), Flag.optional),
+    filename: Flag.String("filename").pipe(
       Flag.withDescription("File name used for --body/--body-file content"),
       Flag.optional,
     ),
-    files: Flag.string("files").pipe(
+    files: Flag.String("files").pipe(
       Flag.withDescription("Comma-separated paths of existing files to upload"),
       Flag.optional,
     ),
     format: formatOption,
-    public: Flag.boolean("public").pipe(
+    public: Flag.Boolean("public").pipe(
       Flag.withDescription("Publish as a public gist (gists are secret by default)"),
       Flag.withDefault(false),
     ),
@@ -526,26 +526,26 @@ export const gistCreateCommand = Command.make(
 export const gistEditCommand = Command.make(
   "edit",
   {
-    add: Flag.string("add").pipe(
+    add: Flag.String("add").pipe(
       Flag.withDescription("Path of a new file to add to the gist"),
       Flag.optional,
     ),
-    body: Flag.string("body").pipe(
+    body: Flag.String("body").pipe(
       Flag.withDescription("Replacement content for --filename"),
       Flag.optional,
     ),
-    bodyFile: Flag.string("body-file").pipe(
+    bodyFile: Flag.String("body-file").pipe(
       Flag.withDescription("Read replacement content from a file path or '-' for stdin"),
       Flag.optional,
     ),
-    desc: Flag.string("desc").pipe(Flag.withDescription("New gist description"), Flag.optional),
-    filename: Flag.string("filename").pipe(
+    desc: Flag.String("desc").pipe(Flag.withDescription("New gist description"), Flag.optional),
+    filename: Flag.String("filename").pipe(
       Flag.withDescription("Gist file to replace with --body/--body-file"),
       Flag.optional,
     ),
     format: formatOption,
-    id: Flag.string("id").pipe(Flag.withDescription("Gist id or URL")),
-    remove: Flag.string("remove").pipe(
+    id: Flag.String("id").pipe(Flag.withDescription("Gist id or URL")),
+    remove: Flag.String("remove").pipe(
       Flag.withDescription("File name to remove from the gist"),
       Flag.optional,
     ),
@@ -609,12 +609,12 @@ export const gistEditCommand = Command.make(
 export const gistDeleteCommand = Command.make(
   "delete",
   {
-    confirm: Flag.boolean("confirm").pipe(
+    confirm: Flag.Boolean("confirm").pipe(
       Flag.withDescription("Actually delete the gist (without this flag, only shows dry-run)"),
       Flag.withDefault(false),
     ),
     format: formatOption,
-    id: Flag.string("id").pipe(Flag.withDescription("Gist id or URL")),
+    id: Flag.String("id").pipe(Flag.withDescription("Gist id or URL")),
   },
   ({ confirm, format, id }) =>
     Effect.gen(function* () {