Diving Deep into Lightning Service Authentication Tokens--LSATs

Lightning Service Authentication Tokens (LSATs) are a new authentication method that uses lightning network micropayments instead of traditional user accounts. LSATs allow services to authenticate requests without storing sensitive user data. This post dives deeper into how LSATs work with detailed examples and an overview of the open source LSAT toolkit.

What is an LSAT?

An LSAT token contains two key components:

The Macaroon

• Encodes caveats like permissions, restrictions, and expiration time.

• Allows delegation through adding caveats.

• Example caveat: Only allow requests from a specific IP address.

The Proof of Payment

• A preimage that proves a specific lightning invoice was paid.

• Generated when the invoice is created, hashed to make invoice payment hash.

• Revealed only when invoice is paid.

• Impossible to determine preimage without paying invoice.

Walkthrough of the LSAT Authentication Flow

Let's walk through a detailed example of the authentication sequence:

1. Client makes GET request to /protected-endpoint on the server.

2. Server returns 402 Payment Required status code.

3. Server provides WWW-Authenticate header with:

• A randomly generated macaroon requiring payment.

• A lightning invoice with hash lnbc10u1psd...9w2dpsd

4. Client application pays lightning invoice, receives preimage 11a7ab...f43ac9

5. Client application encodes macaroon and preimage into LSAT token.

6. Client sends GET request to /protected-endpoint with Authorization header:

   Authorization: LSAT macaroon="eyJpd...f5K", preimage="11a7ab...f43ac9"

7. Server verifies preimage matches hash of paid invoice. Macaroon caveats are also enforced.

8. Request authenticated! Server provides access to protected endpoint.

Prevent Reuse with HODL Invoices

By default, LSATs use HODL invoices to prevent reuse:

• Invoice is held after payment until explicitly settled later.

• Held invoice LSATs are valid, settled/unpaid are invalid.

• Invoice settled after request, LSAT can't be reused.

Sequence

1. Client pays HODL invoice, submits request.

2. Server verifies LSAT, handles request.

3. Server settles invoice to invalidate LSAT.

This ensures a single payment can't be used for multiple requests.

LSAT Toolkit for Developers

Several open source libraries enable LSAT adoption:

Boltwall

Express middleware to add LSAT authentication to Node.js/JavaScript apps https://github.com/Tierion/boltwall. Usage:

app.use('/protected', boltwall(), (req, res) => {
  // Handle authorized request
})

now-boltwall

Tool for deploying Boltwall servers to Zeit Now. Connects to your LND node. https://github.com/Tierion/now-boltwall

lsat-js

JavaScript library for building and verifying LSAT tokens in apps. Can be used in frontends and backends. https://github.com/Tierion/lsat-js

LSAT Playground

Test LSAT transactions with a demo service and real BTC payments. Great for learning. https://lsat-playground.bucko.vercel.app/

Conclusion

LSATs are a powerful new authentication primitive with significant advantages over traditional methods. The open source tools make adoption simple and make decentralized, private auth a reality. As LSAT usage grows, devs have an opportunity to replace auth systems and give users control over their identities.