Updated version and assets for release v23.02.3

Updated selectable elements to be divs instead of buttons since Safari
akwardly does not focus on buttons on click.
Also standardised keyboard handling to our standard nav class.
Also addressed empty tag values showing in results.
For #4139

.env.example.complete

@@ -80,6 +80,9 @@ MAIL_USERNAME=null
 MAIL_PASSWORD=null
 MAIL_ENCRYPTION=null
 
+# Command to use when email is sent via sendmail
+MAIL_SENDMAIL_COMMAND="/usr/sbin/sendmail -bs"
+
 # Cache & Session driver to use
 # Can be 'file', 'database', 'memcached' or 'redis'
 CACHE_DRIVER=file
@@ -263,7 +266,12 @@ OIDC_ISSUER_DISCOVER=false
 OIDC_PUBLIC_KEY=null
 OIDC_AUTH_ENDPOINT=null
 OIDC_TOKEN_ENDPOINT=null
+OIDC_ADDITIONAL_SCOPES=null
 OIDC_DUMP_USER_DETAILS=false
+OIDC_USER_TO_GROUPS=false
+OIDC_GROUPS_CLAIM=groups
+OIDC_REMOVE_FROM_GROUPS=false
+OIDC_EXTERNAL_ID_CLAIM=sub
 
 # Disable default third-party services such as Gravatar and Draw.IO
 # Service-specific options will override this option
@@ -295,7 +303,7 @@ APP_DEFAULT_DARK_MODE=false
 # Page revision limit
 # Number of page revisions to keep in the system before deleting old revisions.
 # If set to 'false' a limit will not be enforced.
-REVISION_LIMIT=50
+REVISION_LIMIT=100
 
 # Recycle Bin Lifetime
 # The number of days that content will remain in the recycle bin before

.github/translators.txt

@@ -56,6 +56,7 @@ Name :: Languages
 @arcoai :: Spanish
 @Jokuna :: Korean
 @smartshogu :: German; German Informal
+@samadha56 :: Persian
 cipi1965 :: Italian
 Mykola Ronik (Mantikor) :: Ukrainian
 furkanoyk :: Turkish
@@ -137,7 +138,7 @@ Xiphoseer :: German
 MerlinSVK (merlinsvk) :: Slovak
 Kauê Sena (kaue.sena.ks) :: Portuguese, Brazilian
 MatthieuParis :: French
-Douradinho :: Portuguese, Brazilian
+Douradinho :: Portuguese, Brazilian; Portuguese
 Gaku Yaguchi (tama11) :: Japanese
 johnroyer :: Chinese Traditional
 jackaaa :: Chinese Traditional
@@ -175,7 +176,7 @@ Alexander Predl (Harveyhase68) :: German
 Rem (Rem9000) :: Dutch
 Michał Stelmach (stelmach-web) :: Polish
 arniom :: French
-REMOVED_USER :: Dutch; Turkish
+REMOVED_USER :: ; French; Dutch; Turkish
 林祖年 (contagion) :: Chinese Traditional
 Siamak Guodarzi (siamakgoudarzi88) :: Persian
 Lis Maestrelo (lismtrl) :: Portuguese, Brazilian
@@ -267,3 +268,55 @@ Filip Antala (AntalaFilip) :: Slovak
 mcgong (GongMingCai) :: Chinese Simplified; Chinese Traditional
 Nanang Setia Budi (sefidananang) :: Indonesian
 Андрей Павлов (andrei.pavlov) :: Russian
+Alex Navarro (alex.n.navarro) :: Portuguese, Brazilian
+Ji-Hyeon Gim (PotatoGim) :: Korean
+Mihai Ochian (soulstorm19) :: Romanian
+HeartCore :: German Informal; German
+simon.pct :: French
+okaeiz :: Persian
+Naoto Ishikawa (na3shkw) :: Japanese
+sdhadi :: Persian
+DerLinkman (derlinkman) :: German; German Informal
+TurnArabic :: Arabic
+Martin Sebek (sebekmartin) :: Czech
+Kuchinashi Hoshikawa (kuchinashi) :: Chinese Simplified
+digilady :: Greek
+Linus (LinusOP) :: Swedish
+Felipe Cardoso (felipecardosoruff) :: Portuguese, Brazilian
+RandomUser0815 :: German Informal; German
+Ismael Mesquita (mesquitoliveira) :: Portuguese, Brazilian
+구인회 (laskdjlaskdj12) :: Korean
+LiZerui (CNLiZerui) :: Chinese Traditional
+Fabrice Boyer (FabriceBoyer) :: French
+mikael (bitcanon) :: Swedish
+Matthias Mai (schnapsidee) :: German; German Informal
+Ufuk Ayyıldız (ufukayyildiz) :: Turkish
+Jan Mitrof (jan.kachlik) :: Czech
+edwardsmirnov :: Russian
+Mr_OSS117 :: French
+shotu :: French
+Cesar_Lopez_Aguillon :: Spanish
+bdewoop :: German
+dina davoudi (dina.davoudi) :: Persian
+Angelos Chouvardas (achouvardas) :: Greek
+rndrss :: Portuguese, Brazilian
+rirac294 :: Russian
+David Furman (thefourCraft) :: Hebrew
+Pafzedog :: French
+Yllelder :: Spanish
+Adrian Ocneanu (aocneanu) :: Romanian
+Eduardo Castanho (EduardoCastanho) :: Portuguese
+VIET NAM VPS (vietnamvps) :: Vietnamese
+m4tthi4s :: French
+toras9000 :: Japanese
+pathab :: German
+MichelSchoon85 :: Dutch
+Jøran Haugli (haugli92) :: Norwegian Bokmal
+Vasileios Kouvelis (VasilisKouvelis) :: Greek
+Dremski :: Bulgarian
+Frédéric SENE (nothingfr) :: French
+bendem :: French
+kostasdizas :: Greek
+Ricardo Schroeder (brownstone666) :: Portuguese, Brazilian
+Eitan MG (EitanMG) :: Hebrew
+Robin Flikkema (RobinFlikkema) :: Dutch

.github/workflows/analyse-php.yml

@@ -1,36 +1,34 @@
-name: phpstan
+name: analyse-php
 
 on: [push, pull_request]
 
 jobs:
   build:
     if: ${{ github.ref != 'refs/heads/l10n_development' }}
-    runs-on: ubuntu-20.04
-    strategy:
-      matrix:
-        php: ['7.4']
+    runs-on: ubuntu-22.04
     steps:
     - uses: actions/checkout@v1
 
     - name: Setup PHP
       uses: shivammathur/setup-php@v2
       with:
-        php-version: ${{ matrix.php }}
+        php-version: 8.1
         extensions: gd, mbstring, json, curl, xml, mysql, ldap
 
     - name: Get Composer Cache Directory
       id: composer-cache
       run: |
-        echo "::set-output name=dir::$(composer config cache-files-dir)"
+        echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
 
     - name: Cache composer packages
-      uses: actions/cache@v1
+      uses: actions/cache@v3
       with:
         path: ${{ steps.composer-cache.outputs.dir }}
-        key: ${{ runner.os }}-composer-${{ matrix.php }}
+        key: ${{ runner.os }}-composer-8.1
+        restore-keys: ${{ runner.os }}-composer-
 
     - name: Install composer dependencies
       run: composer install --prefer-dist --no-interaction --ansi
 
-    - name: Run PHPStan
-      run: php${{ matrix.php }} ./vendor/bin/phpstan analyse --memory-limit=2G
+    - name: Run static analysis check
+      run: composer check-static

.github/workflows/lint-php.yml

@@ -0,0 +1,19 @@
+name: lint-php
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    if: ${{ github.ref != 'refs/heads/l10n_development' }}
+    runs-on: ubuntu-22.04
+    steps:
+    - uses: actions/checkout@v1
+
+    - name: Setup PHP
+      uses: shivammathur/setup-php@v2
+      with:
+        php-version: 8.1
+        tools: phpcs
+
+    - name: Run formatting check
+      run: composer lint

.github/workflows/test-migrations.yml

@@ -5,10 +5,10 @@ on: [push, pull_request]
 jobs:
   build:
     if: ${{ github.ref != 'refs/heads/l10n_development' }}
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     strategy:
       matrix:
-        php: ['7.4', '8.0', '8.1']
+        php: ['8.0', '8.1', '8.2']
     steps:
       - uses: actions/checkout@v1
 
@@ -21,13 +21,14 @@ jobs:
       - name: Get Composer Cache Directory
         id: composer-cache
         run: |
-          echo "::set-output name=dir::$(composer config cache-files-dir)"
+          echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
 
       - name: Cache composer packages
-        uses: actions/cache@v1
+        uses: actions/cache@v3
         with:
           path: ${{ steps.composer-cache.outputs.dir }}
           key: ${{ runner.os }}-composer-${{ matrix.php }}
+          restore-keys: ${{ runner.os }}-composer-
 
       - name: Start MySQL
         run: |

.github/workflows/test-php.yml

@@ -1,14 +1,14 @@
-name: phpunit
+name: test-php
 
 on: [push, pull_request]
 
 jobs:
   build:
     if: ${{ github.ref != 'refs/heads/l10n_development' }}
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     strategy:
       matrix:
-        php: ['7.4', '8.0', '8.1']
+        php: ['8.0', '8.1', '8.2']
     steps:
     - uses: actions/checkout@v1
 
@@ -16,18 +16,19 @@ jobs:
       uses: shivammathur/setup-php@v2
       with:
         php-version: ${{ matrix.php }}
-        extensions: gd, mbstring, json, curl, xml, mysql, ldap
+        extensions: gd, mbstring, json, curl, xml, mysql, ldap, gmp
 
     - name: Get Composer Cache Directory
       id: composer-cache
       run: |
-        echo "::set-output name=dir::$(composer config cache-files-dir)"
+        echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
 
     - name: Cache composer packages
-      uses: actions/cache@v1
+      uses: actions/cache@v3
       with:
         path: ${{ steps.composer-cache.outputs.dir }}
         key: ${{ runner.os }}-composer-${{ matrix.php }}
+        restore-keys: ${{ runner.os }}-composer-
 
     - name: Start Database
       run: |
@@ -48,5 +49,5 @@ jobs:
         php${{ matrix.php }} artisan migrate --force -n --database=mysql_testing
         php${{ matrix.php }} artisan db:seed --force -n --class=DummyContentSeeder --database=mysql_testing
 
-    - name: phpunit
+    - name: Run PHP tests
       run: php${{ matrix.php }} ./vendor/bin/phpunit

.gitignore

@@ -11,6 +11,7 @@ yarn-error.log
 /public/js/*.map
 /public/bower
 /public/build/
+/public/favicon.ico
 /storage/images
 _ide_helper.php
 /storage/debugbar

LICENSE

@@ -1,7 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015-present, Dan Brown and the BookStack Project contributors
-https://github.com/BookStackApp/BookStack/graphs/contributors
+Copyright (c) 2015-2023, Dan Brown and the BookStack Project contributors.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

app/Actions/Activity.php

@@ -2,10 +2,12 @@
 
 namespace BookStack\Actions;
 
+use BookStack\Auth\Permissions\JointPermission;
 use BookStack\Auth\User;
 use BookStack\Entities\Models\Entity;
 use BookStack\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\HasMany;
 use Illuminate\Database\Eloquent\Relations\MorphTo;
 use Illuminate\Support\Str;
 
@@ -40,6 +42,12 @@ class Activity extends Model
         return $this->belongsTo(User::class);
     }
 
+    public function jointPermissions(): HasMany
+    {
+        return $this->hasMany(JointPermission::class, 'entity_id', 'entity_id')
+            ->whereColumn('activities.entity_type', '=', 'joint_permissions.entity_type');
+    }
+
     /**
      * Returns text from the language files, Looks up by using the activity key.
      */

app/Actions/ActivityType.php

@@ -29,6 +29,9 @@ class ActivityType
     const COMMENTED_ON = 'commented_on';
     const PERMISSIONS_UPDATE = 'permissions_update';
 
+    const REVISION_RESTORE = 'revision_restore';
+    const REVISION_DELETE = 'revision_delete';
+
     const SETTINGS_UPDATE = 'settings_update';
     const MAINTENANCE_ACTION_RUN = 'maintenance_action_run';
 

app/Actions/Favourite.php

@@ -2,7 +2,9 @@
 
 namespace BookStack\Actions;
 
+use BookStack\Auth\Permissions\JointPermission;
 use BookStack\Model;
+use Illuminate\Database\Eloquent\Relations\HasMany;
 use Illuminate\Database\Eloquent\Relations\MorphTo;
 
 class Favourite extends Model
@@ -16,4 +18,10 @@ class Favourite extends Model
     {
         return $this->morphTo();
     }
+
+    public function jointPermissions(): HasMany
+    {
+        return $this->hasMany(JointPermission::class, 'entity_id', 'favouritable_id')
+            ->whereColumn('favourites.favouritable_type', '=', 'joint_permissions.entity_type');
+    }
 }

app/Actions/Queries/WebhooksAllPaginatedAndSorted.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace BookStack\Actions\Queries;
+
+use BookStack\Actions\Webhook;
+use BookStack\Util\SimpleListOptions;
+use Illuminate\Pagination\LengthAwarePaginator;
+
+/**
+ * Get all the webhooks in the system in a paginated format.
+ */
+class WebhooksAllPaginatedAndSorted
+{
+    public function run(int $count, SimpleListOptions $listOptions): LengthAwarePaginator
+    {
+        $query = Webhook::query()->select(['*'])
+            ->withCount(['trackedEvents'])
+            ->orderBy($listOptions->getSort(), $listOptions->getOrder());
+
+        if ($listOptions->getSearch()) {
+            $term = '%' . $listOptions->getSearch() . '%';
+            $query->where(function ($query) use ($term) {
+                $query->where('name', 'like', $term)
+                    ->orWhere('endpoint', 'like', $term);
+            });
+        }
+
+        return $query->paginate($count);
+    }
+}

app/Actions/Tag.php

@@ -2,8 +2,10 @@
 
 namespace BookStack\Actions;
 
+use BookStack\Auth\Permissions\JointPermission;
 use BookStack\Model;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Relations\HasMany;
 use Illuminate\Database\Eloquent\Relations\MorphTo;
 
 /**
@@ -27,6 +29,12 @@ class Tag extends Model
         return $this->morphTo('entity');
     }
 
+    public function jointPermissions(): HasMany
+    {
+        return $this->hasMany(JointPermission::class, 'entity_id', 'entity_id')
+            ->whereColumn('tags.entity_type', '=', 'joint_permissions.entity_type');
+    }
+
     /**
      * Get a full URL to start a tag name search for this tag name.
      */

app/Actions/TagRepo.php

@@ -4,24 +4,29 @@ namespace BookStack\Actions;
 
 use BookStack\Auth\Permissions\PermissionApplicator;
 use BookStack\Entities\Models\Entity;
+use BookStack\Util\SimpleListOptions;
 use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Support\Collection;
 use Illuminate\Support\Facades\DB;
 
 class TagRepo
 {
-    protected PermissionApplicator $permissions;
-
-    public function __construct(PermissionApplicator $permissions)
-    {
-        $this->permissions = $permissions;
+    public function __construct(
+        protected PermissionApplicator $permissions
+    ) {
     }
 
     /**
      * Start a query against all tags in the system.
      */
-    public function queryWithTotals(string $searchTerm, string $nameFilter): Builder
+    public function queryWithTotals(SimpleListOptions $listOptions, string $nameFilter): Builder
     {
+        $searchTerm = $listOptions->getSearch();
+        $sort = $listOptions->getSort();
+        if ($sort === 'name' && $nameFilter) {
+            $sort = 'value';
+        }
+
         $query = Tag::query()
             ->select([
                 'name',
@@ -32,7 +37,7 @@ class TagRepo
                 DB::raw('SUM(IF(entity_type = \'book\', 1, 0)) as book_count'),
                 DB::raw('SUM(IF(entity_type = \'bookshelf\', 1, 0)) as shelf_count'),
             ])
-            ->orderBy($nameFilter ? 'value' : 'name');
+            ->orderBy($sort, $listOptions->getOrder());
 
         if ($nameFilter) {
             $query->where('name', '=', $nameFilter);
@@ -57,21 +62,21 @@ class TagRepo
      * Get tag name suggestions from scanning existing tag names.
      * If no search term is given the 50 most popular tag names are provided.
      */
-    public function getNameSuggestions(?string $searchTerm): Collection
+    public function getNameSuggestions(string $searchTerm): Collection
     {
         $query = Tag::query()
             ->select('*', DB::raw('count(*) as count'))
             ->groupBy('name');
 
         if ($searchTerm) {
-            $query = $query->where('name', 'LIKE', $searchTerm . '%')->orderBy('name', 'desc');
+            $query = $query->where('name', 'LIKE', $searchTerm . '%')->orderBy('name', 'asc');
         } else {
             $query = $query->orderBy('count', 'desc')->take(50);
         }
 
         $query = $this->permissions->restrictEntityRelationQuery($query, 'tags', 'entity_id', 'entity_type');
 
-        return $query->get(['name'])->pluck('name');
+        return $query->pluck('name');
     }
 
     /**
@@ -79,10 +84,11 @@ class TagRepo
      * If no search is given the 50 most popular values are provided.
      * Passing a tagName will only find values for a tags with a particular name.
      */
-    public function getValueSuggestions(?string $searchTerm, ?string $tagName): Collection
+    public function getValueSuggestions(string $searchTerm, string $tagName): Collection
     {
         $query = Tag::query()
             ->select('*', DB::raw('count(*) as count'))
+            ->where('value', '!=', '')
             ->groupBy('value');
 
         if ($searchTerm) {
@@ -97,7 +103,7 @@ class TagRepo
 
         $query = $this->permissions->restrictEntityRelationQuery($query, 'tags', 'entity_id', 'entity_type');
 
-        return $query->get(['value'])->pluck('value');
+        return $query->pluck('value');
     }
 
     /**

app/Actions/View.php

@@ -2,8 +2,10 @@
 
 namespace BookStack\Actions;
 
+use BookStack\Auth\Permissions\JointPermission;
 use BookStack\Interfaces\Viewable;
 use BookStack\Model;
+use Illuminate\Database\Eloquent\Relations\HasMany;
 use Illuminate\Database\Eloquent\Relations\MorphTo;
 
 /**
@@ -28,6 +30,12 @@ class View extends Model
         return $this->morphTo();
     }
 
+    public function jointPermissions(): HasMany
+    {
+        return $this->hasMany(JointPermission::class, 'entity_id', 'viewable_id')
+            ->whereColumn('views.viewable_type', '=', 'joint_permissions.entity_type');
+    }
+
     /**
      * Increment the current user's view count for the given viewable model.
      */

app/Actions/Webhook.php

@@ -22,10 +22,10 @@ use Illuminate\Database\Eloquent\Relations\HasMany;
  */
 class Webhook extends Model implements Loggable
 {
-    protected $fillable = ['name', 'endpoint', 'timeout'];
-
     use HasFactory;
 
+    protected $fillable = ['name', 'endpoint', 'timeout'];
+
     protected $casts = [
         'last_called_at'  => 'datetime',
         'last_errored_at' => 'datetime',

app/Actions/WebhookTrackedEvent.php

@@ -12,7 +12,7 @@ use Illuminate\Database\Eloquent\Model;
  */
 class WebhookTrackedEvent extends Model
 {
-    protected $fillable = ['event'];
-
     use HasFactory;
+
+    protected $fillable = ['event'];
 }

app/Api/ApiEntityListFormatter.php

@@ -0,0 +1,107 @@
+<?php
+
+namespace BookStack\Api;
+
+use BookStack\Entities\Models\Entity;
+
+class ApiEntityListFormatter
+{
+    /**
+     * The list to be formatted.
+     * @var Entity[]
+     */
+    protected $list = [];
+
+    /**
+     * The fields to show in the formatted data.
+     * Can be a plain string array item for a direct model field (If existing on model).
+     * If the key is a string, with a callable value, the return value of the callable
+     * will be used for the resultant value. A null return value will omit the property.
+     * @var array<string|int, string|callable>
+     */
+    protected $fields = [
+        'id', 'name', 'slug', 'book_id', 'chapter_id',
+        'draft', 'template', 'created_at', 'updated_at',
+    ];
+
+    public function __construct(array $list)
+    {
+        $this->list = $list;
+
+        // Default dynamic fields
+        $this->withField('url', fn(Entity $entity) => $entity->getUrl());
+    }
+
+    /**
+     * Add a field to be used in the formatter, with the property using the given
+     * name and value being the return type of the given callback.
+     */
+    public function withField(string $property, callable $callback): self
+    {
+        $this->fields[$property] = $callback;
+        return $this;
+    }
+
+    /**
+     * Show the 'type' property in the response reflecting the entity type.
+     * EG: page, chapter, bookshelf, book
+     * To be included in results with non-pre-determined types.
+     */
+    public function withType(): self
+    {
+        $this->withField('type', fn(Entity $entity) => $entity->getType());
+        return $this;
+    }
+
+    /**
+     * Include tags in the formatted data.
+     */
+    public function withTags(): self
+    {
+        $this->withField('tags', fn(Entity $entity) => $entity->tags);
+        return $this;
+    }
+
+    /**
+     * Format the data and return an array of formatted content.
+     * @return array[]
+     */
+    public function format(): array
+    {
+        $results = [];
+
+        foreach ($this->list as $item) {
+            $results[] = $this->formatSingle($item);
+        }
+
+        return $results;
+    }
+
+    /**
+     * Format a single entity item to a plain array.
+     */
+    protected function formatSingle(Entity $entity): array
+    {
+        $result = [];
+        $values = (clone $entity)->toArray();
+
+        foreach ($this->fields as $field => $callback) {
+            if (is_string($callback)) {
+                $field = $callback;
+                if (!isset($values[$field])) {
+                    continue;
+                }
+                $value = $values[$field];
+            } else {
+                $value = $callback($entity);
+                if (is_null($value)) {
+                    continue;
+                }
+            }
+
+            $result[$field] = $value;
+        }
+
+        return $result;
+    }
+}

app/Api/ListingResponseBuilder.php

@@ -2,24 +2,31 @@
 
 namespace BookStack\Api;
 
-use BookStack\Model;
 use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Collection;
+use Illuminate\Database\Eloquent\Model;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
 
 class ListingResponseBuilder
 {
-    protected $query;
-    protected $request;
-    protected $fields;
+    protected Builder $query;
+    protected Request $request;
+
+    /**
+     * @var string[]
+     */
+    protected array $fields;
 
     /**
      * @var array<callable>
      */
-    protected $resultModifiers = [];
+    protected array $resultModifiers = [];
 
-    protected $filterOperators = [
+    /**
+     * @var array<string, string>
+     */
+    protected array $filterOperators = [
         'eq'   => '=',
         'ne'   => '!=',
         'gt'   => '>',
@@ -63,9 +70,9 @@ class ListingResponseBuilder
     /**
      * Add a callback to modify each element of the results.
      *
-     * @param (callable(Model)) $modifier
+     * @param (callable(Model): void) $modifier
      */
-    public function modifyResults($modifier): void
+    public function modifyResults(callable $modifier): void
     {
         $this->resultModifiers[] = $modifier;
     }

app/Auth/Access/LdapService.php

@@ -105,7 +105,7 @@ class LdapService
             'name'  => $this->getUserResponseProperty($user, $displayNameAttr, $userCn),
             'dn'    => $user['dn'],
             'email' => $this->getUserResponseProperty($user, $emailAttr, null),
-            'avatar'=> $thumbnailAttr ? $this->getUserResponseProperty($user, $thumbnailAttr, null) : null,
+            'avatar' => $thumbnailAttr ? $this->getUserResponseProperty($user, $thumbnailAttr, null) : null,
         ];
 
         if ($this->config['dump_user_details']) {

app/Auth/Access/LoginService.php

@@ -5,6 +5,7 @@ namespace BookStack\Auth\Access;
 use BookStack\Actions\ActivityType;
 use BookStack\Auth\Access\Mfa\MfaSession;
 use BookStack\Auth\User;
+use BookStack\Exceptions\LoginAttemptException;
 use BookStack\Exceptions\StoppedAuthenticationException;
 use BookStack\Facades\Activity;
 use BookStack\Facades\Theme;
@@ -149,6 +150,7 @@ class LoginService
      * May interrupt the flow if extra authentication requirements are imposed.
      *
      * @throws StoppedAuthenticationException
+     * @throws LoginAttemptException
      */
     public function attempt(array $credentials, string $method, bool $remember = false): bool
     {

app/Auth/Access/Oidc/OidcJwtSigningKey.php

@@ -67,11 +67,10 @@ class OidcJwtSigningKey
             throw new OidcInvalidKeyException("Only RS256 keys are currently supported. Found key using {$alg}");
         }
 
-        if (empty($jwk['use'])) {
-            throw new OidcInvalidKeyException('A "use" parameter on the provided key is expected');
-        }
-
-        if ($jwk['use'] !== 'sig') {
+        // 'use' is optional for a JWK but we assume 'sig' where no value exists since that's what
+        // the OIDC discovery spec infers since 'sig' MUST be set if encryption keys come into play.
+        $use = $jwk['use'] ?? 'sig';
+        if ($use !== 'sig') {
             throw new OidcInvalidKeyException("Only signature keys are currently supported. Found key for use {$jwk['use']}");
         }
 

app/Auth/Access/Oidc/OidcOAuthProvider.php

@@ -30,6 +30,11 @@ class OidcOAuthProvider extends AbstractProvider
      */
     protected $tokenEndpoint;
 
+    /**
+     * Scopes to use for the OIDC authorization call.
+     */
+    protected array $scopes = ['openid', 'profile', 'email'];
+
     /**
      * Returns the base URL for authorizing a client.
      */
@@ -54,6 +59,15 @@ class OidcOAuthProvider extends AbstractProvider
         return '';
     }
 
+    /**
+     * Add an additional scope to this provider upon the default.
+     */
+    public function addScope(string $scope): void
+    {
+        $this->scopes[] = $scope;
+        $this->scopes = array_unique($this->scopes);
+    }
+
     /**
      * Returns the default scopes used by this provider.
      *
@@ -62,7 +76,7 @@ class OidcOAuthProvider extends AbstractProvider
      */
     protected function getDefaultScopes(): array
     {
-        return ['openid', 'profile', 'email'];
+        return $this->scopes;
     }
 
     /**

app/Auth/Access/Oidc/OidcProviderSettings.php

@@ -15,40 +15,17 @@ use Psr\Http\Client\ClientInterface;
  */
 class OidcProviderSettings
 {
-    /**
-     * @var string
-     */
-    public $issuer;
-
-    /**
-     * @var string
-     */
-    public $clientId;
-
-    /**
-     * @var string
-     */
-    public $clientSecret;
-
-    /**
-     * @var string
-     */
-    public $redirectUri;
-
-    /**
-     * @var string
-     */
-    public $authorizationEndpoint;
-
-    /**
-     * @var string
-     */
-    public $tokenEndpoint;
+    public string $issuer;
+    public string $clientId;
+    public string $clientSecret;
+    public ?string $redirectUri;
+    public ?string $authorizationEndpoint;
+    public ?string $tokenEndpoint;
 
     /**
      * @var string[]|array[]
      */
-    public $keys = [];
+    public ?array $keys = [];
 
     public function __construct(array $settings)
     {
@@ -164,9 +141,10 @@ class OidcProviderSettings
     protected function filterKeys(array $keys): array
     {
         return array_filter($keys, function (array $key) {
-            $alg = $key['alg'] ?? null;
+            $alg = $key['alg'] ?? 'RS256';
+            $use = $key['use'] ?? 'sig';
 
-            return $key['kty'] === 'RSA' && $key['use'] === 'sig' && (is_null($alg) || $alg === 'RS256');
+            return $key['kty'] === 'RSA' && $use === 'sig' && $alg === 'RS256';
         });
     }
 

app/Auth/Access/Oidc/OidcService.php

@@ -2,20 +2,18 @@
 
 namespace BookStack\Auth\Access\Oidc;
 
-use function auth;
+use BookStack\Auth\Access\GroupSyncService;
 use BookStack\Auth\Access\LoginService;
 use BookStack\Auth\Access\RegistrationService;
 use BookStack\Auth\User;
 use BookStack\Exceptions\JsonDebugException;
 use BookStack\Exceptions\StoppedAuthenticationException;
 use BookStack\Exceptions\UserRegistrationException;
-use function config;
+use Illuminate\Support\Arr;
 use Illuminate\Support\Facades\Cache;
 use League\OAuth2\Client\OptionProvider\HttpBasicAuthOptionProvider;
 use League\OAuth2\Client\Provider\Exception\IdentityProviderException;
 use Psr\Http\Client\ClientInterface as HttpClient;
-use function trans;
-use function url;
 
 /**
  * Class OpenIdConnectService
@@ -26,15 +24,21 @@ class OidcService
     protected RegistrationService $registrationService;
     protected LoginService $loginService;
     protected HttpClient $httpClient;
+    protected GroupSyncService $groupService;
 
     /**
      * OpenIdService constructor.
      */
-    public function __construct(RegistrationService $registrationService, LoginService $loginService, HttpClient $httpClient)
-    {
+    public function __construct(
+        RegistrationService $registrationService,
+        LoginService $loginService,
+        HttpClient $httpClient,
+        GroupSyncService $groupService
+    ) {
         $this->registrationService = $registrationService;
         $this->loginService = $loginService;
         $this->httpClient = $httpClient;
+        $this->groupService = $groupService;
     }
 
     /**
@@ -48,7 +52,6 @@ class OidcService
     {
         $settings = $this->getProviderSettings();
         $provider = $this->getProvider($settings);
-
         return [
             'url'   => $provider->getAuthorizationUrl(),
             'state' => $provider->getState(),
@@ -117,10 +120,31 @@ class OidcService
      */
     protected function getProvider(OidcProviderSettings $settings): OidcOAuthProvider
     {
-        return new OidcOAuthProvider($settings->arrayForProvider(), [
+        $provider = new OidcOAuthProvider($settings->arrayForProvider(), [
             'httpClient'     => $this->httpClient,
             'optionProvider' => new HttpBasicAuthOptionProvider(),
         ]);
+
+        foreach ($this->getAdditionalScopes() as $scope) {
+            $provider->addScope($scope);
+        }
+
+        return $provider;
+    }
+
+    /**
+     * Get any user-defined addition/custom scopes to apply to the authentication request.
+     *
+     * @return string[]
+     */
+    protected function getAdditionalScopes(): array
+    {
+        $scopeConfig = $this->config()['additional_scopes'] ?: '';
+
+        $scopeArr = explode(',', $scopeConfig);
+        $scopeArr = array_map(fn (string $scope) => trim($scope), $scopeArr);
+
+        return array_filter($scopeArr);
     }
 
     /**
@@ -145,19 +169,43 @@ class OidcService
         return implode(' ', $displayName);
     }
 
+    /**
+     * Extract the assigned groups from the id token.
+     *
+     * @return string[]
+     */
+    protected function getUserGroups(OidcIdToken $token): array
+    {
+        $groupsAttr = $this->config()['groups_claim'];
+        if (empty($groupsAttr)) {
+            return [];
+        }
+
+        $groupsList = Arr::get($token->getAllClaims(), $groupsAttr);
+        if (!is_array($groupsList)) {
+            return [];
+        }
+
+        return array_values(array_filter($groupsList, function ($val) {
+            return is_string($val);
+        }));
+    }
+
     /**
      * Extract the details of a user from an ID token.
      *
-     * @return array{name: string, email: string, external_id: string}
+     * @return array{name: string, email: string, external_id: string, groups: string[]}
      */
     protected function getUserDetails(OidcIdToken $token): array
     {
-        $id = $token->getClaim('sub');
+        $idClaim = $this->config()['external_id_claim'];
+        $id = $token->getClaim($idClaim);
 
         return [
             'external_id' => $id,
             'email'       => $token->getClaim('email'),
             'name'        => $this->getUserDisplayName($token, $id),
+            'groups'      => $this->getUserGroups($token),
         ];
     }
 
@@ -209,6 +257,12 @@ class OidcService
             throw new OidcException($exception->getMessage());
         }
 
+        if ($this->shouldSyncGroups()) {
+            $groups = $userDetails['groups'];
+            $detachExisting = $this->config()['remove_from_groups'];
+            $this->groupService->syncUserWithFoundGroups($user, $groups, $detachExisting);
+        }
+
         $this->loginService->login($user, 'oidc');
 
         return $user;
@@ -221,4 +275,12 @@ class OidcService
     {
         return config('oidc');
     }
+
+    /**
+     * Check if groups should be synced.
+     */
+    protected function shouldSyncGroups(): bool
+    {
+        return $this->config()['user_to_groups'] !== false;
+    }
 }

app/Auth/Access/Saml2Service.php

@@ -20,14 +20,11 @@ use OneLogin\Saml2\ValidationError;
  */
 class Saml2Service
 {
-    protected $config;
-    protected $registrationService;
-    protected $loginService;
-    protected $groupSyncService;
+    protected array $config;
+    protected RegistrationService $registrationService;
+    protected LoginService $loginService;
+    protected GroupSyncService $groupSyncService;
 
-    /**
-     * Saml2Service constructor.
-     */
     public function __construct(
         RegistrationService $registrationService,
         LoginService $loginService,
@@ -109,9 +106,10 @@ class Saml2Service
         $errors = $toolkit->getErrors();
 
         if (!empty($errors)) {
-            throw new Error(
-                'Invalid ACS Response: ' . implode(', ', $errors)
-            );
+            $reason = $toolkit->getLastErrorReason();
+            $message = 'Invalid ACS Response; Errors: ' . implode(', ', $errors);
+            $message .= $reason ? "; Reason: {$reason}" : '';
+            throw new Error($message);
         }
 
         if (!$toolkit->isAuthenticated()) {
@@ -168,7 +166,7 @@ class Saml2Service
      */
     public function metadata(): string
     {
-        $toolKit = $this->getToolkit();
+        $toolKit = $this->getToolkit(true);
         $settings = $toolKit->getSettings();
         $metadata = $settings->getSPMetadata();
         $errors = $settings->validateMetadata($metadata);
@@ -189,7 +187,7 @@ class Saml2Service
      * @throws Error
      * @throws Exception
      */
-    protected function getToolkit(): Auth
+    protected function getToolkit(bool $spOnly = false): Auth
     {
         $settings = $this->config['onelogin'];
         $overrides = $this->config['onelogin_overrides'] ?? [];
@@ -199,14 +197,14 @@ class Saml2Service
         }
 
         $metaDataSettings = [];
-        if ($this->config['autoload_from_metadata']) {
+        if (!$spOnly && $this->config['autoload_from_metadata']) {
             $metaDataSettings = IdPMetadataParser::parseRemoteXML($settings['idp']['entityId']);
         }
 
         $spSettings = $this->loadOneloginServiceProviderDetails();
         $settings = array_replace_recursive($settings, $spSettings, $metaDataSettings, $overrides);
 
-        return new Auth($settings);
+        return new Auth($settings, $spOnly);
     }
 
     /**

app/Auth/Permissions/EntityPermission.php

@@ -2,20 +2,41 @@
 
 namespace BookStack\Auth\Permissions;
 
+use BookStack\Auth\Role;
 use BookStack\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\MorphTo;
 
+/**
+ * @property int $id
+ * @property int $role_id
+ * @property int $entity_id
+ * @property string $entity_type
+ * @property boolean $view
+ * @property boolean $create
+ * @property boolean $update
+ * @property boolean $delete
+ */
 class EntityPermission extends Model
 {
-    protected $fillable = ['role_id', 'action'];
+    public const PERMISSIONS = ['view', 'create', 'update', 'delete'];
+
+    protected $fillable = ['role_id', 'view', 'create', 'update', 'delete'];
     public $timestamps = false;
 
     /**
-     * Get all this restriction's attached entity.
-     *
-     * @return \Illuminate\Database\Eloquent\Relations\MorphTo
+     * Get this restriction's attached entity.
      */
-    public function restrictable()
+    public function restrictable(): MorphTo
     {
         return $this->morphTo('restrictable');
     }
+
+    /**
+     * Get the role assigned to this entity permission.
+     */
+    public function role(): BelongsTo
+    {
+        return $this->belongsTo(Role::class);
+    }
 }

app/Auth/Permissions/EntityPermissionEvaluator.php

@@ -0,0 +1,141 @@
+<?php
+
+namespace BookStack\Auth\Permissions;
+
+use BookStack\Auth\Role;
+use BookStack\Entities\Models\Entity;
+use Illuminate\Database\Eloquent\Builder;
+
+class EntityPermissionEvaluator
+{
+    protected string $action;
+
+    public function __construct(string $action)
+    {
+        $this->action = $action;
+    }
+
+    public function evaluateEntityForUser(Entity $entity, array $userRoleIds): ?bool
+    {
+        if ($this->isUserSystemAdmin($userRoleIds)) {
+            return true;
+        }
+
+        $typeIdChain = $this->gatherEntityChainTypeIds(SimpleEntityData::fromEntity($entity));
+        $relevantPermissions = $this->getPermissionsMapByTypeId($typeIdChain, [...$userRoleIds, 0]);
+        $permitsByType = $this->collapseAndCategorisePermissions($typeIdChain, $relevantPermissions);
+
+        $status = $this->evaluatePermitsByType($permitsByType);
+
+        return is_null($status) ? null : $status === PermissionStatus::IMPLICIT_ALLOW || $status === PermissionStatus::EXPLICIT_ALLOW;
+    }
+
+    /**
+     * @param array<string, array<string, int>> $permitsByType
+     */
+    protected function evaluatePermitsByType(array $permitsByType): ?int
+    {
+        // Return grant or reject from role-level if exists
+        if (count($permitsByType['role']) > 0) {
+            return max($permitsByType['role']) ? PermissionStatus::EXPLICIT_ALLOW : PermissionStatus::EXPLICIT_DENY;
+        }
+
+        // Return fallback permission if exists
+        if (count($permitsByType['fallback']) > 0) {
+            return $permitsByType['fallback'][0] ? PermissionStatus::IMPLICIT_ALLOW : PermissionStatus::IMPLICIT_DENY;
+        }
+
+        return null;
+    }
+
+    /**
+     * @param string[] $typeIdChain
+     * @param array<string, EntityPermission[]> $permissionMapByTypeId
+     * @return array<string, array<string, int>>
+     */
+    protected function collapseAndCategorisePermissions(array $typeIdChain, array $permissionMapByTypeId): array
+    {
+        $permitsByType = ['fallback' => [], 'role' => []];
+
+        foreach ($typeIdChain as $typeId) {
+            $permissions = $permissionMapByTypeId[$typeId] ?? [];
+            foreach ($permissions as $permission) {
+                $roleId = $permission->role_id;
+                $type = $roleId === 0 ? 'fallback' : 'role';
+                if (!isset($permitsByType[$type][$roleId])) {
+                    $permitsByType[$type][$roleId] = $permission->{$this->action};
+                }
+            }
+
+            if (isset($permitsByType['fallback'][0])) {
+                break;
+            }
+        }
+
+        return $permitsByType;
+    }
+
+    /**
+     * @param string[] $typeIdChain
+     * @return array<string, EntityPermission[]>
+     */
+    protected function getPermissionsMapByTypeId(array $typeIdChain, array $filterRoleIds): array
+    {
+        $query = EntityPermission::query()->where(function (Builder $query) use ($typeIdChain) {
+            foreach ($typeIdChain as $typeId) {
+                $query->orWhere(function (Builder $query) use ($typeId) {
+                    [$type, $id] = explode(':', $typeId);
+                    $query->where('entity_type', '=', $type)
+                        ->where('entity_id', '=', $id);
+                });
+            }
+        });
+
+        if (!empty($filterRoleIds)) {
+            $query->where(function (Builder $query) use ($filterRoleIds) {
+                $query->whereIn('role_id', [...$filterRoleIds, 0]);
+            });
+        }
+
+        $relevantPermissions = $query->get(['entity_id', 'entity_type', 'role_id', $this->action])->all();
+
+        $map = [];
+        foreach ($relevantPermissions as $permission) {
+            $key = $permission->entity_type . ':' . $permission->entity_id;
+            if (!isset($map[$key])) {
+                $map[$key] = [];
+            }
+
+            $map[$key][] = $permission;
+        }
+
+        return $map;
+    }
+
+    /**
+     * @return string[]
+     */
+    protected function gatherEntityChainTypeIds(SimpleEntityData $entity): array
+    {
+        // The array order here is very important due to the fact we walk up the chain
+        // elsewhere in the class. Earlier items in the chain have higher priority.
+
+        $chain = [$entity->type . ':' . $entity->id];
+
+        if ($entity->type === 'page' && $entity->chapter_id) {
+            $chain[] = 'chapter:' . $entity->chapter_id;
+        }
+
+        if ($entity->type === 'page' || $entity->type === 'chapter') {
+            $chain[] = 'book:' . $entity->book_id;
+        }
+
+        return $chain;
+    }
+
+    protected function isUserSystemAdmin($userRoleIds): bool
+    {
+        $adminRoleId = Role::getSystemRole('admin')->id;
+        return in_array($adminRoleId, $userRoleIds);
+    }
+}

app/Auth/Permissions/JointPermissionBuilder.php

@@ -19,11 +19,6 @@ use Illuminate\Support\Facades\DB;
  */
 class JointPermissionBuilder
 {
-    /**
-     * @var array<string, array<int, SimpleEntityData>>
-     */
-    protected $entityCache;
-
     /**
      * Re-generate all entity permission from scratch.
      */
@@ -40,7 +35,7 @@ class JointPermissionBuilder
         });
 
         // Chunk through all bookshelves
-        Bookshelf::query()->withTrashed()->select(['id', 'restricted', 'owned_by'])
+        Bookshelf::query()->withTrashed()->select(['id', 'owned_by'])
             ->chunk(50, function (EloquentCollection $shelves) use ($roles) {
                 $this->createManyJointPermissions($shelves->all(), $roles);
             });
@@ -92,58 +87,24 @@ class JointPermissionBuilder
         });
 
         // Chunk through all bookshelves
-        Bookshelf::query()->select(['id', 'restricted', 'owned_by'])
+        Bookshelf::query()->select(['id', 'owned_by'])
             ->chunk(50, function ($shelves) use ($roles) {
                 $this->createManyJointPermissions($shelves->all(), $roles);
             });
     }
 
-    /**
-     * Prepare the local entity cache and ensure it's empty.
-     *
-     * @param SimpleEntityData[] $entities
-     */
-    protected function readyEntityCache(array $entities)
-    {
-        $this->entityCache = [];
-
-        foreach ($entities as $entity) {
-            if (!isset($this->entityCache[$entity->type])) {
-                $this->entityCache[$entity->type] = [];
-            }
-
-            $this->entityCache[$entity->type][$entity->id] = $entity;
-        }
-    }
-
-    /**
-     * Get a book via ID, Checks local cache.
-     */
-    protected function getBook(int $bookId): SimpleEntityData
-    {
-        return $this->entityCache['book'][$bookId];
-    }
-
-    /**
-     * Get a chapter via ID, Checks local cache.
-     */
-    protected function getChapter(int $chapterId): SimpleEntityData
-    {
-        return $this->entityCache['chapter'][$chapterId];
-    }
-
     /**
      * Get a query for fetching a book with its children.
      */
     protected function bookFetchQuery(): Builder
     {
         return Book::query()->withTrashed()
-            ->select(['id', 'restricted', 'owned_by'])->with([
+            ->select(['id', 'owned_by'])->with([
                 'chapters' => function ($query) {
-                    $query->withTrashed()->select(['id', 'restricted', 'owned_by', 'book_id']);
+                    $query->withTrashed()->select(['id', 'owned_by', 'book_id']);
                 },
                 'pages' => function ($query) {
-                    $query->withTrashed()->select(['id', 'restricted', 'owned_by', 'book_id', 'chapter_id']);
+                    $query->withTrashed()->select(['id', 'owned_by', 'book_id', 'chapter_id']);
                 },
             ]);
     }
@@ -214,14 +175,7 @@ class JointPermissionBuilder
         $simpleEntities = [];
 
         foreach ($entities as $entity) {
-            $attrs = $entity->getAttributes();
-            $simple = new SimpleEntityData();
-            $simple->id = $attrs['id'];
-            $simple->type = $entity->getMorphClass();
-            $simple->restricted = boolval($attrs['restricted'] ?? 0);
-            $simple->owned_by = $attrs['owned_by'] ?? 0;
-            $simple->book_id = $attrs['book_id'] ?? null;
-            $simple->chapter_id = $attrs['chapter_id'] ?? null;
+            $simple = SimpleEntityData::fromEntity($entity);
             $simpleEntities[] = $simple;
         }
 
@@ -231,31 +185,16 @@ class JointPermissionBuilder
     /**
      * Create & Save entity jointPermissions for many entities and roles.
      *
-     * @param Entity[] $entities
+     * @param Entity[] $originalEntities
      * @param Role[]   $roles
      */
     protected function createManyJointPermissions(array $originalEntities, array $roles)
     {
         $entities = $this->entitiesToSimpleEntities($originalEntities);
-        $this->readyEntityCache($entities);
         $jointPermissions = [];
 
-        // Create a mapping of entity restricted statuses
-        $entityRestrictedMap = [];
-        foreach ($entities as $entity) {
-            $entityRestrictedMap[$entity->type . ':' . $entity->id] = $entity->restricted;
-        }
-
         // Fetch related entity permissions
-        $permissions = $this->getEntityPermissionsForEntities($entities);
-
-        // Create a mapping of explicit entity permissions
-        $permissionMap = [];
-        foreach ($permissions as $permission) {
-            $key = $permission->restrictable_type . ':' . $permission->restrictable_id . ':' . $permission->role_id;
-            $isRestricted = $entityRestrictedMap[$permission->restrictable_type . ':' . $permission->restrictable_id];
-            $permissionMap[$key] = $isRestricted;
-        }
+        $permissions = new MassEntityPermissionEvaluator($entities, 'view');
 
         // Create a mapping of role permissions
         $rolePermissionMap = [];
@@ -268,13 +207,14 @@ class JointPermissionBuilder
         // Create Joint Permission Data
         foreach ($entities as $entity) {
             foreach ($roles as $role) {
-                $jointPermissions[] = $this->createJointPermissionData(
+                $jp = $this->createJointPermissionData(
                     $entity,
                     $role->getRawAttribute('id'),
-                    $permissionMap,
+                    $permissions,
                     $rolePermissionMap,
                     $role->system_name === 'admin'
                 );
+                $jointPermissions[] = $jp;
             }
         }
 
@@ -308,98 +248,45 @@ class JointPermissionBuilder
         return $idsByType;
     }
 
-    /**
-     * Get the entity permissions for all the given entities.
-     *
-     * @param SimpleEntityData[] $entities
-     *
-     * @return EntityPermission[]
-     */
-    protected function getEntityPermissionsForEntities(array $entities): array
-    {
-        $idsByType = $this->entitiesToTypeIdMap($entities);
-        $permissionFetch = EntityPermission::query()
-            ->where('action', '=', 'view')
-            ->where(function (Builder $query) use ($idsByType) {
-                foreach ($idsByType as $type => $ids) {
-                    $query->orWhere(function (Builder $query) use ($type, $ids) {
-                        $query->where('restrictable_type', '=', $type)->whereIn('restrictable_id', $ids);
-                    });
-                }
-            });
-
-        return $permissionFetch->get()->all();
-    }
-
     /**
      * Create entity permission data for an entity and role
      * for a particular action.
      */
-    protected function createJointPermissionData(SimpleEntityData $entity, int $roleId, array $permissionMap, array $rolePermissionMap, bool $isAdminRole): array
+    protected function createJointPermissionData(SimpleEntityData $entity, int $roleId, MassEntityPermissionEvaluator $permissionMap, array $rolePermissionMap, bool $isAdminRole): array
     {
+        // Ensure system admin role retains permissions
+        if ($isAdminRole) {
+            return $this->createJointPermissionDataArray($entity, $roleId, PermissionStatus::EXPLICIT_ALLOW, true);
+        }
+
+        // Return evaluated entity permission status if it has an affect.
+        $entityPermissionStatus = $permissionMap->evaluateEntityForRole($entity, $roleId);
+        if ($entityPermissionStatus !== null) {
+            return $this->createJointPermissionDataArray($entity, $roleId, $entityPermissionStatus, false);
+        }
+
+        // Otherwise default to the role-level permissions
         $permissionPrefix = $entity->type . '-view';
         $roleHasPermission = isset($rolePermissionMap[$roleId . ':' . $permissionPrefix . '-all']);
         $roleHasPermissionOwn = isset($rolePermissionMap[$roleId . ':' . $permissionPrefix . '-own']);
-
-        if ($isAdminRole) {
-            return $this->createJointPermissionDataArray($entity, $roleId, true, true);
-        }
-
-        if ($entity->restricted) {
-            $hasAccess = $this->mapHasActiveRestriction($permissionMap, $entity, $roleId);
-
-            return $this->createJointPermissionDataArray($entity, $roleId, $hasAccess, $hasAccess);
-        }
-
-        if ($entity->type === 'book' || $entity->type === 'bookshelf') {
-            return $this->createJointPermissionDataArray($entity, $roleId, $roleHasPermission, $roleHasPermissionOwn);
-        }
-
-        // For chapters and pages, Check if explicit permissions are set on the Book.
-        $book = $this->getBook($entity->book_id);
-        $hasExplicitAccessToParents = $this->mapHasActiveRestriction($permissionMap, $book, $roleId);
-        $hasPermissiveAccessToParents = !$book->restricted;
-
-        // For pages with a chapter, Check if explicit permissions are set on the Chapter
-        if ($entity->type === 'page' && $entity->chapter_id !== 0) {
-            $chapter = $this->getChapter($entity->chapter_id);
-            $hasPermissiveAccessToParents = $hasPermissiveAccessToParents && !$chapter->restricted;
-            if ($chapter->restricted) {
-                $hasExplicitAccessToParents = $this->mapHasActiveRestriction($permissionMap, $chapter, $roleId);
-            }
-        }
-
-        return $this->createJointPermissionDataArray(
-            $entity,
-            $roleId,
-            ($hasExplicitAccessToParents || ($roleHasPermission && $hasPermissiveAccessToParents)),
-            ($hasExplicitAccessToParents || ($roleHasPermissionOwn && $hasPermissiveAccessToParents))
-        );
-    }
-
-    /**
-     * Check for an active restriction in an entity map.
-     */
-    protected function mapHasActiveRestriction(array $entityMap, SimpleEntityData $entity, int $roleId): bool
-    {
-        $key = $entity->type . ':' . $entity->id . ':' . $roleId;
-
-        return $entityMap[$key] ?? false;
+        $status = $roleHasPermission ? PermissionStatus::IMPLICIT_ALLOW : PermissionStatus::IMPLICIT_DENY;
+        return $this->createJointPermissionDataArray($entity, $roleId, $status, $roleHasPermissionOwn);
     }
 
     /**
      * Create an array of data with the information of an entity jointPermissions.
      * Used to build data for bulk insertion.
      */
-    protected function createJointPermissionDataArray(SimpleEntityData $entity, int $roleId, bool $permissionAll, bool $permissionOwn): array
+    protected function createJointPermissionDataArray(SimpleEntityData $entity, int $roleId, int $permissionStatus, bool $hasPermissionOwn): array
     {
+        $ownPermissionActive = ($hasPermissionOwn && $permissionStatus !== PermissionStatus::EXPLICIT_DENY && $entity->owned_by);
+
         return [
-            'entity_id'          => $entity->id,
-            'entity_type'        => $entity->type,
-            'has_permission'     => $permissionAll,
-            'has_permission_own' => $permissionOwn,
-            'owned_by'           => $entity->owned_by,
-            'role_id'            => $roleId,
+            'entity_id'   => $entity->id,
+            'entity_type' => $entity->type,
+            'role_id'     => $roleId,
+            'status'      => $permissionStatus,
+            'owner_id'    => $ownPermissionActive ? $entity->owned_by : null,
         ];
     }
 }

app/Auth/Permissions/MassEntityPermissionEvaluator.php

@@ -0,0 +1,81 @@
+<?php
+
+namespace BookStack\Auth\Permissions;
+
+class MassEntityPermissionEvaluator extends EntityPermissionEvaluator
+{
+    /**
+     * @var SimpleEntityData[]
+     */
+    protected array $entitiesInvolved;
+    protected array $permissionMapCache;
+
+    public function __construct(array $entitiesInvolved, string $action)
+    {
+        $this->entitiesInvolved = $entitiesInvolved;
+        parent::__construct($action);
+    }
+
+    public function evaluateEntityForRole(SimpleEntityData $entity, int $roleId): ?int
+    {
+        $typeIdChain = $this->gatherEntityChainTypeIds($entity);
+        $relevantPermissions = $this->getPermissionMapByTypeIdForChainAndRole($typeIdChain, $roleId);
+        $permitsByType = $this->collapseAndCategorisePermissions($typeIdChain, $relevantPermissions);
+
+        return $this->evaluatePermitsByType($permitsByType);
+    }
+
+    /**
+     * @param string[] $typeIdChain
+     * @return array<string, EntityPermission[]>
+     */
+    protected function getPermissionMapByTypeIdForChainAndRole(array $typeIdChain, int $roleId): array
+    {
+        $allPermissions = $this->getPermissionMapByTypeIdAndRoleForAllInvolved();
+        $relevantPermissions = [];
+
+        // Filter down permissions to just those for current typeId
+        // and current roleID or fallback permissions.
+        foreach ($typeIdChain as $typeId) {
+            $relevantPermissions[$typeId] = [
+                ...($allPermissions[$typeId][$roleId] ?? []),
+                ...($allPermissions[$typeId][0] ?? [])
+            ];
+        }
+
+        return $relevantPermissions;
+    }
+
+    /**
+     * @return array<string, array<int, EntityPermission[]>>
+     */
+    protected function getPermissionMapByTypeIdAndRoleForAllInvolved(): array
+    {
+        if (isset($this->permissionMapCache)) {
+            return $this->permissionMapCache;
+        }
+
+        $entityTypeIdChain = [];
+        foreach ($this->entitiesInvolved as $entity) {
+            $entityTypeIdChain[] = $entity->type . ':' . $entity->id;
+        }
+
+        $permissionMap = $this->getPermissionsMapByTypeId($entityTypeIdChain, []);
+
+       // Manipulate permission map to also be keyed by roleId.
+        foreach ($permissionMap as $typeId => $permissions) {
+            $permissionMap[$typeId] = [];
+            foreach ($permissions as $permission) {
+                $roleId = $permission->getRawAttribute('role_id');
+                if (!isset($permissionMap[$typeId][$roleId])) {
+                    $permissionMap[$typeId][$roleId] = [];
+                }
+                $permissionMap[$typeId][$roleId][] = $permission;
+            }
+        }
+
+        $this->permissionMapCache = $permissionMap;
+
+        return $this->permissionMapCache;
+    }
+}

app/Auth/Permissions/PermissionApplicator.php

@@ -4,7 +4,6 @@ namespace BookStack\Auth\Permissions;
 
 use BookStack\Auth\Role;
 use BookStack\Auth\User;
-use BookStack\Entities\Models\Chapter;
 use BookStack\Entities\Models\Entity;
 use BookStack\Entities\Models\Page;
 use BookStack\Model;
@@ -34,7 +33,13 @@ class PermissionApplicator
         $ownRolePermission = $user->can($fullPermission . '-own');
         $nonJointPermissions = ['restrictions', 'image', 'attachment', 'comment'];
         $ownerField = ($ownable instanceof Entity) ? 'owned_by' : 'created_by';
-        $isOwner = $user->id === $ownable->getAttribute($ownerField);
+        $ownableFieldVal = $ownable->getAttribute($ownerField);
+
+        if (is_null($ownableFieldVal)) {
+            throw new InvalidArgumentException("{$ownerField} field used but has not been loaded");
+        }
+
+        $isOwner = $user->id === $ownableFieldVal;
         $hasRolePermission = $allRolePermission || ($isOwner && $ownRolePermission);
 
         // Handle non entity specific jointPermissions
@@ -53,30 +58,9 @@ class PermissionApplicator
      */
     protected function hasEntityPermission(Entity $entity, array $userRoleIds, string $action): ?bool
     {
-        $adminRoleId = Role::getSystemRole('admin')->id;
-        if (in_array($adminRoleId, $userRoleIds)) {
-            return true;
-        }
+        $this->ensureValidEntityAction($action);
 
-        $chain = [$entity];
-        if ($entity instanceof Page && $entity->chapter_id) {
-            $chain[] = $entity->chapter;
-        }
-
-        if ($entity instanceof Page || $entity instanceof Chapter) {
-            $chain[] = $entity->book;
-        }
-
-        foreach ($chain as $currentEntity) {
-            if ($currentEntity->restricted) {
-                return $currentEntity->permissions()
-                    ->whereIn('role_id', $userRoleIds)
-                    ->where('action', '=', $action)
-                    ->count() > 0;
-            }
-        }
-
-        return null;
+        return (new EntityPermissionEvaluator($action))->evaluateEntityForUser($entity, $userRoleIds);
     }
 
     /**
@@ -85,18 +69,16 @@ class PermissionApplicator
      */
     public function checkUserHasEntityPermissionOnAny(string $action, string $entityClass = ''): bool
     {
-        if (strpos($action, '-') !== false) {
-            throw new InvalidArgumentException('Action should be a simple entity permission action, not a role permission');
-        }
+        $this->ensureValidEntityAction($action);
 
         $permissionQuery = EntityPermission::query()
-            ->where('action', '=', $action)
+            ->where($action, '=', true)
             ->whereIn('role_id', $this->getCurrentUserRoleIds());
 
         if (!empty($entityClass)) {
             /** @var Entity $entityInstance */
             $entityInstance = app()->make($entityClass);
-            $permissionQuery = $permissionQuery->where('restrictable_type', '=', $entityInstance->getMorphClass());
+            $permissionQuery = $permissionQuery->where('entity_type', '=', $entityInstance->getMorphClass());
         }
 
         $hasPermission = $permissionQuery->count() > 0;
@@ -112,10 +94,12 @@ class PermissionApplicator
     {
         return $query->where(function (Builder $parentQuery) {
             $parentQuery->whereHas('jointPermissions', function (Builder $permissionQuery) {
-                $permissionQuery->whereIn('role_id', $this->getCurrentUserRoleIds())
-                    ->where(function (Builder $query) {
-                        $this->addJointHasPermissionCheck($query, $this->currentUser()->id);
-                    });
+                $permissionQuery->select(['entity_id', 'entity_type'])
+                    ->selectRaw('max(owner_id) as owner_id')
+                    ->selectRaw('max(status) as status')
+                    ->whereIn('role_id', $this->getCurrentUserRoleIds())
+                    ->groupBy(['entity_type', 'entity_id'])
+                    ->havingRaw('(status IN (1, 3) or (owner_id = ? and status != 2))', [$this->currentUser()->id]);
             });
         });
     }
@@ -139,35 +123,23 @@ class PermissionApplicator
      * Filter items that have entities set as a polymorphic relation.
      * For simplicity, this will not return results attached to draft pages.
      * Draft pages should never really have related items though.
-     *
-     * @param Builder|QueryBuilder $query
      */
-    public function restrictEntityRelationQuery($query, string $tableName, string $entityIdColumn, string $entityTypeColumn)
+    public function restrictEntityRelationQuery(Builder $query, string $tableName, string $entityIdColumn, string $entityTypeColumn): Builder
     {
         $tableDetails = ['tableName' => $tableName, 'entityIdColumn' => $entityIdColumn, 'entityTypeColumn' => $entityTypeColumn];
         $pageMorphClass = (new Page())->getMorphClass();
 
-        $q = $query->whereExists(function ($permissionQuery) use (&$tableDetails) {
-            /** @var Builder $permissionQuery */
-            $permissionQuery->select(['role_id'])->from('joint_permissions')
-                ->whereColumn('joint_permissions.entity_id', '=', $tableDetails['tableName'] . '.' . $tableDetails['entityIdColumn'])
-                ->whereColumn('joint_permissions.entity_type', '=', $tableDetails['tableName'] . '.' . $tableDetails['entityTypeColumn'])
-                ->whereIn('joint_permissions.role_id', $this->getCurrentUserRoleIds())
-                ->where(function (QueryBuilder $query) {
-                    $this->addJointHasPermissionCheck($query, $this->currentUser()->id);
-                });
-        })->where(function ($query) use ($tableDetails, $pageMorphClass) {
-            /** @var Builder $query */
-            $query->where($tableDetails['entityTypeColumn'], '!=', $pageMorphClass)
+        return $this->restrictEntityQuery($query)
+            ->where(function ($query) use ($tableDetails, $pageMorphClass) {
+                /** @var Builder $query */
+                $query->where($tableDetails['entityTypeColumn'], '!=', $pageMorphClass)
                 ->orWhereExists(function (QueryBuilder $query) use ($tableDetails, $pageMorphClass) {
                     $query->select('id')->from('pages')
                         ->whereColumn('pages.id', '=', $tableDetails['tableName'] . '.' . $tableDetails['entityIdColumn'])
                         ->where($tableDetails['tableName'] . '.' . $tableDetails['entityTypeColumn'], '=', $pageMorphClass)
                         ->where('pages.draft', '=', false);
                 });
-        });
-
-        return $q;
+            });
     }
 
     /**
@@ -179,49 +151,20 @@ class PermissionApplicator
     public function restrictPageRelationQuery(Builder $query, string $tableName, string $pageIdColumn): Builder
     {
         $fullPageIdColumn = $tableName . '.' . $pageIdColumn;
-        $morphClass = (new Page())->getMorphClass();
-
-        $existsQuery = function ($permissionQuery) use ($fullPageIdColumn, $morphClass) {
-            /** @var Builder $permissionQuery */
-            $permissionQuery->select('joint_permissions.role_id')->from('joint_permissions')
-                ->whereColumn('joint_permissions.entity_id', '=', $fullPageIdColumn)
-                ->where('joint_permissions.entity_type', '=', $morphClass)
-                ->whereIn('joint_permissions.role_id', $this->getCurrentUserRoleIds())
-                ->where(function (QueryBuilder $query) {
-                    $this->addJointHasPermissionCheck($query, $this->currentUser()->id);
+        return $this->restrictEntityQuery($query)
+            ->where(function ($query) use ($fullPageIdColumn) {
+                /** @var Builder $query */
+                $query->whereExists(function (QueryBuilder $query) use ($fullPageIdColumn) {
+                    $query->select('id')->from('pages')
+                        ->whereColumn('pages.id', '=', $fullPageIdColumn)
+                        ->where('pages.draft', '=', false);
+                })->orWhereExists(function (QueryBuilder $query) use ($fullPageIdColumn) {
+                    $query->select('id')->from('pages')
+                        ->whereColumn('pages.id', '=', $fullPageIdColumn)
+                        ->where('pages.draft', '=', true)
+                        ->where('pages.created_by', '=', $this->currentUser()->id);
                 });
-        };
-
-        $q = $query->where(function ($query) use ($existsQuery, $fullPageIdColumn) {
-            $query->whereExists($existsQuery)
-                ->orWhere($fullPageIdColumn, '=', 0);
-        });
-
-        // Prevent visibility of non-owned draft pages
-        $q->whereExists(function (QueryBuilder $query) use ($fullPageIdColumn) {
-            $query->select('id')->from('pages')
-                ->whereColumn('pages.id', '=', $fullPageIdColumn)
-                ->where(function (QueryBuilder $query) {
-                    $query->where('pages.draft', '=', false)
-                        ->orWhere('pages.owned_by', '=', $this->currentUser()->id);
-                });
-        });
-
-        return $q;
-    }
-
-    /**
-     * Add the query for checking the given user id has permission
-     * within the join_permissions table.
-     *
-     * @param QueryBuilder|Builder $query
-     */
-    protected function addJointHasPermissionCheck($query, int $userIdToCheck)
-    {
-        $query->where('joint_permissions.has_permission', '=', true)->orWhere(function ($query) use ($userIdToCheck) {
-            $query->where('joint_permissions.has_permission_own', '=', true)
-                ->where('joint_permissions.owned_by', '=', $userIdToCheck);
-        });
+            });
     }
 
     /**
@@ -245,4 +188,16 @@ class PermissionApplicator
 
         return $this->currentUser()->roles->pluck('id')->values()->all();
     }
+
+    /**
+     * Ensure the given action is a valid and expected entity action.
+     * Throws an exception if invalid otherwise does nothing.
+     * @throws InvalidArgumentException
+     */
+    protected function ensureValidEntityAction(string $action): void
+    {
+        if (!in_array($action, EntityPermission::PERMISSIONS)) {
+            throw new InvalidArgumentException('Action should be a simple entity permission action, not a role permission');
+        }
+    }
 }

app/Auth/Permissions/PermissionFormData.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace BookStack\Auth\Permissions;
+
+use BookStack\Auth\Role;
+use BookStack\Entities\Models\Entity;
+
+class PermissionFormData
+{
+    protected Entity $entity;
+
+    public function __construct(Entity $entity)
+    {
+        $this->entity = $entity;
+    }
+
+    /**
+     * Get the permissions with assigned roles.
+     */
+    public function permissionsWithRoles(): array
+    {
+        return $this->entity->permissions()
+            ->with('role')
+            ->where('role_id', '!=', 0)
+            ->get()
+            ->sortBy('role.display_name')
+            ->all();
+    }
+
+    /**
+     * Get the roles that don't yet have specific permissions for the
+     * entity we're managing permissions for.
+     */
+    public function rolesNotAssigned(): array
+    {
+        $assigned = $this->entity->permissions()->pluck('role_id');
+        return Role::query()
+            ->where('system_name', '!=', 'admin')
+            ->whereNotIn('id', $assigned)
+            ->orderBy('display_name', 'asc')
+            ->get()
+            ->all();
+    }
+
+    /**
+     * Get the entity permission for the "Everyone Else" option.
+     */
+    public function everyoneElseEntityPermission(): EntityPermission
+    {
+        /** @var ?EntityPermission $permission */
+        $permission = $this->entity->permissions()
+            ->where('role_id', '=', 0)
+            ->first();
+        return $permission ?? (new EntityPermission());
+    }
+
+    /**
+     * Get the "Everyone Else" role entry.
+     */
+    public function everyoneElseRole(): Role
+    {
+        return (new Role())->forceFill([
+            'id' => 0,
+            'display_name' => trans('entities.permissions_role_everyone_else'),
+            'description' => trans('entities.permissions_role_everyone_else_desc'),
+        ]);
+    }
+}

app/Auth/Permissions/PermissionStatus.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace BookStack\Auth\Permissions;
+
+class PermissionStatus
+{
+    const IMPLICIT_DENY = 0;
+    const IMPLICIT_ALLOW = 1;
+    const EXPLICIT_DENY = 2;
+    const EXPLICIT_ALLOW = 3;
+}

app/Auth/Permissions/PermissionsRepo.php

@@ -12,11 +12,8 @@ use Illuminate\Database\Eloquent\Collection;
 class PermissionsRepo
 {
     protected JointPermissionBuilder $permissionBuilder;
-    protected $systemRoles = ['admin', 'public'];
+    protected array $systemRoles = ['admin', 'public'];
 
-    /**
-     * PermissionsRepo constructor.
-     */
     public function __construct(JointPermissionBuilder $permissionBuilder)
     {
         $this->permissionBuilder = $permissionBuilder;
@@ -41,7 +38,7 @@ class PermissionsRepo
     /**
      * Get a role via its ID.
      */
-    public function getRoleById($id): Role
+    public function getRoleById(int $id): Role
     {
         return Role::query()->findOrFail($id);
     }
@@ -52,10 +49,10 @@ class PermissionsRepo
     public function saveNewRole(array $roleData): Role
     {
         $role = new Role($roleData);
-        $role->mfa_enforced = ($roleData['mfa_enforced'] ?? 'false') === 'true';
+        $role->mfa_enforced = boolval($roleData['mfa_enforced'] ?? false);
         $role->save();
 
-        $permissions = isset($roleData['permissions']) ? array_keys($roleData['permissions']) : [];
+        $permissions = $roleData['permissions'] ?? [];
         $this->assignRolePermissions($role, $permissions);
         $this->permissionBuilder->rebuildForRole($role);
 
@@ -66,42 +63,45 @@ class PermissionsRepo
 
     /**
      * Updates an existing role.
-     * Ensure Admin role always have core permissions.
+     * Ensures Admin system role always have core permissions.
      */
-    public function updateRole($roleId, array $roleData)
+    public function updateRole($roleId, array $roleData): Role
     {
         $role = $this->getRoleById($roleId);
 
-        $permissions = isset($roleData['permissions']) ? array_keys($roleData['permissions']) : [];
+        if (isset($roleData['permissions'])) {
+            $this->assignRolePermissions($role, $roleData['permissions']);
+        }
+
+        $role->fill($roleData);
+        $role->save();
+        $this->permissionBuilder->rebuildForRole($role);
+
+        Activity::add(ActivityType::ROLE_UPDATE, $role);
+
+        return $role;
+    }
+
+    /**
+     * Assign a list of permission names to the given role.
+     */
+    protected function assignRolePermissions(Role $role, array $permissionNameArray = []): void
+    {
+        $permissions = [];
+        $permissionNameArray = array_values($permissionNameArray);
+
+        // Ensure the admin system role retains vital system permissions
         if ($role->system_name === 'admin') {
-            $permissions = array_merge($permissions, [
+            $permissionNameArray = array_unique(array_merge($permissionNameArray, [
                 'users-manage',
                 'user-roles-manage',
                 'restrictions-manage-all',
                 'restrictions-manage-own',
                 'settings-manage',
-            ]);
+            ]));
         }
 
-        $this->assignRolePermissions($role, $permissions);
-
-        $role->fill($roleData);
-        $role->mfa_enforced = ($roleData['mfa_enforced'] ?? 'false') === 'true';
-        $role->save();
-        $this->permissionBuilder->rebuildForRole($role);
-
-        Activity::add(ActivityType::ROLE_UPDATE, $role);
-    }
-
-    /**
-     * Assign a list of permission names to a role.
-     */
-    protected function assignRolePermissions(Role $role, array $permissionNameArray = [])
-    {
-        $permissions = [];
-        $permissionNameArray = array_values($permissionNameArray);
-
-        if ($permissionNameArray) {
+        if (!empty($permissionNameArray)) {
             $permissions = RolePermission::query()
                 ->whereIn('name', $permissionNameArray)
                 ->pluck('id')
@@ -114,13 +114,13 @@ class PermissionsRepo
     /**
      * Delete a role from the system.
      * Check it's not an admin role or set as default before deleting.
-     * If an migration Role ID is specified the users assign to the current role
+     * If a migration Role ID is specified the users assign to the current role
      * will be added to the role of the specified id.
      *
      * @throws PermissionsException
      * @throws Exception
      */
-    public function deleteRole($roleId, $migrateRoleId)
+    public function deleteRole(int $roleId, int $migrateRoleId = 0): void
     {
         $role = $this->getRoleById($roleId);
 
@@ -131,7 +131,7 @@ class PermissionsRepo
             throw new PermissionsException(trans('errors.role_registration_default_cannot_delete'));
         }
 
-        if ($migrateRoleId) {
+        if ($migrateRoleId !== 0) {
             $newRole = Role::query()->find($migrateRoleId);
             if ($newRole) {
                 $users = $role->users()->pluck('id')->toArray();
@@ -139,6 +139,7 @@ class PermissionsRepo
             }
         }
 
+        $role->entityPermissions()->delete();
         $role->jointPermissions()->delete();
         Activity::add(ActivityType::ROLE_DELETE, $role);
         $role->delete();

app/Auth/Permissions/RolePermission.php

@@ -8,6 +8,8 @@ use Illuminate\Database\Eloquent\Relations\BelongsToMany;
 
 /**
  * @property int $id
+ * @property string $name
+ * @property string $display_name
  */
 class RolePermission extends Model
 {

app/Auth/Permissions/SimpleEntityData.php

@@ -2,12 +2,27 @@
 
 namespace BookStack\Auth\Permissions;
 
+use BookStack\Entities\Models\Entity;
+
 class SimpleEntityData
 {
     public int $id;
     public string $type;
-    public bool $restricted;
     public int $owned_by;
     public ?int $book_id;
     public ?int $chapter_id;
+
+    public static function fromEntity(Entity $entity): self
+    {
+        $attrs = $entity->getAttributes();
+        $simple = new self();
+
+        $simple->id = $attrs['id'];
+        $simple->type = $entity->getMorphClass();
+        $simple->owned_by = $attrs['owned_by'] ?? 0;
+        $simple->book_id = $attrs['book_id'] ?? null;
+        $simple->chapter_id = $attrs['chapter_id'] ?? null;
+
+        return $simple;
+    }
 }

app/Auth/Queries/RolesAllPaginatedAndSorted.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace BookStack\Auth\Queries;
+
+use BookStack\Auth\Role;
+use BookStack\Util\SimpleListOptions;
+use Illuminate\Pagination\LengthAwarePaginator;
+
+/**
+ * Get all the roles in the system in a paginated format.
+ */
+class RolesAllPaginatedAndSorted
+{
+    public function run(int $count, SimpleListOptions $listOptions): LengthAwarePaginator
+    {
+        $sort = $listOptions->getSort();
+        if ($sort === 'created_at') {
+            $sort = 'users.created_at';
+        }
+
+        $query = Role::query()->select(['*'])
+            ->withCount(['users', 'permissions'])
+            ->orderBy($sort, $listOptions->getOrder());
+
+        if ($listOptions->getSearch()) {
+            $term = '%' . $listOptions->getSearch() . '%';
+            $query->where(function ($query) use ($term) {
+                $query->where('display_name', 'like', $term)
+                    ->orWhere('description', 'like', $term);
+            });
+        }
+
+        return $query->paginate($count);
+    }
+}

app/Auth/Queries/UsersAllPaginatedAndSorted.php

@@ -3,6 +3,7 @@
 namespace BookStack\Auth\Queries;
 
 use BookStack\Auth\User;
+use BookStack\Util\SimpleListOptions;
 use Illuminate\Pagination\LengthAwarePaginator;
 
 /**
@@ -11,23 +12,23 @@ use Illuminate\Pagination\LengthAwarePaginator;
  * user is assumed to be trusted. (Admin users).
  * Email search can be abused to extract email addresses.
  */
-class AllUsersPaginatedAndSorted
+class UsersAllPaginatedAndSorted
 {
-    /**
-     * @param array{sort: string, order: string, search: string} $sortData
-     */
-    public function run(int $count, array $sortData): LengthAwarePaginator
+    public function run(int $count, SimpleListOptions $listOptions): LengthAwarePaginator
     {
-        $sort = $sortData['sort'];
+        $sort = $listOptions->getSort();
+        if ($sort === 'created_at') {
+            $sort = 'users.created_at';
+        }
 
         $query = User::query()->select(['*'])
             ->scopes(['withLastActivityAt'])
             ->with(['roles', 'avatar'])
             ->withCount('mfaValues')
-            ->orderBy($sort, $sortData['order']);
+            ->orderBy($sort, $listOptions->getOrder());
 
-        if ($sortData['search']) {
-            $term = '%' . $sortData['search'] . '%';
+        if ($listOptions->getSearch()) {
+            $term = '%' . $listOptions->getSearch() . '%';
             $query->where(function ($query) use ($term) {
                 $query->where('name', 'like', $term)
                     ->orWhere('email', 'like', $term);

app/Auth/Role.php

@@ -2,6 +2,7 @@
 
 namespace BookStack\Auth;
 
+use BookStack\Auth\Permissions\EntityPermission;
 use BookStack\Auth\Permissions\JointPermission;
 use BookStack\Auth\Permissions\RolePermission;
 use BookStack\Interfaces\Loggable;
@@ -26,10 +27,14 @@ class Role extends Model implements Loggable
 {
     use HasFactory;
 
-    protected $fillable = ['display_name', 'description', 'external_auth_id'];
+    protected $fillable = ['display_name', 'description', 'external_auth_id', 'mfa_enforced'];
 
     protected $hidden = ['pivot'];
 
+    protected $casts = [
+        'mfa_enforced' => 'boolean',
+    ];
+
     /**
      * The roles that belong to the role.
      */
@@ -54,6 +59,14 @@ class Role extends Model implements Loggable
         return $this->belongsToMany(RolePermission::class, 'permission_role', 'role_id', 'permission_id');
     }
 
+    /**
+     * Get the entity permissions assigned to this role.
+     */
+    public function entityPermissions(): HasMany
+    {
+        return $this->hasMany(EntityPermission::class);
+    }
+
     /**
      * Check if this role has a permission.
      */
@@ -98,26 +111,13 @@ class Role extends Model implements Loggable
      */
     public static function getSystemRole(string $systemName): ?self
     {
-        return static::query()->where('system_name', '=', $systemName)->first();
-    }
+        static $cache = [];
 
-    /**
-     * Get all visible roles.
-     */
-    public static function visible(): Collection
-    {
-        return static::query()->where('hidden', '=', false)->orderBy('name')->get();
-    }
+        if (!isset($cache[$systemName])) {
+            $cache[$systemName] = static::query()->where('system_name', '=', $systemName)->first();
+        }
 
-    /**
-     * Get the roles that can be restricted.
-     */
-    public static function restrictable(): Collection
-    {
-        return static::query()
-            ->where('system_name', '!=', 'admin')
-            ->orderBy('display_name', 'asc')
-            ->get();
+        return $cache[$systemName];
     }
 
     /**

app/Auth/User.php

@@ -72,7 +72,7 @@ class User extends Model implements AuthenticatableContract, CanResetPasswordCon
      */
     protected $hidden = [
         'password', 'remember_token', 'system_name', 'email_confirmed', 'external_auth_id', 'email',
-        'created_at', 'updated_at', 'image_id', 'roles', 'avatar', 'user_id',
+        'created_at', 'updated_at', 'image_id', 'roles', 'avatar', 'user_id', 'pivot',
     ];
 
     /**
@@ -80,6 +80,11 @@ class User extends Model implements AuthenticatableContract, CanResetPasswordCon
      */
     protected ?Collection $permissions;
 
+    /**
+     * This holds the user's avatar URL when loaded to prevent re-calculating within the same request.
+     */
+    protected string $avatarUrl = '';
+
     /**
      * This holds the default user when loaded.
      *
@@ -195,6 +200,7 @@ class User extends Model implements AuthenticatableContract, CanResetPasswordCon
     public function attachRole(Role $role)
     {
         $this->roles()->attach($role->id);
+        $this->unsetRelation('roles');
     }
 
     /**
@@ -233,12 +239,18 @@ class User extends Model implements AuthenticatableContract, CanResetPasswordCon
             return $default;
         }
 
+        if (!empty($this->avatarUrl)) {
+            return $this->avatarUrl;
+        }
+
         try {
             $avatar = $this->avatar ? url($this->avatar->getThumb($size, $size, false)) : $default;
         } catch (Exception $err) {
             $avatar = $default;
         }
 
+        $this->avatarUrl = $avatar;
+
         return $avatar;
     }
 

app/Auth/UserRepo.php

@@ -10,6 +10,7 @@ use BookStack\Exceptions\UserUpdateException;
 use BookStack\Facades\Activity;
 use BookStack\Uploads\UserAvatars;
 use Exception;
+use Illuminate\Support\Facades\Hash;
 use Illuminate\Support\Facades\Log;
 use Illuminate\Support\Str;
 
@@ -61,7 +62,7 @@ class UserRepo
         $user = new User();
         $user->name = $data['name'];
         $user->email = $data['email'];
-        $user->password = bcrypt(empty($data['password']) ? Str::random(32) : $data['password']);
+        $user->password = Hash::make(empty($data['password']) ? Str::random(32) : $data['password']);
         $user->email_confirmed = $emailConfirmed;
         $user->external_auth_id = $data['external_auth_id'] ?? '';
 
@@ -126,7 +127,7 @@ class UserRepo
         }
 
         if (!empty($data['password'])) {
-            $user->password = bcrypt($data['password']);
+            $user->password = Hash::make($data['password']);
         }
 
         if (!empty($data['language'])) {
@@ -157,6 +158,9 @@ class UserRepo
         // Delete user profile images
         $this->userAvatar->destroyAllForUser($user);
 
+        // Delete related activities
+        setting()->deleteUserSettings($user->id);
+
         if (!empty($newOwnerId)) {
             $newOwner = User::query()->find($newOwnerId);
             if (!is_null($newOwner)) {
@@ -230,6 +234,8 @@ class UserRepo
      */
     protected function setUserRoles(User $user, array $roles)
     {
+        $roles = array_filter(array_values($roles));
+
         if ($this->demotingLastAdmin($user, $roles)) {
             throw new UserUpdateException(trans('errors.role_cannot_remove_only_admin'), $user->getEditUrl());
         }

app/Config/app.php

@@ -8,6 +8,8 @@
  * Do not edit this file unless you're happy to maintain any changes yourself.
  */
 
+use Illuminate\Support\Facades\Facade;
+
 return [
 
     // The environment to run BookStack in.
@@ -22,7 +24,7 @@ return [
     // The number of revisions to keep in the database.
     // Once this limit is reached older revisions will be deleted.
     // If set to false then a limit will not be enforced.
-    'revision_limit' => env('REVISION_LIMIT', 50),
+    'revision_limit' => env('REVISION_LIMIT', 100),
 
     // The number of days that content will remain in the recycle bin before
     // being considered for auto-removal. It is not a guarantee that content will
@@ -75,7 +77,7 @@ return [
     'locale' => env('APP_LANG', 'en'),
 
     // Locales available
-    'locales' => ['en', 'ar', 'bg', 'bs', 'ca', 'cs', 'cy', 'da', 'de', 'de_informal', 'es', 'es_AR', 'et', 'eu', 'fa', 'fr', 'he', 'hr', 'hu', 'id', 'it', 'ja', 'ko', 'lt', 'lv', 'nl', 'nb', 'pt', 'pt_BR', 'sk', 'sl', 'sv', 'pl',  'ru', 'th', 'tr', 'uk', 'uz', 'vi', 'zh_CN', 'zh_TW'],
+    'locales' => ['en', 'ar', 'bg', 'bs', 'ca', 'cs', 'cy', 'da', 'de', 'de_informal', 'el', 'es', 'es_AR', 'et', 'eu', 'fa', 'fr', 'he', 'hr', 'hu', 'id', 'it', 'ja', 'ka', 'ko', 'lt', 'lv', 'nl', 'nb', 'pt', 'pt_BR', 'sk', 'sl', 'sv', 'pl',  'ro', 'ru', 'tr', 'uk', 'uz', 'vi', 'zh_CN', 'zh_TW'],
 
     //  Application Fallback Locale
     'fallback_locale' => 'en',
@@ -98,7 +100,13 @@ return [
     // Encryption cipher
     'cipher' => 'AES-256-CBC',
 
-    // Application Services Provides
+    // Maintenance Mode Driver
+    'maintenance' => [
+        'driver' => 'file',
+        // 'store'  => 'redis',
+    ],
+
+    // Application Service Providers
     'providers' => [
 
         // Laravel Framework Service Providers...
@@ -114,6 +122,8 @@ return [
         Illuminate\Foundation\Providers\FoundationServiceProvider::class,
         Illuminate\Hashing\HashServiceProvider::class,
         Illuminate\Mail\MailServiceProvider::class,
+        Illuminate\Notifications\NotificationServiceProvider::class,
+        Illuminate\Pagination\PaginationServiceProvider::class,
         Illuminate\Pipeline\PipelineServiceProvider::class,
         Illuminate\Queue\QueueServiceProvider::class,
         Illuminate\Redis\RedisServiceProvider::class,
@@ -121,81 +131,27 @@ return [
         Illuminate\Session\SessionServiceProvider::class,
         Illuminate\Validation\ValidationServiceProvider::class,
         Illuminate\View\ViewServiceProvider::class,
-        Illuminate\Notifications\NotificationServiceProvider::class,
-        SocialiteProviders\Manager\ServiceProvider::class,
 
         // Third party service providers
-        Intervention\Image\ImageServiceProvider::class,
         Barryvdh\DomPDF\ServiceProvider::class,
         Barryvdh\Snappy\ServiceProvider::class,
-
-        // BookStack replacement service providers (Extends Laravel)
-        BookStack\Providers\PaginationServiceProvider::class,
-        BookStack\Providers\TranslationServiceProvider::class,
+        Intervention\Image\ImageServiceProvider::class,
+        SocialiteProviders\Manager\ServiceProvider::class,
 
         // BookStack custom service providers
         BookStack\Providers\ThemeServiceProvider::class,
-        BookStack\Providers\AuthServiceProvider::class,
         BookStack\Providers\AppServiceProvider::class,
-        BookStack\Providers\BroadcastServiceProvider::class,
+        BookStack\Providers\AuthServiceProvider::class,
         BookStack\Providers\EventServiceProvider::class,
         BookStack\Providers\RouteServiceProvider::class,
-        BookStack\Providers\CustomFacadeProvider::class,
-        BookStack\Providers\CustomValidationServiceProvider::class,
+        BookStack\Providers\TranslationServiceProvider::class,
+        BookStack\Providers\ValidationRuleServiceProvider::class,
+        BookStack\Providers\ViewTweaksServiceProvider::class,
     ],
 
-    /*
-    |--------------------------------------------------------------------------
-    | Class Aliases
-    |--------------------------------------------------------------------------
-    |
-    | This array of class aliases will be registered when this application
-    | is started. However, feel free to register as many as you wish as
-    | the aliases are "lazy" loaded so they don't hinder performance.
-    |
-    */
-
-    // Class aliases, Registered on application start
-    'aliases' => [
-        // Laravel
-        'App'          => Illuminate\Support\Facades\App::class,
-        'Arr'          => Illuminate\Support\Arr::class,
-        'Artisan'      => Illuminate\Support\Facades\Artisan::class,
-        'Auth'         => Illuminate\Support\Facades\Auth::class,
-        'Blade'        => Illuminate\Support\Facades\Blade::class,
-        'Bus'          => Illuminate\Support\Facades\Bus::class,
-        'Cache'        => Illuminate\Support\Facades\Cache::class,
-        'Config'       => Illuminate\Support\Facades\Config::class,
-        'Cookie'       => Illuminate\Support\Facades\Cookie::class,
-        'Crypt'        => Illuminate\Support\Facades\Crypt::class,
-        'Date'         => Illuminate\Support\Facades\Date::class,
-        'DB'           => Illuminate\Support\Facades\DB::class,
-        'Eloquent'     => Illuminate\Database\Eloquent\Model::class,
-        'Event'        => Illuminate\Support\Facades\Event::class,
-        'File'         => Illuminate\Support\Facades\File::class,
-        'Gate'         => Illuminate\Support\Facades\Gate::class,
-        'Hash'         => Illuminate\Support\Facades\Hash::class,
-        'Http'         => Illuminate\Support\Facades\Http::class,
-        'Lang'         => Illuminate\Support\Facades\Lang::class,
-        'Log'          => Illuminate\Support\Facades\Log::class,
-        'Mail'         => Illuminate\Support\Facades\Mail::class,
-        'Notification' => Illuminate\Support\Facades\Notification::class,
-        'Password'     => Illuminate\Support\Facades\Password::class,
-        'Queue'        => Illuminate\Support\Facades\Queue::class,
-        'RateLimiter'  => Illuminate\Support\Facades\RateLimiter::class,
-        'Redirect'     => Illuminate\Support\Facades\Redirect::class,
-        // 'Redis'        => Illuminate\Support\Facades\Redis::class,
-        'Request'      => Illuminate\Support\Facades\Request::class,
-        'Response'     => Illuminate\Support\Facades\Response::class,
-        'Route'        => Illuminate\Support\Facades\Route::class,
-        'Schema'       => Illuminate\Support\Facades\Schema::class,
-        'Session'      => Illuminate\Support\Facades\Session::class,
-        'Storage'      => Illuminate\Support\Facades\Storage::class,
-        'Str'          => Illuminate\Support\Str::class,
-        'URL'          => Illuminate\Support\Facades\URL::class,
-        'Validator'    => Illuminate\Support\Facades\Validator::class,
-        'View'         => Illuminate\Support\Facades\View::class,
-
+    // Class Aliases
+    // This array of class aliases to be registered on application start.
+    'aliases' => Facade::defaultAliases()->merge([
         // Laravel Packages
         'Socialite'    => Laravel\Socialite\Facades\Socialite::class,
 
@@ -205,7 +161,7 @@ return [
         // Custom BookStack
         'Activity'    => BookStack\Facades\Activity::class,
         'Theme'       => BookStack\Facades\Theme::class,
-    ],
+    ])->toArray(),
 
     // Proxy configuration
     'proxies' => env('APP_PROXIES', ''),

app/Config/broadcasting.php

@@ -14,7 +14,7 @@ return [
     // This option controls the default broadcaster that will be used by the
     // framework when an event needs to be broadcast. This can be set to
     // any of the connections defined in the "connections" array below.
-    'default' => env('BROADCAST_DRIVER', 'pusher'),
+    'default' => 'null',
 
     // Broadcast Connections
     // Here you may define all of the broadcast connections that will be used
@@ -22,21 +22,7 @@ return [
     // each available type of connection are provided inside this array.
     'connections' => [
 
-        'pusher' => [
-            'driver'  => 'pusher',
-            'key'     => env('PUSHER_APP_KEY'),
-            'secret'  => env('PUSHER_APP_SECRET'),
-            'app_id'  => env('PUSHER_APP_ID'),
-            'options' => [
-                'cluster' => env('PUSHER_APP_CLUSTER'),
-                'useTLS'  => true,
-            ],
-        ],
-
-        'redis' => [
-            'driver'     => 'redis',
-            'connection' => 'default',
-        ],
+        // Default options removed since we don't use broadcasting.
 
         'log' => [
             'driver' => 'log',

app/Config/cache.php

@@ -87,6 +87,6 @@ return [
     |
     */
 
-    'prefix' => env('CACHE_PREFIX', Str::slug(env('APP_NAME', 'laravel'), '_') . '_cache'),
+    'prefix' => env('CACHE_PREFIX', Str::slug(env('APP_NAME', 'laravel'), '_') . '_cache_'),
 
 ];

app/Config/dompdf.php

@@ -7,6 +7,7 @@
  * Configuration should be altered via the `.env` file or environment variables.
  * Do not edit this file unless you're happy to maintain any changes yourself.
  */
+
 $dompdfPaperSizeMap = [
     'a4'     => 'a4',
     'letter' => 'letter',

app/Config/filesystems.php

@@ -33,17 +33,20 @@ return [
             'driver'     => 'local',
             'root'       => public_path(),
             'visibility' => 'public',
+            'throw'      => true,
         ],
 
         'local_secure_attachments' => [
             'driver' => 'local',
             'root'   => storage_path('uploads/files/'),
+            'throw'  => true,
         ],
 
         'local_secure_images' => [
             'driver'     => 'local',
             'root'       => storage_path('uploads/images/'),
             'visibility' => 'public',
+            'throw'      => true,
         ],
 
         's3' => [
@@ -54,6 +57,7 @@ return [
             'bucket'                  => env('STORAGE_S3_BUCKET', 'your-bucket'),
             'endpoint'                => env('STORAGE_S3_ENDPOINT', null),
             'use_path_style_endpoint' => env('STORAGE_S3_ENDPOINT', null) !== null,
+            'throw'                   => true,
         ],
 
     ],

app/Config/logging.php

@@ -21,6 +21,15 @@ return [
     // one of the channels defined in the "channels" configuration array.
     'default' => env('LOG_CHANNEL', 'single'),
 
+    // Deprecations Log Channel
+    // This option controls the log channel that should be used to log warnings
+    // regarding deprecated PHP and library features. This allows you to get
+    // your application ready for upcoming major versions of dependencies.
+    'deprecations' => [
+        'channel' => 'null',
+        'trace' => false,
+    ],
+
     // Log Channels
     // Here you may configure the log channels for your application. Out of
     // the box, Laravel uses the Monolog PHP logging library. This gives

app/Config/mail.php

@@ -14,13 +14,7 @@ return [
     // From Laravel 7+ this is MAIL_MAILER in laravel.
     // Kept as MAIL_DRIVER in BookStack to prevent breaking change.
     // Options: smtp, sendmail, log, array
-    'driver' => env('MAIL_DRIVER', 'smtp'),
-
-    // SMTP host address
-    'host' => env('MAIL_HOST', 'smtp.mailgun.org'),
-
-    // SMTP host port
-    'port' => env('MAIL_PORT', 587),
+    'default' => env('MAIL_DRIVER', 'smtp'),
 
     // Global "From" address & name
     'from' => [
@@ -28,17 +22,42 @@ return [
         'name'    => env('MAIL_FROM_NAME', 'BookStack'),
     ],
 
-    // Email encryption protocol
-    'encryption' => env('MAIL_ENCRYPTION', 'tls'),
+    // Mailer Configurations
+    // Available mailing methods and their settings.
+    'mailers' => [
+        'smtp' => [
+            'transport' => 'smtp',
+            'host' => env('MAIL_HOST', 'smtp.mailgun.org'),
+            'port' => env('MAIL_PORT', 587),
+            'encryption' => env('MAIL_ENCRYPTION', 'tls'),
+            'username' => env('MAIL_USERNAME'),
+            'password' => env('MAIL_PASSWORD'),
+            'timeout' => null,
+            'local_domain' => env('MAIL_EHLO_DOMAIN'),
+        ],
 
-    // SMTP server username
-    'username' => env('MAIL_USERNAME'),
+        'sendmail' => [
+            'transport' => 'sendmail',
+            'path' => env('MAIL_SENDMAIL_COMMAND', '/usr/sbin/sendmail -bs'),
+        ],
 
-    // SMTP server password
-    'password' => env('MAIL_PASSWORD'),
+        'log' => [
+            'transport' => 'log',
+            'channel' => env('MAIL_LOG_CHANNEL'),
+        ],
 
-    // Sendmail application path
-    'sendmail' => '/usr/sbin/sendmail -bs',
+        'array' => [
+            'transport' => 'array',
+        ],
+
+        'failover' => [
+            'transport' => 'failover',
+            'mailers' => [
+                'smtp',
+                'log',
+            ],
+        ],
+    ],
 
     // Email markdown configuration
     'markdown' => [
@@ -47,11 +66,4 @@ return [
             resource_path('views/vendor/mail'),
         ],
     ],
-
-    // Log Channel
-    // If you are using the "log" driver, you may specify the logging channel
-    // if you prefer to keep mail messages separate from other log entries
-    // for simpler reading. Otherwise, the default channel will be used.
-    'log_channel' => env('MAIL_LOG_CHANNEL'),
-
 ];

app/Config/oidc.php

@@ -8,9 +8,12 @@ return [
     // Dump user details after a login request for debugging purposes
     'dump_user_details' => env('OIDC_DUMP_USER_DETAILS', false),
 
-    // Attribute, within a OpenId token, to find the user's display name
+    // Claim, within an OpenId token, to find the user's display name
     'display_name_claims' => explode('|', env('OIDC_DISPLAY_NAME_CLAIMS', 'name')),
 
+    // Claim, within an OpenID token, to use to connect a BookStack user to the OIDC user.
+    'external_id_claim' => env('OIDC_EXTERNAL_ID_CLAIM', 'sub'),
+
     // OAuth2/OpenId client id, as configured in your Authorization server.
     'client_id' => env('OIDC_CLIENT_ID', null),
 
@@ -32,4 +35,16 @@ return [
     // OAuth2 endpoints.
     'authorization_endpoint' => env('OIDC_AUTH_ENDPOINT', null),
     'token_endpoint'         => env('OIDC_TOKEN_ENDPOINT', null),
+
+    // Add extra scopes, upon those required, to the OIDC authentication request
+    // Multiple values can be provided comma seperated.
+    'additional_scopes' => env('OIDC_ADDITIONAL_SCOPES', null),
+
+    // Group sync options
+    // Enable syncing, upon login, of OIDC groups to BookStack roles
+    'user_to_groups' => env('OIDC_USER_TO_GROUPS', false),
+    // Attribute, within a OIDC ID token, to find group names within
+    'groups_claim' => env('OIDC_GROUPS_CLAIM', 'groups'),
+    // When syncing groups, remove any groups that no longer match. Otherwise sync only adds new groups.
+    'remove_from_groups' => env('OIDC_REMOVE_FROM_GROUPS', false),
 ];

app/Config/setting-defaults.php

@@ -16,16 +16,27 @@ return [
     'app-editor'           => 'wysiwyg',
     'app-color'            => '#206ea7',
     'app-color-light'      => 'rgba(32,110,167,0.15)',
+    'link-color'           => '#206ea7',
     'bookshelf-color'      => '#a94747',
     'book-color'           => '#077b70',
     'chapter-color'        => '#af4d0d',
     'page-color'           => '#206ea7',
     'page-draft-color'     => '#7e50b1',
+    'app-color-dark'       => '#195785',
+    'app-color-light-dark' => 'rgba(32,110,167,0.15)',
+    'link-color-dark'      => '#429fe3',
+    'bookshelf-color-dark' => '#ff5454',
+    'book-color-dark'      => '#389f60',
+    'chapter-color-dark'   => '#ee7a2d',
+    'page-color-dark'      => '#429fe3',
+    'page-draft-color-dark' => '#a66ce8',
     'app-custom-head'      => false,
     'registration-enabled' => false,
 
     // User-level default settings
     'user' => [
+        'ui-shortcuts'          => '{}',
+        'ui-shortcuts-enabled'  => false,
         'dark-mode-enabled'     => env('APP_DEFAULT_DARK_MODE', false),
         'bookshelves_view_type' => env('APP_VIEWS_BOOKSHELVES', 'grid'),
         'bookshelf_view_type'   => env('APP_VIEWS_BOOKSHELF', 'grid'),

app/Config/snappy.php

@@ -7,6 +7,7 @@
  * Configuration should be altered via the `.env` file or environment variables.
  * Do not edit this file unless you're happy to maintain any changes yourself.
  */
+
 $snappyPaperSizeMap = [
     'a4'     => 'A4',
     'letter' => 'Letter',

app/Console/Commands/CopyShelfPermissions.php

@@ -3,7 +3,7 @@
 namespace BookStack\Console\Commands;
 
 use BookStack\Entities\Models\Bookshelf;
-use BookStack\Entities\Repos\BookshelfRepo;
+use BookStack\Entities\Tools\PermissionsUpdater;
 use Illuminate\Console\Command;
 
 class CopyShelfPermissions extends Command
@@ -25,19 +25,16 @@ class CopyShelfPermissions extends Command
      */
     protected $description = 'Copy shelf permissions to all child books';
 
-    /**
-     * @var BookshelfRepo
-     */
-    protected $bookshelfRepo;
+    protected PermissionsUpdater $permissionsUpdater;
 
     /**
      * Create a new command instance.
      *
      * @return void
      */
-    public function __construct(BookshelfRepo $repo)
+    public function __construct(PermissionsUpdater $permissionsUpdater)
     {
-        $this->bookshelfRepo = $repo;
+        $this->permissionsUpdater = $permissionsUpdater;
         parent::__construct();
     }
 
@@ -69,18 +66,18 @@ class CopyShelfPermissions extends Command
                 return;
             }
 
-            $shelves = Bookshelf::query()->get(['id', 'restricted']);
+            $shelves = Bookshelf::query()->get(['id']);
         }
 
         if ($shelfSlug) {
-            $shelves = Bookshelf::query()->where('slug', '=', $shelfSlug)->get(['id', 'restricted']);
+            $shelves = Bookshelf::query()->where('slug', '=', $shelfSlug)->get(['id']);
             if ($shelves->count() === 0) {
                 $this->info('No shelves found with the given slug.');
             }
         }
 
         foreach ($shelves as $shelf) {
-            $this->bookshelfRepo->copyDownPermissions($shelf, false);
+            $this->permissionsUpdater->updateBookPermissionsFromShelf($shelf, false);
             $this->info('Copied permissions for shelf [' . $shelf->id . ']');
         }
 

app/Console/Commands/RegenerateCommentContent.php

@@ -5,6 +5,7 @@ namespace BookStack\Console\Commands;
 use BookStack\Actions\Comment;
 use BookStack\Actions\CommentRepo;
 use Illuminate\Console\Command;
+use Illuminate\Support\Facades\DB;
 
 class RegenerateCommentContent extends Command
 {
@@ -43,9 +44,9 @@ class RegenerateCommentContent extends Command
      */
     public function handle()
     {
-        $connection = \DB::getDefaultConnection();
+        $connection = DB::getDefaultConnection();
         if ($this->option('database') !== null) {
-            \DB::setDefaultConnection($this->option('database'));
+            DB::setDefaultConnection($this->option('database'));
         }
 
         Comment::query()->chunk(100, function ($comments) {
@@ -55,7 +56,9 @@ class RegenerateCommentContent extends Command
             }
         });
 
-        \DB::setDefaultConnection($connection);
+        DB::setDefaultConnection($connection);
         $this->comment('Comment HTML content has been regenerated');
+
+        return 0;
     }
 }

app/Console/Commands/RegeneratePermissions.php

@@ -50,5 +50,7 @@ class RegeneratePermissions extends Command
 
         DB::setDefaultConnection($connection);
         $this->comment('Permissions regenerated');
+
+        return 0;
     }
 }

app/Console/Commands/RegenerateReferences.php

@@ -0,0 +1,59 @@
+<?php
+
+namespace BookStack\Console\Commands;
+
+use BookStack\References\ReferenceStore;
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\DB;
+
+class RegenerateReferences extends Command
+{
+    /**
+     * The name and signature of the console command.
+     *
+     * @var string
+     */
+    protected $signature = 'bookstack:regenerate-references {--database= : The database connection to use.}';
+
+    /**
+     * The console command description.
+     *
+     * @var string
+     */
+    protected $description = 'Regenerate all the cross-item model reference index';
+
+    protected ReferenceStore $references;
+
+    /**
+     * Create a new command instance.
+     *
+     * @return void
+     */
+    public function __construct(ReferenceStore $references)
+    {
+        $this->references = $references;
+        parent::__construct();
+    }
+
+    /**
+     * Execute the console command.
+     *
+     * @return int
+     */
+    public function handle()
+    {
+        $connection = DB::getDefaultConnection();
+
+        if ($this->option('database')) {
+            DB::setDefaultConnection($this->option('database'));
+        }
+
+        $this->references->updateForAllPages();
+
+        DB::setDefaultConnection($connection);
+
+        $this->comment('References have been regenerated');
+
+        return 0;
+    }
+}

app/Console/Commands/RegenerateSearch.php

@@ -3,7 +3,7 @@
 namespace BookStack\Console\Commands;
 
 use BookStack\Entities\Models\Entity;
-use BookStack\Entities\Tools\SearchIndex;
+use BookStack\Search\SearchIndex;
 use Illuminate\Console\Command;
 use Illuminate\Support\Facades\DB;
 

app/Entities/Models/Book.php

@@ -19,6 +19,7 @@ use Illuminate\Support\Collection;
  * @property \Illuminate\Database\Eloquent\Collection $chapters
  * @property \Illuminate\Database\Eloquent\Collection $pages
  * @property \Illuminate\Database\Eloquent\Collection $directPages
+ * @property \Illuminate\Database\Eloquent\Collection $shelves
  */
 class Book extends Entity implements HasCoverImage
 {
@@ -27,7 +28,7 @@ class Book extends Entity implements HasCoverImage
     public $searchFactor = 1.2;
 
     protected $fillable = ['name', 'description'];
-    protected $hidden = ['restricted', 'pivot', 'image_id', 'deleted_at'];
+    protected $hidden = ['pivot', 'image_id', 'deleted_at'];
 
     /**
      * Get the url for this book.
@@ -119,4 +120,13 @@ class Book extends Entity implements HasCoverImage
 
         return $pages->concat($chapters)->sortBy('priority')->sortByDesc('draft');
     }
+
+    /**
+     * Get a visible book by its slug.
+     * @throws \Illuminate\Database\Eloquent\ModelNotFoundException
+     */
+    public static function getBySlug(string $slug): self
+    {
+        return static::visible()->where('slug', '=', $slug)->firstOrFail();
+    }
 }

app/Entities/Models/BookChild.php

@@ -2,6 +2,7 @@
 
 namespace BookStack\Entities\Models;
 
+use BookStack\References\ReferenceUpdater;
 use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
 
@@ -57,11 +58,16 @@ abstract class BookChild extends Entity
      */
     public function changeBook(int $newBookId): Entity
     {
+        $oldUrl = $this->getUrl();
         $this->book_id = $newBookId;
         $this->refreshSlug();
         $this->save();
         $this->refresh();
 
+        if ($oldUrl !== $this->getUrl()) {
+            app()->make(ReferenceUpdater::class)->updateEntityPageReferences($this, $oldUrl);
+        }
+
         // Update all child pages if a chapter
         if ($this instanceof Chapter) {
             foreach ($this->pages()->withTrashed()->get() as $page) {

app/Entities/Models/Bookshelf.php

@@ -17,7 +17,7 @@ class Bookshelf extends Entity implements HasCoverImage
 
     protected $fillable = ['name', 'description', 'image_id'];
 
-    protected $hidden = ['restricted', 'image_id', 'deleted_at'];
+    protected $hidden = ['image_id', 'deleted_at'];
 
     /**
      * Get the books in this shelf.
@@ -86,7 +86,7 @@ class Bookshelf extends Entity implements HasCoverImage
      */
     public function coverImageTypeKey(): string
     {
-        return 'cover_shelf';
+        return 'cover_bookshelf';
     }
 
     /**
@@ -109,4 +109,13 @@ class Bookshelf extends Entity implements HasCoverImage
         $maxOrder = $this->books()->max('order');
         $this->books()->attach($book->id, ['order' => $maxOrder + 1]);
     }
+
+    /**
+     * Get a visible shelf by its slug.
+     * @throws \Illuminate\Database\Eloquent\ModelNotFoundException
+     */
+    public static function getBySlug(string $slug): self
+    {
+        return static::visible()->where('slug', '=', $slug)->firstOrFail();
+    }
 }

app/Entities/Models/Chapter.php

@@ -19,7 +19,7 @@ class Chapter extends BookChild
     public $searchFactor = 1.2;
 
     protected $fillable = ['name', 'description', 'priority'];
-    protected $hidden = ['restricted', 'pivot', 'deleted_at'];
+    protected $hidden = ['pivot', 'deleted_at'];
 
     /**
      * Get the pages that this chapter contains.
@@ -58,4 +58,13 @@ class Chapter extends BookChild
         ->orderBy('priority', 'asc')
         ->get();
     }
+
+    /**
+     * Get a visible chapter by its book and page slugs.
+     * @throws \Illuminate\Database\Eloquent\ModelNotFoundException
+     */
+    public static function getBySlugs(string $bookSlug, string $chapterSlug): self
+    {
+        return static::visible()->whereSlugs($bookSlug, $chapterSlug)->firstOrFail();
+    }
 }

app/Entities/Models/Entity.php

@@ -11,7 +11,6 @@ use BookStack\Auth\Permissions\EntityPermission;
 use BookStack\Auth\Permissions\JointPermission;
 use BookStack\Auth\Permissions\JointPermissionBuilder;
 use BookStack\Auth\Permissions\PermissionApplicator;
-use BookStack\Entities\Tools\SearchIndex;
 use BookStack\Entities\Tools\SlugGenerator;
 use BookStack\Interfaces\Deletable;
 use BookStack\Interfaces\Favouritable;
@@ -19,6 +18,9 @@ use BookStack\Interfaces\Loggable;
 use BookStack\Interfaces\Sluggable;
 use BookStack\Interfaces\Viewable;
 use BookStack\Model;
+use BookStack\References\Reference;
+use BookStack\Search\SearchIndex;
+use BookStack\Search\SearchTerm;
 use BookStack\Traits\HasCreatorAndUpdater;
 use BookStack\Traits\HasOwner;
 use Carbon\Carbon;
@@ -40,7 +42,6 @@ use Illuminate\Database\Eloquent\SoftDeletes;
  * @property Carbon     $deleted_at
  * @property int        $created_by
  * @property int        $updated_by
- * @property bool       $restricted
  * @property Collection $tags
  *
  * @method static Entity|Builder visible()
@@ -174,16 +175,15 @@ abstract class Entity extends Model implements Sluggable, Favouritable, Viewable
      */
     public function permissions(): MorphMany
     {
-        return $this->morphMany(EntityPermission::class, 'restrictable');
+        return $this->morphMany(EntityPermission::class, 'entity');
     }
 
     /**
      * Check if this entity has a specific restriction set against it.
      */
-    public function hasRestriction(int $role_id, string $action): bool
+    public function hasPermissions(): bool
     {
-        return $this->permissions()->where('role_id', '=', $role_id)
-            ->where('action', '=', $action)->count() > 0;
+        return $this->permissions()->count() > 0;
     }
 
     /**
@@ -202,6 +202,22 @@ abstract class Entity extends Model implements Sluggable, Favouritable, Viewable
         return $this->morphMany(Deletion::class, 'deletable');
     }
 
+    /**
+     * Get the references pointing from this entity to other items.
+     */
+    public function referencesFrom(): MorphMany
+    {
+        return $this->morphMany(Reference::class, 'from');
+    }
+
+    /**
+     * Get the references pointing to this entity from other items.
+     */
+    public function referencesTo(): MorphMany
+    {
+        return $this->morphMany(Reference::class, 'to');
+    }
+
     /**
      * Check if this instance or class is a certain type of entity.
      * Examples of $type are 'page', 'book', 'chapter'.

app/Entities/Models/Page.php

@@ -39,7 +39,7 @@ class Page extends BookChild
 
     public $textField = 'text';
 
-    protected $hidden = ['html', 'markdown', 'text', 'restricted', 'pivot', 'deleted_at'];
+    protected $hidden = ['html', 'markdown', 'text', 'pivot', 'deleted_at'];
 
     protected $casts = [
         'draft'    => 'boolean',
@@ -88,8 +88,6 @@ class Page extends BookChild
 
     /**
      * Get the current revision for the page if existing.
-     *
-     * @return PageRevision|null
      */
     public function currentRevision(): HasOne
     {
@@ -145,4 +143,13 @@ class Page extends BookChild
 
         return $refreshed;
     }
+
+    /**
+     * Get a visible page by its book and page slugs.
+     * @throws \Illuminate\Database\Eloquent\ModelNotFoundException
+     */
+    public static function getBySlugs(string $bookSlug, string $pageSlug): self
+    {
+        return static::visible()->whereSlugs($bookSlug, $pageSlug)->firstOrFail();
+    }
 }

app/Entities/Models/PageRevision.php

@@ -3,6 +3,7 @@
 namespace BookStack\Entities\Models;
 
 use BookStack\Auth\User;
+use BookStack\Interfaces\Loggable;
 use BookStack\Model;
 use Carbon\Carbon;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
@@ -27,10 +28,10 @@ use Illuminate\Database\Eloquent\Relations\BelongsTo;
  * @property Page   $page
  * @property-read ?User $createdBy
  */
-class PageRevision extends Model
+class PageRevision extends Model implements Loggable
 {
     protected $fillable = ['name', 'text', 'summary'];
-    protected $hidden = ['html', 'markdown', 'restricted', 'text'];
+    protected $hidden = ['html', 'markdown', 'text'];
 
     /**
      * Get the user that created the page revision.
@@ -83,4 +84,9 @@ class PageRevision extends Model
     {
         return $type === 'revision';
     }
+
+    public function logDescriptor(): string
+    {
+        return "Revision #{$this->revision_number} (ID: {$this->id}) for page ID {$this->page_id}";
+    }
 }

app/Entities/Repos/BaseRepo.php

@@ -6,6 +6,7 @@ use BookStack\Actions\TagRepo;
 use BookStack\Entities\Models\Entity;
 use BookStack\Entities\Models\HasCoverImage;
 use BookStack\Exceptions\ImageUploadException;
+use BookStack\References\ReferenceUpdater;
 use BookStack\Uploads\ImageRepo;
 use Illuminate\Http\UploadedFile;
 
@@ -13,11 +14,13 @@ class BaseRepo
 {
     protected TagRepo $tagRepo;
     protected ImageRepo $imageRepo;
+    protected ReferenceUpdater $referenceUpdater;
 
-    public function __construct(TagRepo $tagRepo, ImageRepo $imageRepo)
+    public function __construct(TagRepo $tagRepo, ImageRepo $imageRepo, ReferenceUpdater $referenceUpdater)
     {
         $this->tagRepo = $tagRepo;
         $this->imageRepo = $imageRepo;
+        $this->referenceUpdater = $referenceUpdater;
     }
 
     /**
@@ -38,6 +41,7 @@ class BaseRepo
             $this->tagRepo->saveTagsToEntity($entity, $input['tags']);
         }
 
+        $entity->refresh();
         $entity->rebuildPermissions();
         $entity->indexForSearch();
     }
@@ -47,10 +51,12 @@ class BaseRepo
      */
     public function update(Entity $entity, array $input)
     {
+        $oldUrl = $entity->getUrl();
+
         $entity->fill($input);
         $entity->updated_by = user()->id;
 
-        if ($entity->isDirty('name')) {
+        if ($entity->isDirty('name') || empty($entity->slug)) {
             $entity->refreshSlug();
         }
 
@@ -63,6 +69,10 @@ class BaseRepo
 
         $entity->rebuildPermissions();
         $entity->indexForSearch();
+
+        if ($oldUrl !== $entity->getUrl()) {
+            $this->referenceUpdater->updateEntityPageReferences($entity, $oldUrl);
+        }
     }
 
     /**
@@ -76,14 +86,15 @@ class BaseRepo
     public function updateCoverImage($entity, ?UploadedFile $coverImage, bool $removeImage = false)
     {
         if ($coverImage) {
-            $this->imageRepo->destroyImage($entity->cover);
-            $image = $this->imageRepo->saveNew($coverImage, 'cover_book', $entity->id, 512, 512, true);
+            $imageType = $entity->coverImageTypeKey();
+            $this->imageRepo->destroyImage($entity->cover()->first());
+            $image = $this->imageRepo->saveNew($coverImage, $imageType, $entity->id, 512, 512, true);
             $entity->cover()->associate($image);
             $entity->save();
         }
 
         if ($removeImage) {
-            $this->imageRepo->destroyImage($entity->cover);
+            $this->imageRepo->destroyImage($entity->cover()->first());
             $entity->image_id = 0;
             $entity->save();
         }

app/Entities/Repos/BookshelfRepo.php

@@ -134,31 +134,6 @@ class BookshelfRepo
         $shelf->books()->sync($syncData);
     }
 
-    /**
-     * Copy down the permissions of the given shelf to all child books.
-     */
-    public function copyDownPermissions(Bookshelf $shelf, $checkUserPermissions = true): int
-    {
-        $shelfPermissions = $shelf->permissions()->get(['role_id', 'action'])->toArray();
-        $shelfBooks = $shelf->books()->get(['id', 'restricted']);
-        $updatedBookCount = 0;
-
-        /** @var Book $book */
-        foreach ($shelfBooks as $book) {
-            if ($checkUserPermissions && !userCan('restrictions-manage', $book)) {
-                continue;
-            }
-            $book->permissions()->delete();
-            $book->restricted = $shelf->restricted;
-            $book->permissions()->createMany($shelfPermissions);
-            $book->save();
-            $book->rebuildPermissions();
-            $updatedBookCount++;
-        }
-
-        return $updatedBookCount;
-    }
-
     /**
      * Remove a bookshelf from the system.
      *

app/Entities/Repos/PageRepo.php

@@ -16,20 +16,31 @@ use BookStack\Exceptions\MoveOperationException;
 use BookStack\Exceptions\NotFoundException;
 use BookStack\Exceptions\PermissionsException;
 use BookStack\Facades\Activity;
+use BookStack\References\ReferenceStore;
+use BookStack\References\ReferenceUpdater;
 use Exception;
-use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Pagination\LengthAwarePaginator;
 
 class PageRepo
 {
-    protected $baseRepo;
+    protected BaseRepo $baseRepo;
+    protected RevisionRepo $revisionRepo;
+    protected ReferenceStore $referenceStore;
+    protected ReferenceUpdater $referenceUpdater;
 
     /**
      * PageRepo constructor.
      */
-    public function __construct(BaseRepo $baseRepo)
-    {
+    public function __construct(
+        BaseRepo $baseRepo,
+        RevisionRepo $revisionRepo,
+        ReferenceStore $referenceStore,
+        ReferenceUpdater $referenceUpdater
+    ) {
         $this->baseRepo = $baseRepo;
+        $this->revisionRepo = $revisionRepo;
+        $this->referenceStore = $referenceStore;
+        $this->referenceUpdater = $referenceUpdater;
     }
 
     /**
@@ -39,6 +50,7 @@ class PageRepo
      */
     public function getById(int $id, array $relations = ['book']): Page
     {
+        /** @var Page $page */
         $page = Page::visible()->with($relations)->find($id);
 
         if (!$page) {
@@ -70,17 +82,7 @@ class PageRepo
      */
     public function getByOldSlug(string $bookSlug, string $pageSlug): ?Page
     {
-        /** @var ?PageRevision $revision */
-        $revision = PageRevision::query()
-            ->whereHas('page', function (Builder $query) {
-                $query->scopes('visible');
-            })
-            ->where('slug', '=', $pageSlug)
-            ->where('type', '=', 'version')
-            ->where('book_slug', '=', $bookSlug)
-            ->orderBy('created_at', 'desc')
-            ->with('page')
-            ->first();
+        $revision = $this->revisionRepo->getBySlugs($bookSlug, $pageSlug);
 
         return $revision->page ?? null;
     }
@@ -112,7 +114,7 @@ class PageRepo
     public function getParentFromSlugs(string $bookSlug, string $chapterSlug = null): Entity
     {
         if ($chapterSlug !== null) {
-            return $chapter = Chapter::visible()->whereSlugs($bookSlug, $chapterSlug)->firstOrFail();
+            return Chapter::visible()->whereSlugs($bookSlug, $chapterSlug)->firstOrFail();
         }
 
         return Book::visible()->where('slug', '=', $bookSlug)->firstOrFail();
@@ -123,9 +125,7 @@ class PageRepo
      */
     public function getUserDraft(Page $page): ?PageRevision
     {
-        $revision = $this->getUserDraftQuery($page)->first();
-
-        return $revision;
+        return $this->revisionRepo->getLatestDraftForCurrentUser($page);
     }
 
     /**
@@ -165,11 +165,10 @@ class PageRepo
         $draft->draft = false;
         $draft->revision_count = 1;
         $draft->priority = $this->getNewPriority($draft);
-        $draft->refreshSlug();
         $draft->save();
 
-        $this->savePageRevision($draft, trans('entities.pages_initial_revision'));
-        $draft->indexForSearch();
+        $this->revisionRepo->storeNewForPage($draft, trans('entities.pages_initial_revision'));
+        $this->referenceStore->updateForPage($draft);
         $draft->refresh();
 
         Activity::add(ActivityType::PAGE_CREATE, $draft);
@@ -189,13 +188,14 @@ class PageRepo
 
         $this->updateTemplateStatusAndContentFromInput($page, $input);
         $this->baseRepo->update($page, $input);
+        $this->referenceStore->updateForPage($page);
 
         // Update with new details
         $page->revision_count++;
         $page->save();
 
         // Remove all update drafts for this user & page.
-        $this->getUserDraftQuery($page)->delete();
+        $this->revisionRepo->deleteDraftsForCurrentUser($page);
 
         // Save a revision after updating
         $summary = trim($input['summary'] ?? '');
@@ -203,7 +203,7 @@ class PageRepo
         $nameChanged = isset($input['name']) && $input['name'] !== $oldName;
         $markdownChanged = isset($input['markdown']) && $input['markdown'] !== $oldMarkdown;
         if ($htmlChanged || $nameChanged || $markdownChanged || $summary) {
-            $this->savePageRevision($page, $summary);
+            $this->revisionRepo->storeNewForPage($page, $summary);
         }
 
         Activity::add(ActivityType::PAGE_UPDATE, $page);
@@ -239,32 +239,6 @@ class PageRepo
         }
     }
 
-    /**
-     * Saves a page revision into the system.
-     */
-    protected function savePageRevision(Page $page, string $summary = null): PageRevision
-    {
-        $revision = new PageRevision();
-
-        $revision->name = $page->name;
-        $revision->html = $page->html;
-        $revision->markdown = $page->markdown;
-        $revision->text = $page->text;
-        $revision->page_id = $page->id;
-        $revision->slug = $page->slug;
-        $revision->book_slug = $page->book->slug;
-        $revision->created_by = user()->id;
-        $revision->created_at = $page->updated_at;
-        $revision->type = 'version';
-        $revision->summary = $summary;
-        $revision->revision_number = $page->revision_count;
-        $revision->save();
-
-        $this->deleteOldRevisions($page);
-
-        return $revision;
-    }
-
     /**
      * Save a page update draft.
      */
@@ -280,7 +254,7 @@ class PageRepo
         }
 
         // Otherwise, save the data to a revision
-        $draft = $this->getPageRevisionToUpdate($page);
+        $draft = $this->revisionRepo->getNewDraftForCurrentUser($page);
         $draft->fill($input);
 
         if (!empty($input['markdown'])) {
@@ -314,6 +288,7 @@ class PageRepo
      */
     public function restoreRevision(Page $page, int $revisionId): Page
     {
+        $oldUrl = $page->getUrl();
         $page->revision_count++;
 
         /** @var PageRevision $revision */
@@ -332,11 +307,17 @@ class PageRepo
         $page->refreshSlug();
         $page->save();
         $page->indexForSearch();
+        $this->referenceStore->updateForPage($page);
 
         $summary = trans('entities.pages_revision_restored_from', ['id' => strval($revisionId), 'summary' => $revision->summary]);
-        $this->savePageRevision($page, $summary);
+        $this->revisionRepo->storeNewForPage($page, $summary);
+
+        if ($oldUrl !== $page->getUrl()) {
+            $this->referenceUpdater->updateEntityPageReferences($page, $oldUrl);
+        }
 
         Activity::add(ActivityType::PAGE_RESTORE, $page);
+        Activity::add(ActivityType::REVISION_RESTORE, $revision);
 
         return $page;
     }
@@ -392,48 +373,6 @@ class PageRepo
         return $parentClass::visible()->where('id', '=', $entityId)->first();
     }
 
-    /**
-     * Get a page revision to update for the given page.
-     * Checks for an existing revisions before providing a fresh one.
-     */
-    protected function getPageRevisionToUpdate(Page $page): PageRevision
-    {
-        $drafts = $this->getUserDraftQuery($page)->get();
-        if ($drafts->count() > 0) {
-            return $drafts->first();
-        }
-
-        $draft = new PageRevision();
-        $draft->page_id = $page->id;
-        $draft->slug = $page->slug;
-        $draft->book_slug = $page->book->slug;
-        $draft->created_by = user()->id;
-        $draft->type = 'update_draft';
-
-        return $draft;
-    }
-
-    /**
-     * Delete old revisions, for the given page, from the system.
-     */
-    protected function deleteOldRevisions(Page $page)
-    {
-        $revisionLimit = config('app.revision_limit');
-        if ($revisionLimit === false) {
-            return;
-        }
-
-        $revisionsToDelete = PageRevision::query()
-            ->where('page_id', '=', $page->id)
-            ->orderBy('created_at', 'desc')
-            ->skip(intval($revisionLimit))
-            ->take(10)
-            ->get(['id']);
-        if ($revisionsToDelete->count() > 0) {
-            PageRevision::query()->whereIn('id', $revisionsToDelete->pluck('id'))->delete();
-        }
-    }
-
     /**
      * Get a new priority for a page.
      */
@@ -449,15 +388,4 @@ class PageRepo
 
         return (new BookContents($page->book))->getLastPriority() + 1;
     }
-
-    /**
-     * Get the query to find the user's draft copies of the given page.
-     */
-    protected function getUserDraftQuery(Page $page)
-    {
-        return PageRevision::query()->where('created_by', '=', user()->id)
-            ->where('type', 'update_draft')
-            ->where('page_id', '=', $page->id)
-            ->orderBy('created_at', 'desc');
-    }
 }

app/Entities/Repos/RevisionRepo.php

@@ -0,0 +1,131 @@
+<?php
+
+namespace BookStack\Entities\Repos;
+
+use BookStack\Entities\Models\Page;
+use BookStack\Entities\Models\PageRevision;
+use Illuminate\Database\Eloquent\Builder;
+
+class RevisionRepo
+{
+    /**
+     * Get a revision by its stored book and page slug values.
+     */
+    public function getBySlugs(string $bookSlug, string $pageSlug): ?PageRevision
+    {
+        /** @var ?PageRevision $revision */
+        $revision = PageRevision::query()
+            ->whereHas('page', function (Builder $query) {
+                $query->scopes('visible');
+            })
+            ->where('slug', '=', $pageSlug)
+            ->where('type', '=', 'version')
+            ->where('book_slug', '=', $bookSlug)
+            ->orderBy('created_at', 'desc')
+            ->with('page')
+            ->first();
+
+        return $revision;
+    }
+
+    /**
+     * Get the latest draft revision, for the given page, belonging to the current user.
+     */
+    public function getLatestDraftForCurrentUser(Page $page): ?PageRevision
+    {
+        /** @var ?PageRevision $revision */
+        $revision = $this->queryForCurrentUserDraft($page->id)->first();
+
+        return $revision;
+    }
+
+    /**
+     * Delete all drafts revisions, for the given page, belonging to the current user.
+     */
+    public function deleteDraftsForCurrentUser(Page $page): void
+    {
+        $this->queryForCurrentUserDraft($page->id)->delete();
+    }
+
+    /**
+     * Get a user update_draft page revision to update for the given page.
+     * Checks for an existing revisions before providing a fresh one.
+     */
+    public function getNewDraftForCurrentUser(Page $page): PageRevision
+    {
+        $draft = $this->getLatestDraftForCurrentUser($page);
+
+        if ($draft) {
+            return $draft;
+        }
+
+        $draft = new PageRevision();
+        $draft->page_id = $page->id;
+        $draft->slug = $page->slug;
+        $draft->book_slug = $page->book->slug;
+        $draft->created_by = user()->id;
+        $draft->type = 'update_draft';
+
+        return $draft;
+    }
+
+    /**
+     * Store a new revision in the system for the given page.
+     */
+    public function storeNewForPage(Page $page, string $summary = null): PageRevision
+    {
+        $revision = new PageRevision();
+
+        $revision->name = $page->name;
+        $revision->html = $page->html;
+        $revision->markdown = $page->markdown;
+        $revision->text = $page->text;
+        $revision->page_id = $page->id;
+        $revision->slug = $page->slug;
+        $revision->book_slug = $page->book->slug;
+        $revision->created_by = user()->id;
+        $revision->created_at = $page->updated_at;
+        $revision->type = 'version';
+        $revision->summary = $summary;
+        $revision->revision_number = $page->revision_count;
+        $revision->save();
+
+        $this->deleteOldRevisions($page);
+
+        return $revision;
+    }
+
+    /**
+     * Delete old revisions, for the given page, from the system.
+     */
+    protected function deleteOldRevisions(Page $page)
+    {
+        $revisionLimit = config('app.revision_limit');
+        if ($revisionLimit === false) {
+            return;
+        }
+
+        $revisionsToDelete = PageRevision::query()
+            ->where('page_id', '=', $page->id)
+            ->orderBy('created_at', 'desc')
+            ->skip(intval($revisionLimit))
+            ->take(10)
+            ->get(['id']);
+
+        if ($revisionsToDelete->count() > 0) {
+            PageRevision::query()->whereIn('id', $revisionsToDelete->pluck('id'))->delete();
+        }
+    }
+
+    /**
+     * Query update draft revisions for the current user.
+     */
+    protected function queryForCurrentUserDraft(int $pageId): Builder
+    {
+        return PageRevision::query()
+            ->where('created_by', '=', user()->id)
+            ->where('type', 'update_draft')
+            ->where('page_id', '=', $pageId)
+            ->orderBy('created_at', 'desc');
+    }
+}

app/Entities/Tools/BookContents.php

@@ -11,22 +11,15 @@ use Illuminate\Support\Collection;
 
 class BookContents
 {
-    /**
-     * @var Book
-     */
-    protected $book;
+    protected Book $book;
 
-    /**
-     * BookContents constructor.
-     */
     public function __construct(Book $book)
     {
         $this->book = $book;
     }
 
     /**
-     * Get the current priority of the last item
-     * at the top-level of the book.
+     * Get the current priority of the last item at the top-level of the book.
      */
     public function getLastPriority(): int
     {
@@ -188,7 +181,7 @@ class BookContents
             $model->changeBook($newBook->id);
         }
 
-        if ($chapterChanged) {
+        if ($model instanceof Page && $chapterChanged) {
             $model->chapter_id = $newChapter->id ?? 0;
         }
 
@@ -242,7 +235,7 @@ class BookContents
             }
 
             $hasPageEditPermission = userCan('page-update', $model);
-            $newParentInRightLocation = ($newParent instanceof Book || $newParent->book_id === $newBook->id);
+            $newParentInRightLocation = ($newParent instanceof Book || ($newParent instanceof Chapter && $newParent->book_id === $newBook->id));
             $newParentPermission = ($newParent instanceof Chapter) ? 'chapter-update' : 'book-update';
             $hasNewParentPermission = userCan($newParentPermission, $newParent);
 

app/Entities/Tools/Cloner.php

@@ -4,8 +4,10 @@ namespace BookStack\Entities\Tools;
 
 use BookStack\Actions\Tag;
 use BookStack\Entities\Models\Book;
+use BookStack\Entities\Models\Bookshelf;
 use BookStack\Entities\Models\Chapter;
 use BookStack\Entities\Models\Entity;
+use BookStack\Entities\Models\HasCoverImage;
 use BookStack\Entities\Models\Page;
 use BookStack\Entities\Repos\BookRepo;
 use BookStack\Entities\Repos\ChapterRepo;
@@ -71,8 +73,10 @@ class Cloner
         $bookDetails = $this->entityToInputData($original);
         $bookDetails['name'] = $newName;
 
+        // Clone book
         $copyBook = $this->bookRepo->create($bookDetails);
 
+        // Clone contents
         $directChildren = $original->getDirectChildren();
         foreach ($directChildren as $child) {
             if ($child instanceof Chapter && userCan('chapter-create', $copyBook)) {
@@ -84,6 +88,14 @@ class Cloner
             }
         }
 
+        // Clone bookshelf relationships
+        /** @var Bookshelf $shelf */
+        foreach ($original->shelves as $shelf) {
+            if (userCan('bookshelf-update', $shelf)) {
+                $shelf->appendBook($copyBook);
+            }
+        }
+
         return $copyBook;
     }
 
@@ -98,9 +110,11 @@ class Cloner
         $inputData['tags'] = $this->entityTagsToInputArray($entity);
 
         // Add a cover to the data if existing on the original entity
-        if ($entity->cover instanceof Image) {
-            $uploadedFile = $this->imageToUploadedFile($entity->cover);
-            $inputData['image'] = $uploadedFile;
+        if ($entity instanceof HasCoverImage) {
+            $cover = $entity->cover()->first();
+            if ($cover) {
+                $inputData['image'] = $this->imageToUploadedFile($cover);
+            }
         }
 
         return $inputData;
@@ -111,8 +125,7 @@ class Cloner
      */
     public function copyEntityPermissions(Entity $sourceEntity, Entity $targetEntity): void
     {
-        $targetEntity->restricted = $sourceEntity->restricted;
-        $permissions = $sourceEntity->permissions()->get(['role_id', 'action'])->toArray();
+        $permissions = $sourceEntity->permissions()->get(['role_id', 'view', 'create', 'update', 'delete'])->toArray();
         $targetEntity->permissions()->delete();
         $targetEntity->permissions()->createMany($permissions);
         $targetEntity->rebuildPermissions();

app/Entities/Tools/ExportFormatter.php

@@ -235,7 +235,7 @@ class ExportFormatter
         $linksOutput = [];
         preg_match_all("/\<a.*href\=(\'|\")(.*?)(\'|\").*?\>/i", $htmlContent, $linksOutput);
 
-        // Replace image src with base64 encoded image strings
+        // Update relative links to be absolute, with instance url
         if (isset($linksOutput[0]) && count($linksOutput[0]) > 0) {
             foreach ($linksOutput[0] as $index => $linkMatch) {
                 $oldLinkString = $linkMatch;
@@ -248,7 +248,6 @@ class ExportFormatter
             }
         }
 
-        // Replace any relative links with system domain
         return $htmlContent;
     }
 

app/Entities/Tools/HierarchyTransformer.php

@@ -65,7 +65,7 @@ class HierarchyTransformer
         foreach ($book->chapters as $index => $chapter) {
             $newBook = $this->transformChapterToBook($chapter);
             $shelfBookSyncData[$newBook->id] = ['order' => $index];
-            if (!$newBook->restricted) {
+            if (!$newBook->hasPermissions()) {
                 $this->cloner->copyEntityPermissions($shelf, $newBook);
             }
         }

app/Entities/Tools/Markdown/CustomListItemRenderer.php

@@ -2,18 +2,18 @@
 
 namespace BookStack\Entities\Tools\Markdown;
 
-use League\CommonMark\Block\Element\AbstractBlock;
-use League\CommonMark\Block\Element\ListItem;
-use League\CommonMark\Block\Element\Paragraph;
-use League\CommonMark\Block\Renderer\BlockRendererInterface;
-use League\CommonMark\Block\Renderer\ListItemRenderer;
-use League\CommonMark\ElementRendererInterface;
+use League\CommonMark\Extension\CommonMark\Node\Block\ListItem;
+use League\CommonMark\Extension\CommonMark\Renderer\Block\ListItemRenderer;
 use League\CommonMark\Extension\TaskList\TaskListItemMarker;
-use League\CommonMark\HtmlElement;
+use League\CommonMark\Node\Block\Paragraph;
+use League\CommonMark\Node\Node;
+use League\CommonMark\Renderer\ChildNodeRendererInterface;
+use League\CommonMark\Renderer\NodeRendererInterface;
+use League\CommonMark\Util\HtmlElement;
 
-class CustomListItemRenderer implements BlockRendererInterface
+class CustomListItemRenderer implements NodeRendererInterface
 {
-    protected $baseRenderer;
+    protected ListItemRenderer $baseRenderer;
 
     public function __construct()
     {
@@ -23,11 +23,11 @@ class CustomListItemRenderer implements BlockRendererInterface
     /**
      * @return HtmlElement|string|null
      */
-    public function render(AbstractBlock $block, ElementRendererInterface $htmlRenderer, bool $inTightList = false)
+    public function render(Node $node, ChildNodeRendererInterface $childRenderer)
     {
-        $listItem = $this->baseRenderer->render($block, $htmlRenderer, $inTightList);
+        $listItem = $this->baseRenderer->render($node, $childRenderer);
 
-        if ($this->startsTaskListItem($block)) {
+        if ($node instanceof ListItem && $this->startsTaskListItem($node) && $listItem instanceof HtmlElement) {
             $listItem->setAttribute('class', 'task-list-item');
         }
 

app/Entities/Tools/Markdown/CustomStrikeThroughExtension.php

@@ -2,16 +2,16 @@
 
 namespace BookStack\Entities\Tools\Markdown;
 
-use League\CommonMark\ConfigurableEnvironmentInterface;
+use League\CommonMark\Environment\EnvironmentBuilderInterface;
 use League\CommonMark\Extension\ExtensionInterface;
 use League\CommonMark\Extension\Strikethrough\Strikethrough;
 use League\CommonMark\Extension\Strikethrough\StrikethroughDelimiterProcessor;
 
 class CustomStrikeThroughExtension implements ExtensionInterface
 {
-    public function register(ConfigurableEnvironmentInterface $environment)
+    public function register(EnvironmentBuilderInterface $environment): void
     {
         $environment->addDelimiterProcessor(new StrikethroughDelimiterProcessor());
-        $environment->addInlineRenderer(Strikethrough::class, new CustomStrikethroughRenderer());
+        $environment->addRenderer(Strikethrough::class, new CustomStrikethroughRenderer());
     }
 }

app/Entities/Tools/Markdown/CustomStrikethroughRenderer.php

@@ -2,25 +2,23 @@
 
 namespace BookStack\Entities\Tools\Markdown;
 
-use League\CommonMark\ElementRendererInterface;
 use League\CommonMark\Extension\Strikethrough\Strikethrough;
-use League\CommonMark\HtmlElement;
-use League\CommonMark\Inline\Element\AbstractInline;
-use League\CommonMark\Inline\Renderer\InlineRendererInterface;
+use League\CommonMark\Node\Node;
+use League\CommonMark\Renderer\ChildNodeRendererInterface;
+use League\CommonMark\Renderer\NodeRendererInterface;
+use League\CommonMark\Util\HtmlElement;
 
 /**
  * This is a somewhat clone of the League\CommonMark\Extension\Strikethrough\StrikethroughRender
  * class but modified slightly to use <s> HTML tags instead of <del> in order to
  * match front-end markdown-it rendering.
  */
-class CustomStrikethroughRenderer implements InlineRendererInterface
+class CustomStrikethroughRenderer implements NodeRendererInterface
 {
-    public function render(AbstractInline $inline, ElementRendererInterface $htmlRenderer)
+    public function render(Node $node, ChildNodeRendererInterface $childRenderer)
     {
-        if (!($inline instanceof Strikethrough)) {
-            throw new \InvalidArgumentException('Incompatible inline type: ' . get_class($inline));
-        }
+        Strikethrough::assertInstanceOf($node);
 
-        return new HtmlElement('s', $inline->getData('attributes', []), $htmlRenderer->renderInlines($inline->children()));
+        return new HtmlElement('s', $node->data->get('attributes'), $childRenderer->renderNodes($node->children()));
     }
 }

app/Entities/Tools/Markdown/MarkdownToHtml.php

@@ -4,11 +4,12 @@ namespace BookStack\Entities\Tools\Markdown;
 
 use BookStack\Facades\Theme;
 use BookStack\Theming\ThemeEvents;
-use League\CommonMark\Block\Element\ListItem;
-use League\CommonMark\CommonMarkConverter;
-use League\CommonMark\Environment;
+use League\CommonMark\Environment\Environment;
+use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension;
+use League\CommonMark\Extension\CommonMark\Node\Block\ListItem;
 use League\CommonMark\Extension\Table\TableExtension;
 use League\CommonMark\Extension\TaskList\TaskListExtension;
+use League\CommonMark\MarkdownConverter;
 
 class MarkdownToHtml
 {
@@ -21,15 +22,16 @@ class MarkdownToHtml
 
     public function convert(): string
     {
-        $environment = Environment::createCommonMarkEnvironment();
+        $environment = new Environment();
+        $environment->addExtension(new CommonMarkCoreExtension());
         $environment->addExtension(new TableExtension());
         $environment->addExtension(new TaskListExtension());
         $environment->addExtension(new CustomStrikeThroughExtension());
         $environment = Theme::dispatch(ThemeEvents::COMMONMARK_ENVIRONMENT_CONFIGURE, $environment) ?? $environment;
-        $converter = new CommonMarkConverter([], $environment);
+        $converter = new MarkdownConverter($environment);
 
-        $environment->addBlockRenderer(ListItem::class, new CustomListItemRenderer(), 10);
+        $environment->addRenderer(ListItem::class, new CustomListItemRenderer(), 10);
 
-        return $converter->convertToHtml($this->markdown);
+        return $converter->convert($this->markdown)->getContent();
     }
 }

app/Entities/Tools/PageContent.php

@@ -5,6 +5,8 @@ namespace BookStack\Entities\Tools;
 use BookStack\Entities\Models\Page;
 use BookStack\Entities\Tools\Markdown\MarkdownToHtml;
 use BookStack\Exceptions\ImageUploadException;
+use BookStack\Facades\Theme;
+use BookStack\Theming\ThemeEvents;
 use BookStack\Uploads\ImageRepo;
 use BookStack\Uploads\ImageService;
 use BookStack\Util\HtmlContentFilter;
@@ -17,20 +19,15 @@ use Illuminate\Support\Str;
 
 class PageContent
 {
-    protected Page $page;
-
-    /**
-     * PageContent constructor.
-     */
-    public function __construct(Page $page)
-    {
-        $this->page = $page;
+    public function __construct(
+        protected Page $page
+    ) {
     }
 
     /**
      * Update the content of the page with new provided HTML.
      */
-    public function setNewHTML(string $html)
+    public function setNewHTML(string $html): void
     {
         $html = $this->extractBase64ImagesFromHtml($html);
         $this->page->html = $this->formatHtml($html);
@@ -41,7 +38,7 @@ class PageContent
     /**
      * Update the content of the page with new provided Markdown content.
      */
-    public function setNewMarkdown(string $markdown)
+    public function setNewMarkdown(string $markdown): void
     {
         $markdown = $this->extractBase64ImagesFromMarkdown($markdown);
         $this->page->markdown = $markdown;
@@ -55,7 +52,7 @@ class PageContent
      */
     protected function extractBase64ImagesFromHtml(string $htmlText): string
     {
-        if (empty($htmlText) || strpos($htmlText, 'data:image') === false) {
+        if (empty($htmlText) || !str_contains($htmlText, 'data:image')) {
             return $htmlText;
         }
 
@@ -89,7 +86,7 @@ class PageContent
      * Attempting to capture the whole data uri using regex can cause PHP
      * PCRE limits to be hit with larger, multi-MB, files.
      */
-    protected function extractBase64ImagesFromMarkdown(string $markdown)
+    protected function extractBase64ImagesFromMarkdown(string $markdown): string
     {
         $matches = [];
         $contentLength = strlen($markdown);
@@ -181,32 +178,13 @@ class PageContent
         $childNodes = $body->childNodes;
         $xPath = new DOMXPath($doc);
 
-        // Set ids on top-level nodes
+        // Map to hold used ID references
         $idMap = [];
-        foreach ($childNodes as $index => $childNode) {
-            [$oldId, $newId] = $this->setUniqueId($childNode, $idMap);
-            if ($newId && $newId !== $oldId) {
-                $this->updateLinks($xPath, '#' . $oldId, '#' . $newId);
-            }
-        }
+        // Map to hold changing ID references
+        $changeMap = [];
 
-        // Set ids on nested header nodes
-        $nestedHeaders = $xPath->query('//body//*//h1|//body//*//h2|//body//*//h3|//body//*//h4|//body//*//h5|//body//*//h6');
-        foreach ($nestedHeaders as $nestedHeader) {
-            [$oldId, $newId] = $this->setUniqueId($nestedHeader, $idMap);
-            if ($newId && $newId !== $oldId) {
-                $this->updateLinks($xPath, '#' . $oldId, '#' . $newId);
-            }
-        }
-
-        // Ensure no duplicate ids within child items
-        $idElems = $xPath->query('//body//*//*[@id]');
-        foreach ($idElems as $domElem) {
-            [$oldId, $newId] = $this->setUniqueId($domElem, $idMap);
-            if ($newId && $newId !== $oldId) {
-                $this->updateLinks($xPath, '#' . $oldId, '#' . $newId);
-            }
-        }
+        $this->updateIdsRecursively($body, 0, $idMap, $changeMap);
+        $this->updateLinks($xPath, $changeMap);
 
         // Generate inner html as a string
         $html = '';
@@ -221,20 +199,53 @@ class PageContent
     }
 
     /**
-     * Update the all links to the $old location to instead point to $new.
+     * For the given DOMNode, traverse its children recursively and update IDs
+     * where required (Top-level, headers & elements with IDs).
+     * Will update the provided $changeMap array with changes made, where keys are the old
+     * ids and the corresponding values are the new ids.
      */
-    protected function updateLinks(DOMXPath $xpath, string $old, string $new)
+    protected function updateIdsRecursively(DOMNode $element, int $depth, array &$idMap, array &$changeMap): void
     {
-        $old = str_replace('"', '', $old);
-        $matchingLinks = $xpath->query('//body//*//*[@href="' . $old . '"]');
-        foreach ($matchingLinks as $domElem) {
-            $domElem->setAttribute('href', $new);
+        /* @var DOMNode $child */
+        foreach ($element->childNodes as $child) {
+            if ($child instanceof DOMElement && ($depth === 0 || in_array($child->nodeName, ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']) || $child->getAttribute('id'))) {
+                [$oldId, $newId] = $this->setUniqueId($child, $idMap);
+                if ($newId && $newId !== $oldId && !isset($idMap[$oldId])) {
+                    $changeMap[$oldId] = $newId;
+                }
+            }
+
+            if ($child->hasChildNodes()) {
+                $this->updateIdsRecursively($child, $depth + 1, $idMap, $changeMap);
+            }
+        }
+    }
+
+    /**
+     * Update the all links in the given xpath to apply requires changes within the
+     * given $changeMap array.
+     */
+    protected function updateLinks(DOMXPath $xpath, array $changeMap): void
+    {
+        if (empty($changeMap)) {
+            return;
+        }
+
+        $links = $xpath->query('//body//*//*[@href]');
+        /** @var DOMElement $domElem */
+        foreach ($links as $domElem) {
+            $href = ltrim($domElem->getAttribute('href'), '#');
+            $newHref = $changeMap[$href] ?? null;
+            if ($newHref) {
+                $domElem->setAttribute('href', '#' . $newHref);
+            }
         }
     }
 
     /**
      * Set a unique id on the given DOMElement.
-     * A map for existing ID's should be passed in to check for current existence.
+     * A map for existing ID's should be passed in to check for current existence,
+     * and this will be updated with any new IDs set upon elements.
      * Returns a pair of strings in the format [old_id, new_id].
      */
     protected function setUniqueId(DOMNode $element, array &$idMap): array
@@ -245,7 +256,7 @@ class PageContent
 
         // Stop if there's an existing valid id that has not already been used.
         $existingId = $element->getAttribute('id');
-        if (strpos($existingId, 'bkmrk') === 0 && !isset($idMap[$existingId])) {
+        if (str_starts_with($existingId, 'bkmrk') && !isset($idMap[$existingId])) {
             $idMap[$existingId] = true;
 
             return [$existingId, $existingId];
@@ -256,7 +267,7 @@ class PageContent
         // the same content is passed through.
         $contentId = 'bkmrk-' . mb_substr(strtolower(preg_replace('/\s+/', '-', trim($element->nodeValue))), 0, 20);
         $newId = urlencode($contentId);
-        $loopIndex = 0;
+        $loopIndex = 1;
 
         while (isset($idMap[$newId])) {
             $newId = urlencode($contentId . '-' . $loopIndex);
@@ -372,23 +383,30 @@ class PageContent
                 continue;
             }
 
-            // Find page and skip this if page not found
+            // Find page to use, and default replacement to empty string for non-matches.
             /** @var ?Page $matchedPage */
             $matchedPage = Page::visible()->find($pageId);
-            if ($matchedPage === null) {
-                $html = str_replace($fullMatch, '', $html);
-                continue;
+            $replacement = '';
+
+            if ($matchedPage && count($splitInclude) === 1) {
+                // If we only have page id, just insert all page html and continue.
+                $replacement = $matchedPage->html;
+            } elseif ($matchedPage && count($splitInclude) > 1) {
+                // Otherwise, if our include tag defines a section, load that specific content
+                $innerContent = $this->fetchSectionOfPage($matchedPage, $splitInclude[1]);
+                $replacement = trim($innerContent);
             }
 
-            // If we only have page id, just insert all page html and continue.
-            if (count($splitInclude) === 1) {
-                $html = str_replace($fullMatch, $matchedPage->html, $html);
-                continue;
-            }
+            $themeReplacement = Theme::dispatch(
+                ThemeEvents::PAGE_INCLUDE_PARSE,
+                $includeId,
+                $replacement,
+                clone $this->page,
+                $matchedPage ? (clone $matchedPage) : null,
+            );
 
-            // Create and load HTML into a document
-            $innerContent = $this->fetchSectionOfPage($matchedPage, $splitInclude[1]);
-            $html = str_replace($fullMatch, trim($innerContent), $html);
+            // Perform the content replacement
+            $html = str_replace($fullMatch, $themeReplacement ?? $replacement, $html);
         }
 
         return $html;
@@ -431,8 +449,8 @@ class PageContent
     {
         libxml_use_internal_errors(true);
         $doc = new DOMDocument();
-        $html = '<body>' . $html . '</body>';
-        $doc->loadHTML(mb_convert_encoding($html, 'HTML-ENTITIES', 'UTF-8'));
+        $html = '<?xml encoding="utf-8" ?><body>' . $html . '</body>';
+        $doc->loadHTML($html);
 
         return $doc;
     }

app/Entities/Tools/PageEditActivity.php

@@ -42,7 +42,7 @@ class PageEditActivity
             $userMessage = trans('entities.pages_draft_edit_active.start_b', ['userName' => $firstDraft->createdBy->name ?? '']);
         }
 
-        $timeMessage = trans('entities.pages_draft_edit_active.time_b', ['minCount'=> 60]);
+        $timeMessage = trans('entities.pages_draft_edit_active.time_b', ['minCount' => 60]);
 
         return trans('entities.pages_draft_edit_active.message', ['start' => $userMessage, 'time' => $timeMessage]);
     }

app/Entities/Tools/PermissionsUpdater.php

@@ -3,7 +3,10 @@
 namespace BookStack\Entities\Tools;
 
 use BookStack\Actions\ActivityType;
+use BookStack\Auth\Permissions\EntityPermission;
 use BookStack\Auth\User;
+use BookStack\Entities\Models\Book;
+use BookStack\Entities\Models\Bookshelf;
 use BookStack\Entities\Models\Entity;
 use BookStack\Facades\Activity;
 use Illuminate\Http\Request;
@@ -16,11 +19,9 @@ class PermissionsUpdater
      */
     public function updateFromPermissionsForm(Entity $entity, Request $request)
     {
-        $restricted = $request->get('restricted') === 'true';
-        $permissions = $request->get('restrictions', null);
+        $permissions = $request->get('permissions', null);
         $ownerId = $request->get('owned_by', null);
 
-        $entity->restricted = $restricted;
         $entity->permissions()->delete();
 
         if (!is_null($permissions)) {
@@ -52,18 +53,43 @@ class PermissionsUpdater
     }
 
     /**
-     * Format permissions provided from a permission form to be
-     * EntityPermission data.
+     * Format permissions provided from a permission form to be EntityPermission data.
      */
-    protected function formatPermissionsFromRequestToEntityPermissions(array $permissions): Collection
+    protected function formatPermissionsFromRequestToEntityPermissions(array $permissions): array
     {
-        return collect($permissions)->flatMap(function ($restrictions, $roleId) {
-            return collect($restrictions)->keys()->map(function ($action) use ($roleId) {
-                return [
-                    'role_id' => $roleId,
-                    'action'  => strtolower($action),
-                ];
-            });
-        });
+        $formatted = [];
+
+        foreach ($permissions as $roleId => $info) {
+            $entityPermissionData = ['role_id' => $roleId];
+            foreach (EntityPermission::PERMISSIONS as $permission) {
+                $entityPermissionData[$permission] = (($info[$permission] ?? false) === "true");
+            }
+            $formatted[] = $entityPermissionData;
+        }
+
+        return $formatted;
+    }
+
+    /**
+     * Copy down the permissions of the given shelf to all child books.
+     */
+    public function updateBookPermissionsFromShelf(Bookshelf $shelf, $checkUserPermissions = true): int
+    {
+        $shelfPermissions = $shelf->permissions()->get(['role_id', 'view', 'create', 'update', 'delete'])->toArray();
+        $shelfBooks = $shelf->books()->get(['id', 'owned_by']);
+        $updatedBookCount = 0;
+
+        /** @var Book $book */
+        foreach ($shelfBooks as $book) {
+            if ($checkUserPermissions && !userCan('restrictions-manage', $book)) {
+                continue;
+            }
+            $book->permissions()->delete();
+            $book->permissions()->createMany($shelfPermissions);
+            $book->rebuildPermissions();
+            $updatedBookCount++;
+        }
+
+        return $updatedBookCount;
     }
 }

app/Entities/Tools/TrashCan.php

@@ -376,6 +376,8 @@ class TrashCan
         $entity->searchTerms()->delete();
         $entity->deletions()->delete();
         $entity->favourites()->delete();
+        $entity->referencesTo()->delete();
+        $entity->referencesFrom()->delete();
 
         if ($entity instanceof HasCoverImage && $entity->cover()->exists()) {
             $imageService = app()->make(ImageService::class);

app/Exceptions/BookStackExceptionHandlerPage.php

@@ -2,25 +2,18 @@
 
 namespace BookStack\Exceptions;
 
-use Whoops\Handler\Handler;
+use Illuminate\Contracts\Foundation\ExceptionRenderer;
 
-class WhoopsBookStackPrettyHandler extends Handler
+class BookStackExceptionHandlerPage implements ExceptionRenderer
 {
-    /**
-     * @return int|null A handler may return nothing, or a Handler::HANDLE_* constant
-     */
-    public function handle()
+    public function render($throwable)
     {
-        $exception = $this->getException();
-
-        echo view('errors.debug', [
-            'error'       => $exception->getMessage(),
-            'errorClass'  => get_class($exception),
-            'trace'       => $exception->getTraceAsString(),
+        return view('errors.debug', [
+            'error'       => $throwable->getMessage(),
+            'errorClass'  => get_class($throwable),
+            'trace'       => $throwable->getTraceAsString(),
             'environment' => $this->getEnvironment(),
         ])->render();
-
-        return Handler::QUIT;
     }
 
     protected function safeReturn(callable $callback, $default = null)

app/Exceptions/Handler.php

@@ -17,7 +17,7 @@ class Handler extends ExceptionHandler
     /**
      * A list of the exception types that are not reported.
      *
-     * @var array
+     * @var array<int, class-string<\Throwable>>
      */
     protected $dontReport = [
         NotFoundException::class,
@@ -25,9 +25,9 @@ class Handler extends ExceptionHandler
     ];
 
     /**
-     * A list of the inputs that are never flashed for validation exceptions.
+     * A list of the inputs that are never flashed to the session on validation exceptions.
      *
-     * @var array
+     * @var array<int, string>
      */
     protected $dontFlash = [
         'current_password',
@@ -98,6 +98,7 @@ class Handler extends ExceptionHandler
         ];
 
         if ($e instanceof ValidationException) {
+            $responseData['error']['message'] = 'The given data was invalid.';
             $responseData['error']['validation'] = $e->errors();
             $code = $e->status;
         }

app/Facades/Activity.php

@@ -5,7 +5,7 @@ namespace BookStack\Facades;
 use Illuminate\Support\Facades\Facade;
 
 /**
- * @see \BookStack\Actions\ActivityLogger
+ * @mixin \BookStack\Actions\ActivityLogger
  */
 class Activity extends Facade
 {

app/Http/Controllers/Api/ApiController.php

@@ -32,10 +32,15 @@ abstract class ApiController extends Controller
      */
     public function getValidationRules(): array
     {
-        if (method_exists($this, 'rules')) {
-            return $this->rules();
-        }
+        return $this->rules();
+    }
 
+    /**
+     * Get the validation rules for the actions in this controller.
+     * Defaults to a $rules property but can be a rules() method.
+     */
+    protected function rules(): array
+    {
         return $this->rules;
     }
 }

app/Http/Controllers/Api/AttachmentApiController.php

@@ -13,11 +13,9 @@ use Illuminate\Validation\ValidationException;
 
 class AttachmentApiController extends ApiController
 {
-    protected $attachmentService;
-
-    public function __construct(AttachmentService $attachmentService)
-    {
-        $this->attachmentService = $attachmentService;
+    public function __construct(
+        protected AttachmentService $attachmentService
+    ) {
     }
 
     /**
@@ -174,13 +172,13 @@ class AttachmentApiController extends ApiController
                 'name'        => ['required', 'min:1', 'max:255', 'string'],
                 'uploaded_to' => ['required', 'integer', 'exists:pages,id'],
                 'file'        => array_merge(['required_without:link'], $this->attachmentService->getFileValidationRules()),
-                'link'        => ['required_without:file', 'min:1', 'max:255', 'safe_url'],
+                'link'        => ['required_without:file', 'min:1', 'max:2000', 'safe_url'],
             ],
             'update' => [
                 'name'        => ['min:1', 'max:255', 'string'],
                 'uploaded_to' => ['integer', 'exists:pages,id'],
                 'file'        => $this->attachmentService->getFileValidationRules(),
-                'link'        => ['min:1', 'max:255', 'safe_url'],
+                'link'        => ['min:1', 'max:2000', 'safe_url'],
             ],
         ];
     }

app/Http/Controllers/Api/BookApiController.php

@@ -2,14 +2,18 @@
 
 namespace BookStack\Http\Controllers\Api;
 
+use BookStack\Api\ApiEntityListFormatter;
 use BookStack\Entities\Models\Book;
+use BookStack\Entities\Models\Chapter;
+use BookStack\Entities\Models\Entity;
 use BookStack\Entities\Repos\BookRepo;
+use BookStack\Entities\Tools\BookContents;
 use Illuminate\Http\Request;
 use Illuminate\Validation\ValidationException;
 
 class BookApiController extends ApiController
 {
-    protected $bookRepo;
+    protected BookRepo $bookRepo;
 
     public function __construct(BookRepo $bookRepo)
     {
@@ -47,11 +51,25 @@ class BookApiController extends ApiController
 
     /**
      * View the details of a single book.
+     * The response data will contain 'content' property listing the chapter and pages directly within, in
+     * the same structure as you'd see within the BookStack interface when viewing a book. Top-level
+     * contents will have a 'type' property to distinguish between pages & chapters.
      */
     public function read(string $id)
     {
         $book = Book::visible()->with(['tags', 'cover', 'createdBy', 'updatedBy', 'ownedBy'])->findOrFail($id);
 
+        $contents = (new BookContents($book))->getTree(true, false)->all();
+        $contentsApiData = (new ApiEntityListFormatter($contents))
+            ->withType()
+            ->withField('pages', function (Entity $entity) {
+                if ($entity instanceof Chapter) {
+                    return (new ApiEntityListFormatter($entity->pages->all()))->format();
+                }
+                return null;
+            })->format();
+        $book->setAttribute('contents', $contentsApiData);
+
         return response()->json($book);
     }
 

app/Http/Controllers/Api/BookshelfApiController.php

@@ -13,9 +13,6 @@ class BookshelfApiController extends ApiController
 {
     protected BookshelfRepo $bookshelfRepo;
 
-    /**
-     * BookshelfApiController constructor.
-     */
     public function __construct(BookshelfRepo $bookshelfRepo)
     {
         $this->bookshelfRepo = $bookshelfRepo;

app/Http/Controllers/Api/PageApiController.php

@@ -86,6 +86,9 @@ class PageApiController extends ApiController
      *
      * Pages will always have HTML content. They may have markdown content
      * if the markdown editor was used to last update the page.
+     *
+     * See the "Content Security" section of these docs for security considerations when using
+     * the page content returned from this endpoint.
      */
     public function read(string $id)
     {

app/Http/Controllers/Api/RoleApiController.php

@@ -0,0 +1,136 @@
+<?php
+
+namespace BookStack\Http\Controllers\Api;
+
+use BookStack\Auth\Permissions\PermissionsRepo;
+use BookStack\Auth\Role;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+
+class RoleApiController extends ApiController
+{
+    protected PermissionsRepo $permissionsRepo;
+
+    protected array $fieldsToExpose = [
+        'display_name', 'description', 'mfa_enforced', 'external_auth_id', 'created_at', 'updated_at',
+    ];
+
+    protected $rules = [
+        'create' => [
+            'display_name'  => ['required', 'string', 'min:3', 'max:180'],
+            'description'   => ['string', 'max:180'],
+            'mfa_enforced'  => ['boolean'],
+            'external_auth_id' => ['string'],
+            'permissions'   => ['array'],
+            'permissions.*' => ['string'],
+        ],
+        'update' => [
+            'display_name'  => ['string', 'min:3', 'max:180'],
+            'description'   => ['string', 'max:180'],
+            'mfa_enforced'  => ['boolean'],
+            'external_auth_id' => ['string'],
+            'permissions'   => ['array'],
+            'permissions.*' => ['string'],
+        ]
+    ];
+
+    public function __construct(PermissionsRepo $permissionsRepo)
+    {
+        $this->permissionsRepo = $permissionsRepo;
+
+        // Checks for all endpoints in this controller
+        $this->middleware(function ($request, $next) {
+            $this->checkPermission('user-roles-manage');
+
+            return $next($request);
+        });
+    }
+
+    /**
+     * Get a listing of roles in the system.
+     * Requires permission to manage roles.
+     */
+    public function list()
+    {
+        $roles = Role::query()->select(['*'])
+            ->withCount(['users', 'permissions']);
+
+        return $this->apiListingResponse($roles, [
+            ...$this->fieldsToExpose,
+            'permissions_count',
+            'users_count',
+        ]);
+    }
+
+    /**
+     * Create a new role in the system.
+     * Permissions should be provided as an array of permission name strings.
+     * Requires permission to manage roles.
+     */
+    public function create(Request $request)
+    {
+        $data = $this->validate($request, $this->rules()['create']);
+
+        $role = null;
+        DB::transaction(function () use ($data, &$role) {
+            $role = $this->permissionsRepo->saveNewRole($data);
+        });
+
+        $this->singleFormatter($role);
+
+        return response()->json($role);
+    }
+
+    /**
+     * View the details of a single role.
+     * Provides the permissions and a high-level list of the users assigned.
+     * Requires permission to manage roles.
+     */
+    public function read(string $id)
+    {
+        $user = $this->permissionsRepo->getRoleById($id);
+        $this->singleFormatter($user);
+
+        return response()->json($user);
+    }
+
+    /**
+     * Update an existing role in the system.
+     * Permissions should be provided as an array of permission name strings.
+     * An empty "permissions" array would clear granted permissions.
+     * In many cases, where permissions are changed, you'll want to fetch the existing
+     * permissions and then modify before providing in your update request.
+     * Requires permission to manage roles.
+     */
+    public function update(Request $request, string $id)
+    {
+        $data = $this->validate($request, $this->rules()['update']);
+        $role = $this->permissionsRepo->updateRole($id, $data);
+
+        $this->singleFormatter($role);
+
+        return response()->json($role);
+    }
+
+    /**
+     * Delete a role from the system.
+     * Requires permission to manage roles.
+     */
+    public function delete(string $id)
+    {
+        $this->permissionsRepo->deleteRole(intval($id));
+
+        return response('', 204);
+    }
+
+    /**
+     * Format the given role model for single-result display.
+     */
+    protected function singleFormatter(Role $role)
+    {
+        $role->load('users:id,name,slug');
+        $role->unsetRelation('permissions');
+        $role->setAttribute('permissions', $role->permissions()->orderBy('name', 'asc')->pluck('name'));
+        $role->makeVisible(['users', 'permissions']);
+    }
+}

app/Http/Controllers/Api/SearchApiController.php

@@ -2,16 +2,17 @@
 
 namespace BookStack\Http\Controllers\Api;
 
+use BookStack\Api\ApiEntityListFormatter;
 use BookStack\Entities\Models\Entity;
-use BookStack\Entities\Tools\SearchOptions;
-use BookStack\Entities\Tools\SearchResultsFormatter;
-use BookStack\Entities\Tools\SearchRunner;
+use BookStack\Search\SearchOptions;
+use BookStack\Search\SearchResultsFormatter;
+use BookStack\Search\SearchRunner;
 use Illuminate\Http\Request;
 
 class SearchApiController extends ApiController
 {
-    protected $searchRunner;
-    protected $resultsFormatter;
+    protected SearchRunner $searchRunner;
+    protected SearchResultsFormatter $resultsFormatter;
 
     protected $rules = [
         'all' => [
@@ -50,24 +51,17 @@ class SearchApiController extends ApiController
         $results = $this->searchRunner->searchEntities($options, 'all', $page, $count);
         $this->resultsFormatter->format($results['results']->all(), $options);
 
-        /** @var Entity $result */
-        foreach ($results['results'] as $result) {
-            $result->setVisible([
-                'id', 'name', 'slug', 'book_id',
-                'chapter_id', 'draft', 'template',
-                'created_at', 'updated_at',
-                'tags', 'type', 'preview_html', 'url',
-            ]);
-            $result->setAttribute('type', $result->getType());
-            $result->setAttribute('url', $result->getUrl());
-            $result->setAttribute('preview_html', [
-                'name'    => (string) $result->getAttribute('preview_name'),
-                'content' => (string) $result->getAttribute('preview_content'),
-            ]);
-        }
+        $data = (new ApiEntityListFormatter($results['results']->all()))
+            ->withType()->withTags()
+            ->withField('preview_html', function (Entity $entity) {
+                return [
+                    'name'    => (string) $entity->getAttribute('preview_name'),
+                    'content' => (string) $entity->getAttribute('preview_content'),
+                ];
+            })->format();
 
         return response()->json([
-            'data'  => $results['results'],
+            'data'  => $data,
             'total' => $results['total'],
         ]);
     }

app/Http/Controllers/Api/UserApiController.php

@@ -13,9 +13,9 @@ use Illuminate\Validation\Rules\Unique;
 
 class UserApiController extends ApiController
 {
-    protected $userRepo;
+    protected UserRepo $userRepo;
 
-    protected $fieldsToExpose = [
+    protected array $fieldsToExpose = [
         'email', 'created_at', 'updated_at', 'last_activity_at', 'external_auth_id',
     ];
 
@@ -36,26 +36,26 @@ class UserApiController extends ApiController
     {
         return [
             'create' => [
-                'name'  => ['required', 'min:2'],
+                'name'  => ['required', 'min:2', 'max:100'],
                 'email' => [
                     'required', 'min:2', 'email', new Unique('users', 'email'),
                 ],
                 'external_auth_id' => ['string'],
-                'language'         => ['string'],
+                'language'         => ['string', 'max:15', 'alpha_dash'],
                 'password'         => [Password::default()],
                 'roles'            => ['array'],
                 'roles.*'          => ['integer'],
                 'send_invite'      => ['boolean'],
             ],
             'update' => [
-                'name'  => ['min:2'],
+                'name'  => ['min:2', 'max:100'],
                 'email' => [
                     'min:2',
                     'email',
                     (new Unique('users', 'email'))->ignore($userId ?? null),
                 ],
                 'external_auth_id' => ['string'],
-                'language'         => ['string'],
+                'language'         => ['string', 'max:15', 'alpha_dash'],
                 'password'         => [Password::default()],
                 'roles'            => ['array'],
                 'roles.*'          => ['integer'],

app/Http/Controllers/AttachmentController.php

@@ -15,16 +15,10 @@ use Illuminate\Validation\ValidationException;
 
 class AttachmentController extends Controller
 {
-    protected AttachmentService $attachmentService;
-    protected PageRepo $pageRepo;
-
-    /**
-     * AttachmentController constructor.
-     */
-    public function __construct(AttachmentService $attachmentService, PageRepo $pageRepo)
-    {
-        $this->attachmentService = $attachmentService;
-        $this->pageRepo = $pageRepo;
+    public function __construct(
+        protected AttachmentService $attachmentService,
+        protected PageRepo $pageRepo
+    ) {
     }
 
     /**
@@ -112,7 +106,7 @@ class AttachmentController extends Controller
         try {
             $this->validate($request, [
                 'attachment_edit_name' => ['required', 'string', 'min:1', 'max:255'],
-                'attachment_edit_url'  => ['string', 'min:1', 'max:255', 'safe_url'],
+                'attachment_edit_url'  => ['string', 'min:1', 'max:2000', 'safe_url'],
             ]);
         } catch (ValidationException $exception) {
             return response()->view('attachments.manager-edit-form', array_merge($request->only(['attachment_edit_name', 'attachment_edit_url']), [
@@ -148,7 +142,7 @@ class AttachmentController extends Controller
             $this->validate($request, [
                 'attachment_link_uploaded_to' => ['required', 'integer', 'exists:pages,id'],
                 'attachment_link_name'        => ['required', 'string', 'min:1', 'max:255'],
-                'attachment_link_url'         => ['required', 'string', 'min:1', 'max:255', 'safe_url'],
+                'attachment_link_url'         => ['required', 'string', 'min:1', 'max:2000', 'safe_url'],
             ]);
         } catch (ValidationException $exception) {
             return response()->view('attachments.manager-link-form', array_merge($request->only(['attachment_link_name', 'attachment_link_url']), [

app/Http/Controllers/AuditLogController.php

@@ -3,6 +3,8 @@
 namespace BookStack\Http\Controllers;
 
 use BookStack\Actions\Activity;
+use BookStack\Actions\ActivityType;
+use BookStack\Util\SimpleListOptions;
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\DB;
 
@@ -13,10 +15,15 @@ class AuditLogController extends Controller
         $this->checkPermission('settings-manage');
         $this->checkPermission('users-manage');
 
-        $listDetails = [
-            'order'     => $request->get('order', 'desc'),
+        $sort = $request->get('sort', 'activity_date');
+        $order = $request->get('order', 'desc');
+        $listOptions = (new SimpleListOptions('', $sort, $order))->withSortOptions([
+            'created_at' => trans('settings.audit_table_date'),
+            'type' => trans('settings.audit_table_event'),
+        ]);
+
+        $filters = [
             'event'     => $request->get('event', ''),
-            'sort'      => $request->get('sort', 'created_at'),
             'date_from' => $request->get('date_from', ''),
             'date_to'   => $request->get('date_to', ''),
             'user'      => $request->get('user', ''),
@@ -25,39 +32,38 @@ class AuditLogController extends Controller
 
         $query = Activity::query()
             ->with([
-                'entity' => function ($query) {
-                    $query->withTrashed();
-                },
+                'entity' => fn ($query) => $query->withTrashed(),
                 'user',
             ])
-            ->orderBy($listDetails['sort'], $listDetails['order']);
+            ->orderBy($listOptions->getSort(), $listOptions->getOrder());
 
-        if ($listDetails['event']) {
-            $query->where('type', '=', $listDetails['event']);
+        if ($filters['event']) {
+            $query->where('type', '=', $filters['event']);
         }
-        if ($listDetails['user']) {
-            $query->where('user_id', '=', $listDetails['user']);
+        if ($filters['user']) {
+            $query->where('user_id', '=', $filters['user']);
         }
 
-        if ($listDetails['date_from']) {
-            $query->where('created_at', '>=', $listDetails['date_from']);
+        if ($filters['date_from']) {
+            $query->where('created_at', '>=', $filters['date_from']);
         }
-        if ($listDetails['date_to']) {
-            $query->where('created_at', '<=', $listDetails['date_to']);
+        if ($filters['date_to']) {
+            $query->where('created_at', '<=', $filters['date_to']);
         }
-        if ($listDetails['ip']) {
-            $query->where('ip', 'like', $listDetails['ip'] . '%');
+        if ($filters['ip']) {
+            $query->where('ip', 'like', $filters['ip'] . '%');
         }
 
         $activities = $query->paginate(100);
-        $activities->appends($listDetails);
+        $activities->appends($request->all());
 
-        $types = DB::table('activities')->select('type')->distinct()->pluck('type');
+        $types = ActivityType::all();
         $this->setPageTitle(trans('settings.audit'));
 
         return view('settings.audit', [
             'activities'    => $activities,
-            'listDetails'   => $listDetails,
+            'filters'       => $filters,
+            'listOptions'   => $listOptions,
             'activityTypes' => $types,
         ]);
     }

app/Http/Controllers/Auth/ConfirmEmailController.php

@@ -14,9 +14,9 @@ use Illuminate\Http\Request;
 
 class ConfirmEmailController extends Controller
 {
-    protected $emailConfirmationService;
-    protected $loginService;
-    protected $userRepo;
+    protected EmailConfirmationService $emailConfirmationService;
+    protected LoginService $loginService;
+    protected UserRepo $userRepo;
 
     /**
      * Create a new controller instance.
@@ -51,14 +51,28 @@ class ConfirmEmailController extends Controller
         return view('auth.user-unconfirmed', ['user' => $user]);
     }
 
+    /**
+     * Show the form for a user to provide their positive confirmation of their email.
+     */
+    public function showAcceptForm(string $token)
+    {
+        return view('auth.register-confirm-accept', ['token' => $token]);
+    }
+
     /**
      * Confirms an email via a token and logs the user into the system.
      *
      * @throws ConfirmationEmailException
      * @throws Exception
      */
-    public function confirm(string $token)
+    public function confirm(Request $request)
     {
+        $validated = $this->validate($request, [
+            'token' => ['required', 'string']
+        ]);
+
+        $token = $validated['token'];
+
         try {
             $userId = $this->emailConfirmationService->checkTokenAndGetUserId($token);
         } catch (UserTokenNotFoundException $exception) {

app/Http/Controllers/Auth/ForgotPasswordController.php

@@ -4,25 +4,11 @@ namespace BookStack\Http\Controllers\Auth;
 
 use BookStack\Actions\ActivityType;
 use BookStack\Http\Controllers\Controller;
-use Illuminate\Foundation\Auth\SendsPasswordResetEmails;
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\Password;
 
 class ForgotPasswordController extends Controller
 {
-    /*
-    |--------------------------------------------------------------------------
-    | Password Reset Controller
-    |--------------------------------------------------------------------------
-    |
-    | This controller is responsible for handling password reset emails and
-    | includes a trait which assists in sending these notifications from
-    | your application to your users. Feel free to explore this trait.
-    |
-    */
-
-    use SendsPasswordResetEmails;
-
     /**
      * Create a new controller instance.
      *
@@ -34,6 +20,14 @@ class ForgotPasswordController extends Controller
         $this->middleware('guard:standard');
     }
 
+    /**
+     * Display the form to request a password reset link.
+     */
+    public function showLinkRequestForm()
+    {
+        return view('auth.passwords.email');
+    }
+
     /**
      * Send a reset link to the given user.
      *
@@ -50,7 +44,7 @@ class ForgotPasswordController extends Controller
         // We will send the password reset link to this user. Once we have attempted
         // to send the link, we will examine the response then see the message we
         // need to show to the user. Finally, we'll send out a proper response.
-        $response = $this->broker()->sendResetLink(
+        $response = Password::broker()->sendResetLink(
             $request->only('email')
         );
 

app/Http/Controllers/Auth/LoginController.php

@@ -8,30 +8,14 @@ use BookStack\Exceptions\LoginAttemptEmailNeededException;
 use BookStack\Exceptions\LoginAttemptException;
 use BookStack\Facades\Activity;
 use BookStack\Http\Controllers\Controller;
-use Illuminate\Foundation\Auth\AuthenticatesUsers;
+use Illuminate\Http\RedirectResponse;
 use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Auth;
 use Illuminate\Validation\ValidationException;
 
 class LoginController extends Controller
 {
-    /*
-    |--------------------------------------------------------------------------
-    | Login Controller
-    |--------------------------------------------------------------------------
-    |
-    | This controller handles authenticating users for the application and
-    | redirecting them to your home screen. The controller uses a trait
-    | to conveniently provide its functionality to your applications.
-    |
-    */
-
-    use AuthenticatesUsers { logout as traitLogout; }
-
-    /**
-     * Redirection paths.
-     */
-    protected $redirectTo = '/';
-    protected $redirectPath = '/';
+    use ThrottlesLogins;
 
     protected SocialAuthService $socialAuthService;
     protected LoginService $loginService;
@@ -47,21 +31,6 @@ class LoginController extends Controller
 
         $this->socialAuthService = $socialAuthService;
         $this->loginService = $loginService;
-
-        $this->redirectPath = url('/');
-    }
-
-    public function username()
-    {
-        return config('auth.method') === 'standard' ? 'email' : 'username';
-    }
-
-    /**
-     * Get the needed authorization credentials from the request.
-     */
-    protected function credentials(Request $request)
-    {
-        return $request->only('username', 'email', 'password');
     }
 
     /**
@@ -97,27 +66,15 @@ class LoginController extends Controller
 
     /**
      * Handle a login request to the application.
-     *
-     * @param \Illuminate\Http\Request $request
-     *
-     * @throws \Illuminate\Validation\ValidationException
-     *
-     * @return \Illuminate\Http\RedirectResponse|\Illuminate\Http\Response|\Illuminate\Http\JsonResponse
      */
     public function login(Request $request)
     {
         $this->validateLogin($request);
         $username = $request->get($this->username());
 
-        // If the class is using the ThrottlesLogins trait, we can automatically throttle
-        // the login attempts for this application. We'll key this by the username and
-        // the IP address of the client making these requests into this application.
-        if (method_exists($this, 'hasTooManyLoginAttempts') &&
-            $this->hasTooManyLoginAttempts($request)) {
-            $this->fireLockoutEvent($request);
-
+        // Check login throttling attempts to see if they've gone over the limit
+        if ($this->hasTooManyLoginAttempts($request)) {
             Activity::logFailedLogin($username);
-
             return $this->sendLockoutResponse($request);
         }
 
@@ -131,24 +88,62 @@ class LoginController extends Controller
             return $this->sendLoginAttemptExceptionResponse($exception, $request);
         }
 
-        // If the login attempt was unsuccessful we will increment the number of attempts
-        // to login and redirect the user back to the login form. Of course, when this
-        // user surpasses their maximum number of attempts they will get locked out.
+        // On unsuccessful login attempt, Increment login attempts for throttling and log failed login.
         $this->incrementLoginAttempts($request);
-
         Activity::logFailedLogin($username);
 
-        return $this->sendFailedLoginResponse($request);
+        // Throw validation failure for failed login
+        throw ValidationException::withMessages([
+            $this->username() => [trans('auth.failed')],
+        ])->redirectTo('/login');
+    }
+
+    /**
+     * Logout user and perform subsequent redirect.
+     */
+    public function logout(Request $request)
+    {
+        Auth::guard()->logout();
+        $request->session()->invalidate();
+        $request->session()->regenerateToken();
+
+        $redirectUri = $this->shouldAutoInitiate() ? '/login?prevent_auto_init=true' : '/';
+
+        return redirect($redirectUri);
+    }
+
+    /**
+     * Get the expected username input based upon the current auth method.
+     */
+    protected function username(): string
+    {
+        return config('auth.method') === 'standard' ? 'email' : 'username';
+    }
+
+    /**
+     * Get the needed authorization credentials from the request.
+     */
+    protected function credentials(Request $request): array
+    {
+        return $request->only('username', 'email', 'password');
+    }
+
+    /**
+     * Send the response after the user was authenticated.
+     * @return RedirectResponse
+     */
+    protected function sendLoginResponse(Request $request)
+    {
+        $request->session()->regenerate();
+        $this->clearLoginAttempts($request);
+
+        return redirect()->intended('/');
     }
 
     /**
      * Attempt to log the user into the application.
-     *
-     * @param \Illuminate\Http\Request $request
-     *
-     * @return bool
      */
-    protected function attemptLogin(Request $request)
+    protected function attemptLogin(Request $request): bool
     {
         return $this->loginService->attempt(
             $this->credentials($request),
@@ -157,29 +152,12 @@ class LoginController extends Controller
         );
     }
 
-    /**
-     * The user has been authenticated.
-     *
-     * @param \Illuminate\Http\Request $request
-     * @param mixed                    $user
-     *
-     * @return mixed
-     */
-    protected function authenticated(Request $request, $user)
-    {
-        return redirect()->intended($this->redirectPath());
-    }
 
     /**
      * Validate the user login request.
-     *
-     * @param \Illuminate\Http\Request $request
-     *
-     * @throws \Illuminate\Validation\ValidationException
-     *
-     * @return void
+     * @throws ValidationException
      */
-    protected function validateLogin(Request $request)
+    protected function validateLogin(Request $request): void
     {
         $rules = ['password' => ['required', 'string']];
         $authMethod = config('auth.method');
@@ -213,22 +191,6 @@ class LoginController extends Controller
         return redirect('/login');
     }
 
-    /**
-     * Get the failed login response instance.
-     *
-     * @param \Illuminate\Http\Request $request
-     *
-     * @throws \Illuminate\Validation\ValidationException
-     *
-     * @return \Symfony\Component\HttpFoundation\Response
-     */
-    protected function sendFailedLoginResponse(Request $request)
-    {
-        throw ValidationException::withMessages([
-            $this->username() => [trans('auth.failed')],
-        ])->redirectTo('/login');
-    }
-
     /**
      * Update the intended URL location from their previous URL.
      * Ignores if not from the current app instance or if from certain
@@ -268,20 +230,4 @@ class LoginController extends Controller
 
         return $autoRedirect && count($socialDrivers) === 0 && in_array($authMethod, ['oidc', 'saml2']);
     }
-
-    /**
-     * Logout user and perform subsequent redirect.
-     *
-     * @param \Illuminate\Http\Request $request
-     *
-     * @return mixed
-     */
-    public function logout(Request $request)
-    {
-        $this->traitLogout($request);
-
-        $redirectUri = $this->shouldAutoInitiate() ? '/login?prevent_auto_init=true' : '/';
-
-        return redirect($redirectUri);
-    }
 }

app/Http/Controllers/Auth/RegisterController.php

@@ -5,42 +5,19 @@ namespace BookStack\Http\Controllers\Auth;
 use BookStack\Auth\Access\LoginService;
 use BookStack\Auth\Access\RegistrationService;
 use BookStack\Auth\Access\SocialAuthService;
-use BookStack\Auth\User;
 use BookStack\Exceptions\StoppedAuthenticationException;
 use BookStack\Exceptions\UserRegistrationException;
 use BookStack\Http\Controllers\Controller;
-use Illuminate\Foundation\Auth\RegistersUsers;
+use Illuminate\Contracts\Validation\Validator as ValidatorContract;
 use Illuminate\Http\Request;
-use Illuminate\Support\Facades\Hash;
 use Illuminate\Support\Facades\Validator;
 use Illuminate\Validation\Rules\Password;
 
 class RegisterController extends Controller
 {
-    /*
-    |--------------------------------------------------------------------------
-    | Register Controller
-    |--------------------------------------------------------------------------
-    |
-    | This controller handles the registration of new users as well as their
-    | validation and creation. By default this controller uses a trait to
-    | provide this functionality without requiring any additional code.
-    |
-    */
-
-    use RegistersUsers;
-
-    protected $socialAuthService;
-    protected $registrationService;
-    protected $loginService;
-
-    /**
-     * Where to redirect users after login / registration.
-     *
-     * @var string
-     */
-    protected $redirectTo = '/';
-    protected $redirectPath = '/';
+    protected SocialAuthService $socialAuthService;
+    protected RegistrationService $registrationService;
+    protected LoginService $loginService;
 
     /**
      * Create a new controller instance.
@@ -56,23 +33,6 @@ class RegisterController extends Controller
         $this->socialAuthService = $socialAuthService;
         $this->registrationService = $registrationService;
         $this->loginService = $loginService;
-
-        $this->redirectTo = url('/');
-        $this->redirectPath = url('/');
-    }
-
-    /**
-     * Get a validator for an incoming registration request.
-     *
-     * @return \Illuminate\Contracts\Validation\Validator
-     */
-    protected function validator(array $data)
-    {
-        return Validator::make($data, [
-            'name'     => ['required', 'min:2', 'max:255'],
-            'email'    => ['required', 'email', 'max:255', 'unique:users'],
-            'password' => ['required', Password::default()],
-        ]);
     }
 
     /**
@@ -115,22 +75,18 @@ class RegisterController extends Controller
 
         $this->showSuccessNotification(trans('auth.register_success'));
 
-        return redirect($this->redirectPath());
+        return redirect('/');
     }
 
     /**
-     * Create a new user instance after a valid registration.
-     *
-     * @param array $data
-     *
-     * @return User
+     * Get a validator for an incoming registration request.
      */
-    protected function create(array $data)
+    protected function validator(array $data): ValidatorContract
     {
-        return User::create([
-            'name'     => $data['name'],
-            'email'    => $data['email'],
-            'password' => Hash::make($data['password']),
+        return Validator::make($data, [
+            'name'     => ['required', 'min:2', 'max:100'],
+            'email'    => ['required', 'email', 'max:255', 'unique:users'],
+            'password' => ['required', Password::default()],
         ]);
     }
 }

app/Http/Controllers/Auth/ResetPasswordController.php

@@ -3,66 +3,87 @@
 namespace BookStack\Http\Controllers\Auth;
 
 use BookStack\Actions\ActivityType;
+use BookStack\Auth\Access\LoginService;
+use BookStack\Auth\User;
 use BookStack\Http\Controllers\Controller;
-use Illuminate\Foundation\Auth\ResetsPasswords;
+use Illuminate\Http\RedirectResponse;
 use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Hash;
 use Illuminate\Support\Facades\Password;
+use Illuminate\Support\Str;
+use Illuminate\Validation\Rules\Password as PasswordRule;
 
 class ResetPasswordController extends Controller
 {
-    /*
-    |--------------------------------------------------------------------------
-    | Password Reset Controller
-    |--------------------------------------------------------------------------
-    |
-    | This controller is responsible for handling password reset requests
-    | and uses a simple trait to include this behavior. You're free to
-    | explore this trait and override any methods you wish to tweak.
-    |
-    */
+    protected LoginService $loginService;
 
-    use ResetsPasswords;
-
-    protected $redirectTo = '/';
-
-    /**
-     * Create a new controller instance.
-     *
-     * @return void
-     */
-    public function __construct()
+    public function __construct(LoginService $loginService)
     {
         $this->middleware('guest');
         $this->middleware('guard:standard');
+
+        $this->loginService = $loginService;
+    }
+
+    /**
+     * Display the password reset view for the given token.
+     * If no token is present, display the link request form.
+     */
+    public function showResetForm(Request $request)
+    {
+        $token = $request->route()->parameter('token');
+
+        return view('auth.passwords.reset')->with(
+            ['token' => $token, 'email' => $request->email]
+        );
+    }
+
+    /**
+     * Reset the given user's password.
+     */
+    public function reset(Request $request)
+    {
+        $request->validate([
+            'token' => 'required',
+            'email' => 'required|email',
+            'password' => ['required', 'confirmed', PasswordRule::defaults()],
+        ]);
+
+        // Here we will attempt to reset the user's password. If it is successful we
+        // will update the password on an actual user model and persist it to the
+        // database. Otherwise we will parse the error and return the response.
+        $credentials = $request->only('email', 'password', 'password_confirmation', 'token');
+        $response = Password::broker()->reset($credentials, function (User $user, string $password) {
+            $user->password = Hash::make($password);
+            $user->setRememberToken(Str::random(60));
+            $user->save();
+
+            $this->loginService->login($user, auth()->getDefaultDriver());
+        });
+
+        // If the password was successfully reset, we will redirect the user back to
+        // the application's home authenticated view. If there is an error we can
+        // redirect them back to where they came from with their error message.
+        return $response === Password::PASSWORD_RESET
+            ? $this->sendResetResponse()
+            : $this->sendResetFailedResponse($request, $response);
     }
 
     /**
      * Get the response for a successful password reset.
-     *
-     * @param Request $request
-     * @param string  $response
-     *
-     * @return \Illuminate\Http\Response
      */
-    protected function sendResetResponse(Request $request, $response)
+    protected function sendResetResponse(): RedirectResponse
     {
-        $message = trans('auth.reset_password_success');
-        $this->showSuccessNotification($message);
+        $this->showSuccessNotification(trans('auth.reset_password_success'));
         $this->logActivity(ActivityType::AUTH_PASSWORD_RESET_UPDATE, user());
 
-        return redirect($this->redirectPath())
-            ->with('status', trans($response));
+        return redirect('/');
     }
 
     /**
      * Get the response for a failed password reset.
-     *
-     * @param \Illuminate\Http\Request $request
-     * @param string                   $response
-     *
-     * @return \Illuminate\Http\RedirectResponse|\Illuminate\Http\JsonResponse
      */
-    protected function sendResetFailedResponse(Request $request, $response)
+    protected function sendResetFailedResponse(Request $request, string $response): RedirectResponse
     {
         // We show invalid users as invalid tokens as to not leak what
         // users may exist in the system.

app/Http/Controllers/Auth/Saml2Controller.php

@@ -9,7 +9,7 @@ use Illuminate\Support\Str;
 
 class Saml2Controller extends Controller
 {
-    protected $samlService;
+    protected Saml2Service $samlService;
 
     /**
      * Saml2Controller constructor.

app/Http/Controllers/Auth/SocialController.php

@@ -16,9 +16,9 @@ use Laravel\Socialite\Contracts\User as SocialUser;
 
 class SocialController extends Controller
 {
-    protected $socialAuthService;
-    protected $registrationService;
-    protected $loginService;
+    protected SocialAuthService $socialAuthService;
+    protected RegistrationService $registrationService;
+    protected LoginService $loginService;
 
     /**
      * SocialController constructor.
@@ -28,7 +28,7 @@ class SocialController extends Controller
         RegistrationService $registrationService,
         LoginService $loginService
     ) {
-        $this->middleware('guest')->only(['getRegister', 'postRegister']);
+        $this->middleware('guest')->only(['register']);
         $this->socialAuthService = $socialAuthService;
         $this->registrationService = $registrationService;
         $this->loginService = $loginService;

app/Http/Controllers/Auth/ThrottlesLogins.php

@@ -0,0 +1,92 @@
+<?php
+
+namespace BookStack\Http\Controllers\Auth;
+
+use Illuminate\Cache\RateLimiter;
+use Illuminate\Http\Request;
+use Illuminate\Http\Response;
+use Illuminate\Support\Str;
+use Illuminate\Validation\ValidationException;
+
+trait ThrottlesLogins
+{
+    /**
+     * Determine if the user has too many failed login attempts.
+     */
+    protected function hasTooManyLoginAttempts(Request $request): bool
+    {
+        return $this->limiter()->tooManyAttempts(
+            $this->throttleKey($request),
+            $this->maxAttempts()
+        );
+    }
+
+    /**
+     * Increment the login attempts for the user.
+     */
+    protected function incrementLoginAttempts(Request $request): void
+    {
+        $this->limiter()->hit(
+            $this->throttleKey($request),
+            $this->decayMinutes() * 60
+        );
+    }
+
+    /**
+     * Redirect the user after determining they are locked out.
+     * @throws ValidationException
+     */
+    protected function sendLockoutResponse(Request $request): \Symfony\Component\HttpFoundation\Response
+    {
+        $seconds = $this->limiter()->availableIn(
+            $this->throttleKey($request)
+        );
+
+        throw ValidationException::withMessages([
+            $this->username() => [trans('auth.throttle', [
+                'seconds' => $seconds,
+                'minutes' => ceil($seconds / 60),
+            ])],
+        ])->status(Response::HTTP_TOO_MANY_REQUESTS);
+    }
+
+    /**
+     * Clear the login locks for the given user credentials.
+     */
+    protected function clearLoginAttempts(Request $request): void
+    {
+        $this->limiter()->clear($this->throttleKey($request));
+    }
+
+    /**
+     * Get the throttle key for the given request.
+     */
+    protected function throttleKey(Request $request): string
+    {
+        return Str::transliterate(Str::lower($request->input($this->username())) . '|' . $request->ip());
+    }
+
+    /**
+     * Get the rate limiter instance.
+     */
+    protected function limiter(): RateLimiter
+    {
+        return app(RateLimiter::class);
+    }
+
+    /**
+     * Get the maximum number of attempts to allow.
+     */
+    public function maxAttempts(): int
+    {
+        return 5;
+    }
+
+    /**
+     * Get the number of minutes to throttle for.
+     */
+    public function decayMinutes(): int
+    {
+        return 1;
+    }
+}