Login with Lightning ⚡

Prove you control this key.

You can't access an account without authentication. login-with-lightning is the gate — drop-in LNURL-auth for any website. Users scan a QR code with their Lightning wallet and they're in. No emails, no passwords, no third-party OAuth. Just cryptographic key pairs and the open Lightning protocol.

Part of the constraint chain: identity (login-with-lightning) enables trust (ai-wot) enables payment (lightning-agent).

Installation

npm install login-with-lightning

Peer dependencies: express (v4+)

Quick Start

Server (Express)

const express = require('express');
const { lightningAuth } = require('login-with-lightning/server');

const app = express();

const auth = lightningAuth({
  callbackUrl: 'https://yoursite.com/auth/lightning/verify',
  jwtSecret: 'your-secret-key-change-this'
});

app.use('/auth', auth);

// Protected route
app.get('/api/me', auth.requireAuth, (req, res) => {
  res.json({ pubkey: req.user.pubkey });
});

app.listen(3000);

Client (Script Tag)

<script src="/path/to/widget.js"></script>

<div id="login"></div>

<script>
  LightningLoginWidget.create('#login', {
    endpoint: '/auth/lightning',
    onSuccess: (token, pubkey) => {
      console.log('Authenticated!', pubkey);
    }
  });
</script>

Client (ES Module / Bundler)

const { LightningLoginWidget } = require('login-with-lightning/client');

const widget = new LightningLoginWidget({
  endpoint: '/auth/lightning',
  onSuccess: (token, pubkey) => {
    console.log('Authenticated!', pubkey);
  }
});

widget.mount('#login');

React

const { LightningLogin, useLightningAuth } = require('login-with-lightning/client/react');

function App() {
  const { token, pubkey, logout } = useLightningAuth();

  return (
    <div>
      <LightningLogin
        endpoint="/auth/lightning"
        theme="dark"
        onSuccess={(token, pubkey) => console.log('Logged in!', pubkey)}
      />
      {pubkey && <p>Logged in as {pubkey}</p>}
      {token && <button onClick={logout}>Logout</button>}
    </div>
  );
}

Demo

Run the included demo to see it in action:

cd demo
npm install
node server.js
# Open http://localhost:3000

API Reference

Server

lightningAuth(options)

Creates Express router middleware with LNURL-auth routes.

Options:

Option	Type	Default	Description
callbackUrl	string	required	Public URL wallets will call back to (must be /auth/lightning/verify)
jwtSecret	string	required	Secret for signing JWT tokens
jwtExpiresIn	string	'24h'	JWT token lifetime (e.g. '1h', '7d')
challengeTtlMs	number	300000	Challenge validity in milliseconds (default 5 min)
onAuth	function	null	Callback (pubkey, token) fired on successful authentication

Routes created:

Route	Description
GET /lightning	Generate challenge — returns { k1, lnurl, expiresAt, qr }
GET /lightning/verify	Wallet callback — verifies signature, returns { status: "OK" }
GET /lightning/status/:k1	Frontend polling — returns { status, token?, pubkey? }

Utilities on the router:

• router.requireAuth — Express middleware that checks Authorization: Bearer <token> header. Sets req.user with { pubkey, iat, exp }.
• router.verifyToken(token) — Manually verify a JWT. Returns decoded payload or null.

Client

new LightningLoginWidget(options)

Creates a login widget instance.

Options:

Option	Type	Default	Description
endpoint	string	'/auth/lightning'	Server auth endpoint path
theme	string	'dark'	'dark' or 'light'
buttonText	string	'Login with Lightning ⚡'	Button label
title	string	'Login with Lightning ⚡'	Modal title
subtitle	string	'Scan with your Lightning wallet'	Modal subtitle
pollInterval	number	2000	Status polling interval in ms
storageKey	string	'lwl_token'	localStorage key for persisting JWT
storeToken	boolean	true	Whether to store the JWT in localStorage
onSuccess	function	null	Callback (token, pubkey) on successful auth
onError	function	null	Callback (error) on failure
onCancel	function	null	Callback when user closes modal
accentColor	string	null	Custom accent color (CSS color value)
css	string	null	Custom CSS to inject instead of defaults

Methods:

Method	Description
mount(target)	Mount the button into a DOM element (selector string or element)
unmount()	Remove the widget and clean up
open()	Programmatically open the login modal
closeModal()	Close the modal
getToken()	Get the stored JWT token
logout()	Remove stored token and re-render button

Static:

• LightningLoginWidget.create(selector, options) — Create and mount in one call.

React Component

<LightningLogin />

React component wrapping the vanilla widget. Accepts all widget options as props.

useLightningAuth(storageKey?)

React hook that returns { token, pubkey, logout }.

How LNURL-auth Works

LNURL-auth (LUD-04) is a passwordless authentication protocol:

1. Server generates a challenge — a random 32-byte k1 value, encoded as an LNURL (bech32-encoded URL)
2. User scans QR code — their Lightning wallet reads the LNURL and extracts the challenge
3. Wallet signs the challenge — using secp256k1 (the same cryptography as Bitcoin), the wallet signs k1 with the user's private key
4. Wallet sends signature back — GET callback?k1=...&sig=...&key=...
5. Server verifies — checks the signature against the public key. If valid, the user is authenticated
6. Session established — server issues a JWT containing the user's public key

The user's identity is their public key. No personal information is exchanged. Different services see different derived keys (per the LNURL-auth spec), preserving privacy.

Security Considerations

• JWT Secret: Use a strong, random secret in production. Never use the demo default.
• HTTPS Required: The callbackUrl must be HTTPS in production. Lightning wallets won't call back to HTTP URLs (except localhost for development).
• Challenge Expiry: Challenges expire after 5 minutes by default. Adjust challengeTtlMs as needed.
• One-time Use: Each challenge can only be used once. Replaying a signature will fail.
• Token Storage: JWTs are stored in localStorage by default. For higher security, set storeToken: false and handle storage yourself (e.g., httpOnly cookies via your server).
• No Password Equivalent: Unlike passwords, LNURL-auth keys can't be phished — each domain gets a unique derived key, and the signing happens entirely in the user's wallet.

Compatible Wallets

Any wallet supporting LNURL-auth (LUD-04), including:

• Phoenix
• Zeus
• Breez
• BlueWallet
• Alby (browser extension)
• Blixt
• And many more

Package Structure

login-with-lightning/
  src/
    server/
      middleware.js    — Express middleware
      jwt.js          — JWT helpers
      index.js        — Server exports
    client/
      widget.js       — Vanilla JS widget (includes built-in QR generator)
      widget.css      — Standalone CSS file
      react.jsx       — React wrapper component
      index.js        — Client exports
    index.js          — Package entry point
  demo/
    server.js         — Demo Express server
    public/
      index.html      — Demo page
  LICENSE             — MIT
  README.md

License

MIT