@arcjet/node 1.0.0-alpha.9

package/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.

package/README.md

@@ -0,0 +1,126 @@
+<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">
+  </picture>
+</a>
+
+# `@arcjet/node`
+
+<p>
+  <a href="https://www.npmjs.com/package/@arcjet/node">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/npm/v/%40arcjet%2Fnode?style=flat-square&label=%E2%9C%A6Aj&labelColor=000000&color=5C5866">
+      <img alt="npm badge" src="https://img.shields.io/npm/v/%40arcjet%2Fnode?style=flat-square&label=%E2%9C%A6Aj&labelColor=ECE6F0&color=ECE6F0">
+    </picture>
+  </a>
+</p>
+
+[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].
+
+**Looking for our Next.js framework SDK?** Check out the
+[`@arcjet/next`](https://www.npmjs.com/package/@arcjet/next) package.
+
+## 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

package/index.d.ts

@@ -0,0 +1,57 @@
+import { ArcjetDecision, ArcjetOptions, Primitive, Product, Runtime, ExtraProps, RemoteClient, RemoteClientOptions } from "arcjet";
+export * from "arcjet";
+type Simplify<T> = {
+    [KeyType in keyof T]: T[KeyType];
+} & {};
+declare const emptyObjectSymbol: unique symbol;
+type WithoutCustomProps = {
+    [emptyObjectSymbol]?: never;
+};
+type PlainObject = {
+    [key: string]: unknown;
+};
+export declare function createNodeRemoteClient(options?: RemoteClientOptions): RemoteClient;
+export interface ArcjetNodeRequest {
+    headers?: Record<string, string | string[] | undefined>;
+    socket?: Partial<{
+        remoteAddress: string;
+        encrypted: boolean;
+    }>;
+    method?: string;
+    httpVersion?: string;
+    url?: string;
+}
+/**
+ * The ArcjetNode client provides a public `protect()` method to
+ * make a decision about how a Node.js request should be handled.
+ */
+export interface ArcjetNode<Props extends PlainObject> {
+    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, ...props: Props extends WithoutCustomProps ? [] : [Props]): Promise<ArcjetDecision>;
+    /**
+     * 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 extends Primitive | Product>(rule: Rule): ArcjetNode<Simplify<Props & ExtraProps<Rule>>>;
+}
+/**
+ * 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<const Rules extends (Primitive | Product)[]>(options: ArcjetOptions<Rules>): ArcjetNode<Simplify<ExtraProps<Rules>>>;

package/index.js

@@ -0,0 +1,109 @@
+import { createConnectTransport } from '@connectrpc/connect-node';
+import core__default, { defaultBaseUrl, createRemoteClient, ArcjetHeaders } from 'arcjet';
+export * from 'arcjet';
+import findIP from '@arcjet/ip';
+
+function createNodeRemoteClient(options) {
+    // 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 = "1.0.0-alpha.9";
+    return createRemoteClient({ ...options, transport, sdkStack, sdkVersion });
+}
+function cookiesToString(cookies) {
+    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;
+}
+function toArcjetRequest(request, props) {
+    // 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) {
+    return Object.freeze({
+        get runtime() {
+            return aj.runtime;
+        },
+        withRule(rule) {
+            const client = aj.withRule(rule);
+            return withClient(client);
+        },
+        async protect(request, ...[props]) {
+            // 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 ?? {});
+            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.
+ */
+function arcjet(options) {
+    const client = options.client ?? createNodeRemoteClient();
+    const aj = core__default({ ...options, client });
+    return withClient(aj);
+}
+
+export { createNodeRemoteClient, arcjet as default };

package/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 <sindresorhus@gmail.com>
+// (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<T> = { [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<string, string | string[] | undefined>;
+  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<Props extends PlainObject> {
+  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<ArcjetDecision>;
+
+  /**
+   * 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 extends Primitive | Product>(
+    rule: Rule,
+  ): ArcjetNode<Simplify<Props & ExtraProps<Rule>>>;
+}
+
+function toArcjetRequest<Props extends PlainObject>(
+  request: ArcjetNodeRequest,
+  props: Props,
+): ArcjetRequest<Props> {
+  // 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<const Rules extends (Primitive | Product)[]>(
+  aj: Arcjet<ExtraProps<Rules>>,
+): ArcjetNode<ExtraProps<Rules>> {
+  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<Rules> extends WithoutCustomProps
+        ? []
+        : [ExtraProps<Rules>]
+    ): Promise<ArcjetDecision> {
+      // 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<Rules>
+      >;
+
+      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<const Rules extends (Primitive | Product)[]>(
+  options: ArcjetOptions<Rules>,
+): ArcjetNode<Simplify<ExtraProps<Rules>>> {
+  const client = options.client ?? createNodeRemoteClient();
+
+  const aj = core({ ...options, client });
+
+  return withClient(aj);
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@arcjet/node",
+  "version": "1.0.0-alpha.9",
+  "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.9",
+    "@connectrpc/connect-node": "1.4.0",
+    "arcjet": "1.0.0-alpha.9"
+  },
+  "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",
+    "@types/node": "18.18.0",
+    "@rollup/wasm-node": "4.12.0",
+    "jest": "29.7.0",
+    "typescript": "5.3.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  }
+}