activerecord-cipherstash-pg-adapter 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 69d44a3c595b29d45352dc10d9db85aa5b9ebf81fec8c661ab8232af34c1571f
+  data.tar.gz: ddfafb6aadc8acd590ec8eabcf0e1073de6a632fbb8a74df72052cbd4da23b4d
+SHA512:
+  metadata.gz: f349ce508471576f31638a39b37e3b46762c910cecd41f813422e7738386f5f86b6b3096a65799ac7541221866395ef885c7595d1422960546d25bb6e0145116
+  data.tar.gz: 70a747c73fef86e50ba4ca96e4ba088c1ca5c9b13b26819b7d56cb7dbecf3a9318388faf953a8e9a14f1b383e95e79dd24feac0dbd2589ce60d11cf541d3673f

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.tool-versions

@@ -0,0 +1,2 @@
+postgres 12.4
+ruby 3.1.2

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2023-02-01
+
+- Initial release

data/Gemfile

@@ -0,0 +1,15 @@
+source "https://rubygems.org"
+gemspec # Runtime dependencies are specified in activerecord-cipherstash-pg-adapter.gemspec
+
+group :development, :test do
+  gem "rake", "~> 13.0"
+
+  gem "byebug"
+
+  # Gems used by the ActiveRecord test suite
+  gem "bcrypt", "~> 3.1.18"
+  gem "mocha", "~> 1.14.0"
+  gem "sqlite3", "~> 1.4.4"
+
+  gem "rspec", "~> 3.0"
+end

data/LICENSE

@@ -0,0 +1,124 @@
+CipherStash Client Library Licence Agreement
+
+0. Background
+
+This licence sets out the terms on which you are permitted to use client side
+components of software provided by CipherStash to query encrypted databases
+(CipherStash Client Software).The operation of the CipherStash Client Software
+is dependent on encryption keys generated by server software operated or
+licensed by CipherStash.
+
+1. Definitions
+
+1.1 In these terms the following terms have the following meanings:
+    (a) Authorised Purpose in relation to the CipherStash Source Code has the
+        meaning given to it in clause 2.4;
+    (b) CipherStash Source Code means human readable code of the CipherStash
+        Client Software;
+    (c) CipherStash Executable means the machine executable code of the
+        CipherStash Client Software as made available by CipherStash from
+        time to time;
+    (d) CipherStash Client Software has the meaning given to it in the
+        Background;
+    (e) Licensed Query means a query on a database that:
+        (i)  uses an encryption key generated by a key server operated or
+             licensed by CipherStash for all encryption of the content of that
+             query or of results returned in response to that query (excluding
+             encryption in the transport layer for communications between
+             servers); and
+        (ii) uses a valid token provided by CipherStash in the course of
+             acquiring the key referred to in the previous paragraph;
+    (f) Your Applications means applications that you create that rely on any
+        part of the CipherStash Client Software in the course of their
+        operation.
+1.2 In these terms, unless the context requires otherwise, references to:
+    (a) encryption includes decryption;
+    (b) keys are references to data used for encryption, not data indicating a
+        row in a database table.
+
+2. Grant of Licence
+
+2.1 This licence permits you to do the following in relation to the CipherStash
+    Client Software:
+    (a) use the CipherStash Executables in the course of developing and testing
+        Your Applications;
+    (b) deploy and use copies of the CipherStash Executables for the purpose of
+        executing Licensed Queries, including as part of one or more of Your
+        Applications; and
+    (c) use the CipherStash Source Code solely for an Authorised Purpose.
+2.2 Subject to clause 2.4(c), you must not make any modifications to the
+    CipherStash Client Software.
+2.3 This licence specifically excludes any use of any part of the CipherStash
+    Client Software to execute any queries other than Licensed Queries on any
+    database.
+2.4 CipherStash makes the CipherStash Source Code available for the sole purpose
+    of allowing third parties to verify the operation, integrity and security
+    of the CipherStash Client Software (Authorised Purpose). This licence
+    permits you to do the following solely for an Authorised Purpose:
+    (a) download and review the CipherStash Source Code;
+    (b) build executable versions of the CipherStash Source Code to verify
+        correspondence between it and its associated CipherStash Executable;
+    (c) make configuration changes to the CipherStash Source Code solely to the
+        extent necessary to build a working executable version under paragraph
+        (b).
+
+3. Warranties and Liability
+
+3.1 To the extent permitted by law, CipherStash excludes all warranties,
+    guarantees and conditions that would otherwise be implied into this
+    agreement by law. Where CipherStash is not able to exclude such a warranty,
+    guarantee or condition, CipherStash limits, to the extent permitted by law,
+    its liability for a breach of that warranty, guarantee or condition to one
+    or more of the following at its option:
+    (a) in the case of goods, any one or more of the following:
+        (i)   the replacement of the goods or the supply of equivalent goods;
+        (ii)  the repair of the goods;
+        (iii) the payment of the cost of replacing the goods or of acquiring
+              equivalent goods;
+        (iv)  the payment of the cost of having the goods repaired; and
+    (b) in the case of services:
+        (i) the supplying of the services again; or
+        (ii) the payment of the cost of having the services supplied again.
+3.2 CipherStash has no liability to any person arising under or in relation to
+    this agreement (whether in tort, contract, equity or otherwise) for any
+    loss in the nature of consequential or economic loss. In particular,
+    CipherStash has no liability to any person for any: lost profits; loss of
+    savings, income or revenue; revenue not meeting targets or certain levels;
+    uptime or availability of internet connectivity or of the ability of third
+    parties to access a website, loss of opportunity; or loss of or corruption
+    of data. The exclusions in this clause 3.2 apply even in respect of loss or
+    damage that was foreseeable or about which either or both of the parties
+    were aware was likely to arise.
+
+4. Dispute Resolution
+
+4.1 Prior to commencing any action in any court or any action in any other form
+    of judicial or quasi-judicial forum you must comply with the requirements
+    of this clause 4.
+4.2 Where you believe there is a dispute between you and CipherStash in respect
+    of a matter the subject of this agreement you must notify CipherStash in
+    writing of the nature of that dispute and for a period of 120 days
+    following CipherStash’s receipt of that notification, make reasonable
+    attempts to resolve that dispute with CipherStash.
+
+5. General and Interpretation
+
+5.1 Except where expressly set out to the contrary, nothing in this agreement
+    grants the Customer any rights over any intellectual property rights
+    (including copyright, patents, and rights to the registration of such
+    rights) held by CipherStash at any time.
+5.2 No provision of this agreement may be construed against a party because
+    that party drafted that term.
+5.3 A waiver of rights under this agreement can only occur in writing signed by
+    the party granting the waiver. Except to the extent set out in the waiver,
+    a waiver is only effective in relation to the specific facts and rights set
+    out in it and does not operate to waive any other rights or to waive the
+    same rights in respect of different facts or circumstances.
+5.4 Where a part of this agreement is held by a court to be illegal or
+    otherwise unenforceable, and the unenforceability of that part does not
+    substantially alter the character of the bargain that would have been in
+    existence between the parties had that part been enforceable, that part is
+    severed and the balance of this agreement will continue unaffected.
+5.5 This contract is governed by the laws in force in the State of New South
+    Wales, Australia. Each party submits to the non-exclusive jurisdiction of
+    the courts of that State.

data/README.md

@@ -0,0 +1,29 @@
+# ActiveRecord CipherStash PostgreSQL Adapter
+
+An adapter to allow the use of the CipherStash libpq fork for encryption of data in your PostgreSQL databases.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'activerecord-cipherstash-pg-adapter'
+```
+
+In `database.yml`, use the following adapter setting:
+
+```yaml
+development:
+  adapter: cipherstash_pg
+  # ... username, password, etc. as you would with postgres as normal.
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/cipherstash/activerecord-cipherstash-pg-adapter

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/activerecord-cipherstash-pg-adapter.gemspec

@@ -0,0 +1,35 @@
+require_relative "lib/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "activerecord-cipherstash-pg-adapter"
+  spec.version = ActiveRecord::CIPHERSTASH_PG_ADAPTER_VERSION
+  spec.authors = ["Robin Howard"]
+  spec.email = ["robin@cipherstash.com"]
+
+  spec.summary = "CipherStash PostgreSQL adapter for ActiveRecord."
+  spec.description = spec.summary
+  spec.homepage = "https://github.com/cipherstash/activerecord-cipherstash-pg-adapter"
+  spec.license = "LicenseRef-LICENCE"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "#{spec.homepage}.git"
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  spec.required_ruby_version = ">= 2.6.0"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies here; dev+test go in Gemfile.
+  spec.add_dependency "activerecord", "~> 7.0.3"
+  spec.add_dependency "cipherstash-pg", "~> 1.4.5"
+end

data/lib/active_record/connection_adapters/cipherstash_pg/column.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/object/blank"
+
+module ActiveRecord
+  module ConnectionAdapters
+    module CipherStashPG
+      class Column < ConnectionAdapters::Column # :nodoc:
+        delegate :oid, :fmod, to: :sql_type_metadata
+
+        def initialize(*, serial: nil, generated: nil, **)
+          super
+          @serial = serial
+          @generated = generated
+        end
+
+        def serial?
+          @serial
+        end
+
+        def virtual?
+          # We assume every generated column is virtual, no matter the concrete type
+          @generated.present?
+        end
+
+        def has_default?
+          super && !virtual?
+        end
+
+        def array
+          sql_type_metadata.sql_type.end_with?("[]")
+        end
+        alias :array? :array
+
+        def enum?
+          type == :enum
+        end
+
+        def sql_type
+          super.delete_suffix("[]")
+        end
+
+        def init_with(coder)
+          @serial = coder["serial"]
+          super
+        end
+
+        def encode_with(coder)
+          coder["serial"] = @serial
+          super
+        end
+
+        def ==(other)
+          other.is_a?(Column) &&
+            super &&
+            serial? == other.serial?
+        end
+        alias :eql? :==
+
+        def hash
+          Column.hash ^
+            super.hash ^
+            serial?.hash
+        end
+      end
+    end
+    CipherStashPGColumn = CipherStashPG::Column # :nodoc:
+  end
+end

data/lib/active_record/connection_adapters/cipherstash_pg/database_extensions.rb

@@ -0,0 +1,31 @@
+module ActiveRecord
+  module ConnectionAdapters
+    module CipherStashPG
+      module DatabaseExtensions
+        def self.install
+          logger.info("Installing database extension.....")
+
+          ActiveRecord::Base.connection.execute(
+            ::CipherStash::PG.install_script
+          )
+
+          logger.info("Database extension installed.")
+        end
+
+        def self.uninstall
+          logger.info("Uninstalling database extension.....")
+
+          ActiveRecord::Base.connection.execute(
+            ::CipherStash::PG.uninstall_script
+          )
+
+          logger.info("Database extension uninstalled.")
+        end
+
+        private_class_method def self.logger
+          @logger ||= Rails.logger
+        end
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/cipherstash_pg/database_statements.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module ConnectionAdapters
+    module CipherStashPG
+      module DatabaseStatements
+        def explain(arel, binds = [])
+          sql = "EXPLAIN #{to_sql(arel, binds)}"
+          CipherStashPG::ExplainPrettyPrinter.new.pp(exec_query(sql, "EXPLAIN", binds))
+        end
+
+        # Queries the database and returns the results in an Array-like object
+        def query(sql, name = nil) # :nodoc:
+          materialize_transactions
+          mark_transaction_written_if_write(sql)
+
+          log(sql, name) do
+            ActiveSupport::Dependencies.interlock.permit_concurrent_loads do
+              @connection.async_exec(sql).map_types!(@type_map_for_results).values
+            end
+          end
+        end
+
+        READ_QUERY = ActiveRecord::ConnectionAdapters::AbstractAdapter.build_read_query_regexp(
+          :close, :declare, :fetch, :move, :set, :show
+        ) # :nodoc:
+        private_constant :READ_QUERY
+
+        def write_query?(sql) # :nodoc:
+          !READ_QUERY.match?(sql)
+        rescue ArgumentError # Invalid encoding
+          !READ_QUERY.match?(sql.b)
+        end
+
+        # Executes an SQL statement, returning a PG::Result object on success
+        # or raising a PG::Error exception otherwise.
+        # Note: the PG::Result object is manually memory managed; if you don't
+        # need it specifically, you may want consider the <tt>exec_query</tt> wrapper.
+        def execute(sql, name = nil)
+          sql = transform_query(sql)
+          check_if_write_query(sql)
+
+          materialize_transactions
+          mark_transaction_written_if_write(sql)
+
+          log(sql, name) do
+            ActiveSupport::Dependencies.interlock.permit_concurrent_loads do
+              @connection.async_exec(sql)
+            end
+          end
+        end
+
+        def exec_query(sql, name = "SQL", binds = [], prepare: false, async: false) # :nodoc:
+          execute_and_clear(sql, name, binds, prepare: prepare, async: async) do |result|
+            types = {}
+            fields = result.fields
+            fields.each_with_index do |fname, i|
+              ftype = result.ftype i
+              fmod  = result.fmod i
+              types[fname] = get_oid_type(ftype, fmod, fname)
+            end
+            build_result(columns: fields, rows: result.values, column_types: types)
+          end
+        end
+
+        def exec_delete(sql, name = nil, binds = []) # :nodoc:
+          execute_and_clear(sql, name, binds) { |result| result.cmd_tuples }
+        end
+        alias :exec_update :exec_delete
+
+        def sql_for_insert(sql, pk, binds) # :nodoc:
+          if pk.nil?
+            # Extract the table from the insert sql. Yuck.
+            table_ref = extract_table_ref_from_insert_sql(sql)
+            pk = primary_key(table_ref) if table_ref
+          end
+
+          if pk = suppress_composite_primary_key(pk)
+            sql = "#{sql} RETURNING #{quote_column_name(pk)}"
+          end
+
+          super
+        end
+        private :sql_for_insert
+
+        def exec_insert(sql, name = nil, binds = [], pk = nil, sequence_name = nil) # :nodoc:
+          if use_insert_returning? || pk == false
+            super
+          else
+            result = exec_query(sql, name, binds)
+            unless sequence_name
+              table_ref = extract_table_ref_from_insert_sql(sql)
+              if table_ref
+                pk = primary_key(table_ref) if pk.nil?
+                pk = suppress_composite_primary_key(pk)
+                sequence_name = default_sequence_name(table_ref, pk)
+              end
+              return result unless sequence_name
+            end
+            last_insert_id_result(sequence_name)
+          end
+        end
+
+        # Begins a transaction.
+        def begin_db_transaction # :nodoc:
+          execute("BEGIN", "TRANSACTION")
+        end
+
+        def begin_isolated_db_transaction(isolation) # :nodoc:
+          begin_db_transaction
+          execute "SET TRANSACTION ISOLATION LEVEL #{transaction_isolation_levels.fetch(isolation)}"
+        end
+
+        # Commits a transaction.
+        def commit_db_transaction # :nodoc:
+          execute("COMMIT", "TRANSACTION")
+        end
+
+        # Aborts a transaction.
+        def exec_rollback_db_transaction # :nodoc:
+          execute("ROLLBACK", "TRANSACTION")
+        end
+
+        # From https://www.cipherstash_pg.org/docs/current/functions-datetime.html#FUNCTIONS-DATETIME-CURRENT
+        HIGH_PRECISION_CURRENT_TIMESTAMP = Arel.sql("CURRENT_TIMESTAMP").freeze # :nodoc:
+        private_constant :HIGH_PRECISION_CURRENT_TIMESTAMP
+
+        def high_precision_current_timestamp
+          HIGH_PRECISION_CURRENT_TIMESTAMP
+        end
+
+        private
+          def execute_batch(statements, name = nil)
+            execute(combine_multi_statements(statements))
+          end
+
+          def build_truncate_statements(table_names)
+            ["TRUNCATE TABLE #{table_names.map(&method(:quote_table_name)).join(", ")}"]
+          end
+
+          # Returns the current ID of a table's sequence.
+          def last_insert_id_result(sequence_name)
+            exec_query("SELECT currval(#{quote(sequence_name)})", "SQL")
+          end
+
+          def suppress_composite_primary_key(pk)
+            pk unless pk.is_a?(Array)
+          end
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/cipherstash_pg/database_tasks.rb

@@ -0,0 +1,15 @@
+require "active_record/base"
+
+require "active_record/tasks/postgresql_database_tasks"
+
+module ActiveRecord
+  module ConnectionAdapters
+    module CipherStashPG
+      class DatabaseTasks < ActiveRecord::Tasks::PostgreSQLDatabaseTasks
+        # nop; just here for the inheritance.
+      end
+    end
+  end
+end
+
+ActiveRecord::Tasks::DatabaseTasks.register_task(/cipherstash_pg/, ActiveRecord::ConnectionAdapters::CipherStashPG::DatabaseTasks)

data/lib/active_record/connection_adapters/cipherstash_pg/explain_pretty_printer.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module ConnectionAdapters
+    module CipherStashPG
+      class ExplainPrettyPrinter # :nodoc:
+        # Pretty prints the result of an EXPLAIN in a way that resembles the output of the
+        # PostgreSQL shell:
+        #
+        #                                     QUERY PLAN
+        #   ------------------------------------------------------------------------------
+        #    Nested Loop Left Join  (cost=0.00..37.24 rows=8 width=0)
+        #      Join Filter: (posts.user_id = users.id)
+        #      ->  Index Scan using users_pkey on users  (cost=0.00..8.27 rows=1 width=4)
+        #            Index Cond: (id = 1)
+        #      ->  Seq Scan on posts  (cost=0.00..28.88 rows=8 width=4)
+        #            Filter: (posts.user_id = 1)
+        #   (6 rows)
+        #
+        def pp(result)
+          header = result.columns.first
+          lines  = result.rows.map(&:first)
+
+          # We add 2 because there's one char of padding at both sides, note
+          # the extra hyphens in the example above.
+          width = [header, *lines].map(&:length).max + 2
+
+          pp = []
+
+          pp << header.center(width).rstrip
+          pp << "-" * width
+
+          pp += lines.map { |line| " #{line}" }
+
+          nrows = result.rows.length
+          rows_label = nrows == 1 ? "row" : "rows"
+          pp << "(#{nrows} #{rows_label})"
+
+          pp.join("\n") + "\n"
+        end
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/cipherstash_pg/oid/array.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module ConnectionAdapters
+    module CipherStashPG
+      module OID # :nodoc:
+        class Array < Type::Value # :nodoc:
+          include ActiveModel::Type::Helpers::Mutable
+
+          Data = Struct.new(:encoder, :values) # :nodoc:
+
+          attr_reader :subtype, :delimiter
+          delegate :type, :user_input_in_time_zone, :limit, :precision, :scale, to: :subtype
+
+          def initialize(subtype, delimiter = ",")
+            @subtype = subtype
+            @delimiter = delimiter
+
+            @pg_encoder = PG::TextEncoder::Array.new name: "#{type}[]", delimiter: delimiter
+            @pg_decoder = PG::TextDecoder::Array.new name: "#{type}[]", delimiter: delimiter
+          end
+
+          def deserialize(value)
+            case value
+            when ::String
+              type_cast_array(@pg_decoder.decode(value), :deserialize)
+            when Data
+              type_cast_array(value.values, :deserialize)
+            else
+              super
+            end
+          end
+
+          def cast(value)
+            if value.is_a?(::String)
+              value = begin
+                @pg_decoder.decode(value)
+              rescue TypeError
+                # malformed array string is treated as [], will raise in PG 2.0 gem
+                # this keeps a consistent implementation
+                []
+              end
+            end
+            type_cast_array(value, :cast)
+          end
+
+          def serialize(value)
+            if value.is_a?(::Array)
+              casted_values = type_cast_array(value, :serialize)
+              Data.new(@pg_encoder, casted_values)
+            else
+              super
+            end
+          end
+
+          def ==(other)
+            other.is_a?(Array) &&
+              subtype == other.subtype &&
+              delimiter == other.delimiter
+          end
+
+          def type_cast_for_schema(value)
+            return super unless value.is_a?(::Array)
+            "[" + value.map { |v| subtype.type_cast_for_schema(v) }.join(", ") + "]"
+          end
+
+          def map(value, &block)
+            value.map { |v| subtype.map(v, &block) }
+          end
+
+          def changed_in_place?(raw_old_value, new_value)
+            deserialize(raw_old_value) != new_value
+          end
+
+          def force_equality?(value)
+            value.is_a?(::Array)
+          end
+
+          private
+            def type_cast_array(value, method)
+              if value.is_a?(::Array)
+                value.map { |item| type_cast_array(item, method) }
+              else
+                @subtype.public_send(method, value)
+              end
+            end
+        end
+      end
+    end
+  end
+end