AshGrant.PermissionValidation (AshGrant v0.22.0)

Copy Markdown View Source

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:

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

CodeSegmentSeverityMeaning
:parse_error:permissionerrorAshGrant.Permission.parse/1 rejects the string
:unknown_resource:resourceerrornot *, and no configured resource answers to that name
:unknown_action:actionerrora literal action name no targeted resource has
:unknown_action_type:actionerrorfrom AshGrant.Permission.diagnostics/1
:deprecated_type_wildcard:actionwarningfrom AshGrant.Permission.diagnostics/1
:dead_instance_type_wildcard:actionwarningfrom AshGrant.Permission.diagnostics/1
:undeclared_scope:scopeerror¹no resource the grant applies to declares the scope
:scope_missing_on:scopeerror¹some of the resources the grant applies to lack the scope — listed in :resources
:unverifiable_scope:scopewarningundeclared, but a scope_resolver is configured and may know it
:unknown_field_group:field_grouperrorno resource the grant applies to declares the field group
:field_group_missing_on:field_grouperrorsome of the resources the grant applies to lack the field group — listed in :resources
:deny_with_field_group:field_grouperrorthe 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 string resource: 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 or CanPerform calculations. An instance permission may also name an action of any resource that scope_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), plus always and all, which every check accepts without a declaration. global is accepted by name on the read path only; AshGrant.Check raises on it, so an undeclared global is reported whenever the grant can reach a write or generic action.
  • Field group — AshGrant.Info.field_groups/1.

Summary

Types

A problem check/2 found in one permission.

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

issue()

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

mode()

@type mode() :: :off | :warn | :strict

Functions

check(permission, opts \\ [])

@spec check(term(), keyword()) :: [issue()]

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_domains instead.

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]
#=>   }
#=> ]

check_all(permissions, opts \\ [])

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

errors?(issues)

@spec errors?([issue()]) :: boolean()

Returns true when issues contains at least one :error.

validate(permissions, mode, opts \\ [])

@spec validate(list(), mode(), keyword()) :: :ok

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.