Scopes encryption keys to the Ash tenant of the operation.
context.ash_context is the raw Ash context — an Ash.Resource.Change.Context, an
Ash.Resource.Calculation.Context, or a plain map. The tenant is looked up in order:
- the top-level
:tenantfield, which is where both Ash context structs carry it source_context[:tenant], for contexts whose tenant only reached the source context
The first non-nil wins. No specific struct module is ever required.
The tenant is then normalised to a stable binary by to_scope_key/1:
- a binary is used as-is
- an atom or integer is stringified
- a struct with an
:idis reduced to the stringified id - anything else raises
AshVault.Errors.MissingScopewithreason: :unsupported_tenant_shape, whose message says what was received and which shapes are accepted — a tenant WAS passed, it just could not be reduced to a stable key, and telling the operator to "pass a tenant" would send them hunting something that is not missing
That "what was received" is a description, never the tenant itself: see
describe_tenant/1. A tenant is routinely a loaded record full of customer PII, and
the error it fails with ends up in logs and APM.
Stringification (rather than :erlang.term_to_binary/1) keeps scope keys readable and
stable across processes, releases and OTP upgrades.
When no tenant is present the operator gets an actionable error explaining that the resource uses tenant-scoped encryption.
Summary
Functions
Describe a tenant term for an operator-facing error, without reproducing its contents.
Resolve the tenant of an operation to a stable scope key.
Normalise a tenant term into a stable binary scope key.
Functions
Describe a tenant term for an operator-facing error, without reproducing its contents.
MissingScope's :tenant field is rendered into Exception.message/1 and travels
wherever Ash sends the error — logs, Sentry, an APM trace. A tenant is very often a
whole loaded record (%MyApp.Organization{name: ..., billing_email: ...}), so
inspect/2 here would push customer PII into every one of those places to answer a
question that only needs the shape: what did we get, and why could we not reduce it
to a key?
Structs are therefore named, not printed, and the description says explicitly whether
an :id was present-but-nil or absent altogether — which is the whole diagnosis.
Every non-struct term is described by AshVault.Scope.describe/1, which
AshVault.Errors.InvalidScope uses too, so a scope term is redacted the same way
wherever it surfaces.
@spec resolve!(AshVault.Context.t()) :: binary()
Resolve the tenant of an operation to a stable scope key.
Raises AshVault.Errors.MissingScope when no tenant is present, or when the tenant is
of a shape AshVault cannot turn into a stable key.
@spec to_scope_key(term(), AshVault.Context.t() | nil) :: binary()
Normalise a tenant term into a stable binary scope key.