# omniauth-lightning

This gem implements an Omniauth strategy to login via the Lightning Network. It uses [LNPay.co]
as the backend.

Once integrated, users of your application can submit an invoice from their own node,
this gem will decode the invoice to extract the pubkey of the user's node and use that pubkey
as the UID of the user.

Note that the user will submit Lightning Network invoices to your application, but your application
won't need to pay them.

## Installation

Add to your `Gemfile`:

```ruby
gem 'omniauth-lightning'
```

and run `bundle install`.

## Integration

Next, tell OmniAuth about this provider. For a Rails app, your `config/initializers/omniauth.rb` file should look like this:

```ruby
Rails.application.config.middleware.use OmniAuth::Builder do
  provider :lightning,
    invoice_sats_amount: 1,
    validating_text: 'my-app-auth-string',
    lnpay_key: 'my-lnpay-key' # secret api key from https://lnpay.co/dashboard/developers
end
```

This configuration will make the strategy require a `1 sat` invoice that includes the text `my-app-auth-string`
to validate the invoice.

### Configuration

The following settings are available:
```ruby
:title                      # title of the rendered form that prompts user to submit their invoice
:sats_amount                # amount of sats that the invoice should include
:validating_text            # text that should be included in the invoice's description
:invoice_max_age_in_seconds # maximum age of invoices that are accepted in seconds
:lnpay_key                  # Key from LNPay.co to use to decode invoices
```

### Error keys

The following errors might be returned from the gem; you might want to handle them on your
application to display errors:

```ruby
:invalid_invoice                 # invoice invalid
:invoice_without_required_amount # invoice wasn't for the amount specified on :sats_amount
:invoice_without_required_text   # invoice didn't include the required text specified on :validating_text
:old_invoice                     # invoice is older than :invoice_max_age_in_seconds
:custodial_wallet                # invoice was generated by a custodial wallet
```

## Customizing Invoice Form

To use your own custom invoice form, create a form that POSTs to '/auth/lightning/callback' with `invoice`.

```erb
<%= form_tag '/auth/lightning/callback' do |f| %>
  <h1>Submit your invoice</h1>
  <%= text_field_tag :invoice %>
  <%= submit_tag %>
<% end %>
```

## Example app

If you want to see an app using this gem, checkout [bitcoiners-best]. To see a live version of this, checkout https://bitcoiners.best/

## Author

Written by [@pablof7z].

[LNPay.co]: https://lnpay.co
[bitcoiners-best]: https://github.com/bitcoiners-Best/bitcoinersbest
[@pablof7z]: https://twitter.com/pablof7z