I just released LetMe 2.0.0!

What’s New?

Internal Policy Rule Representation

The internal representation of the policy rules has been changed to a tree-like expression format using AllOf, AnyOf, Check, Literal, and Not structs. An expression might look like this:

%AllOf{
  children: [
    %Check{name: :role, arg: :admin},
    %Check{name: :two_fa}
  ]
}

Or this:

%AllOf{
  children: [
    %Not{expression: %Check{name: :suspended}},
    %Check{name: :two_fa},
    %AnyOf{
      children: [
        %Check{name: :user_type, arg: :admin},
        %Check{name: :user_type, arg: :client}
      ]
    }
  ]
}

Or just:

%Literal{passed?: true}

These expressions are generated from the policy rules you define with the macro DSL. At compile time, a few basic normalization steps are applied, for example to remove unnecessary nesting or to factorize common checks in AnyOf expressions.

Lazy Evaluation

All expressions are now evaluated lazily when an authorization check is performed.

Checks With Custom Return Values

Previously, all check functions had to return a boolean. Now, the return type is boolean | :ok | :error | {:ok, term} | {:error, term}.

Detailed Authorization Errors

By default, c:LetMe.Policy.authorize/4 still returns {:error, :unauthorized} if an authorization check fails. But there is a new error option you can pass to use LetMe to set a default value and to c:LetMe.Policy.authorize/4 and c:LetMe.Policy.authorize!/4 to override the default. The available values are:

:detailed

If you set the value to :detailed, authorize/4 returns an UnauthorizedError struct with the parts of the expression that were evaluated until a decision was made. You can find the exact return value of the check function in the result field of the Check struct. The UnauthorizedErrorexception raised by authorize!/4 also contains the expression with this option value.

defmodule MyApp.Policy
  use LetMe.Policy, error: :detailed
  
  # ...
end

iex> MyApp.Policy.authorize(:article_update, user_2, article)
{
  :error,
  %LetMe.UnauthorizedError{
    expression: %LetMe.AllOf{
      children: [
        %LetMe.Check{
          name: :role,
          arg: :admin,
          result: true,
          passed?: true
        },
        %LetMe.Check{
          name: :aal2,
          result: {:error, :aal1},
          passed?: false
        }
      ],
      passed?: false
    },
    message: "unauthorized"
  }
}

:simple

If you set the value to :simple, authorize/4 returns an UnauthorizedError struct without the expression. Likewise, authorize!/4 raises an UnauthorizedError exception without it.

defmodule MyApp.Policy
  use LetMe.Policy, error: :simple
  
  # ...
end

iex> MyApp.Policy.authorize(:article_update, user_2, article)
{:error, %LetMe.UnauthorizedError{
  message: "unauthorized",
  expression: nil
}}

any

Any other value will be used directly in the error tuple:

defmodule MyApp.Policy
  use LetMe.Policy, error: :forbidden
  
  # ...
end

iex> MyApp.Policy.authorize(:article_update, user_2, article)
{:error, :forbidden}

Upgrade from v1

The policy DSL and authorization API remain unchanged. The only breaking changes are:

• The removal of the allow and deny fields of the LetMe.Rule struct in favor of the new expression field.
• The removal of the error_reason and error_message options from use LetMe.Policy in favor of the new error option.
• The removal of the allow and deny filter options on LetMe.filter_rules/2 and
  c:LetMe.Policy.list_rules/1 in favor of a single check option.

For more details, refer to the changelog.

LetMe 1.1.0 was released, which adds a metadata macro and a metadata field to the LetMe.Rule struct, which allows you to extend the functionality of the library. Thanks to Stephen for the contribution.

Awesome Library. Looks succinct. I loved the introspection aspect and redaction of information!

I was curious about how the library will handle Role explosion and some of the scenarios mentioned below?

Say a customer comes to bar, instead of having a role depicting that they can consume alcohol, they claim that they can_drink.

We can take the claim and restrict it with policy saying, age must be drinking age, based on attribute country.

And maybe add a scope, saying that the customer can only access the drinks available on counter.

Later, bouncer might grant or revoke access on the fly!

Maybe the customer gets recognised as a VIP, so now he should have access to drinks from cellar! Perhaps they fancy a private lounge. (Instead of creating another role for people who can enter the lounge or drink special wine, they can be assigned claims like: can_enter_private_lounge)

I have a verbose way achieving the above scenarios:

P.S. I am excited about this. I won’t have to write much code. I am just trying to piece together how I can make use of the library.