@arcjet/node 1.0.0-alpha.12 → 1.0.0-alpha.14

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, RemoteClient, RemoteClientOptions } from "arcjet";
 export * from "arcjet";
 type Simplify<T> = {
     [KeyType in keyof T]: T[KeyType];
@@ -10,7 +10,7 @@ type WithoutCustomProps = {
 type PlainObject = {
     [key: string]: unknown;
 };
-export declare function createNodeRemoteClient(options?: RemoteClientOptions): RemoteClient;
+export declare function createNodeRemoteClient(options?: Partial<RemoteClientOptions>): RemoteClient;
 export interface ArcjetNodeRequest {
     headers?: Record<string, string | string[] | undefined>;
     socket?: Partial<{
@@ -26,7 +26,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,34 @@
 import { createConnectTransport } from '@connectrpc/connect-node';
-import core__default, { defaultBaseUrl, createRemoteClient, ArcjetHeaders } from 'arcjet';
+import core__default, { createRemoteClient } 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';
 
 function createNodeRemoteClient(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,
+            baseUrl: url,
             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`
+    // TODO(#223): Create separate options type to exclude these
     const sdkStack = "NODEJS";
-    const sdkVersion = "1.0.0-alpha.12";
-    return createRemoteClient({ ...options, transport, sdkStack, sdkVersion });
+    const sdkVersion = "1.0.0-alpha.14";
+    return createRemoteClient({
+        transport,
+        baseUrl: url,
+        timeout,
+        sdkStack,
+        sdkVersion,
+    });
 }
 function cookiesToString(cookies) {
     if (typeof cookies === "undefined") {
@@ -29,9 +41,20 @@ function cookiesToString(cookies) {
     return cookies;
 }
 function toArcjetRequest(request, props) {
+    // We pull the cookies from the request before wrapping them in ArcjetHeaders
+    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 = "";
@@ -61,7 +84,6 @@ function toArcjetRequest(request, props) {
     else {
         path = request.url ?? "";
     }
-    const cookies = cookiesToString(request.headers?.cookie);
     return {
         ...props,
         ip,
@@ -76,9 +98,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);
@@ -88,7 +107,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,7 +121,12 @@ function withClient(aj) {
  */
 function arcjet(options) {
     const client = options.client ?? createNodeRemoteClient();
-    const aj = core__default({ ...options, client });
+    const log = options.log
+        ? options.log
+        : new Logger({
+            level: logLevel(process.env),
+        });
+    const aj = core__default({ ...options, client, log });
     return withClient(aj);
 }
 

package/index.ts

@@ -4,17 +4,23 @@ 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";
 
 // Re-export all named exports from the generic SDK
 export * from "arcjet";
@@ -57,25 +63,35 @@ type PlainObject = {
 };
 
 export function createNodeRemoteClient(
-  options?: RemoteClientOptions,
+  options?: Partial<RemoteClientOptions>,
 ): RemoteClient {
   // 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,
+      baseUrl: url,
       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`
+  // TODO(#223): Create separate options type to exclude these
   const sdkStack = "NODEJS";
   const sdkVersion = "__ARCJET_SDK_VERSION__";
 
-  return createRemoteClient({ ...options, transport, sdkStack, sdkVersion });
+  return createRemoteClient({
+    transport,
+    baseUrl: url,
+    timeout,
+    sdkStack,
+    sdkVersion,
+  });
 }
 
 // Interface of fields that the Arcjet Node.js SDK expects on `IncomingMessage`
@@ -106,7 +122,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
@@ -139,10 +154,22 @@ function toArcjetRequest<Props extends PlainObject>(
   request: ArcjetNodeRequest,
   props: Props,
 ): ArcjetRequest<Props> {
+  // We pull the cookies from the request before wrapping them in ArcjetHeaders
+  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 = "";
@@ -172,8 +199,6 @@ function toArcjetRequest<Props extends PlainObject>(
     path = request.url ?? "";
   }
 
-  const cookies = cookiesToString(request.headers?.cookie);
-
   return {
     ...props,
     ip,
@@ -191,9 +216,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);
@@ -211,7 +233,7 @@ function withClient<const Rules extends (Primitive | Product)[]>(
         ExtraProps<Rules>
       >;
 
-      return aj.protect(req);
+      return aj.protect({}, req);
     },
   });
 }
@@ -229,7 +251,13 @@ export default function arcjet<const Rules extends (Primitive | Product)[]>(
 ): ArcjetNode<Simplify<ExtraProps<Rules>>> {
   const client = options.client ?? createNodeRemoteClient();
 
-  const aj = core({ ...options, client });
+  const log = options.log
+    ? options.log
+    : new Logger({
+        level: logLevel(process.env),
+      });
+
+  const aj = core({ ...options, client, log });
 
   return withClient(aj);
 }

package/package.json

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