passport-lnurl-auth

A passport strategy for lnurl-auth.

Installation
Usage
- Debugging
- Remote Tunneling
  - Using SSH and a VPS
  - Using ngrok
Changelog
License
Funding

Installation

Add to your application via npm:

npm install passport-lnurl-auth --save

This will install the module and add it to your application's package.json file.

Usage

const LnurlAuth = require('passport-lnurl-auth');

passport.use(new LnurlAuth.Strategy(function(linkingPublicKey, done) {
	// The user has successfully authenticated using lnurl-auth.
	// The linked public key is provided here.
	// You can use this as a unique reference for the user similar to a username or email address.
	const user = { id: linkingPublicKey };
	done(null, user);
}));

app.use(passport.authenticate('lnurl-auth'));

app.get('/', function(req, res) {
	if (!req.user) {
		return res.send('You are not authenticated. To login go <a href="/login">here</a>.');
	}
	res.send('Logged-in');
});

app.get('/login',
	function(req, res, next) {
		if (req.user) {
			return res.redirect('/');
		}
		next();
	},
	new LnurlAuth.Middleware({
		// The externally reachable URL for the lnurl-auth middleware.
		// It should resolve to THIS endpoint on your server.
		callbackUrl: 'http://localhost:3000/login',
		// The URL of the "Cancel" button on the login page.
		// When set to NULL or some other falsey value, the cancel button will be hidden.
		cancelUrl: '/',
		// Instruction text shown below the title on the login page:
		instruction: 'Scan the QR code to login',
		// The file path to the login.html template:
		loginTemplateFilePath: path.join(__dirname, '..', 'templates', 'login.html'),
		// The number of seconds to wait before refreshing the login page:
		refreshSeconds: 5,
		// The title of the login page:
		title: 'Login with lnurl-auth',
		// The URI schema prefix used before the encoded LNURL.
		// e.g. "lightning:" or "LIGHTNING:" or "" (empty-string)
		uriSchemaPrefix: 'LIGHTNING:',
		// Use your own custom session store abstraction to get/save sessions with corresponding k1.
		// This is useful in the case of "serverless" environments.
		// See lib/stores/memory.js for implementation details.
		// If NULL, the default MemoryStore will be used.
		store: null,
		// Options object passed to QRCode.toDataURL(data, options) - for further details:
		// https://github.com/soldair/node-qrcode/#qr-code-options
		qrcode: {
			errorCorrectionLevel: 'L',
			margin: 2,
			type: 'image/png',
		},
	})
);

For a complete, working example see the simple server included with this project.

To test the end-to-end login flow with lnurl-auth, see Remote Tunneling.

Debugging

This module uses the debug module. To output all debug messages to the console, run your node app with the DEBUG environment variable:

DEBUG=passport-lnurl-auth* node your-app.js

This will output log messages as well as error messages related to this module.

Remote Tunneling

While working locally, your web application will need to be accessible by the mobile app that you will use to perform the lnurl-auth authentication. This means that the web app must be reachable from the public internet. To achieve this, you can configure remote tunneling to your localhost. There are a few ways that this can be done.

Using SSH and a VPS

You can use this method if you already have a virtual private server (VPS) with its own static, public IP address.

cat >> /etc/ssh/sshd_config << EOL
    RSAAuthentication yes
    PubkeyAuthentication yes
    GatewayPorts yes
    AllowTcpForwarding yes
    ClientAliveInterval 60
    EOL

Restart the SSH service:

service ssh restart

On your local machine, run the following command to open a reverse-proxy tunnel:

ssh -v -N -T -R 3000:localhost:3000 VPS_HOST_OR_IP_ADDRESS

This will forward all traffic to port 3000 to the VPS thru the SSH tunnel to port 3000 on your local machine.

Provide the VPS IP address + endpoint path as the callbackUrl option. For example:

app.get('/login',
	function(req, res, next) {
		if (req.user) {
			return res.redirect('/');
		}
		next();
	},
	new LnurlAuth.Middleware({
		callbackUrl: 'http://VPS_IP_ADDRESS:3000/login'
	})
);

Be sure to replace VPS_IP_ADDRESS with the actual IP address of your server.

Using ngrok

If you don't have access to your own VPS, ngrok is another possible solution. Follow the installation instructions on the project's website before continuing here. Once you have ngrok installed, you can continue with the instructions here.

To create an HTTP tunnel:

ngrok http --region eu 3000

You should see something like the following:

Provide the HTTPS tunnel URL + endpoint path as the callbackUrl option. For example:

app.get('/login',
	function(req, res, next) {
		if (req.user) {
			return res.redirect('/');
		}
		next();
	},
	new LnurlAuth.Middleware({
		callbackUrl: 'https://a9453568.eu.ngrok.io/login'
	})
);

Note that each time you open a tunnel with ngrok, your tunnel URL changes.

Changelog

See CHANGELOG.md

License

This software is MIT licensed:

A short, permissive software license. Basically, you can do whatever you want as long as you include the original copyright and license notice in any copy of the software/source. There are many variations of this license in use.

Funding

This project is free and open-source. If you would like to show your appreciation by helping to fund the project's continued development and maintenance, you can find available options here.

chill117/passport-lnurl-auth