@arcjet/analyze 1.0.0-beta.1 → 1.0.0-beta.11

package/README.md

@@ -22,37 +22,71 @@ against common attacks.
 
 This is the [Arcjet][arcjet] local analysis engine.
 
-## Installation
+- [npm package (`@arcjet/analyze`)](https://www.npmjs.com/package/@arcjet/analyze)
+- [GitHub source code (`analyze/` in `arcjet/arcjet-js`)](https://github.com/arcjet/arcjet-js/tree/main/analyze)
 
-```shell
-npm install -S @arcjet/analyze
-```
+## What is this?
 
-## Example
+This package provides functionality to analyze requests.
+The work is done in WebAssembly but is called here from JavaScript.
+The functionality is wrapped up into rules in our core package
+([`arcjet`][github-arcjet-arcjet]),
+in turn exposed from our adapters (such as `@arcjet/next`).
 
-```ts
-import { generateFingerprint, isValidEmail } from "@arcjet/analyze";
+<!-- TODO(@wooorm-arcjet): link `adapters` above when the main repo is up to date. -->
+
+The WebAssembly files are in
+[`@arcjet/analyze-wasm`][github-arcjet-analyze-wasm].
+They are separate because we need to change the import structure for each
+runtime that we support in the bindings.
+Separate packages lets us not duplicate code while providing a combined
+higher-level API for calling our core functionality.
+
+## When should I use this?
 
-const fingerprint = generateFingerprint("127.0.0.1");
-console.log("fingerprint: ", fingerprint);
+This is an internal Arcjet package not designed for public use.
+See our [_Get started_ guide][arcjet-get-started] for how to use Arcjet in your
+application.
 
-const valid = isValidEmail("hello@example.com");
-console.log("is email valid?", valid);
+## Install
+
+This package is ESM only.
+Install with npm in Node.js:
+
+```sh
+npm install @arcjet/analyze
 ```
 
-## Implementation
+## Use
 
-This package uses the Wasm bindings provided by `@arcjet/analyze-wasm` to
-call various functions that are exported by our wasm bindings.
+```js
+import { generateFingerprint, isValidEmail } from "@arcjet/analyze";
 
-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.
+const fingerprint = await generateFingerprint(
+  { characteristics: [] },
+  { ip: "127.0.0.1" },
+);
+console.log(fingerprint);
+// => "fp::2::0d219da6100b99f95cf639b77e088c6df3c096aa5fd61dec5287c5cf94d5e545"
+
+const result = await isValidEmail({}, "hello@example.com", {
+  tag: "allow-email-validation-config",
+  val: {
+    allowDomainLiteral: false,
+    allow: [],
+    requireTopLevelDomain: true,
+  },
+});
+console.log(result);
+// => { blocked: [], validity: "valid" }
+```
 
 ## License
 
-Licensed under the [Apache License, Version 2.0][apache-license].
+[Apache License, Version 2.0][apache-license] © [Arcjet Labs, Inc.][arcjet]
 
 [arcjet]: https://arcjet.com
+[arcjet-get-started]: https://docs.arcjet.com/get-started
 [apache-license]: http://www.apache.org/licenses/LICENSE-2.0
+[github-arcjet-analyze-wasm]: https://github.com/arcjet/arcjet-js/tree/main/analyze-wasm
+[github-arcjet-arcjet]: https://github.com/arcjet/arcjet-js/tree/main/arcjet

package/index.d.ts

@@ -1,4 +1,4 @@
-import type { BotConfig, BotResult, DetectedSensitiveInfoEntity, DetectSensitiveInfoFunction, EmailValidationConfig, EmailValidationResult, SensitiveInfoEntities, SensitiveInfoEntity, SensitiveInfoResult } from "@arcjet/analyze-wasm";
+import type { BotConfig, BotResult, DetectedSensitiveInfoEntity, DetectSensitiveInfoFunction, EmailValidationConfig, EmailValidationResult, FilterResult, SensitiveInfoEntities, SensitiveInfoEntity, SensitiveInfoResult } from "@arcjet/analyze-wasm";
 import type { ArcjetLogger } from "@arcjet/protocol";
 interface AnalyzeContext {
     log: ArcjetLogger;
@@ -15,15 +15,81 @@ type AnalyzeRequest = {
     query?: string;
     extra?: Record<string, string>;
 };
-export { type EmailValidationConfig, type BotConfig, type SensitiveInfoEntity, type DetectedSensitiveInfoEntity, };
+export { type EmailValidationConfig, type BotConfig, type FilterResult, type SensitiveInfoEntity, type DetectedSensitiveInfoEntity, };
 /**
- * Generate a fingerprint for the client. This is used to identify the client
- * across multiple requests.
- * @param context - The Arcjet Analyze context.
- * @param request - The request to fingerprint.
- * @returns A SHA-256 string fingerprint.
+ * Generate a fingerprint.
+ *
+ * Fingerprints can be used to identify the client across multiple requests.
+ *
+ * This considers different things on the `request` based on the passed
+ * `context.characteristics`.
+ *
+ * See [*Fingerprints* on
+ * `docs.arcjet.com`](https://docs.arcjet.com/fingerprints/) for more info.
+ *
+ * @param context
+ *   Context.
+ * @param request
+ *   Request.
+ * @returns
+ *   Promise for a SHA-256 fingerprint.
  */
 export declare function generateFingerprint(context: AnalyzeContext, request: AnalyzeRequest): Promise<string>;
-export declare function isValidEmail(context: AnalyzeContext, candidate: string, options: EmailValidationConfig): Promise<EmailValidationResult>;
+/**
+ * Check whether an email is valid.
+ *
+ * @param context
+ *   Context.
+ * @param value
+ *   Value.
+ * @param options
+ *   Configuration.
+ * @returns
+ *   Promise for a result.
+ */
+export declare function isValidEmail(context: AnalyzeContext, value: string, options: EmailValidationConfig): Promise<EmailValidationResult>;
+/**
+ * Detect whether a request is by a bot.
+ *
+ * @param context
+ *   Context.
+ * @param request
+ *   Request.
+ * @param options
+ *   Configuration.
+ * @returns
+ *   Promise for a result.
+ */
 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>;
+/**
+ * Detect sensitive info in a value.
+ *
+ * @param context
+ *   Context.
+ * @param value
+ *   Value.
+ * @param entities
+ *   Strategy to use for detecting sensitive info;
+ *   either by denying everything and allowing certain tags or by allowing
+ *   everything and denying certain tags.
+ * @param contextWindowSize
+ *   Number of tokens to pass to `detect`.
+ * @param detect
+ *   Function to detect sensitive info (optional).
+ * @returns
+ *   Promise for a result.
+ */
+export declare function detectSensitiveInfo(context: AnalyzeContext, value: string, entities: SensitiveInfoEntities, contextWindowSize: number, detect?: DetectSensitiveInfoFunction): Promise<SensitiveInfoResult>;
+/**
+ * Check if a filter matches a request.
+ *
+ * @param context
+ *   Arcjet context.
+ * @param request
+ *   Request.
+ * @param expressions
+ *   Filter expressions.
+ * @returns
+ *   Promise to whether the filter matches the request.
+ */
+export declare function matchFilters(context: AnalyzeContext, request: AnalyzeRequest, expressions: ReadonlyArray<string>, allowIfMatch: boolean): Promise<FilterResult>;

package/index.js

@@ -7,14 +7,20 @@ const FREE_EMAIL_PROVIDERS = [
     "aol.com",
     "hotmail.co.uk",
 ];
-function noOpDetect() {
+function noOpSensitiveInfoDetect() {
+    return [];
+}
+function noOpBotsDetect() {
     return [];
 }
 function createCoreImports(detect) {
     if (typeof detect !== "function") {
-        detect = noOpDetect;
+        detect = noOpSensitiveInfoDetect;
     }
     return {
+        "arcjet:js-req/bot-identifier": {
+            detect: noOpBotsDetect,
+        },
         "arcjet:js-req/email-validator-overrides": {
             isFreeEmail(domain) {
                 if (FREE_EMAIL_PROVIDERS.includes(domain)) {
@@ -32,9 +38,11 @@ function createCoreImports(detect) {
                 return "unknown";
             },
         },
+        // TODO(@wooorm-arcjet): figure out a test case for this with the default `detect`.
         "arcjet:js-req/sensitive-information-identifier": {
             detect,
         },
+        // TODO(@wooorm-arcjet): figure out a test case for this that calls `verify`.
         "arcjet:js-req/verify-bot": {
             verify() {
                 return "unverifiable";
@@ -43,11 +51,22 @@ function createCoreImports(detect) {
     };
 }
 /**
- * Generate a fingerprint for the client. This is used to identify the client
- * across multiple requests.
- * @param context - The Arcjet Analyze context.
- * @param request - The request to fingerprint.
- * @returns A SHA-256 string fingerprint.
+ * Generate a fingerprint.
+ *
+ * Fingerprints can be used to identify the client across multiple requests.
+ *
+ * This considers different things on the `request` based on the passed
+ * `context.characteristics`.
+ *
+ * See [*Fingerprints* on
+ * `docs.arcjet.com`](https://docs.arcjet.com/fingerprints/) for more info.
+ *
+ * @param context
+ *   Context.
+ * @param request
+ *   Request.
+ * @returns
+ *   Promise for a SHA-256 fingerprint.
  */
 async function generateFingerprint(context, request) {
     const { log } = context;
@@ -55,62 +74,119 @@ async function generateFingerprint(context, request) {
     const analyze = await initializeWasm(coreImports);
     if (typeof analyze !== "undefined") {
         return analyze.generateFingerprint(JSON.stringify(request), context.characteristics);
+        // Ignore the `else` branch as we test in places that have WebAssembly.
+        /* node:coverage ignore next 4 */
     }
-    else {
-        log.debug("WebAssembly is not supported in this runtime");
-    }
+    log.debug("WebAssembly is not supported in this runtime");
     return "";
 }
-async function isValidEmail(context, candidate, options) {
+/**
+ * Check whether an email is valid.
+ *
+ * @param context
+ *   Context.
+ * @param value
+ *   Value.
+ * @param options
+ *   Configuration.
+ * @returns
+ *   Promise for a result.
+ */
+async function isValidEmail(context, value, options) {
     const { log } = context;
     const coreImports = createCoreImports();
     const analyze = await initializeWasm(coreImports);
     if (typeof analyze !== "undefined") {
-        return analyze.isValidEmail(candidate, options);
-    }
-    else {
-        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: [],
-        };
+        return analyze.isValidEmail(value, options);
+        // Ignore the `else` branch as we test in places that have WebAssembly.
+        /* node:coverage ignore next 4 */
     }
+    log.debug("WebAssembly is not supported in this runtime");
+    return { blocked: [], validity: "valid" };
 }
+/**
+ * Detect whether a request is by a bot.
+ *
+ * @param context
+ *   Context.
+ * @param request
+ *   Request.
+ * @param options
+ *   Configuration.
+ * @returns
+ *   Promise for a result.
+ */
 async function detectBot(context, request, options) {
     const { log } = context;
     const coreImports = createCoreImports();
     const analyze = await initializeWasm(coreImports);
     if (typeof analyze !== "undefined") {
         return analyze.detectBot(JSON.stringify(request), options);
+        // Ignore the `else` branch as we test in places that have WebAssembly.
+        /* node:coverage ignore next 4 */
     }
-    else {
-        log.debug("WebAssembly is not supported in this runtime");
-        // Skip the local evaluation of the rule if Wasm is not available
-        return {
-            allowed: [],
-            denied: [],
-            spoofed: false,
-            verified: false,
-        };
-    }
+    log.debug("WebAssembly is not supported in this runtime");
+    return { allowed: [], denied: [], spoofed: false, verified: false };
 }
-async function detectSensitiveInfo(context, candidate, entities, contextWindowSize, detect) {
+/**
+ * Detect sensitive info in a value.
+ *
+ * @param context
+ *   Context.
+ * @param value
+ *   Value.
+ * @param entities
+ *   Strategy to use for detecting sensitive info;
+ *   either by denying everything and allowing certain tags or by allowing
+ *   everything and denying certain tags.
+ * @param contextWindowSize
+ *   Number of tokens to pass to `detect`.
+ * @param detect
+ *   Function to detect sensitive info (optional).
+ * @returns
+ *   Promise for a result.
+ */
+async function detectSensitiveInfo(context, value, 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, {
+        return analyze.detectSensitiveInfo(value, {
             entities,
             contextWindowSize,
             skipCustomDetect,
         });
+        // Ignore the `else` branch as we test in places that have WebAssembly.
+        /* node:coverage ignore next 4 */
     }
-    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.");
+    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.");
+}
+/**
+ * Check if a filter matches a request.
+ *
+ * @param context
+ *   Arcjet context.
+ * @param request
+ *   Request.
+ * @param expressions
+ *   Filter expressions.
+ * @returns
+ *   Promise to whether the filter matches the request.
+ */
+async function matchFilters(context, request, expressions, allowIfMatch) {
+    const coreImports = createCoreImports();
+    const analyze = await initializeWasm(coreImports);
+    if (typeof analyze !== "undefined") {
+        return analyze.matchFilters(JSON.stringify(request), 
+        // @ts-expect-error: WebAssembly does not support readonly values.
+        expressions, allowIfMatch);
+        // Ignore the `else` branch as we test in places that have WebAssembly.
+        /* node:coverage ignore next 4 */
     }
+    context.log.debug("WebAssembly is not supported in this runtime");
+    throw new Error("FILTER rule failed to run because Wasm is not supported in this environment.");
 }
 
-export { detectBot, detectSensitiveInfo, generateFingerprint, isValidEmail };
+export { detectBot, detectSensitiveInfo, generateFingerprint, isValidEmail, matchFilters };

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "@arcjet/analyze",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.11",
   "description": "Arcjet local analysis engine",
+  "keywords": [
+    "analyze",
+    "arcjet",
+    "attack",
+    "limit",
+    "protect",
+    "verify"
+  ],
   "license": "Apache-2.0",
   "homepage": "https://arcjet.com",
   "repository": {
@@ -25,34 +33,29 @@
   "main": "./index.js",
   "types": "./index.d.ts",
   "files": [
-    "LICENSE",
-    "README.md",
-    "_virtual/",
-    "wasm/",
-    "*.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-api": "node --test",
+    "test-coverage": "node --experimental-test-coverage --test",
+    "test": "npm run build && npm run lint && npm run test-coverage"
   },
   "dependencies": {
-    "@arcjet/analyze-wasm": "1.0.0-beta.1",
-    "@arcjet/protocol": "1.0.0-beta.1"
+    "@arcjet/analyze-wasm": "1.0.0-beta.11",
+    "@arcjet/protocol": "1.0.0-beta.11"
   },
   "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.11",
+    "@arcjet/rollup-config": "1.0.0-beta.11",
     "@bytecodealliance/jco": "1.5.0",
-    "@rollup/wasm-node": "4.30.1",
-    "@types/node": "18.18.0",
-    "expect": "29.7.0",
-    "typescript": "5.7.3"
+    "@rollup/wasm-node": "4.50.0",
+    "@types/node": "24.3.0",
+    "eslint": "9.34.0",
+    "typescript": "5.9.2"
   },
   "publishConfig": {
     "access": "public",