docs: token generalization and version field for L402 spec#21
Open
Roasbeef wants to merge 1 commit into
Open
Conversation
In this commit, we generalize the L402 protocol from macaroon-specific to token-format agnostic. The WWW-Authenticate challenge header now uses token= instead of the former macaroon= and includes a new version="0" parameter to enable future protocol evolution. Any authentication token that can commit to a payment hash may now be used, with macaroons remaining the RECOMMENDED format due to their support for delegation, attenuation, and stateless verification. We also add a new "Token Format" section (Section 5.3) to the protocol spec laying out the three requirements a token format must satisfy, and expand the backwards compatibility section with explicit rules for accepting both L402/LSAT scheme names and token=/macaroon= parameter names. The gRPC flow is simplified to use standard trailing headers (Grpc-Message + Grpc-Status: 13) with the token sent as Custom-Metadata. All supporting docs are updated to match: the auth-flow mermaid diagram now shows the version="0" and token= header format, the introduction adds a token-agnostic paragraph, and the macaroons chapter notes that its conventions are RECOMMENDED but not mandatory. The README gets a "What's New" section, a "Token Format" section, and Fewsats added to the implementations list. This aligns the spec with bLIP-0026.
Roasbeef
force-pushed
the
docs/blip-0026-spec-update
branch
from
f48f7d1 to
a7b2442
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
In this PR, we generalize the L402 protocol from macaroon-specific to
token-format agnostic based on protocol feedback. The
WWW-Authenticatechallenge header now usestoken=instead of theformer
macaroon=, and includes a newversion="0"parameter toenable future protocol evolution without breaking existing clients.
Any authentication token that can commit to a payment hash may now be
used as the credential format. Macaroons remain the RECOMMENDED default
due to their support for delegation, attenuation via caveats, and
stateless HMAC-chain verification.
The protocol spec gets several additions on top of the recent RFC-style
restructure:
token format must satisfy: commit to payment hash, stateless
verification, and scope restriction.
accepting both
L402/LSATscheme names,token=/macaroon=parameter names, and missing
versionparameters from older clients.(
Grpc-Message+Grpc-Status: 13) with the token sent asCustom-Metadata, replacing the oldgrpc-status-details-binprotoapproach.
All supporting docs, diagrams, and the README are updated to match the
new header format.