@arcjet/node 1.0.0-beta.1 → 1.0.0-beta.10

package/README.md

@@ -25,6 +25,9 @@ This is the [Arcjet][arcjet] SDK for [Node.js][node-js].
 **Looking for our Next.js framework SDK?** Check out the
 [`@arcjet/next`][alt-sdk] package.
 
+- [npm package (`@arcjet/node`)](https://www.npmjs.com/package/@arcjet/node)
+- [GitHub source code (`arcjet-node/` in `arcjet/arcjet-js`)](https://github.com/arcjet/arcjet-js/tree/main/arcjet-node)
+
 ## Getting started
 
 Visit the [quick start guide][quick-start] to get started.
@@ -34,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
-
-```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.
+## What is this?
 
-Bot detection is also enabled to block requests from known bots.
+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.
 
-```ts
-import arcjet, { tokenBucket, detectBot } from "@arcjet/node";
-import http from "node:http";
+## When should I use this?
 
-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
-    }),
-  ],
-});
+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 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);
+## Install
 
-  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" }));
-  }
-});
+This package is ESM only.
+Install with npm in Node.js:
 
-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.js

@@ -1,13 +1,45 @@
 import core__default from 'arcjet';
 export * from 'arcjet';
-import findIP from '@arcjet/ip';
+import findIP, { parseProxy } from '@arcjet/ip';
 import ArcjetHeaders from '@arcjet/headers';
-import { logLevel, baseUrl, isDevelopment, platform } from '@arcjet/env';
+import { logLevel, isDevelopment, baseUrl, platform } from '@arcjet/env';
 import { Logger } from '@arcjet/logger';
 import { createClient } from '@arcjet/protocol/client.js';
 import { createTransport } from '@arcjet/transport';
 import { readBody } from '@arcjet/body';
 
+// An object with getters that access the `process.env.SOMEVAR` values directly.
+// This allows bundlers to replace the dot-notation access with string literals
+// while still allowing dynamic access in runtime environments.
+const env = {
+    get FLY_APP_NAME() {
+        return process.env.FLY_APP_NAME;
+    },
+    get VERCEL() {
+        return process.env.VERCEL;
+    },
+    get RENDER() {
+        return process.env.RENDER;
+    },
+    get MODE() {
+        return process.env.MODE;
+    },
+    get NODE_ENV() {
+        return process.env.NODE_ENV;
+    },
+    get ARCJET_KEY() {
+        return process.env.ARCJET_KEY;
+    },
+    get ARCJET_ENV() {
+        return process.env.ARCJET_ENV;
+    },
+    get ARCJET_LOG_LEVEL() {
+        return process.env.ARCJET_LOG_LEVEL;
+    },
+    get ARCJET_BASE_URL() {
+        return process.env.ARCJET_BASE_URL;
+    },
+};
 // TODO: Deduplicate with other packages
 function errorMessage(err) {
     if (err) {
@@ -25,14 +57,14 @@ function errorMessage(err) {
 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(process.env);
+    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(process.env) ? 1000 : 500);
+    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.1";
+    const sdkVersion = "1.0.0-beta.10";
     return createClient({
         transport,
         baseUrl: url,
@@ -64,8 +96,14 @@ function arcjet(options) {
     const log = options.log
         ? options.log
         : new Logger({
-            level: logLevel(process.env),
+            level: logLevel(env),
         });
+    const proxies = Array.isArray(options.proxies)
+        ? options.proxies.map(parseProxy)
+        : undefined;
+    if (isDevelopment(env)) {
+        log.warn("Arcjet will use 127.0.0.1 when missing public IP address in development mode");
+    }
     function toArcjetRequest(request, props) {
         // We pull the cookies from the request before wrapping them in ArcjetHeaders
         const cookies = cookiesToString(request.headers?.cookie);
@@ -74,12 +112,11 @@ function arcjet(options) {
         let ip = findIP({
             socket: request.socket,
             headers,
-        }, { platform: platform(process.env), proxies: options.proxies });
+        }, { 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.
-            if (isDevelopment(process.env)) {
-                log.warn("Using 127.0.0.1 as IP address in development mode");
+            if (isDevelopment(env)) {
                 ip = "127.0.0.1";
             }
             else {

package/package.json

@@ -1,7 +1,19 @@
 {
   "name": "@arcjet/node",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.10",
   "description": "Arcjet SDK for Node.js",
+  "keywords": [
+    "analyze",
+    "arcjet",
+    "attack",
+    "limit",
+    "nodejs",
+    "node",
+    "protect",
+    "secure",
+    "security",
+    "verify"
+  ],
   "license": "Apache-2.0",
   "homepage": "https://arcjet.com",
   "repository": {
@@ -25,37 +37,33 @@
   "main": "./index.js",
   "types": "./index.d.ts",
   "files": [
-    "LICENSE",
-    "README.md",
-    "*.js",
-    "*.d.ts",
-    "!*.config.js"
+    "index.d.ts",
+    "index.js"
   ],
   "scripts": {
-    "prepublishOnly": "npm run build",
     "build": "rollup --config rollup.config.js",
     "lint": "eslint .",
-    "pretest": "npm run build",
-    "test": "node --test --experimental-test-coverage"
+    "prepublishOnly": "npm run build",
+    "test": "npm run build && npm run lint"
   },
   "dependencies": {
-    "@arcjet/env": "1.0.0-beta.1",
-    "@arcjet/headers": "1.0.0-beta.1",
-    "@arcjet/ip": "1.0.0-beta.1",
-    "@arcjet/logger": "1.0.0-beta.1",
-    "@arcjet/protocol": "1.0.0-beta.1",
-    "@arcjet/transport": "1.0.0-beta.1",
-    "@arcjet/body": "1.0.0-beta.1",
-    "arcjet": "1.0.0-beta.1"
+    "@arcjet/env": "1.0.0-beta.10",
+    "@arcjet/headers": "1.0.0-beta.10",
+    "@arcjet/ip": "1.0.0-beta.10",
+    "@arcjet/logger": "1.0.0-beta.10",
+    "@arcjet/protocol": "1.0.0-beta.10",
+    "@arcjet/transport": "1.0.0-beta.10",
+    "@arcjet/body": "1.0.0-beta.10",
+    "arcjet": "1.0.0-beta.10"
   },
   "devDependencies": {
-    "@arcjet/eslint-config": "1.0.0-beta.1",
-    "@arcjet/rollup-config": "1.0.0-beta.1",
-    "@arcjet/tsconfig": "1.0.0-beta.1",
+    "@arcjet/eslint-config": "1.0.0-beta.10",
+    "@arcjet/rollup-config": "1.0.0-beta.10",
+    "@arcjet/tsconfig": "1.0.0-beta.10",
     "@types/node": "18.18.0",
-    "@rollup/wasm-node": "4.30.1",
-    "expect": "29.7.0",
-    "typescript": "5.7.3"
+    "@rollup/wasm-node": "4.46.2",
+    "eslint": "9.32.0",
+    "typescript": "5.9.2"
   },
   "publishConfig": {
     "access": "public",