@arcjet/bun 1.3.0 → 1.4.0

package/README.md

@@ -16,95 +16,522 @@
   </a>
 </p>
 
-[Arcjet][arcjet] helps developers protect their apps in just a few lines of
-code. Implement rate limiting, bot protection, email verification, and defense
-against common attacks.
+[Arcjet][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 Bun application.
 
-This is the [Arcjet][arcjet] SDK for [Bun.sh][bun-sh].
-
-- [npm package (`@arcjet/bun`)](https://www.npmjs.com/package/@arcjet/bun)
-- [GitHub source code (`arcjet-bun/` in `arcjet/arcjet-js`)](https://github.com/arcjet/arcjet-js/tree/main/arcjet-bun)
+This is the [Arcjet][arcjet] SDK for [Bun][bun-sh].
 
 ## Getting started
 
-Visit the [quick start guide][quick-start] to get started.
+1. Get your API key at [`app.arcjet.com`](https://app.arcjet.com)
+2. `bun add @arcjet/bun`
+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/bun) |
+[GitHub source](https://github.com/arcjet/arcjet-js/tree/main/arcjet-bun) |
+[Full docs][arcjet-reference-bun] |
+[Other SDKs on GitHub](https://github.com/arcjet)
+
+## Features
+
+- 🔒 [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 Bun HTTP server with bot detection, Shield WAF, and
+token bucket rate limiting.
 
-## Example
+```ts
+// index.ts
+import arcjet, { detectBot, shield, tokenBucket } from "@arcjet/bun";
+import { isSpoofedBot } from "@arcjet/inspect";
+import { env } from "bun";
 
-Try an Arcjet protected Next.js app live at
-[`example.arcjet.com`][example-next-url]
-([source code][example-next-source]).
+const aj = arcjet({
+  key: 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",
+      // 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
+    }),
+  ],
+});
 
-<!--
+export default {
+  port: 3000,
+  fetch: aj.handler(async (req) => {
+    const decision = await aj.protect(req, { requested: 5 }); // Deduct 5 tokens
+    console.log("Arcjet decision", decision);
 
-TODO: Bun example.
+    if (decision.isDenied()) {
+      if (decision.reason.isRateLimit()) {
+        return new Response("Too many requests", { status: 429 });
+      } else if (decision.reason.isBot()) {
+        return new Response("No bots allowed", { status: 403 });
+      } else {
+        return new Response("Forbidden", { status: 403 });
+      }
+    }
 
-See [`arcjet/example-bun`][example-astro-source] for a Bun example.
+    // Requests from hosting IPs are likely from bots.
+    // https://docs.arcjet.com/blueprints/vpn-proxy-detection
+    if (decision.ip.isHosting()) {
+      return new Response("Forbidden", { status: 403 });
+    }
 
-[example-bun-source]: https://github.com/arcjet/example-bun
+    // 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)) {
+      return new Response("Forbidden", { status: 403 });
+    }
 
--->
+    return new Response("Hello world");
+  }),
+};
+```
 
-## What is this?
+For the full reference, see the [Arcjet Bun SDK docs][arcjet-reference-bun].
 
-This is our adapter to integrate Arcjet into Bun.
-Arcjet helps you secure your Bun server.
-This package exists so that we can provide the best possible experience to
-Bun users.
+## Prompt injection detection
 
-## When should I use this?
+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.
 
-You can use this if you are using Bun.
-See our [_Get started_ guide][arcjet-get-started] for other supported
-runtimes.
+```ts
+import arcjet, { detectPromptInjection } from "@arcjet/bun";
+import { env } from "bun";
 
-## Install
+const aj = arcjet({
+  key: env.ARCJET_KEY!,
+  rules: [
+    detectPromptInjection({
+      mode: "LIVE", // Blocks requests. Use "DRY_RUN" to log only
+    }),
+  ],
+});
 
-This package is ESM only.
-Install with Bun:
+export default {
+  fetch: aj.handler(async (req) => {
+    const { message } = await req.json();
+
+    const decision = await aj.protect(req, {
+      detectPromptInjectionMessage: message,
+    });
+
+    if (decision.isDenied() && decision.reason.isPromptInjection()) {
+      return new Response(
+        "Prompt injection detected — please rephrase your message",
+        { status: 400 },
+      );
+    }
 
-```sh
-bun add @arcjet/bun
+    // Forward to your AI model...
+    return new Response("OK");
+  }),
+};
 ```
 
-## Use
+## Bot protection
 
-```ts
-import arcjet, { shield } from "@arcjet/bun";
+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.
 
-// Get your Arcjet key at <https://app.arcjet.com>.
-// Set it as an environment variable instead of hard coding it.
-const arcjetKey = Bun.env.ARCJET_KEY;
+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].
 
-if (!arcjetKey) {
-  throw new Error("Cannot find `ARCJET_KEY` environment variable");
-}
+```ts
+import arcjet, { detectBot } from "@arcjet/bun";
+import { isSpoofedBot } from "@arcjet/inspect";
+import { env } from "bun";
 
 const aj = arcjet({
-  key: arcjetKey,
+  key: env.ARCJET_KEY!,
   rules: [
-    // Shield protects your app from common attacks.
-    // Use `DRY_RUN` instead of `LIVE` to only log.
-    shield({ mode: "LIVE" }),
+    detectBot({
+      mode: "LIVE",
+      allow: [
+        "CATEGORY:SEARCH_ENGINE",
+        // See the full list at https://arcjet.com/bot-list
+      ],
+    }),
   ],
 });
 
 export default {
-  port: 8000,
-  fetch: aj.handler(async function (request: Request) {
-    const decision = await aj.protect(request);
+  fetch: aj.handler(async (req) => {
+    const decision = await aj.protect(req);
 
-    if (decision.isDenied()) {
-      return Response.json({ message: "Forbidden" }, { status: 403 });
+    if (decision.isDenied() && decision.reason.isBot()) {
+      return new Response("No bots allowed", { status: 403 });
+    }
+
+    // Verifies the authenticity of common bots using IP data.
+    if (decision.results.some(isSpoofedBot)) {
+      return new Response("Forbidden", { status: 403 });
     }
 
-    return Response.json({ message: "Hello world" });
+    return new Response("Hello world");
   }),
 };
 ```
 
-For more on how to configure Arcjet with Bun and how to protect Bun,
-see the [Arcjet Bun SDK reference][arcjet-reference-bun] on our website.
+### 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)) {
+  return new Response("Forbidden", { status: 403 });
+}
+```
+
+## 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/bun";
+import { env } from "bun";
+
+const aj = arcjet({
+  key: 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()) {
+  return new Response("Rate limit exceeded", { status: 429 });
+}
+```
+
+## 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/bun";
+import { env } from "bun";
+
+const aj = arcjet({
+  key: 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()) {
+  return new Response("Sensitive information detected", { status: 400 });
+}
+```
+
+## Shield WAF
+
+Protect your application against common web attacks, including the OWASP
+Top 10.
+
+```ts
+import arcjet, { shield } from "@arcjet/bun";
+import { env } from "bun";
+
+const aj = arcjet({
+  key: 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/bun";
+import { env } from "bun";
+
+const aj = arcjet({
+  key: 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()) {
+  return new Response("Invalid email address", { status: 400 });
+}
+```
+
+## Request filters
+
+Filter requests using expression-based rules against request properties (IP,
+headers, path, method, etc.).
+
+```ts
+import arcjet, { filter } from "@arcjet/bun";
+import { env } from "bun";
+
+const aj = arcjet({
+  key: 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()) {
+  return new Response("VPN traffic not allowed", { status: 403 });
+}
+```
+
+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
+  return new Response("Forbidden", { status: 403 });
+}
+
+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: 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/bun";
+import { env } from "bun";
+
+export default arcjet({
+  key: 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/bun";
+
+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: Request) {
+  const decision = await routeAj.protect(req, { requested: 500 });
+  // ...
+}
+```
+
+**Other recommendations:**
+
+- **Call `protect()` once per request** in the handler where you need it.
+- **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: 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
+  }
+  ```
 
 ## Test
 
@@ -119,11 +546,12 @@ bun test
 
 [Apache License, Version 2.0][apache-license] © [Arcjet Labs, Inc.][arcjet]
 
-[arcjet-get-started]: https://docs.arcjet.com/get-started
-[arcjet-reference-bun]: https://docs.arcjet.com/reference/bun
 [arcjet]: https://arcjet.com
+[arcjet-reference-bun]: https://docs.arcjet.com/reference/bun
 [bun-sh]: https://bun.sh/
-[example-next-source]: https://github.com/arcjet/example-nextjs
-[example-next-url]: https://example.arcjet.com
-[quick-start]: https://docs.arcjet.com/get-started/bun
 [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

package/index.js

@@ -26,7 +26,7 @@ function createRemoteClient(options) {
     // Transport is the HTTP client that the client uses to make requests.
     const transport = createTransport(url);
     const sdkStack = "BUN";
-    const sdkVersion = "1.3.0";
+    const sdkVersion = "1.4.0";
     return createClient({
         transport,
         baseUrl: url,

package/package.json

@@ -1,18 +1,25 @@
 {
   "name": "@arcjet/bun",
-  "version": "1.3.0",
-  "description": "Arcjet SDK for Bun",
+  "version": "1.4.0",
+  "description": "Arcjet runtime security SDK for Bun — bot protection, rate limiting, prompt injection detection, PII blocking, and WAF",
   "keywords": [
+    "ai",
     "analyze",
     "arcjet",
     "attack",
-    "bun.sh",
+    "bot-detection",
     "bun",
+    "bun.sh",
     "limit",
+    "llm",
+    "pii",
+    "prompt-injection",
     "protect",
+    "rate-limiting",
     "secure",
     "security",
-    "verify"
+    "verify",
+    "waf"
   ],
   "license": "Apache-2.0",
   "homepage": "https://arcjet.com",
@@ -44,23 +51,23 @@
     "test": "npm run build && npm run lint"
   },
   "dependencies": {
-    "@arcjet/body": "1.3.0",
-    "@arcjet/env": "1.3.0",
-    "@arcjet/headers": "1.3.0",
-    "@arcjet/ip": "1.3.0",
-    "@arcjet/logger": "1.3.0",
-    "@arcjet/protocol": "1.3.0",
-    "@arcjet/transport": "1.3.0",
-    "arcjet": "1.3.0"
+    "@arcjet/body": "1.4.0",
+    "@arcjet/env": "1.4.0",
+    "@arcjet/headers": "1.4.0",
+    "@arcjet/ip": "1.4.0",
+    "@arcjet/logger": "1.4.0",
+    "@arcjet/protocol": "1.4.0",
+    "@arcjet/transport": "1.4.0",
+    "arcjet": "1.4.0"
   },
   "devDependencies": {
-    "@arcjet/eslint-config": "1.3.0",
-    "@arcjet/rollup-config": "1.3.0",
-    "@rollup/wasm-node": "4.57.1",
-    "bun-types": "1.3.8",
-    "eslint": "9.39.2",
+    "@arcjet/eslint-config": "1.4.0",
+    "@arcjet/rollup-config": "1.4.0",
+    "@rollup/wasm-node": "4.59.0",
+    "bun-types": "1.3.10",
+    "eslint": "9.39.3",
     "typescript": "5.9.3",
-    "undici-types": "7.19.2"
+    "undici-types": "7.22.0"
   },
   "publishConfig": {
     "access": "public",