asherah 0.9.1-aarch64-linux → 0.10.1-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a15d3515d893c8e672cf112ebb220a6ce147510602f31b771d90356d16dfe656
-  data.tar.gz: 5a2ec90e50d2d4a900edc88c5becac82fd4116ab15da11891013b053858a2005
+  metadata.gz: b7c5fccb13d0c1617f5b063ff214e76bdd1f8003d5858baae801ea7e52f663d5
+  data.tar.gz: 1332860879b52ff9c58dbd14515bc5ae361d993306e545ff1ae84dd4d207f5bb
 SHA512:
-  metadata.gz: 621fb0dd726e9f927c3358bd036b7816892aee34182cfed6781296ad9fffab436b893ce65053966870f3403056aca06ebb0018977dc7e0be7aae6ae5976d707f
-  data.tar.gz: 4a24837072a9d0f24aaba4575924672525b9021eb5ef50746239e2ea9d6dd070d4cdb1afd8ab3ce2044fc1e65e530028127af7357eba6e65e14fb4ad9000215f
+  metadata.gz: 2a2941c03f970770ad1218095bd1b7082b749b8bd21a2732e2974abef1be402d4f251f29716dc9eb67bd5ae7a79d67b1adeb86d8d1efe04ca49e00b3de53ead9
+  data.tar.gz: 8e4dee620411e8d5b868f3902b746805e06b245c2f35f10bf8b26bbafdaf1e463bcab999c0e08fe55cdc86af7f897190d19e6a21ae359d0e54d9de8a11e3eb13

data/README.md

@@ -1,106 +1,386 @@
-# Asherah
+# asherah
 
-Asherah is a Ruby FFI wrapper around the Rust version of [Asherah](https://github.com/godaddy/asherah-ffi) application-layer encryption SDK. Asherah provides advanced encryption features and defense in depth against compromise. It uses a technique known as "envelope encryption" and supports cloud-agnostic data storage and key management.
+Ruby bindings for [Asherah](https://github.com/godaddy/asherah-ffi) envelope encryption with automatic key rotation.
 
-Check out the following documentation to get more familiar with the concepts and configuration options:
-
-- [Design and Architecture](https://github.com/godaddy/asherah/blob/master/docs/DesignAndArchitecture.md)
-- [Key Caching](https://github.com/godaddy/asherah/blob/master/docs/KeyCaching.md)
-- [Key Management Service](https://github.com/godaddy/asherah/blob/master/docs/KeyManagementService.md)
-- [Metastore](https://github.com/godaddy/asherah/blob/master/docs/Metastore.md)
-- [System Requirements](https://github.com/godaddy/asherah/blob/master/docs/SystemRequirements.md)
-
-## Supported Platforms
-
-Currently supported platforms are Linux and Darwin operating systems for x64 and arm64 CPU architectures.
+Published to [RubyGems](https://rubygems.org/gems/asherah) with prebuilt native libraries for Linux x64/ARM64 (glibc and musl/Alpine) and macOS x64/ARM64. A fallback source gem is available for other platforms (requires the Rust toolchain to compile).
 
 ## Installation
 
-Add this line to your application's Gemfile:
+```bash
+gem install asherah
+```
+
+Or add to your Gemfile:
 
 ```ruby
 gem 'asherah'
 ```
 
-```bash
-bundle install
-```
+The gem uses FFI to load the native Asherah library. Platform-specific gems ship the prebuilt library; the source gem builds it during installation.
 
-Or install it yourself as:
+## Documentation
 
-```bash
-gem install asherah
+Task-oriented walkthroughs under [`docs/`](./docs/):
+
+| Guide | When to read |
+|---|---|
+| [Getting started](./docs/getting-started.md) | `gem install` through round-trip encrypt/decrypt. |
+| [Framework integration](./docs/framework-integration.md) | Rails, Sidekiq, Sinatra, Rack middleware, AWS Lambda. |
+| [AWS production setup](./docs/aws-production-setup.md) | KMS keys, DynamoDB, IAM policy, region routing. |
+| [Testing](./docs/testing.md) | RSpec/Minitest fixtures, Testcontainers, mocking patterns. |
+| [Troubleshooting](./docs/troubleshooting.md) | Common errors with what to check first. |
+
+## Quick Start
+
+The simplest way to use Asherah is the static module API. Call `setup` once at startup and `shutdown` on exit:
+
+```ruby
+require "asherah"
+
+Asherah.setup(
+  "ServiceName" => "my-service",
+  "ProductID"   => "my-product",
+  "Metastore"   => "memory",   # testing only
+  "KMS"         => "static"    # testing only
+)
+
+ciphertext = Asherah.encrypt_string("partition-id", "sensitive data")
+plaintext  = Asherah.decrypt_string("partition-id", ciphertext)
+
+Asherah.shutdown
 ```
 
-## Usage
+The static API manages a session cache internally. Sessions are created on first use per partition and reused for subsequent calls.
+
+### Block-style configuration
 
-Configure Asherah:
+For an API compatible with the canonical GoDaddy Asherah Ruby gem, use `configure` with a block:
 
 ```ruby
 Asherah.configure do |config|
-  config.kms = 'static'
-  config.metastore = 'memory'
-  config.service_name = 'service'
-  config.product_id = 'product'
+  config.service_name = "my-service"
+  config.product_id   = "my-product"
+  config.kms          = "static"   # testing only
+  config.metastore    = "memory"   # testing only
 end
+
+ciphertext = Asherah.encrypt_string("partition-id", "sensitive data")
+plaintext  = Asherah.decrypt_string("partition-id", ciphertext)
+
+Asherah.shutdown
 ```
 
-See [config.rb](lib/asherah/config.rb) for all available configuration options.
+## Session-Based API
 
-Encrypt some data for a `partition_id`
+For direct control over session lifecycle, use `SessionFactory` and `Session`:
 
 ```ruby
-partition_id = 'user_1'
-data = 'PII data'
-data_row_record_json = Asherah.encrypt(partition_id, data)
-puts data_row_record_json
+require "asherah"
+
+Asherah.configure do |config|
+  config.service_name = "my-service"
+  config.product_id   = "my-product"
+  config.kms          = "static"   # testing only
+  config.metastore    = "memory"   # testing only
+end
+
+factory = Asherah::SessionFactory.new(
+  Asherah::Native.asherah_factory_new_with_config(config_json)
+)
+session = factory.get_session("partition-id")
+
+ciphertext = session.encrypt_bytes("sensitive data")
+plaintext  = session.decrypt_bytes(ciphertext)
+
+session.close
+factory.close
 ```
 
-Decrypt `data_row_record_json`
+Or via the static API's internal factory (the typical pattern):
 
 ```ruby
-decrypted_data = Asherah.decrypt(partition_id, data_row_record_json)
-puts decrypted_data
-```
+Asherah.setup("ServiceName" => "my-service", "ProductID" => "my-product",
+              "Metastore" => "memory", "KMS" => "static") # testing only
 
-## Development
+# The static API acquires and caches sessions automatically
+ct = Asherah.encrypt("partition-id", "data")
+pt = Asherah.decrypt("partition-id", ct)
 
-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.
+Asherah.shutdown
+```
 
-For tests requiring secrets (AWS KMS, database credentials), copy `.env.secrets.example` to `.env.secrets` and fill in the required values. The `.env.secrets` file is already in `.gitignore` to prevent accidental commits.
+## Async API
 
-### Cross-Language Tests
+### Session-level async (true async via Rust tokio)
 
-Cross-language tests verify that data encrypted with the Rust implementation can be decrypted with the Ruby implementation and vice versa.
+The session's async methods dispatch work to Rust's tokio runtime and receive results via FFI callbacks:
 
-**Prerequisites:**
-- MySQL running locally
-- Go 1.24+ installed
+```ruby
+session = factory.get_session("partition-id")
 
-**Running the tests:**
+ct = session.encrypt_bytes_async(data)
+pt = session.decrypt_bytes_async(ct)
 
-```bash
-TEST_DB_PASSWORD=pass bin/cross-language-test.sh
+session.close
 ```
 
-See `bin/cross-language-test.sh` for available environment variables and their defaults.
+### Static-level async (thread-based)
+
+The static API's async methods run in a Ruby `Thread`:
+
+```ruby
+thread = Asherah.encrypt_async("partition-id", data) do |result|
+  puts "Encrypted: #{result.bytesize} bytes"
+end
+thread.join
+```
 
-To install this gem onto your local machine, run `rake install`.
+### Async Behavior
+
+The session-level async methods (`encrypt_bytes_async`, `decrypt_bytes_async`) are true async. The encrypt/decrypt work runs on Rust's tokio worker threads and completes via an FFI callback. The Ruby interpreter is NOT blocked during the native call.
+
+However, the implementation uses `Queue#pop` to synchronize the callback result back to the calling Ruby thread. This means `queue.pop` blocks the calling Ruby thread until the result arrives. True concurrency requires multiple Ruby threads or Ractors dispatching async calls in parallel.
+
+If the FFI callback never fires (e.g. the worker pool deadlocks), the
+async call raises `Asherah::Error::Timeout` after 30 seconds rather
+than blocking indefinitely. Override the bound by setting the
+`ASHERAH_RUBY_ASYNC_TIMEOUT` environment variable (in seconds) before
+the gem is loaded.
+
+The static-level async methods (`Asherah.encrypt_async`, `Asherah.decrypt_async`) simply run the sync operation in a new `Thread`.
+
+## Input contract
+
+**Partition ID** (`nil`, `""`): always rejected as programming errors
+with `ArgumentError` (`"partition_id cannot be empty"`). No row is ever
+written to the metastore under a degenerate partition ID.
+
+**Plaintext** to encrypt:
+- `nil` → `ArgumentError` from explicit guards in the public API before
+  any FFI call.
+- Empty `String` (`""`) and empty bytes (`"".b`) are **valid**
+  plaintexts. `Asherah.encrypt_string` / `session.encrypt_bytes`
+  produce a real `DataRowRecord` envelope; the matching decrypt returns
+  exactly `""` or empty bytes.
+
+**Ciphertext** to decrypt:
+- `nil` → `ArgumentError`.
+- Empty `String` → `Asherah::Error::DecryptFailed` (not valid
+  `DataRowRecord` JSON).
+
+**Do not short-circuit empty plaintext encryption in caller code** —
+empty data is real data, encrypting it produces a genuine envelope, and
+skipping encryption leaks the fact that the value was empty. See
+[docs/input-contract.md](../docs/input-contract.md) for the full
+rationale.
+
+## Migration from Canonical Ruby SDK
+
+This replaces the original `asherah` gem which was built on Go via Cobhan FFI. The API is drop-in compatible:
+
+| | Canonical (Go/Cobhan) | This binding (Rust/FFI) |
+|---|---|---|
+| Implementation | Go + Cobhan FFI | Rust + Ruby FFI gem |
+| `Asherah.configure` | Supported | Supported (same API) |
+| `Asherah.encrypt` / `decrypt` | Supported | Supported (same API) |
+| `SessionFactory` | Supported | Supported (same API) |
+| Memory protection | None | memguard (locked, wiped pages) |
+| Async support | None | Session-level true async |
+
+Migration steps:
+1. Update the `asherah` gem version in your Gemfile
+2. No code changes required -- the API is compatible
+3. Both read the same metastore tables -- no data migration required
+
+## Performance
+
+Benchmarked on Apple M4 Max, 64-byte payload, hot session cache:
+
+| Operation | Latency |
+|---|---|
+| Encrypt | ~1,170 ns |
+| Decrypt | ~1,110 ns |
+
+## Configuration
+
+### `setup` (hash style)
+
+Keys are PascalCase strings matching the Asherah configuration format:
+
+| Key | Type | Required | Description |
+|---|---|---|---|
+| `ServiceName` | `String` | Yes | Service identifier for key hierarchy |
+| `ProductID` | `String` | Yes | Product identifier for key hierarchy |
+| `Metastore` | `String` | Yes | `"rdbms"`, `"dynamodb"`, `"memory"` (testing) |
+| `KMS` | `String` | Yes | `"static"` or `"aws"` |
+| `ConnectionString` | `String` | No | RDBMS connection string |
+| `DynamoDBEndpoint` | `String` | No | Custom DynamoDB endpoint |
+| `DynamoDBRegion` | `String` | No | DynamoDB region — drives endpoint URL resolution and (when `DynamoDBSigningRegion` is unset) SigV4 signing |
+| `DynamoDBSigningRegion` | `String` | No | SigV4 signing region. When set distinct from `DynamoDBRegion`, the URL is built from `DynamoDBRegion` but SigV4 signs as `DynamoDBSigningRegion` |
+| `DynamoDBTableName` | `String` | No | DynamoDB table name |
+| `RegionMap` | `Hash` | No | AWS KMS region-to-ARN map |
+| `PreferredRegion` | `String` | No | Preferred AWS KMS region |
+| `AwsProfileName` | `String` | No | AWS shared-credentials profile for KMS, DynamoDB, and Secrets Manager clients (native Rust SDK) |
+| `EnableRegionSuffix` | `Boolean` | No | Append region suffix to key IDs |
+| `EnableSessionCaching` | `Boolean` | No | Enable session caching (default: true) |
+| `SessionCacheMaxSize` | `Integer` | No | Max cached sessions |
+| `SessionCacheDuration` | `Integer` | No | Cache TTL in milliseconds |
+| `ExpireAfter` | `Integer` | No | Key expiration in seconds |
+| `CheckInterval` | `Integer` | No | Key check interval in seconds |
+| `Verbose` | `Boolean` | No | Enable verbose logging (default: false) |
+| `PoolMaxOpen` | `Integer` | No | Max open DB connections (default: 0 = unlimited) |
+| `PoolMaxIdle` | `Integer` | No | Max idle connections to retain (default: 2) |
+| `PoolMaxLifetime` | `Integer` | No | Max connection lifetime in seconds (default: 0 = unlimited) |
+| `PoolMaxIdleTime` | `Integer` | No | Max idle time per connection in seconds (default: 0 = unlimited) |
+
+For AWS KMS, DynamoDB, or Secrets Manager, when `AwsProfileName` is omitted the native Rust credential chain applies (including `AWS_PROFILE` and shared config under `~/.aws/`). Setting `AwsProfileName` / `aws_profile_name` selects a named profile explicitly.
+
+### `configure` (block style)
+
+Uses snake_case attribute accessors:
+
+| Attribute | Maps to |
+|---|---|
+| `service_name` | `ServiceName` |
+| `product_id` | `ProductID` |
+| `metastore` | `Metastore` |
+| `kms` | `KMS` |
+| `connection_string` | `ConnectionString` |
+| `dynamo_db_endpoint` | `DynamoDBEndpoint` |
+| `dynamo_db_region` | `DynamoDBRegion` |
+| `dynamo_db_signing_region` | `DynamoDBSigningRegion` |
+| `dynamo_db_table_name` | `DynamoDBTableName` |
+| `region_map` | `RegionMap` |
+| `preferred_region` | `PreferredRegion` |
+| `aws_profile_name` | `AwsProfileName` |
+| `enable_region_suffix` | `EnableRegionSuffix` |
+| `enable_session_caching` | `EnableSessionCaching` |
+| `session_cache_max_size` | `SessionCacheMaxSize` |
+| `session_cache_duration` | `SessionCacheDuration` |
+| `expire_after` | `ExpireAfter` |
+| `check_interval` | `CheckInterval` |
+| `verbose` | `Verbose` |
+| `pool_max_open` | `PoolMaxOpen` |
+| `pool_max_idle` | `PoolMaxIdle` |
+| `pool_max_lifetime` | `PoolMaxLifetime` |
+| `pool_max_idle_time` | `PoolMaxIdleTime` |
+
+## API Reference
+
+### `Asherah` (module-level static API)
+
+| Method | Description |
+|---|---|
+| `setup(config_hash)` | Initialize with PascalCase config hash |
+| `configure { \|c\| ... }` | Initialize with block-style snake_case config |
+| `setup_async(config_hash, &block)` | Async `setup` in a Thread |
+| `shutdown` | Release all resources and cached sessions |
+| `shutdown_async(&block)` | Async `shutdown` in a Thread |
+| `get_setup_status` | Returns `true` if initialized |
+| `encrypt(partition, data)` | Encrypt bytes, returns DRR JSON bytes |
+| `encrypt_string(partition, text)` | Encrypt string, returns DRR JSON string |
+| `encrypt_async(partition, data, &block)` | Encrypt in a Thread |
+| `decrypt(partition, drr)` | Decrypt DRR JSON bytes to plaintext |
+| `decrypt_string(partition, drr)` | Decrypt DRR JSON string to plaintext string |
+| `decrypt_async(partition, drr, &block)` | Decrypt in a Thread |
+| `setenv(hash)` / `set_env(hash)` | Set environment variables |
+
+### `Asherah::SessionFactory`
+
+| Method | Description |
+|---|---|
+| `get_session(partition_id)` | Create a session for a partition |
+| `close` | Release the factory |
+| `closed?` | Returns `true` if closed |
+
+### `Asherah::Session`
+
+| Method | Description |
+|---|---|
+| `encrypt_bytes(data)` | Encrypt bytes, returns DRR JSON bytes |
+| `decrypt_bytes(json)` | Decrypt DRR JSON bytes to plaintext bytes |
+| `encrypt_bytes_async(data)` | True async encrypt via Rust tokio |
+| `decrypt_bytes_async(json)` | True async decrypt via Rust tokio |
+| `close` | Release the session |
+| `closed?` | Returns `true` if closed |
+
+## Observability hooks
+
+### Log hook
+
+Asherah ships first-class stdlib `Logger` integration. The simplest way to
+wire up logging is to hand it any Logger-compatible instance — stdlib
+`Logger`, `ActiveSupport::Logger`, `SemanticLogger`, `Ougai`, etc. — and the
+bridge dispatches each record via `Logger#add(severity, message, target)`
+so the logger's own filter rules and formatters apply.
 
-To release a new version, update the version number in `version.rb`, create and push a version tag:
+```ruby
+require "logger"
+log = Logger.new($stdout)
+log.level = Logger::WARN
+Asherah.set_log_hook(log)
 
+# ...later
+Asherah.clear_log_hook
 ```
-git tag -a v$(rake version) -m "Version $(rake version)"
-git push origin v$(rake version)
+
+For raw access pass a block; the event is a `Hash` with both a
+`Logger::Severity` integer and a matching lowercase symbol:
+
+```ruby
+Asherah.set_log_hook do |event|
+  # event[:severity] => Logger::DEBUG | INFO | WARN | ERROR
+  # event[:level]    => :debug | :info | :warn | :error  (symbol, for case dispatch)
+  # event[:target]   => "asherah::session"
+  # event[:message]  => "..."
+  next if event[:severity] < Logger::WARN
+  warn "[asherah #{event[:level]}] #{event[:target]}: #{event[:message]}"
+end
 ```
 
-And then create a release in Github with title `echo "Version $(rake version)"` that will trigger `.github/workflows/publish.yml` workflow and push the `.gem` file to [rubygems.org](https://rubygems.org):
+The Rust `log` crate has a TRACE level that stdlib `Logger` does not; Asherah
+maps `trace` records to `Logger::DEBUG` so the value is still meaningful.
+The block may fire from any thread (Rust tokio worker threads, DB driver
+threads), so implementations must be thread-safe and should not block.
+Exceptions raised from the callback are caught and silently swallowed —
+propagating an exception across the FFI boundary is undefined behavior.
 
+### Metrics hook
+
+Receive timing observations (`:encrypt`, `:decrypt`, `:store`, `:load`) and
+cache events (`:cache_hit`, `:cache_miss`, `:cache_stale`) via
+`Asherah.set_metrics_hook`. Installing a hook implicitly enables the global
+metrics gate; clearing it disables the gate.
+
+```ruby
+Asherah.set_metrics_hook do |event|
+  case event[:type]
+  when :encrypt, :decrypt, :store, :load
+    # event[:duration_ns] is the elapsed time in nanoseconds, event[:name] is nil
+    Statsd.timing("asherah.#{event[:type]}", event[:duration_ns] / 1_000_000.0)
+  when :cache_hit, :cache_miss, :cache_stale
+    # event[:name] is the cache identifier, event[:duration_ns] is 0
+    Statsd.increment("asherah.#{event[:type]}.#{event[:name]}")
+  end
+end
+
+# ...later
+Asherah.clear_metrics_hook
+```
 
-## Contributing
+| Event type | `:duration_ns` | `:name` |
+|---|---|---|
+| `:encrypt` | elapsed ns | `nil` |
+| `:decrypt` | elapsed ns | `nil` |
+| `:store` | elapsed ns | `nil` |
+| `:load` | elapsed ns | `nil` |
+| `:cache_hit` | `0` | cache identifier |
+| `:cache_miss` | `0` | cache identifier |
+| `:cache_stale` | `0` | cache identifier |
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/godaddy/asherah-ruby.
+The same threading caveats apply as for the log hook — implementations must
+be thread-safe and non-blocking, and exceptions are caught.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](LICENSE.txt).
+Licensed under the Apache License, Version 2.0.

data/lib/asherah/config.rb

@@ -1,28 +1,19 @@
 # frozen_string_literal: true
 
-require 'json'
+require "json"
 
 module Asherah
-  # @attr [String] service_name, The name of this service
-  # @attr [String] product_id, The name of the product that owns this service
-  # @attr [String] kms, The master key management service (static or aws)
-  # @attr [String] metastore, The type of metastore for persisting keys (rdbms, dynamodb, memory)
-  # @attr [String] connection_string, The database connection string (required when metastore is rdbms)
-  # @attr [String] replica_read_consistency, For Aurora sessions using write forwarding (eventual, global, session)
-  # @attr [String] sql_metastore_db_type, Which SQL driver to use (mysql, postgres, oracle), defaults to mysql
-  # @attr [String] dynamo_db_endpoint, An optional endpoint URL (for dynamodb metastore)
-  # @attr [String] dynamo_db_region, The AWS region for DynamoDB requests (for dynamodb metastore)
-  # @attr [String] dynamo_db_table_name, The table name for DynamoDB (for dynamodb metastore)
-  # @attr [Boolean] enable_region_suffix, Configure the metastore to use regional suffixes (for dynamodb metastore)
-  # @attr [String] region_map, List of key-value pairs in the form of REGION1=ARN1[,REGION2=ARN2] (required for aws kms)
-  # @attr [String] preferred_region, The preferred AWS region (required for aws kms)
-  # @attr [Integer] session_cache_max_size, The maximum number of sessions to cache
-  # @attr [Integer] session_cache_duration, The amount of time in seconds a session will remain cached
-  # @attr [Integer] expire_after, The amount of time in seconds a key is considered valid
-  # @attr [Integer] check_interval, The amount of time in seconds before cached keys are considered stale
-  # @attr [Boolean] enable_session_caching, Enable shared session caching
-  # @attr [Boolean] disable_zero_copy, Disable zero-copy FFI input buffers to prevent use-after-free from caller runtime
-  # @attr [Boolean] verbose, Enable verbose logging output
+  # Configuration class compatible with the canonical godaddy/asherah-ruby gem.
+  # Provides snake_case attr_accessors that map to PascalCase config keys
+  # expected by the Rust FFI layer.
+  #
+  # Usage:
+  #   Asherah.configure do |config|
+  #     config.service_name = "MyService"
+  #     config.product_id = "MyProduct"
+  #     config.kms = "static"
+  #     config.metastore = "memory"
+  #   end
   class Config
     MAPPING = {
       service_name: :ServiceName,
@@ -34,83 +25,82 @@ module Asherah
       sql_metastore_db_type: :SQLMetastoreDBType,
       dynamo_db_endpoint: :DynamoDBEndpoint,
       dynamo_db_region: :DynamoDBRegion,
+      dynamo_db_signing_region: :DynamoDBSigningRegion,
       dynamo_db_table_name: :DynamoDBTableName,
       enable_region_suffix: :EnableRegionSuffix,
       region_map: :RegionMap,
       preferred_region: :PreferredRegion,
+      aws_profile_name: :AwsProfileName,
       session_cache_max_size: :SessionCacheMaxSize,
       session_cache_duration: :SessionCacheDuration,
       enable_session_caching: :EnableSessionCaching,
       disable_zero_copy: :DisableZeroCopy,
       expire_after: :ExpireAfter,
       check_interval: :CheckInterval,
-      verbose: :Verbose
+      verbose: :Verbose,
+      # Connection pool
+      pool_max_open: :PoolMaxOpen,
+      pool_max_idle: :PoolMaxIdle,
+      pool_max_lifetime: :PoolMaxLifetime,
+      pool_max_idle_time: :PoolMaxIdleTime,
+      # KMS: AWS
+      kms_key_id: :KmsKeyId,
+      # KMS: AWS Secrets Manager
+      secrets_manager_secret_id: :SecretsManagerSecretId,
+      # KMS: HashiCorp Vault Transit
+      vault_addr: :VaultAddr,
+      vault_token: :VaultToken,
+      vault_auth_method: :VaultAuthMethod,
+      vault_auth_role: :VaultAuthRole,
+      vault_auth_mount: :VaultAuthMount,
+      vault_approle_role_id: :VaultApproleRoleId,
+      vault_approle_secret_id: :VaultApproleSecretId,
+      vault_client_cert: :VaultClientCert,
+      vault_client_key: :VaultClientKey,
+      vault_k8s_token_path: :VaultK8sTokenPath,
+      vault_transit_key: :VaultTransitKey,
+      vault_transit_mount: :VaultTransitMount,
     }.freeze
 
-    KMS_TYPES = ['static', 'aws', 'test-debug-static'].freeze
-    METASTORE_TYPES = ['rdbms', 'dynamodb', 'memory', 'test-debug-memory'].freeze
-    SQL_METASTORE_DB_TYPES = ['mysql', 'postgres', 'oracle'].freeze
+    KMS_TYPES = ["static", "aws", "vault", "vault-transit", "secrets-manager", "test-debug-static"].freeze
+    METASTORE_TYPES = ["rdbms", "dynamodb", "memory", "test-debug-memory"].freeze
+    SQL_METASTORE_DB_TYPES = ["mysql", "postgres", "oracle"].freeze
 
     attr_accessor(*MAPPING.keys)
 
     def validate!
-      validate_service_name
-      validate_product_id
-      validate_kms
-      validate_metastore
-      validate_sql_metastore_db_type
-      validate_kms_attributes
-    end
-
-    def to_json(*args)
-      config = {}.tap do |c|
-        MAPPING.each_pair do |our_key, their_key|
-          value = public_send(our_key)
-          c[their_key] = value unless value.nil?
-        end
-      end
-
-      JSON.generate(config, *args)
-    end
-
-    private
-
-    def validate_service_name
-      raise Error::ConfigError, 'config.service_name not set' if service_name.nil?
-    end
-
-    def validate_product_id
-      raise Error::ConfigError, 'config.product_id not set' if product_id.nil?
-    end
-
-    def validate_kms
-      raise Error::ConfigError, 'config.kms not set' if kms.nil?
+      raise Error::ConfigError, "config.service_name not set" if service_name.nil?
+      raise Error::ConfigError, "config.product_id not set" if product_id.nil?
+      raise Error::ConfigError, "config.kms not set" if kms.nil?
       unless KMS_TYPES.include?(kms)
-        raise Error::ConfigError, "config.kms must be one of these: #{KMS_TYPES.join(', ')}"
+        raise Error::ConfigError, "config.kms must be one of these: #{KMS_TYPES.join(", ")}"
       end
-    end
-
-    def validate_metastore
-      raise Error::ConfigError, 'config.metastore not set' if metastore.nil?
+      raise Error::ConfigError, "config.metastore not set" if metastore.nil?
       unless METASTORE_TYPES.include?(metastore)
-        raise Error::ConfigError, "config.metastore must be one of these: #{METASTORE_TYPES.join(', ')}"
+        raise Error::ConfigError, "config.metastore must be one of these: #{METASTORE_TYPES.join(", ")}"
+      end
+      if sql_metastore_db_type && !SQL_METASTORE_DB_TYPES.include?(sql_metastore_db_type)
+        raise Error::ConfigError, "config.sql_metastore_db_type must be one of these: #{SQL_METASTORE_DB_TYPES.join(", ")}"
+      end
+      if kms == "aws"
+        raise Error::ConfigError, "config.region_map not set" if region_map.nil?
+        raise Error::ConfigError, "config.region_map must be a Hash" unless region_map.is_a?(Hash)
+        raise Error::ConfigError, "config.preferred_region not set" if preferred_region.nil?
       end
     end
 
-    def validate_sql_metastore_db_type
-      return if sql_metastore_db_type.nil?
-
-      unless SQL_METASTORE_DB_TYPES.include?(sql_metastore_db_type)
-        raise Error::ConfigError,
-              "config.sql_metastore_db_type must be one of these: #{SQL_METASTORE_DB_TYPES.join(', ')}"
-      end
+    def to_json(*args)
+      JSON.generate(to_h, *args)
     end
 
-    def validate_kms_attributes
-      return unless kms == 'aws'
-      raise Error::ConfigError, 'config.region_map not set' if region_map.nil?
-      raise Error::ConfigError, 'config.region_map must be a Hash' unless region_map.is_a?(Hash)
-      raise Error::ConfigError, 'config.preferred_region not set' if preferred_region.nil?
+    # Convert to the PascalCase Hash expected by Asherah.setup
+    def to_h
+      hash = {}
+      MAPPING.each_pair do |attr, key|
+        value = public_send(attr)
+        hash[key] = value unless value.nil?
+      end
+      hash
     end
   end
 end