@goodandready/dsh-approval-gate 0.1.18 → 0.1.20

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.1.20
+
+- Feature: Безопасная альтернатива необратимому удалению (`Reversible Trash Move` в `lib/trash.js`) с переносом удаляемых файлов в изолированную сессионную корзину `<workspace>/.dsh/trash/<session_id>/` вместо деструктивного `rm` (Refs: #104).
+- Feature: Реестр сессионных артефактов (`ArtifactRegistry` в `lib/artifacts.js`) для автоматического отслеживания и безопасного разрешения очистки временных файлов текущей сессии на стадии P1 без спама подтверждениями (Refs: #100).
+- Security: Парсер проектных правил безопасности из `AGENTS.md` (`lib/agents-parser.js`) с жестким перехватом запрещенных команд и путей на стадии P0 (`agents-md-prohibited-command`, `agents-md-prohibited-path` -> `deny`) (Refs: #91).
+- Resilience: Проверка совместимости версий хоста DSH (`assertHarnessCompatibility` в `lib/compat.js`) и безопасные полифилы `provideServicePolyfill` / `registerHookPolyfill` для бесшовной работы на различных версиях Cordis (Refs: #106).
+- Security: Страж зависимостей проекта (`VersionGuard` в `lib/version-guard.js`) с автоматическим обнаружением мажорных обновлений в `package.json` и переводом их на ручное подтверждение человеком (`major-version-bump` -> `ask`) (Refs: #95).
+
+## 0.1.19
+
+- Security: Структурированная категоризация рисков операций по 5 стандартизированным бакетам (`READ_ONLY`, `WORKSPACE`, `EGRESS`, `SYSTEM`, `SECRETS`) в `lib/risk.js` с приоритетной оценкой чувствительности путей, команд и сетевых направлений (Refs: #58).
+- Security: Многомерное тегирование рисков (`risk_tags`: `read-only`, `file-mutation`, `network`, `git`, `credentials`, `package-manager`, `system-mutation`, `privilege-escalation`, `destructive`) для детального анализа и обогащения решений безопасности (Refs: #70).
+- Resilience: Трекер задержки семантического классификатора (`ClassifierLatencyTracker` в `lib/latency.js`) со скользящим окном p95/avg и автоматическим переходом на детерминированные правила при превышении SLA (`classifier-sla-fallback` -> `ask`) (Refs: #57).
+- Resilience: Плавный fallback при несовместимости эндпоинта с OpenAI JSON-mode (`isShapeRejectError`), извлечение JSON из markdown/raw-ответов (`extractJsonPayload`) и повторный запрос без `response_format` для Ollama/vLLM (Refs: #59).
+- Security: Строгая Schemastery-схема вердиктов классификатора (`ClassifierVerdictSchema`, `validateClassifierResponse`) с fail-closed защитой от некорректных/неполных ответов модели (`malformed-classifier-response` -> `ask`) (Refs: #66).
+
 ## 0.1.18
 
 - Security: Эвристический предохранитель размера аргументов (`computePayloadSize` / `maxPayloadBytes`, по умолчанию 64 КБ) для предотвращения переполнения контекста LLM-ревьюера и обхода инспекции (`payload-too-large` -> `ask`) (Refs: #71).

package/lib/agents-parser.js

@@ -0,0 +1,183 @@
+// lib/agents-parser.js
+// Parser and enforcement for local project safety rules from AGENTS.md / CLAUDE.md (#91).
+
+import fs from "node:fs";
+import path from "node:path";
+
+const AGENTS_FILENAMES = ["AGENTS.md", ".dsh/AGENTS.md", "CLAUDE.md"];
+
+const SECURITY_HEADING_REGEX = /^(?:#{1,3})\s*(?:security|safety|rules|constraints|prohibited|forbidden|restrictions|do\s+not|never)\b/i;
+
+const FORBIDDEN_DIRECTIVE_REGEX = /(?:(?:never|do\s+not|don't|prohibit(?:ed)?|forbid(?:den)?|cannot|must\s+not)\s+(?:run|execute|use|modify|delete|touch|access|call|write)|forbidden:\s*|prohibited:\s*)/i;
+
+/**
+ * Parses markdown text of AGENTS.md and extracts active security constraints (#91).
+ *
+ * @param {string} content - Markdown document text
+ * @returns {{
+ *   rules: Array<{ type: "command" | "path" | "keyword" | "directive", pattern: string, text: string }>,
+ *   rawDirectives: string[]
+ * }}
+ */
+export function parseAgentsSecurityRules(content) {
+  if (typeof content !== "string" || !content.trim()) {
+    return { rules: [], rawDirectives: [] };
+  }
+
+  const lines = content.split(/\r?\n/);
+  const rules = [];
+  const rawDirectives = [];
+
+  let inSecuritySection = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const rawLine = lines[i];
+    const trimmed = rawLine.trim();
+
+    // Check headings
+    if (trimmed.startsWith("#")) {
+      inSecuritySection = SECURITY_HEADING_REGEX.test(trimmed);
+      continue;
+    }
+
+    if (!trimmed) continue;
+
+    // Check bullet points or bold directives in security section or explicit global directives
+    const isBullet = /^[-*+]\s+/.test(trimmed) || /^\d+\.\s+/.test(trimmed);
+    const cleanText = trimmed.replace(/^[-*+]\s+/, "").replace(/^\d+\.\s+/, "").trim();
+
+    if ((inSecuritySection && isBullet) || FORBIDDEN_DIRECTIVE_REGEX.test(cleanText)) {
+      rawDirectives.push(cleanText);
+
+      // 1. Check for command / tool restriction: e.g. `Never run rm -rf`, `Do not execute curl`
+      const cmdMatch = /(?:run|execute|use|call)\s+(?:`([^`]+)`|"([^"]+)"|([a-zA-Z0-9_\-\.\/]+(?:\s+[a-zA-Z0-9_\-\.\/]+)?))/i.exec(cleanText);
+      if (cmdMatch) {
+        const cmdPattern = (cmdMatch[1] || cmdMatch[2] || cmdMatch[3]).trim();
+        if (cmdPattern && !["to", "the", "a", "an", "any", "this"].includes(cmdPattern.toLowerCase())) {
+          rules.push({
+            type: "command",
+            pattern: cmdPattern,
+            text: cleanText,
+          });
+          continue;
+        }
+      }
+
+      // 2. Check for path restriction: e.g. `Do not modify package.json`, `Do not touch .env`
+      const pathMatch = /(?:modify|edit|delete|write|overwrite|touch)\s+(?:`([^`]+)`|"([^"]+)"|([a-zA-Z0-9_\-\.\/\*]+))/i.exec(cleanText);
+      if (pathMatch) {
+        const pathPattern = (pathMatch[1] || pathMatch[2] || pathMatch[3]).trim();
+        if (pathPattern && !["to", "the", "a", "an", "any", "this"].includes(pathPattern.toLowerCase())) {
+          rules.push({
+            type: "path",
+            pattern: pathPattern,
+            text: cleanText,
+          });
+          continue;
+        }
+      }
+
+      // 3. Fallback general directive
+      rules.push({
+        type: "directive",
+        pattern: cleanText,
+        text: cleanText,
+      });
+    }
+  }
+
+  return { rules, rawDirectives };
+}
+
+/**
+ * Loads and parses AGENTS.md rules from a workspace directory (#91).
+ *
+ * @param {string} [workspaceDir]
+ * @returns {{ rules: Array<any>, rawDirectives: string[], filePath?: string } | null}
+ */
+export function loadAgentsRules(workspaceDir) {
+  const ws = workspaceDir && typeof workspaceDir === "string" ? workspaceDir : process.cwd();
+
+  for (const rel of AGENTS_FILENAMES) {
+    const fullPath = path.resolve(ws, rel);
+    try {
+      if (fs.existsSync(fullPath)) {
+        const content = fs.readFileSync(fullPath, "utf-8");
+        const parsed = parseAgentsSecurityRules(content);
+        return {
+          rules: parsed.rules,
+          rawDirectives: parsed.rawDirectives,
+          filePath: fullPath,
+        };
+      }
+    } catch {
+      // ignore read faults
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Evaluates an execution against active AGENTS.md rules (#91).
+ *
+ * @param {Array<any>} rules - Parsed rules from parseAgentsSecurityRules
+ * @param {{ name?: string, arguments?: any }} execution
+ * @param {string} [targetPath]
+ * @returns {{ match: boolean, reason?: string, rule?: any }}
+ */
+export function evaluateAgentsRules(rules, execution, targetPath) {
+  if (!Array.isArray(rules) || rules.length === 0) {
+    return { match: false };
+  }
+
+  const args = execution && execution.arguments;
+  const command = (args && typeof args === "object" && typeof args.command === "string")
+    ? args.command.trim()
+    : (typeof args === "string" ? args.trim() : "");
+  const toolName = String((execution && execution.name) || "").trim();
+  const pathToCheck = String(targetPath || (args && (args.path || args.file || args.TargetFile)) || "").trim();
+
+  for (const rule of rules) {
+    if (rule.type === "command") {
+      const pat = rule.pattern.toLowerCase();
+      if (command && command.toLowerCase().includes(pat)) {
+        return {
+          match: true,
+          reason: "agents-md-prohibited-command",
+          rule,
+        };
+      }
+      if (toolName && toolName.toLowerCase() === pat) {
+        return {
+          match: true,
+          reason: "agents-md-prohibited-command",
+          rule,
+        };
+      }
+    }
+
+    if (rule.type === "path" && pathToCheck) {
+      const pat = rule.pattern.replace(/\\/g, "/");
+      const normPath = pathToCheck.replace(/\\/g, "/");
+      if (pat.endsWith("*")) {
+        const prefix = pat.slice(0, -1);
+        if (normPath.startsWith(prefix) || normPath.includes(prefix)) {
+          return {
+            match: true,
+            reason: "agents-md-prohibited-path",
+            rule,
+          };
+        }
+      } else if (normPath.endsWith(pat) || normPath === pat) {
+        return {
+          match: true,
+          reason: "agents-md-prohibited-path",
+          rule,
+        };
+      }
+    }
+  }
+
+  return { match: false };
+}

package/lib/artifacts.js

@@ -0,0 +1,162 @@
+// lib/artifacts.js
+// Session Artifact Registry: tracks files created during current session
+// to permit safe auto-cleanup of temporary artifacts without approval prompt spam (#100).
+
+import path from "node:path";
+
+/**
+ * Normalizes file paths for consistent artifact matching across relative and absolute forms.
+ *
+ * @param {string} filePath
+ * @param {string} [workspaceDir]
+ * @returns {string}
+ */
+export function normalizeArtifactPath(filePath, workspaceDir) {
+  if (typeof filePath !== "string" || !filePath.trim()) return "";
+  let p = filePath.trim().replace(/^["']|["']$/g, "");
+  p = p.replace(/\\/g, "/");
+
+  if (workspaceDir && typeof workspaceDir === "string") {
+    const ws = workspaceDir.replace(/\\/g, "/").replace(/\/+$/, "");
+    if (p.startsWith(ws + "/")) {
+      p = p.slice(ws.length + 1);
+    }
+  }
+
+  p = p.replace(/^\.\//, "");
+  return p;
+}
+
+/**
+ * Registry tracking temporary artifacts created within agent sessions (#100).
+ */
+export class ArtifactRegistry {
+  /**
+   * @param {{ workspaceDir?: string }} [options]
+   */
+  constructor(options = {}) {
+    this.workspaceDir = options.workspaceDir || "";
+    /** @type {Map<string, Set<string>>} */
+    this._sessions = new Map();
+  }
+
+  /**
+   * Records a created or written artifact for a session.
+   *
+   * @param {string} sessionId
+   * @param {string} filePath
+   * @returns {boolean} True if new artifact added, false if already tracked or invalid
+   */
+  recordArtifact(sessionId, filePath) {
+    const sid = String(sessionId || "default");
+    const norm = normalizeArtifactPath(filePath, this.workspaceDir);
+    if (!norm) return false;
+
+    let set = this._sessions.get(sid);
+    if (!set) {
+      set = new Set();
+      this._sessions.set(sid, set);
+    }
+    const had = set.has(norm);
+    set.add(norm);
+    return !had;
+  }
+
+  /**
+   * Checks whether a specific file was created as an artifact in the given session.
+   *
+   * @param {string} sessionId
+   * @param {string} filePath
+   * @returns {boolean}
+   */
+  isSessionArtifact(sessionId, filePath) {
+    const sid = String(sessionId || "default");
+    const norm = normalizeArtifactPath(filePath, this.workspaceDir);
+    if (!norm) return false;
+
+    const set = this._sessions.get(sid);
+    if (!set) return false;
+    return set.has(norm);
+  }
+
+  /**
+   * Checks whether ALL provided files are artifacts created in the given session.
+   *
+   * @param {string} sessionId
+   * @param {string[]} filePaths
+   * @returns {boolean}
+   */
+  areAllSessionArtifacts(sessionId, filePaths) {
+    if (!Array.isArray(filePaths) || filePaths.length === 0) return false;
+    const sid = String(sessionId || "default");
+    const set = this._sessions.get(sid);
+    if (!set || set.size === 0) return false;
+
+    for (const fp of filePaths) {
+      const norm = normalizeArtifactPath(fp, this.workspaceDir);
+      if (!norm || !set.has(norm)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Removes an artifact from session tracking (e.g. after deletion).
+   *
+   * @param {string} sessionId
+   * @param {string} filePath
+   * @returns {boolean}
+   */
+  removeArtifact(sessionId, filePath) {
+    const sid = String(sessionId || "default");
+    const norm = normalizeArtifactPath(filePath, this.workspaceDir);
+    if (!norm) return false;
+
+    const set = this._sessions.get(sid);
+    if (!set) return false;
+    return set.delete(norm);
+  }
+
+  /**
+   * Returns list of recorded artifacts for a session.
+   *
+   * @param {string} sessionId
+   * @returns {string[]}
+   */
+  getArtifacts(sessionId) {
+    const sid = String(sessionId || "default");
+    const set = this._sessions.get(sid);
+    if (!set) return [];
+    return Array.from(set);
+  }
+
+  /**
+   * Returns total count of artifacts recorded for a session.
+   *
+   * @param {string} sessionId
+   * @returns {number}
+   */
+  count(sessionId) {
+    const sid = String(sessionId || "default");
+    const set = this._sessions.get(sid);
+    return set ? set.size : 0;
+  }
+
+  /**
+   * Clears tracked artifacts for a specific session.
+   *
+   * @param {string} sessionId
+   */
+  clearSession(sessionId) {
+    const sid = String(sessionId || "default");
+    this._sessions.delete(sid);
+  }
+
+  /**
+   * Clears all session artifacts across the entire registry.
+   */
+  clearAll() {
+    this._sessions.clear();
+  }
+}

package/lib/classifier.js

@@ -4,6 +4,7 @@
 
 import { redactCredentials, redactUrl } from "./redact.js";
 import { CircuitBreaker } from "./breaker.js";
+import Schema from "@deepseek-ai/schemastery";
 
 // Additional regex patterns for sensitive tokens & API keys (#115)
 const OPENAI_KEY_PATTERN = /\bsk-[a-zA-Z0-9_\-]{20,}\b/g;
@@ -244,7 +245,104 @@ export function isLowRiskExecution(execution) {
 }
 
 /**
- * Standalone resilient LLM Classifier client (#127, #129, #118, #115, #117).
+ * Checks whether an error is caused by endpoint rejection of JSON-mode / response_format (#59).
+ * Common in local LLM runtimes like Ollama, vLLM, and older endpoints.
+ *
+ * @param {any} err
+ * @returns {boolean}
+ */
+export function isShapeRejectError(err) {
+  if (!err) return false;
+  const status = err.status || (err.response && err.response.status);
+  if (status === 400 || status === 415 || status === 422) return true;
+  const msg = String(err.message || "").toLowerCase();
+  return (
+    msg.includes("response_format") ||
+    msg.includes("json_object") ||
+    msg.includes("unsupported parameter") ||
+    msg.includes("schema")
+  );
+}
+
+/**
+ * Robust JSON extraction from raw strings, handling markdown code blocks and raw JSON (#59).
+ *
+ * @param {string} content
+ * @returns {any | null}
+ */
+export function extractJsonPayload(content) {
+  if (!content || typeof content !== "string") return null;
+  const trimmed = content.trim();
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    // Check markdown code block
+    const mdMatch = /```(?:json)?\s*([\s\S]*?)\s*```/i.exec(trimmed);
+    if (mdMatch && mdMatch[1]) {
+      try {
+        return JSON.parse(mdMatch[1].trim());
+      } catch {
+        // continue
+      }
+    }
+    // Check bracketed JSON
+    const braceMatch = /\{[\s\S]*\}/.exec(trimmed);
+    if (braceMatch) {
+      try {
+        return JSON.parse(braceMatch[0]);
+      } catch {
+        // ignore
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Strict Schemastery schema for validating structured classifier decisions (#66).
+ */
+export const ClassifierVerdictSchema = Schema.object({
+  verdict: Schema.union(["allow", "deny", "ask"]).required(),
+  reason: Schema.string().default("classifier-evaluated"),
+  riskScore: Schema.number().default(0.5),
+  tags: Schema.array(Schema.string()).default([]),
+});
+
+/**
+ * Validates and normalizes structured classifier response (#66).
+ *
+ * @param {any} parsed
+ * @returns {{ valid: boolean, verdict?: "allow" | "deny" | "ask", reason?: string, riskScore?: number, tags?: string[], error?: string }}
+ */
+export function validateClassifierResponse(parsed) {
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return { valid: false, error: "Response is not a valid JSON object" };
+  }
+  const rawVerdict = String(parsed.verdict || "").toLowerCase().trim();
+  if (!["allow", "deny", "ask"].includes(rawVerdict)) {
+    return { valid: false, error: `Invalid verdict '${parsed.verdict}', expected allow|deny|ask` };
+  }
+  const reason = typeof parsed.reason === "string" && parsed.reason.trim()
+    ? parsed.reason.trim()
+    : `classifier-${rawVerdict}`;
+  const riskScore = typeof parsed.riskScore === "number" && !isNaN(parsed.riskScore)
+    ? Math.max(0, Math.min(1, parsed.riskScore))
+    : (rawVerdict === "deny" ? 1.0 : (rawVerdict === "ask" ? 0.6 : 0.1));
+  const tags = Array.isArray(parsed.tags)
+    ? parsed.tags.filter((t) => typeof t === "string" && t.trim()).map((t) => t.trim())
+    : [];
+
+  return {
+    valid: true,
+    verdict: rawVerdict,
+    reason,
+    riskScore,
+    tags,
+  };
+}
+
+/**
+ * Standalone resilient LLM Classifier client (#127, #129, #118, #115, #117, #59, #66).
  */
 export class LlmClassifier {
   /**
@@ -256,6 +354,7 @@ export class LlmClassifier {
    *   timeoutPolicy?: "strict" | "permissive",
    *   maxRetries?: number,
    *   maxContextChars?: number,
+   *   supportsJsonMode?: boolean,
    *   fetch?: typeof globalThis.fetch
    * }} [options]
    */
@@ -267,11 +366,12 @@ export class LlmClassifier {
     this.timeoutPolicy = options.timeoutPolicy === "permissive" ? "permissive" : "strict";
     this.maxRetries = typeof options.maxRetries === "number" ? options.maxRetries : 2;
     this.maxContextChars = typeof options.maxContextChars === "number" ? options.maxContextChars : 1000;
+    this.supportsJsonMode = options.supportsJsonMode !== false;
     this.fetch = options.fetch || globalThis.fetch;
   }
 
   /**
-   * Builds prompt messages with sanitized credentials and bounded context size (#115, #117).
+   * Builds prompt messages with sanitized credentials and bounded context size (#115, #117, #66).
    *
    * @param {any} execution
    * @param {any} [context]
@@ -286,7 +386,7 @@ export class LlmClassifier {
         role: "system",
         content:
           "You are a security approval gate classifier. Analyze the provided tool execution request. " +
-          "Respond strictly in valid JSON format: {\"verdict\": \"allow\"|\"deny\"|\"ask\", \"reason\": \"<short explanation>\"}.",
+          "Respond strictly in valid JSON format: {\"verdict\": \"allow\"|\"deny\"|\"ask\", \"reason\": \"<short explanation>\", \"riskScore\": <0.0-1.0>, \"tags\": [\"<tag>\"]}.",
       },
       {
         role: "user",
@@ -296,11 +396,11 @@ export class LlmClassifier {
   }
 
   /**
-   * Classifies an execution request using the configured LLM endpoint (#118, #127, #129, #115, #117).
+   * Classifies an execution request using the configured LLM endpoint (#118, #127, #129, #115, #117, #59, #66).
    *
    * @param {any} execution
    * @param {any} [context]
-   * @returns {Promise<{ verdict: "allow" | "deny" | "ask", reason: string, timeout?: boolean, error?: any }>}
+   * @returns {Promise<{ verdict: "allow" | "deny" | "ask", reason: string, riskScore?: number, tags?: string[], timeout?: boolean, error?: any }>}
    */
   async classify(execution, context = {}) {
     if (!this.endpoint || typeof this.fetch !== "function") {
@@ -308,15 +408,19 @@ export class LlmClassifier {
     }
 
     const messages = this.formatMessages(execution, context);
-    const body = JSON.stringify({
-      model: this.model,
-      messages,
-      temperature: 0.1,
-      response_format: { type: "json_object" },
-    });
 
-    try {
-      const response = await withLlmRetry(
+    const callApi = async (useJsonMode) => {
+      const payload = {
+        model: this.model,
+        messages,
+        temperature: 0.1,
+      };
+      if (useJsonMode) {
+        payload.response_format = { type: "json_object" };
+      }
+      const body = JSON.stringify(payload);
+
+      return withLlmRetry(
         async () => {
           const controller = new AbortController();
           const timer = setTimeout(() => controller.abort(), this.timeoutMs);
@@ -354,23 +458,49 @@ export class LlmClassifier {
           retryOn: shouldRetryLlmError,
         }
       );
+    };
+
+    try {
+      let response;
+      if (this.supportsJsonMode) {
+        try {
+          response = await callApi(true);
+        } catch (err) {
+          if (isShapeRejectError(err)) {
+            this.supportsJsonMode = false;
+            response = await callApi(false);
+          } else {
+            throw err;
+          }
+        }
+      } else {
+        response = await callApi(false);
+      }
 
       const content = response?.choices?.[0]?.message?.content;
       if (!content) {
         return { verdict: "ask", reason: "classifier-empty-response" };
       }
 
-      let parsed;
-      try {
-        parsed = JSON.parse(content);
-      } catch {
+      const parsed = extractJsonPayload(content);
+      if (!parsed) {
         return { verdict: "ask", reason: "classifier-invalid-json" };
       }
 
-      const verdict = ["allow", "deny", "ask"].includes(parsed.verdict) ? parsed.verdict : "ask";
+      const validated = validateClassifierResponse(parsed);
+      if (!validated.valid) {
+        return {
+          verdict: "ask",
+          reason: "malformed-classifier-response",
+          detail: validated.error,
+        };
+      }
+
       return {
-        verdict,
-        reason: parsed.reason || `classifier-${verdict}`,
+        verdict: validated.verdict,
+        reason: validated.reason,
+        riskScore: validated.riskScore,
+        tags: validated.tags,
       };
     } catch (err) {
       const isTimeout = CircuitBreaker.isFaultOrTimeout(err) || Boolean(err?.isTimeout);