Fix webhook payload encoding failure

Add a fail-closed guard in WebhookChannel when alert payloads cannot be
serialized as JSON. Non-serializable payloads are no longer signed, sent,
or reported as delivered.

Add regression coverage for invalid UTF-8 and non-finite float payloads.
Extract the canonical Webhook Channel spec and archive the pilot artifacts.

Author: mab056

changes/archive/2026-06-21-webhook-json-encode-guard/analyze.md

@@ -0,0 +1,31 @@
+# Analyze — webhook-json-encode-guard
+
+> Artefatto storico archiviato. L'`analyze` verifica la **coerenza documentale** del change:
+> che codice, test, spec e regole di progetto non si contraddicano. Non è validazione del
+> comportamento reale — quella proviene dal RED eseguito (vedi `runtime-red-probe.md`).
+
+## Coerenza con le regole di progetto (CLAUDE.md)
+
+- **No singleton / static / final:** il change non introduce metodi/proprietà static né classi/metodi final. `WebhookChannel` resta non-final, `send()` resta metodo d'istanza. ✅
+- **Sicurezza — escape/sanitize:** il guard non introduce input/output utente nuovo; il messaggio d'errore è una stringa fissa localizzata via `__()`. ✅
+- **Anti-SSRF:** l'outbound HTTP resta interamente su `HttpClientInterface::post()`; il guard anzi *previene* una chiamata su corpo malformato. Nessuna chiamata HTTP diretta introdotta. ✅
+- **WPCS:** indentazione tab, Allman, PHPDoc invariata; `composer phpcs` 0 errori. ✅
+- **TDD:** test scritti prima (RED osservato), poi fix (GREEN). ✅
+
+## Coerenza tra artefatti
+
+- `current-state.md` (bug) ↔ `change-delta.md` (delta) ↔ `specs/channels/webhook.md` (stato): la sezione "Codifica del payload → Fail-closed" della spec descrive esattamente l'esito del guard implementato.
+- `DR-WEBHOOK-001` (active) registra la scelta fail-closed e indica cosa aggiornare se in futuro si scegliesse la normalizzazione: spec, sezione Codifica, Contratto di ritorno, test. Coerente con il codice.
+- Il "Contratto di ritorno" della spec (`success`/`error`) corrisponde alla shape ritornata da `send()` nel ramo guard e nei rami esistenti.
+- La sezione "Verifica richiesta" della spec elenca rischi coperti dai test presenti (happy path, firma, fail-closed non inviato, errore trasporto propagato).
+
+## Punti di attenzione documentale
+
+- `package-lock.json` riporta un bump `version 0.5.0 → 0.6.2` causato da `npm install` (sincronizzazione da `package.json`), **estraneo** a questo change. Va escluso. È un sintomo del finding di review sul disallineamento di versione, da trattare separatamente.
+- La spec dichiara la **delega** al client HTTP per anti-SSRF/timeout/limiti, senza certificarne il livello: coerente con il principio "la spec del canale documenta la delega, non certifica un altro layer".
+
+## Limite dell'analyze
+
+Questa analisi è documentale. La prova che il comportamento reale sia quello descritto viene
+**solo** dal RED eseguito e dal GREEN eseguito sul codice reale, non dalla coerenza tra documenti
+né dal consenso tra reviewer.

changes/archive/2026-06-21-webhook-json-encode-guard/change-delta.md

@@ -0,0 +1,51 @@
+# Change delta — webhook-json-encode-guard
+
+> Artefatto storico archiviato (linguaggio di cambiamento). Il delta documenta la transizione
+> dallo stato precedente a quello corrente; **non è fonte attiva**.
+> La fonte attiva del comportamento è [specs/channels/webhook.md](../../../specs/channels/webhook.md).
+
+## Obiettivo del change
+
+Rendere `WebhookChannel::send()` fail-closed quando il payload non è serializzabile in JSON,
+in modo che un payload malformato non venga firmato, inviato e riportato come consegnato.
+
+## Delta di comportamento
+
+| Aspetto | Prima | Dopo |
+| --- | --- | --- |
+| `json_encode()` ritorna `false` | firma su stringa vuota, POST del corpo spurio `"false"`, esito `success=true` su 2xx | nessuna firma, nessuna POST, esito `success=false` con `error` non vuoto |
+| Payload valido (happy path) | invariato | invariato |
+| Firma HMAC per payload valido | invariata | invariata |
+
+## Delta di codice (produzione)
+
+`src/Channels/WebhookChannel.php` — guard aggiunto subito dopo `json_encode()` e **prima** di
+`hash_hmac()` e `http_client->post()`:
+
+    $raw_body = json_encode( $payload );
+
+    if ( false === $raw_body ) {
+        return [
+            'success' => false,
+            'error'   => __( 'Failed to encode webhook payload.', 'ops-health-dashboard' ),
+        ];
+    }
+
+## Delta di test
+
+`tests/Unit/Channels/WebhookChannelTest.php`:
+
+- helper `create_http_client_spy( &$called )` — mock `post()` con `andReturnUsing` che registra l'invocazione e ritorna successo (così `send()` ritorna sempre normalmente);
+- `test_send_returns_failure_when_payload_contains_invalid_utf8` — payload `[ 'x' => "\xB1\x31" ]`;
+- `test_send_returns_failure_when_payload_contains_non_finite_float` — payload `[ 'value' => NAN ]`.
+
+## Decisione di prodotto
+
+Fail-closed (non normalizzazione/coercizione). Registrata come `DR-WEBHOOK-001` (active) nella
+spec canonica.
+
+## Confini espliciti (non toccati)
+
+`HttpClient`, altri canali, `AlertManager`, storage/settings/admin, anti-SSRF/redaction,
+metadati composer/package. Nessun refactor. Nessun uso di `wp_json_encode()`, `@json_encode()`,
+`set_error_handler()`.

changes/archive/2026-06-21-webhook-json-encode-guard/closeout.md

@@ -0,0 +1,62 @@
+# Closeout — webhook-json-encode-guard
+
+> Artefatto storico archiviato. Evidenze red/green e stato di chiusura del change.
+
+## RED evidence
+
+Comando (PRIMA del fix): `vendor/bin/phpunit --testsuite=unit --filter WebhookChannelTest`
+
+    Tests: 17, Failures: 2.   (gli altri 15 verdi)
+
+    1) test_send_returns_failure_when_payload_contains_invalid_utf8
+       "post() must NOT be called when the payload cannot be encoded"
+       Failed asserting that true is false.   (WebhookChannelTest.php:556)
+    2) test_send_returns_failure_when_payload_contains_non_finite_float
+       "post() must NOT be called when the payload cannot be encoded"
+       Failed asserting that true is false.   (WebhookChannelTest.php:591)
+
+Motivo del fallimento: **corretto**. `json_encode()` ritorna `false` silenziosamente (nessun
+Warning/ErrorException), `send()` prosegue e chiama `post()` → lo spy imposta `$called=true`.
+RED per "post() was called", coerente con la Runtime RED Probe.
+
+## GREEN evidence
+
+- `composer test:unit -- --filter WebhookChannelTest` → OK (17 tests, 28 assertions)
+- `composer phpcs` → 35/35, 0 errori
+- `composer analyse` (PHPStan level 6) → [OK] No errors
+- Suite unit completa → OK (639 tests, 1508 assertions); 1 risky **pre-esistente**
+  (`CheckRunnerTest::test_clear_results_deletes_from_storage`, file non toccato — vedi
+  `pilot-retrospective.md › Follow-up debt`).
+
+## Changed files
+
+- `src/Channels/WebhookChannel.php` (+9) — guard fail-closed in `send()`.
+- `tests/Unit/Channels/WebhookChannelTest.php` (+98) — 2 test + helper `create_http_client_spy()`.
+- `specs/channels/webhook.md` (new) — spec canonica (fonte attiva).
+- `changes/archive/2026-06-21-webhook-json-encode-guard/` (new) — artefatti storici.
+
+## Scope deviations
+
+none. Non modificati: `HttpClient`, altri canali, `AlertManager`, storage/settings/admin,
+anti-SSRF/redaction, metadati composer/package. Assenti nel diff: `wp_json_encode()`,
+`@json_encode()`, `set_error_handler()`.
+
+## Excluded / unrelated
+
+- `package-lock.json` — bump `0.5.0 → 0.6.2` da `npm install`, estraneo al change. **Escluso**
+  dal commit (lasciato `M` nel working tree per decisione del maintainer).
+
+## Versioning decision (maintainer)
+
+Da versionare nel commit del change (branch dedicato):
+
+- `src/Channels/WebhookChannel.php`, `tests/Unit/Channels/WebhookChannelTest.php` (codice + test);
+- `specs/channels/webhook.md` (spec canonica);
+- `changes/archive/2026-06-21-webhook-json-encode-guard/**` (artefatti d'archivio);
+- `CODE_REVIEW_v0.6.2.md`, `PILOT_CANDIDATE_REPORT.md` (report del programma pilota).
+
+Escluso dal commit: `package-lock.json` (lasciato com'è).
+
+## Closeout readiness
+
+READY → ARCHIVED. Commit in attesa di via libera esplicito del maintainer (no commit/tag finora).

changes/archive/2026-06-21-webhook-json-encode-guard/current-state.md

@@ -0,0 +1,44 @@
+# Current state (pre-change) — webhook-json-encode-guard
+
+> Artefatto storico archiviato. Cattura lo stato del canale Webhook **prima** del change.
+> La fonte attiva del comportamento corrente è [specs/channels/webhook.md](../../../specs/channels/webhook.md).
+
+## Componente
+
+`OpsHealthDashboard\Channels\WebhookChannel` — canale di alert che invia una HTTP POST JSON
+con firma HMAC opzionale, tramite `HttpClientInterface::post()`.
+
+## Comportamento osservato prima del change
+
+In `WebhookChannel::send()` il payload veniva serializzato con `json_encode( $payload )`
+senza verificare il valore di ritorno. In caso di fallimento della serializzazione:
+
+- `json_encode()` ritorna `false` (silenziosamente, senza emettere PHP Warning);
+- `hash_hmac( 'sha256', false, $secret )` calcolava la firma sulla stringa vuota;
+- `HttpClient::post( $url, false, ... )` riceveva `false` e lo ri-serializzava nella stringa
+  letterale `"false"`, inviata come corpo;
+- su risposta HTTP 2xx, `send()` restituiva `success = true`.
+
+Effetto netto: un payload non rappresentabile in JSON veniva trasmesso come corpo spurio,
+con una firma che non corrispondeva al corpo, e l'esito veniva riportato come consegnato.
+La perdita dell'alert era completamente silenziosa.
+
+## Causa scatenante realistica
+
+Il payload include `message` e `details` provenienti dall'output dei check. `ErrorLogCheck`
+legge righe di log via `fread()`; byte UTF-8 non validi (path latin-1, frammenti binari di
+stack trace) sopravvivono alla redazione (solo regex, nessuna normalizzazione UTF-8) e
+raggiungono il payload. `json_encode()` ritorna `false` (JSON_ERROR_UTF8) su UTF-8 non valido,
+e analogamente su valori float non finiti (`NAN`/`INF`).
+
+## Origine
+
+Code review v0.6.2 — finding correctness (medium) su `WebhookChannel.php:104-112`.
+Selezione come pilota in [PILOT_CANDIDATE_REPORT.md](../../../PILOT_CANDIDATE_REPORT.md) (Candidate 1).
+
+## Vincoli rilevanti dello stato corrente
+
+- PHP 7.4+ (osservato in CI/dev: 8.3.31).
+- `phpunit.xml.dist`: `convertWarningsToExceptions="true"` — ma `json_encode()` non emette
+  warning, quindi non viene convertito in eccezione (verificato con probe).
+- Tutto l'outbound HTTP deve passare per `HttpClientInterface` (regola anti-SSRF di progetto).

changes/archive/2026-06-21-webhook-json-encode-guard/pilot-retrospective.md

@@ -0,0 +1,53 @@
+# Key lesson
+
+I gate che hanno funzionato sono stati quelli ancorati alla verità di terra:
+
+- eseguire il test reale;
+- osservare il RED reale;
+- leggere l'artefatto realmente prodotto;
+- verificare il working tree reale.
+
+Il consenso tra reviewer o tra AI non è validazione.
+
+Il maintainer resta il gate, soprattutto quando più reviewer concordano: modelli diversi
+possono condividere lo stesso punto cieco.
+
+Questa lezione va considerata parte del workflow:
+
+- `analyze` verifica coerenza documentale;
+- il RED eseguito verifica il comportamento reale;
+- la review del file prodotto verifica l'artefatto reale;
+- nessun passaggio AI↔AI sostituisce il giudizio del maintainer.
+
+---
+
+# Pilot retrospective — webhook-json-encode-guard
+
+## Cosa è andato bene
+
+- Il pilota era piccolo, localizzato e a basso rischio: un solo metodo di produzione, due test, una spec nuova.
+- La Runtime RED Probe ha smontato un'assunzione teorica (il timore che `convertWarningsToExceptions` rendesse il RED "sbagliato"): il probe reale ha mostrato che `json_encode()` non emette warning, quindi il guard `json_encode` semplice era sufficiente, senza `@`/`set_error_handler`/`wp_json_encode`.
+- Il RED ha fallito per il motivo giusto ("post() was called"), confermato sul codice reale prima del fix.
+- I gate di qualità (phpcs, phpstan, suite unit completa) erano già a baseline pulita, rendendo il GREEN inequivocabile.
+
+## Cosa ha richiesto correzione in closeout
+
+- La spec iniziale "certificava" le protezioni del client HTTP nella sezione Trasporto: corretta in linguaggio di **delega**, non di certificazione.
+- La spec doveva contenere una **Decision record attiva** (`DR-WEBHOOK-001`), non solo prosa descrittiva.
+- Necessità di mantenere il Markdown render-safe (nessun fence annidato).
+
+## Punto cieco condiviso
+
+Più passaggi di analisi (incluse revisioni AI) possono concordare e restare comunque
+incompleti. La validazione è arrivata dall'esecuzione reale e dal giudizio del maintainer,
+non dall'accordo tra revisori.
+
+## Follow-up debt
+
+- **Risky test pre-esistente:** `OpsHealthDashboard\Tests\Unit\Services\CheckRunnerTest::test_clear_results_deletes_from_storage`
+  (`tests/Unit/Services/CheckRunnerTest.php:309`) — segnalato da PHPUnit come "This test did not
+  perform any assertions". **Pre-esistente**, in un file non toccato da questo change.
+  **Non corretto qui** (fuori scope). Da affrontare come change separato.
+- **Disallineamento versione `package-lock.json`** (`0.5.0` → `0.6.2`, sincronizzato da
+  `npm install`): sintomo del finding di review sul disallineamento delle versioni tra
+  `package.json`, `composer.json`, header plugin, `readme.txt`. Da trattare separatamente.

changes/archive/2026-06-21-webhook-json-encode-guard/plan.md

@@ -0,0 +1,28 @@
+# Plan — webhook-json-encode-guard
+
+> Artefatto storico archiviato. Piano approvato dal maintainer prima dell'implementazione.
+
+## Approccio
+
+TDD red→green, scope minimo, fail-closed. Decisione validata dalla Runtime RED Probe
+(verità di terra: probe reale + RED reale), non da consenso tra reviewer.
+
+## Sequenza approvata
+
+1. **RED test (UTF-8 invalido)** — aggiungere `test_send_returns_failure_when_payload_contains_invalid_utf8` con spy su `post()` e flag `$called`.
+2. **RED test (NAN/INF)** — aggiungere `test_send_returns_failure_when_payload_contains_non_finite_float`.
+3. **Verifica RED** — `composer test:unit -- --filter WebhookChannelTest`; i nuovi test devono fallire perché `post()` viene chiamato (non per Warning/ErrorException).
+4. **Fix guard** — in `WebhookChannel::send()`, dopo `json_encode()` e prima di `hash_hmac()`/`post()`, ritornare fail-closed se `false === $raw_body`.
+5. **Verifica GREEN** — `composer test:unit -- --filter WebhookChannelTest`, `composer phpcs`, `composer analyse`.
+6. **Closeout + bozza spec** — preparare evidenze, `specs/channels/webhook.md` in linguaggio di stato; nessun archive finché non approvato.
+
+## Vincoli decisi
+
+- Fix limitato a `WebhookChannel::send()`.
+- Niente `wp_json_encode()`, `@json_encode()`, `set_error_handler()`.
+- Messaggio d'errore utente generico e localizzato (no `json_last_error_msg()` esposto).
+- Nessun commit/tag durante il pilota.
+
+## Rischio mitigato
+
+Un payload malformato non deve essere inviato e riportato come consegnato.