README.md

# SlackVerify

SlackVerify is a plug that enables [verifying Slack requests](https://api.slack.com/docs/verifying-requests-from-slack).

## Installation
Installation is a five-step process.

1) Add the dependency in your mix.deps:
```elixir
def deps do
  [
    {:slack_verify, "~> 0.2.1"}
  ]
end
```

2) Configure your application's Slack signing secret:
```elixir
# config.exs
config :slack_verify, slack_signing_secret: System.get_env("MY_SLACK_SIGNING_SECRET")
```

3) SlackVerify relies on the raw request body for signature verification. To achieve this,
configure the `body_reader` option on `Plug.Parsers`:
```elixir
plug Plug.Parsers,
  parsers: [:urlencoded, :multipart, :json],
  pass: ["*/*"],
  body_reader: {CacheBodyReader, :read_body, []}, # <-- right here
  json_decoder: Poison
```

4) Then, per [the Plug.Parsers documentation](https://hexdocs.pm/plug/Plug.Parsers.html#module-custom-body-reader) define the CacheBodyReader module like so:
```elixir
defmodule CacheBodyReader do
  def read_body(conn, opts) do
    {:ok, body, conn} = Plug.Conn.read_body(conn, opts)
    conn = update_in(conn.assigns[:raw_body], &[body | (&1 || [])])
    {:ok, body, conn}
  end
end
```

5) Plug it in!
```elixir
plug SlackVerify
```

## Common Patterns

It's advisable to configure a controller specifically to handle Slack requests. Then you can only
plug SlackVerify in your Slack controller and leave other controller logic in your app untouched.

```elixir
defmodule MyAppWeb.MySlackController do
  use MyAppWeb, :controller

  plug SlackVerify

  def handle(conn, _params) do
    text conn, "Hello, Slack!"
  end
end
```

Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
be found at [https://hexdocs.pm/slack_verify](https://hexdocs.pm/slack_verify).