A scope is the blast radius of a key. Everything sharing a scope shares key material, and destroying that scope's key crypto-erases all of it at once. Choosing the scope is therefore the most consequential design decision in an AshVault deployment: it decides what "delete this customer's data" can mean.

AshVault ships two implementations:

  • AshVault.Scopes.AshTenant — one key lineage per Ash tenant. The default, and the right answer for almost every multitenant application.
  • AshVault.Scopes.Global — the constant "global". One key lineage for the whole application; rotation and erasure are application-wide.

You write your own when the unit of erasure is neither of those — per-user in a single-tenant app, per-row for a data-retention regime, per-region for a residency one.

The contract

@callback resolve!(AshVault.Context.t()) :: term()

One function. It receives the context of the operation and returns the scope key, or raises AshVault.Errors.MissingScope if it cannot.

The scope key must be a stable binary

AshVault.Vault.Runtime enforces the binary part in one place, right after resolve!/1 returns:

MyApp.Scopes.PerUser.resolve!/1 returned {:user, "u_1"}, which is not a binary.

AshVault scope keys must be binaries: they name key material in the provider and are
bound into every ciphertext's associated data, so they have to be stable across
processes, releases and OTP upgrades.

That is AshVault.Errors.InvalidScope. The stable part it cannot enforce, and it matters more. The scope key is used for two things at once:

  1. it names key material and the tombstone in the provider, and
  2. it is interpolated into the AAD of every ciphertext: "ashvault:v1|" <> scope <> "|" <> inspect(resource) <> "|" <> field.

So a scope key that changes value for the same logical subject is a double failure: the tombstone moves (the scope resurrects with a freshly minted key) and the AAD no longer matches (every existing ciphertext fails to authenticate).

Concretely, never do this:

# WRONG — :erlang.term_to_binary/1 output is not guaranteed stable across OTP releases
def resolve!(ctx), do: :erlang.term_to_binary(ctx.ash_context.tenant)

# WRONG — a hash of a mutable field. Rename the org, lose the data.
def resolve!(ctx), do: Base.encode16(:crypto.hash(:sha256, ctx.ash_context.tenant.name))

Do this instead: derive from an immutable identifier and stringify.

def resolve!(ctx), do: "user:" <> to_string(id)

A prefix is worth adding. It keeps two different scope kinds from colliding in the same provider namespace, and it makes a directory listing or a bao list transit/keys legible.

Ash.ToTenant normalization

Ash hands you the raw tenant. It may be a binary, an integer, an atom, or a whole %Organization{} struct — Ash.Changeset's :tenant field is deliberately not normalized. Two callers passing the same logical tenant in different shapes must produce the same scope key, or one of them cannot read the other's rows.

AshVault.Scopes.AshTenant.to_scope_key/2 handles this:

  • a binary is used as-is,
  • an atom or integer is stringified,
  • a struct with a non-nil :id is reduced to the stringified id,
  • anything else raises MissingScope with reason: :unsupported_tenant_shape.

That last branch is worth copying. The naive thing is to fall through to the missing-tenant error, which tells an operator who did pass a tenant to go and find the tenant they did not forget:

Cannot encrypt MyApp.Accounts.User.email because the tenant is of a shape
AshVault.Scopes.AshTenant cannot turn into a stable scope key.

Received: %{org: "acme"}

A tenant was present — this is not a missing-tenant error. Accepted shapes are:

  * a binary, used as-is
  * an atom or an integer, stringified
  * a struct with a non-nil `:id`, reduced to the stringified id

To support another shape, implement `to_scope_key/2` in your own
`AshVault.Scope` module (see `AshVault.Scopes.AshTenant.to_scope_key/2`) and
configure it as the vault's `:scope`.

If you accept a struct shape Ash's own Ash.ToTenant protocol already understands, prefer calling Ash.ToTenant.to_tenant/2 and stringifying the result, so a tenant struct and its id land on the same key.

Failure modes that matter

  • Never fall back to a default scope. A resolve!/1 that returns "global" when no tenant is present will silently encrypt tenant data under the shared key, and that data survives the tenant's erasure. A missing scope is an error, full stop — which is why there is no context \\ nil default anywhere in AshVault.
  • Never make the scope depend on the actor unless the actor is the scope. If the scope varies with who is reading, the AAD varies too, and a row written by one user cannot be read by another.
  • Do not put the field or resource in the scope key. They are already in the AAD. Adding them to the scope multiplies your provider keys by your column count for no gain, and makes erasure per-column instead of per-subject.
  • Per-row scopes cost one provider key per row. That is the honest price of row-level crypto-erasure, and for some providers it is prohibitive. Measure before committing.
  • Read the context defensively. ash_context is a normalized map on the Ash paths (%{tenant:, actor:, source_context:, phase:}) but the crypto core promises no more than "a map, a struct, or nil" — a plain map works, which is what direct vault calls and tests use.

A worked example

Per-user scoping, for a single-tenant application that must honour individual deletion requests. The user id travels in the Ash context rather than as a tenant.

defmodule MyApp.Scopes.PerUser do
  @moduledoc """
  One key lineage per user, so a single user's data can be crypto-erased without
  touching anyone else's.

  The user id is read from `source_context[:user_id]`, set by the caller:

      MyApp.Note
      |> Ash.Changeset.for_create(:create, %{body: body})
      |> Ash.Changeset.set_context(%{user_id: user.id})
      |> Ash.create!()

  Costs one provider key per user. Erasure is
  `AshVault.destroy_keys!(MyApp.Vault, "user:" <> user.id)`.
  """

  @behaviour AshVault.Scope

  alias AshVault.Context
  alias AshVault.Errors.MissingScope

  @impl AshVault.Scope
  @spec resolve!(Context.t()) :: binary()
  def resolve!(%Context{} = context) do
    case user_id(context) do
      nil ->
        raise MissingScope.exception(
                resource: context.resource,
                field: context.field,
                scope_module: __MODULE__,
                reason: :no_user_id
              )

      id when is_binary(id) ->
        "user:" <> id

      %_struct{id: id} when is_binary(id) ->
        "user:" <> id

      other ->
        raise MissingScope.exception(
                resource: context.resource,
                field: context.field,
                scope_module: __MODULE__,
                reason: :unsupported_tenant_shape,
                tenant: inspect(other, limit: 5, printable_limit: 128, structs: false)
              )
    end
  end

  defp user_id(%Context{ash_context: ash_context}) when is_map(ash_context) do
    case get_in(ash_context, [Access.key(:source_context, %{}), :user_id]) do
      nil -> get_in(ash_context, [Access.key(:source_context, %{}), :private, :user_id])
      id -> id
    end
  end

  defp user_id(%Context{}), do: nil
end

MissingScope.message/1 has a branch for a :reason it does not specifically know, so :no_user_id produces:

Cannot encrypt MyApp.Note.body: MyApp.Scopes.PerUser could not resolve a scope (:no_user_id).

Wiring it up

The scope lives on the vault — that is the one AshVault.Vault.Runtime actually resolves with:

defmodule MyApp.Vault do
  use AshVault.Vault,
    key_provider: MyApp.KeyProviders.Sql,
    scope: MyApp.Scopes.PerUser
end

And the resource must restate it:

ash_vault do
  vault MyApp.Vault
  scope MyApp.Scopes.PerUser

  encrypt :body
end

AshVault.Verifiers.VerifyVault enforces that agreement at compile time, because the resource's scope is what the key_lifecycle actions rotate and destroy while the vault's is what data is encrypted under. If they disagree:

This resource's key scope is AshVault.Scopes.AshTenant but MyApp.Vault encrypts with
MyApp.Scopes.PerUser.

The vault resolves the scope every value is actually encrypted under, while the
resource's `scope` is what the `key_lifecycle` actions rotate and destroy. If the
two disagree, rotation and cryptographic erasure act on the wrong keys.

Either set `scope` to match the vault, or point at a vault built with
`use AshVault.Vault, scope: AshVault.Scopes.AshTenant`.

See Tenant-scoped encryption for why the check is a restatement rather than an inference.

Testing it

test/ash_vault/scopes/ash_tenant_test.exs is the model. Assert:

  • every shape you accept maps to the key you expect, and two shapes of the same subject map to the same key;
  • a missing subject raises MissingScope, and Exception.message/1 on it reads the way you want at 3am;
  • a shape you do not accept raises MissingScope with reason: :unsupported_tenant_shape and not the missing-subject message;
  • an end-to-end vault roundtrip through a vault configured with your scope, plus a cross-scope decrypt that fails with AshVault.Errors.CiphertextIntegrityFailed. Use a fixed-key provider for that last one (see AshVault.Test.Support.FixedKeyVault) — with per-scope keys the failure could be the key differing rather than the AAD binding, and the test would not prove what it claims.