SecureAuth SDK

The Problem with JWT

Security Comparison

Getting Started in 5 Minutes

1. Installation

npm install secure-auth-server ioredis express cookie-parser

2. Generate Keys

npx tsx -e "import { SecureAuth } from 'secure-auth-server'; console.log(SecureAuth.generateKeys());"

PASETO_PRIVATE_KEY=302e...
PASETO_PUBLIC_KEY=302a...
REDIS_URL=redis://localhost:6379

3. Basic Implementation

import express from 'express';
import cookieParser from 'cookie-parser';
import { SecureAuth } from 'secure-auth-server';

const app = express();
app.use(express.json());
app.use(cookieParser()); // Required for refresh token rotation

// 1. Initialize the Engine
const auth = new SecureAuth({
  redis: { url: process.env.REDIS_URL! },
  keys: {
    private: process.env.PASETO_PRIVATE_KEY!,
    public: process.env.PASETO_PUBLIC_KEY!,
  },
  tokenTTL: 900,         // Access tokens expire in 15 mins
  refreshTTL: 604800,    // Refresh tokens expire in 7 days
  bindingMode: 'ua-only', // Binds tokens to the browser's User-Agent
  onRedisError: 'fail-open', // Allow auth when Redis is down
  cookieOptions: {
    secure: true,        // Set to false for local dev without HTTPS
    sameSite: 'strict',
    domain: '.example.com' // Optional: share cookies across subdomains
  }
});

// 2. Add Auto-Managed Routes
// Mounts POST /auth/refresh, POST /auth/logout, and POST /auth/logout/all
app.use('/auth', auth.router());

// 3. Login Endpoint (Your custom logic)
app.post('/login', async (req, res) => {
  const { username, password } = req.body;
  
  // Verify user credentials against your DB...
  if (username === 'alice' && password === 'secret') {
    const userId = 'user_123';
    const roles = ['user'];
    
    // Issue tokens: passing `res` automatically sets the refresh token
    // as an httpOnly cookie with the SDK's secure configuration.
    const tokens = await auth.issueTokens(userId, roles, req, res);
    
    res.json({
      accessToken: tokens.accessToken,
      expiresAt: tokens.accessTokenExpiresAt
    });
  } else {
    res.status(401).json({ error: 'Invalid credentials' });
  }
});

// 4. Protected Route
// auth.verify() checks signature, expiration, Redis revocation, and fingerprint
app.get('/api/protected', auth.verify(), (req, res) => {
  // Access validated user details from req.auth
  res.json({
    message: 'Welcome to the protected zone!',
    userId: req.auth!.sub,
    roles: req.auth!.roles
  });
});

app.listen(3000, () => console.log('SecureAuth server running on port 3000'));

How It Works

Bearer Token → Ed25519 Signature Check → Expiry/nbf Check → Redis Revocation Check → Fingerprint Match

interface AuthContext {
  sub: string;    // User ID
  jti: string;    // Unique token ID
  roles: string[]; // User roles
  fp: string;     // Device fingerprint
}

Configuration

Device Fingerprinting

Advanced Usage

Emergency User Revocation

await auth.revokeUser('user_123');

Session Listing

GET /auth/sessions
Authorization: Bearer <access_token>

{
  "sessions": [
    { "jti": "abc123...", "expiresAt": "2026-07-25T15:30:00.000Z" },
    { "jti": "def456...", "expiresAt": "2026-07-25T16:00:00.000Z" }
  ]
}

Health Check

const isHealthy = await auth.healthCheck(); // true if Redis is reachable

Error Codes

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

Auto-Managed Routes

Project Structure

secureauth-sdk/
├── packages/
│   ├── core/          # Shared types, errors, and utilities
│   └── server/        # PASETO engine, Redis services, middleware
├── apps/
│   └── example-express/  # Working reference implementation
├── scripts/
│   └── keygen.ts      # Ed25519 key pair generator
└── SECURITY.md        # Security policy and design principles

License