@useatlas/create 0.0.1

package/templates/docker/src/lib/tools/salesforce.ts

@@ -0,0 +1,138 @@
+/**
+ * Salesforce SOQL query tool for the Atlas agent.
+ *
+ * Parallel to executeSQL but for Salesforce objects via SOQL.
+ * Uses the SalesforceDataSource instead of DBConnection.
+ */
+
+import { tool } from "ai";
+import { z } from "zod";
+import {
+  getSalesforceSource,
+  listSalesforceSources,
+} from "@atlas/api/lib/db/salesforce";
+import { validateSOQL, appendSOQLLimit } from "./soql-validation";
+import { getWhitelistedTables } from "@atlas/api/lib/semantic";
+import { logQueryAudit } from "@atlas/api/lib/auth/audit";
+import { SENSITIVE_PATTERNS } from "@atlas/api/lib/security";
+import { createLogger } from "@atlas/api/lib/logger";
+
+const log = createLogger("salesforce-tool");
+
+const ROW_LIMIT = parseInt(process.env.ATLAS_ROW_LIMIT ?? "1000", 10);
+const QUERY_TIMEOUT = parseInt(
+  process.env.ATLAS_QUERY_TIMEOUT ?? "30000",
+  10,
+);
+
+export const querySalesforce = tool({
+  description: `Execute a read-only SOQL query against Salesforce. Only SELECT queries are allowed.
+
+Rules:
+- Always read the relevant entity schema from the semantic layer BEFORE writing SOQL
+- Use exact field names from the schema — never guess
+- SOQL does not support JOINs — use relationship queries instead (e.g. Account.Name)
+- Include a LIMIT clause for large result sets
+- If a query fails, fix the issue — do not retry the same SOQL`,
+
+  inputSchema: z.object({
+    soql: z.string().describe("The SELECT SOQL query to execute"),
+    explanation: z
+      .string()
+      .describe("Brief explanation of what this query does and why"),
+    connectionId: z
+      .string()
+      .optional()
+      .describe(
+        "Target Salesforce connection ID. Omit for the default Salesforce connection.",
+      ),
+  }),
+
+  execute: async ({ soql, explanation, connectionId }) => {
+    // Resolve which Salesforce source to use
+    const sources = listSalesforceSources();
+    const connId = connectionId ?? (sources.length > 0 ? sources[0] : "default");
+
+    let source;
+    try {
+      source = getSalesforceSource(connId);
+    } catch {
+      return {
+        success: false,
+        error: `Salesforce source "${connId}" is not registered. Available: ${sources.join(", ") || "(none)"}`,
+      };
+    }
+
+    // Get whitelist for this connection
+    const allowed = getWhitelistedTables(connId);
+
+    // Validate SOQL
+    const validation = validateSOQL(soql, allowed);
+    if (!validation.valid) {
+      logQueryAudit({
+        sql: soql.slice(0, 2000),
+        durationMs: 0,
+        rowCount: null,
+        success: false,
+        error: `Validation rejected: ${validation.error}`,
+      });
+      return { success: false, error: validation.error };
+    }
+
+    // Auto-append LIMIT
+    const querySoql = appendSOQLLimit(soql.trim(), ROW_LIMIT);
+
+    const start = performance.now();
+    try {
+      const result = await source.query(querySoql, QUERY_TIMEOUT);
+      const durationMs = Math.round(performance.now() - start);
+      const truncated = result.rows.length >= ROW_LIMIT;
+
+      try {
+        logQueryAudit({
+          sql: querySoql,
+          durationMs,
+          rowCount: result.rows.length,
+          success: true,
+        });
+      } catch (auditErr) {
+        log.warn({ err: auditErr }, "Failed to write query audit log");
+      }
+
+      return {
+        success: true,
+        explanation,
+        row_count: result.rows.length,
+        columns: result.columns,
+        rows: result.rows,
+        truncated,
+      };
+    } catch (err) {
+      const durationMs = Math.round(performance.now() - start);
+      const message =
+        err instanceof Error ? err.message : "Unknown Salesforce error";
+
+      try {
+        logQueryAudit({
+          sql: querySoql,
+          durationMs,
+          rowCount: null,
+          success: false,
+          error: message,
+        });
+      } catch (auditErr) {
+        log.warn({ err: auditErr }, "Failed to write query audit log");
+      }
+
+      // Block errors that might expose connection details or internal state
+      if (SENSITIVE_PATTERNS.test(message)) {
+        return {
+          success: false,
+          error: "Salesforce query failed — check server logs for details.",
+        };
+      }
+
+      return { success: false, error: message };
+    }
+  },
+});

package/templates/docker/src/lib/tools/soql-validation.ts

@@ -0,0 +1,172 @@
+/**
+ * SOQL validation — regex + structural checks.
+ *
+ * SOQL is simpler than SQL, so no AST parser is needed. Validation layers:
+ * 0. Empty check
+ * 1. Regex mutation guard (INSERT, UPDATE, DELETE, UPSERT, MERGE, UNDELETE)
+ * 2. Must start with SELECT, no semicolons
+ * 3. Object whitelist — FROM object must be in the allowed set
+ */
+
+const SOQL_FORBIDDEN_PATTERNS = [
+  /\b(INSERT)\b/i,
+  /\b(UPDATE)\b/i,
+  /\b(DELETE)\b/i,
+  /\b(UPSERT)\b/i,
+  /\b(MERGE)\b/i,
+  /\b(UNDELETE)\b/i,
+];
+
+/**
+ * Strip single-quoted string literals from SOQL so regex guards don't match
+ * keywords embedded in user values (e.g. `WHERE Name = 'delete this'`).
+ */
+function stripStringLiterals(soql: string): string {
+  return soql.replace(/'[^']*'/g, "''");
+}
+
+/**
+ * Extract top-level object names referenced in FROM clauses.
+ *
+ * Parent-to-child relationship subqueries — `(SELECT ... FROM Contacts)` inside
+ * the SELECT list — use relationship names (plural) that don't appear in the
+ * object whitelist. Salesforce enforces object-level security server-side for
+ * these, so we skip nested FROM inside parenthesized subqueries.
+ *
+ * Semi-join / anti-join subqueries in WHERE — `WHERE Id IN (SELECT ... FROM Contact)`
+ * — reference real object names and ARE checked.
+ */
+function extractFromObjects(soql: string): string[] {
+  const objects: string[] = [];
+
+  // Step 1: Remove parenthesized subqueries that appear in the SELECT clause
+  // (relationship subqueries). We do this by stripping content between the
+  // top-level SELECT and the top-level FROM, then extracting FROM objects from
+  // the remainder.
+  //
+  // Strategy: find the top-level FROM position (not inside parens), then only
+  // extract FROM objects from that point onward.
+
+  let depth = 0;
+  let topLevelFromIndex = -1;
+
+  // We need to find the top-level FROM keyword (not inside parentheses)
+  const upperSoql = soql.toUpperCase();
+  for (let i = 0; i < soql.length; i++) {
+    if (soql[i] === "(") {
+      depth++;
+    } else if (soql[i] === ")") {
+      depth--;
+    } else if (depth === 0) {
+      // Check if this position starts "FROM " at the top level
+      if (
+        upperSoql.startsWith("FROM", i) &&
+        (i === 0 || /\s/.test(soql[i - 1])) &&
+        i + 4 < soql.length &&
+        /\s/.test(soql[i + 4])
+      ) {
+        topLevelFromIndex = i;
+        break;
+      }
+    }
+  }
+
+  if (topLevelFromIndex === -1) {
+    return objects;
+  }
+
+  // Extract the top-level FROM object
+  const afterFrom = soql.slice(topLevelFromIndex);
+  const topMatch = /\bFROM\s+(\w+)/i.exec(afterFrom);
+  if (topMatch) {
+    objects.push(topMatch[1]);
+  }
+
+  // Now extract FROM objects in WHERE/HAVING subqueries (semi-joins/anti-joins).
+  // These are parenthesized SELECT...FROM blocks that appear AFTER the top-level FROM.
+  const whereClause = soql.slice(topLevelFromIndex + (topMatch ? topMatch[0].length : 4));
+  // Find FROM inside parenthesized subqueries in WHERE — these are real object references
+  const subqueryPattern = /\(\s*SELECT\b[^)]*\bFROM\s+(\w+)/gi;
+  let subMatch;
+  while ((subMatch = subqueryPattern.exec(whereClause)) !== null) {
+    objects.push(subMatch[1]);
+  }
+
+  return objects;
+}
+
+/**
+ * Validate a SOQL query for safety.
+ *
+ * @param soql - The SOQL query string.
+ * @param allowedObjects - Set of allowed Salesforce object names (case-insensitive).
+ * @returns Validation result.
+ */
+export function validateSOQL(
+  soql: string,
+  allowedObjects: Set<string>,
+): { valid: boolean; error?: string } {
+  // 0. Empty check
+  const trimmed = soql.trim();
+  if (!trimmed) {
+    return { valid: false, error: "Empty query" };
+  }
+
+  // Reject semicolons (no statement chaining)
+  if (trimmed.includes(";")) {
+    return { valid: false, error: "Semicolons are not allowed in SOQL queries" };
+  }
+
+  // 1. Regex mutation guard — strip string literals first so keywords inside
+  //    values like `WHERE Name = 'delete this'` don't trigger false positives.
+  const stripped = stripStringLiterals(trimmed);
+  for (const pattern of SOQL_FORBIDDEN_PATTERNS) {
+    if (pattern.test(stripped)) {
+      return {
+        valid: false,
+        error: `Forbidden SOQL operation detected: ${pattern.source}`,
+      };
+    }
+  }
+
+  // 2. Must start with SELECT
+  if (!/^\s*SELECT\b/i.test(trimmed)) {
+    return {
+      valid: false,
+      error: "Only SELECT queries are allowed in SOQL",
+    };
+  }
+
+  // 3. Object whitelist
+  const objects = extractFromObjects(trimmed);
+  if (objects.length === 0) {
+    return { valid: false, error: "No FROM clause found in query" };
+  }
+
+  // Build lowercase allowed set for case-insensitive comparison
+  const allowedLower = new Set(
+    Array.from(allowedObjects).map((o) => o.toLowerCase()),
+  );
+
+  for (const obj of objects) {
+    if (!allowedLower.has(obj.toLowerCase())) {
+      return {
+        valid: false,
+        error: `Object "${obj}" is not in the allowed list. Check catalog.yml for available objects.`,
+      };
+    }
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Append a LIMIT clause to a SOQL query if one is not already present.
+ */
+export function appendSOQLLimit(soql: string, limit: number): string {
+  const trimmed = soql.trim();
+  if (/\bLIMIT\b/i.test(trimmed)) {
+    return trimmed;
+  }
+  return `${trimmed} LIMIT ${limit}`;
+}