kinko 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 816a9f7595eccbf358a03ec748a0ee6ba723bc81f7292ae589bd3b1954605285
+  data.tar.gz: ce1314b805ed12a494f84c412e638db9448423fffcab89699aaadc876c2c1080
+SHA512:
+  metadata.gz: c988acbeae16dea88a9c3a9151a5da080ea38f7e596d74d901a290231aca38e5d8c4b06dae22009e59022d7f9de3916a26f9e4a8a1894c2d5ef9acc0306ef4c1
+  data.tar.gz: 191ff65897bacae44081edd2a42c7abe15409ea45912fb0e2021a7343e5608be65a6f7f835607bc38a000751a0bc5c766011845f92354f026b157df70a02d0a6

data/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## v0.1.0
+
+### Added
+
+- Initial scaffolding inspired by the
+  [Crystal avram_encrypted shard](https://codeberg.org/fluck/avram_encrypted).
+- `Kinko::Configuration` with `keys` and `key_version`, accessed via
+  `Kinko.configure`. `Kinko.generate_key` returns a base64-encoded 32-byte key.
+- `Kinko::Cipher` for AES-256-GCM encryption with a `"version:payload"`
+  envelope, JSON round-trip for non-string values (with optional `type:` hook for
+  custom classes via `.from_json`), key-version dispatch, and a `recrypt` helper
+  for bulk rotation.
+- `Kinko::BlindIndex` for HMAC-SHA256 lookup digests over encrypted values,
+  versioned symmetrically with the cipher. Built-in `:none`, `:downcase`,
+  `:strip`, `:downcase_strip`, and `:unicode` normalizers, plus any callable.
+- Sequel adapter (`kinko/adapters/sequel`): plugin adding `kinko_encrypt`,
+  `kinko_blind_index`, and `blind_index_for(column, value)` to models.
+- ROM adapter (`kinko/adapters/rom`): `Kinko::Adapters::ROM::Types.encrypted`
+  and `.blind_index` schema types for read-side decryption, plus module-level
+  `encrypt` / `decrypt` / `blind_index` helpers for use in changesets and
+  repositories.
+- Active Record adapter (`kinko/adapters/active_record`): concern adding
+  `encrypts`, `blind_indexed`, and `blind_index_for(column, value)` to models.
+- `Kinko::Error`, `Kinko::ConfigurationError`, `Kinko::InvalidEnvelope`, and
+  `Kinko::UnknownKeyVersion` exception types.
+- README covering quickstart, framework integration for Sequel, ROM, and Active
+  Record, key rotation, and threat-model notes.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wout <hi@wout.codes>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,340 @@
+# Kinko
+
+[![Version](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fcodeberg.org%2Fapi%2Fv1%2Frepos%2Ffluck%2Fkinko%2Ftags&query=%24%5B0%5D.name&label=version)](https://codeberg.org/fluck/kinko/tags)
+
+Encrypted columns for Ruby with versioned key rotation and optional blind
+indexes for equality lookups. Framework-agnostic core and adapters for Sequel,
+ROM, and Active Record.
+
+> _Kinko_ (金庫) is the Japanese word for "safe" or "vault", the small locked
+> box you keep valuables in.
+
+This is a Ruby companion to the [Crystal avram_encrypted
+shard](https://codeberg.org/fluck/avram_encrypted). It bundels two primitives
+into one gem:
+
+1. **Cipher**. AES-256-GCM envelope encryption keyed by a version prefix, so
+   you can rotate keys without touching old rows. Any value that
+   JSON-serializes survives a round-trip.
+2. **Blind index**. HMAC-SHA256 lookup digests, so encrypted columns remain
+   queryable through a sidecar column, with optional case/whitespace/unicode
+   normalization.
+
+> [!NOTE]
+> The original repository is hosted at
+> [Codeberg](https://codeberg.org/fluck/kinko). The [GitHub
+> repo](https://github.com/flucksite/kinko) is just a mirror.
+
+## How it compares
+
+### kinko
+
+- Frameworks: any Ruby app and adapters for Sequel, ROM, Active Record
+- AES-256-GCM + HMAC-SHA256 blind index
+- Versioned envelope for key rotation
+- JSON round-trip so integers, hashes, and custom objects survive
+
+### [lockbox](https://github.com/ankane/lockbox)
+
+- Frameworks: Active Record, Mongoid
+- AES-GCM + XChaCha20-Poly1305
+- Actively maintained, richer ecosystem
+
+### [Active Record Encryption](https://guides.rubyonrails.org/active_record_encryption.html)
+
+- Frameworks: Active Record only (Rails 7+)
+- AES-256-GCM, deterministic + non-deterministic modes
+- Built into Rails, no extra gem
+
+On Rails, the built-in `encrypts` or `lockbox` will usually be the better fit.
+Kinko exists for stacks where a portable core with adapters across Sequel, ROM,
+and Active Record matters more than deep framework integration.
+
+## When to encrypt vs. blind-index
+
+- **Encrypt** when you need to read the value back later (email addresses on
+  display, API tokens, JSON payloads). Reversible with the key, unreadable
+  without.
+- **Blind-index** when you only need to _verify_ a value (recovery codes,
+  one-time tokens, deduplication keys). One-way HMAC, high enough to survive a
+  stolen DB dump as long as the key stays out of it.
+- **Both** on the same column when you need reversible storage _plus_ equality
+  lookups (encrypted email + `email_blind_index` for the login-by-email query).
+
+## Installation
+
+Add this to your Gemfile:
+
+```ruby
+gem "kinko"
+```
+
+Then `bundle install`.
+
+## Quickstart
+
+Configure your keys once at boot:
+
+```ruby
+# config/initializers/kinko.rb
+Kinko.configure do |c|
+  c.keys = {
+    "v1" => ENV.fetch("KINKO_KEY_V1")
+  }
+  c.key_version = "v1"
+end
+```
+
+Generate a new key with `Kinko.generate_key` (returns a base64-encoded 32-byte
+string).
+
+> [!NOTE]
+> Keys can be anything you like. It could be `"v1"`, `"v2"`, etc. like in the
+> example above, but also something more self-documenting like `"202607"` for
+> example.
+
+### Encrypt and decrypt directly
+
+```ruby
+envelope = Kinko::Cipher.encrypt("I’m not a diva. I’m a queen!")
+# => "v1:AAECAwQFBgcICQoLDA..."
+
+Kinko::Cipher.decrypt(envelope)
+# => "swordfish"
+```
+
+Non-string values round-trip through JSON:
+
+```ruby
+Kinko::Cipher.encrypt(42)                        # ⇒ envelope
+Kinko::Cipher.decrypt(envelope)                  # ⇒ 42
+
+Kinko::Cipher.encrypt({name: "moi", age: 36})    # ⇒ envelope
+Kinko::Cipher.decrypt(envelope)                  # ⇒ {"name" => "moi", "age" => 36}
+```
+
+For custom classes, pass a `type:` that responds to `.from_json`:
+
+```ruby
+class ContactCard
+  attr_reader :name, :email
+
+  def initialize(name:, email:) = (@name, @email = name, email)
+
+  def to_json(*args) = {name: @name, email: @email}.to_json(*args)
+
+  def self.from_json(json) = new(**JSON.parse(json, symbolize_names: true))
+end
+
+envelope = Kinko::Cipher.encrypt(ContactCard.new(name: "Moi", email: "m@o.i"))
+card     = Kinko::Cipher.decrypt(envelope, type: ContactCard)
+# => #<ContactCard @name="Moi", @email="m@o.i">
+```
+
+### Blind-index a value for lookups
+
+```ruby
+digest = Kinko::BlindIndex.compute("attitude")
+# => "v1:9f4bcafdb1..."
+
+Kinko::BlindIndex.match?("attitude", digest) # => true
+Kinko::BlindIndex.match?("grace", digest) # => false
+```
+
+Normalize the input for forgiving lookups:
+
+```ruby
+Kinko::BlindIndex.compute("  MP@moi.com  ", normalize: :downcase_strip)
+# ⇒ same digest as "mp@moi.com"
+```
+
+Built-in normalizers: `:none` (default), `:downcase`, `:strip`,
+`:downcase_strip`, `:unicode` (NFC). Or pass any callable:
+
+```ruby
+Kinko::BlindIndex.compute(phone, normalize: ->(v) { v.to_s.tr("^0-9", "") })
+```
+
+Store the digest in a plain column and query by it directly.
+
+## Framework integration
+
+### Sequel
+
+```ruby
+require "kinko/adapters/sequel"
+
+class User < Sequel::Model
+  plugin :kinko
+
+  kinko_encrypt :email_ciphertext,
+                index: :email_blind_index,
+                normalize: :downcase_strip
+  kinko_blind_index :recovery_code, normalize: :downcase
+end
+
+# Insert transparently:
+User.create(email_ciphertext: "hi@moi.com", recovery_code: "abcdef2345")
+
+# Lookup by the blind index:
+User.first(email_blind_index: User.blind_index_for(:email_blind_index, "HI@moi.com"))
+```
+
+`kinko_encrypt` encrypts writes to the column and decrypts reads. When `index:`
+is given, the same value is HMAC'd into the sidecar column for equality
+lookups.
+
+`kinko_blind_index` skips encryption entirely and stores only the digest,
+which is what you want for values you only need to verify (recovery codes,
+one-time tokens).
+
+Both accept `normalize:` (any of the built-in strategies or a callable).
+`kinko_encrypt` also accepts `type:` for custom class deserialization on read.
+
+### ROM
+
+Reads via a dry-types constructor:
+
+```ruby
+require "kinko/adapters/rom"
+
+class Users < ROM::Relation[:sql]
+  schema(:users, infer: true) do
+    attribute :secret_ciphertext, Kinko::Adapters::ROM::Types.encrypted
+    attribute :email_blind_index, Kinko::Adapters::ROM::Types.blind_index
+  end
+end
+```
+
+Writes go through a changeset, since ROM's write path is intentionally
+decoupled from the schema:
+
+```ruby
+class UserChangeset < ROM::Changeset::Create
+  map do |tuple|
+    tuple.merge(
+      secret_ciphertext: Kinko::Cipher.encrypt(tuple[:secret]),
+      email_blind_index: Kinko::BlindIndex.compute(tuple[:email], normalize: :downcase_strip)
+    )
+  end
+end
+```
+
+Or directly from a repository:
+
+```ruby
+class UserRepo < ROM::Repository[:users]
+  def by_email(email)
+    digest = Kinko::BlindIndex.compute(email, normalize: :downcase_strip)
+    users.where(email_blind_index: digest).one
+  end
+end
+```
+
+### Active Record
+
+```ruby
+require "kinko/adapters/active_record"
+
+class User < ApplicationRecord
+  include Kinko::Adapters::ActiveRecord
+
+  encrypts :secret_ciphertext
+  encrypts :email_ciphertext, index: :email_blind_index, normalize: :downcase_strip
+  blind_indexed :recovery_code, normalize: :downcase
+end
+
+user = User.create!(email_ciphertext: "hi@moi.com")
+User.find_by(email_blind_index: User.blind_index_for(:email_blind_index, "HI@moi.com"))
+```
+
+`encrypts` writes ciphertext + optional blind index mirror. `blind_indexed`
+stores only the digest. Both accept `normalize:`; `encrypts` also accepts
+`type:` for custom classes.
+
+## Column types
+
+Encrypted values are base64-encoded envelopes; a `String` / `text` column
+holds them fine. If you prefer bytes, decode before storing, but base64 is
+the default so migrations don't need to think about binary.
+
+Blind indexes are `"vN:"` (or any other key name format you chose) plus 64 hex
+characters (~68 characters). Any `String` column with an index on it works:
+
+```ruby
+# Sequel migration
+alter_table :users do
+  add_column :email_ciphertext,  String
+  add_column :email_blind_index, String
+  add_index  :email_blind_index, unique: true
+end
+```
+
+```ruby
+# Rails migration
+add_column :users, :email_ciphertext,  :string
+add_column :users, :email_blind_index, :string
+add_index  :users, :email_blind_index, unique: true
+```
+
+## Key rotation
+
+Add the new key alongside the old one, flip `key_version`, and existing rows
+keep decrypting from their original key while new writes use the new one:
+
+```ruby
+Kinko.configure do |c|
+  c.keys = {
+    "v1" => ENV.fetch("KINKO_KEY_V1"),
+    "v2" => ENV.fetch("KINKO_KEY_V2")
+  }
+  c.key_version = "v2"
+end
+```
+
+Rewrap old ciphertexts in bulk when you have time:
+
+```ruby
+User.where(Sequel.like(:email_ciphertext, "v1:%")).each do |user|
+  user.update(email_ciphertext: Kinko::Cipher.recrypt(user[:email_ciphertext]))
+end
+```
+
+Blind indexes are deterministic per key, so their equivalent rotation is to
+recompute from the plaintext (which you have during writes). Old digests
+keep matching until the row is next written.
+
+## Threat model
+
+Kinko protects against **database-only compromise**: an attacker with a copy of
+your rows can't read encrypted values or brute-force blind indexes without the
+encryption key.
+
+Kinko does **not** protect against:
+
+- Compromise of the application host, where the key is loaded into memory.
+- Application-layer bugs (SQL injection, template injection) that let an
+  attacker call `Kinko::Cipher.decrypt` on your behalf.
+
+Store your keys somewhere the database can't reach. Rotate them if you suspect
+either the DB or the app host was accessed.
+
+For anything more elaborate (per-tenant keys, envelope encryption backed by a
+KMS, deterministic ciphers) you probably want
+[lockbox](https://github.com/ankane/lockbox) or a purpose-built solution.
+
+## Contributing
+
+We use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/)
+for our commit messages, so please adhere to that pattern.
+
+1. Fork it (<https://codeberg.org/fluck/kinko/fork>)
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'feat: new feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](LICENSE).

data/lib/kinko/adapters/active_record.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "kinko"
+
+module Kinko
+  module Adapters
+    module ActiveRecord
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :kinko_index_normalizers, instance_writer: false, default: {}
+      end
+
+      class_methods do
+        def encrypts(column, type: nil, index: nil, normalize: :none)
+          self.kinko_index_normalizers = kinko_index_normalizers.merge(index => normalize) if index
+
+          define_method(column) do
+            raw = self[column]
+            raw.nil? ? nil : Kinko::Cipher.decrypt(raw, type: type)
+          end
+
+          define_method("#{column}=") do |value|
+            if value.nil?
+              self[column] = nil
+              self[index] = nil if index
+            else
+              self[column] = Kinko::Cipher.encrypt(value)
+              self[index] = Kinko::BlindIndex.compute(value, normalize:) if index
+            end
+          end
+        end
+
+        def blind_indexed(column, normalize: :none)
+          self.kinko_index_normalizers = kinko_index_normalizers.merge(column => normalize)
+
+          define_method("#{column}=") do |value|
+            if value.nil?
+              self[column] = nil
+            else
+              self[column] = Kinko::BlindIndex.compute(value, normalize:)
+            end
+          end
+        end
+
+        def blind_index_for(column, value)
+          normalize = kinko_index_normalizers.fetch(column) do
+            raise ArgumentError, "no blind index registered for #{column.inspect}"
+          end
+          Kinko::BlindIndex.compute(value, normalize:)
+        end
+      end
+    end
+  end
+end

data/lib/kinko/adapters/rom.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "dry/types"
+require "kinko"
+
+module Kinko
+  module Adapters
+    module ROM
+      module Types
+        module_function
+
+        def encrypted(type: nil, inner: nil)
+          inner ||= type ? Dry::Types["any"].optional : Dry::Types["string"].optional
+          inner.constructor do |value|
+            value.nil? ? nil : Kinko::Cipher.decrypt(value, type:)
+          end
+        end
+
+        def blind_index(inner: Dry::Types["string"].optional) = inner
+      end
+
+      module_function
+
+      def encrypt(value, **opts)
+        Kinko::Cipher.encrypt(value, **opts)
+      end
+
+      def decrypt(envelope, **opts)
+        Kinko::Cipher.decrypt(envelope, **opts)
+      end
+
+      def blind_index(value, **opts)
+        Kinko::BlindIndex.compute(value, **opts)
+      end
+    end
+  end
+end

data/lib/kinko/adapters/sequel.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "sequel"
+require "sequel/plugins/kinko"

data/lib/kinko/blind_index.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "base64"
+require "openssl"
+
+module Kinko
+  # HMAC-SHA256 lookup digest for encrypted columns.
+  module BlindIndex
+    extend self
+
+    DIGEST = "SHA256"
+    SEPARATOR = ":"
+
+    NORMALIZERS = {
+      none: ->(v) { v.to_s },
+      downcase: ->(v) { v.to_s.downcase },
+      strip: ->(v) { v.to_s.strip },
+      downcase_strip: ->(v) { v.to_s.downcase.strip },
+      unicode: ->(v) { v.to_s.unicode_normalize(:nfc) }
+    }.freeze
+
+    def compute(value, version: Kinko.config.key_version, normalize: :none)
+      Kinko.config.require!
+      key = decode_key(Kinko.config.key_for(version))
+      hex = OpenSSL::HMAC.hexdigest(DIGEST, key, normalize_with(normalize, value))
+      "#{version}#{SEPARATOR}#{hex}"
+    end
+
+    def match?(value, stored, normalize: :none)
+      version, digest = split(stored)
+      return false unless key = Kinko.config.keys[version]
+
+      candidate = OpenSSL::HMAC.hexdigest(
+        DIGEST,
+        decode_key(key),
+        normalize_with(normalize, value)
+      )
+      OpenSSL.fixed_length_secure_compare(digest, candidate)
+    rescue InvalidEnvelope, ArgumentError
+      false
+    end
+
+    def version_of(stored) = split(stored).first
+
+    private
+
+    def split(stored)
+      version, digest = stored.to_s.split(SEPARATOR, 2)
+      raise InvalidEnvelope, stored unless version && digest && !digest.empty?
+
+      [version, digest]
+    end
+
+    def normalize_with(strategy, value)
+      if strategy.respond_to?(:call)
+        strategy
+      else
+        NORMALIZERS.fetch(strategy) do
+          raise ArgumentError,
+            "unknown normalize strategy #{strategy.inspect}; " \
+              "one of #{NORMALIZERS.keys.inspect} or a callable"
+        end
+      end.call(value)
+    end
+
+    def decode_key(key)
+      bytes = key.to_s
+      return bytes if bytes.bytesize == Configuration::KEY_BYTES
+
+      Base64.strict_decode64(bytes).tap do |decoded|
+        next if decoded.bytesize == Configuration::KEY_BYTES
+
+        raise ConfigurationError,
+          "keys must be #{Configuration::KEY_BYTES} bytes (raw or base64)"
+      end
+    end
+  end
+end

data/lib/kinko/cipher.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "openssl"
+
+module Kinko
+  module Cipher
+    extend self
+
+    ALGORITHM = "aes-256-gcm"
+    NONCE_BYTES = 12
+    TAG_BYTES = 16
+    SEPARATOR = ":"
+
+    def encrypt(value, version: Kinko.config.key_version)
+      Kinko.config.require!
+      key = decode_key(Kinko.config.key_for(version))
+      cipher = new_cipher(:encrypt, key)
+      nonce = cipher.random_iv
+      ciphertext = cipher.update(serialize(value)) + cipher.final
+      envelope(version, nonce + ciphertext + cipher.auth_tag)
+    end
+
+    def decrypt(envelope, type: nil)
+      version, payload = split(envelope)
+      key = decode_key(Kinko.config.key_for(version))
+      raw = Base64.strict_decode64(payload)
+      nonce, ciphertext, tag = split_payload(raw)
+      cipher = new_cipher(:decrypt, key)
+      cipher.iv = nonce
+      cipher.auth_tag = tag
+      deserialize(cipher.update(ciphertext) + cipher.final, type)
+    end
+
+    def recrypt(envelope, version: Kinko.config.key_version)
+      current, = split(envelope)
+      return envelope if current == version.to_s
+
+      encrypt(decrypt(envelope), version:)
+    end
+
+    def version_of(envelope) = split(envelope).first
+
+    private
+
+    def new_cipher(mode, key)
+      OpenSSL::Cipher.new(ALGORITHM).public_send(mode).tap { _1.key = key }
+    end
+
+    def envelope(version, bytes)
+      "#{version}#{SEPARATOR}#{Base64.strict_encode64(bytes)}"
+    end
+
+    def split(envelope)
+      version, payload = envelope.to_s.split(SEPARATOR, 2)
+      raise InvalidEnvelope, envelope unless version && payload && !payload.empty?
+
+      [version, payload]
+    end
+
+    def split_payload(raw)
+      raise InvalidEnvelope, raw if raw.bytesize <= NONCE_BYTES + TAG_BYTES
+
+      nonce = raw.byteslice(0, NONCE_BYTES)
+      tag = raw.byteslice(-TAG_BYTES, TAG_BYTES)
+      ciphertext = raw.byteslice(NONCE_BYTES, raw.bytesize - NONCE_BYTES - TAG_BYTES)
+      [nonce, ciphertext, tag]
+    end
+
+    def serialize(value) = JSON.generate(value)
+
+    def deserialize(json, type)
+      return type.from_json(json) if type.respond_to?(:from_json)
+
+      JSON.parse(json)
+    end
+
+    def decode_key(key)
+      bytes = key.to_s
+      return bytes if bytes.bytesize == Configuration::KEY_BYTES
+
+      Base64.strict_decode64(bytes).tap do |decoded|
+        next if decoded.bytesize == Configuration::KEY_BYTES
+
+        raise ConfigurationError,
+          "keys must be #{Configuration::KEY_BYTES} bytes (raw or base64)"
+      end
+    end
+  end
+end

data/lib/kinko/configuration.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Kinko
+  class Configuration
+    KEY_BYTES = 32
+
+    attr_accessor :keys, :key_version
+
+    def initialize
+      @keys = {}
+      @key_version = nil
+    end
+
+    def current_key
+      require!
+      keys.fetch(key_version)
+    end
+
+    def key_for(version)
+      keys[version] || raise(UnknownKeyVersion, version)
+    end
+
+    def require!
+      raise ConfigurationError, "at least one key must be configured" if keys.empty?
+      raise ConfigurationError, "key_version must be set" if key_version.nil?
+      return if keys.key?(key_version)
+
+      raise ConfigurationError,
+        "key_version #{key_version.inspect} is not present in keys"
+    end
+  end
+end

data/lib/kinko/error.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Kinko
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  class InvalidEnvelope < Error
+    def initialize(value)
+      super(
+        "Envelope #{value.inspect} does not match the expected " \
+          "\"version:payload\" format."
+      )
+    end
+  end
+
+  class UnknownKeyVersion < Error
+    def initialize(version)
+      super(
+        "No key configured for version #{version.inspect}. Add it to " \
+          "Kinko.configure so old values remain decryptable."
+      )
+    end
+  end
+end

data/lib/kinko/tasks.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rake"
+require "kinko"
+
+namespace :kinko do
+  desc "Print a fresh base64-encoded 32-byte key"
+  task :generate_key do
+    puts Kinko.generate_key
+  end
+end

data/lib/kinko/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Kinko
+  VERSION = "0.1.0"
+end

data/lib/kinko.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require_relative "kinko/version"
+require_relative "kinko/error"
+require_relative "kinko/configuration"
+require_relative "kinko/cipher"
+require_relative "kinko/blind_index"
+
+module Kinko
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+      config.require!
+      config
+    end
+
+    def reset_config!
+      @config = Configuration.new
+    end
+
+    def generate_key
+      Base64.strict_encode64(SecureRandom.random_bytes(Configuration::KEY_BYTES))
+    end
+  end
+end

data/lib/sequel/plugins/kinko.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "kinko"
+
+module Sequel
+  module Plugins
+    module Kinko
+      def self.apply(model, *)
+        model.instance_variable_set(:@kinko_encrypted_columns, [])
+        model.instance_variable_set(:@kinko_indexed_columns, [])
+        model.instance_variable_set(:@kinko_index_normalizers, {})
+      end
+
+      module ClassMethods
+        attr_reader :kinko_encrypted_columns, :kinko_indexed_columns, :kinko_index_normalizers
+
+        def kinko_encrypt(column, type: nil, index: nil, normalize: :none)
+          @kinko_encrypted_columns << column
+          @kinko_index_normalizers[index] = normalize if index
+
+          define_method(column) do
+            raw = self[column]
+            raw.nil? ? nil : ::Kinko::Cipher.decrypt(raw, type: type)
+          end
+
+          define_method("#{column}=") do |value|
+            if value.nil?
+              self[column] = nil
+              self[index] = nil if index
+            else
+              self[column] = ::Kinko::Cipher.encrypt(value)
+              self[index] = ::Kinko::BlindIndex.compute(value, normalize:) if index
+            end
+          end
+        end
+
+        def kinko_blind_index(column, normalize: :none)
+          @kinko_indexed_columns << column
+          @kinko_index_normalizers[column] = normalize
+
+          define_method("#{column}=") do |value|
+            if value.nil?
+              self[column] = nil
+            else
+              self[column] = ::Kinko::BlindIndex.compute(value, normalize:)
+            end
+          end
+        end
+
+        def blind_index_for(column, value)
+          normalize = @kinko_index_normalizers.fetch(column) do
+            raise ArgumentError, "no blind index registered for #{column.inspect}"
+          end
+          ::Kinko::BlindIndex.compute(value, normalize:)
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: kinko
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Wout
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: openssl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: |
+  Encrypted column values with versioned key rotation and optional blind
+  indexes for equality lookups. Framework-agnostic core (AES-256-GCM
+  envelope + HMAC-SHA256 blind index) with opt-in adapters for Sequel, ROM,
+  and Active Record. Ruby companion to the Crystal avram_encrypted shard.
+email:
+- hi@wout.codes
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/kinko.rb
+- lib/kinko/adapters/active_record.rb
+- lib/kinko/adapters/rom.rb
+- lib/kinko/adapters/sequel.rb
+- lib/kinko/blind_index.rb
+- lib/kinko/cipher.rb
+- lib/kinko/configuration.rb
+- lib/kinko/error.rb
+- lib/kinko/tasks.rb
+- lib/kinko/version.rb
+- lib/sequel/plugins/kinko.rb
+homepage: https://codeberg.org/fluck/kinko
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://codeberg.org/fluck/kinko
+  bug_tracker_uri: https://codeberg.org/fluck/kinko/issues
+  changelog_uri: https://codeberg.org/fluck/kinko/src/branch/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.15
+specification_version: 4
+summary: Storage-agnostic encrypted attributes for Ruby, with thin Sequel, ROM, and
+  Active Record adapters.
+test_files: []