Protector v5

Maximum protection shield for Node.js HTTP servers. Intercepts all incoming requests at the core level, detects and blocks suspicious traffic from servers, bots, and automated tools, while allowing only legitimate browser-based requests.

Features

• Core-Level Interception: Overrides http.createServer to inspect every HTTP request
• Intelligent Threat Detection: Identifies requests from servers, curl, Postman, bots, and missing headers
• Immediate Blocking: Rejects suspicious requests with HTTP 403 Forbidden
• Selective Logging: Only logs suspicious requests to JSON files on disk
• Framework Agnostic: Works with Express, Fastify, raw Node.js, or any HTTP server
• No Dependencies: Uses only Node.js core modules (http, fs, path)
• Fail-Safe Design: Blocks requests if protection mechanisms fail
• Localhost Allowance: Permits localhost requests for development

Installation

npm install protector

Usage

Wrap your server startup function with protector():

const protector = require('protector');
const http = require('http');

protector(() => {
  const server = http.createServer((req, res) => {
    res.writeHead(200, { 'Content-Type': 'text/plain' });
    res.end('Hello, protected world!');
  });

  server.listen(3000, () => {
    console.log('Server running on port 3000');
  });
});

Works with Express:

const protector = require('protector');
const express = require('express');

protector(() => {
  const app = express();
  app.get('/', (req, res) => res.send('Protected Express app'));
  app.listen(3000);
});

Session Binding

Protector v5 introduces session binding to further enhance security by tying requests to specific browser sessions.

Creating a Session

const { createSession } = require('protector');

const { sessionId, token } = createSession();
// Send sessionId and token to the client

Sending Session to Client

After creating a session, send the sessionId and token to the client in a response:

const { createSession } = require('protector');

app.get('/init-session', (req, res) => {
  const { sessionId, token } = createSession();
  res.json({ sessionId, token });
});

The client should store these values and include them in headers for subsequent requests.

Validating Sessions in Your Application

In your request handlers, validate the session:

const { validateSession } = require('protector');

app.get('/protected', (req, res) => {
  const sessionId = req.headers['x-session-id'];
  const token = req.headers['x-session-token'];
  
  if (!validateSession(sessionId, token)) {
    return res.status(403).send('Invalid session');
  }
  
  res.send('Protected content');
});

Rotating Tokens

Optionally rotate tokens periodically:

const { rotateSessionToken } = require('protector');

const newToken = rotateSessionToken(sessionId);
// Send newToken to client

Security Logic

Requests are flagged as suspicious if:

• Missing User-Agent header
• User-Agent contains bot/server indicators (bot, curl, wget, python, java/, postman, etc.)
• Missing Accept header
• Missing Accept-Language header
• Abnormal HTTP methods (only GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH allowed)

Logging

Suspicious requests are logged to protector-logs/suspicious-requests.json with:

• IP address
• HTTP method
• URL
• Timestamp
• Reason for flagging

Architecture

• index.js: Main entry point
• lib/runtime.js: Runtime lock mechanism
• shield/ipShield.js: Core request inspection and blocking
• storage/logger.js: JSON-based persistent logging

Requirements

• Node.js >= 18
• No external dependencies

License

MIT