aiwaf-js 0.0.7 → 0.0.9

package/README.md

@@ -1,6 +1,7 @@
 # aiwaf-js
 
 AIWAF-JS is a Node.js/Express Web Application Firewall that combines deterministic protections with anomaly detection and continuous learning. It ships as middleware, a CLI for ops workflows, and an offline trainer for IsolationForest models.
+Supported frameworks: Express (native), Fastify, Hapi, Koa, NestJS (Express/Fastify wrappers), Next.js (API route wrapper), and AdonisJS.
 
 ## What It Does
 
@@ -62,6 +63,15 @@ AIWAF-JS is a Node.js/Express Web Application Firewall that combines determinist
 npm install aiwaf-js
 ```
 
+### Optional WASM Acceleration
+
+AIWAF can use the `aiwaf-wasm` optional dependency for faster IsolationForest scoring and deterministic feature validation.
+If the WASM module fails to load, it automatically falls back to the JS implementation.
+
+```bash
+npm install aiwaf-wasm
+```
+
 ## Quick Start
 
 ```js
@@ -88,6 +98,184 @@ app.get('/', (req, res) => res.send('Protected'));
 app.listen(3000);
 ```
 
+## Fastify Usage
+
+```js
+const fastify = require('fastify')({ logger: true });
+const aiwaf = require('aiwaf-js');
+
+fastify.register(aiwaf.fastify, {
+  staticKeywords: ['.php', '.env', '.git'],
+  dynamicTopN: 10,
+  WINDOW_SEC: 10,
+  MAX_REQ: 20,
+  FLOOD_REQ: 40,
+  HONEYPOT_FIELD: 'hp_field'
+});
+
+fastify.get('/', async () => 'Protected');
+fastify.listen({ port: 3000 });
+```
+
+## Hapi Usage
+
+```js
+const Hapi = require('@hapi/hapi');
+const aiwaf = require('aiwaf-js');
+
+const server = Hapi.server({ port: 3000 });
+await server.register({
+  plugin: aiwaf.hapi,
+  options: {
+    staticKeywords: ['.php', '.env', '.git'],
+    dynamicTopN: 10,
+    WINDOW_SEC: 10,
+    MAX_REQ: 20,
+    FLOOD_REQ: 40,
+    HONEYPOT_FIELD: 'hp_field'
+  }
+});
+
+server.route({ method: 'GET', path: '/', handler: () => 'Protected' });
+await server.start();
+```
+
+## Koa Usage
+
+```js
+const Koa = require('koa');
+const bodyParser = require('koa-bodyparser');
+const aiwaf = require('aiwaf-js');
+
+const app = new Koa();
+app.use(bodyParser());
+
+app.use(aiwaf.koa({
+  staticKeywords: ['.php', '.env', '.git'],
+  dynamicTopN: 10,
+  WINDOW_SEC: 10,
+  MAX_REQ: 20,
+  FLOOD_REQ: 40,
+  HONEYPOT_FIELD: 'hp_field'
+}));
+
+app.use(ctx => {
+  ctx.body = 'Protected';
+});
+
+app.listen(3000);
+```
+
+## NestJS (Express) Usage
+
+```ts
+import { Module, MiddlewareConsumer, NestModule } from '@nestjs/common';
+import aiwaf from 'aiwaf-js';
+
+@Module({})
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    consumer
+      .apply(aiwaf.nest({
+        staticKeywords: ['.php', '.env', '.git'],
+        dynamicTopN: 10,
+        WINDOW_SEC: 10,
+        MAX_REQ: 20,
+        FLOOD_REQ: 40,
+        HONEYPOT_FIELD: 'hp_field'
+      }))
+      .forRoutes('*');
+  }
+}
+```
+
+If you need to guarantee ordering before other middleware/proxies, you can also attach the Express middleware directly in `main.ts`:
+
+```ts
+import { NestFactory } from '@nestjs/core';
+import aiwaf from 'aiwaf-js';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  app.use(aiwaf({
+    staticKeywords: ['.php', '.env', '.git'],
+    dynamicTopN: 10,
+    WINDOW_SEC: 10,
+    MAX_REQ: 20,
+    FLOOD_REQ: 40,
+    HONEYPOT_FIELD: 'hp_field'
+  }));
+  await app.listen(3000);
+}
+bootstrap();
+```
+
+## NestJS (Fastify) Usage
+
+Use the Fastify plugin when running Nest with `FastifyAdapter`:
+
+```ts
+import { NestFactory } from '@nestjs/core';
+import { FastifyAdapter } from '@nestjs/platform-fastify';
+import aiwaf from 'aiwaf-js';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule, new FastifyAdapter());
+  await app.register(aiwaf.fastify, {
+    staticKeywords: ['.php', '.env', '.git'],
+    dynamicTopN: 10,
+    WINDOW_SEC: 10,
+    MAX_REQ: 20,
+    FLOOD_REQ: 40,
+    HONEYPOT_FIELD: 'hp_field'
+  });
+  await app.listen(3000, '0.0.0.0');
+}
+bootstrap();
+```
+
+## Next.js (API Routes) Usage
+
+Use the `aiwaf.next` helper to wrap a Next.js API route handler.
+
+```ts
+import aiwaf from 'aiwaf-js';
+
+function handler(req, res) {
+  res.status(200).json({ ok: true });
+}
+
+export default aiwaf.next(handler, {
+  staticKeywords: ['.php', '.env', '.git'],
+  dynamicTopN: 10,
+  WINDOW_SEC: 10,
+  MAX_REQ: 20,
+  FLOOD_REQ: 40,
+  HONEYPOT_FIELD: 'hp_field'
+});
+```
+
+## AdonisJS Usage
+
+Register the middleware in your Adonis middleware stack:
+
+```ts
+import aiwaf from 'aiwaf-js';
+
+export const middleware = [
+  () => aiwaf.adonis({
+    staticKeywords: ['.php', '.env', '.git'],
+    dynamicTopN: 10,
+    WINDOW_SEC: 10,
+    MAX_REQ: 20,
+    FLOOD_REQ: 40,
+    HONEYPOT_FIELD: 'hp_field'
+  })
+];
+```
+
 ## Configuration
 
 ### Core Controls
@@ -105,6 +293,8 @@ app.listen(3000);
 | `cache` | fallback memory cache | Custom cache backend used by limiter/features |
 | `nTrees` | `100` | IsolationForest trees when model is initialized in-process |
 | `sampleSize` | `256` | IsolationForest sample size |
+| `AIWAF_WASM_VALIDATION` | `true` | Enable WASM validation when available (headers, URL, content, recent) |
+| `AIWAF_WASM_VALIDATE_RECENT` | `false` | Run WASM recent-behavior validation on recent request logs |
 
 ### Header Validation
 
@@ -318,6 +508,7 @@ node examples/sandbox/run-and-compare.js http://localhost:3001 http://localhost:
 ```
 
 The comparison output includes per‑attack block rates and total blocked requests.
+Fastify proxy is also available on `http://localhost:3002`.
 
 ## License
 

package/index.js

@@ -1,3 +1,16 @@
 // aiwaf‑js/index.js
-// Export the middleware factory from lib/wafMiddleware.js
-module.exports = require('./lib/wafMiddleware');  // :contentReference[oaicite:0]{index=0}​:contentReference[oaicite:1]{index=1}
+const createExpressMiddleware = require('./lib/wafMiddleware');
+const createFastifyPlugin = require('./lib/fastifyPlugin');
+const createHapiPlugin = require('./lib/hapiPlugin');
+const createKoaMiddleware = require('./lib/koaMiddleware');
+const createNestMiddleware = require('./lib/nestMiddleware');
+const createNextHandler = require('./lib/nextMiddleware');
+const createAdonisMiddleware = require('./lib/adonisMiddleware');
+
+module.exports = createExpressMiddleware;
+module.exports.fastify = createFastifyPlugin;
+module.exports.hapi = createHapiPlugin;
+module.exports.koa = createKoaMiddleware;
+module.exports.nest = createNestMiddleware;
+module.exports.next = createNextHandler;
+module.exports.adonis = createAdonisMiddleware;

package/lib/adonisMiddleware.js

@@ -0,0 +1,82 @@
+const createExpressMiddleware = require('./wafMiddleware');
+
+function createExpressLikeResponse(ctx) {
+  const rawRes = ctx.response?.response;
+  const res = {
+    locals: {},
+    on: (...args) => rawRes?.on?.(...args),
+    get statusCode() {
+      return rawRes?.statusCode ?? ctx.response?.statusCode ?? 200;
+    },
+    set statusCode(code) {
+      if (rawRes) rawRes.statusCode = code;
+      if (ctx.response) ctx.response.statusCode = code;
+    },
+    status(code) {
+      if (ctx.response?.status) {
+        ctx.response.status(code);
+      } else {
+        res.statusCode = code;
+      }
+      res._handled = true;
+      return res;
+    },
+    json(payload) {
+      if (ctx.response?.json) {
+        ctx.response.json(payload);
+      } else if (ctx.response?.send) {
+        ctx.response.send(payload);
+      }
+      res._handled = true;
+      return res;
+    },
+    send(payload) {
+      if (ctx.response?.send) {
+        ctx.response.send(payload);
+      } else if (rawRes?.end) {
+        rawRes.end(payload);
+      }
+      res._handled = true;
+      return res;
+    }
+  };
+
+  return res;
+}
+
+module.exports = function createAdonisMiddleware(opts = {}) {
+  const middleware = createExpressMiddleware(opts);
+
+  return async (ctx, next) => {
+    const req = ctx.request?.request || ctx.request || {};
+    const res = createExpressLikeResponse(ctx);
+
+    // Only set path/url/ip if not already available
+    if (!req.path) req.path = ctx.request?.url?.() || ctx.request?.url || req.url;
+    if (!req.url) req.url = req.path;
+    if (!req.ip) req.ip = ctx.request?.ip?.() || ctx.request?.ip;
+    
+    // Don't override headers - the raw request already has them from the HTTP server
+
+    await new Promise(resolve => {
+      let resolved = false;
+      const finish = () => {
+        if (resolved) return;
+        resolved = true;
+        resolve();
+      };
+      const maybePromise = middleware(req, res, finish);
+      if (res._handled) {
+        finish();
+        return;
+      }
+      Promise.resolve(maybePromise).then(finish).catch(finish);
+    });
+
+    if (res._handled || ctx.response?.response?.writableEnded || ctx.response?.response?.headersSent) {
+      return;
+    }
+
+    await next();
+  };
+};

package/lib/anomalyDetector.js

@@ -1,4 +1,5 @@
 const { IsolationForest } = require('./isolationForest');
+const { createIsolationForest, getWasmStatus } = require('./wasmAdapter');
 const modelStore = require('./modelStore');
 const requestLogStore = require('./requestLogStore');
 const { STATIC_KW } = require('./featureUtils');
@@ -12,6 +13,7 @@ let loadStarted = false;
 let minAiLogs = 0;
 let aiLogsSufficient = true;
 let aiLogCount = null;
+let wasmStatus = { loaded: false, error: null };
 
 async function loadModel(opts = {}) {
   if (loadStarted) return;
@@ -150,20 +152,25 @@ module.exports = {
   async init(opts = {}) {
     minAiLogs = Number.isFinite(Number(opts.AIWAF_MIN_AI_LOGS))
       ? Number(opts.AIWAF_MIN_AI_LOGS)
-      : 0;
+      : 10000; // Default: require 10k training samples
     await checkAiLogSufficiency();
     await loadModel(opts);
     if (!model) {
-      model = new IsolationForest({ nTrees: opts.nTrees || 100, sampleSize: opts.sampleSize || 256 });
+      model = await createIsolationForest({
+        nTrees: opts.nTrees || 100,
+        sampleSize: opts.sampleSize || 256,
+        threshold: opts.threshold || 0.5
+      });
+      wasmStatus = getWasmStatus();
     }
 
     if (model && !aiLogsSufficient) {
       model = null;
       trained = false;
       if (aiLogCount !== null) {
-        console.log(`AIWAF AI model disabled due to insufficient logs (${aiLogCount}/${minAiLogs}).`);
+        console.log(`AIWAF AI model disabled due to insufficient logs (${aiLogCount}/${minAiLogs}). Require at least ${minAiLogs} logs before using AI detection.`);
       } else {
-        console.log(`AIWAF AI model disabled due to insufficient logs (unknown/${minAiLogs}).`);
+        console.log(`AIWAF AI model disabled due to insufficient logs (unknown/${minAiLogs}). Require at least ${minAiLogs} logs before using AI detection.`);
       }
     }
   },
@@ -177,6 +184,11 @@ module.exports = {
     return !!model && trained;
   },
 
+  isModelSufficientlyTrained() {
+    // Model must exist AND have enough training data
+    return !!model && trained && aiLogsSufficient;
+  },
+
   // Expects a feature vector: [pathLen, kwHits, statusIdx, responseTime, burst, total404]
   isAnomalous(features, threshold = 0.5) {
     if (!trained || !model) {
@@ -222,7 +234,8 @@ module.exports = {
       threshold: 0.5,
       minAiLogs,
       aiLogsSufficient,
-      aiLogCount
+      aiLogCount,
+      wasm: wasmStatus
     };
   }
 };

package/lib/fastifyPlugin.js

@@ -0,0 +1,49 @@
+const createExpressMiddleware = require('./wafMiddleware');
+
+function createExpressLikeResponse(reply) {
+  const raw = reply.raw;
+  const res = {
+    locals: {},
+    on: (...args) => raw.on(...args),
+    get statusCode() {
+      return raw.statusCode;
+    },
+    set statusCode(code) {
+      raw.statusCode = code;
+    },
+    status(code) {
+      reply.code(code);
+      return res;
+    },
+    json(payload) {
+      reply.type('application/json').send(payload);
+      return res;
+    },
+    send(payload) {
+      reply.send(payload);
+      return res;
+    }
+  };
+  return res;
+}
+
+function fastifyPlugin(fastify, opts = {}, done) {
+  const middleware = createExpressMiddleware(opts);
+
+  fastify.addHook('onRequest', async (request, reply) => {
+    await new Promise(resolve => {
+      const res = createExpressLikeResponse(reply);
+      middleware(request.raw, res, resolve);
+    });
+
+    if (reply.sent) {
+      return reply;
+    }
+  });
+
+  done();
+}
+
+fastifyPlugin[Symbol.for('skip-override')] = true;
+
+module.exports = fastifyPlugin;

package/lib/featureUtils.js

@@ -33,6 +33,15 @@ function init(opts = {}) {
   }
 }
 
+function cleanup() {
+  if (cleanupInterval) {
+    clearInterval(cleanupInterval);
+    cleanupInterval = null;
+  }
+  ipRequestHistory.clear();
+  ip404Counts.clear();
+}
+
 function recordRequest(ip, statusCode) {
   const now = Date.now();
   
@@ -83,7 +92,7 @@ function getResponseTime(req) {
 
 async function extractFeatures(req, res = null) {
   const uri = req.path || req.url;
-  const ip = req.ip || req.connection?.remoteAddress || req.socket?.remoteAddress || 'unknown';
+  const ip = req.ip || req.socket?.remoteAddress || req.connection?.remoteAddress || 'unknown';
   
   // Get status code from response if available, otherwise default to 200
   let statusCode = 200;
@@ -168,6 +177,7 @@ module.exports = {
   get404Count,
   markRequestStart,
   getResponseTime,
+  cleanup,
   STATIC_KW,
   STATUS_IDX
 };

package/lib/hapiPlugin.js

@@ -0,0 +1,92 @@
+const createExpressMiddleware = require('./wafMiddleware');
+
+function createExpressLikeResponse(h, rawRes) {
+  const res = {
+    locals: {},
+    on: (...args) => rawRes.on(...args),
+    get statusCode() {
+      return rawRes.statusCode;
+    },
+    set statusCode(code) {
+      rawRes.statusCode = code;
+    },
+    status(code) {
+      res._statusCode = code;
+      res._handled = true;
+      return res;
+    },
+    json(payload) {
+      res._payload = payload;
+      res._contentType = 'application/json';
+      res._handled = true;
+      return res;
+    },
+    send(payload) {
+      res._payload = payload;
+      res._handled = true;
+      return res;
+    }
+  };
+
+  res.toResponse = () => {
+    const response = h.response(res._payload);
+    if (res._contentType) {
+      response.type(res._contentType);
+    }
+    if (res._statusCode) {
+      response.code(res._statusCode);
+    }
+    return response;
+  };
+
+  return res;
+}
+
+module.exports = {
+  name: 'aiwaf',
+  version: '1.0.0',
+  register: async (server, opts = {}) => {
+    const middleware = createExpressMiddleware(opts);
+
+    server.ext('onRequest', async (request, h) => {
+      const res = createExpressLikeResponse(h, request.raw.res);
+      const req = request.raw.req;
+      
+      // Set path and URL from Hapi's request object
+      req.path = request.path || req.path;
+      req.url = request.url?.pathname || req.url;
+      
+      // For headers: prefer the framework's parsed headers, but merge them
+      // Don't try to replace req.headers entirely as it's read-only on raw requests
+      if (request.headers) {
+        // Copy headers to the req.headers object (which is read-only but properties can be added)
+        try {
+          Object.keys(request.headers).forEach(key => {
+            if (!req.headers[key]) {
+              req.headers[key] = request.headers[key];
+            }
+          });
+        } catch (err) {
+          // If we can't modify headers, continue anyway
+        }
+      }
+      
+      req.ip = request.info?.remoteAddress || req.ip;
+
+      return new Promise(resolve => {
+        let resolved = false;
+        const finish = () => {
+          if (resolved) return;
+          resolved = true;
+          if (res._payload !== undefined || res._statusCode) {
+            resolve(res.toResponse().takeover());
+          } else {
+            resolve(h.continue);
+          }
+        };
+        const maybePromise = middleware(req, res, finish);
+        Promise.resolve(maybePromise).then(finish).catch(finish);
+      });
+    });
+  }
+};

package/lib/headerValidation.js

@@ -203,6 +203,15 @@ module.exports = {
     );
     headers['server-protocol'] = req.httpVersion ? `HTTP/${req.httpVersion}` : headers['server-protocol'];
 
+    if (process.env.AIWAF_DEBUG_HEADERS) {
+      console.error(`[HEADER-VALIDATION] headers keys: ${Object.keys(headers).join(', ')}`);
+      console.error(`[HEADER-VALIDATION] user-agent: ${headers['user-agent']}`);
+      console.error(`[HEADER-VALIDATION] accept: ${headers['accept']}`);
+      console.error(`[HEADER-VALIDATION] accept-language: ${headers['accept-language']}`);
+      console.error(`[HEADER-VALIDATION] accept-encoding: ${headers['accept-encoding']}`);
+      console.error(`[HEADER-VALIDATION] connection: ${headers['connection']}`);
+    }
+
     if (isStaticRequest(req.path || req.url || '')) return null;
 
     const capReason = enforceHeaderCaps(headers);

package/lib/koaMiddleware.js

@@ -0,0 +1,68 @@
+const createExpressMiddleware = require('./wafMiddleware');
+
+function createExpressLikeResponse(ctx) {
+  const res = {
+    locals: {},
+    on: (...args) => ctx.res.on(...args),
+    get statusCode() {
+      return ctx.status;
+    },
+    set statusCode(code) {
+      ctx.status = code;
+    },
+    status(code) {
+      ctx.status = code;
+      res._handled = true;
+      return res;
+    },
+    json(payload) {
+      ctx.type = 'application/json';
+      ctx.body = payload;
+      res._handled = true;
+      return res;
+    },
+    send(payload) {
+      ctx.body = payload;
+      res._handled = true;
+      return res;
+    }
+  };
+  return res;
+}
+
+module.exports = function createKoaMiddleware(opts = {}) {
+  const middleware = createExpressMiddleware(opts);
+
+  return async (ctx, next) => {
+    const res = createExpressLikeResponse(ctx);
+    const req = ctx.req;  // Raw Node.js http.IncomingMessage - already has headers
+    
+    // Only set these if not already available
+    if (!req.path) req.path = ctx.path;
+    if (!req.url) req.url = ctx.url;
+    if (!req.ip) req.ip = ctx.ip;
+    
+    // Don't override headers - use what's already on the raw request
+    // ctx.headers is Koa's parsed version, but req.headers from Node.js has the originals
+
+    await new Promise(resolve => {
+      let resolved = false;
+      const finish = () => {
+        if (resolved) return;
+        resolved = true;
+        resolve();
+      };
+      const maybePromise = middleware(req, res, finish);
+      if (res._handled) {
+        finish();
+      }
+      Promise.resolve(maybePromise).then(finish).catch(finish);
+    });
+
+    if (ctx.body !== undefined) {
+      return;
+    }
+
+    await next();
+  };
+};

package/lib/nestMiddleware.js

@@ -0,0 +1,12 @@
+const createExpressMiddleware = require('./wafMiddleware');
+
+module.exports = function createNestMiddleware(opts = {}) {
+  const middleware = createExpressMiddleware(opts);
+
+  return class AIWAFNestMiddleware {
+    use(req, res, next) {
+      // Express middleware - req/res already have headers set by Express itself
+      return middleware(req, res, next);
+    }
+  };
+};