let_me

# LetMe

[![CI](https://github.com/woylie/let_me/workflows/CI/badge.svg)](https://github.com/woylie/let_me/actions) [![Hex](https://img.shields.io/hexpm/v/let_me)](https://hex.pm/packages/let_me) [![Hex Docs](https://img.shields.io/badge/hex-docs-green)](https://hexdocs.pm/let_me/readme.html) [![Coverage Status](https://coveralls.io/repos/github/woylie/let_me/badge.svg)](https://coveralls.io/github/woylie/let_me)

LetMe is an authorization library for Elixir that defines a Domain Specific
Language (DSL) for authorization rules.

Policy expressions are optimized at compile time and evaluated lazily using
[Spek](https://github.com/woylie/spek). It is possible to get the evaluated
part of the policy expression in the error case, which can be useful for
debugging, detailed error messages, or authorization decision logs.

The library also provides introspection functions that allow you to:

- List all authorization rules including their boolean expression tree for a
  documentation page.
- Fetch an authorization rule by name.
- Filter authorization rules by subject, object, or checks that are applied.

## Installation

Add LetMe to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:let_me, "~> 3.0.4"}
  ]
end
```

This package is tested against the Elixir and OTP versions that are still
supported upstream. Older versions down to the requirement in `mix.exs` may
still work, but they are not covered by CI and not officially supported.

Include LetMe in your `.formatter.exs` file:

```elixir
[
  import_deps: [:let_me]
]
```

This ensures that `mix format` does not add unnecessary parentheses to the
LetMe macro calls for policy definitions.

## Policy module

You define your authorization rules in a policy module using the LetMe macros.
These rules are compiled into [Spek](https://github.com/woylie/spek)
expressions, and functions for both authorization checks and introspection are
defined.

For instance, this is how you could define a policy for a simple article CRUD
interface:

```elixir
defmodule MyApp.Policy do
  use LetMe.Policy

  object :article do
    # Creating articles is allowed if the user role is `editor` or `writer`.
    action :create do
      allow role: :editor
      allow role: :writer
      desc "Create a new article"
    end

    # Viewing articles is always allowed, unless the user is banned.
    action :read do
      allow true
      deny :banned
      desc "Read an article"
    end

    # Updating an article is allowed if (the user role is `editor`) OR
    # (the user role is `writer` AND the article belongs to the user).
    action :update do
      allow role: :editor
      allow [:own_resource, role: :writer]
      desc "Update an article"
    end

    # Deleting an article is allowed if the user is an editor.
    action :delete do
      allow role: :editor
      desc "Delete an article"
    end
  end
end
```

You can work with a single policy module, or you can define one policy module
for each of your conte