@composurecdk/wafv2 0.0.0-stage → 0.13.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jason Duffett
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,241 @@
-# Temporary Holding Version
+# @composurecdk/wafv2
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+AWS WAF web ACL builder for [ComposureCDK](../../README.md).
+
+This package provides a fluent builder for [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) web ACLs, their rules and their associations. CDK has no L2 for WAF, so it wraps the [`CfnWebACL`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_wafv2.CfnWebACL.html) and [`CfnWebACLAssociation`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_wafv2.CfnWebACLAssociation.html) L1s directly, and handles the parts of them that only fail at deploy time.
+
+```ts
+import { compose, ref } from "@composurecdk/core";
+import { createRestApiBuilder, type RestApiBuilderResult } from "@composurecdk/apigateway";
+import { createWebAclBuilder } from "@composurecdk/wafv2";
+
+compose(
+  {
+    api: createRestApiBuilder(),
+    waf: 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, { json: { message: "Not found" } }),
+      ),
+  },
+  { api: [], waf: ["api"] },
+);
+```
+
+The result is `{ webAcl, associations, logGroup?, logging?, metrics, alarms }`:
+
+| Field          | Type                                   | Description                                                                                              |
+| -------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `webAcl`       | `CfnWebACL`                            | The web ACL. Its ARN is `webAcl.attrArn`.                                                                |
+| `associations` | `CfnWebACLAssociation[]`               | One per `associateWith` call, in that order. Always empty for a CLOUDFRONT web ACL.                      |
+| `logGroup`     | `LogGroup \| undefined`                | The `aws-waf-logs-` log group WAF writes to. Absent when logging is off or goes to your own destination. |
+| `logging`      | `CfnLoggingConfiguration \| undefined` | The logging configuration. Absent when logging is off.                                                   |
+| `metrics`      | `WebAclMetrics`                        | Metrics for the web ACL, its default action and each rule — see [Metrics](#metrics).                     |
+| `alarms`       | `Record<string, Alarm>`                | Recommended and custom alarms, keyed by alarm key — see [Alarms](#alarms).                               |
+
+## Defaults
+
+| Setting             | Default            | Rationale                                                                                                                                                                                                                                                                                                         |
+| ------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `scope`             | `REGIONAL`         | API Gateway, Application Load Balancers, AppSync, Cognito, App Runner and Verified Access are regional. Set `.scope("CLOUDFRONT")` for a distribution — see [CloudFront](#cloudfront).                                                                                                                            |
+| default action      | Allow              | A web ACL in front of an application usually lets through what no rule blocks. Use `.defaultAction("block")` for an allow-list.                                                                                                                                                                                   |
+| CloudWatch metrics  | on, ACL and rules  | Free, and the only way to see what the rules are doing. Not configurable.                                                                                                                                                                                                                                         |
+| metric name         | from name or path  | The web ACL's `name` when set; otherwise a name derived from its construct path, so two web ACLs never share a metric name. Each rule's metric name is its own name.                                                                                                                                              |
+| `sampledRequests`   | `false`            | A sampled request keeps every header, including credentials, and [logging redaction does not apply to it](https://docs.aws.amazon.com/waf/latest/developerguide/waf-data-protection-and-logging.html). Turning it on without a `dataProtectionConfig` adds the warning `@composurecdk/wafv2:sampling-unredacted`. |
+| logging             | on, non-Allow only | WAF logs go to a created `aws-waf-logs-` log group, keeping the requests it blocks, counts or challenges and redacting `authorization` and `cookie`. See [Logging](#logging).                                                                                                                                     |
+| managed rule groups | none               | Every managed group blocks some legitimate traffic until it is tuned. None is added for you.                                                                                                                                                                                                                      |
+
+`WEB_ACL_DEFAULTS` and `WEB_ACL_VISIBILITY_DEFAULTS` export these for inspection. Everything else in `CfnWebACLProps` — `name`, `description`, `dataProtectionConfig`, `captchaConfig`, `challengeConfig`, `tokenDomains`, `associationConfig` and the rest — is set with its own builder method and passed through.
+
+## Rules
+
+`addRule(name, configure)` adds a rule. `configure` receives a rule builder:
+
+| Method                                                          | What it does                                                                         |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `statement(raw)`                                                | The rule's statement, as CloudFormation's `StatementProperty`. Exactly one per rule. |
+| `block()` · `allow()` · `count()` · `captcha()` · `challenge()` | The action. `block()` is the default.                                                |
+| `respond(status, body?, headers?)`                              | Block with a custom response — see [Custom responses](#custom-responses).            |
+| `labels(...labels)`                                             | Labels to add to matching requests, for later rules to match on.                     |
+| `priority(n)`                                                   | Overrides the priority — see [Priorities](#priorities).                              |
+| `metricName(name)`                                              | The rule's CloudWatch metric name. Defaults to the rule's name.                      |
+| `sampledRequests(enabled)`                                      | Overrides the web ACL's sampling setting for this rule.                              |
+| `captchaConfig(…)` · `challengeConfig(…)`                       | Passed through to the rule.                                                          |
+
+Rule names are checked when the rule is added: 1–128 characters of `[A-Za-z0-9_-]`, and unique within the web ACL.
+
+### Raw statements and CloudFormation casing
+
+`statement()` takes CDK's `CfnWebACL.StatementProperty`. Most of it is camelCase, as usual, but CDK types several fields as `any` and passes them through untouched, so **they need CloudFormation's PascalCase**. A wrong case is accepted at synth and fails at deploy.
+
+```ts
+rule.statement({
+  sizeConstraintStatement: {
+    fieldToMatch: { singleHeader: { Name: "x-api-key" } }, // Name, not name
+    comparisonOperator: "GT",
+    size: 0,
+    textTransformations: [{ priority: 0, type: "NONE" }],
+  },
+});
+```
+
+The `any`-typed fields are `FieldToMatch`'s `singleHeader`, `singleQueryArgument`, `allQueryArguments`, `queryString`, `uriPath` and `method`, and a rate-based statement's custom keys `ip`, `forwardedIp`, `httpMethod` and `asn`. Fields that are empty objects (`uriPath: {}`) are unaffected.
+
+### Priorities
+
+WAF evaluates rules from the lowest priority up. Each rule's priority defaults to ten times its position in `addRule` order — 0, 10, 20, … — so rules run in the order they are declared, and there is room to insert one with an explicit `.priority(n)` without renumbering the rest. Two rules with the same priority throw at build, naming both. Changing a priority updates the web ACL in place.
+
+### Rule groups
+
+A rule whose statement is a `managedRuleGroupStatement` or a `ruleGroupReferenceStatement` evaluates a group of rules that keep their own actions, so CloudFormation gives it an `overrideAction` instead of an `action`. The builder emits `overrideAction: { None: {} }`, or `{ Count: {} }` when the rule calls `.count()` — the way to try a group out before it blocks anything. Any other action throws.
+
+```ts
+createWebAclBuilder().addRule("CommonRuleSet", (rule) =>
+  rule
+    .statement({
+      managedRuleGroupStatement: { vendorName: "AWS", name: "AWSManagedRulesCommonRuleSet" },
+    })
+    .count(),
+);
+```
+
+### Other checks at synth
+
+- A rate-based rule cannot Allow, and a web ACL can have at most ten of them.
+- Labels are 1–128 characters of `[A-Za-z0-9_-]` per colon-separated part, with at most five namespaces, and none of WAF's reserved words (`awswaf`, `aws`, `waf`, `rulegroup`, `webacl`, `regexpatternset`, `ipset`, `managed`). WAF adds the `awswaf:<account>:webacl:<name>:` prefix itself.
+- Metric names follow the rule for names, and `All` and `Default_Action` are reserved.
+
+The builder does not compute [web ACL capacity units](https://docs.aws.amazon.com/waf/latest/developerguide/aws-waf-capacity-units.html): only WAF's `CheckCapacity` is authoritative. A web ACL over 1,500 WCU is billed extra, and 5,000 is the hard limit.
+
+## Custom responses
+
+`respond(status, body?, headers?)` blocks with your own status code, body and headers rather than WAF's `403`. CloudFormation wants the body declared once on the web ACL and referenced by key from the rule; the builder does that for you, keying each body by the first rule that uses it and sharing one key between identical bodies.
+
+```ts
+rule.respond(429, { json: { reason: "throttled" } }, { "Retry-After": "60" });
+```
+
+The body is `{ json }` (serialised unless it is already a string), `{ text }` or `{ html }`, which set the content type. The default action can respond too: `.defaultAction("block", { status: 403, body: { text: "Forbidden" } })`.
+
+These are checked at synth, against the [supported status codes](https://docs.aws.amazon.com/waf/latest/developerguide/customizing-the-response-status-codes.html) and [quotas](https://docs.aws.amazon.com/waf/latest/developerguide/limits.html):
+
+- **Status:** one of 200, 201, 202, 204, 206, 300, 301, 302, 303, 304, 307, 308, 400, 401, 403, 404, 405, 408, 409, 411, 412, 413, 414, 415, 416, 421, 429, 500, 501, 502, 503, 504 or 505. Notably not 410, and 402 is reserved for Monetize. Exported as `SUPPORTED_CUSTOM_RESPONSE_STATUS_CODES`.
+- **Body:** at most 4 KB each, 50 distinct bodies and 50 KB in total per web ACL.
+- **Headers:** at most 10, names of 1–64 characters of `[a-zA-Z0-9._$-]`, no duplicates, and not `content-type`, which WAF sets from the body.
+
+A custom response only applies to Block, so `respond()` after another action, or another action after `respond()`, throws.
+
+## Logging
+
+Logging is on by default, because the [Well-Architected security pillar](https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/sec_detect_investigate_events_app_service_logging.html) asks for it and cdk-nag's NIST 800-53, PCI DSS and HIPAA packs fail a web ACL without it (`WAFv2LoggingEnabled`). The builder:
+
+- creates a CloudWatch log group through [`@composurecdk/logs`](../logs/README.md), so it gets that package's retention and removal defaults, named `aws-waf-logs-<web ACL name>` (or a name derived from the construct path), since WAF only logs to names with that prefix;
+- points an `AWS::WAFv2::LoggingConfiguration` at it, using the log group ARN **without** the trailing `:*` that `logGroup.logGroupArn` has, which WAF rejects;
+- keeps only the requests WAF blocks, counts, or answers with a CAPTCHA or challenge (`DEFAULT_LOGGING_FILTER`). Filtering is AWS's main lever on log [volume and cost](https://docs.aws.amazon.com/waf/latest/developerguide/logging-management.html);
+- redacts the `authorization` and `cookie` headers (`DEFAULT_LOGGING_REDACTED_HEADERS`), which carry replayable credentials and are no help when tuning a rule.
+
+```ts
+createWebAclBuilder().logging({
+  filter: "all",
+  redact: { headers: ["x-amz-security-token"], queryString: true },
+  configure: (logGroup) => logGroup.retention(RetentionDays.ONE_YEAR),
+});
+```
+
+| Option        | Effect                                                                                                                                                                                                                                                                           |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `filter`      | `"non-allow"` (default), `"all"`, or a typed `{ defaultBehavior, filters }` whose conditions are `{ action }` or `{ label }`. The builder emits CloudFormation's PascalCase JSON, which CDK types as `any`.                                                                      |
+| `redact`      | `headers`, `queryString`, `uriPath`, `method`. **`headers` adds to `authorization` and `cookie`; it does not replace them.** At most 100 fields.                                                                                                                                 |
+| `configure`   | Customizes the created log group's builder. A name that does not start with `aws-waf-logs-` throws, since the deploy would fail.                                                                                                                                                 |
+| `destination` | Logs to an existing CloudWatch log group, S3 bucket or Firehose stream instead, by ARN or `ref`. Its name must start with `aws-waf-logs-`; an S3 bucket must use SSE-S3 or a customer managed key, and a Firehose stream must be DirectPut. Cannot be combined with `configure`. |
+
+`.logging(false)` turns logging off.
+
+WAF grants `delivery.logs.amazonaws.com` write access to the log group itself when the logging configuration is created. It does this with a policy on the log group, not an account-level one, so it does not count toward CloudWatch Logs' limit of 10 resource policies per Region. The identity that creates the configuration (CloudFormation's execution role, under a CDK bootstrap) needs `logs:PutResourcePolicy`, `logs:DescribeResourcePolicies` and `logs:CreateLogDelivery` alongside its WAF permissions. Without them, the logging configuration fails to create and the deploy rolls back; logging is never left silently off. To see the policy, run `aws logs describe-resource-policies --policy-scope RESOURCE --resource-arn <log group ARN>`. A plain `describe-resource-policies` lists only account-level policies. Redaction applies to logs only — see `sampledRequests` in [Defaults](#defaults).
+
+## Metrics
+
+`result.metrics` builds the [`AWS/WAFV2` metrics](https://docs.aws.amazon.com/waf/latest/developerguide/waf-metrics.html) from the names the builder gave the web ACL and its rules, so there is nothing to thread through by hand:
+
+```ts
+const { metrics } = createWebAclBuilder().addRule("PerIpRate", …).build(stack, "Waf");
+
+metrics.blockedRequests(); // every rule: Rule=ALL
+metrics.rule("PerIpRate").blockedRequests(); // one rule, by the name given to addRule
+metrics.defaultAction.allowedRequests(); // requests no rule terminated
+metrics.daysToExpiry({ vendorName: "AWS", name: "AWSManagedRulesCommonRuleSet", version: "Version_1.12" });
+```
+
+Each request metric — `allowedRequests`, `blockedRequests`, `countedRequests`, `captchaRequests`, `challengeRequests` — is a Sum over 5 minutes unless you pass `MetricOptions`.
+
+The dimensions follow what WAF actually publishes, which differs from its documentation in two places (checked against a deployed web ACL):
+
+- **`WebACL` is the web ACL's _name_**, not its `VisibilityConfig` metric name. An unnamed web ACL's dimension reads the generated name from its `Ref`.
+- **The default action is published as `Rule=<the web ACL's metric name>`**, not `Rule=Default_Action`.
+- `Rule` is the rule's metric name, and `Region` is present for a regional web ACL only.
+
+## Alarms
+
+The recommended alarms are per rule. AWS publishes [no recommended alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html) for WAF, so the defaults below (`WEB_ACL_RULE_ALARM_DEFAULTS`) are this library's starting points. Every alarm treats missing data as not breaching, because WAF publishes a datapoint only when its count is non-zero. No alarm actions are configured — apply them from the result or with [`alarmActionsPolicy`](../cloudwatch/README.md).
+
+| Alarm key               | Created for                                | Metric                         | Default threshold | Why                                                                                                                                                                                                          |
+| ----------------------- | ------------------------------------------ | ------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `<rule>BlockedRequests` | a rule you wrote whose action is Block     | `BlockedRequests` (Sum, 5 min) | > 0               | A block by your own rule is a signal: a throttled client, a request without its credentials. Raise it on a rule that blocks routinely.                                                                       |
+| `<rule>BlockedRequests` | a rule-group rule — **opt-in**             | `BlockedRequests` (Sum, 5 min) | > 0               | Managed rules block internet background noise all day; on by default, it would page constantly.                                                                                                              |
+| `<rule>DaysToExpiry`    | a managed rule group pinned to a `version` | `DaysToExpiry` (Min, 1 hour)   | < 30              | [Once a pinned version expires](https://docs.aws.amazon.com/waf/latest/developerguide/waf-managed-rule-groups-versioning-expiration.html), WAF rejects every update to the web ACL that does not move it on. |
+
+`<rule>` is the rule's name in camelCase: `PerIpRate` and `per-ip-rate` both become `perIpRate`, so two rules whose names differ only that way cannot both have alarms; the build throws, naming them. No alarm is created for a rule that counts, allows, or answers with a CAPTCHA or challenge.
+
+Tune or disable a rule's alarms with `.alarms()`, all of them with `.recommendedAlarms(false)`, and add your own with `addAlarm`, whose metric factory receives `WebAclMetrics`:
+
+```ts
+createWebAclBuilder()
+  .addRule("PerIpRate", (rule) => rule.statement(…).alarms({ blockedRequests: { threshold: 50 } }))
+  .addRule("CommonRuleSet", (rule) => rule.statement(…).alarms({ blockedRequests: { threshold: 1000 } }))
+  .addRule("Probe", (rule) => rule.statement(…).count().alarms(false))
+  .addAlarm("probeCounted", (alarm) =>
+    alarm.metric((m) => m.rule("Probe").countedRequests()).threshold(100),
+  );
+```
+
+A CLOUDFRONT web ACL's metrics are published in `us-east-1`, where the web ACL must be, so its alarms need nothing special.
+
+## Associations
+
+`associateWith(target)` protects a regional resource. Call it once per resource; one web ACL can protect many. The target is an ARN, a CDK reference that `CfnWebACLAssociation` accepts in your `aws-cdk-lib` (recent releases take an Application Load Balancer or AppSync API), or an API Gateway stage, as a value or a `ref`.
+
+- The association references the web ACL by `webAcl.attrArn`, so tools that check for one by reference, such as cdk-nag's `AwsSolutions-APIG3`, find it.
+- A stage's ARN references the stage, so the association waits for it. A construct target is also depended on explicitly.
+- AWS accepts one `AssociateWebACL` call every two seconds, so each association depends on the one before it rather than racing it.
+- Each association's construct id is derived from its target, not its position, so removing one target does not replace — and briefly disassociate — the others.
+
+## CloudFront
+
+A web ACL for a CloudFront distribution has `.scope("CLOUDFRONT")` and must be created in `us-east-1`. The builder throws at synth when its stack is in another region, falls back to `CDK_DEFAULT_REGION` for an environment-agnostic stack, and warns (`@composurecdk/wafv2:cloudfront-region`) when it cannot tell. A distribution attaches the web ACL itself, through its `webAclId`, so `associateWith` throws:
+
+```ts
+const { webAcl } = createWebAclBuilder().scope("CLOUDFRONT").build(usEast1Stack, "EdgeWaf");
+// distribution.webAclId(webAcl.attrArn)
+```
+
+## Constraints
+
+Names, metric names and labels are validated at build against the AWS rules above ([ADR-0010](../../docs/adr/0010-aws-property-constraints.md)). The validators are exported for direct use:
+
+```ts
+import { constraints } from "@composurecdk/wafv2";
+
+constraints.validate.webAclName("api-waf");
+constraints.validate.ruleName("PerIpRate");
+constraints.validate.metricName("PerIpRate");
+constraints.validate.ruleLabel("auth:missing-token");
+```

package/dist/commonjs/alarm-config.d.ts

@@ -0,0 +1,60 @@
+import type { AlarmConfig } from "@composurecdk/cloudwatch";
+/**
+ * Controls the web ACL's recommended alarms. They are per rule — see
+ * {@link WebAclRuleAlarmConfig} — so this is the master switch.
+ */
+export interface WebAclAlarmConfig {
+    /**
+     * Set to `false` to create none of the recommended alarms. Alarms added
+     * with `addAlarm()` are unaffected.
+     * @default true
+     */
+    enabled?: boolean;
+}
+/**
+ * Controls one rule's recommended alarms, set with the rule builder's
+ * `.alarms()`. Set an alarm to `false` to disable it, or to an
+ * {@link AlarmConfig} to enable it (if off by default) or tune it. Defaults
+ * are in {@link WEB_ACL_RULE_ALARM_DEFAULTS}.
+ *
+ * Every alarm treats missing data as not breaching: WAF publishes a
+ * datapoint only when the count is non-zero.
+ *
+ * AWS publishes no recommended alarms for WAF, so the thresholds are this
+ * library's starting points.
+ */
+export interface WebAclRuleAlarmConfig {
+    /**
+     * Set to `false` to disable all of this rule's recommended alarms.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Alarm when the rule blocks requests: `BlockedRequests` (Sum, 5 minutes)
+     * above the threshold.
+     *
+     * On by default for a rule you wrote whose action is Block, where a block
+     * is a signal — a throttled client, a request missing its credentials.
+     * Off by default for a rule-group rule, whose managed rules block internet
+     * background noise all day; pass an {@link AlarmConfig} to turn it on.
+     * Never created for a rule that does not block.
+     *
+     * Default threshold: > 0 blocked requests in one 5-minute period.
+     */
+    blockedRequests?: AlarmConfig | false;
+    /**
+     * Alarm when a pinned managed rule group version is about to expire:
+     * `DaysToExpiry` (Minimum, 1 hour) below the threshold. Once a version
+     * expires, WAF rejects every update to the web ACL that does not move
+     * the group to a current version.
+     *
+     * On by default for a managed rule group with a `version`; never created
+     * otherwise.
+     *
+     * Default threshold: < 30 days.
+     *
+     * @see https://docs.aws.amazon.com/waf/latest/developerguide/waf-managed-rule-groups-versioning-expiration.html
+     */
+    daysToExpiry?: AlarmConfig | false;
+}
+//# sourceMappingURL=alarm-config.d.ts.map

package/dist/commonjs/alarm-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-config.d.ts","sourceRoot":"","sources":["../../src/alarm-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAEtC;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;CACpC"}

package/dist/commonjs/alarm-config.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=alarm-config.js.map

package/dist/commonjs/alarm-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-config.js","sourceRoot":"","sources":["../../src/alarm-config.ts"],"names":[],"mappings":""}

package/dist/commonjs/alarm-defaults.d.ts

@@ -0,0 +1,34 @@
+import { TreatMissingData } from "aws-cdk-lib/aws-cloudwatch";
+/**
+ * Default configuration of each rule's recommended alarms. AWS publishes no
+ * recommended alarms for WAF, so these are this library's starting points.
+ * Both treat missing data as not breaching, because WAF publishes a
+ * datapoint only when its value is non-zero.
+ */
+export declare const WEB_ACL_RULE_ALARM_DEFAULTS: {
+    /**
+     * Any block in a 5-minute period. A rule you wrote encodes your own
+     * contract — a credential every caller should send, a rate no client
+     * should reach — so a single block is worth a look. Raise the threshold
+     * on a rule that blocks routinely.
+     */
+    blockedRequests: {
+        threshold: number;
+        evaluationPeriods: number;
+        datapointsToAlarm: number;
+        treatMissingData: TreatMissingData.NOT_BREACHING;
+    };
+    /**
+     * Fewer than 30 days before a pinned version expires, which leaves time to
+     * test and move to a newer one.
+     *
+     * @see https://docs.aws.amazon.com/waf/latest/developerguide/waf-managed-rule-groups-best-practice.html
+     */
+    daysToExpiry: {
+        threshold: number;
+        evaluationPeriods: number;
+        datapointsToAlarm: number;
+        treatMissingData: TreatMissingData.NOT_BREACHING;
+    };
+};
+//# sourceMappingURL=alarm-defaults.d.ts.map

package/dist/commonjs/alarm-defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-defaults.d.ts","sourceRoot":"","sources":["../../src/alarm-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAG9D;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B;IACtC;;;;;OAKG;;;;;;;IAQH;;;;;OAKG;;;;;;;CAO0C,CAAC"}

package/dist/commonjs/alarm-defaults.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WEB_ACL_RULE_ALARM_DEFAULTS = void 0;
+const aws_cloudwatch_1 = require("aws-cdk-lib/aws-cloudwatch");
+/**
+ * Default configuration of each rule's recommended alarms. AWS publishes no
+ * recommended alarms for WAF, so these are this library's starting points.
+ * Both treat missing data as not breaching, because WAF publishes a
+ * datapoint only when its value is non-zero.
+ */
+exports.WEB_ACL_RULE_ALARM_DEFAULTS = {
+    /**
+     * Any block in a 5-minute period. A rule you wrote encodes your own
+     * contract — a credential every caller should send, a rate no client
+     * should reach — so a single block is worth a look. Raise the threshold
+     * on a rule that blocks routinely.
+     */
+    blockedRequests: {
+        threshold: 0,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+    /**
+     * Fewer than 30 days before a pinned version expires, which leaves time to
+     * test and move to a newer one.
+     *
+     * @see https://docs.aws.amazon.com/waf/latest/developerguide/waf-managed-rule-groups-best-practice.html
+     */
+    daysToExpiry: {
+        threshold: 30,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+};
+//# sourceMappingURL=alarm-defaults.js.map

package/dist/commonjs/alarm-defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-defaults.js","sourceRoot":"","sources":["../../src/alarm-defaults.ts"],"names":[],"mappings":";;;AAAA,+DAA8D;AAG9D;;;;;GAKG;AACU,QAAA,2BAA2B,GAAG;IACzC;;;;;OAKG;IACH,eAAe,EAAE;QACf,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED;;;;;OAKG;IACH,YAAY,EAAE;QACZ,SAAS,EAAE,EAAE;QACb,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;CAC4C,CAAC"}

package/dist/commonjs/alarms.d.ts

@@ -0,0 +1,18 @@
+import { type AlarmDefinition } from "@composurecdk/cloudwatch";
+import type { WebAclAlarmConfig } from "./alarm-config.js";
+import { type WebAclMetrics } from "./metrics.js";
+import type { BuiltRule } from "./rule-builder.js";
+/**
+ * The alarm-key prefix for a rule: its name in camelCase, so `PerIpRate` and
+ * `per-ip-rate` both become `perIpRate`.
+ *
+ * @internal
+ */
+export declare function ruleAlarmKey(name: string): string;
+/**
+ * Resolves each rule's recommended alarms into {@link AlarmDefinition}s.
+ *
+ * @internal
+ */
+export declare function resolveWebAclAlarmDefinitions(owner: string, metrics: WebAclMetrics, rules: readonly BuiltRule[], config: WebAclAlarmConfig | false | undefined): AlarmDefinition[];
+//# sourceMappingURL=alarms.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"alarms.d.ts","sourceRoot":"","sources":["../../src/alarms.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,eAAe,EAGrB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAInD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIjD;AAiBD;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,MAAM,EAAE,iBAAiB,GAAG,KAAK,GAAG,SAAS,GAC5C,eAAe,EAAE,CAkBnB"}

package/dist/commonjs/alarms.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ruleAlarmKey = ruleAlarmKey;
+exports.resolveWebAclAlarmDefinitions = resolveWebAclAlarmDefinitions;
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const aws_cloudwatch_1 = require("aws-cdk-lib/aws-cloudwatch");
+const cloudwatch_1 = require("@composurecdk/cloudwatch");
+const alarm_defaults_js_1 = require("./alarm-defaults.js");
+const metrics_js_1 = require("./metrics.js");
+const PERIOD_LABEL = `${String(metrics_js_1.REQUEST_METRIC_PERIOD.toMinutes())} minutes`;
+/**
+ * The alarm-key prefix for a rule: its name in camelCase, so `PerIpRate` and
+ * `per-ip-rate` both become `perIpRate`.
+ *
+ * @internal
+ */
+function ruleAlarmKey(name) {
+    const parts = name.split(/[-_]+/).filter(Boolean);
+    const pascal = parts.map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join("");
+    return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}
+function isOff(config) {
+    return config === false || config?.enabled === false;
+}
+/** The managed rule group a statement pins to a version, if any. */
+function pinnedGroup(statement) {
+    // The rule builder only takes a `StatementProperty`, never a token.
+    const group = statement.managedRuleGroupStatement;
+    if (group === undefined || aws_cdk_lib_1.Token.isUnresolved(group))
+        return undefined;
+    const { vendorName, name, version } = group;
+    return version === undefined ? undefined : { vendorName, name, version };
+}
+/**
+ * Resolves each rule's recommended alarms into {@link AlarmDefinition}s.
+ *
+ * @internal
+ */
+function resolveWebAclAlarmDefinitions(owner, metrics, rules, config) {
+    if (isOff(config))
+        return [];
+    const keys = new Map();
+    return rules.flatMap((rule) => {
+        const definitions = resolveRuleAlarms(metrics, rule);
+        if (definitions.length === 0)
+            return [];
+        const { name } = rule.property;
+        const key = ruleAlarmKey(name);
+        const other = keys.get(key);
+        if (other !== undefined) {
+            throw new Error(`${owner}: rules "${other}" and "${name}" both have alarm key "${key}", because ` +
+                `alarm keys are rule names in camelCase. Rename one of them.`);
+        }
+        keys.set(key, name);
+        return definitions;
+    });
+}
+function definition(key, metric, comparisonOperator, userConfig, defaults, describe) {
+    const { alarmName, threshold, evaluationPeriods, datapointsToAlarm, treatMissingData } = (0, cloudwatch_1.resolveAlarmConfig)(userConfig, defaults);
+    return {
+        key,
+        alarmName,
+        metric,
+        threshold,
+        comparisonOperator,
+        evaluationPeriods,
+        datapointsToAlarm,
+        treatMissingData,
+        description: describe(threshold),
+    };
+}
+function resolveRuleAlarms(metrics, rule) {
+    const config = rule.alarms;
+    if (isOff(config))
+        return [];
+    const { name } = rule.property;
+    const key = ruleAlarmKey(name);
+    const definitions = [];
+    const blocked = config ? config.blockedRequests : undefined;
+    // A rule group's managed rules block background noise, so its alarm is opt-in.
+    if (rule.blocks && blocked !== false && (!rule.ruleGroup || blocked !== undefined)) {
+        definitions.push(definition(`${key}BlockedRequests`, metrics.rule(name).blockedRequests(), aws_cloudwatch_1.ComparisonOperator.GREATER_THAN_THRESHOLD, blocked, alarm_defaults_js_1.WEB_ACL_RULE_ALARM_DEFAULTS.blockedRequests, (t) => `WAF rule "${name}" is blocking requests. Threshold: > ${String(t)} blocked requests in ${PERIOD_LABEL}.`));
+    }
+    const group = pinnedGroup(rule.property.statement);
+    const expiry = config ? config.daysToExpiry : undefined;
+    if (group && expiry !== false) {
+        const version = aws_cdk_lib_1.Token.isUnresolved(group.version)
+            ? "its pinned version"
+            : `version ${group.version}`;
+        definitions.push(definition(`${key}DaysToExpiry`, metrics.daysToExpiry(group), aws_cloudwatch_1.ComparisonOperator.LESS_THAN_THRESHOLD, expiry, alarm_defaults_js_1.WEB_ACL_RULE_ALARM_DEFAULTS.daysToExpiry, (t) => `WAF rule "${name}" pins ${group.name} at ${version}, which expires in under ${String(t)} days. Move it to a newer version; WAF rejects updates to the web ACL once it expires.`));
+    }
+    return definitions;
+}
+//# sourceMappingURL=alarms.js.map

package/dist/commonjs/alarms.js.map

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

package/dist/commonjs/association.d.ts

@@ -0,0 +1,21 @@
+import type { Stage } from "aws-cdk-lib/aws-apigateway";
+import { CfnWebACLAssociation, type CfnWebACLAssociationProps } from "aws-cdk-lib/aws-wafv2";
+import { type IConstruct } from "constructs";
+/**
+ * A resource a regional web ACL can protect: an ARN, a CDK reference CDK
+ * itself accepts (an Application Load Balancer, an AppSync API, …), or an API
+ * Gateway REST API stage.
+ *
+ * The ARN and reference types are read from CDK's own `resourceArn` prop, so
+ * they track the installed `aws-cdk-lib` (ADR-0018).
+ */
+export type WebAclAssociationTarget = NonNullable<CfnWebACLAssociationProps["resourceArn"]> | Pick<Stage, "stageArn" | "node">;
+/**
+ * Creates one `AWS::WAFv2::WebACLAssociation` per target, each depending on
+ * the one before it: AWS allows one `AssociateWebACL` call every two seconds
+ * per account and Region, so parallel associations throttle themselves.
+ *
+ * @internal
+ */
+export declare function associate(scope: IConstruct, id: string, webAclArn: string, targets: WebAclAssociationTarget[]): CfnWebACLAssociation[];
+//# sourceMappingURL=association.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"association.d.ts","sourceRoot":"","sources":["../../src/association.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,KAAK,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAC7F,OAAO,EAAa,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAExD;;;;;;;GAOG;AACH,MAAM,MAAM,uBAAuB,GACjC,WAAW,CAAC,yBAAyB,CAAC,aAAa,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAAC,CAAC;AA2B3F;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,uBAAuB,EAAE,GACjC,oBAAoB,EAAE,CAsBxB"}