Introduce trust_anchor_hints claim

Author: cicnavi

src/Codebooks/ClaimsEnum.php

@@ -182,6 +182,7 @@ enum ClaimsEnum: string
     // Type
     case Typ = 'typ';
     case Type = 'type';
+    case TrustAnchorHints = 'trust_anchor_hints';
     case TrustChain = 'trust_chain';
     case TrustMark = 'trust_mark';
     case TrustMarkIssuers = 'trust_mark_issuers';

src/Federation/EntityStatement.php

@@ -127,6 +127,42 @@ public function getAuthorityHints(): ?array
     }
 
 
+    /**
+     * @throws \SimpleSAML\OpenID\Exceptions\EntityStatementException
+     * @throws \SimpleSAML\OpenID\Exceptions\JwsException
+     * @return null|non-empty-string[]
+     */
+    public function getTrustAnchorHints(): ?array
+    {
+        // trust_anchor_hints
+        // OPTIONAL. An array of strings representing the Entity Identifiers of Trust Anchors trusted by the Entity.
+        // Its value MUST NOT be the empty array []. This Claim MUST NOT be present in Entity Configurations
+        // of Trust Anchors with no Superiors.
+
+        $claimKey = ClaimsEnum::TrustAnchorHints->value;
+        $trustAnchorHints = $this->getPayloadClaim($claimKey);
+
+        if (is_null($trustAnchorHints)) {
+            return null;
+        }
+
+        if (!is_array($trustAnchorHints)) {
+            throw new EntityStatementException('Invalid Trust Anchor Hints claim.');
+        }
+
+        if ($trustAnchorHints === []) {
+            throw new EntityStatementException('Empty Trust Anchor Hints claim encountered.');
+        }
+
+        // It MUST NOT be present in Subordinate Statements.
+        if (!$this->isConfiguration()) {
+            throw new EntityStatementException('Trust Anchor Hints claim encountered in non-configuration statement.');
+        }
+
+        return $this->helpers->type()->ensureArrayWithValuesAsNonEmptyStrings($trustAnchorHints, $claimKey);
+    }
+
+
     /**
      * @return ?array<string,mixed>
      * @throws \SimpleSAML\OpenID\Exceptions\JwsException
@@ -379,6 +415,7 @@ protected function validate(): void
             $this->getType(...),
             $this->getKeyId(...),
             $this->getAuthorityHints(...),
+            $this->getTrustAnchorHints(...),
             $this->getMetadata(...),
             $this->getMetadataPolicy(...),
             $this->getTrustMarks(...),

tests/src/Federation/EntityStatementTest.php

@@ -136,6 +136,7 @@ protected function setUp(): void
         $typeHelperMock->method('ensureString')->willReturnArgument(0);
         $typeHelperMock->method('ensureNonEmptyString')->willReturnArgument(0);
         $typeHelperMock->method('ensureInt')->willReturnArgument(0);
+        $typeHelperMock->method('ensureArrayWithValuesAsNonEmptyStrings')->willReturnArgument(0);
 
         $this->claimFactoryMock = $this->createMock(ClaimFactory::class);
         $this->federationClaimFactoryMock = $this->createMock(FederationClaimFactory::class);
@@ -277,6 +278,61 @@ public function testThrowsIfAuthorityHintsNotInConfigurationStatement(): void
     }
 
 
+    public function testCanDefineTrustAnchorHints(): void
+    {
+        $this->validPayload['trust_anchor_hints'] = ['trust-anchor-id'];
+
+        $this->signatureMock->method('getProtectedHeader')->willReturn($this->sampleHeader);
+        $this->jsonHelperMock->method('decode')->willReturn($this->validPayload);
+
+
+        $this->assertSame(['trust-anchor-id'], $this->sut()->getTrustAnchorHints());
+    }
+
+
+    public function testThrowsOnInvalidTrustAnchorHints(): void
+    {
+        $this->validPayload['trust_anchor_hints'] = 'invalid';
+
+        $this->expectException(JwsException::class);
+        $this->expectExceptionMessage('Invalid');
+
+        $this->signatureMock->method('getProtectedHeader')->willReturn($this->sampleHeader);
+        $this->jsonHelperMock->method('decode')->willReturn($this->validPayload);
+
+        $this->sut();
+    }
+
+
+    public function testThrowsOnEmptyTrustAnchorHints(): void
+    {
+        $this->validPayload['trust_anchor_hints'] = [];
+
+        $this->expectException(JwsException::class);
+        $this->expectExceptionMessage('Empty');
+
+        $this->signatureMock->method('getProtectedHeader')->willReturn($this->sampleHeader);
+        $this->jsonHelperMock->method('decode')->willReturn($this->validPayload);
+
+        $this->sut();
+    }
+
+
+    public function testThrowsIfTrustAnchorHintsNotInConfigurationStatement(): void
+    {
+        $this->validPayload['trust_anchor_hints'] = ['trust-anchor-id'];
+        $this->validPayload['iss'] = 'something-else';
+
+        $this->expectException(JwsException::class);
+        $this->expectExceptionMessage('non-configuration');
+
+        $this->signatureMock->method('getProtectedHeader')->willReturn($this->sampleHeader);
+        $this->jsonHelperMock->method('decode')->willReturn($this->validPayload);
+
+        $this->sut();
+    }
+
+
     public function testTrustMarksAreOptional(): void
     {
         $payload = $this->validPayload;