[Security] Add ability for voters to explain their vote

Author: nicolas-grekas

Authorization/AccessDecision.php

@@ -0,0 +1,56 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Security\Core\Authorization;
+
+use Symfony\Component\Security\Core\Authorization\Voter\Vote;
+use Symfony\Component\Security\Core\Authorization\Voter\VoterInterface;
+
+/**
+ * Contains the access verdict and all the related votes.
+ *
+ * @author Dany Maillard <danymaillard93b@gmail.com>
+ * @author Roman JOLY <eltharin18@outlook.fr>
+ * @author Nicolas Grekas <p@tchwork.com>
+ */
+class AccessDecision
+{
+    /**
+     * @var class-string<AccessDecisionStrategyInterface>|string|null
+     */
+    public ?string $strategy = null;
+
+    public bool $isGranted;
+
+    /**
+     * @var Vote[]
+     */
+    public array $votes = [];
+
+    public function getMessage(): string
+    {
+        $message = $this->isGranted ? 'Access Granted.' : 'Access Denied.';
+        $access = $this->isGranted ? VoterInterface::ACCESS_GRANTED : VoterInterface::ACCESS_DENIED;
+
+        if ($this->votes) {
+            foreach ($this->votes as $vote) {
+                if ($vote->result !== $access) {
+                    continue;
+                }
+                foreach ($vote->reasons as $reason) {
+                    $message .= ' '.$reason;
+                }
+            }
+        }
+
+        return $message;
+    }
+}

Authorization/AccessDecisionManager.php

@@ -15,6 +15,8 @@
 use Symfony\Component\Security\Core\Authorization\Strategy\AccessDecisionStrategyInterface;
 use Symfony\Component\Security\Core\Authorization\Strategy\AffirmativeStrategy;
 use Symfony\Component\Security\Core\Authorization\Voter\CacheableVoterInterface;
+use Symfony\Component\Security\Core\Authorization\Voter\TraceableVoter;
+use Symfony\Component\Security\Core\Authorization\Voter\Vote;
 use Symfony\Component\Security\Core\Authorization\Voter\VoterInterface;
 use Symfony\Component\Security\Core\Exception\InvalidArgumentException;
 
@@ -35,6 +37,7 @@ final class AccessDecisionManager implements AccessDecisionManagerInterface
     private array $votersCacheAttributes = [];
     private array $votersCacheObject = [];
     private AccessDecisionStrategyInterface $strategy;
+    private array $accessDecisionStack = [];
 
     /**
      * @param iterable<mixed, VoterInterface> $voters An array or an iterator of VoterInterface instances
@@ -49,35 +52,56 @@ public function __construct(
     /**
      * @param bool $allowMultipleAttributes Whether to allow passing multiple values to the $attributes array
      */
-    public function decide(TokenInterface $token, array $attributes, mixed $object = null, bool $allowMultipleAttributes = false): bool
+    public function decide(TokenInterface $token, array $attributes, mixed $object = null, bool|AccessDecision|null $accessDecision = null, bool $allowMultipleAttributes = false): bool
     {
+        if (\is_bool($accessDecision)) {
+            $allowMultipleAttributes = $accessDecision;
+            $accessDecision = null;
+        }
+
         // Special case for AccessListener, do not remove the right side of the condition before 6.0
         if (\count($attributes) > 1 && !$allowMultipleAttributes) {
             throw new InvalidArgumentException(\sprintf('Passing more than one Security attribute to "%s()" is not supported.', __METHOD__));
         }
 
-        return $this->strategy->decide(
-            $this->collectResults($token, $attributes, $object)
-        );
+        $accessDecision ??= end($this->accessDecisionStack) ?: new AccessDecision();
+        $this->accessDecisionStack[] = $accessDecision;
+
+        $accessDecision->strategy = $this->strategy instanceof \Stringable ? $this->strategy : get_debug_type($this->strategy);
+
+        try {
+            return $accessDecision->isGranted = $this->strategy->decide(
+                $this->collectResults($token, $attributes, $object, $accessDecision)
+            );
+        } finally {
+            array_pop($this->accessDecisionStack);
+        }
     }
 
     /**
-     * @return \Traversable<int, int>
+     * @return \Traversable<int, VoterInterface::ACCESS_*>
      */
-    private function collectResults(TokenInterface $token, array $attributes, mixed $object): \Traversable
+    private function collectResults(TokenInterface $token, array $attributes, mixed $object, AccessDecision $accessDecision): \Traversable
     {
         foreach ($this->getVoters($attributes, $object) as $voter) {
-            $result = $voter->vote($token, $object, $attributes);
+            $vote = new Vote();
+            $result = $voter->vote($token, $object, $attributes, $vote);
+
             if (!\is_int($result) || !(self::VALID_VOTES[$result] ?? false)) {
                 throw new \LogicException(\sprintf('"%s::vote()" must return one of "%s" constants ("ACCESS_GRANTED", "ACCESS_DENIED" or "ACCESS_ABSTAIN"), "%s" returned.', get_debug_type($voter), VoterInterface::class, var_export($result, true)));
             }
 
+            $voter = $voter instanceof TraceableVoter ? $voter->getDecoratedVoter() : $voter;
+            $vote->voter = $voter instanceof \Stringable ? $voter : get_debug_type($voter);
+            $vote->result = $result;
+            $accessDecision->votes[] = $vote;
+
             yield $result;
         }
     }
 
     /**
-     * @return iterable<mixed, VoterInterface>
+     * @return iterable<int, VoterInterface>
      */
     private function getVoters(array $attributes, $object = null): iterable
     {

Authorization/AccessDecisionManagerInterface.php

@@ -23,8 +23,9 @@ interface AccessDecisionManagerInterface
     /**
      * Decides whether the access is possible or not.
      *
-     * @param array $attributes An array of attributes associated with the method being invoked
-     * @param mixed $object     The object to secure
+     * @param array               $attributes     An array of attributes associated with the method being invoked
+     * @param mixed               $object         The object to secure
+     * @param AccessDecision|null $accessDecision Should be used to explain the decision
      */
-    public function decide(TokenInterface $token, array $attributes, mixed $object = null): bool;
+    public function decide(TokenInterface $token, array $attributes, mixed $object = null/* , ?AccessDecision $accessDecision = null */): bool;
 }

Authorization/AuthorizationChecker.php

@@ -24,20 +24,28 @@
  */
 class AuthorizationChecker implements AuthorizationCheckerInterface
 {
+    private array $accessDecisionStack = [];
+
     public function __construct(
         private TokenStorageInterface $tokenStorage,
         private AccessDecisionManagerInterface $accessDecisionManager,
     ) {
     }
 
-    final public function isGranted(mixed $attribute, mixed $subject = null): bool
+    final public function isGranted(mixed $attribute, mixed $subject = null, ?AccessDecision $accessDecision = null): bool
     {
         $token = $this->tokenStorage->getToken();
 
         if (!$token || !$token->getUser()) {
             $token = new NullToken();
         }
+        $accessDecision ??= end($this->accessDecisionStack) ?: new AccessDecision();
+        $this->accessDecisionStack[] = $accessDecision;
 
-        return $this->accessDecisionManager->decide($token, [$attribute], $subject);
+        try {
+            return $accessDecision->isGranted = $this->accessDecisionManager->decide($token, [$attribute], $subject, $accessDecision);
+        } finally {
+            array_pop($this->accessDecisionStack);
+        }
     }
 }

Authorization/AuthorizationCheckerInterface.php

@@ -21,7 +21,8 @@ interface AuthorizationCheckerInterface
     /**
      * Checks if the attribute is granted against the current authentication token and optionally supplied subject.
      *
-     * @param mixed $attribute A single attribute to vote on (can be of any type, string and instance of Expression are supported by the core)
+     * @param mixed               $attribute      A single attribute to vote on (can be of any type, string and instance of Expression are supported by the core)
+     * @param AccessDecision|null $accessDecision Should be used to explain the decision
      */
-    public function isGranted(mixed $attribute, mixed $subject = null): bool;
+    public function isGranted(mixed $attribute, mixed $subject = null/* , ?AccessDecision $accessDecision = null */): bool;
 }

Authorization/TraceableAccessDecisionManager.php

@@ -12,7 +12,6 @@
 namespace Symfony\Component\Security\Core\Authorization;
 
 use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
-use Symfony\Component\Security\Core\Authorization\Strategy\AccessDecisionStrategyInterface;
 use Symfony\Component\Security\Core\Authorization\Voter\VoterInterface;
 
 /**
@@ -25,77 +24,68 @@
  */
 class TraceableAccessDecisionManager implements AccessDecisionManagerInterface
 {
-    private ?AccessDecisionStrategyInterface $strategy = null;
-    /** @var iterable<mixed, VoterInterface> */
-    private iterable $voters = [];
+    private ?string $strategy = null;
+    /** @var array<VoterInterface> */
+    private array $voters = [];
     private array $decisionLog = []; // All decision logs
     private array $currentLog = [];  // Logs being filled in
+    private array $accessDecisionStack = [];
 
     public function __construct(
         private AccessDecisionManagerInterface $manager,
     ) {
-        // The strategy and voters are stored in a private properties of the decorated service
-        if (property_exists($manager, 'strategy')) {
-            $reflection = new \ReflectionProperty($manager::class, 'strategy');
-            $this->strategy = $reflection->getValue($manager);
-        }
-        if (property_exists($manager, 'voters')) {
-            $reflection = new \ReflectionProperty($manager::class, 'voters');
-            $this->voters = $reflection->getValue($manager);
-        }
     }
 
-    public function decide(TokenInterface $token, array $attributes, mixed $object = null, bool $allowMultipleAttributes = false): bool
+    public function decide(TokenInterface $token, array $attributes, mixed $object = null, bool|AccessDecision|null $accessDecision = null, bool $allowMultipleAttributes = false): bool
     {
-        $currentDecisionLog = [
+        if (\is_bool($accessDecision)) {
+            $allowMultipleAttributes = $accessDecision;
+            $accessDecision = null;
+        }
+
+        // Using a stack since decide can be called by voters
+        $this->currentLog[] = [
             'attributes' => $attributes,
             'object' => $object,
             'voterDetails' => [],
         ];
 
-        $this->currentLog[] = &$currentDecisionLog;
-
-        $result = $this->manager->decide($token, $attributes, $object, $allowMultipleAttributes);
-
-        $currentDecisionLog['result'] = $result;
-
-        $this->decisionLog[] = array_pop($this->currentLog); // Using a stack since decide can be called by voters
-
-        return $result;
+        $accessDecision ??= end($this->accessDecisionStack) ?: new AccessDecision();
+        $this->accessDecisionStack[] = $accessDecision;
+
+        try {
+            return $accessDecision->isGranted = $this->manager->decide($token, $attributes, $object, $accessDecision);
+        } finally {
+            $this->strategy = $accessDecision->strategy;
+            $currentLog = array_pop($this->currentLog);
+            if (isset($accessDecision->isGranted)) {
+                $currentLog['result'] = $accessDecision->isGranted;
+            }
+            $this->decisionLog[] = $currentLog;
+        }
     }
 
-    /**
-     * Adds voter vote and class to the voter details.
-     *
-     * @param array $attributes attributes used for the vote
-     * @param int   $vote       vote of the voter
-     */
-    public function addVoterVote(VoterInterface $voter, array $attributes, int $vote): void
+    public function addVoterVote(VoterInterface $voter, array $attributes, int $vote, array $reasons = []): void
     {
         $currentLogIndex = \count($this->currentLog) - 1;
         $this->currentLog[$currentLogIndex]['voterDetails'][] = [
             'voter' => $voter,
             'attributes' => $attributes,
             'vote' => $vote,
+            'reasons' => $reasons,
         ];
+        $this->voters[$voter::class] = $voter;
     }
 
     public function getStrategy(): string
     {
-        if (null === $this->strategy) {
-            return '-';
-        }
-        if ($this->strategy instanceof \Stringable) {
-            return (string) $this->strategy;
-        }
-
-        return get_debug_type($this->strategy);
+        return $this->strategy ?? '-';
     }
 
     /**
-     * @return iterable<mixed, VoterInterface>
+     * @return array<VoterInterface>
      */
-    public function getVoters(): iterable
+    public function getVoters(): array
     {
         return $this->voters;
     }
@@ -104,4 +94,11 @@ public function getDecisionLog(): array
     {
         return $this->decisionLog;
     }
+
+    public function reset(): void
+    {
+        $this->strategy = null;
+        $this->voters = [];
+        $this->decisionLog = [];
+    }
 }

Authorization/UserAuthorizationChecker.php

@@ -24,8 +24,8 @@ public function __construct(
     ) {
     }
 
-    public function isGrantedForUser(UserInterface $user, mixed $attribute, mixed $subject = null): bool
+    public function isGrantedForUser(UserInterface $user, mixed $attribute, mixed $subject = null, ?AccessDecision $accessDecision = null): bool
     {
-        return $this->accessDecisionManager->decide(new UserAuthorizationCheckerToken($user), [$attribute], $subject);
+        return $this->accessDecisionManager->decide(new UserAuthorizationCheckerToken($user), [$attribute], $subject, $accessDecision);
     }
 }

Authorization/UserAuthorizationCheckerInterface.php

@@ -23,7 +23,8 @@ interface UserAuthorizationCheckerInterface
     /**
      * Checks if the attribute is granted against the user and optionally supplied subject.
      *
-     * @param mixed $attribute A single attribute to vote on (can be of any type, string and instance of Expression are supported by the core)
+     * @param mixed               $attribute      A single attribute to vote on (can be of any type, string and instance of Expression are supported by the core)
+     * @param AccessDecision|null $accessDecision Should be used to explain the decision
      */
-    public function isGrantedForUser(UserInterface $user, mixed $attribute, mixed $subject = null): bool;
+    public function isGrantedForUser(UserInterface $user, mixed $attribute, mixed $subject = null, ?AccessDecision $accessDecision = null): bool;
 }