Introduction to L402

L402, previously referred to as LSAT, represents a pioneering standard designed to facilitate the monetization of services and user authentication within distributed networks. This protocol ingeniously merges the robust authentication capabilities of Macaroons with the efficient payment solutions offered by the Lightning Network.

History

The L402 protocol has its roots in the early architecture of the web, specifically in the concept of the HTTP 402 error code. This error code, labeled "Payment Required," was originally included in the HTTP specification with a vision for future internet-native payment systems. However, for many years, the 402 error remained largely underutilized, as there was no widely accepted digital payment mechanism that could be integrated seamlessly into web protocols.

The advent of Bitcoin and the Lightning Network, however, provided the missing piece of the puzzle, offering a decentralized, internet-native currency capable of facilitating microtransactions and rapid payments.

Building on this foundation, the L402 protocol emerged as a modern solution to activate the long-dormant potential of the HTTP 402 error. It was developed by Lightning Labs to address the need for a standardized method of charging for services and authenticating users in distributed networks, particularly in scenarios where traditional payment and authentication methods were cumbersome or inefficient. The protocol, initially known as LSAT (Lightning Service Authentication Tokens), combined the flexible and secure authentication capabilities of Macaroons with the efficiency and scalability of the Lightning Network's payment system. This innovation marked a significant step forward in the practical application of HTTP 402, transforming it from a theoretical concept into a tool for building the machine-payable web of the future.

Building Blocks

Macaroons: Flexible Authentication Tokens

Macaroons are a central component of the L402 protocol, serving as highly flexible and secure authentication tokens. Unlike traditional authentication methods like cookies, Macaroons offer several advanced features:

• Contextual Caveats: Macaroons allow the embedding of "caveats" that constrain and specify the token's permissions. This feature enables fine-grained control over what actions an authenticated user can perform.
• Delegability: They can be delegated or attenuated, meaning a Macaroon's permissions can be reduced or extended by the bearer under certain conditions, making them highly adaptable for various use cases.
• Decentralized Verification: Macaroons can be verified using only a root key and basic cryptography, eliminating the need for a central database to check each token's validity. This aspect is particularly beneficial for distributed systems.

Lightning API Keys: Integrating Payment with Authentication

Lightning API Keys are an innovative aspect of the L402 protocol, representing a fusion of authentication and payment verification:

• Combination with Preimages: A Lightning API Key is a Macaroon that includes a payment hash from a Lightning Network invoice. For the Macaroon to become valid (i.e., for the API key to be activated), it must be presented along with the preimage of the payment hash, which is obtained only after the corresponding invoice is paid on the Lightning Network.
• Streamlined Verification Process: This design ensures that the verification of payment and user authentication can be conducted simultaneously. When a user presents a Lightning API Key, the service provider can easily verify both the authenticity of the Macaroon and the completion of the required payment.
• Enhanced Security and Efficiency: By tying the Macaroon's validity to a Lightning Network payment, the L402 protocol ensures a higher level of security and efficiency. It eliminates the need for service providers to separately track and validate payments, as the cryptographic validity of the Macaroon itself guarantees that the payment has been made.

Protocol Data Flow

The L402 protocol works in this way:

1. Issuance of Macaroon and Invoice: The service provider issues a Macaroon, which includes a specific payment hash, along with a corresponding Lightning Network invoice.
2. Payment by User: The user pays the invoice through the Lightning Network.
3. Receipt of Preimage: Upon successful payment of the invoice, the user receives a cryptographic preimage, which serves as proof of payment.
4. Activation of Lightning API Key: The user combines the received preimage with the initially issued Macaroon. This combination activates the Macaroon, turning it into a valid Lightning API Key.
5. Presentation for Service Access: The user presents this activated Lightning API Key to the service provider in order to gain access to the service.
6. Verification by Service Provider: The service provider verifies the integrity of the Macaroon and checks the embedded payment hash against the provided preimage. This step confirms both the user's identity and the completion of the payment.
7. Access Granted: Upon successful verification, the user is granted access to the requested service, completing the transaction process.

Specification

The "L402" authentication scheme is designed to transmit credentials in the format <macaroon(s)>:<preimage>.

In this format:

• The 'Preimage' is encoded in hexadecimal.
• The 'Macaroon' is encoded in base64.
• If multiple Macaroons are used, they are individually base64 encoded and listed as comma-separated values before the colon.

Utilization of RFC 7235 Authentication Framework

In challenges, the scheme name used is "L402", which is case-insensitive. The credentials syntax is defined as follows:

Macaroons: <base64 encoding>, comma-separated if multiple Macaroons are present.

Preimage: <hex encoding>

Token: "macaroons":"preimage"

This syntax is akin to the "token68" syntax used in HTTP basic auth.

Security Considerations

It's crucial to use the L402 scheme in conjunction with a secure system like TLS. Without such a system, the Macaroon and preimage are vulnerable as they are transmitted in cleartext over the network.

Reusing Credentials

L402 credentials are designed for reuse until revocation. The server issues a new challenge if the L402 becomes invalid, triggered by conditions like expiry, exceeding usage limits, or the need for a tier upgrade. Specific revocation conditions and other details are further elaborated in the higher-level design document.

Flexibility and Application

L402 can be configured either per backend service or for all Lightning Labs services. This flexibility is possible because all services are verified by the same L402 proxy, which checks all Macaroons for each service.

The role of Sulu

Sulu plays a pivotal role in the ecosystem of the L402 protocol by acting as a reverse proxy that simplifies the monetization of API endpoints. It serves as a bridge between API providers and consumers, leveraging the L402 protocol to enable seamless transactions.

For API providers, Sulu offers a suite of tools that streamline the process of integrating Lightning Network payments into their services, effectively monetizing their APIs without delving into the complexities of the payment system.

Similarly, for consumers, Sulu provides an accessible platform to utilize these monetized APIs, handling the intricacies of L402 and Lightning Network transactions on their behalf. By abstracting the technical details of the Lightning Network and payment processes, Sulu allows both providers and consumers to focus on their core products and services, ensuring a smooth, efficient, and user-friendly experience in the API economy.

Further Reading

• L402
• Protocol specification