asherah 0.9.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8e2ce61ef519439f64e0b27b4faef3ed6cacbdb7176d5e20df379bf96c5e6df
-  data.tar.gz: 0bcb2c49582f27af5cf0d4202e93a33b353d098d8261a1e636546b95c16dc401
+  metadata.gz: 31eda555f1f9ab86b17f12a4bff59bdcaa08b886c7ccbfba9e5fb341b73d3c1c
+  data.tar.gz: 0e85ad61fc1c9b192cd1d1fe670cfb6dc4feec26b174acc3e83de808fa74255a
 SHA512:
-  metadata.gz: 505671ed110011fc6dffa187f16cb16e41fe8e72afb151c7ca311e802828bff64dffde0df94a16ff6e52aa193b963ee5768091fbcbb09d28c0ac7174e928dcfa
-  data.tar.gz: 188e278c8e03c4621004040283d0b268aec02a6a0ea8e0c9dea6dd60dae94e0ded4ba37fc5b1c83c25981e0edda21fdfd3282476ea95c33c0051998bd2a22548
+  metadata.gz: 52e79b34969c3c5ff56e844d9a471ee4db1db13fa0b729f5b68be0d8a27b016a9513f0e731b6073dca0fd3a8dd6db964441b1b48fc8b4e2084e64c8075777fd6
+  data.tar.gz: cbb446aeffbf134ce576c49646e5c63edcf5b0b64a690e2fab93f0f8f578d592344167fc35427f9ce2a80cb762e1049bfd049e0a90b4a2c5c95e12f6efac78ac

data/NATIVE_VERSION

@@ -0,0 +1 @@
+v0.6.109

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/ext/asherah/asherah.c

@@ -0,0 +1,2 @@
+/* No-op C extension — native library is downloaded by fetch_native.rb */
+void Init_asherah(void) {}

data/ext/asherah/extconf.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
-require 'mkmf'
-create_makefile('asherah/asherah')
+require "mkmf"
 
-require_relative 'native_file'
-NativeFile.download
+# Create a no-op Makefile (we don't compile C; we download a prebuilt binary)
+create_makefile("asherah/asherah")
+
+require_relative "fetch_native"
+AsherahFetchNative.download

data/ext/asherah/fetch_native.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require "open-uri"
+require "fileutils"
+require "digest"
+require "rbconfig"
+
+# Downloads the prebuilt native library for the current platform from
+# GitHub Releases during `gem install` (fallback gem only — platform gems
+# ship the binary directly and never run this).
+module AsherahFetchNative
+  REPO = "godaddy/asherah-ffi"
+  MAX_ATTEMPTS = 3
+  RETRY_DELAY = 5 # seconds, doubles each retry
+  ROOT_DIR = File.expand_path("../../", __dir__)
+  NATIVE_DIR = File.join(ROOT_DIR, "lib", "asherah", "native")
+
+  # Map Ruby platform identifiers to our release asset names.
+  # Keys: [os, cpu] from RbConfig. Values: [asset_name, local_name].
+  PLATFORM_MAP = {
+    ["linux", "x86_64"]        => ["libasherah-x64.so",         "libasherah_ffi.so"],
+    ["linux", "aarch64"]       => ["libasherah-arm64.so",       "libasherah_ffi.so"],
+    ["linux-musl", "x86_64"]   => ["libasherah-x64-musl.so",    "libasherah_ffi.so"],
+    ["linux-musl", "aarch64"]  => ["libasherah-arm64-musl.so",  "libasherah_ffi.so"],
+    ["darwin", "x86_64"]       => ["libasherah-x64.dylib",      "libasherah_ffi.dylib"],
+    ["darwin", "arm64"]        => ["libasherah-arm64.dylib",    "libasherah_ffi.dylib"],
+    ["mingw", "x86_64"]        => ["libasherah-x64.dll",        "asherah_ffi.dll"],
+    ["mingw", "aarch64"]       => ["libasherah-arm64.dll",      "asherah_ffi.dll"],
+  }.freeze
+
+  class << self
+    def download
+      asset_name, local_name = resolve_platform
+      dest = File.join(NATIVE_DIR, local_name)
+
+      if File.exist?(dest)
+        puts "#{dest} already exists, skipping download"
+        return
+      end
+
+      version = resolve_version
+      url = "https://github.com/#{REPO}/releases/download/#{version}/#{asset_name}"
+
+      puts "Downloading native library: #{url}"
+      content = download_with_retry(url)
+
+      if content.bytesize < 1024
+        abort "ERROR: Downloaded file is too small (#{content.bytesize} bytes) — likely a 404 or error page"
+      end
+
+      verify_checksum(content, asset_name, version)
+
+      FileUtils.mkdir_p(NATIVE_DIR)
+      File.binwrite(dest, content)
+      File.chmod(0o755, dest) unless Gem.win_platform?
+      puts "Installed native library: #{dest} (#{content.bytesize} bytes)"
+    end
+
+    private
+
+    def resolve_platform
+      host_os = RbConfig::CONFIG["host_os"]
+      host_cpu = RbConfig::CONFIG["host_cpu"]
+
+      os = case host_os
+           when /linux.*musl/    then "linux-musl"
+           when /linux/          then musl_libc? ? "linux-musl" : "linux"
+           when /darwin/         then "darwin"
+           when /mswin|mingw/    then "mingw"
+           else                       host_os
+           end
+
+      cpu = case host_cpu
+            when /x86_64|x64|amd64/   then "x86_64"
+            when /aarch64|arm64/       then os == "darwin" ? "arm64" : "aarch64"
+            else                            host_cpu
+            end
+
+      key = [os, cpu]
+      result = PLATFORM_MAP[key]
+      abort "ERROR: Unsupported platform #{os}-#{cpu} (#{RUBY_PLATFORM})" unless result
+      result
+    end
+
+    # True when running on musl libc (e.g. Alpine Linux). Modern Ruby on
+    # Alpine reports host_os=linux-musl directly, but older builds may
+    # report just "linux" — fall back to inspecting RUBY_PLATFORM and
+    # the dynamic loader.
+    def musl_libc?
+      return true if RUBY_PLATFORM.include?("musl")
+      return true if File.exist?("/lib/ld-musl-x86_64.so.1") || File.exist?("/lib/ld-musl-aarch64.so.1")
+      false
+    end
+
+    def resolve_version
+      # NATIVE_VERSION is stamped into published fallback gems by the publish
+      # workflow with the release tag (e.g. "v0.6.73"). It is not committed
+      # to the repo — the gem version and the native binary version are
+      # intentionally decoupled.
+      # Environment variable override: NATIVE_VERSION=v0.6.22 bundle install
+      env_version = ENV["NATIVE_VERSION"]
+      if env_version && !env_version.strip.empty?
+        tag = env_version.strip
+        tag = "v#{tag}" unless tag.start_with?("v")
+        puts "Using native version from environment: #{tag}"
+        return tag
+      end
+
+      # Published fallback gems have NATIVE_VERSION stamped by the publish workflow
+      native_version_file = File.join(ROOT_DIR, "NATIVE_VERSION")
+      if File.exist?(native_version_file)
+        tag = File.read(native_version_file).strip
+        unless tag.empty?
+          puts "Using native version: #{tag}"
+          return tag
+        end
+      end
+
+      abort <<~MSG
+        ERROR: Native binary version not specified.
+
+        Set the NATIVE_VERSION environment variable to the release tag:
+          NATIVE_VERSION=0.6.73 bundle install
+
+        Or create a NATIVE_VERSION file in the asherah-ruby directory:
+          echo "v0.6.73" > asherah-ruby/NATIVE_VERSION
+
+        Available releases: https://github.com/#{REPO}/releases
+      MSG
+    end
+
+    def download_with_retry(url)
+      attempt = 0
+      delay = RETRY_DELAY
+
+      loop do
+        attempt += 1
+        begin
+          return URI.parse(url).open(
+            "Accept" => "application/octet-stream",
+            redirect: true,
+            read_timeout: 60,
+            open_timeout: 30
+          ).read
+        rescue OpenURI::HTTPError => e
+          if e.message.include?("404")
+            abort "ERROR: Release asset not found at #{url}\n" \
+                  "       Ensure the release exists and includes this platform's binary."
+          end
+          raise unless attempt < MAX_ATTEMPTS
+
+          puts "Download failed (attempt #{attempt}/#{MAX_ATTEMPTS}): #{e.message}"
+          puts "Retrying in #{delay}s..."
+          sleep delay
+          delay *= 2
+        rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNRESET, Errno::ECONNREFUSED => e
+          raise unless attempt < MAX_ATTEMPTS
+
+          puts "Download failed (attempt #{attempt}/#{MAX_ATTEMPTS}): #{e.class}: #{e.message}"
+          puts "Retrying in #{delay}s..."
+          sleep delay
+          delay *= 2
+        end
+      end
+    end
+
+    def verify_checksum(content, asset_name, version)
+      sums_url = "https://github.com/#{REPO}/releases/download/#{version}/SHA256SUMS"
+      begin
+        sums = URI.parse(sums_url).open(read_timeout: 15, open_timeout: 10).read
+        expected = nil
+        sums.each_line do |line|
+          hash, name = line.strip.split(/\s+/, 2)
+          if name == asset_name
+            expected = hash
+            break
+          end
+        end
+
+        if expected
+          actual = Digest::SHA256.hexdigest(content)
+          if actual != expected
+            abort "ERROR: SHA256 checksum mismatch for #{asset_name}\n" \
+                  "  Expected: #{expected}\n" \
+                  "  Actual:   #{actual}"
+          end
+          puts "SHA256 checksum verified: #{actual}"
+        else
+          puts "WARNING: No checksum found for #{asset_name} in SHA256SUMS"
+        end
+      rescue OpenURI::HTTPError, Net::OpenTimeout, Net::ReadTimeout => e
+        puts "WARNING: Could not verify checksum (#{e.class}: #{e.message})"
+      end
+    end
+  end
+end