Permission-based authorization extension for Ash Framework.

AshGrant provides a flexible, Apache Shiro-inspired permission string system that integrates seamlessly with Ash's policy authorizer. It combines:

• Permission-based access control with resource:instance:action:scope matching
• Attribute-based scopes for row-level filtering (ABAC-like)
• Instance-level permissions for resource sharing (ReBAC-like)
• Deny-wins semantics for intuitive permission overrides

AshGrant focuses on permission evaluation, not role management. It works well on top of RBAC systems—just resolve roles to permissions in your resolver.

Key Features

• Unified Permission Format: resource:instance_id:action:scope[:field_group] syntax (4-part or 5-part)
• Field-level permissions: Column-level read access via field groups with inheritance and masking
• Instance-level permissions: Share specific resources (like Google Docs sharing)
• Instance permissions with scopes (ABAC): Conditional instance access (doc:doc_123:update:draft)
• Deny-wins semantics: Deny rules always override allow rules
• Wildcard matching: * for resources/actions, read* for action types
• Scope DSL: Define scopes inline with expr() expressions
• Context injection: Use ^context(:key) for injectable/testable scopes
• Multi-tenancy Support: Full support for ^tenant() in scope expressions
• Three check types: filter_check/1 for reads, check/1 for writes, field_check/1 for field-level access
• Default policies: Auto-generate standard policies to reduce boilerplate

Installation

See the README for installation instructions.

Quick Start

Minimal Setup (with Default Policies)

With default_policies: true, you don't need to write any policy boilerplate:

defmodule MyApp.Blog.Post do
  use Ash.Resource,
    domain: MyApp.Blog,
    authorizers: [Ash.Policy.Authorizer],
    extensions: [AshGrant]

  ash_grant do
    resolver MyApp.PermissionResolver
    default_policies true  # Auto-generates read/write policies!

    scope :always, true
    scope :own, expr(author_id == ^actor(:id))
    scope :published, expr(status == :published)
  end

  # No policies block needed - AshGrant generates them automatically!
  # ... attributes, actions, etc.
end

Explicit Policies (Full Control)

For more control, disable default_policies and define policies explicitly:

defmodule MyApp.Blog.Post do
  use Ash.Resource,
    domain: MyApp.Blog,
    authorizers: [Ash.Policy.Authorizer],
    extensions: [AshGrant]

  ash_grant do
    resolver MyApp.PermissionResolver
    resource_name "post"

    scope :always, true
    scope :own, expr(author_id == ^actor(:id))
    scope :published, expr(status == :published)
  end

  policies do
    bypass actor_attribute_equals(:role, :admin) do
      authorize_if always()
    end

    policy action_type(:read) do
      authorize_if AshGrant.filter_check()
    end

    policy action_type([:create, :update, :destroy]) do
      authorize_if AshGrant.check()
    end
  end
end

Implement a PermissionResolver

The resolver fetches permissions for the current actor:

defmodule MyApp.PermissionResolver do
  @behaviour AshGrant.PermissionResolver

  @impl true
  def resolve(nil, _context), do: []

  @impl true
  def resolve(actor, _context) do
    actor
    |> get_roles()
    |> Enum.flat_map(& &1.permissions)
  end
end

Permissions with Metadata (for debugging)

Return AshGrant.PermissionInput structs for enhanced debugging and explain/4:

defmodule MyApp.PermissionResolver do
  @behaviour AshGrant.PermissionResolver

  @impl true
  def resolve(actor, _context) do
    actor
    |> get_roles()
    |> Enum.flat_map(fn role ->
      Enum.map(role.permissions, fn perm ->
        %AshGrant.PermissionInput{
          string: perm,
          description: "From role permissions",
          source: "role:#{role.name}"
        }
      end)
    end)
  end
end

Custom Structs with Permissionable Protocol

Implement the AshGrant.Permissionable protocol for your custom structs:

defmodule MyApp.RolePermission do
  defstruct [:permission_string, :label, :role_name]
end

defimpl AshGrant.Permissionable, for: MyApp.RolePermission do
  def to_permission_input(%MyApp.RolePermission{} = rp) do
    %AshGrant.PermissionInput{
      string: rp.permission_string,
      description: rp.label,
      source: "role:#{rp.role_name}"
    }
  end
end

# Then just return your structs from the resolver
defmodule MyApp.PermissionResolver do
  @behaviour AshGrant.PermissionResolver

  @impl true
  def resolve(actor, _context) do
    MyApp.Accounts.get_role_permissions(actor)
  end
end

Permission Format

Permission String Format

[!]resource:instance_id:action:scope[:field_group]

The 5th part (field_group) is optional. When omitted (4-part format), all fields are visible.

RBAC Permissions (instance_id = *)

"blog:*:read:always"           # Read all blogs
"blog:*:read:published"     # Read only published blogs
"blog:*:update:own"         # Update own blogs only
"blog:*:*:always"              # All actions on all blogs
"*:*:read:always"              # Read all resources
"blog:*:read*:always"          # All read-type actions
"!blog:*:delete:always"        # DENY delete on all blogs

Instance Permissions (specific instance_id)

"blog:post_abc123xyz789ab:read:"     # Read specific post
"blog:post_abc123xyz789ab:*:"        # Full access to specific post
"!blog:post_abc123xyz789ab:delete:"  # DENY delete on specific post

Instance Permissions with Scopes (ABAC)

Instance permissions can include scopes for attribute-based conditions:

"doc:doc_123:update:draft"           # Update only when document is in draft
"doc:doc_123:read:business_hours"    # Read only during business hours
"invoice:inv_456:approve:small"      # Approve only if amount is small

Use AshGrant.Evaluator.get_instance_scope/3 to retrieve the scope condition.

Scope DSL

Define scopes inline using expr() expressions:

ash_grant do
  scope :always, true
  scope :own, expr(author_id == ^actor(:id))
  scope :published, expr(status == :published)
  scope :own_draft, [:own], expr(status == :draft)  # Inheritance
end

Context Injection for Testable Scopes

Use ^context(:key) for injectable values instead of database functions:

ash_grant do
  # Instead of: scope :today, expr(fragment("DATE(inserted_at) = CURRENT_DATE"))
  # Use injectable context:
  scope :today, expr(fragment("DATE(inserted_at) = ?", ^context(:reference_date)))
  scope :threshold, expr(amount < ^context(:max_amount))
end

Inject values at query time:

Post
|> Ash.Query.for_read(:read)
|> Ash.Query.set_context(%{reference_date: Date.utc_today()})
|> Ash.read!(actor: actor)

This enables deterministic testing by controlling the injected values.

Deny-Wins Pattern

When both allow and deny rules match, deny always takes precedence:

permissions = [
  "blog:*:*:always",           # Allow all blog actions
  "!blog:*:delete:always"      # Deny delete
]

# Result: read/update allowed, delete DENIED

Check Types

• filter_check/1 - For read actions (returns filter expression)
• check/1 - For write actions (returns true/false)

DSL Configuration

ash_grant do
  resolver MyApp.PermissionResolver       # Required
  default_policies true                   # Optional: auto-generate policies
  resource_name "custom_name"             # Optional

  scope :always, true
  scope :own, expr(author_id == ^actor(:id))
  scope :same_tenant, expr(tenant_id == ^tenant())  # Multi-tenancy

  # UI visibility — auto-generates :can_update? and :can_destroy? calculations
  can_perform_actions [:update, :destroy]

  # Or individually with custom name
  can_perform :read, name: :visible?

  # Field groups (whitelist)
  field_group :public, [:name, :department]
  field_group :sensitive, [:phone, :address], inherits: [:public]

  # Field groups (blacklist with except)
  # field_group :public, :all, except: [:salary, :ssn]
end

Related Modules

• AshGrant.Permission - Permission parsing and matching (4-part and 5-part formats)
• AshGrant.PermissionInput - Permission input with metadata for debugging
• AshGrant.Permissionable - Protocol for converting custom structs to permissions
• AshGrant.Evaluator - Deny-wins permission evaluation with field group support
• AshGrant.PermissionResolver - Behaviour for resolving permissions
• AshGrant.Check - SimpleCheck for write actions
• AshGrant.FilterCheck - FilterCheck for read actions
• AshGrant.FieldCheck - SimpleCheck for field-level authorization in field_policies
• AshGrant.Info - DSL introspection helpers (scopes, field groups, configuration)
• AshGrant.Introspect - Runtime permission introspection for UIs and APIs
• AshGrant.Explanation - Authorization decision explanation struct
• AshGrant.Transformers.AddDefaultPolicies - Policy generation transformer
• AshGrant.Transformers.AddCanPerformCalculations - CanPerform calculation generation from DSL