yusufkhon-guard 1.0.0

package/src/modules/connectionGuard.js

@@ -0,0 +1,128 @@
+'use strict';
+
+/**
+ * @file connectionGuard.js
+ * @description Ulanish (soket) darajasidagi L7 DDoS himoyasi — Slowloris va
+ *              slow-POST hujumlariga qarshi. Bunday hujumlar so'rovni ataylab
+ *              juda sekin yuborib, server soketlarini uzoq band qilib qo'yadi.
+ *
+ *              Himoya choralari:
+ *                • sarlavha va butun so'rovni qabul qilish uchun timeout;
+ *                • bo'sh turgan (idle) soketni uzish;
+ *                • bitta IP dan ochilishi mumkin bo'lgan ulanishlar sonini cheklash.
+ *
+ *              Bu — middleware EMAS, balki `http`/`https` serverga biriktiriladigan
+ *              yordamchi funksiya.
+ * @module modules/connectionGuard
+ */
+
+const { defaultLogger } = require('../utils/logger');
+
+/**
+ * @typedef {Object} ConnectionGuardOptions
+ * @property {number} [headersTimeoutMs=10000] - Sarlavhalarni to'liq qabul qilish muddati (Slowloris, Node ichki).
+ * @property {number} [requestTimeoutMs=20000] - Butun so'rovni qabul qilish muddati, slow-POST (0 -> o'chirilgan).
+ * @property {number} [idleSocketMs=10000] - Soket shu vaqt davomida jim tursa (ma'lumot kelmasa) uziladi — TEZKOR Slowloris himoyasi.
+ * @property {number} [keepAliveTimeoutMs=5000] - Bo'sh Keep-Alive ulanishini yopish muddati.
+ * @property {number} [checkIntervalMs=2000] - Node'ning headersTimeout/requestTimeout ni tez-tez tekshirish oralig'i.
+ * @property {number} [maxConnectionsPerIp=50] - Bitta IP dan maksimal parallel ulanishlar.
+ * @property {string[]} [whitelist] - Cheklovsiz IP'lar.
+ * @property {import('./firewall').Firewall} [firewall] - Suiiste'molchini bloklash uchun (ixtiyoriy).
+ * @property {import('../utils/logger').Logger} [logger=defaultLogger] - Logger.
+ */
+
+/** @type {ConnectionGuardOptions} */
+const DEFAULTS = {
+  headersTimeoutMs: 10000,
+  requestTimeoutMs: 20000,
+  idleSocketMs: 10000,
+  keepAliveTimeoutMs: 5000,
+  checkIntervalMs: 2000,
+  maxConnectionsPerIp: 50,
+  whitelist: ['127.0.0.1', '::1'],
+};
+
+/**
+ * `http`/`https` serverga Slowloris himoyasini biriktiradi.
+ *
+ * @example
+ * const http = require('http');
+ * const { connectionGuard } = require('yusufkhon-guard');
+ * const server = http.createServer(app);
+ * connectionGuard(server, { maxConnectionsPerIp: 40 });
+ * server.listen(3000);
+ *
+ * @param {import('http').Server} server - HTTP/HTTPS server.
+ * @param {ConnectionGuardOptions} [options={}]
+ * @returns {import('http').Server} O'sha server (zanjirlash uchun).
+ */
+function connectionGuard(server, options = {}) {
+  const opts = { ...DEFAULTS, ...options };
+  const logger = opts.logger || defaultLogger;
+  const whitelist = new Set(opts.whitelist || []);
+
+  // Node HTTP server timeout'lari (Slowloris/slow-POST himoyasi).
+  //   headersTimeout — sarlavhalarni sekin yuborishga qarshi;
+  //   requestTimeout — butun so'rovni sekin yuborishga qarshi;
+  //   keepAliveTimeout — bo'sh keep-alive ulanishini yopadi.
+  // Node bu timeout'larni `connectionsCheckingInterval` (standart 30s!) bo'yicha
+  // tekshiradi — uni tezlashtiramiz, aks holda buzilish 30s kech seziladi.
+  server.headersTimeout = opts.headersTimeoutMs;
+  if (opts.requestTimeoutMs) server.requestTimeout = opts.requestTimeoutMs;
+  server.keepAliveTimeout = opts.keepAliveTimeoutMs;
+  if (opts.checkIntervalMs) {
+    server.connectionsCheckingInterval = opts.checkIntervalMs;
+  }
+
+  /** @type {Map<string, number>} IP -> ochiq ulanishlar soni. */
+  const perIp = new Map();
+
+  server.on('connection', (socket) => {
+    const ip = socket.remoteAddress ? socket.remoteAddress.replace(/^::ffff:/, '') : 'unknown';
+
+    if (!whitelist.has(ip)) {
+      const count = (perIp.get(ip) || 0) + 1;
+      perIp.set(ip, count);
+
+      // Bitta IP dan juda ko'p ulanish -> uzamiz.
+      if (count > opts.maxConnectionsPerIp) {
+        logger.blocked(ip, 'Slowloris: per-IP ulanishlar chegarasi', { connections: count, limit: opts.maxConnectionsPerIp });
+        if (opts.firewall) opts.firewall.blocker.addStrike(ip, 35, 'Connection flood');
+        socket.destroy();
+        const n = (perIp.get(ip) || 1) - 1;
+        if (n <= 0) perIp.delete(ip); else perIp.set(ip, n);
+        return;
+      }
+
+      socket.on('close', () => {
+        const n = (perIp.get(ip) || 1) - 1;
+        if (n <= 0) perIp.delete(ip); else perIp.set(ip, n);
+      });
+    }
+
+    // TEZKOR Slowloris himoyasi: soket `idleSocketMs` davomida jim tursa
+    // (ma'lumot kelmasa) — uzamiz. Har yangi ma'lumotda taymer qayta boshlanadi.
+    if (opts.idleSocketMs) {
+      socket.setTimeout(opts.idleSocketMs, () => {
+        logger.warn('Slowloris: jim/sekin soket uzildi', { ip });
+        socket.destroy();
+      });
+    }
+  });
+
+  // requestTimeout ishlaganda (sekin so'rov) 408 qaytaradi — buni loglaymiz.
+  server.on('timeout', (socket) => {
+    try { socket.destroy(); } catch { /* ignore */ }
+  });
+
+  logger.info('connectionGuard yoqildi (Slowloris/slow-POST himoyasi).', {
+    headersTimeoutMs: opts.headersTimeoutMs,
+    requestTimeoutMs: opts.requestTimeoutMs,
+    maxConnectionsPerIp: opts.maxConnectionsPerIp,
+  });
+
+  return server;
+}
+
+module.exports = connectionGuard;
+module.exports.connectionGuard = connectionGuard;

package/src/modules/csrf.js

@@ -0,0 +1,130 @@
+'use strict';
+
+/**
+ * @file csrf.js
+ * @description CSRF (Cross-Site Request Forgery) himoyasi. O'zgartiruvchi
+ *              so'rovlarni (POST/PUT/PATCH/DELETE) `Origin`/`Referer` sarlavhalari
+ *              orqali tekshiradi va begona (cross-site) manbadan kelgan
+ *              so'rovlarni bloklaydi.
+ *
+ *              Sabab: brauzerlar cross-site so'rovlarga `Origin` sarlavhasini
+ *              qo'yadi; agar u ruxsat etilgan hostlar ro'yxatiga kirmasa —
+ *              so'rov soxta manbadan kelgan bo'lishi mumkin.
+ * @module modules/csrf
+ */
+
+const { defaultLogger } = require('../utils/logger');
+
+/**
+ * @typedef {Object} CsrfOptions
+ * @property {string[]} [allowedOrigins] - Ruxsat etilgan originlar (masalan, 'https://mysite.uz'). Bo'sh -> so'rov hostiga tenglashtiriladi.
+ * @property {boolean} [trustSameHost=true] - Origin host === so'rov hosti bo'lsa ruxsat berish.
+ * @property {string[]} [methods] - Tekshiriladigan metodlar (standart: POST/PUT/PATCH/DELETE).
+ * @property {boolean} [requireOrigin=false] - Origin/Referer umuman bo'lmasa ham bloklash.
+ * @property {boolean} [allowNullOrigin=false] - `Origin: null` (sandboxed iframe/opaque) ni ochiq ruxsat berish. Standart holatda RAD etiladi.
+ * @property {(req: import('express').Request) => boolean} [skip] - Ba'zi so'rovlarni o'tkazib yuborish (masalan, webhook, API-key).
+ * @property {number} [statusCode=403] - Bloklash status kodi.
+ * @property {import('../utils/logger').Logger} [logger=defaultLogger] - Logger.
+ */
+
+/** @type {string[]} */
+const STATE_CHANGING = ['POST', 'PUT', 'PATCH', 'DELETE'];
+
+/**
+ * URL'dan origin (protokol + host) ni ajratadi.
+ * @private
+ * @param {string} value
+ * @returns {string|null}
+ */
+function originOf(value) {
+  try {
+    const u = new URL(value);
+    return `${u.protocol}//${u.host}`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * CSRF himoya middleware'ini yaratadi.
+ *
+ * @example
+ * const { csrf } = require('yusufkhon-guard');
+ * app.use(csrf({ allowedOrigins: ['https://mysite.uz'] }));
+ *
+ * @param {CsrfOptions} [options={}]
+ * @returns {import('express').RequestHandler}
+ */
+function csrf(options = {}) {
+  const logger = options.logger || defaultLogger;
+  const methods = new Set((options.methods || STATE_CHANGING).map((m) => m.toUpperCase()));
+  const allowed = new Set(options.allowedOrigins || []);
+  const trustSameHost = options.trustSameHost !== false;
+  const statusCode = options.statusCode || 403;
+
+  /**
+   * @param {import('express').Request} req
+   * @param {import('express').Response} res
+   * @param {import('express').NextFunction} next
+   */
+  return function csrfMiddleware(req, res, next) {
+    if (!methods.has(req.method)) return next();
+    if (typeof options.skip === 'function' && options.skip(req)) return next();
+
+    const headers = req.headers || {};
+
+    const reject = (reason) => {
+      logger.blocked(req.ip || 'unknown', `CSRF: ${reason}`, { method: req.method, path: req.originalUrl || req.url });
+      return res.status
+        ? res.status(statusCode).json({ success: false, error: 'CSRF tekshiruvidan o\'tmadi (begona manba).' })
+        : (res.statusCode = statusCode, res.end('Forbidden'));
+    };
+
+    /**
+     * Berilgan origin (protokol//host) ruxsatlimi — ro'yxatda yoki same-host.
+     * @param {string} value
+     * @returns {boolean}
+     */
+    const isAllowedOrigin = (value) => {
+      if (allowed.has(value)) return true;
+      if (trustSameHost) {
+        const host = headers['host'];
+        if (host && value.endsWith('//' + host)) return true;
+      }
+      return false;
+    };
+
+    const rawOrigin = headers['origin'];
+
+    // 1. Origin sarlavhasi MAVJUD bo'lsa — u asosiy (authoritative) manba.
+    if (rawOrigin !== undefined && rawOrigin !== '') {
+      const parsed = originOf(rawOrigin);
+
+      // `Origin: null` yoki buzuq/opaque — bu "Origin yo'q" bilan BIR XIL EMAS.
+      // Bu mavjud, lekin ishonchsiz (sandboxed iframe, file:) manba. Administrator
+      // `allowNullOrigin: true` bermasa, HAR DOIM (requireOrigin holatidan
+      // qat'i nazar) RAD etiladi.
+      if (parsed === null) {
+        if (options.allowNullOrigin === true) return next();
+        return reject('null/opaque origin');
+      }
+
+      if (isAllowedOrigin(parsed)) return next();
+      return reject(`ruxsatsiz origin ${parsed}`);
+    }
+
+    // 2. Origin yo'q — Referer'ga zaxira (fallback) sifatida qaraymiz.
+    const refOrigin = headers['referer'] ? originOf(headers['referer']) : null;
+    if (refOrigin) {
+      if (isAllowedOrigin(refOrigin)) return next();
+      return reject(`ruxsatsiz referer origin ${refOrigin}`);
+    }
+
+    // 3. Origin ham, Referer ham umuman yo'q — lenient (yoki requireOrigin bilan qattiq).
+    if (options.requireOrigin) return reject('Origin/Referer yo\'q');
+    return next();
+  };
+}
+
+module.exports = csrf;
+module.exports.csrf = csrf;

package/src/modules/dashboard.js

@@ -0,0 +1,257 @@
+'use strict';
+
+/**
+ * @file dashboard.js
+ * @description Bloklangan IP'lar va xavfsizlik hodisalarini REAL VAQTDA
+ *              ko'rsatuvchi web admin-panel. Express ilovasiga oddiy middleware
+ *              sifatida ulanadi va o'zi marshrutlaydi (tashqi kutubxonasiz).
+ *
+ *              Real vaqt yangilanishlari Server-Sent Events (SSE) orqali beriladi.
+ *              Barcha /api yo'llari token bilan himoyalangan.
+ * @module modules/dashboard
+ */
+
+const crypto = require('crypto');
+const { renderDashboard } = require('./dashboardHtml');
+const { defaultLogger } = require('../utils/logger');
+
+/**
+ * @typedef {Object} DashboardOptions
+ * @property {import('./firewall').Firewall} firewall - Kuzatiladigan Firewall nusxasi (majburiy).
+ * @property {import('express').RequestHandler & { ddos: import('events').EventEmitter, metrics: Object }} [ddos] - L7 DDoS middleware (ixtiyoriy) — Attack Mode indikatori uchun.
+ * @property {string} [token] - Kirish tokeni. Berilmasa — avtomat yaratiladi va log qilinadi.
+ * @property {string} [title='yusufkhon-guard'] - Panel sarlavhasi.
+ * @property {import('../utils/logger').Logger} [logger=defaultLogger] - Logger.
+ */
+
+/**
+ * Firewall hodisasi yukini (payload) tarmoq orqali yuborishga XAVFSIZ
+ * (JSON'ga aylantiriladigan) ko'rinishga keltiradi — `req` kabi aylanma
+ * (circular) obyektlarni chiqarib tashlaydi.
+ * @private
+ * @param {string} type
+ * @param {Object} payload
+ * @returns {Object}
+ */
+function safeEvent(type, payload = {}) {
+  const base = { type, at: Date.now() };
+  switch (type) {
+    case 'ban':
+      return { ...base, ip: payload.ip, reason: payload.reason };
+    case 'blocked':
+      return { ...base, ip: payload.ip, path: payload.path };
+    case 'threat':
+      return {
+        ...base,
+        ip: payload.ip,
+        severity: payload.report && payload.report.severity,
+        score: payload.report && payload.report.score,
+        types: payload.report && payload.report.signals
+          ? payload.report.signals.map((s) => s.type)
+          : [],
+      };
+    case 'tick':
+      return { ...base, stats: payload };
+    default:
+      return base;
+  }
+}
+
+/**
+ * JSON javob yuboradi (Express `res.json` bo'lmasa ham ishlaydi).
+ * @private
+ * @param {import('http').ServerResponse} res
+ * @param {number} status
+ * @param {Object} body
+ * @returns {void}
+ */
+function sendJson(res, status, body) {
+  res.statusCode = status;
+  res.setHeader('Content-Type', 'application/json; charset=utf-8');
+  res.end(JSON.stringify(body));
+}
+
+/**
+ * Real vaqtli web admin-panelni Express middleware sifatida yaratadi.
+ *
+ * @example
+ * const guard = require('yusufkhon-guard');
+ * const shield = guard({ firewall: {} });
+ * app.use(shield);
+ * app.use('/admin', guard.dashboard({ firewall: shield.firewall, token: 'maxfiy' }));
+ * // Brauzer: http://localhost:3000/admin/?token=maxfiy
+ *
+ * @param {DashboardOptions} options
+ * @returns {import('express').RequestHandler & { token: string, close: () => void }}
+ */
+function dashboard(options = {}) {
+  const firewall = options.firewall;
+  const logger = options.logger || defaultLogger;
+  const title = options.title || 'yusufkhon-guard';
+  const token = options.token || crypto.randomBytes(16).toString('hex');
+
+  if (!firewall || typeof firewall.on !== 'function') {
+    throw new Error('dashboard(): `firewall` nusxasi majburiy (guard({...}).firewall).');
+  }
+
+  if (!options.token) {
+    logger.warn(`Dashboard tokeni avtomat yaratildi: ${token} (uni saqlab qo'ying)`);
+  }
+
+  /** @type {Set<import('http').ServerResponse>} SSE ga ulangan mijozlar. */
+  const clients = new Set();
+
+  /**
+   * Barcha ulangan SSE mijozlariga hodisa yuboradi.
+   * @param {Object} event - safeEvent() natijasi.
+   */
+  function broadcast(event) {
+    const line = `data: ${JSON.stringify(event)}\n\n`;
+    for (const res of clients) {
+      try {
+        res.write(line);
+      } catch {
+        clients.delete(res);
+      }
+    }
+  }
+
+  // Firewall hodisalariga obuna bo'lamiz.
+  const listeners = {
+    ban: (p) => broadcast(safeEvent('ban', p)),
+    blocked: (p) => broadcast(safeEvent('blocked', p)),
+    threat: (p) => broadcast(safeEvent('threat', p)),
+    tick: (p) => broadcast(safeEvent('tick', p)),
+  };
+  for (const [ev, fn] of Object.entries(listeners)) firewall.on(ev, fn);
+
+  // L7 DDoS Attack Mode hodisalari (ixtiyoriy).
+  const ddos = options.ddos;
+  if (ddos && ddos.ddos && typeof ddos.ddos.on === 'function') {
+    ddos.ddos.on('attack-start', (m) => broadcast({ type: 'attack', at: Date.now(), active: true, ...m }));
+    ddos.ddos.on('attack-end', (m) => broadcast({ type: 'attack', at: Date.now(), active: false, ...m }));
+  }
+
+  // Har 2 soniyada jonli statistikani yuboramiz (mijoz bo'lsa).
+  const statTimer = setInterval(() => {
+    if (clients.size === 0) return;
+    broadcast(safeEvent('tick', { ...firewall.metrics, ...firewall.blocker.stats() }));
+  }, 2000);
+  if (typeof statTimer.unref === 'function') statTimer.unref();
+
+  /**
+   * Joriy holat statistikasi.
+   * @returns {Object}
+   */
+  function getStats() {
+    return {
+      metrics: firewall.metrics,
+      store: firewall.blocker.stats(),
+      ddos: ddos && ddos.metrics ? ddos.metrics : null,
+      uptimeSec: Math.floor(process.uptime()),
+      startedAt: Date.now() - Math.floor(process.uptime() * 1000),
+    };
+  }
+
+  /**
+   * @param {import('express').Request} req
+   * @param {import('express').Response} res
+   * @param {import('express').NextFunction} next
+   */
+  function dashboardMiddleware(req, res, next) {
+    const parsed = new URL(req.url, 'http://localhost');
+    const pathname = parsed.pathname.replace(/\/+$/, '') || '/';
+    const qToken = parsed.searchParams.get('token');
+    const authed = qToken === token || req.headers['x-guard-token'] === token;
+
+    // 1. Panel sahifasi (HTML).
+    if (req.method === 'GET' && pathname === '/') {
+      res.statusCode = 200;
+      res.setHeader('Content-Type', 'text/html; charset=utf-8');
+      res.end(renderDashboard({ title, token: authed ? token : '', authed }));
+      return;
+    }
+
+    // 2. Real vaqt oqimi (SSE) — token bilan.
+    if (req.method === 'GET' && pathname === '/api/events') {
+      if (!authed) return sendJson(res, 401, { error: 'unauthorized' });
+      res.statusCode = 200;
+      res.setHeader('Content-Type', 'text/event-stream');
+      res.setHeader('Cache-Control', 'no-cache, no-transform');
+      res.setHeader('Connection', 'keep-alive');
+      res.write('retry: 3000\n\n');
+      res.write(`data: ${JSON.stringify(safeEvent('hello', {}))}\n\n`);
+      clients.add(res);
+      req.on('close', () => clients.delete(res));
+      return;
+    }
+
+    // 3. Boshqa barcha /api yo'llari — token talab qiladi.
+    if (pathname.startsWith('/api/')) {
+      if (!authed) return sendJson(res, 401, { error: 'unauthorized' });
+
+      if (req.method === 'GET' && pathname === '/api/stats') {
+        return sendJson(res, 200, { success: true, ...getStats() });
+      }
+
+      if (req.method === 'GET' && pathname === '/api/bans') {
+        return sendJson(res, 200, { success: true, banned: firewall.blocker.listBanned() });
+      }
+
+      // /api/unban/:ip
+      const unbanMatch = pathname.match(/^\/api\/unban\/(.+)$/);
+      if (req.method === 'POST' && unbanMatch) {
+        const ip = decodeURIComponent(unbanMatch[1]);
+        const ok = firewall.blocker.unban(ip);
+        logger.info(`Dashboard: unban ${ip} (${ok ? 'bajarildi' : 'topilmadi'})`);
+        return sendJson(res, 200, { success: ok, ip });
+      }
+
+      // /api/block/:ip
+      const blockMatch = pathname.match(/^\/api\/block\/(.+)$/);
+      if (req.method === 'POST' && blockMatch) {
+        const ip = decodeURIComponent(blockMatch[1]);
+        const reason = 'Dashboard orqali qo\'lda bloklandi';
+        // `ban()` haqiqiy BanRecord qaytaradi — 'ban' hodisasini record bilan
+        // emit qilamiz, shunda Alerter/SSE oqimi va custom handler'lar qo'lda
+        // bloklashdan ham xabardor bo'ladi (honeypot/ddosGuard bilan izchil).
+        const record = firewall.blocker.ban(ip, reason);
+        if (typeof firewall.emit === 'function') {
+          firewall.emit('ban', { ip, reason, record });
+        }
+        logger.info(`Dashboard: manual block ${ip}`);
+        return sendJson(res, 200, { success: true, ip });
+      }
+
+      // /api/allow/:ip (oq ro'yxatga qo'shish)
+      const allowMatch = pathname.match(/^\/api\/allow\/(.+)$/);
+      if (req.method === 'POST' && allowMatch) {
+        const ip = decodeURIComponent(allowMatch[1]);
+        firewall.blocker.allow(ip);
+        logger.info(`Dashboard: allow (whitelist) ${ip}`);
+        return sendJson(res, 200, { success: true, ip });
+      }
+
+      return sendJson(res, 404, { error: 'not_found' });
+    }
+
+    return next();
+  }
+
+  // Tashqaridan boshqarish uchun qo'shimchalar.
+  dashboardMiddleware.token = token;
+  dashboardMiddleware.close = () => {
+    clearInterval(statTimer);
+    for (const [ev, fn] of Object.entries(listeners)) firewall.removeListener(ev, fn);
+    for (const res of clients) {
+      try { res.end(); } catch { /* ignore */ }
+    }
+    clients.clear();
+  };
+
+  return dashboardMiddleware;
+}
+
+module.exports = dashboard;
+module.exports.dashboard = dashboard;
+module.exports.safeEvent = safeEvent;