deepdebug-local-agent 1.0.23 → 1.2.0

package/src/utils/bind-host.js

@@ -0,0 +1,29 @@
+/**
+ * bind-host.js — which interface the agent's HTTP server listens on.
+ *
+ * Fail-closed default (security review 2026-10-11, C1): the agent only listens
+ * on all interfaces (0.0.0.0) when it is meant to be reached remotely, i.e. the
+ * auth mode is `token` (LOCAL_AGENT_TOKEN / AGENT_SHARED_SECRET), Cloud Run
+ * `compat` (IAM is the perimeter) or an explicit opt-out. Otherwise (the
+ * implicit `loopback` mode) it binds 127.0.0.1, so the port is not even open
+ * to the LAN. LOCAL_AGENT_BIND_HOST always wins. BYOC Azure (ACI)
+ * container groups put a TLS-terminating Caddy sidecar in front of the agent
+ * and set LOCAL_AGENT_BIND_HOST=127.0.0.1 so the agent is reachable only
+ * through the sidecar (containers in an ACI group share localhost).
+ */
+import net from "node:net";
+
+export const DEFAULT_BIND_HOST = "0.0.0.0";
+export const LOOPBACK_BIND_HOST = "127.0.0.1";
+
+/** @param authCfg result of resolveAuthConfig(); without it the safe loopback default applies. */
+export function resolveBindHost(env = process.env, authCfg = null) {
+    const raw = (env.LOCAL_AGENT_BIND_HOST || "").trim();
+    const remoteCapable = Boolean(authCfg) && ["token", "compat", "off"].includes(authCfg.mode);
+    const fallback = remoteCapable ? DEFAULT_BIND_HOST : LOOPBACK_BIND_HOST;
+    if (!raw) return fallback;
+    if (raw === "localhost") return "127.0.0.1";
+    if (net.isIP(raw)) return raw;
+    console.warn(`[bind-host] ignoring invalid LOCAL_AGENT_BIND_HOST=${JSON.stringify(raw)}; using ${fallback}`);
+    return fallback;
+}

package/src/utils/branch-refspec.js

@@ -0,0 +1,98 @@
+/**
+ * BRANCH REFSPEC FIX - explicit ref fetch for /workspace/open REUSE paths.
+ *
+ * Problem (proven in QA, 2026-07-20, agent rev 00021-kd8): the initial clone
+ * uses `git clone --branch <b> --single-branch`, which restricts the remote
+ * refspec to that ONE branch. When a LATER /workspace/open of the SAME repo
+ * asks for a DIFFERENT branch (e.g. the auto-review of a PR branch created
+ * minutes earlier), the reuse path runs `git fetch origin` (which only
+ * fetches the restricted refspec), swallows the checkout error, and dies on
+ * `git reset --hard origin/<branch>` with "fatal: ambiguous argument ...
+ * unknown revision" -> HTTP 500 -> review FAILED (PR #13 row in
+ * ai_pr_reviews). The fix: BEFORE checkout/reset, fetch the requested ref
+ * explicitly with `+refs/heads/<b>:refs/remotes/origin/<b>` so single-branch
+ * clones can see branches born after the original clone.
+ *
+ * Kept pure/dependency-injected so guard tests can pin every decision
+ * without a running server (same style as utils/open-gate.js).
+ */
+
+/**
+ * Shell-safety + git-ref sanity predicate for a requested branch name.
+ * The reuse path interpolates the branch into a shell command line, so we
+ * fail CLOSED on anything outside a conservative charset (no quotes, no
+ * whitespace, no $ ` ; & | > < ( ) { } \ ~ ^ : ? * [ @{ ), plus the git
+ * ref rules that matter here (no "..", no "//", no leading "-" or ".",
+ * no trailing "/" or ".lock").
+ */
+export function isSafeBranchName(branch) {
+    if (typeof branch !== "string") return false;
+    const b = branch.trim();
+    if (!b || b.length > 255) return false;
+    if (!/^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(b)) return false;
+    if (b.includes("..") || b.includes("//")) return false;
+    if (b.endsWith("/") || b.endsWith(".lock")) return false;
+    return true;
+}
+
+/**
+ * The explicit refspec that makes a single-branch clone see the requested
+ * branch: +refs/heads/<b>:refs/remotes/origin/<b>. Caller MUST validate the
+ * branch with isSafeBranchName first; this builder throws on unsafe input
+ * as defense in depth (never silently emits an injectable string).
+ */
+export function explicitBranchRefspec(branch) {
+    if (!isSafeBranchName(branch)) {
+        throw new Error(`unsafe branch name for refspec: ${String(branch)}`);
+    }
+    const b = branch.trim();
+    return `+refs/heads/${b}:refs/remotes/origin/${b}`;
+}
+
+/**
+ * Does a `git fetch origin <refspec>` failure mean the branch does not
+ * exist on the remote (as opposed to auth/network/other errors)?
+ * git says: "fatal: couldn't find remote ref refs/heads/<b>" and clones say
+ * "Remote branch <b> not found in upstream origin".
+ */
+export function isRemoteBranchMissing(message) {
+    if (typeof message !== "string" || !message) return false;
+    const m = message.toLowerCase();
+    return m.includes("couldn't find remote ref")
+        || m.includes("could not find remote ref")
+        || (m.includes("remote branch") && m.includes("not found"));
+}
+
+/**
+ * Fetch the requested ref explicitly on a REUSE path, with an injectable
+ * exec so guard tests can pin the exact command without git or a server.
+ *
+ * Throws tagged errors the HTTP handlers translate into CLEAR responses
+ * (never a generic 500):
+ *   .code = "INVALID_BRANCH"   .httpStatus = 400  (shell-unsafe branch name)
+ *   .code = "BRANCH_NOT_FOUND" .httpStatus = 404  (branch absent on remote)
+ * Any other fetch failure is rethrown untouched (existing catch semantics).
+ *
+ * @param {(cmd:string, opts:object)=>Promise<any>} execFn e.g. execAsync
+ * @param {string} branch requested branch
+ * @param {string} cwd repo dir on disk
+ */
+export async function fetchRequestedRef(execFn, branch, cwd) {
+    if (!isSafeBranchName(branch)) {
+        const err = new Error(`invalid branch name: ${String(branch)}`);
+        err.code = "INVALID_BRANCH";
+        err.httpStatus = 400;
+        throw err;
+    }
+    try {
+        await execFn(`git fetch origin "${explicitBranchRefspec(branch)}"`, { cwd, timeout: 120000 });
+    } catch (fetchErr) {
+        if (isRemoteBranchMissing(fetchErr && fetchErr.message)) {
+            const err = new Error(`branch not found on remote: ${branch.trim()}`);
+            err.code = "BRANCH_NOT_FOUND";
+            err.httpStatus = 404;
+            throw err;
+        }
+        throw fetchErr;
+    }
+}

package/src/utils/child-env.js

@@ -0,0 +1,34 @@
+/**
+ * child-env.js — environment handed to commands the MODEL asked us to run
+ * (/workspace/exec, /setup/run-command, /mcp/execute-command).
+ *
+ * WHY. Those routes spawned `{ ...process.env }`, so a command such as `env`
+ * or `cat /proc/self/environ` (or any prompt-injected one) read the agent's
+ * own credentials: AUTH_TOKEN / DEEPDEBUG_API_KEY (gateway), AGENT_SHARED_SECRET
+ * / LOCAL_AGENT_TOKEN (this API), git tokens. The child gets everything else
+ * (PATH, HOME, JAVA_HOME, proxies...) so builds and tests still work.
+ */
+
+const SECRET_NAME = /(TOKEN|SECRET|PASSWORD|PASSWD|API[_-]?KEY|APIKEY|CREDENTIAL|PRIVATE[_-]?KEY|SIGNING[_-]?KEY)/i;
+
+/** Names that match the pattern but carry no secret and are needed by git/tools. */
+const KEEP = new Set([
+    "GIT_TERMINAL_PROMPT", "GIT_ASKPASS", "GIT_SSH_COMMAND", "SSH_AUTH_SOCK",
+]);
+
+export function isSecretEnvName(name) {
+    return !KEEP.has(name) && SECRET_NAME.test(String(name));
+}
+
+/**
+ * Copy of `env` without secret-looking variables, plus `extra` (which is never
+ * filtered: the caller is explicit about what it adds).
+ */
+export function sanitizedChildEnv(env = process.env, extra = {}) {
+    const out = {};
+    for (const [k, v] of Object.entries(env)) {
+        if (v === undefined || isSecretEnvName(k)) continue;
+        out[k] = v;
+    }
+    return { ...out, ...extra };
+}

package/src/utils/environment-diagnostics.js

@@ -8,22 +8,22 @@ const execAsync = promisify(exec);
 /**
  * EnvironmentDiagnostics
  *
- * Detecta automaticamente ferramentas de desenvolvimento instaladas no sistema.
- * Útil para debugging e setup do ambiente.
+ * Automatically detects development tools installed on the system.
+ * Useful for debugging and environment setup.
  */
 export class EnvironmentDiagnostics {
 
     constructor() {
         this.cache = null;
         this.cacheTime = 0;
-        this.cacheTTL = 60000; // 1 minuto
+        this.cacheTTL = 60000; // 1 minute
     }
 
     /**
-     * Executa diagnóstico completo do ambiente
+     * Runs a full environment diagnostic
      */
     async diagnose() {
-        // Usar cache se ainda válido
+        // Use the cache if still valid
         if (this.cache && (Date.now() - this.cacheTime) < this.cacheTTL) {
             return this.cache;
         }
@@ -89,7 +89,7 @@ export class EnvironmentDiagnostics {
     }
 
     /**
-     * Informações do sistema
+     * System information
      */
     async getSystemInfo() {
         return {
@@ -110,7 +110,7 @@ export class EnvironmentDiagnostics {
     }
 
     /**
-     * Detecta Java
+     * Detects Java
      */
     async detectJava() {
         const result = {
@@ -122,19 +122,19 @@ export class EnvironmentDiagnostics {
         };
 
         try {
-            // Tentar java -version
+            // Try java -version
             const { stderr } = await execAsync('java -version 2>&1');
             const output = stderr || '';
 
             result.installed = true;
 
-            // Extrair versão (ex: "openjdk version "17.0.1"")
+            // Extract the version (e.g.: "openjdk version "17.0.1"")
             const versionMatch = output.match(/version\s+"([^"]+)"/);
             if (versionMatch) {
                 result.version = versionMatch[1];
             }
 
-            // Extrair vendor
+            // Extract the vendor
             if (output.includes('OpenJDK')) {
                 result.vendor = 'OpenJDK';
             } else if (output.includes('Oracle')) {
@@ -147,7 +147,7 @@ export class EnvironmentDiagnostics {
                 result.vendor = 'Eclipse Temurin';
             }
 
-            // Encontrar path
+            // Find the path
             const { stdout: whichOutput } = await execAsync('which java').catch(() => ({ stdout: '' }));
             result.path = whichOutput.trim() || null;
 
@@ -159,7 +159,7 @@ export class EnvironmentDiagnostics {
     }
 
     /**
-     * Detecta Maven
+     * Detects Maven
      */
     async detectMaven() {
         const result = {
@@ -174,19 +174,19 @@ export class EnvironmentDiagnostics {
 
             result.installed = true;
 
-            // Extrair versão (ex: "Apache Maven 3.9.0")
+            // Extract the version (e.g.: "Apache Maven 3.9.0")
             const versionMatch = stdout.match(/Apache Maven (\d+\.\d+\.\d+)/);
             if (versionMatch) {
                 result.version = versionMatch[1];
             }
 
-            // Extrair Java version usado pelo Maven
+            // Extract the Java version used by Maven
             const javaMatch = stdout.match(/Java version: ([^\n,]+)/);
             if (javaMatch) {
                 result.javaVersion = javaMatch[1].trim();
             }
 
-            // Encontrar path
+            // Find the path
             const { stdout: whichOutput } = await execAsync('which mvn').catch(() => ({ stdout: '' }));
             result.path = whichOutput.trim() || null;
 
@@ -198,7 +198,7 @@ export class EnvironmentDiagnostics {
     }
 
     /**
-     * Detecta Gradle
+     * Detects Gradle
      */
     async detectGradle() {
         const result = {
@@ -213,13 +213,13 @@ export class EnvironmentDiagnostics {
 
             result.installed = true;
 
-            // Extrair versão (ex: "Gradle 8.0")
+            // Extract the version (e.g.: "Gradle 8.0")
             const versionMatch = stdout.match(/Gradle (\d+\.\d+\.?\d*)/);
             if (versionMatch) {
                 result.version = versionMatch[1];
             }
 
-            // Encontrar path
+            // Find the path
             const { stdout: whichOutput } = await execAsync('which gradle').catch(() => ({ stdout: '' }));
             result.path = whichOutput.trim() || null;
 
@@ -231,7 +231,7 @@ export class EnvironmentDiagnostics {
     }
 
     /**
-     * Detecta Node.js
+     * Detects Node.js
      */
     async detectNode() {
         const result = {
@@ -246,7 +246,7 @@ export class EnvironmentDiagnostics {
             result.installed = true;
             result.version = stdout.trim().replace('v', '');
 
-            // Encontrar path
+            // Find the path
             const { stdout: whichOutput } = await execAsync('which node').catch(() => ({ stdout: '' }));
             result.path = whichOutput.trim() || null;
 
@@ -258,7 +258,7 @@ export class EnvironmentDiagnostics {
     }
 
     /**
-     * Detecta npm
+     * Detects npm
      */
     async detectNpm() {
         const result = {
@@ -278,7 +278,7 @@ export class EnvironmentDiagnostics {
             const { stdout: prefixOutput } = await execAsync('npm config get prefix').catch(() => ({ stdout: '' }));
             result.globalPrefix = prefixOutput.trim() || null;
 
-            // Encontrar path
+            // Find the path
             const { stdout: whichOutput } = await execAsync('which npm').catch(() => ({ stdout: '' }));
             result.path = whichOutput.trim() || null;
 
@@ -290,7 +290,7 @@ export class EnvironmentDiagnostics {
     }
 
     /**
-     * Detecta Yarn
+     * Detects Yarn
      */
     async detectYarn() {
         const result = {
@@ -305,7 +305,7 @@ export class EnvironmentDiagnostics {
             result.installed = true;
             result.version = stdout.trim();
 
-            // Encontrar path
+            // Find the path
             const { stdout: whichOutput } = await execAsync('which yarn').catch(() => ({ stdout: '' }));
             result.path = whichOutput.trim() || null;
 
@@ -317,7 +317,7 @@ export class EnvironmentDiagnostics {
     }
 
     /**
-     * Detecta Python
+     * Detects Python
      */
     async detectPython() {
         const result = {
@@ -328,21 +328,21 @@ export class EnvironmentDiagnostics {
         };
 
         try {
-            // Tentar python3 primeiro
+            // Try python3 first
             const { stdout } = await execAsync('python3 --version 2>&1').catch(() =>
                 execAsync('python --version 2>&1')
             );
 
             result.installed = true;
 
-            // Extrair versão (ex: "Python 3.11.0")
+            // Extract the version (e.g.: "Python 3.11.0")
             const versionMatch = stdout.match(/Python (\d+\.\d+\.?\d*)/);
             if (versionMatch) {
                 result.version = versionMatch[1];
                 result.python3 = result.version.startsWith('3');
             }
 
-            // Encontrar path
+            // Find the path
             const { stdout: whichOutput } = await execAsync('which python3 || which python').catch(() => ({ stdout: '' }));
             result.path = whichOutput.trim() || null;
 
@@ -354,7 +354,7 @@ export class EnvironmentDiagnostics {
     }
 
     /**
-     * Detecta pip
+     * Detects pip
      */
     async detectPip() {
         const result = {
@@ -370,13 +370,13 @@ export class EnvironmentDiagnostics {
 
             result.installed = true;
 
-            // Extrair versão (ex: "pip 23.0.1")
+            // Extract the version (e.g.: "pip 23.0.1")
             const versionMatch = stdout.match(/pip (\d+\.\d+\.?\d*)/);
             if (versionMatch) {
                 result.version = versionMatch[1];
             }
 
-            // Encontrar path
+            // Find the path
             const { stdout: whichOutput } = await execAsync('which pip3 || which pip').catch(() => ({ stdout: '' }));
             result.path = whichOutput.trim() || null;
 
@@ -388,7 +388,7 @@ export class EnvironmentDiagnostics {
     }
 
     /**
-     * Detecta Go
+     * Detects Go
      */
     async detectGo() {
         const result = {
@@ -404,13 +404,13 @@ export class EnvironmentDiagnostics {
 
             result.installed = true;
 
-            // Extrair versão (ex: "go version go1.21.0 darwin/amd64")
+            // Extract the version (e.g.: "go version go1.21.0 darwin/amd64")
             const versionMatch = stdout.match(/go(\d+\.\d+\.?\d*)/);
             if (versionMatch) {
                 result.version = versionMatch[1];
             }
 
-            // Encontrar path
+            // Find the path
             const { stdout: whichOutput } = await execAsync('which go').catch(() => ({ stdout: '' }));
             result.path = whichOutput.trim() || null;
 
@@ -422,7 +422,7 @@ export class EnvironmentDiagnostics {
     }
 
     /**
-     * Detecta .NET
+     * Detects .NET
      */
     async detectDotnet() {
         const result = {
@@ -447,7 +447,7 @@ export class EnvironmentDiagnostics {
             const { stdout: runtimeOutput } = await execAsync('dotnet --list-runtimes 2>&1').catch(() => ({ stdout: '' }));
             result.runtimes = runtimeOutput.trim().split('\n').filter(Boolean).slice(0, 5); // Limitar
 
-            // Encontrar path
+            // Find the path
             const { stdout: whichOutput } = await execAsync('which dotnet').catch(() => ({ stdout: '' }));
             result.path = whichOutput.trim() || null;
 
@@ -459,7 +459,7 @@ export class EnvironmentDiagnostics {
     }
 
     /**
-     * Detecta Git
+     * Detects Git
      */
     async detectGit() {
         const result = {
@@ -475,7 +475,7 @@ export class EnvironmentDiagnostics {
 
             result.installed = true;
 
-            // Extrair versão (ex: "git version 2.39.0")
+            // Extract the version (e.g.: "git version 2.39.0")
             const versionMatch = stdout.match(/git version (\d+\.\d+\.?\d*)/);
             if (versionMatch) {
                 result.version = versionMatch[1];
@@ -488,7 +488,7 @@ export class EnvironmentDiagnostics {
             const { stdout: emailOutput } = await execAsync('git config --global user.email').catch(() => ({ stdout: '' }));
             result.email = emailOutput.trim() || null;
 
-            // Encontrar path
+            // Find the path
             const { stdout: whichOutput } = await execAsync('which git').catch(() => ({ stdout: '' }));
             result.path = whichOutput.trim() || null;
 
@@ -500,7 +500,7 @@ export class EnvironmentDiagnostics {
     }
 
     /**
-     * Detecta Docker
+     * Detects Docker
      */
     async detectDocker() {
         const result = {
@@ -515,13 +515,13 @@ export class EnvironmentDiagnostics {
 
             result.installed = true;
 
-            // Extrair versão (ex: "Docker version 24.0.0, build xxx")
+            // Extract the version (e.g.: "Docker version 24.0.0, build xxx")
             const versionMatch = stdout.match(/Docker version (\d+\.\d+\.?\d*)/);
             if (versionMatch) {
                 result.version = versionMatch[1];
             }
 
-            // Verificar se está rodando
+            // Check whether it is running
             try {
                 await execAsync('docker info 2>&1');
                 result.running = true;
@@ -529,7 +529,7 @@ export class EnvironmentDiagnostics {
                 result.running = false;
             }
 
-            // Encontrar path
+            // Find the path
             const { stdout: whichOutput } = await execAsync('which docker').catch(() => ({ stdout: '' }));
             result.path = whichOutput.trim() || null;
 
@@ -541,7 +541,7 @@ export class EnvironmentDiagnostics {
     }
 
     /**
-     * Gera sumário das capacidades
+     * Generates a capabilities summary
      */
     generateSummary(tools) {
         const capabilities = [];
@@ -579,47 +579,47 @@ export class EnvironmentDiagnostics {
     }
 
     /**
-     * Detecta problemas de configuração
+     * Detects configuration problems
      */
     detectIssues(tools) {
         const issues = [];
 
-        // Java sem JAVA_HOME
+        // Java without JAVA_HOME
         if (tools.java?.installed && !process.env.JAVA_HOME) {
             issues.push({
                 severity: 'warning',
                 tool: 'java',
-                message: 'JAVA_HOME não está configurado',
+                message: 'JAVA_HOME is not configured',
                 fix: 'export JAVA_HOME=$(/usr/libexec/java_home)'
             });
         }
 
-        // Java instalado mas Maven não
+        // Java installed but Maven not
         if (tools.java?.installed && !tools.maven?.installed) {
             issues.push({
                 severity: 'info',
                 tool: 'maven',
-                message: 'Maven não está instalado (necessário para projetos Maven)',
+                message: 'Maven is not installed (required for Maven projects)',
                 fix: 'brew install maven'
             });
         }
 
-        // Node sem npm
+        // Node without npm
         if (tools.node?.installed && !tools.npm?.installed) {
             issues.push({
                 severity: 'error',
                 tool: 'npm',
-                message: 'Node está instalado mas npm não foi encontrado',
-                fix: 'Reinstale o Node.js'
+                message: 'Node is installed but npm was not found',
+                fix: 'Reinstall Node.js'
             });
         }
 
-        // Python 2 ao invés de 3
+        // Python 2 instead of 3
         if (tools.python?.installed && !tools.python?.python3) {
             issues.push({
                 severity: 'warning',
                 tool: 'python',
-                message: 'Python 2 detectado. Recomendado usar Python 3',
+                message: 'Python 2 detected. Using Python 3 is recommended',
                 fix: 'brew install python3'
             });
         }
@@ -628,7 +628,7 @@ export class EnvironmentDiagnostics {
     }
 
     /**
-     * Diagnóstico rápido apenas para uma linguagem
+     * Quick diagnostic for a single language only
      */
     async diagnoseFor(language) {
         switch (language) {