asherah 0.10.0-x86_64-linux-musl

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ae2e01ccf73a40eae6f7cf5d2f653422569d352cfdfee15795d5603c49c291bd
+  data.tar.gz: 10d62fa707459b137e1c7f78727decbba492ef61563a5ff4642e9d0ab1340498
+SHA512:
+  metadata.gz: fabdee0a35b921e8ec2847697d5657b188eb7e2be436eeab99fefc34000ccf442b2d6ae24cc1878e792706d9a1903e305c0a83874655747359dc23e10c98c571
+  data.tar.gz: c0f7d451fdbeafce00d5903bccf112ca0b43c541d16c5e34da460df53fbe5476e2e0f3d0de1c1e64cf130de496db38843aa7b5eace8ccd909d4eaa39ab7ead1c

data/README.md

@@ -0,0 +1,386 @@
+# asherah
+
+Ruby bindings for [Asherah](https://github.com/godaddy/asherah-ffi) envelope encryption with automatic key rotation.
+
+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
+
+```bash
+gem install asherah
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'asherah'
+```
+
+The gem uses FFI to load the native Asherah library. Platform-specific gems ship the prebuilt library; the source gem builds it during installation.
+
+## Documentation
+
+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
+```
+
+The static API manages a session cache internally. Sessions are created on first use per partition and reused for subsequent calls.
+
+### Block-style configuration
+
+For an API compatible with the canonical GoDaddy Asherah Ruby gem, use `configure` with a block:
+
+```ruby
+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
+
+ciphertext = Asherah.encrypt_string("partition-id", "sensitive data")
+plaintext  = Asherah.decrypt_string("partition-id", ciphertext)
+
+Asherah.shutdown
+```
+
+## Session-Based API
+
+For direct control over session lifecycle, use `SessionFactory` and `Session`:
+
+```ruby
+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
+```
+
+Or via the static API's internal factory (the typical pattern):
+
+```ruby
+Asherah.setup("ServiceName" => "my-service", "ProductID" => "my-product",
+              "Metastore" => "memory", "KMS" => "static") # testing only
+
+# The static API acquires and caches sessions automatically
+ct = Asherah.encrypt("partition-id", "data")
+pt = Asherah.decrypt("partition-id", ct)
+
+Asherah.shutdown
+```
+
+## Async API
+
+### Session-level async (true async via Rust tokio)
+
+The session's async methods dispatch work to Rust's tokio runtime and receive results via FFI callbacks:
+
+```ruby
+session = factory.get_session("partition-id")
+
+ct = session.encrypt_bytes_async(data)
+pt = session.decrypt_bytes_async(ct)
+
+session.close
+```
+
+### 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
+```
+
+### 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.
+
+```ruby
+require "logger"
+log = Logger.new($stdout)
+log.level = Logger::WARN
+Asherah.set_log_hook(log)
+
+# ...later
+Asherah.clear_log_hook
+```
+
+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
+```
+
+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
+```
+
+| 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 |
+
+The same threading caveats apply as for the log hook — implementations must
+be thread-safe and non-blocking, and exceptions are caught.
+
+## License
+
+Licensed under the Apache License, Version 2.0.

data/lib/asherah/config.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Asherah
+  # 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,
+      product_id: :ProductID,
+      kms: :KMS,
+      metastore: :Metastore,
+      connection_string: :ConnectionString,
+      replica_read_consistency: :ReplicaReadConsistency,
+      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,
+      # 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", "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!
+      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(", ")}"
+      end
+      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(", ")}"
+      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 to_json(*args)
+      JSON.generate(to_h, *args)
+    end
+
+    # 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

data/lib/asherah/error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Asherah
+  # Base error class. Also serves as a namespace for specific error types
+  # compatible with the canonical godaddy/asherah-ruby gem.
+  class Error < StandardError
+    ConfigError = Class.new(self)
+    NotInitialized = Class.new(self)
+    AlreadyInitialized = Class.new(self)
+    GetSessionFailed = Class.new(self)
+    EncryptFailed = Class.new(self)
+    DecryptFailed = Class.new(self)
+    BadConfig = Class.new(self)
+    Timeout = Class.new(self)
+  end
+end