@dotdo/postgres 0.1.0

package/src/readonly/write-blocker.test.ts

@@ -0,0 +1,459 @@
+/**
+ * RED PHASE Tests for Write Blocking Middleware
+ *
+ * Rejects all write operations in read-only deployment mode.
+ * These tests should FAIL until implementation is complete.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  isWriteQuery,
+  WriteBlockedError,
+  createWriteBlocker,
+  SQL_WRITE_PATTERNS,
+} from './write-blocker'
+import type { ReadOnlyConfig } from './config'
+
+describe('Write Blocking Middleware', () => {
+  describe('SQL_WRITE_PATTERNS', () => {
+    it('should be an array of regex patterns', () => {
+      expect(Array.isArray(SQL_WRITE_PATTERNS)).toBe(true)
+      expect(SQL_WRITE_PATTERNS.length).toBeGreaterThan(0)
+      expect(SQL_WRITE_PATTERNS[0]).toBeInstanceOf(RegExp)
+    })
+  })
+
+  describe('isWriteQuery()', () => {
+    describe('INSERT statements', () => {
+      it('should detect simple INSERT', () => {
+        expect(isWriteQuery('INSERT INTO users (name) VALUES ($1)')).toBe(true)
+      })
+
+      it('should detect INSERT with schema', () => {
+        expect(isWriteQuery('INSERT INTO public.users (name) VALUES ($1)')).toBe(true)
+      })
+
+      it('should detect INSERT with lowercase', () => {
+        expect(isWriteQuery('insert into users (name) values ($1)')).toBe(true)
+      })
+
+      it('should detect INSERT with leading whitespace', () => {
+        expect(isWriteQuery('  INSERT INTO users (name) VALUES ($1)')).toBe(true)
+      })
+
+      it('should detect INSERT with leading newline', () => {
+        expect(isWriteQuery('\nINSERT INTO users (name) VALUES ($1)')).toBe(true)
+      })
+    })
+
+    describe('UPDATE statements', () => {
+      it('should detect simple UPDATE', () => {
+        expect(isWriteQuery('UPDATE users SET name = $1 WHERE id = $2')).toBe(true)
+      })
+
+      it('should detect UPDATE with schema', () => {
+        expect(isWriteQuery('UPDATE public.users SET name = $1')).toBe(true)
+      })
+
+      it('should detect UPDATE with lowercase', () => {
+        expect(isWriteQuery('update users set name = $1')).toBe(true)
+      })
+    })
+
+    describe('DELETE statements', () => {
+      it('should detect simple DELETE', () => {
+        expect(isWriteQuery('DELETE FROM users WHERE id = $1')).toBe(true)
+      })
+
+      it('should detect DELETE with lowercase', () => {
+        expect(isWriteQuery('delete from users where id = $1')).toBe(true)
+      })
+    })
+
+    describe('DDL statements', () => {
+      it('should detect CREATE TABLE', () => {
+        expect(isWriteQuery('CREATE TABLE users (id INT PRIMARY KEY)')).toBe(true)
+      })
+
+      it('should detect CREATE INDEX', () => {
+        expect(isWriteQuery('CREATE INDEX idx_name ON users(name)')).toBe(true)
+      })
+
+      it('should detect CREATE SCHEMA', () => {
+        expect(isWriteQuery('CREATE SCHEMA myschema')).toBe(true)
+      })
+
+      it('should detect ALTER TABLE', () => {
+        expect(isWriteQuery('ALTER TABLE users ADD COLUMN email TEXT')).toBe(true)
+      })
+
+      it('should detect DROP TABLE', () => {
+        expect(isWriteQuery('DROP TABLE users')).toBe(true)
+      })
+
+      it('should detect DROP INDEX', () => {
+        expect(isWriteQuery('DROP INDEX idx_name')).toBe(true)
+      })
+
+      it('should detect TRUNCATE', () => {
+        expect(isWriteQuery('TRUNCATE TABLE users')).toBe(true)
+      })
+    })
+
+    describe('Transaction statements', () => {
+      it('should detect COMMIT (can commit writes)', () => {
+        expect(isWriteQuery('COMMIT')).toBe(true)
+      })
+
+      it('should allow BEGIN (needed for read transactions)', () => {
+        expect(isWriteQuery('BEGIN')).toBe(false)
+      })
+
+      it('should allow ROLLBACK (safe)', () => {
+        expect(isWriteQuery('ROLLBACK')).toBe(false)
+      })
+    })
+
+    describe('Other write statements', () => {
+      it('should detect GRANT', () => {
+        expect(isWriteQuery('GRANT SELECT ON users TO readonly_user')).toBe(true)
+      })
+
+      it('should detect REVOKE', () => {
+        expect(isWriteQuery('REVOKE SELECT ON users FROM readonly_user')).toBe(true)
+      })
+
+      it('should detect VACUUM', () => {
+        expect(isWriteQuery('VACUUM users')).toBe(true)
+      })
+
+      it('should detect REINDEX', () => {
+        expect(isWriteQuery('REINDEX TABLE users')).toBe(true)
+      })
+
+      it('should detect COPY ... FROM (write)', () => {
+        expect(isWriteQuery("COPY users FROM '/path/to/file.csv'")).toBe(true)
+      })
+    })
+
+    describe('Read-only statements', () => {
+      it('should allow SELECT', () => {
+        expect(isWriteQuery('SELECT * FROM users WHERE id = $1')).toBe(false)
+      })
+
+      it('should allow SELECT with CTE', () => {
+        expect(isWriteQuery('WITH active_users AS (SELECT * FROM users WHERE active = true) SELECT * FROM active_users')).toBe(false)
+      })
+
+      it('should allow EXPLAIN', () => {
+        expect(isWriteQuery('EXPLAIN SELECT * FROM users')).toBe(false)
+      })
+
+      it('should allow EXPLAIN ANALYZE on SELECT', () => {
+        expect(isWriteQuery('EXPLAIN ANALYZE SELECT * FROM users')).toBe(false)
+      })
+
+      it('should allow SHOW statements', () => {
+        expect(isWriteQuery('SHOW search_path')).toBe(false)
+      })
+
+      it('should allow SET statements (session only)', () => {
+        expect(isWriteQuery('SET search_path TO public')).toBe(false)
+      })
+
+      it('should allow COPY ... TO (read)', () => {
+        expect(isWriteQuery("COPY users TO '/path/to/file.csv'")).toBe(false)
+      })
+    })
+
+    describe('Edge cases', () => {
+      it('should detect INSERT in subquery context', () => {
+        // This is a write even though it looks like it has a SELECT
+        expect(isWriteQuery('INSERT INTO archive SELECT * FROM users WHERE created < $1')).toBe(true)
+      })
+
+      it('should handle empty string', () => {
+        expect(isWriteQuery('')).toBe(false)
+      })
+
+      it('should handle whitespace only', () => {
+        expect(isWriteQuery('   \n\t  ')).toBe(false)
+      })
+
+      it('should detect UPDATE inside CTE', () => {
+        expect(isWriteQuery('WITH updated AS (UPDATE users SET active = false RETURNING *) SELECT * FROM updated')).toBe(true)
+      })
+    })
+
+    describe('Advanced write patterns (security critical)', () => {
+      it('should detect MERGE (upsert)', () => {
+        expect(isWriteQuery('MERGE INTO users USING new_data ON users.id = new_data.id WHEN MATCHED THEN UPDATE SET name = new_data.name')).toBe(true)
+      })
+
+      it('should detect COMMENT ON (metadata modification)', () => {
+        expect(isWriteQuery("COMMENT ON TABLE users IS 'User accounts'")).toBe(true)
+      })
+
+      it('should detect COMMENT ON COLUMN', () => {
+        expect(isWriteQuery("COMMENT ON COLUMN users.name IS 'Full name'")).toBe(true)
+      })
+
+      it('should detect RENAME', () => {
+        expect(isWriteQuery('RENAME TABLE users TO old_users')).toBe(true)
+      })
+
+      it('should detect CLUSTER (rewrites table)', () => {
+        expect(isWriteQuery('CLUSTER users USING users_pkey')).toBe(true)
+      })
+
+      it('should detect REFRESH MATERIALIZED VIEW', () => {
+        expect(isWriteQuery('REFRESH MATERIALIZED VIEW active_users')).toBe(true)
+      })
+
+      it('should detect REFRESH MATERIALIZED VIEW CONCURRENTLY', () => {
+        expect(isWriteQuery('REFRESH MATERIALIZED VIEW CONCURRENTLY active_users')).toBe(true)
+      })
+
+      it('should detect ANALYZE', () => {
+        expect(isWriteQuery('ANALYZE users')).toBe(true)
+      })
+
+      it('should detect SAVEPOINT', () => {
+        expect(isWriteQuery('SAVEPOINT my_savepoint')).toBe(true)
+      })
+
+      it('should detect RELEASE SAVEPOINT', () => {
+        expect(isWriteQuery('RELEASE SAVEPOINT my_savepoint')).toBe(true)
+      })
+
+      it('should detect PREPARE TRANSACTION (two-phase commit)', () => {
+        expect(isWriteQuery("PREPARE TRANSACTION 'tx123'")).toBe(true)
+      })
+
+      it('should detect COMMIT PREPARED', () => {
+        expect(isWriteQuery("COMMIT PREPARED 'tx123'")).toBe(true)
+      })
+
+      it('should detect ROLLBACK PREPARED', () => {
+        expect(isWriteQuery("ROLLBACK PREPARED 'tx123'")).toBe(true)
+      })
+
+      it('should detect LOCK TABLE', () => {
+        expect(isWriteQuery('LOCK TABLE users IN EXCLUSIVE MODE')).toBe(true)
+      })
+
+      it('should detect LOCK', () => {
+        expect(isWriteQuery('LOCK users')).toBe(true)
+      })
+
+      it('should detect DO blocks (arbitrary SQL)', () => {
+        expect(isWriteQuery("DO $$ BEGIN INSERT INTO users (name) VALUES ('test'); END $$")).toBe(true)
+      })
+
+      it('should detect CALL (procedure invocation)', () => {
+        expect(isWriteQuery('CALL update_all_users()')).toBe(true)
+      })
+
+      it('should detect EXECUTE (prepared statement)', () => {
+        expect(isWriteQuery('EXECUTE insert_user(1, $1)')).toBe(true)
+      })
+
+      it('should detect NOTIFY', () => {
+        expect(isWriteQuery("NOTIFY channel, 'payload'")).toBe(true)
+      })
+
+      it('should detect DISCARD', () => {
+        expect(isWriteQuery('DISCARD ALL')).toBe(true)
+      })
+
+      it('should detect SECURITY LABEL', () => {
+        expect(isWriteQuery("SECURITY LABEL FOR selinux ON TABLE users IS 's0:c123'")).toBe(true)
+      })
+
+      it('should detect LOAD', () => {
+        expect(isWriteQuery("LOAD 'auto_explain'")).toBe(true)
+      })
+
+      it('should detect CREATE OR REPLACE', () => {
+        expect(isWriteQuery("CREATE OR REPLACE FUNCTION my_func() RETURNS void AS $$ BEGIN END; $$ LANGUAGE plpgsql")).toBe(true)
+      })
+
+      it('should detect INSERT without INTO', () => {
+        // PostgreSQL allows INSERT table (...) VALUES (...)
+        expect(isWriteQuery('INSERT users (name) VALUES ($1)')).toBe(true)
+      })
+
+      it('should detect DELETE without FROM', () => {
+        // Some DB dialects allow DELETE table WHERE...
+        expect(isWriteQuery('DELETE users WHERE id = 1')).toBe(true)
+      })
+    })
+
+    describe('Allowed read operations (should NOT block)', () => {
+      it('should allow LISTEN (read notification channel)', () => {
+        expect(isWriteQuery('LISTEN channel')).toBe(false)
+      })
+
+      it('should allow UNLISTEN', () => {
+        expect(isWriteQuery('UNLISTEN channel')).toBe(false)
+      })
+
+      it('should allow FETCH', () => {
+        expect(isWriteQuery('FETCH 10 FROM my_cursor')).toBe(false)
+      })
+
+      it('should allow MOVE', () => {
+        expect(isWriteQuery('MOVE 5 IN my_cursor')).toBe(false)
+      })
+
+      it('should allow CLOSE cursor', () => {
+        expect(isWriteQuery('CLOSE my_cursor')).toBe(false)
+      })
+
+      it('should allow DECLARE cursor', () => {
+        expect(isWriteQuery('DECLARE my_cursor CURSOR FOR SELECT * FROM users')).toBe(false)
+      })
+
+      it('should allow TABLE keyword (shorthand for SELECT)', () => {
+        expect(isWriteQuery('TABLE users')).toBe(false)
+      })
+
+      it('should allow VALUES for read', () => {
+        expect(isWriteQuery("VALUES (1, 'a'), (2, 'b')")).toBe(false)
+      })
+    })
+  })
+
+  describe('WriteBlockedError', () => {
+    it('should be an Error instance', () => {
+      const error = new WriteBlockedError('INSERT INTO users ...')
+      expect(error).toBeInstanceOf(Error)
+    })
+
+    it('should have name WriteBlockedError', () => {
+      const error = new WriteBlockedError('INSERT INTO users ...')
+      expect(error.name).toBe('WriteBlockedError')
+    })
+
+    it('should include the blocked query in message', () => {
+      const error = new WriteBlockedError('INSERT INTO users ...')
+      expect(error.message).toContain('read-only')
+    })
+
+    it('should store the original query', () => {
+      const query = 'INSERT INTO users (name) VALUES ($1)'
+      const error = new WriteBlockedError(query)
+      expect(error.query).toBe(query)
+    })
+
+    it('should have SQLSTATE code for read-only transaction', () => {
+      const error = new WriteBlockedError('INSERT ...')
+      // 25006 = read_only_sql_transaction
+      expect(error.code).toBe('25006')
+    })
+  })
+
+  describe('createWriteBlocker()', () => {
+    const defaultConfig: ReadOnlyConfig = {
+      enabled: true,
+      onWriteAttempt: 'throw',
+    }
+
+    it('should return a function', () => {
+      const blocker = createWriteBlocker(defaultConfig)
+      expect(typeof blocker).toBe('function')
+    })
+
+    describe('with throw mode', () => {
+      const config: ReadOnlyConfig = {
+        enabled: true,
+        onWriteAttempt: 'throw',
+      }
+
+      it('should throw WriteBlockedError for INSERT', () => {
+        const blocker = createWriteBlocker(config)
+        expect(() => blocker('INSERT INTO users (name) VALUES ($1)')).toThrow(WriteBlockedError)
+      })
+
+      it('should throw WriteBlockedError for UPDATE', () => {
+        const blocker = createWriteBlocker(config)
+        expect(() => blocker('UPDATE users SET name = $1')).toThrow(WriteBlockedError)
+      })
+
+      it('should throw WriteBlockedError for DELETE', () => {
+        const blocker = createWriteBlocker(config)
+        expect(() => blocker('DELETE FROM users WHERE id = $1')).toThrow(WriteBlockedError)
+      })
+
+      it('should allow SELECT queries', () => {
+        const blocker = createWriteBlocker(config)
+        expect(() => blocker('SELECT * FROM users')).not.toThrow()
+      })
+
+      it('should return the query for read operations', () => {
+        const blocker = createWriteBlocker(config)
+        const query = 'SELECT * FROM users'
+        expect(blocker(query)).toBe(query)
+      })
+    })
+
+    describe('with ignore mode', () => {
+      const config: ReadOnlyConfig = {
+        enabled: true,
+        onWriteAttempt: 'ignore',
+      }
+
+      it('should not throw for INSERT', () => {
+        const blocker = createWriteBlocker(config)
+        expect(() => blocker('INSERT INTO users (name) VALUES ($1)')).not.toThrow()
+      })
+
+      it('should return null for blocked writes', () => {
+        const blocker = createWriteBlocker(config)
+        expect(blocker('INSERT INTO users (name) VALUES ($1)')).toBeNull()
+      })
+
+      it('should return the query for SELECT', () => {
+        const blocker = createWriteBlocker(config)
+        expect(blocker('SELECT * FROM users')).toBe('SELECT * FROM users')
+      })
+    })
+
+    describe('with log mode', () => {
+      const config: ReadOnlyConfig = {
+        enabled: true,
+        onWriteAttempt: 'log',
+      }
+
+      it('should not throw for INSERT', () => {
+        const blocker = createWriteBlocker(config)
+        expect(() => blocker('INSERT INTO users (name) VALUES ($1)')).not.toThrow()
+      })
+
+      it('should return null for blocked writes', () => {
+        const blocker = createWriteBlocker(config)
+        expect(blocker('UPDATE users SET name = $1')).toBeNull()
+      })
+    })
+
+    describe('when read-only is disabled', () => {
+      const config: ReadOnlyConfig = {
+        enabled: false,
+        onWriteAttempt: 'throw',
+      }
+
+      it('should allow INSERT when disabled', () => {
+        const blocker = createWriteBlocker(config)
+        const query = 'INSERT INTO users (name) VALUES ($1)'
+        expect(blocker(query)).toBe(query)
+      })
+
+      it('should allow all operations when disabled', () => {
+        const blocker = createWriteBlocker(config)
+        expect(blocker('DELETE FROM users')).toBe('DELETE FROM users')
+        expect(blocker('UPDATE users SET x = 1')).toBe('UPDATE users SET x = 1')
+        expect(blocker('DROP TABLE users')).toBe('DROP TABLE users')
+      })
+    })
+  })
+})

package/src/readonly/write-blocker.ts

@@ -0,0 +1,175 @@
+/**
+ * Write Blocking Middleware
+ *
+ * Rejects all write operations in read-only deployment mode.
+ * Security feature to ensure writes are impossible.
+ */
+
+import type { ReadOnlyConfig } from './config'
+
+/**
+ * SQL patterns that indicate a write operation.
+ * These patterns are case-insensitive and match at the start of a query
+ * (after trimming whitespace).
+ *
+ * SECURITY: This list must be exhaustive to prevent ANY data modification.
+ */
+export const SQL_WRITE_PATTERNS: RegExp[] = [
+  // DML write operations
+  /^\s*INSERT\s+INTO\b/i,
+  /^\s*INSERT\s+/i, // Some dialects allow INSERT without INTO
+  /^\s*UPDATE\s+/i,
+  /^\s*DELETE\s+FROM\b/i,
+  /^\s*DELETE\s+/i, // DELETE without FROM (e.g., DELETE users WHERE...)
+  /^\s*MERGE\s+/i, // SQL MERGE (upsert) statement
+
+  // DDL operations
+  /^\s*CREATE\s+/i,
+  /^\s*ALTER\s+/i,
+  /^\s*DROP\s+/i,
+  /^\s*TRUNCATE\s+/i,
+  /^\s*COMMENT\s+ON\b/i, // COMMENT ON TABLE/COLUMN modifies metadata
+  /^\s*RENAME\s+/i, // PostgreSQL RENAME
+
+  // Permission changes
+  /^\s*GRANT\s+/i,
+  /^\s*REVOKE\s+/i,
+
+  // Maintenance operations that modify data
+  /^\s*VACUUM\b/i,
+  /^\s*REINDEX\s+/i,
+  /^\s*CLUSTER\s+/i, // CLUSTER rewrites table data
+  /^\s*REFRESH\s+MATERIALIZED\s+VIEW\b/i, // Modifies materialized view data
+  /^\s*ANALYZE\b/i, // Updates statistics (can be considered write)
+
+  // COPY FROM (imports data)
+  /^\s*COPY\s+\S+\s+FROM\b/i,
+
+  // COMMIT can commit pending writes
+  /^\s*COMMIT\b/i,
+
+  // Savepoint manipulation (could be used to commit partial writes)
+  /^\s*SAVEPOINT\b/i,
+  /^\s*RELEASE\s+SAVEPOINT\b/i,
+
+  // Transaction control that could affect data
+  /^\s*PREPARE\s+TRANSACTION\b/i, // Two-phase commit
+  /^\s*COMMIT\s+PREPARED\b/i,
+  /^\s*ROLLBACK\s+PREPARED\b/i,
+
+  // Lock operations (could be used to interfere with reads)
+  /^\s*LOCK\s+TABLE\b/i,
+  /^\s*LOCK\s+/i,
+
+  // Extension and procedure modifications
+  /^\s*CREATE\s+OR\s+REPLACE\b/i,
+
+  // DO blocks can execute arbitrary SQL including writes
+  /^\s*DO\s+/i,
+
+  // CALL can invoke procedures that write data
+  /^\s*CALL\s+/i,
+
+  // EXECUTE can run prepared statements that write
+  /^\s*EXECUTE\s+/i,
+
+  // NOTIFY/LISTEN can be used for side effects
+  /^\s*NOTIFY\b/i,
+
+  // DISCARD can affect session state
+  /^\s*DISCARD\s+/i,
+
+  // SECURITY LABEL modifies labels
+  /^\s*SECURITY\s+LABEL\b/i,
+
+  // LOAD loads external modules
+  /^\s*LOAD\b/i,
+
+  // CTE with write operations (WITH ... UPDATE/INSERT/DELETE)
+  /^\s*WITH\s+[\s\S]*?\b(UPDATE|INSERT|DELETE)\b/i,
+]
+
+/**
+ * Check if a SQL query is a write operation.
+ *
+ * @param sql - The SQL query to check
+ * @returns true if the query would modify data
+ */
+export function isWriteQuery(sql: string): boolean {
+  if (!sql || !sql.trim()) {
+    return false
+  }
+
+  const trimmed = sql.trim()
+
+  for (const pattern of SQL_WRITE_PATTERNS) {
+    if (pattern.test(trimmed)) {
+      return true
+    }
+  }
+
+  return false
+}
+
+/**
+ * Error thrown when a write operation is blocked in read-only mode.
+ */
+export class WriteBlockedError extends Error {
+  /** The blocked SQL query */
+  readonly query: string
+
+  /** PostgreSQL SQLSTATE code for read-only transaction */
+  readonly code: string = '25006'
+
+  /** Error name */
+  override readonly name: string = 'WriteBlockedError'
+
+  constructor(query: string) {
+    super(`Write operation blocked: database is in read-only mode`)
+    this.query = query
+  }
+}
+
+/**
+ * Write blocker function type.
+ * Returns the query if allowed, null if ignored, or throws if blocked.
+ */
+export type WriteBlockerFn = (sql: string) => string | null
+
+/**
+ * Create a write blocker function based on configuration.
+ *
+ * @param config - Read-only configuration
+ * @returns A function that checks and potentially blocks write queries
+ */
+export function createWriteBlocker(config: ReadOnlyConfig): WriteBlockerFn {
+  return (sql: string): string | null => {
+    // If read-only mode is disabled, allow everything
+    if (!config.enabled) {
+      return sql
+    }
+
+    // Check if this is a write query
+    if (!isWriteQuery(sql)) {
+      return sql
+    }
+
+    // Handle write attempt based on configuration
+    switch (config.onWriteAttempt) {
+      case 'throw':
+        throw new WriteBlockedError(sql)
+
+      case 'ignore':
+        return null
+
+      case 'log':
+        // In a real implementation, we would log here
+        // console.warn(`[read-only] Blocked write query: ${sql.substring(0, 100)}...`)
+        return null
+
+      default:
+        // Default to throw for safety
+        throw new WriteBlockedError(sql)
+    }
+  }
+}