aperture

README

Lightning Service Authentication Token (LSAT) proxy

Aperture is your portal to the Lightning-Native Web. Aperture is used in production today by Lightning Loop, a non-custodial on/off ramp for the Lightning Network.

Aperture is a HTTP 402 reverse proxy that supports proxying requests for gRPC (HTTP/2) and REST (HTTP/1 and HTTP/2) backends using the LSAT Protocol Standard. LSAT stands for: Lightning Service Authentication Token. They combine HTTP 402, macaroons, and the Lightning Network to create a new standard for authentication and paid services on the web.

LSATs are a new standard protocol for authentication and paid APIs developed by Lightning Labs. LSATs can serve both as authentication, as well as a payment mechanism (one can view it as a ticket) for paid APIs. In order to obtain a token, we require the user to pay us over Lightning in order to obtain a preimage, which itself is a cryptographic component of the final LSAT token

The implementation of the authentication token is chosen to be macaroons, as they allow us to package attributes and capabilities along with the token. This system allows one to automate pricing on the fly and allows for a number of novel constructs such as automated tier upgrades. In another light, this can be viewed as a global HTTP 402 reverse proxy at the load balancing level for web services and APIs.

Installation / Setup

lnd

• Make sure lnd ports are reachable.

aperture

• Compilation requires go 1.13.x or later.
• To build aperture in the current directory, run make build and then copy the file ./aperture from the local directory to the server.
• To build and install aperture directly on the machine it will be used, run the make install command which will place the binary into your $GOPATH/bin folder.
• Make sure port 8081 is reachable from outside (or whatever port we choose, could also be 443 at some point)
• Make sure there is a valid tls.cert and tls.key file located in the ~/.aperture directory that is valid for the domain that aperture is running on. Aperture doesn't support creating its own certificate through Let's Encrypt yet. If there is no tls.cert and tls.key found, a self-signed pair will be created.
• Make sure all required configuration items are set in ~/.aperture/aperture.yaml, compare with sample-conf.yaml.
• Start aperture without any command line parameters (./aperture), all configuration is done in the ~/.aperture/aperture.yaml file.

Documentation

Index

• Constants
• func Main()
• func SetupLoggers(root *build.RotatingLogWriter, intercept signal.Interceptor)
• func StartPrometheusExporter(cfg *PrometheusConfig) error
• type Aperture
  • func NewAperture(cfg *Config) *Aperture
  • func (a *Aperture) Start(errChan chan error) error
  • func (a *Aperture) Stop() error
  • func (a *Aperture) UpdateServices(services []*proxy.Service) error
• type AuthConfig
• type Config
  • func NewConfig() *Config
• type EtcdConfig
• type HashMailConfig
• type InvoiceClient
• type InvoiceRequestGenerator
• type LndChallenger
  • func NewLndChallenger(cfg *AuthConfig, genInvoiceReq InvoiceRequestGenerator, errChan chan<- error) (*LndChallenger, error)
  • func (l *LndChallenger) NewChallenge(price int64) (string, lntypes.Hash, error)
  • func (l *LndChallenger) Start() error
  • func (l *LndChallenger) Stop()
  • func (l *LndChallenger) VerifyInvoiceStatus(hash lntypes.Hash, state lnrpc.Invoice_InvoiceState, timeout time.Duration) error
• type PrometheusConfig
• type TorConfig

Constants

const (
	// DefaultMsgRate is the default message rate for a given mailbox that
	// we'll allow. We'll allow one message every 500 milliseconds, or 2
	// messages per second.
	DefaultMsgRate = time.Millisecond * 500

	// DefaultMsgBurstAllowance is the default burst rate that we'll allow
	// for messages. If a new message is about to exceed the burst rate,
	// then we'll allow it up to this burst allowance.
	DefaultMsgBurstAllowance = 10

	// DefaultStaleTimeout is the time after which a mailbox will be torn
	// down if neither of its streams are occupied.
	DefaultStaleTimeout = time.Hour

	// DefaultBufSize is the default number of bytes that are read in a
	// single operation.
	DefaultBufSize = 4096
)

const Subsystem = "APER"

Functions

func Main

func Main()

Main is the true entrypoint of Aperture.

func SetupLoggers

func SetupLoggers(root *build.RotatingLogWriter, intercept signal.Interceptor)

SetupLoggers initializes all package-global logger variables.

func StartPrometheusExporter

func StartPrometheusExporter(cfg *PrometheusConfig) error

StartPrometheusExporter registers all relevant metrics with the Prometheus library, then launches the HTTP server that Prometheus will hit to scrape our metrics.

Types

type Aperture

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

Aperture is the main type of the aperture service. It holds all components that are required for the authenticating reverse proxy to do its job.

func NewAperture

func NewAperture(cfg *Config) *Aperture

NewAperture creates a new instance of the Aperture service.

func (*Aperture) Start

func (a *Aperture) Start(errChan chan error) error

Start sets up the proxy server and starts it.

func (*Aperture) Stop

func (a *Aperture) Stop() error

Stop gracefully shuts down the Aperture service.

func (*Aperture) UpdateServices

func (a *Aperture) UpdateServices(services []*proxy.Service) error

UpdateServices instructs the proxy to re-initialize its internal configuration of backend services. This can be used to add or remove backends at run time or enable/disable authentication on the fly.

type AuthConfig

type AuthConfig struct {
	// LndHost is the hostname of the LND instance to connect to.
	LndHost string `long:"lndhost" description:"Hostname of the LND instance to connect to"`

	TLSPath string `long:"tlspath" description:"Path to LND instance's tls certificate"`

	MacDir string `long:"macdir" description:"Directory containing LND instance's macaroons"`

	Network string `` /* 128-byte string literal not displayed */

	Disable bool `long:"disable" description:"Whether to disable LND auth."`
}

type Config

type Config struct {
	// ListenAddr is the listening address that we should use to allow Aperture
	// to listen for requests.
	ListenAddr string `long:"listenaddr" description:"The interface we should listen on for client requests."`

	// ServerName can be set to a fully qualifying domain name that should
	// be used while creating a certificate through Let's Encrypt.
	ServerName string `long:"servername" description:"Server name (FQDN) to use for the TLS certificate."`

	// AutoCert can be set to true if aperture should try to create a valid
	// certificate through Let's Encrypt using ServerName.
	AutoCert bool `long:"autocert" description:"Automatically create a Let's Encrypt cert using ServerName."`

	// Insecure can be set to disable TLS on incoming connections.
	Insecure bool `long:"insecure" description:"Listen on an insecure connection, disabling TLS for incoming connections."`

	// StaticRoot is the folder where the static content served by the proxy
	// is located.
	StaticRoot string `long:"staticroot" description:"The folder where the static content is located."`

	// ServeStatic defines if static content should be served from the
	// directory defined by StaticRoot.
	ServeStatic bool `long:"servestatic" description:"Flag to enable or disable static content serving."`

	Etcd *EtcdConfig `group:"etcd" namespace:"etcd"`

	Authenticator *AuthConfig `group:"authenticator" namespace:"authenticator"`

	Tor *TorConfig `group:"tor" namespace:"tor"`

	// Services is a list of JSON objects in string format, which specify
	// each backend service to Aperture.
	Services []*proxy.Service `long:"service" description:"Configurations for each Aperture backend service."`

	// HashMail is the configuration section for configuring the Lightning
	// Node Connect mailbox server.
	HashMail *HashMailConfig `group:"hashmail" namespace:"hashmail" description:"Configuration for the Lightning Node Connect mailbox server."`

	// Prometheus is the config for setting up an endpoint for a Prometheus
	// server to scrape metrics from.
	Prometheus *PrometheusConfig `` /* 129-byte string literal not displayed */

	// DebugLevel is a string defining the log level for the service either
	// for all subsystems the same or individual level by subsystem.
	DebugLevel string `long:"debuglevel" description:"Debug level for the Aperture application and its subsystems."`

	// ConfigFile points aperture to an alternative config file.
	ConfigFile string `long:"configfile" description:"Custom path to a config file."`

	// BaseDir is a custom directory to store all aperture flies.
	BaseDir string `long:"basedir" description:"Directory to place all of aperture's files in."`

	// ProfilePort is the port on which the pprof profile will be served.
	ProfilePort uint16 `long:"profile" description:"Enable HTTP profiling on given port -- NOTE port must be between 1024 and 65535"`
}

func NewConfig

func NewConfig() *Config

NewConfig initializes a new Config variable.

type EtcdConfig

type EtcdConfig struct {
	Host     string `long:"host" description:"host:port of an active etcd instance"`
	User     string `long:"user" description:"user authorized to access the etcd host"`
	Password string `long:"password" description:"password of the etcd user"`
}

type HashMailConfig

type HashMailConfig struct {
	Enabled               bool          `long:"enabled"`
	MessageRate           time.Duration `long:"messagerate" description:"The average minimum time that should pass between each message."`
	MessageBurstAllowance int           `long:"messageburstallowance" description:"The burst rate we allow for messages."`
	StaleTimeout          time.Duration `long:"staletimeout" description:"The time after the last activity that a mailbox should be removed. Set to -1s to disable. "`
}

type InvoiceClient

type InvoiceClient interface {
	// ListInvoices returns a paginated list of all invoices known to lnd.
	ListInvoices(ctx context.Context, in *lnrpc.ListInvoiceRequest,
		opts ...grpc.CallOption) (*lnrpc.ListInvoiceResponse, error)

	// SubscribeInvoices subscribes to updates on invoices.
	SubscribeInvoices(ctx context.Context, in *lnrpc.InvoiceSubscription,
		opts ...grpc.CallOption) (
		lnrpc.Lightning_SubscribeInvoicesClient, error)

	// AddInvoice adds a new invoice to lnd.
	AddInvoice(ctx context.Context, in *lnrpc.Invoice,
		opts ...grpc.CallOption) (*lnrpc.AddInvoiceResponse, error)
}

InvoiceClient is an interface that only implements part of a full lnd client, namely the part around the invoices we need for the challenger to work.

type InvoiceRequestGenerator

type InvoiceRequestGenerator func(price int64) (*lnrpc.Invoice, error)

InvoiceRequestGenerator is a function type that returns a new request for the lnrpc.AddInvoice call.

type LndChallenger

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

LndChallenger is a challenger that uses an lnd backend to create new LSAT payment challenges.

func NewLndChallenger

func NewLndChallenger(cfg *AuthConfig, genInvoiceReq InvoiceRequestGenerator,
	errChan chan<- error) (*LndChallenger, error)

NewLndChallenger creates a new challenger that uses the given connection details to connect to an lnd backend to create payment challenges.

func (*LndChallenger) NewChallenge

func (l *LndChallenger) NewChallenge(price int64) (string, lntypes.Hash, error)

NewChallenge creates a new LSAT payment challenge, returning a payment request (invoice) and the corresponding payment hash.

NOTE: This is part of the mint.Challenger interface.

func (*LndChallenger) Start

func (l *LndChallenger) Start() error

Start starts the challenger's main work which is to keep track of all invoices and their states. For that the backing lnd node is queried for all invoices on startup and the a subscription to all subsequent invoice updates is created.

func (*LndChallenger) Stop

func (l *LndChallenger) Stop()

Stop shuts down the challenger.

func (*LndChallenger) VerifyInvoiceStatus

func (l *LndChallenger) VerifyInvoiceStatus(hash lntypes.Hash,
	state lnrpc.Invoice_InvoiceState, timeout time.Duration) error

VerifyInvoiceStatus checks that an invoice identified by a payment hash has the desired status. To make sure we don't fail while the invoice update is still on its way, we try several times until either the desired status is set or the given timeout is reached.

NOTE: This is part of the auth.InvoiceChecker interface.

type PrometheusConfig

type PrometheusConfig struct {
	// Enabled, if true, then Prometheus metrics will be exported.
	Enabled bool `long:"enabled" description:"if true prometheus metrics will be exported"`

	// ListenAddr is the listening address that we should use to allow the
	// main Prometheus server to scrape our metrics.
	ListenAddr string `long:"listenaddr" description:"the interface we should listen on for prometheus"`
}

PrometheusConfig is the set of configuration data that specifies if Prometheus metric exporting is activated, and if so the listening address of the Prometheus server.

type TorConfig

type TorConfig struct {
	Control     string `long:"control" description:"The host:port of the Tor instance."`
	ListenPort  uint16 `` /* 226-byte string literal not displayed */
	VirtualPort uint16 `long:"virtualport" description:"The port through which the onion services created can be reached at."`
	V3          bool   `long:"v3" description:"Whether we should listen for client requests through a v3 onion service."`
}