aperture

README

Lightning Service Authentication Token (LSAT) proxy

Aperture is your portal to the Lightning-Native Web. Aperture is used in production today by Lightning Loop, a non-custodial on/off ramp for the Lightning Network.

Aperture is a HTTP 402 reverse proxy that supports proxying requests for gRPC (HTTP/2) and REST (HTTP/1 and HTTP/2) backends using the LSAT Protocol Standard. LSAT stands for: Lightning Service Authentication Token. They combine HTTP 402, macaroons, and the Lightning Network to create a new standard for authentication and paid services on the web.

LSATs are a new standard protocol for authentication and paid APIs developed by Lightning Labs. LSATs can serve both as authentication, as well as a payment mechanism (one can view it as a ticket) for paid APIs. In order to obtain a token, we require the user to pay us over Lightning in order to obtain a preimage, which itself is a cryptographic component of the final LSAT token

The implementation of the authentication token is chosen to be macaroons, as they allow us to package attributes and capabilities along with the token. This system allows one to automate pricing on the fly and allows for a number of novel constructs such as automated tier upgrades. In another light, this can be viewed as a global HTTP 402 reverse proxy at the load balancing level for web services and APIs.

Installation / Setup

lnd

• Make sure lnd ports are reachable.

aperture

• Compilation requires go 1.13.x or later.
• To build aperture in the current directory, run make build and then copy the file ./aperture from the local directory to the server.
• To build and install aperture directly on the machine it will be used, run the make install command which will place the binary into your $GOPATH/bin folder.
• Make sure port 8081 is reachable from outside (or whatever port we choose, could also be 443 at some point)
• Make sure there is a valid tls.cert and tls.key file located in the ~/.aperture directory that is valid for the domain that aperture is running on. Aperture doesn't support creating its own certificate through Let's Encrypt yet. If there is no tls.cert and tls.key found, a self-signed pair will be created.
• Make sure all required configuration items are set in ~/.aperture/aperture.yaml, compare with sample-conf.yaml.
• Start aperture without any command line parameters (./aperture), all configuration is done in the ~/.aperture/aperture.yaml file.

Demo

There is a demo installation available at test.swap.lightning.today:11010.

Use Case 1: Web GUI

If you visit the demo installation in the browser, you see a simple web GUI. There you can request the current BOS scores for testnet. Notice that you can only request the scores three times per IP addres. After the free requests have been used up, you receive an LSAT token/macaroon and are challenged to pay an invoice to authorize it.

You have two options to pay for the invoice:

1. If you have Joule installed in your browser and connected to a testnet node, you can click the "Pay invoice with Joule" button to pay the invoice. After successful payment the page should automatically refresh.
2. In case you want to pay the invoice manually, copy the payment request to your wallet of choice that has the feature to reveal the preimage after a successful payment. Copy the payment preimage in hex format, then click the button "Paste preimage of manual payment" and paste it in the dialog box.

Use Case 2: cURL

First, let's request the BOS scores until we hit the freebie limit:

curl -k -v https://test.swap.lightning.today:11010/availability/v1/btc.json

At some point, we will get an answer 402 with an authorization header:

www-authenticate: LSAT macaroon="...", invoice="lntb10n1..."

We will need both these values, the macaroon and the invoice so copy them to a text file somewhere (without the single quotes!). Let's pay the invoice now, choose any LN wallet that displays the preimage after a successful payment. Copy the hex encoded preimage to the text file too once you get it from the wallet.

Finally, you can issue the authenticated request with the following command:

curl -k -v \
--header "Authorization: LSAT <macaroon>:<preimage>" \
https://test.swap.lightning.today:11010/availability/v1/btc.json

Documentation

Index

• Constants
• func Main()
• type InvoiceClient
• type InvoiceRequestGenerator
• type LndChallenger
  • func NewLndChallenger(cfg *authConfig, genInvoiceReq InvoiceRequestGenerator, errChan chan<- error) (*LndChallenger, error)
  • func (l *LndChallenger) NewChallenge(price int64) (string, lntypes.Hash, error)
  • func (l *LndChallenger) Start() error
  • func (l *LndChallenger) Stop()
  • func (l *LndChallenger) VerifyInvoiceStatus(hash lntypes.Hash, state lnrpc.Invoice_InvoiceState, timeout time.Duration) error

Constants

const Subsystem = "APER"

Functions

func Main

func Main()

Main is the true entrypoint of Aperture.

Types

type InvoiceClient

type InvoiceClient interface {
	// ListInvoices returns a paginated list of all invoices known to lnd.
	ListInvoices(ctx context.Context, in *lnrpc.ListInvoiceRequest,
		opts ...grpc.CallOption) (*lnrpc.ListInvoiceResponse, error)

	// SubscribeInvoices subscribes to updates on invoices.
	SubscribeInvoices(ctx context.Context, in *lnrpc.InvoiceSubscription,
		opts ...grpc.CallOption) (
		lnrpc.Lightning_SubscribeInvoicesClient, error)

	// AddInvoice adds a new invoice to lnd.
	AddInvoice(ctx context.Context, in *lnrpc.Invoice,
		opts ...grpc.CallOption) (*lnrpc.AddInvoiceResponse, error)
}

InvoiceClient is an interface that only implements part of a full lnd client, namely the part around the invoices we need for the challenger to work.

type InvoiceRequestGenerator

type InvoiceRequestGenerator func(price int64) (*lnrpc.Invoice, error)

InvoiceRequestGenerator is a function type that returns a new request for the lnrpc.AddInvoice call.

type LndChallenger

type LndChallenger struct {
	// contains filtered or unexported fields
}

LndChallenger is a challenger that uses an lnd backend to create new LSAT payment challenges.

func NewLndChallenger

func NewLndChallenger(cfg *authConfig, genInvoiceReq InvoiceRequestGenerator,
	errChan chan<- error) (*LndChallenger, error)

NewLndChallenger creates a new challenger that uses the given connection details to connect to an lnd backend to create payment challenges.

func (*LndChallenger) NewChallenge

func (l *LndChallenger) NewChallenge(price int64) (string, lntypes.Hash, error)

NewChallenge creates a new LSAT payment challenge, returning a payment request (invoice) and the corresponding payment hash.

NOTE: This is part of the mint.Challenger interface.

func (*LndChallenger) Start

func (l *LndChallenger) Start() error

Start starts the challenger's main work which is to keep track of all invoices and their states. For that the backing lnd node is queried for all invoices on startup and the a subscription to all subsequent invoice updates is created.

func (*LndChallenger) Stop

func (l *LndChallenger) Stop()

Stop shuts down the challenger.

func (*LndChallenger) VerifyInvoiceStatus

func (l *LndChallenger) VerifyInvoiceStatus(hash lntypes.Hash,
	state lnrpc.Invoice_InvoiceState, timeout time.Duration) error

VerifyInvoiceStatus checks that an invoice identified by a payment hash has the desired status. To make sure we don't fail while the invoice update is still on its way, we try several times until either the desired status is set or the given timeout is reached.

NOTE: This is part of the auth.InvoiceChecker interface.