docs: add Web Application Firewall reference

reference/index.md

@@ -20,13 +20,14 @@ For concept introductions, tutorials, and guides, see the [Learn](/learn) sectio
 
 ### Access & Security
 
-| Section                                        | Description                                                                |
-| ---------------------------------------------- | -------------------------------------------------------------------------- |
-| [REST](./rest/overview.md)                     | Auto-REST interface, querying, content types, headers, WebSockets, and SSE |
-| [HTTP](./http/overview.md)                     | HTTP server configuration, TLS, and the `server` API                       |
-| [MCP](./mcp/overview.md)                       | Built-in Model Context Protocol server, profiles, CLI, and migration       |
-| [Security](./security/overview.md)             | Authentication mechanisms, certificates, and CORS/SSL configuration        |
-| [Users & Roles](./users-and-roles/overview.md) | RBAC, roles configuration, and user management operations                  |
+| Section                                                            | Description                                                                |
+| ------------------------------------------------------------------ | -------------------------------------------------------------------------- |
+| [REST](./rest/overview.md)                                         | Auto-REST interface, querying, content types, headers, WebSockets, and SSE |
+| [HTTP](./http/overview.md)                                         | HTTP server configuration, TLS, and the `server` API                       |
+| [MCP](./mcp/overview.md)                                           | Built-in Model Context Protocol server, profiles, CLI, and migration       |
+| [Security](./security/overview.md)                                 | Authentication mechanisms, certificates, and CORS/SSL configuration        |
+| [Web Application Firewall](./web-application-firewall/overview.md) | Rule-based filtering for HTTP requests                                     |
+| [Users & Roles](./users-and-roles/overview.md)                     | RBAC, roles configuration, and user management operations                  |
 
 ### Setup & Operation
 

reference/operations-api/operations.md

@@ -815,6 +815,24 @@ Returns the full current configuration object.
 
 ---
 
+## Web Application Firewall
+
+<VersionBadge version="v5.2.0" />
+
+Operations for managing Web Application Firewall rules and cluster-wide enforcement controls.
+
+Detailed documentation: [WAF Operations and Rule Schema](../web-application-firewall/operations.md)
+
+| Operation        | Description                                       | Role Required |
+| ---------------- | ------------------------------------------------- | ------------- |
+| `add_waf_rule`   | Creates a validated WAF rule                      | super_user    |
+| `alter_waf_rule` | Patches and revalidates an existing WAF rule      | super_user    |
+| `drop_waf_rule`  | Deletes a WAF rule                                | super_user    |
+| `list_waf_rules` | Returns all WAF rules                             | super_user    |
+| `set_waf_mode`   | Sets the replicated mode and/or scoring threshold | super_user    |
+
+---
+
 ## System
 
 Operations for restarting Harper and managing system state.

reference/operations-api/overview.md

@@ -64,23 +64,24 @@ Operations are grouped by topic. See [Operations](./operations.md) for the compl
 
 **Topic categories:**
 
-| Category                                                            | Description                                                    | Detailed Docs                                                   |
-| ------------------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------- |
-| [Databases & Tables](./operations.md#databases--tables)             | Create and manage databases, tables, and attributes            | [Database Overview](../database/overview.md)                    |
-| [NoSQL Operations](./operations.md#nosql-operations)                | Insert, update, upsert, delete, and query records              | [REST Querying Reference](../rest/querying.md)                  |
-| [Bulk Operations](./operations.md#bulk-operations)                  | CSV/S3 import and export, batch delete                         | [Database Jobs](../database/jobs.md)                            |
-| [SQL Operations](./operations.md#sql-operations)                    | Execute SQL statements (use for investigation, not production) | —                                                               |
-| [Users & Roles](./operations.md#users--roles)                       | Manage users and role-based access control                     | [Users & Roles Operations](../users-and-roles/operations.md)    |
-| [Token Authentication](./operations.md#token-authentication)        | Create and refresh JWT tokens                                  | [JWT Authentication](../security/jwt-authentication.md)         |
-| [Components](./operations.md#components)                            | Deploy and manage Harper components                            | [Components Overview](../components/overview.md)                |
-| [Replication & Clustering](./operations.md#replication--clustering) | Configure cluster topology and replication                     | [Replication & Clustering](../replication/clustering.md)        |
-| [Configuration](./operations.md#configuration)                      | Read and update Harper configuration                           | —                                                               |
-| [System](./operations.md#system)                                    | Restart, system information, status management                 | —                                                               |
-| [Jobs](./operations.md#jobs)                                        | Query background job status                                    | [Database Jobs](../database/jobs.md)                            |
-| [Logs](./operations.md#logs)                                        | Read standard, transaction, and audit logs                     | [Logging Operations](../logging/operations.md)                  |
-| [Certificate Management](./operations.md#certificate-management)    | Manage TLS certificates                                        | [Certificate Management](../security/certificate-management.md) |
-| [Analytics](./operations.md#analytics)                              | Query analytics metrics                                        | [Analytics Operations](../analytics/operations.md)              |
-| [Registration & Licensing](./operations.md#registration--licensing) | License management                                             | —                                                               |
+| Category                                                             | Description                                                    | Detailed Docs                                                   |
+| -------------------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------- |
+| [Databases & Tables](./operations.md#databases--tables)              | Create and manage databases, tables, and attributes            | [Database Overview](../database/overview.md)                    |
+| [NoSQL Operations](./operations.md#nosql-operations)                 | Insert, update, upsert, delete, and query records              | [REST Querying Reference](../rest/querying.md)                  |
+| [Bulk Operations](./operations.md#bulk-operations)                   | CSV/S3 import and export, batch delete                         | [Database Jobs](../database/jobs.md)                            |
+| [SQL Operations](./operations.md#sql-operations)                     | Execute SQL statements (use for investigation, not production) | —                                                               |
+| [Users & Roles](./operations.md#users--roles)                        | Manage users and role-based access control                     | [Users & Roles Operations](../users-and-roles/operations.md)    |
+| [Token Authentication](./operations.md#token-authentication)         | Create and refresh JWT tokens                                  | [JWT Authentication](../security/jwt-authentication.md)         |
+| [Components](./operations.md#components)                             | Deploy and manage Harper components                            | [Components Overview](../components/overview.md)                |
+| [Replication & Clustering](./operations.md#replication--clustering)  | Configure cluster topology and replication                     | [Replication & Clustering](../replication/clustering.md)        |
+| [Configuration](./operations.md#configuration)                       | Read and update Harper configuration                           | —                                                               |
+| [Web Application Firewall](./operations.md#web-application-firewall) | Manage WAF rules, mode, and score threshold                    | [WAF Operations](../web-application-firewall/operations.md)     |
+| [System](./operations.md#system)                                     | Restart, system information, status management                 | —                                                               |
+| [Jobs](./operations.md#jobs)                                         | Query background job status                                    | [Database Jobs](../database/jobs.md)                            |
+| [Logs](./operations.md#logs)                                         | Read standard, transaction, and audit logs                     | [Logging Operations](../logging/operations.md)                  |
+| [Certificate Management](./operations.md#certificate-management)     | Manage TLS certificates                                        | [Certificate Management](../security/certificate-management.md) |
+| [Analytics](./operations.md#analytics)                               | Query analytics metrics                                        | [Analytics Operations](../analytics/operations.md)              |
+| [Registration & Licensing](./operations.md#registration--licensing)  | License management                                             | —                                                               |
 
 ## Past Release API Documentation
 

reference/security/overview.md

@@ -40,6 +40,7 @@ Harper supports three authentication methods:
   - For HTTP server configuration see [HTTP / Configuration / TLS](../http/tls.md)
   - For Operations API configuration see [Operations API / Configuration](../configuration/operations.md)
 - [Users and Roles](../users-and-roles/overview.md) — Role-Based Access Control (RBAC): defining roles, assigning permissions, and managing users.
+- [Web Application Firewall](../web-application-firewall/overview.md) — Rule-based filtering for HTTP requests before authentication and application routing.
 - [Impersonation](./impersonation.md) — Execute operations as a different user or role.
 
 ## API

reference/web-application-firewall/configuration.md

@@ -0,0 +1,118 @@
+---
+id: configuration
+title: Configuration
+---
+
+# WAF Configuration
+
+<VersionBadge version="v5.2.0" />
+
+The WAF is configured through the top-level `waf` section of `harper-config.yaml`. Harper Pro includes an empty `waf: {}` block by default, which enables the component with its default settings.
+
+```yaml
+waf:
+  enabled: true
+  mode: enforce
+  scoreThreshold: 10
+  debounceMs: 100
+  logRateLimit: 100
+  logRateIntervalMs: 60000
+  region: us-west
+  nodeTags:
+    - edge
+    - canary
+```
+
+Changes to `harper-config.yaml` require a restart. Rule changes and global mode changes made through the [WAF Operations](./operations.md) do not.
+
+## Options
+
+### `waf.enabled`
+
+Type: `boolean`
+
+Default: `true`
+
+Enables the WAF component. Set this to `false` to disable WAF middleware and WAF management operations on this node.
+
+### `waf.mode`
+
+Type: `string`
+
+Default: `enforce`
+
+Fallback enforcement mode when no replicated WAF control value has been set:
+
+- `enforce` - Apply `block` and `score` actions.
+- `monitor` - Evaluate rules, but downgrade all `block` and `score` matches to would-block logs.
+- `off` - Do not evaluate rules.
+
+A mode set through [`set_waf_mode`](./operations.md#set_waf_mode) is stored in the replicated WAF control row and takes precedence over this node-local setting.
+
+### `waf.scoreThreshold`
+
+Type: `number`
+
+Default: `10`
+
+Fallback total at which matched `score` rules block a request. Set this to a finite number greater than zero.
+
+A threshold set through [`set_waf_mode`](./operations.md#set_waf_mode) is replicated and takes precedence. Use the operation for a cluster so every node makes the same scoring decision.
+
+### `waf.debounceMs`
+
+Type: `number` (milliseconds)
+
+Default: `100`
+
+How long a worker waits after a rule-table change before recompiling its matcher. Additional changes during the interval are combined into the same recompile.
+
+### `waf.logRateLimit`
+
+Type: `number`
+
+Default: `100`
+
+Maximum WAF match log lines emitted per rule during each `logRateIntervalMs` window. Harper suppresses additional lines and emits a summary when the next window begins.
+
+This limit affects logging only. It does not change matching or enforcement.
+
+### `waf.logRateIntervalMs`
+
+Type: `number` (milliseconds)
+
+Default: `60000`
+
+Window used by the per-rule WAF log rate limiter.
+
+### `waf.region`
+
+Type: `string`
+
+Default: None
+
+This node's region for rule [`activation.regions`](./operations.md#activation) matching.
+
+### `waf.nodeTags`
+
+Type: `string[]`
+
+Default: `[]`
+
+This node's tags for rule [`activation.tags`](./operations.md#activation) matching. A tag selector matches when at least one rule tag appears in this array.
+
+## Runtime control precedence
+
+For `mode` and `scoreThreshold`, Harper uses the first available value:
+
+1. Replicated control value set by `set_waf_mode`
+2. Local `waf` configuration
+3. Built-in default
+
+The remaining options are node-local configuration.
+
+## Related
+
+- [WAF Overview](./overview.md)
+- [WAF Operations and Rule Schema](./operations.md)
+- [Configuration Overview](../configuration/overview.md)