mkdir magic-link-auth && cd magic-link-auth
npm init -y
npm install express auth-verify dotenv
npm install -D typescript @types/express @types/node ts-node

npx tsc --init

// src/config/types.ts
export interface AuthConfig {
  secretKey: string;
  baseUrl: string;
  tokenExpiry: string;
  storageBackend: 'memory' | 'redis';
}

export interface EmailTransportConfig {
  provider: 'smtp' | 'gmail' | 'api';
  senderAddress: string;
  credentials: Record<string, string | number | boolean>;
}

// src/auth/MagicLinkManager.ts
import AuthVerify from 'auth-verify';
import { AuthConfig, EmailTransportConfig } from '../config/types';

export class MagicLinkManager {
  private instance: AuthVerify;

  constructor(config: AuthConfig) {
    this.instance = new AuthVerify({
      mlSecret: config.secretKey,
      mlExpiry: config.tokenExpiry,
      appUrl: config.baseUrl,
      storeTokens: config.storageBackend
    });
  }

  public configureTransport(transport: EmailTransportConfig): void {
    const baseConfig = {
      service: transport.provider,
      sender: transport.senderAddress,
      ...transport.credentials
    };

    this.instance.magic.sender(baseConfig);
  }

  public async initiateLogin(targetEmail: string, templateOptions?: { subject?: string; html?: string }): Promise<void> {
    await this.instance.magic.send(targetEmail, templateOptions || {});
  }

  public async validateToken(token: string): Promise<Record<string, unknown>> {
    return await this.instance.magic.verify(token);
  }
}

// src/routes/authRoutes.ts
import { Router, Request, Response } from 'express';
import { MagicLinkManager } from '../auth/MagicLinkManager';

const router = Router();
let authManager: MagicLinkManager;

export const initializeAuthRoutes = (manager: MagicLinkManager) => {
  authManager = manager;
  return router;
};

router.post('/login/request', async (req: Reques

t, res: Response) => { const { email } = req.body;

if (!email || typeof email !== 'string') { res.status(400).json({ error: 'Valid email address is required' }); return; }

try { await authManager.initiateLogin(email, { subject: 'Your secure access link', html: <p>Click the button below to sign in. This link expires shortly.</p> <a href="{{link}}" style="padding: 10px 20px; background: #0055ff; color: white; text-decoration: none; border-radius: 4px;">Access Account</a> }); res.json({ status: 'pending', message: 'Check your inbox for the access link' }); } catch (error) { res.status(500).json({ error: 'Failed to dispatch authentication link' }); } });

router.get('/login/complete', async (req: Request, res: Response) => { const token = req.query.token as string;

if (!token) { res.status(400).json({ error: 'Authentication token missing' }); return; }

try { const sessionData = await authManager.validateToken(token); // In production: establish session, set secure cookie, or return JWT res.json({ status: 'authenticated', session: sessionData }); } catch (error) { res.status(401).json({ error: 'Invalid or expired token' }); } });

**Architecture Rationale:**
- **Idempotent Request Flow**: The `/login/request` endpoint always returns a generic success message, even if the email doesn't exist. This prevents email enumeration attacks.
- **Token Validation Isolation**: Verification is handled separately from session establishment. This allows you to swap session mechanisms (cookies, JWT, server-side sessions) without modifying the token validation logic.
- **Placeholder Injection**: The `{{link}}` string is automatically replaced by the underlying library with the full verification URL. No manual string concatenation is required.

### Step 5: Application Bootstrap

```typescript
// src/index.ts
import express from 'express';
import dotenv from 'dotenv';
import { MagicLinkManager } from './auth/MagicLinkManager';
import { initializeAuthRoutes } from './routes/authRoutes';

dotenv.config();

const app = express();
app.use(express.json());

const authConfig = {
  secretKey: process.env.AUTH_SECRET || 'fallback-dev-key',
  baseUrl: process.env.APP_URL || 'http://localhost:3000',
  tokenExpiry: '10m',
  storageBackend: (process.env.TOKEN_STORAGE as 'memory' | 'redis') || 'memory'
};

const authManager = new MagicLinkManager(authConfig);

authManager.configureTransport({
  provider: 'api',
  senderAddress: 'noreply@yourdomain.com',
  credentials: {
    apiService: 'resend',
    apiKey: process.env.RESEND_API_KEY || ''
  }
});

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

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(`Authentication service listening on port ${PORT}`));

Pitfall Guide

1. Memory Token Storage in Production

Explanation: The default memory backend stores tokens in the Node.js process heap. In clustered or multi-instance deployments, tokens generated on one instance cannot be verified on another. Memory also grows unbounded until garbage collection or restart. Fix: Set storeTokens: 'redis' and provide a Redis connection string. Redis provides distributed state, automatic expiration, and sub-millisecond lookup times.

2. Ignoring Token Expiration Windows

Explanation: Long-lived tokens (e.g., 24 hours) increase the window for interception or replay attacks. Users also expect immediate access; delayed clicks often fail silently. Fix: Use mlExpiry: '5m' to '15m'. Communicate the window clearly in the email template. Implement a fallback flow if users report expired links.

3. Hardcoding Secrets in Source Control

Explanation: The mlSecret value signs and validates tokens. If exposed, attackers can forge valid authentication links. Fix: Load AUTH_SECRET from environment variables or a secrets manager. Rotate the secret periodically and invalidate existing tokens on rotation.

4. Skipping Email Format Validation

Explanation: Sending to malformed addresses wastes API quota, triggers bounce penalties, and can degrade sender reputation. Fix: Validate email syntax before calling initiateLogin. Use a lightweight regex or a dedicated validation library. Reject invalid formats early with a 400 response.

5. Logging Tokens or Full URLs

Explanation: Debug logs, error trackers, or proxy servers may capture the full verification URL. Storing tokens in plaintext logs creates a secondary attack surface. Fix: Never log req.query.token or the generated URL. Use structured logging that masks sensitive fields. Configure your logging framework to redact query parameters containing token.

6. Missing Rate Limiting on the Send Endpoint

Explanation: Unprotected /login/request endpoints can be abused to flood users with emails, trigger spam filters, or exhaust third-party email API quotas. Fix: Apply IP-based or email-based rate limiting (e.g., 3 requests per 15 minutes per email). Use middleware like express-rate-limit with a sliding window algorithm.

7. Assuming Email Delivery Equals Authentication

Explanation: Email providers may delay delivery, route to spam, or bounce. Users may click links on different devices or browsers, breaking session continuity. Fix: Implement delivery tracking (webhooks from Resend/Mailgun/SendGrid). Design the verification flow to be device-agnostic. Consider fallback mechanisms like SMS or authenticator apps for critical accounts.

Production Bundle

Action Checklist

• Configure environment variables for AUTH_SECRET, email API keys, and APP_URL
• Switch token storage from memory to redis for distributed deployments
• Implement email validation middleware before invoking the send method
• Apply rate limiting to the /login/request endpoint
• Configure secure session establishment after successful token verification
• Set up email delivery webhooks to track bounces and spam complaints
• Add structured logging with automatic token redaction
• Test token expiration behavior with automated integration tests

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Single-instance development server	storeTokens: 'memory'	Zero infrastructure overhead, fast iteration	$0
Multi-instance production deployment	storeTokens: 'redis'	Cross-instance token validation, automatic TTL cleanup	~$10–$20/mo for managed Redis
Low volume (<1k emails/day)	SMTP or Gmail transport	No API quota limits, predictable delivery	$0–$6/mo (Gmail Workspace)
High volume or transactional focus	API provider (Resend, SendGrid, Mailgun)	Higher deliverability, webhooks, analytics, dedicated IPs	~$0.10 per 1k emails
Strict compliance (HIPAA, SOC2)	Self-hosted SMTP + Redis + audit logging	Full control over data residency and retention	Higher infra & engineering cost

Configuration Template

// src/config/env.ts
import dotenv from 'dotenv';
dotenv.config();

export const ENV = {
  AUTH_SECRET: process.env.AUTH_SECRET || '',
  APP_URL: process.env.APP_URL || 'http://localhost:3000',
  TOKEN_STORAGE: (process.env.TOKEN_STORAGE as 'memory' | 'redis') || 'memory',
  EMAIL_PROVIDER: process.env.EMAIL_PROVIDER || 'resend',
  EMAIL_SENDER: process.env.EMAIL_SENDER || 'noreply@yourdomain.com',
  EMAIL_API_KEY: process.env.EMAIL_API_KEY || '',
  REDIS_URL: process.env.REDIS_URL || 'redis://localhost:6379',
  PORT: parseInt(process.env.PORT || '3000', 10)
};

// Validate critical values at startup
if (!ENV.AUTH_SECRET) throw new Error('AUTH_SECRET is required');
if (!ENV.EMAIL_API_KEY) throw new Error('EMAIL_API_KEY is required');

// src/server.ts
import express from 'express';
import { MagicLinkManager } from './auth/MagicLinkManager';
import { initializeAuthRoutes } from './routes/authRoutes';
import { ENV } from './config/env';

const app = express();
app.use(express.json());

const authManager = new MagicLinkManager({
  secretKey: ENV.AUTH_SECRET,
  baseUrl: ENV.APP_URL,
  tokenExpiry: '10m',
  storageBackend: ENV.TOKEN_STORAGE
});

authManager.configureTransport({
  provider: 'api',
  senderAddress: ENV.EMAIL_SENDER,
  credentials: {
    apiService: ENV.EMAIL_PROVIDER,
    apiKey: ENV.EMAIL_API_KEY
  }
});

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

app.listen(ENV.PORT, () => {
  console.log(`Auth service ready on port ${ENV.PORT}`);
});

Quick Start Guide

1. Initialize the project: Run npm install express auth-verify dotenv typescript @types/express @types/node ts-node and generate tsconfig.json.
2. Set environment variables: Create a .env file with AUTH_SECRET, APP_URL, EMAIL_PROVIDER, EMAIL_SENDER, and EMAIL_API_KEY.
3. Copy the configuration template: Place env.ts, MagicLinkManager.ts, authRoutes.ts, and server.ts in their respective directories.
4. Start the server: Run npx ts-node src/server.ts. The service will listen on port 3000.
5. Test the flow: Send a POST request to http://localhost:3000/auth/login/request with {"email": "test@example.com"}. Check the inbox, click the link, and verify the GET response at /auth/login/complete.

This architecture delivers a secure, scalable, and maintainable passwordless authentication system. By isolating token lifecycle management, enforcing strict configuration boundaries, and preparing for distributed deployment from day one, you eliminate the most common failure modes while keeping the implementation lean and auditable.