@composurecdk/wafv2 0.0.0-stage → 0.13.0

package/dist/commonjs/logging.d.ts

@@ -0,0 +1,59 @@
+import { type CfnLoggingConfigurationProps, type CfnWebACL } from "aws-cdk-lib/aws-wafv2";
+import type { IConstruct } from "constructs";
+import { type Resolvable } from "@composurecdk/core";
+import { type ILogGroupBuilder } from "@composurecdk/logs";
+import { type WebAclLoggingFilter } from "./logging-filter.js";
+import type { WebAclBuilderResult } from "./web-acl-builder.js";
+/** Request fields to redact from the log. */
+export interface WebAclLogRedaction {
+    /**
+     * Header names to redact, **in addition to** `authorization` and `cookie`,
+     * which are always redacted.
+     */
+    readonly headers?: readonly string[];
+    /** Redact the query string. */
+    readonly queryString?: boolean;
+    /** Redact the URI path. */
+    readonly uriPath?: boolean;
+    /** Redact the HTTP method. */
+    readonly method?: boolean;
+}
+/**
+ * Configures the web ACL's logging. On by default: WAF writes the requests it
+ * does not allow to a created `aws-waf-logs-` CloudWatch log group, with the
+ * `authorization` and `cookie` headers redacted. `false` turns it off.
+ */
+export interface WebAclLoggingConfig {
+    /**
+     * Customize the created log group. It starts with an `aws-waf-logs-` name,
+     * which WAF requires, and the `@composurecdk/logs` retention and removal
+     * defaults. The callback's builder resolves `ref`s against the build
+     * context. Cannot be combined with {@link destination}.
+     */
+    readonly configure?: (b: ILogGroupBuilder) => ILogGroupBuilder;
+    /**
+     * Log to an existing destination instead of a created log group: a
+     * CloudWatch log group, S3 bucket or Firehose stream ARN, or a reference
+     * CDK's `CfnLoggingConfiguration` accepts. Its name must start with
+     * `aws-waf-logs-`, a log group ARN must not end in `:*`, an S3 bucket must
+     * use SSE-S3 or a customer managed key, and a Firehose stream must be
+     * DirectPut. Cannot be combined with {@link configure}.
+     */
+    readonly destination?: Resolvable<NonNullable<CfnLoggingConfigurationProps["logDestinationConfigs"]>[number]>;
+    /**
+     * Which requests to log. `"non-allow"`, the default, keeps every request
+     * WAF blocks, counts, or answers with a CAPTCHA or challenge, and drops the
+     * rest. `"all"` keeps everything.
+     */
+    readonly filter?: "non-allow" | "all" | WebAclLoggingFilter;
+    /** Fields to redact, merged with the defaults. */
+    readonly redact?: WebAclLogRedaction;
+}
+/**
+ * Creates the web ACL's logging configuration and, unless a destination was
+ * given, its log group.
+ *
+ * @internal
+ */
+export declare function configureLogging(scope: IConstruct, id: string, owner: string, webAcl: CfnWebACL, config: WebAclLoggingConfig | false, context: Record<string, object>): Pick<WebAclBuilderResult, "logGroup" | "logging">;
+//# sourceMappingURL=logging.d.ts.map

package/dist/commonjs/logging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.d.ts","sourceRoot":"","sources":["../../src/logging.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,4BAA4B,EACjC,KAAK,SAAS,EACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAW,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAyB,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAMlF,OAAO,EAAoB,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAEjF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,6CAA6C;AAC7C,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,+BAA+B;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,2BAA2B;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,gBAAgB,KAAK,gBAAgB,CAAC;IAE/D;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,UAAU,CAC/B,WAAW,CAAC,4BAA4B,CAAC,uBAAuB,CAAC,CAAC,CAAC,MAAM,CAAC,CAC3E,CAAC;IAEF;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,KAAK,GAAG,mBAAmB,CAAC;IAE5D,kDAAkD;IAClD,QAAQ,CAAC,MAAM,CAAC,EAAE,kBAAkB,CAAC;CACtC;AAwED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,mBAAmB,GAAG,KAAK,EACnC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,IAAI,CAAC,mBAAmB,EAAE,UAAU,GAAG,SAAS,CAAC,CAwBnD"}

package/dist/commonjs/logging.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configureLogging = configureLogging;
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const aws_wafv2_1 = require("aws-cdk-lib/aws-wafv2");
+const core_1 = require("@composurecdk/core");
+const logs_1 = require("@composurecdk/logs");
+const defaults_js_1 = require("./defaults.js");
+const logging_filter_js_1 = require("./logging-filter.js");
+const names_js_1 = require("./names.js");
+const MAX_REDACTED_FIELDS = 100;
+const LOGGING_SOURCE = "https://docs.aws.amazon.com/waf/latest/developerguide/logging.html";
+function loggingFilter(filter) {
+    if (filter === "all")
+        return undefined;
+    return (0, logging_filter_js_1.toFilterProperty)(typeof filter === "object" ? filter : defaults_js_1.DEFAULT_LOGGING_FILTER);
+}
+function redactedFields(owner, redact) {
+    const headers = new Map();
+    for (const name of [...defaults_js_1.DEFAULT_LOGGING_REDACTED_HEADERS, ...(redact?.headers ?? [])]) {
+        headers.set(name.toLowerCase(), name);
+    }
+    // `FieldToMatch`'s members are `any` in CDK, so `SingleHeader` needs CloudFormation's `Name`.
+    const fields = [...headers.values()].map((Name) => ({ singleHeader: { Name } }));
+    if (redact?.queryString)
+        fields.push({ queryString: {} });
+    if (redact?.uriPath)
+        fields.push({ uriPath: {} });
+    if (redact?.method)
+        fields.push({ method: {} });
+    if (fields.length > MAX_REDACTED_FIELDS) {
+        throw new Error(`${owner}: logging redacts ${String(fields.length)} fields; AWS WAF allows at most ${String(MAX_REDACTED_FIELDS)}. See ${LOGGING_SOURCE}.`);
+    }
+    return fields;
+}
+function checkLogGroupName(owner, name) {
+    // The builder always seeds a name, but `configure` can replace it with a token.
+    if (name === undefined || aws_cdk_lib_1.Token.isUnresolved(name))
+        return;
+    if (!name.startsWith(defaults_js_1.WAF_LOG_GROUP_NAME_PREFIX)) {
+        throw new Error(`${owner}: the WAF log group is named "${name}", but AWS WAF only logs to log groups ` +
+            `whose names start with "${defaults_js_1.WAF_LOG_GROUP_NAME_PREFIX}". Rename it, or leave the ` +
+            `name to the builder. See ${LOGGING_SOURCE}.`);
+    }
+}
+/**
+ * Creates the WAF log group and returns it with the ARN WAF accepts for it.
+ */
+function createLogGroup(scope, id, owner, webAcl, configure, context) {
+    let builder = (0, logs_1.createLogGroupBuilder)().logGroupName(`${defaults_js_1.WAF_LOG_GROUP_NAME_PREFIX}${(0, names_js_1.webAclBaseName)(webAcl)}`);
+    if (configure)
+        builder = configure(builder);
+    checkLogGroupName(owner, builder.logGroupName());
+    const logGroup = builder.build(scope, `${id}Logs`, context).logGroup;
+    // WAF rejects the `:*` that `logGroupArn` ends in.
+    const arn = logGroup.stack.formatArn({
+        service: "logs",
+        resource: "log-group",
+        resourceName: logGroup.logGroupName,
+        arnFormat: aws_cdk_lib_1.ArnFormat.COLON_RESOURCE_NAME,
+    });
+    return { logGroup, arn };
+}
+/**
+ * Creates the web ACL's logging configuration and, unless a destination was
+ * given, its log group.
+ *
+ * @internal
+ */
+function configureLogging(scope, id, owner, webAcl, config, context) {
+    if (config === false)
+        return {};
+    const { configure, destination, filter, redact } = config;
+    if (configure !== undefined && destination !== undefined) {
+        throw new Error(`${owner}: logging 'configure' cannot be combined with 'destination' — the ` +
+            `destination is user-managed and not built by this builder.`);
+    }
+    const { logGroup, arn } = destination === undefined
+        ? createLogGroup(scope, id, owner, webAcl, configure, context)
+        : { logGroup: undefined, arn: (0, core_1.resolve)(destination, context) };
+    const logging = new aws_wafv2_1.CfnLoggingConfiguration(scope, `${id}Logging`, {
+        resourceArn: webAcl.attrArn,
+        logDestinationConfigs: [arn],
+        loggingFilter: loggingFilter(filter),
+        redactedFields: redactedFields(owner, redact),
+    });
+    if (logGroup)
+        logging.node.addDependency(logGroup);
+    return { logGroup, logging };
+}
+//# sourceMappingURL=logging.js.map

package/dist/commonjs/logging.js.map

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

package/dist/commonjs/metrics.d.ts

@@ -0,0 +1,58 @@
+import { Duration } from "aws-cdk-lib";
+import { Metric, type MetricOptions } from "aws-cdk-lib/aws-cloudwatch";
+import type { CfnWebACL } from "aws-cdk-lib/aws-wafv2";
+/**
+ * The request-count metrics WAF publishes for a web ACL, a rule, or the
+ * default action. Each is a Sum over 5 minutes unless `options` say
+ * otherwise. WAF publishes a datapoint only when the count is non-zero.
+ *
+ * @see https://docs.aws.amazon.com/waf/latest/developerguide/waf-metrics.html
+ */
+export interface WebAclRequestMetrics {
+    allowedRequests(options?: MetricOptions): Metric;
+    blockedRequests(options?: MetricOptions): Metric;
+    countedRequests(options?: MetricOptions): Metric;
+    captchaRequests(options?: MetricOptions): Metric;
+    challengeRequests(options?: MetricOptions): Metric;
+}
+/**
+ * The metrics of a web ACL, with dimensions built from the names the builder
+ * gave it and its rules, so they match what WAF publishes. The top-level
+ * metrics cover every rule (`Rule=ALL`).
+ */
+export interface WebAclMetrics extends WebAclRequestMetrics {
+    /** Requests no rule terminated, which the default action decided. */
+    readonly defaultAction: WebAclRequestMetrics;
+    /**
+     * The metrics of one rule, by the name given to `addRule`.
+     *
+     * @throws when the web ACL has no rule of that name.
+     */
+    rule(name: string): WebAclRequestMetrics;
+    /**
+     * Days until a pinned managed rule group version expires. Published only
+     * for a group the web ACL uses at that version.
+     *
+     * @see https://docs.aws.amazon.com/waf/latest/developerguide/waf-using-managed-rule-groups-expiration.html
+     */
+    daysToExpiry(group: ManagedRuleGroupVersion, options?: MetricOptions): Metric;
+}
+/** A managed rule group at a pinned version. */
+export interface ManagedRuleGroupVersion {
+    readonly vendorName: string;
+    readonly name: string;
+    readonly version: string;
+}
+/** @internal — the period of every request metric unless overridden. */
+export declare const REQUEST_METRIC_PERIOD: Duration;
+/**
+ * Builds a web ACL's {@link WebAclMetrics}.
+ *
+ * @param metricName - The web ACL's own metric name, which WAF publishes the
+ *   default action's metrics under as the `Rule` dimension.
+ * @param ruleMetricNames - Each rule's metric name, by rule name.
+ *
+ * @internal
+ */
+export declare function webAclMetrics(webAcl: CfnWebACL, metricName: string, ruleMetricNames: ReadonlyMap<string, string>): WebAclMetrics;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/commonjs/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/metrics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAoB,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAS,MAAM,4BAA4B,CAAC;AAC/E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEvD;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,eAAe,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CAAC;IACjD,eAAe,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CAAC;IACjD,eAAe,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CAAC;IACjD,eAAe,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CAAC;IACjD,iBAAiB,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CAAC;CACpD;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAc,SAAQ,oBAAoB;IACzD,qEAAqE;IACrE,QAAQ,CAAC,aAAa,EAAE,oBAAoB,CAAC;IAE7C;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,CAAC;IAEzC;;;;;OAKG;IACH,YAAY,CAAC,KAAK,EAAE,uBAAuB,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CAAC;CAC/E;AAED,gDAAgD;AAChD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAGD,wEAAwE;AACxE,eAAO,MAAM,qBAAqB,UAAsB,CAAC;AAezD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAC3C,aAAa,CA8Cf"}

package/dist/commonjs/metrics.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REQUEST_METRIC_PERIOD = void 0;
+exports.webAclMetrics = webAclMetrics;
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const aws_cloudwatch_1 = require("aws-cdk-lib/aws-cloudwatch");
+const NAMESPACE = "AWS/WAFV2";
+/** @internal — the period of every request metric unless overridden. */
+exports.REQUEST_METRIC_PERIOD = aws_cdk_lib_1.Duration.minutes(5);
+const ALL_RULES = "ALL";
+/**
+ * The value of a web ACL's `WebACL` dimension: its name. WAF publishes the
+ * name here, not the `VisibilityConfig` metric name the documentation
+ * describes. A web ACL without a literal name reads it from `Ref`, which is
+ * `name|id|scope`.
+ */
+function webAclDimension(webAcl) {
+    const { name } = webAcl;
+    if (name !== undefined && !aws_cdk_lib_1.Token.isUnresolved(name))
+        return name;
+    return aws_cdk_lib_1.Fn.select(0, aws_cdk_lib_1.Fn.split("|", webAcl.ref));
+}
+/**
+ * Builds a web ACL's {@link WebAclMetrics}.
+ *
+ * @param metricName - The web ACL's own metric name, which WAF publishes the
+ *   default action's metrics under as the `Rule` dimension.
+ * @param ruleMetricNames - Each rule's metric name, by rule name.
+ *
+ * @internal
+ */
+function webAclMetrics(webAcl, metricName, ruleMetricNames) {
+    // CloudFront metrics have no `Region` dimension.
+    const regionDimension = webAcl.scope === "CLOUDFRONT" ? {} : { Region: aws_cdk_lib_1.Stack.of(webAcl).region };
+    const webAclName = webAclDimension(webAcl);
+    const metric = (name, dimensionsMap, options) => new aws_cloudwatch_1.Metric({
+        namespace: NAMESPACE,
+        metricName: name,
+        statistic: aws_cloudwatch_1.Stats.SUM,
+        period: exports.REQUEST_METRIC_PERIOD,
+        ...options,
+        dimensionsMap: { ...dimensionsMap, ...regionDimension, ...options?.dimensionsMap },
+    });
+    const requests = (rule) => {
+        const dimensions = { WebACL: webAclName, Rule: rule };
+        return {
+            allowedRequests: (o) => metric("AllowedRequests", dimensions, o),
+            blockedRequests: (o) => metric("BlockedRequests", dimensions, o),
+            countedRequests: (o) => metric("CountedRequests", dimensions, o),
+            captchaRequests: (o) => metric("CaptchaRequests", dimensions, o),
+            challengeRequests: (o) => metric("ChallengeRequests", dimensions, o),
+        };
+    };
+    return {
+        ...requests(ALL_RULES),
+        defaultAction: requests(metricName),
+        rule: (name) => {
+            const ruleMetricName = ruleMetricNames.get(name);
+            if (ruleMetricName === undefined) {
+                throw new Error(`The web ACL has no rule named "${name}". Rules: ${[...ruleMetricNames.keys()].join(", ") || "none"}.`);
+            }
+            return requests(ruleMetricName);
+        },
+        daysToExpiry: (group, options) => metric("DaysToExpiry", { Vendor: group.vendorName, ManagedRuleGroup: group.name, Version: group.version }, { statistic: aws_cloudwatch_1.Stats.MINIMUM, period: aws_cdk_lib_1.Duration.hours(1), ...options }),
+    };
+}
+//# sourceMappingURL=metrics.js.map

package/dist/commonjs/metrics.js.map

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

package/dist/commonjs/names.d.ts

@@ -0,0 +1,46 @@
+import type { CfnWebACL } from "aws-cdk-lib/aws-wafv2";
+/**
+ * Validates a web ACL name.
+ *
+ * @throws on invalid input.
+ */
+export declare function validateWebAclName(raw: string): void;
+/**
+ * Validates the name of a rule in a web ACL.
+ *
+ * @throws on invalid input.
+ */
+export declare function validateRuleName(raw: string): void;
+/**
+ * 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 declare function validateMetricName(raw: string): void;
+/**
+ * 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 declare function webAclBaseName(webAcl: CfnWebACL): string;
+/**
+ * Turns a construct path or other derived string into a legal metric name, for
+ * when the user has not chosen one.
+ *
+ * @internal
+ */
+export declare function sanitizeMetricName(raw: string): string;
+/**
+ * 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 declare function validateRuleLabel(raw: string): void;
+//# sourceMappingURL=names.d.ts.map

package/dist/commonjs/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/commonjs/names.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateWebAclName = validateWebAclName;
+exports.validateRuleName = validateRuleName;
+exports.validateMetricName = validateMetricName;
+exports.webAclBaseName = webAclBaseName;
+exports.sanitizeMetricName = sanitizeMetricName;
+exports.validateRuleLabel = validateRuleLabel;
+const cloudformation_1 = require("@composurecdk/cloudformation");
+const aws_cdk_lib_1 = require("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: `${cloudformation_1.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 = (0, cloudformation_1.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 = (0, cloudformation_1.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 = (0, cloudformation_1.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.
+ */
+function validateWebAclName(raw) {
+    (0, cloudformation_1.validateString)(raw, WEB_ACL_NAME);
+}
+/**
+ * Validates the name of a rule in a web ACL.
+ *
+ * @throws on invalid input.
+ */
+function validateRuleName(raw) {
+    (0, cloudformation_1.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.
+ */
+function validateMetricName(raw) {
+    (0, cloudformation_1.validateString)(raw, METRIC_NAME);
+    if (!aws_cdk_lib_1.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
+ */
+function webAclBaseName(webAcl) {
+    const { name } = webAcl;
+    if (name !== undefined && !aws_cdk_lib_1.Token.isUnresolved(name))
+        return name;
+    return aws_cdk_lib_1.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
+ */
+function sanitizeMetricName(raw) {
+    return (0, cloudformation_1.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 = (0, cloudformation_1.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.
+ */
+function validateRuleLabel(raw) {
+    if (aws_cdk_lib_1.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) {
+        (0, cloudformation_1.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/commonjs/names.js.map

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

package/dist/commonjs/package.json

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

package/dist/commonjs/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/commonjs/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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"}