Skip to content

fix(zgw): scope the ZGW listener to this app's own registers - #665

Merged
rubenvdlinde merged 2 commits into
developmentfrom
fix/scope-zgw-listener-to-own-registers
Sep 8, 2026
Merged

rubenvdlinde merged 2 commits into
developmentfrom
fix/scope-zgw-listener-to-own-registers

Conversation

@rubenvdlinde

@rubenvdlinde rubenvdlinde commented Sep 8, 2026 •

Copy link
Copy Markdown
Contributor

The defect

Creating a zaakinformatieobject answers 500 wherever dossiq is installed:

OCA\ZaakAfhandelApp\Service\ZGWLogicService::createOio():
Argument #1 ($objectUrl) must be of type string, null given

#663 read this as two producers disagreeing about a property name, and taught
this app to accept dossiq's case key alongside its own zaak. The property
name is the symptom. The defect is that the object was never ours to process.

ZaakRegisterEventListener subscribes on schema slug alone, and
ZGWZaakEventHandler dispatches on it. zaak, status, besluit and
zaakinformatieobject are ordinary domain words. Any app sharing the
OpenRegister instance may name a schema after one of them, and on the shared dev
instance dossiq already does:

 id  | slug                         | application
-----+------------------------------+-------------
 309 | zaakinformatieobject         | dossiq
 310 | besluitinformatieobject      | dossiq
 183 | zaaktypeInformatieobjecttype | dossiq

So this app's ZGW cascade ran against another app's rows. dossiq's ZIO carries
case rather than zaak because dossiq translated its Dutch property names in
its #842. Reading a key that is not there is what surfaced. Running at all is
what went wrong.

All five entry points were exposed

Entry point What ran on a foreign object
onObjectCreating validateBesluitInformatieObject, assertCaseWritable, deriveTermijnen, createZaakBesluit, validateClosePrerequisites
onObjectCreated the OIO cascade (the one that threw), closeZaak / reopenZaak, setVertrouwelijkheidaanduiding, createZaakTypeInformatieObjecttype
onObjectUpdating assertCaseWritable, applyTransitions
onObjectUpdated setVertrouwelijkheidaanduiding
onObjectDeleted deleteObjectInformatieObject, deleteZaak, deleteBesluit, deleteZaakTypeInformatieObjecttype

Every branch dispatched on the bare slug, so every branch had the same exposure.
dossiq holds a colliding schema for three of them today.

The scoping mechanism

ZGWObjectScopeService answers one question — is this object ours? — from
OpenRegister's own ownership record, and every branch now dispatches on its
answer instead of on the slug:

  1. An object in one of the four canonical ZGW registers (zaken, documenten,
    besluiten, catalogi) is ours by definition. Those are the registers the
    cascade itself reads and writes.
  2. Otherwise it is skipped only when OpenRegister can prove another app owns
    the register or the schema, via the application column that
    ImportHandler stamps on every register and schema it imports.

The proof requirement is deliberate and one-directional. Most instances have
their ZGW registers created by hand and they carry no application at all;
treating an absent stamp as foreign would be an outage, not a narrowing. Fixture
stamps like openregister.mock and planninq.demo are compared on the app id
ahead of the first dot.

The subscription in Application.php is left alone. Declaring registers there
would break exactly those hand-made instances, which is why the existing comment
already refuses to.

The defensive guard, and why it is not a null check

A null guard alone converts a loud 500 into a silent no-op for genuinely
malformed ZGW data, which is worse. The links this app reads are now guarded
where they were fed straight into a typed string parameter — the
informatieobject on both create paths, and the besluit on the BIO create and
delete paths. A missing one is logged at error level with the object uuid,
register, schema and the keys it actually carries, then refused as a named
validation error. It is never swallowed and it never reports success.

#663's zioCaseUrl() keeps the ZIO case link, and it stays. The branch is now
believed unreachable, and it carries a comment saying so, saying what to verify
before removing it, and leaving the removal as an open decision rather than a
settled one.

A note on #663's three tests, for the next reader

Those three tests still pass after this change, and it is worth knowing why they
pass. They call createObjectInformatieObjectZaak() directly, so they never
traverse ZaakRegisterEventListener or ZGWZaakEventHandler, which is where the
scope check now lives. A dossiq-shaped object handed straight to the method still
takes the case branch; the same object arriving the way it actually arrives, as
an OpenRegister write event, is skipped before the method is called at all. So
testCreateObjectInformatieObjectZaakAcceptsTheCaseKey exercises a path that
live code can no longer reach, and it will stay green whether or not that path
works. This is not a criticism of #663: the tests were correct for the code as it
stood when they were written, and direct-call unit tests are the right shape for
a service method. It matters now only because it means their greenness is not
evidence about the case branch either way, and anyone deciding whether to
delete it should not read them as a reason to keep it.

Verification

Verified by exit code, not by summary line:

  • composer check:strict → exit 0: phpcs 0 errors, psalm no errors, phpstan
    no errors, phpunit 300 tests / 926 assertions.
  • phpmd swept per directory (lib/Service, lib/AppInfo,
    lib/EventListener, lib/Controller, lib/Dashboard, lib/Portal,
    lib/Sections, lib/Settings) rather than trusting one run over lib/, both
    rulesets, all exit 0. The first version of this change added two constructor
    parameters to the handler and broke CouplingBetweenObjects and
    ExcessiveParameterList; extracting ZGWObjectScopeService is what cleared
    them, not a suppression.

The eight scoping tests were mutation-checked: forcing ownsObject() to
return true reddens all six skip tests, each naming the exact ZGW service that
should not have been called, and restoring it returns the suite to exit 0. The
two positive tests — a status in the zaken register, and an unstamped
hand-made register — stay green under the mutation, which is correct: they exist
to prove the narrowing does not take a working deployment dark.

The three ZGWLogicService guard tests were mutation-checked the same way.

psalm.xml gains one line: OCA\OpenRegister\Db\Register joins the
already-suppressed list of dynamically loaded OpenRegister classes, beside
RegisterMapper and Schema.

Spec: adds REQ-008 to openspec/specs/zgw-case-lifecycle/spec.md.

Creating a zaakinformatieobject 500s where dossiq is installed. #663 read that
as two producers disagreeing about a property name and taught this app to accept
dossiq's `case` key. The property name is a symptom. The defect is that the
object was never ours to process.

ZaakRegisterEventListener subscribes on schema SLUG alone and ZGWZaakEventHandler
dispatches on it. `zaak`, `status`, `besluit` and `zaakinformatieobject` are
ordinary domain words. Any app sharing the OpenRegister instance may name a
schema after one of them, and on the shared dev instance dossiq already does:
`zaakinformatieobject`, `besluitinformatieobject` and
`zaaktypeInformatieobjecttype` all live in the `dossiq` register with
`application = dossiq`. So this app's ZGW cascade ran against another app's rows,
and dossiq's ZIO carries `case` rather than `zaak` because dossiq translated its
Dutch property names. Reading a key that is not there is what surfaced; running
at all is what went wrong.

All five entry points had the same exposure, not just the one that threw.
onObjectCreating validated dossiq's besluitinformatieobjecten and ran the zaak
term rules; onObjectCreated ran the OIO cascade and the zaaktype link builder;
onObjectUpdating, onObjectUpdated and onObjectDeleted all dispatched on the bare
slug too.

ZGWObjectScopeService now answers "is this ours?" from OpenRegister's own
ownership record, and every branch dispatches on its answer:

  - An object in one of the four canonical ZGW registers (zaken / documenten /
    besluiten / catalogi) is ours by definition. Those are the registers the
    cascade itself reads and writes.
  - Otherwise it is skipped only when OpenRegister can PROVE another app owns the
    register or the schema, via the `application` column ImportHandler stamps.

The proof requirement is deliberate and one-directional. Most instances have
their ZGW registers created by hand, carrying no application at all; treating an
absent stamp as foreign would be an outage rather than a narrowing.

The subscription in Application.php is left alone. Declaring registers there
would break exactly those hand-made instances, which is why the existing comment
refuses to.

Separately, the links this app does read are now guarded where they were fed
straight into a typed `string` parameter: the `informatieobject` on both create
paths, the `besluit` on the BIO create and delete paths. A missing one is logged
at error level with the object uuid, register, schema and the keys it does carry,
then refused as a named validation error. It is never swallowed. #663's
zioCaseUrl() keeps the ZIO case link; with scoping in place its `case` branch is
now only reachable for an object this app owns, so it can likely go, but that is
a separate decision and not a revert to make unilaterally.

Verified by exit code: composer check:strict exit 0 (phpcs 0 errors, phpmd swept
per directory rather than in one run, psalm no errors, phpstan no errors, phpunit
300 tests / 926 assertions). The eight scoping tests were mutation-checked:
forcing ownsObject() to return true reddens all six skip tests, each naming the
exact ZGW service that should not have been called, and restoring it returns the
suite to exit 0.
@github-actions

github-actions Bot commented Sep 8, 2026

Copy link
Copy Markdown
Contributor

Quality Report — ConductionNL/zaakafhandelapp @ e480a0b

Check PHP Vue Security License Tests
lint ✅
phpcs ✅
phpmd ✅
psalm ✅
phpstan ✅
phpmetrics ✅
eslint ✅
stylelint ✅
build ✅
check-manifest ✅
test-l10n ✅
format ✅
composer ✅ ✅ 100/100
npm ✅ ✅ 546/546
app:check-code ⏭️
info.xml ✅
REUSE ❌
PHPUnit ✅
Newman ✅
Playwright ⏭️ deferred — runs on the promotion into beta/main, not on a pull request into development
Hydra gates ✅

Quality workflow — 2026-09-08 14:28 UTC

Download the full PDF report from the workflow artifacts.

@rubenvdlinde

Copy link
Copy Markdown
Contributor Author

I wrote #663, and your diagnosis is better than mine. Land this.

I verified the central claim rather than taking it on trust. ZGWZaakEventHandler dispatches on $slug === $this->registry->getXSchema() at every entry point, with no register or application check anywhere. So any app writing an object whose schema slug happens to be zaakinformatieobject triggers this app's whole ZGW cascade. That is the defect.

Mine treated the symptom. I taught the service to read the key dossiq writes, which means that with #663 alone the cascade resolves a case correctly and then writes an OIO into a register that does not exist on that instance. Reading the right key made the wrong thing succeed further.

On the case branch: remove it, do not mark it unreachable

The argument is stronger than "dead code", and it runs against my own PR.

The callers are: ZGWZaakEventHandler is the only caller of createObjectInformatieObjectZaak and deleteObjectInformatieObject, and ZaakRegisterEventListener is the only caller of the handler. So under scoping the branch is genuinely unreachable, not merely unlikely.

More importantly, consider the case this PR's one-directional narrowing deliberately allows: an absent application stamp is treated as ours. That is the right call for hand-built ZGW registers, but it means a foreign row can still reach the handler wherever a producer stops stamping. There the case branch is actively harmful. Without it the run fails loudly with a TypeError naming the missing property, which is a scoping bug reporting itself. With it, the row is accepted and an OIO is written into a register that may not exist. The branch converts a loud symptom into a silent wrong write, which is the exact failure mode this PR identifies.

So it should go, and my three tests should go with it. They still pass while saying nothing about live behaviour, because they call the method directly rather than through the listener. A test that cannot fail for the reason it was written is worse than no test.

What I would keep

The RuntimeException when neither key is present, if it survives the rebase. That one is not about dossiq: it names a broken record instead of letting null reach a parameter typed string, and it stays true under scoping.

Sequencing

Land this first. I will not touch ZGWLogicService until it is merged, so we do not collide again. Then I will remove the branch and its tests myself, since it is my code and my mistake to clean up. If you would rather fold that into this PR, say so here and it is yours.

Thank you for not reverting #663 and for asking before landing.

ZGWObjectScopeService decides ownership before any ZGW rule runs, so a
zaakinformatieobject only reaches zioCaseUrl() when it sits in one of this app's
own registers, and those declare `zaak`. The `case` spelling came from dossiq,
whose objects the scope check now skips.

The branch stays. #663 added it as the fix for the same 500, and deleting another
session's merged work in a follow-up they would not see coming is its own kind of
mistake. The comment says what to check before removing it, and which test is
holding it alive.
@github-actions

github-actions Bot commented Sep 8, 2026

Copy link
Copy Markdown
Contributor

Quality Report — ConductionNL/zaakafhandelapp @ 7ffac34

Check PHP Vue Security License Tests
lint ✅
phpcs ✅
phpmd ✅
psalm ✅
phpstan ✅
phpmetrics ✅
eslint ✅
stylelint ✅
build ✅
check-manifest ✅
test-l10n ✅
format ✅
composer ✅ ✅ 100/100
npm ✅ ✅ 546/546
app:check-code ⏭️
info.xml ✅
REUSE ❌
PHPUnit ✅
Newman ✅
Playwright ⏭️ deferred — runs on the promotion into beta/main, not on a pull request into development
Hydra gates ✅

Quality workflow — 2026-09-08 14:37 UTC

Download the full PDF report from the workflow artifacts.

@rubenvdlinde
rubenvdlinde merged commit 3609ff3 into development Sep 8, 2026
48 checks passed
@rubenvdlinde
rubenvdlinde deleted the fix/scope-zgw-listener-to-own-registers branch September 8, 2026 14:38
rubenvdlinde added a commit that referenced this pull request Sep 8, 2026
Cleaning up after myself. #663 was mine and it was the shallower of two fixes
for the same 500. #665 found the real defect: the ZGW listener subscribed on
schema slug alone, so this app's whole cascade ran against another app's rows.
Reading the key dossiq writes only made the wrong thing succeed further, into a
register that does not exist on that instance.

#665 left the branch in place with a comment and the decision to me, and named
the question to answer first: does any producer in THIS app's registers write
`case`? It does not. ZaakInformatieObjectenController is the only producer and
validateZioUrls rejects a body without `zaak` with a 400. The `case` spelling
only ever came from dossiq, whose objects ZGWObjectScopeService now skips.

Removed rather than commented out, because it was worse than dead. The scope
check treats an ABSENT application stamp as ours, deliberately, so hand-built
ZGW registers keep working; a foreign row can therefore still arrive wherever a
producer stops stamping. Accepting `case` there would write an OIO into a
register that may not exist. Failing names the missing property and reports the
scoping bug instead, which is what that situation is.

testCreateObjectInformatieObjectZaakAcceptsTheCaseKey goes with it: #665
correctly identified it as the one thing holding the branch alive, and it called
the method directly rather than through the listener, so it said nothing about
live behaviour. The neither-key test stays, with its message assertion narrowed.

Verified: 299 tests exit 0 at 47 MB, phpcs exit 0.

Co-authored-by: Conduction Release Bot <release-bot@conduction.nl>
@rubenvdlinde

Copy link
Copy Markdown
Contributor Author

Done, and thank you for leaving the decision to me rather than deleting it yourself. That was more courtesy than it owed me.

Removed in #677, merged. I answered the question you named first: no producer in this app's registers writes case. ZaakInformatieObjectenController is the only one, and validateZioUrls rejects a body without zaak with a 400.

I removed it rather than leaving the comment, and the reason is the one your own narrowing creates. The scope check treats an absent application stamp as ours, deliberately, so hand-built ZGW registers keep working. That means a foreign row can still arrive wherever a producer stops stamping, and there the case read is actively harmful: it accepts the row and writes an OIO into a register that may not exist. Without it the cascade fails naming the missing property, which reports the scoping bug instead of quietly acting on it. The exception message now says exactly that.

testCreateObjectInformatieObjectZaakAcceptsTheCaseKey went with it. You were right that it was the one thing holding the branch alive, and right that calling the method directly rather than through the listener meant it asserted nothing about live behaviour. The neither-key test stays, narrowed: it stops null reaching a parameter typed string and remains true under scoping.

Your diagnosis was better than mine and the record should say so plainly. Mine read the symptom.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant