qr-handshake-auth

Passwordless login: a browser tab shows a QR code, an already-authenticated device scans it and cryptographically signs off, the browser gets a token. No password ever touches the wire. Same family as WhatsApp Web, Notion Desktop, and GitHub CLI's device authorization flow — but you own the code.

How it works

Browser (unauthenticated)          Server                Approver device (already logged in)
        |                            |                              |
        |--- POST /session --------->|                              |
        |<-- {sessionId, nonce,      |                              |
        |     qrDataUrl} ------------|                              |
        |                            |                              |
   [shows QR code]                   |                              |
        |                            |         [scans QR, decodes]  |
        |                            |<-- POST /session/:id/approve-|
        |                            |    {userId, signature}       |
        |                            |    signature = sign(         |
        |                            |      `${sessionId}:${nonce}`,|
        |                            |      device's private key)   |
        |                            |                              |
        |-- GET /session/:id/status->|                              |
        |<-- {status:"approved",     |                              |
        |     token} -----------------|                              |

The signature is verified against a public key you enrolled for that user ahead of time (e.g. when they first set up their phone as an approver device). The private key never leaves that device.

Install

npm install qr-handshake-auth express

Server setup

import express from "express";
import { createAuthRouter, InMemoryKeyRegistry } from "qr-handshake-auth";
import jwt from "jsonwebtoken";

const keyRegistry = new InMemoryKeyRegistry(); // swap for your DB in production

// One-time: when a user sets up their phone as an approver device, generate
// a keypair there and register the public half here.
// await keyRegistry.setPublicKey({ userId, publicKey, enrolledAt: Date.now() });

const app = express();
app.use(express.json());
app.use(
  "/auth/qr",
  createAuthRouter({
    keyRegistry,
    sessionTtlMs: 2 * 60 * 1000,
    issueToken: (userId) => jwt.sign({ sub: userId }, process.env.JWT_SECRET!, { expiresIn: "1h" }),
  }),
);

app.listen(3000);

Browser client (the tab showing the QR code)

import { pollForApproval } from "qr-handshake-auth";

const created = await fetch("/auth/qr/session", { method: "POST" }).then((r) => r.json());
showQrImage(created.qrDataUrl);

const result = await pollForApproval({ baseUrl: "/auth/qr", sessionId: created.sessionId });
if (result.status === "approved") {
  localStorage.setItem("token", result.token); // or set an httpOnly cookie server-side instead
}

Approver device (mobile app / companion app that's already logged in)

import { generateKeyPair, approveSession } from "qr-handshake-auth";

// Enrollment, once:
const { publicKey, secretKey } = generateKeyPair();
// send publicKey to your server to store via keyRegistry.setPublicKey(...)
// secretKey stays on-device (Keychain / Keystore / secure storage) — never sent anywhere.

// On scan:
const scannedPayload = JSON.parse(decodedQrText); // { sessionId, nonce, expiresAt }
await approveSession({
  baseUrl: "https://api.example.com/auth/qr",
  payload: scannedPayload,
  userId: currentUser.id,
  secretKey,
});

Security properties

• No password transmitted, ever. The only secret is a private key that never leaves the approver device.
• Replay-resistant. Each session has a fresh nonce; a signature is only valid for that exact sessionId:nonce pair, so a captured approval can't be replayed against a different session.
• One-time token handoff. The status endpoint hands the token to the polling browser exactly once, then marks the session consumed.
• Time-boxed. Sessions expire (sessionTtlMs, default 2 minutes) whether or not they're ever approved.
• You control token issuance. issueToken is your callback — plug in JWTs, opaque session tokens, whatever your app already uses.

Production notes

• The bundled InMemorySessionStore / InMemoryKeyRegistry are for dev/testing. Implement SessionStore and KeyRegistry against Redis or your database for anything multi-instance.
• Rate-limit POST /session and POST /session/:id/approve at your reverse proxy — this library doesn't do that for you.
• Consider binding sessions to the requesting browser (e.g. a short-lived cookie set at /session creation, checked at /status) so a QR code photographed off someone's screen can't be redeemed from an attacker's browser tab even after legitimate approval. Not included by default to keep the core protocol transport-agnostic.

Scripts

npm run build   # compile to dist/
npm test        # run the vitest suite

License

MIT