From 627329633c1a4eb764cdb2ef61bcd58ce1cd016b Mon Sep 17 00:00:00 2001 From: blaine-arcjet <146491715+blaine-arcjet@users.noreply.github.com> Date: Mon, 4 Mar 2024 10:37:33 -0700 Subject: [PATCH] feat: Implement initial nodejs SDK (#268) This is an initial version of the Arcjet SDK for Node.js, which drastically smooths the process of using Arcjet with a simple Node server. It implements much of the same logic as the Next SDK, but pulls data exclusively from a Node.js `IncomingMessage` type. I've not implemented `createMiddleware` or `withArcjet` because they need addition considerations, for which I opened #267. Closes #49 Draft because we need a bunch of docs that I've linked to in the README that don't exist. --- .github/.release-please-manifest.json | 1 + .github/dependabot.yml | 22 +++ .github/release-please-config.json | 6 + arcjet-node/.eslintignore | 6 + arcjet-node/.eslintrc.cjs | 4 + arcjet-node/.gitignore | 135 +++++++++++++++ arcjet-node/LICENSE | 201 ++++++++++++++++++++++ arcjet-node/README.md | 123 ++++++++++++++ arcjet-node/index.ts | 235 ++++++++++++++++++++++++++ arcjet-node/jest.config.js | 16 ++ arcjet-node/package.json | 61 +++++++ arcjet-node/rollup.config.js | 3 + arcjet-node/tsconfig.json | 4 + examples/nodejs-rl/.env.local.example | 1 + examples/nodejs-rl/README.md | 36 ++++ examples/nodejs-rl/index.js | 34 ++++ examples/nodejs-rl/package-lock.json | 96 +++++++++++ examples/nodejs-rl/package.json | 14 ++ examples/nodejs-rl/tsconfig.json | 8 + package-lock.json | 61 ++++++- 20 files changed, 1066 insertions(+), 1 deletion(-) create mode 100644 arcjet-node/.eslintignore create mode 100644 arcjet-node/.eslintrc.cjs create mode 100644 arcjet-node/.gitignore create mode 100644 arcjet-node/LICENSE create mode 100644 arcjet-node/README.md create mode 100644 arcjet-node/index.ts create mode 100644 arcjet-node/jest.config.js create mode 100644 arcjet-node/package.json create mode 100644 arcjet-node/rollup.config.js create mode 100644 arcjet-node/tsconfig.json create mode 100644 examples/nodejs-rl/.env.local.example create mode 100644 examples/nodejs-rl/README.md create mode 100644 examples/nodejs-rl/index.js create mode 100644 examples/nodejs-rl/package-lock.json create mode 100644 examples/nodejs-rl/package.json create mode 100644 examples/nodejs-rl/tsconfig.json diff --git a/.github/.release-please-manifest.json b/.github/.release-please-manifest.json index a0400e70d..52a7484ea 100644 --- a/.github/.release-please-manifest.json +++ b/.github/.release-please-manifest.json @@ -3,6 +3,7 @@ "analyze": "1.0.0-alpha.8", "arcjet": "1.0.0-alpha.8", "arcjet-next": "1.0.0-alpha.8", + "arcjet-node": "1.0.0-alpha.8", "decorate": "1.0.0-alpha.8", "duration": "1.0.0-alpha.8", "eslint-config": "1.0.0-alpha.8", diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 645b3a004..25bf85e8c 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -131,3 +131,25 @@ updates: # Headers in DOM. - dependency-name: "@types/node" versions: [">18.18"] + + - package-ecosystem: npm + directory: /examples/node-rl + schedule: + # Our dependencies should be checked daily + interval: daily + assignees: + - blaine-arcjet + reviewers: + - blaine-arcjet + commit-message: + prefix: deps(example) + prefix-development: deps(example) + groups: + dependencies: + patterns: + - "*" + ignore: + # Ignore updates to the @types/node package due to conflict between + # Headers in DOM. + - dependency-name: "@types/node" + versions: [">18.18"] diff --git a/.github/release-please-config.json b/.github/release-please-config.json index e204e6631..cebeef677 100644 --- a/.github/release-please-config.json +++ b/.github/release-please-config.json @@ -41,6 +41,10 @@ "component": "@arcjet/next", "skip-github-release": true }, + "arcjet-node": { + "component": "@arcjet/node", + "skip-github-release": true + }, "decorate": { "component": "@arcjet/decorate", "skip-github-release": true @@ -87,6 +91,8 @@ "@arcjet/analyze", "arcjet", "@arjcet/next", + "@arjcet/node", + "@arjcet/decorate", "@arjcet/duration", "@arcjet/eslint-config", "@arcjet/ip", diff --git a/arcjet-node/.eslintignore b/arcjet-node/.eslintignore new file mode 100644 index 000000000..9cfa2cae7 --- /dev/null +++ b/arcjet-node/.eslintignore @@ -0,0 +1,6 @@ +/.turbo/ +/coverage/ +/node_modules/ +*.d.ts +*.js +!*.config.js diff --git a/arcjet-node/.eslintrc.cjs b/arcjet-node/.eslintrc.cjs new file mode 100644 index 000000000..abe4cd7b4 --- /dev/null +++ b/arcjet-node/.eslintrc.cjs @@ -0,0 +1,4 @@ +module.exports = { + root: true, + extends: ["@arcjet/eslint-config"], +}; diff --git a/arcjet-node/.gitignore b/arcjet-node/.gitignore new file mode 100644 index 000000000..35b162da3 --- /dev/null +++ b/arcjet-node/.gitignore @@ -0,0 +1,135 @@ +# Logs +logs +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* +lerna-debug.log* +.pnpm-debug.log* + +# Diagnostic reports (https://nodejs.org/api/report.html) +report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json + +# Runtime data +pids +*.pid +*.seed +*.pid.lock + +# Directory for instrumented libs generated by jscoverage/JSCover +lib-cov + +# Coverage directory used by tools like istanbul +coverage +*.lcov + +# nyc test coverage +.nyc_output + +# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files) +.grunt + +# Bower dependency directory (https://bower.io/) +bower_components + +# node-waf configuration +.lock-wscript + +# Compiled binary addons (https://nodejs.org/api/addons.html) +build/Release + +# Dependency directories +node_modules/ +jspm_packages/ + +# Snowpack dependency directory (https://snowpack.dev/) +web_modules/ + +# TypeScript cache +*.tsbuildinfo + +# Optional npm cache directory +.npm + +# Optional eslint cache +.eslintcache + +# Optional stylelint cache +.stylelintcache + +# Microbundle cache +.rpt2_cache/ +.rts2_cache_cjs/ +.rts2_cache_es/ +.rts2_cache_umd/ + +# Optional REPL history +.node_repl_history + +# Output of 'npm pack' +*.tgz + +# Yarn Integrity file +.yarn-integrity + +# dotenv environment variable files +.env +.env.development.local +.env.test.local +.env.production.local +.env.local + +# parcel-bundler cache (https://parceljs.org/) +.cache +.parcel-cache + +# Next.js build output +.next +out + +# Nuxt.js build / generate output +.nuxt +dist + +# Gatsby files +.cache/ +# Comment in the public line in if your project uses Gatsby and not Next.js +# https://nextjs.org/blog/next-9-1#public-directory-support +# public + +# vuepress build output +.vuepress/dist + +# vuepress v2.x temp and cache directory +.temp +.cache + +# Docusaurus cache and generated files +.docusaurus + +# Serverless directories +.serverless/ + +# FuseBox cache +.fusebox/ + +# DynamoDB Local files +.dynamodb/ + +# TernJS port file +.tern-port + +# Stores VSCode versions used for testing VSCode extensions +.vscode-test + +# yarn v2 +.yarn/cache +.yarn/unplugged +.yarn/build-state.yml +.yarn/install-state.gz +.pnp.* + +# Generated files +index.js +index.d.ts +test/*.js diff --git a/arcjet-node/LICENSE b/arcjet-node/LICENSE new file mode 100644 index 000000000..261eeb9e9 --- /dev/null +++ b/arcjet-node/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/arcjet-node/README.md b/arcjet-node/README.md new file mode 100644 index 000000000..bf0dfc890 --- /dev/null +++ b/arcjet-node/README.md @@ -0,0 +1,123 @@ + + + + Arcjet Logo + + + +# `@arcjet/node` + +

+ + + + npm badge + + +

+ +[Arcjet][arcjet] helps developers protect their apps in just a few lines of +code. Implement rate limiting, bot protection, email verification & defend +against common attacks. + +This is the [Arcjet][arcjet] SDK for [Node.js][node-js]. + +## Installation + +```shell +npm install -S @arcjet/node +``` + +## Rate limit example + +The [Arcjet rate limit][rate-limit-concepts-docs] example below applies a token +bucket rate limit rule to a route where we identify the user based on their ID +e.g. if they are logged in. The bucket is configured with a maximum capacity of +10 tokens and refills by 5 tokens every 10 seconds. Each request consumes 5 +tokens. + +```ts +import arcjet, { tokenBucket } from "@arcjet/node"; +import http from "node:http"; + +const aj = arcjet({ + key: process.env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com + rules: [ + // Create a token bucket rate limit. Other algorithms are supported. + tokenBucket({ + mode: "LIVE", // will block requests. Use "DRY_RUN" to log only + characteristics: ["userId"], // track requests by a custom user ID + refillRate: 5, // refill 5 tokens per interval + interval: 10, // refill every 10 seconds + capacity: 10, // bucket maximum capacity of 10 tokens + }), + ], +}); + +const server = http.createServer(async function ( + req: http.IncomingMessage, + res: http.ServerResponse, +) { + const userId = "user123"; // Replace with your authenticated user ID + const decision = await aj.protect(req, { userId, requested: 5 }); // Deduct 5 tokens from the bucket + console.log("Arcjet decision", decision); + + if (decision.isDenied()) { + res.writeHead(429, { "Content-Type": "application/json" }); + res.end( + JSON.stringify({ error: "Too Many Requests", reason: decision.reason }), + ); + } else { + res.writeHead(200, { "Content-Type": "application/json" }); + res.end(JSON.stringify({ message: "Hello world" })); + } +}); + +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. + +```ts +import arcjet 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 +}); + +const server = http.createServer(async function ( + req: http.IncomingMessage, + res: http.ServerResponse, +) { + const decision = await aj.protect(req); + + if (decision.isDenied()) { + res.writeHead(403, { "Content-Type": "application/json" }); + res.end(JSON.stringify({ error: "Forbidden" })); + } else { + res.writeHead(200, { "Content-Type": "application/json" }); + res.end(JSON.stringify({ message: "Hello world" })); + } +}); + +server.listen(8000); +``` + +## License + +Licensed under the [Apache License, Version 2.0][apache-license]. + +[arcjet]: https://arcjet.com +[node-js]: https://nodejs.org/ +[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 diff --git a/arcjet-node/index.ts b/arcjet-node/index.ts new file mode 100644 index 000000000..f36509fd5 --- /dev/null +++ b/arcjet-node/index.ts @@ -0,0 +1,235 @@ +import { createConnectTransport } from "@connectrpc/connect-node"; +import core, { + ArcjetDecision, + ArcjetOptions, + Primitive, + Product, + ArcjetHeaders, + Runtime, + ArcjetRequest, + ExtraProps, + RemoteClient, + RemoteClientOptions, + defaultBaseUrl, + createRemoteClient, + Arcjet, +} from "arcjet"; +import findIP from "@arcjet/ip"; + +// Re-export all named exports from the generic SDK +export * from "arcjet"; + +// Type helpers from https://github.com/sindresorhus/type-fest but adjusted for +// our use. +// +// Simplify: +// https://github.com/sindresorhus/type-fest/blob/964466c9d59c711da57a5297ad954c13132a0001/source/simplify.d.ts +// EmptyObject: +// https://github.com/sindresorhus/type-fest/blob/b9723d4785f01f8d2487c09ee5871a1f615781aa/source/empty-object.d.ts +// +// Licensed: MIT License Copyright (c) Sindre Sorhus +// (https://sindresorhus.com) +// +// Permission is hereby granted, free of charge, to any person obtaining a copy +// of this software and associated documentation files (the "Software"), to deal +// in the Software without restriction, including without limitation the rights +// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +// copies of the Software, and to permit persons to whom the Software is +// furnished to do so, subject to the following conditions: The above copyright +// notice and this permission notice shall be included in all copies or +// substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +// SOFTWARE. +type Simplify = { [KeyType in keyof T]: T[KeyType] } & {}; +declare const emptyObjectSymbol: unique symbol; +type WithoutCustomProps = { + [emptyObjectSymbol]?: never; +}; + +type PlainObject = { + [key: string]: unknown; +}; + +export function createNodeRemoteClient( + options?: 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(); + + // Transport is the HTTP client that the client uses to make requests. + const transport = + options?.transport ?? + createConnectTransport({ + baseUrl, + 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` + const sdkStack = "NODEJS"; + const sdkVersion = "__ARCJET_SDK_VERSION__"; + + return createRemoteClient({ ...options, transport, sdkStack, sdkVersion }); +} + +// Interface of fields that the Arcjet Node.js SDK expects on `IncomingMessage` +// objects. +export interface ArcjetNodeRequest { + headers?: Record; + socket?: Partial<{ remoteAddress: string; encrypted: boolean }>; + method?: string; + httpVersion?: string; + url?: string; +} + +function cookiesToString(cookies: string | string[] | undefined): string { + if (typeof cookies === "undefined") { + return ""; + } + + // This should never be the case with a Node.js cookie header, but we are safe + if (Array.isArray(cookies)) { + return cookies.join("; "); + } + + return cookies; +} + +/** + * The ArcjetNode client provides a public `protect()` method to + * make a decision about how a Node.js request should be handled. + */ +export interface ArcjetNode { + 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 + * the request. + * + * @param req - An `IncomingMessage` provided to the request handler. + * @param props - Additonal properties required for running rules against a request. + * @returns An {@link ArcjetDecision} indicating Arcjet's decision about the request. + */ + protect( + request: ArcjetNodeRequest, + // We use this neat trick from https://stackoverflow.com/a/52318137 to make a single spread parameter + // that is required if the ExtraProps aren't strictly an empty object + ...props: Props extends WithoutCustomProps ? [] : [Props] + ): Promise; + + /** + * Augments the client with another rule. Useful for varying rules based on + * criteria in your handler—e.g. different rate limit for logged in users. + * + * @param rule The rule to add to this execution. + * @returns An augmented {@link ArcjetNode} client. + */ + withRule( + rule: Rule, + ): ArcjetNode>>; +} + +function toArcjetRequest( + request: ArcjetNodeRequest, + props: Props, +): ArcjetRequest { + // We construct an ArcjetHeaders to normalize over Headers + const headers = new ArcjetHeaders(request.headers); + + const ip = findIP(request, headers); + const method = request.method ?? ""; + const host = headers.get("host") ?? ""; + let path = ""; + let query = ""; + let protocol = ""; + + if (typeof request.socket?.encrypted !== "undefined") { + protocol = request.socket.encrypted ? "https:" : "http:"; + } else { + protocol = "http:"; + } + + // Do some very simple validation, but also try/catch around URL parsing + if (typeof request.url !== "undefined" && request.url !== "" && host !== "") { + try { + const url = new URL(request.url, `${protocol}//${host}`); + path = url.pathname; + query = url.search; + protocol = url.protocol; + } catch { + // If the parsing above fails, just set the path as whatever url we + // received. + // TODO(#216): Add logging to arcjet-node + path = request.url ?? ""; + } + } else { + path = request.url ?? ""; + } + + const cookies = cookiesToString(request.headers?.cookie); + + return { + ...props, + ip, + method, + protocol, + host, + path, + headers, + cookies, + query, + }; +} + +function withClient( + aj: Arcjet>, +): ArcjetNode> { + return Object.freeze({ + get runtime() { + return aj.runtime; + }, + withRule(rule: Primitive | Product) { + const client = aj.withRule(rule); + return withClient(client); + }, + async protect( + request: ArcjetNodeRequest, + ...[props]: ExtraProps extends WithoutCustomProps + ? [] + : [ExtraProps] + ): Promise { + // TODO(#220): The generic manipulations get really mad here, so we cast + // 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 ?? {}) as ArcjetRequest< + ExtraProps + >; + + return aj.protect(req); + }, + }); +} + +/** + * Create a new {@link ArcjetNode} client. Always build your initial client + * outside of a request handler so it persists across requests. If you need to + * augment a client inside a handler, call the `withRule()` function on the base + * client. + * + * @param options - Arcjet configuration options to apply to all requests. + */ +export default function arcjet( + options: ArcjetOptions, +): ArcjetNode>> { + const client = options.client ?? createNodeRemoteClient(); + + const aj = core({ ...options, client }); + + return withClient(aj); +} diff --git a/arcjet-node/jest.config.js b/arcjet-node/jest.config.js new file mode 100644 index 000000000..6d5656840 --- /dev/null +++ b/arcjet-node/jest.config.js @@ -0,0 +1,16 @@ +/** @type {import('jest').Config} */ +const config = { + // We only test JS files once compiled with TypeScript + moduleFileExtensions: ["js"], + coverageDirectory: "coverage", + collectCoverage: true, + // If this is set to default (babel) rather than v8, tests fail with the edge + // runtime and the error "EvalError: Code generation from strings disallowed + // for this context". Tracking in + // https://github.com/vercel/edge-runtime/issues/250 + coverageProvider: "v8", + verbose: true, + testEnvironment: "node", +}; + +export default config; diff --git a/arcjet-node/package.json b/arcjet-node/package.json new file mode 100644 index 000000000..b9126ef34 --- /dev/null +++ b/arcjet-node/package.json @@ -0,0 +1,61 @@ +{ + "name": "@arcjet/node", + "version": "1.0.0-alpha.8", + "description": "Arcjet SDK for Node.js", + "license": "Apache-2.0", + "homepage": "https://arcjet.com", + "repository": { + "type": "git", + "url": "git+https://github.com/arcjet/arcjet-js.git", + "directory": "arcjet-node" + }, + "bugs": { + "url": "https://github.com/arcjet/arcjet-js/issues", + "email": "support@arcjet.com" + }, + "author": { + "name": "Arcjet", + "email": "support@arcjet.com", + "url": "https://arcjet.com" + }, + "engines": { + "node": ">=18" + }, + "type": "module", + "main": "./index.js", + "types": "./index.d.ts", + "files": [ + "LICENSE", + "README.md", + "*.js", + "*.d.ts", + "*.ts", + "!*.config.js" + ], + "scripts": { + "prepublishOnly": "npm run build", + "build": "rollup --config rollup.config.js", + "lint": "eslint .", + "pretest": "npm run build", + "test": "NODE_OPTIONS=--experimental-vm-modules jest --passWithNoTests" + }, + "dependencies": { + "@arcjet/ip": "1.0.0-alpha.8", + "@connectrpc/connect-node": "1.3.0", + "arcjet": "1.0.0-alpha.8" + }, + "devDependencies": { + "@arcjet/eslint-config": "1.0.0-alpha.8", + "@arcjet/rollup-config": "1.0.0-alpha.8", + "@arcjet/tsconfig": "1.0.0-alpha.8", + "@jest/globals": "29.7.0", + "@types/node": "18.18.0", + "@rollup/wasm-node": "4.12.0", + "jest": "29.7.0", + "typescript": "5.3.3" + }, + "publishConfig": { + "access": "public", + "tag": "latest" + } +} diff --git a/arcjet-node/rollup.config.js b/arcjet-node/rollup.config.js new file mode 100644 index 000000000..79177f236 --- /dev/null +++ b/arcjet-node/rollup.config.js @@ -0,0 +1,3 @@ +import { createConfig } from "@arcjet/rollup-config"; + +export default createConfig(import.meta.url); diff --git a/arcjet-node/tsconfig.json b/arcjet-node/tsconfig.json new file mode 100644 index 000000000..7150d9377 --- /dev/null +++ b/arcjet-node/tsconfig.json @@ -0,0 +1,4 @@ +{ + "extends": "@arcjet/tsconfig/base", + "include": ["index.ts"] +} diff --git a/examples/nodejs-rl/.env.local.example b/examples/nodejs-rl/.env.local.example new file mode 100644 index 000000000..0c183c7ac --- /dev/null +++ b/examples/nodejs-rl/.env.local.example @@ -0,0 +1 @@ +ARCJET_KEY= \ No newline at end of file diff --git a/examples/nodejs-rl/README.md b/examples/nodejs-rl/README.md new file mode 100644 index 000000000..294050fab --- /dev/null +++ b/examples/nodejs-rl/README.md @@ -0,0 +1,36 @@ + + + + Arcjet Logo + + + +# Arcjet Rate Limit with Node.js + +This example shows how to use Arcjet with a Node.js server. + +## How to use + +1. From the root of the project, install the SDK dependencies. + + ```bash + npm ci + ``` + +2. Enter this directory and install the example's dependencies. + + ```bash + cd examples/nodejs-rl + npm ci + ``` + +3. Rename `.env.local.example` to `.env.local` and add your Arcjet key. + +4. Start the server. + + ```bash + npm start + ``` + +5. Visit `http://localhost:3000/`. +6. Refresh the page to trigger the rate limit. diff --git a/examples/nodejs-rl/index.js b/examples/nodejs-rl/index.js new file mode 100644 index 000000000..6a27187a9 --- /dev/null +++ b/examples/nodejs-rl/index.js @@ -0,0 +1,34 @@ +import arcjet, { fixedWindow } from "@arcjet/node"; +import * as 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: [ + // Fixed window rate limit. Arcjet also supports sliding window and token + // bucket. + fixedWindow({ + mode: "LIVE", // will block requests. Use "DRY_RUN" to log only + // Limiting by ip.src is the default if not specified + //characteristics: ["ip.src"], + window: "1m", // 1 min fixed window + max: 1, // allow a single request (for demo purposes) + }), + ], +}); + +const server = http.createServer(async function (req, res) { + const decision = await aj.protect(req); + + if (decision.isDenied()) { + res.writeHead(429, { "Content-Type": "application/json" }); + res.end(JSON.stringify({ error: "Too Many Requests" })); + } else { + res.writeHead(200, { "Content-Type": "application/json" }); + res.end(JSON.stringify({ message: "Hello World" })); + } +}); + +server.listen(3000); diff --git a/examples/nodejs-rl/package-lock.json b/examples/nodejs-rl/package-lock.json new file mode 100644 index 000000000..5b51ddd27 --- /dev/null +++ b/examples/nodejs-rl/package-lock.json @@ -0,0 +1,96 @@ +{ + "name": "nodejs-simple", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "dependencies": { + "@arcjet/node": "../../arcjet-node" + }, + "devDependencies": { + "@types/node": "^20", + "typescript": "^5" + } + }, + "../../arcjet": { + "version": "1.0.0-alpha.8", + "extraneous": true, + "license": "Apache-2.0", + "dependencies": { + "@arcjet/analyze": "1.0.0-alpha.8", + "@arcjet/duration": "1.0.0-alpha.8", + "@arcjet/logger": "1.0.0-alpha.8", + "@arcjet/protocol": "1.0.0-alpha.8" + }, + "devDependencies": { + "@arcjet/eslint-config": "1.0.0-alpha.8", + "@arcjet/rollup-config": "1.0.0-alpha.8", + "@arcjet/tsconfig": "1.0.0-alpha.8", + "@edge-runtime/jest-environment": "2.3.10", + "@jest/globals": "29.7.0", + "@rollup/wasm-node": "4.12.0", + "@types/node": "18.18.0", + "jest": "29.7.0", + "typescript": "5.3.3" + }, + "engines": { + "node": ">=18" + } + }, + "../../arcjet-node": { + "name": "@arcjet/node", + "version": "1.0.0-alpha.8", + "license": "Apache-2.0", + "dependencies": { + "@arcjet/ip": "1.0.0-alpha.8", + "@connectrpc/connect-node": "1.3.0", + "arcjet": "1.0.0-alpha.8" + }, + "devDependencies": { + "@arcjet/eslint-config": "1.0.0-alpha.8", + "@arcjet/rollup-config": "1.0.0-alpha.8", + "@arcjet/tsconfig": "1.0.0-alpha.8", + "@jest/globals": "29.7.0", + "@rollup/wasm-node": "4.12.0", + "@types/node": "18.18.0", + "jest": "29.7.0", + "typescript": "5.3.3" + }, + "engines": { + "node": ">=18" + } + }, + "node_modules/@arcjet/node": { + "resolved": "../../arcjet-node", + "link": true + }, + "node_modules/@types/node": { + "version": "20.11.20", + "resolved": "https://registry.npmjs.org/@types/node/-/node-20.11.20.tgz", + "integrity": "sha512-7/rR21OS+fq8IyHTgtLkDK949uzsa6n8BkziAKtPVpugIkO6D+/ooXMvzXxDnZrmtXVfjb1bKQafYpb8s89LOg==", + "dev": true, + "dependencies": { + "undici-types": "~5.26.4" + } + }, + "node_modules/typescript": { + "version": "5.3.3", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.3.3.tgz", + "integrity": "sha512-pXWcraxM0uxAS+tN0AG/BF2TyqmHO014Z070UsJ+pFvYuRSq8KH8DmWpnbXe0pEPDHXZV3FcAbJkijJ5oNEnWw==", + "dev": true, + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + }, + "node_modules/undici-types": { + "version": "5.26.5", + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-5.26.5.tgz", + "integrity": "sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA==", + "dev": true + } + } +} diff --git a/examples/nodejs-rl/package.json b/examples/nodejs-rl/package.json new file mode 100644 index 000000000..fe60e9bf9 --- /dev/null +++ b/examples/nodejs-rl/package.json @@ -0,0 +1,14 @@ +{ + "private": true, + "type": "module", + "scripts": { + "start": "node --env-file .env.local ./index.js" + }, + "dependencies": { + "@arcjet/node": "../../arcjet-node" + }, + "devDependencies": { + "@types/node": "^20", + "typescript": "^5" + } +} diff --git a/examples/nodejs-rl/tsconfig.json b/examples/nodejs-rl/tsconfig.json new file mode 100644 index 000000000..6cc6ccf92 --- /dev/null +++ b/examples/nodejs-rl/tsconfig.json @@ -0,0 +1,8 @@ +{ + "compilerOptions": { + "allowJs": true, + "noEmit": true + }, + "include": ["index.js"], + "exclude": ["node_modules"] +} diff --git a/package-lock.json b/package-lock.json index bd2e48b9a..b4d0870f9 100644 --- a/package-lock.json +++ b/package-lock.json @@ -83,6 +83,28 @@ "node": ">=18" } }, + "arcjet-node": { + "version": "1.0.0-alpha.8", + "license": "Apache-2.0", + "dependencies": { + "@arcjet/ip": "1.0.0-alpha.8", + "@connectrpc/connect-node": "1.3.0", + "arcjet": "1.0.0-alpha.8" + }, + "devDependencies": { + "@arcjet/eslint-config": "1.0.0-alpha.8", + "@arcjet/rollup-config": "1.0.0-alpha.8", + "@arcjet/tsconfig": "1.0.0-alpha.8", + "@jest/globals": "29.7.0", + "@rollup/wasm-node": "4.12.0", + "@types/node": "18.18.0", + "jest": "29.7.0", + "typescript": "5.3.3" + }, + "engines": { + "node": ">=18" + } + }, "decorate": { "name": "@arcjet/decorate", "version": "1.0.0-alpha.8", @@ -229,6 +251,10 @@ "resolved": "arcjet-next", "link": true }, + "node_modules/@arcjet/node": { + "resolved": "arcjet-node", + "link": true + }, "node_modules/@arcjet/protocol": { "resolved": "protocol", "link": true @@ -914,6 +940,21 @@ "@bufbuild/protobuf": "^1.4.2" } }, + "node_modules/@connectrpc/connect-node": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/@connectrpc/connect-node/-/connect-node-1.3.0.tgz", + "integrity": "sha512-2fV/z/8MUFOkTn2Gbm7T/qvRfkpt/D/w7ykYqACZRH6VNG/faY4lH2wUZiNkwv9tzTrECKOJFyPsaGs3nRYK3w==", + "dependencies": { + "undici": "^5.28.2" + }, + "engines": { + "node": ">=16.0.0" + }, + "peerDependencies": { + "@bufbuild/protobuf": "^1.4.2", + "@connectrpc/connect": "1.3.0" + } + }, "node_modules/@connectrpc/connect-web": { "version": "1.3.0", "resolved": "https://registry.npmjs.org/@connectrpc/connect-web/-/connect-web-1.3.0.tgz", @@ -1012,6 +1053,14 @@ "node": "^12.22.0 || ^14.17.0 || >=16.0.0" } }, + "node_modules/@fastify/busboy": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/@fastify/busboy/-/busboy-2.1.0.tgz", + "integrity": "sha512-+KpH+QxZU7O4675t3mnkQKcZZg56u+K/Ct2K+N2AZYNVK8kyeo/bI18tI8aPm3tvNNRyTWfj6s5tnGNlcbQRsA==", + "engines": { + "node": ">=14" + } + }, "node_modules/@humanwhocodes/config-array": { "version": "0.11.14", "resolved": "https://registry.npmjs.org/@humanwhocodes/config-array/-/config-array-0.11.14.tgz", @@ -7384,6 +7433,17 @@ "url": "https://github.com/sponsors/ljharb" } }, + "node_modules/undici": { + "version": "5.28.3", + "resolved": "https://registry.npmjs.org/undici/-/undici-5.28.3.tgz", + "integrity": "sha512-3ItfzbrhDlINjaP0duwnNsKpDQk3acHI3gVJ1z4fmwMK31k5G9OVIAMLSIaP6w4FaGkaAkN6zaQO9LUvZ1t7VA==", + "dependencies": { + "@fastify/busboy": "^2.0.0" + }, + "engines": { + "node": ">=14.0" + } + }, "node_modules/update-browserslist-db": { "version": "1.0.13", "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.0.13.tgz", @@ -7649,7 +7709,6 @@ "version": "1.0.0-alpha.8", "license": "Apache-2.0", "dependencies": { - "@arcjet/logger": "1.0.0-alpha.8", "@bufbuild/protobuf": "1.7.2", "@connectrpc/connect": "1.3.0", "typeid-js": "0.5.0"