# 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). Entries for unreleased work are not written here directly. Each issue drops a fragment in [`changelog.d/`](changelog.d/README.md); the fragments are assembled into a version section at release. See that README for the format and for when a change warrants an entry at all. ## [0.2.0] - 2026-08-28 ### Added - `Encryptor.Ecto.Binary` declares an encrypted `:binary` field: `use` it with a vault, name the module from a schema, and every read and write goes through the vault without a call site changing. - The table and column a field was declared with are bound into every message as encryption context, so bytes lifted out of one column fail authentication in another rather than decrypting into the wrong place. - A dump or load with no tenant resolved raises `MissingTenantError` naming the table and column, instead of falling back to a default tenant and writing a row nobody can recover. - `Encryptor.Ecto.String` declares an encrypted text field: everything `Encryptor.Ecto.Binary` does, with a cast arm that accepts only valid UTF-8, so bytes from a mis-decoded payload become an error on the field instead of a column that decrypts years later into something no reader can render. - `Encryptor.Ecto.Map` declares an encrypted map field, serialized through `:json` - any module exporting `encode!/1` and `decode!/1`, `Jason` by default - and checked at the declaration rather than on the first write. - A loaded map has string keys - guaranteed by the default serializer, and trusted of a host-supplied one - and `%{}` round-trips as `%{}` rather than collapsing into `nil`. - A struct handed to a map field is refused at `cast/2` rather than silently round-tripping into a plain map. - A serializer failure raises `Encryptor.Ecto.SerializationError` naming the serializer and the direction, with the serializer's own exception reduced to its module: `Jason`'s carries the value it could not encode, and this package does not pass that on. - A field declared `tenant: :none` must name a `:single`-profile vault, and pairing one with a `:tenant`-profile vault now raises `Encryptor.Ecto.VaultProfileError` naming the field, the vault and the profile - instead of surfacing on the first write as whatever the vault's key provider happens to refuse first, which names neither. - `Encryptor.Ecto.Binary`'s documentation states at the option itself what `tenant: :none` costs: those ciphertexts are not crypto-shreddable with a tenant key. - `Encryptor.Ecto.Declarations.check_unique!/1` refuses a deploy in which two encrypted fields share one declared table and column - fields that can silently decrypt each other's bytes - and `list/1` reports what a deploy considers encrypted and under what context. - The `:table` and `:column` pins may be written at the field as well as at the `use`, so renaming a physical table or column is a one-line change that leaves every stored row readable. - Encrypted-field failures raise a named exception - `MissingTenantError`, `MissingContextError`, `EncryptError`, `DecryptError` or `SerializationError` - each carrying the declared table, the declared column, the encryption-context key names and the upstream reason, and none of them carrying a plaintext, a ciphertext or key material in its message or its `Inspect` form. - `Encryptor.Ecto.Tenant` holds the current tenant for a unit of work, with `wrap/2` restoring the previous scope so a pooled process cannot leak one. - `Encryptor.Ecto.TenantContext` is the one-callback behaviour a host implements to resolve the tenant its own way; the default `:scope` strategy is an ordinary implementation of it. - `Encryptor.Ecto.TenantScope.scope_tenant/1` scopes an ExUnit case or a single `describe` block to a named tenant, so a host's suite meets fail-closed tenancy without either a default tenant or six lines of setup per case. - `Encryptor.Ecto.Tenant` documents the full list of boundaries a host is expected to wrap, rather than naming a few of them in passing. - `Encryptor.Ecto.BlindIndex.blind_index/3` declares a keyed blind index on an encrypted field, inside the schema beside the column it indexes. The declaration is the one place an index's normalization and key derivation live, so the helper that writes the column and the helper that queries it cannot disagree about either. - `Encryptor.Ecto.BlindIndex.Normalizer` ships the founding set - `:none`, `:trim`, `:downcase`, `:email`, `:digits`, and a host `{module, function}`. The built-ins are total on every binary, including one that is not valid UTF-8; a host normalizer that raises, throws, exits, is not exported, or returns a non-binary produces `NormalizationError` naming the table, the column and the index, and no value. - `Encryptor.Ecto.BlindIndex.Declaration` is the read surface a helper resolves an index through: `list/1`, `fetch!/3`, `derivation!/1` and `normalize!/2`. - Declaring a blind index on a `tenant: :none` field with no `:scope`, or with `scope: :tenant`, is a compile error. `scope: :global` is the only possibility there and it still has to be written, because the reviewer reading that schema line is the person who needs to know the column is cross-tenant correlatable and survives a tenant shred. - Declaring one on a field this package does not encrypt is a compile error, as are an index column that is not a field on the schema, an index column that is itself encrypted, and two declarations sharing an index name or a `{source, column}` pair. - `Encryptor.Ecto.BlindIndex.Derivation` derives a blind index's key through the vault's `derive/3`: the index tree is a salted subkey under the vault's reserved `"encryptor/v1/blind-index"` label, and the table, column, index name and version are the info string inside it, so an index key can never be an encryption key and two columns holding the same plaintext produce unrelated index values. - Index keys are salted with the vault's per-deployment `:derivation_salt`, so two deployments provisioned from the same key material - a restored backup, a cloned staging environment - derive unrelated index values, and a vault without one refuses to derive rather than deriving under nothing. - Key material never reaches this package: there is no argument on any function in the derivation that a tenant master key could be passed as, and every byte comes back from the vault already derived. - A blind index resolves its tenant through the encrypted field's own configured strategy, so a host that replaced the default with a resolver module gets the same replacement for its indexes, and a missing tenant raises `MissingTenantError` rather than silently matching nothing. - `Encryptor.Ecto.BlindIndex.DerivationError` reports a derivation that could not proceed, naming the table, column, index name and version, and never a value. - `Encryptor.Ecto.BlindIndex.put_index/3` computes a declared index column from the cast plaintext: it applies the field's normalizer, derives the index key through the vault, and puts the HMAC. A source field that was not changed is not recomputed, and a source set to `nil` sets the index to `nil` - a `NULL` plaintext beside a non-`NULL` index would leak that a value exists (ADR-0003 decision 8). - `Encryptor.Ecto.BlindIndex.where_eq/3` adds an equality constraint on the index column, against a computed value. Equality is the whole surface permanently (ADR-0003 decision 9): there is no `where_like`, no `where_gt`, no ordering helper, and no operator argument that could be made to generate one. - `Encryptor.Ecto.BlindIndex.where_eq_candidates/3` is the same constraint under the weaker contract a truncated index answers under. `where_eq/3` refuses a truncated index by name, so a call site that has to filter the rows after decrypting them cannot forget that it does. - `Encryptor.Ecto.BlindIndex.compute/3` returns the index value itself, for a host building its own query. It is a directly usable search token, and is on the never-logged list beside plaintext and key material. - Each of the three read helpers has a four-argument form naming the index column, for a field carrying more than one index - ADR-0003 decision 7's rotation window, where both versions are declared and the source field names neither, and decision 3d's per-tenant and `scope: :global` pair. The three-argument form refuses an ambiguous field rather than choosing a key for the caller. - `use Encryptor.Ecto.Migration, repo: MyApp.Repo` declares a migration plan: `rewrite` per schema, `tenant_from/1` or `tenant/1` for how the tenant is resolved, and `field/2` naming the `from:` and `to:` type modules of each column. The module compiles to an `Encryptor.Ecto.Migrator.Plan` struct, handed over by a generated `__plan__/0`. - A plan that would fail on row one fails at `mix compile`: every field and `into:` column is checked against the schema, `tenant_from` against its columns, every `from:` module against the shapes `Encryptor.Ecto.Migrator.Source` can read, and every `to:` module against the load *and* dump pair it has to answer. Each refusal is a `CompileError` naming the schema and field, at the line the plan declared it. - `Encryptor.Ecto.Migrator.Source` is the behaviour a migration plan's `from:` names: one `load/2` callback that reads a column's pre-migration value and returns `{:ok, plaintext}` or `{:error, reason}` rather than raising. - `Encryptor.Ecto.Migrator.Source.EctoType` adapts any module that can already read those bytes - a plain `Ecto.Type` with `load/1`, which is every `cloak_ecto` type module and every hand-rolled one, or an `Ecto.ParameterizedType` with `load/3` - so migrating off a prior encryption scheme needs no dependency on the library being left behind. - A failed legacy read is data rather than an exception: an `:error` return and a raise from the adapted module both become `{:error, reason}`, scoped to the one row, so the migrator can classify the row instead of losing the pass. - A zero-arity function returned by a source is invoked once and its result is the plaintext, so a legacy type that defers its decrypt migrates the value rather than the closure. - `Encryptor.Ecto.Migrator.Source.Plaintext` reads a column that was never encrypted, for the backfill leg of adopting encryption on one. - A `from:` module that can read nothing fails at `mix compile` with an error naming the field, rather than on the first row of a live pass. - `Encryptor.Ecto.Migrator.run/2` rewrites the ciphertext columns a plan names, against live traffic: every row is probed before it is rewritten, so running the pass twice, resuming it from the wrong cursor or interrupting it midway all converge on the same end state. - Writes are compare-and-swap against the exact bytes the migrator read, so a row the application wrote in the meantime is counted as concurrently migrated rather than clobbered with a re-encryption of stale plaintext. - Rows are visited in primary-key order with keyset pagination, one batch per transaction, with the batch's cursor and counts recorded in the same transaction. Single-column integer and binary primary keys are supported; a composite or otherwise unordered key is refused with a message naming the schema rather than paged over under a guess. - The checkpoint key carries the schema prefix, so a host looping `run/2` over its prefixes gets one cursor per prefix instead of the second prefix resuming at the first's and skipping every row below it. - `mode:` is required and has no default: `:dry_run` rehearses every read, probe, decrypt and encrypt and discards the write, `:write` performs it. - A missing checkpoint table is refused with a message naming the generator - this package issues no DDL - and `checkpoint: :none` runs the documented degraded mode with no checkpoint at all. - Failures are loud and the default is to stop: an unreadable row halts the pass, rolls back its batch, and reports the primary key, the schema, the field and a reason that carries no plaintext, ciphertext or key material. `on_error: :continue` records it and finishes, and still exits non-zero. - `Encryptor.Ecto.Migrator.verify/2` is the read-only half of a migration: the same plan, the same classification, no writes, and a non-zero arm for any row that is not already in the target state. It is the acceptance test at the end of a rotation, the drift check a host runs on a schedule, and the signal that the mixed window has closed and `legacy:` can be dropped. - `sample:` verifies a random draw of rows per field rather than the whole scope, for the scheduled check. The draw is random rather than the first rows in key order, because key order is the order a pass writes in and a prefix of it is the region a partial pass has already migrated. - `Encryptor.Ecto.Migrator.Report.verified?/1` is that stricter arm as a function: every row `:already_target` or `:null`, and no failures. It counts a class it has never heard of against a verification, so a class added later cannot arrive as a green report. - `Encryptor.Ecto.Migrator.Census` renders the SQL an operator or a DBA runs with no application and no key material: a format census over a byte prefix wide enough to separate two formats whose first byte collides, rotation progress for one tenant, and a before/after count showing nothing became `NULL` or empty. - `legacy:` opens the migration window: name the type module the column was read with before, and a row the migration has not reached yet still loads, through that module, while every write goes out in the new format. The primary load is always attempted first, and the fallback hangs off the vault's refusal of the stored bytes alone - a missing tenant or a missing required context key raises, because answering a host misconfiguration with a successful legacy read turns a configuration bug into a silent year of un-migrated rows. - A load that falls through emits `[:encryptor_ecto, :legacy_load]`, counting one, with the table and the column and nothing else. The window is per-field, so the pair is what tells a host which of its twelve encrypted columns still has a legacy reader open. The counter is a convenience and not a proof: it is evidence about traffic rather than about rows, and `Encryptor.Ecto.Migrator.verify/2` stays the signal a host drops `legacy:` on. - When both loads fail, the exception raised is the primary `Encryptor.Ecto.DecryptError`. The legacy attempt's reason travels in the non-contractual `:engine` field, reduced to tags and module names, so a legacy reader that prints the bytes it choked on cannot put them into the failure a host sees. - A migration plan field may declare `source_authenticated: false`, which acknowledges that its legacy cipher has no authentication tag: a wrong key or a corrupt row decrypts to something rather than failing, so a successful load is not evidence. Its rows are then counted `:migratable_unverified` rather than `:migratable`, in a dry run, a write and a verification alike, so no report claims a verification that never happened. - `validate:` takes a host-supplied `(term() -> boolean())` applied to the loaded plaintext before it is re-encrypted - a card number is sixteen digits, a serialized map parses, a kept legacy hash column recomputes. A row it rejects is `:undecryptable` and is not written. There is no built-in generic validator: a printable?/UTF-8? check would be reassurance rather than a control, and only the host knows what its own values look like. - `Encryptor.Ecto.Migrator.Report.classes/0` gains `:migratable_unverified`, which counts against `verified?/1` like every class but `:null` and `:already_target`. - `mix encryptor.ecto.migrate PLAN --mode dry-run|write` runs a migration plan through `Encryptor.Ecto.Migrator.run/2`. `--mode` is required and has no default; `--batch-size`, `--resume`/`--no-resume`, `--prefix`, `--no-checkpoint`, `--only Schema:field`, `--only-tenant`, `--except-tenant` and `--on-error halt|continue` each map onto one option of `run/2` and add no capability the library function lacks. - `mix encryptor.ecto.verify PLAN [--sample N|all] [--prefix PREFIX]` runs the read-only pass. Those two flags and no others: a migrate flag passed here refuses and names the verb it belongs to, rather than being silently ignored by a `verify/2` that has no such option. - `mix encryptor.ecto.gen.migration` writes the checkpoint table's migration into the host's tree - `--table` renames it, `--migrations-path` places it. It issues no DDL and never overwrites an existing migration for the table; the host reviews the file, commits it, and runs it with its own `mix ecto.migrate`. - The tasks carry the flag tables and the exit codes in their `@moduledoc`s, which are the reference half of the documentation set. Exit codes: `0` the pass completed with no failures, `1` the pass ran and found something (a dry run that finds `:undecryptable` rows included), `2` a usage error, a plan that will not compile, or a run that could not start. - `mix encryptor.ecto.gen.plan` writes a migration plan skeleton into the host's tree. It loads the host's application, reads every Ecto schema in it, and emits one `rewrite` block per schema with one `field` line per field whose type is a module rather than a built-in Ecto type. `--repo` is read from the app's `:ecto_repos` when that names exactly one; `--app`, `--module` and `--output` cover the rest, and the generator never overwrites a plan that already exists. - The generated file **does not compile**, on purpose (ADR-0004 decision 7), and carries a comment explaining why so that whoever runs `mix compile` next does not read it as a bug. Three facts are left visibly unanswered because a generator cannot know them: every block emits `tenant_from :TODO_tenant_column`, which the plan DSL rejects at compile time - guessing the tenant column re-encrypts every row under one tenant's key, and a skeleton that compiled would be a skeleton somebody ran; every field's `to:` is a comment rather than a value, since a half-guessed target type produces a diff that looks reviewed; and the field list over-reports, because per ADR-0004 decision 1 the generator tests for no other library's marker function, so a custom type that encrypts nothing is listed too. A false positive a human deletes beats a field nobody noticed. - This is the one member of the task family with no release equivalent (ADR-0004 Q6): reading `__schema__(:type, field)` needs the host's schema modules loaded, which a Mix task has and a release command does not. It writes source into a working tree, which is not a thing a release does. ### Changed - **`:bits` is applied.** A blind index declared `bits: 64`, `128` or `192` now stores that many bits - the leading 8, 16 or 24 bytes of the `HMAC-SHA256` - instead of the full 32 bytes it stored while ADR-0003 decision 6's option half was carried unapplied. `bits: 256` remains the default and is unchanged. This is a behaviour change for any declaration already carrying a narrower width; no host has stored a blind index value yet, so nothing needs reindexing. - `Encryptor.Ecto.BlindIndex.Value.byte_width/1` reports a declaration's stored width in bytes, which is what a host sizes its index column against. - ADR-0004 gains a dated proposed amendment answering Q2 on the operator's ruling: silence about `source_authenticated:` is allowed only where authentication is provable from the `from:` type, and every other `from:` must declare it explicitly. Decision 3d's worked example changes with it. The compile-time enforcement is a later bead's; only the record's text lands here. - `mode: :write` is refused, before a row is read, for a field that declares `source_authenticated: false` without a `validate:`. `mode: :dry_run` and `verify/2` still run it, which is how such a field is inspected first. - A plan field whose `from:` type is not one of this package's own vault-backed types must now declare `source_authenticated:` explicitly, and fails at `mix compile` naming the schema and field if it does not. Silence is allowed only where authentication is provable - the context-change case, where `from:` names a type this package wrote the bytes with. Everywhere else `from:` is the host's own legacy reader, and this package cannot tell an AEAD cipher from a stream cipher by looking, so it asks where the question is cheap. Upgrading hosts declare `source_authenticated: true` per legacy field: the reviewable assertion that someone checked. ### Fixed - `Encryptor.Ecto.String` and `Encryptor.Ecto.Map` fields now carry the marker that identifies an encrypted field, so `Encryptor.Ecto.Declarations` sees them. Its uniqueness check previously covered only `Encryptor.Ecto.Binary` fields, which meant a text or map field sharing a declared `{table, column}` pair with another field passed a check whose whole purpose is to deny that pairing - the two are mutually substitutable, since both ride the declared pair as AAD through the same code. ### Notes - **Both sides raise on a missing tenant, `where_eq/3` included.** A query *built* outside tenant scope raises where it is built rather than executing and matching nothing, which is the failure ADR-0003 decision 5 calls the worst this feature can have, because it looks exactly like "the record does not exist". - A write-side computation asks the field's tenant strategy with `:dump` and a read-side computation asks with `:load`, matching what the encrypted field itself would be doing at the same moment. - `:bits` and `:slow` are carried rather than applied *by these helpers*: `where_eq/3`'s refusal reads the declared width and no helper computes with it. `:bits` is applied one layer down, in `Encryptor.Ecto.BlindIndex.Value` - see this release's `ece-6a6` entry, which landed after this one and supersedes its original claim that a declaration written with `bits: 64` stores a full-width value. `:slow` remains carried and unapplied. - A tenant *key* rotation is not ADR-0003 decision 7's rotation. Only the current encryption key is consulted upstream, so rotating a tenant's key changes every index key under it without any declaration changing, and values stored under the superseded key stop being derivable - `where_eq/3` then matches nothing and raises nothing. The record does not describe that case and this package invents no behaviour for it: a host rotating a tenant key must reindex that tenant's index columns. - **The output is truncated, never the key.** The index key stays the full 32 bytes the derivation produces, and `:bits` never reaches the HKDF `info` string - so a width change stores different bytes under the *same* key. A shortened HMAC key would be a weakened HMAC; decision 6 asks for a collision knob on the stored value, and collisions are a property of the value's width. - **The leading bytes are kept.** RFC 2104 section 5 defines HMAC truncation as "the leftmost t bits" and NIST SP 800-107 section 5.3.1 says the same for any approved hash output. Either end is equally sound here, so this is a convention rather than a security choice - but it is a constant a host's stored bytes depend on forever, so it is written down at `Encryptor.Ecto.BlindIndex.Value` rather than left to the reader of a `binary_part/3`. - **Truncation happens in one place**, inside the single function every surface computes through, so `put_index/3` and `where_eq_candidates/3` cannot store and pin different widths. That is ADR-0003 decision 5's promise applied to decision 6, and it is why `:bits` is read at no call site. - A `:bits` change invalidates the column exactly as a normalizer change does (decision 7): the stored value changes even though the key does not, so the two-column dance is the migration. - **`:slow` is still carried rather than applied.** ADR-0003 decision 6 puts Argon2id's parameters in "the vault's configuration rather than this package's", and the vault exposes no Argon2id surface to read them from. Choosing a parameter set here would be this package making a cryptographic decision inline, which this repository's conventions call a defect even when the choice is a good one. A declaration written with `slow: true` is accepted, checked and carried, and does nothing.