Skip to content

gate-3 caller-identity-ignored: an interface-contract $userId an implementor correctly ignores has no app-side fix #339

Closed

Description

@rubenvdlinde

Summary

gate-3 (stub-scan), rule caller-identity-ignored, reports three findings on ConductionNL/procest for which no correct app-side fix exists. The parameter it objects to is an interface-contract obligation, and the interface's other implementors genuinely use it.

This is the same family as the interface-declaration false positive already fixed in #291 — but one step further along: #291 covered bodiless declarations, and this is an implementation with a real body that correctly does not need the parameter.

The findings

lib/Service/Transitions/ChecklistGuard.php:65       method=evaluate rule=caller-identity-ignored param=$userId
lib/Service/Transitions/RequiredDocumentGuard.php:50 method=evaluate rule=caller-identity-ignored param=$userId
lib/Service/Transitions/RequiredFieldGuard.php:48   method=evaluate rule=caller-identity-ignored param=$userId

Why there is no fix the author can make

All three implement one interface:

// lib/Service/Transitions/GuardEvaluatorInterface.php:47
public function evaluate(array $guardConfig, array $case, string $userId): GuardResult;

There are five implementors, and $userId references inside evaluate():

implementor $userId refs uses caller identity?
RoleGuard 12 yes — this is the whole point of the class
MandaatGuard 3 yes
ChecklistGuard 1 (signature only) no — inspects the case's checklist
RequiredDocumentGuard 1 (signature only) no — inspects the case's documents
RequiredFieldGuard 1 (signature only) no — inspects a case field

A guard that asks "is this required field filled in?" has no business consulting the caller. The three flagged classes are correct. The only ways to silence the gate are:

  1. delete the parameter — breaks GuardEvaluatorInterface and every call site in GuardRegistry::evaluateAll(); or
  2. reference $userId pointlessly in the body to get the grep count to 2 — i.e. write dead code to satisfy a stub detector.

Both make the code worse. Neither is something a reviewer should accept.

The signal the gate is walking past

All three already carry an explicit, reason-bearing marker that the parameter is deliberately unused:

 * @param string $userId Current user UID (unused)
 *
 * @SuppressWarnings(PHPMD.UnusedFormalParameter)

That is the house convention for exactly this situation, it is already enforced elsewhere (PHPMD reads it), and gate-3 does not look at it.

Suggested fix

In the caller-identity-ignored loop in run-hydra-gates.sh, skip a method when either holds:

  • the docblock immediately preceding the signature carries @SuppressWarnings(PHPMD.UnusedFormalParameter), or
  • the @param line for the flagged parameter carries an explicit unused/ignored marker.

The first is preferable: it is an existing, tool-enforced annotation rather than a new gate-specific opt-out, so it cannot be sprinkled around freely without PHPMD agreeing.

Please guard the change with a planted true positive: a service method that takes $userId, ignores it, and carries no suppression must still be reported. An exemption that cannot fail is worth less than the finding it removes.

Impact

3 findings on procest. Fleet-wide this pattern will appear anywhere a strategy/guard/handler interface passes caller identity to implementors that do not all need it, which is a normal shape.

Activity

  1. rubenvdlinde commented on Aug 13, 2026

    @rubenvdlinde
    ContributorAuthor

    Reproduced and fixed in #434.

    Reproduction first. Full 60-gate run on a fresh development checkout of six fleet apps (hydra-gates@c26f9a3). procest 792fe1f4b: 3 findings, the same three files and the same parameter. opencatalogi, openregister, softwarecatalog, docudesk, larpingapp: 0 each. The issue is months old and this one re-runs exactly as filed.

    The premise holds. I tried to write the closing action and could not. Deleting $userId breaks GuardEvaluatorInterface and every call site in GuardRegistry::evaluateAll(); referencing it to push the grep count to 2 is dead code written to satisfy a stub detector. There was no third option.

    The fix. New check_caller_identity_exempt.py. A finding is exempt only when both hold:

    1. Contract-imposed — a supertype resolvable in this repository declares the same method with the same parameter (implements/extends, transitively). Fully mechanical, nothing asserted. This is what makes the exemption un-sprinklable: an invented service method has no supertype, so it cannot be silenced by a docblock edit.
    2. Marked unused — the docblock's @param line for that parameter carries an explicit unused marker.

    Condition 1 alone would exempt a genuinely gutted implementation — a RoleGuard that stopped consulting $userId is contract-imposed too, and that is the defect the rule exists for. Condition 2 alone is a one-word escape hatch.

    On the @SuppressWarnings(PHPMD.UnusedFormalParameter) suggestion — I took the stricter of the two options you offered, and the measurement is why. That annotation is method-wide and cannot name which parameter it excuses. MandaatGuard carries it (for a different parameter) while genuinely using $userId; keying on it would have pre-authorised MandaatGuard's $userId for a reason that was never about $userId. The per-@param marker is per-parameter, and all three findings already carry it, so no app-side edit is required — procest's code is untouched.

    Fail-closed: missing helper, unreadable file, or a supertype outside this repository all leave the finding standing.

    The planted true positive you asked for — five arms, four of them controls (test_gate_3_contract_param.sh):

    arm fixture expected got
    1 contract + marker (your shape) 0 0 ✅
    2 control contract, marker deleted 1 1 ✅
    3 control marker, no contract — decidesk#45 with a docblock 1 1 ✅
    4 control both look present, the interface file is absent 1 1 ✅
    5 control supertype declares the method without the parameter 1 1 ✅

    Arms 2–5 each delete exactly one half of the exemption. Revert test: the same suite against origin/main's unmodified runner — arm 1 goes red, all four controls stay green, so they were never depending on the fix.

    Effect: procest 3 → 0 across a full 60-gate run, runner exit 8 → 7, and gate-3 is the only verdict line that moved. 0 → 0 on the other five apps.

  2. added a commit that references this issue on Aug 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions