Query helpers for searchable encrypted fields.
A lookup token is an HMAC, so nobody should ever be building one by hand to put in a
filter — one wrong String.downcase/1 and the query silently matches nothing. There
are two supported ways to query a searchable field, and this module is the lower one.
filter_by/4
AshVault.Query.filter_by(MyApp.User, :email, "Jake@Example.com", tenant: "acme")
|> Ash.read!()Returns an Ash.Query with the tenant set and a filter on email_lookup. The first
argument may also be an existing Ash.Query, so this composes:
MyApp.User
|> Ash.Query.filter(active == true)
|> AshVault.Query.filter_by(:email, "jake@example.com", tenant: "acme")The generated :by_<field> read action
encrypt :email, searchable?: true also generates a read action, :by_email, taking
the plaintext as a sensitive?: true argument. That is the form to expose through a
code interface, which AshVault does not write for you:
# in your domain
resource MyApp.User do
define :get_user_by_email, action: :by_email, args: [:email], get?: true
end
MyApp.Accounts.get_user_by_email!("jake@example.com", tenant: "acme")A missing tenant is an error, never an empty result
Both paths resolve the scope through the resource's configured AshVault.Scope, from
the query's tenant, exactly as a write does. A tenant-scoped query with no tenant
therefore fails with AshVault.Errors.MissingScope.
This is the single most important behaviour in this module. A lookup that quietly returned zero rows for a missing tenant would read as "no such user" — at a login form, at a "is this address taken?" check, at a dedupe pass — and it would look entirely healthy in review, in logs and in tests.
The two paths report it differently, on purpose:
filter_by/4raises. It is a plain function with no query of its own to hang an error on, and returning{:error, _}from something that otherwise returns anAsh.Querywould be easy to ignore.- the generated read action adds the error to the query with
Ash.Query.add_error/2, soAsh.read/2returns{:error, _}andAsh.read!/2raises — which is what every other Ash error does, and what every other AshVault error path already does (AshVault.encrypt_and_set/4adds to the changeset,AshVault.decrypt_value/5returns a value). A preparation that raised would be the only place in AshVault where an error escapes a non-bang Ash call as an exception.
Summary
Functions
The filter clause filter_by/4 applies, for a token already in hand.
Filter a resource or query on a searchable field's value.
Normalize the context argument of filter_by/4 into the map
AshVault.Context.Builder expects.
Functions
@spec apply_filter(Ash.Query.t(), atom(), binary() | nil) :: Ash.Query.t()
The filter clause filter_by/4 applies, for a token already in hand.
A nil token — from a nil plaintext — becomes is_nil, not == nil, so the query
means what it says on every data layer.
@spec filter_by(module() | Ash.Query.t(), atom(), term(), term()) :: Ash.Query.t()
Filter a resource or query on a searchable field's value.
context may be:
- a keyword list or map carrying
:tenant(and optionally:actor) —[tenant: "acme"] - any Ash callback context struct, which carries
:tenantalready nil, for ascope :globalresource- any other term, which is taken to be the tenant itself
Raises AshVault.Errors.MissingScope when the scope cannot be resolved,
AshVault.Errors.KeyDestroyed when the scope has been crypto-erased, and
ArgumentError when field is not a searchable field of the resource.
Normalize the context argument of filter_by/4 into the map
AshVault.Context.Builder expects.