Queue CF Edge Protection — Design

Status: Accepted Date: 2026-05-11 UTC ADR: ADR-0078 Parent card: #1733 WAF threat model: docs/security/waf-threat-model-2026-05-11.md (HIGH-WAF-2) Sister doc: docs/architecture/waf-strategy.md (ADR-0077, just merged)

1. Context

Queue is the centralized identity / RBAC / customer / audit service (ADR-0076: C++, Drogon, running on raxx-queue-{prod,staging}.herokuapp.com). As of 2026-05-11 UTC the Heroku origin URL is directly routable from the internet: no Cloudflare proxy sits in front of it, so all of the following are bypassed:

• Cloudflare WAF managed rulesets
• Cloudflare Bot Fight Mode
• CF rate-limiting rules
• CF Access (any future admin gate)

The WAF threat model (security/waf-threat-model-2026-05-11.md §S11) classified this HIGH-WAF-2. Endpoints reachable in the current state include auth paths that are password-equivalents when Phase 2 ships (backup-codes/redeem) and the billing CRUD endpoints in Phase 1.

This design closes that gap using the same layered pattern applied to Raptor (FLAG_ENFORCE_CF_ORIGIN, cloudflare_origin_guard.py) extended for a C++ / Drogon service.

2. Invariants (non-negotiable)

1. No stored credentials. This design does not change how credentials are handled. CF origin guard headers contain no user credential material.
2. Passkeys / WebAuthn only. Not affected by this design. Edge protection sits in front of auth, not inside it.
3. Audit trail for every state change affecting money, permissions, or data access. The origin guard's reject events are logged at WARN with direct_origin_blocked structured key for audit-trail searchability.
4. Credentials into infra, not into code. CLOUDFLARE_ZONE_ID, CLOUDFLARE_API_TOKEN, and all Heroku domain-attachment secrets are loaded from Infisical at operator runtime; none are committed.
5. Paper-first gating. Not directly relevant here; order-execution paths are in Raptor, not Queue Phase 1.
6. Kill-switch. FLAG_ENFORCE_QUEUE_CF_ORIGIN defaults false; origin guard can be disabled without redeploy.
7. GDPR. The origin guard logs only path and remote_addr; it logs no PII from request bodies. Retention follows Queue's audit log policy (2 years, DPA).

3. Decision Matrix

Three deployment patterns for a Heroku app behind Cloudflare:

Origin guard approach: CF-Connecting-IP header presence check. Cloudflare injects this on every proxied request. Requests arriving at the Heroku origin URL directly carry no CF-Connecting-IP. This is the same proof used by cloudflare_origin_guard.py in Raptor.

Service-to-service auth: Existing InternalAuthFilter (shipped in QP-C7 / #1717) uses X-Queue-Service-Token / Authorization: Bearer <token> on /api/internal/* routes. This is sufficient for in-band service identity. CF Access service tokens are NOT added for service-to-service. Rationale: CF Access service tokens introduce a paired WAF skip rule requirement (see feedback_cf_access_does_not_bypass_bot_fight_mode.md, incident 2026-05-12). Instead, the WAF skip rule is scoped more precisely: it skips Bot Fight Mode when the request has a valid Authorization: Bearer header on /api/internal/* paths (see §4 Layer 1 note).

CF Access posture for Queue: Queue has no human callers in Phase 1. All callers are machine services (Raptor, Console, Velvet) using Bearer tokens, or Stripe webhook delivery. CF Access is NOT applied to Queue in Phase 1. The gate for /api/internal/* is the existing InternalAuthFilter. When Phase 2 ships admin endpoints for Console operators to manage identity, a CF Access policy is added at that time (open question OQ-2).

4. Layered Defense — Queue in the 5-Layer Model

Queue fits into the WAF strategy's 5-layer model (ADR-0077) as follows:

LAYER 1 — CF Edge (WAF + Bot Fight Mode)
  Queue receives:
    ├── Cloudflare Free Managed Ruleset → Block
    ├── OWASP CRS → Log (Phase 3 soak), then Block
    ├── Auth endpoint rate limits (Phase 2 auth endpoints, not in Phase 1)
    │     POST /api/v1/auth/webauthn/login/begin    → 10 req/min/IP → Block
    │     POST /api/v1/auth/webauthn/register/begin → 5 req/min/IP → Block
    │     POST /api/v1/auth/backup-codes/redeem     → 5 req/min/IP → Block
    ├── Billing webhook rate limit (Phase 1)
    │     POST /api/v1/billing/webhook              → 60 req/min/IP → Block
    │     (Stripe webhook IPs are known; stricter than general traffic)
    ├── Bot Fight Mode → ON for all paths
    └── WAF skip rule for service-to-service on /api/internal/*:
          Expression: starts_with(http.request.uri.path, "/api/internal")
                      AND len(http.request.headers["authorization"]) gt 0
          Action: skip (bic, hot, rateLimit, securityLevel, uaBlock)
          Rationale: internal callers (Raptor, Console, Velvet) run on Heroku dynos
                     (AWS ASN) which trip Bot Fight Mode. Skip only on /api/internal
                     where Bearer token is required. The InternalAuthFilter (Layer 4)
                     validates the token before any handler runs.

LAYER 2 — CF Access
  Phase 1: NOT APPLIED. Queue has no human callers.
  Phase 2+: Apply CF Access policy on /admin/* paths when Console operators
            call Queue directly. See OQ-2.

LAYER 3 — Heroku Origin Guard (FLAG_ENFORCE_QUEUE_CF_ORIGIN)
  New: queue/src/middleware/cf_origin_guard.cpp (see §4.3)
  Allowlisted paths: /health (Heroku liveness probe)
  Reject path: CF-Connecting-IP absent → 403 {"error":"direct_origin_blocked"}
  Default: false (enabled post-soak in Phase 3)

LAYER 4 — Service Token Middleware (InternalAuthFilter, already shipped)
  /api/internal/* → Bearer token from env-loaded allowlist
  /api/v1/billing/webhook → Stripe HMAC-SHA256 signature verification (QP-C5)
  /api/v1/billing/* → service-to-service Bearer token

LAYER 5 — RBAC / Row-Level (Phase 2+)
  Not in Phase 1 billing scope.

4.1 WAF Rule Priority Order for Queue Surface

Cloudflare processes rules in priority order (lower number = higher priority):

4.2 Bot Fight Mode and Service-to-Service Traffic

Cloudflare Bot Fight Mode (BFM) evaluates BEFORE CF Access service tokens are inspected (incident documented in feedback_cf_access_does_not_bypass_bot_fight_mode.md, 2026-05-12). Heroku dynos egress from AWS ASNs (AS14618 / AS16509), which Cloudflare flags as bot-origin.

The WAF skip rule (Priority 1) covers only /api/internal/* paths — the exact paths guarded by InternalAuthFilter. This is tighter than zone-wide BFM disable. The pairing:

• WAF skip rule: only skips BFM when path starts with /api/internal AND Authorization header is present
• InternalAuthFilter: validates the token before any handler executes
• If token is invalid: handler returns 401 before any data is accessed

For billing CRUD and webhook endpoints (/api/v1/billing/*), Raptor and Console call these as authenticated callers. Stripe's webhook delivery IPs are AWS-based and will trigger BFM. The billing webhook path needs its own skip rule:

This header is present on all Stripe webhook deliveries. The HMAC verification in the webhook handler (QP-C5) validates the signature before processing.

4.3 C++ Origin Guard Middleware Spec

Feature-developer implements queue/src/middleware/cf_origin_guard.cpp with this interface:

// cf_origin_guard.h
#pragma once

#include <drogon/HttpFilter.h>
#include <string>
#include <unordered_set>

namespace queue {

/**
 * CfOriginGuard — Drogon HttpFilter.
 *
 * Rejects requests that did not transit Cloudflare when
 * FLAG_ENFORCE_QUEUE_CF_ORIGIN is set to "true" or "1".
 *
 * Proof: Cloudflare injects CF-Connecting-IP on every proxied request.
 * Direct-to-origin requests via raxx-queue-{prod,staging}.herokuapp.com
 * carry no CF-Connecting-IP header.
 *
 * Invariants:
 *   I-ALLOW: /health is always permitted (Heroku dyno liveness probe)
 *   I-FLAG:  FLAG_ENFORCE_QUEUE_CF_ORIGIN read at construction; restart
 *            required to change. Default = false (safe during rollout soak).
 *   I-LOG:   Blocked requests log path + remote_addr at WARN level with
 *            key "direct_origin_blocked". No PII from request body is logged.
 *   I-RAII:  No raw new/delete.
 *
 * Registration (in main.cpp):
 *   app().registerFilter("queue::CfOriginGuard");
 *   // Then attach to routes via ADD_METHOD_TO(..., "queue::CfOriginGuard")
 *   // OR register as global pre-filter via app().registerFilter() with
 *   // Drogon's global filter registration (Drogon v1.8+).
 */
class CfOriginGuard : public drogon::HttpFilter<CfOriginGuard> {
public:
    CfOriginGuard();

    void doFilter(const drogon::HttpRequestPtr& req,
                  drogon::FilterCallback&&      callback,
                  drogon::FilterChainCallback&& chainCallback) override;

private:
    bool enforcement_enabled_;

    // Paths that must remain reachable regardless of CF-Connecting-IP.
    // /health: Heroku platform liveness probe (not routed via CF).
    static const std::unordered_set<std::string> kAllowlistedPaths;

    static drogon::HttpResponsePtr make403();
};

} // namespace queue

Key implementation notes for feature-developer:

• Read FLAG_ENFORCE_QUEUE_CF_ORIGIN from std::getenv() in the constructor once; store as enforcement_enabled_. No re-read on each request.
• Allowlisted paths: /health only in Phase 1. Add /api/internal/* to the allowlist if Raptor-to-Queue calls traverse CF and false-positives occur during Phase 2 soak.
• Log format: spdlog::warn("direct_origin_blocked path={} remote={}", req->getPath(), req->getPeerAddr().toIpPort()).
• The 403 response body: {"error":"direct_origin_blocked"} (matches Raptor's Python implementation).
• Apply this filter globally (all routes) via Drogon's app().registerFilter() in main.cpp. It must run before InternalAuthFilter so that direct-origin requests are rejected before token validation.

5. Concrete Terraform Design

Module layout

terraform/queue/
├── versions.tf         # Cloudflare provider ~> 4.0, S3 backend
├── variables.tf        # cloudflare_zone_id, heroku_* vars
├── dns.tf              # cloudflare_record for queue.raxx.app + queue-staging.raxx.app
├── waf.tf              # cloudflare_ruleset for rate limits + WAF rules + skip rules
├── outputs.tf          # record IDs, zone info
├── terraform.tfvars.example
└── README.md

dns.tf sketch

# ---------------------------------------------------------------------------
# Cloudflare DNS — Queue identity service
# ---------------------------------------------------------------------------
# Heroku custom domain must be attached BEFORE DNS is proxied.
# Operator action: see README.md §Operator Bootstrap.
#
# queue.raxx.app → raxx-queue-prod.herokuapp.com (proxied)
# queue-staging.raxx.app → raxx-queue-staging.herokuapp.com (proxied)

resource "cloudflare_record" "queue_prod" {
  zone_id = var.cloudflare_zone_id
  name    = "queue"
  type    = "CNAME"
  value   = "raxx-queue-prod.herokuapp.com"
  proxied = true

  comment = "Queue identity service prod — managed by Terraform"
}

resource "cloudflare_record" "queue_staging" {
  zone_id = var.cloudflare_zone_id
  name    = "queue-staging"
  type    = "CNAME"
  value   = "raxx-queue-staging.herokuapp.com"
  proxied = true

  comment = "Queue identity service staging — managed by Terraform"
}

waf.tf sketch (CF ruleset)

# ---------------------------------------------------------------------------
# CF WAF ruleset for queue.raxx.app + queue-staging.raxx.app
# ---------------------------------------------------------------------------
# Phase 1 rules (billing surface only).
# Phase 2 auth rules activate when WebAuthn endpoints ship (auth endpoints
# are gated behind FLAG_QUEUE_AUTH which is off in Phase 1).

resource "cloudflare_ruleset" "queue_prod_waf" {
  zone_id = var.cloudflare_zone_id
  name    = "Queue prod WAF rules"
  kind    = "zone"
  phase   = "http_request_firewall_custom"

  # Priority 1: Skip Bot Fight Mode for service-to-service /api/internal/*
  # Bearer header presence is a pre-filter; InternalAuthFilter does the real
  # validation. Without this skip, Heroku-egress IPs (AWS ASN) trigger BFM.
  rule {
    action      = "skip"
    expression  = <<-EOT
      (http.host eq "queue.raxx.app" AND
       starts_with(http.request.uri.path, "/api/internal") AND
       len(http.request.headers["authorization"]) gt 0)
    EOT
    description = "Skip Bot Fight Mode for service-to-service calls to /api/internal/*"
    action_parameters {
      phases   = ["http_ratelimit", "http_request_firewall_managed"]
      products = ["bic", "hot", "uaBlock"]
    }
    enabled = true
  }

  # Priority 1b: Skip Bot Fight Mode for Stripe webhook delivery
  rule {
    action      = "skip"
    expression  = <<-EOT
      (http.host eq "queue.raxx.app" AND
       http.request.uri.path eq "/api/v1/billing/webhook" AND
       len(http.request.headers["stripe-signature"]) gt 0)
    EOT
    description = "Skip Bot Fight Mode for Stripe webhook delivery"
    action_parameters {
      phases   = ["http_ratelimit", "http_request_firewall_managed"]
      products = ["bic", "hot", "uaBlock"]
    }
    enabled = true
  }

  # Priority 3: Rate limit billing webhook
  rule {
    action     = "block"
    expression = <<-EOT
      (http.host eq "queue.raxx.app" AND
       http.request.uri.path eq "/api/v1/billing/webhook" AND
       http.request.method eq "POST")
    EOT
    description = "Rate limit Stripe webhook endpoint"
    ratelimit {
      characteristics      = ["ip.src"]
      period               = 60
      requests_per_period  = 60
      mitigation_timeout   = 60
    }
    enabled = true
  }

  # Priority 6: Global rate limit
  rule {
    action     = "managed_challenge"
    expression = "(http.host eq \"queue.raxx.app\")"
    description = "Global rate limit — Queue all paths"
    ratelimit {
      characteristics      = ["ip.src"]
      period               = 60
      requests_per_period  = 300
      mitigation_timeout   = 60
    }
    enabled = true
  }
}

# Staging ruleset mirrors prod (replace host expression with queue-staging.raxx.app).
# Feature-developer may use a module or locals to DRY the two rulesets.

Heroku custom domain attachment

Terraform cannot manage Heroku custom domains (no official Heroku TF provider in the CF TF stack). This is an operator-side CLI action (Phase 0):

# Attach custom domain — prod
heroku domains:add queue.raxx.app --app raxx-queue-prod >/dev/null
heroku domains:wait --app raxx-queue-prod

# Attach custom domain — staging
heroku domains:add queue-staging.raxx.app --app raxx-queue-staging >/dev/null
heroku domains:wait --app raxx-queue-staging

Heroku generates an ACM cert automatically after domain attachment. The Heroku DNS target returned by heroku domains --app raxx-queue-prod is in the format <hash>.herokudns.com. The Terraform CNAME value must use raxx-queue-prod.herokuapp.com (the canonical Heroku origin URL), NOT the herokudns.com target. Cloudflare resolves the CNAME and proxies it correctly.

6. Failure Modes

7. Migrations

No database schema changes in this design. The origin guard is pure middleware.

The only state changes are: - Cloudflare DNS record creation (Terraform apply, reversible with destroy) - Heroku custom domain attachment (CLI, reversible with heroku domains:remove) - Feature flag flip (env var, reversible with heroku config:unset)

Rollback for each phase:

8. Rollout Plan

Phase 0 — Operator actions (no enforcement, no risk)

Target: 2026-05-11 UTC (immediate)

1. Attach custom domain to Heroku apps: bash heroku domains:add queue.raxx.app --app raxx-queue-prod >/dev/null heroku domains:wait --app raxx-queue-prod heroku domains:add queue-staging.raxx.app --app raxx-queue-staging >/dev/null heroku domains:wait --app raxx-queue-staging
2. Note the ACM DNS targets returned by heroku domains --app raxx-queue-prod for verification.
3. Verify heroku certs:auto --app raxx-queue-prod shows ACM cert provisioning in progress.

No traffic change. The Heroku origin URL remains directly reachable. This just prepares the custom domain cert.

Phase 1 — CF proxied DNS live (no enforcement)

Precondition: Phase 0 complete, Heroku ACM cert provisioned.

1. terraform apply in terraform/queue/ — creates CNAME records, proxied=true.
2. Verify: curl -i https://queue.raxx.app/health returns 200 (CF-proxied).
3. Verify: curl -i https://queue.raxx.app/health | grep CF-RAY — presence of CF-RAY header confirms CF is in the path.
4. FLAG_ENFORCE_QUEUE_CF_ORIGIN remains false (default). No traffic impact.
5. Soak 48 hours. Monitor heroku logs --tail --app raxx-queue-prod for unexpected traffic patterns.
6. Update surface matrix in docs/security/web-surface-posture.md to reflect Queue now proxied.

Phase 2 — Caller migration audit

Precondition: Phase 1 soak clean.

Feature-developer runs SC-Q-CF-4: audit all callers for hard-coded raxx-queue-*.herokuapp.com URLs. Callers:

All callers should be calling queue.raxx.app (or queue-staging.raxx.app) before Phase 3.

Phase 3 — Origin guard ON (staging)

Precondition: Phase 2 migration complete on staging.

1. Feature-developer ships cf_origin_guard.cpp (SC-Q-CF-3).
2. heroku config:set FLAG_ENFORCE_QUEUE_CF_ORIGIN=true --app raxx-queue-staging >/dev/null && heroku restart --app raxx-queue-staging
3. Verify: curl -i https://raxx-queue-staging.herokuapp.com/health → 403 direct_origin_blocked.
4. Verify: curl -i https://queue-staging.raxx.app/health → 200 (CF-proxied, allowlisted path).
5. Run full integration test suite against queue-staging.raxx.app (not the Heroku URL).
6. Soak 48 hours. Watch Sentry for unexpected 403s.

Phase 4 — Origin guard ON (prod)

Precondition: Phase 3 soak clean, Phase 2 migration complete on prod.

1. heroku config:set FLAG_ENFORCE_QUEUE_CF_ORIGIN=true --app raxx-queue-prod >/dev/null && heroku restart --app raxx-queue-prod
2. Verify: curl -i https://raxx-queue-prod.herokuapp.com/health → 403.
3. Verify: curl -i https://queue.raxx.app/health → 200.
4. Update docs/security/web-surface-posture.md surface matrix row for Queue.
5. Close #1733.

Total elapsed time from Phase 0 start to Phase 4 completion: minimum 96 hours (two 48h soaks). Realistically 5–7 days including caller migration.

9. Security Considerations

10. Open Questions (require operator decisions)

OQ-1 — Subdomain: queue.raxx.app or api-queue.raxx.app?

queue.raxx.app is clean and matches the service codename. api-queue.raxx.app is more descriptive but breaks the short-subdomain pattern (console.raxx.app, api.raxx.app). Recommended: queue.raxx.app. Feature-developer cannot proceed with Phase 0 until this is confirmed.

OQ-2 — CF Access on Queue's admin endpoints (Phase 2+)?

When Phase 2 ships WebAuthn admin endpoints or Console-operator-to-Queue admin paths (e.g., GET /api/admin/customers, POST /api/admin/rbac/grant), should these be gated by CF Access? Recommended: yes — apply CF Access with the operator allowlist policy, matching the pattern for console.raxx.app. This blocks anyone who discovers the queue.raxx.app URL from probing admin endpoints even if they have a stolen service token. Operator decision needed before Phase 2 sub-cards are groomed.

OQ-3 — Heroku custom domain SSL: automatic (ACM) or BYO cert?

Heroku's Automated Certificate Management (ACM) provisions a free cert automatically on custom domain attachment. This is sufficient. BYO cert adds operational burden. Recommended: ACM. No action needed unless operator has a specific cert requirement.

OQ-4 — Bot Fight Mode policy for Queue auth endpoints: on or super?

super (Cloudflare Super Bot Fight Mode) provides fingerprint-based detection in addition to ASN-based detection. More effective against sophisticated bots but can generate more false-positives. Recommended for Phase 2 auth endpoints: start with on during soak, evaluate false-positive rate on WebAuthn flows, then consider super. Operator decides the final posture.

OQ-5 — WAF log ingestion pipeline?

Cloudflare WAF logs are available via Logpush (Enterprise) or in the dashboard (all plans). For systematic threat monitoring, WAF logs should flow to the same sink as Sentry. This is noted in ADR-0077 D2 (shared open question). Not blocking for Phase 0–4; needed before Queue is customer-facing (Phase 2+).

11. Sequence Diagram

sequenceDiagram
    participant Caller as Caller<br/>(Raptor/Console/Velvet)
    participant CF as Cloudflare Edge<br/>(WAF + BFM)
    participant Origin as Queue Origin<br/>(Heroku dyno)
    participant Guard as CfOriginGuard<br/>(Layer 3)
    participant Auth as InternalAuthFilter<br/>(Layer 4)
    participant Handler as Route Handler

    Caller->>CF: POST queue.raxx.app/api/internal/billing/mirror-sync\n  Authorization: Bearer <token>
    CF->>CF: Priority 1 skip rule matches\n(path starts /api/internal, Authorization present)\nBFM skipped
    CF->>CF: WAF managed rules evaluated\nRate limits evaluated
    CF->>Origin: Forward request\n  CF-Connecting-IP: <client IP>\n  Authorization: Bearer <token>
    Origin->>Guard: doFilter()
    Note over Guard: enforcement_enabled_=true (Phase 4)\nCF-Connecting-IP present → pass
    Guard->>Auth: chainCallback()
    Note over Auth: extract Bearer token\nlookup in token_map_\ncaller=raptor → pass
    Auth->>Handler: chainCallback()
    Handler-->>Caller: 200 OK

    Note over Caller,Handler: --- Direct origin bypass attempt (Phase 4) ---

    Caller->>Origin: POST raxx-queue-prod.herokuapp.com/api/internal/billing/mirror-sync
    Note over CF: Traffic never transits CF\n(direct Heroku URL)
    Origin->>Guard: doFilter()
    Note over Guard: CF-Connecting-IP absent\npath not allowlisted\nenforcement_enabled_=true
    Guard-->>Caller: 403 {"error":"direct_origin_blocked"}

References

• ADR-0078: docs/architecture/adr/0078-queue-cf-edge-protection.md
• ADR-0076: docs/architecture/adr/0076-queue-phase1-cpp-billing-v1.md
• ADR-0077: WAF strategy (just-merged, sister doc)
• docs/security/waf-threat-model-2026-05-11.md §S11, HIGH-WAF-2
• docs/security/web-surface-posture.md — surface inventory
• docs/security/auth-posture.md — surface class framework
• backend_v2/api/middleware/cloudflare_origin_guard.py — Python analog
• queue/src/middleware/internal_auth_filter.cpp — existing C++ middleware pattern
• terraform/freescout/dns.tf — CF proxied DNS pattern reference
• terraform/cf-access/main.tf — CF Access pattern reference
• feedback_cf_access_does_not_bypass_bot_fight_mode.md — BFM/service-token incident
• Issue #1733 — parent card