yusufkhon-guard 1.0.0

package/src/modules/firewall.js

@@ -0,0 +1,239 @@
+'use strict';
+
+/**
+ * @file firewall.js
+ * @description "Blue Team" aktiv himoya yadrosi. `threatDetector` (aniqlash) va
+ *              `ipBlocker` (bloklash) ni birlashtiradi hamda serverni 24/7
+ *              kuzatib boradi. Har bir so'rovni real vaqtda tahlil qiladi,
+ *              tahdid sezilsa avtomat aks-ta'sir ko'rsatadi (IP'ni bloklaydi)
+ *              va hodisalarni tashqariga (webhook/telegram/email) uzatish uchun
+ *              EventEmitter chiqaradi.
+ * @module modules/firewall
+ */
+
+const { EventEmitter } = require('events');
+const threatDetector = require('./threatDetector');
+const { IpBlocker } = require('./ipBlocker');
+const { defaultKeyGenerator } = require('./rateLimiter');
+const { normalizeIp } = require('../utils/cidr');
+const { defaultLogger } = require('../utils/logger');
+
+/**
+ * So'rovning HAQIQIY ulanish (TCP soket) manzilini qaytaradi. Whitelist
+ * tekshiruvi shu manzil bo'yicha bo'lishi kerak — `X-Forwarded-For` sarlavhasi
+ * mijoz tomonidan soxtalashtirilishi mumkin, shu bois uni whitelist uchun
+ * ishonchli deb bo'lmaydi (aks holda hujumchi o'zini localhost qilib ko'rsatib
+ * himoyani chetlab o'tadi).
+ * @param {import('express').Request} req
+ * @returns {string} Normallashtirilgan soket manzili yoki bo'sh satr.
+ */
+function realClientIp(req) {
+  const sock = req.socket || req.connection;
+  const addr = sock && sock.remoteAddress;
+  return addr ? normalizeIp(addr) : '';
+}
+
+/**
+ * @typedef {Object} FirewallOptions
+ * @property {number} [banThreshold=100] - Bloklash uchun kerakli to'plangan ball.
+ * @property {number} [instantBanScore=80] - Bitta so'rovda shu balldan oshsa — darhol blok.
+ * @property {number} [strikeWindowMs=600000] - Ballar to'planadigan oyna (ms).
+ * @property {string[]} [whitelist] - Hech qachon bloklanmaydigan IP'lar.
+ * @property {string|null} [persistPath=null] - Bloklarni saqlash uchun fayl yo'li.
+ * @property {number} [statusCode=403] - Bloklangan IP uchun HTTP status.
+ * @property {string} [message] - Bloklangan IP uchun xabar.
+ * @property {boolean} [monitor=true] - 24/7 davriy holat monitoringini yoqish.
+ * @property {number} [monitorIntervalMs=300000] - Monitoring hisoboti oralig'i (5 daqiqa).
+ * @property {import('../utils/logger').Logger} [logger=defaultLogger] - Logger.
+ * @property {(req: import('express').Request) => string} [keyGenerator] - IP aniqlash.
+ */
+
+/**
+ * Standart sozlamalar.
+ * @type {FirewallOptions}
+ */
+const DEFAULT_OPTIONS = {
+  banThreshold: 100,
+  instantBanScore: 80,
+  strikeWindowMs: 10 * 60 * 1000,
+  statusCode: 403,
+  message: 'Access denied — bu IP xavfsizlik tizimi tomonidan bloklangan.',
+  monitor: true,
+  monitorIntervalMs: 5 * 60 * 1000,
+};
+
+/**
+ * Aktiv himoya (firewall) tizimi.
+ * `EventEmitter` dan meros oladi — quyidagi hodisalarni chiqaradi:
+ *  - `'threat'`  ({ ip, report, req }) — tahdid aniqlandi.
+ *  - `'ban'`     ({ ip, reason, record }) — IP bloklandi.
+ *  - `'blocked'` ({ ip, path }) — bloklangan IP qaytarildi.
+ *  - `'tick'`    (stats) — davriy monitoring hisoboti.
+ *
+ * @class
+ * @extends EventEmitter
+ */
+class Firewall extends EventEmitter {
+  /**
+   * @param {FirewallOptions} [userOptions={}]
+   */
+  constructor(userOptions = {}) {
+    super();
+    /** @type {FirewallOptions} */
+    this.options = { ...DEFAULT_OPTIONS, ...userOptions };
+    /** @type {import('../utils/logger').Logger} */
+    this.logger = this.options.logger || defaultLogger;
+    /** @type {(req: import('express').Request) => string} */
+    this.keyGenerator = this.options.keyGenerator || defaultKeyGenerator;
+
+    /** @type {IpBlocker} */
+    this.blocker = new IpBlocker({
+      banThreshold: this.options.banThreshold,
+      strikeWindowMs: this.options.strikeWindowMs,
+      whitelist: this.options.whitelist,
+      persistPath: this.options.persistPath,
+    });
+
+    /** @type {{requests: number, threats: number, bans: number, blocked: number}} */
+    this.metrics = { requests: 0, threats: 0, bans: 0, blocked: 0 };
+
+    if (this.options.monitor) this._startMonitor();
+  }
+
+  /**
+   * 24/7 davriy monitoringni ishga tushiradi — holat statistikasini loglaydi.
+   * @private
+   * @returns {void}
+   */
+  _startMonitor() {
+    this._monitorTimer = setInterval(() => {
+      const stats = { ...this.metrics, ...this.blocker.stats() };
+      this.logger.info('🛡️  Firewall monitoring', stats);
+      this.emit('tick', stats);
+    }, this.options.monitorIntervalMs);
+    if (typeof this._monitorTimer.unref === 'function') this._monitorTimer.unref();
+  }
+
+  /**
+   * Monitoringni to'xtatadi (test/graceful shutdown uchun).
+   * @returns {void}
+   */
+  stop() {
+    if (this._monitorTimer) clearInterval(this._monitorTimer);
+  }
+
+  /**
+   * Bloklangan IP uchun standart javob yuboradi.
+   * @private
+   * @param {import('express').Response} res
+   * @param {string} ip
+   * @returns {void}
+   */
+  _reject(res, ip) {
+    const secondsLeft = this.blocker.banSecondsLeft(ip);
+    if (secondsLeft > 0) res.setHeader('Retry-After', secondsLeft);
+    res.status(this.options.statusCode).json({
+      success: false,
+      error: this.options.message,
+      bannedFor: secondsLeft === -1 ? 'permanent' : `${secondsLeft}s`,
+    });
+  }
+
+  /**
+   * Firewall Express middleware'ini qaytaradi.
+   * @returns {import('express').RequestHandler}
+   */
+  middleware() {
+    const self = this;
+
+    /**
+     * @param {import('express').Request} req
+     * @param {import('express').Response} res
+     * @param {import('express').NextFunction} next
+     */
+    return function firewallMiddleware(req, res, next) {
+      self.metrics.requests += 1;
+      const ip = self.keyGenerator(req);
+      const realIp = realClientIp(req);
+      const reqPath = req.originalUrl || req.url;
+
+      // 1. Ishonchli IP — tekshiruvsiz o'tkazamiz.
+      //    MUHIM: whitelist HAQIQIY ulanish manzili (socket) bo'yicha tekshiriladi.
+      //    Bu spoofed `X-Forwarded-For: 127.0.0.1` orqali o'zini whitelist qilib
+      //    firewall'ni chetlab o'tishning oldini oladi. Soket manzili bo'lmasa
+      //    (kamdan-kam holat), atributsiya kalitiga qaytamiz.
+      if (realIp ? self.blocker.isWhitelisted(realIp) : self.blocker.isWhitelisted(ip)) {
+        return next();
+      }
+
+      // 2. Allaqachon bloklangan bo'lsa — darhol rad etamiz.
+      if (self.blocker.isBanned(ip)) {
+        self.metrics.blocked += 1;
+        self.logger.blocked(ip, 'Bloklangan IP qayta urindi', { path: reqPath });
+        self.emit('blocked', { ip, path: reqPath });
+        return self._reject(res, ip);
+      }
+
+      // 3. So'rovni tahlil qilamiz.
+      const report = threatDetector.analyze(req);
+
+      if (report.score > 0) {
+        self.metrics.threats += 1;
+        self.logger.warn(`Tahdid aniqlandi [${report.severity}] ${ip}`, {
+          score: report.score,
+          path: reqPath,
+          types: report.signals.map((s) => s.type),
+        });
+        self.emit('threat', { ip, report, req });
+
+        // 3a. Kritik tahdid — darhol bloklaymiz.
+        const instant = report.score >= self.options.instantBanScore;
+        const primaryReason = report.signals[0] ? report.signals[0].detail : 'Threat detected';
+
+        const outcome = instant
+          ? { banned: true, record: self.blocker.ban(ip, primaryReason) }
+          : self.blocker.addStrike(ip, report.score, primaryReason);
+
+        if (outcome.banned) {
+          self.metrics.bans += 1;
+          self.logger.blocked(ip, `AVTO-BLOK (${report.severity})`, {
+            path: reqPath,
+            reason: primaryReason,
+          });
+          self.emit('ban', { ip, reason: primaryReason, record: outcome.record });
+          return self._reject(res, ip);
+        }
+      }
+
+      next();
+    };
+  }
+}
+
+/**
+ * Firewall middleware yaratuvchi qulay funksiya.
+ * Yaratilgan middleware'ga `.firewall` orqali Firewall nusxasi biriktiriladi
+ * (hodisalarga obuna bo'lish va boshqarish uchun).
+ *
+ * @example
+ * const { firewall } = require('yusufkhon-guard');
+ * const fw = firewall({ persistPath: './logs/bans.json' });
+ * fw.firewall.on('ban', ({ ip, reason }) => {
+ *   // Telegram/Email/Webhook orqali xabar berish
+ *   console.log('Bloklandi:', ip, reason);
+ * });
+ * app.use(fw);
+ *
+ * @param {FirewallOptions} [options={}]
+ * @returns {import('express').RequestHandler & { firewall: Firewall }}
+ */
+function firewall(options = {}) {
+  const instance = new Firewall(options);
+  const mw = instance.middleware();
+  mw.firewall = instance;
+  return mw;
+}
+
+module.exports = firewall;
+module.exports.firewall = firewall;
+module.exports.Firewall = Firewall;

package/src/modules/geoBlock.js

@@ -0,0 +1,169 @@
+'use strict';
+
+/**
+ * @file geoBlock.js
+ * @description Hududiy (Geo-IP) va datacenter/VPN himoyasi. Faqat ruxsat berilgan
+ *              davlatlardan kirishga ruxsat berish, yoki ma'lum davlatlarni
+ *              bloklash, hamda VPN/proxy/datacenter IP'larini cheklash.
+ *
+ *              Davlatni aniqlash uchun `lookup(ip) => countryCode` funksiyasi
+ *              beriladi. Agar berilmasa va ixtiyoriy `geoip-lite` paketi
+ *              o'rnatilgan bo'lsa — o'sha ishlatiladi (zero-dependency saqlanadi).
+ * @module modules/geoBlock
+ */
+
+const datacenter = require('./datacenterRanges');
+const { normalizeIp } = require('../utils/cidr');
+const { defaultLogger } = require('../utils/logger');
+
+/**
+ * So'rovni baholash uchun ISHONCHLI mijoz IP'sini aniqlaydi.
+ * Ustuvorlik: `req.ip` (Express'ning `trust proxy` sozlamasiga bo'ysunadi —
+ * administrator belgilagan ishonchli manba), so'ng haqiqiy TCP soket manzili.
+ * Xom `X-Forwarded-For` sarlavhasiga TAYANMAYDI — u mijoz tomonidan
+ * soxtalashtirilishi mumkin (spoofing).
+ * @private
+ * @param {import('express').Request} req
+ * @returns {string} Normallashtirilgan IP yoki bo'sh satr.
+ */
+function trustedClientIp(req) {
+  if (req.ip) return normalizeIp(req.ip);
+  const sock = req.socket || req.connection;
+  const addr = sock && sock.remoteAddress;
+  return addr ? normalizeIp(addr) : '';
+}
+
+/**
+ * `geoip-lite` (ixtiyoriy peer) mavjud bo'lsa, undan lookup funksiyasi yasaydi.
+ * @private
+ * @returns {((ip: string) => string|null)|null}
+ */
+function tryGeoipLite() {
+  try {
+    // eslint-disable-next-line global-require
+    const geoip = require('geoip-lite');
+    return (ip) => {
+      const r = geoip.lookup(ip);
+      return r ? r.country : null;
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @typedef {Object} GeoBlockOptions
+ * @property {string[]} [allowCountries] - Faqat shu davlatlardan (ISO-2, masalan 'UZ','US') ruxsat.
+ * @property {string[]} [denyCountries] - Shu davlatlarni bloklash (allowCountries berilmaganda).
+ * @property {boolean} [blockDatacenter=false] - Datacenter/hosting IP'larini bloklash.
+ * @property {boolean} [blockVpn=false] - Ma'lum VPN diapazonlarini bloklash (blockDatacenter ichida ham bor).
+ * @property {(ip: string) => (string|null)} [lookup] - IP -> davlat kodi funksiyasi.
+ * @property {string[]} [whitelist] - Hech qachon bloklanmaydigan IP'lar.
+ * @property {boolean} [allowUnknown] - Davlati aniqlanmagan (null) IP'ga ruxsat. STANDART: denylist'da `true`, allowlist'da `false` (xavfsiz).
+ * @property {boolean} [failClosed] - `lookup` XATO (exception) tashlasa RAD etilsinmi. STANDART: allowlist'da `true`, denylist'da `false`.
+ * @property {number} [statusCode=403] - Bloklashda status kodi.
+ * @property {string} [message] - Bloklash xabari.
+ * @property {import('./firewall').Firewall} [firewall] - Berilsa, bloklangan IP firewall'ga strike qo'shadi.
+ * @property {import('../utils/logger').Logger} [logger=defaultLogger] - Logger.
+ */
+
+/**
+ * Geo-IP / datacenter / VPN himoya middleware'ini yaratadi.
+ *
+ * @example
+ * const { geoBlock } = require('yusufkhon-guard');
+ * app.use(geoBlock({ allowCountries: ['UZ','US'], blockDatacenter: true }));
+ *
+ * @param {GeoBlockOptions} [options={}]
+ * @returns {import('express').RequestHandler}
+ */
+function geoBlock(options = {}) {
+  const logger = options.logger || defaultLogger;
+  const allow = (options.allowCountries || []).map((c) => c.toUpperCase());
+  const deny = (options.denyCountries || []).map((c) => c.toUpperCase());
+  const whitelist = new Set(options.whitelist || ['127.0.0.1', '::1']);
+
+  // XAVFSIZ-BY-DEFAULT: allowlist (allowCountries) rejimida davlatni aniqlab
+  // bo'lmasa (null natija YOKI lookup xatosi) — RAD etamiz; aks holda geo-bazada
+  // bo'lmagan istalgan IP allowlist'ni jimgina chetlab o'tar edi. Denylist
+  // rejimida esa noma'lumlarni o'tkazamiz (permissive). Ikkalasini ham ochiq
+  // override qilish mumkin (allowUnknown / failClosed).
+  const isAllowlist = allow.length > 0;
+  const allowUnknown = options.allowUnknown !== undefined ? options.allowUnknown : !isAllowlist;
+  const failClosed = options.failClosed !== undefined ? options.failClosed : isAllowlist;
+
+  const statusCode = options.statusCode || 403;
+  const message = options.message || 'Access denied — sizning hududingizdan kirish cheklangan.';
+
+  const lookup = options.lookup || tryGeoipLite();
+  if ((allow.length || deny.length) && !lookup) {
+    logger.warn('geoBlock: davlat bo\'yicha filtrlash uchun `lookup` funksiyasi yoki `geoip-lite` kerak. Geo-qism o\'tkazib yuboriladi.');
+  }
+
+  /**
+   * @param {import('express').Request} req
+   * @param {import('express').Response} res
+   * @param {import('express').NextFunction} next
+   */
+  return function geoBlockMiddleware(req, res, next) {
+    // ISHONCHLI IP (req.ip yoki soket) — spooflanadigan xom XFF'ga tayanmaymiz.
+    const ip = trustedClientIp(req);
+    if (!ip || whitelist.has(ip)) return next();
+
+    /**
+     * So'rovni rad etadi (va ixtiyoriy firewall'ga strike qo'shadi).
+     * @param {string} reason
+     */
+    const reject = (reason) => {
+      logger.blocked(ip, `Geo/DC blok: ${reason}`, { path: req.originalUrl || req.url });
+      if (options.firewall) {
+        options.firewall.blocker.addStrike(ip, 60, `Geo/DC: ${reason}`);
+      }
+      res.status ? res.status(statusCode).json({ success: false, error: message, reason })
+        : (res.statusCode = statusCode, res.end(JSON.stringify({ success: false, error: message })));
+    };
+
+    // 1. Datacenter / VPN tekshiruvi.
+    if (options.blockDatacenter || options.blockVpn) {
+      const dc = datacenter.detect(ip);
+      if (dc) {
+        return reject(`${dc.provider} (datacenter/VPN)`);
+      }
+    }
+
+    // 2. Davlat bo'yicha filtrlash.
+    if (lookup && (allow.length || deny.length)) {
+      let country = null;
+      let lookupFailed = false;
+      try { country = lookup(ip); } catch { lookupFailed = true; }
+
+      // lookup XATO tashladi. Qat'iy rejimda (failClosed) — RAD. Aks holda
+      // "davlat noaniq" sifatida allowUnknown qoidasiga o'tamiz.
+      if (lookupFailed && failClosed) {
+        return reject('geo-lookup xatosi (fail-closed)');
+      }
+
+      if (!country) {
+        if (!allowUnknown) return reject('davlat aniqlanmadi');
+        return next();
+      }
+
+      country = country.toUpperCase();
+
+      // Allow-list rejimi: faqat ruxsat berilganlar o'tadi.
+      if (allow.length && !allow.includes(country)) {
+        return reject(`davlat ${country} ruxsat etilmagan`);
+      }
+      // Deny-list rejimi.
+      if (deny.length && deny.includes(country)) {
+        return reject(`davlat ${country} bloklangan`);
+      }
+    }
+
+    next();
+  };
+}
+
+module.exports = geoBlock;
+module.exports.geoBlock = geoBlock;
+module.exports.datacenter = datacenter;

package/src/modules/headers.js

@@ -0,0 +1,130 @@
+'use strict';
+
+/**
+ * @file headers.js
+ * @description Server javobiga zamonaviy xavfsizlik sarlavhalarini
+ *              (Security Headers) avtomatik biriktiruvchi Express middleware.
+ * @module modules/headers
+ */
+
+/**
+ * @typedef {Object} HeadersOptions
+ * @property {boolean} [frameGuard=true] - `X-Frame-Options: DENY` (clickjacking himoyasi).
+ * @property {boolean} [noSniff=true] - `X-Content-Type-Options: nosniff` (MIME-sniffing himoyasi).
+ * @property {boolean} [xssProtection=true] - `X-XSS-Protection: 1; mode=block`.
+ * @property {boolean|Object} [hsts=true] - HTTP Strict Transport Security sozlamasi.
+ * @property {number}  [hsts.maxAge=15552000] - HSTS amal qilish muddati (soniyalarda, ~180 kun).
+ * @property {boolean} [hsts.includeSubDomains=true] - Subdomenlarni ham qamrab olsinmi.
+ * @property {boolean} [hsts.preload=false] - `preload` bayrog'ini qo'shsinmi.
+ * @property {boolean|string} [contentSecurityPolicy="default-src 'self'"] - CSP qiymati (false — o'chirilgan).
+ * @property {string}  [poweredBy='yusufkhon-guard'] - `X-Powered-By` sarlavhasi qiymati.
+ * @property {string}  [referrerPolicy='no-referrer'] - `Referrer-Policy` qiymati.
+ */
+
+/**
+ * Standart (default) sozlamalar.
+ * @type {HeadersOptions}
+ */
+const DEFAULT_OPTIONS = {
+  frameGuard: true,
+  noSniff: true,
+  xssProtection: true,
+  hsts: true,
+  contentSecurityPolicy: "default-src 'self'",
+  poweredBy: 'yusufkhon-guard',
+  referrerPolicy: 'no-referrer',
+};
+
+/**
+ * HSTS uchun standart qiymatlar.
+ * @type {{maxAge: number, includeSubDomains: boolean, preload: boolean}}
+ */
+const DEFAULT_HSTS = {
+  maxAge: 15552000, // ~180 kun
+  includeSubDomains: true,
+  preload: false,
+};
+
+/**
+ * HSTS sarlavhasi qiymatini tuzadi.
+ * @private
+ * @param {boolean|Object} hsts - Foydalanuvchi bergan HSTS sozlamasi.
+ * @returns {string|null} Tayyor sarlavha qiymati yoki null (o'chirilgan bo'lsa).
+ */
+function buildHstsValue(hsts) {
+  if (!hsts) return null;
+
+  const conf = hsts === true ? DEFAULT_HSTS : { ...DEFAULT_HSTS, ...hsts };
+  const parts = [`max-age=${conf.maxAge}`];
+
+  if (conf.includeSubDomains) parts.push('includeSubDomains');
+  if (conf.preload) parts.push('preload');
+
+  return parts.join('; ');
+}
+
+/**
+ * Xavfsizlik sarlavhalarini o'rnatuvchi Express middleware yaratadi.
+ *
+ * @example
+ * const { securityHeaders } = require('yusufkhon-guard');
+ * app.use(securityHeaders({ contentSecurityPolicy: "default-src 'self'" }));
+ *
+ * @param {HeadersOptions} [userOptions={}] - Sozlamalar (standart qiymatlar bilan birlashtiriladi).
+ * @returns {import('express').RequestHandler} Express middleware funksiyasi.
+ */
+function securityHeaders(userOptions = {}) {
+  const options = { ...DEFAULT_OPTIONS, ...userOptions };
+  const hstsValue = buildHstsValue(options.hsts);
+
+  /**
+   * @param {import('express').Request} req
+   * @param {import('express').Response} res
+   * @param {import('express').NextFunction} next
+   */
+  return function securityHeadersMiddleware(req, res, next) {
+    // Clickjacking himoyasi.
+    if (options.frameGuard) {
+      res.setHeader('X-Frame-Options', 'DENY');
+    }
+
+    // MIME-sniffing himoyasi.
+    if (options.noSniff) {
+      res.setHeader('X-Content-Type-Options', 'nosniff');
+    }
+
+    // Eski brauzerlar uchun XSS filtri.
+    if (options.xssProtection) {
+      res.setHeader('X-XSS-Protection', '1; mode=block');
+    }
+
+    // HTTPS'ni majburlash (faqat HTTPS orqali kelgan bo'lsa mantiqan to'g'ri,
+    // lekin sarlavhani har doim qo'yish xavfsiz — brauzer HTTPS'da hisobga oladi).
+    if (hstsValue) {
+      res.setHeader('Strict-Transport-Security', hstsValue);
+    }
+
+    // Content Security Policy.
+    if (options.contentSecurityPolicy) {
+      res.setHeader('Content-Security-Policy', options.contentSecurityPolicy);
+    }
+
+    // Referrer siyosati.
+    if (options.referrerPolicy) {
+      res.setHeader('Referrer-Policy', options.referrerPolicy);
+    }
+
+    // Server texnologiyasini yashirib, o'z brendimizni qo'yamiz.
+    if (options.poweredBy) {
+      res.setHeader('X-Powered-By', options.poweredBy);
+    } else {
+      res.removeHeader('X-Powered-By');
+    }
+
+    next();
+  };
+}
+
+module.exports = securityHeaders;
+module.exports.securityHeaders = securityHeaders;
+module.exports.buildHstsValue = buildHstsValue;

package/src/modules/honeypot.js

@@ -0,0 +1,149 @@
+'use strict';
+
+/**
+ * @file honeypot.js
+ * @description HoneyPot (tuzoq) tizimi. Saytda ko'rinmaydigan, lekin avtomatik
+ *              skanerlar va hujumchilar qidiradigan soxta yo'llar (masalan,
+ *              `/.env`, `/admin/config.php`, `/wp-login.php`) o'rnatadi.
+ *
+ *              Bunday yo'lga so'rov yuborilishi 100% zararli niyat belgisidir —
+ *              shu bois so'rov yuboruvchi IP DARHOL bloklanadi (firewall +
+ *              ixtiyoriy OS firewall orqali).
+ * @module modules/honeypot
+ */
+
+const { defaultLogger } = require('../utils/logger');
+const { defaultKeyGenerator } = require('./rateLimiter');
+
+/**
+ * Standart tuzoq yo'llari — real ilova ulardan foydalanmasligi kerak.
+ * @type {string[]}
+ */
+const DEFAULT_TRAPS = [
+  '/.env',
+  '/.env.local',
+  '/.git/config',
+  '/wp-login.php',
+  '/wp-admin',
+  '/admin/config.php',
+  '/phpmyadmin',
+  '/config.php',
+  '/.aws/credentials',
+  '/backup.sql',
+  '/.ssh/id_rsa',
+  '/vendor/phpunit/phpunit/src/Util/PHP/eval-stdin.php',
+];
+
+/**
+ * Yo'lni (bounded) iterativ dekodlaydi — hujumchi tuzoqni URL-encoding bilan
+ * yashirishga urinishi mumkin (masalan `/%2eenv` yoki ikki marta kodlangan
+ * `/%252eenv` -> `/.env`). Dekodlash barqarorlashguncha (yoki 5 martagacha)
+ * takrorlanadi. Buzuq (invalid) foizli kodlashda o'zgarishsiz qaytadi.
+ * @private
+ * @param {string} value
+ * @returns {string}
+ */
+function decodePathDeep(value) {
+  let cur = value;
+  let prev;
+  let i = 0;
+  do {
+    prev = cur;
+    try {
+      cur = decodeURIComponent(cur);
+    } catch {
+      break; // buzuq kodlash — bor holicha qoldiramiz
+    }
+    i += 1;
+  } while (cur !== prev && i < 5);
+  return cur;
+}
+
+/**
+ * @typedef {Object} HoneypotOptions
+ * @property {string[]} [traps] - Tuzoq yo'llari (standart ro'yxat qo'shiladi).
+ * @property {boolean} [useDefaults=true] - Standart tuzoqlarni ham qo'shish.
+ * @property {import('./firewall').Firewall} [firewall] - Darhol bloklash uchun (majburiy tavsiya etiladi).
+ * @property {import('./osFirewall')} [osFirewall] - Berilsa, OS firewall'da ham bloklaydi.
+ * @property {boolean} [osBlock=false] - OS darajasida ham bloklansinmi (rozilik/huquq talab qiladi).
+ * @property {number} [statusCode=404] - Tuzoq javobi (odatda 404 — tabiiy ko'rinishi uchun).
+ * @property {import('../utils/logger').Logger} [logger=defaultLogger] - Logger.
+ * @property {(info: {ip:string, path:string}) => void} [onTrap] - Tuzoqqa tushganda chaqiriladigan hook.
+ */
+
+/**
+ * Honeypot middleware'ini yaratadi.
+ *
+ * @example
+ * const { honeypot } = require('yusufkhon-guard');
+ * app.use(honeypot({ firewall: shield.firewall }));
+ *
+ * @param {HoneypotOptions} [options={}]
+ * @returns {import('express').RequestHandler}
+ */
+function honeypot(options = {}) {
+  const logger = options.logger || defaultLogger;
+  const keyGen = defaultKeyGenerator;
+  const statusCode = options.statusCode || 404;
+
+  const traps = new Set(
+    (options.useDefaults === false ? [] : DEFAULT_TRAPS).concat(options.traps || [])
+      .map((t) => t.toLowerCase())
+  );
+
+  /**
+   * @param {import('express').Request} req
+   * @param {import('express').Response} res
+   * @param {import('express').NextFunction} next
+   */
+  return function honeypotMiddleware(req, res, next) {
+    const raw = (req.originalUrl || req.url || '').split('?')[0];
+    // URL-encoding (va ikki marta kodlash) bilan chetlab o'tishga qarshi:
+    // yo'lni dekodlab, so'ng registrsizlantiramiz.
+    const rawPath = decodePathDeep(raw).toLowerCase();
+
+    // To'liq yo'l yoki uning prefiksi tuzoqqa mos kelsa.
+    let trapped = traps.has(rawPath);
+    if (!trapped) {
+      for (const t of traps) {
+        if (rawPath === t || rawPath.startsWith(t + '/')) { trapped = true; break; }
+      }
+    }
+
+    if (!trapped) return next();
+
+    const ip = keyGen(req);
+    logger.blocked(ip, 'HONEYPOT tuzog\'iga tushdi (instant ban)', { path: rawPath });
+
+    // 1. Firewall'da darhol bloklash.
+    if (options.firewall) {
+      // `ban()` haqiqiy BanRecord qaytaradi — uni 'ban' hodisasida ham yuboramiz,
+      // shunda iste'molchilar (dashboard/Alerter/custom handler) record.offenseCount
+      // kabi maydonlarga tayana oladi (firewall'ning o'z bani bilan izchil).
+      const record = options.firewall.blocker.ban(ip, `Honeypot: ${rawPath}`);
+      if (typeof options.firewall.emit === 'function') {
+        options.firewall.emit('ban', { ip, reason: `Honeypot: ${rawPath}`, record });
+      }
+    }
+
+    // 2. OS firewall'da ham bloklash (ixtiyoriy).
+    if (options.osBlock && options.osFirewall) {
+      Promise.resolve(options.osFirewall.block(ip, { autoApprove: true }))
+        .catch((e) => logger.error(`Honeypot OS-blok xatosi: ${e.message}`));
+    }
+
+    // 3. Foydalanuvchi hook'i.
+    if (typeof options.onTrap === 'function') {
+      try { options.onTrap({ ip, path: rawPath }); } catch { /* ignore */ }
+    }
+
+    // Tabiiy ko'rinishi uchun oddiy 404 qaytaramiz (hujumchiga bilintirmaymiz).
+    return res.status
+      ? res.status(statusCode).json({ error: 'Not found' })
+      : (res.statusCode = statusCode, res.end('Not found'));
+  };
+}
+
+module.exports = honeypot;
+module.exports.honeypot = honeypot;
+module.exports.DEFAULT_TRAPS = DEFAULT_TRAPS;