aws_advanced_ruby_driver_wrapper 1.0.0

data/lib/aws_advanced_ruby_driver_wrapper/plugins/kms_encryption/sanitizer.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License").
+#  You may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+module AwsAdvancedRubyDriverWrapper
+  module Plugins
+    module Encryption
+      # Redaction helpers shared by the audit logger, the error context builder, and the
+      # kms_encryption error classes. Every method returns nil when given nil so that callers
+      # can decide how to render a missing value.
+      module Sanitizer
+        # Matches "password=...", "secret=...", "key=...", "token=..." assignments.
+        SENSITIVE_ASSIGNMENT_PATTERN = /(password|secret|key|token)=\S+/i
+        # Same as above, plus "credential=...", and stops at commas and closing braces so that
+        # it works on rendered hashes.
+        CREDENTIAL_ASSIGNMENT_PATTERN = /(password|secret|key|token|credential)=[^\s,}]+/i
+        # The region and account exclude '*' so that an ARN masked by {.arn} is not matched again,
+        # which would garble its partly masked key id. An unmasked ARN never contains a '*'.
+        KMS_ARN_PATTERN = %r{arn:aws:kms:[^:*]+:[^:*]+:key/[a-f0-9-]+}i
+        URL_PASSWORD_PATTERN = /[?&]password=[^&]*/i
+        URL_PWD_PATTERN = /[?&]pwd=[^&]*/i
+        # The password run excludes '/' and whitespace as well as '@', so it cannot scan past the
+        # start of the next authority; without that a string of "://x:" segments is quadratic to
+        # match. A URL's userinfo cannot contain an unencoded '/' anyway.
+        URL_USER_INFO_PATTERN = %r{://[^:/@\s]+:[^@/\s]+@}
+        SQL_STRING_LITERAL_PATTERN = /'[^']*'/
+        SQL_NUMERIC_LITERAL_PATTERN = /\b\d+\b/
+
+        MAX_NAME_LENGTH = 50
+        MAX_DESCRIPTION_LENGTH = 100
+        MAX_CONFIG_DETAILS_LENGTH = 150
+        MAX_ERROR_MESSAGE_LENGTH = 200
+        MAX_SQL_LENGTH = 100
+
+        module_function
+
+        # Masks the account and region of a KMS key ARN, and masks the middle of the trailing key id
+        # the same way {.key_id} does, so a key id is redacted consistently wherever it appears.
+        # @param value [String, nil]
+        # @return [String, nil]
+        def arn(value)
+          return nil if value.nil?
+
+          str = value.to_s
+          last_slash = str.rindex('/')
+          return 'arn:aws:kms:***:***:key/***' if last_slash.nil? || last_slash.zero? || last_slash == str.length - 1
+
+          "arn:aws:kms:***:***:key/#{key_id(str[(last_slash + 1)..])}"
+        end
+
+        # Keeps the first and last four characters of a key id, masking the middle.
+        # @param value [String, nil]
+        # @return [String, nil]
+        def key_id(value)
+          return nil if value.nil?
+
+          str = value.to_s
+          str.length > 8 ? "#{str[0, 4]}***#{str[-4..]}" : '***'
+        end
+
+        # @param value [String, nil]
+        # @return [String, nil]
+        def table_name(value)
+          truncate(value, MAX_NAME_LENGTH)
+        end
+
+        # @param value [String, nil]
+        # @return [String, nil]
+        def column_name(value)
+          truncate(value, MAX_NAME_LENGTH)
+        end
+
+        # @param value [String, nil]
+        # @return [String, nil]
+        def description(value)
+          return nil if value.nil?
+
+          truncate(value.gsub(SENSITIVE_ASSIGNMENT_PATTERN, '\1=***'), MAX_DESCRIPTION_LENGTH)
+        end
+
+        # @param value [String, nil]
+        # @return [String, nil]
+        def error_message(value)
+          return nil if value.nil?
+
+          masked = value.gsub(SENSITIVE_ASSIGNMENT_PATTERN, '\1=***')
+                        .gsub(KMS_ARN_PATTERN, 'arn:aws:kms:***:***:key/***')
+          truncate(masked, MAX_ERROR_MESSAGE_LENGTH)
+        end
+
+        # @param value [String, nil]
+        # @return [String, nil]
+        def config_details(value)
+          return nil if value.nil?
+
+          masked = value.gsub(CREDENTIAL_ASSIGNMENT_PATTERN, '\1=***')
+                        .gsub(KMS_ARN_PATTERN, 'arn:aws:kms:***:***:key/***')
+          truncate(masked, MAX_CONFIG_DETAILS_LENGTH)
+        end
+
+        # Masks credentials embedded in a connection URL, both as query parameters and as user info.
+        # @param value [String, nil]
+        # @return [String, nil]
+        def connection_url(value)
+          return nil if value.nil?
+
+          value.gsub(URL_PASSWORD_PATTERN, '?password=***')
+               .gsub(URL_PWD_PATTERN, '?pwd=***')
+               .gsub(URL_USER_INFO_PATTERN, '://***:***@')
+        end
+
+        # Replaces string and numeric literals so that SQL can be logged without leaking values.
+        # @param value [String, nil]
+        # @return [String, nil]
+        def sql(value)
+          return nil if value.nil?
+
+          masked = value.gsub(SQL_STRING_LITERAL_PATTERN, "'***'")
+                        .gsub(SQL_NUMERIC_LITERAL_PATTERN, '***')
+          truncate(masked, MAX_SQL_LENGTH)
+        end
+
+        # @param value [String, nil]
+        # @param limit [Integer]
+        # @return [String, nil]
+        def truncate(value, limit)
+          return nil if value.nil?
+
+          str = value.to_s
+          str.length > limit ? "#{str[0, limit - 3]}..." : str
+        end
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/plugins/kms_encryption/schema_name.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License").
+#  You may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+module AwsAdvancedRubyDriverWrapper
+  module Plugins
+    module Encryption
+      # A validated database schema name.
+      #
+      # Schema names cannot be bound as statement parameters, so the plugin has to
+      # interpolate them into the metadata queries. Wrapping the name in this type keeps
+      # that interpolation safe: only plain identifiers are accepted, which rules out
+      # quoting, whitespace, comments, and statement separators.
+      class SchemaName
+        VALID_PATTERN = /\A[a-zA-Z_][a-zA-Z0-9_]*\z/
+
+        attr_reader :value
+
+        # @param name [String, Symbol, SchemaName] the schema name to validate
+        # @return [SchemaName]
+        # @raise [ArgumentError] if the name is empty or is not a plain SQL identifier
+        def self.of(name)
+          name.is_a?(SchemaName) ? name : new(name)
+        end
+
+        # @param value [String, Symbol]
+        # @raise [ArgumentError] if the name is empty or is not a plain SQL identifier
+        def initialize(value)
+          name = value.to_s
+          raise ArgumentError, 'Schema name cannot be empty' if value.nil? || name.strip.empty?
+
+          unless VALID_PATTERN.match?(name)
+            raise ArgumentError,
+                  "Invalid schema name: #{name.inspect}. Schema names must start with a letter or underscore and " \
+                  'contain only letters, digits, and underscores.'
+          end
+
+          @value = name.freeze
+          freeze
+        end
+
+        def to_s
+          @value
+        end
+        alias to_str to_s
+
+        def ==(other)
+          other.is_a?(SchemaName) && other.value == @value
+        end
+        alias eql? ==
+
+        def hash
+          [self.class, @value].hash
+        end
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/plugins/kms_encryption/schema_validator.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License").
+#  You may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+require_relative 'schema_name'
+
+module AwsAdvancedRubyDriverWrapper
+  module Plugins
+    module Encryption
+      # Checks that the +encryption_metadata+ and +key_storage+ tables exist and look the way the
+      # plugin expects before any kms_encryption is attempted.
+      #
+      # Everything is read from +information_schema+, which both PostgreSQL and MySQL provide, so
+      # the same queries work for either driver. Only the foreign key lookup differs: MySQL keeps
+      # the referenced table on +key_column_usage+, while PostgreSQL exposes it through
+      # +constraint_column_usage+.
+      class SchemaValidator
+        REQUIRED_ENCRYPTION_METADATA_COLUMNS = %w[
+          table_name column_name encryption_algorithm key_id created_at updated_at
+        ].freeze
+
+        REQUIRED_KEY_STORAGE_COLUMNS = %w[
+          id key_id name master_key_arn encrypted_data_key hmac_key key_spec created_at last_used_at
+        ].freeze
+
+        ENCRYPTION_METADATA_TABLE = 'encryption_metadata'
+        KEY_STORAGE_TABLE = 'key_storage'
+        UNIQUE_METADATA_COLUMNS = %w[table_name column_name].freeze
+
+        # The outcome of a validation run.
+        ValidationResult = Data.define(:valid, :issues)
+
+        # Reopened so that the constant below is scoped to the result class.
+        class ValidationResult
+          def initialize(valid: nil, issues: [])
+            frozen_issues = issues.freeze
+            super(valid: valid.nil? ? frozen_issues.empty? : valid, issues: frozen_issues)
+          end
+
+          # @return [Boolean]
+          def valid?
+            valid
+          end
+
+          def to_s
+            valid? ? 'Schema validation passed' : "Schema validation failed: #{issues.join(', ')}"
+          end
+          alias inspect to_s
+        end
+
+        # @param metadata_schema [SchemaName, String] the schema holding the two tables
+        # @param sql_runner [SqlRunner]
+        def initialize(metadata_schema, sql_runner)
+          raise ArgumentError, 'metadata_schema is required' if metadata_schema.nil?
+
+          @schema = SchemaName.of(metadata_schema)
+          @sql = sql_runner
+        end
+
+        # Validates the schema over an existing connection.
+        #
+        # @param connection [Object] a pg or mysql2 connection
+        # @return [ValidationResult]
+        def validate(connection)
+          issues = []
+
+          issues.concat(validate_table(connection, ENCRYPTION_METADATA_TABLE, REQUIRED_ENCRYPTION_METADATA_COLUMNS) do
+            unique_constraint_issues(connection)
+          end)
+
+          issues.concat(validate_table(connection, KEY_STORAGE_TABLE, REQUIRED_KEY_STORAGE_COLUMNS) do
+            primary_key_issues(connection)
+          end)
+
+          # Only worth checking once both tables are known to be sound.
+          issues.concat(foreign_key_issues(connection)) if issues.empty?
+
+          ValidationResult.new(issues: issues)
+        end
+
+        private
+
+        # Checks that a table exists and has every required column, then runs the table's own
+        # constraint checks.
+        def validate_table(connection, table, required_columns)
+          qualified = qualify(table)
+          return ["Table '#{qualified}' does not exist"] unless table_exists?(connection, table)
+
+          issues = missing_columns(connection, table, required_columns).map do |column|
+            "Table '#{qualified}' is missing required column '#{column}'"
+          end
+          issues.concat(yield)
+        end
+
+        def table_exists?(connection, table)
+          rows = @sql.query(
+            connection,
+            "SELECT 1 AS present FROM information_schema.tables WHERE table_schema #{eq} ? AND table_name #{eq} ?",
+            [@schema.to_s, table]
+          )
+          !rows.empty?
+        end
+
+        def missing_columns(connection, table, required_columns)
+          rows = @sql.query(
+            connection,
+            'SELECT column_name AS name FROM information_schema.columns ' \
+            "WHERE table_schema #{eq} ? AND table_name #{eq} ?",
+            [@schema.to_s, table]
+          )
+          existing = rows.to_set { |row| value(row, 'name').to_s.downcase }
+
+          required_columns.reject { |column| existing.include?(column.downcase) }
+        end
+
+        def unique_constraint_issues(connection)
+          columns = constrained_columns(connection, ENCRYPTION_METADATA_TABLE, ['PRIMARY KEY', 'UNIQUE'])
+          expected = UNIQUE_METADATA_COLUMNS.to_set
+          return [] if columns.include?(expected)
+
+          ["Table '#{qualify(ENCRYPTION_METADATA_TABLE)}' is missing a unique constraint on " \
+           "(#{UNIQUE_METADATA_COLUMNS.join(', ')})"]
+        end
+
+        def primary_key_issues(connection)
+          columns = constrained_columns(connection, KEY_STORAGE_TABLE, ['PRIMARY KEY'])
+          return [] if columns.any? { |constraint_columns| constraint_columns.include?('id') }
+
+          ["Table '#{qualify(KEY_STORAGE_TABLE)}' is missing a primary key on 'id'"]
+        end
+
+        def foreign_key_issues(connection)
+          references = foreign_keys(connection, ENCRYPTION_METADATA_TABLE)
+          matched = references.any? do |reference|
+            reference[:from_column] == 'key_id' &&
+              reference[:to_table] == KEY_STORAGE_TABLE &&
+              reference[:to_column] == 'id'
+          end
+          return [] if matched
+
+          ["Missing foreign key constraint from #{qualify(ENCRYPTION_METADATA_TABLE)}.key_id " \
+           "to #{qualify(KEY_STORAGE_TABLE)}.id"]
+        end
+
+        # The column sets of every constraint of the given types, one set per constraint.
+        #
+        # @return [Array<Set<String>>]
+        def constrained_columns(connection, table, constraint_types)
+          # Spelled out as ORs rather than IN, since IN compares with an unqualified operator.
+          type_matches = Array.new(constraint_types.size, "tc.constraint_type #{eq} ?").join(' OR ')
+          rows = @sql.query(
+            connection,
+            'SELECT tc.constraint_name AS constraint_name, kcu.column_name AS column_name ' \
+            'FROM information_schema.table_constraints tc ' \
+            'JOIN information_schema.key_column_usage kcu ' \
+            "ON tc.constraint_name #{eq} kcu.constraint_name AND tc.table_schema #{eq} kcu.table_schema " \
+            "AND tc.table_name #{eq} kcu.table_name WHERE (#{type_matches}) " \
+            "AND tc.table_schema #{eq} ? AND tc.table_name #{eq} ?",
+            constraint_types + [@schema.to_s, table]
+          )
+
+          grouped = rows.group_by { |row| value(row, 'constraint_name') }
+          grouped.values.map { |group| group.to_set { |row| value(row, 'column_name').to_s.downcase } }
+        end
+
+        # @return [Array<Hash>] one entry per foreign key column of the table
+        def foreign_keys(connection, table)
+          rows = @sql.query(connection, foreign_key_sql, [@schema.to_s, table])
+
+          rows.map do |row|
+            {
+              from_column: value(row, 'from_column').to_s.downcase,
+              to_table: value(row, 'to_table').to_s.downcase,
+              to_column: value(row, 'to_column').to_s.downcase
+            }
+          end
+        end
+
+        def foreign_key_sql
+          @sql.foreign_key_query
+        end
+
+        # MySQL reports information_schema column names in upper case on some versions, so every
+        # lookup accepts either case.
+        def value(row, key)
+          row[key] || row[key.upcase]
+        end
+
+        def qualify(table)
+          "#{@schema}.#{table}"
+        end
+
+        def eq
+          @sql.equals_operator
+        end
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/plugins/kms_encryption/sql_runner.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License").
+#  You may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+require_relative '../../driver_dialects/pg_driver_dialect'
+
+module AwsAdvancedRubyDriverWrapper
+  module Plugins
+    module Encryption
+      # Runs the plugin's own metadata and key storage queries against either driver.
+      #
+      # The plugin needs to talk to +encryption_metadata+ and +key_storage+ itself, and the two
+      # drivers disagree on almost every detail of how to do that: pg wants +$1+ placeholders
+      # and hex escaped bytea, mysql2 wants +?+ placeholders and raw binary, and only pg can
+      # return a generated id from an INSERT. This isolates those differences so that the
+      # managers above it can be written once.
+      #
+      # SQL is always written with +?+ placeholders and translated here.
+      class SqlRunner
+        # @param driver_dialect [DriverDialects::DriverDialect] the dialect of the connection in use
+        def initialize(driver_dialect)
+          @driver_dialect = driver_dialect
+          @pg = driver_dialect.is_a?(DriverDialects::PgDriverDialect)
+        end
+
+        # @return [Boolean] true when the underlying driver is pg
+        def pg?
+          @pg
+        end
+
+        # Runs a query and returns its rows.
+        #
+        # @param connection [Object] a pg or mysql2 connection
+        # @param template [String] SQL using +?+ placeholders
+        # @param params [Array] the bind parameters
+        # @return [Array<Hash{String => Object}>] the result rows, empty for statements without one
+        def query(connection, template, params = [])
+          rows(raw_execute(connection, template, params))
+        end
+        alias execute query
+
+        # Runs an INSERT, UPDATE, or DELETE and returns how many rows it changed.
+        #
+        # @param connection [Object] a pg or mysql2 connection
+        # @param template [String] SQL using +?+ placeholders
+        # @param params [Array] the bind parameters
+        # @return [Integer] the number of affected rows
+        def update(connection, template, params = [])
+          result = raw_execute(connection, template, params)
+          @driver_dialect.affected_rows(connection, result)
+        end
+
+        # Runs an INSERT and returns the generated +id+.
+        #
+        # @param connection [Object] a pg or mysql2 connection
+        # @param template [String] an INSERT using +?+ placeholders, without a RETURNING clause
+        # @param params [Array] the bind parameters
+        # @param id_column [String] the generated column to return
+        # @return [Integer, nil] the generated id
+        def insert_returning_id(connection, template, params, id_column: 'id')
+          @driver_dialect.insert_returning_id(connection, translate(template), params, id_column)
+        end
+
+        # Wraps a binary value so that it can be bound to a bytea or blob parameter.
+        #
+        # @param bytes [String, nil] binary data
+        # @return [Object, nil] the driver specific bind value
+        def binary_param(bytes)
+          return nil if bytes.nil?
+
+          @driver_dialect.binary_param(bytes)
+        end
+
+        # Reads a bytea or blob column back into binary data.
+        #
+        # @param value [String, nil] the raw column value
+        # @return [String, nil] binary data
+        def read_binary(value)
+          return nil if value.nil?
+
+          @driver_dialect.read_binary(value)
+        end
+
+        # Translates +?+ placeholders into the driver's own placeholder syntax.
+        #
+        # @param template [String]
+        # @return [String]
+        def translate(template)
+          @driver_dialect.translate_placeholders(template)
+        end
+
+        # The driver-specific trailing upsert clause for an INSERT.
+        #
+        # @param conflict_columns [Array<String>] the columns whose conflict triggers the update
+        # @param update_columns [Array<String>] the columns to overwrite from the incoming row
+        # @return [String]
+        def upsert_clause(conflict_columns, update_columns)
+          @driver_dialect.upsert_clause(conflict_columns, update_columns)
+        end
+
+        # The driver-specific equality operator. Every comparison in the plugin's own SQL uses it,
+        # so that on pg a user-defined operator earlier in the search_path cannot take its place.
+        #
+        # @return [String]
+        def equals_operator
+          @driver_dialect.equals_operator
+        end
+
+        # The driver-specific query for a table's foreign keys, using +?+ placeholders for the
+        # schema and table names.
+        #
+        # @return [String]
+        def foreign_key_query
+          @driver_dialect.foreign_key_query
+        end
+
+        private
+
+        def raw_execute(connection, template, params)
+          if params.empty?
+            @driver_dialect.execute(connection, translate(template))
+          else
+            @driver_dialect.execute_with_params(connection, translate(template), params)
+          end
+        end
+
+        def rows(result)
+          return [] if result.nil? || !result.respond_to?(:each)
+
+          result.to_a
+        end
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/plugins/kms_encryption/type_marker.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License").
+#  You may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+require 'bigdecimal'
+require 'date'
+
+module AwsAdvancedRubyDriverWrapper
+  module Plugins
+    module Encryption
+      # The single byte written ahead of the ciphertext that records how the plaintext was
+      # serialized, so that a decrypted payload can be turned back into a Ruby value.
+      module TypeMarker
+        STRING = 1
+        INTEGER = 2
+        LONG = 3
+        DOUBLE = 4
+        FLOAT = 5
+        BOOLEAN = 6
+        BIG_DECIMAL = 7
+        DATE = 8
+        TIME = 9
+        TIMESTAMP = 10
+        LOCAL_DATE = 11
+        LOCAL_TIME = 12
+        LOCAL_DATE_TIME = 13
+        BYTE_ARRAY = 14
+        GENERIC = 99
+
+        NAMES = {
+          STRING => 'STRING',
+          INTEGER => 'INTEGER',
+          LONG => 'LONG',
+          DOUBLE => 'DOUBLE',
+          FLOAT => 'FLOAT',
+          BOOLEAN => 'BOOLEAN',
+          BIG_DECIMAL => 'BIG_DECIMAL',
+          DATE => 'DATE',
+          TIME => 'TIME',
+          TIMESTAMP => 'TIMESTAMP',
+          LOCAL_DATE => 'LOCAL_DATE',
+          LOCAL_TIME => 'LOCAL_TIME',
+          LOCAL_DATE_TIME => 'LOCAL_DATE_TIME',
+          BYTE_ARRAY => 'BYTE_ARRAY',
+          GENERIC => 'GENERIC'
+        }.freeze
+
+        ALL = NAMES.keys.freeze
+
+        module_function
+
+        # @param value [Integer] the marker byte read from an encrypted payload
+        # @return [Integer] the same marker, once validated
+        # @raise [ArgumentError] if the byte is not a known marker
+        def from_value(value)
+          raise ArgumentError, "Unknown type marker: #{value.inspect}" unless NAMES.key?(value)
+
+          value
+        end
+
+        # Picks the marker used to serialize a Ruby value. Unknown classes fall back to
+        # {GENERIC}, which is serialized through +to_s+.
+        #
+        # Ruby has a single unbounded Integer type, so integers are always written as
+        # {LONG}. {INTEGER} is still understood on read for payloads written by the wrapper.
+        #
+        # @param value [Object]
+        # @return [Integer]
+        def from_object(value)
+          case value
+          when String then value.encoding == ::Encoding::BINARY ? BYTE_ARRAY : STRING
+          when Integer then LONG
+          when Float then DOUBLE
+          when true, false then BOOLEAN
+          when BigDecimal then BIG_DECIMAL
+          when ::Time then TIMESTAMP
+          when ::DateTime then LOCAL_DATE_TIME
+          when ::Date then LOCAL_DATE
+          else GENERIC
+          end
+        end
+
+        # @param marker [Integer]
+        # @return [String, nil] the human-readable name of the marker
+        def name_for(marker)
+          NAMES[marker]
+        end
+
+        # @param marker [Integer]
+        # @return [Boolean]
+        def known?(marker)
+          NAMES.key?(marker)
+        end
+      end
+    end
+  end
+end