# @arcjet/node
> Arcjet runtime security SDK for Node.js — bot protection, rate limiting, prompt injection detection, PII blocking, and WAF
Latest version **1.14.1** (published 2026-10-07) · Apache-2.0 license · 0 weekly downloads
## Install
```sh
npm install @arcjet/node
pnpm add @arcjet/node
yarn add @arcjet/node
bun add @arcjet/node
```
## Health
**Score 75/100 (B)** — status: active.
Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.
Warnings: low downloads.
## Facts
| | |
|---|---|
| Version | 1.14.1 |
| Published | 2026-10-07 |
| First published | 2024-03-04 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22.21.0 <23 \|\| >=24.5.0 |
| Dependencies | 8 |
| Unpacked size | 44.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 685 |
| Author | Arcjet |
| Maintainers | quinn-arcjet, davidmytton |
| Keywords | ai, analyze, arcjet, attack, bot-detection, limit, llm, node, nodejs, pii, prompt-injection, protect, rate-limiting, secure, security, verify, waf |
## Links
- npm: https://www.npmjs.com/package/@arcjet/node
- Repository: https://github.com/arcjet/arcjet-js
- Homepage: https://arcjet.com
- Issues: https://github.com/arcjet/arcjet-js/issues
- npm.io page: https://npm.io/package/@arcjet/node
## Dependencies (8)
- [arcjet](https://npm.io/package/arcjet.md) 1.14.1
- [@arcjet/ip](https://npm.io/package/@arcjet/ip.md) 1.14.1
- [@arcjet/env](https://npm.io/package/@arcjet/env.md) 1.14.1
- [@arcjet/body](https://npm.io/package/@arcjet/body.md) 1.14.1
- [@arcjet/logger](https://npm.io/package/@arcjet/logger.md) 1.14.1
- [@arcjet/headers](https://npm.io/package/@arcjet/headers.md) 1.14.1
- [@arcjet/protocol](https://npm.io/package/@arcjet/protocol.md) 1.14.1
- [@arcjet/transport](https://npm.io/package/@arcjet/transport.md) 1.14.1
## Alternatives
- [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads
- [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads
- [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads
- [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads
- [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads
## Recent versions
- 1.14.1 (latest) — 2026-10-07
- 1.10.0-rc.1 (rc) — 2026-08-07
- 1.14.0 — 2026-10-01
- 1.13.0 — 2026-09-16
- 1.12.0 — 2026-09-08
- 1.11.0 — 2026-08-26
- 1.10.0 — 2026-08-11
- 1.10.0-rc.0 — 2026-08-04
- 1.9.1 — 2026-07-15
- 1.9.0 — 2026-07-15
- 1.8.0 — 2026-07-07
- 1.8.0-rc.0 — 2026-07-07
- 1.7.0 — 2026-07-06
- 1.7.0-rc.1 — 2026-07-06
- 1.7.0-rc.0 — 2026-07-03
- … 54 more at https://npm.io/package/@arcjet/node/versions
## README
# `@arcjet/node`
[Arcjet][arcjet] is the runtime security platform that ships in your AI code. Detect prompt injection, authorize agent tool calls, redact sensitive data, and block bots and abuse. Real-time security building blocks you call inside your app, before an action happens.
This is the [Arcjet][arcjet] SDK for [Node.js][node-js] **request protection** —
use it to protect HTTP route handlers and API endpoints. If you need to protect
AI agent tool calls, MCP server handlers, or background jobs (anything without
an HTTP request), see [`@arcjet/guard`](https://github.com/arcjet/arcjet-js/tree/main/arcjet-guard).
## Why Arcjet?
Your app's AI features and agents take real actions, calling tools, reading data, hitting APIs. Arcjet runs inside that code and lets you enforce security on each action in real time, then audit what happened
## Getting started
### Quick setup with an AI agent
1. Log in with the CLI:
```sh
npx @arcjet/cli auth login
```
2. Install versioned Agent Skills so your coding agent matches this SDK:
```sh
npx @tanstack/intent@latest install
```
3. Tell your agent what to protect — it handles the rest.
### Manual setup
1. **Log in** with the CLI (or at [`app.arcjet.com`](https://app.arcjet.com?utm_campaign=arcjet-js)):
```sh
npx @arcjet/cli auth login
```
2. `npm install @arcjet/node`
3. Set `ARCJET_KEY=ajkey_yourkey` in your environment
4. Add Arcjet to your server — see the [quick start](#quick-start) below
[npm package](https://www.npmjs.com/package/@arcjet/node) |
[GitHub source](https://github.com/arcjet/arcjet-js/tree/main/arcjet-node) |
[Full docs][arcjet-reference-node] |
[Other SDKs][sdks-github]
## Features
All features below are available with `@arcjet/node` for request protection.
For guard protection (tool calls, MCP servers, queues) see
[`@arcjet/guard`](https://github.com/arcjet/arcjet-js/tree/main/arcjet-guard).
| Feature | `@arcjet/node` | `@arcjet/guard` |
| ------------------------------- | :------------: | :-------------: |
| Rate Limiting | ✅ | ✅ |
| Prompt Injection Detection | ✅ | ✅ |
| Sensitive Information Detection | ✅ | ✅ |
| Bot Protection | ✅ | — |
| Shield WAF | ✅ | — |
| Email Validation | ✅ | — |
| Signup Form Protection | ✅ | — |
| Request Filters | ✅ | — |
| IP Analysis | ✅ | — |
| Custom Rules | — | ✅ |
- 🔒 [Prompt Injection Detection](#prompt-injection-detection) — detect and block
prompt injection attacks before they reach your LLM.
- 🤖 [Bot Protection](#bot-protection) — stop scrapers, credential stuffers, and
AI crawlers from abusing your endpoints.
- 🛑 [Rate Limiting](#rate-limiting) — token bucket, fixed window, and sliding
window algorithms; model AI token budgets per user.
- 🕵️ [Sensitive Information Detection](#sensitive-information-detection) — block
PII, credit cards, and custom patterns from entering your AI pipeline.
- 🛡️ [Shield WAF](#shield-waf) — protect against SQL injection, XSS, and other
common web attacks.
- 📧 [Email Validation](#email-validation) — block disposable, invalid, and
undeliverable addresses at signup.
- 📝 [Signup Form Protection][signup-protection-docs] — combines bot protection,
email validation, and rate limiting to protect your signup forms.
- 🎯 [Request Filters](#request-filters) — expression-based rules on IP, path,
headers, and custom fields.
- 🌐 [IP Analysis](#ip-analysis) — geolocation, ASN, VPN, proxy, Tor, and hosting
detection included with every request.
## Quick start
This example protects a Node.js HTTP server with bot detection, Shield WAF,
and token bucket rate limiting.
```ts
// index.ts
import arcjet, { detectBot, shield, tokenBucket } from "@arcjet/node";
import { isSpoofedBot } from "@arcjet/inspect";
import http from "node:http";
const aj = arcjet({
key: process.env.ARCJET_KEY!, // Get your key with: npx @arcjet/cli sites get-key
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",
// Tracked by IP address by default, but this can be customized
// See https://docs.arcjet.com/fingerprints
refillRate: 5, // Refill 5 tokens per interval
interval: 10, // Refill every 10 seconds
capacity: 10, // Bucket capacity of 10 tokens
}),
],
});
const server = http.createServer(async function (
req: http.IncomingMessage,
res: http.ServerResponse,
) {
const decision = await aj.protect(req, { requested: 5 }); // Deduct 5 tokens
console.log("Arcjet decision", decision);
if (decision.isDenied()) {
if (decision.reason.isRateLimit()) {
res.writeHead(429, { "Content-Type": "application/json" });
res.end(JSON.stringify({ error: "Too many requests" }));
} else if (decision.reason.isBot()) {
res.writeHead(403, { "Content-Type": "application/json" });
res.end(JSON.stringify({ error: "No bots allowed" }));
} else {
res.writeHead(403, { "Content-Type": "application/json" });
res.end(JSON.stringify({ error: "Forbidden" }));
}
} else if (decision.ip.isHosting()) {
// Requests from hosting IPs are likely from bots.
// https://docs.arcjet.com/blueprints/vpn-proxy-detection
res.writeHead(403, { "Content-Type": "application/json" });
res.end(JSON.stringify({ error: "Forbidden" }));
} else if (decision.results.some(isSpoofedBot)) {
// 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
res.writeHead(403, { "Content-Type": "application/json" });
res.end(JSON.stringify({ error: "Forbidden" }));
} else {
res.writeHead(200, { "Content-Type": "application/json" });
res.end(JSON.stringify({ message: "Hello world" }));
}
});
server.listen(8000);
```
For the full reference, see the [Arcjet Node.js SDK docs][arcjet-reference-node].
## 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.
```ts
import arcjet, { detectPromptInjection } from "@arcjet/node";
import { readBody } from "@arcjet/body";
import http from "node:http";
const aj = arcjet({
key: process.env.ARCJET_KEY!,
rules: [
detectPromptInjection({
mode: "LIVE", // Blocks requests. Use "DRY_RUN" to log only
}),
],
});
const server = http.createServer(async function (req, res) {
const body = await readBody(req);
const { message } = JSON.parse(body);
const decision = await aj.protect(req, {
detectPromptInjectionMessage: message,
});
if (decision.isDenied() && decision.reason.isPromptInjection()) {
res.writeHead(400, { "Content-Type": "application/json" });
res.end(
JSON.stringify({
error: "Prompt injection detected — please rephrase your message",
}),
);
return;
}
// 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][bot-list].
```ts
import arcjet, { detectBot } from "@arcjet/node";
import { isSpoofedBot } from "@arcjet/inspect";
const aj = arcjet({
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 request handler:
const decision = await aj.protect(req);
if (decision.isDenied() && decision.reason.isBot()) {
res.writeHead(403);
res.end(JSON.stringify({ error: "No bots allowed" }));
}
// Verifies the authenticity of common bots using IP data.
if (decision.results.some(isSpoofedBot)) {
res.writeHead(403);
res.end(JSON.stringify({ error: "Forbidden" }));
}
```
### Bot categories
Bots can be configured by [category][bot-categories-docs] and/or by [specific
bot name][bot-list]. For example, to allow search engines and the OpenAI
crawler, but deny all other bots:
```ts
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:
```ts
import { isSpoofedBot } from "@arcjet/inspect";
if (decision.results.some(isSpoofedBot)) {
res.writeHead(403);
res.end(JSON.stringify({ error: "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.
```ts
import arcjet, { tokenBucket } from "@arcjet/node";
const aj = arcjet({
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
}),
],
});
const decision = await aj.protect(req, {
userId: "user-123",
requested: estimate, // Number of tokens to deduct
});
if (decision.isDenied() && decision.reason.isRateLimit()) {
res.writeHead(429);
res.end(JSON.stringify({ error: "Rate limit exceeded" }));
}
```
## 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.
```ts
import arcjet, { sensitiveInfo } from "@arcjet/node";
const aj = arcjet({
key: process.env.ARCJET_KEY!,
rules: [
sensitiveInfo({
mode: "LIVE", // Blocks requests. Use "DRY_RUN" to log only
deny: ["CREDIT_CARD_NUMBER", "EMAIL", "PHONE_NUMBER"],
}),
],
});
const decision = await aj.protect(req, {
sensitiveInfoValue: userMessage, // The text content to scan
});
if (decision.isDenied() && decision.reason.isSensitiveInfo()) {
res.writeHead(400);
res.end(JSON.stringify({ error: "Sensitive information detected" }));
}
```
## Shield WAF
Protect your application against common web attacks, including the OWASP
Top 10.
```ts
import arcjet, { shield } from "@arcjet/node";
const aj = arcjet({
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`.
```ts
import arcjet, { validateEmail } from "@arcjet/node";
const aj = arcjet({
key: process.env.ARCJET_KEY!,
rules: [
validateEmail({
mode: "LIVE",
deny: ["DISPOSABLE", "INVALID", "NO_MX_RECORDS"],
}),
],
});
const decision = await aj.protect(req, {
email: "user@example.com",
});
if (decision.isDenied() && decision.reason.isEmail()) {
res.writeHead(400);
res.end(JSON.stringify({ error: "Invalid email address" }));
}
```
## Request filters
Filter requests using expression-based rules against request properties (IP,
headers, path, method, etc.).
```ts
import arcjet, { filter } from "@arcjet/node";
const aj = arcjet({
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:
```ts
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:
```ts
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()`:
```ts
const decision = await aj.protect(req);
if (decision.ip.isVpn() || decision.ip.isTor()) {
res.writeHead(403);
res.end(JSON.stringify({ error: "VPN traffic not allowed" }));
}
```
See the [Request Filters docs][filters-docs],
[IP Geolocation blueprint](https://docs.arcjet.com/blueprints/ip-geolocation), and
[VPN/Proxy Detection blueprint](https://docs.arcjet.com/blueprints/vpn-proxy-detection)
for more details.
## IP analysis
Arcjet enriches every request with IP metadata. Use these helpers to make
policy decisions based on network signals:
```ts
const decision = await aj.protect(req);
if (decision.ip.isHosting()) {
// Requests from cloud/hosting providers are often automated.
// https://docs.arcjet.com/blueprints/vpn-proxy-detection
res.writeHead(403);
res.end(JSON.stringify({ error: "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.
```ts
const aj = arcjet({
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 aj.protect(req, {
userId: "user-123", // Replace with your actual user ID
requested: estimate,
});
```
## Best practices
See the [Arcjet best practices][best-practices] for detailed guidance. Key
recommendations:
**Create a single client instance** and reuse it with `withRule()` for
route-specific rules. The SDK caches decisions and configuration, so creating a
new instance per request wastes that work.
```ts
// lib/arcjet.ts — create once, import everywhere
import arcjet, { shield } from "@arcjet/node";
export default arcjet({
key: process.env.ARCJET_KEY!,
rules: [
shield({ mode: "LIVE" }), // base rules applied to every request
],
});
```
```ts
// routes/chat.ts — extend per-route with withRule()
import aj from "./lib/arcjet.js";
import { detectBot, tokenBucket } from "@arcjet/node";
const routeAj = aj.withRule(detectBot({ mode: "LIVE", allow: [] })).withRule(
tokenBucket({
mode: "LIVE",
refillRate: 2_000,
interval: "1h",
capacity: 5_000,
}),
);
export async function handler(req, res) {
const decision = await routeAj.protect(req, { requested: 500 });
// ...
}
```
**Other recommendations:**
- **Call `protect()` once per request** in the handler where you need it, not
in a global middleware layer.
- **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:
```ts
arcjet({
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:
```ts
if (decision.isErrored()) {
console.error("Arcjet error", decision.reason.message);
// allow the request to proceed
}
```
## License
[Apache License, Version 2.0][apache-license] © [Arcjet Labs, Inc.][arcjet]
[arcjet]: https://arcjet.com
[arcjet-reference-node]: https://docs.arcjet.com/reference/nodejs
[node-js]: https://nodejs.org/
[sdks-github]: https://github.com/arcjet
[apache-license]: http://www.apache.org/licenses/LICENSE-2.0
[bot-categories-docs]: https://docs.arcjet.com/bot-protection/identifying-bots
[bot-list]: https://arcjet.com/bot-list
[signup-protection-docs]: https://docs.arcjet.com/signup-protection
[filters-docs]: https://docs.arcjet.com/filters
[best-practices]: https://docs.arcjet.com/best-practices
---
_Source: https://npm.io/package/@arcjet/node · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
