@arcjet/node 1.0.0-alpha.13 → 1.0.0-alpha.15

package/README.md

@@ -1,7 +1,7 @@
 <a href="https://arcjet.com" target="_arcjet-home">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://arcjet.com/arcjet-logo-dark-planet-arrival.svg">
-    <img src="https://arcjet.com/arcjet-logo-light-planet-arrival.svg" alt="Arcjet Logo" height="144" width="auto">
+    <source media="(prefers-color-scheme: dark)" srcset="https://arcjet.com/logo/arcjet-dark-lockup-voyage-horizontal.svg">
+    <img src="https://arcjet.com/logo/arcjet-light-lockup-voyage-horizontal.svg" alt="Arcjet Logo" height="128" width="auto">
   </picture>
 </a>
 
@@ -17,13 +17,22 @@
 </p>
 
 [Arcjet][arcjet] helps developers protect their apps in just a few lines of
-code. Implement rate limiting, bot protection, email verification & defend
+code. Implement rate limiting, bot protection, email verification, and defense
 against common attacks.
 
 This is the [Arcjet][arcjet] SDK for [Node.js][node-js].
 
 **Looking for our Next.js framework SDK?** Check out the
-[`@arcjet/next`](https://www.npmjs.com/package/@arcjet/next) package.
+[`@arcjet/next`][alt-sdk] package.
+
+## Getting started
+
+Visit the [quick start guide][quick-start] to get started.
+
+## Example app
+
+Try an Arcjet protected app live at [https://example.arcjet.com][example-url]
+([source code][example-source]).
 
 ## Installation
 
@@ -82,19 +91,20 @@ server.listen(8000);
 ## Shield example
 
 [Arcjet Shield][shield-concepts-docs] protects your application against common
-attacks, including the OWASP Top 10. It’s enabled by default and runs on every
-request with negligible performance impact.
+attacks, including the OWASP Top 10. You can run Shield on every request with
+negligible performance impact.
 
 ```ts
-import arcjet from "@arcjet/node";
+import arcjet, { shield } from "@arcjet/node";
 import http from "node:http";
 
 const aj = arcjet({
-  // Get your site key from https://app.arcjet.com
-  // and set it as an environment variable rather than hard coding.
-  // See: https://nextjs.org/docs/app/building-your-application/configuring/environment-variables
-  key: process.env.ARCJET_KEY,
-  rules: [], // Shield requires no rule configuration
+  key: process.env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com
+  rules: [
+    shield({
+      mode: "LIVE", // will block requests. Use "DRY_RUN" to log only
+    }),
+  ],
 });
 
 const server = http.createServer(async function (
@@ -121,6 +131,10 @@ Licensed under the [Apache License, Version 2.0][apache-license].
 
 [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
 [rate-limit-concepts-docs]: https://docs.arcjet.com/rate-limiting/concepts
 [shield-concepts-docs]: https://docs.arcjet.com/shield/concepts
 [apache-license]: http://www.apache.org/licenses/LICENSE-2.0

package/index.d.ts

@@ -1,4 +1,4 @@
-import { ArcjetDecision, ArcjetOptions, Primitive, Product, Runtime, ExtraProps, RemoteClient, RemoteClientOptions } from "arcjet";
+import { ArcjetDecision, ArcjetOptions, Primitive, Product, ExtraProps } from "arcjet";
 export * from "arcjet";
 type Simplify<T> = {
     [KeyType in keyof T]: T[KeyType];
@@ -10,7 +10,11 @@ type WithoutCustomProps = {
 type PlainObject = {
     [key: string]: unknown;
 };
-export declare function createNodeRemoteClient(options?: RemoteClientOptions): RemoteClient;
+export type RemoteClientOptions = {
+    baseUrl?: string;
+    timeout?: number;
+};
+export declare function createRemoteClient(options?: RemoteClientOptions): import("@arcjet/protocol/client.js").Client;
 export interface ArcjetNodeRequest {
     headers?: Record<string, string | string[] | undefined>;
     socket?: Partial<{
@@ -26,7 +30,6 @@ export interface ArcjetNodeRequest {
  * make a decision about how a Node.js request should be handled.
  */
 export interface ArcjetNode<Props extends PlainObject> {
-    get runtime(): Runtime;
     /**
      * Runs a request through the configured protections. The request is
      * analyzed and then a decision made on whether to allow, deny, or challenge

package/index.js

@@ -1,22 +1,33 @@
 import { createConnectTransport } from '@connectrpc/connect-node';
-import core__default, { defaultBaseUrl, createRemoteClient, ArcjetHeaders } from 'arcjet';
+import core__default from 'arcjet';
 export * from 'arcjet';
 import findIP from '@arcjet/ip';
+import ArcjetHeaders from '@arcjet/headers';
+import { logLevel, baseUrl, isProduction, platform, isDevelopment } from '@arcjet/env';
+import { Logger } from '@arcjet/logger';
+import { createClient } from '@arcjet/protocol/client.js';
 
-function createNodeRemoteClient(options) {
+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 baseUrl = options?.baseUrl ?? defaultBaseUrl();
+    const url = options?.baseUrl ?? baseUrl(process.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 ?? (isProduction(process.env) ? 500 : 1000);
     // Transport is the HTTP client that the client uses to make requests.
-    const transport = options?.transport ??
-        createConnectTransport({
-            baseUrl,
-            httpVersion: "2",
-        });
-    // TODO(#223): Do we want to allow overrides to either of these? If not, we should probably define a separate type for `options`
+    const transport = createConnectTransport({
+        baseUrl: url,
+        httpVersion: "2",
+    });
     const sdkStack = "NODEJS";
-    const sdkVersion = "1.0.0-alpha.13";
-    return createRemoteClient({ ...options, transport, sdkStack, sdkVersion });
+    const sdkVersion = "1.0.0-alpha.15";
+    return createClient({
+        transport,
+        baseUrl: url,
+        timeout,
+        sdkStack,
+        sdkVersion,
+    });
 }
 function cookiesToString(cookies) {
     if (typeof cookies === "undefined") {
@@ -33,7 +44,16 @@ function toArcjetRequest(request, props) {
     const cookies = cookiesToString(request.headers?.cookie);
     // We construct an ArcjetHeaders to normalize over Headers
     const headers = new ArcjetHeaders(request.headers);
-    const ip = findIP(request, headers);
+    let ip = findIP(request, headers, { platform: platform(process.env) });
+    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)) {
+            // TODO: Log that the fingerprint is being overridden once the adapter
+            // constructs the logger
+            ip = "127.0.0.1";
+        }
+    }
     const method = request.method ?? "";
     const host = headers.get("host") ?? "";
     let path = "";
@@ -77,9 +97,6 @@ function toArcjetRequest(request, props) {
 }
 function withClient(aj) {
     return Object.freeze({
-        get runtime() {
-            return aj.runtime;
-        },
         withRule(rule) {
             const client = aj.withRule(rule);
             return withClient(client);
@@ -89,7 +106,7 @@ function withClient(aj) {
             // 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 ?? {});
-            return aj.protect(req);
+            return aj.protect({}, req);
         },
     });
 }
@@ -102,9 +119,14 @@ function withClient(aj) {
  * @param options - Arcjet configuration options to apply to all requests.
  */
 function arcjet(options) {
-    const client = options.client ?? createNodeRemoteClient();
-    const aj = core__default({ ...options, client });
+    const client = options.client ?? createRemoteClient();
+    const log = options.log
+        ? options.log
+        : new Logger({
+            level: logLevel(process.env),
+        });
+    const aj = core__default({ ...options, client, log });
     return withClient(aj);
 }
 
-export { createNodeRemoteClient, arcjet as default };
+export { createRemoteClient, arcjet as default };

package/index.ts

@@ -4,17 +4,21 @@ import core, {
   ArcjetOptions,
   Primitive,
   Product,
-  ArcjetHeaders,
-  Runtime,
   ArcjetRequest,
   ExtraProps,
-  RemoteClient,
-  RemoteClientOptions,
-  defaultBaseUrl,
-  createRemoteClient,
   Arcjet,
 } from "arcjet";
 import findIP from "@arcjet/ip";
+import ArcjetHeaders from "@arcjet/headers";
+import {
+  baseUrl,
+  isDevelopment,
+  isProduction,
+  logLevel,
+  platform,
+} from "@arcjet/env";
+import { Logger } from "@arcjet/logger";
+import { createClient } from "@arcjet/protocol/client.js";
 
 // Re-export all named exports from the generic SDK
 export * from "arcjet";
@@ -56,26 +60,36 @@ type PlainObject = {
   [key: string]: unknown;
 };
 
-export function createNodeRemoteClient(
-  options?: RemoteClientOptions,
-): RemoteClient {
+export type RemoteClientOptions = {
+  baseUrl?: string;
+  timeout?: number;
+};
+
+export function createRemoteClient(options?: RemoteClientOptions) {
   // The base URL for the Arcjet API. Will default to the standard production
   // API unless environment variable `ARCJET_BASE_URL` is set.
-  const baseUrl = options?.baseUrl ?? defaultBaseUrl();
+  const url = options?.baseUrl ?? baseUrl(process.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 ?? (isProduction(process.env) ? 500 : 1000);
 
   // Transport is the HTTP client that the client uses to make requests.
-  const transport =
-    options?.transport ??
-    createConnectTransport({
-      baseUrl,
-      httpVersion: "2",
-    });
-
-  // TODO(#223): Do we want to allow overrides to either of these? If not, we should probably define a separate type for `options`
+  const transport = createConnectTransport({
+    baseUrl: url,
+    httpVersion: "2",
+  });
+
   const sdkStack = "NODEJS";
   const sdkVersion = "__ARCJET_SDK_VERSION__";
 
-  return createRemoteClient({ ...options, transport, sdkStack, sdkVersion });
+  return createClient({
+    transport,
+    baseUrl: url,
+    timeout,
+    sdkStack,
+    sdkVersion,
+  });
 }
 
 // Interface of fields that the Arcjet Node.js SDK expects on `IncomingMessage`
@@ -106,7 +120,6 @@ function cookiesToString(cookies: string | string[] | undefined): string {
  * make a decision about how a Node.js request should be handled.
  */
 export interface ArcjetNode<Props extends PlainObject> {
-  get runtime(): Runtime;
   /**
    * Runs a request through the configured protections. The request is
    * analyzed and then a decision made on whether to allow, deny, or challenge
@@ -145,7 +158,16 @@ function toArcjetRequest<Props extends PlainObject>(
   // We construct an ArcjetHeaders to normalize over Headers
   const headers = new ArcjetHeaders(request.headers);
 
-  const ip = findIP(request, headers);
+  let ip = findIP(request, headers, { platform: platform(process.env) });
+  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)) {
+      // TODO: Log that the fingerprint is being overridden once the adapter
+      // constructs the logger
+      ip = "127.0.0.1";
+    }
+  }
   const method = request.method ?? "";
   const host = headers.get("host") ?? "";
   let path = "";
@@ -192,9 +214,6 @@ function withClient<const Rules extends (Primitive | Product)[]>(
   aj: Arcjet<ExtraProps<Rules>>,
 ): ArcjetNode<ExtraProps<Rules>> {
   return Object.freeze({
-    get runtime() {
-      return aj.runtime;
-    },
     withRule(rule: Primitive | Product) {
       const client = aj.withRule(rule);
       return withClient(client);
@@ -212,7 +231,7 @@ function withClient<const Rules extends (Primitive | Product)[]>(
         ExtraProps<Rules>
       >;
 
-      return aj.protect(req);
+      return aj.protect({}, req);
     },
   });
 }
@@ -228,9 +247,15 @@ function withClient<const Rules extends (Primitive | Product)[]>(
 export default function arcjet<const Rules extends (Primitive | Product)[]>(
   options: ArcjetOptions<Rules>,
 ): ArcjetNode<Simplify<ExtraProps<Rules>>> {
-  const client = options.client ?? createNodeRemoteClient();
+  const client = options.client ?? createRemoteClient();
+
+  const log = options.log
+    ? options.log
+    : new Logger({
+        level: logLevel(process.env),
+      });
 
-  const aj = core({ ...options, client });
+  const aj = core({ ...options, client, log });
 
   return withClient(aj);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcjet/node",
-  "version": "1.0.0-alpha.13",
+  "version": "1.0.0-alpha.15",
   "description": "Arcjet SDK for Node.js",
   "license": "Apache-2.0",
   "homepage": "https://arcjet.com",
@@ -40,17 +40,21 @@
     "test": "NODE_OPTIONS=--experimental-vm-modules jest --passWithNoTests"
   },
   "dependencies": {
-    "@arcjet/ip": "1.0.0-alpha.13",
+    "@arcjet/env": "1.0.0-alpha.15",
+    "@arcjet/headers": "1.0.0-alpha.15",
+    "@arcjet/ip": "1.0.0-alpha.15",
+    "@arcjet/logger": "1.0.0-alpha.15",
+    "@arcjet/protocol": "1.0.0-alpha.15",
     "@connectrpc/connect-node": "1.4.0",
-    "arcjet": "1.0.0-alpha.13"
+    "arcjet": "1.0.0-alpha.15"
   },
   "devDependencies": {
-    "@arcjet/eslint-config": "1.0.0-alpha.13",
-    "@arcjet/rollup-config": "1.0.0-alpha.13",
-    "@arcjet/tsconfig": "1.0.0-alpha.13",
+    "@arcjet/eslint-config": "1.0.0-alpha.15",
+    "@arcjet/rollup-config": "1.0.0-alpha.15",
+    "@arcjet/tsconfig": "1.0.0-alpha.15",
     "@jest/globals": "29.7.0",
     "@types/node": "18.18.0",
-    "@rollup/wasm-node": "4.17.2",
+    "@rollup/wasm-node": "4.18.0",
     "jest": "29.7.0",
     "typescript": "5.4.5"
   },