defmodule PlugGPGVerify do
@moduledoc """
plug_gpg_verify does the work of verifing a public key by generating a random
challenge, sending that challenge to the user and expecting the response, having
the client sign the challenge and send it back, then verifying the signature.
This makes a couple of assumptions:
1. GPG is setup and working correctly on your system.
- this uses [gpgmex](https://hexdocs.pm/gpgmex/GPG.html) which requires the rust toolchain installed and working
2. The public key we are validating has already been imported
What this is **NOT**
1. This is **NOT** a way to authenticate. Authentication is left as an excersise to the user of the library
2. This does **NOT** in any way import PGP keys, or verify that the email associated with the public_key
is valid.
## Example Usage
Put this plug somewhere in your router
```elixir
scope "/verify" do
pipe_through(:api)
forward "/", PlugGPGVerify, adapter: MyProject.GPGVerificationPlug
end
```
Create a module that implements the PlugGPGVerify behaviour
```elixir
defmodule MyProject.GPGVerificationPlug do
use PlugGPGVerify
@impl true
def find_user_by_email(email) do
case Repo.get_by(User, :email, email) do
nil -> {:error, :not_found}
user -> {:ok, %{id: user.id, email: user.email}}
end
end
@impl true
def challenge_created(user, challenge) do
changeset = User.changeset(
%User{id: user.id, email: user.email},
%{
challenge: plain_text_challenge,
challenge_expiration: DateTime.add(DateTime.utc_now(), 1, :hour)
}
)
Repo.update(changeset)
end
@impl true
def find_user_by_id(id) do
case Repo.get(User, id) do
nil -> {:error, :not_found}
user ->
# verify expiration
{:ok, %{id: user.id, email: user.email, challenge: challenge}}
end
end
@impl true
def gpg_verified(conn, user) do
# do whatever you want with the connection
token = Phoenix.Token.sign(MyAppWeb.Endpoint, "user auth", user.id)
conn
|> put_status(200)
|> Controller.json(%{token: token})
end
end
```
Your application accepts two new requests at `/verify` (or whatever route you defined):
* GET /verify?email="user@email.com"
* POST /verify
### GET /verify
If a user is found (via the `c:find_user_by_email/1` callback),
AND they have a public_key configured on the system, a new challenge is generated and encrypted.
A 201 is sent back with a JSON response of:
```json
{
challenge: string,
user_id: string
}
```
### POST /verify
This accepts a json body of:
```json
{
challenge_response: string,
user_id: string
}
```
where challenge_response is the signed challenge
## Flow Diagram
```mermaid
sequenceDiagram
Client->>Server: GET /verify?email=example@email.com
Server->>Client: {user_id: 1234, challenge: "challenge string"}
Client->>Server: POST /verify {user_id: 1234, challenge_response: "-----BEGIN PGP MESSAGE----- ..."}
Server->>Client: 200
```
"""
@behaviour Plug
alias Plug.Conn
alias PlugGPGVerify.Verification
@impl Plug
def init(adapter: adapter), do: adapter
def init(_), do: raise("adapter is a required option for PlugGPGVerify")
@impl Plug
def call(%{method: method} = conn, module) do
case validate_method(method) do
:invalid -> Verification.invalid_method(conn)
:get -> Verification.generate_challenge(conn, module)
:post -> Verification.validate_challenge(conn, module)
end
end
@spec validate_method(String.t()) :: :get | :post | :invalid
defp validate_method(method) do
case String.downcase(method) do
"get" -> :get
"post" -> :post
_other -> :invalid
end
end
@typep email :: binary()
@typep id :: any()
@type challenge() :: binary()
@typedoc """
The entity passed between the plug and the callbacks
"""
@type user :: %{id: id(), email: email(), challenge: challenge()}
@doc """
Find a user based on the email sent in the GET request
Typically this is would call into the database to find a user and that user should have a public_key.
Then it is mapped to a `t:PlugGPGVerify.user/0` and returned in an `:ok` tuple.
If this returns an error, a 406 is sent back to the client.
"""
@callback find_user_by_email(email()) :: {:ok, user()} | {:error, any()}
@doc """
Find a user based on the id sent back via the POST request.
When the client sends the POST request, the are required to send the id of the user back
instead of relying on the email. This callback is called to get the `t:PlugGPGVerify.user/0`
including the orginial `t:PlugGPGVerify.challenge/0` created.
Most implementations will also verify that the challenge hasn't expired based on their own
rules.
If an `{:ok, user}` is returned, verification continues
If an `{:error, reason}` is returned, a 401 is sent back to the client
"""
@callback find_user_by_id(id()) :: {:ok, user()} | {:error, any()}
@doc """
Called when the challenge is successfully created.
It is expected that the implementation stores the challenge somewhere to be recalled when
`c:find_user_by_id/1` is called during the POST request.
It is also recommended to store an expiration date with the challenge.
"""
@callback challenge_created(user(), challenge()) :: :ok | {:error, binary()}
@doc """
Called when the GPG public key has been verified because the challenge matches.
This is the final step in the happy path of verification.
This will return the `Plug.Conn` and it's up to the implementation to handle next steps.
Most implementations will likely generate a token, return it to the user and store it in the session/db.
"""
@callback gpg_verified(Conn.t(), user()) :: Conn.t()
defmacro __using__(_) do
quote location: :keep do
require unquote(__MODULE__)
@behaviour PlugGPGVerify
end
end
end
