@composurecdk/wafv2 0.0.0-stage → 0.13.0

package/dist/esm/names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"names.d.ts","sourceRoot":"","sources":["../../src/names.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AA6CvD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAElD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAOpD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAIxD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEtD;AAuBD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAgBnD"}

package/dist/esm/names.js

@@ -0,0 +1,132 @@
+import { charSets, sanitizeString, stringConstraint, validateString, } from "@composurecdk/cloudformation";
+import { Names, Token } from "aws-cdk-lib";
+/**
+ * The name rule WAF applies to web ACLs and to the rules in them: 1–128
+ * characters from `[\w-]`.
+ */
+const WAF_NAME_RULE = {
+    charClass: `${charSets.ALNUM}_\\-`,
+    minLength: 1,
+    maxLength: 128,
+    allowed: "ASCII letters, digits, _ and -",
+};
+/**
+ * AWS-property constraint for a web ACL's name. Module-private; the package
+ * exposes {@link validateWebAclName} through the `constraints` namespace. See
+ * ADR-0010.
+ */
+const WEB_ACL_NAME = stringConstraint({
+    name: "WAFv2 WebACL Name",
+    ...WAF_NAME_RULE,
+    source: "https://docs.aws.amazon.com/waf/latest/APIReference/API_CreateWebACL.html",
+});
+/** AWS-property constraint for a rule's name within a web ACL. */
+const RULE_NAME = stringConstraint({
+    name: "WAFv2 WebACL Rule Name",
+    ...WAF_NAME_RULE,
+    source: "https://docs.aws.amazon.com/waf/latest/APIReference/API_Rule.html",
+});
+/**
+ * AWS-property constraint for a `VisibilityConfig` metric name. The API
+ * accepts a looser set, but the Developer Guide restricts metric names to
+ * these characters, and CloudWatch is where they end up.
+ */
+const METRIC_NAME = stringConstraint({
+    name: "WAFv2 VisibilityConfig MetricName",
+    ...WAF_NAME_RULE,
+    source: "https://docs.aws.amazon.com/waf/latest/APIReference/API_VisibilityConfig.html",
+});
+/** Metric names WAF reserves for its own aggregate metrics. */
+const RESERVED_METRIC_NAMES = ["All", "Default_Action"];
+/**
+ * Validates a web ACL name.
+ *
+ * @throws on invalid input.
+ */
+export function validateWebAclName(raw) {
+    validateString(raw, WEB_ACL_NAME);
+}
+/**
+ * Validates the name of a rule in a web ACL.
+ *
+ * @throws on invalid input.
+ */
+export function validateRuleName(raw) {
+    validateString(raw, RULE_NAME);
+}
+/**
+ * Validates a CloudWatch metric name for a web ACL or rule. `All` and
+ * `Default_Action` are rejected: WAF uses them for its own metrics.
+ *
+ * @throws on invalid input.
+ */
+export function validateMetricName(raw) {
+    validateString(raw, METRIC_NAME);
+    if (!Token.isUnresolved(raw) && RESERVED_METRIC_NAMES.includes(raw)) {
+        throw new Error(`${METRIC_NAME.name} "${raw}" is reserved by AWS WAF. Reserved: ${RESERVED_METRIC_NAMES.join(", ")}. See ${METRIC_NAME.source}.`);
+    }
+}
+/**
+ * The web ACL's name when it is a literal, and otherwise a name derived from
+ * its construct path, unique in the app. The base of its default metric and
+ * log group names.
+ *
+ * @internal
+ */
+export function webAclBaseName(webAcl) {
+    const { name } = webAcl;
+    if (name !== undefined && !Token.isUnresolved(name))
+        return name;
+    return Names.uniqueResourceName(webAcl, { maxLength: 128 });
+}
+/**
+ * Turns a construct path or other derived string into a legal metric name, for
+ * when the user has not chosen one.
+ *
+ * @internal
+ */
+export function sanitizeMetricName(raw) {
+    return sanitizeString(raw, METRIC_NAME, "");
+}
+const LABEL_SOURCE = "https://docs.aws.amazon.com/waf/latest/developerguide/waf-rule-label-requirements.html";
+/** Each colon-separated part of a rule label: a namespace or the name. */
+const LABEL_PART = stringConstraint({
+    name: "WAFv2 rule label part",
+    ...WAF_NAME_RULE,
+    source: LABEL_SOURCE,
+});
+const RESERVED_LABEL_WORDS = [
+    "awswaf",
+    "aws",
+    "waf",
+    "rulegroup",
+    "webacl",
+    "regexpatternset",
+    "ipset",
+    "managed",
+];
+const MAX_LABEL_NAMESPACES = 5;
+/**
+ * Validates a label a rule adds to matching requests: up to five
+ * colon-separated namespaces and a name, each 1–128 characters of
+ * `[A-Za-z0-9_-]`, none of them one of WAF's reserved words. WAF adds the
+ * `awswaf:<account>:webacl:<name>:` prefix itself, so it is not part of the
+ * label.
+ *
+ * @throws on invalid input.
+ */
+export function validateRuleLabel(raw) {
+    if (Token.isUnresolved(raw))
+        return;
+    const components = raw.split(":");
+    if (components.length > MAX_LABEL_NAMESPACES + 1) {
+        throw new Error(`WAFv2 rule label "${raw}" has ${String(components.length - 1)} namespaces; at most ${String(MAX_LABEL_NAMESPACES)} are allowed. See ${LABEL_SOURCE}.`);
+    }
+    for (const component of components) {
+        validateString(component, LABEL_PART);
+        if (RESERVED_LABEL_WORDS.includes(component)) {
+            throw new Error(`WAFv2 rule label "${raw}" uses "${component}", which AWS WAF reserves. Reserved: ${RESERVED_LABEL_WORDS.join(", ")}. See ${LABEL_SOURCE}.`);
+        }
+    }
+}
+//# sourceMappingURL=names.js.map

package/dist/esm/names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"names.js","sourceRoot":"","sources":["../../src/names.ts"],"names":[],"mappings":"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"}

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/esm/rule-builder.d.ts

@@ -0,0 +1,123 @@
+import type { CfnWebACL } from "aws-cdk-lib/aws-wafv2";
+import { COPY_STATE, type IBuilder } from "@composurecdk/core";
+import type { CustomResponseBody, CustomResponseBodies } from "./custom-response.js";
+import type { WebAclRuleAlarmConfig } from "./alarm-config.js";
+/** The action a rule takes on a request that matches its statement. */
+export type WebAclRuleAction = "block" | "allow" | "count" | "captcha" | "challenge";
+/**
+ * Configuration for one rule in a web ACL. The statement, action, custom
+ * response and labels are set with the builder's methods; these are the rest.
+ */
+export interface WebAclRuleBuilderProps {
+    /**
+     * The rule's priority. WAF evaluates rules from the lowest priority up.
+     * Defaults to ten times the rule's position in `addRule` order, so rules
+     * run in the order they are declared. Must be unique within the web ACL.
+     */
+    priority?: number;
+    /**
+     * The name of the rule's CloudWatch metrics. Defaults to the rule's name.
+     */
+    metricName?: string;
+    /**
+     * Whether WAF keeps a sample of the requests this rule matches. Defaults to
+     * the web ACL's `sampledRequests`, which is off.
+     */
+    sampledRequests?: boolean;
+    /** CAPTCHA immunity for this rule, overriding the web ACL's. */
+    captchaConfig?: CfnWebACL.RuleProperty["captchaConfig"];
+    /** Challenge immunity for this rule, overriding the web ACL's. */
+    challengeConfig?: CfnWebACL.RuleProperty["challengeConfig"];
+    /**
+     * This rule's recommended alarms: a `BlockedRequests` alarm, on by default
+     * for a rule you wrote that blocks and opt-in for a rule-group rule, and a
+     * `DaysToExpiry` alarm for a pinned managed rule group version. `false`
+     * disables both.
+     */
+    alarms?: WebAclRuleAlarmConfig | false;
+}
+/** What the web ACL builder knows when it turns a rule into CloudFormation. */
+export interface RuleBuildContext {
+    /** The rule's name, as given to `addRule`. */
+    readonly name: string;
+    /** Names the web ACL in error messages. */
+    readonly owner: string;
+    /** The priority to use unless the rule sets its own. */
+    readonly defaultPriority: number;
+    /** The web ACL's sampling setting, which the rule inherits. */
+    readonly sampledRequests: boolean;
+    /** Where custom response bodies are collected. */
+    readonly bodies: CustomResponseBodies;
+}
+/** A rule turned into CloudFormation, with what the web ACL needs to know about it. */
+export interface BuiltRule {
+    readonly property: CfnWebACL.RuleProperty & {
+        readonly priority: number;
+    };
+    /** The rule's CloudWatch metric name: the `Rule` dimension of its metrics. */
+    readonly metricName: string;
+    readonly sampled: boolean;
+    readonly rateBased: boolean;
+    /** Whether the rule evaluates a rule group, so takes `overrideAction`. */
+    readonly ruleGroup: boolean;
+    /** Whether matching requests are blocked: by the rule, or by a rule group's own rules. */
+    readonly blocks: boolean;
+    /** The rule's recommended alarm configuration. */
+    readonly alarms: WebAclRuleAlarmConfig | false | undefined;
+}
+declare class WebAclRuleBuilder {
+    #private;
+    props: Partial<WebAclRuleBuilderProps>;
+    /**
+     * Sets the rule's statement as raw CloudFormation, for a statement this
+     * builder has no helper for. Fields CDK types as `any` — `singleHeader`,
+     * `queryString`, `uriPath`, `method` and the like — pass through verbatim,
+     * so they must use CloudFormation's PascalCase (`{ Name: "x-api-key" }`).
+     *
+     * A rule has exactly one statement; setting a second throws.
+     */
+    statement(statement: CfnWebACL.StatementProperty): this;
+    /** Blocks matching requests. This is the default action. */
+    block(): this;
+    /** Allows matching requests, ending evaluation of the web ACL. */
+    allow(): this;
+    /**
+     * Counts matching requests and carries on evaluating. On a rule-group rule
+     * this counts every rule in the group instead of applying its actions.
+     */
+    count(): this;
+    /** Answers matching requests with a CAPTCHA puzzle. */
+    captcha(): this;
+    /** Answers matching requests with a silent browser challenge. */
+    challenge(): this;
+    /**
+     * Blocks matching requests with a custom response instead of WAF's `403`.
+     * The body is collected into the web ACL's `customResponseBodies`, so
+     * nothing has to be declared there by hand.
+     *
+     * @param status - One of the status codes WAF supports; `410` is not.
+     * @param body - `{ json }`, `{ text }` or `{ html }`; at most 4 KB.
+     * @param headers - At most 10, and not `content-type`.
+     */
+    respond(status: number, body?: CustomResponseBody, headers?: Record<string, string>): this;
+    /**
+     * Adds labels to matching requests, for later rules to match on with a
+     * label match statement. Give the namespaces and name only, such as
+     * `"auth:missing-token"`; WAF adds the web ACL prefix.
+     */
+    labels(...labels: string[]): this;
+    /** @internal — see ADR-0005. */
+    [COPY_STATE](target: WebAclRuleBuilder): void;
+    /** @internal — the web ACL builder turns each rule into CloudFormation. */
+    toRule(ctx: RuleBuildContext): BuiltRule;
+}
+type FullWebAclRuleBuilder = IBuilder<WebAclRuleBuilderProps, WebAclRuleBuilder>;
+/**
+ * Fluent configuration for one rule in a web ACL, passed to the callback of
+ * {@link IWebAclBuilder.addRule}.
+ */
+export type IWebAclRuleBuilder = Omit<FullWebAclRuleBuilder, "toRule">;
+/** @internal — the web ACL builder makes one of these per rule. */
+export declare function createWebAclRuleBuilder(): FullWebAclRuleBuilder;
+export {};
+//# sourceMappingURL=rule-builder.d.ts.map

package/dist/esm/rule-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-builder.d.ts","sourceRoot":"","sources":["../../src/rule-builder.ts"],"names":[],"mappings":"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"}

package/dist/esm/rule-builder.js

@@ -0,0 +1,160 @@
+import { Builder, COPY_STATE } from "@composurecdk/core";
+import { WEB_ACL_VISIBILITY_DEFAULTS } from "./defaults.js";
+import { validateMetricName, validateRuleLabel } from "./names.js";
+const RULE_GROUP_STATEMENTS = ["managedRuleGroupStatement", "ruleGroupReferenceStatement"];
+/** Whether `statement` evaluates a rule group, so its rule takes `overrideAction`. */
+function isRuleGroupStatement(statement) {
+    return RULE_GROUP_STATEMENTS.some((key) => statement[key] !== undefined);
+}
+class WebAclRuleBuilder {
+    props = {};
+    #statement;
+    #action;
+    #response;
+    #labels = [];
+    /**
+     * Sets the rule's statement as raw CloudFormation, for a statement this
+     * builder has no helper for. Fields CDK types as `any` — `singleHeader`,
+     * `queryString`, `uriPath`, `method` and the like — pass through verbatim,
+     * so they must use CloudFormation's PascalCase (`{ Name: "x-api-key" }`).
+     *
+     * A rule has exactly one statement; setting a second throws.
+     */
+    statement(statement) {
+        this.#setStatement("statement", statement);
+        return this;
+    }
+    /** Blocks matching requests. This is the default action. */
+    block() {
+        return this.#setAction("block");
+    }
+    /** Allows matching requests, ending evaluation of the web ACL. */
+    allow() {
+        return this.#setAction("allow");
+    }
+    /**
+     * Counts matching requests and carries on evaluating. On a rule-group rule
+     * this counts every rule in the group instead of applying its actions.
+     */
+    count() {
+        return this.#setAction("count");
+    }
+    /** Answers matching requests with a CAPTCHA puzzle. */
+    captcha() {
+        return this.#setAction("captcha");
+    }
+    /** Answers matching requests with a silent browser challenge. */
+    challenge() {
+        return this.#setAction("challenge");
+    }
+    /**
+     * Blocks matching requests with a custom response instead of WAF's `403`.
+     * The body is collected into the web ACL's `customResponseBodies`, so
+     * nothing has to be declared there by hand.
+     *
+     * @param status - One of the status codes WAF supports; `410` is not.
+     * @param body - `{ json }`, `{ text }` or `{ html }`; at most 4 KB.
+     * @param headers - At most 10, and not `content-type`.
+     */
+    respond(status, body, headers) {
+        if (this.#action !== undefined && this.#action !== "block") {
+            throw new Error(`respond() blocks the request, but the rule's action is already "${this.#action}". A custom response is only available on Block.`);
+        }
+        this.#action = "block";
+        this.#response = { status, body, headers };
+        return this;
+    }
+    /**
+     * Adds labels to matching requests, for later rules to match on with a
+     * label match statement. Give the namespaces and name only, such as
+     * `"auth:missing-token"`; WAF adds the web ACL prefix.
+     */
+    labels(...labels) {
+        for (const label of labels)
+            validateRuleLabel(label);
+        this.#labels.push(...labels);
+        return this;
+    }
+    /** @internal — see ADR-0005. */
+    [COPY_STATE](target) {
+        target.#statement = this.#statement;
+        target.#action = this.#action;
+        target.#response = this.#response;
+        target.#labels.push(...this.#labels);
+    }
+    #setStatement(method, statement) {
+        if (this.#statement !== undefined) {
+            throw new Error(`${method}(): the rule already has a statement. A rule has exactly one; combine conditions with an AndStatement or OrStatement.`);
+        }
+        this.#statement = statement;
+    }
+    #setAction(action) {
+        if (this.#response !== undefined && action !== "block") {
+            throw new Error(`${action}(): the rule already has a custom response from respond(), which only applies to Block.`);
+        }
+        this.#action = action;
+        return this;
+    }
+    /** @internal — the web ACL builder turns each rule into CloudFormation. */
+    toRule(ctx) {
+        const who = `rule "${ctx.name}"`;
+        const statement = this.#statement;
+        if (statement === undefined) {
+            throw new Error(`${ctx.owner} ${who} has no statement. Give it one, such as .statement({ ... }).`);
+        }
+        const metricName = this.props.metricName ?? ctx.name;
+        validateMetricName(metricName);
+        const sampled = this.props.sampledRequests ?? ctx.sampledRequests;
+        const rateBased = statement.rateBasedStatement !== undefined;
+        const ruleGroup = isRuleGroupStatement(statement);
+        const { blocks, ...action } = this.#actionProperty(ctx, who, ruleGroup, rateBased);
+        const property = {
+            name: ctx.name,
+            priority: this.props.priority ?? ctx.defaultPriority,
+            statement,
+            ...action,
+            visibilityConfig: {
+                ...WEB_ACL_VISIBILITY_DEFAULTS,
+                metricName,
+                sampledRequestsEnabled: sampled,
+            },
+            ...(this.#labels.length > 0 && { ruleLabels: this.#labels.map((name) => ({ name })) }),
+            ...(this.props.captchaConfig && { captchaConfig: this.props.captchaConfig }),
+            ...(this.props.challengeConfig && { challengeConfig: this.props.challengeConfig }),
+        };
+        return {
+            property,
+            metricName,
+            sampled,
+            rateBased,
+            ruleGroup,
+            blocks,
+            alarms: this.props.alarms,
+        };
+    }
+    #actionProperty(ctx, who, ruleGroup, rateBased) {
+        if (ruleGroup) {
+            if (this.#action !== undefined && this.#action !== "count") {
+                throw new Error(`${ctx.owner} ${who} evaluates a rule group, whose rules keep their own actions. ` +
+                    `Use .count() to count them all instead, or leave the action unset.`);
+            }
+            // The group's own rules block unless the whole group is counted.
+            return this.#action === "count"
+                ? { overrideAction: { count: {} }, blocks: false }
+                : { overrideAction: { none: {} }, blocks: true };
+        }
+        const action = this.#action ?? "block";
+        if (action === "allow" && rateBased) {
+            throw new Error(`${ctx.owner} ${who} is rate-based, and a rate-based rule cannot Allow. Use block, count, captcha or challenge.`);
+        }
+        if (action !== "block")
+            return { action: { [action]: {} }, blocks: false };
+        return { action: { block: ctx.bodies.block(who, ctx.name, this.#response) }, blocks: true };
+    }
+}
+/** @internal — the web ACL builder makes one of these per rule. */
+export function createWebAclRuleBuilder() {
+    // eslint-disable-next-line composurecdk/builder-must-be-tagged -- a rule is a property of AWS::WAFv2::WebACL, not a taggable resource
+    return Builder(WebAclRuleBuilder);
+}
+//# sourceMappingURL=rule-builder.js.map

package/dist/esm/rule-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-builder.js","sourceRoot":"","sources":["../../src/rule-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,UAAU,EAAiB,MAAM,oBAAoB,CAAC;AAOxE,OAAO,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAwEnE,MAAM,qBAAqB,GAAG,CAAC,2BAA2B,EAAE,6BAA6B,CAAU,CAAC;AAEpG,sFAAsF;AACtF,SAAS,oBAAoB,CAAC,SAAsC;IAClE,OAAO,qBAAqB,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC,CAAC;AAC3E,CAAC;AAED,MAAM,iBAAiB;IACrB,KAAK,GAAoC,EAAE,CAAC;IAC5C,UAAU,CAA+B;IACzC,OAAO,CAAoB;IAC3B,SAAS,CAAkB;IAClB,OAAO,GAAa,EAAE,CAAC;IAEhC;;;;;;;OAOG;IACH,SAAS,CAAC,SAAsC;QAC9C,IAAI,CAAC,aAAa,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;QAC3C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,4DAA4D;IAC5D,KAAK;QACH,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;IAED,kEAAkE;IAClE,KAAK;QACH,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;IAED;;;OAGG;IACH,KAAK;QACH,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;IAED,uDAAuD;IACvD,OAAO;QACL,OAAO,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IACpC,CAAC;IAED,iEAAiE;IACjE,SAAS;QACP,OAAO,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;IACtC,CAAC;IAED;;;;;;;;OAQG;IACH,OAAO,CAAC,MAAc,EAAE,IAAyB,EAAE,OAAgC;QACjF,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,IAAI,CAAC,OAAO,KAAK,OAAO,EAAE,CAAC;YAC3D,MAAM,IAAI,KAAK,CACb,mEAAmE,IAAI,CAAC,OAAO,kDAAkD,CAClI,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,SAAS,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;QAC3C,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,GAAG,MAAgB;QACxB,KAAK,MAAM,KAAK,IAAI,MAAM;YAAE,iBAAiB,CAAC,KAAK,CAAC,CAAC;QACrD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,gCAAgC;IAChC,CAAC,UAAU,CAAC,CAAC,MAAyB;QACpC,MAAM,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QACpC,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC9B,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAClC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IACvC,CAAC;IAED,aAAa,CAAC,MAAc,EAAE,SAAsC;QAClE,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CACb,GAAG,MAAM,uHAAuH,CACjI,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;IAC9B,CAAC;IAED,UAAU,CAAC,MAAwB;QACjC,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;YACvD,MAAM,IAAI,KAAK,CACb,GAAG,MAAM,yFAAyF,CACnG,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,2EAA2E;IAC3E,MAAM,CAAC,GAAqB;QAC1B,MAAM,GAAG,GAAG,SAAS,GAAG,CAAC,IAAI,GAAG,CAAC;QACjC,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC;QAClC,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CACb,GAAG,GAAG,CAAC,KAAK,IAAI,GAAG,8DAA8D,CAClF,CAAC;QACJ,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,GAAG,CAAC,IAAI,CAAC;QACrD,kBAAkB,CAAC,UAAU,CAAC,CAAC;QAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,eAAe,IAAI,GAAG,CAAC,eAAe,CAAC;QAClE,MAAM,SAAS,GAAG,SAAS,CAAC,kBAAkB,KAAK,SAAS,CAAC;QAC7D,MAAM,SAAS,GAAG,oBAAoB,CAAC,SAAS,CAAC,CAAC;QAElD,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;QACnF,MAAM,QAAQ,GAAG;YACf,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,IAAI,GAAG,CAAC,eAAe;YACpD,SAAS;YACT,GAAG,MAAM;YACT,gBAAgB,EAAE;gBAChB,GAAG,2BAA2B;gBAC9B,UAAU;gBACV,sBAAsB,EAAE,OAAO;aAChC;YACD,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;YACtF,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,aAAa,IAAI,EAAE,aAAa,EAAE,IAAI,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC;YAC5E,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,eAAe,IAAI,EAAE,eAAe,EAAE,IAAI,CAAC,KAAK,CAAC,eAAe,EAAE,CAAC;SACnF,CAAC;QACF,OAAO;YACL,QAAQ;YACR,UAAU;YACV,OAAO;YACP,SAAS;YACT,SAAS;YACT,MAAM;YACN,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM;SAC1B,CAAC;IACJ,CAAC;IAED,eAAe,CACb,GAAqB,EACrB,GAAW,EACX,SAAkB,EAClB,SAAkB;QAElB,IAAI,SAAS,EAAE,CAAC;YACd,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,IAAI,CAAC,OAAO,KAAK,OAAO,EAAE,CAAC;gBAC3D,MAAM,IAAI,KAAK,CACb,GAAG,GAAG,CAAC,KAAK,IAAI,GAAG,+DAA+D;oBAChF,oEAAoE,CACvE,CAAC;YACJ,CAAC;YACD,iEAAiE;YACjE,OAAO,IAAI,CAAC,OAAO,KAAK,OAAO;gBAC7B,CAAC,CAAC,EAAE,cAAc,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE;gBAClD,CAAC,CAAC,EAAE,cAAc,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;QACrD,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC;QACvC,IAAI,MAAM,KAAK,OAAO,IAAI,SAAS,EAAE,CAAC;YACpC,MAAM,IAAI,KAAK,CACb,GAAG,GAAG,CAAC,KAAK,IAAI,GAAG,6FAA6F,CACjH,CAAC;QACJ,CAAC;QACD,IAAI,MAAM,KAAK,OAAO;YAAE,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;QAC3E,OAAO,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAC9F,CAAC;CACF;AAWD,mEAAmE;AACnE,MAAM,UAAU,uBAAuB;IACrC,sIAAsI;IACtI,OAAO,OAAO,CAA4C,iBAAiB,CAAC,CAAC;AAC/E,CAAC"}

package/dist/esm/scope.d.ts

@@ -0,0 +1,15 @@
+import type { IConstruct } from "constructs";
+/** Where a web ACL can be used: CloudFront distributions, or regional resources. */
+export type WebAclScope = "REGIONAL" | "CLOUDFRONT";
+/**
+ * Throws when a CLOUDFRONT web ACL's stack is in a known region other than
+ * `us-east-1`, and warns when the region cannot be known at synth.
+ *
+ * Env-agnostic stacks fall back to `CDK_DEFAULT_REGION`, which the CDK toolkit
+ * uses to fill the deploy region, as `@composurecdk/route53`'s query logging
+ * does.
+ *
+ * @internal
+ */
+export declare function checkCloudFrontRegion(scope: IConstruct, id: string): void;
+//# sourceMappingURL=scope.d.ts.map

package/dist/esm/scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../src/scope.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,oFAAoF;AACpF,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,YAAY,CAAC;AAOpD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAqBzE"}

package/dist/esm/scope.js

@@ -0,0 +1,32 @@
+import { Annotations, Stack, Token } from "aws-cdk-lib";
+const CLOUDFRONT_REGION = "us-east-1";
+const REGION_ANNOTATION = "@composurecdk/wafv2:cloudfront-region";
+const SOURCE = "https://docs.aws.amazon.com/waf/latest/developerguide/how-aws-waf-works-resources.html";
+/**
+ * Throws when a CLOUDFRONT web ACL's stack is in a known region other than
+ * `us-east-1`, and warns when the region cannot be known at synth.
+ *
+ * Env-agnostic stacks fall back to `CDK_DEFAULT_REGION`, which the CDK toolkit
+ * uses to fill the deploy region, as `@composurecdk/route53`'s query logging
+ * does.
+ *
+ * @internal
+ */
+export function checkCloudFrontRegion(scope, id) {
+    const stackRegion = Stack.of(scope).region;
+    const region = Token.isUnresolved(stackRegion) ? process.env.CDK_DEFAULT_REGION : stackRegion;
+    if (region === undefined || region === "") {
+        Annotations.of(scope).addWarningV2(REGION_ANNOTATION, `WebAclBuilder "${id}" has scope CLOUDFRONT, which AWS WAF only accepts in ` +
+            `${CLOUDFRONT_REGION}. This stack is env-agnostic and CDK_DEFAULT_REGION is not ` +
+            `set, so the region cannot be checked at synth. Pin env: { region: ` +
+            `"${CLOUDFRONT_REGION}" } on the stack to silence this warning.`);
+        return;
+    }
+    if (region !== CLOUDFRONT_REGION) {
+        throw new Error(`WebAclBuilder "${id}" has scope CLOUDFRONT, but its stack is in "${region}". ` +
+            `AWS WAF only creates CloudFront web ACLs in ${CLOUDFRONT_REGION}. Deploy this ` +
+            `web ACL from a ${CLOUDFRONT_REGION} stack and pass its ARN to the distribution's ` +
+            `webAclId. See ${SOURCE}.`);
+    }
+}
+//# sourceMappingURL=scope.js.map

package/dist/esm/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.js","sourceRoot":"","sources":["../../src/scope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAMxD,MAAM,iBAAiB,GAAG,WAAW,CAAC;AACtC,MAAM,iBAAiB,GAAG,uCAAuC,CAAC;AAClE,MAAM,MAAM,GACV,wFAAwF,CAAC;AAE3F;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAiB,EAAE,EAAU;IACjE,MAAM,WAAW,GAAG,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC;IAC3C,MAAM,MAAM,GAAG,KAAK,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC,CAAC,WAAW,CAAC;IAC9F,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;QAC1C,WAAW,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,YAAY,CAChC,iBAAiB,EACjB,kBAAkB,EAAE,wDAAwD;YAC1E,GAAG,iBAAiB,6DAA6D;YACjF,oEAAoE;YACpE,IAAI,iBAAiB,2CAA2C,CACnE,CAAC;QACF,OAAO;IACT,CAAC;IACD,IAAI,MAAM,KAAK,iBAAiB,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CACb,kBAAkB,EAAE,gDAAgD,MAAM,KAAK;YAC7E,+CAA+C,iBAAiB,gBAAgB;YAChF,kBAAkB,iBAAiB,gDAAgD;YACnF,iBAAiB,MAAM,GAAG,CAC7B,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/esm/web-acl-builder.d.ts

@@ -0,0 +1,152 @@
+import type { Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import type { LogGroup } from "aws-cdk-lib/aws-logs";
+import { type CfnLoggingConfiguration, CfnWebACL, type CfnWebACLAssociation, type CfnWebACLProps } from "aws-cdk-lib/aws-wafv2";
+import type { IConstruct } from "constructs";
+import { COPY_STATE, type Lifecycle, type Resolvable } from "@composurecdk/core";
+import { type ITaggedBuilder } from "@composurecdk/cloudformation";
+import { type AlarmConfigurer } from "@composurecdk/cloudwatch";
+import type { WebAclAlarmConfig } from "./alarm-config.js";
+import { type WebAclAssociationTarget } from "./association.js";
+import { type CustomResponse } from "./custom-response.js";
+import { type IWebAclRuleBuilder } from "./rule-builder.js";
+import { type WebAclLoggingConfig } from "./logging.js";
+import { type WebAclMetrics } from "./metrics.js";
+import { type WebAclScope } from "./scope.js";
+/**
+ * Configuration for {@link createWebAclBuilder}: CDK's `CfnWebACLProps`, less
+ * what the builder owns. Rules, the default action and associations have
+ * their own methods; custom response bodies and the visibility config are
+ * generated.
+ */
+export interface WebAclBuilderProps extends Omit<CfnWebACLProps, "scope" | "defaultAction" | "rules" | "customResponseBodies" | "visibilityConfig" | "tags"> {
+    /**
+     * `REGIONAL` (the default) for API Gateway, Application Load Balancers,
+     * AppSync, Cognito, App Runner and Verified Access; `CLOUDFRONT` for
+     * CloudFront distributions, which must be deployed in `us-east-1`.
+     */
+    scope?: WebAclScope;
+    /**
+     * The name of the web ACL's CloudWatch metrics. Defaults to its `name` when
+     * that is set, and otherwise to a name derived from its construct path, so
+     * two web ACLs never share metrics.
+     */
+    metricName?: string;
+    /**
+     * Whether WAF keeps samples of the requests the web ACL and its rules
+     * inspect. Off by default: samples keep every header, and logging's
+     * redaction does not apply to them. Turning it on without a
+     * `dataProtectionConfig` warns.
+     */
+    sampledRequests?: boolean;
+    /**
+     * The web ACL's logging. On by default, to a created `aws-waf-logs-`
+     * CloudWatch log group, keeping only the requests WAF does not allow and
+     * redacting the `authorization` and `cookie` headers. `false` turns it off.
+     *
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/sec_detect_investigate_events_app_service_logging.html
+     */
+    logging?: WebAclLoggingConfig | false;
+    /**
+     * The master switch for the recommended alarms, which are configured per
+     * rule with the rule builder's `.alarms()`. `false` creates none; alarms
+     * added with `addAlarm()` are unaffected.
+     *
+     * No alarm actions are configured; apply them from the result or with
+     * `alarmActionsPolicy`.
+     */
+    recommendedAlarms?: WebAclAlarmConfig | false;
+}
+/** The build output of an {@link IWebAclBuilder}. */
+export interface WebAclBuilderResult {
+    /** The web ACL. */
+    webAcl: CfnWebACL;
+    /**
+     * One association per `associateWith` call, in that order. Empty for a
+     * CLOUDFRONT web ACL, which a distribution references by `webAclId`.
+     */
+    associations: CfnWebACLAssociation[];
+    /** The log group WAF writes to. Absent when logging is off or goes to your own destination. */
+    logGroup?: LogGroup;
+    /** The logging configuration. Absent when logging is off. */
+    logging?: CfnLoggingConfiguration;
+    /**
+     * The web ACL's metrics, for the ACL, the default action and each rule,
+     * with dimensions that match what WAF publishes.
+     */
+    metrics: WebAclMetrics;
+    /** The CloudWatch alarms created, recommended and custom, keyed by alarm key. */
+    alarms: Record<string, Alarm>;
+}
+/**
+ * A fluent builder for an AWS WAF web ACL.
+ *
+ * @see {@link createWebAclBuilder}
+ */
+export type IWebAclBuilder = ITaggedBuilder<WebAclBuilderProps, WebAclBuilder>;
+declare class WebAclBuilder implements Lifecycle<WebAclBuilderResult> {
+    #private;
+    props: Partial<WebAclBuilderProps>;
+    /**
+     * What happens to a request no rule decides on. `allow` is the default;
+     * `block` can answer with a custom response.
+     */
+    defaultAction(action: "allow" | "block", response?: CustomResponse): this;
+    /**
+     * Adds a rule. Rules are evaluated in the order they are added, unless a
+     * rule sets its own `.priority(n)`.
+     *
+     * @param name - Unique within the web ACL; also the rule's default metric name.
+     * @param configure - Sets the rule's statement, action and the rest.
+     */
+    addRule(name: string, configure: (rule: IWebAclRuleBuilder) => IWebAclRuleBuilder): this;
+    /**
+     * Protects a regional resource with this web ACL. Call it once per
+     * resource. Accepts an ARN, a CDK reference CloudFormation's
+     * `AWS::WAFv2::WebACLAssociation` takes (an Application Load Balancer, an
+     * AppSync API), or an API Gateway stage, as a concrete value or a `ref`.
+     *
+     * A CLOUDFRONT web ACL cannot be associated: pass its ARN to the
+     * distribution's `webAclId` instead.
+     */
+    associateWith(target: Resolvable<WebAclAssociationTarget>): this;
+    /**
+     * Adds a custom alarm. The metric factory receives the web ACL's
+     * {@link WebAclMetrics}, so a rule's metrics come by its name:
+     * `(m) => m.rule("PerIpRate").countedRequests()`.
+     */
+    addAlarm(key: string, configure: AlarmConfigurer<WebAclMetrics>): this;
+    /**
+     * Adds a set of custom alarms in one call: each entry exactly as if by
+     * `addAlarm(key, configure)`, in the record's iteration order.
+     */
+    addAlarms(alarms: Record<string, AlarmConfigurer<WebAclMetrics>>): this;
+    /** @internal — see ADR-0005. */
+    [COPY_STATE](target: WebAclBuilder): void;
+    build(scope: IConstruct, id: string, context?: Record<string, object>): WebAclBuilderResult;
+}
+/**
+ * Creates a builder for an AWS WAF web ACL, with its rules, its associations
+ * and the visibility settings the rest of the package relies on.
+ *
+ * By default the web ACL is regional, allows what no rule blocks, publishes
+ * CloudWatch metrics for itself and every rule ({@link WEB_ACL_VISIBILITY_DEFAULTS}),
+ * and keeps no sampled requests ({@link WEB_ACL_DEFAULTS}).
+ *
+ * @example
+ * ```ts
+ * createWebAclBuilder()
+ *   .associateWith(ref("api", (r: RestApiBuilderResult) => r.api.deploymentStage))
+ *   .addRule("BlockAdmin", (rule) =>
+ *     rule.statement({
+ *       byteMatchStatement: {
+ *         fieldToMatch: { uriPath: {} },
+ *         positionalConstraint: "STARTS_WITH",
+ *         searchString: "/admin",
+ *         textTransformations: [{ priority: 0, type: "NONE" }],
+ *       },
+ *     }).respond(404));
+ * ```
+ */
+export declare function createWebAclBuilder(): IWebAclBuilder;
+export {};
+//# sourceMappingURL=web-acl-builder.d.ts.map