Skip to content

fix(core): correct the parameter types of the nested token builder - #672

Open
Spomky wants to merge 1 commit into
4.1.xfrom
fix/nested-token-builder-param-types
Open

fix(core): correct the parameter types of the nested token builder#672
Spomky wants to merge 1 commit into
4.1.xfrom
fix/nested-token-builder-param-types

Conversation

@Spomky

@Spomky Spomky commented Aug 6, 2026

Copy link
Copy Markdown
Member

Fixes #662.

Problem

NestedTokenBuilder::create() declared sealed array shapes that reject the documented usage. Analysing the documentation snippet with PHPStan (bleeding edge) or Psalm produced:

Parameter #4 $jweSharedProtectedHeader of method NestedTokenBuilder::create()
expects array{alg?: string, string?: mixed}, array{alg: 'RSA-OAEP', enc: 'A128GCM'} given.
💡 Sealed array shape does not accept array with extra key 'enc'.

Parameter #5 $jweSharedHeader of method NestedTokenBuilder::create()
expects array{alg?: string, string?: mixed}, array{foo: 'bar'} given.
💡 Sealed array shape does not accept array with extra key 'foo'.

Three distinct mistakes were involved:

  1. array{alg?: string, string?: mixed} declares a shape with two optional keys, alg and one literally named string. It was clearly meant to be array<string, mixed>. Every other header parameter — enc, zip, cty, kid, … — was rejected.
  2. array{array{key: JWK, ...}} declares a shape holding exactly one element at key 0, not a list. Building a token with two signatures or two recipients was reported as an error too:
    Parameter #2 $signatures of method NestedTokenBuilder::create() expects
    array{array{key: JWK, protected_header?: ..., header?: ...}}, array{array{...}, array{...}} given.
    💡 Sealed array shape does not accept array with extra key 1.
    
  3. As noted in the report, the JWE layer the builder delegates to declared no value type at all for its header parameters, so nothing downstream could have caught this.

Changes

  • NestedTokenBuilder::create(): $jweSharedProtectedHeader and $jweSharedHeader are array<string, mixed>; $signatures and $recipients are array<array{...}>.
  • JWEBuilder::withSharedProtectedHeader(), withSharedHeader() and addRecipient() now declare array<string, mixed> for their header parameters (their missingType.iterableValue entries are dropped from the PHPStan baseline).
  • JWS::addSignature() and Signature::__construct() carried the same array{alg?: string, string?: mixed} shape and are corrected the same way. The baseline entries that quoted the old shape are updated accordingly.

Documentation only — no runtime behaviour changes.

Verification

The documented snippet, extended with a second signature, was analysed at level max with bleeding edge against both the old and the new signatures: 3 errors before, none after.

  • castor phpstan: 43 errors, identical to the ones already present on 4.1.x before this branch (the QA tooling breakage repaired on 4.2.x by Make the quality gates pass again #669 is not backported here). No new error, no unmatched baseline entry.
  • castor phpunit: 752 tests, 2223 assertions, green.
  • castor ecs cannot run on 4.1.x (Undefined constant SetList::PHPUNIT), pre-existing and unrelated — this change touches docblocks only.

`NestedTokenBuilder::create()` declared sealed array shapes that rejected
the documented usage: the JWE headers only accepted `alg` (plus a key
literally named `string`), so passing `enc` was reported as an error, and
`$signatures`/`$recipients` were shapes holding exactly one element, so a
token with two signatures or two recipients was rejected as well.

The JWE layer the builder delegates to declared no value type at all for
its header parameters, and `JWS::addSignature()`/`Signature::__construct()`
carried the same bogus shape.

Fixes #662
@Spomky Spomky linked an issue Aug 6, 2026 that may be closed by this pull request
@Spomky Spomky added this to the 4.1.9 milestone Aug 6, 2026
@Spomky Spomky added the bug label Aug 6, 2026
@Spomky Spomky self-assigned this Aug 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Parameter types are wrong for NestedTokenBuilder

1 participant