pgsqlarbiter 0.2.0

data/lib/pgsqlarbiter.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "pgsqlarbiter/version"
+require_relative "pgsqlarbiter/error"
+require_relative "pgsqlarbiter/token"
+require_relative "pgsqlarbiter/keywords"
+require_relative "pgsqlarbiter/analysis"
+require_relative "pgsqlarbiter/default_query_functions"
+require_relative "pgsqlarbiter/lexer"
+require_relative "pgsqlarbiter/analyzer"
+require_relative "pgsqlarbiter/verdict"
+require_relative "pgsqlarbiter/arbiter"
+
+# SQL query permission system for PostgreSQL.
+#
+# Pgsqlarbiter restricts database access for semi-trusted users by ensuring only
+# single-statement DML queries are executed and all referenced tables, views, and
+# functions are whitelisted.
+module Pgsqlarbiter
+  # Analyze a SQL query and extract its statement type, referenced tables, and function calls.
+  #
+  # @param sql [String] the SQL query to analyze
+  # @return [Analysis] analysis result containing statement_type, tables, and functions
+  # @raise [ParseError] if the SQL cannot be parsed
+  # @raise [MultipleStatementsError] if the SQL contains more than one statement
+  # @raise [DisallowedStatementError] if the statement type is not a supported DML type
+  def self.analyze(sql)
+    Analyzer.new.analyze(sql)
+  end
+
+  # Judge a SQL query against the given restrictions, returning a {Verdict} that
+  # explains which checks passed or failed.
+  #
+  # This is a convenience method that creates a one-off {Arbiter} instance. For repeated
+  # checks with the same rules, prefer creating an {Arbiter} directly.
+  #
+  # @param sql [String] the SQL query to judge
+  # @param allowed_tables [Array<String>] allowed table and view names
+  # @param allowed_statement_types [Array<Symbol>] allowed statement types
+  #   (default: +[:select]+). Valid types: +:select+, +:insert+, +:update+,
+  #   +:delete+, +:merge+, +:values+
+  # @param allowed_functions [Set<String>, Array<String>] allowed function names
+  #   (default: {DEFAULT_QUERY_FUNCTIONS})
+  # @return [Verdict] detailed result with {Verdict#allowed?}, individual check
+  #   results, and {Verdict#reasons}
+  # @raise [MultipleStatementsError] if the SQL contains more than one statement
+  # @raise [DisallowedStatementError] if the statement type is not a supported DML type
+  def self.judge(sql, allowed_tables:, allowed_statement_types: [:select], allowed_functions: DEFAULT_QUERY_FUNCTIONS)
+    Arbiter.new(allowed_statement_types: allowed_statement_types, allowed_tables: allowed_tables, allowed_functions: allowed_functions).judge(sql)
+  end
+
+  # Check whether a SQL query is allowed under the given restrictions.
+  #
+  # This is a convenience method that creates a one-off {Arbiter} instance. For repeated
+  # checks with the same rules, prefer creating an {Arbiter} directly.
+  #
+  # @param sql [String] the SQL query to check
+  # @param allowed_tables [Array<String>] allowed table and view names
+  # @param allowed_statement_types [Array<Symbol>] allowed statement types
+  #   (default: +[:select]+). Valid types: +:select+, +:insert+, +:update+,
+  #   +:delete+, +:merge+, +:values+
+  # @param allowed_functions [Set<String>, Array<String>] allowed function names
+  #   (default: {DEFAULT_QUERY_FUNCTIONS})
+  # @return [Boolean] +true+ if the query is allowed, +false+ otherwise
+  # @raise [MultipleStatementsError] if the SQL contains more than one statement
+  # @raise [DisallowedStatementError] if the statement type is not a supported DML type
+  def self.allow?(sql, allowed_tables:, allowed_statement_types: [:select], allowed_functions: DEFAULT_QUERY_FUNCTIONS)
+    Arbiter.new(allowed_statement_types: allowed_statement_types, allowed_tables: allowed_tables, allowed_functions: allowed_functions).allow?(sql)
+  end
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: pgsqlarbiter
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- pgsqlarbiter contributors
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Restricts SQL queries to single-statement DML with whitelisted tables,
+  views, and functions.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/pgsqlarbiter.rb
+- lib/pgsqlarbiter/analysis.rb
+- lib/pgsqlarbiter/analyzer.rb
+- lib/pgsqlarbiter/arbiter.rb
+- lib/pgsqlarbiter/default_query_functions.rb
+- lib/pgsqlarbiter/error.rb
+- lib/pgsqlarbiter/keywords.rb
+- lib/pgsqlarbiter/lexer.rb
+- lib/pgsqlarbiter/token.rb
+- lib/pgsqlarbiter/verdict.rb
+- lib/pgsqlarbiter/version.rb
+homepage: https://github.com/pgsqlarbiter/pgsqlarbiter-rb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/pgsqlarbiter/pgsqlarbiter-rb
+  source_code_uri: https://github.com/pgsqlarbiter/pgsqlarbiter-rb
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: SQL query permission system for PostgreSQL
+test_files: []