refactor(auth): make wildcard grants descendants-only

Signed-off-by: memleakd <121398829+memleakd@users.noreply.github.com>

Author: memleakd

docs/quick_start_guide/using_authorization.md

@@ -56,9 +56,9 @@ public array $matrix = [
 ];
 ```
 
-A trailing `*` wildcard on a dotted scope matches the scope itself and all child permission segments. For example, `forum.posts.*` matches `forum.posts`, `forum.posts.create`, and `forum.posts.comments.delete`.
+A trailing `*` wildcard matches descendant permission segments only. For example, `forum.posts.*` matches `forum.posts.create` and `forum.posts.comments.delete`, but not `forum.posts`.
 When `*` appears between segments, it matches exactly one segment. For example, `forum.*.create` matches `forum.posts.create`.
-Parent matching applies to dotted scopes like `forum.posts`, not root labels like `forum`. The first segment cannot be `*`, and a standalone `*` permission does not grant all permissions.
+The first segment cannot be `*`, and a standalone `*` permission does not grant all permissions.
 
 ## Assign Permissions to a User
 

docs/references/authorization.md

@@ -74,7 +74,7 @@ public array $matrix = [
 ```
 
 You can use `*` as a wildcard segment to allow permissions under a scope. A wildcard matches one full segment.
-When the wildcard is trailing on a dotted scope, it also grants the parent scope itself and all descendant permissions.
+When the wildcard is trailing, it grants descendant permissions only.
 The first segment cannot be `*`, and a standalone `*` permission does not grant all permissions.
 
 ```php
@@ -83,11 +83,10 @@ public array $matrix = [
 ];
 ```
 
-For example, `forum.posts.*` matches `forum.posts`, `forum.posts.create`, and `forum.posts.comments.delete`.
+For example, `forum.posts.*` matches `forum.posts.create` and `forum.posts.comments.delete`, but not
+`forum.posts`.
 Wildcards can also appear between segments: `forum.*.create` matches `forum.posts.create` and
 `forum.comments.create`, but does not match `forum.create` or `forum.posts.comments.create`.
-Since `$user->can()` expects dot-separated permissions like `scope.action`, parent matching applies to dotted
-permission scopes like `forum.posts`, not to root labels like `forum`.
 
 Exact child permissions do not grant their parent permission. For example, `forum.posts.create` does not grant
 `forum.posts`.
@@ -96,9 +95,8 @@ Wildcard matching is used by `$user->can()` and `$group->can()` for both user-le
 
 !!! warning
 
-    Wildcard permissions can grant access to the parent scope and to future child permissions added under the
-    same scope. Use broad wildcards like `admin.*` carefully, and prefer literal permissions for highly sensitive
-    access.
+    Wildcard permissions can grant access to future child permissions added under the same scope. Use broad
+    wildcards like `admin.*` carefully, and prefer literal permissions for highly sensitive access.
 
 ## Authorizing Users
 

src/Authorization/PermissionMatcher.php

@@ -52,12 +52,7 @@ private static function matchesWildcardGrant(string $grant, string $permission):
         if (end($grantSegments) === '*') {
             array_pop($grantSegments);
 
-            // Root labels like `admin` are not permission scopes, so `admin.*` should not grant `admin`.
-            if (count($grantSegments) === 1 && count($permissionSegments) === 1) {
-                return false;
-            }
-
-            return count($permissionSegments) >= count($grantSegments)
+            return count($permissionSegments) > count($grantSegments)
                 && self::segmentsMatch($grantSegments, array_slice($permissionSegments, 0, count($grantSegments)));
         }
 

tests/Authorization/AuthorizableTest.php

@@ -317,9 +317,9 @@ public function testCanCascadesToGroupsWithHierarchicalWildcards(): void
         $this->assertTrue($this->user->can('forum.posts.comments.delete'));
         $this->assertTrue($this->user->can('admin.users.create'));
         $this->assertTrue($this->user->can('reports.daily.view'));
-        $this->assertTrue($this->user->can('forum.posts'));
-        $this->assertTrue($this->user->can('reports.daily'));
 
+        $this->assertFalse($this->user->can('forum.posts'));
+        $this->assertFalse($this->user->can('reports.daily'));
         $this->assertFalse($this->user->can('admin.create'));
         $this->assertFalse($this->user->can('admin.users.roles.create'));
         $this->assertFalse($this->user->can('admin.users.delete'));
@@ -335,7 +335,7 @@ public function testCanChecksUserLevelHierarchicalWildcards(): void
 
         $this->assertTrue($this->user->can('forum.posts.create'));
         $this->assertTrue($this->user->can('forum.posts.comments.delete'));
-        $this->assertTrue($this->user->can('forum.posts'));
+        $this->assertFalse($this->user->can('forum.posts'));
         $this->assertFalse($this->user->can('forum.users.create'));
     }
 

tests/Authorization/GroupTest.php

@@ -98,8 +98,8 @@ public function testCanWithHierarchicalWildcards(): void
         $this->assertTrue($group->can('forum.posts.create'));
         $this->assertTrue($group->can('forum.posts.comments.delete'));
         $this->assertTrue($group->can('admin.users.create'));
-        $this->assertTrue($group->can('forum.posts'));
 
+        $this->assertFalse($group->can('forum.posts'));
         $this->assertFalse($group->can('admin.create'));
         $this->assertFalse($group->can('admin.users.roles.create'));
         $this->assertFalse($group->can('admin.users.delete'));

tests/Authorization/PermissionMatcherTest.php

@@ -44,7 +44,7 @@ public static function provideMatches(): iterable
             'trailing wildcard matches child'                              => ['admin.users.create', ['admin.users.*'], true],
             'trailing wildcard matches deeper child'                       => ['admin.users.roles.create', ['admin.users.*'], true],
             'broad trailing wildcard matches child'                        => ['admin.users.create', ['admin.*'], true],
-            'trailing wildcard matches parent'                             => ['admin.users', ['admin.users.*'], true],
+            'trailing wildcard does not match parent'                      => ['admin.users', ['admin.users.*'], false],
             'broad wildcard does not match root permission'                => ['admin', ['admin.*'], false],
             'standalone wildcard does not match child'                     => ['admin.users.create', ['*'], false],
             'leading wildcard does not match child'                        => ['admin.users.create', ['*.users.create'], false],
@@ -54,7 +54,7 @@ public static function provideMatches(): iterable
             'middle wildcard does not match multiple segments'             => ['admin.users.roles.create', ['admin.*.create'], false],
             'middle wildcard does not match no segment'                    => ['admin.create', ['admin.*.create'], false],
             'middle wildcard does not match sibling'                       => ['admin.users.delete', ['admin.*.create'], false],
-            'middle and trailing wildcards match parent'                   => ['admin.users.create', ['admin.*.create.*'], true],
+            'middle and trailing wildcards do not match parent'            => ['admin.users.create', ['admin.*.create.*'], false],
             'middle and trailing wildcards match child'                    => ['admin.users.create.view', ['admin.*.create.*'], true],
             'middle and trailing wildcards do not match multiple segments' => ['admin.users.roles.create', ['admin.*.create.*'], false],
             'middle and trailing wildcards require segment'                => ['admin.create', ['admin.*.create.*'], false],