@chdlabs/my-shield 0.2.0 → 0.3.0

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;

package/src/client/collector.js

@@ -14,11 +14,17 @@ export class MouseTelemetryCollector {
      * @param {number} [options.windowLength=128] Number of equispaced time points
      * @param {number} [options.sampleIntervalMs=10] Equispaced time delta (10ms = 100Hz)
      * @param {number} [options.maxBufferSize=500] Raw event sliding buffer size
+     * @param {number} [options.maxIdleMs=2500] Maximum acceptable idle gap before trajectory considered stale
+     * @param {number} [options.minPoints=15] Minimum raw points required to avoid flat interpolation
+     * @param {boolean} [options.flushOnConsumption=true] Flush buffer after getPayload to avoid replaying identical vectors
      */
     constructor(options = {}) {
         this.windowLength = options.windowLength || 128;
         this.sampleIntervalMs = options.sampleIntervalMs || 10;
         this.maxBufferSize = options.maxBufferSize || 500;
+        this.maxIdleMs = options.maxIdleMs ?? 2500;
+        this.minPoints = options.minPoints ?? 15;
+        this.flushOnConsumption = options.flushOnConsumption !== false;
         this.buffer = [];
         this.isListening = false;
         this._onMove = this._onMove.bind(this);
@@ -64,14 +70,22 @@ export class MouseTelemetryCollector {
      * @returns {{ velocity: number[], isTrusted: boolean, timestamp: number } | null}
      */
     getPayload() {
-        const requiredDuration = this.windowLength * this.sampleIntervalMs;
-        if (this.buffer.length < 10) return null;
+        if (this.buffer.length < this.minPoints) return null;
 
+        const now = typeof performance !== 'undefined' ? performance.now() : Date.now();
         const latest = this.buffer[this.buffer.length - 1];
+
+        // 1. Freshness Guard: If pointer has been stationary for > maxIdleMs (e.g. 2.5s), discard stale vectors
+        if (this.maxIdleMs > 0 && (now - latest.t > this.maxIdleMs)) {
+            if (this.flushOnConsumption) this.buffer = [];
+            return null;
+        }
+
+        const requiredDuration = this.windowLength * this.sampleIntervalMs;
         const threshold = latest.t - requiredDuration;
         const points = this.buffer.filter(p => p.t >= threshold);
 
-        if (points.length < 8) return null;
+        if (points.length < this.minPoints) return null;
 
         // Check synthetic dispatch
         const allTrusted = points.every(p => p.trusted === true);
@@ -84,7 +98,7 @@ export class MouseTelemetryCollector {
         const resampledY = new Float64Array(L);
         let rawIdx = 0;
 
-        // 1. Equispaced linear interpolation
+        // 2. Equispaced linear interpolation
         for (let i = 0; i < L; i++) {
             const targetT = startTime + i * dt;
             while (rawIdx < points.length - 2 && points[rawIdx + 1].t < targetT) {
@@ -99,7 +113,7 @@ export class MouseTelemetryCollector {
             resampledY[i] = p0.y + alpha * (p1.y - p0.y);
         }
 
-        // 2. Velocity Derivation
+        // 3. Velocity Derivation
         const velocity = new Float64Array(L);
         for (let i = 1; i < L; i++) {
             const dx = resampledX[i] - resampledX[i - 1];
@@ -108,6 +122,11 @@ export class MouseTelemetryCollector {
         }
         velocity[0] = velocity[1];
 
+        // 4. Buffer Flush on Consumption (Stops replay of identical kinematics across multiple clicks)
+        if (this.flushOnConsumption) {
+            this.buffer = [];
+        }
+
         return {
             velocity: Array.from(velocity),
             isTrusted: allTrusted,

package/src/client/index.js

@@ -8,6 +8,7 @@
  */
 
 export { MouseTelemetryCollector } from './collector.js';
+export { ShieldClient } from './shieldClient.js';
 
 /**
  * Injects invisible DOM tripwire decoy forms and links to trap automated scrapers

package/src/client/shieldClient.js

@@ -0,0 +1,118 @@
+/**
+ * ShieldClient - Browser Client SDK for Behavioral Biometrics & Tripwires
+ *
+ * Provides real-time mouse kinematics telemetry capture, freshness verification,
+ * replay protection, and transparent HTTP interceptors for fetch and Axios.
+ *
+ * @author ChdLabs
+ * @license MIT
+ */
+import { MouseTelemetryCollector } from './collector.js';
+import { injectTripwire } from './index.js';
+
+export class ShieldClient {
+    /**
+     * @param {Object} [options={}]
+     * @param {number} [options.windowLength=128]
+     * @param {number} [options.sampleIntervalMs=10]
+     * @param {number} [options.maxIdleMs=2500] Discard stale trajectory if pointer idle > 2.5s
+     * @param {number} [options.minPoints=15] Require at least 15 events
+     * @param {boolean} [options.flushOnConsumption=true] Flush buffer after reading payload
+     * @param {boolean} [options.autoInjectTripwire=false] Auto-inject decoy honeypot trap into DOM
+     */
+    constructor(options = {}) {
+        this.options = options;
+        this.collector = new MouseTelemetryCollector(options);
+
+        if (options.autoInjectTripwire && typeof document !== 'undefined') {
+            injectTripwire();
+        }
+    }
+
+    /**
+     * Begin recording pointer movements
+     */
+    start() {
+        this.collector.start();
+    }
+
+    /**
+     * Stop recording pointer movements
+     */
+    stop() {
+        this.collector.stop();
+    }
+
+    /**
+     * Extract normalized 128-sample kinematic telemetry vector
+     * @returns {{ velocity: number[], isTrusted: boolean, timestamp: number } | null}
+     */
+    getPayload() {
+        return this.collector.getPayload();
+    }
+
+    /**
+     * Transparently instrument window.fetch to attach x-shield-telemetry header
+     * @param {Object} [options={}]
+     * @param {string} [options.headerName='x-shield-telemetry']
+     * @param {string[]} [options.endpoints=['*']] URL patterns to match (e.g. ['/api/auth/*', '/checkout'])
+     */
+    instrumentFetch({ headerName = 'x-shield-telemetry', endpoints = ['*'] } = {}) {
+        if (typeof window === 'undefined' || typeof window.fetch !== 'function') return;
+        const originalFetch = window.fetch;
+        const client = this;
+
+        window.fetch = async function(input, init = {}) {
+            let url = typeof input === 'string' ? input : (input?.url || '');
+
+            const isMatch = endpoints.some(pattern => {
+                if (pattern === '*' || pattern === '/*') return true;
+                if (pattern.endsWith('*')) return url.startsWith(pattern.slice(0, -1));
+                return url === pattern;
+            });
+
+            if (isMatch) {
+                const payload = client.getPayload();
+                if (payload) {
+                    const headers = new Headers(init.headers || {});
+                    headers.set(headerName, JSON.stringify(payload));
+                    init = { ...init, headers };
+                }
+            }
+
+            return originalFetch.call(this, input, init);
+        };
+    }
+
+    /**
+     * Transparently instrument an Axios instance to attach telemetry headers
+     * @param {Object} axiosInstance Axios instance
+     * @param {Object} [options={}]
+     * @param {string} [options.headerName='x-shield-telemetry']
+     * @param {string[]} [options.endpoints=['*']]
+     */
+    instrumentAxios(axiosInstance, { headerName = 'x-shield-telemetry', endpoints = ['*'] } = {}) {
+        if (!axiosInstance || !axiosInstance.interceptors || !axiosInstance.interceptors.request) return;
+        const client = this;
+
+        axiosInstance.interceptors.request.use((config) => {
+            const url = config.url || '';
+            const isMatch = endpoints.some(pattern => {
+                if (pattern === '*' || pattern === '/*') return true;
+                if (pattern.endsWith('*')) return url.startsWith(pattern.slice(0, -1));
+                return url === pattern;
+            });
+
+            if (isMatch) {
+                const payload = client.getPayload();
+                if (payload) {
+                    config.headers = config.headers || {};
+                    config.headers[headerName] = JSON.stringify(payload);
+                }
+            }
+            return config;
+        });
+    }
+}
+
+export default ShieldClient;