Report blocked attacks, with rule-scoped evidence

RELEASING.md

@@ -68,6 +68,25 @@ You can also publish an existing tag directly:
 gh workflow run publish.yml -f version=0.3.3
 ```
 
+## Before publishing detection reporting
+
+Detection reporting depends on two server-side behaviours. Check both before cutting a
+release that includes it, because a published version cannot be withdrawn from anyone
+who has already installed it:
+
+- **The detections endpoint deduplicates on `Idempotency-Key`.** Connect sends a stable
+  key for every attempt at a batch and a fresh one per batch, so a redelivery is
+  identifiable — but whether it is counted once is the endpoint's to decide. Published
+  ahead of that, a retry after a lost acknowledgement inflates the counts these reports
+  are read for.
+- **Ingest accepts and stores the current payload:** the `capture` object, the baseline
+  fields `method`, `user_agent`, `query_keys` and `query_keys_total`, and
+  `reporting_state` on the detections body. An endpoint that rejects or silently drops
+  them turns every report into a delivery failure, or into a record missing the evidence
+  it was sent to carry.
+
+Delete this section once both have shipped.
+
 ## Notes
 
 - Tags must be `vX.Y.Z` (the leading `v` is stripped to get the npm version).

rule-contract.json

@@ -1,6 +1,6 @@
 {
   "$comment": "Generated from src/protect/rules/contract.js by scripts/emit-rule-contract.mjs. Do not edit.",
-  "version": "2.7",
+  "version": "2.8",
   "sources": {
     "raw": {
       "keyed": false
@@ -359,6 +359,9 @@
     "method"
   ],
   "null_valued_properties": "refused",
+  "null_exempt_properties": [
+    "capture"
+  ],
   "rule_property_shapes": {
     "max_bytes": "positive-number",
     "bypass_limit": "boolean",
@@ -386,8 +389,31 @@
     "set_headers",
     "remove_headers",
     "cookie_flags",
-    "ensure"
+    "ensure",
+    "capture"
   ],
+  "capture": {
+    "version": 1,
+    "required": [
+      "version",
+      "raw_chars"
+    ],
+    "additional_properties": false,
+    "properties": {
+      "version": {
+        "type": "integer",
+        "const": 1
+      },
+      "raw_chars": {
+        "type": "integer",
+        "minimum": 1
+      }
+    },
+    "raw_chars_effective_maximum": 512,
+    "unknown_version": "grants no capture; the rule still applies",
+    "unreadable": "grants no capture; the rule still applies",
+    "raw_chars_note": "a request for a bounded PREFIX of the body; more than the effective maximum yields the maximum"
+  },
   "limits": {
     "maxRules": 5000,
     "maxWhitelists": 2000,