WIP

Author: cicnavi

docs/5-federation-discovery.md

@@ -61,48 +61,50 @@ The store interface is minimal:
 interface EntityCollectionStoreInterface
 {
     /**
-     * Persist discovered entity IDs for a given Trust Anchor.
+     * Persist discovered entities for a given Trust Anchor.
      */
-    public function storeEntityIds(string $trustAnchorId, array $entityIds, int $ttl): void;
+    public function store(string $trustAnchorId, array $entities, int $ttl): void;
 
     /**
-     * Retrieve previously discovered entity IDs.
+     * Retrieve previously discovered entities.
      * Return null when not found or expired.
      */
-    public function getEntityIds(string $trustAnchorId): ?array;
+    public function get(string $trustAnchorId): ?array;
 
     /**
-     * Remove stored entity IDs (for force re-discovery).
+     * Remove stored entities (for force re-discovery).
      */
-    public function clearEntityIds(string $trustAnchorId): void;
+    public function clear(string $trustAnchorId): void;
 }
 ```
 
-> **Note**: The store tracks only the list of entity IDs per Trust Anchor, not
-> the Entity Configurations themselves. Entity Configurations are fetched
-> dynamically through `EntityStatementFetcher::fromCacheOrWellKnownEndpoint()`,
-> which already handles JWS-level caching and respects expiry.
+> **Note**: The store tracks the JWT payload arrays per Trust Anchor.
+> Entity Configurations are fetched dynamically through `EntityStatementFetcher::fromCacheOrWellKnownEndpoint()`
+> during the traversal process, which handles JWS-level caching and respects expiry.
 
 ## Federation Discovery
 
 Federation Discovery performs a top-down traversal of the federation hierarchy.
 Starting from a Trust Anchor, it follows `federation_list_endpoint` links on
 each entity to collect all subordinate entity IDs recursively.
 
-### Discovering Entity IDs
+### Discovering Entities
 
 ```php
 /** @var \SimpleSAML\OpenID\Federation $federationTools */
 
 $trustAnchorId = 'https://trust-anchor.example.org/';
 
 try {
-    // Discover all entity IDs in the federation.
-    $entityIds = $federationTools->federationDiscovery()
-        ->discoverEntities($trustAnchorId);
+    // Discover all entities (ID -> payload map) in the federation.
+    $entities = $federationTools->federationDiscovery()
+        ->discover($trustAnchorId);
 
-    // $entityIds is an array of entity ID strings, e.g.:
-    // ['https://trust-anchor.example.org/', 'https://intermediate.example.org/', ...]
+    // $entities is an array keyed by entity ID, where values are JWT payload arrays:
+    // [
+    //     'https://trust-anchor.example.org/' => ['iss' => '...', 'metadata' => [...]],
+    //     ...
+    // ]
 } catch (\Throwable $exception) {
     $logger->error('Federation discovery failed: ' . $exception->getMessage());
 }
@@ -115,63 +117,46 @@ The discovery algorithm:
 3. Calls the subordinate listing endpoint to get immediate subordinate IDs.
 4. For each subordinate, fetches its Entity Configuration and, if it has its own
    `federation_list_endpoint`, recurses (up to `maxDiscoveryDepth`).
-5. Deduplicates all collected entity IDs.
-6. Persists the ID list in the store with a TTL based on the Trust Anchor's
+5. Deduplicates all collected entities.
+6. Persists the entity payloads in the store with a TTL based on the Trust Anchor's
    expiry and the configured `maxCacheDuration`.
 
+If you only need the list of entity IDs without their payloads, use the convenience method:
+
+```php
+$entityIds = $federationTools->federationDiscovery()
+    ->discoverEntityIds($trustAnchorId);
+```
+
 ### Applying Filters During Discovery
 
 You can pass filter parameters (e.g. `entity_type`) to the subordinate listing
 endpoint:
 
 ```php
-$entityIds = $federationTools->federationDiscovery()
-    ->discoverEntities(
+$entities = $federationTools->federationDiscovery()
+    ->discover(
         $trustAnchorId,
         filters: ['entity_type' => 'openid_relying_party'],
     );
 ```
 
-### Discovering and Fetching Entity Configurations
-
-The convenience method `discoverAndFetch()` performs discovery and then fetches
-the Entity Configuration for each discovered entity:
-
-```php
-try {
-    // Returns array<string, EntityStatement> keyed by entity ID.
-    $entities = $federationTools->federationDiscovery()
-        ->discoverAndFetch($trustAnchorId);
-
-    foreach ($entities as $entityId => $entityStatement) {
-        $metadata = $entityStatement->getMetadata();
-        // ...
-    }
-} catch (\Throwable $exception) {
-    $logger->error('Discovery failed: ' . $exception->getMessage());
-}
-```
-
-> **Note**: Entity Configurations are fetched through the existing
-> `EntityStatementFetcher`, which caches JWS at the network level. If a cached
-> configuration has expired, a fresh one is fetched automatically.
-
 ### Periodic Refresh (Cron / Background Jobs)
 
-Use the `forceRefresh` parameter to clear the stored entity ID list and
+Use the `forceRefresh` parameter to clear the stored entities and
 re-traverse the federation. This is the intended pattern for cron or background
 refresh jobs:
 
 ```php
 // In a scheduled task / cron job:
 $federationTools->federationDiscovery()
-    ->discoverAndFetch($trustAnchorId, forceRefresh: true);
+    ->discover($trustAnchorId, forceRefresh: true);
 ```
 
 When `forceRefresh` is `true`:
 
 - The full federation traversal is re-executed.
-- The new entity ID list is stored.
+- The new entity payload map is stored.
 - Entity Configurations that haven't expired in the JWS cache are served from
   cache; only stale or new ones trigger network requests.
 
@@ -309,7 +294,7 @@ use SimpleSAML\OpenID\Federation\EntityCollection;
 
 // Prepare a collection from discovery or any other source.
 $entities = $federationTools->federationDiscovery()
-    ->discoverAndFetch($trustAnchorId);
+    ->discover($trustAnchorId);
 $collection = new EntityCollection($entities);
 
 // Filter by entity type and text query.
@@ -321,7 +306,7 @@ $filtered = $federationTools->entityCollectionFilter()->filter(
     ],
 );
 
-// $filtered is array<string, EntityStatement> keyed by entity ID.
+// $filtered is array<string, array<string, mixed>> keyed by entity ID.
 ```
 
 #### EntityCollectionSorter
@@ -333,7 +318,7 @@ Sorts entities by a metadata claim value:
 
 // Sort by display_name under the federation_entity metadata.
 $sorted = $federationTools->entityCollectionSorter()->sortByMetadataClaim(
-    $filtered, // array<string, EntityStatement>
+    $filtered, // array<string, array<string, mixed>>
     ['federation_entity', 'display_name'],
     'asc',
 );
@@ -356,7 +341,7 @@ Slices a pre-sorted result set into a page with an opaque cursor:
 /** @var \SimpleSAML\OpenID\Federation $federationTools */
 
 $paginated = $federationTools->entityCollectionPaginator()->paginate(
-    $sorted, // Pre-sorted array<string, EntityStatement|EntityCollectionEntry>
+    $sorted, // Pre-sorted array<string, array<string, mixed>|EntityCollectionEntry>
     20,      // Limit (page size)
     null,    // Cursor from a previous response's 'next' value, or null
 );

src/Federation/EntityCollection.php

@@ -7,7 +7,7 @@
 class EntityCollection
 {
     /**
-     * @param array<string, \SimpleSAML\OpenID\Federation\EntityStatement> $entities  Keyed by entity ID
+     * @param array<string, array<string, mixed>> $entities  Keyed by entity ID, value is JWT payload
      */
     public function __construct(
         protected readonly array $entities,
@@ -16,7 +16,7 @@ public function __construct(
 
 
     /**
-     * @return array<string, \SimpleSAML\OpenID\Federation\EntityStatement>
+     * @return array<string, array<string, mixed>>
      */
     public function all(): array
     {

src/Federation/EntityCollection/CacheEntityCollectionStore.php

@@ -11,7 +11,7 @@
 
 class CacheEntityCollectionStore implements EntityCollectionStoreInterface
 {
-    protected const PREFIX = 'federation_entity_ids';
+    protected const PREFIX = 'federation_entities';
 
 
     public function __construct(
@@ -22,26 +22,26 @@ public function __construct(
     }
 
 
-    public function storeEntityIds(string $trustAnchorId, array $entityIds, int $ttl): void
+    public function store(string $trustAnchorId, array $entities, int $ttl): void
     {
         try {
             $this->cacheDecorator->set(
-                $this->helpers->json()->encode($entityIds),
+                $this->helpers->json()->encode($entities),
                 $ttl,
                 self::PREFIX,
                 $trustAnchorId,
             );
         } catch (Throwable $throwable) {
-            $this->logger?->error('Unable to store entity IDs in cache.', [
+            $this->logger?->error('Unable to store entities in cache.', [
                 'trustAnchorId' => $trustAnchorId,
-                'entityIds' => $entityIds,
+                'entities' => $entities,
                 'exception_message' => $throwable->getMessage(),
             ]);
         }
     }
 
 
-    public function getEntityIds(string $trustAnchorId): ?array
+    public function get(string $trustAnchorId): ?array
     {
         try {
             /** @var ?string $cached */
@@ -52,9 +52,15 @@ public function getEntityIds(string $trustAnchorId): ?array
             }
 
             $decoded = $this->helpers->json()->decode($cached);
-            return $this->helpers->type()->ensureArrayWithValuesAsNonEmptyStrings($decoded);
+
+            if (!is_array($decoded)) {
+                return null;
+            }
+
+            /** @var array<string, array<string, mixed>> $decoded */
+            return $decoded;
         } catch (Throwable $throwable) {
-            $this->logger?->error('Unable to retrieve entity IDs from cache.', [
+            $this->logger?->error('Unable to retrieve entities from cache.', [
                 'trustAnchorId' => $trustAnchorId,
                 'exception_message' => $throwable->getMessage(),
             ]);
@@ -63,12 +69,12 @@ public function getEntityIds(string $trustAnchorId): ?array
     }
 
 
-    public function clearEntityIds(string $trustAnchorId): void
+    public function clear(string $trustAnchorId): void
     {
         try {
             $this->cacheDecorator->delete(self::PREFIX, $trustAnchorId);
         } catch (Throwable $throwable) {
-            $this->logger?->error('Unable to clear entity IDs from cache.', [
+            $this->logger?->error('Unable to clear entities from cache.', [
                 'trustAnchorId' => $trustAnchorId,
                 'exception_message' => $throwable->getMessage(),
             ]);

src/Federation/EntityCollection/EntityCollectionFilter.php

@@ -6,7 +6,6 @@
 
 use SimpleSAML\OpenID\Codebooks\ClaimsEnum;
 use SimpleSAML\OpenID\Federation\EntityCollection;
-use SimpleSAML\OpenID\Federation\EntityStatement;
 use SimpleSAML\OpenID\Helpers;
 
 class EntityCollectionFilter
@@ -24,8 +23,8 @@ public function __construct(
      *   query?: string,
      *   trust_anchor?: string,
      * } $criteria
-     * @return array<string, \SimpleSAML\OpenID\Federation\EntityStatement>  Filtered
-     * entity configurations keyed by entity ID
+     * @return array<string, array<string, mixed>>  Filtered
+     * entity payloads keyed by entity ID
      */
     public function filter(EntityCollection $entityCollection, array $criteria): array
     {
@@ -34,8 +33,12 @@ public function filter(EntityCollection $entityCollection, array $criteria): arr
         // 1. entity_type
         if (isset($criteria['entity_type']) && $criteria['entity_type'] !== []) {
             $types = $criteria['entity_type'];
-            $filtered = array_filter($filtered, function (EntityStatement $statement) use ($types): bool {
-                $metadata = $statement->getMetadata();
+            $filtered = array_filter($filtered, function (array $payload) use ($types): bool {
+                $metadata = $payload[ClaimsEnum::Metadata->value] ?? null;
+                if (!is_array($metadata)) {
+                    return false;
+                }
+
                 foreach ($types as $type) {
                     if (isset($metadata[$type])) {
                         return true;
@@ -49,18 +52,14 @@ public function filter(EntityCollection $entityCollection, array $criteria): arr
         // 2. trust_mark_type
         if (isset($criteria['trust_mark_type'])) {
             $tmType = $criteria['trust_mark_type'];
-            $filtered = array_filter($filtered, function (EntityStatement $statement) use ($tmType): bool {
-                try {
-                    $marks = $statement->getTrustMarks();
-                    if ($marks instanceof \SimpleSAML\OpenID\Federation\Claims\TrustMarksClaimBag) {
-                        foreach ($marks->getAll() as $mark) {
-                            if ($mark->getTrustMarkType() === $tmType) {
-                                return true;
-                            }
+            $filtered = array_filter($filtered, function (array $payload) use ($tmType): bool {
+                $marks = $payload[ClaimsEnum::TrustMarks->value] ?? null;
+                if (is_array($marks)) {
+                    foreach ($marks as $mark) {
+                        if (is_array($mark) && ($mark[ClaimsEnum::TrustMarkType->value] ?? null) === $tmType) {
+                            return true;
                         }
                     }
-                } catch (\Throwable) {
-                    return false;
                 }
 
                 return false;
@@ -70,14 +69,16 @@ public function filter(EntityCollection $entityCollection, array $criteria): arr
         // 3. query
         if (isset($criteria['query']) && $criteria['query'] !== '') {
             $q = mb_strtolower($criteria['query']);
-            $filtered = array_filter($filtered, function (EntityStatement $statement) use ($q): bool {
-                $sub = mb_strtolower($statement->getSubject());
-                if (str_contains($sub, $q)) {
+            $filtered = array_filter($filtered, function (array $payload) use ($q): bool {
+                $sub = is_string($payload[ClaimsEnum::Sub->value] ?? null) ?
+                mb_strtolower($payload[ClaimsEnum::Sub->value]) :
+                '';
+                if ($sub !== '' && str_contains($sub, $q)) {
                     return true;
                 }
 
-                $metadata = $statement->getMetadata();
-                if ($metadata === null) {
+                $metadata = $payload[ClaimsEnum::Metadata->value] ?? null;
+                if (!is_array($metadata)) {
                     return false;
                 }
 
@@ -111,11 +112,11 @@ public function filter(EntityCollection $entityCollection, array $criteria): arr
         // filter on the authority hint if possible.
         if (isset($criteria['trust_anchor'])) {
             $ta = $criteria['trust_anchor'];
-            $filtered = array_filter($filtered, function (EntityStatement $statement) use ($ta): bool {
+            $filtered = array_filter($filtered, function (array $payload) use ($ta): bool {
                 // In a top-down traversal, everything is subordinate to the TA we started with.
                 // If the collection contains multiple TAs, we would check authority_hints.
                 $hints = $this->helpers->arr()->getNestedValue(
-                    $statement->getPayload(),
+                    $payload,
                     ClaimsEnum::AuthorityHints->value,
                 );
                 if (is_array($hints)) {