@arcjet/nest

Arcjet is the runtime security platform that ships with your AI code. Stop bots and automated attacks from burning your AI budget, leaking data, or misusing tools with Arcjet's AI security building blocks. Every feature works with any NestJS application.

This is the Arcjet SDK for NestJS.

Getting started

1. Get your API key at app.arcjet.com
2. npm install @arcjet/nest
3. Set ARCJET_KEY=ajkey_yourkey in your environment
4. Add Arcjet to your app — see the quick start below

npm package | GitHub source | Full docs | Other SDKs

Features

• 🔒 Prompt Injection Detection — detect and block prompt injection attacks before they reach your LLM.
• 🤖 Bot Protection — stop scrapers, credential stuffers, and AI crawlers from abusing your endpoints.
• 🛑 Rate Limiting — token bucket, fixed window, and sliding window algorithms; model AI token budgets per user.
• 🕵️ Sensitive Information Detection — block PII, credit cards, and custom patterns from entering your AI pipeline.
• 🛡️ Shield WAF — protect against SQL injection, XSS, and other common web attacks.
• 📧 Email Validation — block disposable, invalid, and undeliverable addresses at signup.
• 📝 Signup Form Protection — combines bot protection, email validation, and rate limiting to protect your signup forms.
• 🎯 Request Filters — expression-based rules on IP, path, headers, and custom fields.
• 🌐 IP Analysis — geolocation, ASN, VPN, proxy, Tor, and hosting detection included with every request.

Quick start

This example protects a NestJS application with a global guard using bot detection, Shield WAF, and token bucket rate limiting.

First, register the ArcjetModule in your app module:

// app.module.ts
import { ArcjetModule, detectBot, shield, tokenBucket } from "@arcjet/nest";
import { Module } from "@nestjs/common";

@Module({
  imports: [
    ArcjetModule.forRoot({
      isGlobal: true,
      key: process.env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com
      rules: [
        // Shield protects your app from common attacks e.g. SQL injection
        shield({ mode: "LIVE" }),
        // Create a bot detection rule
        detectBot({
          mode: "LIVE", // Blocks requests. Use "DRY_RUN" to log only
          // Block all bots except the following
          allow: [
            "CATEGORY:SEARCH_ENGINE", // Google, Bing, etc
            // Uncomment to allow these other common bot categories
            // See the full list at https://arcjet.com/bot-list
            //"CATEGORY:MONITOR", // Uptime monitoring services
            //"CATEGORY:PREVIEW", // Link previews e.g. Slack, Discord
          ],
        }),
        // Token bucket rate limit. Other algorithms are supported.
        tokenBucket({
          mode: "LIVE",
          refillRate: 5, // Refill 5 tokens per interval
          interval: 10, // Refill every 10 seconds
          capacity: 10, // Bucket capacity of 10 tokens
        }),
      ],
    }),
  ],
})
export class AppModule {}

Then protect a controller using @InjectArcjet():

// app.controller.ts
import { ArcjetNest, InjectArcjet } from "@arcjet/nest";
import { isSpoofedBot } from "@arcjet/inspect";
import {
  Controller,
  Get,
  HttpException,
  HttpStatus,
  Req,
} from "@nestjs/common";
import type { Request } from "express";

@Controller()
export class AppController {
  constructor(@InjectArcjet() private readonly arcjet: ArcjetNest) {}

  @Get("/")
  async index(@Req() req: Request) {
    const decision = await this.arcjet.protect(req, { requested: 5 });
    console.log("Arcjet decision", decision);

    if (decision.isDenied()) {
      if (decision.reason.isRateLimit()) {
        throw new HttpException(
          "Too many requests",
          HttpStatus.TOO_MANY_REQUESTS,
        );
      } else if (decision.reason.isBot()) {
        throw new HttpException("No bots allowed", HttpStatus.FORBIDDEN);
      } else {
        throw new HttpException("Forbidden", HttpStatus.FORBIDDEN);
      }
    }

    // Requests from hosting IPs are likely from bots.
    // https://docs.arcjet.com/blueprints/vpn-proxy-detection
    if (decision.ip.isHosting()) {
      throw new HttpException("Forbidden", HttpStatus.FORBIDDEN);
    }

    // Verifies the authenticity of common bots using IP data.
    // Verification isn't always possible, so check the results separately.
    // https://docs.arcjet.com/bot-protection/reference#bot-verification
    if (decision.results.some(isSpoofedBot)) {
      throw new HttpException("Forbidden", HttpStatus.FORBIDDEN);
    }

    return { message: "Hello world" };
  }
}

For the full reference, see the Arcjet NestJS SDK docs.

Prompt injection detection

Detect and block prompt injection attacks — attempts to override your AI model's instructions — before they reach your model. Pass the user's message via detectPromptInjectionMessage on each protect() call.

// app.module.ts
import { ArcjetModule, detectPromptInjection } from "@arcjet/nest";
import { Module } from "@nestjs/common";

@Module({
  imports: [
    ArcjetModule.forRoot({
      isGlobal: true,
      key: process.env.ARCJET_KEY!,
      rules: [
        detectPromptInjection({
          mode: "LIVE", // Blocks requests. Use "DRY_RUN" to log only
        }),
      ],
    }),
  ],
})
export class AppModule {}

// chat.controller.ts
import { ArcjetNest, InjectArcjet } from "@arcjet/nest";
import {
  Body,
  Controller,
  HttpException,
  HttpStatus,
  Post,
  Req,
} from "@nestjs/common";
import type { Request } from "express";

@Controller("chat")
export class ChatController {
  constructor(@InjectArcjet() private readonly arcjet: ArcjetNest) {}

  @Post("/")
  async chat(@Req() req: Request, @Body() body: { message: string }) {
    const decision = await this.arcjet.protect(req, {
      detectPromptInjectionMessage: body.message,
    });

    if (decision.isDenied() && decision.reason.isPromptInjection()) {
      throw new HttpException(
        "Prompt injection detected — please rephrase your message",
        HttpStatus.BAD_REQUEST,
      );
    }

    // Forward to your AI model...
  }
}

Bot protection

Arcjet allows you to configure a list of bots to allow or deny. Specifying allow means all other bots are denied. An empty allow list blocks all bots.

Available categories: CATEGORY:ACADEMIC, CATEGORY:ADVERTISING, CATEGORY:AI, CATEGORY:AMAZON, CATEGORY:APPLE, CATEGORY:ARCHIVE, CATEGORY:BOTNET, CATEGORY:FEEDFETCHER, CATEGORY:GOOGLE, CATEGORY:META, CATEGORY:MICROSOFT, CATEGORY:MONITOR, CATEGORY:OPTIMIZER, CATEGORY:PREVIEW, CATEGORY:PROGRAMMATIC, CATEGORY:SEARCH_ENGINE, CATEGORY:SLACK, CATEGORY:SOCIAL, CATEGORY:TOOL, CATEGORY:UNKNOWN, CATEGORY:VERCEL, CATEGORY:WEBHOOK, CATEGORY:YAHOO. You can also allow or deny specific bots by name.

import { ArcjetModule, detectBot } from "@arcjet/nest";

ArcjetModule.forRoot({
  isGlobal: true,
  key: process.env.ARCJET_KEY!,
  rules: [
    detectBot({
      mode: "LIVE",
      allow: [
        "CATEGORY:SEARCH_ENGINE",
        // See the full list at https://arcjet.com/bot-list
      ],
    }),
  ],
});

// In your controller:
import { isSpoofedBot } from "@arcjet/inspect";

const decision = await this.arcjet.protect(req);

if (decision.isDenied() && decision.reason.isBot()) {
  throw new HttpException("No bots allowed", HttpStatus.FORBIDDEN);
}

// Verifies the authenticity of common bots using IP data.
if (decision.results.some(isSpoofedBot)) {
  throw new HttpException("Forbidden", HttpStatus.FORBIDDEN);
}

Bot categories

Bots can be configured by category and/or by specific bot name. For example, to allow search engines and the OpenAI crawler, but deny all other bots:

detectBot({
  mode: "LIVE",
  allow: ["CATEGORY:SEARCH_ENGINE", "OPENAI_CRAWLER_SEARCH"],
});

Verified vs spoofed bots

Bots claiming to be well-known crawlers (e.g. Googlebot) are verified by checking their IP address against known IP ranges. If a bot fails verification, it is labeled as spoofed. Use isSpoofedBot from @arcjet/inspect to check:

import { isSpoofedBot } from "@arcjet/inspect";

if (decision.results.some(isSpoofedBot)) {
  throw new HttpException("Forbidden", HttpStatus.FORBIDDEN);
}

Rate limiting

Arcjet supports token bucket, fixed window, and sliding window algorithms. Token buckets are ideal for controlling AI token budgets — set capacity to the max tokens a user can spend, refillRate to how many tokens are restored per interval, and deduct tokens per request via requested in protect(). The interval accepts strings ("1s", "1m", "1h", "1d") or seconds as a number. Use characteristics to track limits per user instead of per IP.

import {
  ArcjetModule,
  tokenBucket,
  slidingWindow,
  fixedWindow,
} from "@arcjet/nest";

ArcjetModule.forRoot({
  isGlobal: true,
  key: process.env.ARCJET_KEY!,
  characteristics: ["userId"], // Track per user
  rules: [
    tokenBucket({
      mode: "LIVE",
      refillRate: 2_000, // Refill 2,000 tokens per hour
      interval: "1h",
      capacity: 5_000, // Maximum 5,000 tokens in the bucket
    }),
  ],
});

// In your controller:
const decision = await this.arcjet.protect(req, {
  userId: "user-123",
  requested: estimate, // Number of tokens to deduct
});

if (decision.isDenied() && decision.reason.isRateLimit()) {
  throw new HttpException("Rate limit exceeded", HttpStatus.TOO_MANY_REQUESTS);
}

Sensitive information detection

Detect and block PII in request content. Pass the content to scan via sensitiveInfoValue on each protect() call. Built-in entity types: CREDIT_CARD_NUMBER, EMAIL, PHONE_NUMBER, IP_ADDRESS. You can also provide a custom detect callback for additional patterns.

import { ArcjetModule, sensitiveInfo } from "@arcjet/nest";

ArcjetModule.forRoot({
  isGlobal: true,
  key: process.env.ARCJET_KEY!,
  rules: [
    sensitiveInfo({
      mode: "LIVE", // Blocks requests. Use "DRY_RUN" to log only
      deny: ["CREDIT_CARD_NUMBER", "EMAIL", "PHONE_NUMBER"],
    }),
  ],
});

// In your controller:
const decision = await this.arcjet.protect(req, {
  sensitiveInfoValue: userMessage, // The text content to scan
});

if (decision.isDenied() && decision.reason.isSensitiveInfo()) {
  throw new HttpException(
    "Sensitive information detected",
    HttpStatus.BAD_REQUEST,
  );
}

Shield WAF

Protect your application against common web attacks, including the OWASP Top 10.

import { ArcjetModule, shield } from "@arcjet/nest";

ArcjetModule.forRoot({
  isGlobal: true,
  key: process.env.ARCJET_KEY!,
  rules: [
    shield({
      mode: "LIVE", // Blocks requests. Use "DRY_RUN" to log only
    }),
  ],
});

Email validation

Validate and verify email addresses. Deny types: DISPOSABLE, FREE, NO_MX_RECORDS, NO_GRAVATAR, INVALID.

import { ArcjetModule, validateEmail } from "@arcjet/nest";

ArcjetModule.forRoot({
  isGlobal: true,
  key: process.env.ARCJET_KEY!,
  rules: [
    validateEmail({
      mode: "LIVE",
      deny: ["DISPOSABLE", "INVALID", "NO_MX_RECORDS"],
    }),
  ],
});

// In your controller:
const decision = await this.arcjet.protect(req, {
  email: "[email protected]",
});

if (decision.isDenied() && decision.reason.isEmail()) {
  throw new HttpException("Invalid email address", HttpStatus.BAD_REQUEST);
}

Request filters

Filter requests using expression-based rules against request properties (IP, headers, path, method, etc.).

import { ArcjetModule, filter } from "@arcjet/nest";

ArcjetModule.forRoot({
  isGlobal: true,
  key: process.env.ARCJET_KEY!,
  rules: [
    filter({
      mode: "LIVE",
      deny: ['ip.src == "1.2.3.4"'],
    }),
  ],
});

Block by country

Restrict access to specific countries — useful for licensing, compliance, or regional rollouts. The allow list denies all countries not listed:

filter({
  mode: "LIVE",
  // Allow only US traffic — all other countries are denied
  allow: ['ip.src.country == "US"'],
});

Block VPN and proxy traffic

Prevent anonymized traffic from accessing sensitive endpoints — useful for fraud prevention, enforcing geo-restrictions, and reducing abuse:

filter({
  mode: "LIVE",
  deny: [
    "ip.src.vpn", // VPN services
    "ip.src.proxy", // Open proxies
    "ip.src.tor", // Tor exit nodes
  ],
});

For more nuanced handling, use decision.ip helpers after calling protect():

const decision = await this.arcjet.protect(req);

if (decision.ip.isVpn() || decision.ip.isTor()) {
  throw new HttpException("VPN traffic not allowed", HttpStatus.FORBIDDEN);
}

See the Request Filters docs, IP Geolocation blueprint, and VPN/Proxy Detection blueprint for more details.

IP analysis

Arcjet enriches every request with IP metadata. Use these helpers to make policy decisions based on network signals:

const decision = await this.arcjet.protect(req);

if (decision.ip.isHosting()) {
  // Requests from cloud/hosting providers are often automated.
  // https://docs.arcjet.com/blueprints/vpn-proxy-detection
  throw new HttpException("Forbidden", HttpStatus.FORBIDDEN);
}

if (decision.ip.isVpn() || decision.ip.isProxy() || decision.ip.isTor()) {
  // Handle VPN/proxy traffic according to your policy
}

// Access geolocation and network details
console.log(decision.ip.country, decision.ip.city, decision.ip.asn);

Custom characteristics

Track and limit requests by any stable identifier — user ID, API key, session, etc. — rather than IP address alone.

ArcjetModule.forRoot({
  isGlobal: true,
  key: process.env.ARCJET_KEY!,
  characteristics: ["userId"], // Declare at the SDK level
  rules: [
    tokenBucket({
      mode: "LIVE",
      refillRate: 2_000,
      interval: "1h",
      capacity: 5_000,
    }),
  ],
});

// Pass the characteristic value at request time
const decision = await this.arcjet.protect(req, {
  userId: "user-123", // Replace with your actual user ID
  requested: estimate,
});

Best practices

See the Arcjet best practices for detailed guidance. Key recommendations:

Use withRule() for controller-specific rules on top of the global base rules. The SDK caches decisions and configuration, so this is more efficient than creating a new instance per request.

// chat.controller.ts — extend per-route with withRule()
import { ArcjetNest, InjectArcjet, detectBot, tokenBucket } from "@arcjet/nest";
import { Controller, Post, Req } from "@nestjs/common";
import type { Request } from "express";

@Controller("chat")
export class ChatController {
  constructor(@InjectArcjet() private readonly arcjet: ArcjetNest) {}

  @Post("/")
  async chat(@Req() req: Request, @Body() body: { requested: number }) {
    const routeAj = this.arcjet
      .withRule(detectBot({ mode: "LIVE", allow: [] }))
      .withRule(
        tokenBucket({
          mode: "LIVE",
          refillRate: 2_000,
          interval: "1h",
          capacity: 5_000,
        }),
      );
    const decision = await routeAj.protect(req, { requested: body.requested });
    // ...
  }
}

Other recommendations:

• Start rules in DRY_RUN mode to observe behavior before switching to LIVE. This lets you tune thresholds without affecting real traffic.
• Configure proxies if your app runs behind a load balancer or reverse proxy so Arcjet resolves the real client IP:

  ArcjetModule.forRoot({
    key: process.env.ARCJET_KEY!,
    rules: [],
    proxies: ["100.100.100.100"],
  });

• Handle errors explicitly. protect() never throws — on error it returns an ERROR result. Fail open by logging and allowing the request:

  if (decision.isErrored()) {
    console.error("Arcjet error", decision.reason.message);
    // allow the request to proceed
  }

License

Apache License, Version 2.0 © Arcjet Labs, Inc.