AshVault.Query (AshVault v0.2.0)

Copy Markdown View Source

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/4 raises. It is a plain function with no query of its own to hang an error on, and returning {:error, _} from something that otherwise returns an Ash.Query would be easy to ignore.
  • the generated read action adds the error to the query with Ash.Query.add_error/2, so Ash.read/2 returns {:error, _} and Ash.read!/2 raises — which is what every other Ash error does, and what every other AshVault error path already does (AshVault.encrypt_and_set/4 adds to the changeset, AshVault.decrypt_value/5 returns 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

apply_filter(query, lookup_field, token)

@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.

filter_by(resource_or_query, field, value, context \\ nil)

@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 :tenant already
  • nil, for a scope :global resource
  • 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_context(context)

@spec normalize_context(term()) :: map()

Normalize the context argument of filter_by/4 into the map AshVault.Context.Builder expects.