@arcjet/analyze 1.0.0-alpha.9 → 1.0.0-beta.1

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,7 +17,7 @@
 </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] local analysis engine.
@@ -42,37 +42,17 @@ console.log("is email valid?", valid);
 
 ## Implementation
 
-This package provides analyze logic implemented as a WebAssembly module which
-will run local analysis on request details before calling the Arcjet API.
+This package uses the Wasm bindings provided by `@arcjet/analyze-wasm` to
+call various functions that are exported by our wasm bindings.
 
-The [arcjet.wasm.js](./wasm/arcjet.wasm.js) file contains the binary inlined as
-a base64 [Data URL][mdn-data-url] with the `application/wasm` MIME type.
-
-This was chosen to save on storage space over inlining the file directly as a
-Uint8Array, which would take up ~3x the space of the Wasm file. See
-[Better Binary Batter: Mixing Base64 and Uint8Array][wasm-base64-blog] for more
-details.
-
-It is then decoded into an ArrayBuffer to be used directly via WebAssembly's
-`compile()` function in our entry point file.
-
-This is all done to avoid trying to read or bundle the Wasm asset in various
-ways based on the platform or bundler a user is targeting. One example being
-that Next.js requires special `asyncWebAssembly` webpack config to load our
-Wasm file if we don't do this.
-
-In the future, we hope to do away with this workaround when all bundlers
-properly support consistent asset bundling techniques.
-
-## API
-
-In progress.
+We chose to put this logic in a separate package because we need to change the
+import structure for each runtime that we support in the wasm bindings. Moving
+this to a separate package allows us not to have to duplicate code while providing
+a combined higher-level api for calling our core functionality in Wasm.
 
 ## License
 
 Licensed under the [Apache License, Version 2.0][apache-license].
 
 [arcjet]: https://arcjet.com
-[mdn-data-url]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs
-[wasm-base64-blog]: https://blobfolio.com/2019/better-binary-batter-mixing-base64-and-uint8array/
 [apache-license]: http://www.apache.org/licenses/LICENSE-2.0

package/index.d.ts

@@ -1,27 +1,29 @@
-import { type EmailValidationConfig } from "./wasm/arcjet_analyze_js_req.js";
-export { type EmailValidationConfig };
+import type { BotConfig, BotResult, DetectedSensitiveInfoEntity, DetectSensitiveInfoFunction, EmailValidationConfig, EmailValidationResult, SensitiveInfoEntities, SensitiveInfoEntity, SensitiveInfoResult } from "@arcjet/analyze-wasm";
+import type { ArcjetLogger } from "@arcjet/protocol";
+interface AnalyzeContext {
+    log: ArcjetLogger;
+    characteristics: string[];
+}
+type AnalyzeRequest = {
+    ip?: string;
+    method?: string;
+    protocol?: string;
+    host?: string;
+    path?: string;
+    headers?: Record<string, string>;
+    cookies?: string;
+    query?: string;
+    extra?: Record<string, string>;
+};
+export { type EmailValidationConfig, type BotConfig, type SensitiveInfoEntity, type DetectedSensitiveInfoEntity, };
 /**
  * Generate a fingerprint for the client. This is used to identify the client
  * across multiple requests.
- * @param ip - The IP address of the client.
+ * @param context - The Arcjet Analyze context.
+ * @param request - The request to fingerprint.
  * @returns A SHA-256 string fingerprint.
  */
-export declare function generateFingerprint(ip: string): Promise<string>;
-export declare function isValidEmail(candidate: string, options?: EmailValidationConfig): Promise<boolean>;
-/**
- * Represents the result of the bot detection.
- *
- * @property `bot_type` - What type of bot this is. This will be one of `BotType`.
- * @property `bot_score` - A score ranging from 0 to 99 representing the degree of
- * certainty. The higher the number within the type category, the greater the
- * degree of certainty. E.g. `BotType.Automated` with a score of 1 means we are
- * sure the request was made by an automated bot. `BotType.LikelyNotABot` with a
- * score of 30 means we don't think this request was a bot, but it's lowest
- * confidence level. `BotType.LikelyNotABot` with a score of 99 means we are
- * almost certain this request was not a bot.
- */
-export interface BotResult {
-    bot_type: number;
-    bot_score: number;
-}
-export declare function detectBot(headers: string, patterns_add: string, patterns_remove: string): Promise<BotResult>;
+export declare function generateFingerprint(context: AnalyzeContext, request: AnalyzeRequest): Promise<string>;
+export declare function isValidEmail(context: AnalyzeContext, candidate: string, options: EmailValidationConfig): Promise<EmailValidationResult>;
+export declare function detectBot(context: AnalyzeContext, request: AnalyzeRequest, options: BotConfig): Promise<BotResult>;
+export declare function detectSensitiveInfo(context: AnalyzeContext, candidate: string, entities: SensitiveInfoEntities, contextWindowSize: number, detect?: DetectSensitiveInfoFunction): Promise<SensitiveInfoResult>;

package/index.js

@@ -1,109 +1,116 @@
-import initWasm, { detect_bot, generate_fingerprint, is_valid_email } from './wasm/arcjet_analyze_js_req.js';
+import { initializeWasm } from '@arcjet/analyze-wasm';
 
-let state = "uninitialized";
-/**
- * Initialize the WASM module. This can be explicitly called after creating
- * the client, but it will be called automatically if it has not been called
- * when the first request is made. This uses a factory-style pattern because
- * the call must be async and the constructor cannot be async.
- */
-async function init() {
-    if (state === "errored" || state === "unsupported")
-        return;
-    if (typeof WebAssembly === "undefined") {
-        state = "unsupported";
-        return;
-    }
-    if (state === "uninitialized") {
-        try {
-            let wasmModule;
-            // We use `NEXT_RUNTIME` env var to DCE the Node/Browser code in the `else` block
-            // possible values: "edge" | "nodejs" | undefined
-            if (process.env["NEXT_RUNTIME"] === "edge") {
-                const mod = await import(
-                // @ts-expect-error
-                './wasm/arcjet_analyze_js_req_bg.wasm?module');
-                wasmModule = mod.default;
-            }
-            else {
-                const { wasm } = await import('./wasm/arcjet.wasm.js');
-                wasmModule = await WebAssembly.compile(await wasm());
-            }
-            await initWasm(wasmModule);
-            state = "initialized";
-        }
-        catch (err) {
-            state = "errored";
-            return;
-        }
+const FREE_EMAIL_PROVIDERS = [
+    "gmail.com",
+    "yahoo.com",
+    "hotmail.com",
+    "aol.com",
+    "hotmail.co.uk",
+];
+function noOpDetect() {
+    return [];
+}
+function createCoreImports(detect) {
+    if (typeof detect !== "function") {
+        detect = noOpDetect;
     }
     return {
-        detectBot: detect_bot,
-        fingerprint: generate_fingerprint,
-        isValidEmail: is_valid_email,
+        "arcjet:js-req/email-validator-overrides": {
+            isFreeEmail(domain) {
+                if (FREE_EMAIL_PROVIDERS.includes(domain)) {
+                    return "yes";
+                }
+                return "unknown";
+            },
+            isDisposableEmail() {
+                return "unknown";
+            },
+            hasMxRecords() {
+                return "unknown";
+            },
+            hasGravatar() {
+                return "unknown";
+            },
+        },
+        "arcjet:js-req/sensitive-information-identifier": {
+            detect,
+        },
+        "arcjet:js-req/verify-bot": {
+            verify() {
+                return "unverifiable";
+            },
+        },
     };
 }
 /**
  * Generate a fingerprint for the client. This is used to identify the client
  * across multiple requests.
- * @param ip - The IP address of the client.
+ * @param context - The Arcjet Analyze context.
+ * @param request - The request to fingerprint.
  * @returns A SHA-256 string fingerprint.
  */
-async function generateFingerprint(ip) {
-    if (ip == "") {
-        return "";
-    }
-    // We use `NEXT_RUNTIME` env var to DCE the JS fallback code in the `else` block
-    // possible values: "edge" | "nodejs" | undefined
-    if (process.env["NEXT_RUNTIME"] === "edge") {
-        const analyze = await init();
-        // We HAVE to have the WasmAPI in Edge
-        const fingerprint = analyze.fingerprint(ip);
-        return fingerprint;
+async function generateFingerprint(context, request) {
+    const { log } = context;
+    const coreImports = createCoreImports();
+    const analyze = await initializeWasm(coreImports);
+    if (typeof analyze !== "undefined") {
+        return analyze.generateFingerprint(JSON.stringify(request), context.characteristics);
     }
     else {
-        const analyze = await init();
-        if (typeof analyze !== "undefined") {
-            const fingerprint = analyze.fingerprint(ip);
-            return fingerprint;
-        }
-        else {
-            // Conditional import because it's not available in some runtimes, we know
-            // it is when running on Vercel serverless functions.
-            // TODO(#180): Avoid nodejs-specific import
-            const createHash = await import('crypto');
-            // Fingerprint v1 is just the IP address
-            const fingerprintRaw = `fp_1_${ip}`;
-            const fingerprint = createHash
-                .createHash("sha256")
-                .update(fingerprintRaw)
-                .digest("hex");
-            return fingerprint;
-        }
+        log.debug("WebAssembly is not supported in this runtime");
     }
+    return "";
 }
-async function isValidEmail(candidate, options) {
-    const analyze = await init();
+async function isValidEmail(context, candidate, options) {
+    const { log } = context;
+    const coreImports = createCoreImports();
+    const analyze = await initializeWasm(coreImports);
     if (typeof analyze !== "undefined") {
         return analyze.isValidEmail(candidate, options);
     }
     else {
-        // TODO: Fallback to JS if we don't have WASM?
-        return true;
+        log.debug("WebAssembly is not supported in this runtime");
+        // Skip the local evaluation of the rule if WASM is not available
+        return {
+            validity: "valid",
+            blocked: [],
+        };
     }
 }
-async function detectBot(headers, patterns_add, patterns_remove) {
-    const analyze = await init();
+async function detectBot(context, request, options) {
+    const { log } = context;
+    const coreImports = createCoreImports();
+    const analyze = await initializeWasm(coreImports);
     if (typeof analyze !== "undefined") {
-        return analyze.detectBot(headers, patterns_add, patterns_remove);
+        return analyze.detectBot(JSON.stringify(request), options);
     }
     else {
-        // TODO: Fallback to JS if we don't have WASM?
+        log.debug("WebAssembly is not supported in this runtime");
+        // Skip the local evaluation of the rule if Wasm is not available
         return {
-            bot_type: 1, // NOT_ANALYZED
-            bot_score: 0,
+            allowed: [],
+            denied: [],
+            spoofed: false,
+            verified: false,
         };
     }
 }
+async function detectSensitiveInfo(context, candidate, entities, contextWindowSize, detect) {
+    const { log } = context;
+    const coreImports = createCoreImports(detect);
+    const analyze = await initializeWasm(coreImports);
+    if (typeof analyze !== "undefined") {
+        const skipCustomDetect = typeof detect !== "function";
+        return analyze.detectSensitiveInfo(candidate, {
+            entities,
+            contextWindowSize,
+            skipCustomDetect,
+        });
+    }
+    else {
+        log.debug("WebAssembly is not supported in this runtime");
+        throw new Error("SENSITIVE_INFO rule failed to run because Wasm is not supported in this environment.");
+    }
+}
 
-export { detectBot, generateFingerprint, isValidEmail };
+export { detectBot, detectSensitiveInfo, generateFingerprint, isValidEmail };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcjet/analyze",
-  "version": "1.0.0-alpha.9",
+  "version": "1.0.0-beta.1",
   "description": "Arcjet local analysis engine",
   "license": "Apache-2.0",
   "homepage": "https://arcjet.com",
@@ -27,10 +27,10 @@
   "files": [
     "LICENSE",
     "README.md",
+    "_virtual/",
     "wasm/",
     "*.js",
     "*.d.ts",
-    "*.ts",
     "!*.config.js"
   ],
   "scripts": {
@@ -38,23 +38,21 @@
     "build": "rollup --config rollup.config.js",
     "lint": "eslint .",
     "pretest": "npm run build",
-    "test": "NODE_OPTIONS=--experimental-vm-modules jest --passWithNoTests"
+    "test": "node --test --experimental-test-coverage"
   },
-  "sideEffects": [
-    "./wasm/arcjet_analyze_js_req_bg.js"
-  ],
   "dependencies": {
-    "@arcjet/logger": "1.0.0-alpha.9"
+    "@arcjet/analyze-wasm": "1.0.0-beta.1",
+    "@arcjet/protocol": "1.0.0-beta.1"
   },
   "devDependencies": {
-    "@arcjet/eslint-config": "1.0.0-alpha.9",
-    "@arcjet/rollup-config": "1.0.0-alpha.9",
-    "@arcjet/tsconfig": "1.0.0-alpha.9",
-    "@jest/globals": "29.7.0",
-    "@rollup/wasm-node": "4.12.0",
+    "@arcjet/eslint-config": "1.0.0-beta.1",
+    "@arcjet/rollup-config": "1.0.0-beta.1",
+    "@arcjet/tsconfig": "1.0.0-beta.1",
+    "@bytecodealliance/jco": "1.5.0",
+    "@rollup/wasm-node": "4.30.1",
     "@types/node": "18.18.0",
-    "jest": "29.7.0",
-    "typescript": "5.3.3"
+    "expect": "29.7.0",
+    "typescript": "5.7.3"
   },
   "publishConfig": {
     "access": "public",

package/index.ts

@@ -1,165 +0,0 @@
-import initWasm, {
-  detect_bot,
-  generate_fingerprint,
-  is_valid_email,
-  type EmailValidationConfig,
-} from "./wasm/arcjet_analyze_js_req.js";
-
-export { type EmailValidationConfig };
-
-type WasmAPI = {
-  /**
-   * The WASM detect_bot function. Initialized by calling `init()`. Defined at a
-   * class level to avoid having to load the WASM module multiple times.
-   */
-  detectBot: typeof detect_bot;
-  /**
-   * The WASM fingerprint function. Initialized by calling `init()`. Defined at
-   * a class level to avoid having to load the WASM module multiple times.
-   */
-  fingerprint: typeof generate_fingerprint;
-  /**
-   * The WASM email validation function. Initialized by calling `init()`. Defined at
-   * a class level to avoid having to load the WASM module multiple times.
-   */
-  isValidEmail: typeof is_valid_email;
-};
-
-type WasmState = "initialized" | "uninitialized" | "unsupported" | "errored";
-
-let state: WasmState = "uninitialized";
-
-/**
- * Initialize the WASM module. This can be explicitly called after creating
- * the client, but it will be called automatically if it has not been called
- * when the first request is made. This uses a factory-style pattern because
- * the call must be async and the constructor cannot be async.
- */
-async function init(): Promise<WasmAPI | undefined> {
-  if (state === "errored" || state === "unsupported") return;
-
-  if (typeof WebAssembly === "undefined") {
-    state = "unsupported";
-    return;
-  }
-
-  if (state === "uninitialized") {
-    try {
-      let wasmModule: WebAssembly.Module;
-      // We use `NEXT_RUNTIME` env var to DCE the Node/Browser code in the `else` block
-      // possible values: "edge" | "nodejs" | undefined
-      if (process.env["NEXT_RUNTIME"] === "edge") {
-        const mod = await import(
-          // @ts-expect-error
-          "./wasm/arcjet_analyze_js_req_bg.wasm?module"
-        );
-        wasmModule = mod.default;
-      } else {
-        const { wasm } = await import("./wasm/arcjet.wasm.js");
-        wasmModule = await WebAssembly.compile(await wasm());
-      }
-
-      await initWasm(wasmModule);
-      state = "initialized";
-    } catch (err) {
-      state = "errored";
-      return;
-    }
-  }
-
-  return {
-    detectBot: detect_bot,
-    fingerprint: generate_fingerprint,
-    isValidEmail: is_valid_email,
-  };
-}
-
-/**
- * Generate a fingerprint for the client. This is used to identify the client
- * across multiple requests.
- * @param ip - The IP address of the client.
- * @returns A SHA-256 string fingerprint.
- */
-export async function generateFingerprint(ip: string): Promise<string> {
-  if (ip == "") {
-    return "";
-  }
-
-  // We use `NEXT_RUNTIME` env var to DCE the JS fallback code in the `else` block
-  // possible values: "edge" | "nodejs" | undefined
-  if (process.env["NEXT_RUNTIME"] === "edge") {
-    const analyze = await init();
-    // We HAVE to have the WasmAPI in Edge
-    const fingerprint = analyze!.fingerprint(ip);
-    return fingerprint;
-  } else {
-    const analyze = await init();
-    if (typeof analyze !== "undefined") {
-      const fingerprint = analyze.fingerprint(ip);
-      return fingerprint;
-    } else {
-      // Conditional import because it's not available in some runtimes, we know
-      // it is when running on Vercel serverless functions.
-      // TODO(#180): Avoid nodejs-specific import
-      const createHash = await import("crypto");
-
-      // Fingerprint v1 is just the IP address
-      const fingerprintRaw = `fp_1_${ip}`;
-
-      const fingerprint = createHash
-        .createHash("sha256")
-        .update(fingerprintRaw)
-        .digest("hex");
-      return fingerprint;
-    }
-  }
-}
-
-export async function isValidEmail(
-  candidate: string,
-  options?: EmailValidationConfig,
-) {
-  const analyze = await init();
-
-  if (typeof analyze !== "undefined") {
-    return analyze.isValidEmail(candidate, options);
-  } else {
-    // TODO: Fallback to JS if we don't have WASM?
-    return true;
-  }
-}
-
-/**
- * Represents the result of the bot detection.
- *
- * @property `bot_type` - What type of bot this is. This will be one of `BotType`.
- * @property `bot_score` - A score ranging from 0 to 99 representing the degree of
- * certainty. The higher the number within the type category, the greater the
- * degree of certainty. E.g. `BotType.Automated` with a score of 1 means we are
- * sure the request was made by an automated bot. `BotType.LikelyNotABot` with a
- * score of 30 means we don't think this request was a bot, but it's lowest
- * confidence level. `BotType.LikelyNotABot` with a score of 99 means we are
- * almost certain this request was not a bot.
- */
-export interface BotResult {
-  bot_type: number;
-  bot_score: number;
-}
-
-export async function detectBot(
-  headers: string,
-  patterns_add: string,
-  patterns_remove: string,
-): Promise<BotResult> {
-  const analyze = await init();
-
-  if (typeof analyze !== "undefined") {
-    return analyze.detectBot(headers, patterns_add, patterns_remove);
-  } else {
-    // TODO: Fallback to JS if we don't have WASM?
-    return {
-      bot_type: 1, // NOT_ANALYZED
-      bot_score: 0,
-    };
-  }
-}

package/wasm/arcjet.wasm.d.ts

@@ -1,31 +0,0 @@
-// @generated by wasm2module - DO NOT EDIT
-/* tslint:disable */
-/* eslint-disable */
-
-/**
- * This file contains the Arcjet Wasm binary inlined as a base64
- * [Data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs)
- * with the application/wasm MIME type.
- *
- * This was chosen to save on storage space over inlining the file directly as
- * a Uint8Array, which would take up ~3x the space of the Wasm file. See
- * https://blobfolio.com/2019/better-binary-batter-mixing-base64-and-uint8array/
- * for more details.
- *
- * It is then decoded into an ArrayBuffer to be used directly via WebAssembly's
- * `compile()` function in our entry point file.
- *
- * This is all done to avoid trying to read or bundle the Wasm asset in various
- * ways based on the platform or bundler a user is targeting. One example being
- * that Next.js requires special `asyncWebAssembly` webpack config to load our
- * Wasm file if we don't do this.
- *
- * In the future, we hope to do away with this workaround when all bundlers
- * properly support consistent asset bundling techniques.
- */
-
-/**
- * Returns an ArrayBuffer for the Arcjet Wasm binary, decoded from a base64 Data
- * URL.
- */
-export function wasm(): Promise<ArrayBuffer>;