Skip to content

Arcjet Security Middleware

Relevant source files - config/arcjet.js - config/env.js - middlewares/arcjet.middleware.js

The Subscription Tracker API employs Arcjet as its primary security layer to provide Web Application Firewall (WAF) capabilities, bot protection, and rate limiting. This layer acts as a gatekeeper for all sensitive API routes, ensuring that malicious traffic is mitigated before it reaches the application logic.

Configuration and Rule Sets

The Arcjet instance is configured in config/arcjet.js using the @arcjet/node SDK. It initializes a security engine with three primary rule sets: Shield, Bot Detection, and Token Bucket Rate Limiting.

Security Rules Implementation

The configuration uses a "LIVE" mode for all rules to actively block non-compliant requests config/arcjet.js9-19

Rule Type Configuration Detail Purpose
Shield (WAF) mode: "LIVE" Protects against common attacks like SQL injection and Cross-Site Scripting (XSS) config/arcjet.js9
Bot Detection allow: ["CATEGORY:SEARCH_ENGINE"] Blocks automated bots while permitting verified search engine crawlers config/arcjet.js10-13
Rate Limiting capacity: 10, refillRate: 5, interval: 10 Implements a Token Bucket algorithm with a maximum burst of 10 requests and a refill of 5 tokens every 10 seconds config/arcjet.js14-19

Sources:

Middleware Logic and Data Flow

The arcjetMiddleware in middlewares/arcjet.middleware.js intercepts incoming requests and interacts with the configured Arcjet instance (aj) to determine if a request should be allowed or denied.

Path Exclusion Logic

To prevent unnecessary processing and ensure availability of diagnostic tools, the middleware includes a bypass mechanism for specific routes middlewares/arcjet.middleware.js5-10

  • Health Checks:/api/v1/health is excluded to allow monitoring services to verify uptime.
  • Documentation: Routes starting with /api-docs (Swagger UI) are excluded.
  • Non-API Routes: Static files and the homepage (any route not starting with /api/v1) bypass security checks.

IP Extraction and Fingerprinting

Arcjet requires an IP address for fingerprinting and rate limiting. The middleware extracts the client IP with a fallback sequence middlewares/arcjet.middleware.js15-18:

  1. req.ip (Standard Express IP).
  2. The first entry in the x-forwarded-for header (to handle proxies/load balancers).
  3. A default fallback to 127.0.0.1.

Fail-Open Strategy

The middleware implements a "fail-open" error handling strategy. If the aj.protect() call fails due to network issues or service downtime, the error is logged, and next() is called to allow the request to proceed rather than crashing the API middlewares/arcjet.middleware.js32-35

Sources:

Request Processing Lifecycle

The following diagram illustrates how a request flows through the arcjetMiddleware and interacts with the aj instance defined in config/arcjet.js.

Security Decision Flow

[Flowchart Diagram]

Sources:

Mapping Code Entities to Security Concepts

This diagram bridges the natural language security requirements to the specific variables and functions in the codebase.

Entity Relationship Diagram

Sources:

Summary of Denial Responses

When decision.isDenied() returns true, the middleware maps Arcjet reasons to standard HTTP status codes:

Condition Method Call Status Code JSON Response
Rate Limit Exceeded decision.reason.isRateLimit() 429 { "error": "Too Many Requests" }
Malicious Bot decision.reason.isBot() 403 { "error": "Bot detected" }
WAF Trigger/Shield Default Case 403 { "error": "Access Denied" }

Sources: