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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +53 -19
  2. package/index.js +29 -27
  3. package/package.json +23 -19
package/README.md CHANGED
@@ -22,37 +22,71 @@ against common attacks.
22
22
 
23
23
  This is the [Arcjet][arcjet] local analysis engine.
24
24
 
25
- ## Installation
25
+ - [npm package (`@arcjet/analyze`)](https://www.npmjs.com/package/@arcjet/analyze)
26
+ - [GitHub source code (`analyze/` in `arcjet/arcjet-js`)](https://github.com/arcjet/arcjet-js/tree/main/analyze)
26
27
 
27
- ```shell
28
- npm install -S @arcjet/analyze
29
- ```
28
+ ## What is this?
30
29
 
31
- ## Example
30
+ This package provides functionality to analyze requests.
31
+ The work is done in WebAssembly but is called here from JavaScript.
32
+ The functionality is wrapped up into rules in our core package
33
+ ([`arcjet`][github-arcjet-arcjet]),
34
+ in turn exposed from our adapters (such as `@arcjet/next`).
32
35
 
33
- ```ts
34
- import { generateFingerprint, isValidEmail } from "@arcjet/analyze";
36
+ <!-- TODO(@wooorm-arcjet): link `adapters` above when the main repo is up to date. -->
37
+
38
+ The WebAssembly files are in
39
+ [`@arcjet/analyze-wasm`][github-arcjet-analyze-wasm].
40
+ They are separate because we need to change the import structure for each
41
+ runtime that we support in the bindings.
42
+ Separate packages lets us not duplicate code while providing a combined
43
+ higher-level API for calling our core functionality.
44
+
45
+ ## When should I use this?
35
46
 
36
- const fingerprint = generateFingerprint("127.0.0.1");
37
- console.log("fingerprint: ", fingerprint);
47
+ This is an internal Arcjet package not designed for public use.
48
+ See our [_Get started_ guide][arcjet-get-started] for how to use Arcjet in your
49
+ application.
38
50
 
39
- const valid = isValidEmail("hello@example.com");
40
- console.log("is email valid?", valid);
51
+ ## Install
52
+
53
+ This package is ESM only.
54
+ Install with npm in Node.js:
55
+
56
+ ```sh
57
+ npm install @arcjet/analyze
41
58
  ```
42
59
 
43
- ## Implementation
60
+ ## Use
44
61
 
45
- This package uses the Wasm bindings provided by `@arcjet/analyze-wasm` to
46
- call various functions that are exported by our wasm bindings.
62
+ ```js
63
+ import { generateFingerprint, isValidEmail } from "@arcjet/analyze";
47
64
 
48
- We chose to put this logic in a separate package because we need to change the
49
- import structure for each runtime that we support in the wasm bindings. Moving
50
- this to a separate package allows us not to have to duplicate code while providing
51
- a combined higher-level api for calling our core functionality in Wasm.
65
+ const fingerprint = await generateFingerprint(
66
+ { characteristics: [] },
67
+ { ip: "127.0.0.1" },
68
+ );
69
+ console.log(fingerprint);
70
+ // => "fp::2::0d219da6100b99f95cf639b77e088c6df3c096aa5fd61dec5287c5cf94d5e545"
71
+
72
+ const result = await isValidEmail({}, "hello@example.com", {
73
+ tag: "allow-email-validation-config",
74
+ val: {
75
+ allowDomainLiteral: false,
76
+ allow: [],
77
+ requireTopLevelDomain: true,
78
+ },
79
+ });
80
+ console.log(result);
81
+ // => { blocked: [], validity: "valid" }
82
+ ```
52
83
 
53
84
  ## License
54
85
 
55
- Licensed under the [Apache License, Version 2.0][apache-license].
86
+ [Apache License, Version 2.0][apache-license] © [Arcjet Labs, Inc.][arcjet]
56
87
 
57
88
  [arcjet]: https://arcjet.com
89
+ [arcjet-get-started]: https://docs.arcjet.com/get-started
58
90
  [apache-license]: http://www.apache.org/licenses/LICENSE-2.0
91
+ [github-arcjet-analyze-wasm]: https://github.com/arcjet/arcjet-js/tree/main/analyze-wasm
92
+ [github-arcjet-arcjet]: https://github.com/arcjet/arcjet-js/tree/main/arcjet
package/index.js CHANGED
@@ -7,14 +7,20 @@ const FREE_EMAIL_PROVIDERS = [
7
7
  "aol.com",
8
8
  "hotmail.co.uk",
9
9
  ];
10
- function noOpDetect() {
10
+ function noOpSensitiveInfoDetect() {
11
+ return [];
12
+ }
13
+ function noOpBotsDetect() {
11
14
  return [];
12
15
  }
13
16
  function createCoreImports(detect) {
14
17
  if (typeof detect !== "function") {
15
- detect = noOpDetect;
18
+ detect = noOpSensitiveInfoDetect;
16
19
  }
17
20
  return {
21
+ "arcjet:js-req/bot-identifier": {
22
+ detect: noOpBotsDetect,
23
+ },
18
24
  "arcjet:js-req/email-validator-overrides": {
19
25
  isFreeEmail(domain) {
20
26
  if (FREE_EMAIL_PROVIDERS.includes(domain)) {
@@ -32,9 +38,11 @@ function createCoreImports(detect) {
32
38
  return "unknown";
33
39
  },
34
40
  },
41
+ // TODO(@wooorm-arcjet): figure out a test case for this with the default `detect`.
35
42
  "arcjet:js-req/sensitive-information-identifier": {
36
43
  detect,
37
44
  },
45
+ // TODO(@wooorm-arcjet): figure out a test case for this that calls `verify`.
38
46
  "arcjet:js-req/verify-bot": {
39
47
  verify() {
40
48
  return "unverifiable";
@@ -42,6 +50,7 @@ function createCoreImports(detect) {
42
50
  },
43
51
  };
44
52
  }
53
+ // TODO(@wooorm-arcjet): document what is used to fingerprint.
45
54
  /**
46
55
  * Generate a fingerprint for the client. This is used to identify the client
47
56
  * across multiple requests.
@@ -55,46 +64,39 @@ async function generateFingerprint(context, request) {
55
64
  const analyze = await initializeWasm(coreImports);
56
65
  if (typeof analyze !== "undefined") {
57
66
  return analyze.generateFingerprint(JSON.stringify(request), context.characteristics);
67
+ // Ignore the `else` branch as we test in places that have WebAssembly.
68
+ /* node:coverage ignore next 4 */
58
69
  }
59
- else {
60
- log.debug("WebAssembly is not supported in this runtime");
61
- }
70
+ log.debug("WebAssembly is not supported in this runtime");
62
71
  return "";
63
72
  }
73
+ // TODO(@wooorm-arcjet): docs.
64
74
  async function isValidEmail(context, candidate, options) {
65
75
  const { log } = context;
66
76
  const coreImports = createCoreImports();
67
77
  const analyze = await initializeWasm(coreImports);
68
78
  if (typeof analyze !== "undefined") {
69
79
  return analyze.isValidEmail(candidate, options);
80
+ // Ignore the `else` branch as we test in places that have WebAssembly.
81
+ /* node:coverage ignore next 4 */
70
82
  }
71
- else {
72
- log.debug("WebAssembly is not supported in this runtime");
73
- // Skip the local evaluation of the rule if WASM is not available
74
- return {
75
- validity: "valid",
76
- blocked: [],
77
- };
78
- }
83
+ log.debug("WebAssembly is not supported in this runtime");
84
+ return { blocked: [], validity: "valid" };
79
85
  }
86
+ // TODO(@wooorm-arcjet): docs.
80
87
  async function detectBot(context, request, options) {
81
88
  const { log } = context;
82
89
  const coreImports = createCoreImports();
83
90
  const analyze = await initializeWasm(coreImports);
84
91
  if (typeof analyze !== "undefined") {
85
92
  return analyze.detectBot(JSON.stringify(request), options);
93
+ // Ignore the `else` branch as we test in places that have WebAssembly.
94
+ /* node:coverage ignore next 4 */
86
95
  }
87
- else {
88
- log.debug("WebAssembly is not supported in this runtime");
89
- // Skip the local evaluation of the rule if Wasm is not available
90
- return {
91
- allowed: [],
92
- denied: [],
93
- spoofed: false,
94
- verified: false,
95
- };
96
- }
96
+ log.debug("WebAssembly is not supported in this runtime");
97
+ return { allowed: [], denied: [], spoofed: false, verified: false };
97
98
  }
99
+ // TODO(@wooorm-arcjet): docs.
98
100
  async function detectSensitiveInfo(context, candidate, entities, contextWindowSize, detect) {
99
101
  const { log } = context;
100
102
  const coreImports = createCoreImports(detect);
@@ -106,11 +108,11 @@ async function detectSensitiveInfo(context, candidate, entities, contextWindowSi
106
108
  contextWindowSize,
107
109
  skipCustomDetect,
108
110
  });
111
+ // Ignore the `else` branch as we test in places that have WebAssembly.
112
+ /* node:coverage ignore next 4 */
109
113
  }
110
- else {
111
- log.debug("WebAssembly is not supported in this runtime");
112
- throw new Error("SENSITIVE_INFO rule failed to run because Wasm is not supported in this environment.");
113
- }
114
+ log.debug("WebAssembly is not supported in this runtime");
115
+ throw new Error("SENSITIVE_INFO rule failed to run because Wasm is not supported in this environment.");
114
116
  }
115
117
 
116
118
  export { detectBot, detectSensitiveInfo, generateFingerprint, isValidEmail };
package/package.json CHANGED
@@ -1,7 +1,15 @@
1
1
  {
2
2
  "name": "@arcjet/analyze",
3
- "version": "1.0.0-beta.1",
3
+ "version": "1.0.0-beta.10",
4
4
  "description": "Arcjet local analysis engine",
5
+ "keywords": [
6
+ "analyze",
7
+ "arcjet",
8
+ "attack",
9
+ "limit",
10
+ "protect",
11
+ "verify"
12
+ ],
5
13
  "license": "Apache-2.0",
6
14
  "homepage": "https://arcjet.com",
7
15
  "repository": {
@@ -25,34 +33,30 @@
25
33
  "main": "./index.js",
26
34
  "types": "./index.d.ts",
27
35
  "files": [
28
- "LICENSE",
29
- "README.md",
30
- "_virtual/",
31
- "wasm/",
32
- "*.js",
33
- "*.d.ts",
34
- "!*.config.js"
36
+ "index.d.ts",
37
+ "index.js"
35
38
  ],
36
39
  "scripts": {
37
- "prepublishOnly": "npm run build",
38
40
  "build": "rollup --config rollup.config.js",
39
41
  "lint": "eslint .",
40
- "pretest": "npm run build",
41
- "test": "node --test --experimental-test-coverage"
42
+ "prepublishOnly": "npm run build",
43
+ "test-api": "node --test",
44
+ "test-coverage": "node --experimental-test-coverage --test",
45
+ "test": "npm run build && npm run lint && npm run test-coverage"
42
46
  },
43
47
  "dependencies": {
44
- "@arcjet/analyze-wasm": "1.0.0-beta.1",
45
- "@arcjet/protocol": "1.0.0-beta.1"
48
+ "@arcjet/analyze-wasm": "1.0.0-beta.10",
49
+ "@arcjet/protocol": "1.0.0-beta.10"
46
50
  },
47
51
  "devDependencies": {
48
- "@arcjet/eslint-config": "1.0.0-beta.1",
49
- "@arcjet/rollup-config": "1.0.0-beta.1",
50
- "@arcjet/tsconfig": "1.0.0-beta.1",
52
+ "@arcjet/eslint-config": "1.0.0-beta.10",
53
+ "@arcjet/rollup-config": "1.0.0-beta.10",
54
+ "@arcjet/tsconfig": "1.0.0-beta.10",
51
55
  "@bytecodealliance/jco": "1.5.0",
52
- "@rollup/wasm-node": "4.30.1",
56
+ "@rollup/wasm-node": "4.46.2",
53
57
  "@types/node": "18.18.0",
54
- "expect": "29.7.0",
55
- "typescript": "5.7.3"
58
+ "eslint": "9.32.0",
59
+ "typescript": "5.9.2"
56
60
  },
57
61
  "publishConfig": {
58
62
  "access": "public",