LSATs: Pseudonymous Authentication using Bitcoin Lightning Payments

For several months, we’ve worked with engineers at Lightning Labs to develop Lightning Service Authentication Tokens (LSATs). Our goal is to let users authenticate with services without requiring user accounts or storing any user data. LSATs combine Bitcoin micro-payments over Lightning, with standards such as the 402: Payment Required HTTP status code, macaroons, and authorization headers. Today we’re debuting a collection of open source tools for developers to create their own LSAT enabled applications.

Background

Authentication and Authorization are required for many web and mobile applications. Authentication establishes who is making a request, and Authorization sets the permissions for each user.

There are two notable downsides to the way modern applications implement authentication. First, they rely on third parties to store sensitive information. This information is frequently stolen or leaked, putting you at risk. Second, users’ real world identities are often linked to authentication. Tying your real identity to a third party authentication service, such as Google or Facebook, reveals information about which services you use and how often you use them.

In 2019, Tierion started working on a solution to these problems. We released Boltwall, a middleware for deploying lightning-powered paywall servers. The original version of Boltwall used a type of bearer credential, called macaroons, that were linked to lightning invoices. Requests were authorized based on whether or not the invoice was paid.

A few months later, Olaoluwa Osuntokun‏, CTO of Lightning Labs, announced a proposal for what he called “Lightning Service Authentication Tokens”. Though Boltwall was developed independently, the motivations described in the LSAT presentation closely matched our own: using lightning payments for authentication that did not rely on personal or private information.

We recognized that a single standard was necessary. After Lightning Labs announced their own implementation, we decided to move in parallel towards the same goal. We worked with the developers at Lightning Labs to advance the LSAT standard, migrated Boltwall to be LSAT-compatible, and built a toolkit that lets developers use LSATs in their own applications.

What is an LSAT?

An LSAT is an HTTP header that encodes a macaroon and corresponding lightning invoice. Proof of payment is the baseline requirement to produce a valid LSAT.

The LSAT Token

An LSAT token is made up of two parts: a macaroon and a proof of payment. Lightning payments provide a cryptographically secure way to prove payment. Each invoice generated has an associated 32-byte payment hash. To generate this hash, a random 32-byte string, known as a *preimage, *is hashed using the SHA-256 algorithm. This preimage is only revealed upon successful payment of a lightning invoice. While it’s impossible to guess the preimage, it’s trivial to prove that only that preimage could have been used to generate the invoice’s payment hash. By attaching a preimage, which can only be known by paying the corresponding invoice, to your LSAT you have satisfied the proof of payment requirement for a valid LSAT.

The Authentication Sequence

The LSAT authentication workflow will be familiar to anyone familiar with HTTP. Let’s examine the simplest LSAT authentication sequence to show how it works.

A client makes a request to a protected route on a server without any authentication.
The server returns a response with the 402: Payment Required status code (See IETF RFC 7231 for details).
The response also contains a WWW-Authenticate header (RFC 2617). In it is a “challenge” to the client that indicates the type (LSAT) and the encoded conditions that must be satisfied: a macaroon and an invoice.
The client then pays the invoice and receives a 32-byte preimage in return.
The preimage and the macaroon from the original WWW-Authenticate header are then encoded into a token. The client then sends the token in the Authorization header with a type-prefix “LSAT”.

Anyone reading this request can verify payment by matching the preimage with the hash encoded in the LSAT. The macaroon can also have other caveats encoded in it. Caveats dictate further restrictions on the use of that token such as expiration time, request origin, or service levels. Macaroons also enable delegation. This allows the client to add a caveat to their LSAT with a more restrictive condition, such as a lower service level or an earlier expiration. This amended LSAT can then be loaned to another entity to use with the same service.

Machine-to-Machine Payments in Chainpoint

Tierion began building lightning-powered authentication in 2019 when designing a new version of the Chainpoint Network that was entirely Bitcoin native.

Chainpoint lets developers anchor data to the blockchain to create a timestamp proof. A network of nodes collect and aggregate hashes, and submit anchoring transactions to the blockchain. Chainpoint operators need an incentive and payment mechanism to run the infrastructure. On-chain Bitcoin payments don’t make sense due to Bitcoin’s high transaction fees and limited throughput.

The Lightning Network lets each Chainpoint Core require micro-payments to submit a hash. With Boltwall-powered LSATs, a Core can issue an LSAT challenge to any client that wants to submit a hash. After payment, the client submits a hash in a request authorized with the LSAT. This allows each Core to verify payment for performing services. The cost to the client is a fraction of what it would be if they anchored on their own Bitcoin transaction.

With a service like Loop Out, each Core could fund its on-chain wallet used for anchoring transactions with the satoshis earned from lightning payments, thus creating a completely closed loop, BTC-native ecosystem.

Single-Use Tokens with HODL Invoices

Discerning readers may have noticed a major problem with using only a paid invoice to authorize hash submissions; a single payment could allow for unlimited submissions to a Core. The overhead of tracking invoices and hash submission requests in a distributed network is impractical. Instead, we use another protocol native to lightning to track state: HODL Invoices. Native support for HODL invoices is built directly into Boltwall’s LSAT implementation so it can be used in other projects.

The way a HODL invoice works is that they are not automatically settled, unlike a normal invoice. After a payer has paid, the *receiver *can verify the payment, but the funds are not yet available. Settlement happens when a pre-determined preimage is revealed to the *receiver. *If this never happens, the *payer *is refunded. There are many use cases for HODL invoices (see the original pull request in LND for an explanation and examples), but in Chainpoint we use them simply to track state.

In Boltwall, only LSATs with a held invoice are considered valid. Unpaid and settled invoices are invalid. When a client pays the invoice before submitting a hash to a Chainpoint Core, the invoice associated with the LSAT is in a held state. If a hash is never submitted, the payment is eventually refunded. When a hash is submitted, the invoice will be settled by Chainpoint and the preimage will be attached to the LSAT. Since settled HODL invoices are considered expired, any future requests with that LSAT will fail with a 401: Unauthorized response.

The LSAT Toolkit

Our motivation for advancing LSATs wasn’t just for using lightning payments and authentication in Chainpoint. The more applications that use LSATs, the more useful they become for everyone. Thus, we’ve decided to open source the tools we’ve developed, and empower others to create their own LSAT enabled applications. Below are the libraries we’ve published so far:

BOLTWALL

Boltwall enables Bitcoin Lightning paywalls and authentication using LSATs. Charge to access your API without requiring user accounts, API keys, credit cards, or storing any user data. All you need is a single line of code in your Expressjs server (or similar Nodejs framework such as Restify) in front of a route that you would like to protect with a paywall. An LSAT will be issued to any client request trying to access that route. Learn more about configuration, use cases, installation, and code documentation on the Boltwall Github.

NOW-BOLTWALL

now-boltwall is a command line utility to help you easily deploy a live, Boltwall-enabled server that connects to a running lnd instance. It provides tools to help retrieve and set your lnd connection credentials, setup your Boltwall configuration, and even run a quick connection to a BTCPayServer. Servers are deployed using Zeit’s Now, a serverless deployment framework with a generous free-tier. Complete documentation available on GitHub.

LSAT-JS

lsat-js is a utility library written in TypeScript and compatible with most modern browsers. It provides tools to build, parse, and verify LSATs either on the server or client-side. Code and documentation can be found on GitHub.

LSAT PLAYGROUND

We’ve even developed a client-side webapp that demonstrates all the tools available in lsat-js. LSAT Playground includes code snippets and gives you a place to interact with LSATs without having to write a single line of code. It even provides a live demo where you can pay using a testnet node to get timed access to an API protected with Boltwall. Checkout the LSAT Playground to start using LSATs today.

Conclusion

Bitcoin introduced the idea of a payment system native to the Internet. Innovative uses of Lightning show that the technology is valuable beyond financial transactions. LSATs are a step towards a world where we don’t have to trust third parties with our private information, and users have more secure and private authentication. We hope Boltwall and lsat-js is make it easy for developers to create applications built on top of a better authentication infrastructure.

Please checkout the repos on GitHub, and give us feedback! Development of Boltwall and the associated LSAT tools was led by Buck Perley. Contact Buck on Twitter if you have questions.