v0.31.0

docs/CACHE.md

@@ -13,7 +13,7 @@ different vhost/config scopes internally and uses response `Vary` to select repr
 variants.
 
 This is not a VCL implementation. Generic Varnish grace, ESI, public unauthenticated
-BAN/PURGE and distributed cache state are not implemented. RustProxy 0.22.1 adds bounded
+unrestricted public BAN/PURGE and distributed cache state are not implemented. RustProxy 0.22.1 adds bounded
 foreground request collapsing, authenticated selective PURGE/BAN and optional proactive
 refresh while keeping directive-controlled stale delivery through RFC 5861 and request
 `max-stale`; it is not an unconditional availability/grace layer. RustProxy also keeps its
@@ -36,6 +36,48 @@ proxy origins, range requests and conditional requests can reuse fresh stored
 representations. Do not rely on stale-if-error remote-backend refresh behavior
 for local Web Server routes.
 
+## HTTP BAN / PURGE from authorized client IPs
+
+The **Settings → Cache → HTTP BAN / PURGE IP allowlist** control sets
+`cache.http_invalidation_allowed_cidrs`. The default is **empty (disabled)**.
+Allow individual client IPs or small CIDR ranges, one per line. Saves validate
+IPv4/IPv6 CIDR syntax and reject `/0` networks. An allowed request must also
+pass the vhost listener binding, global/vhost ACL, and rate limits. The
+operation is restricted to the matched external HTTP/HTTPS scheme, `Host` and
+vhost; it cannot choose other tenants or the opposite scheme through headers. Commands use the existing
+cache invalidation engine, are audit-logged before execution and share a
+two-worker maintenance limit with authenticated admin invalidation (429 when
+busy). They are never forwarded upstream.
+
+- `PURGE /path?query` immediately invalidates exact cached representations of
+  that URL. Returns `200` with JSON result/count. Other query variants are not
+  matched.
+- `BAN /prefix` records a lazy prefix ban of older cached representations
+  for that host/vhost. Returns `202` and ban ID, normally expires after one hour.
+  Optional `X-RustProxy-Ban-Ttl: 30` sets 1..604800 seconds. Newly filled
+  representations are allowed (Varnish-like lazy BAN).
+- `BAN /` requires `X-RustProxy-Confirm-Wide: 1` to prevent accidental
+  whole-host invalidation. Request bodies, upgrades, arbitrary selectors and
+  wildcard cross-vhost operations are rejected.
+
+Examples from an allowlisted machine (replace the domain and path):
+
+```sh
+curl -i -X PURGE 'https://site.example/assets/app.js?v=3'
+curl -i -X BAN 'https://site.example/assets/'
+curl -i -X BAN 'https://site.example/' -H 'X-RustProxy-Confirm-Wide: 1'
+```
+
+**Behind a reverse proxy:** forward nonstandard `BAN`/`PURGE` methods to the
+RustProxy public listener; do not let an upstream cache intercept them. Configure
+RustProxy's existing `forwarding.trusted_proxies` accurately and ensure the
+edge sanitizes/replaces untrusted `Forwarded`/`X-Forwarded-For` headers. When a
+trusted proxy does not provide a usable real-client chain, BAN/PURGE fails
+closed. Do **not** allowlist an entire proxy NAT network unless all its users
+should have destructive cache access. Unlike full Varnish VCL, this interface
+intentionally provides only exact PURGE and bounded URL-prefix BAN, not an
+arbitrary untrusted regex/VCL expression.
+
 ## Settings
 
 | Field | Default | Bounds / meaning |
@@ -66,6 +108,7 @@ for local Web Server routes.
 | max_ttl_seconds | 86400 | 1..604800; maximum configured retention/freshness cap |
 | bypass_query | false | Bypass requests containing a query when enabled |
 | bypass_prefixes | [] | Up to 64 normalized absolute path prefixes |
+| http_invalidation_allowed_cidrs | [] | Opt-in IP/CIDR allowlist (max 32) for HTTP BAN/PURGE. Empty blocks all HTTP methods; `/0` is invalid. |
 | static_ignore_cookies | true | For configured static extensions only, ignore request Cookie for eligibility/keying |
 | expose_status | false | Emit `X-Cache: HIT`, `MISS` or `BYPASS` |
 | expose_hits | false | Emit per-object `X-Cache-Hits` |
@@ -175,9 +218,13 @@ Cache invalidation remains explicit:
 - regex rules and prefix `/` are treated as broad operations and require explicit confirmation,
 - only cache-compatibility changes advance the normal cache generation/revision; unrelated logging/TLS/admin/metrics/response-presentation saves retain objects, and cache request-bypass edits plus response-only `X-Cache`/`Cache-Status`/resident-age/`Via` diagnostics also apply without purging stored objects.
 
-There is no public unauthenticated PURGE/BAN endpoint. If an application changes a GET
-resource after POST/PUT/PATCH/DELETE, use origin freshness/validators or the authenticated
-administration invalidation path; RustProxy does not guess the affected URLs.
+Unrestricted anonymous cache-maintenance access is not exposed: the public
+HTTP BAN/PURGE interface is explicitly IP/CIDR-authorized (empty by default),
+separate from the administrator-only selective invalidation API. If an
+application changes a GET resource after POST/PUT/PATCH/DELETE, use origin
+freshness/validators or one of the explicit invalidation paths; RustProxy
+does not guess the affected URLs. For exposure review and test scenarios, see
+[0.31.0 security audit](SECURITY_AUDIT_0.31.0.md).
 
 ## Eligibility and freshness