@chdlabs/my-shield 0.2.0 → 0.3.1

package/src/admin/otpGate.js

@@ -0,0 +1,370 @@
+/**
+ * Shield OTP Admin Verification Gate
+ *
+ * Provides a zero-dependency MFA challenge gate for the Shield Admin Dashboard
+ * and sensitive governance endpoints. Uses cryptographically secure OTP generation,
+ * timing-safe HMAC validation, rate limiting, and a self-contained dark-mode challenge UI.
+ *
+ * @author ChdLabs
+ * @license MIT
+ */
+import crypto from 'node:crypto';
+
+export class OTPGate {
+    /**
+     * @param {Object} [options={}]
+     * @param {string} [options.adminEmail]
+     * @param {string} [options.jwtSecret] Secret for HMAC signing (auto-generated if omitted)
+     * @param {string} [options.cookieName='shield_session']
+     * @param {number} [options.codeTtlMs=300000] 5 minutes default
+     * @param {number} [options.sessionTtlMs=86400000] 24 hours default
+     * @param {number} [options.maxAttempts=5]
+     * @param {Function} [options.sendOtp] Async delivery function: async (email, code) => void
+     * @param {Object} [options.logger]
+     */
+    constructor(options = {}) {
+        this.adminEmail = options.adminEmail || 'admin@localhost';
+        this.secret = options.jwtSecret || options.secret || crypto.randomBytes(32).toString('hex');
+        this.cookieName = options.cookieName || 'shield_session';
+        this.codeTtlMs = options.codeTtlMs || 5 * 60 * 1000;
+        this.sessionTtlMs = options.sessionTtlMs || 24 * 60 * 60 * 1000;
+        this.maxAttempts = Math.max(1, options.maxAttempts || 5);
+        this.logger = options.logger || console;
+
+        // Fallback default sender logs code to console if no mailer provided
+        this.sendOtp = options.sendOtp || (async (email, code) => {
+            this.logger.info?.(`[SHIELD:OTP] Verification code for ${email}: ${code}`);
+        });
+
+        // In-memory active challenge store: email -> { code, expiresAt, attempts }
+        this.challenges = new Map();
+    }
+
+    /**
+     * Generate secure 6-digit numeric OTP code
+     * @returns {string}
+     */
+    generateCode() {
+        return crypto.randomInt(100000, 1000000).toString();
+    }
+
+    /**
+     * Create an HMAC signed session token
+     * @param {string} email
+     * @returns {string}
+     */
+    createSessionToken(email) {
+        const expiresAt = Date.now() + this.sessionTtlMs;
+        const payload = `${email}:${expiresAt}`;
+        const signature = crypto.createHmac('sha256', this.secret).update(payload).digest('hex');
+        return Buffer.from(`${payload}:${signature}`).toString('base64url');
+    }
+
+    /**
+     * Verify session token using timing-safe comparison
+     * @param {string} token
+     * @returns {{ valid: boolean, email?: string }}
+     */
+    verifySessionToken(token) {
+        if (!token || typeof token !== 'string') return { valid: false };
+        try {
+            const raw = Buffer.from(token, 'base64url').toString('utf8');
+            const parts = raw.split(':');
+            if (parts.length < 3) return { valid: false };
+
+            const signature = parts.pop();
+            const expiresAt = parseInt(parts.pop(), 10);
+            const email = parts.join(':');
+
+            if (!expiresAt || expiresAt < Date.now()) {
+                return { valid: false };
+            }
+
+            const payload = `${email}:${expiresAt}`;
+            const expected = crypto.createHmac('sha256', this.secret).update(payload).digest('hex');
+
+            const sigBuf = Buffer.from(signature, 'hex');
+            const expBuf = Buffer.from(expected, 'hex');
+
+            if (sigBuf.length !== expBuf.length || !crypto.timingSafeEqual(sigBuf, expBuf)) {
+                return { valid: false };
+            }
+
+            return { valid: true, email };
+        } catch {
+            return { valid: false };
+        }
+    }
+
+    /**
+     * Parse cookies from request header
+     * @param {Object} req
+     * @returns {Record<string, string>}
+     */
+    parseCookies(req) {
+        const header = req.headers?.cookie;
+        if (!header) return {};
+        const cookies = {};
+        for (const pair of header.split(';')) {
+            const [k, ...v] = pair.trim().split('=');
+            if (k) cookies[k] = decodeURIComponent(v.join('='));
+        }
+        return cookies;
+    }
+
+    /**
+     * Render self-contained zero-dependency dark-mode HTML challenge page
+     */
+    renderChallengeHtml(req, errorMessage = '') {
+        const baseUrl = req.baseUrl || '';
+        return `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Shield Admin Authentication</title>
+    <style>
+        :root {
+            --bg: #090d16;
+            --surface: #131b2e;
+            --border: #1f2d4d;
+            --primary: #3b82f6;
+            --primary-hover: #2563eb;
+            --text: #f8fafc;
+            --muted: #94a3b8;
+            --danger: #ef4444;
+            --success: #10b981;
+        }
+        * { box-sizing: border-box; margin: 0; padding: 0; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; }
+        body {
+            background-color: var(--bg);
+            color: var(--text);
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            min-height: 100vh;
+            padding: 1.5rem;
+        }
+        .card {
+            background: var(--surface);
+            border: 1px solid var(--border);
+            border-radius: 12px;
+            padding: 2.5rem;
+            width: 100%;
+            max-width: 420px;
+            box-shadow: 0 20px 40px rgba(0,0,0,0.4);
+        }
+        .header { text-align: center; margin-bottom: 2rem; }
+        .logo { font-size: 2.5rem; margin-bottom: 0.5rem; }
+        h1 { font-size: 1.5rem; font-weight: 600; margin-bottom: 0.25rem; }
+        p.subtitle { color: var(--muted); font-size: 0.875rem; }
+        .alert {
+            background: rgba(239, 68, 68, 0.15);
+            border: 1px solid var(--danger);
+            color: #fca5a5;
+            padding: 0.75rem 1rem;
+            border-radius: 6px;
+            font-size: 0.875rem;
+            margin-bottom: 1.25rem;
+        }
+        .success-box {
+            background: rgba(16, 185, 129, 0.15);
+            border: 1px solid var(--success);
+            color: #6ee7b7;
+            padding: 0.75rem 1rem;
+            border-radius: 6px;
+            font-size: 0.875rem;
+            margin-bottom: 1.25rem;
+        }
+        .form-group { margin-bottom: 1.25rem; }
+        label { display: block; font-size: 0.875rem; font-weight: 500; margin-bottom: 0.5rem; color: var(--muted); }
+        input[type="text"] {
+            width: 100%;
+            background: #0b1120;
+            border: 1px solid var(--border);
+            color: var(--text);
+            padding: 0.75rem 1rem;
+            border-radius: 6px;
+            font-size: 1.125rem;
+            letter-spacing: 0.25em;
+            text-align: center;
+            outline: none;
+            transition: border-color 0.2s;
+        }
+        input[type="text"]:focus { border-color: var(--primary); }
+        button {
+            width: 100%;
+            background: var(--primary);
+            color: white;
+            border: none;
+            padding: 0.75rem;
+            border-radius: 6px;
+            font-size: 0.95rem;
+            font-weight: 600;
+            cursor: pointer;
+            transition: background 0.2s;
+        }
+        button:hover { background: var(--primary-hover); }
+        .actions { display: flex; justify-content: space-between; margin-top: 1rem; }
+        .actions button.secondary {
+            background: transparent;
+            border: 1px solid var(--border);
+            color: var(--muted);
+            font-weight: normal;
+        }
+        .actions button.secondary:hover { color: var(--text); border-color: var(--text); background: transparent; }
+    </style>
+</head>
+<body>
+    <div class="card">
+        <div class="header">
+            <div class="logo">🛡️</div>
+            <h1>Shield Security Gate</h1>
+            <p class="subtitle">Enter the 6-digit authentication code sent to administrator.</p>
+        </div>
+
+        ${errorMessage ? `<div class="alert">${errorMessage}</div>` : ''}
+
+        <form method="POST" action="${baseUrl}/__shield_verify">
+            <div class="form-group">
+                <label for="otp">One-Time Passcode</label>
+                <input id="otp" name="code" type="text" maxlength="6" pattern="[0-9]{6}" inputmode="numeric" placeholder="••••••" required autofocus autocomplete="one-time-code" />
+            </div>
+            <button type="submit">Verify & Access Console</button>
+        </form>
+
+        <form method="POST" action="${baseUrl}/__shield_request" style="margin-top: 1rem;">
+            <button type="submit" class="secondary">Request New Code</button>
+        </form>
+    </div>
+</body>
+</html>`;
+    }
+
+    /**
+     * Express middleware handler
+     */
+    middleware() {
+        return async (req, res, next) => {
+            const cookies = this.parseCookies(req);
+            const sessionToken = cookies[this.cookieName] || req.headers?.['x-shield-auth-token'];
+
+            // 1. Check existing verified session
+            if (sessionToken) {
+                const verification = this.verifySessionToken(sessionToken);
+                if (verification.valid) {
+                    req.shieldAdmin = { email: verification.email };
+                    return next();
+                }
+            }
+
+            const path = req.path || '';
+
+            // 2. Handle POST Request to send a new code
+            if (req.method === 'POST' && path.endsWith('/__shield_request')) {
+                const code = this.generateCode();
+                this.challenges.set(this.adminEmail, {
+                    code,
+                    expiresAt: Date.now() + this.codeTtlMs,
+                    attempts: 0
+                });
+
+                try {
+                    await this.sendOtp(this.adminEmail, code);
+                } catch (err) {
+                    this.logger.error?.('[SHIELD:OTP] Error dispatching OTP email:', err.message);
+                }
+
+                if (req.accepts('html')) {
+                    res.setHeader('Content-Type', 'text/html; charset=utf-8');
+                    return res.send(this.renderChallengeHtml(req, ''));
+                }
+                return res.json({ success: true, message: 'Verification code generated' });
+            }
+
+            // 3. Handle POST Request to verify code
+            if (req.method === 'POST' && path.endsWith('/__shield_verify')) {
+                // Parse body if express.urlencoded/json not mounted
+                let code = req.body?.code;
+                if (!code && typeof req.body === 'string') {
+                    const match = req.body.match(/code=([^&]+)/);
+                    if (match) code = decodeURIComponent(match[1]);
+                }
+
+                const challenge = this.challenges.get(this.adminEmail);
+                if (!challenge || Date.now() > challenge.expiresAt) {
+                    if (req.accepts('html')) {
+                        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+                        return res.status(401).send(this.renderChallengeHtml(req, 'Code has expired. Please request a new code.'));
+                    }
+                    return res.status(401).json({ error: 'Code has expired', code: 'EXPIRED_CODE' });
+                }
+
+                challenge.attempts = (challenge.attempts || 0) + 1;
+                if (challenge.attempts > this.maxAttempts) {
+                    this.challenges.delete(this.adminEmail);
+                    if (req.accepts('html')) {
+                        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+                        return res.status(403).send(this.renderChallengeHtml(req, 'Too many failed attempts. Locked out.'));
+                    }
+                    return res.status(403).json({ error: 'Maximum verification attempts exceeded', code: 'MAX_ATTEMPTS_EXCEEDED' });
+                }
+
+                // Verify code with timing-safe comparison
+                const userCodeBuf = Buffer.from(String(code || '').trim());
+                const expectedCodeBuf = Buffer.from(challenge.code);
+
+                const isMatch = userCodeBuf.length === expectedCodeBuf.length &&
+                                crypto.timingSafeEqual(userCodeBuf, expectedCodeBuf);
+
+                if (isMatch) {
+                    this.challenges.delete(this.adminEmail);
+                    const token = this.createSessionToken(this.adminEmail);
+
+                    // Set HttpOnly signed cookie
+                    const isSecure = req.secure || req.headers['x-forwarded-proto'] === 'https';
+                    const cookieFlags = [
+                        `${this.cookieName}=${encodeURIComponent(token)}`,
+                        'Path=/',
+                        'HttpOnly',
+                        'SameSite=Lax',
+                        `Max-Age=${Math.floor(this.sessionTtlMs / 1000)}`
+                    ];
+                    if (isSecure) cookieFlags.push('Secure');
+
+                    res.setHeader('Set-Cookie', cookieFlags.join('; '));
+
+                    if (req.accepts('html')) {
+                        const targetUrl = req.baseUrl || '/';
+                        return res.redirect(targetUrl || '/');
+                    }
+                    return res.json({ success: true, token });
+                }
+
+                if (req.accepts('html')) {
+                    res.setHeader('Content-Type', 'text/html; charset=utf-8');
+                    return res.status(401).send(this.renderChallengeHtml(req, 'Invalid verification code. Please try again.'));
+                }
+                return res.status(401).json({ error: 'Invalid verification code', code: 'INVALID_CODE' });
+            }
+
+            // 4. Default unauthenticated presentation
+            if (req.accepts('html')) {
+                res.setHeader('Content-Type', 'text/html; charset=utf-8');
+                return res.status(401).send(this.renderChallengeHtml(req, ''));
+            }
+
+            return res.status(401).json({
+                error: 'Shield OTP authentication required',
+                code: 'SHIELD_OTP_REQUIRED'
+            });
+        };
+    }
+}
+
+export function createOtpGate(options = {}) {
+    const gate = new OTPGate(options);
+    return gate.middleware();
+}
+
+export default createOtpGate;