feat(stuf): StUF-ZDS writes reach the owning app as generic case operations (decision 206)

[rubenvdlinde]

What this does

Decision 206 (Ruben, 12 Oct): another system may write cases and documents into dossiq over StUF, but only through integriq and authenticated. This is the integriq half. The dossiq half is ConductionNL/dossiq#3801, which lands after this one.

The provider receiver from #2659 already authenticated a zakLk01 and an edcLk01 against the source's WS-Security UsernameToken (with acceptsProviderRequests set) and dispatched an event. That event carried raw StUF element names, and dossiq refused every one. Now:

• StufProviderOperationMapper maps the three StUF-ZDS 1.2 write messages onto generic case operations: creeerZaak (zakLk01, mutatiesoort T) becomes create, updateZaak (zakLk01, W) becomes update, voegZaakdocumentToe (edcLk01, T) becomes add-document. Keys are generic (title, startDate, caseTypeCode, initiator, content), dates are ISO, and the document bytes are decoded. The mapping is the adapter for a national standard, so it is code here (decision 182). Which case type a zaaktype opens on is configuration in the owning app.
• A W kennisgeving sends the old object and then the new one. The reader took the first. It now takes the last.
• Any other mutatiesoort (V, E, a document change) and an inhoud that is not base64 are refused here. The owning app is not asked.
• A kennisgeving is answered as StUF-ZDS 1.2 pairs it: Bv03 when accepted, Fo03 when not. feat(stuf): provider receiver answers StUF queries through the owning app (decision 199) #2659 answered Bv01 and Fo01, which a ZDS client does not expect. buildBv01 had no other caller and is removed.
• The owning app can say why it refuses. refuse() takes a kind, and each kind has its own HTTP status: refused 400, forbidden 403, not found 404, conflict 409. Not authenticated stays 401 and nobody answering stays 500. A fault never travels as HTTP 200.
• A write that a sibling app forwarded from its own URL (StufProviderRequestReceivedEvent) is refused with 403. So dossiq's old /api/stuf/zaken address cannot become a write route. Queries can still be forwarded.

What it does not do

• The StUF fault code for every refusal by the owning app stays StUF058. I did not assert a finer code per kind, because I could not check the StUF fault catalogue from here.
• A request body is capped at 2 MiB, as before, so a document of about 1.5 MB is the largest that fits. MTOM is not built.
• actualiseerZaakstatus, genereerZaakIdentificatie and document changes are not carried out.

Rollout, for an administrator

1. Nothing changes for a source that does not set configuration.acceptsProviderRequests.
2. A case system that sent kennisgevingen to /apps/integriq/api/stuf-zkn/provider/{sourceId}/cases now gets a Bv03 or Fo03 where it got a Bv01 or Fo01.
3. Writes are carried out only when the owning app accepts them. For dossiq that is the paired PR and its endpoint setting.

Verified

• StufProviderReceiverTest and StufProviderRequestReceivedListenerTest: 20 tests, 268 assertions, green. A control run with the 403 mapping and the forwarded-write guard broken on purpose turned two tests red (refactor/r2/logs/w1-control-red.log).
• The delivered status is read after Nextcloud's OCSMiddleware. Inside a server (CI) the test runs the real OC\AppFramework\Middleware\OCSMiddleware. In the bare unit run that class is not loadable, so the test applies its measured rule instead (a 401 or 403 from an OCSController becomes 200). The controller is a plain Controller, and the test asserts that too.
• phpcs and phpmd on the changed files: clean.
• composer check:strict, once, on 1771c35 (refactor/r2/logs/w1-strict.log): no-legacy-types, routes, lint, phpcs, phpmd, psalm and phpstan green. The suite's only red is 11 errors in tests/Unit/AppInfo, the same 11 development carries (a DIContainer type in the test double), none in a file this PR touches.
• Not verified: a live exchange with a StUF client. Owed as one live pass with dossiq installed.

[github-actions]

Quality Report — ConductionNL/integriq @ 26ece02

Check	PHP	Vue	Security	License	Tests
lint	✅
phpcs	✅
phpmd	✅
psalm	✅
phpstan	✅
phpmetrics	✅
eslint		✅
stylelint		✅
build		✅
build		✅
check-specs		✅
test-l10n		✅
format		✅
check-schema-l10n		✅
check-l10n-js		✅
composer			✅	✅ 143/143
npm			✅	✅ 647/647
app:check-code	⏭️
info.xml	✅
REUSE	❌
lockfile sync		✅
PHPUnit					✅ 5438/5438 · 1 skipped
Newman					✅ 130/130
Playwright					⏭️ deferred: E2E runs locally and on the promotion path only. This pull request targets development, so the suite is asked once per promotion into beta and main rather than once per push per open pull request. Run it locally with npx playwright test, or from the Actions tab on a branch with no open pull request into development.
Hydra gates					✅
Hydra gates (axe)					✅

---

Quality workflow — 2026-10-12 08:10 UTC

Download the full PDF report from the workflow artifacts.