Epic: Google Cloud Armor adapter

[gfargo]

Split out of the #156 roadmap spike (Tier 4: provider epic). Medium-large.

Cost profile

Cloud Armor custom rules use CEL — another flat expression-string DSL, structurally the same problem as Cloudflare's wirefilter. Expect to reuse the pattern doorman already built (ExpressionBuilder for generation + WirefilterParser for parsing, ~967 lines combined) but not the code: a CelExpressionBuilder + CelParser pair of comparable size.

That puts this in the ~5-6x cost class relative to a structured-JSON provider. Budget accordingly — the expression layer, not the client or service, is the bulk of the work.

Note the parser side is now a well-understood problem: #178 established the "invert our own generator" approach (parse exactly the grammar subset we emit, report anything else as unparseable rather than guessing). Apply the same discipline to CEL — do not attempt general-purpose CEL parsing.

Dependencies

Required: #181 (open ProviderType), #182 (generalize credentials — GCP service-account/OAuth2 is the case that most stresses the current flat-token assumption)
Required: #185 (multi-resource targeting) — Cloud Armor policies attach to N backend services; this is not optional for real use
Recommended: #183 (managed rule groups) — preconfigured OWASP CRS rules are most of a typical Cloud Armor policy
Recommended first: #179 — Cloud Armor requires an explicit integer priority on every rule, so doorman's ordering story must be real before this lands

Scope

• CloudArmorClient extending BaseFirewallClient, with GCP OAuth2/service-account auth
• CloudArmorFirewallService implementing IFirewallProvider
• CelExpressionBuilder + CelParser (mirroring the wirefilter pair, including round-trip tests)
• FieldMapper entries for CEL's request attribute paths
• Preconfigured-WAF-rule support via Model: managed rule group support (config surface + provider plumbing) #183's managed-rules surface
• Mock server fixture + end-to-end verification

Known unknowns

• CEL subset actually accepted by Cloud Armor's expr.expression field (it's narrower than full CEL)
• How priority collisions are handled (Cloud Armor rejects duplicates)
• Whether download/backup can faithfully reconstruct a policy that mixes custom + preconfigured rules

Acceptance criteria

• All 8 commands work with no command-layer changes
• CEL round-trip fidelity tests for every condition shape doorman can express
• Explicit, warned failure (never silent corruption) for any rule doorman can't faithfully represent in CEL

[gfargo]

Two scoping findings from research before starting implementation — both change this epic's shape enough to record here before writing code.

#185 is not actually required for GCP

This issue lists #185 (multi-resource targeting) as Required, with the reasoning "Cloud Armor policies attach to N backend services; this is not optional for real use." I checked this against the real GCP API (Compute v1 discovery document, REST reference, and the Terraform provider docs for google_compute_security_policy / google_compute_backend_service), and the attachment relationship is purely one-directional and lives entirely on the backend-service side:

• google_compute_security_policy's full field list (ddosProtectionConfig, rules, adaptiveProtectionConfig, associations [org/folder-tier only, not this], etc.) has no field referencing backend services at all.
• google_compute_backend_service carries the securityPolicy pointer instead, set via backendServices.setSecurityPolicy — a separate step, after the policy and its rules already exist (gcloud compute backend-services update BACKEND --security-policy=POLICY).
• Every securityPolicies.* method (insert, patch, addRule, patchRule, removeRule, get, list) takes only project + policy name/priority — none take or expose a backend-service parameter.

So a security policy's rule content is fully manageable, independent of which (if any) backend services reference it — the same shape doorman already has for Vercel (one project) and Cloudflare (one zone). "Attach this policy to backend X" is a separate piece of GCP infrastructure config (normally Terraform/Pulumi/gcloud's job), not something a WAF-rules tool needs to own. This epic can target one security policy per config, exactly like every existing provider, with zero dependency on #185.

(#185 remains real for AWS — a WebACL's association with N ARNs is a first-class part of the WebACL API surface itself, a materially different shape. Left a note on #185 too.)

CEL's real-world Cloud Armor usage is flat, not recursive

The cost estimate above assumes a CelExpressionBuilder/CelParser pair "comparable size" to the wirefilter pair (~967 lines). I checked whether Cloud Armor's actual CEL usage needs #184's recursive condition tree (CEL syntactically supports arbitrary nesting, unlike wirefilter) — it doesn't. Google's own Cloud Armor CEL documentation and every real-world example I found (37 documented rule expressions across GCP's docs) are flat, single-level boolean chains — Google's own guidance caps this explicitly ("up to five subexpressions" combined with &&/||, no nesting). #184 is not needed for this epic; the CelExpressionBuilder/CelParser pair should mirror wirefilter's flat case only, which meaningfully undercuts the "~5-6x cost" estimate — closer to the wirefilter pair's actual size, not larger.

Net effect: this epic's real prerequisite list is just #181 (closed) + #182 (closed, #229/#230) — both already done. Starting implementation now.

[gfargo]

Status update: core adapter is shipped and merged.

• refactor: make BaseFirewallClient.getAuthHeaders() async #232 — async auth (GCP service-account/ADC OAuth2, refreshed per-request)
• feat: add CelExpressionBuilder/CelParser for Cloud Armor CEL #234 — CelExpressionBuilder + CelParser (flat-CEL only, per the scoping note above — round-trip tested)
• feat: add GCP Cloud Armor provider #238 — CloudArmorClient + CloudArmorFirewallService + full provider wiring (7-file shape matching Fastly's Epic: Fastly Next-Gen WAF adapter #186 precedent), plus demos/cloudarmor-mock-server.mjs and fixtures
• fix: apply UnifiedCondition.negated in Cloud Armor CEL generation #240 — fixed UnifiedCondition.negated not round-tripping through CEL generation

Two items from this issue's original scope are still open, not done:

• Preconfigured/managed rule groups (the "Recommended: Model: managed rule group support (config surface + provider plumbing) #183" scope item) — Model: managed rule group support (config surface + provider plumbing) #183 itself is still open, so Cloud Armor's managed-rule surface (OWASP CRS etc., "most of a typical Cloud Armor policy" per the cost profile above) isn't wired up yet.
• Real-GCP-project end-to-end verification — testing so far is unit tests plus the mock server fixture (demos/cloudarmor-mock-server.mjs), not a run against an actual GCP project/policy. The acceptance criteria here ("all 8 commands work," CEL round-trip fidelity, warned-not-silent failure on unrepresentable rules) are covered by mocked tests but not confirmed against the real API surface yet.

Leaving this open until at least the real-project e2e pass; whether to fold #183's managed-rule support in before closing or split it out as separate follow-up work is an open question.

[gfargo]

Update: ran a holistic epic-wide review (/code-review high against the cumulative #232+#234+#238+#240 diff, not per-PR) — the review this issue's earlier comment said was still outstanding. It found real problems the per-PR reviews missed, two of them severe enough to change the status below materially.

Fixed and merged (#253):

• Every real API call was sending zero auth headers. getRequestHeaders() returns a WHATWG Headers instance, not a plain object — BaseFirewallClient.makeRequest's {...headers} merge silently produced {}. Verified against the actual installed google-auth-library source and empirically in Node before fixing. This is almost certainly why the real-GCP-project e2e mentioned below has never succeeded — it would have failed on the first request with a 401/403, every time.
• Every fetched rule's CEL expression was being parsed twice per fetchConfig/getChanges call (classify, then translate) — fixed by threading the parsed result through instead of re-parsing.

Filed as follow-up issues (each needs a deliberate design decision, not a quick patch):

• gcp: a plain single-IP rule is misclassified as an IP-list entry, causing delete+recreate every sync #248 (critical) — a plain single-IP rules[] entry gets misclassified as an IP-list entry, causing delete+recreate every sync, forever, with a real enforcement gap each time
• gcp: editing a rule's priority never actually relocates it (PATCH addressed by old priority, body carries new) #249 (high) — editing a rule's priority in config silently never relocates it server-side
• gcp: a translation error mid-sync discards already-applied rule additions, permanently desyncing config #250 (high) — a translation error mid-sync can discard already-applied rule additions, permanently desyncing local config from what's actually live
• gcp: Operation polling has no fast-path/backoff, compounding with fully-sequential syncRules loops into slow syncs #251 — Operation polling has no backoff, compounding with fully-sequential sync loops into slow syncs
• Extract shared TokenStream + OR-branch validation between CelParser and WirefilterParser #252 (code-quality) — the new CEL parser hand-duplicates safety-critical logic from the existing Cloudflare wirefilter parser instead of sharing it (with a confirmed precedent: a bug fix already landed in one and never made it to the other)

Net effect on this epic's status: "core shipped, needs real-project e2e" undersold it — #248 and the auth-header bug both meant it would have failed immediately or actively corrupted state on first real use. With #253 merged, the provider can at least authenticate and sync now, but #248 in particular (rule misclassification) is a real correctness risk worth fixing before this is called done, not just before it's called polished.

Still open from before: real-GCP-project e2e (needs project ID / policy name / auth method), and whether #183's managed-rule support is in-scope for closing this epic or a deliberate follow-up.

[gfargo]

Update: all 5 follow-up issues from the epic-wide review are now fixed and merged.

• gcp: a plain single-IP rule is misclassified as an IP-list entry, causing delete+recreate every sync #248 → fix(gcp): a single-IP rules[] entry no longer gets misclassified as an ips[] entry #254 — a single-IP rules[] entry no longer gets misclassified as an ips[] entry and destroyed/recreated every sync.
• gcp: editing a rule's priority never actually relocates it (PATCH addressed by old priority, body carries new) #249 → fix(gcp): relocate a rule via remove+add, not patch, when its priority changes #256 — editing only a rule's priority now actually relocates it (remove+add), instead of a silent no-op PATCH.
• gcp: a translation error mid-sync discards already-applied rule additions, permanently desyncing config #250 → fix(gcp): isolate per-rule translation failures during sync instead of aborting the whole batch #257 — a translation failure on one rule during sync no longer discards already-applied changes to other rules in the same batch.
• gcp: Operation polling has no fast-path/backoff, compounding with fully-sequential syncRules loops into slow syncs #251 → fix(gcp): back off Operation polling instead of always sleeping the full interval #258 — Operation polling now backs off from a fast 250ms start toward the previous 1000ms ceiling, instead of always sleeping the full second. (The issue's other half — parallelizing sync's within-category loops — was deliberately left alone; no real-API evidence Cloud Armor tolerates concurrent mutations against one policy, so it stays sequential until that's verified.)
• Extract shared TokenStream + OR-branch validation between CelParser and WirefilterParser #252 → refactor(translators): share TokenStream and OR-validation between CEL/wirefilter parsers #259 — CelParser and WirefilterParser now share their token-cursor and OR-branch fail-closed validator instead of hand-duplicating them, closing the gap that already let one bug fix (fix: parse negated starts_with/ends_with/matches/gt/ge/lt/le CEL back correctly #241) land in one parser and never reach the other.

Combined with #253 (the two critical bugs — dropped auth headers, double CEL parsing), that's all 7 findings from the review resolved.

What's left before this epic is actually done, not just "core shipped":

• Real-GCP-project end-to-end verification — still not done. Testing so far is unit tests plus the local mock server; nothing has run against an actual GCP project/policy yet. This needs project ID / policy name / auth method to proceed, and is now meaningfully more likely to succeed than when this was last attempted, since the auth-header bug (fix(gcp): auth headers silently dropped on every request; CEL parsed twice per rule #253) that would have failed it outright is fixed.
• Model: managed rule group support (config surface + provider plumbing) #183 (managed/preconfigured rule groups) — still open, still part of this epic's original scope ("most of a typical Cloud Armor policy" per the cost estimate above). Open question whether it needs to land before closing this issue or is better split into its own follow-up.

[gfargo]

Update: ran the first real end-to-end pass against an actual GCP project (not just unit tests + the local mock server) — disposable Cloud Armor policy, status/diff/sync/download, priority relocation, deletion, then tore the policy down.

Found and fixed 3 real bugs, none reachable by the existing unit/mock-server coverage:

• Every real policy carries a mandatory, server-injected default rule (priority 2147483647) using the basic versionedExpr/config match shape, not CEL — translatePolicy assumed every rule was CEL-shaped and crashed on the very first real fetchConfig/getChanges call. This means real-project usage would have failed outright on literally the first command, every time — unlike the auth-header bug (fix(gcp): auth headers silently dropped on every request; CEL parsed twice per rule #253), the mock server's own fixtures never happened to include this rule either, so it was invisible there too.
• applySyncResultToConfig only ever wrote id remappings back onto config.rules[], never config.ips[] — a brand-new IP rule kept id: undefined forever after a real sync, so every following status/diff misread it as a new local add with the real remote entry as an orphaned delete.
• download's --ci flag never actually gated its overwrite-confirmation prompt, so download couldn't run outside a real TTY at all, despite documenting the flag for exactly that.

All three fixed, regression-tested, mutation-verified: #264 (merged).

With those fixed, the full command surface verified clean against real infrastructure: auth headers (confirming #253's fix works against Google's real oauth2.googleapis.com), rule/IP add+update+delete, priority collision-free assignment, priority relocation (remove+add, #249's path), and Operation long-poll-to-DONE, all against a live policy.

Still open from this epic's original scope: #183 (managed/preconfigured rule groups).