<div align="center"> <img src="https://github.com/user-attachments/assets/f0352656-397d-4d90-999a-d3adbae1095f"> <h1>Permit</h1> <p><strong>Plain-Elixir, DSL-less, extensible authorization library for Elixir.

</strong></p>

</div> <br/>

Purpose and usage

Provide a single source of truth of action permissions throughout your codebase, making use of Ecto to have your Phoenix Controllers and LiveViews authorize access to resources without having to repeat yourself.

Permit supports multiple integration points across the Elixir ecosystem:

Phoenix Controllers & LiveView - with support for LiveView 1.0 and Streams
GraphQL APIs - through Absinthe integration (experimental)
Custom integrations - extensible architecture for other frameworks

Configure & define your permissions

Required package: :permit.

defmodule MyApp.Authorization do
  use Permit, permissions_module: MyApp.Permissions
end

defmodule MyApp.Permissions do
  use Permit.Permissions, actions_module: Permit.Phoenix.Actions

  def can(%{role: :admin} = user) do
    permit()
    |> all(MyApp.Blog.Article)
  end

  def can(%{id: user_id} = user) do
    permit()
    |> all(MyApp.Blog.Article, author_id: user_id)
    |> read(MyApp.Blog.Article) # allows :index and :show
  end

  def can(user), do: permit()
end

Set up your controller

Requires :permit_phoenix package, and optionally :permit_ecto for sourcing authorization data from the DB.

defmodule MyAppWeb.Blog.ArticleController do
  use MyAppWeb, :controller

  use Permit.Phoenix.Controller,
    authorization_module: MyApp.Authorization,
    resource_module: MyApp.Blog.Article

  # assumption: current user is in assigns[:current_user] - this is configurable

  def show(conn, _params) do
    # At this point, the Article has already been preloaded by Ecto and checked for authorization
    # based on action name (:show).
    # It's available as the @loaded_resource assign.

    render(conn, "show.html")
  end

  def index(conn, _params) do
    # The list of Articles accessible by current user has been preloaded by Ecto
    # into the @loaded_resources assign.

    render(conn, "index.html")
  end

  # Optionally, implement the handle_unauthorized/1 callback to deal with authorization denial.
end

Set up your LiveView

Requires :permit_phoenix, and optionally :permit_ecto.

defmodule MyAppWeb.Router do
  use Phoenix.Router
  import Phoenix.LiveView.Router

  live_session :authenticated, on_mount: Permit.Phoenix.LiveView.AuthorizeHook do
    live("/articles", MyAppWeb.Blog.ArticlesLive, :index)
    live("/articles/:id", MyAppWeb.Blog.ArticlesLive, :show)
  end
end

defmodule MyAppWeb.Blog.ArticleLive do
  use Phoenix.LiveView

  use Permit.Phoenix.LiveView,
    authorization_module: MyApp.Authorization,
    resource_module: MyApp.Blog.Article,
    use_stream?: true  # Enable LiveView 1.0 Streams support

  @impl true
  def fetch_subject(session), do: # load current user

  # Both in the mount/3 callback and in a hook attached to the handle_params event,
  # authorization will be performed based on assigns[:live_action].
  # With streams enabled, :index actions will use streams instead of assigns.

  # Optionally, implement the handle_unauthorized/1 callback to deal with authorization denial.
end

Set up your GraphQL API with Absinthe

Requires :permit_absinthe, whereas :permit_ecto is automatically retrieved to provide Dataloader support - see Permit.Absinthe docs.

defmodule MyAppWeb.Schema do
  use Absinthe.Schema
  use Permit.Absinthe, authorization_module: MyApp.Authorization

  object :article do
    permit schema: MyApp.Blog.Article

    field :id, :id
    field :title, :string
    field :content, :string
    field :author_id, :id
  end

  query do
    field :article, :article do
      permit action: :read
      arg :id, non_null(:id)
      resolve &load_and_authorize/2  # Automatically loads and authorizes based on permissions
    end

    field :articles, list_of(:article) do
      permit action: :read
      resolve &load_and_authorize/2  # Returns only articles accessible by current user
    end
  end

  mutation do
    field :create_article, :article do
      permit action: :create
      arg :title, non_null(:string)
      arg :content, non_null(:string)

      # Use middleware for complex authorization scenarios
      middleware Permit.Absinthe.Middleware.LoadAndAuthorize

      resolve fn _, args, %{context: %{current_user: user}} ->
        MyApp.Blog.create_article(user, args)
      end
    end
  end
end

Quick authorization checks

Requires :permit for the basic checks, and :permit_ecto for accessible_by!/3.

# Check permissions directly
can(current_user) |> update?(article)

# Generate Ecto queries based on permissions
MyApp.Authorization.accessible_by!(current_user, :read, Article)

# Use the friendly API for multiple actions
can(current_user) |> do([:read, :update], article)

Ecosystem

Permit is designed as a modular ecosystem with multiple packages:

| Package | Version | Description | |---------|---------|-------------| | permit | | Core authorization library | | permit_ecto | | Ecto integration for database queries | | permit_phoenix | | Phoenix Controllers & LiveView integration | | permit_absinthe | | GraphQL API authorization via Absinthe |

Recent Updates

Version 0.3.3 fixed a bug in the predicate function behaviour with has-many associations not matching Permit.Ecto behaviour.

Version 0.3.2 fixed a bug in the predicate functions respecting action grouping.

Version 0.3.1 fixed a bug in the loader function.

Version 0.3 brought several major improvements:

Phoenix LiveView 1.0 support with Streams for managing large collections
Router-based action inference - automatically derive action names from Phoenix routes
Friendly can(user) |> do(action, resource) API for more readable permission checks
Enhanced performance and better error handling

See our recent blog posts for more details:

Roadmap

An outline of our development goals for both the "MVP" and further releases.

Milestone 1

The following features of Permit (along with its companion packages), originally intended as an initial backlog, has already been fulfilled:

Rule definition syntax
- [x] Defining rules for Create, Read, Update and Delete actions
- [x] Defining rules for arbitrarily named actions

[x] Authorization resolution
- [x] Authorizing a subject to perform a specific action on a resource type (i.e. struct module, Ecto schema)
- [x] Authorizing a subject to perform a specific action on a specific resource (i.e. struct, loaded Ecto record)

[x] Ecto integration
- [x] Loading and authorizing a record based on a set of params (e.g. ID) and subject
- [x] Building Ecto queries scoping accessible records based on subject and resource type
[x] Phoenix Framework integration
- Authorizing singular resource actions (e.g. show, update)
  - [x] Plug / Controller
  - [x] LiveView
- Preloading record (based on params) in singular resource actions and authorizing the specific record
  - [x] Plug/Controller
  - [x] LiveView
- Authorizing non-singular resource actions (e.g. index)
  - [x] Plug/Controller
  - [x] LiveView
- Preloading accessible records in non-singular resource actions (e.g. index)
  - [x] Plug/Controller
  - [x] LiveView
[x] Documentation
- [x] Examples of vanilla usage, Plug and Phoenix Framework integrations
- [x] Thorough documentation of the entire public API
[x] Dependency management
- [x] Introduce permit_ecto and permit_phoenix libraries providing the possibility of using the library without unneeded dependencies

Future plans

This list of planned items relates to the main Permit repository as well as to Permit.Ecto, Permit.Phoenix, [

Permit

Install / Use

README