blip-0026: L402 - Lightning HTTP 402 Protocol

[Roasbeef]

In this commit, we add a bLIP for the L402 (formerly known as LSAT) protocol. The L402 protocol presents a standardized way of adding LN micropayments to any existing HTTP-REST or gRPC API. The L402 protocol repurposes the HTTP 402 Payment Required error code with the necessary authentication headers required to bind a request's validity to the payment of an LN invoice. Macaroons are used as flexible authentication credentials (supports custom caveats, attenuation, etc) which allow an L402 reverse-proxy to validate an L402 API key without backend LN node interaction for each request (the macaroon commits to the payment hash).

[Roasbeef]

cc @wpaulino @guggero @kodylow

[niftynei]

hey yall, i've been making a L402 lib for the CLN ecosystem. Here's a bit of feedback.

• This doc contains way more than necessary to implement the L402 protocol. Sometimes more verbiage + info can be useful, but in this case it is actually a disservice towards helping people build or re-implement the spec for themselves. I say this having had to parse it to write a conforming Flask interceptor.
• the usage of the term macaroons in the spec is unnecessarily restrictive. you can use any token/hmac system that you'd like. I've been using token in my implementation.

Cool protocol, really nice that this finally is getting some proper documentation that we can do cross implementation on

[Roasbeef]

Thanks for the feedback @niftynei!

This doc contains way more than necessary to implement the L402 protocol

The latest push significantly cuts down on the size of the document. Further edits are likely possible as well near the start and end of the specification.

the usage of the term macaroons in the spec is unnecessarily restrictive

The latest iteration weakens the language around macaroons, and moves the section on a suggested structure to the appendix. You're correct that anything can be used in practice, IMO given the macaroons are already specified and standardized, I think it makes sense to nudge proxy implementations in that direction. Note that clients don't need to introspect into them at all, and just serialize them where expected. It also isn't expected the API backends rely soley on L402 for in-depth authentication, normal auth headers or cookies or w/e can still be used. The proxies are meant to be loosely coupled to the backends they support, such that any API can be put in front of a proxy and Things Just Work^TM.

[slavakurilyak]

Any updates on this since last year?

/cc @roasbeef

[ProofOfKeags]

Any updates on this since last year?

What updates are you looking for specifically?

[TheBlueMatt]

Presumably either feedback being address or the author saying they don't want to address feedback so we can merge this! :)

[Roasbeef]

@slavakurilyak Hi, I've been gathering some significant feedback from a dozen or so teams/companies actively working on integrating the protocol into their offerings. We've been meeting once a month or so to discuss improvements to the protocol and also generally how things are fairing in the wild. I plan to make future PRs to start to incorporate some of this feedback (eg: ways to handle more stateful APIs, structured information outside the macaroon caveats, etc, etc).

With all that said, I'll move to merge this in a few days (addressing the obvious typos/wording improvements suggested above), as the current text has been adequate for those seeking to actively build upon the protocol, and some felt that the lack of a merged PR meant the protocol was in an ambiguous state.