Validates permissions: a request-time rule for the permissions an actor resolves to, and a static checker for the strings an application stores.
Request time: validate/3
Enforces one rule (issue #117): a permission that is a deny (! prefix)
must not carry a field_group (5th part). A field-group deny is invalid
because field-group access is positive-only — column restrictions belong in
the resource's field_group definition (inherits/except/mask), and a
deny carrying a field_group currently over-denies the entire action
(fail-closed) rather than the named group.
The validator never changes the authorization outcome; it only signals the invalid permission according to the configured mode:
:off— do nothing:warn— emit aLogger.warning(deduplicated per process):strict— raiseAshGrant.PermissionValidation.InvalidPermissionError
The mode is configured per resource via the field_group_permissions option in
the ash_grant DSL block (default :warn).
Ahead of time: check/2 and check_all/2
Permission strings are runtime data — a roles table, a seed file, a migration. The compiler never sees them, so nothing stops a stored string from naming a resource, action, scope or field group that does not exist. Most of those fail silently (the grant is inert, or the fields stay forbidden); an undeclared scope raises inside the check, on whatever request first reaches it. A rename in code orphans every stored string that used the old name.
check/2 compares one permission against the application's resources and
returns a list of issues; check_all/2 does the same for a whole table or
file. Run them wherever the strings live:
# One string, e.g. from an admin form
AshGrant.PermissionValidation.check("post:*:read:own", otp_app: :my_app)
#=> []
# Every stored grant, e.g. in a deploy step
MyApp.Role
|> MyApp.Repo.all()
|> Enum.flat_map(& &1.permissions)
|> AshGrant.PermissionValidation.check_all(otp_app: :my_app)
|> Enum.reject(fn {_permission, issues} -> issues == [] end)AshGrant.Validations.PermissionStrings wraps this as an Ash validation for
the attribute that stores grants, and mix ash_grant.check_permissions wraps
it for CI. Like validate/3, none of this changes an authorization outcome.
Issue codes
| Code | Segment | Severity | Meaning |
|---|---|---|---|
:parse_error | :permission | error | AshGrant.Permission.parse/1 rejects the string |
:unknown_resource | :resource | error | not *, and no configured resource answers to that name |
:unknown_action | :action | error | a literal action name no targeted resource has |
:unknown_action_type | :action | error | from AshGrant.Permission.diagnostics/1 |
:deprecated_type_wildcard | :action | warning | from AshGrant.Permission.diagnostics/1 |
:dead_instance_type_wildcard | :action | warning | from AshGrant.Permission.diagnostics/1 |
:undeclared_scope | :scope | error¹ | no resource the grant applies to declares the scope |
:scope_missing_on | :scope | error¹ | some of the resources the grant applies to lack the scope — listed in :resources |
:unverifiable_scope | :scope | warning | undeclared, but a scope_resolver is configured and may know it |
:unknown_field_group | :field_group | error | no resource the grant applies to declares the field group |
:field_group_missing_on | :field_group | error | some of the resources the grant applies to lack the field group — listed in :resources |
:deny_with_field_group | :field_group | error | the rule validate/3 enforces at request time |
¹ A warning on a deny or an instance permission: the framework never
resolves those scopes (a deny applies whatever its scope; an instance scope is
the application's to read via AshGrant.Evaluator.get_instance_scope/3), so an
undeclared one cannot raise.
What "the resources the grant applies to" means
A scope is only resolved on a resource where the grant matches an action. So
*:*:approve:own_unit needs own_unit on every resource that has an approve
action — not on every resource in the application. The same goes for a resource
name shared by several resources. A grant that matches no action anywhere is
reported for its action alone — nothing reads its scope or field group until
that is fixed. Field groups add one exemption: under a *
or shared name, a resource that declares no field groups at all is skipped,
since the 5th segment has nothing to restrict there.
Which names count as declared
- Resource —
AshGrant.Info.resource_name/1, plus any stringresource:override passed to an AshGrant check in the resource's policies. - Action — the resource's actions, plus any
action:override (AshGrant.check(action: "publish")) in its policies orCanPerformcalculations. An instance permission may also name an action of any resource thatscope_throughs this one: the checks match the parent's instance permissions against the child's action. - Scope —
AshGrant.Info.scopes/1(domain-inherited scopes included), plusalwaysandall, which every check accepts without a declaration.globalis accepted by name on the read path only;AshGrant.Checkraises on it, so an undeclaredglobalis reported whenever the grant can reach a write or generic action. - Field group —
AshGrant.Info.field_groups/1.
Summary
Functions
Checks one permission against the application's resources.
Checks many permissions against the application's resources.
Returns true when issues contains at least one :error.
Validates permissions and signals any invalid deny+field_group entries per mode.
Types
@type issue() :: %{ code: atom(), severity: :error | :warning, segment: :permission | :resource | :action | :scope | :field_group, message: String.t(), permission: String.t(), resources: [module()] }
A problem check/2 found in one permission.
segment is the part of the string at fault (:permission for a string that
does not parse). resources lists the resource modules the issue is about —
the ones lacking the scope or field group — and is [] when the issue is not
about particular resources.
@type mode() :: :off | :warn | :strict
Functions
Checks one permission against the application's resources.
Returns [] when every segment names something that exists, otherwise one
issue per problem — see the moduledoc for the codes. Accepts a string, an
%AshGrant.Permission{}, an %AshGrant.PermissionInput{} or anything
implementing AshGrant.Permissionable.
Options
:resources— the resource modules to check against.:otp_app— read the resources from that application's:ash_domainsinstead.
With neither, every AshGrant resource in the started applications'
:ash_domains is used (AshGrant.Introspect.list_resources/0). Resources
without the AshGrant extension or without a resolver are ignored either way.
Examples
AshGrant.PermissionValidation.check("post:*:read:own", resources: [MyApp.Blog.Post])
#=> []
AshGrant.PermissionValidation.check("post:*:read:owm", resources: [MyApp.Blog.Post])
#=> [
#=> %{
#=> code: :undeclared_scope,
#=> severity: :error,
#=> segment: :scope,
#=> message: "Scope `owm` is not declared on MyApp.Blog.Post. The check raises " <>
#=> "when it resolves this scope. Did you mean `own`?",
#=> permission: "post:*:read:owm",
#=> resources: [MyApp.Blog.Post]
#=> }
#=> ]
@spec check_all(Enumerable.t(), keyword()) :: [{term(), [issue()]}]
Checks many permissions against the application's resources.
Returns one {permission, issues} pair per input, in input order, so a caller
can point at the offending row. Takes the same options as check/2 and reads
the resources once for the whole list.
Returns true when issues contains at least one :error.
Validates permissions and signals any invalid deny+field_group entries per mode.
Accepts the same permission representations the resolver may return (strings,
%AshGrant.Permission{} structs, %AshGrant.PermissionInput{}, or
Permissionable maps). Always returns :ok; raises InvalidPermissionError
only in :strict mode when an offender is present.
Options
:resource— the resource module, included in the message for context.