@useatlas/create 0.0.1

package/templates/nextjs-standalone/src/lib/tools/__tests__/soql-validation.test.ts

@@ -0,0 +1,303 @@
+import { describe, it, expect } from "bun:test";
+import { validateSOQL, appendSOQLLimit } from "../soql-validation";
+
+const ALLOWED = new Set(["Account", "Contact", "Opportunity", "Lead"]);
+
+describe("validateSOQL", () => {
+  describe("Layer 0: Empty check", () => {
+    it("rejects empty string", () => {
+      const result = validateSOQL("", ALLOWED);
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain("Empty");
+    });
+
+    it("rejects whitespace-only", () => {
+      const result = validateSOQL("   \n\t  ", ALLOWED);
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain("Empty");
+    });
+  });
+
+  describe("Layer 1: Mutation guard", () => {
+    for (const keyword of ["INSERT", "UPDATE", "DELETE", "UPSERT", "MERGE", "UNDELETE"]) {
+      it(`rejects ${keyword}`, () => {
+        const result = validateSOQL(`${keyword} INTO Account`, ALLOWED);
+        expect(result.valid).toBe(false);
+        expect(result.error).toContain("Forbidden");
+      });
+
+      it(`rejects ${keyword.toLowerCase()}`, () => {
+        const result = validateSOQL(`${keyword.toLowerCase()} into account`, ALLOWED);
+        expect(result.valid).toBe(false);
+        expect(result.error).toContain("Forbidden");
+      });
+    }
+  });
+
+  describe("Layer 2: SELECT-only", () => {
+    it("accepts SELECT query", () => {
+      const result = validateSOQL("SELECT Id FROM Account", ALLOWED);
+      expect(result.valid).toBe(true);
+    });
+
+    it("rejects non-SELECT query", () => {
+      const result = validateSOQL("DESCRIBE Account", ALLOWED);
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain("Only SELECT");
+    });
+
+    it("rejects semicolons", () => {
+      const result = validateSOQL("SELECT Id FROM Account;", ALLOWED);
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain("Semicolons");
+    });
+
+    it("rejects multiple statements", () => {
+      const result = validateSOQL("SELECT Id FROM Account; SELECT Id FROM Contact", ALLOWED);
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain("Semicolons");
+    });
+  });
+
+  describe("Layer 3: Object whitelist", () => {
+    it("allows whitelisted objects", () => {
+      const result = validateSOQL("SELECT Id, Name FROM Account", ALLOWED);
+      expect(result.valid).toBe(true);
+    });
+
+    it("rejects non-whitelisted objects", () => {
+      const result = validateSOQL("SELECT Id FROM CustomObject__c", ALLOWED);
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain("not in the allowed list");
+    });
+
+    it("checks subquery objects", () => {
+      const result = validateSOQL(
+        "SELECT Id FROM Account WHERE Id IN (SELECT AccountId FROM CustomObject__c)",
+        ALLOWED,
+      );
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain("CustomObject__c");
+    });
+
+    it("allows subquery with whitelisted objects", () => {
+      const result = validateSOQL(
+        "SELECT Id FROM Account WHERE Id IN (SELECT AccountId FROM Contact)",
+        ALLOWED,
+      );
+      expect(result.valid).toBe(true);
+    });
+
+    it("is case-insensitive", () => {
+      const result = validateSOQL("SELECT Id FROM account", ALLOWED);
+      expect(result.valid).toBe(true);
+    });
+
+    it("rejects queries with no FROM clause", () => {
+      const result = validateSOQL("SELECT 1", ALLOWED);
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain("No FROM");
+    });
+  });
+
+  describe("Relationship subquery whitelist bypass (parent-to-child)", () => {
+    it("accepts parent-to-child relationship subquery with plural relationship name", () => {
+      // "Contacts" is the relationship name (plural), not in the whitelist.
+      // Only "Contact" (singular) is whitelisted. This should pass because
+      // relationship subqueries in SELECT are not whitelist-checked.
+      const result = validateSOQL(
+        "SELECT Id, Name, (SELECT LastName FROM Contacts) FROM Account",
+        ALLOWED,
+      );
+      expect(result.valid).toBe(true);
+    });
+
+    it("accepts multiple relationship subqueries in SELECT", () => {
+      const result = validateSOQL(
+        "SELECT Id, (SELECT LastName FROM Contacts), (SELECT Amount FROM Opportunities) FROM Account",
+        ALLOWED,
+      );
+      expect(result.valid).toBe(true);
+    });
+
+    it("accepts relationship subquery with unknown relationship name", () => {
+      // Custom relationship names like "Cases" won't be in the whitelist
+      const result = validateSOQL(
+        "SELECT Id, (SELECT Subject FROM Cases) FROM Account",
+        ALLOWED,
+      );
+      expect(result.valid).toBe(true);
+    });
+
+    it("still rejects non-whitelisted objects in WHERE semi-join subqueries", () => {
+      // Semi-join subqueries in WHERE reference real object names — must be checked
+      const result = validateSOQL(
+        "SELECT Id FROM Account WHERE Id IN (SELECT AccountId FROM CustomObject__c)",
+        ALLOWED,
+      );
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain("CustomObject__c");
+    });
+
+    it("allows whitelisted objects in WHERE semi-join subqueries", () => {
+      const result = validateSOQL(
+        "SELECT Id FROM Account WHERE Id IN (SELECT AccountId FROM Contact)",
+        ALLOWED,
+      );
+      expect(result.valid).toBe(true);
+    });
+
+    it("accepts relationship subquery AND valid WHERE subquery together", () => {
+      const result = validateSOQL(
+        "SELECT Id, (SELECT LastName FROM Contacts) FROM Account WHERE Id IN (SELECT AccountId FROM Opportunity)",
+        ALLOWED,
+      );
+      expect(result.valid).toBe(true);
+    });
+
+    it("rejects relationship subquery with invalid WHERE subquery", () => {
+      const result = validateSOQL(
+        "SELECT Id, (SELECT LastName FROM Contacts) FROM Account WHERE Id IN (SELECT AccountId FROM Forbidden__c)",
+        ALLOWED,
+      );
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain("Forbidden__c");
+    });
+
+    it("still checks top-level FROM object", () => {
+      const result = validateSOQL(
+        "SELECT Id, (SELECT LastName FROM Contacts) FROM NotAllowed__c",
+        ALLOWED,
+      );
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain("NotAllowed__c");
+    });
+  });
+
+  describe("String literal false positives in mutation guard", () => {
+    it("allows 'delete' inside a string literal", () => {
+      const result = validateSOQL(
+        "SELECT Id FROM Account WHERE Name = 'delete this'",
+        ALLOWED,
+      );
+      expect(result.valid).toBe(true);
+    });
+
+    it("allows 'update' inside a string literal", () => {
+      const result = validateSOQL(
+        "SELECT Id FROM Account WHERE Description = 'please update record'",
+        ALLOWED,
+      );
+      expect(result.valid).toBe(true);
+    });
+
+    it("allows 'insert' inside a string literal", () => {
+      const result = validateSOQL(
+        "SELECT Id FROM Contact WHERE Name = 'insert coin'",
+        ALLOWED,
+      );
+      expect(result.valid).toBe(true);
+    });
+
+    it("allows 'merge' inside a string literal", () => {
+      const result = validateSOQL(
+        "SELECT Id FROM Lead WHERE Status = 'merge pending'",
+        ALLOWED,
+      );
+      expect(result.valid).toBe(true);
+    });
+
+    it("allows 'upsert' inside a string literal", () => {
+      const result = validateSOQL(
+        "SELECT Id FROM Account WHERE Name = 'upsert test'",
+        ALLOWED,
+      );
+      expect(result.valid).toBe(true);
+    });
+
+    it("allows LIKE pattern with forbidden keyword", () => {
+      const result = validateSOQL(
+        "SELECT Id FROM Account WHERE Name LIKE '%delete%'",
+        ALLOWED,
+      );
+      expect(result.valid).toBe(true);
+    });
+
+    it("still rejects actual DELETE statements", () => {
+      const result = validateSOQL("DELETE FROM Account", ALLOWED);
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain("Forbidden");
+    });
+
+    it("still rejects forbidden keyword outside string literal even with strings present", () => {
+      // The keyword DELETE appears outside the string
+      const result = validateSOQL(
+        "DELETE FROM Account WHERE Name = 'safe string'",
+        ALLOWED,
+      );
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain("Forbidden");
+    });
+
+    it("handles multiple string literals with forbidden keywords", () => {
+      const result = validateSOQL(
+        "SELECT Id FROM Account WHERE Name = 'delete' AND Type = 'update this'",
+        ALLOWED,
+      );
+      expect(result.valid).toBe(true);
+    });
+
+    it("handles empty string literals", () => {
+      const result = validateSOQL(
+        "SELECT Id FROM Account WHERE Name = ''",
+        ALLOWED,
+      );
+      expect(result.valid).toBe(true);
+    });
+  });
+
+  describe("valid queries", () => {
+    it("accepts basic query", () => {
+      const result = validateSOQL("SELECT Id, Name FROM Account LIMIT 10", ALLOWED);
+      expect(result.valid).toBe(true);
+    });
+
+    it("accepts query with WHERE clause", () => {
+      const result = validateSOQL(
+        "SELECT Id, Name FROM Account WHERE Name = 'Test'",
+        ALLOWED,
+      );
+      expect(result.valid).toBe(true);
+    });
+
+    it("accepts query with aggregate functions", () => {
+      const result = validateSOQL(
+        "SELECT COUNT(Id) FROM Opportunity GROUP BY StageName",
+        ALLOWED,
+      );
+      expect(result.valid).toBe(true);
+    });
+  });
+});
+
+describe("appendSOQLLimit", () => {
+  it("appends LIMIT when not present", () => {
+    const result = appendSOQLLimit("SELECT Id FROM Account", 100);
+    expect(result).toBe("SELECT Id FROM Account LIMIT 100");
+  });
+
+  it("does not append LIMIT when already present", () => {
+    const result = appendSOQLLimit("SELECT Id FROM Account LIMIT 50", 100);
+    expect(result).toBe("SELECT Id FROM Account LIMIT 50");
+  });
+
+  it("is case-insensitive for existing LIMIT", () => {
+    const result = appendSOQLLimit("SELECT Id FROM Account limit 50", 100);
+    expect(result).toBe("SELECT Id FROM Account limit 50");
+  });
+
+  it("trims whitespace", () => {
+    const result = appendSOQLLimit("  SELECT Id FROM Account  ", 100);
+    expect(result).toBe("SELECT Id FROM Account LIMIT 100");
+  });
+});

package/templates/nextjs-standalone/src/lib/tools/__tests__/sql-audit.test.ts

@@ -0,0 +1,225 @@
+/**
+ * Integration tests: executeSQL → logQueryAudit → internal DB.
+ *
+ * Tests the full audit path without mocking @/lib/auth/audit or @/lib/logger.
+ * Instead, uses _resetPool() to inject a mock pg.Pool that captures INSERT
+ * queries from internalExecute. This avoids bun mock.module leaking across
+ * test files.
+ */
+
+import { describe, expect, it, beforeEach, afterEach, mock, type Mock } from "bun:test";
+import { _resetPool, type InternalPool } from "@atlas/api/lib/db/internal";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyResult = any;
+
+// --- Mocks for sql.ts dependencies (NOT audit or logger) ---
+
+mock.module("@atlas/api/lib/semantic", () => ({
+  getWhitelistedTables: () => new Set(["companies", "people"]),
+  _resetWhitelists: () => {},
+}));
+
+let queryFn: Mock<(sql: string, timeout: number) => Promise<{ columns: string[]; rows: Record<string, unknown>[] }>>;
+
+const mockConn = {
+  query: (...args: [string, number]) => queryFn(...args),
+  close: async () => {},
+};
+
+mock.module("@atlas/api/lib/db/connection", () => ({
+  getDB: () => mockConn,
+  connections: {
+    get: () => mockConn,
+    getDefault: () => mockConn,
+    getDBType: () => "postgres",
+    getTargetHost: () => "localhost",
+    getValidator: () => undefined,
+    list: () => ["default"],
+  },
+  detectDBType: () => "postgres",
+}));
+
+mock.module("@atlas/api/lib/tracing", () => ({
+  withSpan: async (
+    _name: string,
+    _attrs: Record<string, unknown>,
+    fn: () => Promise<unknown>,
+  ) => fn(),
+}));
+
+mock.module("@atlas/api/lib/db/source-rate-limit", () => ({
+  acquireSourceSlot: () => ({ acquired: true }),
+  decrementSourceConcurrency: () => {},
+}));
+
+// Import after mocks
+const { executeSQL } = await import("@atlas/api/lib/tools/sql");
+
+// --- Internal DB mock pool to capture audit inserts ---
+
+let auditInserts: Array<{ sql: string; params?: unknown[] }> = [];
+
+const mockPool: InternalPool = {
+  query: async (sql: string, params?: unknown[]) => {
+    auditInserts.push({ sql, params });
+    return { rows: [] };
+  },
+  end: async () => {},
+  on: () => {},
+};
+
+/**
+ * Audit INSERT parameters are positional ($1-$8).
+ * This helper extracts named fields from the params array so tests
+ * are not coupled to column ordering.
+ */
+function extractAuditParams(params: unknown[]) {
+  return {
+    userId: params[0],
+    userLabel: params[1],
+    authMode: params[2],
+    sql: params[3] as string,
+    durationMs: params[4] as number,
+    rowCount: params[5] as number | null,
+    success: params[6] as boolean,
+    error: params[7] as string | null,
+    sourceId: params[8] as string | null,
+    sourceType: params[9] as string | null,
+    targetHost: params[10] as string | null,
+  };
+}
+
+describe("executeSQL audit logging", () => {
+  const origDbUrl = process.env.DATABASE_URL;
+  const origDatasource = process.env.ATLAS_DATASOURCE_URL;
+
+  beforeEach(() => {
+    auditInserts = [];
+    process.env.ATLAS_DATASOURCE_URL = "postgresql://test:test@localhost:5432/test";
+    // Enable internal DB so audit inserts are captured
+    process.env.DATABASE_URL = "postgresql://test:test@localhost:5432/atlas";
+    _resetPool(mockPool);
+    queryFn = mock(() =>
+      Promise.resolve({
+        columns: ["id", "name"],
+        rows: [{ id: 1, name: "Acme" }],
+      }),
+    );
+  });
+
+  afterEach(() => {
+    if (origDbUrl) {
+      process.env.DATABASE_URL = origDbUrl;
+    } else {
+      delete process.env.DATABASE_URL;
+    }
+    if (origDatasource) {
+      process.env.ATLAS_DATASOURCE_URL = origDatasource;
+    } else {
+      delete process.env.ATLAS_DATASOURCE_URL;
+    }
+    _resetPool(null);
+  });
+
+  const exec = (sql: string) =>
+    executeSQL.execute!(
+      { sql, explanation: "test" },
+      { toolCallId: "test", messages: [], abortSignal: undefined as never },
+    ) as Promise<AnyResult>;
+
+  /** Find audit INSERT queries from the mock pool */
+  const getAuditInserts = () =>
+    auditInserts.filter((q) => q.sql.includes("INSERT INTO audit_log"));
+
+  it("logs audit with success: true on successful query", async () => {
+    const result = await exec("SELECT id, name FROM companies");
+
+    expect(result.success).toBe(true);
+    const inserts = getAuditInserts();
+    expect(inserts).toHaveLength(1);
+    const audit = extractAuditParams(inserts[0].params!);
+    expect(audit.success).toBe(true);
+    expect(audit.sql).toContain("SELECT id, name FROM companies");
+    expect(audit.rowCount).toBe(1);
+  });
+
+  it("logs audit with success: false on query execution failure", async () => {
+    queryFn = mock(() => Promise.reject(new Error("column \"nope\" does not exist")));
+
+    const result = await exec("SELECT nope FROM companies");
+
+    expect(result.success).toBe(false);
+    const inserts = getAuditInserts();
+    expect(inserts).toHaveLength(1);
+    const audit = extractAuditParams(inserts[0].params!);
+    expect(audit.success).toBe(false);
+    expect(audit.error).toContain("column \"nope\" does not exist");
+    expect(audit.rowCount).toBeNull();
+  });
+
+  it("logs audit with 'Validation rejected:' prefix on validation failure", async () => {
+    const result = await exec("DROP TABLE companies");
+
+    expect(result.success).toBe(false);
+    const inserts = getAuditInserts();
+    expect(inserts).toHaveLength(1);
+    const audit = extractAuditParams(inserts[0].params!);
+    expect(audit.success).toBe(false);
+    expect((audit.error as string).startsWith("Validation rejected:")).toBe(true);
+    expect(audit.durationMs).toBe(0);
+    expect(audit.rowCount).toBeNull();
+  });
+
+  it("logs audit for non-whitelisted table access attempt", async () => {
+    const result = await exec("SELECT * FROM unknown_table");
+
+    expect(result.success).toBe(false);
+    const inserts = getAuditInserts();
+    expect(inserts).toHaveLength(1);
+    const audit = extractAuditParams(inserts[0].params!);
+    expect(audit.success).toBe(false);
+    expect(audit.error).toContain("Validation rejected:");
+    expect(audit.error).toContain("not in the allowed list");
+  });
+
+  it("truncates SQL to 2000 chars in validation-rejected audit entries", async () => {
+    const longSql = "DROP TABLE " + "x".repeat(3000);
+    await exec(longSql);
+
+    const inserts = getAuditInserts();
+    expect(inserts).toHaveLength(1);
+    const audit = extractAuditParams(inserts[0].params!);
+    expect(audit.sql.length).toBeLessThanOrEqual(2000);
+  });
+
+  it("auto-appends LIMIT to the SQL logged on success", async () => {
+    await exec("SELECT id FROM companies");
+
+    const inserts = getAuditInserts();
+    expect(inserts).toHaveLength(1);
+    const audit = extractAuditParams(inserts[0].params!);
+    expect(audit.sql).toContain("LIMIT");
+  });
+
+  it("includes sourceId and targetHost in audit entries on success", async () => {
+    await exec("SELECT id FROM companies");
+
+    const inserts = getAuditInserts();
+    expect(inserts).toHaveLength(1);
+    const audit = extractAuditParams(inserts[0].params!);
+    expect(audit.sourceId).toBe("default");
+    expect(audit.sourceType).toBe("postgres");
+    expect(audit.targetHost).toBe("localhost");
+  });
+
+  it("includes sourceId in validation-rejected audit entries", async () => {
+    await exec("DROP TABLE companies");
+
+    const inserts = getAuditInserts();
+    expect(inserts).toHaveLength(1);
+    const audit = extractAuditParams(inserts[0].params!);
+    expect(audit.sourceId).toBe("default");
+    expect(audit.sourceType).toBe("postgres");
+  });
+});

package/templates/nextjs-standalone/src/lib/tools/__tests__/sql-connection-whitelist.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Tests for per-connection table whitelist enforcement in validateSQL.
+ *
+ * Separated from sql.test.ts because it needs a different mock for
+ * getWhitelistedTables that respects the connectionId parameter.
+ */
+import { describe, it, expect, mock } from "bun:test";
+
+// Mock getWhitelistedTables to return different sets per connectionId
+mock.module("@atlas/api/lib/semantic", () => ({
+  getWhitelistedTables: (connectionId?: string) => {
+    switch (connectionId) {
+      case "warehouse":
+        return new Set(["events", "analytics.events"]);
+      case "nonexistent":
+        return new Set(); // empty — unknown connection
+      default:
+        return new Set(["orders", "users", "companies"]);
+    }
+  },
+  _resetWhitelists: () => {},
+}));
+
+// Mock the DB connection — validateSQL doesn't need it, but the module
+// imports it at the top level.
+mock.module("@atlas/api/lib/db/connection", () => ({
+  getDB: () => ({
+    query: async () => ({ columns: [], rows: [] }),
+    close: async () => {},
+  }),
+  connections: {
+    get: () => ({
+      query: async () => ({ columns: [], rows: [] }),
+      close: async () => {},
+    }),
+    getDefault: () => ({
+      query: async () => ({ columns: [], rows: [] }),
+      close: async () => {},
+    }),
+    getDBType: (id?: string) => {
+      if (id === "nonexistent") throw new Error(`Connection "nonexistent" is not registered.`);
+      return "postgres" as const;
+    },
+    getValidator: () => undefined,
+    list: () => ["default", "warehouse"],
+    describe: () => [
+      { id: "default", dbType: "postgres" as const },
+      { id: "warehouse", dbType: "postgres" as const },
+    ],
+    _reset: () => {},
+  },
+  detectDBType: () => "postgres" as const,
+  ConnectionRegistry: class {},
+}));
+
+const { validateSQL } = await import("../sql");
+
+describe("per-connection whitelist enforcement", () => {
+  it("allows table in default connection whitelist", () => {
+    const result = validateSQL("SELECT * FROM orders");
+    expect(result.valid).toBe(true);
+  });
+
+  it("allows table in warehouse connection whitelist", () => {
+    const result = validateSQL("SELECT * FROM events", "warehouse");
+    expect(result.valid).toBe(true);
+  });
+
+  it("rejects table not in target connection whitelist", () => {
+    const result = validateSQL("SELECT * FROM orders", "warehouse");
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain("not in the allowed list");
+  });
+
+  it("rejects all tables for unknown connection", () => {
+    // getDBType throws for "nonexistent", so validateSQL returns an error
+    const result = validateSQL("SELECT * FROM orders", "nonexistent");
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain("not registered");
+  });
+
+  it("default connection cannot access warehouse-only tables", () => {
+    const result = validateSQL("SELECT * FROM events");
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain("not in the allowed list");
+  });
+
+  it("allows schema-qualified table in warehouse whitelist", () => {
+    const result = validateSQL("SELECT * FROM analytics.events", "warehouse");
+    expect(result.valid).toBe(true);
+  });
+
+  it("rejects schema-qualified table not in warehouse whitelist", () => {
+    const result = validateSQL("SELECT * FROM public.orders", "warehouse");
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain("not in the allowed list");
+  });
+});