EPIC: Structured build & test for PostGuard — shrink the matrix + central e2e harness

[rubenhensen]

Why

PostGuard spans ~12 repos bound by a few implicit contracts, each tested in isolation with mocks. Flows are combinatorial and crypto-core versions have drifted with no single source of truth. Symptom: "fix one thing, three others break," found late and by hand.

The matrix has two axes

• Flows — sender × recipient × channel (website, Outlook, Thunderbird, SDK/API, mobile)
• Versions — pg-core ↔ pg-wasm ↔ pg-js ↔ pg-ffi ↔ PKG v2

They meet at three contracts (the seams):

1. Wire format — pg-core VERSION_V3 + bincode-v1 preamble.
2. PKG v2 HTTP API — /v2/parameters, /v2/{irma,request}/start|jwt|key|sign/key, /v2/api-key/validate.
3. Yivi condiscon — the IrmaAuthRequest/ConItem shape (the in-flight feat/condiscon-auth-request).

Two workstreams

• Shrink the matrix — enumerate the finite real flows; make the 3 contracts explicit/versioned; retire the dead postguard-thunderbird-extension; de-duplicate addon glue; one Yivi binding; one pg-js version; a compat manifest.
• Central harness — grow postguard-version-matrix → postguard-e2e with 4 layers: contract tests, crypto-compat fixtures, e2e golden flows (headless Yivi via irmaclient, real-device swappable later), version matrix in CI. Runs nightly + on contract-affecting PRs.

Assets we build on (don't rebuild)

• postguard-website/docker-compose.yml — full stack incl. irma-server + mailcrab
• postguard-version-matrix — manual version sweep
• irmago/irmaclient + internal/sessiontest — headless Yivi (disproves "decryption can't be automated")
• cryptify/api-description.yaml — OpenAPI pattern to copy
• postguard-docs/docs/guide/{architecture,usage-flows,protocol}.md

Progress is tracked via the sub-issues below.

[rubenhensen]

Mid-course review (Phase 0 at 3/5)

Stepped back and critically re-examined the approach before finishing Phase 0. Verdict: the direction holds — on evidence, not theory. Building the harness surfaced four real cross-component defects that no per-repo unit test could see, now filed: #233 (PKG dies if the IRMA server is briefly unreachable at boot), #234 (PKG never refreshes the IRMA JWT key → key rotation breaks all auth until restart), #235 (cryptify panics at startup if the PKG is unreachable), #236 (the pbdf email attribute is hardcoded across pg-js/cryptify/PKG — a testability and coupling problem).

Honest caveats now reflected in the plan:

• The golden flow (First green e2e golden flow: website → website happy path #205) drives a bespoke client, so it's a backend-contract test — it does not cover the real SDKs. Phase 2 (Phase 2 — Cover all supported flows (to decompose) #213, re-scoped) fixes this via pg-js's session-callback seam; Parametrize the email attribute type (pbdf.sidn-pbdf.email.email hardcoded across pg-js, cryptify, PKG) #236 unblocks it.
• Everything so far is HEAD-vs-HEAD. The time axis — old ciphertexts must keep decrypting, old published clients must keep working — is exactly Crypto-compat fixtures (L2): seal-by-each-client, unseal-all #206 (fixtures) and L4 (version matrix in CI). Crypto-compat fixtures (L2): seal-by-each-client, unseal-all #206 is next.
• Test-env fidelity gaps tracked: e2e: provision business-db from real postguard-business migrations (schema-contract fidelity) #237 (business-db from real migrations), e2e: keyshare-backed disclosure flow (test scheme + keyshare server) #238 (keyshare parity).
• e2e CI: cache the Rust image builds before making the workflow a required check #239: the e2e workflow must get build caching before becoming a required check anywhere — a slow mandatory gate gets bypassed, and then it protects nothing.
• The shrink-the-matrix workstream (Phases 3–4) remains the original first priority and the only thing that reduces how many parts can break; the harness is the safety net that makes that consolidation safe to do.

Priority order from here: #207 (CI, in flight) → #206 (fixtures) → #239 (caching) → Phase 2 starting with #236 → shrink workstream.