refactor: make PolicyFor's resource optional and rename to Policy

Author: innocenzi

docs/2-features/04-authentication.md

@@ -236,17 +236,23 @@ This paradigm is known as [policy-based access control](https://en.wikipedia.org
 
 ### Defining policies
 
-To create a policy, you may define a method in any class and annotate it with the {b`#[Tempest\Auth\AccessControl\PolicyFor]`} attribute. Typically, this is done in a dedicated policy class.
+To create a policy, you may define a method in any class and annotate it with the {b`#[Tempest\Auth\AccessControl\Policy]`} attribute. Typically, this is done in a dedicated policy class.
 
-The attribute expects the class name of the resource as its first parameter, and an optional action name as the second parameter. If the action name is not provided, the kebab-cased method name is used instead.
+The attribute expects the class name of the resource as its first parameter, and the action name as the second parameter. If the resource is not specified, it will be inferred by the method's first parameter. Similarly, if the action name is not provided, the kebab-cased method name is used instead.
 
 ```php app/PostPolicy.php
-use Tempest\Auth\AccessControl\PolicyFor;
+use Tempest\Auth\AccessControl\Policy;
 use Tempest\Auth\AccessControl\AccessDecision;
 
 final class PostPolicy
 {
-    #[PolicyFor(Post::class)]
+    #[Policy(Post::class)]
+    public function create(): bool
+    {
+        return true;
+    }
+
+    #[Policy]
     public function view(Post $post): bool
     {
         if (! $post->published) {
@@ -256,7 +262,7 @@ final class PostPolicy
         return true;
     }
 
-    #[PolicyFor(Post::class, action: ['edit', 'update'])]
+    #[Policy(action: ['edit', 'update'])]
     public function edit(Post $post, ?User $user): bool
     {
         if ($user === null) {

…ges/auth/src/AccessControl/PolicyFor.php …ckages/auth/src/AccessControl/Policy.phppackages/auth/src/AccessControl/PolicyFor.php renamed to packages/auth/src/AccessControl/Policy.php packages/auth/src/AccessControl/PolicyFor.php renamed to packages/auth/src/AccessControl/Policy.php

@@ -7,17 +7,17 @@
 
 /**
  * When applied on a method, this attribute indicates that the method is a policy method for the specified resource.
- * The method must accept an action as its first parameter, the resource instance as its second, and the subject as its last.
+ * The method must accept the resource instance as its first parameter and the subject as its second one.
  */
 #[Attribute(Attribute::TARGET_METHOD)]
-final class PolicyFor
+final class Policy
 {
     /**
-     * @param class-string $resource A resource class that this policy applies to.
+     * @param class-string $resource A resource class that this policy applies to. If not specified, it will be inferred by the method's first argument.
      * @param null|UnitEnum|string|iterable<string|UnitEnum|null> $action An optional action that this policy applies to. If null, the policy applies to all actions for the resource.
      */
     public function __construct(
-        public string $resource,
+        public ?string $resource = null,
         public null|UnitEnum|string|iterable $action = null,
     ) {}
 }

packages/auth/src/AccessControl/PolicyDiscovery.php

@@ -20,7 +20,7 @@ public function __construct(
     public function discover(DiscoveryLocation $location, ClassReflector $class): void
     {
         foreach ($class->getPublicMethods() as $method) {
-            $policy = $method->getAttribute(PolicyFor::class);
+            $policy = $method->getAttribute(Policy::class);
 
             if (! $policy) {
                 continue;

packages/auth/src/AuthConfig.php

@@ -5,8 +5,10 @@
 namespace Tempest\Auth;
 
 use BackedEnum;
-use Tempest\Auth\AccessControl\PolicyFor;
+use Tempest\Auth\AccessControl\Policy;
 use Tempest\Auth\Authentication\CanAuthenticate;
+use Tempest\Auth\Exceptions\PolicyIsInvalid;
+use Tempest\Auth\Exceptions\PolicyMethodIsInvalid;
 use Tempest\Reflection\MethodReflector;
 use Tempest\Support\Arr;
 use Tempest\Support\Str;
@@ -23,8 +25,18 @@ public function __construct(
         public array $policies = [],
     ) {}
 
-    public function registerPolicy(MethodReflector $handler, PolicyFor $policy): self
+    public function registerPolicy(MethodReflector $handler, Policy $policy): self
     {
+        if (! $policy->resource) {
+            $policy->resource = $handler->getParameter(key: 0)?->getType()?->getName();
+        }
+
+        if (! $policy->resource) {
+            throw PolicyIsInvalid::resourceCouldNotBeInferred(
+                policyName: sprintf('%s::%s', $handler->getDeclaringClass()->getName(), $handler->getName()),
+            );
+        }
+
         $this->policies[$policy->resource] ??= [];
 
         if ($policy->action === null) {

packages/auth/src/Exceptions/PolicyIsInvalid.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Tempest\Auth\Exceptions;
+
+use Exception;
+
+final class PolicyIsInvalid extends Exception implements AuthenticationException
+{
+    public static function resourceCouldNotBeInferred(string $policyName): self
+    {
+        return new self(sprintf(
+            "The resource for policy `%s` could not be inferred because it is missing from the method's parameters. You must specify it in the attribute instead.",
+            $policyName,
+        ));
+    }
+}

tests/Integration/Auth/AccessControl/AccessControlTest.php

@@ -7,7 +7,7 @@
 use PHPUnit\Framework\Attributes\Test;
 use Tempest\Auth\AccessControl\AccessControl;
 use Tempest\Auth\AccessControl\AccessDecision;
-use Tempest\Auth\AccessControl\PolicyFor;
+use Tempest\Auth\AccessControl\Policy;
 use Tempest\Auth\Authentication\Authenticator;
 use Tempest\Auth\Authentication\AuthenticatorInitializer;
 use Tempest\Auth\Authentication\CanAuthenticate;
@@ -125,13 +125,13 @@ public function __construct(
 
 final class ArticlePolicy
 {
-    #[PolicyFor(Article::class, action: 'view')]
+    #[Policy(Article::class, action: 'view')]
     public function view(): bool
     {
         return true;
     }
 
-    #[PolicyFor(Article::class, action: 'edit')]
+    #[Policy(Article::class, action: 'edit')]
     public function edit(Article $article, ?TestUser $subject): bool
     {
         if ($subject === null) {
@@ -141,7 +141,7 @@ public function edit(Article $article, ?TestUser $subject): bool
         return $subject->role === 'admin' || $subject->role === 'author' && $article->authorId === $subject->id->value;
     }
 
-    #[PolicyFor(Article::class, action: 'delete')]
+    #[Policy(Article::class, action: 'delete')]
     public function delete(Article $article, ?TestUser $subject): bool|AccessDecision
     {
         if ($subject === null) {
@@ -159,7 +159,7 @@ public function delete(Article $article, ?TestUser $subject): bool|AccessDecisio
         return AccessDecision::denied('Insufficient permissions for this action');
     }
 
-    #[PolicyFor(Article::class, action: 'manage')]
+    #[Policy(Article::class, action: 'manage')]
     public function manage(?Article $_, ?TestUser $subject): bool
     {
         return $subject?->role === 'admin';
@@ -168,13 +168,13 @@ public function manage(?Article $_, ?TestUser $subject): bool
 
 final class CommentPolicy
 {
-    #[PolicyFor(ArticleComment::class, action: 'view')]
+    #[Policy(ArticleComment::class, action: 'view')]
     public function view(): bool
     {
         return true;
     }
 
-    #[PolicyFor(ArticleComment::class, action: 'edit')]
+    #[Policy(ArticleComment::class, action: 'edit')]
     public function edit(ArticleComment $comment, ?TestUser $subject): bool
     {
         if ($subject === null) {
@@ -184,7 +184,7 @@ public function edit(ArticleComment $comment, ?TestUser $subject): bool
         return $comment->authorId === $subject->id->value || $subject->role === 'admin';
     }
 
-    #[PolicyFor(ArticleComment::class, action: 'delete')]
+    #[Policy(ArticleComment::class, action: 'delete')]
     public function delete(ArticleComment $_, ?TestUser $subject): bool
     {
         return $subject?->role === 'admin';

tests/Integration/Auth/AccessControl/HasPolicyTests.php

@@ -2,7 +2,7 @@
 
 namespace Tests\Tempest\Integration\Auth\AccessControl;
 
-use Tempest\Auth\AccessControl\PolicyFor;
+use Tempest\Auth\AccessControl\Policy;
 use Tempest\Auth\AuthConfig;
 use Tempest\Reflection\ClassReflector;
 
@@ -16,7 +16,7 @@ public function registerPoliciesFrom(string|object $class): self
         $config = $this->container->get(AuthConfig::class);
 
         foreach (new ClassReflector($class)->getPublicMethods() as $method) {
-            if ($policy = $method->getAttribute(PolicyFor::class)) {
+            if ($policy = $method->getAttribute(Policy::class)) {
                 $config->registerPolicy($method, $policy);
             }
         }

tests/Integration/Auth/AccessControl/PolicyBasedAccessControlTest.php

@@ -7,14 +7,15 @@
 use PHPUnit\Framework\Attributes\Test;
 use Tempest\Auth\AccessControl\AccessControl;
 use Tempest\Auth\AccessControl\AccessDecision;
+use Tempest\Auth\AccessControl\Policy;
 use Tempest\Auth\AccessControl\PolicyBasedAccessControl;
-use Tempest\Auth\AccessControl\PolicyFor;
 use Tempest\Auth\AuthConfig;
 use Tempest\Auth\Authentication\Authenticator;
 use Tempest\Auth\Authentication\AuthenticatorInitializer;
 use Tempest\Auth\Authentication\CanAuthenticate;
 use Tempest\Auth\Exceptions\AccessWasDenied;
 use Tempest\Auth\Exceptions\NoPolicyWereFoundForResource;
+use Tempest\Auth\Exceptions\PolicyIsInvalid;
 use Tempest\Auth\Exceptions\PolicyMethodIsInvalid;
 use Tempest\Database\PrimaryKey;
 use Tests\Tempest\Integration\Auth\Fixtures\InMemoryAuthenticatorInitializer;
@@ -271,6 +272,17 @@ public function throws_exception_when_policy_resource_parameter_type_is_invalid(
         $accessControl->isGranted('view', $post, $user);
     }
 
+    #[Test]
+    public function throws_exception_when_policy_resource_is_not_specified_anywhere(): void
+    {
+        $this->expectException(PolicyIsInvalid::class);
+        $this->expectExceptionMessageMatches(
+            "/The resource for policy `.*::missingResourceType` could not be inferred because it is missing from the method's parameters\. You must specify it in the attribute instead\./",
+        );
+
+        $this->registerPoliciesFrom(MissingResourceTypePolicy::class);
+    }
+
     #[Test]
     public function throws_exception_when_policy_subject_parameter_type_is_invalid(): void
     {
@@ -358,19 +370,19 @@ public function __construct(
 
 final class PostPolicy
 {
-    #[PolicyFor(Post::class, action: 'view')]
+    #[Policy(Post::class, action: 'view')]
     public function view(): bool
     {
         return true;
     }
 
-    #[PolicyFor(Post::class, action: PostAction::VIEW)]
+    #[Policy(Post::class, action: PostAction::VIEW)]
     public function viewEnum(): bool
     {
         return true;
     }
 
-    #[PolicyFor(Post::class, action: 'edit')]
+    #[Policy(action: 'edit')]
     public function edit(?Post $resource, ?User $subject): bool
     {
         if (! ($subject instanceof User)) {
@@ -380,7 +392,7 @@ public function edit(?Post $resource, ?User $subject): bool
         return $resource?->authorId === $subject->id->value;
     }
 
-    #[PolicyFor(Post::class, action: PostAction::EDIT)]
+    #[Policy(action: PostAction::EDIT)]
     public function editEnum(?Post $resource, ?User $subject): bool
     {
         if (! ($subject instanceof User)) {
@@ -390,7 +402,7 @@ public function editEnum(?Post $resource, ?User $subject): bool
         return $resource?->authorId === $subject->id->value;
     }
 
-    #[PolicyFor(Post::class, action: 'delete')]
+    #[Policy(action: 'delete')]
     public function delete(?Post $resource, ?User $subject): bool|AccessDecision
     {
         if (! ($subject instanceof User)) {
@@ -402,7 +414,7 @@ public function delete(?Post $resource, ?User $subject): bool|AccessDecision
             : AccessDecision::denied('Only the author can delete their post');
     }
 
-    #[PolicyFor(Post::class, action: PostAction::DELETE)]
+    #[Policy(action: PostAction::DELETE)]
     public function deleteEnum(?Post $resource, ?User $subject): bool|AccessDecision
     {
         if (! ($subject instanceof User)) {
@@ -414,7 +426,7 @@ public function deleteEnum(?Post $resource, ?User $subject): bool|AccessDecision
             : AccessDecision::denied('Only the author can delete their post');
     }
 
-    #[PolicyFor(Post::class, action: 'create')]
+    #[Policy(Post::class, action: 'create')]
     public function create(): bool
     {
         return true;
@@ -423,7 +435,7 @@ public function create(): bool
 
 final class UserPolicy
 {
-    #[PolicyFor(User::class, action: 'manage')]
+    #[Policy(action: 'manage')]
     public function manage(?User $resource, ?User $subject): bool
     {
         if (! ($subject instanceof User)) {
@@ -446,7 +458,7 @@ public function __construct(
 
 final class MultiActionPolicy
 {
-    #[PolicyFor(Document::class, action: ['read', 'download'])]
+    #[Policy(action: ['read', 'download'])]
     public function readAndDownload(?Document $resource, ?User $subject): bool
     {
         if (! ($subject instanceof User)) {
@@ -459,7 +471,7 @@ public function readAndDownload(?Document $resource, ?User $subject): bool
 
 final class MultiAuthenticatablePolicy
 {
-    #[PolicyFor(Document::class)]
+    #[Policy]
     public function view(?Document $_resource, null|User|ServiceAccount $subject): bool
     {
         if (! ($subject instanceof CanAuthenticate)) {
@@ -470,10 +482,20 @@ public function view(?Document $_resource, null|User|ServiceAccount $subject): b
     }
 }
 
+final class MissingResourceTypePolicy
+{
+    // no resource is specified
+    #[Policy]
+    public function missingResourceType(): bool
+    {
+        return true;
+    }
+}
+
 final class InvalidResourceTypePolicy
 {
     // expects a User as resource but will receive a Post
-    #[PolicyFor(Post::class, action: 'view')]
+    #[Policy(Post::class, action: 'view')]
     public function invalidResourceType(User $_resource, ?User $_subject): bool
     {
         return true;
@@ -483,7 +505,7 @@ public function invalidResourceType(User $_resource, ?User $_subject): bool
 final class InvalidSubjectTypePolicy
 {
     // expects a Document as subject but will receive a User
-    #[PolicyFor(Post::class, action: 'edit')]
+    #[Policy(Post::class, action: 'edit')]
     public function invalidSubjectType(?Post $_resource, Document $_subject): bool
     {
         return true;
@@ -492,7 +514,7 @@ public function invalidSubjectType(?Post $_resource, Document $_subject): bool
 
 final class PolicyWithoutActionNames
 {
-    #[PolicyFor(Post::class)]
+    #[Policy(Post::class)]
     public function canMarkAsPublished(?Post $post, ?User $user): bool
     {
         if ($user === null) {
@@ -502,7 +524,7 @@ public function canMarkAsPublished(?Post $post, ?User $user): bool
         return $post?->authorId === $user->id->value;
     }
 
-    #[PolicyFor(Post::class)]
+    #[Policy(Post::class)]
     public function approveForPublication(?Post $post, ?User $user): bool
     {
         if ($user === null) {