@gfargo/doorman 3.14.0 → 3.14.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gfargo/doorman",
-  "version": "3.14.0",
+  "version": "3.14.2",
   "description": "Manage firewall rules as code across multiple providers",
   "publishConfig": {
     "access": "public"

package/skills/doorman/SKILL.md

@@ -76,7 +76,7 @@ FASTLY_WORKSPACE_ID=workspace_xxx
 }
 ```
 
-For Cloudflare or Fastly, add `provider` and `providers` fields instead of `projectId`/`teamId`.
+For Cloudflare or Fastly, add `provider` and `providers` fields instead of `projectId`/`teamId` — and note this switches the *rule* shape too, not just the top-level fields. See [Rule Shape](#rule-shape-minimal) below.
 
 ## Core Workflow
 
@@ -93,6 +93,10 @@ doorman backup && doorman validate && doorman diff && doorman sync && doorman st
 
 ## Rule Shape (Minimal)
 
+Two different rule shapes, picked by whether the config has `provider`/`providers` set (see [Config Structure](#config-structure) above) — **they are not interchangeable, and mixing them fails validation.**
+
+**Legacy shape** (no `provider`/`providers` — Vercel-only):
+
 ```json
 {
   "name": "Block Admin",
@@ -108,7 +112,26 @@ doorman backup && doorman validate && doorman diff && doorman sync && doorman st
 
 **Operators**: `eq`, `pre` (prefix), `suf` (suffix), `sub` (contains), `inc` (in array), `re` (regex), `ex` (exists), `nex` (not exists)
 
-**Actions**: `deny`, `challenge`, `rate_limit`, `redirect`, `log`, `bypass`
+**Actions**: `deny`, `challenge`, `rate_limit`, `redirect`, `log`, `bypass` (no `allow`/`block`)
+
+**Unified shape** (`provider`/`providers` set — required for Cloudflare/Fastly):
+
+```json
+{
+  "name": "Block Admin",
+  "enabled": true,
+  "conditions": [{ "field": "path", "operator": "starts_with", "value": "/admin" }],
+  "action": { "type": "deny" }
+}
+```
+
+**Logic**: conditions default to AND across all of them. Tag conditions with a `group` number for OR-of-AND-groups (same conditions sharing a `group` are AND'd, distinct `group`s are OR'd) — see [references/rules.md](references/rules.md) for the full explanation and an example.
+
+**Condition fields**: `ip`, `country`, `region`, `city`, `asn`, `path`, `host`, `method`, `header`, `query`, `cookie`, `user_agent`, `referer`, `scheme`, `port` — support varies by provider, see [references/cloudflare.md](references/cloudflare.md)/[references/fastly.md](references/fastly.md)/[references/gcp.md](references/gcp.md)
+
+**Operators**: `eq`, `ne`, `contains`, `not_contains`, `starts_with`, `ends_with`, `matches`, `in`, `not_in`, `gt`, `ge`, `lt`, `le`, `exists`, `not_exists` — **on Vercel specifically, `ne`/`not_contains`/`not_in`/`gt`/`ge`/`lt`/`le` currently degrade silently to `eq` (known bug, [doorman#261](https://github.com/gfargo/doorman/issues/261)) — avoid them in a Vercel-targeted config until that's fixed.**
+
+**Actions**: `log`, `deny`, `challenge`, `bypass`, `rate_limit`, `redirect`, `allow`, `block` — **`allow`/`block` are invalid on Vercel specifically ([doorman#262](https://github.com/gfargo/doorman/issues/262)); use `bypass`/`deny` there instead.**
 
 ## When to Read Each Reference
 
@@ -117,8 +140,9 @@ Load the relevant reference file for detailed documentation:
 | Task                                                                                        | Reference                                            |
 | ------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
 | Writing rules — full field docs, operators, actions, IP blocking, patterns                  | [references/rules.md](references/rules.md)           |
-| Cloudflare-specific setup, Lists API, expression translation, limitations                   | [references/cloudflare.md](references/cloudflare.md) |
+| Cloudflare-specific setup, Lists API, managed rule groups, expression translation, limitations | [references/cloudflare.md](references/cloudflare.md) |
 | Fastly-specific setup, condition/action mapping, rate-limit signal requirement, limitations | [references/fastly.md](references/fastly.md)         |
+| GCP Cloud Armor setup, CEL translation, priority model, manual e2e verification runbook     | [references/gcp.md](references/gcp.md)                |
 | Available templates and what they protect against                                           | [references/templates.md](references/templates.md)   |
 | CI/CD integration, automation, export formats, validation in pipelines                      | [references/cicd.md](references/cicd.md)             |
 

package/skills/doorman/references/cloudflare.md

@@ -54,37 +54,50 @@ doorman list --provider cloudflare          # Show deployed rules
 
 ## Rule Translation
 
-Doorman translates its unified rule format into Cloudflare Wirefilter expressions automatically. The translation is bidirectional — `doorman download` pulls Cloudflare expressions back into the unified format.
+Doorman translates its unified rule format (`conditions`/`enabled`/`action: {type}` — different from the legacy shape [rules.md](rules.md) documents) into Cloudflare Wirefilter expressions automatically. The translation is bidirectional — `doorman download` pulls Cloudflare expressions back into the unified format. Cloudflare requires the unified format — a config with `provider: "cloudflare"` cannot use the legacy `conditionGroup`/`mitigate` shape.
 
 ### Field Mapping
 
-| Doorman Type         | Cloudflare Field              |
-| -------------------- | ----------------------------- |
-| `path`               | `http.request.uri.path`       |
-| `method`             | `http.request.method`         |
-| `host`               | `http.host`                   |
-| `user_agent`         | `http.user_agent`             |
-| `ip_address`         | `ip.src`                      |
-| `header`             | `http.request.headers["key"]` |
-| `query`              | `http.request.uri.query`      |
-| `cookie`             | `http.cookie`                 |
-| `geo_country`        | `ip.geoip.country`            |
-| `geo_city`           | `ip.geoip.city`               |
-| `geo_continent`      | `ip.geoip.continent`          |
-| `geo_country_region` | `ip.geoip.subdivision_1`      |
-| `geo_as_number`      | `ip.geoip.asnum`              |
-| `scheme`             | `ssl` (boolean)               |
+Cloudflare supports all 15 unified condition fields:
+
+| Doorman Field | Cloudflare Field              | Notes                                                                                    |
+| -------------- | ------------------------------ | ------------------------------------------------------------------------------------------ |
+| `ip`          | `ip.src`                      |                                                                                          |
+| `country`     | `ip.geoip.country`            |                                                                                          |
+| `region`      | `ip.geoip.subdivision_1`      |                                                                                          |
+| `city`        | `ip.geoip.city`                |                                                                                          |
+| `asn`         | `ip.geoip.asnum`               |                                                                                          |
+| `path`        | `http.request.uri.path`       |                                                                                          |
+| `host`        | `http.host`                   |                                                                                          |
+| `method`      | `http.request.method`         |                                                                                          |
+| `header`      | `http.request.headers["key"]` | Requires `key` (the header name)                                                        |
+| `query`       | `http.request.uri.query`      | ⚠️ `key` is currently ignored — matches the whole query string, not one parameter ([doorman#263](https://github.com/gfargo/doorman/issues/263)) |
+| `cookie`      | `http.cookie["key"]`          | Requires `key` (the cookie name)                                                         |
+| `user_agent`  | `http.user_agent`             |                                                                                          |
+| `referer`     | `http.referer`                |                                                                                          |
+| `scheme`      | `ssl` (boolean)                |                                                                                          |
+| `port`        | `cf.edge.server_port`         |                                                                                          |
+
+### Operator Mapping
+
+Cloudflare supports all 15 unified operators exactly, no approximation — `not_contains`/`not_in`/`not_exists` compile to a wrapped `not (...)` expression rather than a single wirefilter token, but the semantics are exact:
+
+`eq`, `ne`, `contains`, `not_contains`, `starts_with`, `ends_with`, `matches`, `in`, `not_in`, `gt`, `ge`, `lt`, `le`, `exists`, `not_exists`
+
+`matches` (regex) may be plan-restricted on Cloudflare's side — regex matching in the Ruleset Engine is an Enterprise-plan feature on some plans. Doorman always emits the correct `matches` expression regardless of plan; Cloudflare's API may reject it if your zone's plan doesn't support regex. Use `contains`/`starts_with`/`ends_with` as fallbacks if you hit this.
 
 ### Action Mapping
 
-| Doorman Action | Cloudflare Action                |
-| -------------- | -------------------------------- |
-| `deny`         | `block`                          |
-| `challenge`    | `managed_challenge`              |
-| `rate_limit`   | `block` + `ratelimit` config     |
-| `redirect`     | `redirect` + `from_value` params |
-| `log`          | `log`                            |
-| `bypass`       | `skip`                           |
+| Doorman Action | Cloudflare Action                | Notes                                                                                                                  |
+| --------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `log`          | `log`                              |                                                                                                                        |
+| `deny`         | `block`                            |                                                                                                                        |
+| `challenge`    | `managed_challenge`                | Cloudflare's `challenge`/`managed_challenge`/`js_challenge` all fold back to unified `challenge` on `download` — a one-way narrowing, not a failure |
+| `bypass`       | `skip`                             |                                                                                                                        |
+| `allow`        | `allow`                            |                                                                                                                        |
+| `block`        | `block`                            | Same target as `deny`                                                                                                  |
+| `rate_limit`   | `block` + `ratelimit` config       | ⚠️ If `action.rateLimit` is omitted, this silently becomes a plain unconditional `block` rule with no rate-limit effect — no error raised locally |
+| `redirect`     | `redirect` + `from_value` params   | ⚠️ If `action.redirect` is omitted, this silently becomes a rule with no redirect target — no error raised locally |
 
 ## Lists API (Bulk IP Management)
 
@@ -99,27 +112,27 @@ Without `CLOUDFLARE_ACCOUNT_ID`, IP blocking falls back to individual WAF rules
 
 ## Limitations & Differences
 
-| Feature                   | Vercel              | Cloudflare                    | Notes                                             |
-| ------------------------- | ------------------- | ----------------------------- | ------------------------------------------------- |
-| `re` operator             | All plans           | Enterprise only               | Use `sub`/`pre`/`suf` as alternatives             |
-| `environment` type        | Yes                 | No                            | Vercel-specific concept                           |
-| `ja3_digest`/`ja4_digest` | Yes                 | No                            | Vercel TLS fingerprints                           |
-| `region` type             | Yes                 | No                            | Vercel edge region                                |
-| IP Lists (bulk)           | Individual rules    | Lists API                     | Cloudflare needs `accountId`                      |
-| Max custom rules          | ~100                | 5-125 (plan dependent)        | Free: 5, Pro: 20, Business: 100, Enterprise: 125+ |
-| Rate limit                | Via rule action     | Separate phase                | Different underlying mechanism                    |
-| Rule order                | Parallel evaluation | Sequential (first match wins) | Ordering matters on Cloudflare                    |
+`environment`, `ja3_digest`, `ja4_digest` are **legacy-format-only concepts** — they exist on Vercel's native rule type but have no unified-format equivalent at all, so they're not reachable through a `provider`/`providers`-tagged config for *any* provider, not just Cloudflare. Every other unified field maps to something on Cloudflare — see Field Mapping above.
+
+| Feature                   | Cloudflare                    | Notes                                             |
+| -------------------------- | ------------------------------ | ------------------------------------------------- |
+| `matches` (regex)         | Enterprise-plan-restricted on some plans | Doorman emits it regardless; Cloudflare's API may reject it — see Operator Mapping above |
+| IP Lists (bulk)           | Lists API                      | Needs `accountId`; without it, falls back to individual `ip.src` rules |
+| Max custom rules          | 5-125 (plan dependent)         | Free: 5, Pro: 20, Business: 100, Enterprise: 125+ |
+| Rate limit                | Separate phase                 | `ratelimit` config attached to a `block` action, not a distinct rule type |
+| Rule order                | Sequential (first match wins)  | `priority` is fully honoured — unlike Vercel, which can't reposition rules that already exist remotely |
+| Managed rule groups       | Supported via `managedRules`   | See [Managed Rule Groups](#managed-rule-groups) below — Cloudflare-only among doorman's providers today |
 
 ## Translation Warnings
 
 The `RuleTranslator` surfaces warnings when a translation is lossy:
 
-- **Regex on non-Enterprise** — `re` operator only works on Cloudflare Enterprise; downgraded to `contains` with a warning
-- **Unsupported types** — Vercel-only fields (`environment`, `ja3_digest`, `ja4_digest`, `region`) are dropped with a warning
-- **Duration differences** — `actionDuration` maps differently between providers
+- **Unmapped managed-ruleset override action** — an `action`/`overrides[].action` in `managedRules` with no Cloudflare equivalent (only `log`/`deny`/`challenge`/`allow` map cleanly) is dropped with a warning
 - **Negation edge cases** — complex negated conditions may produce subtly different behavior in Wirefilter
 
-Run `doorman validate` to surface warnings before deploying — it auto-detects Cloudflare from the config's `provider` field.
+Doorman does **not** currently warn on the `rate_limit`/`redirect` omitted-config-object cases noted in Action Mapping above, or the `query`-condition `key`-ignored case noted in Field Mapping above ([doorman#263](https://github.com/gfargo/doorman/issues/263)) — both are known gaps, not something `doorman validate` catches today. Double-check those specifically rather than relying on validation output.
+
+Run `doorman validate` to surface the warnings that do exist before deploying — it auto-detects Cloudflare from the config's `provider` field.
 
 ## Cloudflare-Specific Validation
 
@@ -139,6 +152,39 @@ The `CloudflareOptimizer` consolidates rules for efficient deployment:
 - Deduplicates IP entries across rules and Lists
 - Computes minimal changesets to avoid unnecessary API calls (diff-based sync)
 
+## Managed Rule Groups
+
+Cloudflare is the only provider doorman can deploy vendor-managed rulesets (Cloudflare Managed Ruleset, OWASP CRS, etc.) for today. Add a `managedRules` array alongside `rules`/`ips`:
+
+```json
+{
+  "managedRules": [
+    {
+      "id": "execute-owasp-crs",
+      "ruleset": "efb7b8c949ac4650a09736fc376e9aee",
+      "name": "OWASP Core Ruleset",
+      "enabled": true,
+      "action": "log",
+      "overrides": [
+        { "ruleId": "981176", "action": "deny" },
+        { "ruleId": "981245", "enabled": false }
+      ]
+    }
+  ]
+}
+```
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | string | No | Doorman's diff/sync identifier for this deployment. Omit for a new declaration — doorman assigns one on first sync. |
+| `ruleset` | string | Yes | The vendor ruleset id to deploy (e.g. Cloudflare Managed Ruleset's well-known id shown above) |
+| `name` | string | No | Human label |
+| `enabled` | boolean | Yes | Whether this deployment is active |
+| `action` | string | No | Ruleset-wide override — downgrade every rule in the group to this action. One of `log`, `deny`, `challenge`, `allow` |
+| `overrides` | array | No | Per-rule overrides within the ruleset — `{ "ruleId": string, "action"?: string, "enabled"?: boolean }`, referenced by the *vendor's* rule id within that ruleset, not a doorman id |
+
+Managed rule groups deploy in Cloudflare's separate managed-rules phase, evaluated independently of custom `rules` — no ordering interaction to think about between the two. `getChanges`/`syncRules` diff `managedRules` the same way as `rules`/`ips` — `doorman diff`/`doorman sync` cover it with no extra flags.
+
 ## Example: Full Cloudflare Config
 
 ```json
@@ -156,31 +202,37 @@ The `CloudflareOptimizer` consolidates rules for efficient deployment:
       "id": "rule_block_bots",
       "name": "Block Bad Bots",
       "description": "Block known malicious crawlers",
-      "active": true,
-      "conditionGroup": [
-        { "conditions": [{ "type": "user_agent", "op": "sub", "value": "AhrefsBot" }] },
-        { "conditions": [{ "type": "user_agent", "op": "sub", "value": "SemrushBot" }] }
+      "enabled": true,
+      "conditions": [
+        { "field": "user_agent", "operator": "contains", "value": "AhrefsBot", "group": 0 },
+        { "field": "user_agent", "operator": "contains", "value": "SemrushBot", "group": 1 }
       ],
-      "action": { "mitigate": { "action": "deny" } }
+      "action": { "type": "deny" }
     },
     {
       "id": "rule_rate_limit_api",
       "name": "Rate Limit API",
       "description": "Limit API requests to 100/min per IP",
-      "active": true,
-      "conditionGroup": [{ "conditions": [{ "type": "path", "op": "pre", "value": "/api/" }] }],
+      "enabled": true,
+      "conditions": [{ "field": "path", "operator": "starts_with", "value": "/api/" }],
       "action": {
-        "mitigate": {
-          "action": "rate_limit",
-          "rateLimit": {
-            "requests": 100,
-            "window": "1m",
-            "characteristics": ["ip.src"]
-          }
+        "type": "rate_limit",
+        "rateLimit": {
+          "requests": 100,
+          "window": "1m",
+          "characteristics": ["ip.src"]
         }
       }
     }
   ],
+  "managedRules": [
+    {
+      "ruleset": "efb7b8c949ac4650a09736fc376e9aee",
+      "name": "OWASP Core Ruleset",
+      "enabled": true,
+      "action": "log"
+    }
+  ],
   "ips": [{ "ip": "203.0.113.0/24", "action": "deny", "notes": "Known attack subnet" }]
 }
 ```

package/skills/doorman/references/fastly.md

@@ -119,7 +119,7 @@ Unlike classic Fastly VCL services, Next-Gen WAF rule and list writes take effec
 | -------------------------- | ----------------------------- | ---------------------- | ------------------------------------------------------------------------- |
 | Geo targeting              | Country/city/continent/region | Country only           | No sub-country condition field                                            |
 | Rule ordering              | Best-effort (insertion order) | None                   | Next-Gen WAF rules are evaluated independently — `priority` has no effect |
-| Managed/vendor rule groups | CRS (enterprise)              | Templated signal rules | Not yet configurable through Doorman for either provider (#183)           |
+| Managed/vendor rule groups | CRS (enterprise)              | Templated signal rules | Doorman-managed on Cloudflare only ([cloudflare.md](cloudflare.md)); not yet configurable through Doorman for Vercel or Fastly |
 | Signal/exclusion rules     | —                             | `type: signal`         | Not managed by Doorman — see below                                        |
 
 Fastly rules of type `signal` or `templated_signal` (which tag or exclude WAF signals rather than allow/block/redirect a request) are skipped entirely by `doorman download`/`fetchConfig` rather than forced into a lossy `UnifiedRule` — they simply don't appear in the local config.

package/skills/doorman/references/gcp.md

@@ -0,0 +1,184 @@
+# GCP Cloud Armor Provider Reference
+
+Google Cloud Armor support in Doorman (beta). Manage a Cloud Armor security policy's custom rules through the same config-as-code workflow as Vercel/Cloudflare/Fastly.
+
+## Setup
+
+### Environment Variables
+
+Unlike the other three providers, GCP intentionally reuses GCP's own ecosystem-standard env var names rather than doorman-prefixed ones — a user with GCP already configured for anything else likely has these set already:
+
+```bash
+GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json  # Optional — service account key path; omit to use Application Default Credentials
+GOOGLE_CLOUD_PROJECT=your-project-id              # Required — GCP project ID
+GCP_POLICY_NAME=your-policy-name                  # Required — Cloud Armor security policy name (no ecosystem-standard env var exists for this)
+```
+
+### One-Time Project Setup
+
+1. **Enable the Compute Engine API** — Cloud Armor security policies live under it:
+   ```bash
+   gcloud services enable compute.googleapis.com --project=YOUR_PROJECT
+   ```
+2. **Authenticate** — two options:
+   - **Application Default Credentials** (recommended for local/dev use): `gcloud auth application-default login`. Uses your own Google account, no key file to create, store, or later revoke. Leave `serviceAccountKeyPath`/`GOOGLE_APPLICATION_CREDENTIALS` unset — `GoogleAuth` falls through to ADC automatically.
+   - **Service account key** (for CI/production): create a service account with `roles/compute.securityAdmin` (the narrowest predefined role covering `securityPolicies.get/insert/patch/addRule/patchRule/removeRule/list`), generate a JSON key, and point `GOOGLE_APPLICATION_CREDENTIALS`/`serviceAccountKeyPath` at it.
+3. **Create the security policy itself** — Doorman manages rules *within* an existing policy, it does not create the policy resource:
+   ```bash
+   gcloud compute security-policies create YOUR_POLICY_NAME --description="managed by doorman"
+   ```
+
+### Config Shape
+
+Multi-provider config with explicit provider declaration:
+
+```json
+{
+  "$schema": "https://doorman.griffen.codes/schema.json",
+  "provider": "gcp",
+  "providers": {
+    "gcp": {
+      "projectId": "your-project-id",
+      "policyName": "your-policy-name"
+    }
+  },
+  "rules": [],
+  "ips": []
+}
+```
+
+Or pass `--provider gcp` to any provider-aware command to override auto-detection. `serviceAccountKeyPath` has no `configKey` — a filesystem path is environment-specific and never belongs in a config file meant to be shared/committed; set it via `GOOGLE_APPLICATION_CREDENTIALS` instead.
+
+## Usage
+
+`doorman init` only supports Vercel today — it has no `--provider` flag and doesn't prompt for GCP credentials. Create `.doorman.json` by hand using the config shape above, then:
+
+```bash
+doorman validate                    # Validate — auto-detects gcp from the config's `provider` field
+doorman status --provider gcp
+doorman diff --provider gcp
+doorman sync --provider gcp
+doorman download --provider gcp
+```
+
+## Rule Translation
+
+Cloud Armor rules match on CEL (Common Expression Language) — an expression-string DSL, structurally the same problem as Cloudflare's Wirefilter. Doorman generates/parses only the flat subset Cloud Armor's real-world usage actually needs: Google's own docs cap this at "up to five subexpressions" combined with `&&`/`||`, no nesting — unlike Wirefilter, Cloud Armor's CEL condition tree never needs an OR nested inside an AND.
+
+### Field Mapping
+
+| Doorman Field | Cloud Armor CEL                                     | Notes                                                                              |
+| -------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `ip`           | `origin.ip == '...'` or `inIpRange(origin.ip, '...')` | Bare address uses `==`; a CIDR value (contains `/`) uses `inIpRange()`              |
+| `path`         | `request.path`                                        |                                                                                     |
+| `method`       | `request.method`                                      |                                                                                     |
+| `country`      | `origin.region_code`                                  | Country-level only                                                                 |
+| `asn`          | `origin.asn`                                          | Numeric comparison                                                                 |
+| `host`         | `request.headers['host']`                             | Guarded with `has(...)` — indexing an absent header key is a CEL runtime error     |
+| `user_agent`   | `request.headers['user-agent']`                       | Guarded with `has(...)`                                                            |
+| `referer`      | `request.headers['referer']`                          | Guarded with `has(...)`                                                            |
+| `header`       | `request.headers['<key>']`                            | Requires `key` (the header name); guarded with `has(...)`                          |
+| `query`        | `request.query`                                       | Raw, undecoded query string — no parsed per-parameter map                          |
+| `cookie`       | `request.headers['cookie']`                           | No parsed cookie map — see Cookie Matching below                                   |
+
+Fields with **no CEL equivalent at all** (`region`, `city`, `port`, `scheme`) fail loudly with a clear error rather than being silently dropped or approximated — Cloud Armor has no continent/region/city-level geo attribute (only country-level `origin.region_code`), and no per-request port attribute (Cloud Armor operates at L7 behind a load balancer). A rule using one of these doesn't sync at all; there's no partial/lossy version of it to fall back to.
+
+### Cookie Matching
+
+Cloud Armor has no parsed per-cookie map, only the raw `Cookie` header string. Without a `key`, a cookie condition checks the whole header. *With* a `key` (the common case — "is this specific cookie set to this value") Doorman composes a `key=value` substring and searches for it in the raw header — the only thing CEL can actually check. Only `eq`/`ne`/`contains`/`not_contains` have an unambiguous meaning against that synthesized substring; any other operator on a keyed cookie condition throws rather than emitting a check that looks precise but isn't.
+
+### Action Mapping
+
+| Doorman Action | Cloud Armor Action | Notes                                                                 |
+| --------------- | -------------------- | ----------------------------------------------------------------------- |
+| `deny`, `block` | `deny(403)`           |                                                                        |
+| `allow`         | `allow`               |                                                                        |
+| `bypass`        | `allow`               |                                                                        |
+| `rate_limit`    | `throttle`            | Requires `rateLimitOptions` — see below                               |
+| `redirect`      | `redirect`             | Requires `redirectOptions` (target URL)                               |
+| `log`           | `allow` + `preview: true` | No dedicated log-only action — evaluates and logs without enforcing |
+| `challenge`     | `deny(403)` (with a warning) | No standalone challenge action for ordinary custom rules       |
+
+## The Priority Model
+
+Cloud Armor's real structural difference from every other provider: there is no separate, server-assigned rule id. A rule's `priority` — an explicit integer required on every rule — is simultaneously its doorman `id`, its evaluation order, **and** its addressing key for updates/deletes.
+
+- A new local rule/IP with no priority yet gets one assigned automatically during `sync`, spaced 1000 apart (matching common Cloud Armor/`gcloud` convention), checked against a freshly-fetched remote policy to avoid collisions.
+- **Cloud Armor has no "change priority" operation.** Editing a rule's `priority` in config relocates it via remove-then-add-at-the-new-priority — the only relocation path the real API supports — not an in-place PATCH.
+- Cloud Armor rejects a priority that collides with an existing rule outright.
+
+## No Dedicated IP-Blocking Resource
+
+Unlike Vercel/Cloudflare/Fastly, Cloud Armor has no separate IP-list resource — an `ips[]` entry is just an ordinary rule under the hood, with a single `ip == X` (or `inIpRange(...)` for CIDR) CEL condition and nothing else layered on. Doorman classifies a fetched rule as an IP entry only when it has *exactly* that shape (one condition, `allow`/`deny(403)` action, nothing else) — a hand-authored `rules[]` entry that happens to match on `ip` alone is left as a rule, not silently reclassified into `ips[]`.
+
+## The Mandatory Default Rule
+
+Every real Cloud Armor security policy carries one rule Doorman never manages: a server-injected default catch-all at the maximum priority (`2147483647`), using a different match shape (`versionedExpr`/`config.srcIpRanges`, not CEL) — it cannot be removed, only its action changed. Doorman skips it entirely on fetch; it never appears in your local config and is never a candidate for deletion. If you need to change its action (rarely necessary — it only fires when nothing else matches), use `gcloud compute security-policies describe`/`update` directly.
+
+Any *other* rule using that same basic (non-CEL) match shape — e.g. hand-created via `gcloud ... --src-ip-ranges` or the Console — gets an explicit warning on fetch rather than a crash or a silent drop: Doorman can't represent it, and leaves it unmanaged.
+
+## Rate Limiting
+
+`rate_limit` maps to Cloud Armor's `throttle` action, with `rateLimitOptions.rateLimitThreshold` (`count`/`intervalSec`) and `conformAction: 'allow'`/`exceedAction: 'deny(429)'`. A `rate_limit` rule with no `rateLimit` block configured emits a warning and will likely be rejected by the API — Cloud Armor requires `rateLimitOptions` for this action.
+
+## Operations & Polling
+
+Every mutating call (`addRule`/`patchRule`/`removeRule`) returns a long-running GCP Operation, not the updated resource directly. Doorman polls it internally — starting at 250ms, backing off toward a 1s ceiling, capped at 60s total — until it reports `DONE`, so every command still presents the same "await and it's done" shape the other three providers already have; GCP's async-operation model never leaks into the CLI surface.
+
+## Limitations & Differences
+
+| Feature                     | Vercel                        | GCP Cloud Armor                          | Notes                                                                    |
+| ----------------------------- | -------------------------------- | ------------------------------------------- | --------------------------------------------------------------------------- |
+| Rule ordering                | Best-effort (insertion order)     | Explicit required `priority`                | Lower priority number evaluates first; collisions rejected outright     |
+| IP blocking                  | Dedicated resource                | Just a specially-shaped `rules[]` entry     | No separate list/resource — see above                                   |
+| Geo targeting                | Country/city/continent/region     | Country only (`origin.region_code`)         | `region`/`city` fields throw rather than silently drop                  |
+| Port / scheme conditions     | Yes                                | No CEL equivalent                            | Throw rather than silently drop                                         |
+| Managed/vendor rule groups   | —                                  | Preconfigured WAF rules exist on the real API | Not yet configurable through Doorman for any provider (tracked separately) |
+| Standalone challenge action  | Yes                                | No                                            | Falls back to `deny(403)` with a warning                                |
+| Change a rule's priority     | N/A (no priority concept)         | Remove + re-add under the new priority       | No in-place relocation on the real API                                  |
+
+## Manual End-to-End Verification
+
+Cloud Armor is the one provider where a fully-offline mock-server e2e is not possible: `demos/cloudarmor-mock-server.mjs` can only exercise `CloudArmorClient`'s request/response handling once a caller already has a real, working `GoogleAuth` setup — `google-auth-library`'s OAuth2 token exchange has to reach Google's real `oauth2.googleapis.com` even for local testing (see that file's own top-of-file comment). Verifying a change to this provider for real means testing against an actual, disposable GCP resource:
+
+1. Confirm `gcloud` is authenticated: `gcloud auth application-default login`.
+2. Enable the API once per project: `gcloud services enable compute.googleapis.com --project=YOUR_PROJECT`.
+3. Create a throwaway policy: `gcloud compute security-policies create doorman-e2e-test --description="disposable - safe to delete"`.
+4. Hand-author a `.doorman.json` pointing `providers.gcp.projectId`/`policyName` at it, with a couple of rules and IPs. Use RFC 5737 documentation-only ranges for IPs (`203.0.113.0/24`, `198.51.100.0/24`, `192.0.2.0/24`) — never real addresses.
+5. Run the full command surface against it: `status` → `diff` → `sync --ci` → `status` → `download --ci`. Then edit a rule's `priority` in the config and re-sync to exercise relocation, and remove a rule and run `sync --ci --allowDeletions` to exercise deletion — `sync --ci` alone correctly refuses to delete anything without that flag, rather than silently proceeding.
+6. Delete the policy when done: `gcloud compute security-policies delete doorman-e2e-test --project=YOUR_PROJECT --quiet`.
+
+**Cost**: Cloud Armor Standard is $5/policy/month + $1/rule/month (pay-as-you-go, prorated), independent of whether the policy is attached to a backend service. Trivial for a verification run lasting a few hours, but not literally free — delete the policy promptly when done.
+
+## Example: Full GCP Config
+
+```json
+{
+  "$schema": "https://doorman.griffen.codes/schema.json",
+  "provider": "gcp",
+  "providers": {
+    "gcp": {
+      "projectId": "my-gcp-project",
+      "policyName": "doorman-managed-policy"
+    }
+  },
+  "rules": [
+    {
+      "name": "Block Bad Bots",
+      "enabled": true,
+      "conditions": [{ "field": "user_agent", "operator": "contains", "value": "AhrefsBot" }],
+      "action": { "type": "deny" }
+    },
+    {
+      "name": "Rate Limit API",
+      "enabled": true,
+      "conditions": [{ "field": "path", "operator": "starts_with", "value": "/api/" }],
+      "action": {
+        "type": "rate_limit",
+        "rateLimit": { "requests": 100, "window": "1m" }
+      }
+    }
+  ],
+  "ips": [{ "ip": "203.0.113.0/24", "action": "deny", "notes": "Known attack subnet" }]
+}
+```