@arcjet/astro 1.0.0-beta.9 → 1.1.0-rc

package/index.js

@@ -7,107 +7,112 @@ const validateProxies = z.array(z.string());
 const validateCharacteristics = z.array(z.string());
 const validateClientOptions = z
     .object({
-    baseUrl: z.string(),
-    timeout: z.number(),
+    baseUrl: z.string().optional(),
+    timeout: z.number().optional(),
 })
     .strict()
     .optional();
+// TODO: once `arcjet` core has `exactOptionalProperties` we can use
+// `satisfies z.ZodType<ShieldOptions>` and such here.
 const validateShieldOptions = z
     .object({
-    mode: validateMode,
+    mode: validateMode.optional(),
 })
-    .strict()
-    .optional();
-const validateBotOptions = z
-    .union([
+    .strict();
+const validateBotOptions = z.union([
     z
         .object({
-        mode: validateMode,
+        mode: validateMode.optional(),
         allow: z.array(z.string()),
     })
         .strict(),
     z
         .object({
-        mode: validateMode,
+        mode: validateMode.optional(),
         deny: z.array(z.string()),
     })
         .strict(),
-])
-    .optional();
-const validateEmailOptions = z
-    .union([
+]);
+const validateEmailOptions = z.union([
     z
         .object({
-        mode: validateMode,
+        mode: validateMode.optional(),
         allow: z.array(z.string()),
-        requireTopLevelDomain: z.boolean(),
-        allowDomainLiteral: z.boolean(),
+        requireTopLevelDomain: z.boolean().optional(),
+        allowDomainLiteral: z.boolean().optional(),
     })
         .strict(),
     z
         .object({
-        mode: validateMode,
+        mode: validateMode.optional(),
         deny: z.array(z.string()),
-        requireTopLevelDomain: z.boolean(),
-        allowDomainLiteral: z.boolean(),
+        requireTopLevelDomain: z.boolean().optional(),
+        allowDomainLiteral: z.boolean().optional(),
     })
         .strict(),
-])
-    .optional();
-const validateSensitiveInfoOptions = z
-    .union([
+]);
+const validateFilterOptions = z.union([
     z
         .object({
-        mode: validateMode,
+        mode: validateMode.optional(),
         allow: z.array(z.string()),
-        contextWindowSize: z.number(),
     })
         .strict(),
     z
         .object({
-        mode: validateMode,
+        mode: validateMode.optional(),
         deny: z.array(z.string()),
-        contextWindowSize: z.number(),
     })
         .strict(),
-])
-    .optional();
+]);
+const validateSensitiveInfoOptions = z.union([
+    z
+        .object({
+        mode: validateMode.optional(),
+        allow: z.array(z.string()),
+        contextWindowSize: z.number().optional(),
+    })
+        .strict(),
+    z
+        .object({
+        mode: validateMode.optional(),
+        deny: z.array(z.string()),
+        contextWindowSize: z.number().optional(),
+    })
+        .strict(),
+]);
 const validateFixedWindowOptions = z
     .object({
-    mode: validateMode,
-    characteristics: validateCharacteristics,
+    mode: validateMode.optional(),
+    characteristics: validateCharacteristics.optional(),
     window: z.union([z.string(), z.number()]),
     max: z.number(),
 })
-    .strict()
-    .optional();
+    .strict();
 const validateSlidingWindowOptions = z
     .object({
-    mode: validateMode,
-    characteristics: validateCharacteristics,
+    mode: validateMode.optional(),
+    characteristics: validateCharacteristics.optional(),
     interval: z.union([z.string(), z.number()]),
     max: z.number(),
 })
-    .strict()
-    .optional();
+    .strict();
 const validateTokenBucketOptions = z
     .object({
-    mode: validateMode,
-    characteristics: validateCharacteristics,
+    mode: validateMode.optional(),
+    characteristics: validateCharacteristics.optional(),
     refillRate: z.number(),
     interval: z.union([z.string(), z.number()]),
     capacity: z.number(),
 })
-    .strict()
-    .optional();
+    .strict();
 const validateProtectSignupOptions = z
     .object({
     rateLimit: validateSlidingWindowOptions,
     bots: validateBotOptions,
     email: validateEmailOptions,
 })
-    .strict()
-    .optional();
+    .strict();
 function validateAndSerialize(schema, value) {
     const v = schema.parse(value);
     return v ? JSON.stringify(v) : "";
@@ -135,6 +140,13 @@ function integrationRuleToClientRule(rule) {
                 code: `validateEmail(${serializedOpts})`,
             };
         }
+        case "filter": {
+            const serializedOpts = validateAndSerialize(validateFilterOptions, rule.options);
+            return {
+                importName: `filter`,
+                code: `filter(${serializedOpts})`,
+            };
+        }
         case "sensitiveInfo": {
             const serializedOpts = validateAndSerialize(validateSensitiveInfoOptions, rule.options);
             return {
@@ -176,34 +188,270 @@ function integrationRuleToClientRule(rule) {
     }
 }
 // Mirror the rule functions in the SDK but produce serializable rules
+// Note: please keep JSDocs in sync with `arcjet` core.
+/**
+ * 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.
+ */
 function shield(options) {
     return { type: "shield", options };
 }
+// Note: please keep JSDocs in sync with `arcjet` core.
+/**
+ * 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.
+ */
 function detectBot(options) {
     return { type: "bot", options };
 }
+// Note: please keep JSDocs in sync with `arcjet` core.
+/**
+ * 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.
+ */
 function validateEmail(options) {
     return { type: "email", options };
 }
+// Note: please keep JSDocs in sync with `arcjet` core.
+/**
+ * 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
+ */
+function filter(options) {
+    return { type: "filter", options };
+}
+// Note: please keep JSDocs in sync with `arcjet` core.
+/**
+ * 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.
+ */
 function sensitiveInfo(options) {
     return { type: "sensitiveInfo", options };
 }
+// Note: please keep JSDocs in sync with `arcjet` core.
+/**
+ * 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.
+ */
 function fixedWindow(options) {
-    return { type: "fixedWindow", options };
+    return {
+        type: "fixedWindow",
+        options,
+    };
 }
+// Note: please keep JSDocs in sync with `arcjet` core.
+/**
+ * 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.
+ */
 function slidingWindow(options) {
-    return { type: "slidingWindow", options };
+    return {
+        type: "slidingWindow",
+        options,
+    };
 }
+// Note: please keep JSDocs in sync with `arcjet` core.
+/**
+ * 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.
+ */
 function tokenBucket(options) {
-    return { type: "tokenBucket", options };
+    return {
+        type: "tokenBucket",
+        options,
+    };
 }
+// Note: please keep JSDocs in sync with `arcjet` core.
+/**
+ * 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.
+ */
 function protectSignup(options) {
-    return { type: "protectSignup", options };
+    return {
+        type: "protectSignup",
+        options,
+    };
 }
-function createRemoteClient({ baseUrl, timeout }) {
-    return { baseUrl, timeout };
+/**
+ * Create a remote client.
+ *
+ * @param options
+ *   Configuration (optional).
+ * @returns
+ *   Client.
+ */
+function createRemoteClient(options) {
+    const settings = options ?? {};
+    return { baseUrl: settings.baseUrl, timeout: settings.timeout };
 }
-function arcjet({ rules, characteristics, client, proxies, } = { rules: [] }) {
+/**
+ * Create a new Astro integration of Arcjet.
+ *
+ * @template Characteristics
+ *   Characteristics to track a user by.
+ * @param options
+ *   Configuration.
+ * @returns
+ *   Astro integration of Arcjet.
+ */
+function arcjet(options = { rules: [] }) {
+    const { rules, characteristics, client, proxies } = options;
     const arcjetImports = new Set();
     const arcjetRules = [];
     for (const rule of rules) {
@@ -266,6 +514,21 @@ function arcjet({ rules, characteristics, client, proxies, } = { rules: [] }) {
                                 access: "public",
                                 optional: true,
                             },
+                            FIREBASE_CONFIG: {
+                                access: "public",
+                                context: "server",
+                                optional: true,
+                                type: "string",
+                            },
+                            // No `MODE`, that is a vite value on `import.meta.env.MODE`,
+                            // it is inferred in `internal.ts` directly.
+                            // No `NODE_ENV`.
+                            RENDER: {
+                                access: "public",
+                                context: "server",
+                                optional: true,
+                                type: "string",
+                            },
                         },
                     },
                     vite: {
@@ -331,6 +594,21 @@ function arcjet({ rules, characteristics, client, proxies, } = { rules: [] }) {
               ${Array.from(arcjetImports).join(",\n")}
             } from "arcjet"
 
+            /**
+             * Instance of the Astro integration of Arcjet.
+             *
+             * Primarily has a \`protect()\` method to make a decision about how a request
+             * should be handled.
+             *
+             * > 👉 **Note**: this is generated by \`@arcjet/astro\` based on how you configure
+             * > Arcjet in your \`astro.config.mjs\` file.
+             * > In that configuration file, you can pass the (serializable) options that apply
+             * > to all requests.
+             * > You can call \`aj.withRule\` *on* this default client to extend its behavior.
+             *
+             * @template Props
+             *   Configuration.
+             */
             const client = createArcjetClient({
               rules: [
                 ${arcjetRules.join(",\n")}
@@ -348,4 +626,4 @@ function arcjet({ rules, characteristics, client, proxies, } = { rules: [] }) {
     };
 }
 
-export { createRemoteClient, arcjet as default, detectBot, fixedWindow, protectSignup, sensitiveInfo, shield, slidingWindow, tokenBucket, validateEmail };
+export { createRemoteClient, arcjet as default, detectBot, filter, fixedWindow, protectSignup, sensitiveInfo, shield, slidingWindow, tokenBucket, validateEmail };

package/internal.d.ts

@@ -4,57 +4,115 @@ type Simplify<T> = {
     [KeyType in keyof T]: T[KeyType];
 } & {};
 declare const emptyObjectSymbol: unique symbol;
-type WithoutCustomProps = {
-    [emptyObjectSymbol]?: never;
-};
 type PlainObject = {
     [key: string]: unknown;
 };
+/**
+ * Dynamically generate whether zero or one `properties` object must or can be passed.
+ */
+type MaybeProperties<T> = {
+    [P in keyof T]?: T[P];
+} extends T ? T extends {
+    [emptyObjectSymbol]?: never;
+} ? [
+] : [
+    properties?: T
+] : [
+    properties: T
+];
+/**
+ * Configuration for {@linkcode createRemoteClient}.
+ */
 export type RemoteClientOptions = {
+    /**
+     * 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;
+    /**
+     * Timeout in milliseconds for the Decide API (optional).
+     *
+     * Defaults to `500` in production and `1000` in development.
+     */
     timeout?: number;
 };
+/**
+ * Create a remote client.
+ *
+ * @param options
+ *   Configuration (optional).
+ * @returns
+ *   Client.
+ */
 export declare function createRemoteClient(options?: RemoteClientOptions): import("@arcjet/protocol/client.js").Client;
 /**
- * The options used to configure an {@link ArcjetAstro} client.
+ * Configuration for the Astro integration of Arcjet.
+ *
+ * @template Rules
+ *   List of rules.
+ * @template Characteristics
+ *   Characteristics to track a user by.
  */
 export type ArcjetOptions<Rules extends [...Array<Primitive | Product>], Characteristics extends readonly string[]> = Simplify<CoreOptions<Rules, Characteristics> & {
     /**
-     * One or more IP Address of trusted proxies in front of the application.
-     * These addresses will be excluded when Arcjet detects a public IP address.
+     * IP addresses and CIDR ranges of trusted load balancers and proxies
+     * (optional, example: `["100.100.100.100", "100.100.100.0/24"]`).
      */
     proxies?: Array<string>;
 }>;
 /**
- * The ArcjetAstro client provides a public `protect()` method to
- * make a decision about how an Astro request should be handled.
+ * Instance of the Astro integration of Arcjet.
+ *
+ * Primarily has a `protect()` method to make a decision about how a request
+ * should be handled.
+ *
+ * @template Props
+ *   Configuration.
  */
 export interface ArcjetAstro<Props extends PlainObject> {
     /**
-     * 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.
+     * Make a decision about how to handle a request.
      *
-     * @param request - A `Request` provided to the fetch handler.
-     * @param props - Additonal properties required for running rules against a request.
-     * @returns An {@link ArcjetDecision} indicating Arcjet's decision about the request.
+     * This will analyze the request locally where possible and otherwise call
+     * the Arcjet decision API.
+     *
+     * @param ctx
+     *   Additional context for this function call.
+     * @param request
+     *   Details about the {@linkcode ArcjetRequest} that Arcjet needs to make a
+     *   decision.
+     * @returns
+     *   Promise that resolves to an {@linkcode ArcjetDecision} indicating
+     *   Arcjet’s decision about the request.
      */
-    protect(request: Request, ...props: Props extends WithoutCustomProps ? [] : [Props]): Promise<ArcjetDecision>;
+    protect(request: Request, ...props: MaybeProperties<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.
+     * Augment the client with another rule.
+     *
+     * Useful for varying rules based on criteria in your handler such as
+     * different rate limit for logged in users.
      *
-     * @param rule The rule to add to this execution.
-     * @returns An augmented {@link ArcjetAstro} client.
+     * @template Rule
+     *   Type of rule.
+     * @param rule
+     *   Rule to add to Arcjet.
+     * @returns
+     *   Arcjet instance augmented with the given rule.
      */
-    withRule<Rule extends Primitive | Product>(rule: Rule): ArcjetAstro<Simplify<Props & ExtraProps<Rule>>>;
+    withRule<ChildProperties extends PlainObject>(rule: Primitive<ChildProperties> | Product<ChildProperties>): ArcjetAstro<Props & ChildProperties>;
 }
 /**
- * Create a new {@link ArcjetAstro} 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.
+ * Create a new Astro integration of Arcjet.
  *
- * @param options - Arcjet configuration options to apply to all requests.
+ * @template Rules
+ *   List of rules.
+ * @template Characteristics
+ *   Characteristics to track a user by.
+ * @param options
+ *   Configuration.
+ * @returns
+ *   Astro integration of Arcjet.
  */
-export declare function createArcjetClient<const Rules extends (Primitive | Product)[], const Characteristics extends readonly string[]>(options: ArcjetOptions<Rules, Characteristics>): ArcjetAstro<Simplify<ExtraProps<Rules> & CharacteristicProps<Characteristics>>>;
+export declare function createArcjetClient<const Rules extends (Primitive | Product)[], const Characteristics extends readonly string[]>(options: ArcjetOptions<Rules, Characteristics>): ArcjetAstro<ExtraProps<Rules> & CharacteristicProps<Characteristics>>;