@arcjet/astro 1.0.0-beta.8 → 1.0.0

package/README.md

@@ -22,6 +22,9 @@ against common attacks.
 
 This is the [Arcjet][arcjet] SDK integration for [Astro][astro].
 
+- [npm package (`@arcjet/astro`)](https://www.npmjs.com/package/@arcjet/astro)
+- [GitHub source code (`arcjet-astro/` in `arcjet/arcjet-js`)](https://github.com/arcjet/arcjet-js/tree/main/arcjet-astro)
+
 ## Getting started
 
 Visit the [quick start guide][quick-start] to get started.
@@ -31,187 +34,55 @@ Visit the [quick start guide][quick-start] to get started.
 Try an Arcjet protected app live at [https://example.arcjet.com][example-url]
 ([source code][example-source]).
 
-## Installation
-
-```shell
-npx astro add @arcjet/astro
-```
-
-## Usage
+## What is this?
 
-If installed via the Astro CLI command above, your `astro.config.mjs` should be
-changed like:
+This is our adapter to integrate Arcjet into Astro.
+Arcjet helps you secure your Astro website.
+This package exists so that we can provide the best possible experience to
+Astro users.
 
-```diff
-  // @ts-check
-  import { defineConfig } from "astro/config";
-+ import arcjet from "@arcjet/astro";
+## When should I use this?
 
-  // https://astro.build/config
-  export default defineConfig({
-+   integrations: [
-+     arcjet(),
-+   ],
-  });
-```
+You can use this if you are using Astro.
+See our [_Get started_ guide][arcjet-get-started] for other supported
+frameworks.
 
-However, if installed manually, you'll want to add the above lines to your Astro
-configuration.
-
-We also recommended validating your environment variables at build time. To do
-this, update your `astro.config.mjs` to add the option:
-
-```diff
-  // @ts-check
-  import { defineConfig } from "astro/config";
-  import arcjet from "@arcjet/astro";
-
-  // https://astro.build/config
-  export default defineConfig({
-+   env: {
-+     validateSecrets: true
-+   },
-    integrations: [
-      arcjet(),
-    ],
-  });
-```
+## Install
 
-Once Arcjet is added as an integration, you'll want to start the Astro dev
-server to build the `arcjet:client` virtual module and types. In your terminal,
-run:
+This package is ESM only.
+Install with npm and the Astro CLI in Node.js:
 
 ```sh
-npx astro dev
-```
-
-You can now import from the `arcjet:client` module within your Astro project!
-
-This example adds Arcjet to your middleware, but note this only works for
-non-prerendered pages:
-
-```ts
-// src/middleware.ts
-import { defineMiddleware } from "astro:middleware";
-import aj from "arcjet:client";
-
-export const onRequest = defineMiddleware(
-  async ({ isPrerendered, request }, next) => {
-    // Arcjet can be run in your middleware; however, Arcjet can only process a
-    // request when the page is NOT prerendered.
-    if (!isPrerendered) {
-      // console.log(request);
-      const decision = await aj.protect(request);
-
-      // Deny decisions respond immediately to avoid any additional server
-      // processing.
-      if (decision.isDenied()) {
-        return new Response(null, { status: 403, statusText: "Forbidden" });
-      }
-    }
-
-    return next();
-  },
-);
-```
-
-## Rate limit + bot detection 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.
-
-The rule is defined in your `astro.config.mjs` file:
-
-```js
-// @ts-check
-import { defineConfig } from "astro/config";
-import arcjet, { tokenBucket, detectBot } from "@arcjet/astro";
-
-// https://astro.build/config
-export default defineConfig({
-  env: {
-    validateSecrets: true,
-  },
-  integrations: [
-    arcjet({
-      characteristics: ["userId"], // track requests by a custom user ID
-      rules: [
-        // Create a token bucket rate limit. Other algorithms are supported.
-        tokenBucket({
-          mode: "LIVE", // will block requests. Use "DRY_RUN" to log only
-          refillRate: 5, // refill 5 tokens per interval
-          interval: 10, // refill every 10 seconds
-          capacity: 10, // bucket maximum capacity of 10 tokens
-        }),
-        detectBot({
-          mode: "LIVE", // will block requests. Use "DRY_RUN" to log only
-          // configured with a list of bots to allow from
-          // https://arcjet.com/bot-list
-          allow: [], // "allow none" will block all detected bots
-        }),
-      ],
-    }),
-  ],
-});
-```
-
-Then Arcjet is called from within this page route:
-
-```ts
-// src/pages/api.json.ts
-import type { APIRoute } from "astro";
-import aj from "arcjet:client";
-
-export const GET: APIRoute = async ({ request }) => {
-  const userId = "user123"; // Replace with your authenticated user ID
-  const decision = await aj.protect(request, { userId, requested: 5 }); // Deduct 5 tokens from the bucket
-  console.log("Arcjet decision", decision);
-
-  if (decision.isDenied()) {
-    return Response.json({ error: "Forbidden" }, { status: 403 });
-  } else {
-    return Response.json({ message: "Hello world" });
-  }
-};
+npx astro add @arcjet/astro
 ```
 
-## Shield example
-
-[Arcjet Shield][shield-concepts-docs] protects your application against common
-attacks, including the OWASP Top 10. You can run Shield on every request with
-negligible performance impact.
+## Use
 
-The rule is defined in your `astro.config.mjs` file:
+Configure Arcjet in `astro.config.mjs`:
 
 ```js
-// @ts-check
-import { defineConfig } from "astro/config";
 import arcjet, { shield } from "@arcjet/astro";
+import { defineConfig } from "astro/config";
 
-// https://astro.build/config
 export default defineConfig({
-  env: {
-    validateSecrets: true,
-  },
+  // We recommend setting
+  // [`validateSecrets`](https://docs.astro.build/en/reference/configuration-reference/#envvalidatesecrets).
+  env: { validateSecrets: true },
   integrations: [
     arcjet({
       rules: [
-        shield({
-          mode: "LIVE", // will block requests. Use "DRY_RUN" to log only
-        }),
+        // Shield protects your app from common attacks.
+        // Use `DRY_RUN` instead of `LIVE` to only log.
+        shield({ mode: "LIVE" }),
       ],
     }),
   ],
 });
 ```
 
-Then Arcjet is called from within this page route:
+…then use Arcjet in on-demand routes (such as `src/pages/api.json.ts`):
 
 ```ts
-// src/pages/api.json.ts
 import type { APIRoute } from "astro";
 import aj from "arcjet:client";
 
@@ -219,22 +90,25 @@ export const GET: APIRoute = async ({ request }) => {
   const decision = await aj.protect(request);
 
   if (decision.isDenied()) {
-    return Response.json({ error: "Forbidden" }, { status: 403 });
-  } else {
-    return Response.json({ message: "Hello world" });
+    return Response.json({ message: "Forbidden" }, { status: 403 });
   }
+
+  return Response.json({ message: "Hello world" });
 };
 ```
 
+For more on how to configure Arcjet with Astro and how to protect Astro,
+see the [Arcjet Astro SDK reference][arcjet-reference-astro] on our website.
+
 ## License
 
-Licensed under the [Apache License, Version 2.0][apache-license].
+[Apache License, Version 2.0][apache-license] © [Arcjet Labs, Inc.][arcjet]
 
+[arcjet-get-started]: https://docs.arcjet.com/get-started
+[arcjet-reference-astro]: https://docs.arcjet.com/reference/astro
 [arcjet]: https://arcjet.com
 [astro]: https://astro.build/
 [example-url]: https://example.arcjet.com
 [quick-start]: https://docs.arcjet.com/get-started/astro
 [example-source]: https://github.com/arcjet/arcjet-js-example
-[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

@@ -1,75 +1,330 @@
-import type { BotOptions, EmailOptions, FixedWindowRateLimitOptions, ProtectSignupOptions, SensitiveInfoOptions, ShieldOptions, SlidingWindowRateLimitOptions, TokenBucketRateLimitOptions } from "arcjet";
+import type { BotOptions, EmailOptions, FilterOptions, FixedWindowRateLimitOptions, ProtectSignupOptions, SensitiveInfoOptions, ShieldOptions, SlidingWindowRateLimitOptions, TokenBucketRateLimitOptions } from "arcjet";
 import type { AstroIntegration } from "astro";
 type IntegrationRule<Characteristics extends readonly string[]> = {
     type: "shield";
-    options?: ShieldOptions;
+    options: ShieldOptions;
 } | {
     type: "bot";
-    options?: BotOptions;
+    options: BotOptions;
 } | {
     type: "email";
-    options?: EmailOptions;
+    options: EmailOptions;
+} | {
+    type: "filter";
+    options: FilterOptions;
 } | {
     type: "sensitiveInfo";
-    options?: SensitiveInfoOptions<never>;
+    options: SensitiveInfoOptions<undefined>;
 } | {
     type: "fixedWindow";
-    options?: FixedWindowRateLimitOptions<Characteristics>;
+    options: FixedWindowRateLimitOptions<Characteristics>;
 } | {
     type: "slidingWindow";
-    options?: SlidingWindowRateLimitOptions<Characteristics>;
+    options: SlidingWindowRateLimitOptions<Characteristics>;
 } | {
     type: "tokenBucket";
-    options?: TokenBucketRateLimitOptions<Characteristics>;
+    options: TokenBucketRateLimitOptions<Characteristics>;
 } | {
     type: "protectSignup";
-    options?: ProtectSignupOptions<Characteristics>;
+    options: ProtectSignupOptions<Characteristics>;
 };
-type ArcjetIntegrationOptions<Characteristics extends readonly string[]> = {
+/**
+ * Configuration for the Astro integration of Arcjet.
+ *
+ * @template Characteristics
+ *   Characteristics to track a user by.
+ */
+export type ArcjetOptions<Characteristics extends readonly string[]> = {
+    /**
+     * Integration rules to apply when protecting a request (required).
+     *
+     * These rules are *different* from those exposed from `arcjet` core.
+     * You have to import them from this integration (`@arcjet/astro`) instead.
+     */
     rules: IntegrationRule<Characteristics>[];
+    /**
+     * Characteristics to track a user by (default: `["src.ip"]`).
+     *
+     * Can also be passed to rules.
+     */
     characteristics?: Characteristics;
+    /**
+     * Configuration for the default client (optional).
+     */
     client?: RemoteClientOptions;
+    /**
+     * IP addresses and CIDR ranges of trusted load balancers and proxies
+     * (optional, example: `["100.100.100.100", "100.100.100.0/24"]`).
+     */
     proxies?: string[];
 };
-export declare function shield(options?: ShieldOptions): {
+/**
+ * Arcjet Shield WAF rule.
+ *
+ * Applying this rule protects your application against common attacks,
+ * including the OWASP Top 10.
+ *
+ * The Arcjet Shield WAF analyzes every request to your application to detect
+ * suspicious activity.
+ * Once a certain suspicion threshold is reached,
+ * subsequent requests from that client are blocked for a period of time.
+ *
+ * @param options
+ *   Configuration for the Shield rule.
+ * @returns
+ *   Astro integration Shield rule to provide to the SDK in the `rules` field.
+ */
+export declare function shield(options: ShieldOptions): {
     readonly type: "shield";
-    readonly options: ShieldOptions | undefined;
+    readonly options: ShieldOptions;
 };
-export declare function detectBot(options?: BotOptions): {
+/**
+ * Arcjet bot detection rule.
+ *
+ * Applying this rule allows you to manage traffic by automated clients and
+ * bots.
+ *
+ * Bots can be good (such as search engine crawlers or monitoring agents) or bad
+ * (such as scrapers or automated scripts).
+ * Arcjet allows you to configure which bots you want to allow or deny by
+ * specific bot names such as curl, as well as by category such as search
+ * engine bots.
+ *
+ * Bots are detected based on various signals such as the user agent, IP
+ * address, DNS records, and more.
+ *
+ * @param options
+ *   Configuration for the bot rule (required).
+ * @returns
+ *   Astro integration Bot rule to provide to the SDK in the `rules` field.
+ */
+export declare function detectBot(options: BotOptions): {
     readonly type: "bot";
-    readonly options: BotOptions | undefined;
+    readonly options: BotOptions;
 };
-export declare function validateEmail(options?: EmailOptions): {
+/**
+ * Arcjet email validation rule.
+ *
+ * Applying this rule allows you to validate and verify an email address.
+ *
+ * The first step of the analysis is to validate the email address syntax.
+ * This runs locally within the SDK and validates the email address is in the
+ * correct format.
+ * If the email syntax is valid, the SDK will pass the email address to the
+ * Arcjet cloud API to verify the email address.
+ * This performs several checks, depending on the rule configuration.
+ *
+ * @param options
+ *   Configuration for the email validation rule (required).
+ * @returns
+ *   Astro integration Email rule to provide to the SDK in the `rules` field.
+ */
+export declare function validateEmail(options: EmailOptions): {
     readonly type: "email";
-    readonly options: EmailOptions | undefined;
+    readonly options: EmailOptions;
+};
+/**
+ * Arcjet filter rule.
+ *
+ * Applying this rule lets you block requests using Wireshark-like display
+ * filter expressions over HTTP headers, IP addresses, and other request
+ * fields.
+ * You can quickly enforce rules like allow/deny by country, network, or
+ * `user-agent` pattern.
+ *
+ * See the [reference guide](https://docs.arcjet.com/filters/reference) for
+ * more info on the expression language fields, functions, and values.
+ *
+ * @param options
+ *   Configuration (required).
+ * @returns
+ *   Astro integration Filter rule to provide to the SDK in the `rules` field.
+ *
+ * @example
+ *   In this example, the expression matches non-VPN GET requests from the US.
+ *   Requests matching the expression are allowed, all others are denied.
+ *
+ *   ```ts
+ *   filter({
+ *     allow: [
+ *       'http.request.method eq "GET" and ip.src.country eq "US" and not ip.src.vpn',
+ *     ],
+ *     mode: "LIVE",
+ *   })
+ *   ```
+ *
+ * @link https://docs.arcjet.com/filters/reference
+ */
+export declare function filter(options: FilterOptions): {
+    readonly type: "filter";
+    readonly options: FilterOptions;
 };
-export declare function sensitiveInfo(options?: SensitiveInfoOptions<never>): {
+/**
+ * Arcjet sensitive information detection rule.
+ *
+ * Applying this rule protects against clients sending you sensitive information
+ * such as personally identifiable information (PII) that you do not wish to
+ * handle.
+ * The rule runs entirely locally so no data ever leaves your environment.
+ *
+ * This rule includes built-in detections for email addresses, credit/debit card
+ * numbers, IP addresses, and phone numbers.
+ * You can also provide a custom detection function to identify additional
+ * sensitive information.
+ *
+ * @param options
+ *   Configuration for the sensitive information detection rule (required).
+ * @returns
+ *   Astro integration Sensitive information rule to provide to the SDK in the `rules` field.
+ */
+export declare function sensitiveInfo(options: SensitiveInfoOptions<never>): {
     readonly type: "sensitiveInfo";
-    readonly options: SensitiveInfoOptions<never> | undefined;
+    readonly options: SensitiveInfoOptions<never>;
 };
-export declare function fixedWindow<Characteristics extends readonly string[]>(options?: FixedWindowRateLimitOptions<Characteristics>): {
+/**
+ * Arcjet fixed window rate limiting rule.
+ *
+ * Applying this rule sets a fixed window rate limit which tracks the number of
+ * requests made by a client over a fixed time window.
+ *
+ * This is the simplest algorithm.
+ * It tracks the number of requests made by a client over a fixed time window
+ * such as 60 seconds.
+ * If the client exceeds the limit, they are blocked until the window expires.
+ *
+ * This algorithm is useful when you want to apply a simple fixed limit in a
+ * fixed time window.
+ * For example, a simple limit on the total number of requests a client can make.
+ * However, it can be susceptible to the stampede problem where a client makes
+ * a burst of requests at the start of a window and then is blocked for the rest
+ * of the window.
+ * The sliding window algorithm can be used to avoid this.
+ *
+ * @template Characteristics
+ *   Characteristics to track a user by.
+ * @param options
+ *   Configuration for the fixed window rate limiting rule (required).
+ * @returns
+ *   Astro integration Fixed window rule to provide to the SDK in the `rules` field.
+ */
+export declare function fixedWindow<Characteristics extends readonly string[]>(options: FixedWindowRateLimitOptions<Characteristics>): {
     readonly type: "fixedWindow";
-    readonly options: FixedWindowRateLimitOptions<Characteristics> | undefined;
+    readonly options: FixedWindowRateLimitOptions<Characteristics>;
 };
-export declare function slidingWindow<Characteristics extends readonly string[]>(options?: SlidingWindowRateLimitOptions<Characteristics>): {
+/**
+ * Arcjet sliding window rate limiting rule.
+ *
+ * Applying this rule sets a sliding window rate limit which tracks the number
+ * of requests made by a client over a sliding window so that the window moves
+ * with time.
+ *
+ * This algorithm is useful to avoid the stampede problem of the fixed window.
+ * It provides smoother rate limiting over time and can prevent a client from
+ * making a burst of requests at the start of a window and then being blocked
+ * for the rest of the window.
+ *
+ * @template Characteristics
+ *   Characteristics to track a user by.
+ * @param options
+ *   Configuration for the sliding window rate limiting rule (required).
+ * @returns
+ *   Astro integration Sliding window rule to provide to the SDK in the `rules` field.
+ */
+export declare function slidingWindow<Characteristics extends readonly string[]>(options: SlidingWindowRateLimitOptions<Characteristics>): {
     readonly type: "slidingWindow";
-    readonly options: SlidingWindowRateLimitOptions<Characteristics> | undefined;
+    readonly options: SlidingWindowRateLimitOptions<Characteristics>;
 };
-export declare function tokenBucket<Characteristics extends readonly string[]>(options?: TokenBucketRateLimitOptions<Characteristics>): {
+/**
+ * Arcjet token bucket rate limiting rule.
+ *
+ * Applying this rule sets a token bucket rate limit.
+ *
+ * This algorithm is based on a bucket filled with a specific number of tokens.
+ * Each request withdraws some amount of tokens from the bucket and the bucket
+ * is refilled at a fixed rate.
+ * Once the bucket is empty, the client is blocked until the bucket refills.
+ *
+ * This algorithm is useful when you want to allow clients to make a burst of
+ * requests and then still be able to make requests at a slower rate.
+ *
+ * @template Characteristics
+ *   Characteristics to track a user by.
+ * @param options
+ *   Configuration for the token bucket rate limiting rule (required).
+ * @returns
+ *   Astro integration Token bucket rule to provide to the SDK in the `rules` field.
+ */
+export declare function tokenBucket<Characteristics extends readonly string[]>(options: TokenBucketRateLimitOptions<Characteristics>): {
     readonly type: "tokenBucket";
-    readonly options: TokenBucketRateLimitOptions<Characteristics> | undefined;
+    readonly options: TokenBucketRateLimitOptions<Characteristics>;
 };
-export declare function protectSignup<Characteristics extends readonly string[]>(options?: ProtectSignupOptions<Characteristics>): {
+/**
+ * Arcjet signup form protection rule.
+ *
+ * Applying this rule combines rate limiting, bot protection, and email
+ * validation to protect your signup forms from abuse.
+ * Using this rule will configure the following:
+ *
+ * - Rate limiting - signup forms are a common target for bots. Arcjet’s rate
+ *   limiting helps to prevent bots and other automated or malicious clients
+ *   from submitting your signup form too many times in a short period of time.
+ * - Bot protection - signup forms are usually exclusively used by humans, which
+ *   means that any automated submissions to the form are likely to be
+ *   fraudulent.
+ * - Email validation - email addresses should be validated to ensure the signup
+ *   is coming from a legitimate user with a real email address that can
+ *   actually receive messages.
+ *
+ * @template Characteristics
+ *   Characteristics to track a user by.
+ * @param options
+ *   Configuration for the signup form protection rule.
+ * @returns
+ *   Astro integration Signup form protection rule to provide to the SDK in the `rules` field.
+ */
+export declare function protectSignup<Characteristics extends readonly string[]>(options: ProtectSignupOptions<Characteristics>): {
     readonly type: "protectSignup";
-    readonly options: ProtectSignupOptions<Characteristics> | undefined;
+    readonly options: ProtectSignupOptions<Characteristics>;
 };
+/**
+ * Configuration for {@linkcode createRemoteClient}.
+ */
 export type RemoteClientOptions = {
-    baseUrl?: string;
-    timeout?: number;
+    /**
+     * Base URI for HTTP requests to Decide API (optional).
+     *
+     * Defaults to the environment variable `ARCJET_BASE_URL` (if that value
+     * is known and allowed) and the standard production API otherwise.
+     */
+    baseUrl?: string | undefined;
+    /**
+     * Timeout in milliseconds for the Decide API (optional).
+     *
+     * Defaults to `500` in production and `1000` in development.
+     */
+    timeout?: number | undefined;
 };
-export declare function createRemoteClient({ baseUrl, timeout }: RemoteClientOptions): {
+/**
+ * Create a remote client.
+ *
+ * @param options
+ *   Configuration (optional).
+ * @returns
+ *   Client.
+ */
+export declare function createRemoteClient(options?: RemoteClientOptions | undefined): {
     readonly baseUrl: string | undefined;
     readonly timeout: number | undefined;
 };
-export default function arcjet<Characteristics extends readonly string[]>({ rules, characteristics, client, proxies, }?: ArcjetIntegrationOptions<Characteristics>): AstroIntegration;
+/**
+ * Create a new Astro integration of Arcjet.
+ *
+ * @template Characteristics
+ *   Characteristics to track a user by.
+ * @param options
+ *   Configuration.
+ * @returns
+ *   Astro integration of Arcjet.
+ */
+export default function arcjet<Characteristics extends readonly string[]>(options?: ArcjetOptions<Characteristics>): AstroIntegration;
 export {};