@javagt/express-easy-auth 1.0.0

package/demo/server.js

@@ -0,0 +1,195 @@
+import 'dotenv/config';
+import express from 'express';
+import session from 'express-session';
+import cookieParser from 'cookie-parser';
+import helmet from 'helmet';
+import cors from 'cors';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+// 1. Import the library's main integration tools
+import {
+  setupAuth,
+  authRouter,
+  SQLiteSessionStore,
+  authErrorLogger,
+  requireApiKey
+} from '../src/index.js';
+import { DatabaseSync } from 'node:sqlite';
+import profileRouter from './profileRouter.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// ─── CONFIG ──────────────────────────────────────────────────────────────────
+const DOMAIN = process.env.DOMAIN || 'localhost';
+const PORT = parseInt(process.env.PORT || '3000', 10);
+const SESSION_SECRET = process.env.SESSION_SECRET || 'change-this-in-production-please';
+const IS_PROD = process.env.NODE_ENV === 'production';
+
+// Robust hostname extraction
+let HOSTNAME = DOMAIN.replace(/^https?:\/\//, '').split('/')[0].split(':')[0];
+const IS_LOCALHOST = HOSTNAME.includes('localhost') || HOSTNAME.includes('127.0.0.1');
+const PROTOCOL = (IS_PROD || !IS_LOCALHOST) ? 'https' : 'http';
+const ORIGIN = `${PROTOCOL}://${HOSTNAME}${(!IS_PROD && IS_LOCALHOST && PORT !== 80 && PORT !== 443) ? `:${PORT}` : ''}`;
+
+const config = {
+  domain: HOSTNAME,
+  port: PORT,
+  protocol: PROTOCOL,
+  origin: ORIGIN,
+  rpName: 'Auth Server Demo',
+  rpID: HOSTNAME,
+};
+
+const app = express();
+
+// 2. Initialize Authentication Services
+const dataDir = path.join(__dirname, '../data');
+setupAuth(app, {
+  dataDir,
+  exposeErrors: !IS_PROD,
+  config
+});
+
+// 2b. Initialize Application Database (External to Auth Server)
+const appDataDb = new DatabaseSync(path.join(dataDir, 'app_data.db'));
+appDataDb.exec(`
+  CREATE TABLE IF NOT EXISTS profiles (
+    user_id TEXT PRIMARY KEY,
+    display_name TEXT,
+    bio TEXT,
+    avatar_url TEXT,
+    location TEXT,
+    website TEXT,
+    preferences TEXT, -- JSON string for app settings
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL
+  );
+`);
+
+// Attach appDataDb to app for use in routers
+app.set('appDataDb', appDataDb);
+
+
+// ─── MIDDLEWARE ──────────────────────────────────────────────────────────────
+
+app.set('trust proxy', 1);
+
+app.use(helmet({
+  hsts: IS_PROD,
+  contentSecurityPolicy: {
+    directives: {
+      defaultSrc: ["'self'"],
+      scriptSrc: ["'self'"],
+      styleSrc: ["'self'", "'unsafe-inline'", 'https://fonts.googleapis.com'],
+      fontSrc: ["'self'", 'https://fonts.gstatic.com'],
+      imgSrc: ["'self'", 'data:'],
+      connectSrc: ["'self'"],
+    },
+  },
+}));
+
+app.use(cors({
+  origin: ORIGIN,
+  credentials: true,
+}));
+
+app.use(express.json());
+app.use(express.urlencoded({ extended: true }));
+app.use(cookieParser(SESSION_SECRET));
+
+// ─── SESSION ─────────────────────────────────────────────────────────────────
+
+const sessionStore = new SQLiteSessionStore();
+
+app.use(session({
+  secret: SESSION_SECRET,
+  store: sessionStore,
+  resave: false,
+  saveUninitialized: false,
+  name: 'auth.sid',
+  cookie: {
+    secure: PROTOCOL === 'https',
+    httpOnly: true,
+    sameSite: 'lax',
+    maxAge: 7 * 24 * 60 * 60 * 1000 // 1 week
+  },
+}));
+
+// ─── ROUTES ──────────────────────────────────────────────────────────────────
+
+// 3. Mount Library & Application Routes
+app.use('/api/v1/auth', authRouter);
+app.use('/api/v1/profile', profileRouter);
+
+// Sample Public API protected by API Keys
+app.get('/api/public/data', requireApiKey, (req, res) => {
+  if (!req.permissions.includes('action:read')) {
+    return res.status(403).json({ error: 'Missing permission: action:read' });
+  }
+  res.json({
+    message: 'Success! You accessed this data with an API key.',
+    user: req.userId,
+    permissions: req.permissions,
+    timestamp: new Date().toISOString()
+  });
+});
+
+app.post('/api/public/data', requireApiKey, (req, res) => {
+  if (!req.permissions.includes('action:write')) {
+    return res.status(403).json({ error: 'Missing permission: action:write' });
+  }
+  res.json({
+    message: 'Success! You published data with an API key.',
+    publishedAt: new Date().toISOString()
+  });
+});
+
+// Health check
+app.get('/api/health', (req, res) => {
+  res.json({ status: 'ok', domain: DOMAIN, timestamp: new Date().toISOString() });
+});
+
+// ─── DEMO MAILBOX (TEST ENDPOINTS) ──────────────────────────────────────────
+const mailboxMessages = [];
+
+app.get('/api/v1/test/mailbox', (req, res) => {
+  res.json({ messages: mailboxMessages });
+});
+
+app.post('/api/v1/test/mailbox', (req, res) => {
+  const { type, subject, body } = req.body;
+  const msg = {
+    id: Math.random().toString(36).substring(2, 9),
+    type: type || 'System',
+    subject: subject || 'No Subject',
+    body: body || '',
+    timestamp: Date.now()
+  };
+  mailboxMessages.unshift(msg);
+  if (mailboxMessages.length > 50) mailboxMessages.pop();
+  res.status(201).json(msg);
+});
+
+app.delete('/api/v1/test/mailbox', (req, res) => {
+  mailboxMessages.length = 0;
+  res.status(204).send();
+});
+
+// Serve frontend from demo directory
+app.use(express.static(path.join(__dirname, './public')));
+
+// ─── ERROR HANDLER ───────────────────────────────────────────────────────────
+
+app.use(authErrorLogger);
+
+// ─── START ───────────────────────────────────────────────────────────────────
+
+app.listen(PORT, () => {
+  console.log(`\n🔐 Auth Demo Server running`);
+  console.log(`   URL:     ${ORIGIN}`);
+  console.log(`   RPID:    ${config.rpID}`);
+  console.log(`   Env:     ${IS_PROD ? 'production' : 'development'}\n`);
+});

package/examples/01-basic-setup.js

@@ -0,0 +1,118 @@
+/**
+ * Example 01: Basic setup
+ * 
+ * Demonstrates how to initialize the auth library and protect a basic route.
+ */
+
+import express from 'express';
+import session from 'express-session';
+// In your app, use: import { setupAuth, authRouter, SQLiteSessionStore, requireAuth } from 'auth-server';
+import { 
+  setupAuth, 
+  authRouter, 
+  SQLiteSessionStore, 
+  requireAuth,
+  AuthClient 
+} from '../src/index.js';
+
+const app = express();
+
+// 1. JSON Middleware is required for API routes
+app.use(express.json());
+
+// 2. Initialize the Library
+setupAuth(app, {
+  dataDir: './data-example', // Directory for SQLite DBs
+  exposeErrors: process.env.NODE_ENV !== 'production', // Explicit debug setting
+  config: {
+    domain: 'localhost',
+    rpName: 'Basic Example App',
+    rpID: 'localhost',
+    origin: 'http://localhost:3000'
+  }
+});
+
+// 3. Configure Sessions
+// The library provides SQLiteSessionStore which is optimized for auth-server
+app.use(session({
+  secret: 'keyboard-cat-secret',
+  store: new SQLiteSessionStore(),
+  resave: false,
+  saveUninitialized: false,
+  cookie: { secure: false } // 'true' in production with HTTPS
+}));
+
+// 1. Mount Auth (Unified Router)
+app.use('/api/v1/auth', authRouter);
+
+// 5. Protect your routes
+app.get('/dashboard', requireAuth, (req, res) => {
+  res.json({
+    message: 'Access granted!',
+    userId: req.userId,
+    sessionID: req.sessionID
+  });
+});
+
+// 6. Client-side SDK Demo
+app.get('/', (req, res) => {
+  res.send(`
+    <!DOCTYPE html>
+    <html>
+    <head><title>Auth SDK Demo - Basic</title></head>
+    <body style="font-family: sans-serif; padding: 2rem; background: #f4f4f9;">
+      <h1>Auth SDK Demo: Basic Setup</h1>
+      <p>This page uses the <b>AuthClient</b> SDK to interact with the backend.</p>
+      <div id="status">Checking status...</div>
+      <hr>
+      <button id="regBtn">Register Demo User</button>
+      <button id="loginBtn">Login Demo User</button>
+      <button id="logoutBtn">Logout</button>
+      
+      <script type="module">
+        import { AuthClient } from '/auth-sdk.js';
+        const auth = new AuthClient();
+        
+        async function updateStatus() {
+          const status = await auth.getStatus();
+          document.getElementById('status').innerText = 'Authenticated: ' + status.authenticated + (status.username ? ' (' + status.username + ')' : '');
+          console.log('Current Status:', status);
+        }
+
+        document.getElementById('regBtn').onclick = async () => {
+          const username = 'user_' + Math.floor(Math.random()*1000);
+          try {
+            const res = await auth.register(username, username + '@example.com', 'password123');
+            alert('Registered: ' + username);
+            await updateStatus();
+          } catch (e) { alert('Error: ' + e.message); }
+        };
+
+        document.getElementById('loginBtn').onclick = async () => {
+          const username = prompt('Username?');
+          try {
+            await auth.login(username, 'password123');
+            alert('Logged in!');
+            await updateStatus();
+          } catch (e) { alert('Error: ' + e.message); }
+        };
+
+        document.getElementById('logoutBtn').onclick = async () => {
+          await auth.logout();
+          alert('Logged out');
+          await updateStatus();
+        };
+
+        updateStatus();
+      </script>
+    </body>
+    </html>
+  `);
+});
+
+const PORT = 3000;
+app.listen(PORT, () => {
+  console.log(`Example 01 running at http://localhost:${PORT}`);
+  console.log(`- Try: GET http://localhost:${PORT}/api/v1/auth/status`);
+  console.log(`- Try: GET http://localhost:${PORT}/dashboard (will return 401 until login)`);
+});

package/examples/02-passkeys.js

@@ -0,0 +1,106 @@
+/**
+ * Example 02: Passkeys (WebAuthn)
+ * 
+ * Demonstrates how to enable and manage biometric passkeys.
+ */
+
+import express from 'express';
+import session from 'express-session';
+import { 
+  setupAuth, 
+  authRouter, 
+  SQLiteSessionStore, 
+  requireAuth 
+} from '../src/index.js';
+
+const app = express();
+app.use(express.json());
+
+setupAuth(app, {
+  dataDir: './data-example',
+  config: {
+    domain: 'localhost',
+    rpName: 'Passkey Example',
+    rpID: 'localhost',
+    origin: 'http://localhost:3000'
+  }
+});
+
+app.use(session({
+  secret: 'passkey-secret',
+  store: new SQLiteSessionStore(),
+  resave: false,
+  saveUninitialized: false,
+  cookie: { secure: false }
+}));
+
+// 1. Mount Auth (Unified Router)
+app.use('/api/v1/auth', authRouter);
+
+// 2. The SDK will now automatically use /api/v1/auth/...
+
+app.get('/', (req, res) => {
+  res.send(`
+    <!DOCTYPE html>
+    <html>
+    <head><title>Auth SDK Demo - Passkeys</title></head>
+    <body style="font-family: sans-serif; padding: 2rem; background: #fdf6e3;">
+      <h1>Auth SDK Demo: Passkeys</h1>
+      <p>This page demonstrates <b>WebAuthn</b> registration and login via the SDK.</p>
+      <div id="status">Checking status...</div>
+      <hr>
+      <div id="controls">
+        <button id="regBtn">1. Register Password Account</button>
+        <button id="pkRegBtn">2. Register Passkey</button>
+        <button id="pkLoginBtn">3. Login with Passkey</button>
+      </div>
+
+      <script type="module">
+        import { AuthClient } from '/auth-sdk.js';
+        const auth = new AuthClient();
+        
+        async function updateStatus() {
+          const status = await auth.getStatus();
+          document.getElementById('status').innerHTML = \`
+            <strong>Authenticated:</strong> \${status.authenticated}<br>
+            <strong>User ID:</strong> \${status.userId || 'None'}<br>
+            <strong>Passkeys:</strong> \${status.passkeyCount || 0}
+          \`;
+        }
+
+        document.getElementById('regBtn').onclick = async () => {
+          const u = 'pk_user_' + Math.floor(Math.random()*1000);
+          try {
+            await auth.register(u, u + '@example.com', 'password123');
+            alert('Created password account: ' + u + '. Now register a passkey!');
+            await updateStatus();
+          } catch (e) { alert(e.message); }
+        };
+
+        document.getElementById('pkRegBtn').onclick = async () => {
+          try {
+            await auth.registerPasskey('My Laptop');
+            alert('Passkey Registered!');
+            await updateStatus();
+          } catch (e) { alert(e.message); }
+        };
+
+        document.getElementById('pkLoginBtn').onclick = async () => {
+          try {
+            const res = await auth.loginWithPasskey();
+            alert('Logged in with Passkey!');
+            await updateStatus();
+          } catch (e) { alert(e.message); }
+        };
+
+        updateStatus();
+      </script>
+    </body>
+    </html>
+  `);
+});
+
+const PORT = 3000;
+app.listen(PORT, () => {
+  console.log(`Example 02 running at http://localhost:${PORT}`);
+});

package/examples/03-api-keys.js

@@ -0,0 +1,108 @@
+/**
+ * Example 03: API Keys
+ * 
+ * Demonstrates service-to-service authentication using API keys.
+ */
+
+import express from 'express';
+import { setupAuth, authRouter, requireApiKey } from '../src/index.js';
+
+const app = express();
+app.use(express.json());
+
+setupAuth(app, {
+  dataDir: './data-example',
+  config: { domain: 'localhost' }
+});
+
+// 1. Mount Auth router for identity management
+app.use('/api/v1/auth', authRouter);
+
+// 2. Protect routes with the requireApiKey middleware
+// It looks for 'X-API-Key' or 'Authorization: Bearer <key>'
+app.get('/api/v1/protected-data', requireApiKey, (req, res) => {
+  // Authentication verified
+  // req.userId is set to the owner of the key
+  // req.permissions contains the key's allowed scopes
+  
+  res.json({
+    success: true,
+    message: 'Accessed via API key',
+    owner: req.userId,
+    permissions: req.permissions
+  });
+});
+
+// 3. Granular permission check
+app.post('/api/v1/write-data', requireApiKey, (req, res) => {
+  if (!req.permissions.includes('action:write')) {
+    return res.status(403).json({ error: 'Key lacks action:write permission' });
+  }
+  
+  res.json({ success: true, message: 'Write operation authorized' });
+});
+
+app.get('/', (req, res) => {
+  res.send(`
+    <!DOCTYPE html>
+    <html>
+    <head><title>Auth SDK Demo - API Keys</title></head>
+    <body style="font-family: sans-serif; padding: 2rem; background: #eef2ff;">
+      <h1>Auth SDK Demo: API Keys</h1>
+      <p>This page demonstrates API key lifecycle management via the SDK.</p>
+      
+      <div id="controls">
+        <button id="loginBtn">1. Login as Admin</button>
+        <button id="createKeyBtn">2. Create API Key</button>
+        <button id="testKeyBtn">3. Test Created Key</button>
+      </div>
+      <hr>
+      <div id="output" style="background: #333; color: #fff; padding: 1rem; border-radius: 4px; font-family: monospace; min-height: 100px; white-space: pre-wrap;">Console Output...</div>
+
+      <script type="module">
+        import { AuthClient } from '/auth-sdk.js';
+        const auth = new AuthClient();
+        let lastKey = null;
+
+        const log = (msg) => {
+          document.getElementById('output').innerText += '\\n> ' + msg;
+        };
+
+        document.getElementById('loginBtn').onclick = async () => {
+          try {
+            // Ensure a user exists first
+            await auth.register('api_admin', 'api@example.com', 'admin123').catch(() => {});
+            await auth.login('api_admin', 'admin123');
+            log('Logged in as api_admin');
+          } catch (e) { log('Login Error: ' + e.message); }
+        };
+
+        document.getElementById('createKeyBtn').onclick = async () => {
+          try {
+            const res = await auth.createApiKey('Demo Key', ['action:read']);
+            lastKey = res.key;
+            log('Key Created: ' + lastKey);
+          } catch (e) { log('Error: ' + e.message); }
+        };
+
+        document.getElementById('testKeyBtn').onclick = async () => {
+          if (!lastKey) return alert('Create a key first!');
+          try {
+            const res = await fetch('/api/v1/protected-data', {
+              headers: { 'X-API-Key': lastKey }
+            });
+            const data = await res.json();
+            log('Test Result: ' + JSON.stringify(data));
+          } catch (e) { log('Test Error: ' + e.message); }
+        };
+      </script>
+    </body>
+    </html>
+  `);
+});
+
+const PORT = 3000;
+app.listen(PORT, () => {
+  console.log(`Example 03 running at http://localhost:${PORT}`);
+  console.log(`- Request with: curl -H "X-API-Key: YOUR_KEY" http://localhost:${PORT}/api/v1/protected-data`);
+});

package/examples/04-totp-setup.js

@@ -0,0 +1,125 @@
+/**
+ * Example 04: TOTP 2FA
+ * 
+ * Demonstrates the full lifecycle of setting up and using TOTP 2FA.
+ */
+
+import express from 'express';
+import session from 'express-session';
+import { 
+  setupAuth, 
+  authRouter, 
+  SQLiteSessionStore, 
+  requireAuth,
+  requireFreshAuth
+} from '../src/index.js';
+
+const app = express();
+app.use(express.json());
+
+setupAuth(app, {
+  dataDir: './data-example',
+  config: { domain: 'localhost' }
+});
+
+app.use(session({
+  secret: 'totp-secret',
+  store: new SQLiteSessionStore(),
+  resave: false,
+  saveUninitialized: false,
+  cookie: { secure: false }
+}));
+
+// 1. Mount Auth (Unified Router)
+app.use('/api/v1/auth', authRouter);
+
+// 1. Initial login (Password only)
+// POST /api/auth/login
+
+// 2. Setup 2FA (Requires valid session)
+// POST /api/auth/2fa/setup -> Returns { secret, qrCode }
+
+// 3. Verify Setup (Enables 2FA for the account)
+// POST /api/auth/2fa/verify-setup { token: "123456" }
+
+// 4. Test Fresh Auth (Protecting sensitive actions)
+// requireFreshAuth ensures the user has authed within the last few minutes
+app.post('/api/user/delete-account', requireAuth, requireFreshAuth, (req, res) => {
+  res.json({ success: true, message: 'Sensitive action authorized' });
+});
+
+app.get('/', (req, res) => {
+  res.send(`
+    <!DOCTYPE html>
+    <html>
+    <head><title>Auth SDK Demo - TOTP 2FA</title></head>
+    <body style="font-family: sans-serif; padding: 2rem; background: #fff5f5;">
+      <h1>Auth SDK Demo: TOTP 2FA</h1>
+      <p>This page demonstrates <b>TOTP</b> (Authenticator App) setup via the SDK.</p>
+      <div id="status">Checking status...</div>
+      <hr>
+      <div id="controls">
+        <button id="loginBtn">1. Login</button>
+        <button id="setupBtn">2. Setup 2FA</button>
+      </div>
+      <div id="qrArea" style="margin: 1rem 0; display: none;">
+        <p>Scan this QR code in your app (Google Authenticator, etc):</p>
+        <img id="qrImg" src="" style="border: 1px solid #ccc; padding: 10px;">
+        <p>Then enter the token below:</p>
+        <input type="text" id="tokenIn" placeholder="123456">
+        <button id="verifyBtn">Verify & Enable</button>
+      </div>
+
+      <script type="module">
+        import { AuthClient } from '/auth-sdk.js';
+        const auth = new AuthClient();
+        
+        async function updateStatus() {
+          const status = await auth.getStatus();
+          document.getElementById('status').innerHTML = \`
+            <strong>Authenticated:</strong> \${status.authenticated}<br>
+            <strong>2FA Enabled:</strong> \${status.totpEnabled}<br>
+            <strong>Current User:</strong> \${status.username || 'None'}
+          \`;
+        }
+
+        document.getElementById('loginBtn').onclick = async () => {
+          const u = 'totp_user_' + Math.floor(Math.random()*1000);
+          try {
+            await auth.register(u, u + '@example.com', 'password123');
+            await auth.login(u, 'password123');
+            alert('Logged in! Now setup 2FA.');
+            await updateStatus();
+          } catch (e) { alert(e.message); }
+        };
+
+        document.getElementById('setupBtn').onclick = async () => {
+          try {
+            const res = await auth.setup2FA();
+            document.getElementById('qrImg').src = res.qrCode;
+            document.getElementById('qrArea').style.display = 'block';
+            alert('Scan the QR code!');
+          } catch (e) { alert(e.message); }
+        };
+
+        document.getElementById('verifyBtn').onclick = async () => {
+          const token = document.getElementById('tokenIn').value;
+          try {
+            await auth.verify2FASetup(token);
+            alert('2FA Enabled Successfully!');
+            document.getElementById('qrArea').style.display = 'none';
+            await updateStatus();
+          } catch (e) { alert(e.message); }
+        };
+
+        updateStatus();
+      </script>
+    </body>
+    </html>
+  `);
+});
+
+const PORT = 3000;
+app.listen(PORT, () => {
+  console.log(`Example 04 running at http://localhost:${PORT}`);
+});