# simple_auth-magic_link

[![Tests](https://github.com/fnando/simple_auth-magic_link/workflows/ruby-tests/badge.svg)](https://github.com/fnando/simple_auth-magic_link)
[![Gem](https://img.shields.io/gem/v/simple_auth-magic_link.svg)](https://rubygems.org/gems/simple_auth-magic_link)
[![Gem](https://img.shields.io/gem/dt/simple_auth-magic_link.svg)](https://rubygems.org/gems/simple_auth-magic_link)
[![MIT License](https://img.shields.io/:License-MIT-blue.svg)](https://tldrlegal.com/license/mit-license)

Passwordless authentication for
[simple_auth](https://github.com/fnando/simple_auth).

## Installation

```bash
gem install simple_auth-magic_link
```

Or add the following line to your project's Gemfile:

```ruby
gem "simple_auth-magic_link"
```

## Usage

First, you need to copy the migration files and apply the migrations to your
database.

```console
$ rails simple_auth_magic_link_engine:install:migrations
$ rails db:migrate
```

You can configure the magic link's ttl, code generator and default purpose by
setting these options directly to `SimpleAuth::MagicLink`:

```ruby
SimpleAuth::MagicLink.tap do |magic_link|
  # Optional. By default 6 random numbers.
  magic_link.code = > { Array.new(6) { SecureRandom.random_number(0..9) }.join }

  # Optional. By default, links expires 3 minutes from now.
  magic_link.ttl = 1.minute

  # Optional. By default, uses "default".
  magic_link.purpose = :default

  # Required. The lambda that will be used to generate the magic link.
  # This will require the default url options like in
  # `Rails.application.routes.default_url_options = {host: "example.com"}`
  magic_link.url = -> { verify_email_url }

  # Required. The keyring that will be used to encrypt the user's email.
  # Generate the keyring secret and digest salt with the following command:
  # dd if=/dev/urandom bs=32 count=1 2>/dev/null | openssl base64 -A
  keyring = {"1" => "<32 bytes>"}
  magic_link.attr_keyring keyring, digest_salt: "<32 bytes>"
end
```

Then, you can create magic links by using
`magic_link = SimpleAuth::MagicLink.create!(options)`, where `options` can be:

- `email`: required. The email tied to this magic link.
- `purpose`: optional. A string that identifies the purpose of the magic link.
  Defaults to `default`. You can use this to discern links that will be used for
  other purposes (e.g. confirm an action, login, signup, etc).
- `expires_at`: optional. The code's expiration time. Defaults to three minutes
  from now.
- `code`: optional. The code that tied to this magic link. Defaults to
  [haikunate](https://github.com/fnando/haikunate).

After you create a link, you can send it by email by using `magic_link.url`.

> [!IMPORTANT]
>
> Save `magic_link.id` on the session. This id will be used later on to ensure
> that the link was generated on the same browser/device.

To verify the magic link, you can use
`email = SimpleAuth::MagicLink.verify(url: request.original_url, id: session[:magic_link_id], **options)`,
where options can be:

- `purpose`: required. The purpose of the code being verified.

If the url is valid (i.e. it hasn't been tempered and it hasn't expired), then
you'll get the email tied to the token back. Otherwise, you'll get `nil`.

> [!INFO]
>
> Verified magic links are automatically removed upon verification.

You can also verify the magic link by using just the code (maybe you sent this
by SMS instead). In this case, you need to call something like
`email = SimpleAuth::MagicLink.verify_code(code:, id: session[:magic_link_id], **options)`.
It expects the same options as `SimpleAuth::MagicLink.verify`.

To remove expires links, use `SimpleAuth::MagicLink.clean!`.

Notice that this plugin doesn't implement any mailers, so you'll need to handle
that yourself. For example, a complete flow for a login/signup process would be
something like this:

1. User fills in log-in form with email address
2. You call `magic_link = SimpleAuth::MagicLink.create!(email: params[:email])`
3. You persist the magic link id with `session[:magic_link_id] = magic_link.id`
4. You then pass this in to your mailer with something like
   `Mailer.login(magic_link).send_later`
5. On your mailer, you can then have access to the user email via
   `magic_link.email`, the code via `magic_link.code` and the signed url via
   `magic_link.url`.

## Maintainer

- [me@fnando.com](https://github.com/fnando)

## Contributors

- <https://github.com/fnando/simple_auth-magic_link/contributors>

## Contributing

For more details about how to contribute, please read
<https://github.com/fnando/simple_auth-magic_link/blob/main/CONTRIBUTING.md>.

## License

The gem is available as open source under the terms of the
[MIT License](https://opensource.org/licenses/MIT). A copy of the license can be
found at
<https://github.com/fnando/simple_auth-magic_link/blob/main/LICENSE.md>.

## Code of Conduct

Everyone interacting in the simple_auth-magic_link project's codebases, issue
trackers, chat rooms and mailing lists is expected to follow the
[code of conduct](https://github.com/fnando/simple_auth-magic_link/blob/main/CODE_OF_CONDUCT.md).