# `AshGrant.PermissionValidation`
[🔗](https://github.com/jhlee111/ash_grant/blob/v0.22.0/lib/ash_grant/permission_validation.ex#L1)

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 a `Logger.warning` (deduplicated per process)
  * `:strict` — raise `AshGrant.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 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_through`s 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`.

# `issue`

```elixir
@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`

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

# `check`

```elixir
@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`

```elixir
@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?`

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

Returns true when `issues` contains at least one `:error`.

# `validate`

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*
