@arcjet/node 1.0.0-beta.9 → 1.0.0

package/README.md

@@ -37,111 +37,83 @@ Visit the [quick start guide][quick-start] to get started.
 Try an Arcjet protected app live at [https://example.arcjet.com][example-url]
 ([source code][example-source]).
 
-## Installation
+## What is this?
 
-```shell
-npm install -S @arcjet/node
-```
-
-## Rate limit example
-
-The example below applies a token bucket rate limit rule to a route where we
-identify the user based on their ID e.g. if they are logged in. The bucket is
-configured with a maximum capacity of 10 tokens and refills by 5 tokens every 10
-seconds. Each request consumes 5 tokens.
+This is our adapter to integrate Arcjet into Node.js.
+Arcjet helps you secure your Node server.
+This package exists so that we can provide the best possible experience to
+Node users.
 
-Bot detection is also enabled to block requests from known bots.
+## When should I use this?
 
-```ts
-import arcjet, { tokenBucket, detectBot } from "@arcjet/node";
-import http from "node:http";
+You can use this if you are using Node.js.
+See our [_Get started_ guide][arcjet-get-started] for other supported
+frameworks and runtimes.
 
-const aj = arcjet({
-  key: process.env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com
-  characteristics: ["userId"], // track requests by a custom user ID
-  rules: [
-    // Create a token bucket rate limit. Other algorithms are supported.
-    tokenBucket({
-      mode: "LIVE", // will block requests. Use "DRY_RUN" to log only
-      refillRate: 5, // refill 5 tokens per interval
-      interval: 10, // refill every 10 seconds
-      capacity: 10, // bucket maximum capacity of 10 tokens
-    }),
-    detectBot({
-      mode: "LIVE", // will block requests. Use "DRY_RUN" to log only
-      // configured with a list of bots to allow from
-      // https://arcjet.com/bot-list
-      allow: [], // "allow none" will block all detected bots
-    }),
-  ],
-});
+## Install
 
-const server = http.createServer(async function (
-  req: http.IncomingMessage,
-  res: http.ServerResponse,
-) {
-  const userId = "user123"; // Replace with your authenticated user ID
-  const decision = await aj.protect(req, { userId, requested: 5 }); // Deduct 5 tokens from the bucket
-  console.log("Arcjet decision", decision);
+This package is ESM only.
+Install with npm in Node.js:
 
-  if (decision.isDenied()) {
-    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);
+```sh
+npm install @arcjet/node
 ```
 
-## Shield example
-
-[Arcjet Shield][shield-concepts-docs] protects your application against common
-attacks, including the OWASP Top 10. You can run Shield on every request with
-negligible performance impact.
+## Use
 
 ```ts
-import arcjet, { shield } from "@arcjet/node";
 import http from "node:http";
+import arcjet, { shield } from "@arcjet/node";
+
+// Get your Arcjet key at <https://app.arcjet.com>.
+// Set it as an environment variable instead of hard coding it.
+const arcjetKey = process.env.ARCJET_KEY;
+
+if (!arcjetKey) {
+  throw new Error("Cannot find `ARCJET_KEY` environment variable");
+}
 
 const aj = arcjet({
-  key: process.env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com
+  key: arcjetKey,
   rules: [
-    shield({
-      mode: "LIVE", // will block requests. Use "DRY_RUN" to log only
-    }),
+    // Shield protects your app from common attacks.
+    // Use `DRY_RUN` instead of `LIVE` to only log.
+    shield({ mode: "LIVE" }),
   ],
 });
 
 const server = http.createServer(async function (
-  req: http.IncomingMessage,
-  res: http.ServerResponse,
+  request: http.IncomingMessage,
+  response: http.ServerResponse,
 ) {
-  const decision = await aj.protect(req);
+  const decision = await aj.protect(request);
 
   if (decision.isDenied()) {
-    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" }));
+    response.writeHead(403, { "Content-Type": "application/json" });
+    response.end(JSON.stringify({ message: "Forbidden" }));
+    return;
   }
+
+  response.writeHead(200, { "Content-Type": "application/json" });
+  response.end(JSON.stringify({ message: "Hello world" }));
 });
 
 server.listen(8000);
 ```
 
+For more on how to configure Arcjet with Node.js and how to protect Node,
+see the [Arcjet Node.js SDK reference][arcjet-reference-node] on our website.
+
 ## License
 
-Licensed under the [Apache License, Version 2.0][apache-license].
+[Apache License, Version 2.0][apache-license] © [Arcjet Labs, Inc.][arcjet]
 
+[arcjet-get-started]: https://docs.arcjet.com/get-started
+[arcjet-reference-node]: https://docs.arcjet.com/reference/nodejs
 [arcjet]: https://arcjet.com
 [node-js]: https://nodejs.org/
 [alt-sdk]: https://www.npmjs.com/package/@arcjet/next
 [example-url]: https://example.arcjet.com
 [quick-start]: https://docs.arcjet.com/get-started/nodejs
 [example-source]: https://github.com/arcjet/arcjet-js-example
-[shield-concepts-docs]: https://docs.arcjet.com/shield/concepts
 [apache-license]: http://www.apache.org/licenses/LICENSE-2.0

package/index.d.ts

@@ -4,72 +4,184 @@ type Simplify<T> = {
     [KeyType in keyof T]: T[KeyType];
 } & {};
 declare const emptyObjectSymbol: unique symbol;
-type WithoutCustomProps = {
-    [emptyObjectSymbol]?: never;
-};
 type PlainObject = {
     [key: string]: unknown;
 };
+/**
+ * Dynamically generate whether zero or one `properties` object must or can be passed.
+ */
+type MaybeProperties<T> = {
+    [P in keyof T]?: T[P];
+} extends T ? T extends {
+    [emptyObjectSymbol]?: never;
+} ? [
+] : [
+    properties?: T
+] : [
+    properties: T
+];
+/**
+ * Configuration for {@linkcode createRemoteClient}.
+ */
 export type RemoteClientOptions = {
+    /**
+     * Base URI for HTTP requests to Decide API (optional).
+     *
+     * Defaults to the environment variable `ARCJET_BASE_URL` (if that value
+     * is known and allowed) and the standard production API otherwise.
+     */
     baseUrl?: string;
+    /**
+     * Timeout in milliseconds for the Decide API (optional).
+     *
+     * Defaults to `500` in production and `1000` in development.
+     */
     timeout?: number;
 };
+/**
+ * Create a remote client.
+ *
+ * @param options
+ *   Configuration (optional).
+ * @returns
+ *   Client.
+ */
 export declare function createRemoteClient(options?: RemoteClientOptions): import("@arcjet/protocol/client.js").Client;
 type EventHandlerLike = (event: string, listener: (...args: any[]) => void) => void;
+/**
+ * Request for the Node.js integration of Arcjet.
+ *
+ * This is the minimum interface similar to `http.IncomingMessage`.
+ */
 export interface ArcjetNodeRequest {
-    headers?: Record<string, string | string[] | undefined>;
+    /**
+     * Headers of the request.
+     */
+    headers?: Record<string, string | string[] | undefined> | undefined;
+    /**
+     * `net.Socket` object associated with the connection.
+     *
+     * See <https://nodejs.org/api/http.html#messagesocket>.
+     */
     socket?: Partial<{
-        remoteAddress: string;
+        remoteAddress?: string | undefined;
         encrypted: boolean;
-    }>;
-    method?: string;
-    httpVersion?: string;
-    url?: string;
+    }> | undefined;
+    /**
+     * HTTP method of the request.
+     */
+    method?: string | undefined;
+    /**
+     * HTTP version sent by the client.
+     *
+     * See <https://nodejs.org/api/http.html#messagehttpversion>.
+     */
+    httpVersion?: string | undefined;
+    /**
+     * URL.
+     */
+    url?: string | undefined;
+    /**
+     * Request body.
+     */
     body?: unknown;
-    on?: EventHandlerLike;
-    removeListener?: EventHandlerLike;
-    readable?: boolean;
+    /**
+     * Add event handlers.
+     *
+     * This field is available through `stream.Readable` from `EventEmitter`.
+     *
+     * See <https://nodejs.org/api/events.html#emitteroneventname-listener>.
+     */
+    on?: EventHandlerLike | undefined;
+    /**
+     * Remove event handlers.
+     *
+     * This field is available through `stream.Readable` from `EventEmitter`.
+     *
+     * See <https://nodejs.org/api/events.html#emitterremovelistenereventname-listener>.
+     */
+    removeListener?: EventHandlerLike | undefined;
+    /**
+     * Whether the readable stream is readable.
+     *
+     * This field is available from `stream.Readable`.
+     *
+     * See <https://nodejs.org/api/stream.html#readablereadable>.
+     */
+    readable?: boolean | undefined;
 }
 /**
- * The options used to configure an {@link ArcjetNode} client.
+ * Configuration for the Node.js integration of Arcjet.
+ *
+ * @template Rules
+ *   List of rules.
+ * @template Characteristics
+ *   Characteristics to track a user by.
  */
 export type ArcjetOptions<Rules extends [...Array<Primitive | Product>], Characteristics extends readonly string[]> = Simplify<CoreOptions<Rules, Characteristics> & {
     /**
-     * One or more IP Address of trusted proxies in front of the application.
-     * These addresses will be excluded when Arcjet detects a public IP address.
+     * IP addresses and CIDR ranges of trusted load balancers and proxies
+     * (optional, example: `["100.100.100.100", "100.100.100.0/24"]`).
      */
     proxies?: Array<string>;
 }>;
 /**
- * The ArcjetNode client provides a public `protect()` method to
- * make a decision about how a Node.js request should be handled.
+ * Instance of the Node.js integration of Arcjet.
+ *
+ * Primarily has a `protect()` method to make a decision about how a Node request
+ * should be handled.
+ *
+ * @template Props
+ *   Configuration.
  */
 export interface ArcjetNode<Props extends PlainObject> {
     /**
-     * Runs a request through the configured protections. The request is
-     * analyzed and then a decision made on whether to allow, deny, or challenge
-     * the request.
+     * Make a decision about how to handle a request.
      *
-     * @param req - An `IncomingMessage` provided to the request handler.
-     * @param props - Additonal properties required for running rules against a request.
-     * @returns An {@link ArcjetDecision} indicating Arcjet's decision about the request.
+     * This will analyze the request locally where possible and otherwise call
+     * the Arcjet decision API.
+     *
+     * @param request
+     *   Details about the {@linkcode ArcjetNodeRequest} that Arcjet needs to make a
+     *   decision.
+     * @param props
+     *   Additional properties required for running rules against a request.
+     * @returns
+     *   Promise that resolves to an {@linkcode ArcjetDecision} indicating
+     *   Arcjet’s decision about the request.
      */
-    protect(request: ArcjetNodeRequest, ...props: Props extends WithoutCustomProps ? [] : [Props]): Promise<ArcjetDecision>;
+    protect(request: ArcjetNodeRequest, ...props: MaybeProperties<Props>): Promise<ArcjetDecision>;
     /**
-     * Augments the client with another rule. Useful for varying rules based on
-     * criteria in your handler—e.g. different rate limit for logged in users.
+     * Augment the client with another rule.
+     *
+     * Useful for varying rules based on criteria in your handler such as
+     * different rate limit for logged in users.
      *
-     * @param rule The rule to add to this execution.
-     * @returns An augmented {@link ArcjetNode} client.
+     * @template Rule
+     *   Type of rule.
+     * @param rule
+     *   Rule to add to Arcjet.
+     * @returns
+     *   Arcjet instance augmented with the given rule.
      */
-    withRule<Rule extends Primitive | Product>(rule: Rule): ArcjetNode<Simplify<Props & ExtraProps<Rule>>>;
+    withRule<ChildProperties extends PlainObject>(rule: Primitive<ChildProperties> | Product<ChildProperties>): ArcjetNode<Props & ChildProperties>;
 }
 /**
- * Create a new {@link ArcjetNode} client. Always build your initial client
- * outside of a request handler so it persists across requests. If you need to
- * augment a client inside a handler, call the `withRule()` function on the base
- * client.
+ * Create a new Node.js integration of Arcjet.
+ *
+ * > 👉 **Tip**:
+ * > build your initial base client with as many rules as possible outside of a
+ * > request handler;
+ * > if you need more rules inside handlers later then you can call `withRule()`
+ * > on that base client.
  *
- * @param options - Arcjet configuration options to apply to all requests.
+ * @template Rules
+ *   List of rules.
+ * @template Characteristics
+ *   Characteristics to track a user by.
+ * @param options
+ *   Configuration.
+ * @returns
+ *   Node.js integration of Arcjet.
  */
-export default function arcjet<const Rules extends (Primitive | Product)[], const Characteristics extends readonly string[]>(options: ArcjetOptions<Rules, Characteristics>): ArcjetNode<Simplify<ExtraProps<Rules> & CharacteristicProps<Characteristics>>>;
+export default function arcjet<const Rules extends (Primitive | Product)[], const Characteristics extends readonly string[]>(options: ArcjetOptions<Rules, Characteristics>): ArcjetNode<ExtraProps<Rules> & CharacteristicProps<Characteristics>>;

package/index.js

@@ -1,7 +1,8 @@
+import * as core from 'arcjet';
 import core__default from 'arcjet';
 export * from 'arcjet';
-import findIP, { parseProxy } from '@arcjet/ip';
-import ArcjetHeaders from '@arcjet/headers';
+import findIp, { parseProxy } from '@arcjet/ip';
+import { ArcjetHeaders } from '@arcjet/headers';
 import { logLevel, isDevelopment, baseUrl, platform } from '@arcjet/env';
 import { Logger } from '@arcjet/logger';
 import { createClient } from '@arcjet/protocol/client.js';
@@ -27,9 +28,6 @@ const env = {
     get NODE_ENV() {
         return process.env.NODE_ENV;
     },
-    get ARCJET_KEY() {
-        return process.env.ARCJET_KEY;
-    },
     get ARCJET_ENV() {
         return process.env.ARCJET_ENV;
     },
@@ -39,32 +37,26 @@ const env = {
     get ARCJET_BASE_URL() {
         return process.env.ARCJET_BASE_URL;
     },
+    get FIREBASE_CONFIG() {
+        return process.env.FIREBASE_CONFIG;
+    },
 };
-// TODO: Deduplicate with other packages
-function errorMessage(err) {
-    if (err) {
-        if (typeof err === "string") {
-            return err;
-        }
-        if (typeof err === "object" &&
-            "message" in err &&
-            typeof err.message === "string") {
-            return err.message;
-        }
-    }
-    return "Unknown problem";
-}
+let warnedForAutomaticBodyRead = false;
+/**
+ * Create a remote client.
+ *
+ * @param options
+ *   Configuration (optional).
+ * @returns
+ *   Client.
+ */
 function createRemoteClient(options) {
-    // The base URL for the Arcjet API. Will default to the standard production
-    // API unless environment variable `ARCJET_BASE_URL` is set.
     const url = options?.baseUrl ?? baseUrl(env);
-    // The timeout for the Arcjet API in milliseconds. This is set to a low value
-    // in production so calls fail open.
     const timeout = options?.timeout ?? (isDevelopment(env) ? 1000 : 500);
     // Transport is the HTTP client that the client uses to make requests.
     const transport = createTransport(url);
     const sdkStack = "NODEJS";
-    const sdkVersion = "1.0.0-beta.9";
+    const sdkVersion = "1.0.0";
     return createClient({
         transport,
         baseUrl: url,
@@ -84,12 +76,22 @@ function cookiesToString(cookies) {
     return cookies;
 }
 /**
- * Create a new {@link ArcjetNode} client. Always build your initial client
- * outside of a request handler so it persists across requests. If you need to
- * augment a client inside a handler, call the `withRule()` function on the base
- * client.
+ * Create a new Node.js integration of Arcjet.
  *
- * @param options - Arcjet configuration options to apply to all requests.
+ * > 👉 **Tip**:
+ * > build your initial base client with as many rules as possible outside of a
+ * > request handler;
+ * > if you need more rules inside handlers later then you can call `withRule()`
+ * > on that base client.
+ *
+ * @template Rules
+ *   List of rules.
+ * @template Characteristics
+ *   Characteristics to track a user by.
+ * @param options
+ *   Configuration.
+ * @returns
+ *   Node.js integration of Arcjet.
  */
 function arcjet(options) {
     const client = options.client ?? createRemoteClient();
@@ -109,10 +111,14 @@ function arcjet(options) {
         const cookies = cookiesToString(request.headers?.cookie);
         // We construct an ArcjetHeaders to normalize over Headers
         const headers = new ArcjetHeaders(request.headers);
-        let ip = findIP({
-            socket: request.socket,
-            headers,
-        }, { platform: platform(env), proxies });
+        const xArcjetIp = isDevelopment(env)
+            ? headers.get("x-arcjet-ip")
+            : undefined;
+        let ip = xArcjetIp ||
+            findIp({
+                socket: request.socket,
+                headers,
+            }, { platform: platform(env), proxies });
         if (ip === "") {
             // If the `ip` is empty but we're in development mode, we default the IP
             // so the request doesn't fail.
@@ -167,62 +173,41 @@ function arcjet(options) {
         };
     }
     function withClient(aj) {
-        return Object.freeze({
+        const client = {
             withRule(rule) {
                 const client = aj.withRule(rule);
                 return withClient(client);
             },
-            async protect(request, ...[props]) {
-                // TODO(#220): The generic manipulations get really mad here, so we cast
-                // Further investigation makes it seem like it has something to do with
-                // the definition of `props` in the signature but it's hard to track down
-                const req = toArcjetRequest(request, props ?? {});
+            async protect(request, props) {
+                // Cast of `{}` because here we switch from `undefined` to `Properties`.
+                const req = toArcjetRequest(request, props || {});
                 const getBody = async () => {
-                    try {
-                        // If request.body is present then the body was likely read by a package like express' `body-parser`.
-                        // If it's not present then we attempt to read the bytes from the IncomingMessage ourselves.
-                        if (typeof request.body === "string") {
-                            return request.body;
+                    // Read the stream if the body is not present.
+                    if (request.body === null || request.body === undefined) {
+                        let expectedLength;
+                        // TODO: This shouldn't need to build headers again but the type
+                        // for `req` above is overly relaxed
+                        const headers = new ArcjetHeaders(request.headers);
+                        const expectedLengthStr = headers.get("content-length");
+                        if (typeof expectedLengthStr === "string") {
+                            expectedLength = parseInt(expectedLengthStr, 10);
                         }
-                        else if (typeof request.body !== "undefined" &&
-                            // BigInt cannot be serialized with JSON.stringify
-                            typeof request.body !== "bigint") {
-                            return JSON.stringify(request.body);
+                        if (!warnedForAutomaticBodyRead) {
+                            warnedForAutomaticBodyRead = true;
+                            log.warn("Automatically reading the request body is deprecated; please pass an explicit `sensitiveInfoValue` field. See <https://docs.arcjet.com/upgrading/sdk-migration>.");
                         }
-                        if (typeof request.on === "function" &&
-                            typeof request.removeListener === "function") {
-                            let expectedLength;
-                            // TODO: This shouldn't need to build headers again but the type
-                            // for `req` above is overly relaxed
-                            const headers = new ArcjetHeaders(request.headers);
-                            const expectedLengthStr = headers.get("content-length");
-                            if (typeof expectedLengthStr === "string") {
-                                try {
-                                    expectedLength = parseInt(expectedLengthStr, 10);
-                                }
-                                catch {
-                                    // If the expected length couldn't be parsed we'll just not set one.
-                                }
-                            }
-                            // Awaited to throw if it rejects and we'll just return undefined
-                            const body = await readBody(request, {
-                                // We will process 1mb bodies
-                                limit: 1048576,
-                                expectedLength,
-                            });
-                            return body;
-                        }
-                        log.warn("no body available");
-                        return;
+                        return readBody(request, { expectedLength });
                     }
-                    catch (e) {
-                        log.error("failed to get request body: %s", errorMessage(e));
-                        return;
+                    // A package like `body-parser` was used to read the stream.
+                    if (typeof request.body === "string") {
+                        return request.body;
                     }
+                    return JSON.stringify(request.body);
                 };
                 return aj.protect({ getBody }, req);
             },
-        });
+        };
+        return Object.freeze(client);
     }
     const aj = core__default({ ...options, client, log });
     return withClient(aj);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcjet/node",
-  "version": "1.0.0-beta.9",
+  "version": "1.0.0",
   "description": "Arcjet SDK for Node.js",
   "keywords": [
     "analyze",
@@ -31,7 +31,7 @@
     "url": "https://arcjet.com"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "type": "module",
   "main": "./index.js",
@@ -44,26 +44,28 @@
     "build": "rollup --config rollup.config.js",
     "lint": "eslint .",
     "prepublishOnly": "npm run build",
-    "test": "npm run build && npm run lint"
+    "test-api": "node --test -- test/*.test.js",
+    "test-coverage#": "TODO: after node 20, use: ` --test-coverage-branches=100 --test-coverage-exclude \"../{analyze-wasm,analyze,arcjet,cache,duration,env,headers,ip,logger,protocol,runtime,sprintf,stable-hash,transport}/**/*.{js,ts}\" --test-coverage-exclude \"test/**/*.{js,ts}\" --test-coverage-functions=100 --test-coverage-lines=100`",
+    "test-coverage": "node --experimental-test-coverage --test -- test/*.test.js",
+    "test": "npm run build && npm run lint && npm run test-coverage"
   },
   "dependencies": {
-    "@arcjet/env": "1.0.0-beta.9",
-    "@arcjet/headers": "1.0.0-beta.9",
-    "@arcjet/ip": "1.0.0-beta.9",
-    "@arcjet/logger": "1.0.0-beta.9",
-    "@arcjet/protocol": "1.0.0-beta.9",
-    "@arcjet/transport": "1.0.0-beta.9",
-    "@arcjet/body": "1.0.0-beta.9",
-    "arcjet": "1.0.0-beta.9"
+    "@arcjet/env": "1.0.0",
+    "@arcjet/headers": "1.0.0",
+    "@arcjet/ip": "1.0.0",
+    "@arcjet/logger": "1.0.0",
+    "@arcjet/protocol": "1.0.0",
+    "@arcjet/transport": "1.0.0",
+    "@arcjet/body": "1.0.0",
+    "arcjet": "1.0.0"
   },
   "devDependencies": {
-    "@arcjet/eslint-config": "1.0.0-beta.9",
-    "@arcjet/rollup-config": "1.0.0-beta.9",
-    "@arcjet/tsconfig": "1.0.0-beta.9",
-    "@types/node": "18.18.0",
-    "@rollup/wasm-node": "4.44.2",
-    "eslint": "9.30.1",
-    "typescript": "5.8.3"
+    "@arcjet/eslint-config": "1.0.0",
+    "@arcjet/rollup-config": "1.0.0",
+    "@types/node": "25.0.8",
+    "@rollup/wasm-node": "4.55.1",
+    "eslint": "9.39.2",
+    "typescript": "5.9.3"
   },
   "publishConfig": {
     "access": "public",