@aurorajs.dev/catalyst-cli 1.1.3 → 2.0.0

package/dist/templates/backend/application/scripts/db/query.spec.ts

@@ -0,0 +1,497 @@
+import type { Pool, PoolClient } from 'pg';
+
+import {
+  DENIED_SQL_FUNCTIONS,
+  formatAsJson,
+  formatAsTable,
+  PRIVILEGE_PROBE_QUERY,
+  resolveQueryCredentials,
+  runReadOnlyQuery,
+  STATEMENT_TIMEOUT_QUERY,
+  validateReadOnlyQuery,
+} from './query.js';
+
+describe('resolveQueryCredentials', () => {
+  it('rejects a missing DATABASE_QUERY_USER, naming both env vars', () => {
+    const result = resolveQueryCredentials({});
+
+    expect(result.ok).toBe(false);
+    expect(result.ok === false && result.reason).toContain('DATABASE_QUERY_USER');
+    expect(result.ok === false && result.reason).toContain('DATABASE_QUERY_PASSWORD');
+  });
+
+  it('rejects an empty-string DATABASE_QUERY_USER', () => {
+    const result = resolveQueryCredentials({ DATABASE_QUERY_USER: '' });
+
+    expect(result.ok).toBe(false);
+    expect(result.ok === false && result.reason).toContain('DATABASE_QUERY_USER');
+  });
+
+  it('points the reader at the catalyst-schema-migrations skill for the CREATE ROLE snippet', () => {
+    const result = resolveQueryCredentials({});
+
+    expect(result.ok === false && result.reason).toContain(
+      'backend/.claude/skills/catalyst-schema-migrations/SKILL.md',
+    );
+  });
+
+  it('says the role must not be a superuser', () => {
+    const result = resolveQueryCredentials({});
+
+    expect(result.ok === false && result.reason.toLowerCase()).toContain('superuser');
+  });
+
+  it('accepts a present user with a present password', () => {
+    const result = resolveQueryCredentials({
+      DATABASE_QUERY_USER: 'catalyst_readonly',
+      DATABASE_QUERY_PASSWORD: 'secret',
+    });
+
+    expect(result).toEqual({ ok: true, user: 'catalyst_readonly', password: 'secret' });
+  });
+
+  // Decision: an empty/absent password is NOT an error — trust auth and `.pgpass` are
+  // legitimate ways to authenticate a role without a password in the environment. Only
+  // DATABASE_QUERY_USER is mandatory. It must resolve to `undefined`, not `''`: `pg` only
+  // falls through to `.pgpass`/trust auth when the password is `null`/`undefined` — an
+  // empty string is sent to the server as-is and fails authentication for any role that
+  // actually needs a password.
+  it('accepts a present user with a missing password, resolving it to undefined', () => {
+    const result = resolveQueryCredentials({ DATABASE_QUERY_USER: 'catalyst_readonly' });
+
+    expect(result).toEqual({ ok: true, user: 'catalyst_readonly', password: undefined });
+  });
+
+  it('accepts a present user with an empty-string password, resolving it to undefined', () => {
+    const result = resolveQueryCredentials({
+      DATABASE_QUERY_USER: 'catalyst_readonly',
+      DATABASE_QUERY_PASSWORD: '',
+    });
+
+    expect(result).toEqual({ ok: true, user: 'catalyst_readonly', password: undefined });
+  });
+});
+
+describe('validateReadOnlyQuery', () => {
+  it('rejects empty input', () => {
+    expect(validateReadOnlyQuery('')).toEqual({ ok: false, reason: expect.any(String) });
+  });
+
+  it('rejects blank input', () => {
+    expect(validateReadOnlyQuery('   \n  ')).toEqual({ ok: false, reason: expect.any(String) });
+  });
+
+  it('accepts a SELECT statement', () => {
+    expect(validateReadOnlyQuery('SELECT 1')).toEqual({ ok: true, query: 'SELECT 1' });
+  });
+
+  it('accepts a WITH statement', () => {
+    const query = 'WITH t AS (SELECT 1) SELECT * FROM t';
+    expect(validateReadOnlyQuery(query)).toEqual({ ok: true, query });
+  });
+
+  it('is case-insensitive on the leading keyword', () => {
+    expect(validateReadOnlyQuery('select 1')).toEqual({ ok: true, query: 'select 1' });
+    expect(validateReadOnlyQuery('With x AS (SELECT 1) SELECT * FROM x')).toEqual({
+      ok: true,
+      query: 'With x AS (SELECT 1) SELECT * FROM x',
+    });
+  });
+
+  it('rejects a keyword that only looks like SELECT/WITH by prefix (word boundary)', () => {
+    const result = validateReadOnlyQuery('SELECTFROM foo');
+    expect(result.ok).toBe(false);
+  });
+
+  it('rejects INSERT/UPDATE/DELETE/DROP statements', () => {
+    expect(validateReadOnlyQuery('INSERT INTO foo VALUES (1)').ok).toBe(false);
+    expect(validateReadOnlyQuery('UPDATE foo SET x = 1').ok).toBe(false);
+    expect(validateReadOnlyQuery('DELETE FROM foo').ok).toBe(false);
+    expect(validateReadOnlyQuery('DROP TABLE foo').ok).toBe(false);
+  });
+
+  it('rejects a statement disguised behind leading whitespace and a semicolon', () => {
+    const result = validateReadOnlyQuery('   ; DROP TABLE foo');
+    expect(result.ok).toBe(false);
+  });
+
+  it('strips a single trailing semicolon (and trailing whitespace after it)', () => {
+    expect(validateReadOnlyQuery('SELECT 1;')).toEqual({ ok: true, query: 'SELECT 1' });
+    expect(validateReadOnlyQuery('SELECT 1;   ')).toEqual({ ok: true, query: 'SELECT 1' });
+  });
+
+  it('rejects more than one statement (semicolon-separated)', () => {
+    const result = validateReadOnlyQuery('SELECT 1; DROP TABLE foo');
+    expect(result.ok).toBe(false);
+  });
+
+  it('rejects a query with an embedded semicolon even with a trailing one too', () => {
+    const result = validateReadOnlyQuery('SELECT 1; SELECT 2;');
+    expect(result.ok).toBe(false);
+  });
+
+  // Layer 3 (`BEGIN TRANSACTION READ ONLY`) is what actually stops these — Postgres
+  // rejects any statement whose plan contains a data-modifying node, at any nesting
+  // depth. Layer 2 (`validateReadOnlyQuery`, this function) only checks the leading
+  // keyword, the single-statement shape, and the denylist — none of that understands a
+  // data-modifying CTE or a SELECT INTO, so they pass this layer. Pinning `ok: true` here
+  // documents that division of labour instead of silently implying layer 2 catches them.
+  // Note: no test in this suite drives layer 3 against a real Postgres server — these
+  // four `ok: true` cases document the division of labour between the two layers; they do
+  // not themselves verify that layer 3 actually rejects these statements.
+  describe('data-modifying statements that only layer 3 (READ ONLY transaction) stops', () => {
+    it('accepts a WITH wrapping a DELETE ... RETURNING', () => {
+      const query = 'WITH x AS (DELETE FROM foo RETURNING *) SELECT * FROM x';
+      expect(validateReadOnlyQuery(query)).toEqual({ ok: true, query });
+    });
+
+    it('accepts a WITH wrapping an INSERT ... RETURNING', () => {
+      const query = 'WITH x AS (INSERT INTO foo (id) VALUES (1) RETURNING *) SELECT * FROM x';
+      expect(validateReadOnlyQuery(query)).toEqual({ ok: true, query });
+    });
+
+    it('accepts a WITH wrapping an UPDATE ... RETURNING', () => {
+      const query = 'WITH x AS (UPDATE foo SET a = 1 RETURNING *) SELECT * FROM x';
+      expect(validateReadOnlyQuery(query)).toEqual({ ok: true, query });
+    });
+
+    it('accepts SELECT ... INTO', () => {
+      const query = 'SELECT * INTO foo FROM bar';
+      expect(validateReadOnlyQuery(query)).toEqual({ ok: true, query });
+    });
+  });
+
+  describe('denylisted filesystem/host-reaching functions (backstop, not a full defense)', () => {
+    // The loop test below iterates `DENIED_SQL_FUNCTIONS` itself, so it is true by
+    // construction: deleting a name from the constant would make the loop test pass with
+    // one fewer iteration, silently losing coverage for that function. This test pins the
+    // constant's actual contents so a shrink is caught.
+    it('pins the denylist to exactly these 15 known dangerous functions', () => {
+      expect(DENIED_SQL_FUNCTIONS).toEqual([
+        'pg_read_file',
+        'pg_read_binary_file',
+        'pg_stat_file',
+        'pg_ls_dir',
+        'pg_ls_logdir',
+        'pg_ls_waldir',
+        'pg_ls_tmpdir',
+        'pg_ls_archive_statusdir',
+        'lo_import',
+        'lo_export',
+        'lo_get',
+        'lo_put',
+        'lo_from_bytea',
+        'dblink',
+        'dblink_exec',
+      ]);
+    });
+
+    it('rejects every function in DENIED_SQL_FUNCTIONS, naming the matched function', () => {
+      for (const fn of DENIED_SQL_FUNCTIONS) {
+        const result = validateReadOnlyQuery(`SELECT ${fn}('x')`);
+        expect(result.ok).toBe(false);
+        expect(result.ok === false && result.reason).toContain(fn);
+      }
+    });
+
+    it('is case-insensitive', () => {
+      const result = validateReadOnlyQuery("SELECT PG_READ_FILE('/etc/passwd')");
+      expect(result.ok).toBe(false);
+      expect(result.ok === false && result.reason.toLowerCase()).toContain('pg_read_file');
+    });
+
+    it('names dblink_exec, not dblink, when the statement calls dblink_exec', () => {
+      const result = validateReadOnlyQuery("SELECT dblink_exec('conn', 'DELETE FROM foo')");
+      expect(result.ok).toBe(false);
+      expect(result.ok === false && result.reason).toContain('dblink_exec');
+      expect(result.ok === false && result.reason).not.toMatch(/dblink(?!_exec)/);
+    });
+
+    it('names dblink, not dblink_exec, when the statement calls plain dblink', () => {
+      const result = validateReadOnlyQuery("SELECT * FROM dblink('conn', 'SELECT 1') AS t(a int)");
+      expect(result.ok).toBe(false);
+      expect(result.ok === false && result.reason).toContain('dblink');
+      expect(result.ok === false && result.reason).not.toContain('dblink_exec');
+    });
+
+    it('still accepts a legitimate catalog query over pg_type/pg_attribute (the D5 example)', () => {
+      const query = `SELECT c.relname AS tabla, a.attname AS columna, t.typname AS tipo
+FROM pg_type t
+JOIN pg_namespace n ON n.oid = t.typnamespace
+LEFT JOIN pg_attribute a ON a.atttypid = t.oid AND a.attnum > 0 AND NOT a.attisdropped
+LEFT JOIN pg_class c ON c.oid = a.attrelid
+WHERE t.typtype = 'e' AND n.nspname = 'public'
+ORDER BY t.typname`;
+      expect(validateReadOnlyQuery(query)).toEqual({ ok: true, query });
+    });
+  });
+
+  // Both checks below are TEXTUAL — neither parses string literals or comments — so a
+  // legitimate single statement that merely CONTAINS the trigger text as data is rejected
+  // too. Failing closed is correct; the defect this fixes is the reason string implying a
+  // second statement or a function CALL exists, which sends the reader hunting for
+  // something that is not there. The corrected wording must say the check is textual and
+  // point at the workaround instead.
+  describe('misleading reason wording on textual false positives', () => {
+    it('rejects a literal `;` inside a string value, and says the check is textual', () => {
+      const result = validateReadOnlyQuery("SELECT * FROM iam_user WHERE name = 'a;b'");
+
+      expect(result.ok).toBe(false);
+      expect(result.ok === false && result.reason).toContain('textual');
+      expect(result.ok === false && result.reason).toContain('does not parse string literals');
+    });
+
+    it('rejects a denylisted name appearing only as a string literal, and says the check is textual', () => {
+      const result = validateReadOnlyQuery(
+        "SELECT proname FROM pg_proc WHERE proname = 'pg_read_file'",
+      );
+
+      expect(result.ok).toBe(false);
+      expect(result.ok === false && result.reason).toContain('textual');
+      expect(result.ok === false && result.reason).toContain('does not parse');
+      expect(result.ok === false && result.reason).toContain('pg_read_file');
+    });
+  });
+});
+
+describe('formatAsTable', () => {
+  it('renders an empty result set', () => {
+    expect(formatAsTable([])).toBe('(0 rows)');
+  });
+
+  it('renders a header row and aligned columns', () => {
+    const rows = [
+      { id: 'uuid-1', name: 'feature' },
+      { id: 'uuid-2', name: 'a' },
+    ];
+
+    // Pins the exact layout — width computation, padding, and the `-+-` separator row —
+    // rather than `toContain`ing fragments, which stays green even if `padEnd` and the
+    // separator row are removed entirely.
+    expect(formatAsTable(rows)).toBe(
+      ['id     | name   ', '-------+--------', 'uuid-1 | feature', 'uuid-2 | a      '].join('\n'),
+    );
+  });
+
+  it('renders null/undefined cell values as empty strings, not the literal text', () => {
+    const rows = [{ id: 'uuid-1', deletedAt: null }];
+    const table = formatAsTable(rows);
+    expect(table).not.toContain('null');
+  });
+
+  // Measured on this runtime (Node, V8): `Math.max(...arr)` throws `RangeError: Maximum
+  // call stack size exceeded` at 130,000 spread arguments but not at 100,000. 150,000
+  // rows gives headroom above the measured threshold while staying fast — computing
+  // column widths for this many rows with `reduce` takes low single-digit milliseconds.
+  it('computes column widths for a large result set without a stack overflow', () => {
+    const rows = Array.from({ length: 150_000 }, (_, index) => ({ id: `row-${index}` }));
+
+    expect(() => formatAsTable(rows)).not.toThrow();
+  });
+});
+
+describe('formatAsJson', () => {
+  it('pretty-prints rows as JSON with 2-space indent', () => {
+    const rows = [{ id: 'uuid-1' }];
+    expect(formatAsJson(rows)).toBe(JSON.stringify(rows, null, 2));
+  });
+
+  it('renders an empty array', () => {
+    expect(formatAsJson([])).toBe('[]');
+  });
+});
+
+describe('runReadOnlyQuery', () => {
+  function createMockPool(client: Partial<PoolClient>): Pool {
+    return {
+      connect: vi.fn().mockResolvedValue(client),
+    } as unknown as Pool;
+  }
+
+  /** A probe response for a non-superuser role with no server-file role membership. */
+  const SAFE_PROBE_ROW = { is_superuser: 'off', has_file_role: false };
+
+  it('runs BEGIN TRANSACTION READ ONLY, the probe, the query, then COMMIT, and releases the client', async () => {
+    const calls: unknown[] = [];
+    const client: Partial<PoolClient> = {
+      query: vi.fn((sql: string) => {
+        calls.push(sql);
+        if (sql === PRIVILEGE_PROBE_QUERY) {
+          return Promise.resolve({ rows: [SAFE_PROBE_ROW] });
+        }
+        return Promise.resolve({ rows: [{ id: 'uuid-1' }] });
+      }) as unknown as PoolClient['query'],
+      release: vi.fn(),
+    };
+    const pool = createMockPool(client);
+
+    const rows = await runReadOnlyQuery(pool, 'SELECT 1');
+
+    expect(calls).toEqual([
+      'BEGIN TRANSACTION READ ONLY',
+      STATEMENT_TIMEOUT_QUERY,
+      PRIVILEGE_PROBE_QUERY,
+      'SELECT 1',
+      'COMMIT',
+    ]);
+    expect(client.release).toHaveBeenCalledTimes(1);
+    expect(rows).toEqual([{ id: 'uuid-1' }]);
+  });
+
+  it('rolls back and re-throws when the query fails, and still releases the client', async () => {
+    const calls: unknown[] = [];
+    const failure = new Error('boom');
+    const client: Partial<PoolClient> = {
+      query: vi.fn((sql: string) => {
+        calls.push(sql);
+        if (sql === PRIVILEGE_PROBE_QUERY) {
+          return Promise.resolve({ rows: [SAFE_PROBE_ROW] });
+        }
+        if (sql === 'SELECT 1') {
+          return Promise.reject(failure);
+        }
+        return Promise.resolve({ rows: [] });
+      }) as unknown as PoolClient['query'],
+      release: vi.fn(),
+    };
+    const pool = createMockPool(client);
+
+    await expect(runReadOnlyQuery(pool, 'SELECT 1')).rejects.toThrow(failure);
+
+    expect(calls).toEqual([
+      'BEGIN TRANSACTION READ ONLY',
+      STATEMENT_TIMEOUT_QUERY,
+      PRIVILEGE_PROBE_QUERY,
+      'SELECT 1',
+      'ROLLBACK',
+    ]);
+    expect(client.release).toHaveBeenCalledTimes(1);
+    // The failure is a plain query rejection, not a dead connection — release() still gets
+    // the original error so the connection is discarded rather than pooled for reuse.
+    expect(client.release).toHaveBeenCalledWith(failure);
+  });
+
+  it('surfaces the ORIGINAL error, not a rejecting ROLLBACK, and still discards the client', async () => {
+    const calls: unknown[] = [];
+    const originalFailure = new Error('connection terminated unexpectedly');
+    const rollbackFailure = new Error('rollback failed: connection already closed');
+    const client: Partial<PoolClient> = {
+      query: vi.fn((sql: string) => {
+        calls.push(sql);
+        if (sql === PRIVILEGE_PROBE_QUERY) {
+          return Promise.resolve({ rows: [SAFE_PROBE_ROW] });
+        }
+        if (sql === 'SELECT 1') {
+          return Promise.reject(originalFailure);
+        }
+        if (sql === 'ROLLBACK') {
+          return Promise.reject(rollbackFailure);
+        }
+        return Promise.resolve({ rows: [] });
+      }) as unknown as PoolClient['query'],
+      release: vi.fn(),
+    };
+    const pool = createMockPool(client);
+
+    // Without the guard, the rejecting ROLLBACK replaces `originalFailure` and this
+    // assertion fails with `rollbackFailure` instead.
+    await expect(runReadOnlyQuery(pool, 'SELECT 1')).rejects.toBe(originalFailure);
+
+    expect(calls).toEqual([
+      'BEGIN TRANSACTION READ ONLY',
+      STATEMENT_TIMEOUT_QUERY,
+      PRIVILEGE_PROBE_QUERY,
+      'SELECT 1',
+      'ROLLBACK',
+    ]);
+    expect(client.release).toHaveBeenCalledTimes(1);
+    expect(client.release).toHaveBeenCalledWith(originalFailure);
+  });
+
+  describe('privilege probe', () => {
+    function createProbeClient(
+      probeRow: { is_superuser: string; has_file_role: boolean | null },
+      callerRows: Record<string, unknown>[] = [],
+    ): { client: Partial<PoolClient>; calls: string[] } {
+      const calls: string[] = [];
+      const client: Partial<PoolClient> = {
+        query: vi.fn((sql: string) => {
+          calls.push(sql);
+          if (sql === PRIVILEGE_PROBE_QUERY) {
+            return Promise.resolve({ rows: [probeRow] });
+          }
+          return Promise.resolve({ rows: callerRows });
+        }) as unknown as PoolClient['query'],
+        release: vi.fn(),
+      };
+      return { client, calls };
+    }
+
+    it('runs the probe immediately after BEGIN and before the caller query', async () => {
+      const { client, calls } = createProbeClient(SAFE_PROBE_ROW, [{ id: 'uuid-1' }]);
+      const pool = createMockPool(client);
+
+      await runReadOnlyQuery(pool, 'SELECT 1');
+
+      expect(calls).toEqual([
+        'BEGIN TRANSACTION READ ONLY',
+        STATEMENT_TIMEOUT_QUERY,
+        PRIVILEGE_PROBE_QUERY,
+        'SELECT 1',
+        'COMMIT',
+      ]);
+    });
+
+    it('rejects when is_superuser is on, the caller query never runs, and rolls back', async () => {
+      const { client, calls } = createProbeClient({ is_superuser: 'on', has_file_role: false });
+      const pool = createMockPool(client);
+
+      await expect(runReadOnlyQuery(pool, 'SELECT 1')).rejects.toThrow(/superuser/i);
+
+      expect(calls).toEqual([
+        'BEGIN TRANSACTION READ ONLY',
+        STATEMENT_TIMEOUT_QUERY,
+        PRIVILEGE_PROBE_QUERY,
+        'ROLLBACK',
+      ]);
+      expect(calls).not.toContain('SELECT 1');
+      expect(client.release).toHaveBeenCalledTimes(1);
+    });
+
+    it('rejects when has_file_role is true, the caller query never runs, and rolls back', async () => {
+      const { client, calls } = createProbeClient({ is_superuser: 'off', has_file_role: true });
+      const pool = createMockPool(client);
+
+      await expect(runReadOnlyQuery(pool, 'SELECT 1')).rejects.toThrow(/server-file role/i);
+
+      expect(calls).toEqual([
+        'BEGIN TRANSACTION READ ONLY',
+        STATEMENT_TIMEOUT_QUERY,
+        PRIVILEGE_PROBE_QUERY,
+        'ROLLBACK',
+      ]);
+      expect(calls).not.toContain('SELECT 1');
+      expect(client.release).toHaveBeenCalledTimes(1);
+    });
+
+    it('accepts is_superuser off with has_file_role null (older server, roles do not exist)', async () => {
+      const { client } = createProbeClient({ is_superuser: 'off', has_file_role: null }, [
+        { id: 'uuid-1' },
+      ]);
+      const pool = createMockPool(client);
+
+      const rows = await runReadOnlyQuery(pool, 'SELECT 1');
+
+      expect(rows).toEqual([{ id: 'uuid-1' }]);
+    });
+
+    it('accepts is_superuser off with has_file_role false', async () => {
+      const { client } = createProbeClient(SAFE_PROBE_ROW, [{ id: 'uuid-1' }]);
+      const pool = createMockPool(client);
+
+      const rows = await runReadOnlyQuery(pool, 'SELECT 1');
+
+      expect(rows).toEqual([{ id: 'uuid-1' }]);
+    });
+  });
+});