README.md

# Password [![hex.pm](https://img.shields.io/hexpm/v/password.svg?style=flat-square)](https://hex.pm/packages/password) [![hexdocs.pm](https://img.shields.io/badge/docs-latest-green.svg?style=flat-square)](https://hexdocs.pm/password)

Flexible password policies for Elixir.

## Installation

Add to your `mix.exs`:

```elixir
def deps do
  [
    {:password, "~> 1.0"}
  ]
end
```

If you're not using [application inference](https://elixir-lang.org/blog/2017/01/05/elixir-v1-4-0-released/#application-inference), then add `:password` to your `applications` list.

## Usage

Create a new file and define a module like so:

```elixir
defmodule MyApp.Password do
  use Password, [
    # Policies
  ]

end
```

The empty list is where password policies go. For example:

```elixir
defmodule MyApp.Password do
  use Password, [
    {Password.Policy.SpecialCharacters}
  ]

end
```

To run the policies agains an input, use the `validate/1` function:

```elixir
iex> MyApp.Password.validate("password")
{:error, [Password.Policy.SpecialCharacters]}

iex> MyApp.Password.validate("password$")
:ok
```

To learn more about the included password policies and how to configure them,
see below.

## Password policies

Password's Policy modules are essentially middleware that you can plug
in or extend to create your own. At moment, the current modules are included:

- [Password.Policy.Length](https://hexdocs.pm/password/Password.Policy.Length.html) - verifies input is of minimum length
- [Password.Policy.SpecialCharacters](https://hexdocs.pm/password/Password.Policy.SpecialCharacters.html) - verifies input includes 1 (or more) special characters
- [Password.Policy.CommonPasswords](https://hexdocs.pm/password/Password.Policy.CommonPasswords.html) - verifies input is not one of the most common used passwords

Check documentation on [hexdocs](https://hexdocs.pm/password/api-reference.html).

To create your own password policies, simply create a module that implements the `Password.Policy` behaviour and provide the `validate/2` function. See source of included modules as an example.

## About

<img src="http://cdn.heresy.io/media/logo.png" alt="Heresy logo" width=300>

This project is sponsored by [Heresy](http://heresy.io). We're always looking for great engineers to join our team, so if you love Elixir, open source and enjoy some challenge, drop us a line and say hello!

## License

* Password: See LICENSE file.
* "Heresy" name and logo: Copyright © 2018 Heresy Software Ltd