asherah 0.9.0-aarch64-linux → 0.10.0-aarch64-linux

data/lib/asherah.rb

@@ -1,135 +1,321 @@
 # frozen_string_literal: true
 
-require_relative 'asherah/version'
-require 'asherah/config'
-require 'asherah/error'
-require 'cobhan'
+require "json"
 
-# Asherah is a Ruby wrapper around Asherah Go application-layer encryption SDK.
-module Asherah
-  extend Cobhan
+require_relative "asherah/version"
+require_relative "asherah/error"
+require_relative "asherah/config"
+require_relative "asherah/native"
+require_relative "asherah/session_factory"
+require_relative "asherah/session"
+require_relative "asherah/hooks"
 
-  LIB_ROOT_PATH = File.expand_path('asherah/native', __dir__)
-  load_library(LIB_ROOT_PATH, 'libasherah', [
-    [:SetEnv, [:pointer], :int32],
-    [:SetupJson, [:pointer], :int32],
-    [:EncryptToJson, [:pointer, :pointer, :pointer], :int32],
-    [:DecryptFromJson, [:pointer, :pointer, :pointer], :int32],
-    [:Shutdown, [], :void]
-  ].freeze)
+module Asherah
+  DEFAULT_SESSION_CACHE_MAX_SIZE = 1000
 
-  ESTIMATED_ENCRYPTION_OVERHEAD = 48
-  ESTIMATED_ENVELOPE_OVERHEAD = 185
-  BASE64_OVERHEAD = 1.34
+  @mutex = Mutex.new
+  @factory = nil
+  # @sessions is an LRU cache. Ruby Hash preserves insertion order, so we
+  # implement LRU by delete-and-reinsert on hit (moves the entry to the
+  # end), and `shift` on overflow (removes the oldest, i.e. least-recently
+  # used). Bounded by @session_cache_max_size, which honors the
+  # SessionCacheMaxSize config field — same default (1000) as the Rust
+  # core and the other bindings.
+  @sessions = {}
+  @initialized = false
+  @session_cache_enabled = true
+  @session_cache_max_size = DEFAULT_SESSION_CACHE_MAX_SIZE
+  @verbose = false
 
   class << self
-    # Set environment variables needed by Asherah dependencies for when
-    # Go os.Getenv() doesn't see variables set by C.setenv().
-    # References:
-    #   https://github.com/golang/go/wiki/cgo#environmental-variables
-    #   https://github.com/golang/go/issues/44108
+    # Configure Asherah using a block with snake_case accessors.
+    # Compatible with the canonical godaddy/asherah-ruby gem API.
     #
-    # @yield [Config]
-    # @param env [Hash], Key-value pairs to set Asherah ENV
-    # @return [void]
-    def set_env(env = {})
-      env_buffer = string_to_cbuffer(env.to_json)
+    #   Asherah.configure do |config|
+    #     config.service_name = "MyService"
+    #     config.product_id = "MyProduct"
+    #     config.kms = "static"
+    #     config.metastore = "memory"
+    #   end
+    def configure
+      @mutex.synchronize do
+        raise Error::AlreadyInitialized if @initialized
 
-      result = SetEnv(env_buffer)
-      Error.check_result!(result, 'SetEnv failed')
-    ensure
-      env_buffer&.free
+        config = Config.new
+        yield config
+        config.validate!
+
+        json = config.to_json
+        pointer = Native.asherah_factory_new_with_config(json)
+        @factory = SessionFactory.new(pointer)
+        @sessions = {}
+        @initialized = true
+        @session_cache_enabled = config.enable_session_caching != false
+        @session_cache_max_size = positive_int(config.session_cache_max_size) || DEFAULT_SESSION_CACHE_MAX_SIZE
+        @verbose = config.verbose == true
+      end
     end
 
-    # Configures Asherah
-    #
-    # @yield [Config]
-    # @return [void]
-    def configure
-      raise Asherah::Error::AlreadyInitialized if @initialized
+    # Initialize Asherah with a PascalCase config hash.
+    # Also accepts snake_case string/symbol keys (auto-normalized).
+    def setup(config)
+      normalized = normalize_config(config)
+      json = JSON.generate(normalized)
 
-      config = Config.new
-      yield config
-      config.validate!
-      @intermediated_key_overhead_bytesize = config.product_id.bytesize + config.service_name.bytesize
+      pointer = Native.asherah_factory_new_with_config(json)
+      factory = SessionFactory.new(pointer)
 
-      config_buffer = string_to_cbuffer(config.to_json)
+      @mutex.synchronize do
+        raise Error::AlreadyInitialized if @initialized
 
-      result = SetupJson(config_buffer)
-      Error.check_result!(result, 'SetupJson failed')
-      @initialized = true
-    ensure
-      config_buffer&.free
+        @factory = factory
+        @sessions = {}
+        @initialized = true
+        @session_cache_enabled = truthy(normalized["EnableSessionCaching"], default: true)
+        @session_cache_max_size = positive_int(normalized["SessionCacheMaxSize"]) || DEFAULT_SESSION_CACHE_MAX_SIZE
+        @verbose = truthy(normalized["Verbose"], default: false)
+      end
+
+      nil
+    rescue StandardError
+      factory&.close if defined?(factory) && factory
+      raise
     end
 
-    # Encrypts data for a given partition_id and returns DataRowRecord in JSON format.
-    #
-    # DataRowRecord contains the encrypted key and data, as well as the information
-    # required to decrypt the key encryption key. This object data should be stored
-    # in your data persistence as it's required to decrypt data.
-    #
-    # EnvelopeKeyRecord represents an encrypted key and is the data structure used
-    # to persist the key in the key table. It also contains the meta data
-    # of the key used to encrypt it.
-    #
-    # KeyMeta contains the `id` and `created` timestamp for an encryption key.
-    #
-    # @param partition_id [String]
-    # @param data [String]
-    # @return [String], DataRowRecord in JSON format
-    def encrypt(partition_id, data)
-      raise Asherah::Error::NotInitialized unless @initialized
+    # Run setup in a background Thread. Yields the result to +block+ on
+    # success. Exceptions raised by setup propagate via the Thread's
+    # joined error — the previous implementation called the block with
+    # the result on success but silently dropped the Thread's error
+    # state on failure, leaving callers unable to distinguish completion
+    # from an unsetup factory. The Thread aborts on exception
+    # (`Thread.report_on_exception = true`), so a stack trace lands on
+    # stderr; callers that need programmatic access should
+    # `thread.join` to re-raise. T-finding "setup_async/shutdown_async/
+    # encrypt_async/decrypt_async swallow Thread exceptions" in
+    # `docs/review-2026-05-05-findings.md`.
+    def setup_async(config, &block)
+      Thread.new do
+        Thread.current.report_on_exception = true
+        result = setup(config)
+        block&.call(result)
+        result
+      end
+    end
 
-      partition_id_buffer = string_to_cbuffer(partition_id)
-      data_buffer = string_to_cbuffer(data)
-      estimated_buffer_bytesize = estimate_buffer(data.bytesize, partition_id.bytesize)
-      output_buffer = allocate_cbuffer(estimated_buffer_bytesize)
+    def shutdown
+      factory = nil
+      sessions = nil
+      @mutex.synchronize do
+        raise Error::NotInitialized unless @initialized
 
-      result = EncryptToJson(partition_id_buffer, data_buffer, output_buffer)
-      Error.check_result!(result, 'EncryptToJson failed')
+        factory = @factory
+        sessions = @sessions.values
+        @factory = nil
+        @sessions = {}
+        @initialized = false
+      end
 
-      cbuffer_to_string(output_buffer)
-    ensure
-      [partition_id_buffer, data_buffer, output_buffer].compact.each(&:free)
+      Array(sessions).each do |session|
+        begin
+          session.close unless session.closed?
+        rescue StandardError => e
+          warn "asherah: error closing session during shutdown: #{e.message}"
+        end
+      end
+      factory&.close unless factory&.closed?
+      nil
     end
 
-    # Decrypts a DataRowRecord in JSON format for a partition_id and returns decrypted data.
-    #
-    # @param partition_id [String]
-    # @param json [String], DataRowRecord in JSON format
-    # @return [String], Decrypted data
-    def decrypt(partition_id, json)
-      raise Asherah::Error::NotInitialized unless @initialized
+    # Run shutdown in a background Thread; see `setup_async` for the
+    # exception-propagation contract.
+    def shutdown_async(&block)
+      Thread.new do
+        Thread.current.report_on_exception = true
+        result = shutdown
+        block&.call(result)
+        result
+      end
+    end
 
-      partition_id_buffer = string_to_cbuffer(partition_id)
-      data_buffer = string_to_cbuffer(json)
-      output_buffer = allocate_cbuffer(json.bytesize)
+    def get_setup_status
+      @mutex.synchronize { @initialized }
+    end
 
-      result = DecryptFromJson(partition_id_buffer, data_buffer, output_buffer)
-      Error.check_result!(result, 'DecryptFromJson failed')
+    def setenv(env = {})
+      data = case env
+             when String
+               JSON.parse(env)
+             else
+               env
+             end
+      unless data.respond_to?(:each_pair)
+        raise ArgumentError, "environment payload must be a Hash or JSON object"
+      end
+      data.each_pair do |k, v|
+        if v.nil?
+          ENV.delete(String(k))
+        else
+          ENV[String(k)] = v.to_s
+        end
+      end
+      nil
+    end
+    alias_method :set_env, :setenv
 
-      cbuffer_to_string(output_buffer)
-    ensure
-      [partition_id_buffer, data_buffer, output_buffer].compact.each(&:free)
+    def encrypt(partition_id, payload)
+      raise ArgumentError, "payload cannot be nil" if payload.nil?
+      session = resolve_session(partition_id)
+      session.encrypt_bytes(payload)
     end
 
-    # Stop the Asherah instance
-    def shutdown
-      raise Asherah::Error::NotInitialized unless @initialized
+    def encrypt_string(partition_id, text)
+      raise ArgumentError, "text cannot be nil" if text.nil?
+      encrypt(partition_id, text)
+    end
+
+    def decrypt(partition_id, data_row_record)
+      raise ArgumentError, "data_row_record cannot be nil" if data_row_record.nil?
+      session = resolve_session(partition_id)
+      session.decrypt_bytes(data_row_record).force_encoding(Encoding::UTF_8)
+    end
+
+    def decrypt_string(partition_id, data_row_record)
+      raise ArgumentError, "data_row_record cannot be nil" if data_row_record.nil?
+      decrypt(partition_id, data_row_record).force_encoding(Encoding::UTF_8)
+    end
+
+    # Run encrypt in a background Thread; see `setup_async` for the
+    # exception-propagation contract.
+    def encrypt_async(partition_id, payload, &block)
+      Thread.new do
+        Thread.current.report_on_exception = true
+        result = encrypt(partition_id, payload)
+        block&.call(result)
+        result
+      end
+    end
+
+    # Run decrypt in a background Thread; see `setup_async` for the
+    # exception-propagation contract.
+    def decrypt_async(partition_id, data_row_record, &block)
+      Thread.new do
+        Thread.current.report_on_exception = true
+        result = decrypt(partition_id, data_row_record)
+        block&.call(result)
+        result
+      end
+    end
+
+    # Install a log hook. Yields a +Hash+ +{level:, target:, message:}+ for
+    # every log record emitted by the underlying Rust crates. The block may
+    # fire from any thread; implementations must be thread-safe and
+    # non-blocking. Pass +nil+ to clear (equivalent to {clear_log_hook}).
+    #
+    # Replaces any previously installed log hook. Exceptions raised from the
+    # callback are caught and silently swallowed.
+    def set_log_hook(callback = nil, &block)
+      Hooks.set_log_hook(callback, &block)
+    end
 
-      Shutdown()
-      @initialized = false
+    # Remove the active log hook, if any. Idempotent.
+    def clear_log_hook
+      Hooks.clear_log_hook
+    end
+
+    # Install a metrics hook. Yields a +Hash+ +{type:, duration_ns:, name:}+
+    # for every metrics event. Timing events ({:encrypt, :decrypt, :store,
+    # :load}) carry a positive +duration_ns+ and a +nil+ +name+; cache events
+    # ({:cache_hit, :cache_miss, :cache_stale}) carry +duration_ns+ == 0 and
+    # the cache identifier in +name+.
+    #
+    # Installing a hook implicitly enables the global metrics gate; clearing
+    # it disables the gate. Replaces any previously installed metrics hook.
+    # Pass +nil+ to clear (equivalent to {clear_metrics_hook}).
+    def set_metrics_hook(callback = nil, &block)
+      Hooks.set_metrics_hook(callback, &block)
+    end
+
+    # Remove the active metrics hook and disable metrics. Idempotent.
+    def clear_metrics_hook
+      Hooks.clear_metrics_hook
     end
 
     private
 
-    def estimate_buffer(data_bytesize, partition_bytesize)
-      est_data_len = (((data_bytesize + ESTIMATED_ENCRYPTION_OVERHEAD) * BASE64_OVERHEAD).to_i + 1)
+    REQUIRED_KEYS = %w[ServiceName ProductID Metastore].freeze
+
+    def normalize_config(config)
+      unless config.respond_to?(:each_pair)
+        raise ArgumentError, "config must be a Hash-like object"
+      end
+      normalized = {}
+      config.each_pair do |key, value|
+        normalized[String(key)] = value
+      end
+      REQUIRED_KEYS.each do |key|
+        raise ArgumentError, "#{key} is required" if normalized[key].nil? || normalized[key].to_s.strip.empty?
+      end
+      normalized
+    end
+
+    def truthy(value, default: false)
+      return default if value.nil?
+
+      case value
+      when true, "1", "true", "TRUE", "yes", "on" then true
+      when false, "0", "false", "FALSE", "no", "off" then false
+      else
+        default
+      end
+    end
+
+    def resolve_session(partition_id)
+      raise ArgumentError, "partition_id cannot be empty" if String(partition_id).empty?
+
+      evicted = nil
+      session = @mutex.synchronize do
+        raise Error::NotInitialized unless @initialized
+
+        unless @session_cache_enabled
+          break @factory.get_session(partition_id)
+        end
+
+        # LRU: on hit, delete + reinsert to move the entry to the
+        # most-recently-used end of the Hash (Ruby Hash is insertion-
+        # ordered). On miss + overflow, `shift` removes the oldest entry,
+        # which is the least-recently-used.
+        if (existing = @sessions.delete(partition_id))
+          @sessions[partition_id] = existing
+          break existing
+        end
+
+        fresh = @factory.get_session(partition_id)
+        @sessions[partition_id] = fresh
+        if @sessions.size > @session_cache_max_size
+          _, evicted = @sessions.shift
+        end
+        fresh
+      end
+
+      # Close evicted session outside the lock — close hits the FFI and
+      # we don't want to serialize all encrypts behind one eviction.
+      if evicted
+        begin
+          evicted.close unless evicted.closed?
+        rescue StandardError => e
+          warn "asherah: error closing evicted session: #{e.message}"
+        end
+      end
+
+      session
+    end
 
-      ESTIMATED_ENVELOPE_OVERHEAD +
-        @intermediated_key_overhead_bytesize +
-        partition_bytesize +
-        est_data_len
+    def positive_int(value)
+      return nil if value.nil?
+      n = Integer(value)
+      n.positive? ? n : nil
+    rescue ArgumentError, TypeError
+      nil
     end
   end
 end

metadata

@@ -1,68 +1,72 @@
 --- !ruby/object:Gem::Specification
 name: asherah
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: aarch64-linux
 authors:
-- GoDaddy
+- Jay Gowdy
+- Bo Thompson
+- Michael Micco
+- Dalibor Nasevic
 autorequire:
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2026-03-23 00:00:00.000000000 Z
+date: 2026-06-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: cobhan
+  name: ffi
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: '1.15'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.0
-  force_ruby_platform: false
-description: |
-  Asherah is an application-layer encryption SDK that provides advanced
-  encryption features and defense in depth against compromise.
-email:
-- oss@godaddy.com
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+description: Asherah application-layer encryption for Ruby with automatic key rotation,
+  powered by the native Rust implementation.
+email: oss@godaddy.com
 executables: []
-extensions:
-- ext/asherah/extconf.rb
+extensions: []
 extra_rdoc_files: []
 files:
-- ".env.secrets.example"
-- ".rspec"
-- ".rubocop.yml"
-- ".ruby-version"
-- CHANGELOG.md
-- CODE_OF_CONDUCT.md
-- CONTRIBUTING.md
-- Gemfile
-- LICENSE.txt
 - README.md
-- Rakefile
-- SECURITY.md
-- asherah.gemspec
-- ext/asherah/checksums.yml
-- ext/asherah/extconf.rb
-- ext/asherah/native_file.rb
 - lib/asherah.rb
 - lib/asherah/config.rb
 - lib/asherah/error.rb
-- lib/asherah/native/libasherah-arm64.so
+- lib/asherah/hooks.rb
+- lib/asherah/native.rb
+- lib/asherah/native/libasherah_ffi.so
+- lib/asherah/session.rb
+- lib/asherah/session_factory.rb
 - lib/asherah/version.rb
-homepage: https://github.com/godaddy/asherah-ruby
+homepage: https://github.com/godaddy/asherah-ffi
 licenses:
-- MIT
+- Apache-2.0
 metadata:
-  homepage_uri: https://github.com/godaddy/asherah-ruby
-  source_code_uri: https://github.com/godaddy/asherah-ruby
-  changelog_uri: https://github.com/godaddy/asherah-ruby/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/godaddy/asherah-ffi
+  source_code_uri: https://github.com/godaddy/asherah-ffi
+  github_repo: https://github.com/godaddy/asherah-ffi
+  changelog_uri: https://github.com/godaddy/asherah-ffi/releases
+  bug_tracker_uri: https://github.com/godaddy/asherah-ffi/issues
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -72,15 +76,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Application Layer Encryption SDK
+summary: Asherah application-layer encryption for Ruby with automatic key rotation.
 test_files: []

data/.env.secrets.example

@@ -1,9 +0,0 @@
-# Example secrets file for KMS integration tests
-# Copy this file to .env.secrets and fill in actual values
-# 
-# IMPORTANT: Never commit .env.secrets to version control
-# The .env.secrets file is already in .gitignore
-
-# AWS KMS Key ARN for integration tests (optional)
-# Only needed if running spec/kms_spec.rb
-# KMS_KEY_ARN=arn:aws:kms:us-west-2:123456789012:key/12345678-1234-1234-1234-123456789012

data/.rspec

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

data/.rubocop.yml

@@ -1,112 +0,0 @@
-AllCops:
-  TargetRubyVersion: 2.7
-  NewCops: enable
-  SuggestExtensions: false
-  Exclude:
-    - 'vendor/**/*' # Github Actions
-    - 'tmp/**/*'
-
-Layout/LineLength:
-  Max: 120
-
-# Metrics cops with reasonable limits
-Metrics/BlockLength:
-  Max: 25
-  Exclude:
-    - 'spec/**/*'
-    - '*.gemspec'
-    - 'Rakefile'
-
-Metrics/MethodLength:
-  Max: 15
-  Exclude:
-    - 'spec/**/*'
-    - 'tasks/**/*'
-
-Metrics/AbcSize:
-  Max: 20
-  Exclude:
-    - 'spec/**/*'
-    - 'tasks/**/*'
-
-Metrics/CyclomaticComplexity:
-  Max: 10
-  Exclude:
-    - 'spec/**/*'
-
-Metrics/PerceivedComplexity:
-  Max: 10
-  Exclude:
-    - 'spec/**/*'
-
-Metrics/ClassLength:
-  Max: 150
-  Exclude:
-    - 'spec/**/*'
-
-Metrics/ModuleLength:
-  Max: 150
-  Exclude:
-    - 'spec/**/*'
-
-# Style cops that were disabled but should be enabled
-Style/WordArray:
-  MinSize: 3
-  EnforcedStyle: brackets
-
-Style/SymbolArray:
-  MinSize: 3
-  EnforcedStyle: brackets
-
-Style/MultilineBlockChain:
-  Enabled: true
-  Exclude:
-    - 'spec/**/*'
-
-Style/BlockDelimiters:
-  EnforcedStyle: semantic
-  FunctionalMethods:
-    - let
-    - let!
-    - subject
-    - before
-    - after
-  Exclude:
-    - 'asherah.gemspec'
-    - 'ext/asherah/native_file.rb'
-
-Style/GuardClause:
-  MinBodyLength: 3
-  Exclude:
-    - 'ext/asherah/native_file.rb'
-
-# Naming cop adjustment
-Naming/AccessorMethodName:
-  Exclude:
-    - 'lib/asherah.rb' # set_env is intentionally named
-
-# Documentation cops
-Style/Documentation:
-  Enabled: true
-  Exclude:
-    - 'spec/**/*'
-    - 'features/**/*'
-
-Style/DocumentationMethod:
-  Enabled: false # YARD comments are optional
-
-Style/EmptyClassDefinition:
-  Enabled: false
-
-# Additional cops for code quality
-Lint/UnusedMethodArgument:
-  Enabled: true
-
-Lint/UnusedBlockArgument:
-  Enabled: true
-
-Security/Eval:
-  Enabled: true
-
-Security/JSONLoad:
-  Enabled: true

data/.ruby-version

@@ -1 +0,0 @@
-3.2.2