@openwop/openwop-conformance 1.138.1 → 1.140.0

package/src/scenarios/webhook-signed-delivery.test.ts

@@ -16,13 +16,59 @@
  * Capability-gated: skips when the host does not advertise
  * `capabilities.webhooks.supported = true`.
  *
- * Operator contract: hosts that implement a SSRF guard on
- * `POST /v1/webhooks` (rejecting loopback / RFC1918 / link-local
- * destinations to protect deployer infrastructure) MUST allow the test
- * receiver. The SQLite reference host bypasses the guard when the
- * `OPENWOP_WEBHOOK_ALLOW_PRIVATE=true` env var is set at boot. Test-only
- * hosts SHOULD provide an equivalent opt-in. When the host rejects with
- * `400 webhook_url_rejected`, this scenario skips with a warning.
+ * Operator contract — THREE gates, not one (clarified 2026-08-25).
+ *
+ * The test receiver is `http://127.0.0.1:{port}/`, and `webhooks.md`
+ * forbids it three separate times. A host honoring
+ * `OPENWOP_WEBHOOK_ALLOW_PRIVATE=true` (or an equivalent opt-in) MUST
+ * relax ALL THREE for this scenario to be witnessable:
+ *
+ *   1. **Scheme.** §"SSRF protection" bullet 1 rejects non-`https://`
+ *      protocols, and §"Register" says `url` MUST be `https://`. The
+ *      receiver is plain `http`. This gate is the one the flag's
+ *      description omitted until 2026-08-25, and it fires FIRST on a
+ *      host that validates scheme before address.
+ *   2. **Registration-time address check.** §"SSRF protection": the
+ *      server MUST validate subscription URLs at registration time and
+ *      reject loopback / RFC1918 / link-local / ULA / metadata.
+ *   3. **Delivery-time re-resolution.** §"Delivery-time egress
+ *      validation (RFC 0093)": the dispatcher MUST re-resolve at
+ *      delivery time and validate every resolved address against the
+ *      same ranges.
+ *
+ * Gates 2 and 3 are INDEPENDENT MUSTs at different layers, so "which
+ * layer must the opt-in reach" is not a matter of taste: a relaxation
+ * reaching only one layer cannot produce a witness. Delivery-only leaves
+ * registration returning `400 webhook_url_rejected` (observed on a tier-2
+ * host, 2026-08-25); registration-only leaves the dispatcher re-resolving
+ * `127.0.0.1` and refusing to connect. A host whose opt-in reaches one
+ * layer is not non-conformant — it simply cannot witness this scenario,
+ * and that is a property of the test posture, not of its webhook signing.
+ *
+ * What that costs is more than a checkmark, and it is worth stating plainly
+ * because the cost is invisible from inside such a host. This scenario is
+ * typically the ONLY automated oracle a host has on its delivery header
+ * NAMES: a host-local delivery test almost always compares a hand-written
+ * literal in the test to a hand-written literal in the implementation, which
+ * is a mirror — typo both and it stays green — while the HMAC assertion
+ * beside it recomputes from `node:crypto` and is real. So the names go
+ * unchecked exactly where the bytes are checked well. All three reference
+ * hosts emitted invented header names for 16 days (openwop-examples#22) and
+ * the runs that would have caught it were the ones this scenario could not
+ * reach. A host that runs it is not thereby careful; it is thereby measured.
+ *
+ * Relaxing gates 2 and 3 is test-only posture. See
+ * `SECURITY/threat-model-secret-leakage.md` §4.9 for why a
+ * registration-time relaxation is the more dangerous of the two: it
+ * writes a durable subscription row that survives the flag being turned
+ * back off.
+ *
+ * When the host rejects with `400 webhook_url_rejected`, this scenario
+ * records `blocked` (RFC 0148 §A) — NOT a pass. Under a plain
+ * `vitest run` the console still prints "1 passed", because that is
+ * vitest reporting test outcomes rather than conformance dispositions;
+ * the run-end disposition summary (`src/global-setup.ts`) is where the
+ * `blocked` becomes visible without `--certify`.
  *
  * @see spec/v1/webhooks.md §"Signature scheme"
  */

package/src/setup.ts

@@ -278,7 +278,7 @@ afterAll(({}, suite) => {
   // the marker detail — never to a pass. Floors still REJECT that row, so the
   // honest bundle row and the pressure to say why both survive. The rule is
   // `resolveFileRecord` (pinned by conformance-execution-witness.test.ts).
-  const { disposition, detail } = resolveFileRecord(states, gateReason, assertionCount, softSkipDisposition(file));
+  const { disposition, detail } = resolveFileRecord(states, gateReason, assertionCount, softSkipDisposition(file), file);
   const fileRequirementId = requirementIdForFile(file);
   // A scenario that classified ITSELF wins outright — including its `detail` and
   // its `assertionCount`.

package/vitest.config.ts

@@ -17,5 +17,12 @@ export default defineConfig({
     // populates `lib/fixtures.ts` so `describe.skipIf(...)` predicates
     // see the cached set when scenarios register their tests.
     setupFiles: ['src/setup.ts'],
+    // RFC 0148 §A run-end disposition summary. `setup.ts` records an honest
+    // disposition per scenario file on EVERY run; before this, only
+    // `--certify` set OPENWOP_LEDGER_PATH, so on a plain `vitest run` the
+    // recording was computed and then discarded, leaving "N passed" as the
+    // sole artifact for rows the suite had classified `blocked`. This routes
+    // the ledger to a temp file and prints what did not witness.
+    globalSetup: ['src/global-setup.ts'],
   },
 });