@chdlabs/my-shield

High-performance, zero-latency security shield middleware for Express. Built with pure JavaScript probabilistic data structures (Bloom filter + LRU cache), honeypot traps, MiniRocket behavioral biometrics, pluggable threat persistence, and container-native enterprise IP resolution.

Highlights

• Sub-0.1ms Clean Pass: Legitimate requests pass through the L1 Bloom filter in < 0.1ms.
• Zero False-Positive Blocks: Two-tiered L1 caching (Bloom filter + LRU confirmed threat cache) guarantees statistical Bloom false positives are never blocked.
• Enterprise Client IP Resolution (IPResolver): Production-tested parsing for Cloudflare (CF-Connecting-IP), Akamai (True-Client-IP), Nginx (X-Real-IP), and multi-hop HAProxy chains (X-Forwarded-For) with IPv6-mapped IPv4 normalization and port stripping.
• Docker & Gateway Protection: Docker bridge gateways (172.17.0.1) and loopback addresses (127.0.0.1, ::1) are permanently immune from bans, preventing accidental container isolation.
• Mission-Critical Route Protection: First-class shield.strictBotGuard() to protect /login, /checkout, and /register against credential stuffing, carding (card testing), and automated account spam.
• Dual-Mode Behavioral Biometrics: Calibrated Ridge decision boundary (0.50) supporting non-blocking 'audit' mode (for searches and queries) alongside strict 'block' mode (for auth and checkout).
• First-Party Client SDK (@chdlabs/my-shield/client): Unified ShieldClient and PointerTelemetryCollector with mobile touch support (pointerdown, touchmove, tap dwell kinetics), pointer freshness guards ($t_{\text{idle}} \le 2.5\text{s}$), buffer flushes on consumption, and automatic fetch/Axios interceptors.
• Threat Footprint Harvester & Fast-Track Learning: Automatically harvests reconnaissance dictionaries from blocked/blacklisted scanners (e.g. /.ssh/id_ed25519, /secrets.json, /docker-compose.yml) and fast-tracks them into permanent honeypot traps (learned_malicious_probe).
• Modern Built-in Trap Signatures: Expanded DEFAULT_TRAP_ROUTES covering cloud manifests, container compose files, SSH keys, shell histories, SSL private keys, and database archive dumps.
• Reserved Route Immunity (reservedPaths): Protects legitimate application routes from ever being converted to traps, even when targeted by aggressive scanners.
• Pluggable Threat Persistence: Zero-overhead in-memory adapter, local JSON file persistence (FileStorageAdapter), or universal database hooks (PostgreSQL, MySQL, Redis, Prisma).
• Built-in Admin OTP / MFA Challenge Gate: Standalone, dark-mode OTP verification portal (shield.otpGate()) with timing-safe HMAC validation and brute-force protection.
• Silent Honeypot Decoys: Static trap routes (/.env, /wp-login.php, /.git/config, etc.) return a silent 200 OK decoy response and instantly blacklist scanners.
• 404 Anomaly & Intelligence: Captures every 404 URL probe, bans scanners probing $\ge 5$ unique paths in 60s, and auto-promotes frequent attack targets to active honeypots.
• Zero Production Dependencies: Pure JavaScript built exclusively with Node.js built-ins (crypto, fs, path, events, net).

Architecture

Incoming Request
       │
       ▼
┌───────────────────────────────────────┐
│ Enterprise IPResolver                 │
│ Cloudflare / Nginx / HAProxy / Direct │
│ Gateway Protection (172.17.0.1 Immune)│
└──────────────────┬────────────────────┘
                   ▼
┌───────────────────────────────────────┐
│ L1 Shield Guard                       │
│ 1. IP Whitelisted? ──▶ Pass           │
│ 2. Bloom Filter?   ──▶ False = Pass   │
│ 3. LRU Cache?      ──▶ Found = Block  │
└──────────────────┬────────────────────┘
                   ▼
┌───────────────────────────────────────┐
│ Honeypot Trap Router                  │
│ Hits sensitive path? ──▶ Silent 200   │
│                          Blacklist IP │
└──────────────────┬────────────────────┘
                   ▼
┌───────────────────────────────────────┐
│ Route-Level Bot Defenses (Optional)   │
│ • strictBotGuard() on /login & /pay   │
│ • behavioralGuard({ mode: 'audit' })  │
│ • costThrottle() on high-cost routes  │
└──────────────────┬────────────────────┘
                   ▼
┌───────────────────────────────────────┐
│ Application Routes (Your API)         │
└──────────────────┬────────────────────┘
                   ▼
┌───────────────────────────────────────┐
│ 404 Intelligence Collector            │
│ ≥ 5 unique 404s/60s? ──▶ Ban IP       │
│ Auto-promotes frequent targets        │
└───────────────────────────────────────┘

Installation

npm install @chdlabs/my-shield

Quick Start (Express)

import express from 'express';
import { createShield } from '@chdlabs/my-shield';

const app = express();

const shield = createShield({
  whitelist: ['127.0.0.1', '::1'],
  trustProxy: true, // Auto-resolve Cloudflare, Nginx, or HAProxy client IPs
  protectGateways: true, // Prevents 172.17.0.1 & loopbacks from ever being banned
  storage: 'file', // Persist bans to ./data/shield/blocked_ips.json across restarts
  admin: {
    enabled: true // Set to true to activate dashboard (Default: false)
  }
});

// Hydrate persisted threats into Bloom and LRU on application startup
await shield.init();

// 1. Mount main defense guard (FIRST middleware after parsing)
app.use(shield.middleware());

// 2. Mount honeypot trap router (BEFORE application routes)
app.use(shield.honeypot());

// 3. Application Routes
app.get('/api/catalog', (req, res) => res.json({ items: [] }));

// 4. Mount 404 intelligence collector (AFTER application routes)
app.use(shield.notFoundCollector());

// 5. Standalone OTP Protected Admin Console
app.use('/admin/shield', shield.otpGate({
  adminEmail: '[email protected]',
  async sendOtp(email, code) {
    // Send OTP via your email service (Nodemailer, SendGrid, etc.)
    console.log(`[OTP] Sent code ${code} to ${email}`);
  }
}));
app.use('/admin/shield', shield.adminRouter());

// Graceful shutdown: flushes intelligence and threat persistence to disk
process.on('SIGTERM', async () => {
  await shield.shutdown();
  process.exit(0);
});

Protecting Mission-Critical Routes (/login, /checkout, /register) From Bots

Automated bots attack high-value mutation endpoints in three distinct ways:

1. Credential Stuffing & Brute Force (/login): Trying thousands of leaked email/password combinations.
2. Card Testing / Carding (/checkout): Testing stolen credit card numbers, which triggers costly payment gateway decline fees and chargebacks.
3. Account Farming (/register): Creating fake accounts for spamming or exploiting promotional credits.

1. Backend Route Protection (shield.strictBotGuard())

Mount shield.strictBotGuard() directly on your sensitive POST endpoints. It verifies behavioral mouse dynamics, rejects synthetic or automated bot vectors with 403 Forbidden, and instantly auto-bans the attacker's IP:

import express from 'express';
import { createShield } from '@chdlabs/my-shield';

const app = express();
app.use(express.json());

const shield = createShield({ trustProxy: true });
await shield.init();

// Global ingress guard
app.use(shield.middleware());

// ── Protect High-Risk Mutations ──

// Protect Login against credential stuffing
app.post('/api/auth/login', shield.strictBotGuard(), (req, res) => {
  // Only authentic human users reach this handler!
  res.json({ success: true, token: 'session_token' });
});

// Protect User Registration against fake accounts
app.post('/api/auth/register', shield.strictBotGuard(), (req, res) => {
  res.json({ success: true, user: req.body.email });
});

// Protect Checkout: Combine Strict Bot Defense with Cost Throttling
app.post('/api/checkout',
  shield.strictBotGuard(),
  shield.costThrottle({ weight: 5, maxCost: 50, windowMs: 60000 }),
  (req, res) => {
    res.json({ success: true, orderId: 'ord_123' });
  }
);

// ── Protect High-Volume Reads with Audit Mode ──
// Does not reject searches, but logs kinematics and attaches X-Shield-Verdict header
app.get('/api/search', shield.behavioralGuard({ mode: 'audit' }), (req, res) => {
  res.json({ results: [] });
});

2. Frontend Client Integration (ShieldClient)

Install @chdlabs/my-shield in your frontend application (or import ./client).

The client captures human pointer micro-movements across desktop mice, trackpads, and mobile touchscreens (measuring both continuous trajectory gestures and button tap dwell kinetics). When instrumentFetch() is enabled, it automatically attaches the x-shield-telemetry header to your API requests:

// client/index.js (React, Vue, or Vanilla JS)
import { ShieldClient } from '@chdlabs/my-shield/client';

// 1. Initialize client SDK
const shieldClient = new ShieldClient({
  sampleIntervalMs: 10,
  windowLength: 128,
  minPoints: 15,          // Minimum raw events for continuous trajectories
  maxIdleMs: 2500,        // Freshness Guard: Discards trajectory if pointer idle > 2.5s
  captureTouch: true,     // Enables mobile touch & pointer dynamics
  minTapDwellMs: 20,      // Distinguishes genuine human taps from instant 0ms bot clicks
  flushOnConsumption: true, // Prevents replaying identical trajectories
  autoInjectTripwire: true // Injects invisible honeypot decoy trap into DOM
});

// 2. Start recording kinematics
shieldClient.start();

// 3. Transparently instrument fetch (or Axios)
shieldClient.instrumentFetch({
  headerName: 'x-shield-telemetry',
  endpoints: ['/api/auth/*', '/api/checkout*']
});

// Now standard fetch calls automatically include kinematics telemetry!
async function submitLogin(email, password) {
  try {
    const res = await fetch('/api/auth/login', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email, password })
    });

    if (res.status === 403) {
      const err = await res.json();
      if (err.shieldCode === 'AUTOMATED_KINEMATICS_DETECTED') {
        alert('Bot behavior detected. Please interact with the page normally.');
        return;
      }
    }

    const data = await res.json();
    console.log('Login successful:', data);
  } catch (err) {
    console.error('Request failed:', err);
  }
}

Enterprise Reverse Proxies & Gateway Protection

When deploying in Docker, Kubernetes, AWS, or behind Cloudflare, standard req.ip lookups fail or ban internal container gateways. IPResolver resolves this natively:

const shield = createShield({
  // Trust proxy headers: true | false | 'loopback,linklocal,uniquelocal'
  trustProxy: true,

  // Permanently protects Docker bridge (172.17.0.1) & loopbacks from bans
  protectGateways: true,

  // Optional custom subnets to shield from accidental bans
  protectedSubnets: ['10.0.0.1', '192.168.1.1']
});

Supported Proxy Headers (in priority order):

1. cf-connecting-ip (Cloudflare)
2. true-client-ip (Akamai & Cloudflare Enterprise)
3. x-real-ip (Nginx proxy_set_header X-Real-IP $remote_addr)
4. x-client-ip
5. x-forwarded-for (Multi-hop chains are parsed to find the first non-internal public IP)

If trustProxy: false is set (direct internet exposure without reverse proxy), all proxy headers are ignored to prevent header spoofing injection attacks.

Pluggable Threat Persistence

In containerized or serverless deployments, in-memory caches reset on every restart. Shield supports pluggable persistence adapters to maintain active threat bans:

1. Single-Container File Persistence (Zero External Dependencies)

const shield = createShield({
  storage: {
    type: 'file',
    directory: './data/shield',
    filename: 'blocked_ips.json',
    debounceMs: 500 // Debounced atomic writes
  }
});
await shield.init();

2. Database & Cache Persistence (PostgreSQL, Redis, MongoDB, Prisma)

Plug any database into Shield with three async callbacks:

const shield = createShield({
  storage: {
    async onLoad() {
      // Return active unexpired blocked IPs on boot
      const { rows } = await db.query(
        'SELECT ip, reason, metadata, expires_at AS "expiresAt" FROM blocked_threats WHERE expires_at IS NULL OR expires_at > NOW()'
      );
      return rows;
    },
    async onBlock(ip, reason, metadata, expiresAt) {
      // Save or update blocked threat
      await db.query(
        `INSERT INTO blocked_threats (ip, reason, metadata, expires_at)
         VALUES ($1, $2, $3, $4)
         ON CONFLICT (ip) DO UPDATE SET reason = $2, metadata = $3, expires_at = $4`,
        [ip, reason, JSON.stringify(metadata), expiresAt ? new Date(expiresAt) : null]
      );
    },
    async onUnblock(ip) {
      await db.query('DELETE FROM blocked_threats WHERE ip = $1', [ip]);
    }
  }
});

// Restores unexpired database threats into Bloom filter and LRU cache
await shield.init();

Built-in Admin OTP / MFA Challenge Gate

Shield includes a standalone, zero-dependency dark-mode OTP challenge gate (shield.otpGate()) that protects /admin/shield without requiring external login libraries:

app.use('/admin/shield', shield.otpGate({
  adminEmail: '[email protected]',
  jwtSecret: process.env.SHIELD_SECRET, // Signs session cookies
  codeTtlMs: 5 * 60 * 1000,             // Code valid for 5 minutes
  maxAttempts: 5,                        // Locks out after 5 invalid tries
  async sendOtp(email, code) {
    // Deliver via email or SMS
    await mailer.sendMail({
      to: email,
      subject: 'Shield Admin Passcode',
      text: `Your one-time passcode is: ${code}`
    });
  }
}));

// Mount dashboard router
app.use('/admin/shield', shield.adminRouter());

Configuration Reference

| Option | Type | Default | Description | |---|---|---|---| | whitelist | string[] | [] | List of IP addresses that are never blocked | | trustProxy | boolean\|string | 'loopback,linklocal,uniquelocal' | Reverse proxy trust configuration | | protectGateways | boolean | true | Protects Docker bridge (172.17.0.1) and loopback from bans | | storage | string\|Object | 'memory' | Storage adapter ('memory', 'file', or callback hooks) | | admin.enabled | boolean | false | Explicit switch to enable admin dashboard & telemetry | | bloom.expectedItems | number | 100000 | Estimated distinct IPs to hold in Bloom filter | | bloom.falsePositiveRate | number | 0.01 | Target false positive probability (1%) | | lru.maxSize | number | 10000 | Max entries in confirmed threat cache | | lru.ttlMs | number | 300000 | Threat cache TTL in ms (5 minutes) | | honeypot.enabled | boolean | true | Enable/disable static honeypot traps | | honeypot.delayMs | number | 500 | Delay before sending silent 200 OK decoy | | intelligence.anomalyThreshold | number | 5 | Unique 404s before IP is banned | | intelligence.anomalyWindowMs | number | 60000 | Sliding window in ms (60 seconds) |

Programmatic API

// Manual IP Governance
shield.blockIP('198.51.100.42', 'manual_ban', { admin: 'dev1' });
shield.unblockIP('198.51.100.42');
shield.allowIP('192.168.1.50');       // Add to whitelist
shield.isWhitelisted('192.168.1.50'); // Returns boolean

// Telemetry & Metrics
shield.getStats();          // Returns aggregate stats, LRU sizes, traps list
shield.getIntelligence();   // Full 404 intelligence snapshot
shield.getBloomHealth();    // Saturation percentage and estimated FPR

// Route-Level Bot Defenses
app.post('/api/auth/login', shield.strictBotGuard(), handler);
app.get('/api/search', shield.behavioralGuard({ mode: 'audit' }), handler);

// Denial-of-Wallet Cost Throttling
app.post('/api/ai-generate', shield.costThrottle({ weight: 10, maxCost: 100 }), handler);

// API Key / Secret Leak Detector
app.use(shield.keyLeakDetector());

License

MIT © CHDLabs