l402

Documentation

Index

• Constants
• Variables
• func DecodeMacIdentifier(id []byte) (uint16, [32]byte, [32]byte, error)
• type Authenticator
  • func NewAuthenticator(logger *slog.Logger, provider InvoiceProvider, cfg *Config, store Store, ...) *Authenticator
  • func (l *Authenticator) ExtractCredentials(authHeader string) (*Credentials, error)
  • func (l *Authenticator) NewChallenge(ctx context.Context, productName string, pubKeyHex string, ...) (*Challenge, error)
  • func (l *Authenticator) ValidateCredentials(ctx context.Context, creds *Credentials) error
  • func (l *Authenticator) ValidateL402Credentials(ctx context.Context, authHeader string) (string, error)
  • func (l *Authenticator) ValidateSignature(pubKeyHex, signatureHex, domain string, timestamp int64) error
• type Challenge
  • func NewChallenge(macaroon *macaroon.Macaroon, invoice *lightning.LNInvoice) *Challenge
  • func (c *Challenge) EncodedCredentials() (string, error)
  • func (c *Challenge) EncodedPaymentRequest() (string, error)
  • func (c *Challenge) HeaderKey() string
  • func (c *Challenge) HeaderValue() (string, error)
• type Config
  • func DefaultConfig() *Config
• type Credentials
  • func DecodeL402Credentials(macBase64, preimageHex string) (*Credentials, error)
  • func (c *Credentials) ValidatePreimage() error
  • func (c *Credentials) VerifyMacaroon(rootKey string) error
• type InvoiceProvider
• type Store

Constants

const (
	// ChallengeHeaderValueFormat is the format for the L402 challenge header value.
	ChallengeHeaderValueFormat = "L402 macaroon=\"%s\", invoice=\"%s\""
)

Variables

var (

	// ErrMissingAuthorizationHeader is returned when the Authorization header is
	// missing.
	ErrMissingAuthorizationHeader = errors.New("missing Authorization header")

	// ErrMissingL402Header is returned when the L402 Authorization header is
	// missing.
	ErrMissingL402Header = errors.New("missing L402 Authorization header")

	// ErrInvalidPreimage is returned when the preimage is invalid.
	ErrInvalidPreimage = errors.New("invalid preimage")
)

Functions

func DecodeMacIdentifier

func DecodeMacIdentifier(id []byte) (uint16, [32]byte, [32]byte, error)

DecodeMacIdentifier decodes the macaroon identifier into its version, payment hash and user ID.

Types

type Authenticator

type Authenticator struct {
	// contains filtered or unexported fields
}

Authenticator is an authenticator that uses L402 tokens.

func NewAuthenticator

func NewAuthenticator(logger *slog.Logger, provider InvoiceProvider,
	cfg *Config, store Store, clock utils.Clock) *Authenticator

NewAuthenticator creates a new L402 authenticator.

func (*Authenticator) ExtractCredentials

func (l *Authenticator) ExtractCredentials(authHeader string) (*Credentials,
	error)

ExtractL402Credentials extracts the L402 credentials from the Authorization header.

func (*Authenticator) NewChallenge

func (l *Authenticator) NewChallenge(ctx context.Context, productName string,
	pubKeyHex string, priceInUSDCents uint64,
	caveats map[string]string) (*Challenge, error)

NewL402Challenge creates a new L402 challenge (macaroon, invoice).

func (*Authenticator) ValidateCredentials

func (l *Authenticator) ValidateCredentials(ctx context.Context,
	creds *Credentials) error

ValidateL402Credentials validates the L402 credentials in the Authorization header.

TODO(positiveblue): add req context to check the caveats.

func (*Authenticator) ValidateL402Credentials

func (l *Authenticator) ValidateL402Credentials(ctx context.Context,
	authHeader string) (string, error)

ValidateL402Credentials validates the L402 credentials in the Authorization header.

func (*Authenticator) ValidateSignature

func (l *Authenticator) ValidateSignature(pubKeyHex, signatureHex,
	domain string, timestamp int64) error

type Challenge

type Challenge struct {
	// Macaroon is the credentials for the L402 challenge in V0.
	Macaroon *macaroon.Macaroon

	// Invoice is the Lightning invoice used as payment request for the L402
	// challenge in V0.
	Invoice *lightning.LNInvoice
}

Challenge represents an L402 challenge.

NOTE: an L402 challenge has two components: - Credentials - Payment request In the current version of the L402 protocol (V0), the credentials are a macaroon and the payment request is a Lightning Network invoice.

func NewChallenge

func NewChallenge(macaroon *macaroon.Macaroon,
	invoice *lightning.LNInvoice) *Challenge

NewChallenge creates a new L402 challenge.

func (*Challenge) EncodedCredentials

func (c *Challenge) EncodedCredentials() (string, error)

EncodedCredentials returns the encoded credentials for the L402 challenge.

func (*Challenge) EncodedPaymentRequest

func (c *Challenge) EncodedPaymentRequest() (string, error)

EncodedPaymentRequest returns the encoded payment request for the L402 challenge.

func (*Challenge) HeaderKey

func (c *Challenge) HeaderKey() string

HeaderKey returns the header key for the L402 challenge.

func (*Challenge) HeaderValue

func (c *Challenge) HeaderValue() (string, error)

HeaderValue returns the header value for the L402 challenge.

type Config

type Config struct {
	Domain string `long:"domain" description:"Domain"`
}

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig returns all default values for the Config struct.

type Credentials

type Credentials struct {
	// Macaroon is the credentials for the L402 challenge in V0.
	Macaroon *macaroon.Macaroon

	// Preimage is the preimage for the payment request.
	Preimage [32]byte

	// Version is the version of the macaroon.
	Version uint16

	// PaymentHash is the payment hash of the macaroon.
	PaymentHash [32]byte

	// Identifier is the identifier of the macaroon.
	Identifier string
}

Credentials represents the credentials for an L402 challenge in the Authorization header.

func DecodeL402Credentials

func DecodeL402Credentials(macBase64, preimageHex string) (*Credentials,
	error)

DecodeL402Credentials decodes the L402 credentials from the given encoded credentials from the Authorization header.

func (*Credentials) ValidatePreimage

func (c *Credentials) ValidatePreimage() error

VerifyPreimage checks that the preimage matches the payment hash of the macaroon.

func (*Credentials) VerifyMacaroon

func (c *Credentials) VerifyMacaroon(rootKey string) error

VerifyMacaroon verifies the macaroon with the given root key and checks that all the caveats are valid.

type InvoiceProvider

type InvoiceProvider interface {
	// CreateInvoice creates a new LN invoice for the given price and
	// description.
	CreateInvoice(ctx context.Context, amount uint64, currency string,
		description string) (*lightning.LNInvoice, error)

	// GetInvoicePreimage checks the status of a given invoice.
	GetInvoicePreimage(ctx context.Context, paymentHash string) (string, error)
}

InvoiceProvider is the interface for creating new LN invoices.

type Store

type Store interface {
	// CreateRootKey stores the root key for a given token ID.
	CreateRootKey(ctx context.Context, identifier string, rootKey string,
		encodedBaseMacaroon string) error

	// GetRootKey retrieves the root key for a given token ID.
	GetRootKey(ctx context.Context, identifier string) (string, error)
}