@arcjet/analyze 1.0.0-beta.9 → 1.0.0

package/README.md

@@ -25,43 +25,67 @@ This is the [Arcjet][arcjet] local analysis engine.
 - [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)
 
-## Installation
+## What is this?
 
-```shell
-npm install -S @arcjet/analyze
-```
+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 [SDKs][github-arcjet-sdks] (such as `@arcjet/next`).
 
-## Example
+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.
 
-<!--
-  TODO(@wooorm-arcjet): I think this example is out of date?
-  Either remove it if we don’t want people to use this.
-  Or, change the API to allow simpler use?
--->
+## When should I use this?
 
-```ts
-import { generateFingerprint, isValidEmail } from "@arcjet/analyze";
+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.
+
+## Install
 
-const fingerprint = generateFingerprint("127.0.0.1");
-console.log("fingerprint: ", fingerprint);
+This package is ESM only.
+Install with npm in Node.js:
 
-const valid = isValidEmail("hello@example.com");
-console.log("is email valid?", valid);
+```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
+[github-arcjet-sdks]: https://github.com/arcjet/arcjet-js#sdks

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

@@ -38,6 +38,11 @@ function createCoreImports(detect) {
                 return "unknown";
             },
         },
+        "arcjet:js-req/filter-overrides": {
+            ipLookup() {
+                return undefined;
+            },
+        },
         // TODO(@wooorm-arcjet): figure out a test case for this with the default `detect`.
         "arcjet:js-req/sensitive-information-identifier": {
             detect,
@@ -50,13 +55,23 @@ function createCoreImports(detect) {
         },
     };
 }
-// TODO(@wooorm-arcjet): document what is used to fingerprint.
 /**
- * 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;
@@ -70,20 +85,42 @@ async function generateFingerprint(context, request) {
     log.debug("WebAssembly is not supported in this runtime");
     return "";
 }
-// TODO(@wooorm-arcjet): docs.
-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);
+        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" };
 }
-// TODO(@wooorm-arcjet): docs.
+/**
+ * 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();
@@ -96,14 +133,31 @@ async function detectBot(context, request, options) {
     log.debug("WebAssembly is not supported in this runtime");
     return { allowed: [], denied: [], spoofed: false, verified: false };
 }
-// TODO(@wooorm-arcjet): docs.
-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,
@@ -114,5 +168,30 @@ async function detectSensitiveInfo(context, candidate, entities, contextWindowSi
     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,6 +1,6 @@
 {
   "name": "@arcjet/analyze",
-  "version": "1.0.0-beta.9",
+  "version": "1.0.0",
   "description": "Arcjet local analysis engine",
   "keywords": [
     "analyze",
@@ -27,7 +27,7 @@
     "url": "https://arcjet.com"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "type": "module",
   "main": "./index.js",
@@ -40,23 +40,22 @@
     "build": "rollup --config rollup.config.js",
     "lint": "eslint .",
     "prepublishOnly": "npm run build",
-    "test-api": "node --test",
-    "test-coverage": "node --experimental-test-coverage --test",
+    "test-api": "node --test -- test/*.test.js",
+    "test-coverage": "node --experimental-test-coverage --test -- test/*.test.js",
     "test": "npm run build && npm run lint && npm run test-coverage"
   },
   "dependencies": {
-    "@arcjet/analyze-wasm": "1.0.0-beta.9",
-    "@arcjet/protocol": "1.0.0-beta.9"
+    "@arcjet/analyze-wasm": "1.0.0",
+    "@arcjet/protocol": "1.0.0"
   },
   "devDependencies": {
-    "@arcjet/eslint-config": "1.0.0-beta.9",
-    "@arcjet/rollup-config": "1.0.0-beta.9",
-    "@arcjet/tsconfig": "1.0.0-beta.9",
+    "@arcjet/eslint-config": "1.0.0",
+    "@arcjet/rollup-config": "1.0.0",
     "@bytecodealliance/jco": "1.5.0",
-    "@rollup/wasm-node": "4.44.2",
-    "@types/node": "18.18.0",
-    "eslint": "9.30.1",
-    "typescript": "5.8.3"
+    "@rollup/wasm-node": "4.55.1",
+    "@types/node": "25.0.8",
+    "eslint": "9.39.2",
+    "typescript": "5.9.3"
   },
   "publishConfig": {
     "access": "public",