Arcjet JS

The protect() method accepts a metadata object. This object allows you to attach any JSON-serializable value (including nested objects and arrays) to the decision for correlation and analytics.

Constraints and Limits:

• Format: Must be a plain object. Non-plain objects are ignored. Values like undefined, functions, BigInt, or circular references are dropped.
• Server Limits: Up to 128 top-level keys, 4 KiB per serialized value, and 10 levels of nesting. Key names must be letters, digits, -, ., or _.
• SDK Limits: The SDK drops keys if the total metadata for one request exceeds 768 KiB to prevent exceeding the 1 MiB protocol limit.
• Security: Metadata is untrusted and not redacted. Do not put secrets or PII in it.
• Precision: For integers above Number.MAX_SAFE_INTEGER, pass them as strings to avoid precision loss.

const decision = await aj.protect(request, {
  metadata: {
    requestId,
    user: { id: userId, plan: "pro" },
    flags: { beta: true },
  },
});

By default, proxying on Node.js downgrades the connection from HTTP/2 to HTTP/1.1 because the built-in agent proxy support only works over HTTP/1.1. This can increase latency for concurrent requests.

To maintain HTTP/2 end-to-end, set proxyHttpVersion: "2" in your TransportOptions. This opens an HTTP CONNECT tunnel to the proxy and performs the TLS handshake directly with the origin.

Requirements and Caveats:

• Node.js only: Bun, Deno, and edge runtimes do not support this setting.
• Requires a tunneling (CONNECT) proxy: A proxy that terminates TLS and re-originates an HTTP/1.1 connection (MITM proxy) cannot preserve HTTP/2.
• Proxy must not buffer the tunnel: If the proxy buffers tunneled bytes, it can add ~40ms of latency per round trip. Ensure your proxy (like Squid) sets TCP_NODELAY on CONNECT tunnels.

const transport = createTransport("https://decide.arcjet.com", {
  proxyHttpVersion: "2"
});

The detectBot rule allows you to manage which bots can access your endpoints. If you specify an allow list, all other bots are denied. You can allow bots by CATEGORY or by specific bot name.

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.

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

import arcjet, { detectBot } from "npm:@arcjet/deno";
import { isSpoofedBot } from "npm:@arcjet/inspect";

const aj = arcjet({
  key: Deno.env.get("ARCJET_KEY")!,
  rules: [
    detectBot({
      mode: "LIVE",
      allow: [
        "CATEGORY:SEARCH_ENGINE",
        "OPENAI_CRAWLER_SEARCH",
      ],
    }),
  ],
});

// In your request handler:
const decision = await aj.protect(request);

if (decision.isDenied() && decision.reason.isBot()) {
  return Response.json({ error: "No bots allowed" }, { status: 403 });
}

// Verifies the authenticity of common bots using IP data.
if (decision.results.some(isSpoofedBot)) {
  return Response.json({ error: "Forbidden" }, { status: 403 });
}