@chdlabs/my-shield 0.1.3 → 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/biometrics/index.js

@@ -0,0 +1,10 @@
+/**
+ * @file src/biometrics/index.js
+ * Behavioral Biometrics Engine Exports
+ *
+ * @author ChdLabs
+ * @license MIT
+ */
+
+export { MiniRocket } from './minirocket.js';
+export { DualRidgeClassifier } from './ridge.js';

package/src/biometrics/minirocket.js

@@ -0,0 +1,213 @@
+/**
+ * @file src/biometrics/minirocket.js
+ * Deterministic MiniRocket 1D Transform Engine
+ * High-performance, zero-dependency feature extractor using 84 fixed length-9 kernels
+ * with binary/ternary weights {-1, 2} and proportion of positive values (PPV).
+ *
+ * @author ChdLabs
+ * @license MIT
+ */
+
+const MR_KERNEL_LENGTH = 9;
+const MR_NUM_KERNELS = 84;
+
+export class MiniRocket {
+    /**
+     * @param {number} [windowLength=128] Length of the input kinematic series
+     * @param {number} [numFeatures=500] Number of MiniRocket PPV features to extract
+     */
+    constructor(windowLength = 128, numFeatures = 500) {
+        this.windowLength = windowLength;
+        this.targetFeatures = numFeatures;
+
+        this.kernelIndices = this._buildIndices();
+        this.dilations = this._buildDilations();
+        this.featureMap = this._buildFeatureMap();
+        this.thresholds = null;
+
+        // Pre-allocated scratch buffers to eliminate per-inference GC allocations
+        this._ca = new Float64Array(this.windowLength);
+        this._cg = new Float64Array(MR_KERNEL_LENGTH * this.windowLength);
+        this._c = new Float64Array(this.windowLength);
+    }
+
+    /**
+     * Build all C(9, 3) = 84 combinations of 3 positive kernel indices
+     * @private
+     */
+    _buildIndices() {
+        const indices = new Int32Array(MR_NUM_KERNELS * 3);
+        let p = 0;
+        for (let a = 0; a < MR_KERNEL_LENGTH; a++) {
+            for (let b = a + 1; b < MR_KERNEL_LENGTH; b++) {
+                for (let c = b + 1; c < MR_KERNEL_LENGTH; c++) {
+                    indices[p * 3 + 0] = a;
+                    indices[p * 3 + 1] = b;
+                    indices[p * 3 + 2] = c;
+                    p++;
+                }
+            }
+        }
+        return indices;
+    }
+
+    /**
+     * Compute multi-scale dilation schedule
+     * @private
+     */
+    _buildDilations() {
+        const maxExp = Math.log2((this.windowLength - 1) / (MR_KERNEL_LENGTH - 1));
+        const maxDilations = Math.min(32, Math.floor(this.targetFeatures / MR_NUM_KERNELS));
+        const dilations = [];
+
+        for (let i = 0; i < maxDilations; i++) {
+            const exponent = (i === maxDilations - 1) ? maxExp : (i * maxExp) / (maxDilations - 1);
+            const d = Math.floor(Math.pow(2, exponent));
+            if (!dilations.includes(d) && d >= 1) {
+                dilations.push(d);
+            }
+        }
+        return Int32Array.from(dilations);
+    }
+
+    /**
+     * Map feature indices to kernel index, dilation, and golden ratio quantile
+     * @private
+     */
+    _buildFeatureMap() {
+        const map = [];
+        const phi = (Math.sqrt(5) + 1) / 2;
+        let count = 0;
+
+        for (const d of this.dilations) {
+            for (let k = 0; k < MR_NUM_KERNELS; k++) {
+                if (count >= this.targetFeatures) break;
+                map.push({ kernelIdx: k, dilation: d, quantile: (count * phi) % 1.0 });
+                count++;
+            }
+            if (count >= this.targetFeatures) break;
+        }
+        return map;
+    }
+
+    /**
+     * Shared prefix sum computation across all kernels sharing dilation d
+     * @private
+     */
+    _convolveBase(x, d) {
+        const L = this.windowLength;
+        const padding = Math.floor(((MR_KERNEL_LENGTH - 1) * d) / 2);
+        const mid = Math.floor(MR_KERNEL_LENGTH / 2);
+
+        this._ca.fill(0);
+        this._cg.fill(0);
+
+        for (let i = 0; i < L; i++) {
+            this._ca[i] = -x[i];
+            this._cg[mid * L + i] = 3.0 * x[i];
+        }
+
+        let end = L - padding;
+        for (let g = 0; g < mid; g++) {
+            const e = Math.min(end, L);
+            if (e > 0) {
+                const off = L - e;
+                for (let j = 0; j < e; j++) {
+                    this._ca[off + j] -= x[j];
+                    this._cg[g * L + off + j] = 3.0 * x[j];
+                }
+            }
+            end += d;
+        }
+
+        let start = d;
+        for (let g = mid + 1; g < MR_KERNEL_LENGTH; g++) {
+            const m = L - start;
+            for (let j = 0; j < m; j++) {
+                this._ca[j] -= x[start + j];
+                this._cg[g * L + j] = 3.0 * x[start + j];
+            }
+            start += d;
+        }
+    }
+
+    /**
+     * Evaluate kernel output using precomputed prefix sums and 3 index lookups
+     * @private
+     */
+    _kernelOut(kernelIdx) {
+        const L = this.windowLength;
+        const i0 = this.kernelIndices[kernelIdx * 3 + 0] * L;
+        const i1 = this.kernelIndices[kernelIdx * 3 + 1] * L;
+        const i2 = this.kernelIndices[kernelIdx * 3 + 2] * L;
+
+        for (let i = 0; i < L; i++) {
+            this._c[i] = this._ca[i] + this._cg[i0 + i] + this._cg[i1 + i] + this._cg[i2 + i];
+        }
+    }
+
+    /**
+     * Load pre-computed bias thresholds
+     * @param {number[]|Float32Array} thresholdsArray
+     */
+    loadThresholds(thresholdsArray) {
+        this.thresholds = Float32Array.from(thresholdsArray);
+    }
+
+    /**
+     * Fit bias thresholds from a collection of training series
+     * @param {Array<number[]|Float64Array>} trainingWindows
+     */
+    fit(trainingWindows) {
+        const N = trainingWindows.length;
+        if (N === 0) throw new Error('Training windows cannot be empty.');
+        this.thresholds = new Float32Array(this.featureMap.length);
+
+        for (let f = 0; f < this.featureMap.length; f++) {
+            const feat = this.featureMap[f];
+            this._convolveBase(trainingWindows[f % N], feat.dilation);
+            this._kernelOut(feat.kernelIdx);
+
+            const sorted = Float64Array.from(this._c).sort();
+            const qIdx = Math.min(this.windowLength - 1, Math.floor(feat.quantile * this.windowLength));
+            this.thresholds[f] = sorted[qIdx];
+        }
+    }
+
+    /**
+     * Transform a 1D input series into Proportion of Positive Values (PPV) representation
+     * @param {number[]|Float64Array} series Equispaced series of length equal to windowLength
+     * @returns {Float32Array} PPV feature vector
+     */
+    transform(series) {
+        if (!this.thresholds) {
+            throw new Error('MiniRocket requires fitted or loaded thresholds.');
+        }
+        if (series.length !== this.windowLength) {
+            throw new Error(`Input series length (${series.length}) must match windowLength (${this.windowLength}).`);
+        }
+
+        const out = new Float32Array(this.featureMap.length);
+        let currentDilation = -1;
+
+        for (let f = 0; f < this.featureMap.length; f++) {
+            const feat = this.featureMap[f];
+
+            if (feat.dilation !== currentDilation) {
+                this._convolveBase(series, feat.dilation);
+                currentDilation = feat.dilation;
+            }
+
+            this._kernelOut(feat.kernelIdx);
+
+            const thresh = this.thresholds[f];
+            let pos = 0;
+            for (let i = 0; i < this.windowLength; i++) {
+                if (this._c[i] > thresh) pos++;
+            }
+            out[f] = pos / this.windowLength;
+        }
+
+        return out;
+    }
+}